@mailwoman/react 0.0.1 → 7.4.0

package/pipeline/ComponentTable.tsx

@@ -0,0 +1,41 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `ComponentTable` — the tag / value / confidence table of decoded components. Presentational.
+ */
+
+import type { ReactNode } from "react"
+
+import { ConfidenceCell } from "./ConfidenceCell.tsx"
+import type { ParsedComponent } from "./types.ts"
+
+export interface ComponentTableProps {
+	nodes: ParsedComponent[]
+}
+
+export function ComponentTable({ nodes }: ComponentTableProps): ReactNode {
+	return (
+		<table className="mw-components">
+			<thead>
+				<tr>
+					<th>tag</th>
+					<th>value</th>
+					<th>confidence</th>
+				</tr>
+			</thead>
+			<tbody>
+				{nodes.map((node, i) => (
+					<tr key={i}>
+						<td>{node.tag}</td>
+						<td>{String(node.value ?? "")}</td>
+						<td>
+							<ConfidenceCell confidence={node.confidence} />
+						</td>
+					</tr>
+				))}
+			</tbody>
+		</table>
+	)
+}

package/pipeline/ConfidenceCell.tsx

@@ -0,0 +1,33 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `ConfidenceCell` — a compact confidence bar + value for the component table. Tiers the fill colour
+ *   at 0.8 / 0.5. Presentational.
+ */
+
+import { cx } from "../common/cx.ts"
+
+function tier(confidence?: number): "high" | "mid" | "low" {
+	if (confidence == null) return "mid"
+
+	return confidence >= 0.8 ? "high" : confidence >= 0.5 ? "mid" : "low"
+}
+
+export interface ConfidenceCellProps {
+	confidence?: number
+}
+
+export function ConfidenceCell({ confidence }: ConfidenceCellProps) {
+	if (confidence == null) return <span className="mw-conf__dash">—</span>
+
+	const pct = Math.max(0, Math.min(1, confidence)) * 100
+
+	return (
+		<div className="mw-conf">
+			<div className={cx("mw-conf__bar", `mw-conf__bar--${tier(confidence)}`)} style={{ width: `${pct}%` }} />
+			<span className="mw-conf__value">{confidence.toFixed(2)}</span>
+		</div>
+	)
+}

package/pipeline/PipelineExplorer.tsx

@@ -0,0 +1,148 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `PipelineExplorer` — the composed parse+resolve tester. Drives the injected {@link PipelineRuntime}
+ *   through {@link useParsePipeline}, renders the core result (kind badge, component table, resolved
+ *   place, candidate picker), and slots host-supplied panels (span highlight, tree, timing, …) around
+ *   it. No model/gazetteer code here — composition + a `ClientOnly` SSR boundary only.
+ */
+
+import type { ReactNode } from "react"
+
+import { ClientOnly } from "../common/ClientOnly.tsx"
+import { CopyButton } from "../common/CopyButton.tsx"
+import { KindBadge } from "../common/KindBadge.tsx"
+import { LoadingIndicator } from "../common/LoadingIndicator.tsx"
+import { PresetChips, type Preset } from "../common/PresetChips.tsx"
+import { CandidatePicker } from "./CandidatePicker.tsx"
+import { ComponentTable } from "./ComponentTable.tsx"
+import { buildParsePayload } from "./copy.ts"
+import { PIPELINE_DEFAULT_ADDRESS, PIPELINE_PRESETS } from "./presets.ts"
+import { QueryForm } from "./QueryForm.tsx"
+import { ResolvedPlace } from "./ResolvedPlace.tsx"
+import type { PipelinePanels, PipelineRuntime } from "./types.ts"
+import { useParsePipeline } from "./useParsePipeline.ts"
+
+export interface PipelineExplorerProps {
+	/** The injected model/gazetteer runtime (the host wires this to its bundle). */
+	runtime: PipelineRuntime
+	/** Address to pre-fill. @default the White House */
+	defaultAddress?: string
+	/** Example chips. @default the built-in address presets */
+	presets?: ReadonlyArray<Preset>
+	/** Host-injected panels + controls (version selector, span highlight, tree, …). */
+	panels?: PipelinePanels
+}
+
+interface PipelineExplorerInnerProps extends Required<Pick<PipelineExplorerProps, "runtime" | "defaultAddress">> {
+	presets: ReadonlyArray<Preset>
+	panels: PipelinePanels
+}
+
+function PipelineExplorerInner({ runtime, defaultAddress, presets, panels }: PipelineExplorerInnerProps): ReactNode {
+	const pipeline = useParsePipeline({ runtime, defaultText: defaultAddress })
+	const { text, setText, busy, parseStage, result, parseError, selectedCandidate } = pipeline
+
+	const loading = runtime.loading
+	const errorMessage = parseError ?? runtime.errorMessage ?? null
+
+	return (
+		<div className="mw-pipeline-explorer">
+			{panels.header}
+			{panels.releaseInfo}
+			{panels.versionControl}
+			{panels.backendControl}
+
+			<QueryForm
+				value={text}
+				onChange={setText}
+				onSubmit={pipeline.submit}
+				disabled={!runtime.ready}
+				busy={busy}
+				placeholder={PIPELINE_DEFAULT_ADDRESS}
+			/>
+
+			<PresetChips
+				presets={presets}
+				disabled={!runtime.ready || busy}
+				onPick={(value) => {
+					setText(value)
+					pipeline.reset()
+				}}
+			/>
+
+			{loading && !runtime.ready ? (
+				<LoadingIndicator
+					mode="staged"
+					steps={loading.stepLabels.length > 0 ? loading.stepLabels : undefined}
+					activeStep={loading.stepIndex}
+					label={loading.progress}
+				/>
+			) : null}
+			{errorMessage ? <p className="mw-error">{errorMessage}</p> : null}
+
+			{busy ? (
+				<div className="mw-result">
+					<LoadingIndicator mode="staged" steps={runtime.parseStageLabels} activeStep={parseStage} />
+				</div>
+			) : result ? (
+				<div className="mw-result">
+					<div className="mw-result__header">
+						<h2>Parsed components</h2>
+						<CopyButton
+							value={() => buildParsePayload(result, selectedCandidate)}
+							label="Copy JSON"
+							copiedLabel="✓ Copied"
+						/>
+					</div>
+
+					{result.kindResult ? <KindBadge kindResult={result.kindResult} /> : null}
+
+					{panels.extras ? panels.extras(result) : null}
+
+					<ComponentTable nodes={result.nodes} />
+
+					{selectedCandidate ? (
+						<>
+							<ResolvedPlace place={selectedCandidate} dualRoles={result.dualRoles} />
+							{result.candidates.length > 1 ? (
+								<CandidatePicker
+									candidates={result.candidates}
+									selectedIndex={pipeline.selectedCandidateIndex}
+									onSelect={pipeline.selectCandidate}
+								/>
+							) : null}
+						</>
+					) : panels.failure ? (
+						panels.failure(result)
+					) : null}
+				</div>
+			) : null}
+
+			{panels.footer}
+		</div>
+	)
+}
+
+export function PipelineExplorer({
+	runtime,
+	defaultAddress = PIPELINE_DEFAULT_ADDRESS,
+	presets = PIPELINE_PRESETS,
+	panels = {},
+}: PipelineExplorerProps): ReactNode {
+	return (
+		<ClientOnly
+			fallback={
+				<div className="mw-pipeline-explorer">
+					<p>Loading demo embed…</p>
+				</div>
+			}
+		>
+			{() => (
+				<PipelineExplorerInner runtime={runtime} defaultAddress={defaultAddress} presets={presets} panels={panels} />
+			)}
+		</ClientOnly>
+	)
+}

package/pipeline/QueryForm.tsx

@@ -0,0 +1,52 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `QueryForm` — the address input + submit button for the pipeline explorer. Shows a spinner while
+ *   parsing. Presentational; `onSubmit` fires on form submission.
+ */
+
+import type { ReactNode } from "react"
+
+import { LoadingIndicator } from "../common/LoadingIndicator.tsx"
+
+export interface QueryFormProps {
+	value: string
+	onChange: (value: string) => void
+	onSubmit: () => void
+	disabled?: boolean
+	busy?: boolean
+	placeholder?: string
+}
+
+export function QueryForm({ value, onChange, onSubmit, disabled, busy, placeholder }: QueryFormProps): ReactNode {
+	return (
+		<form
+			className="mw-field"
+			onSubmit={(e) => {
+				e.preventDefault()
+				onSubmit()
+			}}
+		>
+			<label htmlFor="mw-pipeline-input">Address</label>
+			<input
+				id="mw-pipeline-input"
+				type="text"
+				value={value}
+				onChange={(e) => onChange(e.target.value)}
+				disabled={disabled}
+				placeholder={placeholder}
+			/>
+			<button type="submit" disabled={disabled || busy}>
+				{busy ? (
+					<>
+						<LoadingIndicator mode="spinner" size="small" /> Parsing…
+					</>
+				) : (
+					"Parse + resolve"
+				)}
+			</button>
+		</form>
+	)
+}

package/pipeline/ResolvedPlace.tsx

@@ -0,0 +1,50 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `ResolvedPlace` — the "Resolved place" detail list (name, placetype, WOF id, coords, score) plus an
+ *   optional dual-role note. Presentational.
+ */
+
+import { Fragment, type ReactNode } from "react"
+
+import type { DualRoleView, ResolvedPlaceView } from "./types.ts"
+
+export interface ResolvedPlaceProps {
+	place: ResolvedPlaceView
+	dualRoles?: DualRoleView[]
+}
+
+export function ResolvedPlace({ place, dualRoles }: ResolvedPlaceProps): ReactNode {
+	return (
+		<div className="mw-resolved">
+			<h2>Resolved place</h2>
+			<dl>
+				<dt>name</dt>
+				<dd>{place.name}</dd>
+				<dt>placetype</dt>
+				<dd>{place.placetype}</dd>
+				<dt>WOF id</dt>
+				<dd>{place.id}</dd>
+				<dt>coords</dt>
+				<dd>
+					{place.lat.toFixed(4)}, {place.lon.toFixed(4)}
+				</dd>
+				<dt>score</dt>
+				<dd>{place.score.toFixed(3)}</dd>
+			</dl>
+			{dualRoles && dualRoles.length > 0 ? (
+				<p className="mw-resolved__dual">
+					🏛️ <strong>Dual-role place.</strong> {place.name} also resolves as{" "}
+					{dualRoles.map((role, i) => (
+						<Fragment key={`${role.role}-${role.id}`}>
+							{i > 0 ? ", " : ""}a <strong>{role.role}</strong> ({role.relationshipType.replace(/-/g, " ")})
+						</Fragment>
+					))}
+					.
+				</p>
+			) : null}
+		</div>
+	)
+}

package/pipeline/copy.ts

@@ -0,0 +1,37 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Builds the "Copy JSON" payload for a parse result — the components + the selected resolved place,
+ *   pretty-printed. Pure; shared by the explorer's copy button.
+ */
+
+import type { ParseResult, ResolvedPlaceView } from "./types.ts"
+
+export function buildParsePayload(result: ParseResult, selected: ResolvedPlaceView | null): string {
+	return JSON.stringify(
+		{
+			input: result.input,
+			components: result.nodes.map((node) => ({
+				tag: node.tag,
+				value: node.value ?? null,
+				confidence: node.confidence ?? null,
+				start: node.start ?? null,
+				end: node.end ?? null,
+			})),
+			resolved: selected
+				? {
+						name: selected.name,
+						placetype: selected.placetype,
+						id: selected.id,
+						lat: selected.lat,
+						lon: selected.lon,
+						score: selected.score,
+					}
+				: null,
+		},
+		null,
+		2
+	)
+}

package/pipeline/presets.ts

@@ -0,0 +1,24 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Default query + example addresses for the pipeline explorer. Hosts can override via props; these
+ *   mirror the docs demo's set so the extracted component looks identical out of the box.
+ */
+
+import type { Preset } from "../common/PresetChips.tsx"
+
+export const PIPELINE_DEFAULT_ADDRESS = "1600 Pennsylvania Ave NW, Washington, DC 20500"
+
+export const PIPELINE_PRESETS: ReadonlyArray<Preset> = [
+	{ label: "White House", value: "1600 Pennsylvania Ave NW, Washington, DC 20500" },
+	{ label: "Apple Park", value: "1 Apple Park Way, Cupertino, CA 95014" },
+	{ label: "30 Rockefeller Plaza", value: "30 Rockefeller Plaza, New York, NY 10112" },
+	{ label: "Pier 39 SF", value: "Pier 39, San Francisco, CA 94133" },
+	{ label: "Wrigley Field", value: "1060 W Addison St, Chicago, IL 60613" },
+	{ label: "Space Needle", value: "400 Broad St, Seattle, WA 98109" },
+	{ label: "ZIP only", value: "90210" },
+	{ label: "Berlin (native order)", value: "Straußstraße 27, 12623 Berlin" },
+	{ label: "Paris (street fall-through)", value: "181 Rue du Chevaleret, Paris" },
+]

package/pipeline/types.ts

@@ -0,0 +1,118 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Types for the pipeline (parse + resolve) explorer. The model/gazetteer runtime is INJECTED as a
+ *   {@link PipelineRuntime}: this package owns the UI state machine + presentation, while the host
+ *   (the docs site's DemoEmbed, or any app) owns loading ONNX/WOF and executing a parse. That keeps
+ *   onnxruntime-web, sql.js-httpvfs, and node builtins entirely out of this package's browser graph.
+ */
+
+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`. */
+export interface ParsedComponent {
+	tag: string
+	value?: unknown
+	confidence?: number
+	start?: number
+	end?: number
+}
+
+/** A resolved gazetteer place, projected to what the "Resolved place" panel + copy payload need. */
+export interface ResolvedPlaceView {
+	id: number
+	name: string
+	placetype: string
+	lat: number
+	lon: number
+	score: number
+}
+
+/** An additional admin role a resolved place also fulfils (the dual-role / city-state relation, #402). */
+export interface DualRoleView {
+	id: number
+	name: string
+	placetype: string
+	relationshipType: string
+	role: string
+}
+
+/** 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. */
+export interface FSTProvenance {
+	builtAt: string
+	stateCount: number
+	placeCount: number
+	importanceMatches: number
+}
+
+/** 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. */
+	tree: unknown
+	nodes: ParsedComponent[]
+	kindResult?: KindBadgeResult
+	timing?: StageTiming
+	resolved: ResolvedPlaceView | null
+	candidates: ResolvedPlaceView[]
+	fstActive: boolean
+	fstProvenance?: FSTProvenance | null
+	dualRoles?: DualRoleView[]
+}
+
+/** Bundle-load progress surfaced before the runtime is `ready`. */
+export interface PipelineLoadingState {
+	progress?: string
+	stepLabels: string[]
+	stepIndex: number
+}
+
+/**
+ * The injected parse runtime. The host implements `runParse` (compute shape → classify → resolve) and reports load
+ * 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. */
+	ready: boolean
+	/** 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). */
+	parseStageLabels: string[]
+	/** Bundle-load progress (before `ready`). */
+	loading?: PipelineLoadingState | null
+	/** Error surfaced by the bundle load, distinct from a per-parse error. */
+	errorMessage?: string | null
+}
+
+/**
+ * Optional host-injected panels. Each is a function of the current parse result returning already-rendered content (the
+ * docs site's SpanHighlight, TreeView, TimingPanel, …). Kept as `ReactNode` thunks so this package needs neither those
+ * components nor their heavy data types.
+ */
+export interface PipelinePanels {
+	/** Rendered above the form (e.g. the docs "About this demo"). */
+	header?: ReactNode
+	/** Rendered below everything (e.g. a guided tour). */
+	footer?: ReactNode
+	/** Model-version selector, wired to the host's bundle state. */
+	versionControl?: ReactNode
+	/** Backend indicator + WASM toggle. */
+	backendControl?: ReactNode
+	/** One-line release blurb. */
+	releaseInfo?: ReactNode
+	/** 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). */
+	failure?: (result: ParseResult) => ReactNode
+}

package/pipeline/useParsePipeline.ts

@@ -0,0 +1,84 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `useParsePipeline` — the headless core of the pipeline explorer. Owns the query text, the
+ *   busy/stage flags, the parse result, and the candidate selection; delegates the actual parse+resolve
+ *   to the injected {@link PipelineRuntime}. No model or gazetteer code lives here — it just drives the
+ *   contract and shapes the UI state.
+ */
+
+import { useCallback, useState } from "react"
+
+import type { ParseResult, PipelineRuntime, ResolvedPlaceView } from "./types.ts"
+
+export interface UseParsePipelineOptions {
+	runtime: PipelineRuntime
+	defaultText: string
+}
+
+export interface UseParsePipeline {
+	text: string
+	setText: (text: string) => void
+	busy: boolean
+	/** 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. */
+	selectedCandidate: ResolvedPlaceView | null
+	/** 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). */
+	reset: () => void
+}
+
+export function useParsePipeline({ runtime, defaultText }: UseParsePipelineOptions): UseParsePipeline {
+	const [text, setText] = useState(defaultText)
+	const [busy, setBusy] = useState(false)
+	const [parseStage, setParseStage] = useState(-1)
+	const [result, setResult] = useState<ParseResult | null>(null)
+	const [selectedCandidateIndex, setSelectedCandidateIndex] = useState(0)
+	const [parseError, setParseError] = useState<string | null>(null)
+
+	const submit = useCallback(async () => {
+		if (!runtime.ready || busy) return
+
+		setBusy(true)
+		setParseStage(0)
+		setParseError(null)
+
+		try {
+			const parsed = await runtime.runParse(text, { onStage: setParseStage })
+			setSelectedCandidateIndex(0)
+			setResult(parsed)
+		} catch (err) {
+			setParseError(err instanceof Error ? err.message : String(err))
+		} finally {
+			setBusy(false)
+			setParseStage(-1)
+		}
+	}, [runtime, text, busy])
+
+	const reset = useCallback(() => setResult(null), [])
+
+	// Derived during render — no effect needed.
+	const selectedCandidate = result ? (result.candidates[selectedCandidateIndex] ?? result.candidates[0] ?? null) : null
+
+	return {
+		text,
+		setText,
+		busy,
+		parseStage,
+		result,
+		parseError,
+		selectedCandidateIndex,
+		selectCandidate: setSelectedCandidateIndex,
+		selectedCandidate,
+		submit,
+		reset,
+	}
+}

package/poi/AbstainPanel.tsx

@@ -0,0 +1,22 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `AbstainPanel` — shown when the query carries no POI intent (it parses as an address). Names the
+ *   classifier's kind so the abstention is legible. Presentational.
+ */
+
+import type { ReactNode } from "react"
+
+export interface AbstainPanelProps {
+	kind: string
+}
+
+export function AbstainPanel({ kind }: AbstainPanelProps): ReactNode {
+	return (
+		<p className="mw-muted">
+			No POI intent detected — parses as an address (kind <code>{kind}</code>).
+		</p>
+	)
+}

package/poi/LiveResultsBlock.tsx

@@ -0,0 +1,70 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `LiveResultsBlock` — the on-demand live poi.db search affordance: a "Search live" button plus the
+ *   idle / loading / error / results states. Presentational — all behavior comes in via props (the
+ *   `usePOISearch` hook owns the state machine + the injected probe).
+ */
+
+import type { ReactNode } from "react"
+
+import { formatDistance } from "./runtime.ts"
+import type { LiveSearchState } from "./types.ts"
+
+export interface LiveResultsBlockProps {
+	/** Category label for empty-state copy ("No hospital results near …"). */
+	categoryLabel: string
+	/** The location anchor the search runs against (empty ⇒ the button is disabled with a hint). */
+	anchor: string
+	state: LiveSearchState
+	onSearch: () => void
+}
+
+export function LiveResultsBlock({ categoryLabel, anchor, state, onSearch }: LiveResultsBlockProps): ReactNode {
+	const hasAnchor = anchor.trim().length > 0
+
+	return (
+		<div className="mw-live">
+			<div className="mw-panel__header">
+				<h3>Live results</h3>
+				<button
+					type="button"
+					className="mw-btn"
+					onClick={onSearch}
+					disabled={!hasAnchor || state.status === "loading"}
+					title={hasAnchor ? "Search the published poi.db layer" : 'Needs a location anchor (e.g. "near Springfield")'}
+				>
+					{state.status === "loading" ? "Searching…" : "Search live"}
+				</button>
+			</div>
+
+			{!hasAnchor ? (
+				<p className="mw-muted">Add a location anchor (e.g. "near Springfield") to search live.</p>
+			) : state.status === "error" ? (
+				<p className="mw-error">{state.message}</p>
+			) : state.status === "success" ? (
+				state.hits.length === 0 ? (
+					<p className="mw-muted">
+						No {categoryLabel.toLowerCase()} results near {state.centerName}.
+					</p>
+				) : (
+					<>
+						<p className="mw-live__caption">Near {state.centerName}, ranked by distance:</p>
+						<ul className="mw-live__results">
+							{state.hits.map((hit, i) => (
+								<li key={`${hit.name}-${i}`}>
+									<span className="mw-live__name">{hit.name}</span>
+									<span className="mw-live__meta">
+										{formatDistance(hit.distanceM)} · {hit.country}
+									</span>
+								</li>
+							))}
+						</ul>
+					</>
+				)
+			) : null}
+		</div>
+	)
+}