@mailwoman/react 10.0.0 → 10.2.0

package/lib/poi/types.ts

@@ -3,22 +3,27 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Types for the POI explorer. The intent path (classification → subject → OverpassQL) is fully
- *   self-contained over the pure `@mailwoman/*` packages; the live poi.db path is expressed only as an
- *   INJECTED async function ({@link POILiveSearch}) so the httpvfs/worker implementation stays out of this
- *   package's browser graph (it lives in the docs site, which knows where the layer is served).
+ *   Types for the POI explorer. Live poi.db search is injected as {@link POILiveSearch} so the httpvfs
+ *   worker stays out of this package's browser graph.
  */
 
 import type { QueryKindResult } from "@mailwoman/core/pipeline"
+import type { POIDistanceHit } from "@mailwoman/core/resolver"
 import type { POIPhraseLookup, createKindClassifier } from "@mailwoman/kind-classifier"
 import type { createPOITaxonomyLookup } from "@mailwoman/poi-taxonomy/table"
 
+/**
+ * The POI taxonomy lookup that the explorer runtime loads.
+ */
 export type TaxonomyLookup = ReturnType<typeof createPOITaxonomyLookup>
 
+/**
+ * One taxonomy category record.
+ */
 export type CategoryRecord = NonNullable<ReturnType<TaxonomyLookup["getPOICategory"]>>
 
 /**
- * The lazily-loaded POI runtime: the taxonomy lookup, the adapted lexicon, and the kind classifier over it.
+ * The lazily loaded POI runtime holds the taxonomy lookup, the lexicon and the kind classifier.
  */
 export interface POIRuntime {
 	lookup: TaxonomyLookup
@@ -33,27 +38,27 @@ export interface POISubjectBase {
 	matchedPhrase: string
 	confidence: number
 	/**
-	 * The non-subject remainder of the query (the location anchor, e.g. "near Springfield").
+	 * The rest of the query after the subject, usually the location anchor such as "near Springfield".
 	 */
 	remainder: string
 }
 
 /**
- * A resolved POI subject that names a taxonomy CATEGORY (`cafe`, `hospital`, `drinking fountain`).
+ * A resolved POI subject that matched a taxonomy category such as `cafe` or `hospital`.
  */
 export interface POICategorySubject extends POISubjectBase {
 	kind: "category"
 	category: CategoryRecord
 	/**
-	 * Whether this category needs the locally-built OSM (ODbL) layer — precomputed off the runtime.
+	 * Whether this category requires the locally built OSM (ODbL) layer.
 	 */
 	buildLocal: boolean
 }
 
 /**
- * A resolved POI subject that names a chain BRAND (`chevron`, `applebee's`). Brands carry a Wikidata QID and are
- * searched by that QID, NOT by category k-ring — see `@mailwoman/poi-taxonomy`'s brand table + the layer's
- * `brand_wikidata` index.
+ * A resolved POI subject that matched a chain brand such as `chevron`.
+ *
+ * Live search looks up a brand by its Wikidata QID instead of by category k-ring.
  */
 export interface POIBrandSubject extends POISubjectBase {
 	kind: "brand"
@@ -62,41 +67,39 @@ export interface POIBrandSubject extends POISubjectBase {
 	 */
 	name: string
 	/**
-	 * Wikidata QID, when the lexicon carried one (`Q319642` = Chevron). Absent ⇒ matched by name alone.
+	 * The brand's Wikidata QID.
+	 * It is `null` when the lexicon had no QID for the brand.
 	 */
-	wikidata?: string
+	wikidata: string | null
 }
 
 /**
- * A resolved POI subject — a taxonomy category or a chain brand — plus its match metadata.
+ * A resolved POI subject, either a taxonomy category or a chain brand.
  */
 export type POISubject = POICategorySubject | POIBrandSubject
 
 /**
- * The intent-only result: the kind verdict plus (when a subject was detected) its OverpassQL export (category only).
+ * The intent-only result.
+ *
+ * It holds the kind verdict and, when a category subject was detected, its OverpassQL export.
  */
 export interface POIExplorerResult {
 	kindResult: QueryKindResult
-	subject?: POISubject
-	overpassQL?: string
-	overpassError?: string
+	subject: POISubject | null
+	overpassQL: string | null
+	overpassError: string | null
 }
 
 /**
  * One live poi.db hit, as the results list renders it.
  */
-export interface POISearchHit {
-	name: string
-	lat: number
-	lon: number
-	distanceM: number
-	country: string
-	confidence: number
-}
+export type POISearchHit = POIDistanceHit
 
 /**
- * Result of an injected live search. Preserves the original tester's two failure modes — the anchor not resolving vs
- * the published layer being unreachable — so the UI can word them differently.
+ * The result of an injected live search.
+ *
+ * The `unplaced` and `unavailable` states stay separate so the UI can tell an
+ * unresolved anchor apart from an unreachable layer.
  */
 export type POILiveSearchResult =
 	| { status: "success"; hits: POISearchHit[]; centerName: string }
@@ -104,28 +107,35 @@ export type POILiveSearchResult =
 	| { status: "unavailable" }
 
 /**
- * The injected live-search function. Given the resolved category (+ its Overture leaf fan-out) and the anchor text, it
- * probes the published poi.db and returns hits. Absent ⇒ the explorer runs intent-only (no "Search live" button).
+ * What a live search looks for near `anchor`: a taxonomy category with its Overture
+ * leaf categories, or a chain brand identified by its Wikidata QID.
+ */
+export type POILiveSearchRequest =
+	| {
+			kind: "category"
+			categoryID: string
+			overtureCategoryIDs: string[]
+			anchor: string
+	  }
+	| {
+			kind: "brand"
+			brandName: string
+			wikidata: string
+			anchor: string
+	  }
+
+/**
+ * The injected live-search function.
+ *
+ * It probes the published poi.db for the request's subject and the anchor text.
+ * The explorer runs intent-only when this function is absent.
  *
- * Brand support is ADDITIVE: when the resolved subject is a chain brand, `brandWikidata` carries its QID and the probe
- * fetches by that QID instead of a category k-ring (`categoryID`/`overtureCategoryIDs` are then the brand name / empty
- * and unused). The category path is byte-identical to before. A probe that can't serve brands simply leaves brand live
- * search unwired at the call site (see `usePOISearch`'s `brandLiveSearch` option) — the docs' httpvfs probe does
- * exactly that, brand-wide row hydration being pathological over byte-range (measured; the brand path is server-side
- * only).
+ * A probe that cannot serve brands should leave `usePOISearch`'s `brandLiveSearch` option unset.
  */
-export type POILiveSearch = (params: {
-	categoryID: string
-	overtureCategoryIDs: string[]
-	anchor: string
-	/**
-	 * Present when the subject is a chain brand — the probe fetches by this QID, not a category k-ring.
-	 */
-	brandWikidata?: string
-}) => Promise<POILiveSearchResult>
+export type POILiveSearch = (request: POILiveSearchRequest) => Promise<POILiveSearchResult>
 
 /**
- * "Search live" state machine.
+ * The state of a "Search live" request.
  */
 export type LiveSearchState =
 	| { status: "idle" }
@@ -134,6 +144,7 @@ export type LiveSearchState =
 	| { status: "success"; hits: POISearchHit[]; centerName: string }
 
 /**
- * A single-argument runtime loader — injectable so stories/tests can substitute a mock taxonomy.
+ * A runtime loader.
+ * Stories and tests inject one to substitute a mock taxonomy.
  */
 export type LoadPOIRuntime = () => Promise<POIRuntime>

package/lib/poi/usePOISearch.ts

@@ -2,11 +2,6 @@
  * @copyright Sister Software
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
- *
- *   `usePOISearch` — the headless core of the POI explorer. Owns the taxonomy-runtime load, the
- *   debounced classify → subject → OverpassQL derivation, and the "Search live" state machine. The
- *   runtime loader and the live-search probe are both INJECTABLE, so stories/tests drive it with mocks
- *   and no network or db. Presentation is entirely the caller's concern.
  */
 
 import { matchPOISubject } from "@mailwoman/kind-classifier"
@@ -17,84 +12,115 @@ import { useCallback, useEffect, useEffectEvent, useState } from "react"
 
 import { useDebouncedValue } from "#common/useDebouncedValue"
 import { loadPOIRuntime } from "#poi/runtime"
-import type { LiveSearchState, LoadPOIRuntime, POIExplorerResult, POILiveSearch, POIRuntime } from "#poi/types"
+import type {
+	LiveSearchState,
+	LoadPOIRuntime,
+	POIExplorerResult,
+	POILiveSearch,
+	POILiveSearchRequest,
+	POIRuntime,
+} from "#poi/types"
 
+/**
+ * Options for {@link usePOISearch}.
+ */
 export interface UsePOISearchOptions {
 	/**
-	 * The current query text (controlled by the caller).
+	 * The current query text, owned and updated by the caller.
 	 */
 	text: string
+
 	/**
-	 * Runtime loader. @default loadPOIRuntime
+	 * The loader that the hook calls once on mount.
+	 *
+	 * @defaultValue `loadPOIRuntime`
 	 */
 	loadRuntime?: LoadPOIRuntime
+
 	/**
-	 * Injected live-search probe. Absent ⇒ the live-results affordance is disabled.
+	 * The live-search probe.
+	 * Live search is unavailable when it is absent.
 	 */
 	runLiveSearch?: POILiveSearch
+
 	/**
-	 * Whether the injected probe can serve BRAND subjects (fetch by Wikidata QID). Default false: brand subjects show the
-	 * intent + QID chip but no live-search affordance. The docs' httpvfs probe leaves this off — brand-wide row hydration
-	 * is pathological over byte-range (measured) — so brand live search is a server-side-backend capability. Category
-	 * live search is unaffected either way.
+	 * Whether the probe can search for brand subjects by Wikidata ID, defaulting to
+	 * false. enable it only for a server-side backend, since fetching every row for
+	 * a brand over an HTTP range-request database is too slow.
 	 */
 	brandLiveSearch?: boolean
+
 	/**
-	 * Debounce before (re)classifying. @default 250
+	 * The delay in milliseconds before the text is classified.
+	 *
+	 * @defaultValue `250`
 	 */
 	debounceMs?: number
 }
 
+/**
+ * The state that {@link usePOISearch} returns.
+ */
 export interface UsePOISearch {
 	/**
 	 * True once the taxonomy runtime has loaded.
 	 */
 	runtimeReady: boolean
+
 	/**
-	 * The intent result for the current (debounced) query, or null for empty input.
+	 * The classification for the current debounced text, `null` for empty text
+	 * and while classification is pending.
 	 */
 	result: POIExplorerResult | null
+
 	/**
-	 * State of the on-demand live poi.db search.
+	 * The live-search state for the current debounced text, `idle` until a search runs.
 	 */
 	liveSearch: LiveSearchState
+
 	/**
-	 * Whether a live search can run right now (a probe is wired + there's a resolved subject with an anchor).
+	 * Whether a probe is wired and the subject supports live search with a non-empty place anchor.
 	 */
 	canSearchLive: boolean
+
 	/**
-	 * Kick off a live search for the current subject. No-op when {@link canSearchLive} is false.
+	 * Starts a live search for the current subject.
+	 * It starts no search when `canSearchLive` is false.
 	 */
 	searchLive: () => Promise<void>
 }
 
-/**
- * Compute the OverpassQL export for a matched subject, capturing any emitter error rather than throwing.
- */
 function buildOverpass(
 	runtime: POIRuntime,
-	categoryID: string,
-	matchedPhrase: string,
-	remainder: string
-): { overpassQL?: string; overpassError?: string } {
+	categoryID: string
+): { overpassQL: string | null; overpassError: string | null } {
 	const category = runtime.lookup.getPOICategory(categoryID)
 
 	if (!category) {
-		return {}
+		return { overpassQL: null, overpassError: null }
 	}
 
 	const intent: OverpassIntentLike = {
-		subject: { kind: "category", categoryIDs: [categoryID], matched: matchedPhrase },
-		...(remainder ? { anchor: { text: remainder } } : {}),
+		subject: { kind: "category", categoryIDs: [categoryID] },
+		anchor: null,
 	}
 
 	try {
-		return { overpassQL: emitOverpassQL(intent, category.osmTag ? { osmTags: [category.osmTag] } : {}) }
+		return {
+			overpassQL: emitOverpassQL(intent, category.osmTag ? { osmTags: [category.osmTag] } : {}),
+			overpassError: null,
+		}
 	} catch (error) {
-		return { overpassError: error instanceof Error ? error.message : String(error) }
+		return { overpassQL: null, overpassError: error instanceof Error ? error.message : String(error) }
 	}
 }
 
+/**
+ * Classifies debounced query text as a POI category or brand request and runs live searches on demand.
+ *
+ * Each result is keyed to the query that produced it, live search requires a non-empty anchor.
+ * Brands need `brandLiveSearch` plus a Wikidata ID.
+ */
 export function usePOISearch({
 	text,
 	loadRuntime = loadPOIRuntime,
@@ -103,25 +129,14 @@ export function usePOISearch({
 	debounceMs = 250,
 }: UsePOISearchOptions): UsePOISearch {
 	const [runtime, setRuntime] = useState<POIRuntime | null>(null)
-	/**
-	 * 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()
 
-	// 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(() => {
@@ -138,9 +153,6 @@ 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
 
@@ -156,16 +168,14 @@ export function usePOISearch({
 		runtime.classify(input, shape).then((kindResult) => {
 			if (cancelled) return
 
-			const matched = kindResult.kind === "poi_query" ? matchPOISubject(trimmed, undefined, runtime.lexicon) : null
+			const matched = kindResult.kind === "poi_query" ? matchPOISubject(trimmed, null, runtime.lexicon) : null
 
 			if (!matched) {
-				setStoredResult({ query: trimmed, value: { kindResult } })
+				setStoredResult({ query: trimmed, value: { kindResult, subject: null, overpassQL: null, overpassError: null } })
 
 				return
 			}
 
-			// 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") {
 				setStoredResult({
 					query: trimmed,
@@ -174,11 +184,13 @@ export function usePOISearch({
 						subject: {
 							kind: "brand",
 							name: matched.match.categoryID,
-							...(matched.match.wikidata ? { wikidata: matched.match.wikidata } : {}),
+							wikidata: matched.match.wikidata || null,
 							matchedPhrase: matched.match.matchedPhrase,
 							confidence: matched.match.confidence,
 							remainder: matched.remainder,
 						},
+						overpassQL: null,
+						overpassError: null,
 					},
 				})
 
@@ -188,7 +200,7 @@ export function usePOISearch({
 			const category = runtime.lookup.getPOICategory(matched.match.categoryID)
 
 			if (!category) {
-				setStoredResult({ query: trimmed, value: { kindResult } })
+				setStoredResult({ query: trimmed, value: { kindResult, subject: null, overpassQL: null, overpassError: null } })
 
 				return
 			}
@@ -205,7 +217,7 @@ export function usePOISearch({
 						remainder: matched.remainder,
 						buildLocal: runtime.lookup.requiresBuildLocalLayer(category),
 					},
-					...buildOverpass(runtime, matched.match.categoryID, matched.match.matchedPhrase, matched.remainder),
+					...buildOverpass(runtime, matched.match.categoryID),
 				},
 			})
 		})
@@ -215,19 +227,13 @@ export function usePOISearch({
 		}
 	}, [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
+	const subject = result?.subject ?? null
 
-	// A subject is live-searchable when a probe is wired, it has an anchor, and: a CATEGORY that isn't build-local, or a
-	// BRAND with a QID AND a brand-capable probe (`brandLiveSearch`). Brands without a QID / without a brand probe show
-	// the intent + QID chip but no live affordance.
 	const subjectLiveCapable =
-		subject !== undefined &&
-		(subject.kind === "brand" ? brandLiveSearch && subject.wikidata !== undefined : !subject.buildLocal)
+		subject !== null && (subject.kind === "brand" ? brandLiveSearch && subject.wikidata !== null : !subject.buildLocal)
 
 	const canSearchLive = Boolean(
 		runLiveSearch && runtime && subject && subjectLiveCapable && subject.remainder.trim().length > 0
@@ -236,34 +242,37 @@ export function usePOISearch({
 	const searchLive = useCallback(async () => {
 		if (!runLiveSearch || !runtime || !subject || !subject.remainder.trim()) return
 
-		if (subject.kind === "category" ? subject.buildLocal : !(brandLiveSearch && subject.wikidata)) return
+		let request: POILiveSearchRequest
+
+		if (subject.kind === "brand") {
+			if (!brandLiveSearch || !subject.wikidata) return
+			request = { kind: "brand", brandName: subject.name, wikidata: subject.wikidata, anchor: subject.remainder }
+		} else {
+			if (subject.buildLocal) return
+
+			request = {
+				kind: "category",
+				categoryID: subject.category.id,
+				overtureCategoryIDs: runtime.lookup.resolveOvertureCategories(subject.category.id),
+				anchor: subject.remainder,
+			}
+		}
 
 		setStoredLive({ query: trimmedText, state: { status: "loading" } })
 
 		try {
-			const outcome = await runLiveSearch(
-				subject.kind === "brand"
-					? {
-							categoryID: subject.name,
-							overtureCategoryIDs: [],
-							anchor: subject.remainder,
-							brandWikidata: subject.wikidata,
-						}
-					: {
-							categoryID: subject.category.id,
-							// Fan the canonical seed id out over its Overture leaves — the same translation the Node reader uses.
-							overtureCategoryIDs: runtime.lookup.resolveOvertureCategories(subject.category.id),
-							anchor: subject.remainder,
-						}
-			)
-
-			if (outcome.status === "success") {
+			const response = await runLiveSearch(request)
+
+			if (response.status === "success") {
+				setStoredLive({
+					query: trimmedText,
+					state: { status: "success", hits: response.hits, centerName: response.centerName },
+				})
+			} else if (response.status === "unplaced") {
 				setStoredLive({
 					query: trimmedText,
-					state: { status: "success", hits: outcome.hits, centerName: outcome.centerName },
+					state: { status: "error", message: `couldn't place "${response.anchor}"` },
 				})
-			} else if (outcome.status === "unplaced") {
-				setStoredLive({ query: trimmedText, state: { status: "error", message: `couldn't place "${outcome.anchor}"` } })
 			} else {
 				setStoredLive({
 					query: trimmedText,

package/lib/poi.ts

@@ -0,0 +1,40 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file POI explorer components, hooks, runtime and interfaces.
+ */
+
+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,
+	POILiveSearchRequest,
+	POILiveSearchResult,
+	POIRuntime,
+	POISearchHit,
+	POISubject,
+	POISubjectBase,
+	TaxonomyLookup,
+} from "#poi/types"
+
+export { usePOISearch } from "#poi/usePOISearch"
+export type { UsePOISearch, UsePOISearchOptions } from "#poi/usePOISearch"