@arenarium/maps 1.0.173 → 1.0.175
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.txt +16 -23
- package/README.md +17 -35
- package/package.json +1 -1
package/LICENSE.txt
CHANGED
|
@@ -1,28 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
1
2
|
|
|
2
3
|
Copyright (c) 2025 arenarium.dev
|
|
3
4
|
|
|
4
|
-
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
5
11
|
|
|
6
|
-
|
|
7
|
-
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
8
14
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
without specific prior written permission.
|
|
17
|
-
|
|
18
|
-
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
|
19
|
-
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
|
20
|
-
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
|
21
|
-
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
|
|
22
|
-
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
|
|
23
|
-
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
|
|
24
|
-
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
|
|
25
|
-
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
|
|
26
|
-
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
|
|
27
|
-
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
28
|
-
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -6,39 +6,35 @@ To install the `@aranarium/maps` library using npm, run the following command in
|
|
|
6
6
|
|
|
7
7
|
```
|
|
8
8
|
npm install @arenarium/maps
|
|
9
|
-
|
|
10
9
|
```
|
|
11
10
|
|
|
12
11
|
Import the necessary module and CSS file into your project to begin using the map:
|
|
13
12
|
|
|
14
|
-
```
|
|
13
|
+
```js
|
|
15
14
|
import { MapManager } from '@arenarium/maps';
|
|
16
15
|
import '@arenarium/maps/dist/style.css';
|
|
17
16
|
|
|
18
17
|
// Initialize and mount the map manager (further configuration details follow)
|
|
19
18
|
const mapManager = new MapManager(...);
|
|
20
|
-
|
|
21
19
|
```
|
|
22
20
|
|
|
23
21
|
## CDN
|
|
24
22
|
|
|
25
23
|
To include `@aranarium/maps` directly in your HTML via a Content Delivery Network (CDN), add these script and stylesheet tags to the `<head>` or `<body>` of your HTML document:
|
|
26
24
|
|
|
27
|
-
```
|
|
25
|
+
```html
|
|
28
26
|
<script src="https://unpkg.com/maplibre-gl@^5.6.0/dist/maplibre-gl.js"></script>
|
|
29
27
|
<link href="https://unpkg.com/maplibre-gl@^5.6.0/dist/maplibre-gl.css" rel="stylesheet" />
|
|
30
28
|
|
|
31
29
|
<script src="https://unpkg.com/@arenarium/maps@^1.0.124/dist/index.js"></script>
|
|
32
30
|
<link href="https://unpkg.com/@arenarium/maps@^1.0.124/dist/style.css" rel="stylesheet" />
|
|
33
|
-
|
|
34
31
|
```
|
|
35
32
|
|
|
36
33
|
Once included, you can access the library's functions through the global `arenarium` object to mount the map:
|
|
37
34
|
|
|
38
|
-
```
|
|
35
|
+
```js
|
|
39
36
|
// Initialize and mount the map manager (further configuration details follow)
|
|
40
37
|
const mapManager = new arenarium.MapManager(...);
|
|
41
|
-
|
|
42
38
|
```
|
|
43
39
|
|
|
44
40
|
# Usage
|
|
@@ -47,9 +43,8 @@ const mapManager = new arenarium.MapManager(...);
|
|
|
47
43
|
|
|
48
44
|
To initialize the map, first add a container element to your HTML where the map will be rendered. Then depending on the map library used there are different instructions:
|
|
49
45
|
|
|
50
|
-
```
|
|
46
|
+
```html
|
|
51
47
|
<div id="map"></div>
|
|
52
|
-
|
|
53
48
|
```
|
|
54
49
|
|
|
55
50
|
## Maplibre GL
|
|
@@ -58,12 +53,11 @@ First, install the `maplibre-gl` library:
|
|
|
58
53
|
|
|
59
54
|
```
|
|
60
55
|
npm install maplibre-gl
|
|
61
|
-
|
|
62
56
|
```
|
|
63
57
|
|
|
64
58
|
Next, use the `MapManager` class which requires a `maplibre.Map` class, a `maplibre.Marker` class and a `MapOptions` object.
|
|
65
59
|
|
|
66
|
-
```
|
|
60
|
+
```js
|
|
67
61
|
import maplibregl from 'maplibre-gl';
|
|
68
62
|
import 'maplibre-gl/dist/maplibre-gl.css';
|
|
69
63
|
|
|
@@ -82,23 +76,20 @@ const mapManager = new MapManager(maplibreProvider);
|
|
|
82
76
|
|
|
83
77
|
// Access the maplibre instance for direct map interactions
|
|
84
78
|
const maplibreMap = mapLibreProvider.getMap();
|
|
85
|
-
|
|
86
79
|
```
|
|
87
80
|
|
|
88
81
|
You can change the map's visual appearance by setting a predefined dark or light theme:
|
|
89
82
|
|
|
90
|
-
```
|
|
83
|
+
```js
|
|
91
84
|
import { MaplibreDarkStyle, MaplibreLightStyle } from '@arenarium/maps/maplibre';
|
|
92
85
|
|
|
93
86
|
maplibreMap.setStyle(MaplibreDarkStyle); // or MaplibreLightStyle
|
|
94
|
-
|
|
95
87
|
```
|
|
96
88
|
|
|
97
89
|
Alternatively, you can apply a custom map style by providing a URL to a JSON file that adheres to the [MapLibre Style Specification](https://maplibre.org/maplibre-style-spec/). You can also override specific color properties within a custom style.
|
|
98
90
|
|
|
99
|
-
```
|
|
91
|
+
```js
|
|
100
92
|
mapLibre.setStyle('https://tiles.openfreemap.org/styles/liberty.json');
|
|
101
|
-
|
|
102
93
|
```
|
|
103
94
|
|
|
104
95
|
## Mapbox GL
|
|
@@ -107,12 +98,11 @@ First, install the `mapbox-gl` library:
|
|
|
107
98
|
|
|
108
99
|
```
|
|
109
100
|
npm install mapbox-gl
|
|
110
|
-
|
|
111
101
|
```
|
|
112
102
|
|
|
113
103
|
Next, use the `MapManager` class which requires a `mapbox.Map` class, a `mapbox.Marker` class and a `MapOptions` object.
|
|
114
104
|
|
|
115
|
-
```
|
|
105
|
+
```js
|
|
116
106
|
import mapbox from 'mapbox-gl';
|
|
117
107
|
import 'mapbox-gl/dist/mapbox-gl.css';
|
|
118
108
|
|
|
@@ -131,7 +121,6 @@ const mapManager = new MapManager(mapboxProvider);
|
|
|
131
121
|
|
|
132
122
|
// Access the mapbox instance for direct map interactions
|
|
133
123
|
const mapboxMap = mapboxProvider.getMap();
|
|
134
|
-
|
|
135
124
|
```
|
|
136
125
|
|
|
137
126
|
## Google Maps
|
|
@@ -140,12 +129,11 @@ First, install the `@googlemaps/js-api-loader` library:
|
|
|
140
129
|
|
|
141
130
|
```
|
|
142
131
|
npm install @googlemaps/js-api-loader
|
|
143
|
-
|
|
144
132
|
```
|
|
145
133
|
|
|
146
134
|
To use Google Maps, you'll need to load the Google Maps JavaScript API and create a Google Maps provider instance.
|
|
147
135
|
|
|
148
|
-
```
|
|
136
|
+
```js
|
|
149
137
|
import { Loader } from '@googlemaps/js-api-loader';
|
|
150
138
|
|
|
151
139
|
import { MapManager } from '@arenarium/maps';
|
|
@@ -174,12 +162,11 @@ const mapManager = new MapManager(mapGoogleProvider);
|
|
|
174
162
|
|
|
175
163
|
// Access the Google Maps instance for direct map interactions
|
|
176
164
|
const mapGoogle = mapGoogleProvider.getMap();
|
|
177
|
-
|
|
178
165
|
```
|
|
179
166
|
|
|
180
167
|
You can change the map's visual appearance by using the predefined styles in combination with custom `StyledMapType`:
|
|
181
168
|
|
|
182
|
-
```
|
|
169
|
+
```js
|
|
183
170
|
import { GoogleMapsDarkStyle, GoogleMapsLightStyle } from '@arenarium/maps/google';
|
|
184
171
|
|
|
185
172
|
const mapTypeLight = new google.maps.StyledMapType(GoogleMapsLightStyle, { name: 'Light Map' });
|
|
@@ -189,7 +176,6 @@ mapGoogle.mapTypes.set("light-id", mapTypeLight);
|
|
|
189
176
|
mapGoogle.mapTypes.set("dark-id", mapTypeDark);
|
|
190
177
|
|
|
191
178
|
mapGoogle.setMapTypeId("light-id"); // or "dark-id" for dark theme
|
|
192
|
-
|
|
193
179
|
```
|
|
194
180
|
|
|
195
181
|
## Markers
|
|
@@ -202,7 +188,7 @@ To add markers to the map, you first need to define an array of `MapMarker` obje
|
|
|
202
188
|
|
|
203
189
|
Use the `updateMarkers` method on the map manager to display or update update the markers. This method adds new markers and updates existing ones based on their IDs. Markers not present in the provided array will remain on the map. This approach is designed for continuous updates of map markers.
|
|
204
190
|
|
|
205
|
-
```
|
|
191
|
+
```js
|
|
206
192
|
import { type MapMarker } from '@arenarium/maps';
|
|
207
193
|
|
|
208
194
|
const markers: MapMarker[] = [];
|
|
@@ -223,7 +209,7 @@ for (let i = 0; i < count; i++) {
|
|
|
223
209
|
// The desired height of the marker's tooltip area
|
|
224
210
|
height: ...,
|
|
225
211
|
// The desired width of the marker's tooltip area
|
|
226
|
-
width:
|
|
212
|
+
width: ...,
|
|
227
213
|
// The desired margin of the marker's tooltip area
|
|
228
214
|
margin: ...,
|
|
229
215
|
// The desired radius of the marker's tooltip area
|
|
@@ -238,7 +224,7 @@ for (let i = 0; i < count; i++) {
|
|
|
238
224
|
// The desired height of the marker's pin area
|
|
239
225
|
height: ...,
|
|
240
226
|
// The desired width of the marker's pin area
|
|
241
|
-
width:
|
|
227
|
+
width: ...,
|
|
242
228
|
// The desired radius of the marker's pin area
|
|
243
229
|
radius: ...,
|
|
244
230
|
},
|
|
@@ -251,7 +237,7 @@ for (let i = 0; i < count; i++) {
|
|
|
251
237
|
// The desired height of the marker's popup area
|
|
252
238
|
height: ...,
|
|
253
239
|
// The desired width of the marker's popup area
|
|
254
|
-
width:
|
|
240
|
+
width: ...,
|
|
255
241
|
// The desired margin of the marker's popup area
|
|
256
242
|
margin: ...,
|
|
257
243
|
// The desired radius of the marker's popup area
|
|
@@ -264,29 +250,26 @@ for (let i = 0; i < count; i++) {
|
|
|
264
250
|
}
|
|
265
251
|
|
|
266
252
|
await mapManager.updateMarkers(markers);
|
|
267
|
-
|
|
268
253
|
```
|
|
269
254
|
|
|
270
255
|
To remove all markers from the map, use the `removeMarkers` method:
|
|
271
256
|
|
|
272
|
-
```
|
|
257
|
+
```js
|
|
273
258
|
mapManager.removeMarkers();
|
|
274
|
-
|
|
275
259
|
```
|
|
276
260
|
|
|
277
261
|
To toggle the popup of a marker, use the `showPopup` and `hidePopup` methods:
|
|
278
262
|
|
|
279
|
-
```
|
|
263
|
+
```js
|
|
280
264
|
mapManager.showPopup(id);
|
|
281
265
|
mapManager.hidePopup(id);
|
|
282
|
-
|
|
283
266
|
```
|
|
284
267
|
|
|
285
268
|
## Style
|
|
286
269
|
|
|
287
270
|
You can change the markers style by using the predefined CSS variables:
|
|
288
271
|
|
|
289
|
-
```
|
|
272
|
+
```scss
|
|
290
273
|
--arenarium-maps-pin-background: ...;
|
|
291
274
|
--arenarium-maps-pin-border: ...;
|
|
292
275
|
--arenarium-maps-pin-shadow: ...;
|
|
@@ -294,7 +277,6 @@ You can change the markers style by using the predefined CSS variables:
|
|
|
294
277
|
--arenarium-maps-tooltip-background: ...;
|
|
295
278
|
--arenarium-maps-tooltip-shadow: ...;
|
|
296
279
|
--arenarium-maps-tooltip-shadow-hover: ...;
|
|
297
|
-
|
|
298
280
|
```
|
|
299
281
|
|
|
300
282
|
# Examples
|