@mailwoman/react 0.0.1 → 7.4.0

package/poi/OverpassBlock.tsx

@@ -0,0 +1,37 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `OverpassBlock` — the OverpassQL export panel: a header with a copy button and the query in a code
+ *   block. Renders the emitter error instead when the export failed. Presentational.
+ */
+
+import type { ReactNode } from "react"
+
+import { CopyButton } from "../common/CopyButton.tsx"
+
+export interface OverpassBlockProps {
+	overpassQL?: string
+	overpassError?: string
+}
+
+export function OverpassBlock({ overpassQL, overpassError }: OverpassBlockProps): ReactNode {
+	if (overpassQL) {
+		return (
+			<div className="mw-overpass">
+				<div className="mw-panel__header">
+					<h3>OverpassQL export</h3>
+					<CopyButton value={overpassQL} className="mw-btn" />
+				</div>
+				<pre className="mw-overpass__code">
+					<code>{overpassQL}</code>
+				</pre>
+			</div>
+		)
+	}
+
+	if (overpassError) return <p className="mw-error">{overpassError}</p>
+
+	return null
+}

package/poi/POIExplorer.tsx

@@ -0,0 +1,102 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `POIExplorer` — the composed POI-intent tester. Detects a POI subject in free text, shows the
+ *   category + OverpassQL export, and (when a live-search probe is injected) searches the published
+ *   poi.db layer. The intent path is self-contained — no weights, no network. All runtime concerns are
+ *   in {@link usePOISearch}; this file is composition + a `ClientOnly` SSR boundary.
+ */
+
+import { type ReactNode, useState } from "react"
+
+import { ClientOnly } from "../common/ClientOnly.tsx"
+import { KindBadge } from "../common/KindBadge.tsx"
+import { PresetChips, type Preset } from "../common/PresetChips.tsx"
+import { AbstainPanel } from "./AbstainPanel.tsx"
+import { LiveResultsBlock } from "./LiveResultsBlock.tsx"
+import { OverpassBlock } from "./OverpassBlock.tsx"
+import { QueryInput } from "./QueryInput.tsx"
+import { POI_DEFAULT_TEXT, POI_PRESETS } from "./runtime.ts"
+import { SubjectPanel } from "./SubjectPanel.tsx"
+import type { LoadPOIRuntime, POILiveSearch } from "./types.ts"
+import { usePOISearch } from "./usePOISearch.ts"
+
+export interface POIExplorerProps {
+	/** Query to pre-fill in the input. */
+	defaultText?: string
+	/** Example chips. @default the built-in POI presets */
+	presets?: ReadonlyArray<Preset>
+	/** Override the taxonomy-runtime loader (stories/tests inject a mock). */
+	loadRuntime?: LoadPOIRuntime
+	/** Live poi.db probe. Absent ⇒ intent-only (no live-results affordance). */
+	runLiveSearch?: POILiveSearch
+}
+
+interface POIExplorerInnerProps extends POIExplorerProps {
+	defaultText: string
+	presets: ReadonlyArray<Preset>
+}
+
+function POIExplorerInner({ defaultText, presets, loadRuntime, runLiveSearch }: POIExplorerInnerProps): ReactNode {
+	const [text, setText] = useState(defaultText)
+	const { result, liveSearch, searchLive } = usePOISearch({ text, loadRuntime, runLiveSearch })
+
+	return (
+		<div className="mw-poi-explorer">
+			<QueryInput id="mw-poi-input" label="Query" value={text} onChange={setText} placeholder={POI_DEFAULT_TEXT} />
+			<PresetChips presets={presets} onPick={setText} />
+
+			{result ? (
+				<div className="mw-result">
+					<KindBadge kindResult={result.kindResult} />
+
+					{result.subject ? (
+						<>
+							<SubjectPanel subject={result.subject} />
+							<OverpassBlock overpassQL={result.overpassQL} overpassError={result.overpassError} />
+
+							{runLiveSearch && !result.subject.buildLocal ? (
+								<LiveResultsBlock
+									categoryLabel={result.subject.category.label}
+									anchor={result.subject.remainder}
+									state={liveSearch}
+									onSearch={searchLive}
+								/>
+							) : null}
+						</>
+					) : (
+						<AbstainPanel kind={result.kindResult.kind} />
+					)}
+				</div>
+			) : null}
+		</div>
+	)
+}
+
+export function POIExplorer({
+	defaultText = POI_DEFAULT_TEXT,
+	presets = POI_PRESETS,
+	loadRuntime,
+	runLiveSearch,
+}: POIExplorerProps): ReactNode {
+	return (
+		<ClientOnly
+			fallback={
+				<div className="mw-poi-explorer">
+					<p>Loading POI tester…</p>
+				</div>
+			}
+		>
+			{() => (
+				<POIExplorerInner
+					defaultText={defaultText}
+					presets={presets}
+					loadRuntime={loadRuntime}
+					runLiveSearch={runLiveSearch}
+				/>
+			)}
+		</ClientOnly>
+	)
+}

package/poi/QueryInput.tsx

@@ -0,0 +1,26 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `QueryInput` — the labelled text field for the POI explorer. Controlled; presentational only.
+ */
+
+import type { ReactNode } from "react"
+
+export interface QueryInputProps {
+	id: string
+	label: string
+	value: string
+	onChange: (value: string) => void
+	placeholder?: string
+}
+
+export function QueryInput({ id, label, value, onChange, placeholder }: QueryInputProps): ReactNode {
+	return (
+		<div className="mw-field">
+			<label htmlFor={id}>{label}</label>
+			<input id={id} type="text" value={value} onChange={(e) => onChange(e.target.value)} placeholder={placeholder} />
+		</div>
+	)
+}

package/poi/SubjectPanel.tsx

@@ -0,0 +1,44 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `SubjectPanel` — renders the detected POI subject: the category chip, the optional build-local
+ *   badge + note, and the match-detail list (matched phrase, confidence, anchor). Presentational.
+ */
+
+import type { ReactNode } from "react"
+
+import type { POISubject } from "./types.ts"
+
+export interface SubjectPanelProps {
+	subject: POISubject
+}
+
+export function SubjectPanel({ subject }: SubjectPanelProps): ReactNode {
+	return (
+		<>
+			<div className="mw-subject__row">
+				<span className="mw-subject__chip">{subject.category.label}</span>
+				{subject.buildLocal ? <span className="mw-subject__badge">build-local</span> : null}
+			</div>
+
+			<dl className="mw-subject__detail">
+				<dt>matched phrase</dt>
+				<dd>
+					<code>{subject.matchedPhrase}</code>
+				</dd>
+				<dt>confidence</dt>
+				<dd>{Math.round(subject.confidence * 100)}%</dd>
+				<dt>anchor</dt>
+				<dd>{subject.remainder ? subject.remainder : <em>none — global query</em>}</dd>
+			</dl>
+
+			{subject.buildLocal ? (
+				<p className="mw-subject__note">
+					Requires the locally-built OSM layer (ODbL) — mailwoman ships the builder, not the data.
+				</p>
+			) : null}
+		</>
+	)
+}

package/poi/runtime.ts

@@ -0,0 +1,53 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The default POI runtime loader + presentation helpers. `loadPOIRuntime` dynamically imports the
+ *   ~2k-record Overture taxonomy snapshot (so bundlers code-split it into its own chunk, fetched only
+ *   when the explorer actually mounts) and wires the kind classifier over it. Pure + browser-safe: no
+ *   network, no DOM — the whole intent path runs offline.
+ */
+
+import { createKindClassifier } from "@mailwoman/kind-classifier"
+import type { POIPhraseLookup } from "@mailwoman/kind-classifier"
+import { createPOITaxonomyLookup } from "@mailwoman/poi-taxonomy/table"
+
+import type { POIRuntime } from "./types.ts"
+
+/**
+ * Build the POI runtime, dynamically importing the taxonomy JSON so the ~2k-record table lands in its own chunk. A
+ * static import would inline the whole snapshot into every consumer's bundle.
+ */
+export async function loadPOIRuntime(): Promise<POIRuntime> {
+	const table = (await import("@mailwoman/poi-taxonomy/data/taxonomy.json")).default
+	const lookup = createPOITaxonomyLookup(table as unknown as Parameters<typeof createPOITaxonomyLookup>[0])
+
+	// Adapt `POITaxonomyLookup.lookupPOICategory` to the `POIPhraseLookup` shape the classifier expects.
+	const lexicon: POIPhraseLookup = (phrase, locale) =>
+		lookup.lookupPOICategory(phrase, locale).map((match) => ({
+			kind: "category",
+			categoryID: match.category.id,
+			matchedPhrase: match.matchedPhrase,
+			confidence: match.confidence,
+		}))
+
+	return { lookup, lexicon, classify: createKindClassifier({ poiLexicon: lexicon }) }
+}
+
+/** Default example queries for the POI explorer. */
+export const POI_PRESETS = [
+	{ label: "Drinking fountain", value: "drinking fountain near Springfield" },
+	{ label: "Fire hydrant", value: "fire hydrant" },
+	{ label: "Hospital + address", value: "hospital, 350 5th Ave, New York" },
+	{ label: "Biking trails", value: "biking trails near Portland" },
+] as const
+
+export const POI_DEFAULT_TEXT = POI_PRESETS[0].value
+
+/** `742 m` under 1 km, `1.9 km` past it — matches the demo's distance captions. */
+export function formatDistance(distanceM: number): string {
+	if (distanceM < 1000) return `${Math.round(distanceM)} m`
+
+	return `${(distanceM / 1000).toFixed(1)} km`
+}

package/poi/types.ts

@@ -0,0 +1,82 @@
+/**
+ * @copyright Sister Software
+ * @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 machinery stays out of this
+ *   package's browser graph (it lives in the docs site, which knows where the layer is served).
+ */
+
+import type { POIPhraseLookup, QueryKindResult } from "@mailwoman/kind-classifier"
+import type { createKindClassifier } from "@mailwoman/kind-classifier"
+import type { createPOITaxonomyLookup } from "@mailwoman/poi-taxonomy/table"
+
+export type TaxonomyLookup = ReturnType<typeof createPOITaxonomyLookup>
+export type CategoryRecord = NonNullable<ReturnType<TaxonomyLookup["getPOICategory"]>>
+
+/** The lazily-loaded POI runtime: the taxonomy lookup, the adapted lexicon, and the kind classifier over it. */
+export interface POIRuntime {
+	lookup: TaxonomyLookup
+	lexicon: POIPhraseLookup
+	classify: ReturnType<typeof createKindClassifier>
+}
+
+/** A resolved POI subject — the category the query names plus its match metadata. */
+export interface POISubject {
+	category: CategoryRecord
+	matchedPhrase: string
+	confidence: number
+	/** The non-subject remainder of the query (the location anchor, e.g. "near Springfield"). */
+	remainder: string
+	/** Whether this category needs the locally-built OSM (ODbL) layer — precomputed off the runtime. */
+	buildLocal: boolean
+}
+
+/** The intent-only result: the kind verdict plus (when a subject was detected) its OverpassQL export. */
+export interface POIExplorerResult {
+	kindResult: QueryKindResult
+	subject?: POISubject
+	overpassQL?: string
+	overpassError?: string
+}
+
+/** 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
+}
+
+/**
+ * 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.
+ */
+export type POILiveSearchResult =
+	| { status: "success"; hits: POISearchHit[]; centerName: string }
+	| { status: "unplaced"; anchor: string }
+	| { 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).
+ */
+export type POILiveSearch = (params: {
+	categoryID: string
+	overtureCategoryIDs: string[]
+	anchor: string
+}) => Promise<POILiveSearchResult>
+
+/** "Search live" state machine. */
+export type LiveSearchState =
+	| { status: "idle" }
+	| { status: "loading" }
+	| { status: "error"; message: string }
+	| { status: "success"; hits: POISearchHit[]; centerName: string }
+
+/** A single-argument runtime loader — injectable so stories/tests can substitute a mock taxonomy. */
+export type LoadPOIRuntime = () => Promise<POIRuntime>

package/poi/usePOISearch.ts

@@ -0,0 +1,183 @@
+/**
+ * @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"
+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 { useDebouncedValue } from "../common/useDebouncedValue.ts"
+import { loadPOIRuntime } from "./runtime.ts"
+import type { LiveSearchState, LoadPOIRuntime, POIExplorerResult, POILiveSearch, POIRuntime } from "./types.ts"
+
+export interface UsePOISearchOptions {
+	/** The current query text (controlled by the caller). */
+	text: string
+	/** Runtime loader. @default loadPOIRuntime */
+	loadRuntime?: LoadPOIRuntime
+	/** Injected live-search probe. Absent ⇒ the live-results affordance is disabled. */
+	runLiveSearch?: POILiveSearch
+	/** Debounce before (re)classifying. @default 250 */
+	debounceMs?: number
+}
+
+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. */
+	result: POIExplorerResult | null
+	/** State of the on-demand live poi.db search. */
+	liveSearch: LiveSearchState
+	/** Whether a live search can run right now (a probe is wired + there's a resolved subject with an anchor). */
+	canSearchLive: boolean
+	/** Kick off a live search for the current subject. No-op when {@link 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 } {
+	const category = runtime.lookup.getPOICategory(categoryID)
+
+	if (!category) {
+		return {}
+	}
+
+	const intent: OverpassIntentLike = {
+		subject: { kind: "category", categoryID, matched: matchedPhrase },
+		...(remainder ? { anchor: { text: remainder } } : {}),
+	}
+
+	try {
+		return { overpassQL: emitOverpassQL(intent, category.osmTag ? { osmTag: category.osmTag } : {}) }
+	} catch (err) {
+		return { overpassError: err instanceof Error ? err.message : String(err) }
+	}
+}
+
+export function usePOISearch({
+	text,
+	loadRuntime = loadPOIRuntime,
+	runLiveSearch,
+	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" })
+
+	const debouncedText = useDebouncedValue(text, debounceMs)
+
+	// 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
+
+	useEffect(() => {
+		let cancelled = false
+
+		loadRuntimeRef.current().then((loaded) => {
+			if (!cancelled) {
+				setRuntime(loaded)
+			}
+		})
+
+		return () => {
+			cancelled = true
+		}
+	}, [])
+
+	// Classify the debounced query and derive the subject + OverpassQL (async, so it lives in an effect).
+	useEffect(() => {
+		if (!runtime) return
+
+		let cancelled = false
+		const trimmed = debouncedText.trim()
+
+		// A new query invalidates live results from the previous one.
+		setLiveSearch({ status: "idle" })
+
+		if (!trimmed) {
+			setResult(null)
+
+			return
+		}
+
+		const input = { raw: trimmed, normalized: trimmed }
+		const shape = computeQueryShape(trimmed)
+
+		runtime.classify(input, shape).then((kindResult) => {
+			if (cancelled) return
+
+			const matched = kindResult.kind === "poi_query" ? matchPOISubject(trimmed, undefined, runtime.lexicon) : null
+			const category = matched ? runtime.lookup.getPOICategory(matched.match.categoryID) : undefined
+
+			if (!matched || !category) {
+				setResult({ kindResult })
+
+				return
+			}
+
+			setResult({
+				kindResult,
+				subject: {
+					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),
+			})
+		})
+
+		return () => {
+			cancelled = true
+		}
+	}, [debouncedText, runtime])
+
+	const subject = result?.subject
+	const canSearchLive = Boolean(
+		runLiveSearch && runtime && subject && !subject.buildLocal && subject.remainder.trim().length > 0
+	)
+
+	const searchLive = useCallback(async () => {
+		if (!runLiveSearch || !runtime || !subject || subject.buildLocal || !subject.remainder.trim()) return
+
+		setLiveSearch({ status: "loading" })
+
+		try {
+			const outcome = await runLiveSearch({
+				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") {
+				setLiveSearch({ status: "success", hits: outcome.hits, centerName: outcome.centerName })
+			} else if (outcome.status === "unplaced") {
+				setLiveSearch({ status: "error", message: `couldn't place "${outcome.anchor}"` })
+			} else {
+				setLiveSearch({ status: "error", message: "the published POI layer isn't reachable" })
+			}
+		} catch {
+			setLiveSearch({ status: "error", message: "the published POI layer isn't reachable" })
+		}
+	}, [runLiveSearch, runtime, subject])
+
+	return { runtimeReady: runtime !== null, result, liveSearch, canSearchLive, searchLive }
+}