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

package/dist/ui/TooltipItem.svelte

@@ -0,0 +1,66 @@
+<script lang="ts">
+	import type { FormatProvider } from "../data/format.js";
+	import type { MessageProvider } from "../data/messages.js";
+	import type { FeatureListItem } from "../core/plugin.js";
+	import { NO_LEVEL } from "../data/scale.js";
+	import { levelChip } from "./level-chip.js";
+	import { formatValue } from "./value-format.js";
+
+	// The generic tooltip body under a feature's name: its value and a chip with its level. Shared
+	// by MapTooltip and by plugins that show it for features they don't list.
+
+	interface Props {
+		item: FeatureListItem;
+		messages: MessageProvider;
+		format: FormatProvider;
+	}
+
+	let { item, messages, format }: Props = $props();
+
+	// A level with an empty color shows its label on the neutral chip.
+	const level = $derived(item.level !== NO_LEVEL ? item.level : null);
+	const levelLabel = $derived(level ? level.label : messages("mapsdk_no_level"));
+	const chipColors = $derived.by(() => {
+		const chip = levelChip(level?.color);
+		return chip ? `background:${chip.background};color:${chip.text}` : "";
+	});
+	const valueText = $derived(
+		item.value == null
+			? null
+			: typeof item.value === "number"
+				? formatValue(item.value, item.precision, format)
+				: item.value
+	);
+</script>
+
+<div class="mapsdk-tooltip-item">
+	{#if valueText !== null}
+		<div class="mapsdk-tooltip-value">
+			{valueText}{#if item.units}&nbsp;{item.units}{/if}
+		</div>
+	{/if}
+	<span class="mapsdk-tooltip-chip text-xs" class:neutral={!chipColors} style={chipColors}>
+		{levelLabel}
+	</span>
+</div>
+
+<style>
+	.mapsdk-tooltip-item {
+		display: flex;
+		flex-direction: column;
+		align-items: flex-start;
+		gap: 0.25rem;
+	}
+
+	.mapsdk-tooltip-chip {
+		padding: 0.0625rem 0.5rem;
+		border: var(--swatch-outline-width, 1px) solid
+			var(--swatch-outline-color, color-mix(in srgb, var(--foreground) 75%, var(--background)));
+		border-radius: 999px;
+	}
+
+	.mapsdk-tooltip-chip.neutral {
+		background: var(--muted);
+		color: var(--muted-foreground);
+	}
+</style>

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/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,31 @@
+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 whose point is inside `bounds`, edges included. 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;
+/** 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;
+/** A row's accessible name: name, value, units, and level label. */
+export declare function rowLabel(item: FeatureListItem, messages: MessageProvider, format: FormatProvider): string;

package/dist/ui/feature-list.js

@@ -0,0 +1,80 @@
+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 whose point is inside `bounds`, edges included. No antimeridian handling (the Valley). */
+export function inView(items, bounds) {
+    return items.filter(({ lngLat: [lng, lat] }) => {
+        return lng >= bounds.west && lng <= bounds.east && lat >= bounds.south && lat <= bounds.north;
+    });
+}
+/**
+ * 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;
+}
+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;
+}
+/** A row's accessible name: name, value, units, and level label. */
+export function rowLabel(item, messages, format) {
+    if (item.value === null)
+        return messages("mapsdk_list_row_no_value", { name: item.name });
+    const level = shownLevel(item);
+    const params = {
+        name: item.name,
+        value: typeof item.value === "number" ? formatValue(item.value, item.precision, format) : item.value,
+        units: item.units,
+        level: level ? level.label : messages("mapsdk_no_level")
+    };
+    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,7 @@
+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.
+ */
+export declare function formatValue(value: number, precision: number | undefined, format: FormatProvider): string;

package/dist/ui/value-format.js

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+export function formatValue(value, precision, format) {
+    if (precision === undefined)
+        return format.number(value);
+    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;