@maptoolkit/maplibre-scene3d-control 0.0.0-stage → 0.1.0

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/LICENSE ADDED
@@ -0,0 +1,27 @@
1
+ Copyright (c) 2026, Maptoolkit - Toursprung GmbH
2
+ All rights reserved.
3
+
4
+ Redistribution and use in source and binary forms, with or without
5
+ modification, are permitted provided that the following conditions are met:
6
+
7
+ 1. Redistributions of source code must retain the above copyright notice, this
8
+ list of conditions and the following disclaimer.
9
+
10
+ 2. Redistributions in binary form must reproduce the above copyright notice,
11
+ this list of conditions and the following disclaimer in the documentation
12
+ and/or other third-party materials provided with the distribution.
13
+
14
+ 3. Neither the name of the copyright holder nor the names of its
15
+ contributors may be used to endorse or promote products derived from
16
+ this software without specific prior written permission.
17
+
18
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
19
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
21
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
22
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
25
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
26
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
27
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
package/README.md CHANGED
@@ -1,3 +1,140 @@
1
- # Temporary Holding Version
1
+ # maplibre-scene3d-control
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![License](https://img.shields.io/npm/l/@maptoolkit/maplibre-scene3d-control?style=plastic)](LICENSE)
4
+ [![Version](https://img.shields.io/npm/v/@maptoolkit/maplibre-scene3d-control?style=plastic)](https://www.npmjs.com/package/@maptoolkit/maplibre-scene3d-control)
5
+
6
+ A [MapLibre GL JS](https://maplibre.org/maplibre-gl-js/docs/) control plugin that adds the 3D scene of a Maptoolkit style: 3D buildings and glTF vegetation.
7
+
8
+ Maptoolkit styles name their scene in `metadata["maptoolkit:scene3d"]`. The control reads it whenever the style changes, so switching styles switches the scene. It draws the buildings with a `fill-extrusion` plus [`@maptoolkit/maplibre-3d-layers`](https://www.npmjs.com/package/@maptoolkit/maplibre-3d-layers) (`Fill3DLayer`, `GltfLayer`) and takes care of the rest:
9
+
10
+ - adds the buildings source with your API key,
11
+ - puts the layers under the style's labels,
12
+ - keeps the tilt in the global state `pitch`, which the scene's opacity fades read,
13
+ - rebuilds the layers after a style or terrain change,
14
+ - loads the 3D library (with three.js) only once the map reaches zoom 12.
15
+
16
+ ## Install
17
+
18
+ ```bash
19
+ npm install @maptoolkit/maplibre-scene3d-control @maptoolkit/maplibre-3d-layers three maplibre-gl
20
+ ```
21
+
22
+ ## Usage
23
+
24
+ ```js
25
+ import * as maplibregl from "maplibre-gl";
26
+ import { Scene3dControl } from "@maptoolkit/maplibre-scene3d-control";
27
+ import "@maptoolkit/maplibre-scene3d-control/style.css";
28
+
29
+ const map = new maplibregl.Map({
30
+ container: "map",
31
+ style: "https://styles.maptoolkit.net/maptoolkit/maptoolkit.summer.json?api_key=YOUR_KEY",
32
+ center: [16.359, 48.21],
33
+ zoom: 16,
34
+ pitch: 70,
35
+ maxPitch: 85,
36
+ canvasContextAttributes: { antialias: true }, // soft edges on distant trees
37
+ });
38
+ map.addControl(new Scene3dControl({ apiKey: "YOUR_KEY" }));
39
+ ```
40
+
41
+ That is all: the scene of the style appears from zoom 12, and a style switch brings the next style's scene.
42
+
43
+ ### Without a bundler
44
+
45
+ The package is ESM-only. With an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap), point `maplibre-gl` at its module build and let the control load the standalone build of maplibre-3d-layers, which includes three.js:
46
+
47
+ ```html
48
+ <script type="importmap">
49
+ { "imports": { "maplibre-gl": "https://unpkg.com/maplibre-gl@^6.0.0/dist/maplibre-gl.mjs" } }
50
+ </script>
51
+ <script type="module">
52
+ import * as maplibregl from "maplibre-gl";
53
+ import { Scene3dControl } from "https://unpkg.com/@maptoolkit/maplibre-scene3d-control@^0.1.0/dist/maplibre-scene3d-control.js";
54
+
55
+ const map = new maplibregl.Map({ container: "map", style, center, zoom, pitch: 70, canvasContextAttributes: { antialias: true } });
56
+ map.addControl(
57
+ new Scene3dControl({
58
+ apiKey: "YOUR_KEY",
59
+ library: () => import("https://unpkg.com/@maptoolkit/maplibre-3d-layers@^0.5.1/dist/maplibre-3d-layers.standalone.mjs"),
60
+ }),
61
+ );
62
+ </script>
63
+ ```
64
+
65
+ ## Options
66
+
67
+ | Option | Type | Default | Description |
68
+ | ------------ | ----------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
69
+ | `apiKey` | `string` | — | Maptoolkit API key, added to the buildings source URL as `api_key`. Without it the buildings source answers 403. |
70
+ | `scene` | `Scene3dManifest \| string \| null` | the style's | A scene (or its URL) to show instead of the style's own; `null` shows none. |
71
+ | `enabled` | `boolean` | `true` | Show the scene right away. |
72
+ | `button` | `boolean` | `false` | Add a 3D button that switches the scene on and off. Without it the control has no UI. |
73
+ | `minzoom` | `number` | `12` | Zoom from which the 3D library is loaded. The buildings source has no tiles below 12. |
74
+ | `hideLayers` | `string[]` | `["building_3d", "building_3d_multicolored"]` | Style layers hidden while the scene's buildings are shown, e.g. a style's own 3D buildings. Hidden only once the buildings source has loaded: without a working API key the style keeps them. |
75
+ | `modelBase` | `string` | document base URL | Base for relative model URLs. |
76
+ | `library` | `() => Promise<Scene3dLibrary>` | `import("@maptoolkit/maplibre-3d-layers")` | Loads the 3D library, e.g. from a CDN. |
77
+ | `idPrefix` | `string` | `"scene3d-"` | Prefix of the source and layer ids the control adds. |
78
+
79
+ ## Methods
80
+
81
+ | Method | Description |
82
+ | -------------------------------- | ------------------------------------------------------------------------------------------------------- |
83
+ | `setScene(scene)` | Show another scene: a manifest, its URL, `null` for none, or `undefined` to go back to the style's own. |
84
+ | `getScene()` | The scene shown now, or `null`. |
85
+ | `setEnabled(on)` / `isEnabled()` | Switch the scene on or off. |
86
+ | `getLayers()` | The maplibre-3d-layers layers on the map, e.g. to drive them frame by frame. |
87
+ | `loadLibrary()` / `getLibrary()` | Load the 3D library now instead of at `minzoom`; the loaded library. |
88
+
89
+ ## Events
90
+
91
+ ```js
92
+ control.on("scene.change", (ev) => console.log(ev.scene)); // built, rebuilt or removed
93
+ ```
94
+
95
+ ## The scene (`metadata["maptoolkit:scene3d"]`, version 1)
96
+
97
+ All values are plain MapLibre or maplibre-3d-layers options. Maptoolkit styles get it from [style-family-js](https://github.com/maptoolkit/style-family-js).
98
+
99
+ ```js
100
+ {
101
+ version: 1,
102
+ source: "https://…/buildings.json", // TileJSON of the buildings, without api_key
103
+ lod1: { filter, paint, layout }, // fill-extrusion on the source layer buildings2d
104
+ fill3d: { paint }, // Fill3DLayer on the source layer buildings3d
105
+ models: { tree_1: "https://static.maptoolkit.net/3d/models/…/Tree.gltf" },
106
+ gltf: [{ id, models: ["tree_1"], source: "mtk", "source-layer": "natural", filter, minzoom, layout, paint, lighting }],
107
+ }
108
+ ```
109
+
110
+ Every part is optional except `version` and `source`. A layer goes under the style's labels unless it says `position: "top"`. Vegetation needs the source it names in the style (`mtk` in Maptoolkit styles); a layer whose source the style lacks is left out with a warning.
111
+
112
+ ## Requirements
113
+
114
+ - MapLibre GL JS ≥ 6, `@maptoolkit/maplibre-3d-layers` ≥ 0.5.1 and three.js ≥ 0.160 (peer dependencies of the 3D library).
115
+ - A Maptoolkit API key with access to the buildings source.
116
+ - A style with a scene, or a scene passed with `scene`. Vegetation also needs the style's `mtk` source.
117
+
118
+ ## Styling
119
+
120
+ ```css
121
+ .maplibre-scene3d-control {
122
+ --scene3d-control-color: #333;
123
+ --scene3d-control-color-active: #0074d9;
124
+ }
125
+ ```
126
+
127
+ ## Development
128
+
129
+ ```bash
130
+ npm install
131
+ npm run dev # demo on http://localhost:5173 (demo/index.html, scene in demo/public/scene.json)
132
+ npm test
133
+ npm run lint
134
+ npm run typecheck
135
+ npm run build
136
+ ```
137
+
138
+ ## License
139
+
140
+ BSD-3-Clause
@@ -0,0 +1,170 @@
1
+ import { Evented, ControlPosition, CustomLayerInterface, FilterSpecification, IControl, Map as MaplibreMap, MapLibreEvent } from 'maplibre-gl';
2
+ /** Root metadata key under which a Maptoolkit style carries its 3D scene. */
3
+ export declare const SCENE3D_METADATA_KEY = "maptoolkit:scene3d";
4
+ /** Where a layer of the scene goes: under the style's labels (default) or on top of everything. */
5
+ export type Scene3dPosition = "below-labels" | "top";
6
+ type Expression = unknown;
7
+ /** One glTF vegetation layer: maplibre-3d-layers `GltfLayer` options, `models` as ids of the scene's model library. */
8
+ export interface Scene3dGltfLayer {
9
+ id: string;
10
+ position?: Scene3dPosition;
11
+ /** Model ids from {@link Scene3dManifest.models}; all of them when missing. */
12
+ models?: string[];
13
+ source: string;
14
+ "source-layer"?: string;
15
+ filter?: FilterSpecification;
16
+ minzoom?: number;
17
+ maxzoom?: number;
18
+ layout?: Record<string, Expression>;
19
+ paint?: Record<string, Expression>;
20
+ lighting?: {
21
+ ambient?: number;
22
+ directional?: number;
23
+ environment?: number;
24
+ };
25
+ maxInstances?: number;
26
+ doubleSided?: boolean;
27
+ }
28
+ /** The 3D scene of a style, `metadata["maptoolkit:scene3d"]` (version 1). Values are plain MapLibre / maplibre-3d-layers options. */
29
+ export interface Scene3dManifest {
30
+ version: 1;
31
+ /** TileJSON URL of the buildings source, without api_key. */
32
+ source: string;
33
+ /** `fill-extrusion` on the source layer `buildings2d`. */
34
+ lod1?: {
35
+ position?: Scene3dPosition;
36
+ minzoom?: number;
37
+ maxzoom?: number;
38
+ filter?: FilterSpecification;
39
+ paint?: Record<string, Expression>;
40
+ layout?: Record<string, Expression>;
41
+ };
42
+ /** `Fill3DLayer` on the source layer `buildings3d`. */
43
+ fill3d?: {
44
+ position?: Scene3dPosition;
45
+ filter?: FilterSpecification;
46
+ paint?: Record<string, Expression>;
47
+ };
48
+ /** Model library of the vegetation: id → glTF/glb URL. */
49
+ models?: Record<string, string>;
50
+ gltf?: Scene3dGltfLayer[];
51
+ }
52
+ /** What the control needs from `@maptoolkit/maplibre-3d-layers`. */
53
+ export interface Scene3dLibrary {
54
+ Fill3DLayer: new (options: Record<string, unknown>) => CustomLayerInterface;
55
+ GltfLayer: new (options: Record<string, unknown>) => CustomLayerInterface;
56
+ }
57
+ export interface Scene3dControlOptions {
58
+ /** Maptoolkit API key, added to the buildings source URL as `api_key`. */
59
+ apiKey?: string;
60
+ /**
61
+ * The scene to show. Left out: the one the current style names in `metadata["maptoolkit:scene3d"]`,
62
+ * re-read on every style change. A manifest or its URL replaces it; `null` shows none.
63
+ */
64
+ scene?: Scene3dManifest | string | null;
65
+ /** Show the scene right away (default `true`). */
66
+ enabled?: boolean;
67
+ /** Add a 3D button that switches the scene on and off (default `false`: the control has no UI). */
68
+ button?: boolean;
69
+ /** The 3D library is loaded once the map reaches this zoom; the buildings source has no tiles below 12 (default `12`). */
70
+ minzoom?: number;
71
+ /**
72
+ * Style layers hidden while the scene's buildings are shown, e.g. a style's own 3D buildings (default the v2 ids
73
+ * `building_3d`, `building_3d_multicolored`). Hidden only once the buildings source has loaded, so without a working
74
+ * API key the style keeps them.
75
+ */
76
+ hideLayers?: string[];
77
+ /** Base for relative model URLs (default the document's base URL). */
78
+ modelBase?: string;
79
+ /** Loads `@maptoolkit/maplibre-3d-layers` (default a dynamic import of the package). Pass another loader for its standalone build or a CDN. */
80
+ library?: () => Promise<Scene3dLibrary>;
81
+ /** Prefix of the source and layer ids the control adds (default `"scene3d-"`). */
82
+ idPrefix?: string;
83
+ }
84
+ /** Fired via `control.on("scene.change", ...)` whenever the shown scene is (re)built or removed. */
85
+ export type Scene3dControlEventType = {
86
+ "scene.change": MapLibreEvent<"scene.change"> & {
87
+ scene: Scene3dManifest | null;
88
+ };
89
+ };
90
+ type ResolvedOptions = Required<Omit<Scene3dControlOptions, "apiKey" | "scene" | "modelBase">> & Pick<Scene3dControlOptions, "apiKey" | "modelBase">;
91
+ /**
92
+ * A MapLibre GL JS control plugin that adds the 3D scene of a Maptoolkit style: 3D buildings
93
+ * (a `fill-extrusion` plus maplibre-3d-layers' `Fill3DLayer`) and glTF vegetation (`GltfLayer`).
94
+ *
95
+ * The scene comes from the style itself (`metadata["maptoolkit:scene3d"]`, written by style-family-js),
96
+ * so a style switch brings its own scene. The control keeps the tilt in the global state `pitch`
97
+ * that the scene's opacity fades read, puts the layers under the style's labels, rebuilds them after
98
+ * style and terrain changes and loads the 3D library only when the map gets close enough.
99
+ */
100
+ export declare class Scene3dControl extends Evented<Scene3dControlEventType> implements IControl {
101
+ readonly options: ResolvedOptions;
102
+ private map?;
103
+ private container?;
104
+ private button?;
105
+ private enabled;
106
+ /** undefined: the style's own scene. */
107
+ private override;
108
+ private scene;
109
+ private lib?;
110
+ private libPromise?;
111
+ private custom;
112
+ private native;
113
+ private hidden;
114
+ private loadedStyle;
115
+ private pitch;
116
+ private building;
117
+ private generation;
118
+ private warned;
119
+ /** Stops waiting for the buildings source (see hideOnceBuildingsLoad). */
120
+ private stopWaiting?;
121
+ constructor(options?: Scene3dControlOptions);
122
+ getDefaultPosition(): ControlPosition;
123
+ onAdd(map: MaplibreMap): HTMLElement;
124
+ onRemove(): void;
125
+ /**
126
+ * Replace the style's scene: a manifest, the URL of one, `null` for none, or `undefined` to go back
127
+ * to the style's own scene.
128
+ */
129
+ setScene(scene: Scene3dManifest | string | null | undefined): Promise<void>;
130
+ /** The scene shown now, or null. */
131
+ getScene(): Scene3dManifest | null;
132
+ setEnabled(enabled: boolean): void;
133
+ isEnabled(): boolean;
134
+ /** The maplibre-3d-layers layers on the map (`Fill3DLayer`, `GltfLayer`s), e.g. to drive them frame by frame. */
135
+ getLayers(): CustomLayerInterface[];
136
+ /** The 3D library, once loaded. */
137
+ getLibrary(): Scene3dLibrary | undefined;
138
+ /** Load the 3D library now instead of waiting for `minzoom`. */
139
+ loadLibrary(): Promise<Scene3dLibrary>;
140
+ private onStyleLoad;
141
+ private onStyleData;
142
+ private onTerrain;
143
+ private onZoom;
144
+ /** `["global-state", "pitch"]` for the scene's opacity fades. Whole degrees: each change is a style update. */
145
+ private syncPitch;
146
+ private styleReady;
147
+ private currentScene;
148
+ private refresh;
149
+ private sourceId;
150
+ /** The id of the style's first symbol layer: the scene goes right below it. */
151
+ private labelsAnchor;
152
+ private beforeFor;
153
+ private addNative;
154
+ private loadCustom;
155
+ private addCustom;
156
+ private removeCustom;
157
+ /** Remove everything the control added; `restore` puts hidden style layers back. */
158
+ private teardown;
159
+ /**
160
+ * Hide the style's own 3D buildings (`hideLayers`) only once the scene's buildings source has
161
+ * loaded. Without a working API key it answers 403, and the style keeps its buildings.
162
+ */
163
+ private hideOnceBuildingsLoad;
164
+ private hideStyleLayers;
165
+ private withKey;
166
+ private modelUrl;
167
+ private showState;
168
+ private warnOnce;
169
+ }
170
+ export {};
@@ -0,0 +1,2 @@
1
+ export { Scene3dControl, SCENE3D_METADATA_KEY } from './Scene3dControl';
2
+ export type { Scene3dControlOptions, Scene3dManifest, Scene3dGltfLayer, Scene3dLibrary, Scene3dPosition, Scene3dControlEventType } from './Scene3dControl';
@@ -0,0 +1,2 @@
1
+ .maplibre-scene3d-control{--scene3d-control-color:#333;--scene3d-control-color-active:#0074d9}.maplibre-scene3d-control-hidden{display:none}.maplibre-scene3d-control-toggle{color:var(--scene3d-control-color);justify-content:center;align-items:center;display:flex}.maplibre-scene3d-control-toggle svg{width:20px;height:20px}.maplibre-scene3d-control-toggle[aria-pressed=true]{color:var(--scene3d-control-color-active)}
2
+ /*$vite$:1*/
@@ -0,0 +1,239 @@
1
+ import { Evented as e } from "maplibre-gl";
2
+ // src/Scene3dControl.ts
3
+ var t = "maptoolkit:scene3d", n = {
4
+ enabled: !0,
5
+ button: !1,
6
+ minzoom: 12,
7
+ hideLayers: ["building_3d", "building_3d_multicolored"],
8
+ idPrefix: "scene3d-"
9
+ }, r = "<svg viewBox=\"0 0 24 24\" aria-hidden=\"true\"><path fill=\"currentColor\" d=\"M12 2 3 7v10l9 5 9-5V7l-9-5Zm0 2.3L18.7 8 12 11.7 5.3 8 12 4.3ZM5 9.7l6 3.3v6.7l-6-3.4V9.7Zm8 10V13l6-3.3v6.6l-6 3.4Z\"/></svg>", i = (e) => e.style, a = class extends e {
10
+ options;
11
+ map;
12
+ container;
13
+ button;
14
+ enabled;
15
+ override;
16
+ scene = null;
17
+ lib;
18
+ libPromise;
19
+ custom = [];
20
+ native = [];
21
+ hidden = /* @__PURE__ */ new Map();
22
+ loadedStyle = void 0;
23
+ pitch = null;
24
+ building = !1;
25
+ generation = 0;
26
+ warned = /* @__PURE__ */ new Set();
27
+ stopWaiting;
28
+ constructor(e = {}) {
29
+ super();
30
+ let { scene: t, ...r } = e;
31
+ this.options = {
32
+ ...n,
33
+ library: () => import("@maptoolkit/maplibre-3d-layers"),
34
+ ...Object.fromEntries(Object.entries(r).filter(([, e]) => e !== void 0))
35
+ }, this.enabled = this.options.enabled, t !== void 0 && this.setScene(t);
36
+ }
37
+ getDefaultPosition() {
38
+ return "top-right";
39
+ }
40
+ onAdd(e) {
41
+ this.map = e;
42
+ let t = document.createElement("div");
43
+ if (t.className = "maplibregl-ctrl maplibregl-ctrl-group maplibre-scene3d-control", this.options.button) {
44
+ let e = document.createElement("button");
45
+ e.type = "button", e.className = "maplibre-scene3d-control-toggle", e.title = "3D", e.setAttribute("aria-label", "3D"), e.innerHTML = r, e.addEventListener("click", () => this.setEnabled(!this.enabled)), t.appendChild(e), this.button = e, this.showState();
46
+ } else t.classList.add("maplibre-scene3d-control-hidden");
47
+ return this.container = t, e.on("style.load", this.onStyleLoad), e.on("styledata", this.onStyleData), e.on("terrain", this.onTerrain), e.on("pitch", this.syncPitch), e.on("zoomend", this.onZoom), i(e)?._loaded && this.onStyleLoad(), t;
48
+ }
49
+ onRemove() {
50
+ let e = this.map;
51
+ e && (this.teardown(!0), e.off("style.load", this.onStyleLoad), e.off("styledata", this.onStyleData), e.off("terrain", this.onTerrain), e.off("pitch", this.syncPitch), e.off("zoomend", this.onZoom), this.container?.remove(), this.container = this.button = void 0, this.map = void 0, this.loadedStyle = void 0);
52
+ }
53
+ async setScene(e) {
54
+ if (typeof e == "string") {
55
+ let t = await fetch(new URL(e, document.baseURI).href);
56
+ if (!t.ok) throw Error(`Scene ${e}: HTTP ${t.status}`);
57
+ e = await t.json();
58
+ }
59
+ this.override = e, this.refresh();
60
+ }
61
+ getScene() {
62
+ return this.scene;
63
+ }
64
+ setEnabled(e) {
65
+ this.enabled !== e && (this.enabled = e, this.showState(), this.refresh());
66
+ }
67
+ isEnabled() {
68
+ return this.enabled;
69
+ }
70
+ getLayers() {
71
+ return [...this.custom];
72
+ }
73
+ getLibrary() {
74
+ return this.lib;
75
+ }
76
+ loadLibrary() {
77
+ return this.libPromise ??= this.options.library().then((e) => this.lib = e, (e) => {
78
+ throw this.libPromise = void 0, e;
79
+ }), this.libPromise;
80
+ }
81
+ onStyleLoad = () => {
82
+ this.map && (this.loadedStyle = i(this.map), this.pitch = null, this.teardown(!1), this.refresh());
83
+ };
84
+ onStyleData = () => {
85
+ !this.building && this.map && this.styleReady() && this.scene && [...this.native, ...this.custom.map((e) => e.id)].some((e) => !this.map.getLayer(e)) && this.refresh();
86
+ };
87
+ onTerrain = () => {
88
+ this.map && this.styleReady() && this.custom.length && this.scene && (this.removeCustom(), this.addCustom(this.scene, this.generation));
89
+ };
90
+ onZoom = () => {
91
+ !this.map || this.lib || !this.scene || this.map.getZoom() < this.options.minzoom || this.loadCustom(this.scene, this.generation);
92
+ };
93
+ syncPitch = () => {
94
+ if (!this.map || !this.styleReady()) return;
95
+ let e = Math.round(this.map.getPitch());
96
+ e !== this.pitch && (this.pitch = e, this.map.setGlobalStateProperty("pitch", e));
97
+ };
98
+ styleReady() {
99
+ return !!this.map && !!this.loadedStyle && i(this.map) === this.loadedStyle;
100
+ }
101
+ currentScene() {
102
+ return this.enabled ? this.override === void 0 ? this.map?.getStyle()?.metadata?.["maptoolkit:scene3d"] ?? null : this.override : null;
103
+ }
104
+ refresh() {
105
+ let e = this.map;
106
+ if (e && this.styleReady()) {
107
+ this.building = !0;
108
+ try {
109
+ this.teardown(!0);
110
+ let t = ++this.generation, n = this.currentScene();
111
+ n && n.version !== 1 && (this.warnOnce(`version-${String(n.version)}`, `Scene3dControl: unsupported scene version ${String(n.version)}`), n = null), this.scene = n, n && (this.syncPitch(), (n.lod1 || n.fill3d) && this.hideOnceBuildingsLoad(t), this.addNative(n), this.lib ? this.addCustom(n, t) : e.getZoom() >= this.options.minzoom && this.loadCustom(n, t));
112
+ } finally {
113
+ this.building = !1;
114
+ }
115
+ this.fire("scene.change", { scene: this.scene });
116
+ }
117
+ }
118
+ sourceId() {
119
+ return `${this.options.idPrefix}buildings`;
120
+ }
121
+ labelsAnchor() {
122
+ return this.map?.getStyle().layers.find((e) => e.type === "symbol" && !e.id.startsWith(this.options.idPrefix))?.id;
123
+ }
124
+ beforeFor(e, t) {
125
+ return e === "top" ? void 0 : t;
126
+ }
127
+ addNative(e) {
128
+ let t = this.map, n = this.sourceId();
129
+ t.getSource(n) || t.addSource(n, {
130
+ type: "vector",
131
+ url: this.withKey(e.source)
132
+ });
133
+ let r = this.labelsAnchor(), i = this.options.idPrefix;
134
+ if (e.lod1) {
135
+ let { position: a, ...o } = e.lod1;
136
+ t.addLayer({
137
+ id: `${i}lod1`,
138
+ type: "fill-extrusion",
139
+ source: n,
140
+ "source-layer": "buildings2d",
141
+ ...o
142
+ }, this.beforeFor(a, r)), this.native.push(`${i}lod1`);
143
+ } else e.fill3d && (t.addLayer({
144
+ id: `${i}consumer`,
145
+ type: "fill",
146
+ source: n,
147
+ "source-layer": "buildings2d",
148
+ filter: ["boolean", !1],
149
+ paint: { "fill-opacity": 0 }
150
+ }, this.beforeFor(e.fill3d.position, r)), this.native.push(`${i}consumer`));
151
+ }
152
+ loadCustom(e, t) {
153
+ this.loadLibrary().then(() => {
154
+ t === this.generation && this.scene === e && !this.custom.length && this.addCustom(e, t);
155
+ }, (e) => console.error("Scene3dControl: could not load @maptoolkit/maplibre-3d-layers", e));
156
+ }
157
+ addCustom(e, t) {
158
+ let n = this.map, r = this.lib;
159
+ if (!n || !r || t !== this.generation || !this.styleReady()) return;
160
+ let i = this.labelsAnchor(), a = this.options.idPrefix, o = (e, t) => {
161
+ n.addLayer(e, this.beforeFor(t, i)), this.custom.push(e);
162
+ };
163
+ this.building = !0;
164
+ try {
165
+ if (e.fill3d) {
166
+ let { position: t, ...n } = e.fill3d;
167
+ o(new r.Fill3DLayer({
168
+ id: `${a}fill3d`,
169
+ source: this.sourceId(),
170
+ "source-layer": "buildings3d",
171
+ ...n
172
+ }), t);
173
+ }
174
+ let t = e.models ?? {};
175
+ for (let i of e.gltf ?? []) {
176
+ let { id: e, position: s, models: c, ...l } = i;
177
+ if (!n.getSource(l.source)) {
178
+ this.warnOnce(`source-${l.source}`, `Scene3dControl: the style has no source "${l.source}", layer "${e}" left out`);
179
+ continue;
180
+ }
181
+ let u = c ?? Object.keys(t), d = Object.fromEntries(u.filter((e) => t[e]).map((e) => [e, this.modelUrl(t[e])]));
182
+ Object.keys(d).length && o(new r.GltfLayer({
183
+ id: `${a}${e}`,
184
+ models: d,
185
+ ...l
186
+ }), s);
187
+ }
188
+ } finally {
189
+ this.building = !1;
190
+ }
191
+ }
192
+ removeCustom() {
193
+ let e = this.map;
194
+ for (let t of this.custom) e?.getLayer(t.id) ? e.removeLayer(t.id) : e && t.onRemove?.(e, void 0);
195
+ this.custom = [];
196
+ }
197
+ teardown(e) {
198
+ let t = this.map;
199
+ this.stopWaiting?.(), this.building = !0;
200
+ try {
201
+ if (this.removeCustom(), t) {
202
+ for (let e of this.native) t.getLayer(e) && t.removeLayer(e);
203
+ if (t.getSource(this.sourceId()) && this.styleReady() && t.removeSource(this.sourceId()), e && this.styleReady()) for (let [e, n] of this.hidden) t.getLayer(e) && t.setLayoutProperty(e, "visibility", n);
204
+ }
205
+ this.native = [], this.hidden.clear(), this.scene = null;
206
+ } finally {
207
+ this.building = !1;
208
+ }
209
+ }
210
+ hideOnceBuildingsLoad(e) {
211
+ let t = this.map, n = this.sourceId(), r = (r) => {
212
+ r.sourceId === n && r.sourceDataType === "metadata" && t.getSource(n) && (this.stopWaiting?.(), e === this.generation && this.styleReady() && this.hideStyleLayers());
213
+ };
214
+ t.on("sourcedata", r), this.stopWaiting = () => {
215
+ t.off("sourcedata", r), this.stopWaiting = void 0;
216
+ };
217
+ }
218
+ hideStyleLayers() {
219
+ let e = this.map;
220
+ for (let t of this.options.hideLayers) e.getLayer(t) && (this.hidden.set(t, e.getLayoutProperty(t, "visibility") ?? "visible"), e.setLayoutProperty(t, "visibility", "none"));
221
+ }
222
+ withKey(e) {
223
+ if (!this.options.apiKey) return e;
224
+ let t = new URL(e, document.baseURI);
225
+ return t.searchParams.has("api_key") || t.searchParams.set("api_key", this.options.apiKey), t.href;
226
+ }
227
+ modelUrl(e) {
228
+ return new URL(e, this.options.modelBase ?? document.baseURI).href;
229
+ }
230
+ showState() {
231
+ this.button?.setAttribute("aria-pressed", String(this.enabled));
232
+ }
233
+ warnOnce(e, t) {
234
+ this.warned.has(e) || (this.warned.add(e), console.warn(t));
235
+ }
236
+ };
237
+ export { t as SCENE3D_METADATA_KEY, a as Scene3dControl };
238
+
239
+ //# sourceMappingURL=maplibre-scene3d-control.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"maplibre-scene3d-control.js","names":["SCENE3D_METADATA_KEY","DEFAULTS","CUBE_ICON","styleOf","map","Scene3dControl","Evented","rest","options","v","scene","container","button","response","enabled","lib","err","l","id","pitch","generation","position","anchor","source","p","lod1","add","layer","fill3d","library","entry","ids","picked","models","m","restore","visibility","onData","e","url","u","key","message"],"sources":["../src/Scene3dControl.ts"],"sourcesContent":["import { Evented } from \"maplibre-gl\";\nimport type { ControlPosition, CustomLayerInterface, FilterSpecification, IControl, Map as MaplibreMap, MapLibreEvent, MapSourceDataEvent } from \"maplibre-gl\";\n\n/** Root metadata key under which a Maptoolkit style carries its 3D scene. */\nexport const SCENE3D_METADATA_KEY = \"maptoolkit:scene3d\";\n\n/** Where a layer of the scene goes: under the style's labels (default) or on top of everything. */\nexport type Scene3dPosition = \"below-labels\" | \"top\";\n\ntype Expression = unknown;\n\n/** One glTF vegetation layer: maplibre-3d-layers `GltfLayer` options, `models` as ids of the scene's model library. */\nexport interface Scene3dGltfLayer {\n id: string;\n position?: Scene3dPosition;\n /** Model ids from {@link Scene3dManifest.models}; all of them when missing. */\n models?: string[];\n source: string;\n \"source-layer\"?: string;\n filter?: FilterSpecification;\n minzoom?: number;\n maxzoom?: number;\n layout?: Record<string, Expression>;\n paint?: Record<string, Expression>;\n lighting?: { ambient?: number; directional?: number; environment?: number };\n maxInstances?: number;\n doubleSided?: boolean;\n}\n\n/** The 3D scene of a style, `metadata[\"maptoolkit:scene3d\"]` (version 1). Values are plain MapLibre / maplibre-3d-layers options. */\nexport interface Scene3dManifest {\n version: 1;\n /** TileJSON URL of the buildings source, without api_key. */\n source: string;\n /** `fill-extrusion` on the source layer `buildings2d`. */\n lod1?: {\n position?: Scene3dPosition;\n minzoom?: number;\n maxzoom?: number;\n filter?: FilterSpecification;\n paint?: Record<string, Expression>;\n layout?: Record<string, Expression>;\n };\n /** `Fill3DLayer` on the source layer `buildings3d`. */\n fill3d?: { position?: Scene3dPosition; filter?: FilterSpecification; paint?: Record<string, Expression> };\n /** Model library of the vegetation: id → glTF/glb URL. */\n models?: Record<string, string>;\n gltf?: Scene3dGltfLayer[];\n}\n\n/** What the control needs from `@maptoolkit/maplibre-3d-layers`. */\nexport interface Scene3dLibrary {\n Fill3DLayer: new (options: Record<string, unknown>) => CustomLayerInterface;\n GltfLayer: new (options: Record<string, unknown>) => CustomLayerInterface;\n}\n\nexport interface Scene3dControlOptions {\n /** Maptoolkit API key, added to the buildings source URL as `api_key`. */\n apiKey?: string;\n /**\n * The scene to show. Left out: the one the current style names in `metadata[\"maptoolkit:scene3d\"]`,\n * re-read on every style change. A manifest or its URL replaces it; `null` shows none.\n */\n scene?: Scene3dManifest | string | null;\n /** Show the scene right away (default `true`). */\n enabled?: boolean;\n /** Add a 3D button that switches the scene on and off (default `false`: the control has no UI). */\n button?: boolean;\n /** The 3D library is loaded once the map reaches this zoom; the buildings source has no tiles below 12 (default `12`). */\n minzoom?: number;\n /**\n * Style layers hidden while the scene's buildings are shown, e.g. a style's own 3D buildings (default the v2 ids\n * `building_3d`, `building_3d_multicolored`). Hidden only once the buildings source has loaded, so without a working\n * API key the style keeps them.\n */\n hideLayers?: string[];\n /** Base for relative model URLs (default the document's base URL). */\n modelBase?: string;\n /** Loads `@maptoolkit/maplibre-3d-layers` (default a dynamic import of the package). Pass another loader for its standalone build or a CDN. */\n library?: () => Promise<Scene3dLibrary>;\n /** Prefix of the source and layer ids the control adds (default `\"scene3d-\"`). */\n idPrefix?: string;\n}\n\n/** Fired via `control.on(\"scene.change\", ...)` whenever the shown scene is (re)built or removed. */\nexport type Scene3dControlEventType = {\n \"scene.change\": MapLibreEvent<\"scene.change\"> & { scene: Scene3dManifest | null };\n};\n\ntype ResolvedOptions = Required<Omit<Scene3dControlOptions, \"apiKey\" | \"scene\" | \"modelBase\">> & Pick<Scene3dControlOptions, \"apiKey\" | \"modelBase\">;\n\nconst DEFAULTS: Omit<ResolvedOptions, \"library\"> = {\n enabled: true,\n button: false,\n minzoom: 12,\n hideLayers: [\"building_3d\", \"building_3d_multicolored\"],\n idPrefix: \"scene3d-\",\n};\n\nconst CUBE_ICON =\n '<svg viewBox=\"0 0 24 24\" aria-hidden=\"true\"><path fill=\"currentColor\" d=\"M12 2 3 7v10l9 5 9-5V7l-9-5Zm0 2.3L18.7 8 12 11.7 5.3 8 12 4.3ZM5 9.7l6 3.3v6.7l-6-3.4V9.7Zm8 10V13l6-3.3v6.6l-6 3.4Z\"/></svg>';\n\n// MapLibre's Style is private API; the control only reads whether it has loaded and its identity.\ntype StyleHandle = { _loaded?: boolean } | undefined;\nconst styleOf = (map: MaplibreMap) => (map as unknown as { style?: StyleHandle }).style;\n\n/**\n * A MapLibre GL JS control plugin that adds the 3D scene of a Maptoolkit style: 3D buildings\n * (a `fill-extrusion` plus maplibre-3d-layers' `Fill3DLayer`) and glTF vegetation (`GltfLayer`).\n *\n * The scene comes from the style itself (`metadata[\"maptoolkit:scene3d\"]`, written by style-family-js),\n * so a style switch brings its own scene. The control keeps the tilt in the global state `pitch`\n * that the scene's opacity fades read, puts the layers under the style's labels, rebuilds them after\n * style and terrain changes and loads the 3D library only when the map gets close enough.\n */\nexport class Scene3dControl extends Evented<Scene3dControlEventType> implements IControl {\n readonly options: ResolvedOptions;\n\n private map?: MaplibreMap;\n private container?: HTMLElement;\n private button?: HTMLButtonElement;\n private enabled: boolean;\n /** undefined: the style's own scene. */\n private override: Scene3dManifest | null | undefined;\n private scene: Scene3dManifest | null = null;\n private lib?: Scene3dLibrary;\n private libPromise?: Promise<Scene3dLibrary>;\n private custom: CustomLayerInterface[] = [];\n private native: string[] = [];\n private hidden = new Map<string, \"visible\" | \"none\">();\n private loadedStyle: StyleHandle = undefined;\n private pitch: number | null = null;\n private building = false;\n private generation = 0;\n private warned = new Set<string>();\n /** Stops waiting for the buildings source (see hideOnceBuildingsLoad). */\n private stopWaiting?: () => void;\n\n constructor(options: Scene3dControlOptions = {}) {\n super();\n const { scene, ...rest } = options;\n this.options = {\n ...DEFAULTS,\n library: () => import(\"@maptoolkit/maplibre-3d-layers\") as unknown as Promise<Scene3dLibrary>,\n ...Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== undefined)),\n } as ResolvedOptions;\n this.enabled = this.options.enabled;\n if (scene !== undefined) void this.setScene(scene);\n }\n\n getDefaultPosition(): ControlPosition {\n return \"top-right\";\n }\n\n onAdd(map: MaplibreMap): HTMLElement {\n this.map = map;\n const container = document.createElement(\"div\");\n container.className = \"maplibregl-ctrl maplibregl-ctrl-group maplibre-scene3d-control\";\n if (this.options.button) {\n const button = document.createElement(\"button\");\n button.type = \"button\";\n button.className = \"maplibre-scene3d-control-toggle\";\n button.title = \"3D\";\n button.setAttribute(\"aria-label\", \"3D\");\n button.innerHTML = CUBE_ICON;\n button.addEventListener(\"click\", () => this.setEnabled(!this.enabled));\n container.appendChild(button);\n this.button = button;\n this.showState();\n } else {\n container.classList.add(\"maplibre-scene3d-control-hidden\");\n }\n this.container = container;\n\n map.on(\"style.load\", this.onStyleLoad);\n map.on(\"styledata\", this.onStyleData);\n map.on(\"terrain\", this.onTerrain);\n map.on(\"pitch\", this.syncPitch);\n map.on(\"zoomend\", this.onZoom);\n // Added to a map whose style has already loaded: no style.load will come for it.\n if (styleOf(map)?._loaded) this.onStyleLoad();\n return container;\n }\n\n onRemove(): void {\n const map = this.map;\n if (!map) return;\n this.teardown(true);\n map.off(\"style.load\", this.onStyleLoad);\n map.off(\"styledata\", this.onStyleData);\n map.off(\"terrain\", this.onTerrain);\n map.off(\"pitch\", this.syncPitch);\n map.off(\"zoomend\", this.onZoom);\n this.container?.remove();\n this.container = this.button = undefined;\n this.map = undefined;\n this.loadedStyle = undefined;\n }\n\n /**\n * Replace the style's scene: a manifest, the URL of one, `null` for none, or `undefined` to go back\n * to the style's own scene.\n */\n async setScene(scene: Scene3dManifest | string | null | undefined): Promise<void> {\n if (typeof scene === \"string\") {\n const response = await fetch(new URL(scene, document.baseURI).href);\n if (!response.ok) throw new Error(`Scene ${scene}: HTTP ${response.status}`);\n scene = (await response.json()) as Scene3dManifest;\n }\n this.override = scene;\n this.refresh();\n }\n\n /** The scene shown now, or null. */\n getScene(): Scene3dManifest | null {\n return this.scene;\n }\n\n setEnabled(enabled: boolean): void {\n if (this.enabled === enabled) return;\n this.enabled = enabled;\n this.showState();\n this.refresh();\n }\n\n isEnabled(): boolean {\n return this.enabled;\n }\n\n /** The maplibre-3d-layers layers on the map (`Fill3DLayer`, `GltfLayer`s), e.g. to drive them frame by frame. */\n getLayers(): CustomLayerInterface[] {\n return [...this.custom];\n }\n\n /** The 3D library, once loaded. */\n getLibrary(): Scene3dLibrary | undefined {\n return this.lib;\n }\n\n /** Load the 3D library now instead of waiting for `minzoom`. */\n loadLibrary(): Promise<Scene3dLibrary> {\n this.libPromise ??= this.options.library().then(\n (lib) => (this.lib = lib),\n (err) => {\n this.libPromise = undefined;\n throw err;\n },\n );\n return this.libPromise;\n }\n\n // ---------------------------------------------------------------- map events\n\n private onStyleLoad = () => {\n if (!this.map) return;\n this.loadedStyle = styleOf(this.map);\n this.pitch = null; // a new style starts with its own global state\n this.teardown(false); // whatever of the old scene a style diff left behind\n this.refresh();\n };\n\n // A style switch with diff (setStyle without { diff: false }) keeps the Style object, fires no\n // style.load and drops our layers as \"not in the new style\": rebuild from the new style.\n private onStyleData = () => {\n if (this.building || !this.map || !this.styleReady() || !this.scene) return;\n const ids = [...this.native, ...this.custom.map((l) => l.id)];\n if (ids.some((id) => !this.map!.getLayer(id))) this.refresh();\n };\n\n // The 3D layers take the terrain as it is when they are added.\n private onTerrain = () => {\n if (!this.map || !this.styleReady() || !this.custom.length || !this.scene) return;\n this.removeCustom();\n this.addCustom(this.scene, this.generation);\n };\n\n private onZoom = () => {\n if (!this.map || this.lib || !this.scene || this.map.getZoom() < this.options.minzoom) return;\n this.loadCustom(this.scene, this.generation);\n };\n\n /** `[\"global-state\", \"pitch\"]` for the scene's opacity fades. Whole degrees: each change is a style update. */\n private syncPitch = () => {\n if (!this.map || !this.styleReady()) return;\n const pitch = Math.round(this.map.getPitch());\n if (pitch === this.pitch) return;\n this.pitch = pitch;\n this.map.setGlobalStateProperty(\"pitch\", pitch);\n };\n\n // ---------------------------------------------------------------- building\n\n private styleReady(): boolean {\n return !!this.map && !!this.loadedStyle && styleOf(this.map) === this.loadedStyle;\n }\n\n private currentScene(): Scene3dManifest | null {\n if (!this.enabled) return null;\n if (this.override !== undefined) return this.override;\n const scene = this.map?.getStyle()?.metadata as Record<string, unknown> | undefined;\n return (scene?.[SCENE3D_METADATA_KEY] as Scene3dManifest | undefined) ?? null;\n }\n\n private refresh() {\n const map = this.map;\n if (!map || !this.styleReady()) return;\n this.building = true;\n try {\n this.teardown(true);\n const generation = ++this.generation;\n let scene = this.currentScene();\n if (scene && scene.version !== 1) {\n this.warnOnce(`version-${String(scene.version)}`, `Scene3dControl: unsupported scene version ${String(scene.version)}`);\n scene = null;\n }\n this.scene = scene;\n if (scene) {\n this.syncPitch();\n if (scene.lod1 || scene.fill3d) this.hideOnceBuildingsLoad(generation);\n this.addNative(scene);\n if (this.lib) this.addCustom(scene, generation);\n else if (map.getZoom() >= this.options.minzoom) this.loadCustom(scene, generation);\n }\n } finally {\n this.building = false;\n }\n this.fire(\"scene.change\", { scene: this.scene });\n }\n\n private sourceId() {\n return `${this.options.idPrefix}buildings`;\n }\n\n /** The id of the style's first symbol layer: the scene goes right below it. */\n private labelsAnchor(): string | undefined {\n return this.map?.getStyle().layers.find((l) => l.type === \"symbol\" && !l.id.startsWith(this.options.idPrefix))?.id;\n }\n\n private beforeFor(position: Scene3dPosition | undefined, anchor: string | undefined) {\n return position === \"top\" ? undefined : anchor;\n }\n\n private addNative(scene: Scene3dManifest) {\n const map = this.map!;\n const source = this.sourceId();\n if (!map.getSource(source)) map.addSource(source, { type: \"vector\", url: this.withKey(scene.source) });\n const anchor = this.labelsAnchor();\n const p = this.options.idPrefix;\n if (scene.lod1) {\n const { position, ...lod1 } = scene.lod1;\n map.addLayer({ id: `${p}lod1`, type: \"fill-extrusion\", source, \"source-layer\": \"buildings2d\", ...lod1 } as never, this.beforeFor(position, anchor));\n this.native.push(`${p}lod1`);\n } else if (scene.fill3d) {\n // The Fill3DLayer reads tiles MapLibre only loads for a source a style layer uses.\n map.addLayer(\n { id: `${p}consumer`, type: \"fill\", source, \"source-layer\": \"buildings2d\", filter: [\"boolean\", false], paint: { \"fill-opacity\": 0 } },\n this.beforeFor(scene.fill3d.position, anchor),\n );\n this.native.push(`${p}consumer`);\n }\n }\n\n private loadCustom(scene: Scene3dManifest, generation: number) {\n this.loadLibrary().then(\n () => {\n if (generation === this.generation && this.scene === scene && !this.custom.length) this.addCustom(scene, generation);\n },\n (err) => console.error(\"Scene3dControl: could not load @maptoolkit/maplibre-3d-layers\", err),\n );\n }\n\n private addCustom(scene: Scene3dManifest, generation: number) {\n const map = this.map;\n const lib = this.lib;\n if (!map || !lib || generation !== this.generation || !this.styleReady()) return;\n const anchor = this.labelsAnchor();\n const p = this.options.idPrefix;\n const add = (layer: CustomLayerInterface, position: Scene3dPosition | undefined) => {\n map.addLayer(layer, this.beforeFor(position, anchor));\n this.custom.push(layer);\n };\n this.building = true;\n try {\n if (scene.fill3d) {\n const { position, ...fill3d } = scene.fill3d;\n add(new lib.Fill3DLayer({ id: `${p}fill3d`, source: this.sourceId(), \"source-layer\": \"buildings3d\", ...fill3d }), position);\n }\n const library = scene.models ?? {};\n for (const entry of scene.gltf ?? []) {\n const { id, position, models: ids, ...options } = entry;\n if (!map.getSource(options.source)) {\n this.warnOnce(`source-${options.source}`, `Scene3dControl: the style has no source \"${options.source}\", layer \"${id}\" left out`);\n continue;\n }\n const picked = ids ?? Object.keys(library);\n const models = Object.fromEntries(picked.filter((m) => library[m]).map((m) => [m, this.modelUrl(library[m])]));\n if (!Object.keys(models).length) continue;\n add(new lib.GltfLayer({ id: `${p}${id}`, models, ...options }), position);\n }\n } finally {\n this.building = false;\n }\n }\n\n private removeCustom() {\n const map = this.map;\n for (const layer of this.custom) {\n if (map?.getLayer(layer.id)) map.removeLayer(layer.id);\n // A replaced style never calls onRemove; without it the layer keeps listening to the map.\n else if (map) layer.onRemove?.(map, undefined as unknown as WebGL2RenderingContext);\n }\n this.custom = [];\n }\n\n /** Remove everything the control added; `restore` puts hidden style layers back. */\n private teardown(restore: boolean) {\n const map = this.map;\n this.stopWaiting?.();\n this.building = true;\n try {\n this.removeCustom();\n if (map) {\n for (const id of this.native) if (map.getLayer(id)) map.removeLayer(id);\n if (map.getSource(this.sourceId()) && this.styleReady()) map.removeSource(this.sourceId());\n if (restore && this.styleReady()) {\n for (const [id, visibility] of this.hidden) if (map.getLayer(id)) map.setLayoutProperty(id, \"visibility\", visibility);\n }\n }\n this.native = [];\n this.hidden.clear();\n this.scene = null;\n } finally {\n this.building = false;\n }\n }\n\n /**\n * Hide the style's own 3D buildings (`hideLayers`) only once the scene's buildings source has\n * loaded. Without a working API key it answers 403, and the style keeps its buildings.\n */\n private hideOnceBuildingsLoad(generation: number) {\n const map = this.map!;\n const id = this.sourceId();\n const onData = (e: MapSourceDataEvent) => {\n // removeSource fires a metadata event too; the source is gone by then.\n if (e.sourceId !== id || e.sourceDataType !== \"metadata\" || !map.getSource(id)) return;\n this.stopWaiting?.();\n if (generation === this.generation && this.styleReady()) this.hideStyleLayers();\n };\n map.on(\"sourcedata\", onData);\n this.stopWaiting = () => {\n map.off(\"sourcedata\", onData);\n this.stopWaiting = undefined;\n };\n }\n\n private hideStyleLayers() {\n const map = this.map!;\n for (const id of this.options.hideLayers) {\n if (!map.getLayer(id)) continue;\n this.hidden.set(id, (map.getLayoutProperty(id, \"visibility\") as \"visible\" | \"none\" | undefined) ?? \"visible\");\n map.setLayoutProperty(id, \"visibility\", \"none\");\n }\n }\n\n private withKey(url: string): string {\n if (!this.options.apiKey) return url;\n const u = new URL(url, document.baseURI);\n if (!u.searchParams.has(\"api_key\")) u.searchParams.set(\"api_key\", this.options.apiKey);\n return u.href;\n }\n\n private modelUrl(url: string): string {\n return new URL(url, this.options.modelBase ?? document.baseURI).href;\n }\n\n private showState() {\n this.button?.setAttribute(\"aria-pressed\", String(this.enabled));\n }\n\n private warnOnce(key: string, message: string) {\n if (this.warned.has(key)) return;\n this.warned.add(key);\n console.warn(message);\n }\n}\n"],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,77 @@
1
1
  {
2
2
  "name": "@maptoolkit/maplibre-scene3d-control",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "A MapLibre GL JS control plugin that adds the 3D scene of a Maptoolkit style: 3D buildings and glTF vegetation.",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/maptoolkit/maplibre-scene3d-control.git"
8
+ },
9
+ "homepage": "https://github.com/maptoolkit/maplibre-scene3d-control#readme",
10
+ "bugs": {
11
+ "url": "https://github.com/maptoolkit/maplibre-scene3d-control/issues"
12
+ },
13
+ "type": "module",
14
+ "module": "./dist/maplibre-scene3d-control.js",
15
+ "types": "./dist/index.d.ts",
16
+ "exports": {
17
+ ".": {
18
+ "types": "./dist/index.d.ts",
19
+ "import": "./dist/maplibre-scene3d-control.js"
20
+ },
21
+ "./style.css": "./dist/maplibre-scene3d-control.css"
22
+ },
23
+ "files": [
24
+ "dist"
25
+ ],
26
+ "publishConfig": {
27
+ "access": "public"
28
+ },
29
+ "sideEffects": [
30
+ "*.css"
31
+ ],
32
+ "scripts": {
33
+ "dev": "vite --config demo/vite.config.mts",
34
+ "build": "vite build",
35
+ "test": "vitest run",
36
+ "test:watch": "vitest",
37
+ "lint": "eslint .",
38
+ "format": "prettier --write .",
39
+ "typecheck": "tsc --noEmit",
40
+ "changeset": "changeset",
41
+ "version": "changeset version",
42
+ "release": "npm run build && changeset publish"
43
+ },
44
+ "peerDependencies": {
45
+ "@maptoolkit/maplibre-3d-layers": ">=0.5.1",
46
+ "maplibre-gl": ">=6.0.0"
47
+ },
48
+ "devDependencies": {
49
+ "@changesets/cli": "^3.0.3",
50
+ "@eslint/js": "^10.0.1",
51
+ "@maptoolkit/maplibre-3d-layers": "^0.5.1",
52
+ "@types/node": "^26.5.1",
53
+ "eslint": "^10.10.0",
54
+ "eslint-config-prettier": "^10.1.8",
55
+ "jsdom": "^30.0.1",
56
+ "maplibre-gl": "^6.9.1",
57
+ "prettier": "^3.9.6",
58
+ "three": "^0.185.1",
59
+ "typescript": "^6.0.3",
60
+ "typescript-eslint": "^8.70.0",
61
+ "vite": "^8.3.0",
62
+ "vite-plugin-dts": "^5.1.0",
63
+ "vitest": "^5.0.1"
64
+ },
65
+ "keywords": [
66
+ "maplibre",
67
+ "maplibre-gl",
68
+ "map",
69
+ "plugin",
70
+ "control",
71
+ "3d",
72
+ "buildings",
73
+ "gltf"
74
+ ],
75
+ "author": "",
76
+ "license": "BSD-3-Clause"
77
+ }