@studiometa/ui-mapbox 2.0.0-alpha.1 → 2.0.0-alpha.3
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
package/README.md
CHANGED
|
@@ -76,6 +76,16 @@ Once provided, `@studiometa/ui-mapbox` never imports `mapbox-gl` by specifier
|
|
|
76
76
|
|
|
77
77
|
Heads up to [ui.studiometa.dev](https://ui.studiometa.dev/reference/items/MapboxMap/) for the full documentation.
|
|
78
78
|
|
|
79
|
+
## Agent skills
|
|
80
|
+
|
|
81
|
+
The package ships the `studiometa-ui-mapbox` [agent skill](https://agentskills.io). The skill teaches coding agents how to use the package, and it matches the installed version. Link the skills of your dependencies into your project with the [`skills` CLI](https://github.com/vercel-labs/skills):
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
npx skills experimental_sync
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
The command links each skill from `node_modules` into the agent folders (`.agents/skills/`, `.claude/skills/`…). When you update the package, the linked skill updates too. The command also links the `studiometa-js-toolkit` skill when your version of `@studiometa/js-toolkit` ships it.
|
|
88
|
+
|
|
79
89
|
## Contributing
|
|
80
90
|
|
|
81
91
|
Please read the [contribution docs](https://ui.studiometa.dev/guide/contributing/).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@studiometa/ui-mapbox",
|
|
3
|
-
"version": "2.0.0-alpha.
|
|
3
|
+
"version": "2.0.0-alpha.3",
|
|
4
4
|
"description": "Vanilla js-toolkit components to build Mapbox GL maps declaratively",
|
|
5
5
|
"publishConfig": {
|
|
6
6
|
"access": "public"
|
|
@@ -119,7 +119,8 @@
|
|
|
119
119
|
}
|
|
120
120
|
},
|
|
121
121
|
"scripts": {
|
|
122
|
-
"build": "node scripts/build.js"
|
|
122
|
+
"build": "node scripts/build.js && npm run build:skills",
|
|
123
|
+
"build:skills": "node ../../scripts/build-skills.ts"
|
|
123
124
|
},
|
|
124
125
|
"repository": {
|
|
125
126
|
"type": "git",
|
|
@@ -158,7 +159,11 @@
|
|
|
158
159
|
},
|
|
159
160
|
"files": [
|
|
160
161
|
"dist",
|
|
162
|
+
"skills",
|
|
161
163
|
"README.md",
|
|
162
164
|
"LICENSE.md"
|
|
165
|
+
],
|
|
166
|
+
"skills": [
|
|
167
|
+
"npm:@studiometa/js-toolkit"
|
|
163
168
|
]
|
|
164
169
|
}
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: studiometa-ui-mapbox
|
|
3
|
+
description: Build Mapbox GL maps declaratively with @studiometa/ui-mapbox v2 — MapboxMap, MapboxMarker, MapboxPopup, MapboxSource, MapboxLayer, controls, MapboxGeocoder and StoreLocator on @studiometa/js-toolkit v4. Use when code imports @studiometa/ui-mapbox, when markup uses data-component="MapboxMap" or another Mapbox* component, or when a page needs an interactive map or a store locator.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# @studiometa/ui-mapbox
|
|
7
|
+
|
|
8
|
+
`@studiometa/ui-mapbox` builds Mapbox GL maps from HTML. `MapboxMap` owns the map. Child components (markers, popups, sources, layers, controls) configure it from their attributes. `StoreLocator` is a complete store locator.
|
|
9
|
+
|
|
10
|
+
This skill matches the installed package version. Read the references in this folder before the online docs.
|
|
11
|
+
|
|
12
|
+
## References
|
|
13
|
+
|
|
14
|
+
- [references/index.md](references/index.md): the items of the package.
|
|
15
|
+
- `references/items/MapboxMap/`: the map and all its child components. `js-api.md` documents each component in one page.
|
|
16
|
+
- `references/items/StoreLocator/`: the store locator.
|
|
17
|
+
|
|
18
|
+
## Install
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
npm install @studiometa/ui-mapbox mapbox-gl
|
|
22
|
+
# Only for MapboxGeocoder:
|
|
23
|
+
npm install @mapbox/mapbox-gl-geocoder
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Include the `mapbox-gl` stylesheet, or the map does not render correctly.
|
|
27
|
+
|
|
28
|
+
## Register and author
|
|
29
|
+
|
|
30
|
+
Register each component the page uses. The order does not matter: each child finds its parent map.
|
|
31
|
+
|
|
32
|
+
```js
|
|
33
|
+
import { registerComponents } from '@studiometa/js-toolkit';
|
|
34
|
+
import { MapboxMap, MapboxMarker, MapboxPopup } from '@studiometa/ui-mapbox';
|
|
35
|
+
|
|
36
|
+
registerComponents(MapboxMap, MapboxMarker, MapboxPopup);
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
```html
|
|
40
|
+
<div
|
|
41
|
+
data-component="MapboxMap"
|
|
42
|
+
data-option-access-token="pk.your-access-token"
|
|
43
|
+
data-option-zoom="10"
|
|
44
|
+
data-option-center="[2.3522, 48.8566]">
|
|
45
|
+
<div data-ref="container" class="h-96 w-full"></div>
|
|
46
|
+
<div hidden data-component="MapboxMarker" data-option-lng-lat="[2.3522, 48.8566]"></div>
|
|
47
|
+
</div>
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
- Coordinates are `[lng, lat]` JSON arrays, as in Mapbox GL.
|
|
51
|
+
- Put `hidden` on child components that render nothing (markers, sources, layers). Do not put `hidden` on `MapboxGeocoder`: a hidden element never loads with the autoloader.
|
|
52
|
+
- `MapboxMap` re-emits the map events with a `map-` prefix. Handle them in a parent with `onMapboxMapMapClick`, `onMapboxMapMapLoad`…
|
|
53
|
+
- The `@studiometa/ui-mapbox/autoload` entry registers all components and loads them on demand. `MapboxMap`, `StoreLocator` and `MapboxGeocoder` wait until they are near the viewport.
|
|
54
|
+
|
|
55
|
+
## Loading mapbox-gl
|
|
56
|
+
|
|
57
|
+
`mapbox-gl` (about 230 kB gzipped) loads with a dynamic `import()` when the first map mounts. Do not import it in the main bundle. To use a specific build (a CSP-safe worker, an import map, a CDN), inject it once before the components mount:
|
|
58
|
+
|
|
59
|
+
```js
|
|
60
|
+
import mapboxgl from 'mapbox-gl';
|
|
61
|
+
import { provideMapboxGl } from '@studiometa/ui-mapbox';
|
|
62
|
+
|
|
63
|
+
provideMapboxGl(mapboxgl);
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
`provideMapboxGeocoder()` does the same for `@mapbox/mapbox-gl-geocoder`.
|
|
67
|
+
|
|
68
|
+
## Related skills
|
|
69
|
+
|
|
70
|
+
- `studiometa-ui`: `Action`, `Fetch`, the `Data*` components and the shared markup rules.
|
|
71
|
+
- `studiometa-js-toolkit`: the `Base` class and the component lifecycle.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
# @studiometa/ui-mapbox reference
|
|
2
|
+
|
|
3
|
+
Each item folder holds `index.md` (usage), `js-api.md` or `twig-api.md` (API) and `examples.md` when the docs have them.
|
|
4
|
+
|
|
5
|
+
| Item | Kind | Summary |
|
|
6
|
+
| --- | --- | --- |
|
|
7
|
+
| [MapboxMap](items/MapboxMap/index.md) | component | Compose declarative Mapbox maps from maps, controls, data, markers, and clusters. |
|
|
8
|
+
| [StoreLocator](items/StoreLocator/index.md) | component | Orchestrate a Mapbox cluster into a searchable, selectable store locator. |
|
|
@@ -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
|
+
```
|