@mailwoman/react 10.0.0 → 10.1.0

package/lib/map/ResultCamera.tsx

@@ -2,21 +2,6 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   `<ResultCamera>` — applies the {@link MapCameraTarget} a {@link MapPlaceRenderSpec} computes, by
- *   animating the live map to it. This is the ONE deliberately-imperative touch in the phase-2 overlays,
- *   and it is justified: maplibre exposes animated camera moves (`flyTo`) and viewport-fitting
- *   (`fitBounds`, which needs the map's PIXEL dimensions + padding) ONLY imperatively — react-map-gl has
- *   no declarative prop for "animate to these bounds". It is applied the v8-idiomatic way, through
- *   `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 `<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
- *   as the effect dependency re-runs the camera move exactly when the resolved place changes — no
- *   value-key dance, no dependency-lint suppression.
  */
 
 import type { FitBoundsOptions } from "maplibre-gl"
@@ -26,38 +11,30 @@ import { useMap } from "react-map-gl/maplibre"
 import type { MapCameraTarget } from "#map/place-render"
 
 /**
- * The `fitBounds` options for a `bounds` target — and the reason this is a named function rather than an object literal
- * at the call site.
+ * Builds `fitBounds` options without an undefined `duration` key.
  *
- * `duration` is present ONLY on the non-animated path, and its ABSENCE on the animated one is required. maplibre's
- * `Camera.flyTo` (which `fitBounds` funnels into via `_fitInternal`) branches on `'duration' in options`, not on the
- * value: an explicitly-passed `duration: undefined` therefore survives the key test and is coerced with `+undefined` →
- * `NaN`. Every ease frame then computes `k = easing(elapsed / NaN)` → `NaN`, the flight-path math yields a `NaN` world
- * coordinate, and the FIRST frame throws `Invalid LngLat object: (NaN, NaN)` out of the RAF loop — before the map has
- * moved at all, and with no `move` event to notice it by.
- *
- * Measured 2026-08-05 against maplibre-gl 5.24.0, same bounds and same map: `{padding: 40, duration: undefined}` →
- * `map._easeOptions.duration = NaN` + the throw; `{padding: 40}` → `3937.7 ms` + a normal flight. So pass the key or
- * don't — never pass it holding `undefined`.
+ * MapLibre checks for existence and can turn into a NaN camera move.
  */
 export function fitBoundsOptionsFor(padding: number, animate: boolean): FitBoundsOptions {
 	return animate ? { padding } : { padding, duration: 0 }
 }
 
+/**
+ * Props for {@link ResultCamera}.
+ */
 export interface ResultCameraProps {
 	/**
-	 * The camera target to animate to. `null` leaves the camera untouched (no result yet).
+	 * The camera target; `null` leaves the camera where it is.
 	 */
 	target: MapCameraTarget | null
 	/**
-	 * Animate (`flyTo`/`fitBounds`) vs jump. @default true. When false, a `center` target jumps with `jumpTo`; a `bounds`
-	 * target still uses `fitBounds` (no instantaneous fit exists) but with `duration: 0`.
+	 * Whether to animate the move. @default true
 	 */
 	animate?: boolean
 }
 
 /**
- * Drive the live map to `target`. No DOM of its own — it is a behavior mounted as a `<Map>` child.
+ * Moves the map to `target`; mount it as a child of `<Map>`.
  */
 export function ResultCamera({ target, animate = true }: ResultCameraProps): ReactNode {
 	const map = useMap()

package/lib/map/ResultOverlay.tsx

@@ -2,15 +2,6 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   `<ResultOverlay>` — the resolved-place outline (crisp admin polygon, or an approximate/exact-radius
- *   circle) as a declarative `<Source>` + fill/line `<Layer>`s. This replaces the demo's imperative
- *   `setPlaceOutline` / `drawApproxCircle` / `drawPlaceGeometry` / `clearBbox` helpers and their
- *   `whenStyleReady` guard: react-map-gl owns the "add source/layer once the style is loaded, remove on
- *   unmount" lifecycle, so the hand-rolled `isStyleLoaded()` / `styledata` races disappear.
- *
- *   Pass the `outline` straight from a {@link MapPlaceRenderSpec}; a `null` outline renders nothing (the
- *   bare-point case). NODE-IMPORT SAFETY: imports `react-map-gl/maplibre` — `@mailwoman/react/map` only.
  */
 
 import type { ReactNode } from "react"
@@ -25,7 +16,7 @@ const OUTLINE_COLOR = "#e0367c"
 
 export interface ResultOverlayProps {
 	/**
-	 * The outline geometry to draw, or `null` to draw nothing (the bare-point result).
+	 * The outline geometry to draw, or `null` to draw no geometry (the bare-point result).
 	 */
 	outline: PlaceGeometry | null
 	/**
@@ -47,8 +38,7 @@ export interface ResultOverlayProps {
 }
 
 /**
- * Render the resolved-place outline. One geojson `<Source>` feeds a translucent fill `<Layer>` and a solid line
- * `<Layer>` — the same two layers the imperative `setPlaceOutline` created, now declarative and self-cleaning.
+ * Render the resolved-place outline.
  */
 export function ResultOverlay({
 	outline,

package/lib/map/ResultPanel.tsx

@@ -2,16 +2,6 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   `<ResultPanel>` — the demo's parse+resolve result block, assembled from the SHARED pipeline
- *   presentational units (it does not re-implement any of them): `KindBadge`, `ComponentTable`,
- *   `ResolvedPlace`, `CandidatePicker`, plus the `CopyButton` + `buildParsePayload` copy affordance. This
- *   is the standalone, story-testable unit the demo's floating panel renders (the map analogue of the
- *   result block PipelineExplorer inlines), so `Geocoder` composes ONE panel instead of duplicating
- *   the marker/table/candidate glue. Heavy host visualizers (span highlight, tree, timing) slot in via
- *   `extras`; the no-resolve diagnostic via `failure`.
- *
- *   NODE-SAFE: pure React + the shared units, no maplibre.
  */
 
 import type { ParseResult, ResolvedPlaceView } from "@mailwoman/core/pipeline/client-result"
@@ -26,28 +16,19 @@ import { ComponentTable } from "../pipeline/ComponentTable.tsx"
 import { ResolvedPlace } from "../pipeline/ResolvedPlace.tsx"
 
 export interface ResultPanelProps {
-	/**
-	 * The parse+resolve result to render.
-	 */
 	result: ParseResult
 	/**
 	 * The selected candidate (falls back to the first), used for the resolved-place detail + copy payload.
 	 */
 	selectedCandidate: ResolvedPlaceView | null
-	/**
-	 * The selected candidate index, for the picker's active state.
-	 */
 	selectedCandidateIndex: number
-	/**
-	 * Fired when a candidate in the picker is chosen.
-	 */
 	onSelectCandidate: (index: number) => void
 	/**
 	 * Host-injected heavy visualizers (span highlight, tree, timing, …), rendered from the result.
 	 */
 	extras?: (result: ParseResult) => ReactNode
 	/**
-	 * Host-injected no-resolve diagnostic, rendered when nothing resolved.
+	 * Host-injected no-resolve diagnostic, rendered when no place resolved.
 	 */
 	failure?: (result: ParseResult) => ReactNode
 }

package/lib/map/VersionPicker.tsx

@@ -3,44 +3,32 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `<VersionPicker>` — the model-version `<select>` from the demo's control panel (`_app.tsx:1230-1254`),
- *   as a dumb presentational unit: the available bundles + current selection come in as props, the choice
- *   goes out through `onSelect`. No load state, no manifest fetch — the host (via `useReleaseRuntime`) owns
- *   that. Renders nothing when there is fewer than two versions to choose between.
- *
- *   NODE-SAFE: pure React + a `<select>`, no maplibre. It rides the `@mailwoman/react/map` subpath only
- *   because it is a demo-specific control, not because it needs WebGL.
+ *   Renders a selector for the available model versions. The host owns loading and selection.
  */
 
 import type { ReactNode } from "react"
 
 import type { VersionOption } from "#map/types"
 
+/**
+ * Props for {@link VersionPicker}.
+ */
 export interface VersionPickerProps {
-	/**
-	 * The selectable model bundles.
-	 */
 	versions: ReadonlyArray<VersionOption>
-	/**
-	 * The currently-selected version tag.
-	 */
 	selected: string | null
-	/**
-	 * Fired with the chosen version tag.
-	 */
 	onSelect: (version: string) => void
 	/**
-	 * Disable the control (e.g. while a parse is running).
+	 * Disables the control, for example while a parse runs.
 	 */
 	disabled?: boolean
 	/**
-	 * Field label. @default "Model version"
+	 * @default "Model version"
 	 */
 	label?: string
 }
 
 /**
- * The model-version selector. Renders `null` when there is nothing meaningful to pick.
+ * Renders the model version selector, or `null` when fewer than two versions exist.
  */
 export function VersionPicker({
 	versions,
@@ -62,6 +50,9 @@ export function VersionPicker({
 				value={selected ?? ""}
 				onChange={(e) => onSelect(e.target.value)}
 				disabled={disabled}
+				// The title shows the full label.
+				// The field may clip it.
+				title={versions.find((v) => v.version === selected)?.label ?? selected ?? undefined}
 			>
 				{versions.map((v) => (
 					<option key={v.version} value={v.version}>

package/lib/map/fake-runtime.ts

@@ -2,10 +2,6 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   A fake geocoder runtime: canned parse + resolve, an offline stub map style, canned autocomplete, a version list.
- *   No network, no ONNX, no maplibre at run time — everything is data. It is what the stories and component tests
- *   mount, and what a host mounts to show the UI without the model.
  */
 
 import type { ParseResult } from "@mailwoman/core/pipeline/client-result"
@@ -17,7 +13,8 @@ import type { PipelineRuntime } from "#pipeline/types"
 import type { MapCanvasStyle } from "./MapCanvas.tsx"
 
 /**
- * An offline stub map style — one solid `background` layer, zero sources, zero network. Safe for headless Storybook.
+ * Defines an offline map style with a single background layer and no sources,
+ * so it renders in headless Storybook without network access.
  */
 export const STUB_MAP_STYLE: MapCanvasStyle = {
 	version: 8,
@@ -36,11 +33,11 @@ export const FAKE_SUGGESTIONS: Suggestion[] = [
 ]
 
 /**
- * A fake DEMO runtime — the map analogue of {@link makePipelineRuntime}. It composes the pipeline fake (canned
- * parse+resolve) with the map surface: the offline stub style, a version list, a backend, an injected autocomplete, and
- * a `resolveMapPlace` that hands the selected candidate a bbox so the declarative overlays draw a marker + outline. No
- * network, no ONNX, no maplibre-at-runtime — everything is data. `runParseWithBias` delegates to the base parse (the
- * bias is ignored by the fake but present so the parameter is exercised).
+ * Creates an offline {@link GeocoderRuntime} that extends {@link makePipelineRuntime}
+ * with the stub style, canned suggestions and versions.
+ *
+ * It also provides `resolveMapPlace` that gives the candidate a bounding box so overlays draw.
+ * The fake ignores the bias passed to `runParseWithBias`.
  */
 export function makeFakeGeocoderRuntime(overrides: Partial<GeocoderRuntime> = {}): GeocoderRuntime {
 	const base = makePipelineRuntime()
@@ -64,7 +61,7 @@ export function makeFakeGeocoderRuntime(overrides: Partial<GeocoderRuntime> = {}
 		activeBackend: "webgpu (28 MB int8)",
 		forceWASM: false,
 		setForceWASM: () => {},
-		// Enrich the selected candidate with a bbox so an outline renders (case 4: bbox → approximate circle + fit).
+
 		resolveMapPlace: (candidate): ResolvedMapPlace => ({
 			...candidate,
 			bbox: {
@@ -79,7 +76,8 @@ export function makeFakeGeocoderRuntime(overrides: Partial<GeocoderRuntime> = {}
 }
 
 /**
- * A fixed, fully-populated parse+resolve result — the shared fixture behind the pipeline runtime + the result panel.
+ * Creates a fixed, fully populated parse-and-resolve result for the given input,
+ * shared by the fake pipeline runtime and result-panel fixtures.
  */
 export function makeFakeParseResult(input = "350 5th Ave, New York, NY 10118"): ParseResult {
 	return {

package/lib/map/geometry.ts

@@ -2,28 +2,12 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   Pure map geometry for the geocoder demo — the resolved-place outline math, lifted verbatim from the
- *   docs demo's `_map-helpers.ts`. Zero imports: no React, no `react-map-gl`, no `maplibre-gl`, no DOM.
- *   Every function takes plain numbers and returns plain GeoJSON, so the whole module runs (and is
- *   tested) under bare node — see `geometry.node.test.ts`.
- *
- *   WHY NOT `@mailwoman/spatial`: the only truly-spatial primitive here is the bbox half-diagonal (a
- *   great-circle-ish distance). `@mailwoman/spatial` exposes `haversineKm`, but ONLY via its root barrel,
- *   which pulls `@mailwoman/core` + `h3-js` + `wkx` — a heavy, partly node-only graph — into what must
- *   stay a lightweight, browser-only map bundle (the `@mailwoman/react/map` subpath). The original
- *   `_map-helpers.ts` made the same call: a planar `kmPerDeg` approximation, local, no dependency. We
- *   preserve it so the ported behavior is byte-identical and the browser graph stays clean.
  */
 
-/**
- * Segments used to approximate a circle as a polygon ring.
- */
+import type { LatLonBounds } from "@mailwoman/spatial"
+
 const CIRCLE_SEGMENTS = 64
 
-/**
- * Mean km per degree of latitude (WGS84 average).
- */
 const KM_PER_DEG_LAT = 111.32
 
 /**
@@ -33,31 +17,15 @@ export type PlaceGeometry =
 	| { type: "Polygon"; coordinates: number[][][] }
 	| { type: "MultiPolygon"; coordinates: number[][][][] }
 
-/**
- * A place bounding box in the demo's object form (the WOF points DB carries only these four numbers).
- */
-export interface PlaceBBox {
-	minLat: number
-	maxLat: number
-	minLon: number
-	maxLon: number
-}
-
 /**
  * A `[west, south, east, north]` → `[[minLon, minLat], [maxLon, maxLat]]` pair, the shape `fitBounds` wants.
  */
 export type BoundsTuple = [[number, number], [number, number]]
 
-/**
- * Km per degree of longitude at a given latitude — the meridians converge toward the poles.
- */
 function kmPerDegLon(lat: number): number {
 	return KM_PER_DEG_LAT * Math.cos((lat * Math.PI) / 180)
 }
 
-/**
- * A closed 64-segment (65-point) GeoJSON ring of `radiusKM` around `[lon, lat]`, with latitude correction.
- */
 function circleRing(lat: number, lon: number, radiusKM: number): number[][] {
 	const perLon = kmPerDegLon(lat)
 	const ring: number[][] = []
@@ -72,11 +40,10 @@ function circleRing(lat: number, lon: number, radiusKM: number): number[][] {
 }
 
 /**
- * Approximate-extent circle for places without a crisp polygon: centered on the place point, radius from the bbox
- * half-diagonal (clamped 0.5–50 km). 64-point ring with latitude correction — visually a circle anywhere outside the
- * poles. With no bbox (anchor-centroid postcodes carry no extent) it defaults to a ~ZIP-sized 3 km radius.
+ * Returns a circle approximating the extent of a place that has no polygon, with a radius
+ * of half the bbox diagonal clamped to 0.5–50 km, or 3 km when there is no bbox.
  */
-export function approxCircleGeometry(lat: number, lon: number, bbox?: PlaceBBox): PlaceGeometry {
+export function approxCircleGeometry(lat: number, lon: number, bbox?: LatLonBounds): PlaceGeometry {
 	const halfDiagKm = bbox
 		? Math.hypot((bbox.maxLat - bbox.minLat) * KM_PER_DEG_LAT, (bbox.maxLon - bbox.minLon) * kmPerDegLon(lat)) / 2
 		: 3
@@ -87,9 +54,8 @@ export function approxCircleGeometry(lat: number, lon: number, bbox?: PlaceBBox)
 }
 
 /**
- * A circle of an EXACT radius in meters — for the street-level uncertainty (#377): a 10 m situs floor or a calibrated
- * interp radius. Unlike {@link approxCircleGeometry} (clamped to a ~ZIP-sized 0.5 km floor for admin fallbacks), this
- * honors small radii so an exact building reads as a tight dot (an ~8 m floor keeps a 10 m situs circle visible).
+ * Returns a circle with the given radius in meters for street-level uncertainty, floored at 8 m
+ * so that a precise point stays visible, unlike {@link approxCircleGeometry}'s 0.5 km floor.
  */
 export function radiusCircleGeometry(lat: number, lon: number, radiusM: number): PlaceGeometry {
 	const radiusKM = Math.max(0.008, radiusM / 1000)
@@ -98,11 +64,12 @@ export function radiusCircleGeometry(lat: number, lon: number, radiusM: number):
 }
 
 /**
- * Bounding box of a Polygon / MultiPolygon, for `fitBounds`. Walks the nested coordinate arrays, so it handles both a
- * single-ring polygon and a multi-part polygon uniformly. Antimeridian-crossing geometry is NOT normalized (the naive
- * min/max is returned) — matching the ported behavior; callers that need a wrapped bbox must handle it upstream.
+ * Returns the bounding box of a Polygon or MultiPolygon for `fitBounds`.
+ *
+ * Geometry that crosses the antimeridian gets a naive min/max box, so callers
+ * that need a wrapped box must handle it themselves.
  */
-export function geomBounds(geometry: PlaceGeometry): PlaceBBox {
+export function geomBounds(geometry: PlaceGeometry): LatLonBounds {
 	let minLon = Infinity
 	let minLat = Infinity
 	let maxLon = -Infinity
@@ -145,9 +112,9 @@ export function geomBounds(geometry: PlaceGeometry): PlaceBBox {
 }
 
 /**
- * Reshape a {@link PlaceBBox} into the `[[minLon, minLat], [maxLon, maxLat]]` pair `fitBounds` expects.
+ * Reshape a {@link LatLonBounds} into the `[[minLon, minLat], [maxLon, maxLat]]` pair `fitBounds` expects.
  */
-export function bboxToBounds(bbox: PlaceBBox): BoundsTuple {
+export function bboxToBounds(bbox: LatLonBounds): BoundsTuple {
 	return [
 		[bbox.minLon, bbox.minLat],
 		[bbox.maxLon, bbox.maxLat],

package/lib/map/graticule.ts

@@ -0,0 +1,80 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The graticule's geometry, apart from its component — the same split `place-render.ts` keeps from
+ *   `ResolvedPlaceLayers.tsx`. Pure and node-testable; `#*` resolves `.ts` only, so this is also the file the test can
+ *   import.
+ */
+
+import type { FeatureCollection, MultiLineString } from "geojson"
+
+/**
+ * Degrees between grid lines. 15° is one hour of longitude — twelve meridians and eleven
+ * parallels, dense enough to read as a globe and sparse enough not to read as graph paper.
+ */
+const DEFAULT_STEP_DEGREES = 15
+
+/**
+ * Degrees between vertices along each line.
+ *
+ * A meridian drawn as two points is a straight chord through the sphere under a globe projection.
+ * It has to be densified to curve. 2° keeps the longest line under 100 vertices.
+ */
+/**
+ * The antimeridian, in degrees.
+ *
+ * Longitude runs [-180, 180]; meridians are drawn from the first bound up to but not including
+ * the second, because -180 and 180 are the same line and drawing both puts two strokes on one pixel.
+ */
+const MAX_LONGITUDE = 180
+
+const VERTEX_STEP_DEGREES = 2
+
+/**
+ * The latitude the parallels stop at.
+ *
+ * Past ~85° the meridians have converged close enough that more rings read as a smudge at the pole.
+ * Web Mercator's own limit is 85.051129.
+ */
+const MAX_LATITUDE = 85
+
+/**
+ * Build the graticule as one MultiLineString.
+ *
+ * Pure — same step, same geometry — so it is built once at module scope and never rebuilt for a render.
+ */
+export function buildGraticule(stepDegrees: number = DEFAULT_STEP_DEGREES): FeatureCollection<MultiLineString> {
+	const lines: number[][][] = []
+
+	// Meridians: constant longitude, walking latitude pole to pole.
+	for (let lon = -MAX_LONGITUDE; lon < MAX_LONGITUDE; lon += stepDegrees) {
+		const line: number[][] = []
+
+		for (let lat = -MAX_LATITUDE; lat <= MAX_LATITUDE; lat += VERTEX_STEP_DEGREES) {
+			line.push([lon, lat])
+		}
+
+		line.push([lon, MAX_LATITUDE])
+		lines.push(line)
+	}
+
+	// Parallels: constant latitude, walking longitude all the way round.
+	// The equator is included.
+	// The poles are not.
+	for (let lat = -MAX_LATITUDE + stepDegrees; lat < MAX_LATITUDE; lat += stepDegrees) {
+		const line: number[][] = []
+
+		for (let lon = -MAX_LONGITUDE; lon <= MAX_LONGITUDE; lon += VERTEX_STEP_DEGREES) {
+			line.push([lon, lat])
+		}
+
+		lines.push(line)
+	}
+
+	return {
+		type: "FeatureCollection",
+		features: [{ type: "Feature", properties: {}, geometry: { type: "MultiLineString", coordinates: lines } }],
+	}
+}

package/lib/map/map-debug.ts

@@ -5,7 +5,7 @@
  * @file The bare MapLibre control both debug panels portal into.
  *
  *   `DashboardMap`'s inspector and the demo page's `_debug.tsx` panel each need an `IControl` whose
- *   only job is to own a container element for `createPortal`. The class was duplicated in both;
+ *   only job is to own a container element for `createPortal`. The class was duplicated in both.
  *   the position and container class are the only differences, so they are parameters here.
  */