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

package/dist/plugins/scale-resolution.svelte.js

@@ -0,0 +1,111 @@
+import { untrack } from "svelte";
+/** For a `null` source scale: features still draw, all neutral, with no legend. */
+export const NO_SCALE = {
+    id: "",
+    label: "",
+    units: "",
+    kind: "category",
+    source: null,
+    levels: []
+};
+/** The dataset of a source whose scale is a `ScaleRef`; `undefined` for a literal scale or none. */
+export function datasetOf(source) {
+    const input = source.scale;
+    return input !== null && !("levels" in input) ? input.dataset : undefined;
+}
+/** Equal for scales equal by value. */
+export function scaleKey(scale) {
+    return JSON.stringify(scale);
+}
+function isScale(input) {
+    return input !== null && "levels" in input;
+}
+/** The scale for `input` when it is available synchronously. */
+function immediate(input) {
+    if (input === null)
+        return NO_SCALE;
+    return isScale(input) ? input : null;
+}
+/** Scale resolution shared by the plugins: abort on change, ignore late results. */
+export function createScaleResolver(pluginId, layerLabel, source, 
+/** Title the legend with the entry type's label from the metadata once known. */
+entryTypeTitle = false) {
+    /** The scale resolved for a source scale input, from the latest setup. */
+    let resolution = $state.raw(null);
+    /** The metadata's display precision and label for a source scale input, once known. */
+    let hint = $state.raw(null);
+    function current() {
+        const input = source.scale;
+        const now = immediate(input);
+        if (now)
+            return now;
+        return resolution?.input === input ? resolution.scale : null;
+    }
+    function legend() {
+        const status = source.status;
+        if (status.state === "error" || status.state === "unavailable") {
+            return { pluginId, status };
+        }
+        const scale = current();
+        if (scale === null)
+            return { pluginId, status: { state: "loading" } };
+        if (scale === "unavailable") {
+            const unavailable = { state: "unavailable", reason: "scale" };
+            return { pluginId, status: unavailable };
+        }
+        if (scale === NO_SCALE)
+            return null;
+        const title = entryTypeTitle && hint !== null && hint.input === source.scale && hint.label
+            ? hint.label
+            : layerLabel;
+        return { pluginId, title, units: scale.units, scale };
+    }
+    function precision() {
+        if (hint !== null && hint.input === source.scale && hint.precision !== null) {
+            return hint.precision;
+        }
+        const scale = current();
+        return scale !== null && scale !== "unavailable" && scale.kind === "range" ? 0 : 1;
+    }
+    function track(ctx, isDead) {
+        ctx.effect(() => {
+            const input = source.scale;
+            if (input === null || isScale(input))
+                return;
+            if (untrack(() => hint)?.input === input)
+                return;
+            const controller = new AbortController();
+            // A display hint only: a failure keeps the default.
+            ctx.metadata.entryType(input, controller.signal).then((info) => {
+                if (isDead() || controller.signal.aborted)
+                    return;
+                hint =
+                    info === "unavailable"
+                        ? { input, precision: null, label: null }
+                        : { input, precision: info.precision, label: info.label };
+            }, () => { });
+            return () => controller.abort();
+        });
+        ctx.effect(() => {
+            const input = source.scale;
+            if (input === null || isScale(input))
+                return;
+            // Already resolved by an earlier setup; an "unavailable" result is retried.
+            const known = untrack(() => resolution);
+            if (known?.input === input && known.scale !== "unavailable")
+                return;
+            const controller = new AbortController();
+            ctx.metadata.scale(input, controller.signal).then((scale) => {
+                if (!isDead() && !controller.signal.aborted)
+                    resolution = { input, scale };
+            }, (error) => {
+                if (isDead() || controller.signal.aborted)
+                    return;
+                console.warn(`map-sdk: plugin "${pluginId}" could not resolve its scale`, error);
+                resolution = { input, scale: "unavailable" };
+            });
+            return () => controller.abort();
+        });
+    }
+    return { current, legend, precision, track };
+}

package/dist/plugins/shapes.svelte.d.ts

@@ -0,0 +1,34 @@
+import type { Geometry } from "geojson";
+import type { MapPlugin } from "../core/plugin.js";
+import type { DataSource, MapFeatureProperties } from "../data/types.js";
+export interface ShapesOptions<P extends MapFeatureProperties> {
+    id: string;
+    source: DataSource<P>;
+    /** Already-translated layer name for the list and summary. */
+    layerLabel: string;
+    /** `choropleth` fills by the source's scale; `plain` is neutral with no legend. */
+    mode: "plain" | "choropleth";
+    selectable?: boolean;
+    /** Whether `features()` lists this plugin's features. Default true. */
+    listed?: boolean;
+    /** Fill opacity where a level sets none. Default 0.6. */
+    fillOpacity?: number;
+    /**
+     * Edge of the shapes. `theme` (default) is a 1px `--foreground` line; `level` draws it in the
+     * level's color at the level's opacity (choropleth); `none` draws no outline layer
+     * (so LineString geometries are not drawn either).
+     */
+    outline?: "theme" | "level" | "none";
+    /**
+     * False: hovering a shape shows no tooltip and doesn't hide what is beneath it
+     * (`MapPlugin.hoverable`); list focus still shows it. Default true.
+     */
+    hoverable?: boolean;
+}
+/** The point used to place a feature in lists: its largest ring's centroid, or a line's midpoint. */
+export declare function labelPoint(geometry: Geometry): [number, number] | null;
+/**
+ * Polygons and lines, plain (neutral) or filled by value from a scale (choropleth), with a
+ * thin outline and a thicker highlight outline on selected features.
+ */
+export declare function shapesPlugin<P extends MapFeatureProperties>(options: ShapesOptions<P>): MapPlugin;

package/dist/plugins/shapes.svelte.js

@@ -0,0 +1,325 @@
+import { geometryBbox } from "../core/shape-view.js";
+import { untrack } from "svelte";
+import { decodeRef, selectionId } from "../data/refs.js";
+import { levelFor, NO_LEVEL } from "../data/scale.js";
+import { createScaleResolver, NO_SCALE, datasetOf, scaleKey } from "./scale-resolution.svelte.js";
+import { hitFromProps, SELECTED_OPACITY } from "./shared.js";
+import { asDataURI, SELECTED_OVERLAY_PADDING, selectedOverlay } from "./icons.js";
+import { colorExpression, opacityExpression, themeColors } from "./style.js";
+/** The check image is drawn at this multiple of its size and scaled down, for sharp HiDPI. */
+const IMAGE_RATIO = 2;
+/** The check mark badge is sized for a marker this many pixels across. */
+const CHECK_SIZE = 12;
+const EMPTY = { type: "FeatureCollection", features: [] };
+const DEFAULT_FILL_OPACITY = 0.6;
+const OUTLINE_WIDTH = 1;
+const LINE_WIDTH = 2;
+const SELECTED_WIDTH = 3;
+const LINE_TYPES = ["LineString", "MultiLineString"];
+/** Twice the signed area of a ring, absolute. */
+function ringArea(ring) {
+    let sum = 0;
+    for (let i = 0; i < ring.length - 1; i++) {
+        sum += ring[i][0] * ring[i + 1][1] - ring[i + 1][0] * ring[i][1];
+    }
+    return Math.abs(sum);
+}
+/** Centroid of a ring (the area-weighted one; the vertex mean for a degenerate ring). */
+function ringCentroid(ring) {
+    let area = 0;
+    let cx = 0;
+    let cy = 0;
+    for (let i = 0; i < ring.length - 1; i++) {
+        const cross = ring[i][0] * ring[i + 1][1] - ring[i + 1][0] * ring[i][1];
+        area += cross;
+        cx += (ring[i][0] + ring[i + 1][0]) * cross;
+        cy += (ring[i][1] + ring[i + 1][1]) * cross;
+    }
+    if (area === 0) {
+        const n = Math.max(ring.length - 1, 1);
+        const sum = ring.slice(0, n).reduce((a, p) => [a[0] + p[0], a[1] + p[1]], [0, 0]);
+        return [sum[0] / n, sum[1] / n];
+    }
+    return [cx / (3 * area), cy / (3 * area)];
+}
+/** The point used to place a feature in lists: its largest ring's centroid, or a line's midpoint. */
+export function labelPoint(geometry) {
+    switch (geometry.type) {
+        case "Point":
+            return [geometry.coordinates[0], geometry.coordinates[1]];
+        case "Polygon":
+        case "MultiPolygon": {
+            const polygons = geometry.type === "Polygon" ? [geometry.coordinates] : geometry.coordinates;
+            let best = null;
+            let bestArea = -1;
+            for (const polygon of polygons) {
+                const outer = polygon[0];
+                if (!outer?.length)
+                    continue;
+                const area = ringArea(outer);
+                if (area > bestArea) {
+                    best = outer;
+                    bestArea = area;
+                }
+            }
+            return best ? ringCentroid(best) : null;
+        }
+        case "LineString":
+        case "MultiLineString": {
+            const lines = geometry.type === "LineString" ? [geometry.coordinates] : geometry.coordinates;
+            const longest = lines.reduce((a, b) => (b.length > a.length ? b : a), []);
+            const mid = longest[Math.floor(longest.length / 2)];
+            return mid ? [mid[0], mid[1]] : null;
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * Polygons and lines, plain (neutral) or filled by value from a scale (choropleth), with a
+ * thin outline and a thicker highlight outline on selected features.
+ */
+export function shapesPlugin(options) {
+    const { id: pluginId, source, layerLabel, mode } = options;
+    const selectable = options.selectable ?? false;
+    const fillOpacity = options.fillOpacity ?? DEFAULT_FILL_OPACITY;
+    const choropleth = mode === "choropleth";
+    const outlineMode = options.outline ?? "theme";
+    const scales = createScaleResolver(pluginId, layerLabel, source);
+    /** Plain mode ignores the source's scale. */
+    const currentScale = () => (choropleth ? scales.current() : NO_SCALE);
+    const legend = () => (choropleth ? scales.legend() : null);
+    // Each feature's label point and bbox, measured once per feature object (once per data load):
+    // `features()` runs on every move. Per plugin instance, so two maps share nothing.
+    const measured = new WeakMap();
+    const measure = (feature) => {
+        let m = measured.get(feature);
+        if (!m) {
+            m = { lngLat: labelPoint(feature.geometry), bbox: geometryBbox(feature.geometry) };
+            measured.set(feature, m);
+        }
+        return m;
+    };
+    function features() {
+        const collection = source.features;
+        if (!collection)
+            return [];
+        const resolved = currentScale();
+        const scale = resolved === null || resolved === "unavailable" ? null : resolved;
+        const precision = choropleth ? scales.precision() : 1;
+        const items = [];
+        for (const feature of collection.features) {
+            const props = feature.properties;
+            if (!props || !feature.geometry)
+                continue;
+            const ref = decodeRef(props.refKey);
+            if (!ref)
+                continue;
+            const { lngLat, bbox } = measure(feature);
+            if (!lngLat)
+                continue;
+            items.push({
+                refKey: props.refKey,
+                ref,
+                name: props.name,
+                value: props.value,
+                level: scale ? levelFor(props.value, scale) : NO_LEVEL,
+                units: scale?.units ?? "",
+                precision,
+                lngLat,
+                geometry: feature.geometry,
+                ...(bbox && { bbox }),
+                selectable: selectable && selectionId(ref) !== null
+            });
+        }
+        return items;
+    }
+    const toHit = (props) => hitFromProps(pluginId, props);
+    function setup(ctx) {
+        let dead = false;
+        const { gl } = ctx;
+        const container = gl.getCanvas().closest?.("[data-mapsdk-map]") ?? null;
+        const theme = themeColors(container);
+        let sourceId = null;
+        let checkSourceId = null;
+        /** refKey → label point, from the latest data. */
+        // eslint-disable-next-line svelte/prefer-svelte-reactivity -- bookkeeping, not reactive
+        let labels = new Map();
+        /** Namespaced ids of the layers currently on the map, in draw order. */
+        let layers = [];
+        /** The scale (by `scaleKey`) the layers on the map were built for. */
+        let builtKey = null;
+        let interactiveDone = false;
+        // eslint-disable-next-line svelte/prefer-svelte-reactivity -- bookkeeping, not reactive
+        let applied = new Set();
+        function removeLayers() {
+            for (const layerId of layers.toReversed()) {
+                if (gl.getLayer(layerId))
+                    gl.removeLayer(layerId);
+            }
+            layers = [];
+            builtKey = null;
+        }
+        function buildLayers(scale, src) {
+            removeLayers();
+            const isLine = ["match", ["geometry-type"], LINE_TYPES, true, false];
+            const lineColor = choropleth
+                ? [
+                    "case",
+                    isLine,
+                    colorExpression(scale, "value", theme.neutral),
+                    theme.foreground
+                ]
+                : theme.foreground;
+            const fill = ctx.addLayer("fill", {
+                type: "fill",
+                source: src,
+                paint: {
+                    "fill-color": choropleth ? colorExpression(scale, "value", theme.neutral) : theme.neutral,
+                    "fill-opacity": choropleth ? opacityExpression(scale, "value", fillOpacity) : fillOpacity
+                }
+            });
+            const byLevel = outlineMode === "level" && choropleth;
+            const outline = outlineMode === "none"
+                ? null
+                : ctx.addLayer("outline", {
+                    type: "line",
+                    source: src,
+                    paint: {
+                        "line-color": byLevel ? colorExpression(scale, "value", theme.neutral) : lineColor,
+                        ...(byLevel
+                            ? { "line-opacity": opacityExpression(scale, "value", fillOpacity) }
+                            : {}),
+                        "line-width": ["case", isLine, LINE_WIDTH, OUTLINE_WIDTH]
+                    }
+                });
+            const selectedLayer = ctx.addLayer("selected", {
+                type: "line",
+                source: src,
+                paint: {
+                    "line-color": theme.highlight,
+                    "line-width": SELECTED_WIDTH,
+                    "line-opacity": SELECTED_OPACITY
+                }
+            });
+            const check = ctx.addLayer("check", {
+                type: "symbol",
+                source: checkSourceId,
+                layout: {
+                    "icon-image": ctx.id("selected"),
+                    "icon-size": 1 / IMAGE_RATIO,
+                    "icon-allow-overlap": true,
+                    "icon-ignore-placement": true
+                }
+            });
+            layers = outline ? [fill, outline, selectedLayer, check] : [fill, selectedLayer, check];
+            // Layer ids repeat across rebuilds; register them once.
+            if (!interactiveDone) {
+                interactiveDone = true;
+                ctx.interactive(outline ? [fill, outline] : [fill], toHit);
+            }
+            builtKey = scaleKey(scale);
+        }
+        /** One check-mark point per selected feature present in the data. */
+        function updateCheck(keys) {
+            if (!checkSourceId)
+                return;
+            const out = [];
+            for (const key of keys) {
+                const at = labels.get(key);
+                if (at)
+                    out.push({
+                        type: "Feature",
+                        geometry: { type: "Point", coordinates: at },
+                        properties: {}
+                    });
+            }
+            gl.getSource(checkSourceId).setData({
+                type: "FeatureCollection",
+                features: out
+            });
+        }
+        function applySelection(keys) {
+            if (!sourceId)
+                return;
+            updateCheck(keys);
+            for (const key of applied) {
+                if (!keys.has(key))
+                    gl.removeFeatureState({ source: sourceId, id: key }, "selected");
+            }
+            for (const key of keys) {
+                if (!applied.has(key))
+                    gl.setFeatureState({ source: sourceId, id: key }, { selected: true });
+            }
+            // eslint-disable-next-line svelte/prefer-svelte-reactivity -- bookkeeping, not reactive
+            applied = new Set(keys);
+        }
+        function render(reactive, scale) {
+            // Plain objects: MapLibre structured-clones the data to its worker, which a proxy fails.
+            const data = ($state.snapshot(reactive) ?? {
+                type: "FeatureCollection",
+                features: []
+            });
+            // eslint-disable-next-line svelte/prefer-svelte-reactivity -- bookkeeping, not reactive
+            labels = new Map();
+            for (const feature of data.features) {
+                const props = feature.properties;
+                const at = props && feature.geometry ? labelPoint(feature.geometry) : null;
+                if (props && at)
+                    labels.set(props.refKey, at);
+            }
+            if (sourceId) {
+                gl.getSource(sourceId).setData(data);
+            }
+            else {
+                sourceId = ctx.addSource("shapes", { type: "geojson", data, promoteId: "refKey" });
+                checkSourceId = ctx.addSource("check", { type: "geojson", data: EMPTY });
+            }
+            if (scale === null || scale === "unavailable") {
+                removeLayers();
+            }
+            else if (builtKey !== scaleKey(scale)) {
+                buildLayers(scale, sourceId);
+            }
+            applySelection(untrack(() => ctx.selectedKeys));
+        }
+        if (typeof Image !== "undefined") {
+            const total = CHECK_SIZE + 2 * SELECTED_OVERLAY_PADDING;
+            const image = new Image(total * IMAGE_RATIO, total * IMAGE_RATIO);
+            image.onload = () => {
+                if (!dead)
+                    ctx.addImage("selected", image);
+            };
+            image.src = asDataURI(selectedOverlay(theme.highlight, theme.highlightForeground, CHECK_SIZE));
+        }
+        if (choropleth)
+            scales.track(ctx, () => dead);
+        ctx.effect(() => {
+            const collection = source.features;
+            const scale = currentScale();
+            untrack(() => render(collection, scale));
+        });
+        ctx.effect(() => {
+            const keys = ctx.selectedKeys;
+            untrack(() => applySelection(keys));
+        });
+        return () => {
+            dead = true;
+        };
+    }
+    const plugin = {
+        id: pluginId,
+        label: layerLabel,
+        get dataset() {
+            return datasetOf(source);
+        },
+        setup,
+        legend,
+        selectable
+    };
+    if (options.listed ?? true)
+        plugin.features = features;
+    if (options.hoverable === false)
+        plugin.hoverable = false;
+    return plugin;
+}

package/dist/plugins/shared.d.ts

@@ -0,0 +1,6 @@
+import type { ExpressionSpecification } from "@maptiler/sdk";
+import type { FeatureHit } from "../core/plugin.js";
+/** 1 where the feature's `selected` state is set, else 0. */
+export declare const SELECTED_OPACITY: ExpressionSpecification;
+/** The hit for a rendered feature's properties (`refKey`, `name`), or null without a valid ref. */
+export declare function hitFromProps(pluginId: string, props: Record<string, unknown>): FeatureHit | null;

package/dist/plugins/shared.js

@@ -0,0 +1,18 @@
+import { decodeRef } from "../data/refs.js";
+/** 1 where the feature's `selected` state is set, else 0. */
+export const SELECTED_OPACITY = [
+    "case",
+    ["boolean", ["feature-state", "selected"], false],
+    1,
+    0
+];
+/** The hit for a rendered feature's properties (`refKey`, `name`), or null without a valid ref. */
+export function hitFromProps(pluginId, props) {
+    const refKey = props.refKey;
+    if (typeof refKey !== "string")
+        return null;
+    const ref = decodeRef(refKey);
+    if (!ref)
+        return null;
+    return { pluginId, ref, refKey, name: typeof props.name === "string" ? props.name : "" };
+}

package/dist/plugins/style.d.ts

@@ -0,0 +1,57 @@
+import type { ExpressionSpecification } from "@maptiler/sdk";
+import type { Level, Scale } from "../data/scale-types.js";
+/** Theme token read at plugin setup (getComputedStyle on the container) for unmatched values. */
+export declare const NEUTRAL_COLOR_VAR = "--muted";
+/** Concrete colors for map paint and marker images, read from the host's theme tokens. */
+export interface ThemeColors {
+    /** Values no level covers, and levels with an empty color: `--muted`. */
+    neutral: string;
+    /** The selection ring: `--highlight`, else `--primary`. */
+    highlight: string;
+    /** The check mark on the highlight: `--highlight-foreground`, else `--primary-foreground`. */
+    highlightForeground: string;
+    /** Marker and cluster outlines and cluster counts: `--foreground`. */
+    foreground: string;
+    /** Markers drawn muted by default (see `icon.mutedColor`): `--muted-foreground`. */
+    mutedForeground: string;
+}
+/**
+ * The last resort when the host defines none of a color's tokens (or no DOM, as in unit tests).
+ * Presentation only, never data, and the only hardcoded colors in the plugins.
+ */
+export declare const FALLBACK_THEME_COLORS: Readonly<ThemeColors>;
+/**
+ * Resolves the theme tokens on `container` (the `[data-mapsdk-map]` element) to colors MapLibre
+ * and marker images can use. Token values may be any CSS color (shadcn uses `oklch()`, which
+ * MapLibre can't parse), so each is drawn to a 1×1 canvas and read back as `rgba()`.
+ */
+export declare function themeColors(container: Element | null): ThemeColors;
+/**
+ * The raw values of every token `themeColors` reads, as one string: when it changes, the colors
+ * plugins baked into paint and images are stale.
+ */
+export declare function themeSignature(container: Element): string;
+type Output = string | number;
+/**
+ * What a lookup reads: the feature's `value` property, or an expression computing a value (e.g. a
+ * cluster's average). An expression that may have no value must be numeric and give
+ * `MISSING_VALUE` then (MapLibre won't mix null into a number expression).
+ */
+export type ValueInput = "value" | ExpressionSpecification;
+/** Breakpoint input for null and non-numeric values: below every real level. */
+export declare const MISSING_VALUE = -1;
+/**
+ * True where the input is a reading by `numericValue`'s rule: a number, or a non-blank numeric
+ * string (same blank-string test as `numeric`; "Infinity" is the same accepted gap). A string
+ * that two different `to-number` fallbacks both pass through converted.
+ */
+export declare function hasNumericValue(input: ValueInput): ExpressionSpecification;
+/** Per-level output for the level `input` falls in; `fallback` where no level applies. */
+export declare function levelLookup(scale: Scale, input: ValueInput, fallback: Output, pick: (level: Level) => Output | null): ExpressionSpecification;
+/** Fill color per level; unmatched values and levels with an empty color use `neutral`. */
+export declare function colorExpression(scale: Scale, property: "value", neutral: string): ExpressionSpecification;
+/** Opacity per level, or the plain `fallback` number when no level sets one. */
+export declare function opacityExpression(scale: Scale, property: "value", fallback: number): ExpressionSpecification | number;
+/** Level key per value ("" where no level applies), for filters and icon ids. */
+export declare function levelKeyExpression(scale: Scale, input: ValueInput): ExpressionSpecification;
+export {};