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

package/dist/data/refs.js

@@ -0,0 +1,61 @@
+export function encodeRef(ref) {
+    switch (ref.kind) {
+        case "monitor":
+            return `monitor:${ref.id}`;
+        case "region":
+            return `region:${ref.type}:${ref.code}`;
+        case "feature":
+            return `feature:${ref.id}`;
+    }
+}
+export function decodeRef(key) {
+    const first = key.indexOf(":");
+    if (first < 0)
+        return null;
+    const kind = key.slice(0, first);
+    const rest = key.slice(first + 1);
+    if (kind === "monitor" || kind === "feature") {
+        return rest ? { kind, id: rest } : null;
+    }
+    if (kind === "region") {
+        const second = rest.indexOf(":");
+        if (second <= 0)
+            return null;
+        const code = rest.slice(second + 1);
+        return code ? { kind, type: rest.slice(0, second), code } : null;
+    }
+    return null;
+}
+export function selectionId(ref) {
+    switch (ref.kind) {
+        case "monitor":
+            return ref.id;
+        case "region":
+            return `${ref.type}:${ref.code}`;
+        case "feature":
+            return null;
+    }
+}
+export function toPlaceRef(ref) {
+    switch (ref.kind) {
+        case "monitor":
+            return { kind: "monitor", id: ref.id };
+        case "region":
+            return { kind: "region", type: ref.type, code: ref.code };
+        case "feature":
+            return null;
+    }
+}
+export function fromPlaceRef(place) {
+    if (place.kind === "monitor" && typeof place.id === "string" && place.id) {
+        return { kind: "monitor", id: place.id };
+    }
+    if (place.kind === "region" &&
+        typeof place.type === "string" &&
+        typeof place.code === "string" &&
+        place.type &&
+        place.code) {
+        return { kind: "region", type: place.type, code: place.code };
+    }
+    return null;
+}

package/dist/data/scale-types.d.ts

@@ -0,0 +1,7 @@
+import type { Scale, ScaleLevel, ScaleSource } from "@sjvair/sdk/meta/types";
+export type { Scale, ScaleSource };
+export type Level = ScaleLevel;
+export interface ScaleRef {
+    dataset: string;
+    entryType: string;
+}

package/dist/data/scale-types.js

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

package/dist/data/scale.d.ts

@@ -0,0 +1,13 @@
+import type { Level, Scale } from "./scale-types.js";
+/** Returned by `levelFor` when no level covers the value. */
+export declare const NO_LEVEL: unique symbol;
+/**
+ * A reading as a number: a finite number, or a non-blank string that reads as one; else null.
+ * The one rule for what counts as a reading (levels, averages, tooltips).
+ */
+export declare function numericValue(value: number | string | null | undefined): number | null;
+/**
+ * Find the level a value falls in. Range levels are half-open, [min, max), and a null max
+ * is unbounded. Numeric strings are coerced for range scales only.
+ */
+export declare function levelFor(value: number | string | null | undefined, scale: Scale): Level | typeof NO_LEVEL;

package/dist/data/scale.js

@@ -0,0 +1,27 @@
+/** Returned by `levelFor` when no level covers the value. */
+export const NO_LEVEL = Symbol("no-level");
+/**
+ * A reading as a number: a finite number, or a non-blank string that reads as one; else null.
+ * The one rule for what counts as a reading (levels, averages, tooltips).
+ */
+export function numericValue(value) {
+    if (typeof value !== "number" && (typeof value !== "string" || value.trim() === ""))
+        return null;
+    const n = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(n) ? n : null;
+}
+/**
+ * Find the level a value falls in. Range levels are half-open, [min, max), and a null max
+ * is unbounded. Numeric strings are coerced for range scales only.
+ */
+export function levelFor(value, scale) {
+    if (value === null || value === undefined)
+        return NO_LEVEL;
+    if (scale.kind === "category") {
+        return scale.levels.find((level) => level.value === value) ?? NO_LEVEL;
+    }
+    const n = numericValue(value);
+    if (n === null)
+        return NO_LEVEL;
+    return (scale.levels.find((level) => level.min !== null && n >= level.min && (level.max == null || n < level.max)) ?? NO_LEVEL);
+}

package/dist/data/selection.d.ts

@@ -0,0 +1,13 @@
+import type { FeatureRef, SelectionMode, SpatialSelection } from "./types.js";
+export interface PickGesture {
+    additive: boolean;
+}
+export declare function selectionKind(ref: FeatureRef): "monitors" | "regions" | null;
+export declare function applyPick(current: SpatialSelection | null, ref: FeatureRef, mode: SelectionMode, gesture: PickGesture): SpatialSelection | null;
+/**
+ * A modifier-click (or a card's Select/Remove): toggles `ref`. In `single` mode it is the
+ * selection, or `null` when it already is; in `multiple` mode it is added or removed (another
+ * kind starts a new selection, and removing the last id gives `null`).
+ */
+export declare function toggleInSelection(current: SpatialSelection | null, ref: FeatureRef, mode: SelectionMode): SpatialSelection | null;
+export declare function selectionKeys(sel: SpatialSelection | null): Set<string>;

package/dist/data/selection.js

@@ -0,0 +1,52 @@
+import { selectionId } from "./refs.js";
+export function selectionKind(ref) {
+    switch (ref.kind) {
+        case "monitor":
+            return "monitors";
+        case "region":
+            return "regions";
+        case "feature":
+            return null;
+    }
+}
+export function applyPick(current, ref, mode, gesture) {
+    const kind = selectionKind(ref);
+    const id = selectionId(ref);
+    if (mode === "none" || kind === null || id === null)
+        return current;
+    if (mode === "single" || !gesture.additive || !current || current.kind !== kind) {
+        return { kind, ids: [id] };
+    }
+    if (current.ids.includes(id)) {
+        const ids = current.ids.filter((x) => x !== id);
+        return ids.length ? { kind, ids } : null;
+    }
+    return { kind, ids: [...current.ids, id] };
+}
+/**
+ * A modifier-click (or a card's Select/Remove): toggles `ref`. In `single` mode it is the
+ * selection, or `null` when it already is; in `multiple` mode it is added or removed (another
+ * kind starts a new selection, and removing the last id gives `null`).
+ */
+export function toggleInSelection(current, ref, mode) {
+    const kind = selectionKind(ref);
+    const id = selectionId(ref);
+    if (mode === "none" || kind === null || id === null)
+        return current;
+    const has = current?.kind === kind && current.ids.includes(id);
+    if (mode === "single")
+        return has ? null : { kind, ids: [id] };
+    if (!current || current.kind !== kind)
+        return { kind, ids: [id] };
+    if (has) {
+        const ids = current.ids.filter((x) => x !== id);
+        return ids.length ? { kind, ids } : null;
+    }
+    return { kind, ids: [...current.ids, id] };
+}
+export function selectionKeys(sel) {
+    if (!sel)
+        return new Set();
+    const prefix = sel.kind === "monitors" ? "monitor:" : "region:";
+    return new Set(sel.ids.map((id) => prefix + id));
+}

package/dist/data/static-source.d.ts

@@ -0,0 +1,4 @@
+import type { FeatureCollection, Geometry } from "geojson";
+import type { Scale, ScaleRef } from "./scale-types.js";
+import type { DataSource, MapFeatureProperties } from "./types.js";
+export declare function staticSource<P extends MapFeatureProperties>(features: FeatureCollection<Geometry, P>, scale: ScaleRef | Scale | null): DataSource<P>;

package/dist/data/static-source.js

@@ -0,0 +1,3 @@
+export function staticSource(features, scale) {
+    return { status: { state: "ready" }, features, scale };
+}

package/dist/data/types.d.ts

@@ -0,0 +1,74 @@
+import type { FeatureCollection, Geometry } from "geojson";
+import type { Scale, ScaleRef } from "./scale-types.js";
+export type FeatureRef = {
+    kind: "monitor";
+    id: string;
+} | {
+    kind: "region";
+    type: string;
+    code: string;
+} | {
+    kind: "feature";
+    id: string;
+};
+export type SpatialSelection = {
+    kind: "monitors" | "regions";
+    ids: string[];
+};
+export type SelectionMode = "none" | "single" | "multiple";
+export interface MapFeatureProperties {
+    refKey: string;
+    name: string;
+    value: number | string | null;
+}
+/** An HMS fire on the map: a group of nearby detections, or a single detection. */
+export interface FireFeatureProperties extends MapFeatureProperties {
+    /** Set on a group: how many detections it averages. Absent on a single detection. */
+    count?: number;
+}
+/** A monitor on the map: what the monitors preset draws and its tooltips show. */
+export interface MonitorFeatureProperties extends MapFeatureProperties {
+    /** The server's monitor type (e.g. "purpleair", "airnow"); picks the marker shape. */
+    type: string;
+    isActive: boolean;
+    isSjvair: boolean;
+    location: "inside" | "outside";
+    /** When the reading was taken (ISO 8601), for the tooltip. */
+    timestamp?: string | null;
+}
+export type DataStatus = {
+    state: "loading";
+} | {
+    state: "ready";
+} | {
+    state: "error";
+    error: unknown;
+    retry(): void;
+} | {
+    state: "unavailable";
+    reason: string;
+};
+export interface DataSource<P extends MapFeatureProperties = MapFeatureProperties> {
+    readonly status: DataStatus;
+    readonly features: FeatureCollection<Geometry, P> | null;
+    readonly scale: ScaleRef | Scale | null;
+}
+/**
+ * A collocation site: drawn at its reference monitor with that monitor's type, location,
+ * activity, and reading, plus the collocated monitor's reading. Readings are null when a
+ * monitor isn't in the monitors store (inactive, filtered out, or not loaded yet).
+ */
+export interface CollocationFeatureProperties extends MonitorFeatureProperties {
+    /**
+     * The reference monitor's own name (the tooltip shows it); null when it isn't in the
+     * monitors store.
+     */
+    referenceName: string | null;
+    colocatedId: string;
+    /** Null when the collocated monitor isn't in the monitors store. */
+    colocatedName: string | null;
+    /** The collocated monitor's type, for its tooltip's "(N avg)" note; null when unknown. */
+    colocatedType: string | null;
+    colocatedValue: number | null;
+    colocatedTimestamp: string | null;
+}

package/dist/data/types.js

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

package/dist/index.d.ts

@@ -0,0 +1,59 @@
+import { type CreateMapOptions, type MapContext } from "./core/create-map.svelte.js";
+export { defaultBasemaps } from "./view/create-gl-map.js";
+export { default as MapView } from "./view/MapView.svelte";
+export type { FeatureListOptions, ListPosition } from "./view/list-placement.js";
+export { default as Legend } from "./ui/Legend.svelte";
+export { default as FeatureList } from "./ui/FeatureList.svelte";
+export { default as MapTooltip } from "./ui/MapTooltip.svelte";
+export { default as SelectionBar } from "./ui/SelectionBar.svelte";
+export { default as ViewSummary } from "./ui/ViewSummary.svelte";
+export { default as MapControls } from "./ui/MapControls.svelte";
+export { legendSection } from "./ui/legend-data.js";
+export type { LegendBar as LegendBarData, LegendSection } from "./ui/legend-data.js";
+export { rowLabel } from "./ui/feature-list.js";
+export type { SortBy } from "./ui/feature-list.js";
+export { geometryBbox, intersectsBounds } from "./core/shape-view.js";
+export type { Bbox } from "./core/shape-view.js";
+export { pointsPlugin } from "./plugins/points.svelte.js";
+export type { ClusterInfo, ClusterLayerArgs, PointsOptions, PointsTooltipEnv } from "./plugins/points.svelte.js";
+export type { ClusterLayers } from "./plugins/points-clusters.js";
+export { colorExpression, levelKeyExpression, opacityExpression } from "./plugins/style.js";
+export type { ThemeColors, ValueInput } from "./plugins/style.js";
+export { shapesPlugin } from "./plugins/shapes.svelte.js";
+export type { ShapesOptions } from "./plugins/shapes.svelte.js";
+export { monitorShape, monitorsPlugin } from "./presets/monitors.js";
+export type { MonitorShape, MonitorsPluginOptions } from "./presets/monitors.js";
+export { regionsPlugin } from "./presets/regions.js";
+export type { RegionsPluginOptions } from "./presets/regions.js";
+export { calHeatScorePlugin } from "./presets/calheatscore.js";
+export type { CalHeatScorePluginOptions } from "./presets/calheatscore.js";
+export { forecastZonesPlugin } from "./presets/forecast-zones.js";
+export type { ForecastZonesPluginOptions } from "./presets/forecast-zones.js";
+export { summaryText } from "./ui/view-summary.js";
+export { getMapContext } from "./core/context.js";
+export type { BlockingClick, FeatureHit, FeatureListItem, LayerSpecWithoutId, LegendData, MapPlugin, PluginContext, Providers } from "./core/plugin.js";
+export type { GlMapLike } from "./core/gl.js";
+export type { CustomLayerInterface } from "@maptiler/sdk";
+export type { Hovered } from "./core/interactions.svelte.js";
+export type { BasemapConfig } from "./core/basemap.svelte.js";
+export type { Bounds, CameraState, CameraTarget, CreateMapOptions, FeatureClickHandler, MapConfig, MapContext, PluginOptions } from "./core/create-map.svelte.js";
+/**
+ * The attached MapTiler `Map`, or `null` while detached: an escape hatch for markers and popups
+ * only. The host must never add sources or layers through it; plugins own those.
+ */
+export declare function maptilerMap(map: MapContext): import("@maptiler/sdk").Map | null;
+/**
+ * Creates a map's state and services; show it with `<MapView map={…} />`. Without
+ * `config.basemaps`, the basemaps are MapTiler Streets v4 and its variants, as on today's map.
+ */
+export declare function createMap(options: CreateMapOptions): MapContext;
+export { hmsSmokePlugin } from "./presets/hms-smoke.js";
+export type { HmsSmokePluginOptions } from "./presets/hms-smoke.js";
+export { hmsFirePlugin } from "./presets/hms-fire.js";
+export type { HmsFirePluginOptions } from "./presets/hms-fire.js";
+export { cleanFires, groupFires } from "./presets/fire-groups.js";
+export type { FireDetection, FireGroup } from "./presets/fire-groups.js";
+export { collocationSitesPlugin, COLLOCATION_CROSSHAIR_COLOR } from "./presets/collocation-sites.js";
+export type { CollocationSitesPluginOptions } from "./presets/collocation-sites.js";
+export { circle, CROSSHAIR_ICON_SIZE, square, triangle, withCrosshair } from "./plugins/icons.js";
+export type { CardContext, CardOptions } from "./ui/card.js";

package/dist/index.js

@@ -0,0 +1,42 @@
+import { createMap as createMapContext } from "./core/create-map.svelte.js";
+import { defaultBasemaps } from "./view/create-gl-map.js";
+export { defaultBasemaps } from "./view/create-gl-map.js";
+export { default as MapView } from "./view/MapView.svelte";
+export { default as Legend } from "./ui/Legend.svelte";
+export { default as FeatureList } from "./ui/FeatureList.svelte";
+export { default as MapTooltip } from "./ui/MapTooltip.svelte";
+export { default as SelectionBar } from "./ui/SelectionBar.svelte";
+export { default as ViewSummary } from "./ui/ViewSummary.svelte";
+export { default as MapControls } from "./ui/MapControls.svelte";
+export { legendSection } from "./ui/legend-data.js";
+export { rowLabel } from "./ui/feature-list.js";
+export { geometryBbox, intersectsBounds } from "./core/shape-view.js";
+export { pointsPlugin } from "./plugins/points.svelte.js";
+export { colorExpression, levelKeyExpression, opacityExpression } from "./plugins/style.js";
+export { shapesPlugin } from "./plugins/shapes.svelte.js";
+export { monitorShape, monitorsPlugin } from "./presets/monitors.js";
+export { regionsPlugin } from "./presets/regions.js";
+export { calHeatScorePlugin } from "./presets/calheatscore.js";
+export { forecastZonesPlugin } from "./presets/forecast-zones.js";
+export { summaryText } from "./ui/view-summary.js";
+export { getMapContext } from "./core/context.js";
+/**
+ * The attached MapTiler `Map`, or `null` while detached: an escape hatch for markers and popups
+ * only. The host must never add sources or layers through it; plugins own those.
+ */
+export function maptilerMap(map) {
+    return map.gl;
+}
+/**
+ * Creates a map's state and services; show it with `<MapView map={…} />`. Without
+ * `config.basemaps`, the basemaps are MapTiler Streets v4 and its variants, as on today's map.
+ */
+export function createMap(options) {
+    const basemaps = options.config.basemaps ?? defaultBasemaps();
+    return createMapContext({ ...options, config: { ...options.config, basemaps } });
+}
+export { hmsSmokePlugin } from "./presets/hms-smoke.js";
+export { hmsFirePlugin } from "./presets/hms-fire.js";
+export { cleanFires, groupFires } from "./presets/fire-groups.js";
+export { collocationSitesPlugin, COLLOCATION_CROSSHAIR_COLOR } from "./presets/collocation-sites.js";
+export { circle, CROSSHAIR_ICON_SIZE, square, triangle, withCrosshair } from "./plugins/icons.js";

package/dist/plugins/icons.d.ts

@@ -0,0 +1,21 @@
+export declare function square(color: string, borderWidth: number, borderColor?: string): string;
+export declare function circle(color: string, borderWidth: number, borderColor?: string): string;
+export declare function triangle(color: string, borderWidth: number, borderColor?: string): string;
+/** The size of a `withCrosshair` image: a 24px marker plus the crosshair around it (56px). */
+export declare const CROSSHAIR_ICON_SIZE: number;
+/**
+ * A 24px marker SVG (`circle`, `square`, `triangle`) centered in a crosshair of `color`, as
+ * monitor-map draws collocation sites. The result is `CROSSHAIR_ICON_SIZE` pixels square.
+ */
+export declare function withCrosshair(baseSvg: string, color: string): string;
+export declare function fireIcon(color: string, size: number): string;
+/** Room around the marker for the ring and the check badge. */
+export declare const SELECTED_OVERLAY_PADDING = 6;
+/**
+ * The selection mark drawn over a selected marker `size` pixels across: a ring around it in
+ * `highlight` plus a check mark badge, so selection never relies on color alone. The image is
+ * `size + 2 * SELECTED_OVERLAY_PADDING` pixels square, centered on the marker. Colors are
+ * concrete values read from the `--highlight` and `--highlight-foreground` tokens at setup.
+ */
+export declare function selectedOverlay(highlight: string, checkColor: string, size: number): string;
+export declare function asDataURI(svg: string): string;

package/dist/plugins/icons.js

@@ -0,0 +1,73 @@
+import { darken } from "color2k";
+// Marker shapes ported from monitor-map (src/lib/map/icons.ts). Shapes and sizes are
+// presentation; every color comes in from a scale level or a theme token.
+/**
+ * A slightly darker stroke for a fill color. color2k throws on an empty or unparseable color
+ * (monitor-map crashed on `darken("")`), so those keep the color itself.
+ */
+function strokeFor(color) {
+    try {
+        return darken(color, 0.1);
+    }
+    catch {
+        return color;
+    }
+}
+export function square(color, borderWidth, borderColor) {
+    return `<svg width="24" height="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+    <rect x="${borderWidth / 2}" y="${borderWidth / 2}" width="${24 - borderWidth}" height="${24 - borderWidth}"
+      fill="${color}" stroke="${strokeFor(borderColor ?? color)}" stroke-width="${borderWidth}"/>
+  </svg>`;
+}
+export function circle(color, borderWidth, borderColor) {
+    return `<svg width="24" height="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+    <circle cx="12" cy="12" r="${12 - borderWidth}" fill="${color}" stroke="${strokeFor(borderColor ?? color)}" stroke-width="${borderWidth}"/>
+  </svg>`;
+}
+export function triangle(color, borderWidth, borderColor) {
+    const points = `${12},${borderWidth} ${24 - borderWidth},${24 - borderWidth} ${borderWidth},${24 - borderWidth}`;
+    return `<svg width="24" height="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+    <polygon points="${points}"
+      fill="${color}" stroke="${strokeFor(borderColor ?? color)}" stroke-width="${borderWidth}"/>
+  </svg>`;
+}
+// monitor-map's collocation crosshair (src/lib/map/icons.ts): a ring with ticks around a marker.
+const CROSSHAIR_PATH = "M495.9 248H392c-4.4 0-8 3.6-8 8s3.6 8 8 8H495.9C491.7 390.2 390.2 491.7 264 495.9V392c0-4.4-3.6-8-8-8s-8 3.6-8 8V495.9C121.8 491.7 20.3 390.2 16.1 264H120c4.4 0 8-3.6 8-8s-3.6-8-8-8H16.1C20.3 121.8 121.8 20.3 248 16.1V120c0 4.4 3.6 8 8 8s8-3.6 8-8V16.1C390.2 20.3 491.7 121.8 495.9 248zM0 256a256 256 0 1 0 512 0A256 256 0 1 0 0 256z";
+const CROSSHAIR_PADDING = 16;
+/** The size of a `withCrosshair` image: a 24px marker plus the crosshair around it (56px). */
+export const CROSSHAIR_ICON_SIZE = 24 + CROSSHAIR_PADDING * 2;
+/**
+ * A 24px marker SVG (`circle`, `square`, `triangle`) centered in a crosshair of `color`, as
+ * monitor-map draws collocation sites. The result is `CROSSHAIR_ICON_SIZE` pixels square.
+ */
+export function withCrosshair(baseSvg, color) {
+    const size = CROSSHAIR_ICON_SIZE;
+    const inner = baseSvg.replace("<svg ", `<svg x="${CROSSHAIR_PADDING}" y="${CROSSHAIR_PADDING}" `);
+    return `<svg width="${size}" height="${size}" viewBox="0 0 ${size} ${size}" xmlns="http://www.w3.org/2000/svg">${inner}<svg x="0" y="0" width="${size}" height="${size}" viewBox="-8 -8 528 528"><path d="${CROSSHAIR_PATH}" fill="${color}" stroke="${color}" stroke-width="5"/></svg></svg>`;
+}
+export function fireIcon(color, size) {
+    return `<svg width="${size}" height="${size}" viewBox="0 -960 960 960" xmlns="http://www.w3.org/2000/svg" fill="${color}"><path d="M200-400q0 52 21 98.5t60 81.5q-1-5-1-9v-9q0-32 12-60t35-51l113-111 113 111q23 23 35 51t12 60v9q0 4-1 9 39-35 60-81.5t21-98.5q0-50-18.5-94.5T608-574q-20 13-42 19.5t-45 6.5q-62 0-107.5-41T361-690q-39 33-69 68.5t-50.5 72Q221-513 210.5-475T200-400Zm240 52-57 56q-11 11-17 25t-6 29q0 32 23.5 55t56.5 23q33 0 56.5-23t23.5-55q0-16-6-29.5T497-292l-57-56Zm0-492v132q0 34 23.5 57t57.5 23q18 0 33.5-7.5T582-658l18-22q74 42 117 117t43 163q0 134-93 227T440-80q-134 0-227-93t-93-227q0-129 86.5-245T440-840Zm400 320q-17 0-28.5-11.5T800-560q0-17 11.5-28.5T840-600q17 0 28.5 11.5T880-560q0 17-11.5 28.5T840-520Zm-40-120v-200h80v200h-80Z"/></svg>`;
+}
+/** Room around the marker for the ring and the check badge. */
+export const SELECTED_OVERLAY_PADDING = 6;
+/**
+ * The selection mark drawn over a selected marker `size` pixels across: a ring around it in
+ * `highlight` plus a check mark badge, so selection never relies on color alone. The image is
+ * `size + 2 * SELECTED_OVERLAY_PADDING` pixels square, centered on the marker. Colors are
+ * concrete values read from the `--highlight` and `--highlight-foreground` tokens at setup.
+ */
+export function selectedOverlay(highlight, checkColor, size) {
+    const total = size + 2 * SELECTED_OVERLAY_PADDING;
+    const c = total / 2;
+    const ring = size / 2 + 2.5;
+    const b = SELECTED_OVERLAY_PADDING;
+    const bx = total - b;
+    return `<svg width="${total}" height="${total}" viewBox="0 0 ${total} ${total}" xmlns="http://www.w3.org/2000/svg">
+    <circle cx="${c}" cy="${c}" r="${ring}" fill="none" stroke="${highlight}" stroke-width="3"/>
+    <circle cx="${bx}" cy="${b}" r="${b - 0.5}" fill="${highlight}" stroke="${checkColor}" stroke-width="1"/>
+    <path d="M${bx - 2.5} ${b} l1.75 1.75 l3.25 -3.5" fill="none" stroke="${checkColor}" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+  </svg>`;
+}
+export function asDataURI(svg) {
+    return `data:image/svg+xml;utf8,${encodeURIComponent(svg)}`;
+}

package/dist/plugins/points-clusters.d.ts

@@ -0,0 +1,60 @@
+import type { ExpressionSpecification, FilterSpecification } from "@maptiler/sdk";
+import type { GlMapLike } from "../core/gl.js";
+import type { BlockingClick, FeatureHit, LayerSpecWithoutId } from "../core/plugin.js";
+import type { Scale } from "../data/scale-types.js";
+import type { MapFeatureProperties } from "../data/types.js";
+import type { ThemeColors } from "./style.js";
+/** A hovered cluster bubble. */
+export interface ClusterInfo<P extends MapFeatureProperties> {
+    group: string;
+    pointCount: number;
+    /** The cluster feature's properties, including `cluster.properties` aggregates. */
+    properties: Readonly<Record<string, unknown>>;
+    /** Every point in the cluster; rejects if the cluster is gone, empty once torn down. */
+    leaves(): Promise<Array<{
+        props: P;
+        lngLat: [number, number];
+    }>>;
+}
+/** What custom cluster layers are built from. */
+export interface ClusterLayerArgs {
+    group: string;
+    sourceId: string;
+    scale: Scale;
+    theme: ThemeColors;
+    /**
+     * The `icon-image` for the plugin's icon of `category` at the level `levelKey` evaluates to
+     * (use `levelKeyExpression`); registers that category's images.
+     */
+    iconImage(category: string, levelKey: ExpressionSpecification): ExpressionSpecification;
+    /** The `icon-size` that shows an icon at its `size` (images are drawn larger for HiDPI). */
+    iconSizeScale: number;
+}
+export type ClusterLayers = Array<{
+    local: string;
+    spec: LayerSpecWithoutId;
+}>;
+export declare const CLUSTERED: FilterSpecification;
+/** Cluster bubbles: a neutral circle with the count. */
+export declare function defaultClusterLayers({ sourceId, theme }: ClusterLayerArgs): ClusterLayers;
+/** What a cluster hover hit names: the data generation it was hovered in, the id, the group. */
+export interface ClusterRef {
+    generation: number;
+    clusterId: number;
+    group: string;
+}
+/**
+ * The hover hit for a bubble: a `{ kind: "feature", id: "cluster:<generation>:<id>:<group>" }`
+ * ref (cluster ids are only meaningful for the data they were made from) carrying the bubble's
+ * properties. No side effects: lookups call it too.
+ */
+export declare function clusterHit(pluginId: string, generation: number, group: string, props: Record<string, unknown>): FeatureHit | null;
+/** The cluster a hover hit names, or null for any other hit. */
+export declare function parseClusterHit(hit: FeatureHit): ClusterRef | null;
+/** A cluster's points, from its source; `[]` once `isDead`. */
+export declare function clusterLeaves<P extends MapFeatureProperties>(gl: GlMapLike, sourceId: string, clusterId: number, pointCount: number, isDead: () => boolean): Promise<Array<{
+    props: P;
+    lngLat: [number, number];
+}>>;
+/** Zooms in far enough to expand a clicked bubble; no animation under reduced motion. */
+export declare function zoomIntoCluster(gl: GlMapLike, sourceId: string, feature: BlockingClick, isDead: () => boolean, pluginId: string): void;

package/dist/plugins/points-clusters.js

@@ -0,0 +1,93 @@
+import { encodeRef } from "../data/refs.js";
+export const CLUSTERED = ["has", "point_count"];
+function prefersReducedMotion() {
+    return globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;
+}
+/** Cluster bubbles: a neutral circle with the count. */
+export function defaultClusterLayers({ sourceId, theme }) {
+    return [
+        {
+            local: "clusters",
+            spec: {
+                type: "circle",
+                source: sourceId,
+                filter: CLUSTERED,
+                paint: {
+                    "circle-radius": ["step", ["get", "point_count"], 12, 10, 16, 25, 20],
+                    "circle-color": theme.neutral,
+                    "circle-stroke-color": theme.foreground,
+                    "circle-stroke-width": 1
+                }
+            }
+        },
+        {
+            local: "cluster-count",
+            spec: {
+                type: "symbol",
+                source: sourceId,
+                filter: CLUSTERED,
+                layout: {
+                    "text-field": ["get", "point_count_abbreviated"],
+                    "text-size": 12,
+                    "text-allow-overlap": true
+                },
+                paint: { "text-color": theme.foreground }
+            }
+        }
+    ];
+}
+const CLUSTER_ID = /^cluster:(\d+):(\d+):(.*)$/s;
+/**
+ * The hover hit for a bubble: a `{ kind: "feature", id: "cluster:<generation>:<id>:<group>" }`
+ * ref (cluster ids are only meaningful for the data they were made from) carrying the bubble's
+ * properties. No side effects: lookups call it too.
+ */
+export function clusterHit(pluginId, generation, group, props) {
+    const clusterId = props.cluster_id;
+    if (typeof clusterId !== "number")
+        return null;
+    const ref = { kind: "feature", id: `cluster:${generation}:${clusterId}:${group}` };
+    return { pluginId, ref, refKey: encodeRef(ref), name: "", properties: { ...props } };
+}
+/** The cluster a hover hit names, or null for any other hit. */
+export function parseClusterHit(hit) {
+    if (hit.ref.kind !== "feature")
+        return null;
+    const match = CLUSTER_ID.exec(hit.ref.id);
+    if (!match)
+        return null;
+    return { generation: Number(match[1]), clusterId: Number(match[2]), group: match[3] };
+}
+/** A cluster's points, from its source; `[]` once `isDead`. */
+export async function clusterLeaves(gl, sourceId, clusterId, pointCount, isDead) {
+    const clusters = isDead() ? undefined : gl.getSource(sourceId);
+    if (!clusters)
+        return [];
+    const leaves = await clusters.getClusterLeaves(clusterId, pointCount, 0);
+    if (isDead())
+        return [];
+    return leaves.flatMap((leaf) => leaf.geometry.type === "Point"
+        ? [
+            {
+                props: leaf.properties,
+                lngLat: leaf.geometry.coordinates.slice(0, 2)
+            }
+        ]
+        : []);
+}
+/** Zooms in far enough to expand a clicked bubble; no animation under reduced motion. */
+export function zoomIntoCluster(gl, sourceId, feature, isDead, pluginId) {
+    const clusterId = feature.properties.cluster_id;
+    if (typeof clusterId !== "number" || feature.geometry.type !== "Point")
+        return;
+    const [lng, lat] = feature.geometry.coordinates;
+    const clusters = gl.getSource(sourceId);
+    clusters?.getClusterExpansionZoom(clusterId).then((zoom) => {
+        if (isDead())
+            return;
+        gl.easeTo({ center: [lng, lat], zoom, ...(prefersReducedMotion() && { duration: 0 }) });
+    }, (error) => {
+        if (!isDead())
+            console.warn(`map-sdk: plugin "${pluginId}" could not expand a cluster`, error);
+    });
+}