@studiometa/ui-mapbox 2.0.0-alpha.1 → 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 +10 -0
- 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,957 @@
|
|
|
1
|
+
# JS API
|
|
2
|
+
|
|
3
|
+
This page documents thirteen components — a single root component, `MapboxMap`, which owns the Mapbox `Map` instance, plus the twelve children below — built on the `AbstractMapboxMapChild` (and, for controls, `AbstractMapboxControl`) base classes. The [`StoreLocator`](../StoreLocator/index.md) orchestrator completes the family on its own page. Every map child resolves the closest parent `MapboxMap` on its own and registers itself against its map once it is loaded. `MapboxClusterItem` is the one exception: it is a rendered list element that extends `Base` directly, and resolves the closest `MapboxCluster` instead of a map.
|
|
4
|
+
|
|
5
|
+
[Register](https://ui-v2.studiometa.dev/guide/usage/#registering-components) each component you use — ideally through a lazy [manifest](https://ui-v2.studiometa.dev/guide/autoloading/) entry so the heavy `mapbox-gl` dependency stays out of your main bundle (see [Lazy loading](index.md#lazy-loading)).
|
|
6
|
+
|
|
7
|
+
- **[Map](#map)** — `MapboxMap`
|
|
8
|
+
- **[Markers & Popups](#markers-popups)** — `MapboxMarker`, `MapboxPopup`
|
|
9
|
+
- **[Controls](#controls)** — `MapboxNavigationControl`, `MapboxGeolocateControl`, `MapboxFullscreenControl`, `MapboxGeocoder`
|
|
10
|
+
- **[Data](#data)** — `MapboxSource`, `MapboxLayer`, `MapboxImage`, `MapboxImages`
|
|
11
|
+
- **[Cluster](#cluster)** — `MapboxCluster`, `MapboxClusterItem` (see also the [`StoreLocator`](../StoreLocator/index.md) orchestrator)
|
|
12
|
+
- **[AbstractMapboxMapChild](#abstractmapboxmapchild)** — the shared base class
|
|
13
|
+
|
|
14
|
+
## Providing the `mapbox-gl` dependency
|
|
15
|
+
|
|
16
|
+
By default the components resolve `mapbox-gl` (and the optional `@mapbox/mapbox-gl-geocoder`) with a lazy `import()` the first time a map is built, so nothing needs configuring — keep `mapbox-gl` installed and it just works, staying out of your main bundle until a map is on the page.
|
|
17
|
+
|
|
18
|
+
To control which `mapbox-gl` the components use — a pinned version, a self-hosted build (for example a same-origin worker under a strict CSP), or a module served from an import map or a CDN — inject your own instance once, before the components mount:
|
|
19
|
+
|
|
20
|
+
```js
|
|
21
|
+
import mapboxgl from 'mapbox-gl';
|
|
22
|
+
import MapboxGeocoder from '@mapbox/mapbox-gl-geocoder';
|
|
23
|
+
import { provideMapboxGl, provideMapboxGeocoder } from '@studiometa/ui-mapbox';
|
|
24
|
+
|
|
25
|
+
provideMapboxGl(mapboxgl);
|
|
26
|
+
provideMapboxGeocoder(MapboxGeocoder); // optional geocoder peer
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Once provided, `@studiometa/ui-mapbox` never imports `mapbox-gl` by specifier — it uses the instance you handed it. `resolveMapboxGl()` and `resolveMapboxGeocoder()` are exported too if you want to trigger and await resolution yourself (for example to preload the module).
|
|
30
|
+
|
|
31
|
+
## Reactivity and updates
|
|
32
|
+
|
|
33
|
+
To move the map, change its data or update a marker after mount, reach for the underlying Mapbox objects directly through the component instances:
|
|
34
|
+
|
|
35
|
+
```js
|
|
36
|
+
import { getInstance } from '@studiometa/js-toolkit';
|
|
37
|
+
|
|
38
|
+
// The Mapbox `Map` instance is exposed on the `MapboxMap` component.
|
|
39
|
+
const mapboxMap = getInstance(element, MapboxMap);
|
|
40
|
+
mapboxMap.map.setCenter([2.35, 48.86]);
|
|
41
|
+
mapboxMap.map.setZoom(12);
|
|
42
|
+
|
|
43
|
+
// Markers, popups and sources expose their own Mapbox object too.
|
|
44
|
+
marker.marker.setLngLat([2.29, 48.86]);
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Every component documents the Mapbox object it exposes (`map`, `marker`, `popup`, `control`, …) in its **Getters** section below.
|
|
48
|
+
|
|
49
|
+
**Switching base style keeps your layers**
|
|
50
|
+
|
|
51
|
+
Calling `map.setStyle(…)` wipes the entire style — every source, layer and sprite — while the map instance and the still-mounted child components survive. Each map child subscribes to the map's `style.load` and **re-injects** its contribution automatically, so your declarative sources, layers, images and clusters re-appear on the new base style instead of silently vanishing. You can switch the base style at runtime without re-declaring your data.
|
|
52
|
+
|
|
53
|
+
## Map
|
|
54
|
+
|
|
55
|
+
### MapboxMap
|
|
56
|
+
|
|
57
|
+
Display an interactive Mapbox GL map. This is the root component of the system and the parent of every other component. It instantiates the Mapbox `Map` lazily and re-emits its events.
|
|
58
|
+
|
|
59
|
+
#### Options
|
|
60
|
+
|
|
61
|
+
##### `access-token`
|
|
62
|
+
|
|
63
|
+
- Type: `String`
|
|
64
|
+
|
|
65
|
+
Mapbox GL [access token](https://docs.mapbox.com/help/getting-started/access-tokens/) (required).
|
|
66
|
+
|
|
67
|
+
##### `zoom`
|
|
68
|
+
|
|
69
|
+
- Type: `Number`
|
|
70
|
+
|
|
71
|
+
Initial zoom level.
|
|
72
|
+
|
|
73
|
+
##### `center`
|
|
74
|
+
|
|
75
|
+
- Type: `Array`
|
|
76
|
+
- Default: `[0, 0]`
|
|
77
|
+
|
|
78
|
+
Initial center as `[longitude, latitude]`.
|
|
79
|
+
|
|
80
|
+
##### `map-options`
|
|
81
|
+
|
|
82
|
+
- Type: `Object`
|
|
83
|
+
- Default: `{}`
|
|
84
|
+
|
|
85
|
+
Any other [Mapbox `Map` option](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-parameters), spread into the constructor. This is where `style`, `pitch`, `bearing`, `bounds`, … go.
|
|
86
|
+
|
|
87
|
+
The `access-token`, `zoom` and `center` options act as overridable defaults, then `map-options` is spread into the [Mapbox `Map` constructor](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-parameters). The `container` is always resolved from the component (the `container` ref, falling back to the root element) and can not be overridden. Use `map-options` for anything the convenience options above do not cover — most notably the map [`style`](https://docs.mapbox.com/mapbox-gl-js/api/map/#map-parameters):
|
|
88
|
+
|
|
89
|
+
```html
|
|
90
|
+
<div
|
|
91
|
+
data-component="MapboxMap"
|
|
92
|
+
data-option-access-token="pk.…"
|
|
93
|
+
data-option-map-options='{ "style": "mapbox://styles/mapbox/streets-v12", "pitch": 45 }'>
|
|
94
|
+
<div data-ref="container"></div>
|
|
95
|
+
</div>
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
#### Refs
|
|
99
|
+
|
|
100
|
+
##### `container`
|
|
101
|
+
|
|
102
|
+
- Type: `HTMLElement`
|
|
103
|
+
|
|
104
|
+
The element used as the map container. Falls back to the root element when omitted.
|
|
105
|
+
|
|
106
|
+
#### Getters
|
|
107
|
+
|
|
108
|
+
##### `map`
|
|
109
|
+
|
|
110
|
+
- Type: `mapboxgl.Map | undefined`
|
|
111
|
+
|
|
112
|
+
The underlying Mapbox GL map instance, or `undefined` until it has been built. The map is created in `mounted()`, after `mapbox-gl` resolves — it may be injected or lazily imported — so a caller should either wait for the `map-load` event or go through [`whenMapReady()`](#whenmapready-callback).
|
|
113
|
+
|
|
114
|
+
##### `isLoaded`
|
|
115
|
+
|
|
116
|
+
- Type: `boolean`
|
|
117
|
+
|
|
118
|
+
Whether the map has finished loading (a public field, not a getter).
|
|
119
|
+
|
|
120
|
+
#### Events
|
|
121
|
+
|
|
122
|
+
The component emits a custom `map-load` event, plus all the common Mapbox GL map events prefixed with `map-` to avoid conflicts with native events. Every payload is a named object: `map-load` carries `{ map }`, and every forwarded event carries the Mapbox event object as `{ event }`.
|
|
123
|
+
|
|
124
|
+
##### `map-load`
|
|
125
|
+
|
|
126
|
+
- Payload: `{ map }`
|
|
127
|
+
|
|
128
|
+
The map finished loading (custom event).
|
|
129
|
+
|
|
130
|
+
##### `map-idle`
|
|
131
|
+
|
|
132
|
+
The map is idle after rendering.
|
|
133
|
+
|
|
134
|
+
##### `map-render`
|
|
135
|
+
|
|
136
|
+
A frame is rendered.
|
|
137
|
+
|
|
138
|
+
##### `map-resize`
|
|
139
|
+
|
|
140
|
+
The map container is resized.
|
|
141
|
+
|
|
142
|
+
##### `map-remove`
|
|
143
|
+
|
|
144
|
+
The map is removed.
|
|
145
|
+
|
|
146
|
+
##### `map-error`
|
|
147
|
+
|
|
148
|
+
An error occurred, carrying the Mapbox error event as `{ event }`. Not to be confused with the map children's own `map-error`, which carries `{ error }` — both bubble, so an ancestor listening for `map-error` should read the payload by component.
|
|
149
|
+
|
|
150
|
+
##### `map-click`
|
|
151
|
+
|
|
152
|
+
A click on the map.
|
|
153
|
+
|
|
154
|
+
##### `map-dblclick`
|
|
155
|
+
|
|
156
|
+
A double-click on the map.
|
|
157
|
+
|
|
158
|
+
##### `map-mouseenter`
|
|
159
|
+
|
|
160
|
+
The pointer enters the map canvas.
|
|
161
|
+
|
|
162
|
+
##### `map-mouseleave`
|
|
163
|
+
|
|
164
|
+
The pointer leaves the map canvas.
|
|
165
|
+
|
|
166
|
+
##### `map-mousemove`
|
|
167
|
+
|
|
168
|
+
The pointer moves over the map.
|
|
169
|
+
|
|
170
|
+
##### `map-movestart`
|
|
171
|
+
|
|
172
|
+
Map movement starts (pan, zoom, rotate).
|
|
173
|
+
|
|
174
|
+
##### `map-move`
|
|
175
|
+
|
|
176
|
+
The map is moving.
|
|
177
|
+
|
|
178
|
+
##### `map-moveend`
|
|
179
|
+
|
|
180
|
+
Map movement ends.
|
|
181
|
+
|
|
182
|
+
##### `map-zoomstart`
|
|
183
|
+
|
|
184
|
+
A zoom transition starts.
|
|
185
|
+
|
|
186
|
+
##### `map-zoom`
|
|
187
|
+
|
|
188
|
+
The zoom level changes.
|
|
189
|
+
|
|
190
|
+
##### `map-zoomend`
|
|
191
|
+
|
|
192
|
+
A zoom transition ends.
|
|
193
|
+
|
|
194
|
+
##### `map-rotatestart`
|
|
195
|
+
|
|
196
|
+
Rotation starts.
|
|
197
|
+
|
|
198
|
+
##### `map-rotate`
|
|
199
|
+
|
|
200
|
+
The map is rotating.
|
|
201
|
+
|
|
202
|
+
##### `map-rotateend`
|
|
203
|
+
|
|
204
|
+
Rotation ends.
|
|
205
|
+
|
|
206
|
+
##### `map-pitchstart`
|
|
207
|
+
|
|
208
|
+
A pitch transition starts.
|
|
209
|
+
|
|
210
|
+
##### `map-pitch`
|
|
211
|
+
|
|
212
|
+
The pitch changes.
|
|
213
|
+
|
|
214
|
+
##### `map-pitchend`
|
|
215
|
+
|
|
216
|
+
A pitch transition ends.
|
|
217
|
+
|
|
218
|
+
##### `map-dragstart`
|
|
219
|
+
|
|
220
|
+
A drag starts.
|
|
221
|
+
|
|
222
|
+
##### `map-drag`
|
|
223
|
+
|
|
224
|
+
The map is being dragged.
|
|
225
|
+
|
|
226
|
+
##### `map-dragend`
|
|
227
|
+
|
|
228
|
+
A drag ends.
|
|
229
|
+
|
|
230
|
+
Listen to these events from a parent component with `on<ComponentName><EventName>` methods:
|
|
231
|
+
|
|
232
|
+
```js
|
|
233
|
+
import { Base, registerComponent } from '@studiometa/js-toolkit';
|
|
234
|
+
import { MapboxMap } from '@studiometa/ui-mapbox';
|
|
235
|
+
|
|
236
|
+
class App extends Base {
|
|
237
|
+
static config = {
|
|
238
|
+
name: 'App',
|
|
239
|
+
components: { MapboxMap },
|
|
240
|
+
};
|
|
241
|
+
|
|
242
|
+
onMapboxMapMapLoad({ payload: { map } }) {
|
|
243
|
+
console.log('Map is ready', map);
|
|
244
|
+
}
|
|
245
|
+
|
|
246
|
+
onMapboxMapMapClick({ payload: { event } }) {
|
|
247
|
+
console.log('Clicked at', event.lngLat);
|
|
248
|
+
}
|
|
249
|
+
|
|
250
|
+
onMapboxMapMapZoomend({ payload: { event } }) {
|
|
251
|
+
console.log('New zoom level', event.target.getZoom());
|
|
252
|
+
}
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
registerComponent(App);
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
## Markers & Popups
|
|
259
|
+
|
|
260
|
+
### MapboxMarker
|
|
261
|
+
|
|
262
|
+
Add a [marker](https://docs.mapbox.com/mapbox-gl-js/api/markers/#marker) to the map. A `MapboxPopup` nested inside the marker is automatically attached to it.
|
|
263
|
+
|
|
264
|
+
#### Options
|
|
265
|
+
|
|
266
|
+
##### `lng-lat`
|
|
267
|
+
|
|
268
|
+
- Type: `Array`
|
|
269
|
+
- Default: `[0, 0]`
|
|
270
|
+
|
|
271
|
+
Marker position as `[longitude, latitude]`.
|
|
272
|
+
|
|
273
|
+
##### `marker-options`
|
|
274
|
+
|
|
275
|
+
- Type: `Object`
|
|
276
|
+
- Default: `{}`
|
|
277
|
+
|
|
278
|
+
[Mapbox Marker options](https://docs.mapbox.com/mapbox-gl-js/api/markers/#marker) (color, anchor, draggable, …).
|
|
279
|
+
|
|
280
|
+
#### Getters
|
|
281
|
+
|
|
282
|
+
##### `marker`
|
|
283
|
+
|
|
284
|
+
- Type: `mapboxgl.Marker`
|
|
285
|
+
|
|
286
|
+
The underlying Marker instance.
|
|
287
|
+
|
|
288
|
+
##### `popup`
|
|
289
|
+
|
|
290
|
+
- Type: `MapboxPopup`
|
|
291
|
+
|
|
292
|
+
The first nested `MapboxPopup` child, if any.
|
|
293
|
+
|
|
294
|
+
#### Methods
|
|
295
|
+
|
|
296
|
+
##### `setChildPopup(popup)`
|
|
297
|
+
|
|
298
|
+
- Arguments: `MapboxPopup`
|
|
299
|
+
|
|
300
|
+
Attach a child `MapboxPopup`'s popup to this marker. It is called automatically by whichever of the two mounts last — the marker pulls its child popup once the map is ready, and a popup that mounts after its marker (a dynamic append) pushes itself here. Setting the same popup twice is idempotent.
|
|
301
|
+
|
|
302
|
+
### MapboxPopup
|
|
303
|
+
|
|
304
|
+
Display a [popup](https://docs.mapbox.com/mapbox-gl-js/api/markers/#popup) on the map. It can be used standalone (placed directly on the map at a given position) or nested inside a `MapboxMarker` (attached to the marker, no `lng-lat` needed). The popup content is taken from the element's inner HTML.
|
|
305
|
+
|
|
306
|
+
#### Options
|
|
307
|
+
|
|
308
|
+
##### `lng-lat`
|
|
309
|
+
|
|
310
|
+
- Type: `Array`
|
|
311
|
+
- Default: `[0, 0]`
|
|
312
|
+
|
|
313
|
+
Popup position as `[longitude, latitude]` (standalone popups only).
|
|
314
|
+
|
|
315
|
+
##### `popup-options`
|
|
316
|
+
|
|
317
|
+
- Type: `Object`
|
|
318
|
+
- Default: `{}`
|
|
319
|
+
|
|
320
|
+
[Mapbox Popup options](https://docs.mapbox.com/mapbox-gl-js/api/markers/#popup).
|
|
321
|
+
|
|
322
|
+
#### Getters
|
|
323
|
+
|
|
324
|
+
##### `popup`
|
|
325
|
+
|
|
326
|
+
- Type: `mapboxgl.Popup`
|
|
327
|
+
|
|
328
|
+
The underlying Popup instance.
|
|
329
|
+
|
|
330
|
+
## Controls
|
|
331
|
+
|
|
332
|
+
All controls extend [`AbstractMapboxMapChild`](#abstractmapboxmapchild) and expose the underlying Mapbox control through a `control` getter. They share a `position` option and are added to the map on mount, removed on unmount. `MapboxGeocoder` is the exception: it has no `position` option, and it can render in its own element, with or without a map.
|
|
333
|
+
|
|
334
|
+
### MapboxNavigationControl
|
|
335
|
+
|
|
336
|
+
Add zoom in/out and compass controls to the map.
|
|
337
|
+
|
|
338
|
+
#### Options
|
|
339
|
+
|
|
340
|
+
##### `position`
|
|
341
|
+
|
|
342
|
+
- Type: `String`
|
|
343
|
+
- Default: `'top-right'`
|
|
344
|
+
|
|
345
|
+
Control position: `top-left`, `top-right`, `bottom-left` or `bottom-right`.
|
|
346
|
+
|
|
347
|
+
##### `show-compass`
|
|
348
|
+
|
|
349
|
+
- Type: `Boolean`
|
|
350
|
+
- Default: `false`
|
|
351
|
+
|
|
352
|
+
Show the compass button.
|
|
353
|
+
|
|
354
|
+
##### `show-zoom`
|
|
355
|
+
|
|
356
|
+
- Type: `Boolean`
|
|
357
|
+
- Default: `false`
|
|
358
|
+
|
|
359
|
+
Show the zoom in/out buttons.
|
|
360
|
+
|
|
361
|
+
##### `visualize-pitch`
|
|
362
|
+
|
|
363
|
+
- Type: `Boolean`
|
|
364
|
+
- Default: `false`
|
|
365
|
+
|
|
366
|
+
Visualize the pitch on the compass button.
|
|
367
|
+
|
|
368
|
+
### MapboxGeolocateControl
|
|
369
|
+
|
|
370
|
+
Add a button that uses the browser's geolocation API to locate the user on the map.
|
|
371
|
+
|
|
372
|
+
#### Options
|
|
373
|
+
|
|
374
|
+
##### `position`
|
|
375
|
+
|
|
376
|
+
- Type: `String`
|
|
377
|
+
- Default: `'top-right'`
|
|
378
|
+
|
|
379
|
+
Control position.
|
|
380
|
+
|
|
381
|
+
##### `position-options`
|
|
382
|
+
|
|
383
|
+
- Type: `Object`
|
|
384
|
+
|
|
385
|
+
Browser [`PositionOptions`](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions).
|
|
386
|
+
|
|
387
|
+
##### `fit-bounds-options`
|
|
388
|
+
|
|
389
|
+
- Type: `Object`
|
|
390
|
+
|
|
391
|
+
[`FitBoundsOptions`](https://docs.mapbox.com/mapbox-gl-js/api/map/#map#fitbounds) used when tracking.
|
|
392
|
+
|
|
393
|
+
##### `track-user-location`
|
|
394
|
+
|
|
395
|
+
- Type: `Boolean`
|
|
396
|
+
- Default: `false`
|
|
397
|
+
|
|
398
|
+
Continuously track the user location.
|
|
399
|
+
|
|
400
|
+
##### `show-accuracy-circle`
|
|
401
|
+
|
|
402
|
+
- Type: `Boolean`
|
|
403
|
+
- Default: `false`
|
|
404
|
+
|
|
405
|
+
Show the accuracy circle around the user location.
|
|
406
|
+
|
|
407
|
+
##### `show-user-location`
|
|
408
|
+
|
|
409
|
+
- Type: `Boolean`
|
|
410
|
+
- Default: `false`
|
|
411
|
+
|
|
412
|
+
Show the user location dot.
|
|
413
|
+
|
|
414
|
+
##### `show-user-heading`
|
|
415
|
+
|
|
416
|
+
- Type: `Boolean`
|
|
417
|
+
- Default: `false`
|
|
418
|
+
|
|
419
|
+
Show the user heading indicator.
|
|
420
|
+
|
|
421
|
+
### MapboxFullscreenControl
|
|
422
|
+
|
|
423
|
+
Add a button that toggles the map fullscreen.
|
|
424
|
+
|
|
425
|
+
#### Options
|
|
426
|
+
|
|
427
|
+
##### `position`
|
|
428
|
+
|
|
429
|
+
- Type: `String`
|
|
430
|
+
- Default: `'top-right'`
|
|
431
|
+
|
|
432
|
+
Control position.
|
|
433
|
+
|
|
434
|
+
### MapboxGeocoder
|
|
435
|
+
|
|
436
|
+
Add an address search control powered by [`@mapbox/mapbox-gl-geocoder`](https://github.com/mapbox/mapbox-gl-geocoder). Install the optional `@mapbox/mapbox-gl-geocoder` peer dependency to use it.
|
|
437
|
+
|
|
438
|
+
**Optional, loaded on demand**
|
|
439
|
+
|
|
440
|
+
`@mapbox/mapbox-gl-geocoder` is an optional peer dependency. It is loaded lazily with a dynamic `import()` when a `MapboxGeocoder` mounts, so the rest of the package works without it installed. If you use this component, add it to your project: `npm install @mapbox/mapbox-gl-geocoder`.
|
|
441
|
+
|
|
442
|
+
With autoloading, `MapboxGeocoder` uses the `visible` mount strategy, so it mounts and loads the library when its element nears the viewport. Do not put `hidden` on its element: a hidden element never does. Use `data-mount="eager"` to load it without waiting for the viewport.
|
|
443
|
+
|
|
444
|
+
#### Options
|
|
445
|
+
|
|
446
|
+
##### `access-token`
|
|
447
|
+
|
|
448
|
+
- Type: `String`
|
|
449
|
+
|
|
450
|
+
Mapbox [access token](https://docs.mapbox.com/help/getting-started/access-tokens/) for the geocoding requests. Inside a `MapboxMap`, the geocoder uses the map's `access-token` when this option is not set. Without a parent map, the geocoder needs it (see [Standalone usage](#standalone-usage)).
|
|
451
|
+
|
|
452
|
+
The token is taken from the first of these that is set:
|
|
453
|
+
|
|
454
|
+
1. `accessToken` in the `options` option.
|
|
455
|
+
2. The `access-token` option.
|
|
456
|
+
3. The `access-token` of the parent `MapboxMap`.
|
|
457
|
+
|
|
458
|
+
This is the same order as on `MapboxMap`, where an `accessToken` in [`map-options`](#map-options) wins over its `access-token` option.
|
|
459
|
+
|
|
460
|
+
##### `add-to-map`
|
|
461
|
+
|
|
462
|
+
- Type: `Boolean`
|
|
463
|
+
- Default: `false`
|
|
464
|
+
|
|
465
|
+
Add the geocoder to the map as a control. This requires a parent `MapboxMap`. Otherwise it is rendered inside the component's element, with or without a parent map (see [Standalone usage](#standalone-usage)).
|
|
466
|
+
|
|
467
|
+
##### `options`
|
|
468
|
+
|
|
469
|
+
- Type: `Object`
|
|
470
|
+
- Default: `{}`
|
|
471
|
+
|
|
472
|
+
[Geocoder options](https://github.com/mapbox/mapbox-gl-geocoder/blob/master/API.md#parameters). Non-serializable options (`filter`, `externalGeocoder`, `render`, `getItemValue`, `localGeocoder`) are not supported.
|
|
473
|
+
|
|
474
|
+
An `accessToken` set in `options` wins over the geocoder's `access-token` option. Prefer the `access-token` option: it keeps the token out of the JSON.
|
|
475
|
+
|
|
476
|
+
#### Getters
|
|
477
|
+
|
|
478
|
+
##### `control`
|
|
479
|
+
|
|
480
|
+
- Type: `MapboxGeocoderControl | undefined`
|
|
481
|
+
|
|
482
|
+
The underlying `mapbox-gl-geocoder` control instance. It is created once the lazily imported geocoder module resolves, so it is `undefined` until then.
|
|
483
|
+
|
|
484
|
+
##### `target`
|
|
485
|
+
|
|
486
|
+
- Type: `Map | HTMLElement | string`
|
|
487
|
+
|
|
488
|
+
Where the control is mounted, depending on `add-to-map`.
|
|
489
|
+
|
|
490
|
+
#### Events
|
|
491
|
+
|
|
492
|
+
##### `map-result`
|
|
493
|
+
|
|
494
|
+
- Payload: `{ result }`
|
|
495
|
+
|
|
496
|
+
Emitted when the geocoder resolves an address, carrying the geocoder's selected feature.
|
|
497
|
+
|
|
498
|
+
#### Standalone usage
|
|
499
|
+
|
|
500
|
+
The geocoder does not need a map. Without `add-to-map` and without an ancestor element declared as `MapboxMap`, the component works on its own: it creates the control on mount, adds the search input to its own root element and emits `map-result` with the selected feature. Use it for an address search that drives something other than a map, such as a search form.
|
|
501
|
+
|
|
502
|
+
A standalone geocoder has no map to read the access token from, so set its `access-token` option. Without a token, the component logs a `mapbox-geocoder.missing-access-token` warning and does not create the control. A standalone geocoder does not load `mapbox-gl`.
|
|
503
|
+
|
|
504
|
+
The following example fills a hidden `near` field with the coordinates of the selected address, then submits a [`Fetch`](https://ui-v2.studiometa.dev/reference/items/Fetch/) form. An [`Action`](https://ui-v2.studiometa.dev/reference/items/Action/) on the same element listens to `map-result`. The field stays disabled until an address is selected, so the form never sends an empty `near` parameter.
|
|
505
|
+
|
|
506
|
+
```html
|
|
507
|
+
<form id="store-search" action="/stores" method="get" data-component="Fetch">
|
|
508
|
+
<input type="hidden" name="near" disabled />
|
|
509
|
+
</form>
|
|
510
|
+
|
|
511
|
+
<div
|
|
512
|
+
data-component="Action MapboxGeocoder"
|
|
513
|
+
data-option-access-token="pk.…"
|
|
514
|
+
data-option-options='{"countries": "fr"}'
|
|
515
|
+
data-on:map-result="Fetch(#store-search) -> () => {
|
|
516
|
+
const [lng, lat] = event.detail.result.center;
|
|
517
|
+
const { near } = target.$el.elements;
|
|
518
|
+
near.value = `${lat},${lng}`;
|
|
519
|
+
near.disabled = false;
|
|
520
|
+
target.$el.requestSubmit();
|
|
521
|
+
}"></div>
|
|
522
|
+
|
|
523
|
+
<div id="stores">…</div>
|
|
524
|
+
```
|
|
525
|
+
|
|
526
|
+
Inside a `MapboxMap`, the geocoder uses the map, even when the map mounts after it: the access token falls back to the map's [`access-token`](#access-token). Only a geocoder added to the map with [`add-to-map`](#add-to-map) shows a marker for the result and moves the map: a geocoder rendered in its own element never does, with or without a parent map.
|
|
527
|
+
|
|
528
|
+
In a [`StoreLocator`](../StoreLocator/index.md), the geocoder can also be placed outside the `MapboxMap` element, anywhere inside the `StoreLocator` element. It then works standalone and needs its own `access-token`, and the `StoreLocator` still frames the map on its `map-result` event.
|
|
529
|
+
|
|
530
|
+
## Data
|
|
531
|
+
|
|
532
|
+
### MapboxSource
|
|
533
|
+
|
|
534
|
+
Add a [source](https://docs.mapbox.com/style-spec/reference/sources/) to the map. On unmount, every layer tied to the source is removed before the source itself.
|
|
535
|
+
|
|
536
|
+
#### Options
|
|
537
|
+
|
|
538
|
+
##### `id`
|
|
539
|
+
|
|
540
|
+
- Type: `String`
|
|
541
|
+
|
|
542
|
+
Unique source id, referenced by layers.
|
|
543
|
+
|
|
544
|
+
##### `source`
|
|
545
|
+
|
|
546
|
+
- Type: `Object`
|
|
547
|
+
|
|
548
|
+
A [source specification](https://docs.mapbox.com/style-spec/reference/sources/), e.g. `{ "type": "geojson", "data": … }`.
|
|
549
|
+
|
|
550
|
+
#### Refs
|
|
551
|
+
|
|
552
|
+
##### `geojson`
|
|
553
|
+
|
|
554
|
+
- Type: `HTMLScriptElement`
|
|
555
|
+
|
|
556
|
+
Optional `<script data-ref="geojson" type="application/json">` element holding inline GeoJSON. When present, its parsed content is injected as the source spec's `data`. Invalid JSON is ignored with a warning.
|
|
557
|
+
|
|
558
|
+
#### Getters
|
|
559
|
+
|
|
560
|
+
##### `source`
|
|
561
|
+
|
|
562
|
+
- Type: `SourceSpecification`
|
|
563
|
+
|
|
564
|
+
The resolved source specification, with the `geojson` ref's inline data injected as `data` when present.
|
|
565
|
+
|
|
566
|
+
### MapboxLayer
|
|
567
|
+
|
|
568
|
+
Add a [layer](https://docs.mapbox.com/style-spec/reference/layers/) to the map.
|
|
569
|
+
|
|
570
|
+
#### Options
|
|
571
|
+
|
|
572
|
+
##### `id`
|
|
573
|
+
|
|
574
|
+
- Type: `String`
|
|
575
|
+
|
|
576
|
+
Unique layer id. It is assigned to the `layer` specification on mount.
|
|
577
|
+
|
|
578
|
+
##### `layer`
|
|
579
|
+
|
|
580
|
+
- Type: `Object`
|
|
581
|
+
|
|
582
|
+
A [layer specification](https://docs.mapbox.com/style-spec/reference/layers/).
|
|
583
|
+
|
|
584
|
+
##### `before-id`
|
|
585
|
+
|
|
586
|
+
- Type: `String`
|
|
587
|
+
|
|
588
|
+
Insert the layer before this existing layer id.
|
|
589
|
+
|
|
590
|
+
### MapboxImage
|
|
591
|
+
|
|
592
|
+
Load a single image and register it against the map sprite so it can be referenced from a symbol layer's `icon-image`.
|
|
593
|
+
|
|
594
|
+
#### Options
|
|
595
|
+
|
|
596
|
+
##### `name`
|
|
597
|
+
|
|
598
|
+
- Type: `String`
|
|
599
|
+
|
|
600
|
+
The id under which the image is registered in the sprite.
|
|
601
|
+
|
|
602
|
+
##### `url`
|
|
603
|
+
|
|
604
|
+
- Type: `String`
|
|
605
|
+
|
|
606
|
+
The URL of the image (png, webp or jpg).
|
|
607
|
+
|
|
608
|
+
##### `options`
|
|
609
|
+
|
|
610
|
+
- Type: `Object`
|
|
611
|
+
- Default: `{ pixelRatio: 1, sdf: false }`
|
|
612
|
+
|
|
613
|
+
Options forwarded to [`map.addImage`](https://docs.mapbox.com/mapbox-gl-js/api/map/#map#addimage).
|
|
614
|
+
|
|
615
|
+
#### Events
|
|
616
|
+
|
|
617
|
+
##### `map-ready`
|
|
618
|
+
|
|
619
|
+
- Payload: `{ name, image, options }`
|
|
620
|
+
|
|
621
|
+
Emitted once the image has been loaded and added to the sprite.
|
|
622
|
+
|
|
623
|
+
### MapboxImages
|
|
624
|
+
|
|
625
|
+
Load and register a list of images against the map sprite in one component.
|
|
626
|
+
|
|
627
|
+
#### Options
|
|
628
|
+
|
|
629
|
+
##### `sources`
|
|
630
|
+
|
|
631
|
+
- Type: `Array`
|
|
632
|
+
- Default: `[]`
|
|
633
|
+
|
|
634
|
+
A list of image definitions, each `{ name, url, options? }`. See [`MapboxImage`](#mapboximage) options.
|
|
635
|
+
|
|
636
|
+
#### Events
|
|
637
|
+
|
|
638
|
+
##### `map-ready`
|
|
639
|
+
|
|
640
|
+
- Payload: `{ images }`
|
|
641
|
+
|
|
642
|
+
Emitted once every image has been loaded and added, carrying the loaded images.
|
|
643
|
+
|
|
644
|
+
## Cluster
|
|
645
|
+
|
|
646
|
+
### MapboxCluster
|
|
647
|
+
|
|
648
|
+
A clustered GeoJSON **source driver** whose features ARE its rendered items. The `MapboxClusterItem`s living in its subtree self-register, and the cluster derives its clustered GeoJSON source from that registry — the same markup drives both a sidebar list and the clustered points on the map. It sets up the clustered source, the cluster circles layer, the cluster count labels layer and the unclustered points layer, together with the click-to-zoom interaction on clusters and pointer feedback on features.
|
|
649
|
+
|
|
650
|
+
The cluster is deliberately thin: it owns only the map data and the clustering interaction. It does **not** select, fly to, filter by viewport or open popups — those search-UX concerns belong to the optional [`StoreLocator`](../StoreLocator/index.md) orchestrator, which drives them on top of a cluster. Used on its own, a `MapboxCluster` still renders a working clustered map + list; it simply reports a click on an unclustered point through the `map-item-click` event and lets the caller decide what it means.
|
|
651
|
+
|
|
652
|
+
#### Options
|
|
653
|
+
|
|
654
|
+
##### `cluster-max-zoom`
|
|
655
|
+
|
|
656
|
+
- Type: `Number`
|
|
657
|
+
- Default: `14`
|
|
658
|
+
|
|
659
|
+
Max zoom at which points are clustered.
|
|
660
|
+
|
|
661
|
+
##### `cluster-radius`
|
|
662
|
+
|
|
663
|
+
- Type: `Number`
|
|
664
|
+
- Default: `50`
|
|
665
|
+
|
|
666
|
+
Radius of each cluster when clustering points.
|
|
667
|
+
|
|
668
|
+
##### `cluster-min-points`
|
|
669
|
+
|
|
670
|
+
- Type: `Number`
|
|
671
|
+
- Default: `2`
|
|
672
|
+
|
|
673
|
+
Minimum number of points to form a cluster.
|
|
674
|
+
|
|
675
|
+
##### `cluster-properties`
|
|
676
|
+
|
|
677
|
+
- Type: `Object`
|
|
678
|
+
- Default: `{}`
|
|
679
|
+
|
|
680
|
+
Custom [cluster properties](https://docs.mapbox.com/style-spec/reference/sources/#geojson-clusterProperties).
|
|
681
|
+
|
|
682
|
+
##### `clusters-layout`
|
|
683
|
+
|
|
684
|
+
- Type: `Object`
|
|
685
|
+
- Default: `{}`
|
|
686
|
+
|
|
687
|
+
Layout for the clusters circle layer.
|
|
688
|
+
|
|
689
|
+
##### `clusters-paint`
|
|
690
|
+
|
|
691
|
+
- Type: `Object`
|
|
692
|
+
- Default: `{ 'circle-color': '#000', 'circle-radius': 40 }`
|
|
693
|
+
|
|
694
|
+
Paint for the clusters circle layer.
|
|
695
|
+
|
|
696
|
+
##### `cluster-count-layout`
|
|
697
|
+
|
|
698
|
+
- Type: `Object`
|
|
699
|
+
- Default: `{ 'text-field': ['get', 'point_count_abbreviated'] }`
|
|
700
|
+
|
|
701
|
+
Layout for the cluster count labels.
|
|
702
|
+
|
|
703
|
+
##### `cluster-count-paint`
|
|
704
|
+
|
|
705
|
+
- Type: `Object`
|
|
706
|
+
- Default: `{ 'text-color': 'white' }`
|
|
707
|
+
|
|
708
|
+
Paint for the cluster count labels.
|
|
709
|
+
|
|
710
|
+
##### `unclustered-point-layer-type`
|
|
711
|
+
|
|
712
|
+
- Type: `String`
|
|
713
|
+
- Default: `'circle'`
|
|
714
|
+
|
|
715
|
+
Type of the unclustered points layer.
|
|
716
|
+
|
|
717
|
+
##### `unclustered-point-layout`
|
|
718
|
+
|
|
719
|
+
- Type: `Object`
|
|
720
|
+
- Default: `{}`
|
|
721
|
+
|
|
722
|
+
Layout for the unclustered points layer.
|
|
723
|
+
|
|
724
|
+
##### `unclustered-point-paint`
|
|
725
|
+
|
|
726
|
+
- Type: `Object`
|
|
727
|
+
- Default: `{ 'circle-color': '#000', 'circle-radius': 4 }`
|
|
728
|
+
|
|
729
|
+
Paint for the unclustered points layer.
|
|
730
|
+
|
|
731
|
+
#### Getters
|
|
732
|
+
|
|
733
|
+
##### `items`
|
|
734
|
+
|
|
735
|
+
- Type: `MapboxClusterItem[]`
|
|
736
|
+
|
|
737
|
+
The registered items, in registration order — the read-only surface for an orchestrator.
|
|
738
|
+
|
|
739
|
+
##### `featureCollection`
|
|
740
|
+
|
|
741
|
+
- Type: `FeatureCollection`
|
|
742
|
+
|
|
743
|
+
The GeoJSON derived from the registered items — the data pushed to the source.
|
|
744
|
+
|
|
745
|
+
#### Methods
|
|
746
|
+
|
|
747
|
+
##### `register(item)`
|
|
748
|
+
|
|
749
|
+
Register a `MapboxClusterItem` and schedule a coalesced rebuild. Called automatically by items on mount.
|
|
750
|
+
|
|
751
|
+
##### `unregister(item)`
|
|
752
|
+
|
|
753
|
+
Unregister a `MapboxClusterItem` and schedule a coalesced rebuild. Called automatically by items on unmount.
|
|
754
|
+
|
|
755
|
+
##### `setData(data)`
|
|
756
|
+
|
|
757
|
+
Replace the live source data directly, bypassing the item registry — for imperative control. Safe before mount or after teardown.
|
|
758
|
+
|
|
759
|
+
#### Events
|
|
760
|
+
|
|
761
|
+
##### `map-cluster-click`
|
|
762
|
+
|
|
763
|
+
- Payload: `{ clusterId, event }`
|
|
764
|
+
|
|
765
|
+
A cluster was clicked. Call `event.preventDefault()` to skip the default zoom-to-cluster behavior.
|
|
766
|
+
|
|
767
|
+
##### `map-item-click`
|
|
768
|
+
|
|
769
|
+
- Payload: `{ item, feature, event }`
|
|
770
|
+
|
|
771
|
+
An unclustered point was clicked. `item` is the registered `MapboxClusterItem` behind the feature, or `undefined` when none could be resolved.
|
|
772
|
+
|
|
773
|
+
##### `map-update`
|
|
774
|
+
|
|
775
|
+
- Payload: `{ items }`
|
|
776
|
+
|
|
777
|
+
The item set changed (a rebuild ran). Carries the live item set so an orchestrator can re-fit and re-filter.
|
|
778
|
+
|
|
779
|
+
### MapboxClusterItem
|
|
780
|
+
|
|
781
|
+
A single entry of a `MapboxCluster` — at once a rendered list item AND a map feature. It resolves the closest `MapboxCluster` ancestor, pushes itself into its registry on mount (`register`) and pulls itself out on unmount (`unregister`), so the cluster never has to query for its children. It is headless and passive: it never selects itself — a [`StoreLocator`](../StoreLocator/index.md) orchestrator (when one wraps the cluster) drives its state setters.
|
|
782
|
+
|
|
783
|
+
#### Options
|
|
784
|
+
|
|
785
|
+
##### `id`
|
|
786
|
+
|
|
787
|
+
- Type: `String`
|
|
788
|
+
|
|
789
|
+
Stable identifier, used to match a clicked map feature back to the item.
|
|
790
|
+
|
|
791
|
+
##### `lng-lat`
|
|
792
|
+
|
|
793
|
+
- Type: `Array`
|
|
794
|
+
- Default: `[0, 0]`
|
|
795
|
+
|
|
796
|
+
The point coordinates as `[longitude, latitude]`.
|
|
797
|
+
|
|
798
|
+
##### `properties`
|
|
799
|
+
|
|
800
|
+
- Type: `Object`
|
|
801
|
+
- Default: `{}`
|
|
802
|
+
|
|
803
|
+
Extra feature properties merged into the item's GeoJSON feature.
|
|
804
|
+
|
|
805
|
+
#### Markup
|
|
806
|
+
|
|
807
|
+
##### `[data-ref="popup"]`
|
|
808
|
+
|
|
809
|
+
- Type: `HTMLElement`
|
|
810
|
+
|
|
811
|
+
Optional descendant. It is resolved with a plain query rather than declared as a js-toolkit ref, so it works at any depth: its inner HTML is used as the popup content on selection; otherwise the item's whole inner HTML is used as a fallback.
|
|
812
|
+
|
|
813
|
+
#### Getters
|
|
814
|
+
|
|
815
|
+
##### `id`
|
|
816
|
+
|
|
817
|
+
- Type: `string`
|
|
818
|
+
|
|
819
|
+
The item's stable identifier.
|
|
820
|
+
|
|
821
|
+
##### `lngLat`
|
|
822
|
+
|
|
823
|
+
- Type: `[number, number]`
|
|
824
|
+
|
|
825
|
+
The item's `[lng, lat]` coordinates.
|
|
826
|
+
|
|
827
|
+
##### `properties`
|
|
828
|
+
|
|
829
|
+
- Type: `Record<string, unknown>`
|
|
830
|
+
|
|
831
|
+
The extra feature properties.
|
|
832
|
+
|
|
833
|
+
##### `popupContent`
|
|
834
|
+
|
|
835
|
+
- Type: `string`
|
|
836
|
+
|
|
837
|
+
The HTML used as the popup content when selected.
|
|
838
|
+
|
|
839
|
+
#### Methods
|
|
840
|
+
|
|
841
|
+
The state setters below are called by a `StoreLocator` orchestrator; you generally read the resulting data-attributes from CSS rather than calling them yourself.
|
|
842
|
+
|
|
843
|
+
##### `setInBounds(value)`
|
|
844
|
+
|
|
845
|
+
Toggle the `data-in-bounds` attribute — the list-visibility signal.
|
|
846
|
+
|
|
847
|
+
##### `setActive(value)`
|
|
848
|
+
|
|
849
|
+
Toggle the `data-active` attribute and the `aria-current="true"` state — the selected signal.
|
|
850
|
+
|
|
851
|
+
#### Events
|
|
852
|
+
|
|
853
|
+
##### `map-error`
|
|
854
|
+
|
|
855
|
+
- Payload: `{ error }`
|
|
856
|
+
|
|
857
|
+
Emitted when unregistering the item throws. The failure is contained and reported on the diagnostic channel as well.
|
|
858
|
+
|
|
859
|
+
## AbstractMapboxMapChild
|
|
860
|
+
|
|
861
|
+
The base class every child component extends (controls extend `AbstractMapboxControl`, itself a thin subclass that adds the shared `position` option and the `map.addControl`/`removeControl` lifecycle). It resolves the closest parent `MapboxMap` and exposes its Mapbox `Map` instance so children can register themselves against it. Beyond `mapboxMap`/`map`, it hardens the whole family's lifecycle: guarded injection and teardown, dead-map safety, retryable parent resolution (a child mounted before its map re-resolves on `mapbox-map:connected`), and automatic re-injection after a `map.setStyle(…)`. Extend it to build your own map children.
|
|
862
|
+
|
|
863
|
+
#### Getters
|
|
864
|
+
|
|
865
|
+
##### `mapboxMap`
|
|
866
|
+
|
|
867
|
+
- Type: `MapboxMap`
|
|
868
|
+
|
|
869
|
+
The closest parent `MapboxMap` component instance.
|
|
870
|
+
|
|
871
|
+
##### `map`
|
|
872
|
+
|
|
873
|
+
- Type: `mapboxgl.Map | undefined`
|
|
874
|
+
|
|
875
|
+
The Mapbox `Map` instance of the parent map, or `undefined` while the parent is still resolving `mapbox-gl`. Use `whenMapReady()` rather than reading it directly in `mounted()`.
|
|
876
|
+
|
|
877
|
+
#### Methods
|
|
878
|
+
|
|
879
|
+
##### `whenMapReady(callback)`
|
|
880
|
+
|
|
881
|
+
- Arguments: `(map: mapboxgl.Map) => void | Promise<void>`
|
|
882
|
+
|
|
883
|
+
Run the callback once the parent map is ready — now, on the next `map-load`, or once a `MapboxMap` connects if none exists yet. This is the entry point every child uses. The callback is stored so it can be re-run against a fresh map after a destroy and remount, it never fires after the child is destroyed, and a throw — or a rejected promise, for an `async` callback — is contained rather than rethrown, reported through `$error()` and emitted as a `map-error` event. An `async` callback must re-check that the map it was handed is still the current one after every `await`, since the map can be removed or replaced while the promise is in flight.
|
|
884
|
+
|
|
885
|
+
#### Events
|
|
886
|
+
|
|
887
|
+
##### `map-error`
|
|
888
|
+
|
|
889
|
+
- Payload: `{ error }`
|
|
890
|
+
|
|
891
|
+
Emitted when guarded map injection or teardown throws. The failure is contained and reported on the diagnostic channel as well.
|
|
892
|
+
|
|
893
|
+
```js
|
|
894
|
+
import { AbstractMapboxMapChild } from '@studiometa/ui-mapbox';
|
|
895
|
+
|
|
896
|
+
export class MyMapChild extends AbstractMapboxMapChild {
|
|
897
|
+
static config = {
|
|
898
|
+
name: 'MyMapChild',
|
|
899
|
+
};
|
|
900
|
+
|
|
901
|
+
mounted() {
|
|
902
|
+
this.whenMapReady((map) => {
|
|
903
|
+
// `map` is the fully loaded Mapbox `Map` instance.
|
|
904
|
+
map.addLayer(/* … */);
|
|
905
|
+
});
|
|
906
|
+
}
|
|
907
|
+
}
|
|
908
|
+
```
|
|
909
|
+
|
|
910
|
+
#### Document-level connection events
|
|
911
|
+
|
|
912
|
+
Two constants are exported for integrators building their own children:
|
|
913
|
+
|
|
914
|
+
- `MAPBOX_MAP_CONNECTED` (`'mapbox-map:connected'`) — dispatched on `document` by a `MapboxMap` once its Mapbox instance exists, with the component instance in `detail`. A child that mounted before its map uses it to retry resolving its parent.
|
|
915
|
+
- `MAPBOX_CLUSTER_CONNECTED` (`'mapbox-cluster:connected'`) — the same handshake between a `MapboxCluster` and a `MapboxClusterItem` that mounted first.
|
|
916
|
+
|
|
917
|
+
## AbstractMapboxControl
|
|
918
|
+
|
|
919
|
+
The base class for controls registered through `map.addControl`. It extends [`AbstractMapboxMapChild`](#abstractmapboxmapchild), creates the underlying Mapbox control lazily, and handles its add/remove lifecycle. Extend it when implementing a custom control component.
|
|
920
|
+
|
|
921
|
+
### Options
|
|
922
|
+
|
|
923
|
+
#### `position`
|
|
924
|
+
|
|
925
|
+
- Type: `ControlPosition`
|
|
926
|
+
- Default: `'top-right'`
|
|
927
|
+
|
|
928
|
+
The corner where Mapbox adds the control.
|
|
929
|
+
|
|
930
|
+
### Getters
|
|
931
|
+
|
|
932
|
+
#### `control`
|
|
933
|
+
|
|
934
|
+
- Type: `IControl`
|
|
935
|
+
|
|
936
|
+
The lazily created Mapbox control instance.
|
|
937
|
+
|
|
938
|
+
### Methods
|
|
939
|
+
|
|
940
|
+
#### `createControl(options)`
|
|
941
|
+
|
|
942
|
+
Create and return the concrete Mapbox control. Subclasses must implement this method.
|
|
943
|
+
|
|
944
|
+
```js
|
|
945
|
+
import { AbstractMapboxControl } from '@studiometa/ui-mapbox';
|
|
946
|
+
import { NavigationControl } from 'mapbox-gl';
|
|
947
|
+
|
|
948
|
+
export class CompactNavigationControl extends AbstractMapboxControl {
|
|
949
|
+
static config = {
|
|
950
|
+
name: 'CompactNavigationControl',
|
|
951
|
+
};
|
|
952
|
+
|
|
953
|
+
createControl(options) {
|
|
954
|
+
return new NavigationControl({ ...options, showCompass: false });
|
|
955
|
+
}
|
|
956
|
+
}
|
|
957
|
+
```
|