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

package/dist/plugins/shapes.svelte.js

@@ -0,0 +1,307 @@
+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);
+    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);
+            const lngLat = labelPoint(feature.geometry);
+            if (!ref || !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,
+                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;
+    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 {};

package/dist/plugins/style.js

@@ -0,0 +1,193 @@
+/** Theme token read at plugin setup (getComputedStyle on the container) for unmatched values. */
+export const NEUTRAL_COLOR_VAR = "--muted";
+/**
+ * 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 const FALLBACK_THEME_COLORS = {
+    neutral: "#9ca3af",
+    highlight: "#2563eb",
+    highlightForeground: "#ffffff",
+    foreground: "#111827",
+    mutedForeground: "#6b7280"
+};
+const THEME_TOKENS = {
+    neutral: [NEUTRAL_COLOR_VAR],
+    highlight: ["--highlight", "--primary"],
+    highlightForeground: ["--highlight-foreground", "--primary-foreground"],
+    foreground: ["--foreground"],
+    mutedForeground: ["--muted-foreground"]
+};
+/**
+ * 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 function themeColors(container) {
+    const style = container && typeof getComputedStyle === "function" ? getComputedStyle(container) : null;
+    const read = (names, fallback) => {
+        for (const name of names) {
+            const raw = style?.getPropertyValue(name).trim() ?? "";
+            if (raw && CSS.supports("color", raw))
+                return toRgba(raw, fallback);
+        }
+        return fallback;
+    };
+    const out = { ...FALLBACK_THEME_COLORS };
+    for (const key of Object.keys(THEME_TOKENS)) {
+        out[key] = read(THEME_TOKENS[key], FALLBACK_THEME_COLORS[key]);
+    }
+    return out;
+}
+/**
+ * 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 function themeSignature(container) {
+    const style = getComputedStyle(container);
+    return Object.values(THEME_TOKENS)
+        .flat()
+        .map((name) => style.getPropertyValue(name).trim())
+        .join("|");
+}
+/** A color canvas leaves `fillStyle` at when it rejects a value. */
+const SENTINEL = "#010203";
+function toRgba(color, fallback) {
+    const ctx = document.createElement("canvas").getContext("2d", { willReadFrequently: true });
+    if (!ctx)
+        return color;
+    ctx.fillStyle = SENTINEL;
+    ctx.fillStyle = color;
+    // Unchanged: canvas couldn't parse it (an assignment it rejects is ignored), so not black.
+    if (ctx.fillStyle === SENTINEL && color.toLowerCase() !== SENTINEL)
+        return fallback;
+    ctx.fillRect(0, 0, 1, 1);
+    const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
+    return `rgba(${r}, ${g}, ${b}, ${Math.round((a / 255) * 1000) / 1000})`;
+}
+/** Breakpoint input for null and non-numeric values: below every real level. */
+export const MISSING_VALUE = -1;
+const MISSING = MISSING_VALUE;
+function read(input) {
+    return typeof input === "string" ? ["get", input] : input;
+}
+/**
+ * The value as a number for a range lookup, like `levelFor`: a number, or a non-blank numeric
+ * string; anything else (null, missing, blank or non-numeric strings, booleans, arrays) is
+ * MISSING. `to-number` alone would read null, "", " " and false as 0 (the first level) and
+ * true as 1. There is no trim in expressions, so a string converting to 0 counts as blank unless
+ * it contains a "0" (every non-blank string Number() reads as 0 does).
+ *
+ * Accepted gap: "Infinity" and "1e999" convert to Infinity and step to the top level, while
+ * `levelFor` says NO_LEVEL (expressions have no clean finiteness check).
+ */
+function numeric(input) {
+    const v = ["var", "v"];
+    const n = ["var", "n"];
+    return [
+        "let",
+        "v",
+        read(input),
+        [
+            "case",
+            ["==", ["typeof", v], "number"],
+            ["to-number", v],
+            ["==", ["typeof", v], "string"],
+            [
+                "let",
+                "n",
+                ["to-number", v, MISSING],
+                ["case", ["all", ["==", n, 0], ["!", ["in", "0", ["to-string", v]]]], MISSING, n]
+            ],
+            MISSING
+        ]
+    ];
+}
+/**
+ * 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 function hasNumericValue(input) {
+    const v = ["var", "v"];
+    const a = ["var", "a"];
+    return [
+        "let",
+        "v",
+        read(input),
+        [
+            "case",
+            ["==", ["typeof", v], "number"],
+            true,
+            ["==", ["typeof", v], "string"],
+            [
+                "let",
+                "a",
+                ["to-number", v, -1],
+                [
+                    "all",
+                    ["==", a, ["to-number", v, -2]],
+                    ["!", ["all", ["==", a, 0], ["!", ["in", "0", v]]]]
+                ]
+            ],
+            false
+        ]
+    ];
+}
+/**
+ * Half-open range lookup matching `levelFor`: a level covers [min, max), the value `max` goes
+ * to the next level, and a gap or an unbounded-below input falls to `fallback`.
+ */
+function rangeStep(scale, input, fallback, pick) {
+    const stops = [];
+    let last = null;
+    const levels = scale.levels
+        .filter((l) => l.min !== null)
+        .sort((a, b) => a.min - b.min);
+    for (const level of levels) {
+        const min = level.min;
+        // Close a gap left by the previous level's max.
+        if (last !== null && last < min)
+            stops.push(last, fallback);
+        stops.push(min, pick(level) ?? fallback);
+        last = level.max ?? null;
+        if (last === null)
+            break;
+    }
+    if (last !== null)
+        stops.push(last, fallback);
+    if (stops.length === 0)
+        return ["literal", fallback];
+    return ["step", numeric(input), fallback, ...stops];
+}
+function categoryMatch(scale, input, fallback, pick) {
+    const arms = [];
+    for (const level of scale.levels) {
+        if (level.value === null)
+            continue;
+        arms.push(level.value, pick(level) ?? fallback);
+    }
+    if (arms.length === 0)
+        return ["literal", fallback];
+    return ["match", read(input), ...arms, fallback];
+}
+/** Per-level output for the level `input` falls in; `fallback` where no level applies. */
+export function levelLookup(scale, input, fallback, pick) {
+    return scale.kind === "range"
+        ? rangeStep(scale, input, fallback, pick)
+        : categoryMatch(scale, input, fallback, pick);
+}
+/** Fill color per level; unmatched values and levels with an empty color use `neutral`. */
+export function colorExpression(scale, property, neutral) {
+    return levelLookup(scale, property, neutral, (level) => level.color || null);
+}
+/** Opacity per level, or the plain `fallback` number when no level sets one. */
+export function opacityExpression(scale, property, fallback) {
+    if (!scale.levels.some((level) => level.opacity !== null))
+        return fallback;
+    return levelLookup(scale, property, fallback, (level) => level.opacity);
+}
+/** Level key per value ("" where no level applies), for filters and icon ids. */
+export function levelKeyExpression(scale, input) {
+    return levelLookup(scale, input, "", (level) => level.key);
+}