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

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>

package/dist/view/MapView.svelte.d.ts

@@ -0,0 +1,43 @@
+import "@maptiler/sdk/dist/maptiler-sdk.css";
+import "../ui/controls.css";
+import type { Snippet } from "svelte";
+import type { MapContext } from "../core/create-map.svelte.js";
+import { type FeatureListOptions } 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";
+}
+declare const MapView: import("svelte").Component<Props, {}, "">;
+type MapView = ReturnType<typeof MapView>;
+export default MapView;

package/dist/view/create-gl-map.d.ts

@@ -0,0 +1,34 @@
+import type { BasemapConfig } from "../core/basemap.svelte.js";
+import type { MapContext } from "../core/create-map.svelte.js";
+import type { GlMapLike } from "../core/gl.js";
+/**
+ * Calls `onChange` when the host's theme changes the tokens map colors are read from: on a
+ * `prefers-color-scheme` change, or a `data-theme`, `class`, or `style` change on `<html>`.
+ * Changes that leave the tokens on `container` as they were (e.g. a scroll lock's inline style)
+ * are ignored. Returns the stop function.
+ */
+export declare function watchTheme(container: Element, onChange: () => void): () => void;
+/** Today's live map: MapTiler Streets v4 and its variants, without the busy POI label layers. */
+export declare function defaultBasemaps(): BasemapConfig;
+/**
+ * A `transformRequest` that adds `key` to MapTiler API requests that have none. The SDK's own
+ * transform runs after it and only adds its global `config.apiKey` when `key` is missing, so
+ * each map's requests carry its own key, and two maps with different keys don't clash.
+ */
+export declare function maptilerKeyTransform(key: string): (url: string) => {
+    url: string;
+};
+/**
+ * Creates the MapTiler map for `ctx` in `container`, at `ctx`'s camera with its current basemap.
+ * Reads `ctx` untracked, so calling this in an effect doesn't make it depend on the camera or
+ * basemap. With `engineControls`, the MapTiler SDK adds its default zoom/compass and locate-me
+ * controls at the top right; they go with the map.
+ * Records the camera and bounds once the map loads and after every move.
+ */
+export declare function createGlMap(container: HTMLElement, ctx: MapContext, engineControls?: boolean): GlMapLike;
+/**
+ * Shows `credits` (plain text, one per dataset) in the map's attribution control, after the
+ * style's own credits. The control is replaced, not edited: MapLibre reads its custom
+ * attribution once. Does nothing for a map that isn't one of `createGlMap`'s or has no change.
+ */
+export declare function setDataCredits(gl: GlMapLike, credits: string[]): void;

package/dist/view/create-gl-map.js

@@ -0,0 +1,182 @@
+import { untrack } from "svelte";
+import { AttributionControl, AttributionControlMLGL, Map as MaptilerMap, MapStyle, config as maptilerConfig } from "@maptiler/sdk";
+import { themeSignature } from "../plugins/style.js";
+/**
+ * Calls `onChange` when the host's theme changes the tokens map colors are read from: on a
+ * `prefers-color-scheme` change, or a `data-theme`, `class`, or `style` change on `<html>`.
+ * Changes that leave the tokens on `container` as they were (e.g. a scroll lock's inline style)
+ * are ignored. Returns the stop function.
+ */
+export function watchTheme(container, onChange) {
+    let last = themeSignature(container);
+    const check = () => {
+        const next = themeSignature(container);
+        if (next === last)
+            return;
+        last = next;
+        onChange();
+    };
+    const media = matchMedia("(prefers-color-scheme: dark)");
+    media.addEventListener("change", check);
+    const observer = new MutationObserver(check);
+    observer.observe(document.documentElement, {
+        attributes: true,
+        attributeFilter: ["data-theme", "class", "style"]
+    });
+    return () => {
+        media.removeEventListener("change", check);
+        observer.disconnect();
+    };
+}
+/** Today's live map: MapTiler Streets v4 and its variants, without the busy POI label layers. */
+export function defaultBasemaps() {
+    const streets = MapStyle.STREETS_V4;
+    return {
+        // Style URLs, not variant objects: the basemap fallback matches a failed style by its URL.
+        styles: streets.getVariants().map((v) => ({ id: v.getId(), style: v.getExpandedStyleURL() })),
+        defaultId: streets.getDefaultVariant().getId(),
+        excludedLayers: ["Sport", "Tourism", "Culture", "Shopping", "Food", "Transport"]
+    };
+}
+/**
+ * A `transformRequest` that adds `key` to MapTiler API requests that have none. The SDK's own
+ * transform runs after it and only adds its global `config.apiKey` when `key` is missing, so
+ * each map's requests carry its own key, and two maps with different keys don't clash.
+ */
+export function maptilerKeyTransform(key) {
+    return (url) => {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            return { url };
+        }
+        if (parsed.host !== maptilerConfig.apiHost || parsed.searchParams.has("key"))
+            return { url };
+        parsed.searchParams.append("key", key);
+        return { url: parsed.href };
+    };
+}
+/** MapLibre's own `setStyle`, which MapTiler's `Map` overrides. */
+const clearStyle = Object.getPrototypeOf(MaptilerMap.prototype)
+    .setStyle;
+/**
+ * MapLibre's `remove()` clears the style with `setStyle(null)`. MapTiler's `setStyle` turns
+ * `null` into its default Streets style when no style has loaded yet, so removing a map that is
+ * still loading (hiding it quickly) would request that style for nothing; and once one has
+ * loaded it keeps it, so the style's requests and worker sources outlive the map. `null` goes to
+ * MapLibre's `setStyle` instead (nothing else here passes `null`), and MapTiler's pending
+ * space and halo setup, which would read the cleared style, is marked done.
+ */
+class GlMap extends MaptilerMap {
+    /** Notes the SDK's own attribution control, which it adds while constructing the map. */
+    addControl(...args) {
+        const [control] = args;
+        if (control instanceof AttributionControlMLGL)
+            this.attribution = { control, credits: "[]" };
+        return super.addControl(...args);
+    }
+    setStyle(...args) {
+        if (args[0] !== null)
+            return super.setStyle(...args);
+        const pending = this
+            .spaceboxLoadingState;
+        if (pending)
+            pending.styleLoadedCallbackFired = true;
+        return clearStyle.apply(this, args);
+    }
+    /**
+     * MapTiler's telemetry timer calls this 2 s after the map is created, even when it has been
+     * removed since (a map hidden quickly), and a removed map has no style to ask.
+     */
+    isGlobeProjection() {
+        if (!this.style)
+            return false;
+        return super.isGlobeProjection();
+    }
+}
+/** The style of `ctx`'s current basemap. Throws when there is none, rather than letting MapTiler fall back to its own default style. */
+function styleOf(ctx) {
+    const id = ctx.basemap.current;
+    const entry = ctx.config.basemaps?.styles.find((s) => s.id === id);
+    if (!entry)
+        throw new Error(`map-sdk: no basemap style for "${id}"`);
+    return entry.style;
+}
+function recordView(gl, ctx) {
+    const center = gl.getCenter();
+    const bounds = gl.getBounds();
+    ctx.updateView({
+        center: [center.lng, center.lat],
+        zoom: gl.getZoom(),
+        bearing: gl.getBearing(),
+        pitch: gl.getPitch()
+    }, {
+        west: bounds.getWest(),
+        south: bounds.getSouth(),
+        east: bounds.getEast(),
+        north: bounds.getNorth()
+    });
+}
+/**
+ * Creates the MapTiler map for `ctx` in `container`, at `ctx`'s camera with its current basemap.
+ * Reads `ctx` untracked, so calling this in an effect doesn't make it depend on the camera or
+ * basemap. With `engineControls`, the MapTiler SDK adds its default zoom/compass and locate-me
+ * controls at the top right; they go with the map.
+ * Records the camera and bounds once the map loads and after every move.
+ */
+export function createGlMap(container, ctx, engineControls = false) {
+    const { camera, style } = untrack(() => ({ camera: ctx.camera, style: styleOf(ctx) }));
+    const gl = new GlMap({
+        container,
+        style,
+        center: camera.center,
+        zoom: camera.zoom,
+        bearing: camera.bearing,
+        pitch: camera.pitch,
+        // The key goes on each request, not on the SDK's global config (the `apiKey` option
+        // sets that global).
+        transformRequest: maptilerKeyTransform(ctx.config.maptilerKey),
+        cooperativeGestures: ctx.config.cooperativeGestures ?? false,
+        keyboard: true,
+        // The engine's attribution control (and MapTiler's logo, when the key's plan requires it),
+        // at its automatic size: full on wide maps, collapsed on narrow ones. The SDK's default is
+        // always full, so ask for its automatic mode.
+        attributionControl: { compact: "auto" },
+        // `controls: "engine"` gets the SDK's own zoom/compass and locate-me controls, with its
+        // defaults (as monitor-map has today); otherwise MapView draws the controls.
+        navigationControl: engineControls ? "top-right" : false,
+        geolocateControl: engineControls ? "top-right" : false,
+        logSDKVersion: false,
+        // Only when set, so a map without them gets today's constructor options.
+        ...(ctx.config.projection ? { projection: ctx.config.projection } : {}),
+        ...(ctx.config.space ? { space: ctx.config.space } : {})
+    });
+    gl.on("load", () => recordView(gl, ctx));
+    gl.on("moveend", () => recordView(gl, ctx));
+    return gl;
+}
+const escapeHtml = (text) => text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+/**
+ * Shows `credits` (plain text, one per dataset) in the map's attribution control, after the
+ * style's own credits. The control is replaced, not edited: MapLibre reads its custom
+ * attribution once. Does nothing for a map that isn't one of `createGlMap`'s or has no change.
+ */
+export function setDataCredits(gl, credits) {
+    const map = gl;
+    const current = map.attribution;
+    if (!current || !(map instanceof GlMap))
+        return;
+    const key = JSON.stringify(credits);
+    if (key === current.credits)
+        return;
+    map.removeControl(current.control);
+    map.attribution = null;
+    const next = new AttributionControl({
+        compact: undefined,
+        customAttribution: credits.map(escapeHtml)
+    });
+    map.addControl(next);
+    map.attribution = { control: next, credits: key };
+}

package/dist/view/list-placement.d.ts

@@ -0,0 +1,21 @@
+/** A corner of the map. */
+export type ListPosition = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+/** `MapView`'s `featureList` options. */
+export interface FeatureListOptions {
+    /** The corner the List button sits in; its panel opens from there. Default `"top-left"`. */
+    position?: ListPosition;
+    /**
+     * `"always"` (default) shows the button. `"focus"` shows it 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 and the accessibility tree, like a skip link.
+     */
+    reveal?: "always" | "focus";
+}
+/** The `featureList` prop with its defaults filled in, or `null` when the list is off. */
+export declare function resolveFeatureList(value: boolean | FeatureListOptions | undefined): Required<FeatureListOptions> | null;
+/** A corner's edges, and the other corner on the same side (where the panel must stop). */
+export declare function cornerSides(position: ListPosition): {
+    vertical: "top" | "bottom";
+    horizontal: "left" | "right";
+    far: ListPosition;
+};

package/dist/view/list-placement.js

@@ -0,0 +1,13 @@
+/** The `featureList` prop with its defaults filled in, or `null` when the list is off. */
+export function resolveFeatureList(value) {
+    if (value === false)
+        return null;
+    const options = value === true || value === undefined ? {} : value;
+    return { position: options.position ?? "top-left", reveal: options.reveal ?? "always" };
+}
+/** A corner's edges, and the other corner on the same side (where the panel must stop). */
+export function cornerSides(position) {
+    const [vertical, horizontal] = position.split("-");
+    const far = `${vertical === "top" ? "bottom" : "top"}-${horizontal}`;
+    return { vertical, horizontal, far };
+}