@mailwoman/react 9.0.0 → 9.2.0

package/poi/usePOISearch.ts

@@ -13,7 +13,7 @@ import { matchPOISubject } from "@mailwoman/kind-classifier"
 import { emitOverpassQL } from "@mailwoman/poi-taxonomy/overpass"
 import type { OverpassIntentLike } from "@mailwoman/poi-taxonomy/overpass"
 import { computeQueryShape } from "@mailwoman/query-shape"
-import { useCallback, useEffect, useRef, useState } from "react"
+import { useCallback, useEffect, useEffectEvent, useState } from "react"
 
 import { useDebouncedValue } from "../common/useDebouncedValue.ts"
 import { loadPOIRuntime } from "./runtime.ts"
@@ -103,21 +103,31 @@ export function usePOISearch({
 	debounceMs = 250,
 }: UsePOISearchOptions): UsePOISearch {
 	const [runtime, setRuntime] = useState<POIRuntime | null>(null)
-	const [result, setResult] = useState<POIExplorerResult | null>(null)
-	const [liveSearch, setLiveSearch] = useState<LiveSearchState>({ status: "idle" })
+	/**
+	 * The classify result KEYED BY the query that produced it. The visible result is derived during render
+	 * (`storedResult.query === trimmedText ? … : null`), so a new query invalidates the old answer by derivation — the
+	 * effect never writes state synchronously to "reset", which is the react(set-state-in-effect) shape the lint bump
+	 * rightly flags.
+	 */
+	const [storedResult, setStoredResult] = useState<{ query: string; value: POIExplorerResult } | null>(null)
+	/**
+	 * Live-search state, keyed the same way: launched FOR a query, visible only while that query stands.
+	 */
+	const [storedLive, setStoredLive] = useState<{ query: string; state: LiveSearchState } | null>(null)
 
 	const debouncedText = useDebouncedValue(text, debounceMs)
+	const trimmedText = debouncedText.trim()
 
-	// Capture the loader in a ref so the load fires exactly ONCE on mount, regardless of whether the
-	// caller passes a fresh `loadRuntime` closure each render (an inline `async () => …` would otherwise
-	// retrigger the effect → reload → re-render loop). The runtime is a load-once resource.
-	const loadRuntimeRef = useRef(loadRuntime)
-	loadRuntimeRef.current = loadRuntime
+	// The load fires exactly ONCE on mount regardless of whether the caller passes a fresh `loadRuntime`
+	// closure each render (an inline `async () => …` would otherwise retrigger the effect → reload →
+	// re-render loop). `useEffectEvent` reads the LATEST closure without joining the dependency list —
+	// the runtime is a load-once resource.
+	const loadRuntimeEvent = useEffectEvent(() => loadRuntime())
 
 	useEffect(() => {
 		let cancelled = false
 
-		loadRuntimeRef.current().then((loaded) => {
+		void loadRuntimeEvent().then((loaded) => {
 			if (!cancelled) {
 				setRuntime(loaded)
 			}
@@ -129,20 +139,16 @@ export function usePOISearch({
 	}, [])
 
 	// Classify the debounced query and derive the subject + OverpassQL (async, so it lives in an effect).
+	// Every state write below happens after an await — invalidation on query change is handled by the
+	// key derivation above, not by a synchronous reset here.
 	useEffect(() => {
 		if (!runtime) return
 
-		let cancelled = false
-		const trimmed = debouncedText.trim()
-
-		// A new query invalidates live results from the previous one.
-		setLiveSearch({ status: "idle" })
+		const trimmed = trimmedText
 
-		if (!trimmed) {
-			setResult(null)
+		if (!trimmed) return
 
-			return
-		}
+		let cancelled = false
 
 		const input = { raw: trimmed, normalized: trimmed }
 		const shape = computeQueryShape(trimmed)
@@ -153,7 +159,7 @@ export function usePOISearch({
 			const matched = kindResult.kind === "poi_query" ? matchPOISubject(trimmed, undefined, runtime.lexicon) : null
 
 			if (!matched) {
-				setResult({ kindResult })
+				setStoredResult({ query: trimmed, value: { kindResult } })
 
 				return
 			}
@@ -161,15 +167,18 @@ export function usePOISearch({
 			// Brand subject: the lexicon carries the brand's canonical name as `categoryID` + its Wikidata QID. No category
 			// record, no OverpassQL (brands are searched by QID against the layer's `brand_wikidata` index, not OSM tags).
 			if ((matched.match.kind ?? "category") === "brand") {
-				setResult({
-					kindResult,
-					subject: {
-						kind: "brand",
-						name: matched.match.categoryID,
-						...(matched.match.wikidata ? { wikidata: matched.match.wikidata } : {}),
-						matchedPhrase: matched.match.matchedPhrase,
-						confidence: matched.match.confidence,
-						remainder: matched.remainder,
+				setStoredResult({
+					query: trimmed,
+					value: {
+						kindResult,
+						subject: {
+							kind: "brand",
+							name: matched.match.categoryID,
+							...(matched.match.wikidata ? { wikidata: matched.match.wikidata } : {}),
+							matchedPhrase: matched.match.matchedPhrase,
+							confidence: matched.match.confidence,
+							remainder: matched.remainder,
+						},
 					},
 				})
 
@@ -179,29 +188,37 @@ export function usePOISearch({
 			const category = runtime.lookup.getPOICategory(matched.match.categoryID)
 
 			if (!category) {
-				setResult({ kindResult })
+				setStoredResult({ query: trimmed, value: { kindResult } })
 
 				return
 			}
 
-			setResult({
-				kindResult,
-				subject: {
-					kind: "category",
-					category,
-					matchedPhrase: matched.match.matchedPhrase,
-					confidence: matched.match.confidence,
-					remainder: matched.remainder,
-					buildLocal: runtime.lookup.requiresBuildLocalLayer(category),
+			setStoredResult({
+				query: trimmed,
+				value: {
+					kindResult,
+					subject: {
+						kind: "category",
+						category,
+						matchedPhrase: matched.match.matchedPhrase,
+						confidence: matched.match.confidence,
+						remainder: matched.remainder,
+						buildLocal: runtime.lookup.requiresBuildLocalLayer(category),
+					},
+					...buildOverpass(runtime, matched.match.categoryID, matched.match.matchedPhrase, matched.remainder),
 				},
-				...buildOverpass(runtime, matched.match.categoryID, matched.match.matchedPhrase, matched.remainder),
 			})
 		})
 
 		return () => {
 			cancelled = true
 		}
-	}, [debouncedText, runtime])
+	}, [trimmedText, runtime])
+
+	// Derived visibility: an answer stands only while its query does. A new query reads as null/idle
+	// with no reset write anywhere.
+	const result = storedResult?.query === trimmedText ? storedResult.value : null
+	const liveSearch: LiveSearchState = storedLive?.query === trimmedText ? storedLive.state : { status: "idle" }
 
 	const subject = result?.subject
 
@@ -221,7 +238,7 @@ export function usePOISearch({
 
 		if (subject.kind === "category" ? subject.buildLocal : !(brandLiveSearch && subject.wikidata)) return
 
-		setLiveSearch({ status: "loading" })
+		setStoredLive({ query: trimmedText, state: { status: "loading" } })
 
 		try {
 			const outcome = await runLiveSearch(
@@ -241,16 +258,25 @@ export function usePOISearch({
 			)
 
 			if (outcome.status === "success") {
-				setLiveSearch({ status: "success", hits: outcome.hits, centerName: outcome.centerName })
+				setStoredLive({
+					query: trimmedText,
+					state: { status: "success", hits: outcome.hits, centerName: outcome.centerName },
+				})
 			} else if (outcome.status === "unplaced") {
-				setLiveSearch({ status: "error", message: `couldn't place "${outcome.anchor}"` })
+				setStoredLive({ query: trimmedText, state: { status: "error", message: `couldn't place "${outcome.anchor}"` } })
 			} else {
-				setLiveSearch({ status: "error", message: "the published POI layer isn't reachable" })
+				setStoredLive({
+					query: trimmedText,
+					state: { status: "error", message: "the published POI layer isn't reachable" },
+				})
 			}
 		} catch {
-			setLiveSearch({ status: "error", message: "the published POI layer isn't reachable" })
+			setStoredLive({
+				query: trimmedText,
+				state: { status: "error", message: "the published POI layer isn't reachable" },
+			})
 		}
-	}, [runLiveSearch, runtime, subject, brandLiveSearch])
+	}, [runLiveSearch, runtime, subject, brandLiveSearch, trimmedText])
 
 	return { runtimeReady: runtime !== null, result, liveSearch, canSearchLive, searchLive }
 }

package/runtime/useDemoRuntime.ts

@@ -189,15 +189,18 @@ export function useDemoRuntime<TAssets, TRelease extends DemoReleaseBase = DemoR
 	// Latest-ref the injected loaders: a host that re-creates them each render (an inline arrow) must NOT retrigger the
 	// load effects, which key ONLY on version/backend. The effects read `.current` at run time.
 	const loadManifestRef = useRef(config.loadManifest)
-	loadManifestRef.current = config.loadManifest
 	const loadAssetsRef = useRef(config.loadAssets)
-	loadAssetsRef.current = config.loadAssets
 
 	// Latest manifest for the version-load effect, so it can resolve the release WITHOUT depending on `manifest`
 	// identity — which would double-fire the load the instant the manifest first arrives (the selection transition
 	// null → defaultVersion already fires it once).
 	const manifestRef = useRef<DemoManifest<TRelease> | null>(null)
-	manifestRef.current = manifest
+
+	useEffect(() => {
+		loadManifestRef.current = config.loadManifest
+		loadAssetsRef.current = config.loadAssets
+		manifestRef.current = manifest
+	}, [config.loadAssets, config.loadManifest, manifest])
 
 	// Mount: fetch the manifest, then select the default version.
 	useEffect(() => {

package/styles.css

@@ -15,7 +15,7 @@
 	font-size: 0.95rem;
 }
 
-/* ── Field (label + input + button) ──────────────────────────────────────── */
+/* #region Field (label + input + button) */
 
 .mw-field {
 	display: flex;
@@ -60,7 +60,9 @@
 	cursor: not-allowed;
 }
 
-/* ── Preset chips ────────────────────────────────────────────────────────── */
+/* #endregion */
+
+/* #region Preset chips */
 
 .mw-presets {
 	margin-top: 0.75rem;
@@ -98,7 +100,9 @@
 	cursor: not-allowed;
 }
 
-/* ── Generic button (copy / search) ──────────────────────────────────────── */
+/* #endregion */
+
+/* #region Generic button (copy / search) */
 
 .mw-btn {
 	font-size: 0.8rem;
@@ -120,7 +124,9 @@
 	cursor: not-allowed;
 }
 
-/* ── Result panel + errors ───────────────────────────────────────────────── */
+/* #endregion */
+
+/* #region Result panel + errors */
 
 .mw-result {
 	margin-top: 1.5rem;
@@ -161,7 +167,9 @@
 	white-space: pre-wrap;
 }
 
-/* ── KindBadge ───────────────────────────────────────────────────────────── */
+/* #endregion */
+
+/* #region KindBadge */
 
 .mw-kind {
 	margin-bottom: 0.5rem;
@@ -183,7 +191,9 @@
 	list-style: disc;
 }
 
-/* ── POI subject panel ───────────────────────────────────────────────────── */
+/* #endregion */
+
+/* #region POI subject panel */
 
 .mw-subject__row {
 	display: flex;
@@ -258,7 +268,9 @@
 	margin: 0;
 }
 
-/* ── OverpassQL block ────────────────────────────────────────────────────── */
+/* #endregion */
+
+/* #region OverpassQL block */
 
 .mw-overpass {
 	margin-top: 0.75rem;
@@ -275,7 +287,9 @@
 	overflow-x: auto;
 }
 
-/* ── Live results ────────────────────────────────────────────────────────── */
+/* #endregion */
+
+/* #region Live results */
 
 .mw-live {
 	margin-top: 1rem;
@@ -317,7 +331,9 @@
 	white-space: nowrap;
 }
 
-/* ── Component table ─────────────────────────────────────────────────────── */
+/* #endregion */
+
+/* #region Component table */
 
 .mw-components {
 	width: 100%;
@@ -340,7 +356,9 @@
 	text-transform: uppercase;
 }
 
-/* ── Confidence cell ─────────────────────────────────────────────────────── */
+/* #endregion */
+
+/* #region Confidence cell */
 
 .mw-conf__dash {
 	color: var(--ifm-color-emphasis-500, #8c8c8c);
@@ -377,7 +395,9 @@
 	font-size: 0.8rem;
 }
 
-/* ── Resolved place ──────────────────────────────────────────────────────── */
+/* #endregion */
+
+/* #region Resolved place */
 
 .mw-resolved {
 	margin-top: 1rem;
@@ -416,7 +436,9 @@
 	font-size: 0.9rem;
 }
 
-/* ── Candidate picker ────────────────────────────────────────────────────── */
+/* #endregion */
+
+/* #region Candidate picker */
 
 .mw-candidates {
 	margin-top: 1rem;
@@ -471,7 +493,9 @@
 	color: var(--ifm-color-emphasis-600, #6e6e6e);
 }
 
-/* ── LoadingIndicator ────────────────────────────────────────────────────── */
+/* #endregion */
+
+/* #region LoadingIndicator */
 
 .mw-loading {
 	display: flex;
@@ -647,7 +671,9 @@
 	transform: translateY(-60%) rotate(45deg);
 }
 
-/* ── Demo map (react-map-gl/maplibre shell) ──────────────────────────────── */
+/* #endregion */
+
+/* #region Demo map (react-map-gl/maplibre shell) */
 
 /*
  * The <DemoMap> wrapper. Sizing is the host's call (pass `style`/`className`), but a min-height keeps
@@ -661,8 +687,6 @@
 	overflow: hidden;
 }
 
-/* ── Geocoder demo (composed: full-viewport map + floating control panel) ──── */
-
 /*
  * The demo fills its positioning context; the host sizes it (a full-viewport wrapper in docs). The map is the
  * background layer, the control panel floats over the top-left (bottom on narrow screens). A host that wants a
@@ -705,7 +729,9 @@
 	}
 }
 
-/* ── Demo control field (version / compare-version selects) ──────────────── */
+/* #endregion */
+
+/* #region Demo control field (version / compare-version selects) */
 
 .mw-demo-control {
 	margin-bottom: 0.75rem;
@@ -732,7 +758,9 @@
 	opacity: 0.5;
 }
 
-/* ── Backend indicator + WASM toggle / compare toggle ────────────────────── */
+/* #endregion */
+
+/* #region Backend indicator + WASM toggle / compare toggle */
 
 .mw-demo-backend,
 .mw-demo-compare {
@@ -771,7 +799,9 @@
 	color: var(--ifm-color-emphasis-600, #6e6e6e);
 }
 
-/* ── Place autocomplete listbox (reuses .mw-chip) ────────────────────────── */
+/* #endregion */
+
+/* #region Place autocomplete listbox (reuses .mw-chip) */
 
 .mw-demo-suggest {
 	margin-top: 0.75rem;