@arenarium/maps 1.0.172 → 1.0.174

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.
Files changed (3) hide show
  1. package/LICENSE.txt +16 -23
  2. package/README.md +309 -2
  3. 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
- All rights reserved.
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
- Redistribution and use in source and binary forms, with or without modification,
7
- are permitted provided that the following conditions are met:
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
- * Redistributions of source code must retain the above copyright notice,
10
- this list of conditions and the following disclaimer.
11
- * Redistributions in binary form must reproduce the above copyright notice,
12
- this list of conditions and the following disclaimer in the documentation
13
- and/or other materials provided with the distribution.
14
- * Neither the name of arenarium.dev nor the names of its contributors may be
15
- may be used to endorse or promote products derived from this software
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
@@ -1,7 +1,314 @@
1
- ## Usage
1
+ # Installation
2
+
3
+ ## NPM
4
+
5
+ To install the `@aranarium/maps` library using npm, run the following command in your project directory:
6
+
7
+ ```
8
+ npm install @arenarium/maps
9
+
10
+ ```
11
+
12
+ Import the necessary module and CSS file into your project to begin using the map:
13
+
14
+ ```
15
+ import { MapManager } from '@arenarium/maps';
16
+ import '@arenarium/maps/dist/style.css';
17
+
18
+ // Initialize and mount the map manager (further configuration details follow)
19
+ const mapManager = new MapManager(...);
20
+
21
+ ```
22
+
23
+ ## CDN
24
+
25
+ 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
+
27
+ ```
28
+ <script src="https://unpkg.com/maplibre-gl@^5.6.0/dist/maplibre-gl.js"></script>
29
+ <link href="https://unpkg.com/maplibre-gl@^5.6.0/dist/maplibre-gl.css" rel="stylesheet" />
30
+
31
+ <script src="https://unpkg.com/@arenarium/maps@^1.0.124/dist/index.js"></script>
32
+ <link href="https://unpkg.com/@arenarium/maps@^1.0.124/dist/style.css" rel="stylesheet" />
33
+
34
+ ```
35
+
36
+ Once included, you can access the library's functions through the global `arenarium` object to mount the map:
37
+
38
+ ```
39
+ // Initialize and mount the map manager (further configuration details follow)
40
+ const mapManager = new arenarium.MapManager(...);
41
+
42
+ ```
43
+
44
+ # Usage
45
+
46
+ ## Initialization
47
+
48
+ 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
+
50
+ ```
51
+ <div id="map"></div>
52
+
53
+ ```
54
+
55
+ ## Maplibre GL
56
+
57
+ First, install the `maplibre-gl` library:
58
+
59
+ ```
60
+ npm install maplibre-gl
61
+
62
+ ```
63
+
64
+ Next, use the `MapManager` class which requires a `maplibre.Map` class, a `maplibre.Marker` class and a `MapOptions` object.
65
+
66
+ ```
67
+ import maplibregl from 'maplibre-gl';
68
+ import 'maplibre-gl/dist/maplibre-gl.css';
69
+
70
+ import { MapManager } from '@arenarium/maps';
71
+ import { MapLibreProvider } from '@arenarium/maps/maplibre';
72
+ import '@arenarium/maps/dist/style.css';
73
+
74
+ // Create a maplibre provider instance
75
+ const maplibreProvider = new MapLibreProvider(maplibregl.Map, maplibregl.Marker, {
76
+ container: 'map',
77
+ ...
78
+ });
79
+
80
+ // Initialize the map manager with the provider
81
+ const mapManager = new MapManager(maplibreProvider);
82
+
83
+ // Access the maplibre instance for direct map interactions
84
+ const maplibreMap = mapLibreProvider.getMap();
85
+
86
+ ```
87
+
88
+ You can change the map's visual appearance by setting a predefined dark or light theme:
89
+
90
+ ```
91
+ import { MaplibreDarkStyle, MaplibreLightStyle } from '@arenarium/maps/maplibre';
92
+
93
+ maplibreMap.setStyle(MaplibreDarkStyle); // or MaplibreLightStyle
94
+
95
+ ```
96
+
97
+ 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
+
99
+ ```
100
+ mapLibre.setStyle('https://tiles.openfreemap.org/styles/liberty.json');
101
+
102
+ ```
103
+
104
+ ## Mapbox GL
105
+
106
+ First, install the `mapbox-gl` library:
107
+
108
+ ```
109
+ npm install mapbox-gl
110
+
111
+ ```
112
+
113
+ Next, use the `MapManager` class which requires a `mapbox.Map` class, a `mapbox.Marker` class and a `MapOptions` object.
114
+
115
+ ```
116
+ import mapbox from 'mapbox-gl';
117
+ import 'mapbox-gl/dist/mapbox-gl.css';
118
+
119
+ import { MapManager } from '@arenarium/maps';
120
+ import { MapboxProvider } from '@arenarium/maps/mapbox';
121
+ import '@arenarium/maps/dist/style.css';
122
+
123
+ // Create a mapbox provider instance
124
+ const mapboxProvider = new MapboxProvider(mapbox.Map, mapbox.Marker, {
125
+ container: 'map',
126
+ ...
127
+ });
128
+
129
+ // Initialize the map manager with the provider
130
+ const mapManager = new MapManager(mapboxProvider);
131
+
132
+ // Access the mapbox instance for direct map interactions
133
+ const mapboxMap = mapboxProvider.getMap();
134
+
135
+ ```
136
+
137
+ ## Google Maps
138
+
139
+ First, install the `@googlemaps/js-api-loader` library:
140
+
141
+ ```
142
+ npm install @googlemaps/js-api-loader
143
+
144
+ ```
145
+
146
+ To use Google Maps, you'll need to load the Google Maps JavaScript API and create a Google Maps provider instance.
147
+
148
+ ```
149
+ import { Loader } from '@googlemaps/js-api-loader';
150
+
151
+ import { MapManager } from '@arenarium/maps';
152
+ import { GoogleMapsProvider } from '@arenarium/maps/google';
153
+ import '@arenarium/maps/dist/style.css';
154
+
155
+ // Load Google Maps API
156
+ const loader = new Loader({
157
+ apiKey: 'YOUR_GOOGLE_MAPS_API_KEY',
158
+ version: 'weekly'
159
+ });
160
+
161
+ // Import required libraries
162
+ const mapsLibrary = await loader.importLibrary('maps');
163
+ const markerLibrary = await loader.importLibrary('marker');
164
+
165
+ // Create a Google Maps provider instance
166
+ const mapElement = document.getElementById('map')!;
167
+ const mapGoogleProvider = new GoogleMapsProvider(mapsLibrary.Map, markerLibrary.AdvancedMarkerElement, mapElement, {
168
+ mapId: 'YOUR_GOOGLE_MAPS_MAP_ID', // For enabling advanced marker elements
169
+ ...
170
+ });
171
+
172
+ // Initialize the map manager with the provider
173
+ const mapManager = new MapManager(mapGoogleProvider);
174
+
175
+ // Access the Google Maps instance for direct map interactions
176
+ const mapGoogle = mapGoogleProvider.getMap();
177
+
178
+ ```
179
+
180
+ You can change the map's visual appearance by using the predefined styles in combination with custom `StyledMapType`:
181
+
182
+ ```
183
+ import { GoogleMapsDarkStyle, GoogleMapsLightStyle } from '@arenarium/maps/google';
184
+
185
+ const mapTypeLight = new google.maps.StyledMapType(GoogleMapsLightStyle, { name: 'Light Map' });
186
+ const mapTypeDark = new google.maps.StyledMapType(GoogleMapsDarkStyle, { name: 'Dark Map' });
187
+
188
+ mapGoogle.mapTypes.set("light-id", mapTypeLight);
189
+ mapGoogle.mapTypes.set("dark-id", mapTypeDark);
190
+
191
+ mapGoogle.setMapTypeId("light-id"); // or "dark-id" for dark theme
192
+
193
+ ```
194
+
195
+ ## Markers
196
+
197
+ A marker consist of a pin, a tooltip and an optional popup. The pin is an element that should convey the marker's location and and basic information like an icon or a color. The tooltip is an element that should provide additional information thats needs to be readable, it could be small or large amount of information depending on the application. The popup is an element that should be displayed when the user clicks on the marker. It should contain additional information thats not necessary or too large for a tooltip.
198
+
199
+ The markers toogle between the pin and the tooltip elements as the user zoom in. The pin is displayed when there is no room for the tooltip. When the user zooms in and more space is available, more tooltips are displayed. Which tooltips are displayed first is determined by the ranking of the markers. The higher the rank, the sooner the tooltip is displayed.
200
+
201
+ To add markers to the map, you first need to define an array of `MapMarker` objects. Provide the base marker data and the configuration for the tooltip, pin and popup. The configurations have body callbacks which should return a `HTMLElement`.
202
+
203
+ 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
+
205
+ ```
206
+ import { type MapMarker } from '@arenarium/maps';
207
+
208
+ const markers: MapMarker[] = [];
209
+
210
+ for (let i = 0; i < count; i++) {
211
+ markers.push({
212
+ // A unique identifier for the marker
213
+ id: ...,
214
+ // The ranking of the marker, used for prioritization
215
+ rank: ..,
216
+ // The latitude of the marker's location
217
+ lat: ...,
218
+ // The longitude of the marker's location
219
+ lng: ...,
220
+ // The tooltip configuration of the marker (required)
221
+ tooltip: {
222
+ style: {
223
+ // The desired height of the marker's tooltip area
224
+ height: ...,
225
+ // The desired width of the marker's tooltip area
226
+ width: ...
227
+ // The desired margin of the marker's tooltip area
228
+ margin: ...,
229
+ // The desired radius of the marker's tooltip area
230
+ radius: ...,
231
+ },
232
+ // Callback function that returns the HTMLElement object for the tooltip body
233
+ body: async (id) => { ... }
234
+ },
235
+ // The pin configuration of the marker (optional)
236
+ pin: {
237
+ style: {
238
+ // The desired height of the marker's pin area
239
+ height: ...,
240
+ // The desired width of the marker's pin area
241
+ width: ...
242
+ // The desired radius of the marker's pin area
243
+ radius: ...,
244
+ },
245
+ // Callback function that returns the HTMLElement object for the pin body
246
+ body: async (id) => { ... }
247
+ },
248
+ // The popup configuration of the marker (optional)
249
+ popup: {
250
+ style: {
251
+ // The desired height of the marker's popup area
252
+ height: ...,
253
+ // The desired width of the marker's popup area
254
+ width: ...
255
+ // The desired margin of the marker's popup area
256
+ margin: ...,
257
+ // The desired radius of the marker's popup area
258
+ radius: ...,
259
+ },
260
+ // Callback function that returns the HTMLElement object for the popup body
261
+ body: async (id) => { ... }
262
+ }
263
+ });
264
+ }
265
+
266
+ await mapManager.updateMarkers(markers);
267
+
268
+ ```
269
+
270
+ To remove all markers from the map, use the `removeMarkers` method:
271
+
272
+ ```
273
+ mapManager.removeMarkers();
274
+
275
+ ```
276
+
277
+ To toggle the popup of a marker, use the `showPopup` and `hidePopup` methods:
278
+
279
+ ```
280
+ mapManager.showPopup(id);
281
+ mapManager.hidePopup(id);
282
+
283
+ ```
284
+
285
+ ## Style
286
+
287
+ You can change the markers style by using the predefined CSS variables:
288
+
289
+ ```
290
+ --arenarium-maps-pin-background: ...;
291
+ --arenarium-maps-pin-border: ...;
292
+ --arenarium-maps-pin-shadow: ...;
293
+
294
+ --arenarium-maps-tooltip-background: ...;
295
+ --arenarium-maps-tooltip-shadow: ...;
296
+ --arenarium-maps-tooltip-shadow-hover: ...;
297
+
298
+ ```
299
+
300
+ # Examples
301
+
302
+ [https://github.com/arenarium-dev/arenarium-maps-svelte-kit-example](https://github.com/arenarium-dev/arenarium-maps-svelte-kit-example)
303
+
304
+ # About
305
+
306
+ **@arenarium/maps** is a library designed for the efficient visualization of a large number of ranked points of interest on your maps. It excels in scenarios where you need to present numerous location-based markers with a clear visual hierarchy based on their importance or ranking. By leveraging optimized rendering techniques and a dedicated API for managing dynamic marker states, this library ensures a smooth and informative user experience.
307
+
308
+ # Docs
2
309
 
3
310
  https://arenarium.dev/docs
4
311
 
5
- ## License
312
+ # License
6
313
 
7
314
  [MIT](LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arenarium/maps",
3
- "version": "1.0.172",
3
+ "version": "1.0.174",
4
4
  "license": "MIT",
5
5
  "author": "arenarium.dev",
6
6
  "description": "Visualize complex map markers clearly.",