@mailwoman/react 10.0.0 → 10.1.0

package/lib/map/GraticuleLayer.tsx

@@ -0,0 +1,54 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Draws a grid of meridians and parallels under the basemap so that the globe is readable while
+ *   tiles load. Loaded tiles cover the grid.
+ */
+
+import { type ReactNode, useMemo } from "react"
+import { Layer, Source } from "react-map-gl/maplibre"
+
+import { buildGraticule } from "./graticule.ts"
+
+/**
+ * Props for {@link GraticuleLayer}.
+ */
+export interface GraticuleLayerProps {
+	/**
+	 * The basemap layer to draw the grid beneath.
+	 * Without it, the grid is drawn on top.
+	 */
+	beforeID?: string
+	/**
+	 * Hides the grid. @default false
+	 */
+	hidden?: boolean
+}
+
+/**
+ * Renders the graticule source and line layer.
+ */
+export function GraticuleLayer({ beforeID, hidden = false }: GraticuleLayerProps): ReactNode {
+	const data = useMemo(() => buildGraticule(), [])
+
+	return (
+		<>
+			<Source id="mw-graticule" type="geojson" data={data} />
+			<Layer
+				id="mw-graticule-line"
+				type="line"
+				source="mw-graticule"
+				{...(beforeID ? { beforeId: beforeID } : {})}
+				layout={{ visibility: hidden ? "none" : "visible", "line-cap": "round" }}
+				paint={{
+					"line-color": "#8aa0c8",
+					// The grid fades out by zoom 8, where map detail makes it unnecessary.
+					"line-opacity": ["interpolate", ["linear"], ["zoom"], 0, 0.3, 3, 0.2, 6, 0.09, 8, 0],
+					"line-width": ["interpolate", ["linear"], ["zoom"], 0, 0.5, 4, 0.75],
+				}}
+			/>
+		</>
+	)
+}

package/lib/map/MapCanvas.tsx

@@ -5,18 +5,18 @@
  *
  *   `<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.
+ *   controlled) view state and a `children` slot for overlays/markers from later phases.
  *   No overlay/marker/camera logic lives here yet.
  *
- *   NODE-IMPORT SAFETY: this module imports `react-map-gl/maplibre` (which pulls `maplibre-gl` — WebGL
- *   + DOM at import) at module scope, so it is reachable ONLY through the `@mailwoman/react/map`
+ *   node-import safety: this module imports `react-map-gl/maplibre` (which pulls `maplibre-gl` — WebGL
+ *   + DOM at import) at module scope, so it is reachable only through the `@mailwoman/react/map`
  *   subpath, never from the package root (`index.ts`). The bare `import("@mailwoman/react")` a node
  *   consumer (or the CI smoke IMPORT_CHECK) runs must never transitively load this file. Keep it out of
  *   the root barrel.
  *
  *   CSS: the package imports no CSS from its modules (the node-safe invariant), so a host that renders
  *   `<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
+ *   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 `Geocoder` will in a later phase.
  */
@@ -31,8 +31,10 @@ import type { MapProps, MapRef, ViewStateChangeEvent } from "react-map-gl/maplib
 export type MapCanvasStyle = NonNullable<MapProps["mapStyle"]>
 
 /**
- * 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.
+ * 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 MapCanvasExtraProps = Partial<
 	Omit<MapProps, "mapStyle" | "initialViewState" | "viewState" | "onMove" | "children" | "style" | "ref">
@@ -44,11 +46,15 @@ export interface MapCanvasProps {
 	 */
 	mapStyle: MapCanvasStyle
 	/**
-	 * Uncontrolled initial camera. Use this OR `viewState`, not both.
+	 * Uncontrolled initial camera.
+	 *
+	 * Use this or `viewState`, not both.
 	 */
 	initialViewState?: MapProps["initialViewState"]
 	/**
-	 * Controlled camera. Pair with `onMove` to persist it.
+	 * Controlled camera.
+	 *
+	 * Pair with `onMove` to persist it.
 	 */
 	viewState?: MapProps["viewState"]
 	/**
@@ -64,7 +70,9 @@ export interface MapCanvasProps {
 	 */
 	mapRef?: Ref<MapRef>
 	/**
-	 * Overlays, markers, and controls — rendered as `<Map>` children. Empty in phase 1.
+	 * Overlays, markers and controls — rendered as `<Map>` children.
+	 *
+	 * Empty in phase 1.
 	 */
 	children?: ReactNode
 	/**
@@ -76,7 +84,7 @@ export interface MapCanvasProps {
 	 */
 	style?: CSSProperties
 	/**
-	 * Remaining `<Map>` props MapCanvas does not surface explicitly.
+	 * Other `<Map>` props that MapCanvas does not surface explicitly.
 	 */
 	mapProps?: MapCanvasExtraProps
 }
@@ -84,8 +92,11 @@ export interface MapCanvasProps {
 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`.
+ * 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.
+ * Overlays arrive as `children`.
  */
 export function MapCanvas({
 	mapStyle,

package/lib/map/MapChipRow.tsx

@@ -3,13 +3,7 @@
  * @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.
+ *   Render example-query chips in a single horizontally scrollable row.
  */
 
 import type { ReactNode } from "react"
@@ -22,7 +16,9 @@ export interface MapChip {
 	 */
 	label: string
 	/**
-	 * The query the chip stands for, handed back on press. Defaults to the label.
+	 * The query the chip stands for, handed back on press.
+	 *
+	 * Defaults to the label.
 	 */
 	value?: string
 	/**

package/lib/map/MapCompass.tsx

@@ -3,24 +3,8 @@
  * @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.
+ *   Shows a compass that rotates with the map bearing and hides when the map faces north. A press
+ *   it asks the host to reset the bearing.
  */
 
 import type { ReactNode } from "react"
@@ -28,17 +12,22 @@ 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.
+ * The compass counts as facing north below this bearing.
+ * It fades out below the same threshold.
  */
 const HIDE_BELOW_DEGREES = 0.5
 
+/**
+ * Props for {@link MapCompass}.
+ */
 export interface MapCompassProps {
 	/**
-	 * The map's bearing in degrees, as MapLibre reports it: 0 is north, positive is counter-clockwise.
+	 * The map's bearing in degrees as MapLibre reports it, where 0 is north.
 	 */
 	bearing: number
 	/**
-	 * Fired when the compass is pressed — the host resets its map to north.
+	 * Called when the compass is pressed.
+	 * The host should reset its map to north.
 	 */
 	onResetNorth: () => void
 	/**
@@ -48,6 +37,9 @@ export interface MapCompassProps {
 	className?: string
 }
 
+/**
+ * Renders the compass button.
+ */
 export function MapCompass({ bearing, onResetNorth, label, className }: MapCompassProps): ReactNode {
 	const facingNorth = Math.abs(bearing) < HIDE_BELOW_DEGREES
 
@@ -57,8 +49,7 @@ export function MapCompass({ bearing, onResetNorth, label, className }: MapCompa
 			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.
+			// The hidden compass leaves the tab order and the accessibility tree.
 			aria-hidden={facingNorth}
 			tabIndex={facingNorth ? -1 : 0}
 			onClick={onResetNorth}
@@ -67,7 +58,7 @@ export function MapCompass({ bearing, onResetNorth, label, className }: MapCompa
 				<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. */}
+					{/* The north needle, then the south needle. */}
 					<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>

package/lib/map/MapControlStack.tsx

@@ -3,13 +3,7 @@
  * @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.
+ *   Provide accessible map-control buttons arranged in grouped capsules.
  */
 
 import type { ReactNode } from "react"
@@ -22,7 +16,9 @@ export interface MapControlButtonProps {
 	 */
 	children: ReactNode
 	/**
-	 * The control's accessible name. Required: the visible content is a mark, not a word.
+	 * The control's accessible name.
+	 *
+	 * Required: the visible content is a mark rather than a word.
 	 */
 	label: string
 	onPress: () => void
@@ -63,7 +59,10 @@ export interface MapControlGroupProps {
 }
 
 /**
- * One capsule. Put related controls in the same group; give an unrelated one its own.
+ * 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>

package/lib/map/MapFooter.tsx

@@ -2,19 +2,6 @@
  * @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"
@@ -27,11 +14,11 @@ export interface MapFooterProps {
 	 */
 	identity?: ReactNode
 	/**
-	 * Beside the identity: what is loading right now. Absent when nothing is.
+	 * What is loading right now, beside the identity.
 	 */
 	status?: ReactNode
 	/**
-	 * The credits, one entry per source. Shown in the popover the attribution button opens.
+	 * The credits, one entry per source, shown in the popover the attribution button opens.
 	 */
 	attribution?: ReactNode[]
 	/**
@@ -52,7 +39,6 @@ export function MapFooter({
 	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
 

package/lib/map/MapProgressBar.tsx

@@ -3,16 +3,8 @@
  * @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.
+ *   Show loading progress at the top of the viewport.
+ *   Use a determinate bar when progress is known, otherwise an indeterminate bar.
  */
 
 import type { ReactNode } from "react"
@@ -21,15 +13,20 @@ 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.
+	 * 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.
+	 * 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.
+	 * The bar's accessible name.
+	 * What is loading, in a few words.
 	 */
 	label: string
 	className?: string

package/lib/map/MapSearchBar.tsx

@@ -3,29 +3,38 @@
  * @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.
+ *   Presentational search pill for map UIs. The host supplies the input and icons.
+ *   Busy state uses a bottom-edge indicator to avoid changing the pill layout.
  */
 
 import type { ReactNode } from "react"
 
 import { cx } from "#common/cx"
 
+/**
+ * Draw a consistently sized magnifier for the leading slot.
+ */
+export function SearchGlyph(): ReactNode {
+	return (
+		<svg
+			viewBox="0 0 20 20"
+			width="18"
+			height="18"
+			aria-hidden="true"
+			focusable="false"
+			className="mw-map-searchbar__glyph"
+		>
+			<circle cx="8.75" cy="8.75" r="5.5" fill="none" stroke="currentColor" strokeWidth="1.8" />
+			<line x1="12.9" y1="12.9" x2="17" y2="17" stroke="currentColor" strokeWidth="1.8" strokeLinecap="round" />
+		</svg>
+	)
+}
+
 export interface MapSearchBarProps {
 	/**
-	 * The input (or combobox) the host owns. Rendered between the two slots.
+	 * The input (or combobox) the host owns.
+	 *
+	 * Rendered between the two slots.
 	 */
 	children: ReactNode
 	/**
@@ -33,11 +42,16 @@ export interface MapSearchBarProps {
 	 */
 	leading?: ReactNode
 	/**
-	 * Rendered after the input — a microphone, a menu. Not a spinner: pass {@link busy} instead.
+	 * 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.
+	 * A query is running.
+	 *
+	 * Draws a progress hairline along the pill's lower edge.
+	 * The hairline takes no layout space.
 	 */
 	busy?: boolean
 	/**

package/lib/map/MapSheet.tsx

@@ -3,26 +3,37 @@
  * @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.
+ *   Side panel over the map with a heading, close button and Escape dismissal.
  */
 
 import { type ReactNode, useEffect } from "react"
 
 import { cx } from "#common/cx"
 
+export interface SheetCloseProps {
+	/**
+	 * What is being closed, for the accessible name: "Close the result", "Close About".
+	 */
+	label: string
+	onClose: () => void
+	className?: string
+}
+
+/**
+ * Accessible button for dismissing a sheet.
+ */
+export function SheetClose({ label, onClose, className }: SheetCloseProps): ReactNode {
+	return (
+		<button type="button" className={cx("mw-map-sheet__close", className)} aria-label={label} onClick={onClose}>
+			<span aria-hidden="true">×</span>
+		</button>
+	)
+}
+
 export interface MapSheetProps {
 	/**
-	 * The sheet's heading, and its accessible name.
+	 * The sheet's heading.
+	 * It also supplies the accessible name.
 	 */
 	title: string
 	/**
@@ -51,9 +62,7 @@ export function MapSheet({ title, onClose, children, className }: MapSheetProps)
 			<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>
+				<SheetClose label={`Close ${title}`} onClose={onClose} />
 			</div>
 
 			<div className="mw-map-sheet__body">{children}</div>

package/lib/map/OverlayLayers.tsx

@@ -9,7 +9,7 @@
  *   the host composes the specs, the package renders them, react-map-gl owns the add/remove lifecycle.
  *
  *   Each overlay's `visible` flag flips the layers' `visibility` layout property — the declarative control a
- *   layer-toggle control drives in a later phase. NODE-IMPORT SAFETY: imports `react-map-gl/maplibre` —
+ *   layer-toggle control drives in a later phase. node-import safety: imports `react-map-gl/maplibre` —
  *   reachable only via `@mailwoman/react/map`.
  */
 

package/lib/map/PlaceAutocomplete.tsx

@@ -3,13 +3,7 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `<PlaceAutocomplete>` — the "Did you mean" suggestion listbox from the demo (`_app.tsx:1394-1418`), as
- *   a dumb presentational unit. It renders the current suggestions with the keyboard-highlighted active
- *   descendant; the state + keyboard nav live in {@link usePlaceAutocomplete}. Renders `null` when there
- *   is nothing to suggest, so the row only appears when useful. Wire the ids from the hook so the input's
- *   `aria-controls` / `aria-activedescendant` match this listbox.
- *
- *   NODE-SAFE: pure React, no maplibre.
+ * The `usePlaceAutocomplete` hook owns the state and keyboard navigation.
  */
 
 import type { ReactNode } from "react"
@@ -17,39 +11,34 @@ import type { ReactNode } from "react"
 import { cx } from "#common/cx"
 import type { Suggestion } from "#map/types"
 
+/**
+ * Props for {@link PlaceAutocomplete}.
+ */
 export interface PlaceAutocompleteProps {
-	/**
-	 * The suggestions to render (from {@link usePlaceAutocomplete}).
-	 */
 	suggestions: Suggestion[]
 	/**
-	 * The keyboard-highlighted index; `-1` for none.
+	 * The index highlighted by the keyboard, or `-1` for none.
 	 */
 	activeIndex: number
-	/**
-	 * Fired (with the suggestion `value`) when one is clicked.
-	 */
 	onPick: (value: string) => void
-	/**
-	 * Fired with the index a pointer entered, so hover matches keyboard highlight.
-	 */
 	onHover?: (index: number) => void
 	/**
-	 * The listbox element id — pass `listboxID` from the hook (matches the input's `aria-controls`).
+	 * The listbox element id, passed from the hook so it matches the input's `aria-controls`.
 	 */
 	listboxID: string
 	/**
-	 * Build the option element id — pass `optionID` from the hook.
+	 * Pass `optionID` from the hook.
 	 */
 	optionID: (index: number) => string
 	/**
-	 * Leading label. @default "Did you mean:"
+	 * The label before the suggestions. @default "Did you mean:"
 	 */
 	caption?: string
 }
 
 /**
- * The suggestion listbox.
+ * Renders the suggestion listbox when suggestions exist.
+ * It renders no listbox otherwise.
  */
 export function PlaceAutocomplete({
 	suggestions,

package/lib/map/PlaceMarker.tsx

@@ -8,7 +8,7 @@
  *   `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 `<MapCanvas>`.
  *
- *   NODE-IMPORT SAFETY: imports `react-map-gl/maplibre` at module scope, so it is reachable ONLY through
+ *   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.
  */
 
@@ -40,7 +40,9 @@ export interface PlaceMarkerProps {
 }
 
 /**
- * A single resolved-place marker. Wraps `react-map-gl`'s `<Marker>` with the demo's default color.
+ * A single resolved-place marker.
+ *
+ * Wraps `react-map-gl`'s `<Marker>` with the demo's default color.
  */
 export function PlaceMarker({
 	longitude,

package/lib/map/ResolvedPlaceLayers.tsx

@@ -2,15 +2,6 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   `<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 `<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
- *   React unmounting. NODE-IMPORT SAFETY: pulls the map components — `@mailwoman/react/map` only.
  */
 
 import type { ReactNode } from "react"
@@ -23,16 +14,16 @@ import { ResultOverlay } from "./ResultOverlay.tsx"
 
 export interface ResolvedPlaceLayersProps {
 	/**
-	 * The render spec (from {@link useMapPlaceRender}); `null` renders nothing.
+	 * The render spec (from {@link useMapPlaceRender}); `null` renders no layers.
 	 */
 	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 `<MapCanvas viewState>` fed by {@link cameraToViewState}).
+	 * Apply the computed camera target via {@link ResultCamera}; set false when the consumer drives the camera
+	 * itself (e.g. a controlled `<MapCanvas viewState>` fed by {@link cameraToViewState}). @default true
 	 */
 	applyCamera?: boolean
 	/**
-	 * Animate the camera move. Forwarded to {@link ResultCamera}. @default true
+	 * Animate the camera move, forwarded to {@link ResultCamera}. @default true
 	 */
 	animateCamera?: boolean
 	/**
@@ -46,7 +37,7 @@ export interface ResolvedPlaceLayersProps {
 }
 
 /**
- * Render the marker(s), outline, and (optional) camera move for one resolved place.
+ * Render the marker(s), outline and optional camera move for one resolved place.
  */
 export function ResolvedPlaceLayers({
 	spec,