@mailwoman/react 0.0.1 → 7.4.0

package/out/poi/POIExplorer.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * @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 { useState } from "react";
+import { ClientOnly } from "../common/ClientOnly.js";
+import { KindBadge } from "../common/KindBadge.js";
+import { PresetChips } from "../common/PresetChips.js";
+import { AbstainPanel } from "./AbstainPanel.js";
+import { LiveResultsBlock } from "./LiveResultsBlock.js";
+import { OverpassBlock } from "./OverpassBlock.js";
+import { QueryInput } from "./QueryInput.js";
+import { POI_DEFAULT_TEXT, POI_PRESETS } from "./runtime.js";
+import { SubjectPanel } from "./SubjectPanel.js";
+import { usePOISearch } from "./usePOISearch.js";
+function POIExplorerInner({ defaultText, presets, loadRuntime, runLiveSearch }) {
+    const [text, setText] = useState(defaultText);
+    const { result, liveSearch, searchLive } = usePOISearch({ text, loadRuntime, runLiveSearch });
+    return (_jsxs("div", { className: "mw-poi-explorer", children: [_jsx(QueryInput, { id: "mw-poi-input", label: "Query", value: text, onChange: setText, placeholder: POI_DEFAULT_TEXT }), _jsx(PresetChips, { presets: presets, onPick: setText }), result ? (_jsxs("div", { className: "mw-result", children: [_jsx(KindBadge, { kindResult: result.kindResult }), result.subject ? (_jsxs(_Fragment, { children: [_jsx(SubjectPanel, { subject: result.subject }), _jsx(OverpassBlock, { overpassQL: result.overpassQL, overpassError: result.overpassError }), runLiveSearch && !result.subject.buildLocal ? (_jsx(LiveResultsBlock, { categoryLabel: result.subject.category.label, anchor: result.subject.remainder, state: liveSearch, onSearch: searchLive })) : null] })) : (_jsx(AbstainPanel, { kind: result.kindResult.kind }))] })) : null] }));
+}
+export function POIExplorer({ defaultText = POI_DEFAULT_TEXT, presets = POI_PRESETS, loadRuntime, runLiveSearch, }) {
+    return (_jsx(ClientOnly, { fallback: _jsx("div", { className: "mw-poi-explorer", children: _jsx("p", { children: "Loading POI tester\u2026" }) }), children: () => (_jsx(POIExplorerInner, { defaultText: defaultText, presets: presets, loadRuntime: loadRuntime, runLiveSearch: runLiveSearch })) }));
+}
+//# sourceMappingURL=POIExplorer.js.map

package/out/poi/POIExplorer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"POIExplorer.js","sourceRoot":"","sources":["../../poi/POIExplorer.tsx"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAkB,QAAQ,EAAE,MAAM,OAAO,CAAA;AAEhD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAA0B,CAAA;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAyB,CAAA;AACnD,OAAO,EAAE,WAAW,EAAe,MAAM,0BAA2B,CAAA;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAoB,CAAA;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAwB,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAqB,CAAA;AACnD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAkB,CAAA;AAC7C,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAoB,CAAA;AAEjD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAkBhD,SAAS,gBAAgB,CAAC,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAyB;IACpG,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAA;IAC7C,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,GAAG,YAAY,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,aAAa,EAAE,CAAC,CAAA;IAE7F,OAAO,CACN,eAAK,SAAS,EAAC,iBAAiB,aAC/B,KAAC,UAAU,IAAC,EAAE,EAAC,cAAc,EAAC,KAAK,EAAC,OAAO,EAAC,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,gBAAgB,GAAI,EAC7G,KAAC,WAAW,IAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAI,EAEjD,MAAM,CAAC,CAAC,CAAC,CACT,eAAK,SAAS,EAAC,WAAW,aACzB,KAAC,SAAS,IAAC,UAAU,EAAE,MAAM,CAAC,UAAU,GAAI,EAE3C,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CACjB,8BACC,KAAC,YAAY,IAAC,OAAO,EAAE,MAAM,CAAC,OAAO,GAAI,EACzC,KAAC,aAAa,IAAC,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,aAAa,EAAE,MAAM,CAAC,aAAa,GAAI,EAEpF,aAAa,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAC9C,KAAC,gBAAgB,IAChB,aAAa,EAAE,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,EAC5C,MAAM,EAAE,MAAM,CAAC,OAAO,CAAC,SAAS,EAChC,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,UAAU,GACnB,CACF,CAAC,CAAC,CAAC,IAAI,IACN,CACH,CAAC,CAAC,CAAC,CACH,KAAC,YAAY,IAAC,IAAI,EAAE,MAAM,CAAC,UAAU,CAAC,IAAI,GAAI,CAC9C,IACI,CACN,CAAC,CAAC,CAAC,IAAI,IACH,CACN,CAAA;AACF,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,EAC3B,WAAW,GAAG,gBAAgB,EAC9B,OAAO,GAAG,WAAW,EACrB,WAAW,EACX,aAAa,GACK;IAClB,OAAO,CACN,KAAC,UAAU,IACV,QAAQ,EACP,cAAK,SAAS,EAAC,iBAAiB,YAC/B,mDAA0B,GACrB,YAGN,GAAG,EAAE,CAAC,CACN,KAAC,gBAAgB,IAChB,WAAW,EAAE,WAAW,EACxB,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,WAAW,EACxB,aAAa,EAAE,aAAa,GAC3B,CACF,GACW,CACb,CAAA;AACF,CAAC"}

package/out/poi/QueryInput.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @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 declare function QueryInput({ id, label, value, onChange, placeholder }: QueryInputProps): ReactNode;
+//# sourceMappingURL=QueryInput.d.ts.map

package/out/poi/QueryInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryInput.d.ts","sourceRoot":"","sources":["../../poi/QueryInput.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,MAAM,WAAW,eAAe;IAC/B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAA;IACjC,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,EAAE,eAAe,GAAG,SAAS,CAOlG"}

package/out/poi/QueryInput.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function QueryInput({ id, label, value, onChange, placeholder }) {
+    return (_jsxs("div", { className: "mw-field", children: [_jsx("label", { htmlFor: id, children: label }), _jsx("input", { id: id, type: "text", value: value, onChange: (e) => onChange(e.target.value), placeholder: placeholder })] }));
+}
+//# sourceMappingURL=QueryInput.js.map

package/out/poi/QueryInput.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryInput.js","sourceRoot":"","sources":["../../poi/QueryInput.tsx"],"names":[],"mappings":";AAkBA,MAAM,UAAU,UAAU,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAmB;IACtF,OAAO,CACN,eAAK,SAAS,EAAC,UAAU,aACxB,gBAAO,OAAO,EAAE,EAAE,YAAG,KAAK,GAAS,EACnC,gBAAO,EAAE,EAAE,EAAE,EAAE,IAAI,EAAC,MAAM,EAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,WAAW,EAAE,WAAW,GAAI,IAC3G,CACN,CAAA;AACF,CAAC"}

package/out/poi/SubjectPanel.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @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 declare function SubjectPanel({ subject }: SubjectPanelProps): ReactNode;
+//# sourceMappingURL=SubjectPanel.d.ts.map

package/out/poi/SubjectPanel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubjectPanel.d.ts","sourceRoot":"","sources":["../../poi/SubjectPanel.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAEtC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C,MAAM,WAAW,iBAAiB;IACjC,OAAO,EAAE,UAAU,CAAA;CACnB;AAED,wBAAgB,YAAY,CAAC,EAAE,OAAO,EAAE,EAAE,iBAAiB,GAAG,SAAS,CA0BtE"}

package/out/poi/SubjectPanel.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+export function SubjectPanel({ subject }) {
+    return (_jsxs(_Fragment, { children: [_jsxs("div", { className: "mw-subject__row", children: [_jsx("span", { className: "mw-subject__chip", children: subject.category.label }), subject.buildLocal ? _jsx("span", { className: "mw-subject__badge", children: "build-local" }) : null] }), _jsxs("dl", { className: "mw-subject__detail", children: [_jsx("dt", { children: "matched phrase" }), _jsx("dd", { children: _jsx("code", { children: subject.matchedPhrase }) }), _jsx("dt", { children: "confidence" }), _jsxs("dd", { children: [Math.round(subject.confidence * 100), "%"] }), _jsx("dt", { children: "anchor" }), _jsx("dd", { children: subject.remainder ? subject.remainder : _jsx("em", { children: "none \u2014 global query" }) })] }), subject.buildLocal ? (_jsx("p", { className: "mw-subject__note", children: "Requires the locally-built OSM layer (ODbL) \u2014 mailwoman ships the builder, not the data." })) : null] }));
+}
+//# sourceMappingURL=SubjectPanel.js.map

package/out/poi/SubjectPanel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubjectPanel.js","sourceRoot":"","sources":["../../poi/SubjectPanel.tsx"],"names":[],"mappings":";AAiBA,MAAM,UAAU,YAAY,CAAC,EAAE,OAAO,EAAqB;IAC1D,OAAO,CACN,8BACC,eAAK,SAAS,EAAC,iBAAiB,aAC/B,eAAM,SAAS,EAAC,kBAAkB,YAAE,OAAO,CAAC,QAAQ,CAAC,KAAK,GAAQ,EACjE,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,eAAM,SAAS,EAAC,mBAAmB,4BAAmB,CAAC,CAAC,CAAC,IAAI,IAC9E,EAEN,cAAI,SAAS,EAAC,oBAAoB,aACjC,0CAAuB,EACvB,uBACC,yBAAO,OAAO,CAAC,aAAa,GAAQ,GAChC,EACL,sCAAmB,EACnB,yBAAK,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,GAAG,GAAG,CAAC,SAAO,EAChD,kCAAe,EACf,uBAAK,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,oDAA4B,GAAM,IAC3E,EAEJ,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CACrB,YAAG,SAAS,EAAC,kBAAkB,8GAE3B,CACJ,CAAC,CAAC,CAAC,IAAI,IACN,CACH,CAAA;AACF,CAAC"}

package/out/poi/runtime.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @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 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 declare function loadPOIRuntime(): Promise<POIRuntime>;
+/** Default example queries for the POI explorer. */
+export declare const POI_PRESETS: readonly [{
+    readonly label: "Drinking fountain";
+    readonly value: "drinking fountain near Springfield";
+}, {
+    readonly label: "Fire hydrant";
+    readonly value: "fire hydrant";
+}, {
+    readonly label: "Hospital + address";
+    readonly value: "hospital, 350 5th Ave, New York";
+}, {
+    readonly label: "Biking trails";
+    readonly value: "biking trails near Portland";
+}];
+export declare const POI_DEFAULT_TEXT: "drinking fountain near Springfield";
+/** `742 m` under 1 km, `1.9 km` past it — matches the demo's distance captions. */
+export declare function formatDistance(distanceM: number): string;
+//# sourceMappingURL=runtime.d.ts.map

package/out/poi/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../poi/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C;;;GAGG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,UAAU,CAAC,CAc1D;AAED,oDAAoD;AACpD,eAAO,MAAM,WAAW;;;;;;;;;;;;EAKd,CAAA;AAEV,eAAO,MAAM,gBAAgB,sCAAuB,CAAA;AAEpD,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAIxD"}

package/out/poi/runtime.js

@@ -0,0 +1,43 @@
+/**
+ * @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 { createPOITaxonomyLookup } from "@mailwoman/poi-taxonomy/table";
+/**
+ * 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() {
+    const table = (await import("@mailwoman/poi-taxonomy/data/taxonomy.json")).default;
+    const lookup = createPOITaxonomyLookup(table);
+    // Adapt `POITaxonomyLookup.lookupPOICategory` to the `POIPhraseLookup` shape the classifier expects.
+    const lexicon = (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" },
+];
+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) {
+    if (distanceM < 1000)
+        return `${Math.round(distanceM)} m`;
+    return `${(distanceM / 1000).toFixed(1)} km`;
+}
+//# sourceMappingURL=runtime.js.map

package/out/poi/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../poi/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AAEjE,OAAO,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAA;AAIvE;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc;IACnC,MAAM,KAAK,GAAG,CAAC,MAAM,MAAM,CAAC,4CAA4C,CAAC,CAAC,CAAC,OAAO,CAAA;IAClF,MAAM,MAAM,GAAG,uBAAuB,CAAC,KAAiE,CAAC,CAAA;IAEzG,qGAAqG;IACrG,MAAM,OAAO,GAAoB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CACnD,MAAM,CAAC,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACxD,IAAI,EAAE,UAAU;QAChB,UAAU,EAAE,KAAK,CAAC,QAAQ,CAAC,EAAE;QAC7B,aAAa,EAAE,KAAK,CAAC,aAAa;QAClC,UAAU,EAAE,KAAK,CAAC,UAAU;KAC5B,CAAC,CAAC,CAAA;IAEJ,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,oBAAoB,CAAC,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,EAAE,CAAA;AACpF,CAAC;AAED,oDAAoD;AACpD,MAAM,CAAC,MAAM,WAAW,GAAG;IAC1B,EAAE,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,oCAAoC,EAAE;IAC3E,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,EAAE;IAChD,EAAE,KAAK,EAAE,oBAAoB,EAAE,KAAK,EAAE,iCAAiC,EAAE;IACzE,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,6BAA6B,EAAE;CACvD,CAAA;AAEV,MAAM,CAAC,MAAM,gBAAgB,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;AAEpD,mFAAmF;AACnF,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC/C,IAAI,SAAS,GAAG,IAAI;QAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAA;IAEzD,OAAO,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAA;AAC7C,CAAC"}

package/out/poi/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @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>;
+//# sourceMappingURL=types.d.ts.map

package/out/poi/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../poi/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAClF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAA;AACtE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAA;AAE5E,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAA;AACvE,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,UAAU,CAAC,cAAc,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAA;AAEtF,gHAAgH;AAChH,MAAM,WAAW,UAAU;IAC1B,MAAM,EAAE,cAAc,CAAA;IACtB,OAAO,EAAE,eAAe,CAAA;IACxB,QAAQ,EAAE,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAA;CACjD;AAED,qFAAqF;AACrF,MAAM,WAAW,UAAU;IAC1B,QAAQ,EAAE,cAAc,CAAA;IACxB,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,6FAA6F;IAC7F,SAAS,EAAE,MAAM,CAAA;IACjB,oGAAoG;IACpG,UAAU,EAAE,OAAO,CAAA;CACnB;AAED,yGAAyG;AACzG,MAAM,WAAW,iBAAiB;IACjC,UAAU,EAAE,eAAe,CAAA;IAC3B,OAAO,CAAC,EAAE,UAAU,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,aAAa,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;CAClB;AAED;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAC5B;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,YAAY,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtC;IAAE,MAAM,EAAE,aAAa,CAAA;CAAE,CAAA;AAE5B;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE;IACpC,UAAU,EAAE,MAAM,CAAA;IAClB,mBAAmB,EAAE,MAAM,EAAE,CAAA;IAC7B,MAAM,EAAE,MAAM,CAAA;CACd,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAA;AAElC,mCAAmC;AACnC,MAAM,MAAM,eAAe,GACxB;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAClB;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,GACrB;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACpC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,YAAY,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAA;AAElE,qGAAqG;AACrG,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,CAAA"}

package/out/poi/types.js

@@ -0,0 +1,12 @@
+/**
+ * @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).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/out/poi/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../poi/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/out/poi/usePOISearch.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @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 type { LiveSearchState, LoadPOIRuntime, POIExplorerResult, POILiveSearch } 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>;
+}
+export declare function usePOISearch({ text, loadRuntime, runLiveSearch, debounceMs, }: UsePOISearchOptions): UsePOISearch;
+//# sourceMappingURL=usePOISearch.d.ts.map

package/out/poi/usePOISearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePOISearch.d.ts","sourceRoot":"","sources":["../../poi/usePOISearch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAUH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,iBAAiB,EAAE,aAAa,EAAc,MAAM,YAAY,CAAA;AAE/G,MAAM,WAAW,mBAAmB;IACnC,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAA;IACZ,8CAA8C;IAC9C,WAAW,CAAC,EAAE,cAAc,CAAA;IAC5B,oFAAoF;IACpF,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,YAAY;IAC5B,iDAAiD;IACjD,YAAY,EAAE,OAAO,CAAA;IACrB,oFAAoF;IACpF,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAChC,iDAAiD;IACjD,UAAU,EAAE,eAAe,CAAA;IAC3B,8GAA8G;IAC9G,aAAa,EAAE,OAAO,CAAA;IACtB,iGAAiG;IACjG,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/B;AA2BD,wBAAgB,YAAY,CAAC,EAC5B,IAAI,EACJ,WAA4B,EAC5B,aAAa,EACb,UAAgB,GAChB,EAAE,mBAAmB,GAAG,YAAY,CA2GpC"}

package/out/poi/usePOISearch.js

@@ -0,0 +1,123 @@
+/**
+ * @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 { computeQueryShape } from "@mailwoman/query-shape";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useDebouncedValue } from "../common/useDebouncedValue.js";
+import { loadPOIRuntime } from "./runtime.js";
+/** Compute the OverpassQL export for a matched subject, capturing any emitter error rather than throwing. */
+function buildOverpass(runtime, categoryID, matchedPhrase, remainder) {
+    const category = runtime.lookup.getPOICategory(categoryID);
+    if (!category) {
+        return {};
+    }
+    const intent = {
+        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, }) {
+    const [runtime, setRuntime] = useState(null);
+    const [result, setResult] = useState(null);
+    const [liveSearch, setLiveSearch] = useState({ 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 };
+}
+//# sourceMappingURL=usePOISearch.js.map

package/out/poi/usePOISearch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePOISearch.js","sourceRoot":"","sources":["../../poi/usePOISearch.ts"],"names":[],"mappings":"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"}

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.4.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.4.0",
+    "@mailwoman/poi-taxonomy": "7.4.0",
+    "@mailwoman/query-shape": "7.4.0"
+  },
+  "devDependencies": {
+    "@storybook/addon-docs": "^10.5.0",
+    "@storybook/react-vite": "^10.5.0",
+    "@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.0",
+    "vite": "^8.0.16",
+    "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>
+	)
+}