@studiometa/ui-mapbox 2.0.0-alpha.0 → 2.0.0-alpha.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +22 -16
- package/dist/MapboxGeocoder.d.ts +48 -5
- package/dist/MapboxGeocoder.js +73 -15
- package/dist/MapboxGeocoder.js.map +1 -1
- package/dist/MapboxMap.js +1 -0
- package/dist/MapboxMap.js.map +1 -1
- package/dist/StoreLocator.js +1 -0
- package/dist/StoreLocator.js.map +1 -1
- package/dist/catalog.js +22 -11
- package/dist/catalog.js.map +1 -1
- package/dist/manifest.js +11 -11
- package/dist/manifest.js.map +1 -1
- package/dist/scripts/manifest-types.d.ts +5 -2
- package/package.json +7 -2
- package/skills/studiometa-ui-mapbox/SKILL.md +71 -0
- package/skills/studiometa-ui-mapbox/references/index.md +8 -0
- package/skills/studiometa-ui-mapbox/references/items/MapboxMap/examples.md +481 -0
- package/skills/studiometa-ui-mapbox/references/items/MapboxMap/index.md +102 -0
- package/skills/studiometa-ui-mapbox/references/items/MapboxMap/js-api.md +957 -0
- package/skills/studiometa-ui-mapbox/references/items/StoreLocator/examples.md +647 -0
- package/skills/studiometa-ui-mapbox/references/items/StoreLocator/index.md +135 -0
- package/skills/studiometa-ui-mapbox/references/items/StoreLocator/js-api.md +160 -0
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
# StoreLocator
|
|
2
|
+
|
|
3
|
+
The `StoreLocator` component adds a "find a store near you" experience on top of a [`MapboxMap`](../MapboxMap/index.md). It is a thin **orchestrator**: it owns no map rendering and no item registry of its own. It wraps a `MapboxMap` containing a [`MapboxCluster`](../MapboxMap/js-api.md#cluster) — the declarative clustered map **and** list source driver, whose [`MapboxClusterItem`](../MapboxMap/js-api.md#mapboxclusteritem)s are the sidebar entries — plus an optional [`MapboxGeocoder`](../MapboxMap/js-api.md#mapboxgeocoder) (address search), and layers the search UX on top: selection, viewport filtering and address search. Everything is authored declaratively from your HTML with [js-toolkit](https://js-toolkit.studiometa.dev/).
|
|
4
|
+
|
|
5
|
+
It is part of the [`@studiometa/ui-mapbox`](https://www.npmjs.com/package/@studiometa/ui-mapbox) package, alongside the rest of the [`MapboxMap` family](../MapboxMap/index.md).
|
|
6
|
+
|
|
7
|
+
## Cluster vs. orchestrator
|
|
8
|
+
|
|
9
|
+
The responsibilities are split in two:
|
|
10
|
+
|
|
11
|
+
- The **`MapboxCluster`** is a pure source driver. Its `MapboxClusterItem`s self-register, and it derives a clustered GeoJSON source from that registry (the map data), handles the click-to-zoom on clusters, and reports a click on an unclustered point through a `map-item-click` event. Used on its own it renders a working clustered map + list, but it never selects, flies, filters by viewport or opens popups.
|
|
12
|
+
- The **`StoreLocator`** wraps such a cluster and adds exactly those search-UX concerns: it selects items (fly-to, `active` styling, popup), filters and sorts the list on every map move, wires the geocoder, and re-frames the map on item-set changes.
|
|
13
|
+
|
|
14
|
+
## The three-state model
|
|
15
|
+
|
|
16
|
+
Each store has three independent states, each with its own source of truth. Keeping them separate is what makes the orchestrator predictable — panning the map never rebuilds the map data, and updating the item set never fights with the current viewport.
|
|
17
|
+
|
|
18
|
+
| State | Source of truth | Owner | Drives | Recomputed on |
|
|
19
|
+
| -------------- | ------------------------------------------ | --------------- | --------------------------------------------------- | -------------------- |
|
|
20
|
+
| **Registered** | the item exists in the DOM | `MapboxCluster` | the **map data** (markers/clusters) | item-set change only |
|
|
21
|
+
| **In bounds** | the item's `lngLat` is inside the viewport | `StoreLocator` | **list visibility + distance sort** only | every map `moveend` |
|
|
22
|
+
| **Selected** | the chosen item | `StoreLocator` | fly-to, popup, `active` styling, `map-select` event | selection |
|
|
23
|
+
|
|
24
|
+
Because the map data is derived only from the cluster's registered items, swapping the list (for instance through a [`Fetch`](https://ui-v2.studiometa.dev/reference/items/Fetch/)) updates both the list **and** the map at once: the cluster re-derives its source and emits a `map-update`, and the orchestrator re-fits and re-filters in response. See the [faceted example](examples.md#faceted-list).
|
|
25
|
+
|
|
26
|
+
## Composability
|
|
27
|
+
|
|
28
|
+
The `StoreLocator` emits events and reflects state as data-attributes on each `MapboxClusterItem`; it makes no decision about how a selected store is presented beyond the built-in popup. The [examples](examples.md) use a [`Dialog`](https://ui-v2.studiometa.dev/reference/items/Dialog/) drawer as the detail panel, but a static `aside` would work just as well — wire whichever you like to the [`map-select`](js-api.md#map-select) event.
|
|
29
|
+
|
|
30
|
+
## Table of content
|
|
31
|
+
|
|
32
|
+
- [Examples](examples.md)
|
|
33
|
+
- [JS API](js-api.md)
|
|
34
|
+
|
|
35
|
+
## Installation
|
|
36
|
+
|
|
37
|
+
The component ships with the `@studiometa/ui-mapbox` package. Install it alongside its `mapbox-gl` peer dependency, exactly like the rest of the [`MapboxMap` family](../MapboxMap/index.md#installation).
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
npm install @studiometa/ui-mapbox mapbox-gl
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
The [Mapbox GL stylesheet](../MapboxMap/index.md#installation) and a [Mapbox access token](https://docs.mapbox.com/help/getting-started/access-tokens/) are required, just like for a plain map.
|
|
44
|
+
|
|
45
|
+
## Usage
|
|
46
|
+
|
|
47
|
+
The `StoreLocator` declares no child components — `StoreLocator`, `MapboxMap`, `MapboxCluster`, `MapboxClusterItem` and the optional `MapboxGeocoder` are each [registered](https://ui-v2.studiometa.dev/guide/usage/#registering-components) independently and mount on their own; the orchestrator watches its subtree for them, so mount order does not matter and a cluster inserted later is picked up on its own. As with a plain map, the recommended default is to register the family as a [manifest](https://ui-v2.studiometa.dev/guide/autoloading/), keeping the heavy `mapbox-gl` dependency out of your main bundle until the store locator is on the page.
|
|
48
|
+
|
|
49
|
+
Because a `MapboxClusterItem` resolves its cluster and the cluster resolves its map through the closest matching ancestor, the DOM nests them: the `MapboxCluster` wraps the sidebar list of `MapboxClusterItem`s **inside** the `MapboxMap`, next to the map container. The `StoreLocator` wraps the map. The cluster carries **no** authored data — it derives its source from the registered items.
|
|
50
|
+
|
|
51
|
+
```js [app.js]
|
|
52
|
+
import { registerManifest } from '@studiometa/js-toolkit';
|
|
53
|
+
|
|
54
|
+
// Register only the components your page uses; order doesn't matter.
|
|
55
|
+
registerManifest({
|
|
56
|
+
StoreLocator: {
|
|
57
|
+
mountStrategy: 'visible',
|
|
58
|
+
load: () => import('@studiometa/ui-mapbox/StoreLocator'),
|
|
59
|
+
},
|
|
60
|
+
MapboxMap: {
|
|
61
|
+
mountStrategy: 'visible',
|
|
62
|
+
load: () => import('@studiometa/ui-mapbox/MapboxMap'),
|
|
63
|
+
},
|
|
64
|
+
MapboxCluster: {
|
|
65
|
+
mountStrategy: 'visible',
|
|
66
|
+
load: () => import('@studiometa/ui-mapbox/MapboxCluster'),
|
|
67
|
+
},
|
|
68
|
+
MapboxClusterItem: {
|
|
69
|
+
mountStrategy: 'visible',
|
|
70
|
+
load: () => import('@studiometa/ui-mapbox/MapboxClusterItem'),
|
|
71
|
+
},
|
|
72
|
+
});
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
```html [index.html]
|
|
76
|
+
<div data-component="StoreLocator" class="h-[500px]">
|
|
77
|
+
<div
|
|
78
|
+
data-component="MapboxMap"
|
|
79
|
+
data-option-access-token="<YOUR_MAPBOX_ACCESS_TOKEN>"
|
|
80
|
+
data-option-zoom="11"
|
|
81
|
+
data-option-center="[2.35, 48.86]"
|
|
82
|
+
data-option-map-options='{"style":"mapbox://styles/mapbox/streets-v12"}'
|
|
83
|
+
class="grid h-full grid-cols-[20rem_1fr]">
|
|
84
|
+
<!-- The cluster wraps the list; `contents` lets the items flow into the map grid. -->
|
|
85
|
+
<div data-component="MapboxCluster" class="contents">
|
|
86
|
+
<ul class="overflow-y-auto">
|
|
87
|
+
<li
|
|
88
|
+
data-component="MapboxClusterItem"
|
|
89
|
+
data-option-id="louvre"
|
|
90
|
+
data-option-lng-lat="[2.3364, 48.8592]">
|
|
91
|
+
<button type="button">Paris 1er — Louvre</button>
|
|
92
|
+
</li>
|
|
93
|
+
<!-- more items… -->
|
|
94
|
+
</ul>
|
|
95
|
+
</div>
|
|
96
|
+
|
|
97
|
+
<div data-ref="container" class="h-full w-full"></div>
|
|
98
|
+
</div>
|
|
99
|
+
</div>
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
```css [app.css]
|
|
103
|
+
@import 'mapbox-gl/dist/mapbox-gl.css';
|
|
104
|
+
|
|
105
|
+
/* List-visibility contract: hide items outside the current viewport. */
|
|
106
|
+
[data-component='MapboxClusterItem']:not([data-in-bounds]) {
|
|
107
|
+
display: none;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/* Selected-item contract. */
|
|
111
|
+
[data-component='MapboxClusterItem'][data-active] {
|
|
112
|
+
/* highlight the active store */
|
|
113
|
+
}
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Clicking anywhere in a `MapboxClusterItem` selects it (the orchestrator delegates the click on its root), and clicking an unclustered pin on the map selects the matching item too. The styling contract is entirely data-attribute driven: `data-in-bounds` toggles list visibility, `data-active` (plus `aria-current="true"`) marks the selected item. See the [styling contract](js-api.md#styling-contract) for details.
|
|
117
|
+
|
|
118
|
+
## Lazy loading
|
|
119
|
+
|
|
120
|
+
Registering the family pulls in `MapboxMap` and its heavy `mapbox-gl` dependency (~230 kB gzipped). Register it through a [manifest](https://ui-v2.studiometa.dev/guide/autoloading/) so it is code-split into its own chunk and only loaded when the locator is on the page, the same way as the rest of the [`MapboxMap` family](../MapboxMap/index.md#lazy-loading):
|
|
121
|
+
|
|
122
|
+
```js
|
|
123
|
+
import { registerManifest } from '@studiometa/js-toolkit';
|
|
124
|
+
|
|
125
|
+
registerManifest({
|
|
126
|
+
StoreLocator: {
|
|
127
|
+
mountStrategy: 'visible',
|
|
128
|
+
load: () => import('@studiometa/ui-mapbox/StoreLocator'),
|
|
129
|
+
},
|
|
130
|
+
});
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
When registering only the `StoreLocator` entry, remember to register the `MapboxMap`, `MapboxCluster` and `MapboxClusterItem` it orchestrates too (each is available at its own subpath, whose default export is the component class, so the importer needs no destructuring). The whole package's manifest is available at `@studiometa/ui-mapbox/manifest` when you want all of it.
|
|
134
|
+
|
|
135
|
+
The `idle`, `interaction` and `media:<query>` strategies are available too, and `data-mount` overrides any of them per element — see the [MapboxMap lazy-loading note](../MapboxMap/index.md#lazy-loading).
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
# JS API
|
|
2
|
+
|
|
3
|
+
The store locator is an **orchestrator** built on the [`MapboxMap` family](../MapboxMap/js-api.md):
|
|
4
|
+
|
|
5
|
+
- `StoreLocator` — the coordinator, wrapping a [`MapboxMap`](../MapboxMap/js-api.md#map) that contains a [`MapboxCluster`](../MapboxMap/js-api.md#cluster).
|
|
6
|
+
- [`MapboxClusterItem`](../MapboxMap/js-api.md#mapboxclusteritem) — a single store entry; it registers with the cluster (the owner of the item registry), and the orchestrator reads and drives it. There is **no** dedicated store-item class.
|
|
7
|
+
|
|
8
|
+
The `StoreLocator` declares no child components, so nothing is ever double-mounted. [Register](https://ui-v2.studiometa.dev/guide/usage/#registering-components) `StoreLocator`, `MapboxMap`, `MapboxCluster` and `MapboxClusterItem` each independently — ideally through a lazy [manifest](https://ui-v2.studiometa.dev/guide/autoloading/) entry (see [Lazy loading](../MapboxMap/index.md#lazy-loading)). The orchestrator watches its subtree for the cluster and the optional geocoder, so it does not matter which mounts first, nor whether the geocoder has finished importing its module.
|
|
9
|
+
|
|
10
|
+
To change the store set after mount, change the DOM of the list (add/remove `MapboxClusterItem` elements): the cluster re-derives the map data and emits a `map-update`, and the orchestrator re-fits and re-filters automatically.
|
|
11
|
+
|
|
12
|
+
## StoreLocator
|
|
13
|
+
|
|
14
|
+
The coordinator. It owns no map rendering and no registry: the `MapboxCluster` derives the GeoJSON source from its registered `MapboxClusterItem`s, and the orchestrator reads that item set to filter and sort the list on every map move, wire the geocoder, re-frame the map on item-set changes, and handle selection.
|
|
15
|
+
|
|
16
|
+
### Options
|
|
17
|
+
|
|
18
|
+
#### `item-zoom-level`
|
|
19
|
+
|
|
20
|
+
- Type: `Number`
|
|
21
|
+
- Default: `14`
|
|
22
|
+
|
|
23
|
+
The zoom level the map flies to when a store is selected.
|
|
24
|
+
|
|
25
|
+
#### `no-sort`
|
|
26
|
+
|
|
27
|
+
- Type: `Boolean`
|
|
28
|
+
- Default: `false`
|
|
29
|
+
|
|
30
|
+
Disable the distance sort. Sorting is on by default, reordering the in-view items nearest-first on every map move, so add `data-option-no-sort` to turn it off.
|
|
31
|
+
|
|
32
|
+
#### `fit-on-update`
|
|
33
|
+
|
|
34
|
+
- Type: `Boolean`
|
|
35
|
+
- Default: `false`
|
|
36
|
+
|
|
37
|
+
Fit the map bounds to the whole item set whenever it changes (on load and on any add/remove of items).
|
|
38
|
+
|
|
39
|
+
#### `popup-options`
|
|
40
|
+
|
|
41
|
+
- Type: `Object`
|
|
42
|
+
- Default: `{}`
|
|
43
|
+
|
|
44
|
+
Options forwarded to the `mapboxgl.Popup` opened on selection.
|
|
45
|
+
|
|
46
|
+
<!-- prettier-ignore-start -->
|
|
47
|
+
```html {3}
|
|
48
|
+
<div
|
|
49
|
+
data-component="StoreLocator"
|
|
50
|
+
data-option-item-zoom-level="16"
|
|
51
|
+
data-option-fit-on-update>
|
|
52
|
+
...
|
|
53
|
+
</div>
|
|
54
|
+
```
|
|
55
|
+
<!-- prettier-ignore-end -->
|
|
56
|
+
|
|
57
|
+
### Getters
|
|
58
|
+
|
|
59
|
+
#### `isLoaded`
|
|
60
|
+
|
|
61
|
+
- Type: `boolean`
|
|
62
|
+
|
|
63
|
+
Whether the underlying map has finished loading (a public field, not a getter).
|
|
64
|
+
|
|
65
|
+
#### `mapboxMap`
|
|
66
|
+
|
|
67
|
+
- Type: `MapboxMap`
|
|
68
|
+
|
|
69
|
+
The child `MapboxMap` component.
|
|
70
|
+
|
|
71
|
+
#### `map`
|
|
72
|
+
|
|
73
|
+
- Type: `mapboxgl.Map`
|
|
74
|
+
|
|
75
|
+
The underlying Mapbox `Map` instance. Only valid once the map has loaded.
|
|
76
|
+
|
|
77
|
+
#### `cluster`
|
|
78
|
+
|
|
79
|
+
- Type: `MapboxCluster | undefined`
|
|
80
|
+
|
|
81
|
+
The child `MapboxCluster` (the item registry + map data source).
|
|
82
|
+
|
|
83
|
+
#### `geocoder`
|
|
84
|
+
|
|
85
|
+
- Type: `MapboxGeocoder | undefined`
|
|
86
|
+
|
|
87
|
+
The optional child `MapboxGeocoder`.
|
|
88
|
+
|
|
89
|
+
#### `items`
|
|
90
|
+
|
|
91
|
+
- Type: `readonly MapboxClusterItem[]`
|
|
92
|
+
|
|
93
|
+
The registered items, read from the cluster (their single source of truth).
|
|
94
|
+
|
|
95
|
+
### Methods
|
|
96
|
+
|
|
97
|
+
#### `selectItem(item)`
|
|
98
|
+
|
|
99
|
+
- Arguments: `MapboxClusterItem`
|
|
100
|
+
|
|
101
|
+
Select a store: deactivate the previous one, fly the map to the item at `item-zoom-level`, open a popup from the item's [`popupContent`](../MapboxMap/js-api.md#mapboxclusteritem), mark it active (`data-active` + `aria-current="true"`) and emit [`map-select`](#map-select). Called automatically on a sidebar click (delegated on the root), on the cluster's `map-item-click` (an unclustered pin), and available for you to call directly.
|
|
102
|
+
|
|
103
|
+
#### `deselect()`
|
|
104
|
+
|
|
105
|
+
Clear the current selection, close the popup, remove the active state and emit [`map-deselect`](#map-deselect).
|
|
106
|
+
|
|
107
|
+
### Events
|
|
108
|
+
|
|
109
|
+
#### `map-select`
|
|
110
|
+
|
|
111
|
+
- Payload: `{ item }`
|
|
112
|
+
|
|
113
|
+
Emitted when a store is selected, carrying the selected `MapboxClusterItem` instance. Wire your detail panel here.
|
|
114
|
+
|
|
115
|
+
```js
|
|
116
|
+
onStoreLocatorMapSelect({ payload: { item } }) {
|
|
117
|
+
// item.id, item.lngLat, item.$el …
|
|
118
|
+
}
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
#### `map-deselect`
|
|
122
|
+
|
|
123
|
+
Emitted when the selection is cleared through [`deselect()`](#deselect).
|
|
124
|
+
|
|
125
|
+
#### `map-filter`
|
|
126
|
+
|
|
127
|
+
- Payload: `{ items }`
|
|
128
|
+
|
|
129
|
+
Emitted whenever the in-view list is recomputed (on every map `moveend` and after an item-set change), carrying the in-view items in display order (nearest-first unless `no-sort` is set).
|
|
130
|
+
|
|
131
|
+
```js
|
|
132
|
+
onStoreLocatorMapFilter({ payload: { items } }) {
|
|
133
|
+
// e.g. update a "N stores in view" counter
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## Store entries: `MapboxClusterItem`
|
|
138
|
+
|
|
139
|
+
A single store entry is a [`MapboxClusterItem`](../MapboxMap/js-api.md#mapboxclusteritem). It registers with the closest `MapboxCluster`, exposes `id`, `lngLat`, `properties` and `popupContent`, and reflects its state through `setInBounds`/`setActive` (driven by the orchestrator). Refer to its [reference](../MapboxMap/js-api.md#mapboxclusteritem) for the full API. The orchestrator itself never reintroduces a separate item class — it drives the cluster's items.
|
|
140
|
+
|
|
141
|
+
## Styling contract {#styling-contract}
|
|
142
|
+
|
|
143
|
+
The orchestrator never styles anything: it only reflects state as attributes on each `MapboxClusterItem`. You own the CSS.
|
|
144
|
+
|
|
145
|
+
| Attribute | Meaning | Typical CSS |
|
|
146
|
+
| ------------------------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------ |
|
|
147
|
+
| `data-in-bounds` | The item is inside the current map viewport (list visibility). | `[data-component='MapboxClusterItem']:not([data-in-bounds]) { display: none }` |
|
|
148
|
+
| `data-active` + `aria-current` | The item is the selected one. | `[data-component='MapboxClusterItem'][data-active] { /* highlight */ }` |
|
|
149
|
+
|
|
150
|
+
```css
|
|
151
|
+
/* Hide out-of-view stores from the list. */
|
|
152
|
+
[data-component='MapboxClusterItem']:not([data-in-bounds]) {
|
|
153
|
+
display: none;
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
/* Highlight the selected store. */
|
|
157
|
+
[data-component='MapboxClusterItem'][data-active] {
|
|
158
|
+
background-color: #ecfdf5;
|
|
159
|
+
}
|
|
160
|
+
```
|