@mailwoman/react 9.4.0 → 10.0.0

package/lib/common/About.tsx

@@ -3,87 +3,103 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `About` — the collapsible explainer for the browser geocoder: the neural model, the confidence colours, the
- *   gazetteer resolver, the byte-range database and the FST prior. Prose about the product a host places above or
- *   beside the geocoder; it renders nothing live.
+ *   `About` — the explainer for the browser geocoder: the neural model, the confidence colours, the gazetteer
+ *   resolver, the byte-range database and the FST prior. Prose about the product a host places above or beside the
+ *   geocoder; it renders nothing live.
  */
 
 import type { ReactNode } from "react"
 
-export function About(): ReactNode {
+export interface AboutProps {
+	/**
+	 * Wrap the prose in its own `<details>` disclosure. Set false where the host is already the disclosure — inside a
+	 * sheet opened by an About button, a summary repeating that button's words is one control too many.
+	 *
+	 * @default true
+	 */
+	collapsible?: boolean
+}
+
+export function About({ collapsible = true }: AboutProps = {}): ReactNode {
+	const body = (
+		<div className="mw-about__body">
+			<section className="mw-about__section">
+				<h3 className="mw-about__heading">Neural model</h3>
+				<p>
+					A ~29M-parameter BERT-style encoder classifies each token into one of 33 BIO labels covering 16 address
+					components (street, house number, unit, locality, region, postcode, venue, country, intersection, etc.). It
+					runs entirely in your browser via <strong>onnxruntime-web</strong> (WebGPU with WASM SIMD fallback). The model
+					ships as a 37.6 MB int8-quantized ONNX bundle; fp32 weights are also available for higher accuracy.
+				</p>
+			</section>
+
+			<section className="mw-about__section">
+				<h3 className="mw-about__heading">Confidence colors</h3>
+				<p>
+					Every classified span carries a confidence score between 0 and 1. The colors in the results table give you a
+					quick visual read:
+				</p>
+				<ul className="mw-about__legend">
+					<li className="mw-about__item">
+						<span className="mw-about__swatch mw-about__swatch--high" />
+						<strong>Green</strong> (≥ 0.8) — high confidence. The model is nearly certain.
+					</li>
+					<li className="mw-about__item">
+						<span className="mw-about__swatch mw-about__swatch--mid" />
+						<strong>Amber</strong> (0.5–0.8) — moderate confidence. Worth verifying.
+					</li>
+					<li className="mw-about__item">
+						<span className="mw-about__swatch mw-about__swatch--low" />
+						<strong>Red</strong> (&lt; 0.5) — low confidence. The model is unsure — likely wrong.
+					</li>
+				</ul>
+				<p>
+					These are raw model scores. For calibrated probabilities, the library ships a per-locale isotonic calibrator (
+					<code>calibration.json</code>) that maps the raw scores to well-calibrated probability estimates.
+				</p>
+			</section>
+
+			<section className="mw-about__section">
+				<h3 className="mw-about__heading">WOF resolver</h3>
+				<p>
+					After classification, the resolver queries a <strong>Who&apos;s On First</strong> (WOF) SQLite gazetteer to
+					match the parsed components — locality, region, and postcode — against real-world places with coordinates. The
+					cascade tries postcode first (most precise), then locality, then the raw input text. The result is a sorted
+					list of candidate places with WOF IDs, placetypes, lat/lon, and bounding boxes.
+				</p>
+			</section>
+
+			<section className="mw-about__section">
+				<h3 className="mw-about__heading">Byte-range gazetteer</h3>
+				<p>
+					The gazetteer is a multi-gigabyte SQLite file served from a public bucket. It loads via{" "}
+					<strong>sql.js-httpvfs</strong>, which range-requests only the pages a lookup touches, so your browser fetches
+					a few hundred kilobytes per session instead of the whole file.
+				</p>
+			</section>
+
+			<section className="mw-about__section">
+				<h3 className="mw-about__heading">FST prior</h3>
+				<p>
+					A <strong>finite-state transducer</strong> (FST) built from ~94K US place names runs before the neural
+					classifier. It pre-annotates known locality, region, and postcode spans in the input — places like
+					&quot;Springfield&quot; or &quot;Cook County&quot; that the FST can match exactly. These &quot;FST prior&quot;
+					hits feed the classifier as strong hints, improving locality and region recall on addresses where the neural
+					model alone might miss them. The FST is active whenever the selected release includes it.
+				</p>
+			</section>
+		</div>
+	)
+
+	if (!collapsible) return body
+
 	return (
 		<details className="mw-about">
 			<summary className="mw-about__summary">
 				<span className="mw-about__icon">ℹ️</span>
 				About this geocoder
 			</summary>
-			<div className="mw-about__body">
-				<section className="mw-about__section">
-					<h3 className="mw-about__heading">Neural model</h3>
-					<p>
-						A ~29M-parameter BERT-style encoder classifies each token into one of 33 BIO labels covering 16 address
-						components (street, house number, unit, locality, region, postcode, venue, country, intersection, etc.). It
-						runs entirely in your browser via <strong>onnxruntime-web</strong> (WebGPU with WASM SIMD fallback). The
-						model ships as a 37.6 MB int8-quantized ONNX bundle; fp32 weights are also available for higher accuracy.
-					</p>
-				</section>
-
-				<section className="mw-about__section">
-					<h3 className="mw-about__heading">Confidence colors</h3>
-					<p>
-						Every classified span carries a confidence score between 0 and 1. The colors in the results table give you a
-						quick visual read:
-					</p>
-					<ul className="mw-about__legend">
-						<li className="mw-about__item">
-							<span className="mw-about__swatch mw-about__swatch--high" />
-							<strong>Green</strong> (≥ 0.8) — high confidence. The model is nearly certain.
-						</li>
-						<li className="mw-about__item">
-							<span className="mw-about__swatch mw-about__swatch--mid" />
-							<strong>Amber</strong> (0.5–0.8) — moderate confidence. Worth verifying.
-						</li>
-						<li className="mw-about__item">
-							<span className="mw-about__swatch mw-about__swatch--low" />
-							<strong>Red</strong> (&lt; 0.5) — low confidence. The model is unsure — likely wrong.
-						</li>
-					</ul>
-					<p>
-						These are raw model scores. For calibrated probabilities, the library ships a per-locale isotonic calibrator
-						(<code>calibration.json</code>) that maps the raw scores to well-calibrated probability estimates.
-					</p>
-				</section>
-
-				<section className="mw-about__section">
-					<h3 className="mw-about__heading">WOF resolver</h3>
-					<p>
-						After classification, the resolver queries a <strong>Who&apos;s On First</strong> (WOF) SQLite gazetteer to
-						match the parsed components — locality, region, and postcode — against real-world places with coordinates.
-						The cascade tries postcode first (most precise), then locality, then the raw input text. The result is a
-						sorted list of candidate places with WOF IDs, placetypes, lat/lon, and bounding boxes.
-					</p>
-				</section>
-
-				<section className="mw-about__section">
-					<h3 className="mw-about__heading">Byte-range gazetteer</h3>
-					<p>
-						The gazetteer is a multi-gigabyte SQLite file served from a public bucket. It loads via{" "}
-						<strong>sql.js-httpvfs</strong>, which range-requests only the pages a lookup touches, so your browser
-						fetches a few hundred kilobytes per session instead of the whole file.
-					</p>
-				</section>
-
-				<section className="mw-about__section">
-					<h3 className="mw-about__heading">FST prior</h3>
-					<p>
-						A <strong>finite-state transducer</strong> (FST) built from ~94K US place names runs before the neural
-						classifier. It pre-annotates known locality, region, and postcode spans in the input — places like
-						&quot;Springfield&quot; or &quot;Cook County&quot; that the FST can match exactly. These &quot;FST
-						prior&quot; hits feed the classifier as strong hints, improving locality and region recall on addresses
-						where the neural model alone might miss them. The FST is active whenever the selected release includes it.
-					</p>
-				</section>
-			</div>
+			{body}
 		</details>
 	)
 }

package/lib/common/index.ts

@@ -0,0 +1,22 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Common React primitives.
+ */
+
+export { ClientOnly } from "./ClientOnly.tsx"
+export type { ClientOnlyProps } from "./ClientOnly.tsx"
+export { CopyButton } from "./CopyButton.tsx"
+export type { CopyButtonProps } from "./CopyButton.tsx"
+export { cx } from "#common/cx"
+export type { ClassValue } from "#common/cx"
+export { KindBadge } from "./KindBadge.tsx"
+export type { KindBadgeProps } from "./KindBadge.tsx"
+export { LoadingIndicator } from "./LoadingIndicator.tsx"
+export type { LoadingIndicatorProps, LoadingMode } from "./LoadingIndicator.tsx"
+export { PresetChips } from "./PresetChips.tsx"
+export type { Preset, PresetChipsProps } from "./PresetChips.tsx"
+export { useClipboard } from "#common/useClipboard"
+export type { UseClipboard } from "#common/useClipboard"
+export { useDebouncedValue } from "#common/useDebouncedValue"

package/lib/index.ts

@@ -16,106 +16,11 @@
  *   aware) — no CSS is imported by the component modules, so the bare package import is node-safe.
  */
 
-// ── Common primitives ──────────────────────────────────────────────────────
-export { ClientOnly } from "./common/ClientOnly.tsx"
-export type { ClientOnlyProps } from "./common/ClientOnly.tsx"
-export { CopyButton } from "./common/CopyButton.tsx"
-export type { CopyButtonProps } from "./common/CopyButton.tsx"
-export { cx } from "#common/cx"
-export type { ClassValue } from "#common/cx"
-export { KindBadge } from "./common/KindBadge.tsx"
-export type { KindBadgeProps } from "./common/KindBadge.tsx"
-export { LoadingIndicator } from "./common/LoadingIndicator.tsx"
-export type { LoadingIndicatorProps, LoadingMode } from "./common/LoadingIndicator.tsx"
-export { PresetChips } from "./common/PresetChips.tsx"
-export type { Preset, PresetChipsProps } from "./common/PresetChips.tsx"
-export { useClipboard } from "#common/useClipboard"
-export type { UseClipboard } from "#common/useClipboard"
-export { useDebouncedValue } from "#common/useDebouncedValue"
+export * from "#common/index"
+export * from "#poi/index"
+export * from "#pipeline/index"
+export * from "#runtime/index"
 
-// ── POI explorer ───────────────────────────────────────────────────────────
-export { AbstainPanel } from "./poi/AbstainPanel.tsx"
-export type { AbstainPanelProps } from "./poi/AbstainPanel.tsx"
-export { LiveResultsBlock } from "./poi/LiveResultsBlock.tsx"
-export type { LiveResultsBlockProps } from "./poi/LiveResultsBlock.tsx"
-export { OverpassBlock } from "./poi/OverpassBlock.tsx"
-export type { OverpassBlockProps } from "./poi/OverpassBlock.tsx"
-export { POIExplorer } from "./poi/POIExplorer.tsx"
-export type { POIExplorerProps } from "./poi/POIExplorer.tsx"
-export { QueryInput } from "./poi/QueryInput.tsx"
-export type { QueryInputProps } from "./poi/QueryInput.tsx"
-export { formatDistance, loadPOIRuntime, POI_DEFAULT_TEXT, POI_PRESETS } from "#poi/runtime"
-export { SubjectPanel } from "./poi/SubjectPanel.tsx"
-export type { SubjectPanelProps } from "./poi/SubjectPanel.tsx"
-
-export type {
-	CategoryRecord,
-	LiveSearchState,
-	LoadPOIRuntime,
-	POIBrandSubject,
-	POICategorySubject,
-	POIExplorerResult,
-	POILiveSearch,
-	POILiveSearchResult,
-	POIRuntime,
-	POISearchHit,
-	POISubject,
-	POISubjectBase,
-	TaxonomyLookup,
-} from "#poi/types"
-
-export { usePOISearch } from "#poi/usePOISearch"
-export type { UsePOISearch, UsePOISearchOptions } from "#poi/usePOISearch"
-
-// ── Result visualizers ─────────────────────────────────────────────────────
-
-export { About } from "./common/About.tsx"
-export { FailureDiagnostic } from "./pipeline/FailureDiagnostic.tsx"
-export type { FailureDiagnosticProps } from "./pipeline/FailureDiagnostic.tsx"
-export { SpanHighlight } from "./pipeline/SpanHighlight.tsx"
-export type { SpanHighlightProps } from "./pipeline/SpanHighlight.tsx"
-export { TimingPanel } from "./pipeline/TimingPanel.tsx"
-export type { TimingPanelProps } from "./pipeline/TimingPanel.tsx"
-export { TreeView } from "./pipeline/TreeView.tsx"
-export type { TreeViewProps } from "./pipeline/TreeView.tsx"
-
-// ── Pipeline explorer ──────────────────────────────────────────────────────
-export { CandidatePicker } from "./pipeline/CandidatePicker.tsx"
-export type { CandidatePickerProps } from "./pipeline/CandidatePicker.tsx"
-export { ComponentTable } from "./pipeline/ComponentTable.tsx"
-export type { ComponentTableProps } from "./pipeline/ComponentTable.tsx"
-export { ConfidenceCell } from "./pipeline/ConfidenceCell.tsx"
-export type { ConfidenceCellProps } from "./pipeline/ConfidenceCell.tsx"
-export { buildParsePayload } from "#pipeline/copy"
-export { PIPELINE_DEFAULT_ADDRESS, PIPELINE_PRESETS } from "#pipeline/presets"
-export { PipelineExplorer } from "./pipeline/PipelineExplorer.tsx"
-export type { PipelineExplorerProps } from "./pipeline/PipelineExplorer.tsx"
-export { QueryForm } from "./pipeline/QueryForm.tsx"
-export type { QueryFormProps } from "./pipeline/QueryForm.tsx"
-export { ResolvedPlace } from "./pipeline/ResolvedPlace.tsx"
-export type { ResolvedPlaceProps } from "./pipeline/ResolvedPlace.tsx"
-
-export type { PipelineLoadingState, PipelinePanels, PipelineRuntime } from "#pipeline/types"
-
-export { useParsePipeline } from "#pipeline/useParsePipeline"
-export type { UseParsePipeline, UseParsePipelineOptions } from "#pipeline/useParsePipeline"
-
-// ── Release runtime (shared load orchestration; node-safe — no onnx/httpvfs/maplibre) ──
-export { useReleaseRuntime } from "#runtime/useReleaseRuntime"
-
-export type {
-	AssetsLoadContext,
-	ReleaseBase,
-	ReleaseLoaderState,
-	ReleaseManifest,
-	ReleaseRuntimeConfig,
-} from "#runtime/useReleaseRuntime"
-
-// ── Map (types only from root) ──────────────────────────────────────────────
-// The map SURFACE lives behind the `@mailwoman/react/map` subpath so `maplibre-gl` / `react-map-gl`
-// (WebGL + DOM at import) never enter the package-root graph — a bare `import("@mailwoman/react")` in node
-// must not pull them. Only the CONTRACT types are re-exported here (fully erased at compile time, so no
-// runtime linkage): the `MapCanvas` component + hooks are import-able solely via `@mailwoman/react/map`.
 export type {
 	GeocoderRuntime,
 	InferenceBackend,

package/lib/map/BackendControl.tsx

@@ -34,13 +34,17 @@ export interface BackendControlProps {
 export function BackendControl({ activeBackend, forceWASM, onForceWASMChange }: BackendControlProps): ReactNode {
 	return (
 		<div className="mw-demo-backend">
+			<span className="mw-map-sheet__label">Inference backend</span>
+
 			{activeBackend ? (
 				<span className="mw-demo-backend__active">
-					Backend: <code>{activeBackend}</code>
+					Running on <code>{activeBackend}</code>
 				</span>
 			) : null}
-			<label className="mw-demo-backend__toggle">
-				<input type="checkbox" checked={forceWASM} onChange={(e) => onForceWASMChange(e.target.checked)} /> Force WASM
+
+			<label className="mw-map-sheet__check mw-demo-backend__toggle">
+				<input type="checkbox" checked={forceWASM} onChange={(event) => onForceWASMChange(event.target.checked)} />
+				Force WASM
 			</label>
 		</div>
 	)

package/lib/map/CompareToggle.tsx

@@ -69,8 +69,9 @@ export function CompareToggle({
 
 	return (
 		<div className="mw-demo-compare">
-			<label className="mw-demo-compare__toggle">
-				<input type="checkbox" checked={compareMode} onChange={(e) => onCompareModeChange(e.target.checked)} /> Compare
+			<label className="mw-map-sheet__check mw-demo-compare__toggle">
+				<input type="checkbox" checked={compareMode} onChange={(event) => onCompareModeChange(event.target.checked)} />
+				Compare two model versions
 			</label>
 			{compareMode ? (
 				<div className="mw-demo-control">

package/lib/map/Geocoder.tsx

@@ -19,7 +19,7 @@
  *   over a fake runtime (offline stub style + canned geocode) with no network, no ONNX, no gazetteer.
  */
 
-import { type ReactNode, useCallback, useEffect, useRef } from "react"
+import { type ReactNode, useCallback, useEffect, useRef, useState } from "react"
 import type { MapRef } from "react-map-gl/maplibre"
 
 import type { GeocoderPanels, GeocoderRuntime, MapBias } from "#map/types"
@@ -52,6 +52,16 @@ export interface GeocoderProps {
 	 * Example chips. @default the empty set (host supplies its own).
 	 */
 	presets?: ReadonlyArray<Preset>
+	/**
+	 * Open the developer disclosure on mount — the model version, the backend readout and compare. Collapsed by default
+	 * so the address field is the first thing a visitor meets. @default false
+	 */
+	developer?: boolean
+	/**
+	 * Fired with the query each time one is submitted. The host writes it into its own URL — this package never touches
+	 * `location`, because which parameter carries a query is the app's decision.
+	 */
+	onSubmitQuery?: (query: string) => void
 	/**
 	 * Only hint the viewport bias once the visitor has zoomed past the global view — a whole-globe center is noise.
 	 * Matches the `map.getZoom() >= 4` threshold. @default 4
@@ -66,10 +76,11 @@ export interface GeocoderProps {
 }
 
 interface GeocoderInnerProps extends Required<
-	Pick<GeocoderProps, "runtime" | "defaultAddress" | "minBiasZoom" | "applyResultCamera">
+	Pick<GeocoderProps, "runtime" | "defaultAddress" | "minBiasZoom" | "applyResultCamera" | "developer">
 > {
 	panels: GeocoderPanels
 	presets: ReadonlyArray<Preset>
+	onSubmitQuery?: (query: string) => void
 }
 
 function GeocoderInner({
@@ -79,42 +90,44 @@ function GeocoderInner({
 	presets,
 	minBiasZoom,
 	applyResultCamera,
+	developer,
+	onSubmitQuery,
 }: GeocoderInnerProps): ReactNode {
 	const mapRef = useRef<MapRef>(null)
-
+	// The chrome sits OUTSIDE `<MapCanvas>`, so it cannot take the handle from `useMap()`. A ref alone does not
+	// re-render the compass or the layer control when the map arrives, so the same poll that publishes the test
+	// handle also puts it in state — one poll, two consumers.
+	const [map, setMap] = useState<ReturnType<MapRef["getMap"]> | null>(null)
+
+	// The map announces itself; nothing polls for it. `onLoad` carries the instance, so the compass and the layer
+	// control render on the frame the map is ready rather than up to an interval later.
+	//
 	// TEST INJECTION POINT: the e2e viewport-bias suite drives the REAL map (pan + zoom past the bias threshold)
-	// before submitting, and a browser test cannot reach a React ref — so the live map handle is
-	// republished on `globalThis.__mailwomanMapCanvas`. The ref fills only after react-map-gl instantiates
-	// the map, hence the short poll; cleared on unmount so a torn-down geocoder never leaves a stale
-	// handle behind.
-	useEffect(() => {
-		const host = globalThis as { __mailwomanMapCanvas?: ReturnType<MapRef["getMap"]> }
-
-		const timer = setInterval(() => {
-			const map = mapRef.current?.getMap()
-
-			if (map) {
-				host.__mailwomanMapCanvas = map
-				clearInterval(timer)
-			}
-		}, 250)
-
-		return () => {
-			clearInterval(timer)
-			delete host.__mailwomanMapCanvas
-		}
+	// before submitting, and a browser test cannot reach a React ref — so the same handle is republished on
+	// `globalThis.__mailwomanMapCanvas`, and cleared on unmount so a torn-down geocoder leaves no stale handle.
+	const onMapLoad = useCallback((event: { target: ReturnType<MapRef["getMap"]> }) => {
+		;(globalThis as { __mailwomanMapCanvas?: ReturnType<MapRef["getMap"]> }).__mailwomanMapCanvas = event.target
+		setMap(event.target)
 	}, [])
 
+	useEffect(
+		() => () => {
+			setMap(null)
+			delete (globalThis as { __mailwomanMapCanvas?: ReturnType<MapRef["getMap"]> }).__mailwomanMapCanvas
+		},
+		[]
+	)
+
 	// Read the viewport bias at submit time — through the map handle, never a threaded state value, so granting/zooming
 	// mid-session doesn't re-create the parse callback. Below the min-bias zoom, a whole-globe center is noise → null.
 	const getBias = useCallback((): MapBias | null => {
-		const map = mapRef.current?.getMap()
+		const live = mapRef.current?.getMap()
 
-		if (!map) return null
-		const zoom = map.getZoom()
+		if (!live) return null
+		const zoom = live.getZoom()
 
 		if (zoom < minBiasZoom) return null
-		const center = map.getCenter()
+		const center = live.getCenter()
 
 		return { center: [center.lng, center.lat], zoom }
 	}, [minBiasZoom])
@@ -154,7 +167,7 @@ function GeocoderInner({
 					style={{ width: "100%", height: "100%" }}
 					// One compact attribution pill (the map's own default is a wide, always-open "MapLibre | © …" bar), no
 					// maplibre wordmark logo.
-					mapProps={{ attributionControl: { compact: true }, maplibreLogo: false }}
+					mapProps={{ attributionControl: { compact: true }, maplibreLogo: false, onLoad: onMapLoad }}
 				>
 					<OverlayLayers overlays={runtime.overlays} />
 					<ResolvedPlaceLayers spec={spec} applyCamera={applyResultCamera} />
@@ -170,8 +183,11 @@ function GeocoderInner({
 				panels={panels}
 				presets={presets}
 				placeholder={defaultAddress}
+				map={map}
+				onSubmitQuery={onSubmitQuery}
 				onSelectVersion={onSelectVersion}
 				onForceWASMChange={onForceWASMChange}
+				developer={developer}
 			/>
 
 			{panels.debugDrawer ? panels.debugDrawer({ result: geocode.result }) : null}
@@ -195,6 +211,8 @@ export function Geocoder({
 	presets = NO_PRESETS,
 	minBiasZoom = 4,
 	applyResultCamera = true,
+	developer = false,
+	onSubmitQuery,
 }: GeocoderProps): ReactNode {
 	return (
 		<ClientOnly
@@ -212,6 +230,8 @@ export function Geocoder({
 					presets={presets}
 					minBiasZoom={minBiasZoom}
 					applyResultCamera={applyResultCamera}
+					developer={developer}
+					onSubmitQuery={onSubmitQuery}
 				/>
 			)}
 		</ClientOnly>