@mailwoman/react 9.3.0 → 10.0.0

package/lib/map/{DemoMap.tsx → MapCanvas.tsx}

@@ -3,7 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `<DemoMap>` — the declarative map shell for the geocoder demo, over `react-map-gl/maplibre` (v8).
+ *   `<MapCanvas>` — the declarative map shell for the geocoder demo, over `react-map-gl/maplibre` (v8).
  *   Phase 1 is the shell only: a `<Map>` that takes a host-composed `mapStyle`, an initial (or
  *   controlled) view state, and a `children` slot for the overlays/markers that land in later phases.
  *   No overlay/marker/camera logic lives here yet.
@@ -15,10 +15,10 @@
  *   the root barrel.
  *
  *   CSS: the package imports no CSS from its modules (the node-safe invariant), so a host that renders
- *   `<DemoMap>` must import `maplibre-gl/dist/maplibre-gl.css` itself (plus `@mailwoman/react/styles.css`
- *   for the `.mw-demo-map` container). `<DemoMap>` is intrinsically a client component — a host that
+ *   `<MapCanvas>` must import `maplibre-gl/dist/maplibre-gl.css` itself (plus `@mailwoman/react/styles.css`
+ *   for the `.mw-demo-map` container). `<MapCanvas>` is intrinsically a client component — a host that
  *   server-renders should wrap it in a client boundary (the package's `ClientOnly`), exactly as the
- *   composed `GeocoderDemo` will in a later phase.
+ *   composed `Geocoder` will in a later phase.
  */
 
 import type { CSSProperties, ReactNode, Ref } from "react"
@@ -26,23 +26,23 @@ import { Map } from "react-map-gl/maplibre"
 import type { MapProps, MapRef, ViewStateChangeEvent } from "react-map-gl/maplibre"
 
 /**
- * The style a `<DemoMap>` renders — a style URL or an inline/composed `StyleSpecification`.
+ * The style a `<MapCanvas>` renders — a style URL or an inline/composed `StyleSpecification`.
  */
-export type DemoMapStyle = NonNullable<MapProps["mapStyle"]>
+export type MapCanvasStyle = NonNullable<MapProps["mapStyle"]>
 
 /**
- * Override for the `<Map>` props `<DemoMap>` does not surface explicitly (e.g. `minZoom`, `attributionControl`,
- * `maplibreLogo`). The controlled fields DemoMap owns are omitted so they can't be set twice.
+ * Override for the `<Map>` props `<MapCanvas>` does not surface explicitly (e.g. `minZoom`, `attributionControl`,
+ * `maplibreLogo`). The controlled fields MapCanvas owns are omitted so they can't be set twice.
  */
-export type DemoMapExtraProps = Partial<
+export type MapCanvasExtraProps = Partial<
 	Omit<MapProps, "mapStyle" | "initialViewState" | "viewState" | "onMove" | "children" | "style" | "ref">
 >
 
-export interface DemoMapProps {
+export interface MapCanvasProps {
 	/**
 	 * The map style — host-composed `StyleSpecification` or a style URL.
 	 */
-	mapStyle: DemoMapStyle
+	mapStyle: MapCanvasStyle
 	/**
 	 * Uncontrolled initial camera. Use this OR `viewState`, not both.
 	 */
@@ -76,9 +76,9 @@ export interface DemoMapProps {
 	 */
 	style?: CSSProperties
 	/**
-	 * Remaining `<Map>` props DemoMap does not surface explicitly.
+	 * Remaining `<Map>` props MapCanvas does not surface explicitly.
 	 */
-	mapProps?: DemoMapExtraProps
+	mapProps?: MapCanvasExtraProps
 }
 
 const FILL: CSSProperties = { width: "100%", height: "100%" }
@@ -87,7 +87,7 @@ const FILL: CSSProperties = { width: "100%", height: "100%" }
  * The controlled-viewport map shell. Renders a sized wrapper around a `react-map-gl/maplibre` `<Map>`; everything
  * host-specific (the composed `mapStyle`, the initial center) is injected, and overlays ride in as `children`.
  */
-export function DemoMap({
+export function MapCanvas({
 	mapStyle,
 	initialViewState,
 	viewState,
@@ -98,7 +98,7 @@ export function DemoMap({
 	className,
 	style,
 	mapProps,
-}: DemoMapProps): ReactNode {
+}: MapCanvasProps): ReactNode {
 	const wrapperClassName = className ? `mw-demo-map ${className}` : "mw-demo-map"
 
 	return (

package/lib/map/MapChipRow.tsx

@@ -0,0 +1,77 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<MapChipRow>` — the row of example queries under a search bar.
+ *
+ *   It SCROLLS horizontally and never wraps. Earth's twelve examples wrapped down five ragged rows (3/3/2/1/1/1) and
+ *   took a third of the panel; one scrolling line is the shape the reference map apps use, and it costs a fixed
+ *   height whatever the number of examples.
+ *
+ *   NODE-SAFE: pure React, no maplibre.
+ */
+
+import type { ReactNode } from "react"
+
+import { cx } from "#common/cx"
+
+export interface MapChip {
+	/**
+	 * What the chip reads.
+	 */
+	label: string
+	/**
+	 * The query the chip stands for, handed back on press. Defaults to the label.
+	 */
+	value?: string
+	/**
+	 * Rendered before the label — a category mark.
+	 */
+	icon?: ReactNode
+}
+
+export interface MapChipRowProps {
+	chips: MapChip[]
+	/**
+	 * Fired with the chip's `value` (or its label) when one is pressed.
+	 */
+	onPick: (value: string) => void
+	/**
+	 * The chip matching this value reads as pressed.
+	 */
+	activeValue?: string
+	disabled?: boolean
+	className?: string
+	/**
+	 * Accessible name for the row, e.g. "Example addresses".
+	 */
+	label?: string
+}
+
+export function MapChipRow({ chips, onPick, activeValue, disabled, className, label }: MapChipRowProps): ReactNode {
+	if (!chips.length) return null
+
+	return (
+		<div className={cx("mw-map-chiprow", className)} role="group" aria-label={label}>
+			{chips.map((chip) => {
+				const value = chip.value ?? chip.label
+				const active = value === activeValue
+
+				return (
+					<button
+						key={value}
+						type="button"
+						className={cx("mw-map-chip", active && "mw-map-chip--active")}
+						aria-pressed={active}
+						disabled={disabled}
+						onClick={() => onPick(value)}
+					>
+						{chip.icon ? <span className="mw-map-chip__icon">{chip.icon}</span> : null}
+						{chip.label}
+					</button>
+				)
+			})}
+		</div>
+	)
+}

package/lib/map/MapCompass.tsx

@@ -0,0 +1,77 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<MapCompass>` — the needle that appears when the map leaves north and fades out when it returns.
+ *
+ *   It is a compass ROSE, the way the reference map apps draw it: a ringed dial carrying a two-tone needle whose red
+ *   half points north and whose pale half points south. A single-color arrow cannot say which end is north, so a
+ *   reader has to already know the convention to read it; two tones say it outright. There is no `N` on the dial —
+ *   at this size the letter and the needle's north tip want the same few pixels, and the tip is the clearer of them.
+ *
+ *   The whole dial counter-rotates the bearing, so the needle keeps pointing at true north while the map turns under
+ *   it. Pressing it returns the map to north, which is why the control is a button rather than an ornament.
+ *
+ *   It stays mounted through the fade rather than unmounting on the bearing crossing zero, because a control that
+ *   vanishes mid-gesture is the thing that reads as a glitch. `HIDE_BELOW_DEGREES` is the dead zone: a map settled by
+ *   a snap-to-north lands a fraction off zero, and a compass that lingers over that fraction never goes away.
+ *
+ *   Under `prefers-reduced-motion` it appears and disappears with no transition, and the dial still rotates —
+ *   rotation IS the information, not decoration.
+ *
+ *   NODE-SAFE: pure React, no maplibre. The host reads the bearing off its own map and passes it in.
+ */
+
+import type { ReactNode } from "react"
+
+import { cx } from "#common/cx"
+
+/**
+ * Below this many degrees off north the compass is treated as pointing north and fades out.
+ */
+const HIDE_BELOW_DEGREES = 0.5
+
+export interface MapCompassProps {
+	/**
+	 * The map's bearing in degrees, as MapLibre reports it: 0 is north, positive is counter-clockwise.
+	 */
+	bearing: number
+	/**
+	 * Fired when the compass is pressed — the host resets its map to north.
+	 */
+	onResetNorth: () => void
+	/**
+	 * The control's accessible name. @default "Reset bearing to north"
+	 */
+	label?: string
+	className?: string
+}
+
+export function MapCompass({ bearing, onResetNorth, label, className }: MapCompassProps): ReactNode {
+	const facingNorth = Math.abs(bearing) < HIDE_BELOW_DEGREES
+
+	return (
+		<button
+			type="button"
+			className={cx("mw-map-compass", facingNorth && "mw-map-compass--north", className)}
+			aria-label={label ?? "Reset bearing to north"}
+			title={label ?? "Reset bearing to north"}
+			// Out of the tab order and out of the accessibility tree while it is invisible, so a keyboard reaches only
+			// the controls a pointer can see.
+			aria-hidden={facingNorth}
+			tabIndex={facingNorth ? -1 : 0}
+			onClick={onResetNorth}
+		>
+			<svg viewBox="0 0 32 32" width="26" height="26" aria-hidden="true" focusable="false">
+				<g style={{ transform: `rotate(${-bearing}deg)`, transformOrigin: "16px 16px" }}>
+					<circle cx="16" cy="16" r="12.5" className="mw-map-compass__dial" />
+
+					{/* North, then south. Two triangles meeting at the hub rather than one arrow through it. */}
+					<path d="M16 5.5 L20.5 16 L16 16 Z M16 5.5 L11.5 16 L16 16 Z" className="mw-map-compass__north" />
+					<path d="M16 26.5 L20.5 16 L16 16 Z M16 26.5 L11.5 16 L16 16 Z" className="mw-map-compass__south" />
+				</g>
+			</svg>
+		</button>
+	)
+}

package/lib/map/MapControlStack.tsx

@@ -0,0 +1,98 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<MapControlStack>` — the column of map controls down one edge, and `<MapControlButton>`, the control inside it.
+ *
+ *   Controls sit in GROUPS: a group is one glass capsule with hairlines between its buttons, and separate groups are
+ *   separate capsules with a gap. That grouping is the whole layout idea — related controls read as one object, and
+ *   an unrelated one (a compass that comes and goes) does not join a capsule it would resize.
+ *
+ *   NODE-SAFE: pure React, no maplibre.
+ */
+
+import type { ReactNode } from "react"
+
+import { cx } from "#common/cx"
+
+export interface MapControlButtonProps {
+	/**
+	 * The mark inside the control — an SVG icon or a single glyph.
+	 */
+	children: ReactNode
+	/**
+	 * The control's accessible name. Required: the visible content is a mark, not a word.
+	 */
+	label: string
+	onPress: () => void
+	/**
+	 * Reads as active, for a control that toggles a layer or a mode.
+	 */
+	active?: boolean
+	disabled?: boolean
+	className?: string
+}
+
+export function MapControlButton({
+	children,
+	label,
+	onPress,
+	active,
+	disabled,
+	className,
+}: MapControlButtonProps): ReactNode {
+	return (
+		<button
+			type="button"
+			className={cx("mw-map-control", active && "mw-map-control--active", className)}
+			aria-label={label}
+			aria-pressed={active}
+			title={label}
+			disabled={disabled}
+			onClick={onPress}
+		>
+			{children}
+		</button>
+	)
+}
+
+export interface MapControlGroupProps {
+	children: ReactNode
+	className?: string
+}
+
+/**
+ * One capsule. Put related controls in the same group; give an unrelated one its own.
+ */
+export function MapControlGroup({ children, className }: MapControlGroupProps): ReactNode {
+	return <div className={cx("mw-map-control-group", className)}>{children}</div>
+}
+
+export interface MapControlStackProps {
+	/**
+	 * Groups, top to bottom.
+	 */
+	children: ReactNode
+	/**
+	 * Which edge the column sits against. @default "right"
+	 */
+	side?: "left" | "right"
+	className?: string
+	/**
+	 * Accessible name for the column, e.g. "Map controls".
+	 */
+	label?: string
+}
+
+export function MapControlStack({ children, side = "right", className, label }: MapControlStackProps): ReactNode {
+	return (
+		<div
+			className={cx("mw-map-control-stack", `mw-map-control-stack--${side}`, className)}
+			role="group"
+			aria-label={label}
+		>
+			{children}
+		</div>
+	)
+}

package/lib/map/MapFooter.tsx

@@ -0,0 +1,115 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<MapFooter>` — the strip along the bottom of a map: identity and load status on the left, an attribution button
+ *   on the right.
+ *
+ *   Attribution is a licence obligation for every source these apps draw, so it is a first-class slot rather than
+ *   something an app remembers to add. It sits behind a button because the strip has to stay ONE line: spelled out, the
+ *   credits ran three lines deep on a phone and covered the sheet above them. The button names the obligation, and
+ *   pressing it shows every credit — which is the treatment the reference map apps use.
+ *
+ *   The status slot is where the loader says WHAT it is fetching while the bar at the top of the viewport says how far
+ *   along it is.
+ *
+ *   NODE-SAFE: pure React, no maplibre.
+ */
+
+import { type ReactNode, useEffect, useId, useRef, useState } from "react"
+
+import { cx } from "#common/cx"
+
+export interface MapFooterProps {
+	/**
+	 * The left side: a wordmark, a body name, a line saying what the page does.
+	 */
+	identity?: ReactNode
+	/**
+	 * Beside the identity: what is loading right now. Absent when nothing is.
+	 */
+	status?: ReactNode
+	/**
+	 * The credits, one entry per source. Shown in the popover the attribution button opens.
+	 */
+	attribution?: ReactNode[]
+	/**
+	 * What the attribution button reads. @default "Sources"
+	 */
+	attributionLabel?: string
+	className?: string
+}
+
+export function MapFooter({
+	identity,
+	status,
+	attribution,
+	attributionLabel = "Sources",
+	className,
+}: MapFooterProps): ReactNode {
+	const [open, setOpen] = useState(false)
+	const popoverID = useId()
+	const root = useRef<HTMLElement>(null)
+
+	// A popover closes when the conversation moves elsewhere: a press outside it, or Escape.
+	useEffect(() => {
+		if (!open) return
+
+		const onPointerDown = (event: PointerEvent) => {
+			if (!root.current?.contains(event.target as Node)) {
+				setOpen(false)
+			}
+		}
+
+		const onKeyDown = (event: KeyboardEvent) => {
+			if (event.key === "Escape") {
+				setOpen(false)
+			}
+		}
+
+		document.addEventListener("pointerdown", onPointerDown)
+		document.addEventListener("keydown", onKeyDown)
+
+		return () => {
+			document.removeEventListener("pointerdown", onPointerDown)
+			document.removeEventListener("keydown", onKeyDown)
+		}
+	}, [open])
+
+	if (!identity && !status && !attribution?.length) return null
+
+	return (
+		<footer className={cx("mw-map-footer", className)} ref={root}>
+			<div className="mw-map-footer__identity">
+				{identity}
+				{status ? <span className="mw-map-footer__status">{status}</span> : null}
+			</div>
+
+			{attribution?.length ? (
+				<div className="mw-map-footer__sources">
+					{open ? (
+						<div className="mw-map-footer__popover" id={popoverID} role="group" aria-label="Map data sources">
+							{attribution.map((entry, index) => (
+								// The entries are a fixed, ordered credit list that never reorders, so position is the identity.
+								<span key={index} className="mw-map-footer__credit">
+									{entry}
+								</span>
+							))}
+						</div>
+					) : null}
+
+					<button
+						type="button"
+						className="mw-map-footer__attribution-button"
+						aria-expanded={open}
+						aria-controls={open ? popoverID : undefined}
+						onClick={() => setOpen((value) => !value)}
+					>
+						{attributionLabel}
+					</button>
+				</div>
+			) : null}
+		</footer>
+	)
+}

package/lib/map/MapProgressBar.tsx

@@ -0,0 +1,58 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<MapProgressBar>` — the loading bar pinned across the top of the viewport.
+ *
+ *   Loading a 38 MB model is a page-level event, not a control-level one, so it reports at the page's edge rather than
+ *   inside the search field: a spinner in the field resizes the one control a visitor is trying to type into, and a
+ *   staged list in the result sheet claims the space an answer will need.
+ *
+ *   It reports a FRACTION when the loader names its steps and runs indeterminate when it does not, because a bar that
+ *   invents a percentage is worse than one that admits it is only saying "still working".
+ *
+ *   NODE-SAFE: pure React, no maplibre.
+ */
+
+import type { ReactNode } from "react"
+
+import { cx } from "#common/cx"
+
+export interface MapProgressBarProps {
+	/**
+	 * Whether the bar is showing at all. It stays mounted through its fade rather than unmounting on the transition.
+	 */
+	active: boolean
+	/**
+	 * Completed steps over total steps, in [0, 1]. Omit for work whose length is unknown.
+	 */
+	fraction?: number | null
+	/**
+	 * The bar's accessible name — what is loading, in a few words.
+	 */
+	label: string
+	className?: string
+}
+
+export function MapProgressBar({ active, fraction, label, className }: MapProgressBarProps): ReactNode {
+	const determinate = typeof fraction === "number" && Number.isFinite(fraction)
+	const clamped = determinate ? Math.min(1, Math.max(0, fraction)) : 0
+
+	return (
+		<div
+			className={cx("mw-map-progress", !active && "mw-map-progress--idle", className)}
+			role="progressbar"
+			aria-label={label}
+			aria-hidden={!active}
+			aria-valuemin={determinate ? 0 : undefined}
+			aria-valuemax={determinate ? 100 : undefined}
+			aria-valuenow={determinate ? Math.round(clamped * 100) : undefined}
+		>
+			<div
+				className={cx("mw-map-progress__fill", !determinate && "mw-map-progress__fill--indeterminate")}
+				style={determinate ? { transform: `scaleX(${clamped})` } : undefined}
+			/>
+		</div>
+	)
+}

package/lib/map/MapSearchBar.tsx

@@ -0,0 +1,68 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<MapSearchBar>` — the floating search pill that sits over a map. Presentational only: it supplies the glass
+ *   material, the pill shape and the two icon slots, and the host supplies the input and whatever backend answers it.
+ *   Earth searches an address through the geocoder runtime and the planetary apps search a nomenclature artifact, so
+ *   nothing about the query belongs here.
+ *
+ *   The slots are elements rather than icon names because a leading mark and a trailing control differ per app — a
+ *   magnifier on one, a body glyph on another.
+ *
+ *   BUSY IS A LINE, NOT A SLOT. A spinner placed in the trailing slot changed the pill's height on every submit,
+ *   because a slot is laid out and an indicator is not part of the query. `busy` draws a hairline across the pill's
+ *   lower edge instead, which costs no layout. A host that wants `type="search"` also gets the browser's own clear
+ *   button in that corner, and two crosses side by side is one control too many.
+ *
+ *   NODE-SAFE: pure React, no maplibre.
+ */
+
+import type { ReactNode } from "react"
+
+import { cx } from "#common/cx"
+
+export interface MapSearchBarProps {
+	/**
+	 * The input (or combobox) the host owns. Rendered between the two slots.
+	 */
+	children: ReactNode
+	/**
+	 * Rendered before the input — a magnifier, a body mark, a back arrow.
+	 */
+	leading?: ReactNode
+	/**
+	 * Rendered after the input — a microphone, a menu. Not a spinner: pass {@link busy} instead.
+	 */
+	trailing?: ReactNode
+	/**
+	 * A query is running. Draws a progress hairline along the pill's lower edge, which takes no layout.
+	 */
+	busy?: boolean
+	/**
+	 * Extra class on the pill.
+	 */
+	className?: string
+	/**
+	 * Accessible name for the surrounding region, when the bar is the app's primary search.
+	 */
+	label?: string
+}
+
+export function MapSearchBar({ children, leading, trailing, busy, className, label }: MapSearchBarProps): ReactNode {
+	return (
+		<div
+			className={cx("mw-map-searchbar", busy && "mw-map-searchbar--busy", className)}
+			role={label ? "search" : undefined}
+			aria-label={label}
+			aria-busy={busy}
+		>
+			{leading ? <span className="mw-map-searchbar__slot mw-map-searchbar__slot--leading">{leading}</span> : null}
+
+			<span className="mw-map-searchbar__field">{children}</span>
+
+			{trailing ? <span className="mw-map-searchbar__slot mw-map-searchbar__slot--trailing">{trailing}</span> : null}
+		</div>
+	)
+}

package/lib/map/MapSheet.tsx

@@ -0,0 +1,62 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `<MapSheet>` — a side panel over the map: a title, a close button, and content.
+ *
+ *   The close button is not optional. On a wide screen the control that opened the sheet stays visible beside it and
+ *   could close it again, but on a phone the sheet is the whole panel and covers that control — so a sheet without its
+ *   own close is a sheet a phone cannot dismiss. One component carries it so the four sheets in these apps cannot
+ *   disagree about that.
+ *
+ *   Escape closes it too, because a panel over the whole screen is a modal in every way that matters to someone
+ *   holding a keyboard.
+ *
+ *   NODE-SAFE: pure React, no maplibre.
+ */
+
+import { type ReactNode, useEffect } from "react"
+
+import { cx } from "#common/cx"
+
+export interface MapSheetProps {
+	/**
+	 * The sheet's heading, and its accessible name.
+	 */
+	title: string
+	/**
+	 * Dismiss the sheet.
+	 */
+	onClose: () => void
+	children: ReactNode
+	className?: string
+}
+
+export function MapSheet({ title, onClose, children, className }: MapSheetProps): ReactNode {
+	useEffect(() => {
+		const onKeyDown = (event: KeyboardEvent) => {
+			if (event.key === "Escape") {
+				onClose()
+			}
+		}
+
+		document.addEventListener("keydown", onKeyDown)
+
+		return () => document.removeEventListener("keydown", onKeyDown)
+	}, [onClose])
+
+	return (
+		<aside className={cx("mw-map-sheet mw-map-sheet--side", className)} aria-label={title}>
+			<div className="mw-map-sheet__header">
+				<h2 className="mw-map-sheet__title">{title}</h2>
+
+				<button type="button" className="mw-map-sheet__close" aria-label={`Close ${title}`} onClick={onClose}>
+					<span aria-hidden="true">×</span>
+				</button>
+			</div>
+
+			<div className="mw-map-sheet__body">{children}</div>
+		</aside>
+	)
+}

package/lib/map/PlaceMarker.tsx

@@ -6,7 +6,7 @@
  *   `<PlaceMarker>` — the resolved-place pin, as a declarative `react-map-gl/maplibre` `<Marker>`. This
  *   replaces the old imperative `new maplibre.Marker(...).setLngLat(...).addTo(map)` (+ the manual
  *   `markerRef.current.remove()` teardown) from the demo's redraw effect: mounting/unmounting the marker
- *   is now React's job, keyed on the resolved candidate. Renders as a child of `<DemoMap>`.
+ *   is now React's job, keyed on the resolved candidate. Renders as a child of `<MapCanvas>`.
  *
  *   NODE-IMPORT SAFETY: imports `react-map-gl/maplibre` at module scope, so it is reachable ONLY through
  *   the `@mailwoman/react/map` subpath, never the package root.

package/lib/map/ResolvedPlaceLayers.tsx

@@ -3,10 +3,10 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `<ResolvedPlaceLayers>` — the drop-in that renders a whole {@link MapPlaceRenderSpec} as `<DemoMap>`
+ *   `<ResolvedPlaceLayers>` — the drop-in that renders a whole {@link MapPlaceRenderSpec} as `<MapCanvas>`
  *   children: the marker(s), the outline, and (optionally) the camera move. This is the declarative
  *   replacement for the demo's imperative marker/bbox/camera redraw effect — a consumer computes the spec
- *   with `useMapPlaceRender(place)` and drops `<ResolvedPlaceLayers spec={spec} />` inside `<DemoMap>`.
+ *   with `useMapPlaceRender(place)` and drops `<ResolvedPlaceLayers spec={spec} />` inside `<MapCanvas>`.
  *
  *   `spec = null` (no result / no candidate) renders nothing, which also unmounts the previous marker +
  *   outline — the teardown the old effect did by hand (`markerRef.remove()`, `clearBbox`) is now just
@@ -28,7 +28,7 @@ export interface ResolvedPlaceLayersProps {
 	spec: MapPlaceRenderSpec | null
 	/**
 	 * Apply the computed camera target via {@link ResultCamera}. @default true. Set false when the consumer drives the
-	 * camera itself (e.g. a controlled `<DemoMap viewState>` fed by {@link cameraToViewState}).
+	 * camera itself (e.g. a controlled `<MapCanvas viewState>` fed by {@link cameraToViewState}).
 	 */
 	applyCamera?: boolean
 	/**

package/lib/map/ResultCamera.tsx

@@ -11,7 +11,7 @@
  *   `useMap()` (exactly as `DashboardMap`/`GeoJSONClipboardLayer` reach the map), never a threaded handle.
  *
  *   A consumer that prefers a hard, declarative jump can instead feed the target through
- *   {@link cameraToViewState} into a controlled `<DemoMap viewState>` and skip this component — the
+ *   {@link cameraToViewState} into a controlled `<MapCanvas viewState>` and skip this component — the
  *   `center` case has that declarative path; only `bounds` strictly requires this. Renders nothing.
  *
  *   `target` is expected to be the STABLE, memoized `camera` off a `useMapPlaceRender` spec, so listing it