@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.
@@ -0,0 +1,647 @@
1
+ # Examples
2
+
3
+ Both examples register the Mapbox components they use (`StoreLocator`, `MapboxMap`, `MapboxCluster`, `MapboxClusterItem`) independently — see [Usage](index.md#usage) for the recommended lazy registration — and add a small root component for the detail panel. The `StoreLocator` orchestrates a `MapboxMap` containing a `MapboxCluster` whose `MapboxClusterItem`s are the sidebar entries. Each example loads the [Mapbox GL stylesheet](../MapboxMap/index.md#installation) from a CDN and picks a Mapbox style through the `map-options` option. 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
+ ## Basic store locator
6
+
7
+ A `StoreLocator` wrapping a clustered map whose `MapboxCluster` holds a sidebar list of Paris `MapboxClusterItem`s. The cluster has **no** authored data: it derives a GeoJSON `FeatureCollection` from its registered items, and the orchestrator adds selection, viewport filtering and the detail drawer on top.
8
+
9
+ Try it out:
10
+
11
+ - **Pan or zoom the map** — the sidebar filters to the in-view stores and reorders them nearest-first.
12
+ - **Click a store in the list** — the map flies there, the item is marked active, a popup opens and the detail drawer opens.
13
+ - **Click a cluster** — the map zooms in and splits it; click an individual pin to select its store.
14
+
15
+ The detail panel is the integrator's choice. Here it is a [`Dialog`](https://ui-v2.studiometa.dev/reference/items/Dialog/) drawer, opened from the [`map-select`](js-api.md#map-select) event through a small root component's `onStoreLocatorMapSelect` handler, which copies the selected item's `<template>` detail into the drawer. A static `aside` bound to the same event would work too.
16
+
17
+ ```twig
18
+ <link rel="stylesheet" href="https://esm.sh/mapbox-gl@3.13.0/dist/mapbox-gl.css" />
19
+
20
+ {% set stores = [
21
+ { id: 'paris-1', name: 'Paris 1ᵉʳ — Louvre', address: '2 rue de Rivoli, 75001 Paris', hours: 'Mon–Sat, 10am–7pm', lngLat: [2.3364, 48.8592] },
22
+ { id: 'paris-2', name: 'Paris 2ᵉ — Bourse', address: '14 rue Vivienne, 75002 Paris', hours: 'Mon–Sat, 10am–7pm', lngLat: [2.3412, 48.8697] },
23
+ { id: 'paris-3', name: 'Paris 3ᵉ — Temple', address: '9 rue de Bretagne, 75003 Paris', hours: 'Tue–Sun, 10am–8pm', lngLat: [2.3620, 48.8637] },
24
+ { id: 'paris-4', name: 'Paris 4ᵉ — Marais', address: '30 rue des Archives, 75004 Paris', hours: 'Mon–Sun, 11am–8pm', lngLat: [2.3573, 48.8557] },
25
+ { id: 'paris-5', name: 'Paris 5ᵉ — Panthéon', address: '5 rue Soufflot, 75005 Paris', hours: 'Mon–Sat, 9am–7pm', lngLat: [2.3488, 48.8443] },
26
+ { id: 'paris-6', name: 'Paris 6ᵉ — Saint-Germain', address: '12 rue de Rennes, 75006 Paris', hours: 'Mon–Sat, 10am–7pm', lngLat: [2.3333, 48.8496] },
27
+ { id: 'paris-7', name: 'Paris 7ᵉ — Invalides', address: '40 rue de Grenelle, 75007 Paris', hours: 'Mon–Fri, 9am–6pm', lngLat: [2.3125, 48.8565] },
28
+ { id: 'paris-8', name: 'Paris 8ᵉ — Champs-Élysées', address: '68 avenue des Champs-Élysées, 75008 Paris', hours: 'Mon–Sun, 10am–9pm', lngLat: [2.3126, 48.8726] },
29
+ { id: 'paris-9', name: 'Paris 9ᵉ — Opéra', address: '22 boulevard Haussmann, 75009 Paris', hours: 'Mon–Sat, 9am–8pm', lngLat: [2.3390, 48.8768] },
30
+ { id: 'paris-10', name: 'Paris 10ᵉ — Canal', address: '18 quai de Valmy, 75010 Paris', hours: 'Tue–Sun, 10am–7pm', lngLat: [2.3608, 48.8760] },
31
+ { id: 'paris-11', name: 'Paris 11ᵉ — Bastille', address: '55 rue de la Roquette, 75011 Paris', hours: 'Mon–Sun, 11am–8pm', lngLat: [2.3800, 48.8594] },
32
+ { id: 'paris-12', name: 'Paris 12ᵉ — Bercy', address: '9 cour Saint-Émilion, 75012 Paris', hours: 'Mon–Sun, 10am–8pm', lngLat: [2.3877, 48.8353] },
33
+ { id: 'paris-13', name: 'Paris 13ᵉ — Gobelins', address: '30 avenue des Gobelins, 75013 Paris', hours: 'Mon–Sat, 10am–7pm', lngLat: [2.3620, 48.8322] },
34
+ { id: 'paris-14', name: 'Paris 14ᵉ — Montparnasse', address: '11 rue Daguerre, 75014 Paris', hours: 'Mon–Sat, 9am–7pm', lngLat: [2.3269, 48.8331] },
35
+ { id: 'paris-15', name: 'Paris 15ᵉ — Vaugirard', address: '76 rue du Commerce, 75015 Paris', hours: 'Mon–Sat, 10am–7pm', lngLat: [2.3000, 48.8412] },
36
+ { id: 'paris-16', name: 'Paris 16ᵉ — Passy', address: '20 rue de Passy, 75016 Paris', hours: 'Mon–Fri, 9am–6pm', lngLat: [2.2618, 48.8637] },
37
+ { id: 'paris-17', name: 'Paris 17ᵉ — Batignolles', address: '32 rue des Batignolles, 75017 Paris', hours: 'Tue–Sun, 10am–7pm', lngLat: [2.3068, 48.8848] },
38
+ { id: 'paris-18', name: 'Paris 18ᵉ — Montmartre', address: '6 rue des Abbesses, 75018 Paris', hours: 'Mon–Sun, 10am–8pm', lngLat: [2.3444, 48.8925] }
39
+ ] %}
40
+
41
+ <div data-component="App">
42
+ <div
43
+ data-component="StoreLocator"
44
+ data-option-fit-on-update
45
+ class="grid h-[540px] grid-cols-1 overflow-hidden rounded-lg border border-zinc-200 md:grid-cols-[minmax(0,20rem)_1fr] dark:border-zinc-700">
46
+
47
+ {# The map wraps everything. `contents` lets the cluster's list and the map
48
+ container flow directly into the StoreLocator grid. The MapboxCluster
49
+ carries NO authored data: it derives its source from the MapboxClusterItems
50
+ it contains, and the StoreLocator adds selection, filtering and the drawer. #}
51
+ <div
52
+ data-component="MapboxMap"
53
+ data-option-access-token="pk.eyJ1IjoiYWdlbmNlc3R1ZGlvbWV0YSIsImEiOiJjbXM5NTBycHMwa2Z4MndxeW02YndscmQyIn0.UitMikKpq-TRJOXM-rBcMg"
54
+ data-option-zoom="5"
55
+ data-option-center="[2.35, 48.86]"
56
+ data-option-map-options='{"style":"mapbox://styles/mapbox/streets-v12"}'
57
+ class="contents">
58
+
59
+ {# Sidebar list, wrapped by the cluster so each item resolves it as its
60
+ closest ancestor. Out-of-bounds items are hidden through CSS; the
61
+ StoreLocator reorders the rest nearest-first on every map move. #}
62
+ <div
63
+ data-component="MapboxCluster"
64
+ data-option-cluster-radius="60"
65
+ data-option-clusters-paint='{ "circle-color": "#059669", "circle-radius": 20 }'
66
+ data-option-cluster-count-paint='{ "text-color": "#ffffff" }'
67
+ data-option-unclustered-point-paint='{ "circle-color": "#059669", "circle-radius": 7, "circle-stroke-width": 2, "circle-stroke-color": "#ffffff" }'
68
+ class="contents">
69
+ <ul
70
+ class="divide-y divide-zinc-200 overflow-y-auto bg-white dark:divide-zinc-700 dark:bg-zinc-900">
71
+ {% for store in stores %}
72
+ <li
73
+ data-component="MapboxClusterItem"
74
+ data-option-id="{{ store.id }}"
75
+ data-option-lng-lat="{{ store.lngLat|json_encode }}">
76
+ <button
77
+ type="button"
78
+ class="block w-full px-4 py-3 text-left hover:bg-zinc-50 dark:hover:bg-zinc-800">
79
+ <span class="name block font-semibold">
80
+ {{ store.name }}
81
+ </span>
82
+ <span class="mt-0.5 block text-sm text-zinc-500 dark:text-zinc-400">
83
+ {{ store.address }}
84
+ </span>
85
+ </button>
86
+
87
+ {# Rich detail, kept out of the flow in a <template>; the panel copies
88
+ it in on selection. #}
89
+ <template>
90
+ <h2 class="text-xl font-bold">{{ store.name }}</h2>
91
+ <dl class="mt-4 space-y-3 text-sm">
92
+ <div>
93
+ <dt class="font-semibold text-zinc-500 dark:text-zinc-400">Address</dt>
94
+ <dd>{{ store.address }}</dd>
95
+ </div>
96
+ <div>
97
+ <dt class="font-semibold text-zinc-500 dark:text-zinc-400">Opening hours</dt>
98
+ <dd>{{ store.hours }}</dd>
99
+ </div>
100
+ <div>
101
+ <dt class="font-semibold text-zinc-500 dark:text-zinc-400">Coordinates</dt>
102
+ <dd>{{ store.lngLat[1] }}, {{ store.lngLat[0] }}</dd>
103
+ </div>
104
+ </dl>
105
+ </template>
106
+ </li>
107
+ {% endfor %}
108
+ </ul>
109
+ </div>
110
+
111
+ <div data-ref="container" class="h-full min-h-[300px] w-full"></div>
112
+ </div>
113
+ </div>
114
+
115
+ {# Detail panel — a Dialog drawer. Which panel to use is the integrator's
116
+ choice; a MapboxPopup or a static aside would work too. The host carries
117
+ NO display utility, so a closed drawer stays display:none. #}
118
+ <dialog
119
+ id="store-panel"
120
+ data-component="Action Dialog"
121
+ data-on:cancel.prevent="Dialog.close()"
122
+ data-on:click="event.target === $el && Dialog.close()"
123
+ class="fixed inset-0 m-0 h-full max-h-none w-full max-w-none overflow-hidden bg-transparent p-0">
124
+
125
+ <div
126
+ data-component="Action ViewTransition"
127
+ data-on:click="Dialog(#store-panel)->target.close()"
128
+ data-option-view-transition-name="store-panel-backdrop"
129
+ data-option-leave-to="opacity-0"
130
+ class="fixed inset-0 bg-black/50 opacity-0"></div>
131
+
132
+ <div
133
+ data-component="ViewTransition"
134
+ data-option-view-transition-name="store-panel-panel"
135
+ data-option-leave-to="translate-x-full opacity-0"
136
+ class="absolute inset-y-0 right-0 w-96 max-w-full translate-x-full overflow-y-auto bg-white p-8 text-black opacity-0 shadow-2xl">
137
+ <button
138
+ type="button"
139
+ data-component="Action"
140
+ data-on:click="Dialog(#store-panel)->target.close()"
141
+ class="mb-6 inline-flex items-center gap-1 border-b border-current text-sm">
142
+ Close
143
+ </button>
144
+ <div id="store-panel-content"></div>
145
+ </div>
146
+ </dialog>
147
+ </div>
148
+
149
+ <style>
150
+ /* List-visibility contract: hide every item whose lngLat is outside the
151
+ current map viewport. */
152
+ [data-component='MapboxClusterItem']:not([data-in-bounds]) {
153
+ display: none;
154
+ }
155
+
156
+ /* Selected-item contract: highlight the active item. */
157
+ [data-component='MapboxClusterItem'][data-active] > button {
158
+ background-color: #ecfdf5;
159
+ }
160
+ [data-component='MapboxClusterItem'][data-active] .name {
161
+ color: #047857;
162
+ }
163
+ html.dark [data-component='MapboxClusterItem'][data-active] > button {
164
+ background-color: #022c22;
165
+ }
166
+ html.dark [data-component='MapboxClusterItem'][data-active] .name {
167
+ color: #34d399;
168
+ }
169
+
170
+ dialog::backdrop {
171
+ background: transparent;
172
+ }
173
+
174
+ ::view-transition-group(store-panel-panel) {
175
+ z-index: 2;
176
+ }
177
+ ::view-transition-group(store-panel-backdrop) {
178
+ z-index: 1;
179
+ }
180
+
181
+ @keyframes store-panel-slide-in {
182
+ from {
183
+ transform: translateX(100%);
184
+ }
185
+ }
186
+ @keyframes store-panel-slide-out {
187
+ to {
188
+ transform: translateX(100%);
189
+ }
190
+ }
191
+ ::view-transition-new(store-panel-panel) {
192
+ animation: 300ms ease-out both store-panel-slide-in;
193
+ }
194
+ ::view-transition-old(store-panel-panel) {
195
+ animation: 300ms ease-in both store-panel-slide-out;
196
+ }
197
+
198
+ @keyframes store-panel-fade-in {
199
+ from {
200
+ opacity: 0;
201
+ }
202
+ }
203
+ @keyframes store-panel-fade-out {
204
+ to {
205
+ opacity: 0;
206
+ }
207
+ }
208
+ ::view-transition-new(store-panel-backdrop) {
209
+ animation: 300ms ease-out both store-panel-fade-in;
210
+ }
211
+ ::view-transition-old(store-panel-backdrop) {
212
+ animation: 300ms ease-in both store-panel-fade-out;
213
+ }
214
+ </style>
215
+ ```
216
+
217
+ ```js
218
+ import { Base, registerComponent } from '@studiometa/js-toolkit';
219
+ import {
220
+ StoreLocator,
221
+ MapboxMap,
222
+ MapboxCluster,
223
+ MapboxClusterItem,
224
+ } from '@studiometa/ui-mapbox';
225
+ import { Action, Dialog, ViewTransition } from '@studiometa/ui';
226
+
227
+ /**
228
+ * Root component wiring the detail panel to the store locator.
229
+ *
230
+ * It declares the whole Mapbox family so a single `registerComponent(App)` call
231
+ * mounts everything without double-registration. The `StoreLocator` stays
232
+ * panel-agnostic: it only emits a `map-select` event with the chosen item. Here we
233
+ * react to it through the `on<Component><Event>` convention, copy the item's
234
+ * `<template>` detail into the drawer and open it.
235
+ */
236
+ class App extends Base {
237
+ static config = {
238
+ name: 'App',
239
+ components: {
240
+ StoreLocator,
241
+ MapboxMap,
242
+ MapboxCluster,
243
+ MapboxClusterItem,
244
+ Dialog,
245
+ Action,
246
+ ViewTransition,
247
+ },
248
+ };
249
+
250
+ /**
251
+ * The detail panel Dialog child.
252
+ */
253
+ get panel() {
254
+ return this.$query('Dialog')[0];
255
+ }
256
+
257
+ /**
258
+ * Open the drawer with the selected store's detail.
259
+ * @param {{ payload: { item: MapboxClusterItem } }} props
260
+ */
261
+ onStoreLocatorMapSelect({ payload: { item } }) {
262
+ const template = item.$el.querySelector('template');
263
+ const content = this.$el.querySelector('#store-panel-content');
264
+
265
+ if (template && content) {
266
+ content.replaceChildren(template.content.cloneNode(true));
267
+ }
268
+
269
+ this.panel?.open();
270
+ }
271
+ }
272
+
273
+ registerComponent(App);
274
+ ```
275
+
276
+ ```css
277
+ html.dark {
278
+ background-color: #222;
279
+ color: #eee;
280
+ }
281
+
282
+ body {
283
+ padding: 1rem;
284
+ }
285
+ ```
286
+
287
+ ## Faceted list {#faceted-list}
288
+
289
+ Because the map data is [derived from the registered items](index.md#the-three-state-model), replacing the list updates both the list **and** the map. This example swaps the list markup when a facet is picked: js-toolkit mounts and terminates the `MapboxClusterItem`s accordingly, the cluster re-derives the map data from the new item set and emits a `map-update`, and the orchestrator re-fits and re-filters. With `fit-on-update` set, the map also re-frames to the new subset.
290
+
291
+ ```twig
292
+ <link rel="stylesheet" href="https://esm.sh/mapbox-gl@3.13.0/dist/mapbox-gl.css" />
293
+
294
+ {% set stores = [
295
+ { id: 'paris-1', name: 'Paris 1ᵉʳ — Louvre', address: '2 rue de Rivoli, 75001 Paris', bank: 'right', lngLat: [2.3364, 48.8592] },
296
+ { id: 'paris-2', name: 'Paris 2ᵉ — Bourse', address: '14 rue Vivienne, 75002 Paris', bank: 'right', lngLat: [2.3412, 48.8697] },
297
+ { id: 'paris-3', name: 'Paris 3ᵉ — Temple', address: '9 rue de Bretagne, 75003 Paris', bank: 'right', lngLat: [2.3620, 48.8637] },
298
+ { id: 'paris-4', name: 'Paris 4ᵉ — Marais', address: '30 rue des Archives, 75004 Paris', bank: 'right', lngLat: [2.3573, 48.8557] },
299
+ { id: 'paris-5', name: 'Paris 5ᵉ — Panthéon', address: '5 rue Soufflot, 75005 Paris', bank: 'left', lngLat: [2.3488, 48.8443] },
300
+ { id: 'paris-6', name: 'Paris 6ᵉ — Saint-Germain', address: '12 rue de Rennes, 75006 Paris', bank: 'left', lngLat: [2.3333, 48.8496] },
301
+ { id: 'paris-7', name: 'Paris 7ᵉ — Invalides', address: '40 rue de Grenelle, 75007 Paris', bank: 'left', lngLat: [2.3125, 48.8565] },
302
+ { id: 'paris-8', name: 'Paris 8ᵉ — Champs-Élysées', address: '68 avenue des Champs-Élysées, 75008 Paris', bank: 'right', lngLat: [2.3126, 48.8726] },
303
+ { id: 'paris-9', name: 'Paris 9ᵉ — Opéra', address: '22 boulevard Haussmann, 75009 Paris', bank: 'right', lngLat: [2.3390, 48.8768] },
304
+ { id: 'paris-10', name: 'Paris 10ᵉ — Canal', address: '18 quai de Valmy, 75010 Paris', bank: 'right', lngLat: [2.3608, 48.8760] },
305
+ { id: 'paris-11', name: 'Paris 11ᵉ — Bastille', address: '55 rue de la Roquette, 75011 Paris', bank: 'right', lngLat: [2.3800, 48.8594] },
306
+ { id: 'paris-13', name: 'Paris 13ᵉ — Gobelins', address: '30 avenue des Gobelins, 75013 Paris', bank: 'left', lngLat: [2.3620, 48.8322] },
307
+ { id: 'paris-14', name: 'Paris 14ᵉ — Montparnasse', address: '11 rue Daguerre, 75014 Paris', bank: 'left', lngLat: [2.3269, 48.8331] },
308
+ { id: 'paris-15', name: 'Paris 15ᵉ — Vaugirard', address: '76 rue du Commerce, 75015 Paris', bank: 'left', lngLat: [2.3000, 48.8412] },
309
+ { id: 'paris-16', name: 'Paris 16ᵉ — Passy', address: '20 rue de Passy, 75016 Paris', bank: 'right', lngLat: [2.2618, 48.8637] },
310
+ { id: 'paris-17', name: 'Paris 17ᵉ — Batignolles', address: '32 rue des Batignolles, 75017 Paris', bank: 'right', lngLat: [2.3068, 48.8848] },
311
+ { id: 'paris-18', name: 'Paris 18ᵉ — Montmartre', address: '6 rue des Abbesses, 75018 Paris', bank: 'right', lngLat: [2.3444, 48.8925] }
312
+ ] %}
313
+
314
+ <div data-component="App">
315
+ {# Facet toolbar — lives outside the StoreLocator so its buttons are App refs.
316
+ Selecting a facet swaps the list markup; the coordinator re-derives the map
317
+ data from the new item set. #}
318
+ <div class="mb-3 flex flex-wrap gap-2">
319
+ <button
320
+ type="button"
321
+ data-ref="facet[]"
322
+ data-category="all"
323
+ data-active
324
+ class="facet rounded-full border border-zinc-300 px-3 py-1 text-sm dark:border-zinc-600">
325
+ All stores
326
+ </button>
327
+ <button
328
+ type="button"
329
+ data-ref="facet[]"
330
+ data-category="right"
331
+ class="facet rounded-full border border-zinc-300 px-3 py-1 text-sm dark:border-zinc-600">
332
+ Right bank
333
+ </button>
334
+ <button
335
+ type="button"
336
+ data-ref="facet[]"
337
+ data-category="left"
338
+ class="facet rounded-full border border-zinc-300 px-3 py-1 text-sm dark:border-zinc-600">
339
+ Left bank
340
+ </button>
341
+ </div>
342
+
343
+ <div
344
+ data-component="StoreLocator"
345
+ data-option-fit-on-update
346
+ class="grid h-[500px] grid-cols-1 overflow-hidden rounded-lg border border-zinc-200 md:grid-cols-[minmax(0,20rem)_1fr] dark:border-zinc-700">
347
+
348
+ <div
349
+ data-component="MapboxMap"
350
+ data-option-access-token="pk.eyJ1IjoiYWdlbmNlc3R1ZGlvbWV0YSIsImEiOiJjbXM5NTBycHMwa2Z4MndxeW02YndscmQyIn0.UitMikKpq-TRJOXM-rBcMg"
351
+ data-option-zoom="5"
352
+ data-option-center="[2.35, 48.86]"
353
+ data-option-map-options='{"style":"mapbox://styles/mapbox/streets-v12"}'
354
+ class="contents">
355
+
356
+ {# The cluster wraps the swappable list; picking a facet replaces the
357
+ #store-list markup, and the cluster re-derives its source from the new
358
+ MapboxClusterItems. #}
359
+ <div
360
+ data-component="MapboxCluster"
361
+ data-option-cluster-radius="60"
362
+ data-option-clusters-paint='{ "circle-color": "#7c3aed", "circle-radius": 20 }'
363
+ data-option-cluster-count-paint='{ "text-color": "#ffffff" }'
364
+ data-option-unclustered-point-paint='{ "circle-color": "#7c3aed", "circle-radius": 7, "circle-stroke-width": 2, "circle-stroke-color": "#ffffff" }'
365
+ class="contents">
366
+ <ul
367
+ id="store-list"
368
+ class="divide-y divide-zinc-200 overflow-y-auto bg-white dark:divide-zinc-700 dark:bg-zinc-900">
369
+ {% for store in stores %}
370
+ <li
371
+ data-component="MapboxClusterItem"
372
+ data-option-id="{{ store.id }}"
373
+ data-option-lng-lat="{{ store.lngLat|json_encode }}"
374
+ data-category="{{ store.bank }}">
375
+ <button
376
+ type="button"
377
+ class="block w-full px-4 py-3 text-left hover:bg-zinc-50 dark:hover:bg-zinc-800">
378
+ <span class="name block font-semibold">{{ store.name }}</span>
379
+ <span class="mt-0.5 block text-sm text-zinc-500 dark:text-zinc-400">
380
+ {{ store.address }}
381
+ </span>
382
+ </button>
383
+ <template>
384
+ <h2 class="text-xl font-bold">{{ store.name }}</h2>
385
+ <p class="mt-4 text-sm">{{ store.address }}</p>
386
+ </template>
387
+ </li>
388
+ {% endfor %}
389
+ </ul>
390
+ </div>
391
+
392
+ <div data-ref="container" class="h-full min-h-[300px] w-full"></div>
393
+ </div>
394
+ </div>
395
+
396
+ <dialog
397
+ id="store-panel"
398
+ data-component="Action Dialog"
399
+ data-on:cancel.prevent="Dialog.close()"
400
+ data-on:click="event.target === $el && Dialog.close()"
401
+ class="fixed inset-0 m-0 h-full max-h-none w-full max-w-none overflow-hidden bg-transparent p-0">
402
+
403
+ <div
404
+ data-component="Action ViewTransition"
405
+ data-on:click="Dialog(#store-panel)->target.close()"
406
+ data-option-view-transition-name="store-panel-backdrop"
407
+ data-option-leave-to="opacity-0"
408
+ class="fixed inset-0 bg-black/50 opacity-0"></div>
409
+
410
+ <div
411
+ data-component="ViewTransition"
412
+ data-option-view-transition-name="store-panel-panel"
413
+ data-option-leave-to="translate-x-full opacity-0"
414
+ class="absolute inset-y-0 right-0 w-96 max-w-full translate-x-full overflow-y-auto bg-white p-8 text-black opacity-0 shadow-2xl">
415
+ <button
416
+ type="button"
417
+ data-component="Action"
418
+ data-on:click="Dialog(#store-panel)->target.close()"
419
+ class="mb-6 inline-flex items-center gap-1 border-b border-current text-sm">
420
+ Close
421
+ </button>
422
+ <div id="store-panel-content"></div>
423
+ </div>
424
+ </dialog>
425
+ </div>
426
+
427
+ <style>
428
+ [data-component='MapboxClusterItem']:not([data-in-bounds]) {
429
+ display: none;
430
+ }
431
+
432
+ [data-component='MapboxClusterItem'][data-active] > button {
433
+ background-color: #f5f3ff;
434
+ }
435
+ [data-component='MapboxClusterItem'][data-active] .name {
436
+ color: #6d28d9;
437
+ }
438
+ html.dark [data-component='MapboxClusterItem'][data-active] > button {
439
+ background-color: #2e1065;
440
+ }
441
+ html.dark [data-component='MapboxClusterItem'][data-active] .name {
442
+ color: #a78bfa;
443
+ }
444
+
445
+ .facet[data-active] {
446
+ background-color: #7c3aed;
447
+ border-color: #7c3aed;
448
+ color: #ffffff;
449
+ }
450
+
451
+ dialog::backdrop {
452
+ background: transparent;
453
+ }
454
+
455
+ ::view-transition-group(store-panel-panel) {
456
+ z-index: 2;
457
+ }
458
+ ::view-transition-group(store-panel-backdrop) {
459
+ z-index: 1;
460
+ }
461
+
462
+ @keyframes store-panel-slide-in {
463
+ from {
464
+ transform: translateX(100%);
465
+ }
466
+ }
467
+ @keyframes store-panel-slide-out {
468
+ to {
469
+ transform: translateX(100%);
470
+ }
471
+ }
472
+ ::view-transition-new(store-panel-panel) {
473
+ animation: 300ms ease-out both store-panel-slide-in;
474
+ }
475
+ ::view-transition-old(store-panel-panel) {
476
+ animation: 300ms ease-in both store-panel-slide-out;
477
+ }
478
+
479
+ @keyframes store-panel-fade-in {
480
+ from {
481
+ opacity: 0;
482
+ }
483
+ }
484
+ @keyframes store-panel-fade-out {
485
+ to {
486
+ opacity: 0;
487
+ }
488
+ }
489
+ ::view-transition-new(store-panel-backdrop) {
490
+ animation: 300ms ease-out both store-panel-fade-in;
491
+ }
492
+ ::view-transition-old(store-panel-backdrop) {
493
+ animation: 300ms ease-in both store-panel-fade-out;
494
+ }
495
+ </style>
496
+ ```
497
+
498
+ ```js
499
+ import { Base, registerComponent } from '@studiometa/js-toolkit';
500
+ import {
501
+ StoreLocator,
502
+ MapboxMap,
503
+ MapboxCluster,
504
+ MapboxClusterItem,
505
+ } from '@studiometa/ui-mapbox';
506
+ import { Action, Dialog, ViewTransition } from '@studiometa/ui';
507
+
508
+ /**
509
+ * Root component driving both the detail panel and the facets.
510
+ *
511
+ * The facets swap the list markup client-side to keep the playground static.
512
+ * A real integration would `Fetch` the new list fragment from the server
513
+ * instead — see the prose in the examples page. Either way, the important part
514
+ * is identical: the DOM of the `#store-list` changes, js-toolkit mounts and
515
+ * terminates the `MapboxClusterItem`s accordingly, and the `MapboxCluster`
516
+ * re-derives the map data from the new item set and emits a `map-update` the
517
+ * `StoreLocator` reacts to (markers and clusters follow).
518
+ */
519
+ class App extends Base {
520
+ static config = {
521
+ name: 'App',
522
+ refs: ['facet[]'],
523
+ components: {
524
+ StoreLocator,
525
+ MapboxMap,
526
+ MapboxCluster,
527
+ MapboxClusterItem,
528
+ Dialog,
529
+ Action,
530
+ ViewTransition,
531
+ },
532
+ };
533
+
534
+ /**
535
+ * The authored markup of every list item, captured once as `{ category, html }`.
536
+ * Each facet rebuilds the list from these snippets so every swap produces
537
+ * **fresh** nodes — exactly like a `Fetch` response would. Reusing the same
538
+ * elements would leave js-toolkit's terminated instances lingering on them and
539
+ * block a clean re-mount.
540
+ */
541
+ __allItems = [];
542
+
543
+ /**
544
+ * The detail panel Dialog child.
545
+ */
546
+ get panel() {
547
+ return this.$query('Dialog')[0];
548
+ }
549
+
550
+ /**
551
+ * The swappable list container.
552
+ */
553
+ get list() {
554
+ return this.$el.querySelector('#store-list');
555
+ }
556
+
557
+ /**
558
+ * Capture the initial (full) item set.
559
+ */
560
+ mounted() {
561
+ const { list } = this;
562
+ if (list) {
563
+ this.__allItems = [...list.children].map((item) => ({
564
+ category: item.dataset.category,
565
+ html: item.outerHTML,
566
+ }));
567
+ }
568
+ }
569
+
570
+ /**
571
+ * Filter the list to the clicked facet's category.
572
+ * @param {{ index: number }} props
573
+ */
574
+ onFacetClick({ index }) {
575
+ const button = this.$refs.facet[index];
576
+ const { category } = button.dataset;
577
+ const { list } = this;
578
+
579
+ if (!list) {
580
+ return;
581
+ }
582
+
583
+ for (const facet of this.$refs.facet) {
584
+ facet.toggleAttribute('data-active', facet === button);
585
+ }
586
+
587
+ // Rebuild the list from fresh markup — the same thing a `Fetch` response
588
+ // does. js-toolkit terminates the old `MapboxClusterItem`s (→ unregister) and
589
+ // mounts the new ones (→ register); the cluster coalesces the batch into a
590
+ // single map-data update, so markers and clusters follow the new set.
591
+ list.innerHTML = this.__allItems
592
+ .filter((item) => category === 'all' || item.category === category)
593
+ .map((item) => item.html)
594
+ .join('');
595
+ }
596
+
597
+ /**
598
+ * Open the drawer with the selected store's detail.
599
+ * @param {{ payload: { item: MapboxClusterItem } }} props
600
+ */
601
+ onStoreLocatorMapSelect({ payload: { item } }) {
602
+ const template = item.$el.querySelector('template');
603
+ const content = this.$el.querySelector('#store-panel-content');
604
+
605
+ if (template && content) {
606
+ content.replaceChildren(template.content.cloneNode(true));
607
+ }
608
+
609
+ this.panel?.open();
610
+ }
611
+ }
612
+
613
+ registerComponent(App);
614
+ ```
615
+
616
+ ```css
617
+ html.dark {
618
+ background-color: #222;
619
+ color: #eee;
620
+ }
621
+
622
+ body {
623
+ padding: 1rem;
624
+ }
625
+ ```
626
+
627
+ ### Doing it with `Fetch`
628
+
629
+ The example above swaps the list client-side so it runs on a static page. In a real integration you would instead [`Fetch`](https://ui-v2.studiometa.dev/reference/items/Fetch/) the new list fragment from a server endpoint and let it replace the list container — the cluster reacts to the mounted/terminated `MapboxClusterItem`s exactly the same way, so nothing else changes. The cluster's debounced rebuild coalesces a whole `Fetch` swap into a single map-data update and a single `map-update` the orchestrator reacts to.
630
+
631
+ ```html
632
+ <form data-component="Fetch" action="/stores" method="GET" data-option-selector="#store-list">
633
+ <button type="submit" name="bank" value="left">Left bank</button>
634
+ <button type="submit" name="bank" value="right">Right bank</button>
635
+ </form>
636
+
637
+ <div data-component="StoreLocator">
638
+ <div data-component="MapboxMap">
639
+ <div data-component="MapboxCluster">
640
+ <ul id="store-list">
641
+ <!-- The server responds with a fresh <ul id="store-list"> of MapboxClusterItems. -->
642
+ </ul>
643
+ </div>
644
+ <div data-ref="container"><!-- … --></div>
645
+ </div>
646
+ </div>
647
+ ```