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

package/dist/core/plugin.d.ts

@@ -0,0 +1,155 @@
+import type { CustomLayerInterface, LayerSpecification, SourceSpecification } from "@maptiler/sdk";
+import type { Geometry } from "geojson";
+import type { Snippet } from "svelte";
+import type { FormatProvider } from "../data/format.js";
+import type { MessageProvider } from "../data/messages.js";
+import type { MetadataProvider } from "../data/metadata.js";
+import type { NO_LEVEL } from "../data/scale.js";
+import type { Level, Scale } from "../data/scale-types.js";
+import type { DataStatus, FeatureRef } from "../data/types.js";
+import type { GlMapLike } from "./gl.js";
+export type Providers = {
+    metadata: MetadataProvider;
+    messages: MessageProvider;
+    format: FormatProvider;
+};
+/**
+ * A layer spec without its id (the host assigns it). Distributive: `Omit` over the
+ * `LayerSpecification` union would keep only the keys every layer type shares, losing `source`.
+ */
+export type LayerSpecWithoutId = LayerSpecification extends infer L ? L extends unknown ? Omit<L, "id"> : never : never;
+export interface FeatureHit {
+    pluginId: string;
+    ref: FeatureRef;
+    refKey: string;
+    name: string;
+    /**
+     * The rendered feature's properties, for hover content of a hit no plugin lists (e.g. a
+     * cluster bubble's count and aggregates). Unset for ordinary hits.
+     */
+    properties?: Readonly<Record<string, unknown>>;
+}
+/** The topmost feature of a blocking layer that was clicked. */
+export interface BlockingClick {
+    properties: Record<string, unknown>;
+    geometry: Geometry;
+}
+export interface FeatureListItem {
+    refKey: string;
+    ref: FeatureRef;
+    name: string;
+    value: number | string | null;
+    level: Level | typeof NO_LEVEL;
+    units: string;
+    /**
+     * Decimal places to show a numeric `value` with (the built-in plugins take it from the
+     * metadata's display hint). Without it the value is formatted as given.
+     */
+    precision?: number;
+    lngLat: [number, number];
+    selectable: boolean;
+    /**
+     * A short text about a feature with no level (e.g. "Level 2 charger"), shown where its level
+     * would be: in the feature list, its row's accessible name, and the generic tooltip. Ignored
+     * when the item has a level.
+     */
+    detail?: string;
+}
+export type LegendData = {
+    pluginId: string;
+    title: string;
+    units: string;
+    scale: Scale;
+    /**
+     * `"gradient"` or `"blocks"` (labeled swatches with the levels' own labels). Absent: a
+     * gradient for range scales and blocks for category scales.
+     */
+    display?: "gradient" | "blocks";
+} | {
+    pluginId: string;
+    status: DataStatus;
+};
+export interface ClickEvent {
+    hits: FeatureHit[];
+    additive: boolean;
+    lngLat: [number, number];
+}
+/**
+ * What a plugin's `setup` gets. Everything added through it is removed automatically when the
+ * plugin is torn down, whether or not the plugin's own teardown cleans up.
+ */
+export interface PluginContext {
+    /**
+     * The GL map. Don't use it after teardown: do late async work (an image that finishes
+     * loading, a fetch) through the context's methods, which do nothing once torn down.
+     */
+    readonly gl: GlMapLike;
+    /** `${mapUid}:${pluginId}:${local}` */
+    id(local: string): string;
+    readonly metadata: MetadataProvider;
+    readonly messages: MessageProvider;
+    readonly format: FormatProvider;
+    /** Returns the namespaced id; removed on teardown. */
+    addSource(local: string, spec: SourceSpecification): string;
+    /** Returns the namespaced id; removed on teardown, before sources. */
+    addLayer(local: string, spec: LayerSpecWithoutId): string;
+    /**
+     * Adds a MapLibre custom layer (e.g. a wind layer from a library the host adds) in the
+     * plugin's draw-order slot, with the same lifecycle as `addLayer`. `create` gets the
+     * namespaced id, which the layer must use; the object it returns is added as is, never copied,
+     * and `create` runs again on each restyle, so build a fresh layer every time. Returns the id.
+     */
+    addCustomLayer(local: string, create: (id: string) => CustomLayerInterface): string;
+    /** Adds the image as `id(local)`; removed on teardown. */
+    addImage(local: string, image: HTMLImageElement | ImageData): void;
+    /** Registers layers for click, hover, tooltip, and `featuresAt`. */
+    interactive(layerIds: string[], toHit: (props: Record<string, unknown>) => FeatureHit | null): void;
+    /**
+     * Layers that hide what is beneath them (e.g. cluster bubbles): where one is topmost, a click
+     * picks nothing and calls `onClick` with that feature, and the hover is `toHover`'s hit for it
+     * (for its tooltip), or nothing. `toHover` must have no side effects (lookups call it too).
+     */
+    blocking(layerIds: string[], toHover?: (props: Record<string, unknown>) => FeatureHit | null, onClick?: (feature: BlockingClick) => void): void;
+    /** A layer event listener (e.g. a cluster click), removed on teardown. */
+    on(type: string, layerId: string, listener: (e: any) => void): void;
+    /** Reactive. */
+    readonly selectedKeys: ReadonlySet<string>;
+    /** An `$effect.root` torn down with the plugin. */
+    effect(fn: () => void | (() => void)): void;
+}
+/**
+ * A layer of data on a map. A plugin object keeps per-map state, so it belongs to one map: create
+ * one plugin per map (adding an object that is set up on another map throws).
+ */
+export interface MapPlugin {
+    id: string;
+    /** Already-translated layer name, for the selection bar and view summary. */
+    label?: string;
+    /** The metadata dataset the plugin's data comes from (for attribution); may change with its source. */
+    readonly dataset?: string;
+    /** Adds sources, layers, and icons; returns its teardown. Runs only once a style is loaded. */
+    setup(ctx: PluginContext): () => void;
+    legend?(): LegendData | null;
+    features?(): FeatureListItem[];
+    selectable?: boolean;
+    /**
+     * Which plugin's feature the hover tooltip shows where several are under the pointer: the
+     * highest wins, the topmost on a tie. Default 0. Over a blocking layer (a cluster bubble), a
+     * feature beneath shows only if its plugin's priority is higher than the blocking plugin's.
+     * Clicks ignore this (topmost first), and a blocking layer on top still blocks them.
+     */
+    hoverPriority?: number;
+    displayOptions?: Snippet;
+    /** Richer tooltip content for one of this plugin's features, below its name. */
+    tooltip?(item: FeatureListItem): Snippet | undefined;
+    /**
+     * Set when this plugin's `tooltip` content shows the feature's name itself, so the generic
+     * tooltip leaves its name header out. Default false.
+     */
+    tooltipShowsName?: boolean;
+    /**
+     * Tooltip content for a hovered hit that isn't a listed feature (e.g. a cluster bubble's hover
+     * hit from `PluginContext.blocking`).
+     */
+    hoverTooltip?(hit: FeatureHit): Snippet | undefined;
+}

package/dist/core/plugin.js

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

package/dist/core/scoped-context.d.ts

@@ -0,0 +1,7 @@
+import type { PluginContext } from "./plugin.js";
+/**
+ * A view of `ctx` whose local ids all start with `prefix`, so several plugins can be set up
+ * inside one (one id, one teardown) without their sources, layers, and images colliding.
+ * Everything else is the parent's, read live (`selectedKeys` stays reactive).
+ */
+export declare function scopedContext(ctx: PluginContext, prefix: string): PluginContext;

package/dist/core/scoped-context.js

@@ -0,0 +1,34 @@
+/**
+ * A view of `ctx` whose local ids all start with `prefix`, so several plugins can be set up
+ * inside one (one id, one teardown) without their sources, layers, and images colliding.
+ * Everything else is the parent's, read live (`selectedKeys` stays reactive).
+ */
+export function scopedContext(ctx, prefix) {
+    const local = (name) => `${prefix}${name}`;
+    return {
+        get gl() {
+            return ctx.gl;
+        },
+        get metadata() {
+            return ctx.metadata;
+        },
+        get messages() {
+            return ctx.messages;
+        },
+        get format() {
+            return ctx.format;
+        },
+        get selectedKeys() {
+            return ctx.selectedKeys;
+        },
+        id: (name) => ctx.id(local(name)),
+        addSource: (name, spec) => ctx.addSource(local(name), spec),
+        addLayer: (name, spec) => ctx.addLayer(local(name), spec),
+        addCustomLayer: (name, create) => ctx.addCustomLayer(local(name), create),
+        addImage: (name, image) => ctx.addImage(local(name), image),
+        interactive: (layerIds, toHit) => ctx.interactive(layerIds, toHit),
+        blocking: (layerIds, toHover, onClick) => ctx.blocking(layerIds, toHover, onClick),
+        on: (type, layerId, listener) => ctx.on(type, layerId, listener),
+        effect: (fn) => ctx.effect(fn)
+    };
+}

package/dist/data/format.d.ts

@@ -0,0 +1,10 @@
+export interface FormatProvider {
+    number(value: number, options?: Intl.NumberFormatOptions): string;
+    /** Formats in Pacific time. */
+    dateTime(value: Date | string): string;
+    /** "PT" only when the device zone isn't Pacific. */
+    zoneLabel(): string | null;
+    /** How long ago (or until) `value` is from `now` (default: the current time), e.g. "5 minutes ago". */
+    relativeTime(value: Date | string, now?: Date): string;
+}
+export declare function createDefaultFormat(deviceZone?: string): FormatProvider;

package/dist/data/format.js

@@ -0,0 +1,24 @@
+const PACIFIC = "America/Los_Angeles";
+export function createDefaultFormat(deviceZone = Intl.DateTimeFormat().resolvedOptions().timeZone) {
+    const dateFormat = new Intl.DateTimeFormat("en-US", {
+        timeZone: PACIFIC,
+        dateStyle: "medium",
+        timeStyle: "short"
+    });
+    const relative = new Intl.RelativeTimeFormat("en-US", { numeric: "always" });
+    return {
+        number: (value, options) => new Intl.NumberFormat("en-US", options).format(value),
+        dateTime: (value) => dateFormat.format(typeof value === "string" ? new Date(value) : value),
+        zoneLabel: () => (deviceZone === PACIFIC ? null : "PT"),
+        relativeTime: (value, now = new Date()) => {
+            const ms = (typeof value === "string" ? new Date(value) : value).getTime() - now.getTime();
+            const minutes = Math.round(ms / 60_000);
+            if (Math.abs(minutes) < 60)
+                return relative.format(minutes, "minute");
+            const hours = Math.round(ms / 3_600_000);
+            if (Math.abs(hours) < 24)
+                return relative.format(hours, "hour");
+            return relative.format(Math.round(ms / 86_400_000), "day");
+        }
+    };
+}

package/dist/data/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./types.js";
+export * from "./scale-types.js";
+export * from "./refs.js";
+export * from "./scale.js";
+export * from "./selection.js";
+export * from "./static-source.js";
+export * from "./messages.js";
+export * from "./format.js";
+export * from "./metadata.js";

package/dist/data/index.js

@@ -0,0 +1,9 @@
+export * from "./types.js";
+export * from "./scale-types.js";
+export * from "./refs.js";
+export * from "./scale.js";
+export * from "./selection.js";
+export * from "./static-source.js";
+export * from "./messages.js";
+export * from "./format.js";
+export * from "./metadata.js";

package/dist/data/messages/en.json

@@ -0,0 +1,52 @@
+{
+	"$schema": "https://inlang.com/schema/inlang-message-format",
+	"mapsdk_list_button": "List",
+	"mapsdk_list_button_label": "List of features on the map",
+	"mapsdk_list_label": "Features on the map",
+	"mapsdk_list_sort_name": "Name",
+	"mapsdk_list_sort_value": "Value",
+	"mapsdk_list_row": "{name}, {value} {units}, {level}",
+	"mapsdk_list_row_no_units": "{name}, {value}, {level}",
+	"mapsdk_list_row_no_value": "{name}, no reading",
+	"mapsdk_list_row_detail": "{name}, {detail}",
+	"mapsdk_list_empty": "Nothing on the map in this view",
+	"mapsdk_selected_count_one": "{count} selected",
+	"mapsdk_selected_count_other": "{count} selected",
+	"mapsdk_selection_clear": "Clear",
+	"mapsdk_selection_clear_layer": "Clear selection: {layer}",
+	"mapsdk_selected_in_layer": "{layer}: {selected}",
+	"mapsdk_selection_cleared": "Selection cleared",
+	"mapsdk_summary_one": "{count} {layer}",
+	"mapsdk_summary_other": "{count} {layer}",
+	"mapsdk_summary_level": "{count} {level}",
+	"mapsdk_summary_with_levels": "{layer}: {levels}",
+	"mapsdk_no_level": "No level",
+	"mapsdk_zoom_in": "Zoom in",
+	"mapsdk_zoom_out": "Zoom out",
+	"mapsdk_map_label": "Map. Use arrow keys to pan, plus and minus to zoom.",
+	"mapsdk_unavailable": "{layer} isn't available right now",
+	"mapsdk_loading": "Loading",
+	"mapsdk_error_retry": "Try again",
+	"mapsdk_legend_label": "Legend",
+	"mapsdk_legend_threshold": "from {value}",
+	"mapsdk_controls_label": "Map controls",
+	"mapsdk_selection_label": "Selection",
+	"mapsdk_no_reading": "No reading",
+	"mapsdk_time_with_zone": "{time} {zone}",
+	"mapsdk_monitor_cluster_average": "(cluster avg)",
+	"mapsdk_monitor_cluster_title": "{type} Monitors",
+	"mapsdk_monitor_cluster_title_sjvair": "SJVAir {type} Monitors",
+	"mapsdk_monitor_cluster_count_one": "{count} monitor",
+	"mapsdk_monitor_cluster_count_other": "{count} monitors",
+	"mapsdk_monitor_cluster_max": "Max: {value} {units}",
+	"mapsdk_monitor_cluster_min": "Min: {value} {units}",
+	"mapsdk_monitor_interval_avg": "({interval} avg)",
+	"mapsdk_monitor_updated": "Last updated {when}",
+	"mapsdk_hms_smoke_name": "Smoke",
+	"mapsdk_hms_fire_detection": "Fire detection",
+	"mapsdk_hms_fire_detections": "{count} fire detections",
+	"mapsdk_collocation_reference": "Reference monitor",
+	"mapsdk_collocation_colocated": "Collocated monitor",
+	"mapsdk_collocation_interval_avg": "({interval} avg)",
+	"mapsdk_collocation_updated": "Last updated {when}"
+}

package/dist/data/messages.d.ts

@@ -0,0 +1,10 @@
+import en from "./messages/en.json";
+type Catalog = Omit<typeof en, "$schema">;
+type Literal = keyof Catalog;
+type PluralBase<K> = K extends `${infer B}_one` ? B : never;
+/** Every catalog key, plus the base key of each `_one`/`_other` plural message. */
+export type MessageKey = Literal | PluralBase<Literal>;
+export type MessageParams = Record<string, string | number>;
+export type MessageProvider = (key: MessageKey, params?: MessageParams) => string;
+export declare const defaultMessages: MessageProvider;
+export {};

package/dist/data/messages.js

@@ -0,0 +1,17 @@
+import en from "./messages/en.json";
+const catalog = en;
+const plurals = new Intl.PluralRules("en-US");
+function interpolate(template, params) {
+    if (!params)
+        return template;
+    return template.replace(/\{(\w+)\}/g, (whole, name) => Object.hasOwn(params, name) ? String(params[name]) : whole);
+}
+export const defaultMessages = (key, params) => {
+    let resolved = key;
+    if (!Object.hasOwn(catalog, key) && typeof params?.count === "number") {
+        const variant = `${key}_${plurals.select(params.count) === "one" ? "one" : "other"}`;
+        if (Object.hasOwn(catalog, variant))
+            resolved = variant;
+    }
+    return interpolate(catalog[resolved] ?? key, params);
+};

package/dist/data/metadata.d.ts

@@ -0,0 +1,22 @@
+import type { Scale, ScaleRef } from "./scale-types.js";
+export interface EntryTypeInfo {
+    label: string;
+    units: string;
+    /**
+     * Decimal places to show values with (the catalog's display hint), or null when the metadata
+     * gives none.
+     */
+    precision: number | null;
+}
+export interface MetadataProvider {
+    scale(ref: ScaleRef, signal?: AbortSignal): Promise<Scale | "unavailable">;
+    entryType(ref: ScaleRef, signal?: AbortSignal): Promise<EntryTypeInfo | "unavailable">;
+    monitorTypeLabel(type: string, signal?: AbortSignal): Promise<string | "unavailable">;
+    /**
+     * How often a monitor type reports (e.g. "2 min"), for the tooltip's "(N avg)" note. Optional:
+     * the note is left out when a host's provider lacks it.
+     */
+    monitorTypeInterval?(type: string, signal?: AbortSignal): Promise<string | "unavailable">;
+    attribution(dataset: string, signal?: AbortSignal): Promise<string | "unavailable">;
+}
+export declare function createDefaultMetadata(): MetadataProvider;

package/dist/data/metadata.js

@@ -0,0 +1,110 @@
+import { getCalHeatScoreMeta, getDatasetCatalog, getForecastsMeta, getHMSMeta, getMonitorsMeta } from "@sjvair/sdk";
+const AIR_QUALITY = "air-quality";
+/** Datasets whose meta carries `scales` keyed by entry-type id. */
+const SCALE_DATASETS = ["hms-smoke", "hms-fire", "calheatscore", "forecasts"];
+function hasScales(dataset) {
+    return SCALE_DATASETS.includes(dataset);
+}
+function abortError() {
+    return new DOMException("The operation was aborted.", "AbortError");
+}
+/** Resolve with `promise`, or reject early if `signal` aborts (without touching `promise`). */
+function untilAborted(promise, signal) {
+    if (!signal)
+        return promise;
+    if (signal.aborted)
+        return Promise.reject(abortError());
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(abortError());
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+    });
+}
+/**
+ * Fetch once, share the result, and forget failures so the next call retries. The shared fetch
+ * carries no caller signal, so one caller's abort cannot reject it for the others.
+ */
+function memoize(fetch) {
+    let cached;
+    return (signal) => {
+        if (!cached) {
+            const p = fetch();
+            cached = p;
+            p.catch(() => {
+                if (cached === p)
+                    cached = undefined;
+            });
+        }
+        return untilAborted(cached, signal);
+    };
+}
+export function createDefaultMetadata() {
+    const monitorsMeta = memoize(() => getMonitorsMeta());
+    const catalog = memoize(() => getDatasetCatalog());
+    // The catalog splits HMS into two datasets; one meta carries both scales.
+    const hmsMeta = memoize(() => getHMSMeta());
+    const datasetScales = {
+        "hms-smoke": hmsMeta,
+        "hms-fire": hmsMeta,
+        calheatscore: memoize(() => getCalHeatScoreMeta()),
+        forecasts: memoize(() => getForecastsMeta())
+    };
+    /** The value, `"unavailable"` when `read` finds nothing or the fetch fails; only the caller's abort rejects. */
+    async function guarded(signal, read) {
+        try {
+            return (await read()) ?? "unavailable";
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+            return "unavailable";
+        }
+    }
+    /** The catalog's display precision for an entry type, or null. Only the caller's abort rejects. */
+    async function precisionOf(ref, signal) {
+        try {
+            const { datasets } = await catalog(signal);
+            const entry = datasets
+                .find((d) => d.id === ref.dataset)
+                ?.entry_types.find((e) => e.id === ref.entryType);
+            const precision = entry?.display?.precision;
+            return typeof precision === "number" ? precision : null;
+        }
+        catch (error) {
+            if (signal?.aborted)
+                throw error;
+            return null;
+        }
+    }
+    async function entryMeta(ref, signal) {
+        if (ref.dataset !== AIR_QUALITY)
+            return undefined;
+        return (await monitorsMeta(signal)).entries[ref.entryType];
+    }
+    return {
+        scale: (ref, signal) => guarded(signal, async () => {
+            if (hasScales(ref.dataset)) {
+                const { scales } = await datasetScales[ref.dataset](signal);
+                return Object.hasOwn(scales, ref.entryType) ? scales[ref.entryType] : undefined;
+            }
+            const entry = await entryMeta(ref, signal);
+            return entry?.scale ?? undefined;
+        }),
+        entryType: (ref, signal) => guarded(signal, async () => {
+            let info;
+            if (hasScales(ref.dataset)) {
+                const { scales } = await datasetScales[ref.dataset](signal);
+                const scale = Object.hasOwn(scales, ref.entryType) ? scales[ref.entryType] : undefined;
+                info = scale && { label: scale.label, units: scale.units };
+            }
+            else {
+                const entry = await entryMeta(ref, signal);
+                info = entry && { label: entry.label, units: entry.units ?? "" };
+            }
+            return info && { ...info, precision: await precisionOf(ref, signal) };
+        }),
+        monitorTypeLabel: (type, signal) => guarded(signal, async () => (await monitorsMeta(signal)).monitors[type]?.label),
+        monitorTypeInterval: (type, signal) => guarded(signal, async () => (await monitorsMeta(signal)).monitors[type]?.expected_interval),
+        attribution: (dataset, signal) => guarded(signal, async () => (await catalog(signal)).datasets.find((d) => d.id === dataset)?.source || undefined)
+    };
+}

package/dist/data/refs.d.ts

@@ -0,0 +1,18 @@
+import type { FeatureRef } from "./types.js";
+/** A place as `@sjvair/sdk` and the dashboard name it: a monitor, or a region by type and code. */
+export type PlaceRef = {
+    kind: "monitor";
+    id: string;
+} | {
+    kind: "region";
+    type: string;
+    code: string;
+};
+export declare function encodeRef(ref: FeatureRef): string;
+export declare function decodeRef(key: string): FeatureRef | null;
+export declare function selectionId(ref: FeatureRef): string | null;
+export declare function toPlaceRef(ref: FeatureRef): PlaceRef | null;
+export declare function fromPlaceRef(place: {
+    kind: string;
+    [k: string]: unknown;
+}): FeatureRef | null;

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,7 @@
+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;
+export declare function selectionKeys(sel: SpatialSelection | null): Set<string>;

package/dist/data/selection.js

@@ -0,0 +1,31 @@
+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] };
+}
+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>;