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

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

@@ -0,0 +1,38 @@
+import type { GlMapLike } from "./gl.js";
+export interface BasemapConfig {
+    styles: Array<{
+        id: string;
+        style: unknown;
+    }>;
+    defaultId: string;
+    excludedLayers?: string[];
+}
+/**
+ * The map's current basemap, and switching it on a GL map.
+ *
+ * The GL map is created with the style of `current` (the map's creator does that), so `attach`
+ * calls `setStyle` for nothing. Later `select` calls load the new style. A newer `select`
+ * supersedes one still loading. If the style document fails, the map goes back to the last style
+ * that loaded and `current` reverts; if that fails too, the map stays unstyled until the next
+ * `select`. Right before each `setStyle`, `onStyleChange` is called (it tears the plugins down,
+ * so nothing touches the old style while the new one loads). After each successful load,
+ * `excludedLayers` are removed and `onStyleReady` is called (it sets the plugins up again). The
+ * map's first style is not announced: the plugin host already waits for it.
+ */
+export declare class BasemapState {
+    #private;
+    constructor(config: BasemapConfig | undefined);
+    /** The selected basemap id. Reactive. */
+    get current(): string;
+    /** Unknown ids are ignored. While no map is attached, only `current` changes. */
+    select(id: string): void;
+    /**
+     * For MapView only (through the map context's `attach`): uses `gl` from now on, which must
+     * already show (or be loading) the style of `current`. `onStyleChange` runs right before each
+     * `setStyle`, `onStyleReady` once that style has loaded. Reads `current` untracked, so calling
+     * this in an effect doesn't make it depend on it.
+     */
+    attach(gl: GlMapLike, onStyleReady: () => void, onStyleChange?: () => void): void;
+    /** For MapView only (through the map context's `detach`): stops using the GL map. */
+    detach(): void;
+}

package/dist/core/basemap.svelte.js

@@ -0,0 +1,163 @@
+import { untrack } from "svelte";
+/** The first of these means the style of a map just created is ready. */
+const STYLE_READY_EVENTS = ["style.load", "idle"];
+/**
+ * The map's current basemap, and switching it on a GL map.
+ *
+ * The GL map is created with the style of `current` (the map's creator does that), so `attach`
+ * calls `setStyle` for nothing. Later `select` calls load the new style. A newer `select`
+ * supersedes one still loading. If the style document fails, the map goes back to the last style
+ * that loaded and `current` reverts; if that fails too, the map stays unstyled until the next
+ * `select`. Right before each `setStyle`, `onStyleChange` is called (it tears the plugins down,
+ * so nothing touches the old style while the new one loads). After each successful load,
+ * `excludedLayers` are removed and `onStyleReady` is called (it sets the plugins up again). The
+ * map's first style is not announced: the plugin host already waits for it.
+ */
+export class BasemapState {
+    #current = $state("");
+    #config;
+    #gl = null;
+    #onStyleReady = null;
+    #onStyleChange = null;
+    /** The id last handed to `setStyle` (loaded or loading); null once a load failed with no fallback. */
+    #applied = null;
+    /** The id the map last finished loading, which a failed change falls back to. */
+    #loaded = "";
+    #stopWaiting = null;
+    constructor(config) {
+        this.#config = config;
+        this.#current = config?.defaultId ?? "";
+    }
+    /** The selected basemap id. Reactive. */
+    get current() {
+        return this.#current;
+    }
+    /** Unknown ids are ignored. While no map is attached, only `current` changes. */
+    select(id) {
+        if (!this.#entry(id))
+            return;
+        this.#current = id;
+        if (!this.#gl || id === this.#applied)
+            return;
+        this.#load(id);
+    }
+    /**
+     * For MapView only (through the map context's `attach`): uses `gl` from now on, which must
+     * already show (or be loading) the style of `current`. `onStyleChange` runs right before each
+     * `setStyle`, `onStyleReady` once that style has loaded. Reads `current` untracked, so calling
+     * this in an effect doesn't make it depend on it.
+     */
+    attach(gl, onStyleReady, onStyleChange) {
+        if (this.#gl === gl)
+            return;
+        if (this.#gl)
+            this.detach();
+        this.#gl = gl;
+        this.#onStyleReady = onStyleReady;
+        this.#onStyleChange = onStyleChange ?? null;
+        const id = untrack(() => this.#current);
+        this.#applied = id;
+        this.#loaded = id;
+        // The first style: drop the excluded layers, but leave the plugin host to set itself up.
+        this.#whenReady(gl, () => this.#removeExcluded(gl));
+    }
+    /** For MapView only (through the map context's `detach`): stops using the GL map. */
+    detach() {
+        this.#stopWaiting?.();
+        this.#gl = null;
+        this.#onStyleReady = null;
+        this.#onStyleChange = null;
+    }
+    #entry(id) {
+        return this.#config?.styles.find((s) => s.id === id);
+    }
+    /** Runs `fn` once `gl`'s style is ready, at once if it is. Cancelled by `#stopWaiting`. */
+    #whenReady(gl, fn) {
+        this.#stopWaiting?.();
+        if (gl.isStyleLoaded()) {
+            fn();
+            return;
+        }
+        const listener = () => {
+            stop();
+            fn();
+        };
+        const stop = () => {
+            for (const type of STYLE_READY_EVENTS)
+                gl.off(type, listener);
+            if (this.#stopWaiting === stop)
+                this.#stopWaiting = null;
+        };
+        this.#stopWaiting = stop;
+        for (const type of STYLE_READY_EVENTS)
+            gl.on(type, listener);
+    }
+    #removeExcluded(gl) {
+        for (const layerId of this.#config?.excludedLayers ?? []) {
+            try {
+                if (gl.getLayer(layerId))
+                    gl.removeLayer(layerId);
+            }
+            catch (error) {
+                console.error(`map-sdk: removing basemap layer "${layerId}" failed`, error);
+            }
+        }
+    }
+    #load(id) {
+        const gl = this.#gl;
+        const entry = this.#entry(id);
+        if (!gl || !entry)
+            return;
+        // A newer change supersedes one still in flight.
+        this.#stopWaiting?.();
+        this.#applied = id;
+        const onLoad = () => {
+            stop();
+            this.#loaded = id;
+            this.#removeExcluded(gl);
+            this.#onStyleReady?.();
+        };
+        // "error" also fires for tiles, sprites and glyphs; only the style document failing means
+        // the change failed. That is matched by URL, so a style given as an object (not a URL
+        // string) can't be told apart and is never treated as failed.
+        const url = typeof entry.style === "string" ? entry.style : null;
+        const onError = (event) => {
+            if (url === null || !isRequestFor(event.error, url))
+                return;
+            stop();
+            this.#recover(id);
+        };
+        const stop = () => {
+            gl.off("style.load", onLoad);
+            gl.off("error", onError);
+            if (this.#stopWaiting === stop)
+                this.#stopWaiting = null;
+        };
+        this.#stopWaiting = stop;
+        gl.on("style.load", onLoad);
+        gl.on("error", onError);
+        this.#onStyleChange?.();
+        // No diffing: a diff keeps the plugins' sources and layers in some cases and not others.
+        gl.setStyle(entry.style, { diff: false });
+    }
+    /**
+     * A style that fails to load leaves the map with no style, so go back to the last one that
+     * loaded and make `current` say so. When that one fails too there is nothing to draw on, and
+     * the next `select` starts a fresh attempt.
+     */
+    #recover(failed) {
+        if (failed === this.#loaded) {
+            this.#applied = null;
+            return;
+        }
+        this.#current = this.#loaded;
+        this.#load(this.#loaded);
+    }
+}
+/** Whether a map "error" event's error is a failed request for `url`, ignoring the query. */
+function isRequestFor(error, url) {
+    const failed = error?.url;
+    if (typeof failed !== "string")
+        return false;
+    return failed.split("?")[0] === url.split("?")[0];
+}

package/dist/core/context.d.ts

@@ -0,0 +1,5 @@
+import type { MapContext } from "./create-map.svelte.js";
+/** Provides `ctx` to this component's descendants (MapView does this). */
+export declare function setMapContext(ctx: MapContext): void;
+/** The nearest `MapView`'s map. Throws outside one. */
+export declare function getMapContext(): MapContext;

package/dist/core/context.js

@@ -0,0 +1,13 @@
+import { getContext, setContext } from "svelte";
+const KEY = Symbol("map-sdk:map");
+/** Provides `ctx` to this component's descendants (MapView does this). */
+export function setMapContext(ctx) {
+    setContext(KEY, ctx);
+}
+/** The nearest `MapView`'s map. Throws outside one. */
+export function getMapContext() {
+    const ctx = getContext(KEY);
+    if (!ctx)
+        throw new Error("map-sdk: no map context; use this inside a MapView");
+    return ctx;
+}

package/dist/core/create-map.svelte.d.ts

@@ -0,0 +1,274 @@
+import { type FormatProvider } from "../data/format.js";
+import { type MessageProvider } from "../data/messages.js";
+import { type MetadataProvider } from "../data/metadata.js";
+import type { FeatureRef, SelectionMode, SpatialSelection } from "../data/types.js";
+import { BasemapState, type BasemapConfig } from "./basemap.svelte.js";
+import type { GlMapLike } from "./gl.js";
+import { type Hovered } from "./interactions.svelte.js";
+import type { FeatureHit, FeatureListItem, MapPlugin } from "./plugin.js";
+export interface CameraState {
+    center: [number, number];
+    zoom: number;
+    bearing: number;
+    pitch: number;
+}
+export interface Bounds {
+    west: number;
+    south: number;
+    east: number;
+    north: number;
+}
+export interface MapConfig {
+    maptilerKey: string;
+    basemaps?: BasemapConfig;
+    initialView?: CameraState;
+    cooperativeGestures?: boolean;
+    /** Default `"mercator"`. `"globe"` draws the map on a globe when zoomed out. */
+    projection?: "mercator" | "globe";
+    /**
+     * Default `false`. A preset (monitor-map uses `{ preset: "milkyway" }`) draws space behind a
+     * globe.
+     */
+    space?: false | {
+        preset: string;
+    };
+    /**
+     * Default `true`: MapTiler's own default. `false` turns off MapTiler's telemetry (a usage
+     * report of the SDK version, the API key, and the session id, sent about 2 s after each map is
+     * created) before the GL map is created. It is a page-wide setting in MapTiler's SDK, so once
+     * one map turns it off it stays off for every map on the page. MapTiler's session id (`mtsid`)
+     * stays on: MapTiler bills SDK maps by session, and its tile cache needs sessions.
+     */
+    telemetry?: boolean;
+}
+export interface CreateMapOptions {
+    config: MapConfig;
+    metadata?: MetadataProvider;
+    messages?: MessageProvider;
+    format?: FormatProvider;
+}
+export interface PluginOptions {
+    /**
+     * Draw the plugin just below the plugin with this id (which must be added already). Without
+     * it the plugin goes on top.
+     */
+    before?: string;
+    selectionMode?: SelectionMode;
+    selection?: SpatialSelection | null;
+    onselectionchange?(sel: SpatialSelection | null): void;
+    /**
+     * `"click"` (default): today's rules (a click selects; Shift/⌘/Ctrl or a tap adds in
+     * `"multiple"` mode). `"modifier"`: a plain click or tap only pins the card (use it with
+     * `MapView`'s `card`), and Shift/⌘/Ctrl-click, or the list's Space or Shift+Enter, toggles the
+     * feature in the selection.
+     */
+    pickWith?: "click" | "modifier";
+    /**
+     * Called before a user's pick (a click, a list pick, or the card's `toggle`) changes the
+     * selection, with the selection it would produce. `true` lets it through; a string refuses it
+     * and is the message the map shows (`MapContext.notice`). Not called for `setSelection` or the
+     * selection bar's Clear.
+     */
+    canSelect?(next: SpatialSelection | null, ref: FeatureRef): true | string;
+}
+export type FeatureClickHandler = (e: {
+    pluginId: string;
+    ref: FeatureRef;
+    /**
+     * The click point. For a pick in the feature list, where the item's tooltip pins: its position,
+     * or for a shape whose label point is off-screen, a point of the shape in view.
+     */
+    lngLat: [number, number];
+}) => void;
+/** Where a camera move ends up. `zoom` wins over `minZoom`. */
+export interface CameraTarget {
+    center: [number, number];
+    zoom?: number;
+    /** Zoom to at least this: the move's zoom is `max(current zoom, minZoom)`. */
+    minZoom?: number;
+}
+/** A map's state and services, independent of whether a GL map currently exists. */
+export interface MapContext {
+    readonly uid: string;
+    readonly config: Readonly<MapConfig>;
+    readonly metadata: MetadataProvider;
+    readonly messages: MessageProvider;
+    readonly format: FormatProvider;
+    /** Reactive; updated by MapView on moveend. */
+    readonly camera: CameraState;
+    /** Reactive; `null` until a map reports its bounds. */
+    readonly bounds: Bounds | null;
+    readonly basemap: BasemapState;
+    /**
+     * In draw order, bottom first: later plugins draw above earlier ones, and each plugin's layers
+     * stay together. Reactive.
+     */
+    readonly plugins: readonly MapPlugin[];
+    /** Reactive. */
+    readonly attached: boolean;
+    /**
+     * Reactive. True once the attached map's style has loaded, the map has gone idle for the
+     * first time, and any queued plugin setups have run; false again on `detach()` and while a
+     * basemap switch reloads the style. Adding a plugin to a ready map leaves it true. A load
+     * screen can wait for it.
+     */
+    readonly ready: boolean;
+    /**
+     * Reactive. The attached GL map, or `null`. For markers and popups only (see `maptilerMap`);
+     * never add sources or layers through it.
+     */
+    readonly gl: GlMapLike | null;
+    /**
+     * @internal For `MapView` only; hosts never call it. Marks the attached map ready. Does
+     * nothing while detached.
+     */
+    markReady(): void;
+    /**
+     * Adds a plugin on top, or below `options.before`. Throws if a plugin with the same id is
+     * already added, if `before` names no added plugin, if the same plugin object is set up on
+     * another map (create one plugin per map), or after `destroy()`.
+     */
+    addPlugin(plugin: MapPlugin, options?: PluginOptions): void;
+    /**
+     * Moves a plugin and its layers to the top, or just below `options.before`. Does nothing for
+     * an unknown `id`; throws if `before` names no added plugin.
+     */
+    movePlugin(id: string, options?: {
+        before?: string;
+    }): void;
+    /** Tears the plugin down and forgets its selection, mode, and `onselectionchange`. */
+    removePlugin(id: string): void;
+    /**
+     * Host → map. Kept as given, including ids not in any data. Does not call
+     * `onselectionchange`.
+     */
+    setSelection(pluginId: string, selection: SpatialSelection | null): void;
+    /** Reactive. */
+    getSelection(pluginId: string): SpatialSelection | null;
+    setSelectionMode(pluginId: string, mode: SelectionMode): void;
+    /** Reactive. `"none"` for an unknown plugin. */
+    getSelectionMode(pluginId: string): SelectionMode;
+    /**
+     * Internal, for FeatureList: picks a listed feature exactly like a map click on it. Fires
+     * `featureclick`, then applies the same selection rules (`additive` adds or toggles in
+     * `multiple` mode), calling `onselectionchange` if the selection changes. An item that isn't
+     * selectable is still clicked but not selected. Does nothing for a refKey the plugin doesn't list.
+     */
+    pickFromList(pluginId: string, refKey: string, additive: boolean): void;
+    /**
+     * Internal, for the selection bar: the user clears a plugin's selection. Calls the plugin's
+     * `onselectionchange(null)` when it had a selection; does nothing otherwise.
+     */
+    clearSelection(pluginId: string): void;
+    /**
+     * Called for every feature click (the top hit), whatever the selection mode, before the
+     * selection changes. Returns an unsubscribe function.
+     */
+    on(event: "featureclick", handler: FeatureClickHandler): () => void;
+    /** Hits under a canvas point, topmost first. `[]` while detached. */
+    featuresAt(point: {
+        x: number;
+        y: number;
+    }): FeatureHit[];
+    /**
+     * The hit for a feature-list element: the nearest `[data-mapsdk-ref]` ancestor (or the element
+     * itself), looked up in the plugins' `features()`: in the row's `data-mapsdk-plugin` plugin when
+     * it names one, else the first plugin listing the refKey. Only rows inside this map's own root count:
+     * the row's nearest `[data-mapsdk-map]` ancestor must carry this map's `uid`, which MapView
+     * sets on its container and FeatureList on its root. `null` otherwise.
+     */
+    featureForElement(element: Element): FeatureHit | null;
+    /**
+     * The top feature under the pointer and where it is. Reactive, for the tooltip. Over a cluster
+     * bubble it is the bubble's own hit: a `{ kind: "feature", id: "cluster:…" }` ref no plugin
+     * lists, with the bubble's `properties`, never a feature beneath it.
+     */
+    readonly hovered: Hovered | null;
+    /**
+     * Reactive. The feature whose reading card is pinned, and where, while `MapView`'s `card` is
+     * on; `null` otherwise. A click on a feature pins it (selection and `featureclick` are
+     * unchanged), focusing a feature-list row pins that row's feature, and a click on nothing (or
+     * on a cluster bubble or a feature without a hover card) unpins.
+     */
+    readonly pinned: Hovered | null;
+    /** Reactive. The plugin's `pickWith`: `"click"` for an unknown plugin. */
+    getPickWith(pluginId: string): "click" | "modifier";
+    /**
+     * A user's toggle of `ref` (the card's Select/Remove): the modifier-click rule, with the
+     * plugin's `canSelect` and `onselectionchange`, in either `pickWith` mode.
+     */
+    togglePick(pluginId: string, ref: FeatureRef): void;
+    /**
+     * Reactive. The latest refused pick's message; `id` grows with each refusal, so the same
+     * message twice is announced again. Cleared by the next pick, `clearNotice()`, and detach.
+     */
+    readonly notice: {
+        message: string;
+        id: number;
+    } | null;
+    /** @internal For `PickNotice`: clears the notice. */
+    clearNotice(): void;
+    /** Closes the pinned card. Does nothing when nothing is pinned. */
+    unpin(): void;
+    /** @internal For `MapView` only: turns pinning on or off. Off also unpins. */
+    setCardEnabled(on: boolean): void;
+    /**
+     * Marks the feature focused and pans to it (no animation under reduced motion): the item in
+     * `pluginId`'s features when given, else the first plugin listing `refKey`. `null` clears the
+     * focus without moving the camera. Sets `focusedPluginId` to `pluginId` (or `null`). The pan
+     * centers the feature in the part of the map the feature list panel leaves clear.
+     */
+    focusFeature(refKey: string | null, pluginId?: string): void;
+    /**
+     * Eases the camera to `target` (no animation under reduced motion). Does nothing while
+     * detached.
+     */
+    easeTo(target: CameraTarget): void;
+    /** Like `easeTo`, with a flying animation. */
+    flyTo(target: CameraTarget): void;
+    /**
+     * Fits the camera to `bounds` (no animation under reduced motion). Does nothing while
+     * detached.
+     */
+    fitBounds(bounds: Bounds, options?: {
+        padding?: number;
+        maxZoom?: number;
+    }): void;
+    /** Reactive. */
+    readonly focusedKey: string | null;
+    /** Reactive. The plugin `focusFeature` was given with `focusedKey`, or `null`. */
+    readonly focusedPluginId: string | null;
+    /**
+     * Reactive. Where the focused feature's tooltip pins, set by `focusFeature` (`null` without
+     * focus): its `lngLat`, or for a shape that overlaps the view with its `lngLat` off-screen, a
+     * point of the shape in the part of the view the list panel leaves clear. Fixed at focus
+     * time, so it stays on the feature if the map then moves.
+     */
+    readonly focusedAnchor: [number, number] | null;
+    /**
+     * Where `item`'s tooltip pins in the current view, without moving the camera: its `lngLat`,
+     * or for a shape (`geometry`) with its `lngLat` off-screen, a point of the shape in view.
+     */
+    anchorFor(item: FeatureListItem): [number, number];
+    /** For MapView only: uses `gl` from now on. */
+    attach(gl: GlMapLike): void;
+    /** For MapView only: stops using the current GL map. */
+    detach(): void;
+    /**
+     * For MapView only: how many pixels at the map's left or right edge (`side`, default left)
+     * the open feature list panel covers (0 when closed), which `focusFeature` pans clear of.
+     */
+    setListInset(width: number, side?: "left" | "right"): void;
+    /** For MapView only: records the camera and bounds after a move. */
+    updateView(camera: CameraState, bounds: Bounds): void;
+    /**
+     * For MapView only: the host's theme changed, so plugins set up again and re-read the theme
+     * colors they bake into paint and images. Does nothing while detached. Sets plugins up
+     * synchronously, so never call it from inside an effect (see `PluginHost`).
+     */
+    themeChanged(): void;
+    /** Detaches, removes every plugin, and drops handlers. The context can't be used after. */
+    destroy(): void;
+}
+/** Creates a map's state and services. `MapView` attaches a GL map to it. */
+export declare function createMap(options: CreateMapOptions): MapContext;