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

package/dist/ui/feature-list.js

@@ -0,0 +1,95 @@
+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;
+}
+/**
+ * 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);
+    if (item.value === null) {
+        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: typeof item.value === "number" ? formatValue(item.value, item.precision, format) : item.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,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;

package/dist/view/MapView.svelte

@@ -0,0 +1,373 @@
+<script lang="ts">
+	import "@maptiler/sdk/dist/maptiler-sdk.css";
+	import "../ui/controls.css";
+	import { DEV } from "esm-env";
+	import type { Snippet } from "svelte";
+	import { untrack } from "svelte";
+	import { setMapContext } from "../core/context.js";
+	import type { MapContext } from "../core/create-map.svelte.js";
+	import type { GlMapLike } from "../core/gl.js";
+	import FeatureList from "../ui/FeatureList.svelte";
+	import type { SortBy } from "../ui/feature-list.js";
+	import MapControls from "../ui/MapControls.svelte";
+	import MapTooltip from "../ui/MapTooltip.svelte";
+	import SelectionBar from "../ui/SelectionBar.svelte";
+	import ViewSummary from "../ui/ViewSummary.svelte";
+	import { createDataCredits } from "../ui/data-credits.svelte.js";
+	import { createGlMap, setDataCredits, watchTheme } from "./create-gl-map.js";
+	import {
+		cornerSides,
+		resolveFeatureList,
+		type FeatureListOptions,
+		type ListPosition
+	} from "./list-placement.js";
+
+	interface Props {
+		/** The map to show. Fixed for the component's life. */
+		map: MapContext;
+		/** `false` releases the WebGL context; `true` rebuilds it with the same camera. */
+		active?: boolean;
+		class?: string;
+		/** The region's accessible name. Defaults to the `mapsdk_map_label` message. */
+		label?: string;
+		/** On-screen pieces drawn over the map; they get the map through `getMapContext()`. */
+		overlays?: Snippet;
+		/**
+		 * The List button and its feature list panel: `false` leaves them out; `true` (default) or
+		 * options place them. `position` picks the corner (default `"top-left"`); the button stacks
+		 * below (or, in a bottom corner, above) the controls in that corner, and the open panel stops
+		 * short of the controls and credits at the far end of its side. `reveal: "focus"` shows the
+		 * button only while it or its open panel has keyboard focus (and the whole time the panel is
+		 * open); otherwise it's visually hidden but stays in the Tab order, like a skip link.
+		 */
+		featureList?: boolean | FeatureListOptions;
+		/** `false` leaves out the selection bar. */
+		selectionBar?: boolean;
+		/**
+		 * The zoom controls: `"mapsdk"` (default) draws map-sdk's zoom buttons, `"engine"` the
+		 * MapTiler SDK's default zoom/compass and locate-me controls, `"none"` none. The credits
+		 * always show. Choose it up front: changing it after mount recreates the map (the engine
+		 * controls are part of how the map is built), like `active`.
+		 */
+		controls?: "mapsdk" | "engine" | "none";
+		/**
+		 * `"pinned"` (default) anchors the tooltip to its feature. `"pointer"` shows it at the
+		 * pointer, like sjvair.com's map, and hides it on zoom until the pointer moves again.
+		 * Keyboard focus from the feature list always shows it pinned.
+		 */
+		tooltip?: "pinned" | "pointer";
+	}
+
+	let {
+		map,
+		active = true,
+		class: className,
+		label,
+		overlays,
+		featureList = true,
+		selectionBar = true,
+		controls = "mapsdk",
+		tooltip = "pinned"
+	}: Props = $props();
+
+	const list = $derived(resolveFeatureList(featureList));
+	const sides = $derived(list ? cornerSides(list.position) : null);
+
+	const uid = $props.id();
+	const listId = `${uid}-list`;
+	let listOpen = $state(false);
+	// Kept here: the list is unmounted while closed, so it doesn't sort every feature on each move.
+	let listSort = $state<SortBy>("name");
+	let listButton: HTMLButtonElement | undefined = $state();
+	let listBox: HTMLDivElement | undefined = $state();
+	let listWidth = $state(0);
+
+	// The open panel's right edge, so focusing a feature pans it clear of the list.
+	$effect(() => {
+		const box = listOpen ? listBox : undefined;
+		void listWidth;
+		if (!box) {
+			map.setListInset(0);
+			return;
+		}
+		const panel = box.getBoundingClientRect();
+		const mapBox = root.getBoundingClientRect();
+		if (sides?.horizontal === "right") map.setListInset(mapBox.right - panel.left, "right");
+		else map.setListInset(panel.right - mapBox.left, "left");
+	});
+
+	// How far the controls in the button's corner, and in the other corner on its side, reach in
+	// from the map's top or bottom edge (px, 0 when there are none), so the button stacks clear of
+	// the first and the open panel stops short of the second. Measured, since the engine's
+	// controls change size (the credits switch between compact and full; MapTiler's logo).
+	let nearExtent = $state(0);
+	let farExtent = $state(0);
+
+	function extent(corner: ListPosition): number {
+		const mapBox = root.getBoundingClientRect();
+		const top = corner.startsWith("top");
+		const sources: Element[] = [];
+		const engine = glContainer.querySelector(`.maplibregl-ctrl-${corner}`);
+		if (engine) sources.push(engine);
+		if (corner === "top-right" && controls === "mapsdk") {
+			const zoom = root.querySelector(".mapsdk-zoom");
+			if (zoom) sources.push(zoom);
+		}
+		let reach = 0;
+		for (const el of sources) {
+			const r = el.getBoundingClientRect();
+			if (r.height === 0) continue;
+			reach = Math.max(reach, top ? r.bottom - mapBox.top : mapBox.bottom - r.top);
+		}
+		return Math.max(0, reach);
+	}
+
+	$effect(() => {
+		const s = sides;
+		void projector;
+		void controls;
+		if (!s) return;
+		const measure = () => {
+			nearExtent = extent(`${s.vertical}-${s.horizontal}`);
+			farExtent = extent(s.far);
+		};
+		const observer = new ResizeObserver(measure);
+		observer.observe(root);
+		const corners = [`${s.vertical}-${s.horizontal}`, s.far].map((c) =>
+			glContainer.querySelector(`.maplibregl-ctrl-${c}`)
+		);
+		for (const el of [...corners, root.querySelector(".mapsdk-zoom")]) {
+			if (el) observer.observe(el);
+		}
+		measure();
+		return () => observer.disconnect();
+	});
+
+	const inset = (reach: number) => (reach > 0 ? `calc(${reach}px + 0.5rem)` : undefined);
+
+	function onListKeydown(e: KeyboardEvent) {
+		if (e.key !== "Escape") return;
+		e.preventDefault();
+		listOpen = false;
+		listButton?.focus();
+	}
+
+	// The map is fixed for the component's life, so its first value is the one to provide.
+	// svelte-ignore state_referenced_locally
+	setMapContext(map);
+	// svelte-ignore state_referenced_locally
+	const firstMap = map;
+	if (DEV) {
+		$effect(() => {
+			if (map !== firstMap) {
+				console.warn(
+					"map-sdk: MapView's `map` prop changed after mount. It is fixed for the component's life (overlays keep the first map); wrap MapView in {#key map} to show another map."
+				);
+			}
+		});
+	}
+
+	const dataCredits = createDataCredits(firstMap);
+	// The dataset credits go in the engine's attribution control; it is replaced when they change.
+	$effect(() => {
+		const credits = dataCredits.list;
+		if (projector) untrack(() => setDataCredits(projector!, credits));
+	});
+
+	let root: HTMLDivElement;
+	let glContainer: HTMLDivElement;
+	// The live GL map and a counter bumped on every camera move or resize: the tooltip's `project` reads
+	// both, so it re-runs (and follows its feature) as the map moves.
+	let projector = $state.raw<GlMapLike | null>(null);
+	let moves = $state(0);
+	let width = $state(0);
+	let height = $state(0);
+
+	function project(lngLat: [number, number]) {
+		void moves;
+		return projector ? projector.project(lngLat) : null;
+	}
+
+	$effect(() => {
+		if (!active) return;
+		const ctx = map;
+		const engine = controls === "engine";
+		const gl = untrack(() => {
+			const gl = createGlMap(glContainer, ctx, engine);
+			try {
+				ctx.attach(gl);
+			} catch (error) {
+				gl.remove();
+				throw error;
+			}
+			return gl;
+		});
+		const onMove = () => moves++;
+		gl.on("move", onMove);
+		gl.on("resize", onMove);
+		projector = gl;
+		// Ready is the first idle after each style load (the first style, and every basemap
+		// switch). A wait still pending when the style is replaced or the map detached is dropped,
+		// so a stale idle never marks the context ready.
+		let stopWaiting: (() => void) | null = null;
+		const waitForIdle = () => {
+			stopWaiting?.();
+			const onIdle = () => {
+				stopWaiting?.();
+				if (ctx.gl === gl) ctx.markReady();
+			};
+			stopWaiting = () => {
+				gl.off("idle", onIdle);
+				stopWaiting = null;
+			};
+			gl.on("idle", onIdle);
+		};
+		gl.on("style.load", waitForIdle);
+		waitForIdle();
+		// Plugins bake theme colors into paint and images, so they set up again on a change.
+		const stopTheme = watchTheme(root, () => ctx.themeChanged());
+		return () => {
+			stopTheme();
+			gl.off("style.load", waitForIdle);
+			stopWaiting?.();
+			projector = null;
+			gl.off("move", onMove);
+			gl.off("resize", onMove);
+			try {
+				ctx.detach();
+			} finally {
+				gl.remove();
+			}
+		};
+	});
+</script>
+
+<div
+	bind:this={root}
+	bind:clientWidth={width}
+	bind:clientHeight={height}
+	class={["mapsdk-map mapsdk-focus-outline", className]}
+	role="region"
+	aria-label={label ?? map.messages("mapsdk_map_label")}
+	data-mapsdk-map={map.uid}
+>
+	<div class="mapsdk-gl" bind:this={glContainer}></div>
+	<MapTooltip {map} {project} {width} {height} mode={tooltip} gl={projector} />
+	{#if list && sides}
+		<div
+			class="mapsdk-list-panel"
+			data-position={list.position}
+			data-reveal={list.reveal}
+			data-open={listOpen}
+			style:--mapsdk-list-near={inset(nearExtent)}
+			style:--mapsdk-list-far={inset(farExtent)}
+		>
+			<button
+				bind:this={listButton}
+				type="button"
+				class="mapsdk-list-button mapsdk-focus mapsdk-motion text-sm"
+				aria-label={map.messages("mapsdk_list_button_label")}
+				aria-expanded={listOpen}
+				aria-controls={listOpen ? listId : undefined}
+				onclick={() => (listOpen = !listOpen)}
+			>
+				{map.messages("mapsdk_list_button")}
+			</button>
+			<!-- Escape anywhere in the panel closes it. -->
+			<!-- svelte-ignore a11y_no_static_element_interactions -->
+			{#if listOpen}
+				<div bind:this={listBox} bind:clientWidth={listWidth} onkeydown={onListKeydown}>
+					<FeatureList {map} id={listId} bind:sortBy={listSort} />
+				</div>
+			{/if}
+		</div>
+	{/if}
+	<!-- After the list, so Tab reaches the List button first. -->
+	{#if selectionBar}
+		<SelectionBar {map} clearRight={list?.position === "top-right" && controls === "none"} />
+	{/if}
+	<ViewSummary {map} />
+	{#if controls === "mapsdk"}
+		<MapControls {map} gl={projector} />
+	{/if}
+	{@render overlays?.()}
+</div>
+
+<style>
+	.mapsdk-map {
+		position: relative;
+	}
+
+	/* The region takes focus only from script (the selection bar's Clear), never from Tab: the
+	   outline alone, from .mapsdk-focus-outline. */
+	.mapsdk-gl {
+		position: absolute;
+		inset: 0;
+	}
+
+	/* In its corner: 0.75rem from the edges, or 0.5rem past the controls already there. The open
+	   panel also stops 0.5rem short of the controls at the far end of the side. */
+	.mapsdk-list-panel {
+		position: absolute;
+		z-index: 2;
+		display: flex;
+		flex-direction: column;
+		align-items: flex-start;
+		gap: 0.5rem;
+		max-height: calc(100% - var(--mapsdk-list-near, 0.75rem) - var(--mapsdk-list-far, 0.75rem));
+		pointer-events: none;
+	}
+
+	.mapsdk-list-panel[data-position^="top"] {
+		top: var(--mapsdk-list-near, 0.75rem);
+	}
+
+	.mapsdk-list-panel[data-position^="bottom"] {
+		bottom: var(--mapsdk-list-near, 0.75rem);
+		flex-direction: column-reverse;
+	}
+
+	.mapsdk-list-panel[data-position$="left"] {
+		left: 0.75rem;
+	}
+
+	.mapsdk-list-panel[data-position$="right"] {
+		right: 0.75rem;
+		align-items: flex-end;
+	}
+
+	/* reveal: "focus": hidden like a skip link (still in the Tab order and the accessibility tree)
+	   until it or its panel has focus, and shown the whole time the panel is open. No transition. */
+	.mapsdk-list-panel[data-reveal="focus"][data-open="false"]:not(:focus-within)
+		.mapsdk-list-button {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		padding: 0;
+		border: 0;
+		overflow: hidden;
+		clip-path: inset(50%);
+		white-space: nowrap;
+	}
+
+	.mapsdk-list-panel > div {
+		display: flex;
+		min-height: 0;
+	}
+
+	.mapsdk-list-button {
+		padding: 0.375rem 0.75rem;
+		border: 1px solid var(--card-border, var(--border));
+		border-radius: var(--radius-control, var(--radius));
+		background: var(--background);
+		color: var(--foreground);
+		box-shadow: var(--shadow-card, none);
+		font-family: inherit;
+		cursor: pointer;
+		pointer-events: auto;
+	}
+
+	.mapsdk-list-button:hover {
+		background: var(--accent, var(--muted));
+	}
+</style>