@studiometa/ui-mapbox 2.0.0-alpha.0 → 2.0.0-alpha.2
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/README.md +22 -16
- package/dist/MapboxGeocoder.d.ts +48 -5
- package/dist/MapboxGeocoder.js +73 -15
- package/dist/MapboxGeocoder.js.map +1 -1
- package/dist/MapboxMap.js +1 -0
- package/dist/MapboxMap.js.map +1 -1
- package/dist/StoreLocator.js +1 -0
- package/dist/StoreLocator.js.map +1 -1
- package/dist/catalog.js +22 -11
- package/dist/catalog.js.map +1 -1
- package/dist/manifest.js +11 -11
- package/dist/manifest.js.map +1 -1
- package/dist/scripts/manifest-types.d.ts +5 -2
- package/package.json +7 -2
- package/skills/studiometa-ui-mapbox/SKILL.md +71 -0
- package/skills/studiometa-ui-mapbox/references/index.md +8 -0
- package/skills/studiometa-ui-mapbox/references/items/MapboxMap/examples.md +481 -0
- package/skills/studiometa-ui-mapbox/references/items/MapboxMap/index.md +102 -0
- package/skills/studiometa-ui-mapbox/references/items/MapboxMap/js-api.md +957 -0
- package/skills/studiometa-ui-mapbox/references/items/StoreLocator/examples.md +647 -0
- package/skills/studiometa-ui-mapbox/references/items/StoreLocator/index.md +135 -0
- package/skills/studiometa-ui-mapbox/references/items/StoreLocator/js-api.md +160 -0
|
@@ -0,0 +1,481 @@
|
|
|
1
|
+
# Examples
|
|
2
|
+
|
|
3
|
+
Every component in the family is registered independently, so each example registers exactly the components it uses — `MapboxMap` on its own for a bare map, plus the child components it declares (markers, popups, controls, sources, layers, images, clusters). Each child resolves its parent `MapboxMap` on its own once mounted. Each example loads the [Mapbox GL stylesheet](index.md#installation) from a CDN and picks a Mapbox style through the `map-options` option, which forwards any [`Map` option](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-parameters) to mapbox-gl. Replace the access token with your own [access token](https://docs.mapbox.com/help/getting-started/access-tokens/); the token used here is a public, restricted demo token.
|
|
4
|
+
|
|
5
|
+
Child components that should not take part in the normal document flow (markers, popups, controls, sources, layers, images, clusters) are wrapped in a `hidden` element: their markup is only used as a declarative definition, the actual rendering happens on the map canvas.
|
|
6
|
+
|
|
7
|
+
## Basic map
|
|
8
|
+
|
|
9
|
+
A minimal interactive map with a `container` ref and a size set through CSS.
|
|
10
|
+
|
|
11
|
+
```twig
|
|
12
|
+
<link rel="stylesheet" href="https://esm.sh/mapbox-gl@3.13.0/dist/mapbox-gl.css" />
|
|
13
|
+
|
|
14
|
+
<div
|
|
15
|
+
data-component="MapboxMap"
|
|
16
|
+
data-option-access-token="pk.eyJ1IjoiYWdlbmNlc3R1ZGlvbWV0YSIsImEiOiJjbXM5NTBycHMwa2Z4MndxeW02YndscmQyIn0.UitMikKpq-TRJOXM-rBcMg"
|
|
17
|
+
data-option-zoom="10"
|
|
18
|
+
data-option-center="[2.35, 48.86]"
|
|
19
|
+
data-option-map-options='{"style":"mapbox://styles/mapbox/streets-v12"}'
|
|
20
|
+
class="h-96 w-full">
|
|
21
|
+
<div data-ref="container" class="h-full w-full"></div>
|
|
22
|
+
</div>
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
```js
|
|
26
|
+
import { registerComponent } from '@studiometa/js-toolkit';
|
|
27
|
+
import { MapboxMap } from '@studiometa/ui-mapbox';
|
|
28
|
+
|
|
29
|
+
registerComponent(MapboxMap);
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
```css
|
|
33
|
+
html.dark {
|
|
34
|
+
background-color: #222;
|
|
35
|
+
color: #eee;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
body {
|
|
39
|
+
padding: 1rem;
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Markers and popups
|
|
44
|
+
|
|
45
|
+
Add a `MapboxMarker` for each point. A `MapboxPopup` nested inside a marker is attached to it and opens on click; a `MapboxPopup` placed directly on the map (with its own `lng-lat`) is displayed as a standalone popup. The popup content is taken from the element's inner HTML.
|
|
46
|
+
|
|
47
|
+
```twig
|
|
48
|
+
<link rel="stylesheet" href="https://esm.sh/mapbox-gl@3.13.0/dist/mapbox-gl.css" />
|
|
49
|
+
|
|
50
|
+
<div
|
|
51
|
+
data-component="MapboxMap"
|
|
52
|
+
data-option-access-token="pk.eyJ1IjoiYWdlbmNlc3R1ZGlvbWV0YSIsImEiOiJjbXM5NTBycHMwa2Z4MndxeW02YndscmQyIn0.UitMikKpq-TRJOXM-rBcMg"
|
|
53
|
+
data-option-zoom="12"
|
|
54
|
+
data-option-center="[2.35, 48.86]"
|
|
55
|
+
data-option-map-options='{"style":"mapbox://styles/mapbox/streets-v12"}'
|
|
56
|
+
class="h-96 w-full">
|
|
57
|
+
<div data-ref="container" class="h-full w-full"></div>
|
|
58
|
+
|
|
59
|
+
{# Marker with an attached popup, opened on click #}
|
|
60
|
+
<div hidden data-component="MapboxMarker" data-option-lng-lat="[2.35, 48.86]">
|
|
61
|
+
<div data-component="MapboxPopup">
|
|
62
|
+
<h3>Paris</h3>
|
|
63
|
+
<p>Capital of France</p>
|
|
64
|
+
</div>
|
|
65
|
+
</div>
|
|
66
|
+
|
|
67
|
+
{# Standalone popup, displayed directly on the map #}
|
|
68
|
+
<div hidden data-component="MapboxPopup" data-option-lng-lat="[2.29, 48.86]">
|
|
69
|
+
<p>Near the Eiffel Tower</p>
|
|
70
|
+
</div>
|
|
71
|
+
</div>
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
```js
|
|
75
|
+
import { registerComponents } from '@studiometa/js-toolkit';
|
|
76
|
+
import { MapboxMap, MapboxMarker, MapboxPopup } from '@studiometa/ui-mapbox';
|
|
77
|
+
|
|
78
|
+
// Register every component the markup uses.
|
|
79
|
+
registerComponents(MapboxMap, MapboxMarker, MapboxPopup);
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
```css
|
|
83
|
+
html.dark {
|
|
84
|
+
background-color: #222;
|
|
85
|
+
color: #eee;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
body {
|
|
89
|
+
padding: 1rem;
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## Navigation, geolocate and fullscreen controls
|
|
94
|
+
|
|
95
|
+
Controls are added by declaring the matching child component. Each control accepts a `position` option (`top-left`, `top-right`, `bottom-left`, `bottom-right`). This example also demonstrates the `map-options` option beyond the style: it sets a `pitch` and `bearing` for a tilted, rotated camera — click the navigation control's compass to reset the bearing.
|
|
96
|
+
|
|
97
|
+
```twig
|
|
98
|
+
<link rel="stylesheet" href="https://esm.sh/mapbox-gl@3.13.0/dist/mapbox-gl.css" />
|
|
99
|
+
|
|
100
|
+
{#
|
|
101
|
+
The `map-options` option forwards any mapbox-gl `Map` option. Here it sets a
|
|
102
|
+
specific style and a tilted, rotated camera (`pitch` + `bearing`) — the
|
|
103
|
+
navigation control's compass resets the bearing.
|
|
104
|
+
#}
|
|
105
|
+
<div
|
|
106
|
+
data-component="MapboxMap"
|
|
107
|
+
data-option-access-token="pk.eyJ1IjoiYWdlbmNlc3R1ZGlvbWV0YSIsImEiOiJjbXM5NTBycHMwa2Z4MndxeW02YndscmQyIn0.UitMikKpq-TRJOXM-rBcMg"
|
|
108
|
+
data-option-zoom="10"
|
|
109
|
+
data-option-center="[2.35, 48.86]"
|
|
110
|
+
data-option-map-options='{"style":"mapbox://styles/mapbox/streets-v12","pitch":45,"bearing":-17}'
|
|
111
|
+
class="h-96 w-full">
|
|
112
|
+
<div data-ref="container" class="h-full w-full"></div>
|
|
113
|
+
|
|
114
|
+
<div
|
|
115
|
+
hidden
|
|
116
|
+
data-component="MapboxNavigationControl"
|
|
117
|
+
data-option-position="top-right"
|
|
118
|
+
data-option-show-compass
|
|
119
|
+
data-option-show-zoom></div>
|
|
120
|
+
|
|
121
|
+
<div
|
|
122
|
+
hidden
|
|
123
|
+
data-component="MapboxGeolocateControl"
|
|
124
|
+
data-option-position="top-right"
|
|
125
|
+
data-option-track-user-location></div>
|
|
126
|
+
|
|
127
|
+
<div hidden data-component="MapboxFullscreenControl" data-option-position="top-right"></div>
|
|
128
|
+
</div>
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
```js
|
|
132
|
+
import { registerComponents } from '@studiometa/js-toolkit';
|
|
133
|
+
import {
|
|
134
|
+
MapboxMap,
|
|
135
|
+
MapboxNavigationControl,
|
|
136
|
+
MapboxGeolocateControl,
|
|
137
|
+
MapboxFullscreenControl,
|
|
138
|
+
} from '@studiometa/ui-mapbox';
|
|
139
|
+
|
|
140
|
+
// Register every component the markup uses.
|
|
141
|
+
registerComponents(
|
|
142
|
+
MapboxMap,
|
|
143
|
+
MapboxNavigationControl,
|
|
144
|
+
MapboxGeolocateControl,
|
|
145
|
+
MapboxFullscreenControl,
|
|
146
|
+
);
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
```css
|
|
150
|
+
html.dark {
|
|
151
|
+
background-color: #222;
|
|
152
|
+
color: #eee;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
body {
|
|
156
|
+
padding: 1rem;
|
|
157
|
+
}
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
## Geocoder
|
|
161
|
+
|
|
162
|
+
The `MapboxGeocoder` component adds an address search field powered by [`@mapbox/mapbox-gl-geocoder`](https://github.com/mapbox/mapbox-gl-geocoder). The `add-to-map` option controls where the input is rendered. The search itself calls the Mapbox Geocoding API, so it needs an access token authorized for geocoding; the examples below are shown as static markup.
|
|
163
|
+
|
|
164
|
+
With `add-to-map`, the geocoder is added to the map as a Mapbox control, overlaid on the map canvas:
|
|
165
|
+
|
|
166
|
+
```html
|
|
167
|
+
<div
|
|
168
|
+
data-component="MapboxMap"
|
|
169
|
+
data-option-access-token="<YOUR_MAPBOX_ACCESS_TOKEN>"
|
|
170
|
+
data-option-zoom="5"
|
|
171
|
+
data-option-center="[2.35, 48.86]"
|
|
172
|
+
class="h-96 w-full">
|
|
173
|
+
<div data-ref="container" class="h-full w-full"></div>
|
|
174
|
+
|
|
175
|
+
<div
|
|
176
|
+
data-component="MapboxGeocoder"
|
|
177
|
+
data-option-add-to-map
|
|
178
|
+
data-option-options='{"placeholder": "Search a place…"}'></div>
|
|
179
|
+
</div>
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Without `add-to-map`, the geocoder is rendered inside the component's own element, so you can place the search field anywhere in your layout, outside the map canvas:
|
|
183
|
+
|
|
184
|
+
```html
|
|
185
|
+
<div
|
|
186
|
+
data-component="MapboxMap"
|
|
187
|
+
data-option-access-token="<YOUR_MAPBOX_ACCESS_TOKEN>"
|
|
188
|
+
data-option-zoom="5"
|
|
189
|
+
data-option-center="[2.35, 48.86]"
|
|
190
|
+
class="h-96 w-full">
|
|
191
|
+
<!-- The search field renders here, above the map -->
|
|
192
|
+
<div
|
|
193
|
+
data-component="MapboxGeocoder"
|
|
194
|
+
data-option-options='{"placeholder": "Search a place…"}'></div>
|
|
195
|
+
<div data-ref="container" class="h-full w-full"></div>
|
|
196
|
+
</div>
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
The geocoder uses the access token of the parent `MapboxMap`, unless it sets its own with `data-option-access-token`.
|
|
200
|
+
|
|
201
|
+
Do not put `hidden` on a `MapboxGeocoder` element. With autoloading, the geocoder loads when its element nears the viewport, and a hidden element never does.
|
|
202
|
+
|
|
203
|
+
The geocoder also works without a map. Outside a `MapboxMap`, set its `data-option-access-token` and listen to `map-result` to use the selected address, for example to submit a search form:
|
|
204
|
+
|
|
205
|
+
```html
|
|
206
|
+
<div
|
|
207
|
+
data-component="MapboxGeocoder"
|
|
208
|
+
data-option-access-token="<YOUR_MAPBOX_ACCESS_TOKEN>"
|
|
209
|
+
data-option-options='{"placeholder": "Search a place…"}'></div>
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
See [Standalone usage](js-api.md#standalone-usage) for a complete example.
|
|
213
|
+
|
|
214
|
+
## Source and layer
|
|
215
|
+
|
|
216
|
+
Add a [source](https://docs.mapbox.com/style-spec/reference/sources/) with `MapboxSource`, then render it with one or more `MapboxLayer` elements referencing the source `id`. The `layer` option accepts a full [layer specification](https://docs.mapbox.com/style-spec/reference/layers/).
|
|
217
|
+
|
|
218
|
+
```twig
|
|
219
|
+
<link rel="stylesheet" href="https://esm.sh/mapbox-gl@3.13.0/dist/mapbox-gl.css" />
|
|
220
|
+
|
|
221
|
+
<div
|
|
222
|
+
data-component="MapboxMap"
|
|
223
|
+
data-option-access-token="pk.eyJ1IjoiYWdlbmNlc3R1ZGlvbWV0YSIsImEiOiJjbXM5NTBycHMwa2Z4MndxeW02YndscmQyIn0.UitMikKpq-TRJOXM-rBcMg"
|
|
224
|
+
data-option-zoom="11"
|
|
225
|
+
data-option-center="[2.35, 48.86]"
|
|
226
|
+
data-option-map-options='{"style":"mapbox://styles/mapbox/streets-v12"}'
|
|
227
|
+
class="h-96 w-full">
|
|
228
|
+
<div data-ref="container" class="h-full w-full"></div>
|
|
229
|
+
|
|
230
|
+
{# A GeoJSON source describing a route across Paris #}
|
|
231
|
+
<div
|
|
232
|
+
hidden
|
|
233
|
+
data-component="MapboxSource"
|
|
234
|
+
data-option-id="route"
|
|
235
|
+
data-option-source='{
|
|
236
|
+
"type": "geojson",
|
|
237
|
+
"data": {
|
|
238
|
+
"type": "Feature",
|
|
239
|
+
"geometry": {
|
|
240
|
+
"type": "LineString",
|
|
241
|
+
"coordinates": [
|
|
242
|
+
[2.2945, 48.8584],
|
|
243
|
+
[2.3376, 48.8606],
|
|
244
|
+
[2.3499, 48.8530],
|
|
245
|
+
[2.3653, 48.8467]
|
|
246
|
+
]
|
|
247
|
+
}
|
|
248
|
+
}
|
|
249
|
+
}'></div>
|
|
250
|
+
|
|
251
|
+
{# A line layer rendering the source #}
|
|
252
|
+
<div
|
|
253
|
+
hidden
|
|
254
|
+
data-component="MapboxLayer"
|
|
255
|
+
data-option-id="route-line"
|
|
256
|
+
data-option-layer='{
|
|
257
|
+
"type": "line",
|
|
258
|
+
"source": "route",
|
|
259
|
+
"layout": { "line-join": "round", "line-cap": "round" },
|
|
260
|
+
"paint": { "line-color": "#e11d48", "line-width": 5 }
|
|
261
|
+
}'></div>
|
|
262
|
+
</div>
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
```js
|
|
266
|
+
import { registerComponents } from '@studiometa/js-toolkit';
|
|
267
|
+
import { MapboxMap, MapboxSource, MapboxLayer } from '@studiometa/ui-mapbox';
|
|
268
|
+
|
|
269
|
+
// Register every component the markup uses.
|
|
270
|
+
registerComponents(MapboxMap, MapboxSource, MapboxLayer);
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
```css
|
|
274
|
+
html.dark {
|
|
275
|
+
background-color: #222;
|
|
276
|
+
color: #eee;
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
body {
|
|
280
|
+
padding: 1rem;
|
|
281
|
+
}
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
## Images
|
|
285
|
+
|
|
286
|
+
Register images against the map sprite so they can be referenced from a symbol layer's `icon-image`. Use `MapboxImage` for a single image, or `MapboxImages` to load several at once through its `sources` option. Both emit a `map-ready` event once the image(s) are loaded. The symbol layer below pairs each `icon-image` with a `text-field` label.
|
|
287
|
+
|
|
288
|
+
```twig
|
|
289
|
+
<link rel="stylesheet" href="https://esm.sh/mapbox-gl@3.13.0/dist/mapbox-gl.css" />
|
|
290
|
+
|
|
291
|
+
<div
|
|
292
|
+
data-component="MapboxMap"
|
|
293
|
+
data-option-access-token="pk.eyJ1IjoiYWdlbmNlc3R1ZGlvbWV0YSIsImEiOiJjbXM5NTBycHMwa2Z4MndxeW02YndscmQyIn0.UitMikKpq-TRJOXM-rBcMg"
|
|
294
|
+
data-option-zoom="4"
|
|
295
|
+
data-option-center="[2.35, 48.86]"
|
|
296
|
+
data-option-map-options='{"style":"mapbox://styles/mapbox/streets-v12"}'
|
|
297
|
+
class="h-96 w-full">
|
|
298
|
+
<div data-ref="container" class="h-full w-full"></div>
|
|
299
|
+
|
|
300
|
+
{# Load several images at once into the map sprite #}
|
|
301
|
+
<div
|
|
302
|
+
hidden
|
|
303
|
+
data-component="MapboxImages"
|
|
304
|
+
data-option-sources='[
|
|
305
|
+
{ "name": "cat", "url": "https://docs.mapbox.com/mapbox-gl-js/assets/cat.png" },
|
|
306
|
+
{ "name": "dog", "url": "https://docs.mapbox.com/mapbox-gl-js/assets/dog.png" }
|
|
307
|
+
]'></div>
|
|
308
|
+
|
|
309
|
+
{# Points carrying the icon name and label to use #}
|
|
310
|
+
<div
|
|
311
|
+
hidden
|
|
312
|
+
data-component="MapboxSource"
|
|
313
|
+
data-option-id="pets"
|
|
314
|
+
data-option-source='{
|
|
315
|
+
"type": "geojson",
|
|
316
|
+
"data": {
|
|
317
|
+
"type": "FeatureCollection",
|
|
318
|
+
"features": [
|
|
319
|
+
{ "type": "Feature", "properties": { "icon": "cat", "label": "Cat" }, "geometry": { "type": "Point", "coordinates": [2.35, 48.86] } },
|
|
320
|
+
{ "type": "Feature", "properties": { "icon": "dog", "label": "Dog" }, "geometry": { "type": "Point", "coordinates": [4.83, 45.76] } }
|
|
321
|
+
]
|
|
322
|
+
}
|
|
323
|
+
}'></div>
|
|
324
|
+
|
|
325
|
+
{# A symbol layer rendering each point with its icon and a text label #}
|
|
326
|
+
<div
|
|
327
|
+
hidden
|
|
328
|
+
data-component="MapboxLayer"
|
|
329
|
+
data-option-id="pets-icons"
|
|
330
|
+
data-option-layer='{
|
|
331
|
+
"type": "symbol",
|
|
332
|
+
"source": "pets",
|
|
333
|
+
"layout": {
|
|
334
|
+
"icon-image": ["get", "icon"],
|
|
335
|
+
"icon-size": 0.15,
|
|
336
|
+
"icon-allow-overlap": true,
|
|
337
|
+
"text-field": ["get", "label"],
|
|
338
|
+
"text-offset": [0, 1.6],
|
|
339
|
+
"text-anchor": "top",
|
|
340
|
+
"text-size": 14
|
|
341
|
+
},
|
|
342
|
+
"paint": {
|
|
343
|
+
"text-halo-color": "#fff",
|
|
344
|
+
"text-halo-width": 1
|
|
345
|
+
}
|
|
346
|
+
}'></div>
|
|
347
|
+
</div>
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
```js
|
|
351
|
+
import { registerComponents } from '@studiometa/js-toolkit';
|
|
352
|
+
import { MapboxMap, MapboxImages, MapboxSource, MapboxLayer } from '@studiometa/ui-mapbox';
|
|
353
|
+
|
|
354
|
+
// Register every component the markup uses.
|
|
355
|
+
registerComponents(MapboxMap, MapboxImages, MapboxSource, MapboxLayer);
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
```css
|
|
359
|
+
html.dark {
|
|
360
|
+
background-color: #222;
|
|
361
|
+
color: #eee;
|
|
362
|
+
}
|
|
363
|
+
|
|
364
|
+
body {
|
|
365
|
+
padding: 1rem;
|
|
366
|
+
}
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
## Cluster
|
|
370
|
+
|
|
371
|
+
The `MapboxCluster` component is a clustered GeoJSON **source driver**: it derives its source from the `MapboxClusterItem`s in its subtree, wiring the cluster circles, the cluster count labels and the unclustered points, together with the click-to-zoom interaction. Each item is at once a list entry and a map feature — the same markup drives both. The example below declares a hidden list of items; click a cluster to zoom in and split it.
|
|
372
|
+
|
|
373
|
+
```twig
|
|
374
|
+
<link rel="stylesheet" href="https://esm.sh/mapbox-gl@3.13.0/dist/mapbox-gl.css" />
|
|
375
|
+
|
|
376
|
+
{% set points = [
|
|
377
|
+
[2.3522, 48.8566], [2.2945, 48.8584], [2.3376, 48.8606], [2.3499, 48.853],
|
|
378
|
+
[2.3212, 48.8656], [4.8357, 45.764], [4.8467, 45.7578], [5.3698, 43.2965],
|
|
379
|
+
[5.38, 43.29], [-0.5792, 44.8378], [-1.5536, 47.2184], [3.0573, 50.6292],
|
|
380
|
+
[7.7521, 48.5734], [1.4442, 43.6047], [1.4535, 43.6108], [-4.4861, 48.3904],
|
|
381
|
+
[4.3872, 50.8503], [6.1432, 46.2044]
|
|
382
|
+
] %}
|
|
383
|
+
|
|
384
|
+
<div
|
|
385
|
+
data-component="MapboxMap"
|
|
386
|
+
data-option-access-token="pk.eyJ1IjoiYWdlbmNlc3R1ZGlvbWV0YSIsImEiOiJjbXM5NTBycHMwa2Z4MndxeW02YndscmQyIn0.UitMikKpq-TRJOXM-rBcMg"
|
|
387
|
+
data-option-zoom="4"
|
|
388
|
+
data-option-center="[2.35, 48.86]"
|
|
389
|
+
data-option-map-options='{"style":"mapbox://styles/mapbox/streets-v12"}'
|
|
390
|
+
class="h-96 w-full">
|
|
391
|
+
<div data-ref="container" class="h-full w-full"></div>
|
|
392
|
+
|
|
393
|
+
{# The cluster derives its source from the MapboxClusterItems in its subtree.
|
|
394
|
+
Here they carry no visible list, so the wrapper is hidden — the same markup
|
|
395
|
+
would double as a sidebar in a StoreLocator. #}
|
|
396
|
+
<div
|
|
397
|
+
hidden
|
|
398
|
+
data-component="MapboxCluster"
|
|
399
|
+
data-option-cluster-radius="60"
|
|
400
|
+
data-option-clusters-paint='{ "circle-color": "#51bbd6", "circle-radius": 20 }'
|
|
401
|
+
data-option-unclustered-point-paint='{ "circle-color": "#f28cb1", "circle-radius": 6, "circle-stroke-width": 1, "circle-stroke-color": "#fff" }'>
|
|
402
|
+
<ul>
|
|
403
|
+
{% for point in points %}
|
|
404
|
+
<li
|
|
405
|
+
data-component="MapboxClusterItem"
|
|
406
|
+
data-option-id="p{{ loop.index }}"
|
|
407
|
+
data-option-lng-lat="{{ point|json_encode }}"></li>
|
|
408
|
+
{% endfor %}
|
|
409
|
+
</ul>
|
|
410
|
+
</div>
|
|
411
|
+
</div>
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
```js
|
|
415
|
+
import { registerComponents } from '@studiometa/js-toolkit';
|
|
416
|
+
import { MapboxMap, MapboxCluster, MapboxClusterItem } from '@studiometa/ui-mapbox';
|
|
417
|
+
|
|
418
|
+
registerComponents(MapboxMap, MapboxCluster, MapboxClusterItem);
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
```css
|
|
422
|
+
html.dark {
|
|
423
|
+
background-color: #222;
|
|
424
|
+
color: #eee;
|
|
425
|
+
}
|
|
426
|
+
|
|
427
|
+
body {
|
|
428
|
+
padding: 1rem;
|
|
429
|
+
}
|
|
430
|
+
```
|
|
431
|
+
|
|
432
|
+
### Items drive the source {#cluster-items}
|
|
433
|
+
|
|
434
|
+
The cluster owns no authored data. Each point is a `MapboxClusterItem` that self-registers with the closest `MapboxCluster` ancestor; the cluster derives a clustered GeoJSON `FeatureCollection` from the registry and rebuilds it (debounced) whenever items mount or unmount:
|
|
435
|
+
|
|
436
|
+
```html
|
|
437
|
+
<div hidden data-component="MapboxCluster" data-option-cluster-radius="60">
|
|
438
|
+
<ul>
|
|
439
|
+
<li
|
|
440
|
+
data-component="MapboxClusterItem"
|
|
441
|
+
data-option-id="a"
|
|
442
|
+
data-option-lng-lat="[2.35, 48.86]"></li>
|
|
443
|
+
<li
|
|
444
|
+
data-component="MapboxClusterItem"
|
|
445
|
+
data-option-id="b"
|
|
446
|
+
data-option-lng-lat="[2.29, 48.86]"></li>
|
|
447
|
+
<li
|
|
448
|
+
data-component="MapboxClusterItem"
|
|
449
|
+
data-option-id="c"
|
|
450
|
+
data-option-lng-lat="[-0.13, 51.51]"></li>
|
|
451
|
+
</ul>
|
|
452
|
+
</div>
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
The cluster reports a click on an unclustered point through its `map-item-click` event but never selects or flies on its own. To turn this into a full "find a store near you" experience — selection, popups, viewport filtering and address search — wrap the cluster in a [`StoreLocator`](../StoreLocator/index.md) orchestrator.
|
|
456
|
+
|
|
457
|
+
## Listening to map events
|
|
458
|
+
|
|
459
|
+
The `MapboxMap` component re-emits the Mapbox map events with a `map-` prefix to avoid conflicts with native events. Listen to them from a parent component by defining `on<ComponentName><EventName>` methods — for example `onMapboxMapMapClick` or `onMapboxMapMapLoad`.
|
|
460
|
+
|
|
461
|
+
```js
|
|
462
|
+
import { Base, registerComponent } from '@studiometa/js-toolkit';
|
|
463
|
+
import { MapboxMap } from '@studiometa/ui-mapbox';
|
|
464
|
+
|
|
465
|
+
class App extends Base {
|
|
466
|
+
static config = {
|
|
467
|
+
name: 'App',
|
|
468
|
+
components: { MapboxMap },
|
|
469
|
+
};
|
|
470
|
+
|
|
471
|
+
onMapboxMapMapLoad({ payload: { map } }) {
|
|
472
|
+
console.log('Map loaded', map);
|
|
473
|
+
}
|
|
474
|
+
|
|
475
|
+
onMapboxMapMapClick({ payload: { event } }) {
|
|
476
|
+
console.log('Clicked at', event.lngLat);
|
|
477
|
+
}
|
|
478
|
+
}
|
|
479
|
+
|
|
480
|
+
registerComponent(App);
|
|
481
|
+
```
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
# MapboxMap
|
|
2
|
+
|
|
3
|
+
The `MapboxMap` component and its family let you build [Mapbox GL](https://docs.mapbox.com/mapbox-gl-js/) maps declaratively, straight from your HTML, with [js-toolkit](https://js-toolkit.studiometa.dev/). A `MapboxMap` element owns the underlying Mapbox `Map` instance, and every other component (markers, popups, controls, sources, layers, images, clusters) is authored as a child element that registers itself against that map once it is loaded.
|
|
4
|
+
|
|
5
|
+
These components are published in the standalone [`@studiometa/ui-mapbox`](https://www.npmjs.com/package/@studiometa/ui-mapbox) package and replace the [`@studiometa/vue-mapbox-gl`](https://www.npmjs.com/package/@studiometa/vue-mapbox-gl) library. If you are coming from the Vue library, read the [migration guide](https://ui-v2.studiometa.dev/migration-guides/vue-mapbox-gl/).
|
|
6
|
+
|
|
7
|
+
## Table of content
|
|
8
|
+
|
|
9
|
+
- [Examples](examples.md)
|
|
10
|
+
- [JS API](js-api.md)
|
|
11
|
+
|
|
12
|
+
## Installation
|
|
13
|
+
|
|
14
|
+
Install the package alongside its `mapbox-gl` peer dependency. The [`@mapbox/mapbox-gl-geocoder`](https://github.com/mapbox/mapbox-gl-geocoder) package is only required if you use the [`MapboxGeocoder`](js-api.md#mapboxgeocoder) component.
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
npm install @studiometa/ui-mapbox mapbox-gl
|
|
18
|
+
|
|
19
|
+
# Optional, only for the geocoder control
|
|
20
|
+
npm install @mapbox/mapbox-gl-geocoder
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
The Mapbox GL stylesheet is required for the map, its controls and popups to render correctly. Add it to your page, either as a `<link>` tag pointing to the CDN or by importing it from the package with your bundler.
|
|
24
|
+
|
|
25
|
+
```html
|
|
26
|
+
<link rel="stylesheet" href="https://api.mapbox.com/mapbox-gl-js/v3.13.0/mapbox-gl.css" />
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
```css
|
|
30
|
+
/* or, when using a bundler */
|
|
31
|
+
@import 'mapbox-gl/dist/mapbox-gl.css';
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
You will also need a [Mapbox access token](https://docs.mapbox.com/help/getting-started/access-tokens/). Pass it to the `MapboxMap` component through the `access-token` option.
|
|
35
|
+
|
|
36
|
+
## Usage
|
|
37
|
+
|
|
38
|
+
[Register](https://ui-v2.studiometa.dev/guide/usage/#registering-components) each component your page uses: a bare map with just a `container` needs only `MapboxMap`, and each marker, popup, control, source, layer, image or cluster you declare must be registered too. Registration order does not matter, because a child registered before its `MapboxMap` still wires up once the map connects.
|
|
39
|
+
|
|
40
|
+
Author the map with a root `MapboxMap` element holding a `container` ref, and give it a size through CSS.
|
|
41
|
+
|
|
42
|
+
```js [app.js]
|
|
43
|
+
import { registerComponent } from '@studiometa/js-toolkit';
|
|
44
|
+
import { MapboxMap } from '@studiometa/ui-mapbox';
|
|
45
|
+
|
|
46
|
+
registerComponent(MapboxMap);
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
```html [index.html]
|
|
50
|
+
<div
|
|
51
|
+
data-component="MapboxMap"
|
|
52
|
+
data-option-access-token="<YOUR_MAPBOX_ACCESS_TOKEN>"
|
|
53
|
+
data-option-zoom="10"
|
|
54
|
+
data-option-center="[2.35, 48.86]"
|
|
55
|
+
class="h-96 w-full">
|
|
56
|
+
<div data-ref="container" class="h-full w-full"></div>
|
|
57
|
+
</div>
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
```css [app.css]
|
|
61
|
+
@import 'mapbox-gl/dist/mapbox-gl.css';
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
`mapbox-gl` is a heavy dependency (~230 kB gzipped, more with the geocoder), so the recommended default is to register the components as lazy manifest entries — see [Lazy loading](#lazy-loading) below.
|
|
65
|
+
|
|
66
|
+
## Lazy loading
|
|
67
|
+
|
|
68
|
+
`mapbox-gl` is never in your main bundle: `MapboxMap` loads it with a dynamic `import()` when it mounts, and `MapboxMap` mounts only when the map nears the viewport, whether you register the class or a manifest entry. Registering the family as a [manifest](https://ui-v2.studiometa.dev/guide/autoloading/) rather than as classes also defers the component modules. A manifest entry is a lazy importer plus a mount strategy, so a component module loads only when an element on the page declares its token, and only when its strategy allows.
|
|
69
|
+
|
|
70
|
+
The package ships its own manifest, which is the shortest way to get all of it:
|
|
71
|
+
|
|
72
|
+
```js
|
|
73
|
+
import { registerManifest } from '@studiometa/js-toolkit';
|
|
74
|
+
import { manifest } from '@studiometa/ui-mapbox/manifest';
|
|
75
|
+
|
|
76
|
+
registerManifest(manifest);
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Every component is also available at its own subpath (`@studiometa/ui-mapbox/<Component>`), whose default export is the component class, so a hand-written manifest can carry only the components you use. Each component is registered independently, so list every one you declare: deferring `MapboxMap` pulls in `mapbox-gl`, but a marker or a cluster is its own module and needs its own entry.
|
|
80
|
+
|
|
81
|
+
```js
|
|
82
|
+
import { registerManifest } from '@studiometa/js-toolkit';
|
|
83
|
+
|
|
84
|
+
registerManifest({
|
|
85
|
+
MapboxMap: {
|
|
86
|
+
mountStrategy: 'visible',
|
|
87
|
+
load: () => import('@studiometa/ui-mapbox/MapboxMap'),
|
|
88
|
+
},
|
|
89
|
+
MapboxMarker: {
|
|
90
|
+
mountStrategy: 'eager',
|
|
91
|
+
load: () => import('@studiometa/ui-mapbox/MapboxMarker'),
|
|
92
|
+
},
|
|
93
|
+
MapboxPopup: {
|
|
94
|
+
mountStrategy: 'eager',
|
|
95
|
+
load: () => import('@studiometa/ui-mapbox/MapboxPopup'),
|
|
96
|
+
},
|
|
97
|
+
});
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The map renders, so `visible` holds the `mapbox-gl` import back until a map approaches the viewport. A marker renders nothing, so its element carries `hidden`, and a popup nested in it is hidden with it. A standalone popup shows its content until the map is ready, unless its element carries `hidden` too. A hidden element never intersects the viewport, so give markers and popups `eager`, which waits for nothing beyond the element being on the page. This is what the package manifest already does — see [Package defaults](https://ui-v2.studiometa.dev/guide/autoloading/#package-defaults).
|
|
101
|
+
|
|
102
|
+
Reach for a different strategy when it fits better — `idle`, `interaction`, `media:<query>` — and override any of them per element with `data-mount`. The [Autoloading](https://ui-v2.studiometa.dev/guide/autoloading/) guide lists all six.
|