@arenarium/maps 1.0.171 → 1.0.173

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 (5) hide show
  1. package/README.md +309 -2
  2. package/dist/index.js +1 -1
  3. package/dist/main.cjs.js +1 -1
  4. package/dist/main.es.js +98 -98
  5. package/package.json +1 -1
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)