@mailwoman/react 7.5.0 → 7.7.0

package/runtime/useDemoRuntime.ts

@@ -0,0 +1,245 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `useDemoRuntime` — the headless load-orchestration hook shared by every mailwoman demo surface (the
+ *   inline doc-embeds via `DemoEmbed`, and the geocoder map page). It owns the version-selection state
+ *   machine, the per-version load SEQUENCING, cancellation, and the ready / loading / error state — but
+ *   NOTHING model- or map-specific. The actual asset fetchers (the ONNX classifier factory, the httpvfs
+ *   WOF opener, the FST fetch, the releases.json fetch) are INJECTED by the host as async functions, so
+ *   this module imports only React: no `onnxruntime-web`, no `sql.js-httpvfs`, no `maplibre-gl`, no
+ *   `fetch`-specific plumbing. That keeps it node-import-safe and root-exportable from
+ *   `@mailwoman/react` — the exact seam `PipelineRuntime` established, generalized to the loader itself.
+ *
+ *   The hook is generic over `TAssets` (the opaque bundle the host's `loadAssets` returns — classifier,
+ *   FST, WOF lookup, calibrator, …) and `TRelease` (the host's release-manifest entry). The package
+ *   never inspects either; it just holds, reveals, and re-loads them across version/backend switches.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react"
+
+/** The minimal contract a release-manifest entry must satisfy. Hosts extend this with their own fields. */
+export interface DemoReleaseBase {
+	/** The version tag this entry describes (matched against `selectedVersion`). */
+	version: string
+	/** Optional display label a version picker shows; falls back to `version`. */
+	label?: string
+}
+
+/** The releases manifest the host fetches — the default version plus the selectable release entries. */
+export interface DemoManifest<TRelease extends DemoReleaseBase = DemoReleaseBase> {
+	/** The version selected on first load (before the user picks another). */
+	defaultVersion: string
+	/** Every selectable release. */
+	releases: TRelease[]
+}
+
+/**
+ * The progress channel handed to the host's `loadAssets`. The host reports load progress + the resolved backend + the
+ * staged step labels/index THROUGH these setters (all no-op once the load is superseded/aborted), while the hook owns
+ * the terminal state (revealing the assets + clearing progress on success, surfacing the error on failure).
+ */
+export interface DemoAssetsLoadContext {
+	/** Aborts when this load is superseded (version/backend switch) or the provider unmounts. */
+	signal: AbortSignal
+	/** Whether the host should force the CPU/WASM backend (opt out of WebGPU) for this load. */
+	forceWASM: boolean
+	/** Set the human-readable progress line (e.g. `Loading v7 model (~28 MB)…`). */
+	setProgress: (progress: string) => void
+	/** Set the staged-loader step labels (e.g. `["Loading classifier", "Loading FST gazetteer"]`). */
+	setStepLabels: (labels: string[]) => void
+	/** Advance the staged-loader step index (0-based). */
+	setStepIndex: (index: number) => void
+	/** Report the backend the neural runtime resolved to (e.g. `webgpu (27 MB int8)`). */
+	setBackend: (backend: string) => void
+}
+
+/** The injected loaders the hook orchestrates. Nothing here is model- or map-aware — the host owns all that. */
+export interface DemoRuntimeConfig<TAssets, TRelease extends DemoReleaseBase = DemoReleaseBase> {
+	/**
+	 * Fetch + normalize the releases manifest. Returns `null` when no manifest is available (the demo then shows nothing
+	 * selectable). Rejecting surfaces `errorMessage`. Runs once on mount.
+	 */
+	loadManifest: (signal: AbortSignal) => Promise<DemoManifest<TRelease> | null>
+	/**
+	 * Load the full asset bundle for one release — the classifier, FST, WOF lookup, calibrator, whatever the host needs.
+	 * Runs on every version or `forceWASM` change. Report progress via `ctx`; return the bundle. Rejecting surfaces
+	 * `errorMessage`. Bail early when `ctx.signal.aborted` — the hook discards a superseded result regardless.
+	 */
+	loadAssets: (release: TRelease, ctx: DemoAssetsLoadContext) => Promise<TAssets>
+	/** The progress line shown before the manifest arrives. @default "Loading releases…" */
+	initialProgress?: string
+}
+
+/**
+ * The state `useDemoRuntime` produces — the load-orchestration state a demo surface renders + re-projects.
+ *
+ * NAMING (phase 4): this is the LOADER STATE, deliberately distinct from {@link DemoRuntime} (the injected runtime
+ * contract `<GeocoderDemo>` consumes). The two were same-stem before (`UseDemoRuntime` vs `DemoRuntime`); phase 4
+ * disambiguates by renaming the loader-state type to `DemoLoaderState`. A host builds a {@link DemoRuntime} by pairing
+ * this loader state (assets + backend + version) with the map surface (style, overlays, bias, parse) — see the map
+ * subpath's `DemoRuntime`.
+ */
+export interface DemoLoaderState<TAssets, TRelease extends DemoReleaseBase = DemoReleaseBase> {
+	/** The releases manifest, once fetched. */
+	manifest: DemoManifest<TRelease> | null
+	/** The currently-selected version, or `null` before the manifest resolves. */
+	selectedVersion: string | null
+	/** The release entry matching `selectedVersion` (convenience over `manifest.releases.find`). */
+	selectedRelease: TRelease | null
+	/** The loaded asset bundle for the selected version, or `null` while (re)loading. */
+	assets: TAssets | null
+	/** Whether the asset bundle is loaded and ready to use. */
+	ready: boolean
+	/** Human-readable load progress (`""` when idle/ready). */
+	loadingProgress: string
+	/** Staged-loader step index (0-based; `-1` before the first step). */
+	loadingStepIndex: number
+	/** Staged-loader step labels. */
+	loadingStepLabels: string[]
+	/** A load error (manifest or asset), distinct from any per-parse error a consumer tracks separately. */
+	errorMessage: string | null
+	/** The backend the neural runtime resolved to (e.g. `webgpu (27 MB int8)`), or `""` before it's known. */
+	activeBackend: string
+	/** Whether the CPU/WASM backend is currently forced. */
+	forceWASM: boolean
+	/** Switch to a different version (clears any error, then reloads the asset bundle). */
+	selectVersion: (version: string) => void
+	/** Force (or unforce) the CPU/WASM backend — reloads the asset bundle. */
+	setForceWASM: (forceWASM: boolean) => void
+}
+
+/**
+ * Drive the shared version → asset-bundle load state machine over a host-injected loader.
+ *
+ * Sequence: on mount `loadManifest` runs and its `defaultVersion` becomes the selection; each version (or `forceWASM`)
+ * change reloads the bundle via `loadAssets`, the previous load aborted first. The assets are revealed ATOMICALLY when
+ * `loadAssets` resolves (so `ready` flips exactly once per load), and consumers gate on `ready`.
+ */
+export function useDemoRuntime<TAssets, TRelease extends DemoReleaseBase = DemoReleaseBase>(
+	config: DemoRuntimeConfig<TAssets, TRelease>
+): DemoLoaderState<TAssets, TRelease> {
+	const { initialProgress = "Loading releases…" } = config
+
+	const [manifest, setManifest] = useState<DemoManifest<TRelease> | null>(null)
+	const [selectedVersion, setSelectedVersion] = useState<string | null>(null)
+	const [assets, setAssets] = useState<TAssets | null>(null)
+	const [loadingProgress, setLoadingProgress] = useState<string>(initialProgress)
+	const [loadingStepIndex, setLoadingStepIndex] = useState(-1)
+	const [loadingStepLabels, setLoadingStepLabels] = useState<string[]>([])
+	const [errorMessage, setErrorMessage] = useState<string | null>(null)
+	const [activeBackend, setActiveBackend] = useState<string>("")
+	const [forceWASM, setForceWASMState] = useState(false)
+
+	// Latest-ref the injected loaders: a host that re-creates them each render (an inline arrow) must NOT retrigger the
+	// load effects, which key ONLY on version/backend. The effects read `.current` at run time.
+	const loadManifestRef = useRef(config.loadManifest)
+	loadManifestRef.current = config.loadManifest
+	const loadAssetsRef = useRef(config.loadAssets)
+	loadAssetsRef.current = config.loadAssets
+
+	// Latest manifest for the version-load effect, so it can resolve the release WITHOUT depending on `manifest`
+	// identity — which would double-fire the load the instant the manifest first arrives (the selection transition
+	// null → defaultVersion already fires it once).
+	const manifestRef = useRef<DemoManifest<TRelease> | null>(null)
+	manifestRef.current = manifest
+
+	// Mount: fetch the manifest, then select the default version.
+	useEffect(() => {
+		const controller = new AbortController()
+
+		void (async () => {
+			try {
+				const data = await loadManifestRef.current(controller.signal)
+
+				if (controller.signal.aborted) return
+
+				if (data) {
+					setManifest(data)
+					setSelectedVersion(data.defaultVersion)
+				}
+			} catch (error) {
+				if (controller.signal.aborted) return
+				setErrorMessage(error instanceof Error ? error.message : String(error))
+			}
+		})()
+
+		return () => controller.abort()
+	}, [])
+
+	// Load the per-version asset bundle when the version (or the backend force) changes.
+	useEffect(() => {
+		if (!selectedVersion) return
+
+		const release = manifestRef.current?.releases.find((r) => r.version === selectedVersion) ?? null
+
+		if (!release) return
+
+		const controller = new AbortController()
+		const { signal } = controller
+		const guard = (fn: () => void) => {
+			if (!signal.aborted) {
+				fn()
+			}
+		}
+
+		void (async () => {
+			try {
+				setAssets(null)
+				setLoadingStepIndex(-1)
+				setLoadingStepLabels([])
+				setActiveBackend("")
+
+				const ctx: DemoAssetsLoadContext = {
+					signal,
+					forceWASM,
+					setProgress: (progress) => guard(() => setLoadingProgress(progress)),
+					setStepLabels: (labels) => guard(() => setLoadingStepLabels(labels)),
+					setStepIndex: (index) => guard(() => setLoadingStepIndex(index)),
+					setBackend: (backend) => guard(() => setActiveBackend(backend)),
+				}
+
+				const loaded = await loadAssetsRef.current(release, ctx)
+
+				if (signal.aborted) return
+				setAssets(loaded)
+				setLoadingProgress("")
+			} catch (error) {
+				if (signal.aborted) return
+				setErrorMessage(error instanceof Error ? error.message : String(error))
+				setLoadingProgress("")
+			}
+		})()
+
+		return () => controller.abort()
+	}, [selectedVersion, forceWASM])
+
+	const selectVersion = useCallback((version: string) => {
+		setSelectedVersion(version)
+		setErrorMessage(null)
+	}, [])
+
+	const setForceWASM = useCallback((next: boolean) => setForceWASMState(next), [])
+
+	const selectedRelease = useMemo(
+		() => manifest?.releases.find((r) => r.version === selectedVersion) ?? null,
+		[manifest, selectedVersion]
+	)
+
+	return {
+		manifest,
+		selectedVersion,
+		selectedRelease,
+		assets,
+		ready: assets !== null,
+		loadingProgress,
+		loadingStepIndex,
+		loadingStepLabels,
+		errorMessage,
+		activeBackend,
+		forceWASM,
+		selectVersion,
+		setForceWASM,
+	}
+}

package/styles.css

@@ -646,3 +646,148 @@
 	border-width: 0 2px 2px 0;
 	transform: translateY(-60%) rotate(45deg);
 }
+
+/* ── Demo map (react-map-gl/maplibre shell) ──────────────────────────────── */
+
+/*
+ * The <DemoMap> wrapper. Sizing is the host's call (pass `style`/`className`), but a min-height keeps
+ * the map from collapsing to zero when a consumer forgets. The inner <Map> fills 100% of this box.
+ * The host must ALSO import `maplibre-gl/dist/maplibre-gl.css` for the map's own control/canvas styles.
+ */
+.mw-demo-map {
+	position: relative;
+	width: 100%;
+	min-height: 320px;
+	overflow: hidden;
+}
+
+/* ── Geocoder demo (composed: full-viewport map + floating control panel) ──── */
+
+/*
+ * The demo fills its positioning context; the host sizes it (a full-viewport wrapper in docs). The map is the
+ * background layer, the control panel floats over the top-left (bottom on narrow screens). A host that wants a
+ * different layout can restyle these classes without touching the components.
+ */
+.mw-geocoder-demo {
+	position: relative;
+	width: 100%;
+	height: 100%;
+	min-height: 480px;
+}
+
+.mw-geocoder-demo__map {
+	position: absolute;
+	inset: 0;
+}
+
+.mw-demo-controls {
+	position: absolute;
+	top: 1rem;
+	left: 1rem;
+	z-index: 2;
+	width: min(360px, calc(100% - 2rem));
+	max-height: calc(100% - 2rem);
+	overflow-y: auto;
+	padding: 1rem;
+	border-radius: 10px;
+	background: color-mix(in srgb, var(--ifm-background-surface-color, #fff) 92%, transparent);
+	box-shadow: 0 2px 16px rgba(0, 0, 0, 0.18);
+	font-size: 0.95rem;
+}
+
+@media (max-width: 600px) {
+	.mw-demo-controls {
+		top: auto;
+		bottom: 1rem;
+		left: 1rem;
+		right: 1rem;
+		width: auto;
+	}
+}
+
+/* ── Demo control field (version / compare-version selects) ──────────────── */
+
+.mw-demo-control {
+	margin-bottom: 0.75rem;
+}
+
+.mw-demo-control__label {
+	display: block;
+	margin-bottom: 0.25rem;
+	font-weight: 600;
+	font-size: 0.9rem;
+}
+
+.mw-demo-control__select {
+	width: 100%;
+	padding: 0.4rem;
+	font: inherit;
+	border: 1px solid var(--ifm-color-emphasis-300, #d1d5db);
+	border-radius: 6px;
+	background: var(--ifm-background-surface-color, #fff);
+	color: var(--ifm-font-color-base, inherit);
+}
+
+.mw-demo-control__select:disabled {
+	opacity: 0.5;
+}
+
+/* ── Backend indicator + WASM toggle / compare toggle ────────────────────── */
+
+.mw-demo-backend,
+.mw-demo-compare {
+	display: flex;
+	align-items: center;
+	gap: 0.75rem;
+	flex-wrap: wrap;
+	margin-bottom: 0.75rem;
+	font-size: 0.85rem;
+}
+
+.mw-demo-compare {
+	display: block;
+}
+
+.mw-demo-backend__active {
+	opacity: 0.7;
+}
+
+.mw-demo-backend__toggle,
+.mw-demo-compare__toggle {
+	display: inline-flex;
+	align-items: center;
+	gap: 0.25rem;
+	cursor: pointer;
+	opacity: 0.8;
+}
+
+.mw-demo-compare__toggle {
+	margin-bottom: 0.5rem;
+}
+
+.mw-demo-compare__status {
+	margin: 0.25rem 0 0;
+	font-size: 0.8rem;
+	color: var(--ifm-color-emphasis-600, #6e6e6e);
+}
+
+/* ── Place autocomplete listbox (reuses .mw-chip) ────────────────────────── */
+
+.mw-demo-suggest {
+	margin-top: 0.75rem;
+	display: flex;
+	flex-wrap: wrap;
+	gap: 0.4rem;
+	align-items: baseline;
+}
+
+.mw-demo-suggest__label {
+	font-size: 0.85rem;
+	color: var(--ifm-color-emphasis-600, #6e6e6e);
+	margin-right: 0.25rem;
+}
+
+.mw-chip--active {
+	outline: 2px solid var(--ifm-color-primary, #e0367c);
+	outline-offset: 1px;
+}

package/vitest.node.config.ts

@@ -0,0 +1,20 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Node-mode vitest for `@mailwoman/react` — runs the PURE `*.node.test.ts` suites under bare node (no
+ *   browser, no WebGL, no map). Their existence is the proof that the geometry (`map/geometry.ts`) and
+ *   render-spec (`map/place-render.ts`) modules are side-effect-free and node-safe: if either grew a
+ *   `react-map-gl` / `maplibre-gl` / DOM import, these tests would fail to even load here. The browser
+ *   suite (`vitest.config.ts`) excludes these files, so this is the only entry that runs them.
+ */
+
+import { defineConfig } from "vitest/config"
+
+export default defineConfig({
+	test: {
+		environment: "node",
+		include: ["**/*.node.test.ts"],
+	},
+})