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

package/dist/ui/LegendBar.svelte

@@ -0,0 +1,161 @@
+<script lang="ts">
+	import type { MessageProvider } from "../data/messages.js";
+	import { swatchOverBackground, type LegendBar } from "./legend-data.js";
+
+	interface Props {
+		bar: LegendBar;
+		/** The page background as a color color2k can parse. */
+		background: string;
+		messages: MessageProvider;
+	}
+
+	let { bar, background, messages }: Props = $props();
+
+	// An empty color (a level with none) gets a neutral swatch rather than nothing.
+	const NEUTRAL = "var(--muted-foreground)";
+
+	const items = $derived(
+		bar.kind === "gradient"
+			? bar.stops.map((stop) => ({
+					color: stop.color || NEUTRAL,
+					label: stop.label,
+					// The ticks are aria-hidden, so their numbers reach screen readers here.
+					threshold: stop.tick ? messages("mapsdk_legend_threshold", { value: stop.tick }) : ""
+				}))
+			: bar.blocks.map((block) => ({
+					color: block.color
+						? swatchOverBackground(block.color, block.opacity, background)
+						: NEUTRAL,
+					label: block.label,
+					threshold: block.tick ? messages("mapsdk_legend_threshold", { value: block.tick }) : ""
+				}))
+	);
+
+	const gradient = $derived(
+		bar.kind === "gradient" && bar.stops.length > 0
+			? bar.stops.length === 1
+				? items[0].color
+				: `linear-gradient(to right, ${items.map((item) => item.color).join(", ")})`
+			: null
+	);
+</script>
+
+{#if bar.kind === "gradient" && gradient}
+	<div class="mapsdk-legend-gradient" style:background={gradient} aria-hidden="true"></div>
+	<div class="mapsdk-legend-ticks text-xs" aria-hidden="true">
+		{#each bar.stops as stop, i (i)}
+			<span>{stop.tick}</span>
+		{/each}
+	</div>
+{/if}
+{#if bar.kind === "blocks"}
+	<!-- One contiguous bar, each level's label under its segment (a list for screen readers). -->
+	<div class="mapsdk-legend-blocks" aria-hidden="true">
+		{#each items as item, i (i)}
+			<span class="mapsdk-legend-block" style:background={item.color}></span>
+		{/each}
+	</div>
+	<ul class="mapsdk-legend-block-labels text-xs" style:--blocks={items.length}>
+		{#each items as item, i (i)}
+			<li>
+				{item.label}
+				{#if item.threshold}<span class="mapsdk-legend-threshold">{item.threshold}</span>{/if}
+			</li>
+		{/each}
+	</ul>
+{:else}
+	<ul class="mapsdk-legend-items text-xs">
+		{#each items as item, i (i)}
+			<li>
+				<span class="mapsdk-legend-swatch" style:background={item.color}></span>
+				<span>{item.label}</span>
+				{#if item.threshold}<span class="mapsdk-legend-threshold">{item.threshold}</span>{/if}
+			</li>
+		{/each}
+	</ul>
+{/if}
+
+<style>
+	.mapsdk-legend-gradient {
+		height: 0.75rem;
+		border-radius: 0.25rem;
+		outline: var(--swatch-outline-width, 1px) solid
+			var(--swatch-outline-color, color-mix(in srgb, var(--foreground) 75%, var(--background)));
+		outline-offset: 1px;
+	}
+
+	.mapsdk-legend-blocks {
+		display: flex;
+		height: 0.75rem;
+		border-radius: 0.25rem;
+		overflow: hidden;
+		outline: var(--swatch-outline-width, 1px) solid
+			var(--swatch-outline-color, color-mix(in srgb, var(--foreground) 75%, var(--background)));
+		outline-offset: 1px;
+	}
+
+	.mapsdk-legend-block {
+		flex: 1 1 0;
+	}
+
+	/* Equal columns under the equal segments; long labels wrap inside their column. */
+	.mapsdk-legend-block-labels {
+		display: grid;
+		grid-template-columns: repeat(var(--blocks), minmax(0, 1fr));
+		margin: 0.375rem 0 0;
+		padding: 0;
+		list-style: none;
+		text-align: center;
+	}
+
+	.mapsdk-legend-block-labels li {
+		position: relative;
+		padding: 0 0.125rem;
+		overflow-wrap: anywhere;
+	}
+
+	.mapsdk-legend-ticks {
+		display: flex;
+		justify-content: space-between;
+		margin-top: 0.375rem;
+		font-variant-numeric: tabular-nums;
+	}
+
+	.mapsdk-legend-items {
+		display: flex;
+		flex-wrap: wrap;
+		gap: 0.25rem 0.75rem;
+		margin: 0.5rem 0 0;
+		padding: 0;
+		list-style: none;
+	}
+
+	/* Visually hidden, read after the label. */
+	.mapsdk-legend-threshold {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		overflow: hidden;
+		clip-path: inset(50%);
+		white-space: nowrap;
+	}
+
+	.mapsdk-legend-items li {
+		position: relative;
+		display: flex;
+		align-items: center;
+		gap: 0.375rem;
+	}
+
+	/* The outline sits 1px off the swatch, over the background, so it needs 3:1 against the
+	   background only; the gap keeps a swatch near the outline's own color readable. */
+	.mapsdk-legend-swatch {
+		width: 0.875rem;
+		height: 0.875rem;
+		flex: none;
+		border-radius: 0.125rem;
+		outline: var(--swatch-outline-width, 1px) solid
+			var(--swatch-outline-color, color-mix(in srgb, var(--foreground) 75%, var(--background)));
+		outline-offset: 1px;
+	}
+</style>

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

@@ -0,0 +1,11 @@
+import type { MessageProvider } from "../data/messages.js";
+import { type LegendBar } from "./legend-data.js";
+interface Props {
+    bar: LegendBar;
+    /** The page background as a color color2k can parse. */
+    background: string;
+    messages: MessageProvider;
+}
+declare const LegendBar: import("svelte").Component<Props, {}, "">;
+type LegendBar = ReturnType<typeof LegendBar>;
+export default LegendBar;

package/dist/ui/MapControls.svelte

@@ -0,0 +1,135 @@
+<script lang="ts">
+	import "./controls.css";
+	import type { MapContext } from "../core/create-map.svelte.js";
+	import type { GlMapLike } from "../core/gl.js";
+
+	interface Props {
+		map: MapContext;
+		/** The live GL map; the zoom buttons do nothing while it is `null`. */
+		gl: GlMapLike | null;
+	}
+
+	let { map, gl }: Props = $props();
+
+	function zoomBy(delta: number) {
+		if (!gl) return;
+		const reduced = globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches ?? false;
+		gl.easeTo({ zoom: gl.getZoom() + delta, ...(reduced && { duration: 0 }) });
+	}
+</script>
+
+<div class="mapsdk-zoom" role="group" aria-label={map.messages("mapsdk_controls_label")}>
+	<button type="button" class="mapsdk-focus mapsdk-motion" disabled={!gl} onclick={() => zoomBy(1)}>
+		<span class="mapsdk-zoom-icon" aria-hidden="true">+</span>
+		<span class="mapsdk-sr">{map.messages("mapsdk_zoom_in")}</span>
+		<span class="mapsdk-zoom-tip mapsdk-motion text-xs" aria-hidden="true"
+			>{map.messages("mapsdk_zoom_in")}</span
+		>
+	</button>
+	<button
+		type="button"
+		class="mapsdk-focus mapsdk-motion"
+		disabled={!gl}
+		onclick={() => zoomBy(-1)}
+	>
+		<span class="mapsdk-zoom-icon" aria-hidden="true">&minus;</span>
+		<span class="mapsdk-sr">{map.messages("mapsdk_zoom_out")}</span>
+		<span class="mapsdk-zoom-tip mapsdk-motion text-xs" aria-hidden="true"
+			>{map.messages("mapsdk_zoom_out")}</span
+		>
+	</button>
+</div>
+
+<style>
+	.mapsdk-zoom {
+		position: absolute;
+		top: 0.75rem;
+		right: 0.75rem;
+		z-index: 2;
+		display: flex;
+		flex-direction: column;
+		border: 1px solid var(--card-border, var(--border));
+		border-radius: var(--radius-control, var(--radius));
+		background: var(--background);
+		box-shadow: var(--shadow-card, none);
+		pointer-events: auto;
+	}
+
+	.mapsdk-zoom button {
+		width: 2.25rem;
+		height: 2.25rem;
+		padding: 0;
+		border: 0;
+		background: transparent;
+		color: var(--foreground);
+		font: inherit;
+		cursor: pointer;
+	}
+
+	.mapsdk-zoom button + button {
+		border-top: 1px solid var(--card-border, var(--border));
+	}
+
+	.mapsdk-zoom button:disabled {
+		color: var(--muted-foreground);
+		cursor: default;
+	}
+
+	.mapsdk-zoom button {
+		position: relative;
+	}
+
+	/* The hover fill follows the group's rounded corners. */
+	.mapsdk-zoom button:first-child {
+		border-radius: var(--radius-control, var(--radius)) var(--radius-control, var(--radius)) 0 0;
+	}
+
+	.mapsdk-zoom button:last-child {
+		border-radius: 0 0 var(--radius-control, var(--radius)) var(--radius-control, var(--radius));
+	}
+
+	.mapsdk-zoom button:hover:not(:disabled) {
+		background: var(--accent, var(--muted));
+	}
+
+	/* Above the next button, so the ring isn't cut by it. */
+	.mapsdk-zoom button:focus-visible {
+		z-index: 1;
+	}
+
+	/* The visible name: on hover and focus, left of the button; the screen-reader text stays. */
+	.mapsdk-zoom-tip {
+		position: absolute;
+		top: 50%;
+		right: calc(100% + 0.5rem);
+		padding: 0.125rem 0.5rem;
+		border: 1px solid var(--card-border, var(--border));
+		border-radius: var(--radius-control, var(--radius));
+		background: var(--popover, var(--background));
+		color: var(--popover-foreground, var(--foreground));
+		box-shadow: var(--shadow-lifted, var(--shadow-card, none));
+		white-space: nowrap;
+		opacity: 0;
+		pointer-events: none;
+		transform: translateY(-50%);
+	}
+
+	.mapsdk-zoom button:hover .mapsdk-zoom-tip,
+	.mapsdk-zoom button:focus-visible .mapsdk-zoom-tip {
+		opacity: 1;
+	}
+
+	.mapsdk-zoom-icon {
+		font-size: 1.25rem;
+		line-height: 1;
+	}
+
+	.mapsdk-sr {
+		position: absolute;
+		width: 1px;
+		height: 1px;
+		overflow: hidden;
+		clip-path: inset(50%);
+		white-space: nowrap;
+	}
+</style>

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

@@ -0,0 +1,11 @@
+import "./controls.css";
+import type { MapContext } from "../core/create-map.svelte.js";
+import type { GlMapLike } from "../core/gl.js";
+interface Props {
+    map: MapContext;
+    /** The live GL map; the zoom buttons do nothing while it is `null`. */
+    gl: GlMapLike | null;
+}
+declare const MapControls: import("svelte").Component<Props, {}, "">;
+type MapControls = ReturnType<typeof MapControls>;
+export default MapControls;

package/dist/ui/MapTooltip.svelte

@@ -0,0 +1,158 @@
+<script lang="ts">
+	import { untrack } from "svelte";
+	import type { MapContext } from "../core/create-map.svelte.js";
+	import type { GlMapLike } from "../core/gl.js";
+	import type { FeatureListItem, MapPlugin } from "../core/plugin.js";
+	import TooltipItem from "./TooltipItem.svelte";
+
+	interface Props {
+		map: MapContext;
+		/**
+		 * Canvas pixel for a position, or `null` while there is no GL map. Reactive: it should
+		 * read something that changes when the camera moves, so the tooltip follows the map.
+		 */
+		project: (lngLat: [number, number]) => { x: number; y: number } | null;
+		/** The map container's size; the tooltip stays inside it. Unset: no clamping. */
+		width?: number;
+		height?: number;
+		/**
+		 * `"pinned"` (default) anchors the tooltip to its feature; `"pointer"` shows it at the last
+		 * pointer position and hides it on `gl`'s `zoomstart` until the next pointer move over a
+		 * hit.
+		 * A keyboard-focused list item is always pinned.
+		 */
+		mode?: "pinned" | "pointer";
+		/** The GL map, for `zoomstart` in `"pointer"` mode. */
+		gl?: Pick<GlMapLike, "on" | "off"> | null;
+	}
+
+	let { map, project, width, height, mode = "pinned", gl = null }: Props = $props();
+
+	// Pointer mode only: set by a zoom, cleared by the next pointer move over a hit.
+	let zoomHidden = $state(false);
+	$effect(() => {
+		if (mode !== "pointer" || !gl) return;
+		const onZoomStart = () => (zoomHidden = true);
+		gl.on("zoomstart", onZoomStart);
+		return () => gl.off("zoomstart", onZoomStart);
+	});
+	$effect(() => {
+		// A new hovered object comes with every pointer move over a hit.
+		if (map.hovered) zoomHidden = false;
+	});
+
+	let tipWidth = $state(0);
+	let tipHeight = $state(0);
+	const GAP = 12;
+
+	// The keyboard-focused list item wins over the pointer.
+	const key = $derived(map.focusedKey ?? map.hovered?.hit.refKey ?? null);
+	// Primitives, so moving the pointer within one feature doesn't recompute the content.
+	const hitPluginId = $derived(map.focusedKey ? null : (map.hovered?.hit.pluginId ?? null));
+	const hitName = $derived(map.focusedKey ? null : (map.hovered?.hit.name ?? null));
+
+	// Reads only the shown feature's plugin (or all plugins for a focused key), and only while
+	// something is shown, so an idle map doesn't subscribe to any plugin's data.
+	const found = $derived.by((): { item: FeatureListItem; plugin: MapPlugin } | null => {
+		if (key === null) return null;
+		// The hovered hit's plugin, or the focused one; without either, the first plugin listing the key.
+		const pluginId = hitPluginId ?? map.focusedPluginId;
+		const plugins = pluginId ? map.plugins.filter((p) => p.id === pluginId) : map.plugins;
+		for (const plugin of plugins) {
+			const item = plugin.features?.().find((f) => f.refKey === key);
+			if (item) return { item, plugin };
+		}
+		return null;
+	});
+
+	const item = $derived(found?.item ?? null);
+	const name = $derived(item?.name ?? hitName);
+	// A found item anchors the tooltip at its point (stable while the pointer moves over it).
+	// In pointer mode a hovered hit is anchored at the pointer instead (a focused item stays
+	// pinned).
+	const anchor = $derived(
+		mode === "pointer" && !map.focusedKey
+			? (map.hovered?.lngLat ?? null)
+			: (item?.lngLat ?? map.hovered?.lngLat ?? null)
+	);
+	const projected = $derived(anchor ? project(anchor) : null);
+	// Centered above the point; flipped below it near the top edge; inside the container.
+	const position = $derived.by(() => {
+		if (!projected) return null;
+		let { x, y } = projected;
+		if (width)
+			x = Math.min(Math.max(x, tipWidth / 2), Math.max(width - tipWidth / 2, tipWidth / 2));
+		let top = y - tipHeight - GAP;
+		if (top < 0) top = y + GAP;
+		if (height) top = Math.min(top, Math.max(height - tipHeight, 0));
+		return { left: x - tipWidth / 2, top: Math.max(top, 0) };
+	});
+	const custom = $derived.by(() => {
+		if (found) return found.plugin.tooltip?.(found.item);
+		// A hovered hit no plugin lists (e.g. a cluster bubble): its plugin's hover content.
+		if (key === null || hitPluginId === null) return undefined;
+		const plugin = map.plugins.find((p) => p.id === hitPluginId);
+		const hit = untrack(() => map.hovered?.hit);
+		return hit && plugin?.hoverTooltip?.(hit);
+	});
+
+	// The name header is left out when the plugin's own tooltip content shows the name.
+	const showName = $derived.by(() => {
+		if (!name) return false;
+		if (!custom) return true;
+		const plugin = found?.plugin ?? map.plugins.find((p) => p.id === hitPluginId);
+		return !plugin?.tooltipShowsName;
+	});
+</script>
+
+<!-- Only with something to show: a hit with no name, item, or content gets no empty box. -->
+{#if (name || item || custom) && position && !(zoomHidden && !map.focusedKey)}
+	<div
+		class="mapsdk-tooltip text-sm"
+		role="tooltip"
+		bind:offsetWidth={tipWidth}
+		bind:offsetHeight={tipHeight}
+		style:left="{position.left}px"
+		style:top="{position.top}px"
+	>
+		{#if showName}
+			<div class="mapsdk-tooltip-name">{name}</div>
+		{/if}
+		{#if custom}
+			{@render custom()}
+		{:else if item}
+			<TooltipItem {item} messages={map.messages} format={map.format} />
+		{/if}
+	</div>
+{/if}
+
+<style>
+	.mapsdk-tooltip {
+		position: absolute;
+		z-index: 1;
+		display: flex;
+		flex-direction: column;
+		align-items: flex-start;
+		gap: 0.25rem;
+		max-width: 16rem;
+		box-sizing: border-box;
+		padding: 0.5rem 0.75rem;
+		border: 1px solid var(--card-border, var(--border));
+		border-radius: var(--radius-control, var(--radius));
+		background: var(--popover, var(--background));
+		color: var(--popover-foreground, var(--foreground));
+		box-shadow: var(--shadow-lifted, var(--shadow-card, none));
+		pointer-events: none;
+	}
+
+	/* The monitor, cluster, and collocation tooltips (today's ~420px cards) mark their content
+	   `mapsdk-tooltip-wide`: wide enough for a reading box and name, never wider than the map. */
+	.mapsdk-tooltip:has(:global(.mapsdk-tooltip-wide)) {
+		width: max-content;
+		max-width: min(28rem, calc(100% - 1rem));
+	}
+
+	.mapsdk-tooltip-name {
+		font-weight: 600;
+	}
+</style>

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

@@ -0,0 +1,28 @@
+import type { MapContext } from "../core/create-map.svelte.js";
+import type { GlMapLike } from "../core/gl.js";
+interface Props {
+    map: MapContext;
+    /**
+     * Canvas pixel for a position, or `null` while there is no GL map. Reactive: it should
+     * read something that changes when the camera moves, so the tooltip follows the map.
+     */
+    project: (lngLat: [number, number]) => {
+        x: number;
+        y: number;
+    } | null;
+    /** The map container's size; the tooltip stays inside it. Unset: no clamping. */
+    width?: number;
+    height?: number;
+    /**
+     * `"pinned"` (default) anchors the tooltip to its feature; `"pointer"` shows it at the last
+     * pointer position and hides it on `gl`'s `zoomstart` until the next pointer move over a
+     * hit.
+     * A keyboard-focused list item is always pinned.
+     */
+    mode?: "pinned" | "pointer";
+    /** The GL map, for `zoomstart` in `"pointer"` mode. */
+    gl?: Pick<GlMapLike, "on" | "off"> | null;
+}
+declare const MapTooltip: import("svelte").Component<Props, {}, "">;
+type MapTooltip = ReturnType<typeof MapTooltip>;
+export default MapTooltip;

package/dist/ui/SelectionBar.svelte

@@ -0,0 +1,123 @@
+<script lang="ts">
+	import type { MapContext } from "../core/create-map.svelte.js";
+	import "./controls.css";
+
+	interface Props {
+		map: MapContext;
+		/** Leaves room at the right for a top-right List button, as the bar does at the left. */
+		clearRight?: boolean;
+	}
+
+	let { map, clearRight = false }: Props = $props();
+
+	let bar: HTMLElement | undefined = $state();
+
+	// Every id counts, whether or not it is in the data: a host may select features that load later.
+	const entries = $derived(
+		map.plugins.flatMap((plugin) => {
+			const count = map.getSelection(plugin.id)?.ids.length ?? 0;
+			return count > 0 ? [{ id: plugin.id, layer: plugin.label ?? plugin.id, count }] : [];
+		})
+	);
+
+	/**
+	 * Clears one plugin's selection. The button is about to go (or its row is), so focus moves
+	 * first: to another plugin's Clear button, else the List button, else the map region.
+	 */
+	function clear(id: string, button: HTMLElement) {
+		const another = [...(bar?.querySelectorAll<HTMLElement>("button") ?? [])].find(
+			(b) => b !== button
+		);
+		const region = bar?.closest<HTMLElement>("[data-mapsdk-map]");
+		const target = another ?? region?.querySelector<HTMLElement>(".mapsdk-list-button") ?? region;
+		if (target === region && region && !region.hasAttribute("tabindex")) {
+			region.setAttribute("tabindex", "-1");
+		}
+		target?.focus();
+		map.clearSelection(id);
+	}
+</script>
+
+{#if entries.length > 0}
+	<div
+		bind:this={bar}
+		class={["mapsdk-selection text-sm", clearRight && "mapsdk-selection-clear-right"]}
+		role="group"
+		aria-label={map.messages("mapsdk_selection_label")}
+	>
+		{#each entries as entry (entry.id)}
+			{@const selected = map.messages("mapsdk_selected_count", { count: entry.count })}
+			<div class="mapsdk-selection-row">
+				<span>
+					{entries.length > 1
+						? map.messages("mapsdk_selected_in_layer", { layer: entry.layer, selected })
+						: selected}
+				</span>
+				<button
+					type="button"
+					class="mapsdk-focus mapsdk-motion"
+					aria-label={map.messages("mapsdk_selection_clear_layer", { layer: entry.layer })}
+					onclick={(e) => clear(entry.id, e.currentTarget)}
+				>
+					{map.messages("mapsdk_selection_clear")}
+				</button>
+			</div>
+		{/each}
+	</div>
+{/if}
+
+<style>
+	.mapsdk-selection {
+		position: absolute;
+		top: 0.75rem;
+		/* Clear of the List button (left) and the zoom buttons (right); centered between them. */
+		right: 4rem;
+		left: 5rem;
+		z-index: 2;
+		display: flex;
+		flex-direction: column;
+		gap: 0.25rem;
+		box-sizing: border-box;
+		width: fit-content;
+		margin-inline: auto;
+		padding: 0.375rem 0.5rem 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);
+		pointer-events: auto;
+	}
+
+	.mapsdk-selection-clear-right {
+		right: 5rem;
+	}
+
+	.mapsdk-selection-row {
+		display: flex;
+		flex-wrap: wrap;
+		align-items: center;
+		justify-content: space-between;
+		gap: 0.25rem 0.75rem;
+	}
+
+	.mapsdk-selection-row span {
+		min-width: 0;
+		overflow-wrap: anywhere;
+	}
+
+	button {
+		flex: none;
+		padding: 0.25rem 0.625rem;
+		border: 1px solid var(--border);
+		border-radius: var(--radius-control, var(--radius));
+		background: var(--background);
+		color: var(--foreground);
+		font: inherit;
+		cursor: pointer;
+	}
+
+	button:hover {
+		background: var(--accent, var(--muted));
+	}
+</style>

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

@@ -0,0 +1,10 @@
+import type { MapContext } from "../core/create-map.svelte.js";
+import "./controls.css";
+interface Props {
+    map: MapContext;
+    /** Leaves room at the right for a top-right List button, as the bar does at the left. */
+    clearRight?: boolean;
+}
+declare const SelectionBar: import("svelte").Component<Props, {}, "">;
+type SelectionBar = ReturnType<typeof SelectionBar>;
+export default SelectionBar;