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

package/dist/ui/Legend.svelte

@@ -0,0 +1,213 @@
+<script lang="ts">
+	import { onMount, untrack } from "svelte";
+	import "./controls.css";
+	import type { MapContext } from "../core/create-map.svelte.js";
+	import { watchTheme } from "../view/create-gl-map.js";
+	import LegendBar from "./LegendBar.svelte";
+	import { legendSection, type LegendEntry } from "./legend-data.js";
+
+	let {
+		map,
+		order = "bottom-first",
+		framed = true
+	}: {
+		map: MapContext;
+		/**
+		 * `true` (default) draws the legend's own card. `false` draws no frame (no border,
+		 * background, padding, or fixed width) so a host's card frames it. Translucent swatches
+		 * then blend over the nearest ancestor with an opaque background (a see-through card is
+		 * skipped), else the `--background` token. The color is read on mount, when `framed`
+		 * changes, and on a theme change; a card that changes color through its own class or
+		 * style isn't re-read.
+		 */
+		framed?: boolean;
+		/**
+		 * `"bottom-first"` (default) lists the bottom plugin's section first; `"top-first"`
+		 * last.
+		 */
+		order?: "bottom-first" | "top-first";
+	} = $props();
+
+	let root: HTMLElement | undefined = $state();
+	// The `--background` token as rgb, for mixing translucent swatches over it. Read as soon as the
+	// element exists (the bars wait for it), so no color is assumed before.
+	let background = $state<string | null>(null);
+
+	/**
+	 * A section per plugin with a scale, and a status line per plugin still loading or failing, in
+	 * `order`.
+	 */
+	const entries = $derived(
+		(order === "top-first" ? [...map.plugins].reverse() : map.plugins).flatMap(
+			(plugin): LegendEntry[] => {
+				const data = plugin.legend?.();
+				if (!data) return [];
+				if ("status" in data) {
+					if (data.status.state === "ready") return [];
+					const layer = plugin.label ?? plugin.id;
+					return [{ kind: "status", pluginId: data.pluginId, layer, status: data.status }];
+				}
+				const section = legendSection(data, map.format);
+				return section ? [{ kind: "scale", section }] : [];
+			}
+		)
+	);
+
+	/**
+	 * A computed color as rgb and whether it's opaque; computed colors can be oklch() or color(),
+	 * and a 1x1 canvas turns any of them into rgb.
+	 */
+	function toRgb(css: string): { rgb: string; opaque: boolean } {
+		const ctx = document.createElement("canvas").getContext("2d");
+		if (!ctx) return { rgb: css, opaque: true };
+		ctx.clearRect(0, 0, 1, 1);
+		ctx.fillStyle = css;
+		ctx.fillRect(0, 0, 1, 1);
+		const [r, g, b, a] = ctx.getImageData(0, 0, 1, 1).data;
+		return { rgb: `rgb(${r}, ${g}, ${b})`, opaque: a === 255 };
+	}
+
+	/**
+	 * What translucent swatches blend over: the legend's own card, or without a frame the nearest
+	 * ancestor with an opaque background (the host's card), else the `--background` token.
+	 */
+	function resolveBackground(el: HTMLElement, frameless: boolean): string {
+		if (!frameless) return toRgb(getComputedStyle(el).backgroundColor).rgb;
+		for (let at = el.parentElement; at; at = at.parentElement) {
+			const color = toRgb(getComputedStyle(at).backgroundColor);
+			if (color.opaque) return color.rgb;
+		}
+		// A computed custom property has its var() references already substituted.
+		return toRgb(getComputedStyle(el).getPropertyValue("--background").trim()).rgb;
+	}
+
+	function update() {
+		if (root) background = resolveBackground(root, !framed);
+	}
+
+	onMount(() => watchTheme(root!, update));
+
+	// On mount, and again when `framed` changes.
+	$effect(() => {
+		void framed;
+		untrack(update);
+	});
+</script>
+
+<section
+	bind:this={root}
+	class={["mapsdk-legend", !framed && "mapsdk-legend-frameless"]}
+	aria-label={map.messages("mapsdk_legend_label")}
+	hidden={entries.length === 0}
+>
+	{#each entries as entry (entry.kind === "scale" ? entry.section.pluginId : entry.pluginId)}
+		{#if entry.kind === "scale"}
+			{@const section = entry.section}
+			<div class="mapsdk-legend-section">
+				<h3 class="text-sm">
+					{section.title}
+					{#if section.units}
+						<span class="text-xs">({section.units})</span>
+					{/if}
+				</h3>
+				{#if background !== null}
+					<LegendBar bar={section.bar} {background} messages={map.messages} />
+				{/if}
+			</div>
+		{:else}
+			{@const status = entry.status}
+			<div class="mapsdk-legend-status text-sm" role="status">
+				{#if status.state === "loading"}
+					<h3 class="text-sm">{entry.layer}</h3>
+					<p>{map.messages("mapsdk_loading")}</p>
+				{:else}
+					<p>{map.messages("mapsdk_unavailable", { layer: entry.layer })}</p>
+					{#if status.state === "error"}
+						<button
+							type="button"
+							class="mapsdk-retry mapsdk-focus mapsdk-motion text-sm"
+							onclick={() => status.retry()}
+						>
+							{map.messages("mapsdk_error_retry")}
+						</button>
+					{/if}
+				{/if}
+			</div>
+		{/if}
+	{/each}
+</section>
+
+<style>
+	.mapsdk-legend {
+		display: flex;
+		flex-direction: column;
+		gap: 0.75rem;
+		width: 21rem;
+		max-width: calc(100vw - 2rem);
+		box-sizing: border-box;
+		padding: 0.75rem 1rem;
+		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;
+	}
+
+	/* framed={false}: the host's card is the frame. */
+	.mapsdk-legend-frameless {
+		width: auto;
+		max-width: none;
+		padding: 0;
+		border: 0;
+		border-radius: 0;
+		background: none;
+		box-shadow: none;
+	}
+
+	.mapsdk-legend[hidden] {
+		display: none;
+	}
+
+	h3 {
+		margin: 0 0 0.5rem;
+		text-align: center;
+		font-weight: 600;
+	}
+
+	.mapsdk-legend-status {
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+		gap: 0.5rem;
+		text-align: center;
+	}
+
+	.mapsdk-legend-status h3 {
+		margin: 0;
+	}
+
+	.mapsdk-legend-status p {
+		margin: 0;
+		color: var(--muted-foreground);
+	}
+
+	.mapsdk-retry {
+		padding: 0.25rem 0.75rem;
+		border: 1px solid var(--border);
+		border-radius: var(--radius-control, var(--radius));
+		background: var(--background);
+		color: var(--foreground);
+		font: inherit;
+		cursor: pointer;
+	}
+
+	.mapsdk-retry:hover {
+		background: var(--accent, var(--muted));
+	}
+
+	h3 span {
+		font-weight: 400;
+		color: var(--muted-foreground);
+	}
+</style>

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

@@ -0,0 +1,22 @@
+import "./controls.css";
+import type { MapContext } from "../core/create-map.svelte.js";
+type $$ComponentProps = {
+    map: MapContext;
+    /**
+     * `true` (default) draws the legend's own card. `false` draws no frame (no border,
+     * background, padding, or fixed width) so a host's card frames it. Translucent swatches
+     * then blend over the nearest ancestor with an opaque background (a see-through card is
+     * skipped), else the `--background` token. The color is read on mount, when `framed`
+     * changes, and on a theme change; a card that changes color through its own class or
+     * style isn't re-read.
+     */
+    framed?: boolean;
+    /**
+     * `"bottom-first"` (default) lists the bottom plugin's section first; `"top-first"`
+     * last.
+     */
+    order?: "bottom-first" | "top-first";
+};
+declare const Legend: import("svelte").Component<$$ComponentProps, {}, "">;
+type Legend = ReturnType<typeof Legend>;
+export default Legend;

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;