@mailwoman/react 8.0.0 → 8.2.0

package/pipeline/types.ts

@@ -13,7 +13,9 @@ import type { ReactNode } from "react"
 
 import type { KindBadgeResult } from "../common/KindBadge.tsx"
 
-/** One decoded component, as the table + span views render it. Offsets index into `ParseResult.input`. */
+/**
+ * One decoded component, as the table + span views render it. Offsets index into `ParseResult.input`.
+ */
 export interface ParsedComponent {
 	tag: string
 	value?: unknown
@@ -22,7 +24,9 @@ export interface ParsedComponent {
 	end?: number
 }
 
-/** A resolved gazetteer place, projected to what the "Resolved place" panel + copy payload need. */
+/**
+ * A resolved gazetteer place, projected to what the "Resolved place" panel + copy payload need.
+ */
 export interface ResolvedPlaceView {
 	id: number
 	name: string
@@ -32,7 +36,9 @@ export interface ResolvedPlaceView {
 	score: number
 }
 
-/** An additional admin role a resolved place also fulfils (the dual-role / city-state relation, #402). */
+/**
+ * An additional admin role a resolved place also fulfils (the dual-role / city-state relation, #402).
+ */
 export interface DualRoleView {
 	id: number
 	name: string
@@ -41,14 +47,18 @@ export interface DualRoleView {
 	role: string
 }
 
-/** Per-stage wall-clock (ms) for one parse. `resolve` is absent when the lookup is skipped. */
+/**
+ * Per-stage wall-clock (ms) for one parse. `resolve` is absent when the lookup is skipped.
+ */
 export interface StageTiming {
 	shape: number
 	classify: number
 	resolve?: number
 }
 
-/** FST gazetteer-prior provenance, as the "FST prior" disclosure renders it. */
+/**
+ * FST gazetteer-prior provenance, as the "FST prior" disclosure renders it.
+ */
 export interface FSTProvenance {
 	builtAt: string
 	stateCount: number
@@ -56,10 +66,14 @@ export interface FSTProvenance {
 	importanceMatches: number
 }
 
-/** The presentational projection of one parse+resolve. The host's `runParse` produces it. */
+/**
+ * The presentational projection of one parse+resolve. The host's `runParse` produces it.
+ */
 export interface ParseResult {
 	input: string
-	/** Opaque hierarchy — handed straight to a host-injected tree/visualizer panel. */
+	/**
+	 * Opaque hierarchy — handed straight to a host-injected tree/visualizer panel.
+	 */
 	tree: unknown
 	nodes: ParsedComponent[]
 	kindResult?: KindBadgeResult
@@ -71,7 +85,9 @@ export interface ParseResult {
 	dualRoles?: DualRoleView[]
 }
 
-/** Bundle-load progress surfaced before the runtime is `ready`. */
+/**
+ * Bundle-load progress surfaced before the runtime is `ready`.
+ */
 export interface PipelineLoadingState {
 	progress?: string
 	stepLabels: string[]
@@ -83,15 +99,25 @@ export interface PipelineLoadingState {
  * progress + errors. This package never imports the model or gazetteer — it only calls this contract.
  */
 export interface PipelineRuntime {
-	/** Whether the model/gazetteer bundle is ready to parse. */
+	/**
+	 * Whether the model/gazetteer bundle is ready to parse.
+	 */
 	ready: boolean
-	/** Execute a full parse+resolve, reporting stage progress via `onStage` (0-based index into `parseStageLabels`). */
+	/**
+	 * Execute a full parse+resolve, reporting stage progress via `onStage` (0-based index into `parseStageLabels`).
+	 */
 	runParse: (input: string, hooks: { onStage: (stage: number) => void }) => Promise<ParseResult>
-	/** Per-parse progress labels (differ by whether a gazetteer lookup is wired). */
+	/**
+	 * Per-parse progress labels (differ by whether a gazetteer lookup is wired).
+	 */
 	parseStageLabels: string[]
-	/** Bundle-load progress (before `ready`). */
+	/**
+	 * Bundle-load progress (before `ready`).
+	 */
 	loading?: PipelineLoadingState | null
-	/** Error surfaced by the bundle load, distinct from a per-parse error. */
+	/**
+	 * Error surfaced by the bundle load, distinct from a per-parse error.
+	 */
 	errorMessage?: string | null
 }
 
@@ -101,18 +127,32 @@ export interface PipelineRuntime {
  * components nor their heavy data types.
  */
 export interface PipelinePanels {
-	/** Rendered above the form (e.g. the docs "About this demo"). */
+	/**
+	 * Rendered above the form (e.g. the docs "About this demo").
+	 */
 	header?: ReactNode
-	/** Rendered below everything (e.g. a guided tour). */
+	/**
+	 * Rendered below everything (e.g. a guided tour).
+	 */
 	footer?: ReactNode
-	/** Model-version selector, wired to the host's bundle state. */
+	/**
+	 * Model-version selector, wired to the host's bundle state.
+	 */
 	versionControl?: ReactNode
-	/** Backend indicator + WASM toggle. */
+	/**
+	 * Backend indicator + WASM toggle.
+	 */
 	backendControl?: ReactNode
-	/** One-line release blurb. */
+	/**
+	 * One-line release blurb.
+	 */
 	releaseInfo?: ReactNode
-	/** Heavy visualizers (span highlight, tree, timing, BIO, …), rendered from the result. */
+	/**
+	 * Heavy visualizers (span highlight, tree, timing, BIO, …), rendered from the result.
+	 */
 	extras?: (result: ParseResult) => ReactNode
-	/** Rendered in place of the resolved-place panel when nothing resolved (host's FailureDiagnostic). */
+	/**
+	 * Rendered in place of the resolved-place panel when nothing resolved (host's FailureDiagnostic).
+	 */
 	failure?: (result: ParseResult) => ReactNode
 }

package/pipeline/useParsePipeline.ts

@@ -22,17 +22,25 @@ export interface UseParsePipeline {
 	text: string
 	setText: (text: string) => void
 	busy: boolean
-	/** 0-based index into `runtime.parseStageLabels`; -1 when idle. */
+	/**
+	 * 0-based index into `runtime.parseStageLabels`; -1 when idle.
+	 */
 	parseStage: number
 	result: ParseResult | null
 	parseError: string | null
 	selectedCandidateIndex: number
 	selectCandidate: (index: number) => void
-	/** The currently-selected candidate (falls back to the first), or null. */
+	/**
+	 * The currently-selected candidate (falls back to the first), or null.
+	 */
 	selectedCandidate: ResolvedPlaceView | null
-	/** Run a parse for the current text. Safe to bind to a form's `onSubmit`. */
+	/**
+	 * Run a parse for the current text. Safe to bind to a form's `onSubmit`.
+	 */
 	submit: () => Promise<void>
-	/** Clear the result (used when a preset replaces the input). */
+	/**
+	 * Clear the result (used when a preset replaces the input).
+	 */
 	reset: () => void
 }
 
@@ -55,8 +63,8 @@ export function useParsePipeline({ runtime, defaultText }: UseParsePipelineOptio
 			const parsed = await runtime.runParse(text, { onStage: setParseStage })
 			setSelectedCandidateIndex(0)
 			setResult(parsed)
-		} catch (err) {
-			setParseError(err instanceof Error ? err.message : String(err))
+		} catch (error) {
+			setParseError(error instanceof Error ? error.message : String(error))
 		} finally {
 			setBusy(false)
 			setParseStage(-1)

package/poi/LiveResultsBlock.tsx

@@ -14,9 +14,13 @@ import { formatDistance } from "./runtime.ts"
 import type { LiveSearchState } from "./types.ts"
 
 export interface LiveResultsBlockProps {
-	/** Subject label for empty-state copy — a category ("No hospital results near …") or a brand ("No chevron results …"). */
+	/**
+	 * Subject label for empty-state copy — a category ("No hospital results near …") or a brand ("No chevron results …").
+	 */
 	subjectLabel: string
-	/** The location anchor the search runs against (empty ⇒ the button is disabled with a hint). */
+	/**
+	 * The location anchor the search runs against (empty ⇒ the button is disabled with a hint).
+	 */
 	anchor: string
 	state: LiveSearchState
 	onSearch: () => void
@@ -45,7 +49,7 @@ export function LiveResultsBlock({ subjectLabel, anchor, state, onSearch }: Live
 			) : state.status === "error" ? (
 				<p className="mw-error">{state.message}</p>
 			) : state.status === "success" ? (
-				state.hits.length === 0 ? (
+				!state.hits.length ? (
 					<p className="mw-muted">
 						No {subjectLabel.toLowerCase()} results near {state.centerName}.
 					</p>

package/poi/POIExplorer.tsx

@@ -24,13 +24,21 @@ import type { LoadPOIRuntime, POILiveSearch } from "./types.ts"
 import { usePOISearch } from "./usePOISearch.ts"
 
 export interface POIExplorerProps {
-	/** Query to pre-fill in the input. */
+	/**
+	 * Query to pre-fill in the input.
+	 */
 	defaultText?: string
-	/** Example chips. @default the built-in POI presets */
+	/**
+	 * Example chips. @default the built-in POI presets
+	 */
 	presets?: ReadonlyArray<Preset>
-	/** Override the taxonomy-runtime loader (stories/tests inject a mock). */
+	/**
+	 * Override the taxonomy-runtime loader (stories/tests inject a mock).
+	 */
 	loadRuntime?: LoadPOIRuntime
-	/** Live poi.db probe. Absent ⇒ intent-only (no live-results affordance). */
+	/**
+	 * Live poi.db probe. Absent ⇒ intent-only (no live-results affordance).
+	 */
 	runLiveSearch?: POILiveSearch
 	/**
 	 * Whether {@link runLiveSearch} can serve BRAND subjects (fetch by QID). Default false: a brand subject shows the
@@ -53,6 +61,7 @@ function POIExplorerInner({
 	brandLiveSearch,
 }: POIExplorerInnerProps): ReactNode {
 	const [text, setText] = useState(defaultText)
+
 	const { result, liveSearch, searchLive } = usePOISearch({
 		text,
 		loadRuntime,
@@ -61,6 +70,7 @@ function POIExplorerInner({
 	})
 
 	const subject = result?.subject
+
 	// The live block appears whenever the subject COULD be live-searched with an anchor — i.e. capable minus the
 	// anchor-present requirement (`canSearchLive` also requires an anchor; the block itself renders the "add an anchor"
 	// hint, so it must show one step earlier). Category: not build-local. Brand: brand-capable probe + a QID.

package/poi/SubjectPanel.tsx

@@ -16,7 +16,9 @@ export interface SubjectPanelProps {
 	subject: POISubject
 }
 
-/** The shared match-detail list (matched phrase, confidence, anchor) — identical for category + brand subjects. */
+/**
+ * The shared match-detail list (matched phrase, confidence, anchor) — identical for category + brand subjects.
+ */
 function MatchDetail({ subject }: SubjectPanelProps): ReactNode {
 	return (
 		<dl className="mw-subject__detail">
@@ -27,7 +29,7 @@ function MatchDetail({ subject }: SubjectPanelProps): ReactNode {
 			<dt>confidence</dt>
 			<dd>{Math.round(subject.confidence * 100)}%</dd>
 			<dt>anchor</dt>
-			<dd>{subject.remainder ? subject.remainder : <em>none — global query</em>}</dd>
+			<dd>{subject.remainder || <em>none — global query</em>}</dd>
 		</dl>
 	)
 }

package/poi/runtime.ts

@@ -30,6 +30,7 @@ export async function loadPOIRuntime(): Promise<POIRuntime> {
 		import("@mailwoman/poi-taxonomy/data/taxonomy.json").then((m) => m.default),
 		import("@mailwoman/poi-taxonomy/data/brands.json").then((m) => m.default),
 	])
+
 	const lookup = createPOITaxonomyLookup(table as unknown as Parameters<typeof createPOITaxonomyLookup>[0])
 	const brands = createPOIBrandLookup(brandTable as unknown as Parameters<typeof createPOIBrandLookup>[0])
 
@@ -38,7 +39,7 @@ export async function loadPOIRuntime(): Promise<POIRuntime> {
 	const lexicon: POIPhraseLookup = (phrase, locale) => {
 		const categoryHits = lookup.lookupPOICategory(phrase, locale)
 
-		if (categoryHits.length > 0) {
+		if (categoryHits.length) {
 			return categoryHits.map((match) => ({
 				kind: "category",
 				categoryID: match.category.id,
@@ -59,7 +60,9 @@ export async function loadPOIRuntime(): Promise<POIRuntime> {
 	return { lookup, lexicon, classify: createKindClassifier({ poiLexicon: lexicon }) }
 }
 
-/** Default example queries for the POI explorer — a mix of category, build-local, and chain-brand subjects. */
+/**
+ * Default example queries for the POI explorer — a mix of category, build-local, and chain-brand subjects.
+ */
 export const POI_PRESETS = [
 	{ label: "Drinking fountain", value: "drinking fountain near Springfield" },
 	{ label: "Fire hydrant", value: "fire hydrant" },
@@ -68,9 +71,14 @@ export const POI_PRESETS = [
 	{ label: "Applebee's (brand)", value: "applebee's near Chicago" },
 ] as const
 
+/**
+ * Query the POI explorer opens on — the first preset, so the two stay in step.
+ */
 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. */
+/**
+ * `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`
 

package/poi/types.ts

@@ -9,33 +9,43 @@
  *   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 { POIPhraseLookup, QueryKindResult, 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. */
+/**
+ * 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>
 }
 
-/** Fields shared by every resolved POI subject, category or brand. */
+/**
+ * Fields shared by every resolved POI subject, category or brand.
+ */
 export interface POISubjectBase {
 	matchedPhrase: string
 	confidence: number
-	/** The non-subject remainder of the query (the location anchor, e.g. "near Springfield"). */
+	/**
+	 * The non-subject remainder of the query (the location anchor, e.g. "near Springfield").
+	 */
 	remainder: string
 }
 
-/** A resolved POI subject that names a taxonomy CATEGORY (`cafe`, `hospital`, `drinking fountain`). */
+/**
+ * A resolved POI subject that names a taxonomy CATEGORY (`cafe`, `hospital`, `drinking fountain`).
+ */
 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 needs the locally-built OSM (ODbL) layer — precomputed off the runtime.
+	 */
 	buildLocal: boolean
 }
 
@@ -46,16 +56,24 @@ export interface POICategorySubject extends POISubjectBase {
  */
 export interface POIBrandSubject extends POISubjectBase {
 	kind: "brand"
-	/** The brand's canonical display name. */
+	/**
+	 * The brand's canonical display name.
+	 */
 	name: string
-	/** Wikidata QID, when the lexicon carried one (`Q319642` = Chevron). Absent ⇒ matched by name alone. */
+	/**
+	 * Wikidata QID, when the lexicon carried one (`Q319642` = Chevron). Absent ⇒ matched by name alone.
+	 */
 	wikidata?: string
 }
 
-/** A resolved POI subject — a taxonomy category or a chain brand — plus its match metadata. */
+/**
+ * A resolved POI subject — a taxonomy category or a chain brand — plus its match metadata.
+ */
 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: the kind verdict plus (when a subject was detected) its OverpassQL export (category only).
+ */
 export interface POIExplorerResult {
 	kindResult: QueryKindResult
 	subject?: POISubject
@@ -63,7 +81,9 @@ export interface POIExplorerResult {
 	overpassError?: string
 }
 
-/** One live poi.db hit, as the results list renders it. */
+/**
+ * One live poi.db hit, as the results list renders it.
+ */
 export interface POISearchHit {
 	name: string
 	lat: number
@@ -97,16 +117,22 @@ 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. */
+	/**
+	 * Present when the subject is a chain brand — the probe fetches by this QID, not a category k-ring.
+	 */
 	brandWikidata?: string
 }) => Promise<POILiveSearchResult>
 
-/** "Search live" state machine. */
+/**
+ * "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. */
+/**
+ * A single-argument runtime loader — injectable so stories/tests can substitute a mock taxonomy.
+ */
 export type LoadPOIRuntime = () => Promise<POIRuntime>

package/poi/usePOISearch.ts

@@ -20,11 +20,17 @@ 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). */
+	/**
+	 * The current query text (controlled by the caller).
+	 */
 	text: string
-	/** Runtime loader. @default loadPOIRuntime */
+	/**
+	 * Runtime loader. @default loadPOIRuntime
+	 */
 	loadRuntime?: LoadPOIRuntime
-	/** Injected live-search probe. Absent ⇒ the live-results affordance is disabled. */
+	/**
+	 * Injected live-search probe. Absent ⇒ the live-results affordance is disabled.
+	 */
 	runLiveSearch?: POILiveSearch
 	/**
 	 * Whether the injected probe can serve BRAND subjects (fetch by Wikidata QID). Default false: brand subjects show the
@@ -33,24 +39,38 @@ export interface UsePOISearchOptions {
 	 * live search is unaffected either way.
 	 */
 	brandLiveSearch?: boolean
-	/** Debounce before (re)classifying. @default 250 */
+	/**
+	 * Debounce before (re)classifying. @default 250
+	 */
 	debounceMs?: number
 }
 
 export interface UsePOISearch {
-	/** True once the taxonomy runtime has loaded. */
+	/**
+	 * True once the taxonomy runtime has loaded.
+	 */
 	runtimeReady: boolean
-	/** The intent result for the current (debounced) query, or null for empty input. */
+	/**
+	 * 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. */
+	/**
+	 * 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). */
+	/**
+	 * 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. */
+	/**
+	 * 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. */
+/**
+ * Compute the OverpassQL export for a matched subject, capturing any emitter error rather than throwing.
+ */
 function buildOverpass(
 	runtime: POIRuntime,
 	categoryID: string,
@@ -70,8 +90,8 @@ function buildOverpass(
 
 	try {
 		return { overpassQL: emitOverpassQL(intent, category.osmTag ? { osmTag: category.osmTag } : {}) }
-	} catch (err) {
-		return { overpassError: err instanceof Error ? err.message : String(err) }
+	} catch (error) {
+		return { overpassError: error instanceof Error ? error.message : String(error) }
 	}
 }
 
@@ -184,12 +204,14 @@ export function usePOISearch({
 	}, [debouncedText, runtime])
 
 	const subject = result?.subject
+
 	// 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)
+
 	const canSearchLive = Boolean(
 		runLiveSearch && runtime && subject && subjectLiveCapable && subject.remainder.trim().length > 0
 	)