@voila.dev/ui-map 1.1.9

package/package.json

@@ -0,0 +1,55 @@
+{
+	"name": "@voila.dev/ui-map",
+	"version": "1.1.9",
+	"type": "module",
+	"description": "Maps and a globe on free vector tiles. No API key, no bundle tax.",
+	"license": "MIT",
+	"homepage": "https://ui.voila.dev/components/map-view",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/voila-voila-dev/ui.git",
+		"directory": "packages/ui-map"
+	},
+	"keywords": [
+		"react",
+		"map",
+		"maplibre",
+		"tailwindcss"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"src",
+		"!src/**/*.test.ts",
+		"!src/**/*.test.tsx",
+		"!src/**/*.stories.ts",
+		"!src/**/*.stories.tsx"
+	],
+	"sideEffects": [
+		"**/*.css"
+	],
+	"exports": {
+		"./styles.css": "./src/styles.css",
+		"./components/*": "./src/components/*.tsx"
+	},
+	"imports": {
+		"#/*": "./src/*"
+	},
+	"scripts": {
+		"check": "biome check",
+		"check-types": "tsc --noEmit",
+		"format": "biome format",
+		"lint": "biome lint",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@voila.dev/ui": "0.0.0",
+		"maplibre-gl": "5.24.0"
+	},
+	"peerDependencies": {
+		"react": "^19.0.0",
+		"react-dom": "^19.0.0",
+		"tailwindcss": "^4.0.0"
+	}
+}

package/src/components/globe-view-implementation.tsx

@@ -0,0 +1,293 @@
+import maplibregl from "maplibre-gl";
+import "maplibre-gl/dist/maplibre-gl.css";
+import { cn } from "@voila.dev/ui/lib/utils";
+import { useEffect, useRef, useState } from "react";
+import type { GlobeViewProps } from "#/components/globe-view.tsx";
+import {
+	DEFAULT_DARK_STYLE_URL,
+	DEFAULT_STYLE_URL,
+} from "#/components/map-view-implementation.tsx";
+
+/** A whole hemisphere in frame — the sensible default for a globe. */
+const DEFAULT_CENTER: readonly [number, number] = [2.3522, 30];
+const DEFAULT_ZOOM = 1.4;
+
+/**
+ * Resolves a CSS colour expression (`var(--primary)`, `color-mix(…)`) to the
+ * `rgba()` string MapLibre's style parser accepts. The probe element gives the
+ * expression the right custom-property scope; the 1×1 canvas normalises
+ * whatever colour space the computed value serialises to.
+ */
+function resolveCssColor(
+	scope: HTMLElement,
+	expression: string,
+	fallback: string,
+): string {
+	const probe = document.createElement("span");
+	probe.style.display = "none";
+	probe.style.color = expression;
+	scope.appendChild(probe);
+	const computed = getComputedStyle(probe).color;
+	probe.remove();
+	const canvas = document.createElement("canvas");
+	canvas.width = 1;
+	canvas.height = 1;
+	const context = canvas.getContext("2d");
+	if (context === null) {
+		return fallback;
+	}
+	context.fillStyle = fallback;
+	context.fillStyle = computed;
+	context.fillRect(0, 0, 1, 1);
+	const [r, g, b, a] = context.getImageData(0, 0, 1, 1).data;
+	return `rgba(${r}, ${g}, ${b}, ${((a ?? 0) / 255).toFixed(3)})`;
+}
+
+/** The default WebGL-less fallback: a static globe outline in `--muted`. */
+function StaticGlobeOutline() {
+	return (
+		<svg
+			aria-hidden
+			viewBox="0 0 100 100"
+			className="mx-auto aspect-square h-full max-w-full text-muted"
+		>
+			<title>Globe unavailable</title>
+			<circle
+				cx="50"
+				cy="50"
+				r="48"
+				fill="none"
+				stroke="currentColor"
+				strokeWidth="1.5"
+			/>
+			<ellipse
+				cx="50"
+				cy="50"
+				rx="24"
+				ry="48"
+				fill="none"
+				stroke="currentColor"
+			/>
+			<ellipse
+				cx="50"
+				cy="50"
+				rx="44"
+				ry="48"
+				fill="none"
+				stroke="currentColor"
+				strokeWidth="0.5"
+			/>
+			<line x1="2" y1="50" x2="98" y2="50" stroke="currentColor" />
+			<path d="M 7 26 A 60 60 0 0 1 93 26" fill="none" stroke="currentColor" />
+			<path d="M 7 74 A 60 60 0 0 0 93 74" fill="none" stroke="currentColor" />
+		</svg>
+	);
+}
+
+/**
+ * The MapLibre-backed body of `GlobeView`, loaded through `React.lazy` from
+ * `globe-view.tsx` so the ~270 kB runtime never rides along with a page that
+ * merely links to it. Import `GlobeView` instead of using this directly.
+ */
+export function GlobeViewImplementation({
+	styleUrl,
+	center = DEFAULT_CENTER,
+	zoom = DEFAULT_ZOOM,
+	spin = 0,
+	markers = [],
+	options,
+	className,
+	onReady,
+	unavailableFallback,
+	...props
+}: GlobeViewProps) {
+	const containerRef = useRef<HTMLDivElement | null>(null);
+	const onReadyRef = useRef(onReady);
+	onReadyRef.current = onReady;
+	// Initial view, style, rotation and markers are captured on mount only;
+	// later prop changes don't re-center, restyle or re-pin.
+	const initialRef = useRef({ center, zoom, styleUrl, spin, markers, options });
+	const [unavailable, setUnavailable] = useState(false);
+	const [loaded, setLoaded] = useState(false);
+
+	useEffect(() => {
+		const container = containerRef.current;
+		if (container === null) {
+			return;
+		}
+		const initial = initialRef.current;
+		const themedStyleUrl = () =>
+			container.closest(".dark") === null
+				? DEFAULT_STYLE_URL
+				: DEFAULT_DARK_STYLE_URL;
+		const defaultStyleUrl = themedStyleUrl();
+		const prefersReducedMotion = window.matchMedia(
+			"(prefers-reduced-motion: reduce)",
+		).matches;
+		let instance: maplibregl.Map;
+		try {
+			instance = new maplibregl.Map({
+				...(prefersReducedMotion ? { fadeDuration: 0 } : undefined),
+				...initial.options,
+				container,
+				style: initial.styleUrl ?? defaultStyleUrl,
+				center: [initial.center[0], initial.center[1]],
+				zoom: initial.zoom,
+			});
+		} catch {
+			// WebGL is required and isn't available in this environment.
+			setUnavailable(true);
+			return;
+		}
+
+		// Markers are DOM overlays, so they survive `setStyle` and are added once.
+		for (const marker of initial.markers) {
+			const element = document.createElement("span");
+			element.className = "relative flex size-3";
+			if (marker.pulse) {
+				const ring = document.createElement("span");
+				ring.className =
+					"absolute inline-flex h-full w-full animate-ping rounded-full bg-primary opacity-60 motion-reduce:animate-none";
+				element.appendChild(ring);
+			}
+			const dot = document.createElement("span");
+			dot.className =
+				"relative inline-flex size-3 rounded-full bg-primary shadow-[0_0_10px_2px] shadow-primary/50";
+			element.appendChild(dot);
+			// Without subpixel positioning MapLibre rounds each marker to whole
+			// pixels, which reads as trembling while the globe auto-rotates.
+			new maplibregl.Marker({ element, subpixelPositioning: true })
+				.setLngLat([marker.lngLat[0], marker.lngLat[1]])
+				.addTo(instance);
+		}
+
+		// Projection and sky are style-level state: a theme switch's `setStyle`
+		// drops them, so `handleReady` re-applies both on every style load.
+		const handleReady = () => {
+			instance.setProjection({ type: "globe" });
+			const dark = container.closest(".dark") !== null;
+			// Indigo `--primary` glow in dark mode, a soft slate halo in light —
+			// resolved from the live token values so a rebrand retints the globe.
+			const halo = resolveCssColor(
+				container,
+				dark
+					? "color-mix(in oklab, var(--primary) 65%, transparent)"
+					: "color-mix(in oklab, var(--muted-foreground) 45%, transparent)",
+				dark ? "rgba(99, 102, 241, 0.65)" : "rgba(100, 116, 139, 0.45)",
+			);
+			const fog = resolveCssColor(
+				container,
+				dark
+					? "color-mix(in oklab, var(--primary) 25%, transparent)"
+					: "color-mix(in oklab, var(--muted-foreground) 20%, transparent)",
+				dark ? "rgba(99, 102, 241, 0.25)" : "rgba(100, 116, 139, 0.2)",
+			);
+			instance.setSky({
+				// Transparent space, so the section's `bg-background` shows through.
+				"sky-color": "rgba(0, 0, 0, 0)",
+				"horizon-color": halo,
+				"fog-color": fog,
+				"sky-horizon-blend": 0.8,
+				"horizon-fog-blend": 0.5,
+				"fog-ground-blend": 0.9,
+				"atmosphere-blend": 0.8,
+			});
+			setLoaded(true);
+			onReadyRef.current?.(instance);
+		};
+		if (instance.isStyleLoaded()) {
+			handleReady();
+		} else {
+			instance.once("load", handleReady);
+		}
+
+		// Same live theme following as `MapView`.
+		let themeObserver: MutationObserver | undefined;
+		if (initial.styleUrl === undefined) {
+			let appliedStyleUrl = defaultStyleUrl;
+			themeObserver = new MutationObserver(() => {
+				const nextStyleUrl = themedStyleUrl();
+				if (nextStyleUrl === appliedStyleUrl) {
+					return;
+				}
+				appliedStyleUrl = nextStyleUrl;
+				instance.setStyle(nextStyleUrl);
+				instance.once("style.load", handleReady);
+			});
+			themeObserver.observe(document.documentElement, {
+				attributes: true,
+				attributeFilter: ["class"],
+				subtree: true,
+			});
+		}
+
+		// Auto-rotation: a rAF loop nudging the longitude, paused while the
+		// pointer is down so a drag never fights the spin, skipped entirely under
+		// reduced motion. `jumpTo` (not `easeTo`) keeps each step animation-free.
+		let frame = 0;
+		let interacting = false;
+		const handlePointerDown = () => {
+			interacting = true;
+		};
+		const handlePointerUp = () => {
+			interacting = false;
+		};
+		if (initial.spin !== 0 && !prefersReducedMotion) {
+			container.addEventListener("pointerdown", handlePointerDown);
+			window.addEventListener("pointerup", handlePointerUp);
+			let last: number | undefined;
+			const step = (now: number) => {
+				if (last !== undefined && !interacting) {
+					const current = instance.getCenter();
+					instance.jumpTo({
+						center: [
+							current.lng + (initial.spin * (now - last)) / 1000,
+							current.lat,
+						],
+					});
+				}
+				last = now;
+				frame = requestAnimationFrame(step);
+			};
+			frame = requestAnimationFrame(step);
+		}
+
+		const resizeObserver = new ResizeObserver(() => instance.resize());
+		resizeObserver.observe(container);
+		return () => {
+			cancelAnimationFrame(frame);
+			container.removeEventListener("pointerdown", handlePointerDown);
+			window.removeEventListener("pointerup", handlePointerUp);
+			themeObserver?.disconnect();
+			resizeObserver.disconnect();
+			instance.remove();
+		};
+	}, []);
+
+	return (
+		<div
+			data-slot="globe-view"
+			className={cn(
+				"h-[70vh] w-full overflow-hidden",
+				"dark:[&_.maplibregl-ctrl]:hue-rotate-180 dark:[&_.maplibregl-ctrl]:invert",
+				className,
+			)}
+			{...props}
+		>
+			{unavailable ? (
+				<div data-slot="globe-view-fallback" className="h-full w-full p-4">
+					{unavailableFallback ?? <StaticGlobeOutline />}
+				</div>
+			) : (
+				<div
+					ref={containerRef}
+					data-slot="globe-view-canvas"
+					data-loaded={loaded}
+					// Keep this className identical across renders — MapLibre adds its
+					// own class to the node imperatively (see MapView for the story).
+					className="h-full w-full"
+				/>
+			)}
+		</div>
+	);
+}

package/src/components/globe-view.tsx

@@ -0,0 +1,93 @@
+import { Skeleton } from "@voila.dev/ui/components/skeleton";
+import { cn } from "@voila.dev/ui/lib/utils";
+import type maplibregl from "maplibre-gl";
+import { type ComponentProps, lazy, type ReactNode, Suspense } from "react";
+
+/** A point of interest on the globe, rendered as a token-coloured dot. */
+export type GlobeMarker = {
+	/** `[longitude, latitude]` in WGS84 degrees. */
+	readonly lngLat: readonly [number, number];
+	/** Adds a slow expanding ring behind the dot. */
+	readonly pulse?: boolean;
+};
+
+/**
+ * `MapView`'s sibling, same contract: free key-less OpenFreeMap basemaps
+ * ("liberty" light / "dark" dark) following the `.dark` subtree live, both
+ * overridable via `styleUrl`. The differences are the projection — MapLibre's
+ * native globe — plus an optional auto-rotation and declarative markers.
+ */
+export type GlobeViewProps = Omit<ComponentProps<"div">, "children"> & {
+	/**
+	 * Vector style URL. Read once, on mount; defaults to the OpenFreeMap
+	 * "liberty" basemap — or its "dark" variant while inside a `.dark` subtree,
+	 * following theme switches. An explicit URL opts out of theme following.
+	 */
+	readonly styleUrl?: string;
+	/** Initial center `[longitude, latitude]`. Read once, on mount. */
+	readonly center?: readonly [number, number];
+	/** Initial zoom. Read once, on mount. */
+	readonly zoom?: number;
+	/**
+	 * Auto-rotation speed in degrees of longitude per second; `0` (the default)
+	 * disables it. Rotation pauses while the pointer is down and is skipped
+	 * entirely under `prefers-reduced-motion`. Read once, on mount.
+	 */
+	readonly spin?: number;
+	/** Markers to place, coloured from the token palette. Read once, on mount. */
+	readonly markers?: ReadonlyArray<GlobeMarker>;
+	/**
+	 * Extra MapLibre constructor options (`cooperativeGestures`,
+	 * `attributionControl`…). Read once, on mount.
+	 */
+	readonly options?: Omit<
+		maplibregl.MapOptions,
+		"container" | "style" | "center" | "zoom"
+	>;
+	/**
+	 * Called once the basemap, globe projection and atmosphere are ready, with
+	 * the live MapLibre instance. A theme switch swaps the basemap style (which
+	 * drops custom sources/layers) and calls this again, so the setup must
+	 * tolerate re-runs. The instance is removed on unmount.
+	 */
+	readonly onReady?: (map: maplibregl.Map) => void;
+	/**
+	 * Rendered in place of the globe when WebGL is unavailable
+	 * (sandboxed/headless browsers, disabled GPU). Defaults to a static globe
+	 * outline drawn in `--muted`.
+	 */
+	readonly unavailableFallback?: ReactNode;
+};
+
+// Same discipline as `MapView`: `maplibre-gl` weighs ~270 kB gzipped, so the
+// rendering body lives in its own module and only downloads once a globe
+// actually mounts. Type-only imports of `maplibre-gl` stay free.
+const GlobeViewImplementation = lazy(() =>
+	import("#/components/globe-view-implementation.tsx").then((module) => ({
+		default: module.GlobeViewImplementation,
+	})),
+);
+
+/**
+ * A 3D globe on MapLibre's native globe projection and the same free, key-less
+ * vector tiles as `MapView`. The atmosphere halo is tinted from the token
+ * palette (`--primary` in dark mode, a soft slate in light), the space behind
+ * the globe stays transparent so the surrounding section's background shows
+ * through, and the MapLibre runtime is code-split behind a pulsing skeleton.
+ */
+export function GlobeView({ className, ...props }: GlobeViewProps) {
+	return (
+		<Suspense
+			fallback={
+				<div
+					data-slot="globe-view"
+					className={cn("h-[70vh] w-full overflow-hidden", className)}
+				>
+					<Skeleton className="mx-auto aspect-square h-full max-w-full rounded-full" />
+				</div>
+			}
+		>
+			<GlobeViewImplementation className={className} {...props} />
+		</Suspense>
+	);
+}

package/src/components/map-view-implementation.tsx

@@ -0,0 +1,176 @@
+import maplibregl from "maplibre-gl";
+import "maplibre-gl/dist/maplibre-gl.css";
+import { cn } from "@voila.dev/ui/lib/utils";
+import { useEffect, useRef, useState } from "react";
+import type { MapViewProps } from "#/components/map-view.tsx";
+
+export const DEFAULT_STYLE_URL = "https://tiles.openfreemap.org/styles/liberty";
+export const DEFAULT_DARK_STYLE_URL =
+	"https://tiles.openfreemap.org/styles/dark";
+
+/** Metropolitan France — a sensible default frame for the whole dataset. */
+const DEFAULT_CENTER: readonly [number, number] = [2.3522, 48.8566];
+const DEFAULT_ZOOM = 5;
+
+/**
+ * The MapLibre-backed body of `MapView`. This module owns the only runtime
+ * import of `maplibre-gl` (and its stylesheet) in the package, so it is loaded
+ * through `React.lazy` from `map-view.tsx` — keeping the heavy dependency out
+ * of every bundle that merely links to the map component. Import `MapView`
+ * from `#/components/map-view.tsx` instead of using this directly.
+ */
+export function MapViewImplementation({
+	styleUrl,
+	center = DEFAULT_CENTER,
+	zoom = DEFAULT_ZOOM,
+	options,
+	className,
+	onReady,
+	onMoveEnd,
+	unavailableFallback,
+	...props
+}: MapViewProps) {
+	const containerRef = useRef<HTMLDivElement | null>(null);
+	const onReadyRef = useRef(onReady);
+	onReadyRef.current = onReady;
+	const onMoveEndRef = useRef(onMoveEnd);
+	onMoveEndRef.current = onMoveEnd;
+	// Initial view, style and options are captured on mount only; later prop
+	// changes don't re-center or restyle.
+	const initialRef = useRef({ center, zoom, styleUrl, options });
+	// Set when the basemap can't initialize (no WebGL: sandboxed/headless
+	// browsers, disabled GPU); we render a fallback instead of crashing.
+	const [unavailable, setUnavailable] = useState(false);
+	// Tiles stream in for a few seconds after mount; pulse the box until the
+	// style is ready so the wait doesn't read as a broken blank map.
+	const [loaded, setLoaded] = useState(false);
+
+	useEffect(() => {
+		const container = containerRef.current;
+		if (container === null) {
+			return;
+		}
+		const initial = initialRef.current;
+		// Mirrors the CSS `dark` variant (`.dark *`): default to the dark basemap
+		// under a themed subtree when no explicit style was given.
+		const themedStyleUrl = () =>
+			container.closest(".dark") === null
+				? DEFAULT_STYLE_URL
+				: DEFAULT_DARK_STYLE_URL;
+		const defaultStyleUrl = themedStyleUrl();
+		// MapLibre already skips ease/fly camera animations under reduced motion,
+		// but tile crossfades are opt-out only; mirror the preference here.
+		const prefersReducedMotion = window.matchMedia(
+			"(prefers-reduced-motion: reduce)",
+		).matches;
+		let instance: maplibregl.Map;
+		try {
+			instance = new maplibregl.Map({
+				...(prefersReducedMotion ? { fadeDuration: 0 } : undefined),
+				...initial.options,
+				container,
+				style: initial.styleUrl ?? defaultStyleUrl,
+				center: [initial.center[0], initial.center[1]],
+				zoom: initial.zoom,
+			});
+		} catch {
+			// WebGL is required and isn't available in this environment. Surface a
+			// fallback rather than letting the throw bubble out of the effect.
+			setUnavailable(true);
+			return;
+		}
+		instance.addControl(new maplibregl.NavigationControl(), "top-right");
+
+		const emitMove = () => {
+			const bounds = instance.getBounds();
+			onMoveEndRef.current?.(
+				{
+					west: bounds.getWest(),
+					south: bounds.getSouth(),
+					east: bounds.getEast(),
+					north: bounds.getNorth(),
+				},
+				instance.getZoom(),
+			);
+		};
+		const handleReady = () => {
+			setLoaded(true);
+			onReadyRef.current?.(instance);
+			emitMove();
+		};
+		if (instance.isStyleLoaded()) {
+			handleReady();
+		} else {
+			instance.once("load", handleReady);
+		}
+		instance.on("moveend", emitMove);
+
+		// Follow theme switches: the `.dark` class can land after mount (theme
+		// providers and Storybook's themes addon apply it in an effect) or toggle
+		// live. Swap the basemap when it does and replay `handleReady` once the new
+		// style is in, so consumers re-add the sources/layers the swap dropped.
+		let themeObserver: MutationObserver | undefined;
+		if (initial.styleUrl === undefined) {
+			let appliedStyleUrl = defaultStyleUrl;
+			themeObserver = new MutationObserver(() => {
+				const nextStyleUrl = themedStyleUrl();
+				if (nextStyleUrl === appliedStyleUrl) {
+					return;
+				}
+				appliedStyleUrl = nextStyleUrl;
+				instance.setStyle(nextStyleUrl);
+				instance.once("style.load", handleReady);
+			});
+			themeObserver.observe(document.documentElement, {
+				attributes: true,
+				attributeFilter: ["class"],
+				subtree: true,
+			});
+		}
+
+		// The container may finish sizing after construction (flex/grid, sidebar
+		// toggles); keep the canvas matched so tiles fill the box.
+		const resizeObserver = new ResizeObserver(() => instance.resize());
+		resizeObserver.observe(container);
+		return () => {
+			themeObserver?.disconnect();
+			resizeObserver.disconnect();
+			instance.remove();
+		};
+	}, []);
+
+	return (
+		<div
+			data-slot="map-view"
+			className={cn(
+				"h-[70vh] w-full overflow-hidden rounded-lg border",
+				// MapLibre ships white control chrome (zoom buttons, attribution);
+				// invert it — hue-rotated back so link colors survive — when the map
+				// sits in a dark subtree.
+				"dark:[&_.maplibregl-ctrl]:hue-rotate-180 dark:[&_.maplibregl-ctrl]:invert",
+				className,
+			)}
+			{...props}
+		>
+			{unavailable ? (
+				<div
+					data-slot="map-view-fallback"
+					className="flex h-full w-full items-center justify-center p-4 text-center text-muted-foreground text-sm"
+				>
+					{unavailableFallback}
+				</div>
+			) : (
+				<div
+					ref={containerRef}
+					data-slot="map-view-canvas"
+					data-loaded={loaded}
+					// The className must stay identical across renders: MapLibre adds
+					// its own `maplibregl-map` class (relative + overflow clipping) to
+					// this node imperatively, and any className change makes React
+					// rewrite the attribute and drop it — the map then escapes the box.
+					className="h-full w-full data-[loaded=false]:animate-pulse data-[loaded=false]:bg-muted motion-reduce:animate-none"
+				/>
+			)}
+		</div>
+	);
+}

package/src/components/map-view.tsx

@@ -0,0 +1,100 @@
+import { Skeleton } from "@voila.dev/ui/components/skeleton";
+import { cn } from "@voila.dev/ui/lib/utils";
+import type maplibregl from "maplibre-gl";
+import { type ComponentProps, lazy, type ReactNode, Suspense } from "react";
+
+/** A geographic bounding box in WGS84 (EPSG:4326) degrees. */
+export type MapBounds = {
+	readonly west: number;
+	readonly south: number;
+	readonly east: number;
+	readonly north: number;
+};
+
+/**
+ * Free, key-less vector basemaps. "liberty" is the light default; the "dark"
+ * variant is selected automatically while the component sits inside a `.dark`
+ * subtree, and the basemap restyles live when that class toggles. Both are
+ * overridable via the `styleUrl` prop (e.g. a MapTiler/Mapbox style for richer
+ * cartography). The URL constants live in `map-view-implementation.tsx` with
+ * the rest of the runtime map code.
+ */
+export type MapViewProps = Omit<ComponentProps<"div">, "children"> & {
+	/**
+	 * Vector style URL. Read once, on mount; defaults to the OpenFreeMap
+	 * "liberty" basemap — or its "dark" variant while inside a `.dark` subtree,
+	 * following theme switches. An explicit URL opts out of theme following.
+	 */
+	readonly styleUrl?: string;
+	/** Initial center `[longitude, latitude]`. Read once, on mount. */
+	readonly center?: readonly [number, number];
+	/** Initial zoom. Read once, on mount. */
+	readonly zoom?: number;
+	/**
+	 * Extra MapLibre constructor options (`maxBounds`, `cooperativeGestures`,
+	 * `attributionControl`…). Read once, on mount.
+	 */
+	readonly options?: Omit<
+		maplibregl.MapOptions,
+		"container" | "style" | "center" | "zoom"
+	>;
+	/**
+	 * Called once the basemap and its style are ready, with the live MapLibre
+	 * instance — add sources, layers and markers here. A theme switch swaps the
+	 * basemap style (which drops custom sources/layers) and calls this again, so
+	 * the setup must tolerate re-runs. The instance is removed on unmount, so
+	 * don't retain it past the component's lifetime.
+	 */
+	readonly onReady?: (map: maplibregl.Map) => void;
+	/**
+	 * Called after the view settles — once on load and after every pan/zoom — with
+	 * the current bounds and zoom. Drives viewport-scoped data fetching.
+	 */
+	readonly onMoveEnd?: (bounds: MapBounds, zoom: number) => void;
+	/**
+	 * Rendered in place of the map when the basemap can't initialize because the
+	 * environment has no WebGL (sandboxed/headless browsers, disabled GPU). This
+	 * package is translation-agnostic, so consumers pass their own localized node.
+	 */
+	readonly unavailableFallback?: ReactNode;
+};
+
+// `maplibre-gl` weighs ~270 kB gzipped, so the rendering body lives in its own
+// module and only downloads once a map actually mounts. Type-only imports of
+// `maplibre-gl` (like the one above) stay free — they're erased at compile time.
+const MapViewImplementation = lazy(() =>
+	import("#/components/map-view-implementation.tsx").then((module) => ({
+		default: module.MapViewImplementation,
+	})),
+);
+
+/**
+ * Thin, reusable MapLibre GL basemap: it owns the canvas, lifecycle, navigation
+ * control and resize handling, and surfaces the instance (`onReady`) and view
+ * changes (`onMoveEnd`). It is deliberately presentational and data-agnostic, so
+ * any feature — the admin map's clustered entities, a single provider-profile
+ * pin, an event venue — composes its own sources/layers on top.
+ *
+ * The MapLibre runtime is code-split: while its chunk downloads, a skeleton
+ * with the same frame pulses in place, matching the tile-streaming placeholder
+ * the loaded map shows next.
+ */
+export function MapView({ className, ...props }: MapViewProps) {
+	return (
+		<Suspense
+			fallback={
+				<div
+					data-slot="map-view"
+					className={cn(
+						"h-[70vh] w-full overflow-hidden rounded-lg border",
+						className,
+					)}
+				>
+					<Skeleton className="h-full w-full rounded-none" />
+				</div>
+			}
+		>
+			<MapViewImplementation className={className} {...props} />
+		</Suspense>
+	);
+}

package/src/components/radius-map.tsx

@@ -0,0 +1,131 @@
+import { cn } from "@voila.dev/ui/lib/utils";
+import type maplibregl from "maplibre-gl";
+import { type ReactNode, useCallback, useEffect, useState } from "react";
+import { MapView } from "#/components/map-view.tsx";
+import {
+	circleBounds,
+	circlePolygon,
+	type GeoPoint,
+} from "#/lib/geo-circle.ts";
+
+const SOURCE_ID = "radius-map";
+const FILL_LAYER = `${SOURCE_ID}-fill`;
+const LINE_LAYER = `${SOURCE_ID}-line`;
+const CENTER_LAYER = `${SOURCE_ID}-center`;
+
+/**
+ * The searched area, drawn: a geodesic circle of `radiusKm` around the chosen
+ * place, with a dot on the place itself. The viewport follows the circle so the
+ * whole area stays in frame while the radius slider moves.
+ */
+export function RadiusMap({
+	center,
+	radiusKm,
+	color = "#1e3a8a",
+	className,
+	unavailableFallback,
+}: {
+	readonly center: GeoPoint;
+	readonly radiusKm: number;
+	/** Circle fill/stroke colour. Defaults to the kit's deep blue. */
+	readonly color?: string;
+	readonly className?: string;
+	/** Shown when the environment has no WebGL; this package ships no copy. */
+	readonly unavailableFallback?: ReactNode;
+}) {
+	const [map, setMap] = useState<maplibregl.Map | null>(null);
+
+	// `onReady` replays after a theme-driven basemap swap, which drops custom
+	// sources/layers: re-add them each time they are missing.
+	const handleReady = useCallback(
+		(instance: maplibregl.Map) => {
+			if (instance.getSource(SOURCE_ID) === undefined) {
+				instance.addSource(SOURCE_ID, {
+					type: "geojson",
+					data: { type: "FeatureCollection", features: [] },
+				});
+				instance.addLayer({
+					id: FILL_LAYER,
+					type: "fill",
+					source: SOURCE_ID,
+					filter: ["==", ["geometry-type"], "Polygon"],
+					paint: { "fill-color": color, "fill-opacity": 0.12 },
+				});
+				instance.addLayer({
+					id: LINE_LAYER,
+					type: "line",
+					source: SOURCE_ID,
+					filter: ["==", ["geometry-type"], "Polygon"],
+					paint: { "line-color": color, "line-width": 1.5 },
+				});
+				instance.addLayer({
+					id: CENTER_LAYER,
+					type: "circle",
+					source: SOURCE_ID,
+					filter: ["==", ["geometry-type"], "Point"],
+					paint: {
+						"circle-color": color,
+						"circle-radius": 5,
+						"circle-stroke-color": "#ffffff",
+						"circle-stroke-width": 2,
+					},
+				});
+			}
+			setMap(instance);
+		},
+		[color],
+	);
+
+	useEffect(() => {
+		if (map === null) {
+			return;
+		}
+		const apply = () => {
+			const source = map.getSource(SOURCE_ID) as
+				| maplibregl.GeoJSONSource
+				| undefined;
+			if (source === undefined) {
+				return;
+			}
+			source.setData({
+				type: "FeatureCollection",
+				features: [
+					circlePolygon(center, radiusKm),
+					{
+						type: "Feature",
+						geometry: {
+							type: "Point",
+							coordinates: [center.longitude, center.latitude],
+						},
+						properties: {},
+					},
+				],
+			});
+			const bounds = circleBounds(center, radiusKm);
+			map.fitBounds(
+				[
+					[bounds.west, bounds.south],
+					[bounds.east, bounds.north],
+				],
+				{ padding: 24, animate: false },
+			);
+		};
+		if (map.isStyleLoaded()) {
+			apply();
+		} else {
+			// "idle" (unlike "load") also fires after a theme-driven style swap.
+			map.once("idle", apply);
+		}
+	}, [map, center, radiusKm]);
+
+	return (
+		<MapView
+			className={cn("h-52 overflow-hidden rounded-lg border", className)}
+			center={[center.longitude, center.latitude]}
+			zoom={9}
+			options={{ attributionControl: false }}
+			onReady={handleReady}
+			unavailableFallback={unavailableFallback}
+		/>
+	);
+}

package/src/css-modules.d.ts

@@ -0,0 +1,4 @@
+// Side-effect CSS imports (e.g. maplibre-gl's stylesheet) carry no type
+// declarations; the app bundlers get this from `vite/client`, but this package
+// typechecks standalone, so declare the module shape here.
+declare module "*.css" {}

package/src/lib/geo-circle.ts

@@ -0,0 +1,83 @@
+/** A WGS84 point. Structural, so any `{ latitude, longitude }` fits. */
+export type GeoPoint = {
+	readonly latitude: number;
+	readonly longitude: number;
+};
+
+const EARTH_RADIUS_KM = 6371;
+const toRadians = (degrees: number): number => (degrees * Math.PI) / 180;
+const toDegrees = (radians: number): number => (radians * 180) / Math.PI;
+
+/** Structural GeoJSON Polygon feature, assignable to a MapLibre geojson source. */
+export type CirclePolygonFeature = {
+	readonly type: "Feature";
+	readonly geometry: {
+		readonly type: "Polygon";
+		readonly coordinates: [number, number][][];
+	};
+	readonly properties: Record<string, never>;
+};
+
+/**
+ * A geodesic circle around `center` as a closed GeoJSON Polygon ring
+ * (`segments` + 1 points, first == last), for MapLibre fill/line layers such
+ * as the intervention-radius overlay. Each ring point is projected with the
+ * direct great-circle formula, so the drawn radius stays true at any latitude
+ * (a naive degree offset would flatten the circle away from the equator).
+ */
+export const circlePolygon = (
+	center: GeoPoint,
+	radiusKm: number,
+	segments = 64,
+): CirclePolygonFeature => {
+	const angularDistance = radiusKm / EARTH_RADIUS_KM;
+	const centerLatitude = toRadians(center.latitude);
+	const centerLongitude = toRadians(center.longitude);
+	const ring: [number, number][] = [];
+	for (let step = 0; step <= segments; step++) {
+		const bearing = (step / segments) * 2 * Math.PI;
+		const pointLatitude = Math.asin(
+			Math.sin(centerLatitude) * Math.cos(angularDistance) +
+				Math.cos(centerLatitude) *
+					Math.sin(angularDistance) *
+					Math.cos(bearing),
+		);
+		const pointLongitude =
+			centerLongitude +
+			Math.atan2(
+				Math.sin(bearing) *
+					Math.sin(angularDistance) *
+					Math.cos(centerLatitude),
+				Math.cos(angularDistance) -
+					Math.sin(centerLatitude) * Math.sin(pointLatitude),
+			);
+		ring.push([toDegrees(pointLongitude), toDegrees(pointLatitude)]);
+	}
+	return {
+		type: "Feature",
+		geometry: { type: "Polygon", coordinates: [ring] },
+		properties: {},
+	};
+};
+
+/**
+ * The circle's bounding box (WGS84 degrees), for `fitBounds`. Derived from the
+ * ring points so it shares the geodesic math above.
+ */
+export const circleBounds = (
+	center: GeoPoint,
+	radiusKm: number,
+): { west: number; south: number; east: number; north: number } => {
+	const ring = circlePolygon(center, radiusKm).geometry.coordinates[0];
+	let west = Number.POSITIVE_INFINITY;
+	let south = Number.POSITIVE_INFINITY;
+	let east = Number.NEGATIVE_INFINITY;
+	let north = Number.NEGATIVE_INFINITY;
+	for (const [longitude, latitude] of ring) {
+		west = Math.min(west, longitude);
+		south = Math.min(south, latitude);
+		east = Math.max(east, longitude);
+		north = Math.max(north, latitude);
+	}
+	return { west, south, east, north };
+};

package/src/styles.css

@@ -0,0 +1,10 @@
+/*
+ * Tailwind must scan this package or none of its classes are generated — the
+ * components ship as .tsx source, not as compiled CSS.
+ *
+ * `@source` resolves relative to the file that declares it, so this works
+ * wherever the package ends up: node_modules in an app, a symlink in a
+ * workspace. Consumers import this file and add nothing of their own.
+ */
+@source "./";
+@source not "./**/*.test.*";