@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,102 @@
1
+ # MapboxMap
2
+
3
+ The `MapboxMap` component and its family let you build [Mapbox GL](https://docs.mapbox.com/mapbox-gl-js/) maps declaratively, straight from your HTML, with [js-toolkit](https://js-toolkit.studiometa.dev/). A `MapboxMap` element owns the underlying Mapbox `Map` instance, and every other component (markers, popups, controls, sources, layers, images, clusters) is authored as a child element that registers itself against that map once it is loaded.
4
+
5
+ These components are published in the standalone [`@studiometa/ui-mapbox`](https://www.npmjs.com/package/@studiometa/ui-mapbox) package and replace the [`@studiometa/vue-mapbox-gl`](https://www.npmjs.com/package/@studiometa/vue-mapbox-gl) library. If you are coming from the Vue library, read the [migration guide](https://ui-v2.studiometa.dev/migration-guides/vue-mapbox-gl/).
6
+
7
+ ## Table of content
8
+
9
+ - [Examples](examples.md)
10
+ - [JS API](js-api.md)
11
+
12
+ ## Installation
13
+
14
+ Install the package alongside its `mapbox-gl` peer dependency. The [`@mapbox/mapbox-gl-geocoder`](https://github.com/mapbox/mapbox-gl-geocoder) package is only required if you use the [`MapboxGeocoder`](js-api.md#mapboxgeocoder) component.
15
+
16
+ ```bash
17
+ npm install @studiometa/ui-mapbox mapbox-gl
18
+
19
+ # Optional, only for the geocoder control
20
+ npm install @mapbox/mapbox-gl-geocoder
21
+ ```
22
+
23
+ The Mapbox GL stylesheet is required for the map, its controls and popups to render correctly. Add it to your page, either as a `<link>` tag pointing to the CDN or by importing it from the package with your bundler.
24
+
25
+ ```html
26
+ <link rel="stylesheet" href="https://api.mapbox.com/mapbox-gl-js/v3.13.0/mapbox-gl.css" />
27
+ ```
28
+
29
+ ```css
30
+ /* or, when using a bundler */
31
+ @import 'mapbox-gl/dist/mapbox-gl.css';
32
+ ```
33
+
34
+ You will also need a [Mapbox access token](https://docs.mapbox.com/help/getting-started/access-tokens/). Pass it to the `MapboxMap` component through the `access-token` option.
35
+
36
+ ## Usage
37
+
38
+ [Register](https://ui-v2.studiometa.dev/guide/usage/#registering-components) each component your page uses: a bare map with just a `container` needs only `MapboxMap`, and each marker, popup, control, source, layer, image or cluster you declare must be registered too. Registration order does not matter, because a child registered before its `MapboxMap` still wires up once the map connects.
39
+
40
+ Author the map with a root `MapboxMap` element holding a `container` ref, and give it a size through CSS.
41
+
42
+ ```js [app.js]
43
+ import { registerComponent } from '@studiometa/js-toolkit';
44
+ import { MapboxMap } from '@studiometa/ui-mapbox';
45
+
46
+ registerComponent(MapboxMap);
47
+ ```
48
+
49
+ ```html [index.html]
50
+ <div
51
+ data-component="MapboxMap"
52
+ data-option-access-token="<YOUR_MAPBOX_ACCESS_TOKEN>"
53
+ data-option-zoom="10"
54
+ data-option-center="[2.35, 48.86]"
55
+ class="h-96 w-full">
56
+ <div data-ref="container" class="h-full w-full"></div>
57
+ </div>
58
+ ```
59
+
60
+ ```css [app.css]
61
+ @import 'mapbox-gl/dist/mapbox-gl.css';
62
+ ```
63
+
64
+ `mapbox-gl` is a heavy dependency (~230&nbsp;kB gzipped, more with the geocoder), so the recommended default is to register the components as lazy manifest entries — see [Lazy loading](#lazy-loading) below.
65
+
66
+ ## Lazy loading
67
+
68
+ `mapbox-gl` is never in your main bundle: `MapboxMap` loads it with a dynamic `import()` when it mounts, and `MapboxMap` mounts only when the map nears the viewport, whether you register the class or a manifest entry. Registering the family as a [manifest](https://ui-v2.studiometa.dev/guide/autoloading/) rather than as classes also defers the component modules. A manifest entry is a lazy importer plus a mount strategy, so a component module loads only when an element on the page declares its token, and only when its strategy allows.
69
+
70
+ The package ships its own manifest, which is the shortest way to get all of it:
71
+
72
+ ```js
73
+ import { registerManifest } from '@studiometa/js-toolkit';
74
+ import { manifest } from '@studiometa/ui-mapbox/manifest';
75
+
76
+ registerManifest(manifest);
77
+ ```
78
+
79
+ Every component is also available at its own subpath (`@studiometa/ui-mapbox/<Component>`), whose default export is the component class, so a hand-written manifest can carry only the components you use. Each component is registered independently, so list every one you declare: deferring `MapboxMap` pulls in `mapbox-gl`, but a marker or a cluster is its own module and needs its own entry.
80
+
81
+ ```js
82
+ import { registerManifest } from '@studiometa/js-toolkit';
83
+
84
+ registerManifest({
85
+ MapboxMap: {
86
+ mountStrategy: 'visible',
87
+ load: () => import('@studiometa/ui-mapbox/MapboxMap'),
88
+ },
89
+ MapboxMarker: {
90
+ mountStrategy: 'eager',
91
+ load: () => import('@studiometa/ui-mapbox/MapboxMarker'),
92
+ },
93
+ MapboxPopup: {
94
+ mountStrategy: 'eager',
95
+ load: () => import('@studiometa/ui-mapbox/MapboxPopup'),
96
+ },
97
+ });
98
+ ```
99
+
100
+ The map renders, so `visible` holds the `mapbox-gl` import back until a map approaches the viewport. A marker renders nothing, so its element carries `hidden`, and a popup nested in it is hidden with it. A standalone popup shows its content until the map is ready, unless its element carries `hidden` too. A hidden element never intersects the viewport, so give markers and popups `eager`, which waits for nothing beyond the element being on the page. This is what the package manifest already does — see [Package defaults](https://ui-v2.studiometa.dev/guide/autoloading/#package-defaults).
101
+
102
+ Reach for a different strategy when it fits better — `idle`, `interaction`, `media:<query>` — and override any of them per element with `data-mount`. The [Autoloading](https://ui-v2.studiometa.dev/guide/autoloading/) guide lists all six.