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

package/dist/core/interactions.svelte.js

@@ -0,0 +1,213 @@
+/**
+ * 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 class InteractionRouter {
+    // Bookkeeping only; nothing reads these reactively.
+    /* eslint-disable svelte/prefer-svelte-reactivity */
+    #registrations = new Set();
+    #pickHandlers = new Set();
+    /* eslint-enable svelte/prefer-svelte-reactivity */
+    #gl = null;
+    #canvas = null;
+    /**
+     * The `pointerType` of the latest `pointerdown` on the canvas, for clicks whose original event
+     * has none (Safari before 17 dispatches `click` as a `MouseEvent`). Cleared after each click.
+     */
+    #lastPointerType = null;
+    #hovered = $state.raw(null);
+    /** Whether the canvas cursor is set to a pointer. */
+    #pointer = false;
+    /** The top hit under the pointer and where it is. Reactive, for the tooltip. */
+    get hovered() {
+        return this.#hovered;
+    }
+    /** Records the layers whose features `toHit` turns into hits. Returns an unregister function. */
+    register(pluginId, layerIds, toHit, priority = 0) {
+        return this.#add({ pluginId, layerIds: [...layerIds], toHit, blocking: false, priority });
+    }
+    /**
+     * 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, layerIds, toHover, onClick, priority = 0) {
+        return this.#add({
+            pluginId,
+            layerIds: [...layerIds],
+            toHit: toHover ?? (() => null),
+            blocking: true,
+            onClick,
+            priority
+        });
+    }
+    #add(registration) {
+        const { pluginId } = registration;
+        this.#registrations.add(registration);
+        return () => {
+            if (!this.#registrations.delete(registration))
+                return;
+            if (this.#hovered?.hit.pluginId === pluginId)
+                this.#hovered = null;
+            // The pointer may have been over this plugin; the next move sets it again.
+            this.#setPointer(false);
+        };
+    }
+    /** Listens to `gl` from now on. */
+    attach(gl) {
+        if (this.#gl === gl)
+            return;
+        this.detach();
+        this.#gl = gl;
+        gl.on("click", this.#onClick);
+        gl.on("mousemove", this.#onMove);
+        gl.on("mouseout", this.#onOut);
+        this.#canvas = gl.getCanvas();
+        this.#canvas.addEventListener("pointerdown", this.#onPointerDown);
+    }
+    /** Stops listening and clears `hovered`. */
+    detach() {
+        const gl = this.#gl;
+        if (!gl)
+            return;
+        gl.off("click", this.#onClick);
+        gl.off("mousemove", this.#onMove);
+        gl.off("mouseout", this.#onOut);
+        this.#canvas?.removeEventListener("pointerdown", this.#onPointerDown);
+        this.#setPointer(false);
+        this.#canvas = null;
+        this.#lastPointerType = null;
+        this.#gl = null;
+        this.#hovered = null;
+    }
+    /**
+     * Hits under a canvas point, topmost first, de-duplicated by `refKey`. `[]` when detached or
+     * when a blocking layer is topmost.
+     */
+    hitsAt(point) {
+        const found = this.#lookup(point);
+        return found.blocked ? [] : found.hits;
+    }
+    #lookup(point) {
+        const none = { hits: [], hover: null, blocked: false, blocker: null, blockedBy: null };
+        const gl = this.#gl;
+        if (!gl)
+            return none;
+        // Locals for one lookup; nothing reads them reactively.
+        /* eslint-disable svelte/prefer-svelte-reactivity */
+        const byLayer = new Map();
+        for (const registration of this.#registrations) {
+            for (const id of registration.layerIds) {
+                // MapLibre errors on querying a missing layer (e.g. mid basemap change).
+                if (!byLayer.has(id) && gl.getLayer(id))
+                    byLayer.set(id, registration);
+            }
+        }
+        if (byLayer.size === 0)
+            return none;
+        const hits = [];
+        let hover = null;
+        let hoverPriority = -Infinity;
+        const seen = new Set();
+        /* eslint-enable svelte/prefer-svelte-reactivity */
+        const features = gl.queryRenderedFeatures(point, { layers: [...byLayer.keys()] });
+        const top = features[0] && byLayer.get(features[0].layer.id);
+        if (top?.blocking) {
+            const properties = features[0].properties ?? {};
+            const hit = top.toHit(properties);
+            return {
+                hits: [],
+                hover: null,
+                blocked: true,
+                blocker: hit && { ...hit, pluginId: top.pluginId },
+                blockedBy: { registration: top, feature: { properties, geometry: features[0].geometry } }
+            };
+        }
+        for (const feature of features) {
+            const registration = byLayer.get(feature.layer.id);
+            if (!registration || registration.blocking)
+                continue;
+            const hit = registration.toHit(feature.properties ?? {});
+            if (!hit || seen.has(hit.refKey))
+                continue;
+            seen.add(hit.refKey);
+            const withPlugin = { ...hit, pluginId: registration.pluginId };
+            hits.push(withPlugin);
+            // Strictly greater, so a tie keeps the topmost.
+            if (registration.priority > hoverPriority) {
+                hover = withPlugin;
+                hoverPriority = registration.priority;
+            }
+        }
+        return { hits, hover, blocked: false, blocker: null, blockedBy: null };
+    }
+    /**
+     * 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) {
+        this.#pickHandlers.add(handler);
+        return () => {
+            this.#pickHandlers.delete(handler);
+        };
+    }
+    #onPointerDown = (e) => {
+        this.#lastPointerType = e.pointerType || null;
+    };
+    #onClick = (e) => {
+        const recorded = this.#lastPointerType;
+        this.#lastPointerType = null;
+        const found = this.#lookup([e.point.x, e.point.y]);
+        if (found.blockedBy) {
+            const { registration, feature } = found.blockedBy;
+            try {
+                registration.onClick?.(feature);
+            }
+            catch (error) {
+                console.error("map-sdk: a blocking layer's click handler failed", error);
+            }
+            return;
+        }
+        const { hits } = found;
+        if (hits.length === 0)
+            return;
+        const o = e.originalEvent;
+        const pointerType = o?.pointerType || recorded;
+        const event = {
+            hits,
+            additive: Boolean(o?.shiftKey || o?.metaKey || o?.ctrlKey || pointerType === "touch"),
+            lngLat: [e.lngLat.lng, e.lngLat.lat]
+        };
+        for (const handler of [...this.#pickHandlers]) {
+            try {
+                handler(event);
+            }
+            catch (error) {
+                console.error("map-sdk: a pick handler failed", error);
+            }
+        }
+    };
+    #onMove = (e) => {
+        const found = this.#lookup([e.point.x, e.point.y]);
+        const hit = found.blocked ? found.blocker : found.hover;
+        this.#hovered = hit ? { hit, lngLat: [e.lngLat.lng, e.lngLat.lat] } : null;
+        this.#setPointer(found.blocked || hit !== null);
+    };
+    #onOut = () => {
+        this.#hovered = null;
+        this.#setPointer(false);
+    };
+    /** Sets the canvas cursor only when it changes, so the engine's own cursors are left alone. */
+    #setPointer(on) {
+        if (on === this.#pointer)
+            return;
+        this.#pointer = on;
+        if (this.#canvas)
+            this.#canvas.style.cursor = on ? "pointer" : "";
+    }
+}

package/dist/core/plugin-host.svelte.d.ts

@@ -0,0 +1,46 @@
+import type { GlMapLike } from "./gl.js";
+import type { InteractionRouter } from "./interactions.svelte.js";
+import type { MapPlugin, Providers } from "./plugin.js";
+export interface PluginHostOptions {
+    mapUid: string;
+    providers: Providers;
+    router: InteractionRouter;
+    /** Reactive: read inside a plugin's effects. */
+    selectedKeys(pluginId: string): ReadonlySet<string>;
+}
+/**
+ * Runs plugins against a GL map. Plugins are set up only when the map's style is loaded, and
+ * everything they add through their `PluginContext` is removed on teardown, whatever their own
+ * teardown does. The plugin list outlives any one GL map.
+ *
+ * Plugins draw in list order, later on top: each plugin's layers stay together, below the first
+ * layer of the next plugin in the list that has any.
+ */
+export declare class PluginHost {
+    #private;
+    constructor(opts: PluginHostOptions);
+    /** In draw order, bottom first. Reactive. */
+    get plugins(): readonly MapPlugin[];
+    /**
+     * Adds `plugin` on top, or just below the plugin `before` names. Throws when the same plugin
+     * object is set up on another map at the moment (one plugin object per map).
+     */
+    add(plugin: MapPlugin, before?: string): void;
+    /**
+     * Moves a plugin to the top, or just below the plugin `before` names, with its layers. Does
+     * nothing for an unknown `id` or when `before` is `id`.
+     */
+    move(id: string, before?: string): void;
+    remove(id: string): void;
+    /** Uses `gl` from now on, setting up every plugin once its style is loaded. */
+    attach(gl: GlMapLike): void;
+    /**
+     * Tears every plugin down and stops waiting for a style, before the map's style is replaced:
+     * nothing may touch a style on its way out. `restyle` sets them up again.
+     */
+    suspend(): void;
+    /** Tears down and sets up every plugin again (after a basemap change), once the style loads. */
+    restyle(): void;
+    /** Tears down every plugin. The gl is not touched after this returns. */
+    detach(): void;
+}

package/dist/core/plugin-host.svelte.js

@@ -0,0 +1,366 @@
+import { untrack } from "svelte";
+/** Setup runs on whichever of these fires first. */
+const STYLE_READY_EVENTS = ["style.load", "idle"];
+/**
+ * Marks a plugin object with the host it is set up on, while it is. A plugin object keeps
+ * per-map state (its source and layer ids, its features), so it belongs to one map at a time.
+ * A property on the plugin, not a registry: nothing here is shared between maps.
+ */
+const OWNER = Symbol("map-sdk plugin host");
+function ownedElsewhere(plugin, host) {
+    const owner = plugin[OWNER];
+    return owner !== undefined && owner !== host;
+}
+function ownershipError(plugin) {
+    return new Error(`map-sdk: plugin "${plugin.id}" is already set up on another map; create one plugin per map`);
+}
+/**
+ * Runs plugins against a GL map. Plugins are set up only when the map's style is loaded, and
+ * everything they add through their `PluginContext` is removed on teardown, whatever their own
+ * teardown does. The plugin list outlives any one GL map.
+ *
+ * Plugins draw in list order, later on top: each plugin's layers stay together, below the first
+ * layer of the next plugin in the list that has any.
+ */
+export class PluginHost {
+    #opts;
+    #plugins = $state.raw([]);
+    // Bookkeeping only; nothing reads it reactively.
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    #running = new Map();
+    #gl = null;
+    /** True once the current gl's style has loaded and plugins are set up on it. */
+    #live = false;
+    /**
+     * The pending one-shot listener on `#gl` for `style.load` and `idle`, if waiting. `idle` covers
+     * a style that already loaded while `isStyleLoaded()` is false because sources are loading.
+     */
+    #onStyleLoad = null;
+    constructor(opts) {
+        this.#opts = opts;
+    }
+    /** In draw order, bottom first. Reactive. */
+    get plugins() {
+        return this.#plugins;
+    }
+    /**
+     * The host's own reads are untracked, so calling `add`, `attach`, etc. from inside an effect
+     * doesn't make that effect depend on the plugin list.
+     */
+    get #list() {
+        return untrack(() => this.#plugins);
+    }
+    /**
+     * Adds `plugin` on top, or just below the plugin `before` names. Throws when the same plugin
+     * object is set up on another map at the moment (one plugin object per map).
+     */
+    add(plugin, before) {
+        if (this.#list.some((p) => p.id === plugin.id)) {
+            throw new Error(`map-sdk: a plugin with id "${plugin.id}" is already added`);
+        }
+        if (ownedElsewhere(plugin, this))
+            throw ownershipError(plugin);
+        this.#plugins = this.#inserted(this.#list, plugin, before);
+        if (this.#live)
+            this.#setup(plugin);
+    }
+    /**
+     * Moves a plugin to the top, or just below the plugin `before` names, with its layers. Does
+     * nothing for an unknown `id` or when `before` is `id`.
+     */
+    move(id, before) {
+        const plugin = this.#list.find((p) => p.id === id);
+        if (!plugin || before === id)
+            return;
+        this.#plugins = this.#inserted(this.#list.filter((p) => p !== plugin), plugin, before);
+        const running = this.#running.get(id);
+        if (!running || running.gl !== this.#gl)
+            return;
+        const { gl } = running;
+        const beforeId = this.#layerAbove(id);
+        for (const layerId of running.layers) {
+            try {
+                if (gl.getLayer(layerId))
+                    gl.moveLayer(layerId, beforeId);
+            }
+            catch (error) {
+                console.error(`map-sdk: plugin "${id}" moving layer ${layerId} failed`, error);
+            }
+        }
+    }
+    /** `list` with `plugin` inserted before `before` (at the end without it). */
+    #inserted(list, plugin, before) {
+        if (before === undefined)
+            return [...list, plugin];
+        const at = list.findIndex((p) => p.id === before);
+        if (at < 0)
+            throw new Error(`map-sdk: no plugin with id "${before}"`);
+        return [...list.slice(0, at), plugin, ...list.slice(at)];
+    }
+    /**
+     * The bottom layer of the plugins drawn above `pluginId` on the current gl: where its layers
+     * go. `undefined` (the top) when none above has a layer.
+     */
+    #layerAbove(pluginId) {
+        const gl = this.#gl;
+        if (!gl)
+            return undefined;
+        const list = this.#list;
+        for (const plugin of list.slice(list.findIndex((p) => p.id === pluginId) + 1)) {
+            const running = this.#running.get(plugin.id);
+            if (running?.gl !== gl)
+                continue;
+            const layerId = running.layers.find((l) => gl.getLayer(l));
+            if (layerId !== undefined)
+                return layerId;
+        }
+        return undefined;
+    }
+    remove(id) {
+        if (!this.#list.some((p) => p.id === id))
+            return;
+        this.#teardown(id);
+        this.#plugins = this.#list.filter((p) => p.id !== id);
+    }
+    /** Uses `gl` from now on, setting up every plugin once its style is loaded. */
+    attach(gl) {
+        if (this.#gl === gl)
+            return;
+        if (this.#gl)
+            this.detach();
+        this.#gl = gl;
+        this.#whenStyleLoaded();
+    }
+    /**
+     * Tears every plugin down and stops waiting for a style, before the map's style is replaced:
+     * nothing may touch a style on its way out. `restyle` sets them up again.
+     */
+    suspend() {
+        if (!this.#gl)
+            return;
+        this.#cancelStyleWait();
+        this.#teardownAll();
+    }
+    /** Tears down and sets up every plugin again (after a basemap change), once the style loads. */
+    restyle() {
+        if (!this.#gl)
+            return;
+        this.#teardownAll();
+        this.#whenStyleLoaded();
+    }
+    /** Tears down every plugin. The gl is not touched after this returns. */
+    detach() {
+        const gl = this.#gl;
+        if (!gl)
+            return;
+        this.#cancelStyleWait();
+        this.#teardownAll();
+        this.#gl = null;
+    }
+    #whenStyleLoaded() {
+        const gl = this.#gl;
+        this.#cancelStyleWait();
+        if (gl.isStyleLoaded()) {
+            this.#setupAll();
+            return;
+        }
+        const onStyleLoad = () => {
+            // Stale if the host was detached, re-attached, or restyled since.
+            if (this.#onStyleLoad !== onStyleLoad || this.#gl !== gl)
+                return;
+            this.#cancelStyleWait();
+            this.#setupAll();
+        };
+        this.#onStyleLoad = onStyleLoad;
+        for (const type of STYLE_READY_EVENTS)
+            gl.on(type, onStyleLoad);
+    }
+    #cancelStyleWait() {
+        const listener = this.#onStyleLoad;
+        if (listener && this.#gl) {
+            for (const type of STYLE_READY_EVENTS)
+                this.#gl.off(type, listener);
+        }
+        this.#onStyleLoad = null;
+    }
+    #setupAll() {
+        const gl = this.#gl;
+        this.#live = true;
+        for (const plugin of this.#list) {
+            // A plugin's setup may add, remove, or detach; follow the host's current state.
+            if (this.#gl !== gl || !this.#live)
+                return;
+            if (!this.#list.includes(plugin) || this.#running.has(plugin.id))
+                continue;
+            // Another map set this plugin object up after it was added here.
+            if (ownedElsewhere(plugin, this)) {
+                console.error(ownershipError(plugin));
+                continue;
+            }
+            this.#setup(plugin);
+        }
+    }
+    #teardownAll() {
+        this.#live = false;
+        for (const plugin of this.#list)
+            this.#teardown(plugin.id);
+    }
+    #setup(plugin) {
+        const gl = this.#gl;
+        const running = {
+            plugin,
+            gl,
+            dead: false,
+            teardown: null,
+            effects: [],
+            layers: [],
+            sources: [],
+            images: [],
+            listeners: [],
+            unregisters: []
+        };
+        this.#running.set(plugin.id, running);
+        if (Object.isExtensible(plugin))
+            plugin[OWNER] = this;
+        const ctx = this.#context(plugin.id, running);
+        let teardown;
+        try {
+            // Untracked: setup may be called from inside an effect (e.g. MapView's).
+            teardown = untrack(() => plugin.setup(ctx));
+        }
+        catch (error) {
+            console.error(`map-sdk: plugin "${plugin.id}" setup failed`, error);
+            if (this.#running.get(plugin.id) === running)
+                this.#teardown(plugin.id);
+            return;
+        }
+        if (!running.dead) {
+            running.teardown = teardown;
+            return;
+        }
+        // Torn down during its own setup (it removed itself or detached the host).
+        try {
+            untrack(teardown);
+        }
+        catch (error) {
+            console.error(`map-sdk: plugin "${plugin.id}" teardown failed`, error);
+        }
+    }
+    #teardown(pluginId) {
+        const running = this.#running.get(pluginId);
+        if (!running)
+            return;
+        this.#running.delete(pluginId);
+        running.dead = true;
+        const owned = running.plugin;
+        if (owned[OWNER] === this)
+            delete owned[OWNER];
+        const { gl } = running;
+        const attempt = (what, fn) => {
+            try {
+                fn();
+            }
+            catch (error) {
+                console.error(`map-sdk: plugin "${pluginId}" ${what} failed`, error);
+            }
+        };
+        // Effects stop first so none re-runs against a half-removed plugin.
+        for (const stop of running.effects)
+            attempt("effect cleanup", stop);
+        if (running.teardown)
+            attempt("teardown", untrack.bind(null, running.teardown));
+        // A style change may already have dropped these, so check before removing.
+        for (const id of running.layers.toReversed()) {
+            attempt(`removing layer ${id}`, () => gl.getLayer(id) && gl.removeLayer(id));
+        }
+        for (const id of running.sources.toReversed()) {
+            attempt(`removing source ${id}`, () => gl.getSource(id) && gl.removeSource(id));
+        }
+        for (const id of running.images) {
+            attempt(`removing image ${id}`, () => gl.hasImage(id) && gl.removeImage(id));
+        }
+        for (const { type, layerId, listener } of running.listeners) {
+            attempt(`removing ${type} listener`, () => gl.off(type, layerId, listener));
+        }
+        for (const unregister of running.unregisters)
+            attempt("unregistering", unregister);
+    }
+    #context(pluginId, running) {
+        const { mapUid, providers, router, selectedKeys } = this.#opts;
+        const { gl } = running;
+        const layerAbove = () => this.#layerAbove(pluginId);
+        const id = (local) => `${mapUid}:${pluginId}:${local}`;
+        const addTracked = (full, layer) => {
+            if (running.dead)
+                return full;
+            gl.addLayer(layer, layerAbove());
+            // A re-added layer (a plugin rebuilding its layers) is now its plugin's top layer.
+            const at = running.layers.indexOf(full);
+            if (at >= 0)
+                running.layers.splice(at, 1);
+            running.layers.push(full);
+            return full;
+        };
+        return {
+            gl,
+            id,
+            metadata: providers.metadata,
+            messages: providers.messages,
+            format: providers.format,
+            addSource(local, spec) {
+                const full = id(local);
+                if (running.dead)
+                    return full;
+                gl.addSource(full, spec);
+                running.sources.push(full);
+                return full;
+            },
+            addLayer(local, spec) {
+                return addTracked(id(local), { ...spec, id: id(local) });
+            },
+            addCustomLayer(local, create) {
+                const full = id(local);
+                if (running.dead)
+                    return full;
+                const layer = create(full);
+                if (layer.id !== full) {
+                    throw new Error(`map-sdk: custom layer "${local}" must use the id it is given (${full})`);
+                }
+                return addTracked(full, layer);
+            },
+            addImage(local, image) {
+                if (running.dead)
+                    return;
+                const full = id(local);
+                gl.addImage(full, image);
+                running.images.push(full);
+            },
+            interactive(layerIds, toHit) {
+                if (running.dead)
+                    return;
+                running.unregisters.push(router.register(pluginId, layerIds, toHit, running.plugin.hoverPriority ?? 0));
+            },
+            blocking(layerIds, toHover, onClick) {
+                if (running.dead)
+                    return;
+                running.unregisters.push(router.registerBlocking(pluginId, layerIds, toHover, onClick, running.plugin.hoverPriority ?? 0));
+            },
+            on(type, layerId, listener) {
+                if (running.dead)
+                    return;
+                gl.on(type, layerId, listener);
+                running.listeners.push({ type, layerId, listener });
+            },
+            get selectedKeys() {
+                return selectedKeys(pluginId);
+            },
+            effect(fn) {
+                if (running.dead)
+                    return;
+                running.effects.push($effect.root(() => {
+                    $effect(fn);
+                }));
+            }
+        };
+    }
+}