@mailwoman/react 9.4.0 → 10.1.0

package/lib/map/Geocoder.tsx

@@ -2,24 +2,9 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   `<Geocoder>` — the WHOLE geocoder, composed. It is the map analogue of `PipelineExplorer`
- *   and takes the SAME DI shape: an injected {@link GeocoderRuntime} (the host owns ONNX / httpvfs / R2 /
- *   the composed map style) plus a {@link GeocoderPanels} bag (the host's ModelVisualizer / VersionCompare /
- *   About / Permalink). Everything here is composition + a `ClientOnly` boundary:
- *
- *     - the floating {@link GeocoderControls} panel (version / compare / backend / query+autocomplete / result),
- *     - the declarative {@link MapCanvas} with the phase-2 overlays ({@link OverlayLayers}) and the
- *       resolved-place marker/outline/camera ({@link ResolvedPlaceLayers}) driven by the parse state,
- *     - the hooks that wire them: {@link useGeocode} (parse + viewport bias + map place),
- *       {@link usePlaceAutocomplete}, {@link useCompareState}.
- *
- *   Because it pulls {@link MapCanvas} (→ `react-map-gl` → `maplibre-gl`, WebGL + DOM at import), it lives on
- *   the `@mailwoman/react/map` subpath ONLY — never the package root. The whole thing renders in Storybook
- *   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"
@@ -31,45 +16,80 @@ import { usePlaceAutocomplete } from "#map/usePlaceAutocomplete"
 import { ClientOnly } from "../common/ClientOnly.tsx"
 import type { Preset } from "../common/PresetChips.tsx"
 import { GeocoderControls } from "./GeocoderControls.tsx"
+import { GraticuleLayer } from "./GraticuleLayer.tsx"
 import { MapCanvas } from "./MapCanvas.tsx"
 import { OverlayLayers } from "./OverlayLayers.tsx"
 import { ResolvedPlaceLayers } from "./ResolvedPlaceLayers.tsx"
 
+/**
+ * Props for {@linkcode Geocoder}.
+ */
 export interface GeocoderProps {
 	/**
-	 * The injected geocoder runtime (map style + overlays + parse + version/backend).
+	 * The geocoder runtime supplies the map style and overlays.
+	 *
+	 * It also supplies the parser and version and backend controls.
 	 */
 	runtime: GeocoderRuntime
 	/**
-	 * Host-injected panels (about, release blurb, compare, permalink, debug drawer, map controls, …).
+	 * Panels supplied by the host.
 	 */
 	panels?: GeocoderPanels
 	/**
-	 * Address to pre-fill.
+	 * The address that pre-fills the search field.
+	 * It is not run automatically.
 	 */
 	defaultAddress?: string
 	/**
-	 * Example chips. @default the empty set (host supplies its own).
+	 * A query to run once when the runtime is ready, such as a permalink's `?q=` value.
+	 *
+	 * Unlike {@link GeocoderProps.defaultAddress}, this query is submitted,
+	 * so a shared link reproduces its result.
+	 */
+	initialQuery?: string | null
+	/**
+	 * The example chips.
+	 *
+	 * @default []
 	 */
 	presets?: ReadonlyArray<Preset>
 	/**
-	 * 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
+	 * Whether the developer panel starts open.
+	 *
+	 * @default false
+	 */
+	developer?: boolean
+	/**
+	 * Called with each user-submitted query.
+	 *
+	 * The host decides how to write the query to its URL.
+	 * This package never touches `location`.
+	 */
+	onSubmitQuery?: (query: string) => void
+	/**
+	 * The minimum map zoom at which the viewport is sent as a location bias.
+	 *
+	 * @default 4
 	 */
 	minBiasZoom?: number
 	/**
-	 * Fly/fit the map to the resolved place on each result (via {@link ResolvedPlaceLayers}). @default true. Set false
-	 * for a host that drives the camera itself (a controlled `<MapCanvas viewState>`), or to keep a headless test
-	 * deterministic — the marker + outline still render, only the animated camera move is skipped.
+	 * Whether the map moves to each resolved place.
+	 *
+	 * Set it to false when the host controls the camera or a test needs a fixed view.
+	 * The marker and outline render either way.
+	 *
+	 * @default true
 	 */
 	applyResultCamera?: boolean
 }
 
 interface GeocoderInnerProps extends Required<
-	Pick<GeocoderProps, "runtime" | "defaultAddress" | "minBiasZoom" | "applyResultCamera">
+	Pick<GeocoderProps, "runtime" | "defaultAddress" | "minBiasZoom" | "applyResultCamera" | "developer">
 > {
 	panels: GeocoderPanels
 	presets: ReadonlyArray<Preset>
+	initialQuery: string | null
+	onSubmitQuery?: (query: string) => void
 }
 
 function GeocoderInner({
@@ -79,42 +99,44 @@ function GeocoderInner({
 	presets,
 	minBiasZoom,
 	applyResultCamera,
+	developer,
+	initialQuery,
+	onSubmitQuery,
 }: GeocoderInnerProps): ReactNode {
 	const mapRef = useRef<MapRef>(null)
+	// The controls render outside `<MapCanvas>` and cannot call `useMap()`.
+	// The map is kept in state so they re-render when it loads.
+	const [map, setMap] = useState<ReturnType<MapRef["getMap"]> | null>(null)
 
-	// 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"]> }
+	// The graticule is inserted before the first non-background layer, so it draws under the data layers.
+	const [baseLayerID, setBaseLayerID] = useState<string | undefined>(undefined)
 
-		const timer = setInterval(() => {
-			const map = mapRef.current?.getMap()
+	const onMapLoad = useCallback((event: { target: ReturnType<MapRef["getMap"]> }) => {
+		// Browser tests read the map from this global.
+		;(globalThis as { __mailwomanMapCanvas?: ReturnType<MapRef["getMap"]> }).__mailwomanMapCanvas = event.target
+		setMap(event.target)
 
-			if (map) {
-				host.__mailwomanMapCanvas = map
-				clearInterval(timer)
-			}
-		}, 250)
+		const layers = event.target.getStyle()?.layers ?? []
 
-		return () => {
-			clearInterval(timer)
-			delete host.__mailwomanMapCanvas
-		}
+		setBaseLayerID(layers.find((layer) => layer.type !== "background")?.id)
 	}, [])
 
-	// 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.
+	useEffect(
+		() => () => {
+			setMap(null)
+			delete (globalThis as { __mailwomanMapCanvas?: ReturnType<MapRef["getMap"]> }).__mailwomanMapCanvas
+		},
+		[]
+	)
+
 	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])
@@ -152,10 +174,11 @@ function GeocoderInner({
 						zoom: runtime.initialZoom ?? 3,
 					}}
 					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 }}
+					// The attribution is compact.
+					// The MapLibre logo is hidden.
+					mapProps={{ attributionControl: { compact: true }, maplibreLogo: false, onLoad: onMapLoad }}
 				>
+					<GraticuleLayer beforeID={baseLayerID} />
 					<OverlayLayers overlays={runtime.overlays} />
 					<ResolvedPlaceLayers spec={spec} applyCamera={applyResultCamera} />
 					{panels.mapControls}
@@ -170,23 +193,28 @@ function GeocoderInner({
 				panels={panels}
 				presets={presets}
 				placeholder={defaultAddress}
+				initialQuery={initialQuery}
+				map={map}
+				onSubmitQuery={onSubmitQuery}
 				onSelectVersion={onSelectVersion}
 				onForceWASMChange={onForceWASMChange}
+				developer={developer}
 			/>
-
 			{panels.debugDrawer ? panels.debugDrawer({ result: geocode.result }) : null}
 		</div>
 	)
 }
 
-/**
- * Stable empty defaults — a fresh `{}`/`[]` per render would churn every downstream memo dep.
- */
+// These defaults are module constants so each render sees the same reference and memo dependencies stay stable.
 const NO_PANELS: GeocoderPanels = {}
 const NO_PRESETS: ReadonlyArray<Preset> = []
 
 /**
- * The composed geocoder, behind a `ClientOnly` SSR boundary (the map is intrinsically a client component).
+ * Renders the map and search controls as one geocoder.
+ * It also renders host panels.
+ *
+ * It renders only on the client because MapLibre needs browser APIs.
+ * Import it from `@mailwoman/react/map`.
  */
 export function Geocoder({
 	runtime,
@@ -195,6 +223,9 @@ export function Geocoder({
 	presets = NO_PRESETS,
 	minBiasZoom = 4,
 	applyResultCamera = true,
+	developer = false,
+	initialQuery = null,
+	onSubmitQuery,
 }: GeocoderProps): ReactNode {
 	return (
 		<ClientOnly
@@ -212,6 +243,9 @@ export function Geocoder({
 					presets={presets}
 					minBiasZoom={minBiasZoom}
 					applyResultCamera={applyResultCamera}
+					developer={developer}
+					initialQuery={initialQuery}
+					onSubmitQuery={onSubmitQuery}
 				/>
 			)}
 		</ClientOnly>