@mailwoman/react 9.4.0 → 10.0.0

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/index.ts

@@ -15,6 +15,25 @@
 export { MapCanvas } from "./MapCanvas.tsx"
 export type { MapCanvasExtraProps, MapCanvasProps, MapCanvasStyle } from "./MapCanvas.tsx"
 
+// ── Map chrome (node-safe presentation; the host supplies the input and reads its own map) ──
+export { MapChipRow } from "./MapChipRow.tsx"
+export type { MapChip, MapChipRowProps } from "./MapChipRow.tsx"
+export { MapCompass } from "./MapCompass.tsx"
+export type { MapCompassProps } from "./MapCompass.tsx"
+export { useMapBearing } from "./useMapBearing.ts"
+export type { UseMapBearing } from "./useMapBearing.ts"
+export { useMapLabelPick } from "./useMapLabelPick.ts"
+export { MapControlButton, MapControlGroup, MapControlStack } from "./MapControlStack.tsx"
+export type { MapControlButtonProps, MapControlGroupProps, MapControlStackProps } from "./MapControlStack.tsx"
+export { MapFooter } from "./MapFooter.tsx"
+export type { MapFooterProps } from "./MapFooter.tsx"
+export { MapProgressBar } from "./MapProgressBar.tsx"
+export type { MapProgressBarProps } from "./MapProgressBar.tsx"
+export { MapSheet } from "./MapSheet.tsx"
+export type { MapSheetProps } from "./MapSheet.tsx"
+export { MapSearchBar } from "./MapSearchBar.tsx"
+export type { MapSearchBarProps } from "./MapSearchBar.tsx"
+
 export type {
 	CompareContext,
 	GeocoderPanels,

package/lib/map/types.ts

@@ -17,7 +17,7 @@
 
 import type { ParseResult, ResolvedPlaceView } from "@mailwoman/core/pipeline/client-result"
 import type { ReactNode } from "react"
-import type { LayerSpecification, SourceSpecification } from "react-map-gl/maplibre"
+import type { LayerSpecification, MapInstance, SourceSpecification } from "react-map-gl/maplibre"
 
 import type { LngLat, ResolvedMapPlace } from "#map/place-render"
 import type { PipelineRuntime } from "#pipeline/types"
@@ -263,11 +263,17 @@ export interface GeocoderPanels {
 	 */
 	extras?: (result: ParseResult) => ReactNode
 	/**
-	 * Rendered just above the result block (present or empty). The opt-in display toggles live here — calibrated
-	 * confidence + dev-mode — because the host owns both the toggle state AND the {@link result} / {@link debugDrawer}
-	 * renderers those toggles drive.
+	 * Rendered just above the result block (present or empty), for content that reads on THIS answer.
+	 *
+	 * A control that reads on the model rather than on an address belongs in {@link developerExtras}: above the result it
+	 * is the first thing a visitor meets, and on a phone it pushes the answer below the fold.
 	 */
 	aboveResult?: (context: { result: ParseResult | null }) => ReactNode
+	/**
+	 * Host controls appended to the Developer sheet — the opt-in display toggles, whose state and the renderers they
+	 * drive both belong to the host.
+	 */
+	developerExtras?: ReactNode
 	/**
 	 * Replace the package's default {@link ResultPanel} entirely. When provided, the host renders its own result block
 	 * (span highlight, timing, hierarchy, precision detail, calibrated confidences) from the {@link ResultContext}. Absent
@@ -293,6 +299,14 @@ export interface GeocoderPanels {
 	 * Extra map controls mounted as `<MapCanvas>` children (host's DebugControl / LayerToggle via `useControl`).
 	 */
 	mapControls?: ReactNode
+	/**
+	 * A layer control, rendered in the chrome's top column under the example chips rather than in a MapLibre corner.
+	 *
+	 * A render-prop taking the live map handle, because a layer control reads `getStyle().layers` and writes
+	 * `setLayoutProperty` — it cannot be a static node. The handle is `null` until the map instantiates, so the host
+	 * returns `null` for that first frame rather than rendering an empty control.
+	 */
+	layers?: (context: { map: MapInstance | null }) => ReactNode
 	/**
 	 * A permalink control for the current address (host's PermalinkButton).
 	 */

package/lib/map/useMapBearing.ts

@@ -0,0 +1,56 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `useMapBearing` — the map's rotation as React state, for a compass that appears off north and fades back.
+ *
+ *   The map is an external store, so it is read through `useSyncExternalStore` rather than mirrored into state by an
+ *   effect: the bearing is a number, which makes a stable snapshot, and React tears nothing during a concurrent
+ *   render.
+ *
+ *   It listens on `rotate` rather than `rotateend`, because the needle has to track the gesture rather than snap once
+ *   the gesture is over. `move` is subscribed too: a `flyTo` or an `easeTo` carrying a bearing rotates the map without
+ *   firing a rotate event, and a compass that misses those stays pointing north over a turned map.
+ */
+
+import { useCallback, useSyncExternalStore } from "react"
+import type { MapInstance } from "react-map-gl/maplibre"
+
+export interface UseMapBearing {
+	/**
+	 * Degrees off north, as MapLibre reports it. Zero while there is no map.
+	 */
+	bearing: number
+	/**
+	 * Rotate the map back to north. A no-op while there is no map.
+	 */
+	resetNorth: () => void
+}
+
+export function useMapBearing(map: MapInstance | null): UseMapBearing {
+	const subscribe = useCallback(
+		(onChange: () => void) => {
+			if (!map) return () => undefined
+
+			map.on("rotate", onChange)
+			map.on("move", onChange)
+
+			return () => {
+				map.off("rotate", onChange)
+				map.off("move", onChange)
+			}
+		},
+		[map]
+	)
+
+	// The server snapshot is the same reading: there is no map during a server render, and north is what a compass
+	// shows when it has nothing to report.
+	const readBearing = useCallback(() => map?.getBearing() ?? 0, [map])
+
+	const bearing = useSyncExternalStore(subscribe, readBearing, () => 0)
+
+	const resetNorth = useCallback(() => map?.easeTo({ bearing: 0, pitch: 0 }), [map])
+
+	return { bearing, resetNorth }
+}

package/lib/map/useMapLabelPick.ts

@@ -0,0 +1,123 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `useMapLabelPick` — clicking a place label on the map searches for it, the way the reference map apps behave.
+ *
+ *   A label on a map looks like a link, so a visitor clicks it. Without this the click reaches the map's pan handler
+ *   and nothing happens, which reads as the label being decoration.
+ *
+ *   It reads the label's OWN name from the rendered feature rather than reverse-geocoding the click point: the name
+ *   is what the visitor pointed at, and a lookup by coordinate answers whatever is nearest instead, which on a dense
+ *   basemap is regularly not the thing under the cursor.
+ *
+ *   THE QUERY IS SCOPED, AND THE HOVER QUERY IS THROTTLED. `queryRenderedFeatures` with no `layers` walks the whole
+ *   style: measured at 64.3 ms per call returning 4,819 features over the 79-layer basemap at zoom 14 in Manhattan,
+ *   against 4.9 ms and 44 features scoped to that style's 11 label layers. At one call per pointer move the unscoped
+ *   form is the map's whole frame budget, so the layer list is resolved once per style and the hover query runs at
+ *   most once per animation frame. The click query is not throttled — there is one of those per click.
+ */
+
+import { useEffect, useEffectEvent } from "react"
+import type { MapInstance, MapLayerMouseEvent } from "react-map-gl/maplibre"
+
+/**
+ * The layers whose features carry a place name. Protomaps names its label layers `<theme>_label` and its settlement
+ * layers `places_*`; anything else in the style is geometry, not a label a visitor can read and point at.
+ */
+const LABEL_LAYER = /_label|^places_/
+
+/**
+ * Properties a label carries its text under, in the order they are trusted. `name` is protomaps' own; the localized
+ * variants appear on styles built for a specific script.
+ */
+const NAME_KEYS = ["name", "name:en", "name_en"] as const
+
+/**
+ * The style's label layers, by id.
+ *
+ * A style with none answers an EMPTY ARRAY, and the caller must treat that as "no labels to pick" rather than passing
+ * it to `queryRenderedFeatures` — an empty `layers` option is not the same as an absent one there, and the difference
+ * between "this style has no labels" and "query everything" is the 64 ms this hook exists to avoid.
+ */
+function labelLayerIDs(map: MapInstance): string[] {
+	const layers = map.getStyle()?.layers ?? []
+
+	return layers.map((layer) => layer.id).filter((id) => LABEL_LAYER.test(id))
+}
+
+function labelNameAt(map: MapInstance, point: MapLayerMouseEvent["point"], layers: string[]): string | null {
+	if (!layers.length) return null
+
+	// `queryRenderedFeatures` answers in paint order with the topmost first, which is the label drawn over the others
+	// and therefore the one a click landed on.
+	for (const feature of map.queryRenderedFeatures(point, { layers })) {
+		for (const key of NAME_KEYS) {
+			const value = feature.properties?.[key]
+
+			if (typeof value === "string" && value.trim()) return value
+		}
+	}
+
+	return null
+}
+
+export function useMapLabelPick(map: MapInstance | null, onPick: (name: string) => void): void {
+	// The subscription depends on the MAP alone. `useGeocode` returns a fresh object every render, so a callback built
+	// from it is new every render too — with `onPick` in the dependency list these map listeners were torn down and
+	// re-added on every keystroke in the search field. `useEffectEvent` is the shape for exactly this: an event
+	// handler that always sees the latest props without being a reactive dependency.
+	const pick = useEffectEvent((name: string) => onPick(name))
+
+	useEffect(() => {
+		if (!map) return
+
+		// Recomputed when the style swaps (a theme change, a version switch) and not once per pointer move.
+		let layers = labelLayerIDs(map)
+
+		const readLayers = () => {
+			layers = labelLayerIDs(map)
+		}
+
+		const onClick = (event: MapLayerMouseEvent) => {
+			const name = labelNameAt(map, event.point, layers)
+
+			if (name) {
+				pick(name)
+			}
+		}
+
+		let frame = 0
+
+		const onMove = (event: MapLayerMouseEvent) => {
+			if (frame) return
+
+			frame = requestAnimationFrame(() => {
+				frame = 0
+
+				const canvas = map.getCanvas()
+
+				// The drag cursor belongs to the pan gesture; overriding it mid-drag would fight the map for the pointer.
+				if (canvas.style.cursor === "grabbing") return
+
+				canvas.style.cursor = labelNameAt(map, event.point, layers) ? "pointer" : ""
+			})
+		}
+
+		map.on("styledata", readLayers)
+		map.on("click", onClick)
+		map.on("mousemove", onMove)
+
+		return () => {
+			if (frame) {
+				cancelAnimationFrame(frame)
+			}
+
+			map.off("styledata", readLayers)
+			map.off("click", onClick)
+			map.off("mousemove", onMove)
+			map.getCanvas().style.cursor = ""
+		}
+	}, [map])
+}

package/lib/pipeline/index.ts

@@ -0,0 +1,36 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Pipeline explorer components, visualizers, hooks, and contracts.
+ */
+
+export { About } from "../common/About.tsx"
+export { FailureDiagnostic } from "./FailureDiagnostic.tsx"
+export type { FailureDiagnosticProps } from "./FailureDiagnostic.tsx"
+export { SpanHighlight } from "./SpanHighlight.tsx"
+export type { SpanHighlightProps } from "./SpanHighlight.tsx"
+export { TimingPanel } from "./TimingPanel.tsx"
+export type { TimingPanelProps } from "./TimingPanel.tsx"
+export { TreeView } from "./TreeView.tsx"
+export type { TreeViewProps } from "./TreeView.tsx"
+
+export { CandidatePicker } from "./CandidatePicker.tsx"
+export type { CandidatePickerProps } from "./CandidatePicker.tsx"
+export { ComponentTable } from "./ComponentTable.tsx"
+export type { ComponentTableProps } from "./ComponentTable.tsx"
+export { ConfidenceCell } from "./ConfidenceCell.tsx"
+export type { ConfidenceCellProps } from "./ConfidenceCell.tsx"
+export { buildParsePayload } from "#pipeline/copy"
+export { PIPELINE_DEFAULT_ADDRESS, PIPELINE_PRESETS } from "#pipeline/presets"
+export { PipelineExplorer } from "./PipelineExplorer.tsx"
+export type { PipelineExplorerProps } from "./PipelineExplorer.tsx"
+export { QueryForm } from "./QueryForm.tsx"
+export type { QueryFormProps } from "./QueryForm.tsx"
+export { ResolvedPlace } from "./ResolvedPlace.tsx"
+export type { ResolvedPlaceProps } from "./ResolvedPlace.tsx"
+
+export type { PipelineLoadingState, PipelinePanels, PipelineRuntime } from "#pipeline/types"
+
+export { useParsePipeline } from "#pipeline/useParsePipeline"
+export type { UseParsePipeline, UseParsePipelineOptions } from "#pipeline/useParsePipeline"

package/lib/pipeline/useParsePipeline.ts

@@ -36,9 +36,12 @@ export interface UseParsePipeline {
 	 */
 	selectedCandidate: ResolvedPlaceView | null
 	/**
-	 * Run a parse for the current text. Safe to bind to a form's `onSubmit`.
+	 * Parse and resolve the current text. Safe to bind to a form's `onSubmit`.
+	 *
+	 * Pass `query` to submit a value the field has not re-rendered with yet — a preset press sets the text and submits in
+	 * one handler, and that state update is not visible to this call.
 	 */
-	submit: () => Promise<void>
+	submit: (query?: string) => Promise<void>
 	/**
 	 * Clear the result (used when a preset replaces the input).
 	 */
@@ -53,24 +56,32 @@ export function useParsePipeline({ runtime, defaultText }: UseParsePipelineOptio
 	const [selectedCandidateIndex, setSelectedCandidateIndex] = useState(0)
 	const [parseError, setParseError] = useState<string | null>(null)
 
-	const submit = useCallback(async () => {
-		if (!runtime.ready || busy) return
+	// `query` exists because `setText` does not reach this closure before the call after it runs. A preset that called
+	// `setText(value)` then `submit()` parsed the PREVIOUS text — the field showed the preset and the map answered the
+	// address before it. A caller that already knows the query passes it; the field's own submit passes nothing.
+	const submit = useCallback(
+		async (query?: string) => {
+			if (!runtime.ready || busy) return
 
-		setBusy(true)
-		setParseStage(0)
-		setParseError(null)
+			const input = query ?? text
 
-		try {
-			const parsed = await runtime.runParse(text, { onStage: setParseStage })
-			setSelectedCandidateIndex(0)
-			setResult(parsed)
-		} catch (error) {
-			setParseError(error instanceof Error ? error.message : String(error))
-		} finally {
-			setBusy(false)
-			setParseStage(-1)
-		}
-	}, [runtime, text, busy])
+			setBusy(true)
+			setParseStage(0)
+			setParseError(null)
+
+			try {
+				const parsed = await runtime.runParse(input, { onStage: setParseStage })
+				setSelectedCandidateIndex(0)
+				setResult(parsed)
+			} catch (error) {
+				setParseError(error instanceof Error ? error.message : String(error))
+			} finally {
+				setBusy(false)
+				setParseStage(-1)
+			}
+		},
+		[runtime, text, busy]
+	)
 
 	const reset = useCallback(() => setResult(null), [])