@mailwoman/react 0.0.1 → 7.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mailwoman/react",
-  "version": "0.0.1",
-  "description": "React components + headless hooks for mailwoman — parse/geocode/POI explorers, Storybook-tested, Docusaurus-independent. 0.0.1 is a name-reservation placeholder; the first functional release ships with the next mailwoman minor.",
+  "version": "7.5.0",
+  "description": "React components + headless hooks for mailwoman — parse/geocode/POI explorers, Storybook-tested, Docusaurus-independent.",
   "license": "AGPL-3.0-only OR LicenseRef-Commercial",
   "repository": {
     "type": "git",
@@ -13,6 +13,8 @@
     "out/**/*.js.map",
     "out/**/*.d.ts",
     "out/**/*.d.ts.map",
+    "README.md",
+    "styles.css",
     "*.ts",
     "*.tsx",
     "**/*.ts",
@@ -20,21 +22,63 @@
     "!*.test.ts",
     "!*.test.tsx",
     "!**/*.test.ts",
-    "!**/*.test.tsx"
+    "!**/*.test.tsx",
+    "!**/*.stories.ts",
+    "!**/*.stories.tsx",
+    "!.storybook/**",
+    "!vitest.config.ts",
+    "!test/**",
+    "!out/test/**",
+    "!out/storybook-static/**",
+    "!storybook-static/**"
   ],
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
+    "./styles.css": "./styles.css",
     ".": {
-      "node": "./index.ts",
-      "default": "./out/index.js",
-      "types": "./out/index.d.ts"
+      "types": "./out/index.d.ts",
+      "default": "./out/index.js"
     }
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "exports": {
+      "./package.json": "./package.json",
+      "./styles.css": "./styles.css",
+      ".": {
+        "types": "./out/index.d.ts",
+        "default": "./out/index.js"
+      }
+    }
+  },
+  "scripts": {
+    "storybook": "storybook dev -p 6007 --no-open",
+    "build-storybook": "storybook build",
+    "test:browser": "vitest run --config vitest.config.ts"
+  },
+  "dependencies": {
+    "@mailwoman/kind-classifier": "7.5.0",
+    "@mailwoman/poi-taxonomy": "7.5.0",
+    "@mailwoman/query-shape": "7.5.0"
+  },
+  "devDependencies": {
+    "@storybook/addon-docs": "^10.5.2",
+    "@storybook/react-vite": "^10.5.2",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.3",
+    "@vitest/browser": "4.1.10",
+    "@vitest/browser-playwright": "4.1.10",
+    "playwright": "^1.61.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "storybook": "^10.5.2",
+    "vite": "^8.1.5",
+    "vitest": "4.1.10"
   },
   "peerDependencies": {
-    "react": ">=18"
+    "react": ">=18",
+    "react-dom": ">=18"
   }
 }

package/pipeline/CandidatePicker.tsx

@@ -0,0 +1,45 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `CandidatePicker` — the ranked list of alternate gazetteer candidates; clicking one selects it.
+ *   Presentational; the selected index is owned by the caller (the pipeline hook).
+ */
+
+import type { ReactNode } from "react"
+
+import { cx } from "../common/cx.ts"
+import type { ResolvedPlaceView } from "./types.ts"
+
+export interface CandidatePickerProps {
+	candidates: ResolvedPlaceView[]
+	selectedIndex: number
+	onSelect: (index: number) => void
+}
+
+export function CandidatePicker({ candidates, selectedIndex, onSelect }: CandidatePickerProps): ReactNode {
+	return (
+		<div className="mw-candidates">
+			<h2>Other candidates ({candidates.length - 1})</h2>
+			<ol className="mw-candidates__list">
+				{candidates.map((candidate, i) => (
+					<li key={`${candidate.id}-${i}`}>
+						<button
+							type="button"
+							className={cx("mw-candidates__btn", { "mw-candidates__btn--active": i === selectedIndex })}
+							onClick={() => onSelect(i)}
+							title={`${candidate.placetype} • WOF ${candidate.id} • score ${candidate.score.toFixed(3)}`}
+						>
+							<span className="mw-candidates__rank">#{i + 1}</span>
+							<span className="mw-candidates__name">{candidate.name}</span>
+							<span className="mw-candidates__meta">
+								{candidate.placetype} · {candidate.score.toFixed(2)}
+							</span>
+						</button>
+					</li>
+				))}
+			</ol>
+		</div>
+	)
+}

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
+}