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

package/dist/ui/TooltipItem.svelte.d.ts

@@ -0,0 +1,11 @@
+import type { FormatProvider } from "../data/format.js";
+import type { MessageProvider } from "../data/messages.js";
+import type { FeatureListItem } from "../core/plugin.js";
+interface Props {
+    item: FeatureListItem;
+    messages: MessageProvider;
+    format: FormatProvider;
+}
+declare const TooltipItem: import("svelte").Component<Props, {}, "">;
+type TooltipItem = ReturnType<typeof TooltipItem>;
+export default TooltipItem;

package/dist/ui/ViewSummary.svelte

@@ -0,0 +1,97 @@
+<script lang="ts">
+	import { untrack } from "svelte";
+	import type { MapContext } from "../core/create-map.svelte.js";
+	import { inView } from "./feature-list.js";
+	import { SUMMARY_DEBOUNCE_MS, summaryText } from "./view-summary.js";
+
+	let { map }: { map: MapContext } = $props();
+
+	interface Line {
+		/** Stable per plugin and kind, so an unchanged line keeps its element and isn't re-announced. */
+		key: string;
+		text: string;
+	}
+
+	// The map's one live region: what is in view per layer, and how many are selected. Spoken text
+	// only; the visible pieces are the legend, the list, and the selection bar. Lines are keyed and
+	// the region is not atomic, so only a line that changed is announced.
+	/** Each plugin's selection count as of the last update, to tell when one drops to zero. */
+	let previous: Record<string, number> = {};
+
+	// Selection counts of every plugin, so a change reschedules the update.
+	const selectionCounts = $derived(
+		map.plugins.map((p) => `${p.id}:${map.getSelection(p.id)?.ids.length ?? 0}`).join(",")
+	);
+
+	function compute(): Line[] {
+		const bounds = map.bounds;
+		const out: Line[] = [];
+		const counts: Record<string, number> = {};
+		for (const plugin of map.plugins) {
+			const layer = plugin.label ?? plugin.id;
+			if (bounds && plugin.features) {
+				const data = plugin.legend?.();
+				const scale = data && "scale" in data ? data.scale : null;
+				out.push({
+					key: `view:${plugin.id}`,
+					text: summaryText(layer, inView(plugin.features(), bounds), scale, map.messages)
+				});
+			}
+			const count = map.getSelection(plugin.id)?.ids.length ?? 0;
+			counts[plugin.id] = count;
+			// A drop to zero is said once; the line is gone at the next update.
+			const selected =
+				count > 0
+					? map.messages("mapsdk_selected_count", { count })
+					: (previous[plugin.id] ?? 0) > 0
+						? map.messages("mapsdk_selection_cleared")
+						: null;
+			if (selected !== null) {
+				out.push({
+					key: `selection:${plugin.id}`,
+					text: map.messages("mapsdk_selected_in_layer", { layer, selected })
+				});
+			}
+		}
+		previous = counts;
+		return out;
+	}
+
+	// What is there at mount (the host's view and selection) is the baseline, not news.
+	let lines = $state<Line[]>(untrack(compute));
+
+	let first = true;
+	$effect(() => {
+		void map.bounds;
+		void selectionCounts;
+		if (first) {
+			first = false;
+			return;
+		}
+		const timer = setTimeout(() => {
+			lines = untrack(compute);
+		}, SUMMARY_DEBOUNCE_MS);
+		return () => clearTimeout(timer);
+	});
+</script>
+
+<div class="mapsdk-summary" aria-live="polite" aria-atomic="false">
+	{#each lines as line (line.key)}
+		<p>{line.text}</p>
+	{/each}
+</div>
+
+<style>
+	.mapsdk-summary {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		overflow: hidden;
+		clip-path: inset(50%);
+		white-space: nowrap;
+	}
+
+	p {
+		margin: 0;
+	}
+</style>

package/dist/ui/ViewSummary.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { MapContext } from "../core/create-map.svelte.js";
+type $$ComponentProps = {
+    map: MapContext;
+};
+declare const ViewSummary: import("svelte").Component<$$ComponentProps, {}, "">;
+type ViewSummary = ReturnType<typeof ViewSummary>;
+export default ViewSummary;

package/dist/ui/card.d.ts

@@ -0,0 +1,29 @@
+import type { Snippet } from "svelte";
+import type { FeatureListItem } from "../core/plugin.js";
+import type { FeatureRef } from "../data/types.js";
+/** What a host's card actions get: the card's feature and its selection state. */
+export interface CardContext {
+    readonly pluginId: string;
+    readonly ref: FeatureRef;
+    readonly refKey: string;
+    /** The listed item, or null for a hit its plugin doesn't list (an HMS fire hotspot). */
+    readonly item: FeatureListItem | null;
+    /**
+     * Whether the feature can be selected: its plugin's mode isn't `"none"`, it's a monitor or a
+     * region (not a `feature` ref), and its listed item, if any, is `selectable`. Reactive. Show
+     * Select/Remove only when it's true.
+     */
+    readonly selectable: boolean;
+    /** Whether the feature is in its plugin's selection. Reactive. */
+    readonly selected: boolean;
+    /**
+     * A user's Select/Remove: toggles the feature, with the plugin's `canSelect`. Does nothing
+     * when it isn't `selectable`.
+     */
+    toggle(): void;
+}
+/** `MapView`'s `card` options. */
+export interface CardOptions {
+    /** The host's buttons, in a row at the card's foot. */
+    actions?: Snippet<[CardContext]>;
+}

package/dist/ui/card.js

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

package/dist/ui/controls.css

@@ -0,0 +1,45 @@
+/*
+ * Shared by map-sdk's controls (plain CSS, not scoped: the classes are set by several components).
+ *
+ * Focus ring, only on :focus-visible: a 2px --ring outline with a --ring-edge halo, so the ring
+ * reads against any background. A host without --ring-edge gets the page background.
+ */
+/* Doubled classes raise specificity above any component rule that sets box-shadow (a card
+   shadow, a selected row's ring), so the result never depends on bundle order. */
+.mapsdk-focus.mapsdk-focus:focus-visible {
+	outline: 2px solid var(--ring);
+	outline-offset: 1px;
+	box-shadow: 0 0 0 4px var(--ring-edge, var(--background));
+}
+
+/* For controls and rows inside a container that clips: the ring is drawn inside. */
+.mapsdk-focus-inset.mapsdk-focus-inset:focus-visible,
+.mapsdk-focus-inset-active:focus-visible .mapsdk-active-option.mapsdk-active-option {
+	outline: 2px solid var(--ring);
+	outline-offset: -3px;
+	box-shadow: inset 0 0 0 4px var(--ring-edge, var(--background));
+}
+
+/* Elements only script focuses (tabindex="-1"): the outline alone. */
+.mapsdk-focus-outline:focus-visible {
+	outline: 2px solid var(--ring);
+	outline-offset: -2px;
+}
+
+/* Motion goes through the host's tokens; the fallbacks apply when it defines none. */
+.mapsdk-motion {
+	transition-property: background-color, border-color, color, opacity;
+	transition-duration: var(--motion-duration-fast, 120ms);
+	transition-timing-function: var(--motion-ease-standard, ease);
+}
+
+@media (prefers-reduced-motion: reduce) {
+	.mapsdk-motion {
+		transition-duration: 0s;
+	}
+}
+
+/* The engine's credits keep its colors; links get an underline so color isn't the only cue. */
+.mapsdk-map .maplibregl-ctrl-attrib a {
+	text-decoration: underline;
+}

package/dist/ui/data-credits.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { MapContext } from "../core/create-map.svelte.js";
+/**
+ * The credit text of every dataset the map's plugins declare, each once, as it arrives from the
+ * metadata provider. Call during a component's initialization: the fetching runs in an effect
+ * and stops with the component.
+ */
+export declare function createDataCredits(map: MapContext): {
+    readonly list: string[];
+};

package/dist/ui/data-credits.svelte.js

@@ -0,0 +1,52 @@
+/* eslint-disable svelte/prefer-svelte-reactivity -- derived sets only dedupe; never mutated */
+import { onDestroy, untrack } from "svelte";
+/** An unavailable attribution is tried again on a later moveend, at most once a minute. */
+const RETRY_MS = 60_000;
+/**
+ * The credit text of every dataset the map's plugins declare, each once, as it arrives from the
+ * metadata provider. Call during a component's initialization: the fetching runs in an effect
+ * and stops with the component.
+ */
+export function createDataCredits(map) {
+    const datasets = $derived([
+        ...new Set(map.plugins.flatMap((plugin) => (plugin.dataset ? [plugin.dataset] : [])))
+    ]);
+    let fetched = $state.raw({});
+    const list = $derived([...new Set(datasets.flatMap((d) => (fetched[d] ? [fetched[d]] : [])))]);
+    const controller = new AbortController();
+    onDestroy(() => controller.abort());
+    // Plain collections: bookkeeping, never rendered.
+    const inflight = new Set();
+    const failedAt = new Map();
+    $effect(() => {
+        void map.bounds;
+        const wanted = datasets;
+        untrack(() => {
+            for (const dataset of wanted) {
+                if (fetched[dataset] || inflight.has(dataset))
+                    continue;
+                const failed = failedAt.get(dataset);
+                if (failed !== undefined && Date.now() - failed < RETRY_MS)
+                    continue;
+                inflight.add(dataset);
+                map.metadata.attribution(dataset, controller.signal).then((text) => {
+                    inflight.delete(dataset);
+                    if (controller.signal.aborted)
+                        return;
+                    if (text === "unavailable")
+                        failedAt.set(dataset, Date.now());
+                    else
+                        fetched = { ...fetched, [dataset]: text };
+                }, () => {
+                    inflight.delete(dataset);
+                    failedAt.set(dataset, Date.now());
+                });
+            }
+        });
+    });
+    return {
+        get list() {
+            return list;
+        }
+    };
+}

package/dist/ui/feature-list.d.ts

@@ -0,0 +1,46 @@
+import type { Bounds } from "../core/create-map.svelte.js";
+import type { FeatureListItem } from "../core/plugin.js";
+import type { FormatProvider } from "../data/format.js";
+import type { MessageProvider } from "../data/messages.js";
+import type { Level } from "../data/scale-types.js";
+export type { Bounds };
+export type SortBy = "name" | "value";
+/**
+ * How long after Shift+F10 or the Menu key the browser's own keyboard `contextmenu` event (sent on
+ * keydown or keyup, depending on the platform) is treated as a duplicate of the one sent to the row.
+ */
+export declare const MENU_EVENT_WINDOW_MS = 1000;
+/**
+ * A valid, stable id fragment for a row, from its plugin and refKey: anything but letters and digits
+ * is escaped as `_<hex>_` (`_` and `-` included), so the `--` between the parts can only be the
+ * separator and different rows never share a fragment.
+ */
+export declare function optionIdPart(pluginId: string, refKey: string): string;
+/**
+ * Items in `bounds`, edges included: a shape (`geometry`) when it overlaps them, anything else when
+ * its point is inside. No antimeridian handling (the Valley).
+ */
+export declare function inView(items: FeatureListItem[], bounds: Bounds): FeatureListItem[];
+/**
+ * The item's level, or null for `NO_LEVEL`. A level with an empty color is still shown, by its
+ * label on a neutral swatch.
+ */
+export declare function shownLevel(item: FeatureListItem): Level | null;
+/**
+ * The value as shown, or `null` for none. A category reading, whose value is its level's code
+ * (smoke's "light", the heat score's 2), shows no value: its level label already says it.
+ */
+export declare function shownValue(item: FeatureListItem, format: FormatProvider): string | null;
+/** A sorted copy. `value`: highest first, null values and no level last; ties and `name` by name. */
+export declare function sortItems(items: FeatureListItem[], by: SortBy): FeatureListItem[];
+/** The first index at or after `from` (wrapping) whose name starts with `query`, any case; -1 if none. */
+export declare function typeaheadIndex(items: FeatureListItem[], query: string, from: number): number;
+/**
+ * What stands in an item's level place: its level's label, else its `detail`, else "No level".
+ */
+export declare function levelText(item: FeatureListItem, messages: MessageProvider): {
+    kind: "level" | "detail" | "none";
+    text: string;
+};
+/** A row's accessible name: name, value, units, and level label (or detail). */
+export declare function rowLabel(item: FeatureListItem, messages: MessageProvider, format: FormatProvider): string;

package/dist/ui/feature-list.js

@@ -0,0 +1,115 @@
+import { intersectsBounds } from "../core/shape-view.js";
+import { NO_LEVEL } from "../data/scale.js";
+import { formatValue } from "./value-format.js";
+/**
+ * How long after Shift+F10 or the Menu key the browser's own keyboard `contextmenu` event (sent on
+ * keydown or keyup, depending on the platform) is treated as a duplicate of the one sent to the row.
+ */
+export const MENU_EVENT_WINDOW_MS = 1000;
+/**
+ * A valid, stable id fragment for a row, from its plugin and refKey: anything but letters and digits
+ * is escaped as `_<hex>_` (`_` and `-` included), so the `--` between the parts can only be the
+ * separator and different rows never share a fragment.
+ */
+export function optionIdPart(pluginId, refKey) {
+    const escape = (text) => text.replace(/[^A-Za-z0-9]/g, (c) => `_${c.codePointAt(0).toString(16)}_`);
+    return `${escape(pluginId)}--${escape(refKey)}`;
+}
+/**
+ * Items in `bounds`, edges included: a shape (`geometry`) when it overlaps them, anything else when
+ * its point is inside. No antimeridian handling (the Valley).
+ */
+export function inView(items, bounds) {
+    return items.filter((item) => intersectsBounds(item, bounds));
+}
+/**
+ * The item's level, or null for `NO_LEVEL`. A level with an empty color is still shown, by its
+ * label on a neutral swatch.
+ */
+export function shownLevel(item) {
+    return item.level !== NO_LEVEL ? item.level : null;
+}
+/**
+ * The value as shown, or `null` for none. A category reading, whose value is its level's code
+ * (smoke's "light", the heat score's 2), shows no value: its level label already says it.
+ */
+export function shownValue(item, format) {
+    if (item.value === null)
+        return null;
+    const level = shownLevel(item);
+    if (level && level.value !== null && level.value === item.value)
+        return null;
+    return typeof item.value === "number"
+        ? formatValue(item.value, item.precision, format, item.truncate)
+        : item.value;
+}
+const collator = new Intl.Collator("en-US");
+/** A value's sort weight; `null` sorts last. Category values sort by their level's tier. */
+function weight(item) {
+    if (item.value === null || item.level === NO_LEVEL)
+        return null;
+    if (typeof item.value === "number")
+        return item.value;
+    return item.level.tier ?? null;
+}
+/** A sorted copy. `value`: highest first, null values and no level last; ties and `name` by name. */
+export function sortItems(items, by) {
+    const byName = (a, b) => collator.compare(a.name, b.name);
+    if (by === "name")
+        return items.toSorted(byName);
+    const weighted = items.map((item) => ({ item, w: weight(item) }));
+    weighted.sort((a, b) => {
+        if (a.w === null || b.w === null) {
+            if (a.w !== b.w)
+                return a.w === null ? 1 : -1;
+        }
+        else if (a.w !== b.w) {
+            return b.w - a.w;
+        }
+        return byName(a.item, b.item);
+    });
+    return weighted.map(({ item }) => item);
+}
+/** The first index at or after `from` (wrapping) whose name starts with `query`, any case; -1 if none. */
+export function typeaheadIndex(items, query, from) {
+    const q = query.toLocaleLowerCase("en-US");
+    const n = items.length;
+    for (let step = 0; step < n; step++) {
+        const i = (((from + step) % n) + n) % n;
+        if (items[i].name.toLocaleLowerCase("en-US").startsWith(q))
+            return i;
+    }
+    return -1;
+}
+/**
+ * What stands in an item's level place: its level's label, else its `detail`, else "No level".
+ */
+export function levelText(item, messages) {
+    const level = shownLevel(item);
+    if (level)
+        return { kind: "level", text: level.label };
+    const detail = item.detail?.trim();
+    if (detail)
+        return { kind: "detail", text: detail };
+    return { kind: "none", text: messages("mapsdk_no_level") };
+}
+/** A row's accessible name: name, value, units, and level label (or detail). */
+export function rowLabel(item, messages, format) {
+    const level = levelText(item, messages);
+    const value = shownValue(item, format);
+    if (value === null) {
+        // A category reading: its level is its value.
+        if (item.value !== null && level.kind === "level")
+            return messages("mapsdk_list_row_level", { name: item.name, level: level.text });
+        return level.kind === "detail"
+            ? messages("mapsdk_list_row_detail", { name: item.name, detail: level.text })
+            : messages("mapsdk_list_row_no_value", { name: item.name });
+    }
+    const params = {
+        name: item.name,
+        value,
+        units: item.units,
+        level: level.text
+    };
+    return messages(item.units ? "mapsdk_list_row" : "mapsdk_list_row_no_units", params);
+}

package/dist/ui/legend-data.d.ts

@@ -0,0 +1,41 @@
+import type { LegendData } from "../core/plugin.js";
+import type { FormatProvider } from "../data/format.js";
+import type { DataStatus } from "../data/types.js";
+export type LegendBar = {
+    kind: "gradient";
+    stops: Array<{
+        color: string;
+        label: string;
+        tick: string;
+    }>;
+} | {
+    kind: "blocks";
+    blocks: Array<{
+        color: string;
+        opacity: number | null;
+        label: string;
+        tick: string;
+    }>;
+};
+export interface LegendSection {
+    pluginId: string;
+    title: string;
+    units: string;
+    bar: LegendBar;
+}
+export type LegendEntry = {
+    kind: "scale";
+    section: LegendSection;
+} | {
+    kind: "status";
+    pluginId: string;
+    layer: string;
+    status: DataStatus;
+};
+/** One legend section from a plugin's legend data; null for status-only data or no levels. */
+export declare function legendSection(data: LegendData, format: FormatProvider): LegendSection | null;
+/**
+ * How a translucent fill looks over the page background (`background` is the computed
+ * `--background`, in a form color2k parses). An empty color or no opacity returns the color.
+ */
+export declare function swatchOverBackground(color: string, opacity: number | null, background: string): string;

package/dist/ui/legend-data.js

@@ -0,0 +1,40 @@
+import { mix } from "color2k";
+/** One legend section from a plugin's legend data; null for status-only data or no levels. */
+export function legendSection(data, format) {
+    if (!("scale" in data))
+        return null;
+    const { scale } = data;
+    if (scale.levels.length === 0)
+        return null;
+    const bar = scale.kind === "range" && data.display !== "blocks"
+        ? {
+            kind: "gradient",
+            stops: scale.levels.map((level) => ({
+                color: level.color ?? "",
+                label: level.label,
+                tick: level.min === null ? "" : format.number(Math.floor(level.min))
+            }))
+        }
+        : {
+            kind: "blocks",
+            blocks: scale.levels.map((level) => ({
+                color: level.color ?? "",
+                opacity: level.opacity,
+                label: level.label,
+                // A range scale's lower bound, for screen readers; categories have none.
+                tick: scale.kind === "range" && level.min !== null
+                    ? format.number(Math.floor(level.min))
+                    : ""
+            }))
+        };
+    return { pluginId: data.pluginId, title: data.title, units: data.units, bar };
+}
+/**
+ * How a translucent fill looks over the page background (`background` is the computed
+ * `--background`, in a form color2k parses). An empty color or no opacity returns the color.
+ */
+export function swatchOverBackground(color, opacity, background) {
+    if (!color || opacity === null)
+        return color;
+    return mix(background, color, opacity);
+}

package/dist/ui/level-chip.d.ts

@@ -0,0 +1,11 @@
+/** Colors for something filled with a level's color: the fill, a darker border, readable text. */
+export interface LevelChipColors {
+    background: string;
+    border: string;
+    text: string;
+}
+/**
+ * The colors for a level color, or null when it is empty or unparseable (color2k throws there,
+ * as monitor-map's `darken("")` did), so callers fall back to their neutral look.
+ */
+export declare function levelChip(color: string | null | undefined): LevelChipColors | null;

package/dist/ui/level-chip.js

@@ -0,0 +1,15 @@
+import { darken, readableColor } from "color2k";
+/**
+ * The colors for a level color, or null when it is empty or unparseable (color2k throws there,
+ * as monitor-map's `darken("")` did), so callers fall back to their neutral look.
+ */
+export function levelChip(color) {
+    if (!color)
+        return null;
+    try {
+        return { background: color, border: darken(color, 0.1), text: readableColor(color) };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/ui/value-format.d.ts

@@ -0,0 +1,8 @@
+import type { FormatProvider } from "../data/format.js";
+/**
+ * A numeric value with exactly `precision` decimal places, or as `format.number` gives it when
+ * there is no precision. Every place that shows a value (list rows, tooltips) goes through this,
+ * so they all agree. With `truncate` the extra decimals are cut off rather than rounded (9.96 at
+ * precision 1 is "9.9"), so the number never reads as the next level up.
+ */
+export declare function formatValue(value: number, precision: number | undefined, format: FormatProvider, truncate?: boolean): string;

package/dist/ui/value-format.js

@@ -0,0 +1,20 @@
+/**
+ * A numeric value with exactly `precision` decimal places, or as `format.number` gives it when
+ * there is no precision. Every place that shows a value (list rows, tooltips) goes through this,
+ * so they all agree. With `truncate` the extra decimals are cut off rather than rounded (9.96 at
+ * precision 1 is "9.9"), so the number never reads as the next level up.
+ */
+export function formatValue(value, precision, format, truncate = false) {
+    if (precision === undefined)
+        return format.number(value);
+    if (truncate) {
+        const factor = 10 ** precision;
+        // toPrecision drops float noise first (4.35 * 100 is 434.99999999999994); 15 digits keep
+        // any real value from rounding up.
+        value = Math.trunc(Number((value * factor).toPrecision(15))) / factor;
+    }
+    return format.number(value, {
+        minimumFractionDigits: precision,
+        maximumFractionDigits: precision
+    });
+}

package/dist/ui/view-summary.d.ts

@@ -0,0 +1,11 @@
+import type { FeatureListItem } from "../core/plugin.js";
+import type { MessageProvider } from "../data/messages.js";
+import type { Scale } from "../data/scale-types.js";
+/**
+ * One line describing the listed features: the layer, then how many are at each level, in the
+ * scale's order, zero counts left out (items with no level to show come last). With no scale, or
+ * nothing counted, just the count and layer.
+ */
+export declare function summaryText(layerLabel: string, items: FeatureListItem[], scale: Scale | null, messages: MessageProvider): string;
+/** How long after the last camera move or selection change the live region is updated. */
+export declare const SUMMARY_DEBOUNCE_MS = 750;

package/dist/ui/view-summary.js

@@ -0,0 +1,33 @@
+import { shownLevel } from "./feature-list.js";
+const list = new Intl.ListFormat("en-US", { type: "unit" });
+/**
+ * One line describing the listed features: the layer, then how many are at each level, in the
+ * scale's order, zero counts left out (items with no level to show come last). With no scale, or
+ * nothing counted, just the count and layer.
+ */
+export function summaryText(layerLabel, items, scale, messages) {
+    const plain = () => messages("mapsdk_summary", { count: items.length, layer: layerLabel });
+    if (!scale || items.length === 0)
+        return plain();
+    const counts = new Map();
+    let none = 0;
+    for (const item of items) {
+        const level = shownLevel(item);
+        if (level && scale.levels.some((l) => l.key === level.key)) {
+            counts.set(level.key, (counts.get(level.key) ?? 0) + 1);
+        }
+        else {
+            none++;
+        }
+    }
+    const parts = scale.levels.flatMap((level) => {
+        const count = counts.get(level.key);
+        return count ? [messages("mapsdk_summary_level", { count, level: level.label })] : [];
+    });
+    if (none > 0) {
+        parts.push(messages("mapsdk_summary_level", { count: none, level: messages("mapsdk_no_level") }));
+    }
+    return messages("mapsdk_summary_with_levels", { layer: layerLabel, levels: list.format(parts) });
+}
+/** How long after the last camera move or selection change the live region is updated. */
+export const SUMMARY_DEBOUNCE_MS = 750;