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

package/dist/core/shape-view.d.ts

@@ -0,0 +1,27 @@
+import type { Geometry } from "geojson";
+import type { Bounds } from "./create-map.svelte.js";
+/**
+ * Shapes against the view: a geometry's bounding box, whether it overlaps the view, and a point of
+ * it inside the view. Coordinates are planar lng/lat (as `labelPoint`); no antimeridian handling.
+ */
+/** `[west, south, east, north]`. */
+export type Bbox = [west: number, south: number, east: number, north: number];
+/** The geometry's bounding box, or `null` when it has no coordinates. */
+export declare function geometryBbox(geometry: Geometry): Bbox | null;
+/** Inside an outer ring and outside its holes, for any polygon of the geometry. */
+export declare function containsPoint(geometry: Geometry, p: [number, number]): boolean;
+/**
+ * Whether the item is in view: a shape (`geometry`) when it intersects `bounds` (bbox pre-check,
+ * then the exact test; holes count), anything else when its `lngLat` is inside. Edges included.
+ */
+export declare function intersectsBounds(item: {
+    lngLat: [number, number];
+    geometry?: Geometry;
+    bbox?: Bbox;
+}, bounds: Bounds): boolean;
+/**
+ * A point of the shape inside `view`: `center` when the shape contains it; otherwise a point well
+ * inside the shape's visible part (polygons: the largest clipped one, never in a hole; lines: the
+ * middle of the longest visible piece); `null` when nothing of it is visible.
+ */
+export declare function shapeAnchor(geometry: Geometry, view: Bounds, center: [number, number]): [number, number] | null;

package/dist/core/shape-view.js

@@ -0,0 +1,323 @@
+/** The geometry's bounding box, or `null` when it has no coordinates. */
+export function geometryBbox(geometry) {
+    let west = Infinity;
+    let south = Infinity;
+    let east = -Infinity;
+    let north = -Infinity;
+    const add = (p) => {
+        if (p[0] < west)
+            west = p[0];
+        if (p[0] > east)
+            east = p[0];
+        if (p[1] < south)
+            south = p[1];
+        if (p[1] > north)
+            north = p[1];
+    };
+    const walk = (g) => {
+        switch (g.type) {
+            case "Point":
+                add(g.coordinates);
+                break;
+            case "MultiPoint":
+            case "LineString":
+                g.coordinates.forEach(add);
+                break;
+            case "MultiLineString":
+            case "Polygon":
+                g.coordinates.forEach((ring) => ring.forEach(add));
+                break;
+            case "MultiPolygon":
+                g.coordinates.forEach((poly) => poly.forEach((ring) => ring.forEach(add)));
+                break;
+            case "GeometryCollection":
+                g.geometries.forEach(walk);
+                break;
+        }
+    };
+    walk(geometry);
+    return west <= east ? [west, south, east, north] : null;
+}
+const inRect = (p, b) => p[0] >= b.west && p[0] <= b.east && p[1] >= b.south && p[1] <= b.north;
+/** The polygons of a geometry (each an outer ring and holes), or `null` for a non-polygon. */
+function polygonsOf(g) {
+    if (g.type === "Polygon")
+        return [g.coordinates];
+    if (g.type === "MultiPolygon")
+        return g.coordinates;
+    return null;
+}
+function linesOf(g) {
+    if (g.type === "LineString")
+        return [g.coordinates];
+    if (g.type === "MultiLineString")
+        return g.coordinates;
+    return null;
+}
+/** Ring edges, closing an unclosed ring. Fewer than 3 points: no area, so no edges. */
+function ringEdges(ring) {
+    const n = ring.length;
+    if (n < 3)
+        return [];
+    const edges = [];
+    for (let i = 0; i < n - 1; i++)
+        edges.push([ring[i], ring[i + 1]]);
+    const [a, z] = [ring[0], ring[n - 1]];
+    if (a[0] !== z[0] || a[1] !== z[1])
+        edges.push([z, a]);
+    return edges;
+}
+function inRing(p, ring) {
+    let inside = false;
+    for (const [a, b] of ringEdges(ring)) {
+        if (a[1] > p[1] !== b[1] > p[1]) {
+            const x = ((b[0] - a[0]) * (p[1] - a[1])) / (b[1] - a[1]) + a[0];
+            if (p[0] < x)
+                inside = !inside;
+        }
+    }
+    return inside;
+}
+function inPolygon(p, polygon) {
+    const [outer, ...holes] = polygon;
+    return !!outer && inRing(p, outer) && !holes.some((hole) => inRing(p, hole));
+}
+/** Inside an outer ring and outside its holes, for any polygon of the geometry. */
+export function containsPoint(geometry, p) {
+    return polygonsOf(geometry)?.some((polygon) => inPolygon(p, polygon)) ?? false;
+}
+const cross = (o, a, b) => (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0]);
+const onSegment = (p, a, b) => Math.min(a[0], b[0]) <= p[0] &&
+    p[0] <= Math.max(a[0], b[0]) &&
+    Math.min(a[1], b[1]) <= p[1] &&
+    p[1] <= Math.max(a[1], b[1]);
+/** Whether segments ab and cd meet, touching and collinear overlaps included. */
+function segmentsMeet(a, b, c, d) {
+    const d1 = cross(c, d, a);
+    const d2 = cross(c, d, b);
+    const d3 = cross(a, b, c);
+    const d4 = cross(a, b, d);
+    if (((d1 > 0 && d2 < 0) || (d1 < 0 && d2 > 0)) && ((d3 > 0 && d4 < 0) || (d3 < 0 && d4 > 0)))
+        return true;
+    return ((d1 === 0 && onSegment(a, c, d)) ||
+        (d2 === 0 && onSegment(b, c, d)) ||
+        (d3 === 0 && onSegment(c, a, b)) ||
+        (d4 === 0 && onSegment(d, a, b)));
+}
+function rectCorners(b) {
+    return [
+        [b.west, b.south],
+        [b.east, b.south],
+        [b.east, b.north],
+        [b.west, b.north]
+    ];
+}
+function segmentHitsRect(a, b, r) {
+    if (inRect(a, r) || inRect(b, r))
+        return true;
+    const c = rectCorners(r);
+    return c.some((p, i) => segmentsMeet(a, b, p, c[(i + 1) % 4]));
+}
+function polygonHitsRect(polygon, r) {
+    const edges = polygon.flatMap(ringEdges);
+    if (edges.length === 0)
+        return false;
+    if (edges.some(([a]) => inRect(a, r)))
+        return true;
+    if (rectCorners(r).some((p) => inPolygon(p, polygon)))
+        return true;
+    return edges.some(([a, b]) => segmentHitsRect(a, b, r));
+}
+/**
+ * Whether the item is in view: a shape (`geometry`) when it intersects `bounds` (bbox pre-check,
+ * then the exact test; holes count), anything else when its `lngLat` is inside. Edges included.
+ */
+export function intersectsBounds(item, bounds) {
+    const { geometry } = item;
+    const polygons = geometry && polygonsOf(geometry);
+    const lines = geometry && linesOf(geometry);
+    if (!geometry || (!polygons && !lines && geometry.type !== "Point")) {
+        return inRect(item.lngLat, bounds);
+    }
+    if (geometry.type === "Point")
+        return inRect(geometry.coordinates, bounds);
+    const box = item.bbox ?? geometryBbox(geometry);
+    if (!box ||
+        box[0] > bounds.east ||
+        box[2] < bounds.west ||
+        box[1] > bounds.north ||
+        box[3] < bounds.south) {
+        return false;
+    }
+    if (polygons)
+        return polygons.some((polygon) => polygonHitsRect(polygon, bounds));
+    return lines.some((line) => line.some((p, i) => i === 0 ? line.length === 1 && inRect(p, bounds) : segmentHitsRect(line[i - 1], p, bounds)));
+}
+/** Sutherland–Hodgman: the ring clipped to the rectangle (open, no repeated first point). */
+function clipRing(ring, r) {
+    let pts = ringEdges(ring).map(([a]) => [a[0], a[1]]);
+    const sides = [
+        [(p) => p[0] >= r.west, (a, b) => atX(a, b, r.west)],
+        [(p) => p[0] <= r.east, (a, b) => atX(a, b, r.east)],
+        [(p) => p[1] >= r.south, (a, b) => atY(a, b, r.south)],
+        [(p) => p[1] <= r.north, (a, b) => atY(a, b, r.north)]
+    ];
+    for (const [keep, cut] of sides) {
+        const out = [];
+        for (let i = 0; i < pts.length; i++) {
+            const cur = pts[i];
+            const prev = pts[(i + pts.length - 1) % pts.length];
+            if (keep(cur)) {
+                if (!keep(prev))
+                    out.push(cut(prev, cur));
+                out.push(cur);
+            }
+            else if (keep(prev)) {
+                out.push(cut(prev, cur));
+            }
+        }
+        pts = out;
+        if (pts.length === 0)
+            break;
+    }
+    return pts;
+}
+const atX = (a, b, x) => [
+    x,
+    a[1] + ((b[1] - a[1]) * (x - a[0])) / (b[0] - a[0])
+];
+const atY = (a, b, y) => [
+    a[0] + ((b[0] - a[0]) * (y - a[1])) / (b[1] - a[1]),
+    y
+];
+function openArea(pts) {
+    let area = 0;
+    for (let i = 0; i < pts.length; i++) {
+        const [a, b] = [pts[i], pts[(i + 1) % pts.length]];
+        area += a[0] * b[1] - b[0] * a[1];
+    }
+    return Math.abs(area) / 2;
+}
+/**
+ * A point well inside the clipped polygon (outer ring, then holes): the midpoint of the widest
+ * interior span of a horizontal line through its middle. When that line has none (a C shape,
+ * bands around a hole), the widest span among lines between neighboring vertex heights.
+ */
+function polygonInteriorPoint(rings) {
+    const ys = [...new Set(rings.flatMap((ring) => ring.map((p) => p[1])))].sort((a, b) => a - b);
+    if (ys.length < 2)
+        return null;
+    const middle = widestSpan(rings, ys, [(ys[0] + ys[ys.length - 1]) / 2]);
+    if (middle)
+        return middle;
+    const gaps = [];
+    for (let i = 1; i < ys.length; i++)
+        gaps.push((ys[i - 1] + ys[i]) / 2);
+    return widestSpan(rings, ys, gaps);
+}
+/** The midpoint of the widest interior span on any of the horizontal `lines`. */
+function widestSpan(rings, ys, lines) {
+    let best = null;
+    let width = 0;
+    for (let y of lines) {
+        // On a vertex height the crossings double up; step off it.
+        if (ys.includes(y))
+            y += (ys[ys.length - 1] - ys[0]) * 1e-9;
+        const xs = [];
+        for (const ring of rings) {
+            for (let i = 0; i < ring.length; i++) {
+                const [a, b] = [ring[i], ring[(i + 1) % ring.length]];
+                if (a[1] > y !== b[1] > y)
+                    xs.push(atY(a, b, y)[0]);
+            }
+        }
+        xs.sort((a, b) => a - b);
+        for (let i = 0; i + 1 < xs.length; i += 2) {
+            if (xs[i + 1] - xs[i] > width) {
+                width = xs[i + 1] - xs[i];
+                best = [(xs[i] + xs[i + 1]) / 2, y];
+            }
+        }
+    }
+    return best;
+}
+/** Liang–Barsky: the segment clipped to the rectangle, or `null` when it misses. */
+function clipSegment(a, b, r) {
+    const dx = b[0] - a[0];
+    const dy = b[1] - a[1];
+    let t0 = 0;
+    let t1 = 1;
+    const checks = [
+        [-dx, a[0] - r.west],
+        [dx, r.east - a[0]],
+        [-dy, a[1] - r.south],
+        [dy, r.north - a[1]]
+    ];
+    for (const [p, q] of checks) {
+        if (p === 0) {
+            if (q < 0)
+                return null;
+        }
+        else {
+            const t = q / p;
+            if (p < 0)
+                t0 = Math.max(t0, t);
+            else
+                t1 = Math.min(t1, t);
+            if (t0 > t1)
+                return null;
+        }
+    }
+    return [
+        [a[0] + t0 * dx, a[1] + t0 * dy],
+        [a[0] + t1 * dx, a[1] + t1 * dy]
+    ];
+}
+/**
+ * A point of the shape inside `view`: `center` when the shape contains it; otherwise a point well
+ * inside the shape's visible part (polygons: the largest clipped one, never in a hole; lines: the
+ * middle of the longest visible piece); `null` when nothing of it is visible.
+ */
+export function shapeAnchor(geometry, view, center) {
+    const polygons = polygonsOf(geometry);
+    if (polygons) {
+        if (inRect(center, view) && containsPoint(geometry, center))
+            return center;
+        // Visible parts, largest first; the first that yields a point wins.
+        const parts = [];
+        for (const polygon of polygons) {
+            if (!polygon[0] || ringEdges(polygon[0]).length === 0)
+                continue;
+            const rings = polygon.map((ring) => clipRing(ring, view));
+            const area = rings[0].length >= 3 ? openArea(rings[0]) : 0;
+            if (area > 0)
+                parts.push({ rings: rings.filter((r, i) => i === 0 || r.length >= 3), area });
+        }
+        parts.sort((a, b) => b.area - a.area);
+        for (const { rings } of parts) {
+            const at = polygonInteriorPoint(rings);
+            if (at)
+                return at;
+        }
+        return null;
+    }
+    const lines = linesOf(geometry);
+    if (lines) {
+        let best = null;
+        let length = -1;
+        for (const line of lines) {
+            for (let i = 1; i < line.length; i++) {
+                const piece = clipSegment(line[i - 1], line[i], view);
+                if (!piece)
+                    continue;
+                const len = Math.hypot(piece[1][0] - piece[0][0], piece[1][1] - piece[0][1]);
+                if (len > length) {
+                    length = len;
+                    best = [(piece[0][0] + piece[1][0]) / 2, (piece[0][1] + piece[1][1]) / 2];
+                }
+            }
+        }
+        return best;
+    }
+    return null;
+}

package/dist/data/format.d.ts

@@ -0,0 +1,10 @@
+export interface FormatProvider {
+    number(value: number, options?: Intl.NumberFormatOptions): string;
+    /** Formats in Pacific time like sjvair.com's map: "4:00 pm Friday Nov 06, 2026". */
+    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,37 @@
+const PACIFIC = "America/Los_Angeles";
+export function createDefaultFormat(deviceZone = Intl.DateTimeFormat().resolvedOptions().timeZone) {
+    const dateFormat = new Intl.DateTimeFormat("en-US", {
+        timeZone: PACIFIC,
+        hour: "numeric",
+        minute: "2-digit",
+        hour12: true,
+        weekday: "long",
+        month: "short",
+        day: "2-digit",
+        year: "numeric"
+    });
+    // date-fns' "h:mm aaa EEEE MMM dd, yyyy", assembled from the parts.
+    const dateTime = (value) => {
+        const date = typeof value === "string" ? new Date(value) : value;
+        const part = {};
+        for (const { type, value: text } of dateFormat.formatToParts(date))
+            part[type] = text;
+        return `${part.hour}:${part.minute} ${part.dayPeriod?.toLowerCase()} ${part.weekday} ${part.month} ${part.day}, ${part.year}`;
+    };
+    const relative = new Intl.RelativeTimeFormat("en-US", { numeric: "always" });
+    return {
+        number: (value, options) => new Intl.NumberFormat("en-US", options).format(value),
+        dateTime,
+        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,61 @@
+{
+	"$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_level": "{name}, {level}",
+	"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_count_area_one": "{count} monitor within a {area} mi² area",
+	"mapsdk_monitor_cluster_count_area_other": "{count} monitors within a {area} mi² area",
+	"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_box_header": "Fire ({units})",
+	"mapsdk_hms_fire_box_header_no_units": "Fire",
+	"mapsdk_hms_fire_average": "Average",
+	"mapsdk_level_with_units": "{level} {units}",
+	"mapsdk_hms_fire_detections_one": "{count} fire detection",
+	"mapsdk_hms_fire_detections_other": "{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}",
+	"mapsdk_card_close": "Close"
+}

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;