@sjvair/map-sdk 0.0.0-stage → 0.1.0-beta.10

package/dist/core/create-map.svelte.js

@@ -0,0 +1,591 @@
+import { untrack } from "svelte";
+import { SvelteMap } from "svelte/reactivity";
+import { createDefaultFormat } from "../data/format.js";
+import { defaultMessages } from "../data/messages.js";
+import { createDefaultMetadata } from "../data/metadata.js";
+import { applyPick, selectionKeys, toggleInSelection } from "../data/selection.js";
+import { BasemapState } from "./basemap.svelte.js";
+import { InteractionRouter } from "./interactions.svelte.js";
+import { PluginHost } from "./plugin-host.svelte.js";
+import { intersectsBounds, shapeAnchor } from "./shape-view.js";
+/** Monitor-map's start view. */
+const DEFAULT_VIEW = {
+    center: [-119.7987626619462, 36.76272050981146],
+    zoom: 7,
+    bearing: 0,
+    pitch: 0
+};
+/** One plugin's selection state. */
+class PluginSelection {
+    mode = $state("none");
+    selection = $state.raw(null);
+    onselectionchange;
+    pickWith = $state("click");
+    canSelect;
+}
+function copyView(view) {
+    return { ...view, center: [view.center[0], view.center[1]] };
+}
+function copySelection(sel) {
+    return sel && { kind: sel.kind, ids: [...sel.ids] };
+}
+/** 8 hex characters. `crypto.randomUUID` is missing on insecure origins (a dev server on a LAN IP). */
+function randomUid() {
+    const bytes = crypto.getRandomValues(new Uint8Array(4));
+    return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function sameSelection(a, b) {
+    if (!a || !b)
+        return a === b;
+    return (a.kind === b.kind && a.ids.length === b.ids.length && a.ids.every((id, i) => id === b.ids[i]));
+}
+const inRect = (p, b) => p[0] >= b.west && p[0] <= b.east && p[1] >= b.south && p[1] <= b.north;
+function prefersReducedMotion() {
+    return globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;
+}
+class MapContextImpl {
+    uid = randomUid();
+    config;
+    metadata;
+    messages;
+    format;
+    basemap;
+    #camera = $state.raw(DEFAULT_VIEW);
+    #bounds = $state.raw(null);
+    #attached = $state(false);
+    #ready = $state(false);
+    /** `markReady` came while plugin setups were queued; the queued run sets `ready`. */
+    #readyRequested = false;
+    #glState = $state.raw(null);
+    #focusedKey = $state(null);
+    #focusedPluginId = $state(null);
+    #focusedAnchor = $state.raw(null);
+    #pinned = $state.raw(null);
+    #notice = $state.raw(null);
+    #noticeCount = 0;
+    #cardEnabled = false;
+    #selections = new SvelteMap();
+    #featureClickHandlers = new Set();
+    #router = new InteractionRouter();
+    #host;
+    #gl = null;
+    #destroyed = false;
+    #listInset = 0;
+    #listInsetSide = "left";
+    /** An animated ease that `focusFeature` started is still running (cleared on `moveend`). */
+    #focusEasing = false;
+    #onMoveEnd = () => {
+        this.#focusEasing = false;
+    };
+    constructor(options) {
+        const initialView = copyView(options.config.initialView ?? DEFAULT_VIEW);
+        this.config = {
+            ...options.config,
+            initialView,
+            cooperativeGestures: options.config.cooperativeGestures ?? false
+        };
+        this.metadata = options.metadata ?? createDefaultMetadata();
+        this.messages = options.messages ?? defaultMessages;
+        this.format = options.format ?? createDefaultFormat();
+        this.basemap = new BasemapState(options.config.basemaps);
+        this.#camera = copyView(initialView);
+        this.#host = new PluginHost({
+            mapUid: this.uid,
+            providers: { metadata: this.metadata, messages: this.messages, format: this.format },
+            router: this.#router,
+            selectedKeys: (pluginId) => selectionKeys(this.getSelection(pluginId)),
+            onSettled: () => {
+                // A setup that added a plugin queued another run; that run settles it.
+                if (this.#host.pending)
+                    return;
+                if (this.#readyRequested && this.#gl)
+                    this.#ready = true;
+                this.#readyRequested = false;
+            }
+        });
+        this.#router.onPick((e) => this.#pick(e));
+        this.#router.onMiss(() => this.unpin());
+    }
+    get camera() {
+        return this.#camera;
+    }
+    get bounds() {
+        return this.#bounds;
+    }
+    get plugins() {
+        return this.#host.plugins;
+    }
+    get attached() {
+        return this.#attached;
+    }
+    get ready() {
+        return this.#ready;
+    }
+    get gl() {
+        return this.#glState;
+    }
+    markReady() {
+        if (!this.#gl)
+            return;
+        if (this.#host.pending)
+            this.#readyRequested = true;
+        else
+            this.#ready = true;
+    }
+    get focusedKey() {
+        return this.#focusedKey;
+    }
+    get focusedPluginId() {
+        return this.#focusedPluginId;
+    }
+    get focusedAnchor() {
+        return this.#focusedAnchor;
+    }
+    get hovered() {
+        return this.#router.hovered;
+    }
+    get pinned() {
+        return this.#pinned;
+    }
+    get notice() {
+        return this.#notice;
+    }
+    clearNotice() {
+        if (untrack(() => this.#notice) !== null)
+            this.#notice = null;
+    }
+    getPickWith(pluginId) {
+        return this.#selections.get(pluginId)?.pickWith ?? "click";
+    }
+    togglePick(pluginId, ref) {
+        if (this.#destroyed)
+            return;
+        this.#applyPick(pluginId, ref, { toggle: true });
+    }
+    unpin() {
+        if (untrack(() => this.#pinned) !== null)
+            this.#pinned = null;
+    }
+    setCardEnabled(on) {
+        this.#cardEnabled = on;
+        if (!on)
+            this.unpin();
+    }
+    addPlugin(plugin, options = {}) {
+        this.#assertAlive();
+        const previous = untrack(() => this.#selections.get(plugin.id));
+        const state = new PluginSelection();
+        // Untracked: addPlugin may be called from inside an effect (e.g. a host component's).
+        untrack(() => {
+            state.mode = options.selectionMode ?? previous?.mode ?? "none";
+            state.selection =
+                options.selection !== undefined
+                    ? copySelection(options.selection)
+                    : (previous?.selection ?? null);
+        });
+        state.onselectionchange = options.onselectionchange ?? previous?.onselectionchange;
+        untrack(() => {
+            state.pickWith = options.pickWith ?? previous?.pickWith ?? "click";
+        });
+        state.canSelect = options.canSelect ?? previous?.canSelect;
+        // Stored before the host adds it, so a setup that runs at once sees its selection.
+        this.#selections.set(plugin.id, state);
+        try {
+            this.#host.add(plugin, options.before);
+        }
+        catch (error) {
+            if (previous)
+                this.#selections.set(plugin.id, previous);
+            else
+                this.#selections.delete(plugin.id);
+            throw error;
+        }
+    }
+    movePlugin(id, options = {}) {
+        if (this.#destroyed)
+            return;
+        this.#host.move(id, options.before);
+    }
+    removePlugin(id) {
+        this.#host.remove(id);
+        this.#selections.delete(id);
+        if (untrack(() => this.#pinned)?.hit.pluginId === id)
+            this.unpin();
+    }
+    setSelection(pluginId, selection) {
+        if (this.#destroyed)
+            return;
+        this.#stateFor(pluginId).selection = copySelection(selection);
+    }
+    getSelection(pluginId) {
+        return this.#selections.get(pluginId)?.selection ?? null;
+    }
+    getSelectionMode(pluginId) {
+        return this.#selections.get(pluginId)?.mode ?? "none";
+    }
+    pickFromList(pluginId, refKey, additive) {
+        if (this.#destroyed)
+            return;
+        const found = untrack(() => this.#findItem(refKey, pluginId));
+        if (!found)
+            return;
+        const { item } = found;
+        // Where the row's tooltip pins: the focused anchor for the focused row, else a point of a
+        // shape in view (a point's own position for points and on-screen label points).
+        const focused = untrack(() => this.#focusedKey) === refKey &&
+            (untrack(() => this.#focusedPluginId) ?? pluginId) === pluginId;
+        const anchor = (focused && untrack(() => this.#focusedAnchor)) || this.anchorFor(item);
+        this.#emitClick(pluginId, item.ref, anchor);
+        if (item.selectable)
+            this.#applyPick(pluginId, item.ref, { additive, modifier: additive });
+    }
+    clearSelection(pluginId) {
+        if (this.#destroyed)
+            return;
+        const state = untrack(() => this.#selections.get(pluginId));
+        if (!state || !untrack(() => state.selection))
+            return;
+        state.selection = null;
+        state.onselectionchange?.(null);
+    }
+    setSelectionMode(pluginId, mode) {
+        if (this.#destroyed)
+            return;
+        this.#stateFor(pluginId).mode = mode;
+    }
+    on(event, handler) {
+        if (this.#destroyed)
+            return () => { };
+        this.#featureClickHandlers.add(handler);
+        return () => {
+            this.#featureClickHandlers.delete(handler);
+        };
+    }
+    featuresAt(point) {
+        return this.#router.hitsAt([point.x, point.y]);
+    }
+    featureForElement(element) {
+        const row = element.closest("[data-mapsdk-ref]");
+        if (!row || row.closest("[data-mapsdk-map]")?.getAttribute("data-mapsdk-map") !== this.uid) {
+            return null;
+        }
+        const refKey = row.getAttribute("data-mapsdk-ref") ?? "";
+        const pluginId = row.getAttribute("data-mapsdk-plugin") ?? undefined;
+        const found = untrack(() => this.#findItem(refKey, pluginId));
+        if (!found)
+            return null;
+        const { plugin, item } = found;
+        return { pluginId: plugin.id, ref: item.ref, refKey: item.refKey, name: item.name };
+    }
+    focusFeature(refKey, pluginId) {
+        if (this.#destroyed)
+            return;
+        this.#focusedKey = refKey;
+        this.#focusedPluginId = refKey === null ? null : (pluginId ?? null);
+        this.#focusedAnchor = null;
+        const gl = this.#gl;
+        if (!gl || refKey === null)
+            return;
+        const found = untrack(() => this.#findItem(refKey, pluginId));
+        if (!found)
+            return;
+        const { plugin, item } = found;
+        const place = this.#placeFor(item, gl);
+        this.#focusedAnchor = place.anchor;
+        if (this.#cardEnabled) {
+            this.#pinned = {
+                hit: { pluginId: plugin.id, ref: item.ref, refKey: item.refKey, name: item.name },
+                lngLat: place.anchor
+            };
+        }
+        if (!place.pan) {
+            // Stays where it is now: an earlier focus's ease that is still running stops here.
+            // With nothing running, no move at all.
+            if (this.#focusEasing) {
+                const { lng, lat } = gl.getCenter();
+                gl.easeTo({ center: [lng, lat], duration: 0 });
+                this.#focusEasing = false;
+            }
+            return;
+        }
+        const reduce = prefersReducedMotion();
+        gl.easeTo({
+            center: place.anchor,
+            // The middle of the part the panel leaves clear. An offset, not padding: MapLibre keeps
+            // padding for later moves (zooms, the reported center), an offset applies to this one.
+            ...(this.#listInset > 0 && { offset: [this.#listOffsetX(), 0] }),
+            ...(reduce && { duration: 0 })
+        });
+        // Set after the call: stopping an earlier move fires its `moveend` inside `easeTo`.
+        this.#focusEasing = !reduce;
+    }
+    anchorFor(item) {
+        const gl = this.#gl;
+        if (!gl || !item.geometry)
+            return item.lngLat;
+        const { live, clear, liveCenter, clearCenter } = this.#views(gl);
+        if (inRect(item.lngLat, live) || !intersectsBounds(item, live))
+            return item.lngLat;
+        return (shapeAnchor(item.geometry, clear, clearCenter) ??
+            shapeAnchor(item.geometry, live, liveCenter) ??
+            item.lngLat);
+    }
+    /** The live view, and the part of it the list panel leaves clear, with their centers. */
+    #views(gl) {
+        const b = gl.getBounds();
+        const live = {
+            west: b.getWest(),
+            south: b.getSouth(),
+            east: b.getEast(),
+            north: b.getNorth()
+        };
+        const center = gl.getCenter();
+        const width = untrack(() => gl.getCanvas().clientWidth) || 0;
+        const share = width > 0 ? Math.min(Math.max(this.#listInset / width, 0), 0.99) : 0;
+        const cut = share * (live.east - live.west);
+        const clear = this.#listInsetSide === "left"
+            ? { ...live, west: live.west + cut }
+            : { ...live, east: live.east - cut };
+        return {
+            live,
+            clear,
+            liveCenter: [center.lng, center.lat],
+            clearCenter: [(clear.west + clear.east) / 2, center.lat]
+        };
+    }
+    /**
+     * Where focus puts `item`: `pan: false` keeps the camera (a shape in view whose `lngLat` is
+     * off-screen, with a point in the clear part); otherwise ease to center `anchor`.
+     */
+    #placeFor(item, gl) {
+        const { geometry, lngLat } = item;
+        if (!geometry)
+            return { anchor: lngLat, pan: true };
+        const { live, clear, liveCenter, clearCenter } = this.#views(gl);
+        if (inRect(lngLat, live))
+            return { anchor: lngLat, pan: true };
+        if (intersectsBounds(item, live)) {
+            const inClear = shapeAnchor(geometry, clear, clearCenter);
+            if (inClear)
+                return { anchor: inClear, pan: false };
+            const inLive = shapeAnchor(geometry, live, liveCenter);
+            if (inLive)
+                return { anchor: inLive, pan: true };
+        }
+        const settled = untrack(() => this.#bounds);
+        if (settled && intersectsBounds(item, settled)) {
+            const middle = [
+                (settled.west + settled.east) / 2,
+                (settled.south + settled.north) / 2
+            ];
+            const inSettled = shapeAnchor(geometry, settled, middle);
+            if (inSettled)
+                return { anchor: inSettled, pan: true };
+        }
+        return { anchor: lngLat, pan: true };
+    }
+    #cameraOptions(target, gl) {
+        const zoom = target.zoom ??
+            (target.minZoom === undefined ? undefined : Math.max(gl.getZoom(), target.minZoom));
+        return {
+            center: target.center,
+            ...(zoom !== undefined && { zoom }),
+            ...(prefersReducedMotion() && { duration: 0 })
+        };
+    }
+    easeTo(target) {
+        const gl = this.#destroyed ? null : this.#gl;
+        if (gl)
+            gl.easeTo(this.#cameraOptions(target, gl));
+    }
+    flyTo(target) {
+        const gl = this.#destroyed ? null : this.#gl;
+        if (gl)
+            gl.flyTo(this.#cameraOptions(target, gl));
+    }
+    fitBounds(bounds, options = {}) {
+        const gl = this.#destroyed ? null : this.#gl;
+        if (!gl)
+            return;
+        gl.fitBounds([
+            [bounds.west, bounds.south],
+            [bounds.east, bounds.north]
+        ], {
+            ...(options.padding !== undefined && { padding: options.padding }),
+            ...(options.maxZoom !== undefined && { maxZoom: options.maxZoom }),
+            ...(prefersReducedMotion() && { duration: 0 })
+        });
+    }
+    attach(gl) {
+        this.#assertAlive();
+        if (this.#gl === gl)
+            return;
+        if (this.#gl)
+            this.detach();
+        this.#gl = gl;
+        this.#glState = gl;
+        this.#host.attach(gl);
+        this.#router.attach(gl);
+        gl.on("moveend", this.#onMoveEnd);
+        this.basemap.attach(gl, 
+        // Called from style.load: the style is loaded, though its tiles may not be.
+        () => this.#host.restyle(true), () => {
+            this.#ready = false;
+            this.#readyRequested = false;
+            this.#host.suspend();
+        });
+        this.#attached = true;
+    }
+    detach() {
+        if (!this.#gl)
+            return;
+        this.#gl.off("moveend", this.#onMoveEnd);
+        this.#focusEasing = false;
+        this.unpin();
+        this.clearNotice();
+        this.#router.detach();
+        this.basemap.detach();
+        this.#host.detach();
+        this.#gl = null;
+        this.#glState = null;
+        this.#attached = false;
+        this.#ready = false;
+        this.#readyRequested = false;
+    }
+    themeChanged() {
+        if (this.#gl)
+            this.#host.restyle();
+    }
+    /** Half the panel's width, toward the part of the map it leaves clear. */
+    #listOffsetX() {
+        return ((this.#listInsetSide === "left" ? 1 : -1) * this.#listInset) / 2;
+    }
+    setListInset(width, side = "left") {
+        this.#listInset = Math.max(0, width);
+        this.#listInsetSide = side;
+    }
+    updateView(camera, bounds) {
+        this.#camera = copyView(camera);
+        this.#bounds = { ...bounds };
+    }
+    destroy() {
+        if (this.#destroyed)
+            return;
+        this.detach();
+        for (const plugin of untrack(() => this.plugins))
+            this.#host.remove(plugin.id);
+        this.#selections.clear();
+        this.#featureClickHandlers.clear();
+        this.#focusedKey = null;
+        this.#focusedPluginId = null;
+        this.#focusedAnchor = null;
+        this.#destroyed = true;
+    }
+    /** A click on a feature: report it, then apply it to the top hit's plugin's selection. */
+    #pick(e) {
+        if (this.#destroyed)
+            return;
+        const [hit] = e.hits;
+        const { pluginId, ref } = hit;
+        // A box-zoom Shift-click only counts for a plugin that asked for modifier picks.
+        if (e.boxZoom && untrack(() => this.#selections.get(pluginId)?.pickWith) !== "modifier") {
+            return;
+        }
+        this.#emitClick(pluginId, ref, e.lngLat);
+        this.#applyPick(pluginId, ref, { additive: e.additive, modifier: e.modifier });
+        if (!this.#cardEnabled || this.#destroyed)
+            return;
+        // A feature with no hover card (e.g. a smoke plume) gets no pinned card either.
+        const plugin = untrack(() => this.plugins).find((p) => p.id === pluginId);
+        if (!plugin || plugin.hoverable === false)
+            this.unpin();
+        else
+            this.#pinned = { hit, lngLat: e.lngLat };
+    }
+    #emitClick(pluginId, ref, lngLat) {
+        for (const handler of [...this.#featureClickHandlers]) {
+            try {
+                handler({ pluginId, ref, lngLat });
+            }
+            catch (error) {
+                console.error("map-sdk: a featureclick handler failed", error);
+            }
+        }
+    }
+    /** The one place a user's pick (map click or list key) changes a plugin's selection. */
+    /**
+     * The one place a user's pick (map click, list key, or the card's toggle) changes a plugin's
+     * selection: the plugin's `pickWith` rule, then its `canSelect`.
+     */
+    #applyPick(pluginId, ref, gesture) {
+        // A featureclick handler may have removed the plugin.
+        const state = untrack(() => this.#selections.get(pluginId));
+        if (!state)
+            return;
+        const current = untrack(() => state.selection);
+        const mode = untrack(() => state.mode);
+        let next;
+        if (gesture.toggle)
+            next = toggleInSelection(current, ref, mode);
+        else if (untrack(() => state.pickWith) === "modifier") {
+            // A plain click or tap only pins the card.
+            next = gesture.modifier ? toggleInSelection(current, ref, mode) : current;
+        }
+        else
+            next = applyPick(current, ref, mode, { additive: gesture.additive ?? false });
+        if (sameSelection(current, next)) {
+            this.clearNotice();
+            return;
+        }
+        if (state.canSelect) {
+            let verdict;
+            try {
+                verdict = state.canSelect(copySelection(next), ref);
+            }
+            catch (error) {
+                console.error("map-sdk: canSelect failed", error);
+                return;
+            }
+            if (verdict !== true) {
+                // An empty (or, from untyped JS, false) verdict refuses quietly.
+                if (typeof verdict === "string" && verdict !== "") {
+                    this.#notice = { message: verdict, id: ++this.#noticeCount };
+                }
+                return;
+            }
+        }
+        this.clearNotice();
+        state.selection = next;
+        state.onselectionchange?.(copySelection(next));
+    }
+    /**
+     * A listed item and its plugin: in `pluginId` when given (`null` if that plugin doesn't list
+     * it), else the first plugin listing `refKey`. Reads `features()`, so call it untracked.
+     */
+    #findItem(refKey, pluginId) {
+        for (const plugin of this.plugins) {
+            if (pluginId !== undefined && plugin.id !== pluginId)
+                continue;
+            const item = plugin.features?.().find((f) => f.refKey === refKey);
+            if (item)
+                return { plugin, item };
+        }
+        return null;
+    }
+    #stateFor(pluginId) {
+        let state = untrack(() => this.#selections.get(pluginId));
+        if (!state) {
+            state = new PluginSelection();
+            this.#selections.set(pluginId, state);
+        }
+        return state;
+    }
+    #assertAlive() {
+        if (this.#destroyed)
+            throw new Error("map destroyed");
+    }
+}
+/** Creates a map's state and services. `MapView` attaches a GL map to it. */
+export function createMap(options) {
+    return new MapContextImpl(options);
+}

package/dist/core/gl.d.ts

@@ -0,0 +1,97 @@
+import type { CustomLayerInterface, LayerSpecification, SourceSpecification } from "@maptiler/sdk";
+import type { Geometry } from "geojson";
+/**
+ * The subset of MapLibre's `Map` the core and plugins use. Types only, so nothing in core/
+ * pulls the map engine at runtime, and tests can pass an in-memory fake.
+ */
+export interface GlMapLike {
+    addSource(id: string, source: SourceSpecification): void;
+    removeSource(id: string): void;
+    getSource(id: string): unknown;
+    addLayer(layer: LayerSpecification | CustomLayerInterface, beforeId?: string): void;
+    /** Moves a layer below `beforeId`, or to the top without it. */
+    moveLayer(id: string, beforeId?: string): void;
+    removeLayer(id: string): void;
+    getLayer(id: string): unknown;
+    addImage(id: string, image: HTMLImageElement | ImageData, options?: {
+        pixelRatio?: number;
+    }): void;
+    hasImage(id: string): boolean;
+    removeImage(id: string): void;
+    setFeatureState(target: {
+        source: string;
+        id: string | number;
+    }, state: Record<string, unknown>): void;
+    setLayoutProperty(layerId: string, name: string, value: unknown): void;
+    removeFeatureState(target: {
+        source: string;
+        id?: string | number;
+    }, key?: string): void;
+    queryRenderedFeatures(point: [number, number] | [[number, number], [number, number]], options?: {
+        layers?: string[];
+    }): Array<{
+        layer: {
+            id: string;
+        };
+        source: string;
+        id?: string | number;
+        properties: Record<string, unknown>;
+        geometry: Geometry;
+    }>;
+    isStyleLoaded(): boolean | void;
+    setStyle(style: unknown, options?: {
+        diff?: boolean;
+    }): void;
+    on(type: string, listener: (e: any) => void): void;
+    on(type: string, layerId: string, listener: (e: any) => void): void;
+    off(type: string, listener: (e: any) => void): void;
+    off(type: string, layerId: string, listener: (e: any) => void): void;
+    getBounds(): {
+        getWest(): number;
+        getSouth(): number;
+        getEast(): number;
+        getNorth(): number;
+    };
+    getCenter(): {
+        lng: number;
+        lat: number;
+    };
+    getZoom(): number;
+    getBearing(): number;
+    getPitch(): number;
+    easeTo(options: {
+        center?: [number, number];
+        zoom?: number;
+        duration?: number;
+        /** Where `center` ends up, in pixels from the container's center (positive x is right). */
+        offset?: [number, number];
+    }): void;
+    flyTo(options: {
+        center?: [number, number];
+        zoom?: number;
+        duration?: number;
+    }): void;
+    fitBounds(bounds: [[number, number], [number, number]], options?: {
+        padding?: number;
+        maxZoom?: number;
+        duration?: number;
+    }): void;
+    jumpTo(options: {
+        center?: [number, number];
+        zoom?: number;
+        bearing?: number;
+        pitch?: number;
+    }): void;
+    /** Canvas pixel for a position. */
+    project(lngLat: [number, number]): {
+        x: number;
+        y: number;
+    };
+    /** Position at a canvas pixel. */
+    unproject(point: [number, number]): {
+        lng: number;
+        lat: number;
+    };
+    getCanvas(): HTMLCanvasElement;
+    remove(): void;
+}

package/dist/core/gl.js

@@ -0,0 +1 @@
+export {};