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

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

@@ -0,0 +1,376 @@
+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 } from "../data/selection.js";
+import { BasemapState } from "./basemap.svelte.js";
+import { InteractionRouter } from "./interactions.svelte.js";
+import { PluginHost } from "./plugin-host.svelte.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;
+}
+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]));
+}
+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);
+    #glState = $state.raw(null);
+    #focusedKey = $state(null);
+    #focusedPluginId = $state(null);
+    #selections = new SvelteMap();
+    #featureClickHandlers = new Set();
+    #router = new InteractionRouter();
+    #host;
+    #gl = null;
+    #destroyed = false;
+    #listInset = 0;
+    #listInsetSide = "left";
+    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))
+        });
+        this.#router.onPick((e) => this.#pick(e));
+    }
+    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)
+            this.#ready = true;
+    }
+    get focusedKey() {
+        return this.#focusedKey;
+    }
+    get focusedPluginId() {
+        return this.#focusedPluginId;
+    }
+    get hovered() {
+        return this.#router.hovered;
+    }
+    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;
+        // 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);
+    }
+    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;
+        this.#emitClick(pluginId, found.item.ref, found.item.lngLat);
+        if (found.item.selectable)
+            this.#applyPick(pluginId, found.item.ref, 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);
+        const gl = this.#gl;
+        if (!gl || refKey === null)
+            return;
+        const found = untrack(() => this.#findItem(refKey, pluginId));
+        if (!found)
+            return;
+        gl.easeTo({
+            center: found.item.lngLat,
+            // 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] }),
+            ...(prefersReducedMotion() && { duration: 0 })
+        });
+    }
+    #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);
+        this.basemap.attach(gl, () => this.#host.restyle(), () => {
+            this.#ready = false;
+            this.#host.suspend();
+        });
+        this.#attached = true;
+    }
+    detach() {
+        if (!this.#gl)
+            return;
+        this.#router.detach();
+        this.basemap.detach();
+        this.#host.detach();
+        this.#gl = null;
+        this.#glState = null;
+        this.#attached = false;
+        this.#ready = 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.#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 [{ pluginId, ref }] = e.hits;
+        this.#emitClick(pluginId, ref, e.lngLat);
+        this.#applyPick(pluginId, ref, e.additive);
+    }
+    #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. */
+    #applyPick(pluginId, ref, additive) {
+        // A featureclick handler may have removed the plugin.
+        const state = untrack(() => this.#selections.get(pluginId));
+        if (!state)
+            return;
+        const current = untrack(() => state.selection);
+        const next = applyPick(current, ref, untrack(() => state.mode), { additive });
+        if (sameSelection(current, next))
+            return;
+        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,92 @@
+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;
+    };
+    getCanvas(): HTMLCanvasElement;
+    remove(): void;
+}

package/dist/core/gl.js

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

package/dist/core/interactions.svelte.d.ts

@@ -0,0 +1,42 @@
+import type { GlMapLike } from "./gl.js";
+import type { BlockingClick, ClickEvent, FeatureHit } from "./plugin.js";
+export interface Hovered {
+    hit: FeatureHit;
+    lngLat: [number, number];
+}
+/**
+ * Routes click and hover events on plugin layers to feature hits. One per map.
+ *
+ * Listens on the map itself (`click`, `mousemove`, `mouseout`) and queries only the registered
+ * layers, so registrations can come and go without re-binding listeners. Layers nobody registered
+ * are never hit. A blocking layer (e.g. a cluster bubble, which zooms instead) is never hit either,
+ * but when it is topmost at a point nothing beneath it is hit or hovered.
+ */
+export declare class InteractionRouter {
+    #private;
+    /** The top hit under the pointer and where it is. Reactive, for the tooltip. */
+    get hovered(): Hovered | null;
+    /** Records the layers whose features `toHit` turns into hits. Returns an unregister function. */
+    register(pluginId: string, layerIds: string[], toHit: (props: Record<string, unknown>) => FeatureHit | null, priority?: number): () => void;
+    /**
+     * Records layers that hide what is beneath them: when one is topmost at a point, clicks pick
+     * nothing (calling `onClick` with that feature instead) and the hover is `toHover`'s hit for
+     * it (or nothing). `toHover` must have no side effects: lookups call it too. Returns an
+     * unregister function.
+     */
+    registerBlocking(pluginId: string, layerIds: string[], toHover?: (props: Record<string, unknown>) => FeatureHit | null, onClick?: (feature: BlockingClick) => void, priority?: number): () => void;
+    /** Listens to `gl` from now on. */
+    attach(gl: GlMapLike): void;
+    /** Stops listening and clears `hovered`. */
+    detach(): void;
+    /**
+     * Hits under a canvas point, topmost first, de-duplicated by `refKey`. `[]` when detached or
+     * when a blocking layer is topmost.
+     */
+    hitsAt(point: [number, number]): FeatureHit[];
+    /**
+     * Called for every click with at least one hit. `additive` is true for a shift, ⌘, or Ctrl
+     * click, or a touch tap; selection rules decide what it means for the plugin's mode.
+     */
+    onPick(handler: (e: ClickEvent) => void): () => void;
+}