@poodle64/ui 2026.8.11 → 2026.8.13

package/dist/components/ui/schema-form/widgets/unknown-field.svelte

@@ -0,0 +1,123 @@
+<script lang="ts">
+	import TriangleAlert from '@lucide/svelte/icons/triangle-alert';
+	import StatusBadge from '../../status-badge/status-badge.svelte';
+	import Input from '../../input/input.svelte';
+	import Label from '../../label/label.svelte';
+	import type { JsonSchema, UnknownReason } from '../types.js';
+	import { schemaType } from '../dispatch.js';
+
+	/**
+	 * THE LOUD FALLBACK — the reason this package exists rather than a fourth
+	 * hand-rolled renderer.
+	 *
+	 * The estate's outgoing renderers failed silently in three ways: an
+	 * unrecognised `widget` hint rendered no input, a config group missing from a
+	 * hardcoded order rendered nothing at all, and a nested hint was simply
+	 * inert. Every one of those made the field VANISH, and a form with a missing
+	 * field looks exactly like a form. Nobody noticed for months.
+	 *
+	 * So there is no silent branch anywhere in `<SchemaForm>`: everything the
+	 * renderer cannot dispatch lands here, and here always renders. It says what
+	 * it could not do, names the pointer so the fix is a copy-paste, shows the
+	 * value that would otherwise have been lost, and keeps it editable whenever
+	 * editing a raw value is safe — which is when the value is a primitive. An
+	 * object or an array is shown, not edited: a text box over structured data
+	 * is a data-loss affordance, not a fallback.
+	 */
+	let {
+		label,
+		scope,
+		path,
+		reason,
+		detail,
+		value,
+		schema,
+		disabled = false,
+		id,
+		onchange
+	}: {
+		label: string;
+		/** JSON Pointer this control addressed, or the property's own pointer. */
+		scope: string;
+		/** Dot path into the value. */
+		path: string;
+		reason: UnknownReason;
+		/** What specifically could not be done, in one sentence. */
+		detail: string;
+		value: unknown;
+		schema?: JsonSchema;
+		disabled?: boolean;
+		id: string;
+		/** Emitted when the raw editor commits a primitive. */
+		onchange?: (next: unknown) => void;
+	} = $props();
+
+	// Editing is offered only where a text box can round-trip the value without
+	// destroying structure: a primitive, or an absent value under a primitive
+	// schema. Anything structured is shown read-only.
+	const declared = $derived(schemaType(schema));
+	const structural = $derived(
+		(value !== null && typeof value === 'object') || declared === 'object' || declared === 'array'
+	);
+	const editable = $derived(!structural);
+
+	const raw = $derived(
+		value === undefined || value === null
+			? ''
+			: typeof value === 'object'
+				? JSON.stringify(value, null, 2)
+				: String(value)
+	);
+
+	/** Coerce the typed text back to the schema's declared type where it can. */
+	function commit(text: string) {
+		if (declared === 'number' || declared === 'integer') {
+			const parsed = text.trim() === '' ? undefined : Number(text);
+			onchange?.(parsed !== undefined && Number.isFinite(parsed) ? parsed : text);
+			return;
+		}
+		if (declared === 'boolean') {
+			if (text === 'true' || text === 'false') return onchange?.(text === 'true');
+		}
+		onchange?.(text);
+	}
+</script>
+
+<div
+	role="group"
+	aria-label="Unrecognised field: {label}"
+	data-schema-form-unknown=""
+	data-unknown-reason={reason}
+	data-path={path}
+	class="border-status-warning/50 bg-status-warning/5 grid gap-2 rounded-lg border border-dashed p-3"
+>
+	<div class="flex flex-wrap items-center gap-2">
+		<TriangleAlert class="text-status-warning size-4 shrink-0" aria-hidden="true" />
+		<span class="text-body font-semibold">{label}</span>
+		<StatusBadge status="warning" label="Unrecognised control" />
+	</div>
+
+	<p class="text-muted-foreground text-xs">
+		{detail}. Rendered raw and unstyled so the value is not lost, at
+		<code class="font-mono">{scope}</code>
+	</p>
+
+	{#if editable}
+		<Label for={id} class="text-2xs text-muted-foreground uppercase">Raw value</Label>
+		<Input
+			{id}
+			{disabled}
+			value={raw}
+			class="font-mono"
+			oninput={(event) => commit((event.currentTarget as HTMLInputElement).value)}
+		/>
+	{:else}
+		<pre
+			data-schema-form-unknown-readonly=""
+			class="bg-surface-1 border-border text-muted-foreground max-h-48 overflow-auto rounded-md border p-2 font-mono text-xs">{raw ||
+				'(no value)'}</pre>
+		<p class="text-muted-foreground text-xs">
+			Structured value: shown, not edited, so nothing is silently rewritten.
+		</p>
+	{/if}
+</div>

package/dist/components/ui/schema-form/widgets/unknown-field.svelte.d.ts

@@ -0,0 +1,20 @@
+import type { JsonSchema, UnknownReason } from '../types.js';
+type $$ComponentProps = {
+    label: string;
+    /** JSON Pointer this control addressed, or the property's own pointer. */
+    scope: string;
+    /** Dot path into the value. */
+    path: string;
+    reason: UnknownReason;
+    /** What specifically could not be done, in one sentence. */
+    detail: string;
+    value: unknown;
+    schema?: JsonSchema;
+    disabled?: boolean;
+    id: string;
+    /** Emitted when the raw editor commits a primitive. */
+    onchange?: (next: unknown) => void;
+};
+declare const UnknownField: import("svelte").Component<$$ComponentProps, {}, "">;
+type UnknownField = ReturnType<typeof UnknownField>;
+export default UnknownField;

package/dist/components/ui/search-results/index.d.ts

@@ -0,0 +1,3 @@
+export { default as SearchResults } from './search-results.svelte';
+export { default } from './search-results.svelte';
+export type { LibraryBadge, LibrarySearchResult, SearchSnippetSegment } from '../library-browse/types.js';

package/dist/components/ui/search-results/index.js

@@ -0,0 +1,2 @@
+export { default as SearchResults } from './search-results.svelte';
+export { default } from './search-results.svelte';

package/dist/components/ui/search-results/search-results.svelte

@@ -0,0 +1,187 @@
+<script lang="ts">
+	/**
+	 * SearchResults — a ranked retrieval answer: for each hit, the document's
+	 * title, the passage that matched (with the matching spans emphasised), a
+	 * source chip, consumer-mapped state, and a relevance figure.
+	 *
+	 * Designed, not extracted (#30): no in-repo view existed to generalise
+	 * from. The shape follows the documentation-search results pattern — title
+	 * over highlighted snippet over source — rendered in this package's own
+	 * vocabulary: the highlight is a tint of the app's accent so every
+	 * consumer's results wear its own palette; the score is a mono, tabular
+	 * figure per the machine-value rule; state chips are StatusBadge.
+	 *
+	 * Fixed props over plain data: the page owns the query and the fetch, and
+	 * this only renders the answer. `<ol>` because rank IS the meaning.
+	 */
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { cn, type WithElementRef } from '../../../utils.js';
+	import SearchIcon from '@lucide/svelte/icons/search';
+	import Button from '../button/button.svelte';
+	import StatusBadge from '../status-badge/status-badge.svelte';
+	import EmptyState from '../empty-state/empty-state.svelte';
+	import ErrorState from '../error-state/error-state.svelte';
+	import LoadingState from '../loading-state/loading-state.svelte';
+	import type { LibrarySearchResult, SearchSnippetSegment } from '../library-browse/types.js';
+
+	let {
+		results,
+		query = '',
+		total,
+		loading = false,
+		error = null,
+		promptTitle = 'Search the catalogue',
+		promptDescription = 'Results appear here as you search.',
+		noResultsTitle,
+		noResultsDescription = 'Try a broader term, or search a different collection.',
+		resultHref,
+		onOpen,
+		onRetry,
+		ref = $bindable(null),
+		class: className,
+		...restProps
+	}: WithElementRef<Omit<HTMLAttributes<HTMLDivElement>, 'results'>> & {
+		/** `Omit` above: svelte/elements declares a legacy `results` HTML
+		 *  attribute (number) on every element, and without the omission this
+		 *  prop's type silently intersects with it — callers then cannot pass
+		 *  an array at all. Caught by CI's svelte-check on the test call sites. */
+		results: LibrarySearchResult[];
+		/** The term the page searched for; shown in the count line and empty copy. */
+		query?: string;
+		/** Total hits when the page truncates; defaults to the rows given. */
+		total?: number;
+		loading?: boolean;
+		error?: string | null;
+		/** Copy for the surface before any search has been made. */
+		promptTitle?: string;
+		promptDescription?: string;
+		/** Copy when a search matched nothing; defaults name the query. */
+		noResultsTitle?: string;
+		noResultsDescription?: string;
+		/** The app's own routed link per hit; this package has no router. */
+		resultHref?: (result: LibrarySearchResult) => string;
+		onOpen?: (result: LibrarySearchResult) => void;
+		onRetry?: () => void;
+	} = $props();
+
+	const shownTotal = $derived(total ?? results.length);
+
+	/** Normalise a snippet: plain text becomes one unhighlighted segment. */
+	function segments(snippet: string | SearchSnippetSegment[]): SearchSnippetSegment[] {
+		return typeof snippet === 'string' ? [{ text: snippet }] : snippet;
+	}
+
+	/** Relevance as a whole percentage; the wire value is [0, 1]. */
+	function pct(score: number): number {
+		return Math.round(Math.min(1, Math.max(0, score)) * 100);
+	}
+</script>
+
+<div bind:this={ref} class={cn('flex flex-col gap-3', className)} {...restProps}>
+	{#if loading}
+		<LoadingState message="Searching…" />
+	{:else if error}
+		<ErrorState message={error}>
+			{#snippet action()}
+				{#if onRetry}
+					<Button variant="outline" onclick={onRetry}>Retry</Button>
+				{/if}
+			{/snippet}
+		</ErrorState>
+	{:else if results.length === 0}
+		{#if query}
+			<EmptyState
+				icon={SearchIcon}
+				title={noResultsTitle ?? `No results for “${query}”`}
+				description={noResultsDescription}
+			/>
+		{:else}
+			<EmptyState icon={SearchIcon} title={promptTitle} description={promptDescription} />
+		{/if}
+	{:else}
+		<p class="text-muted-foreground text-sm">
+			<span class="font-mono tabular-nums">{shownTotal}</span>
+			result{shownTotal === 1 ? '' : 's'}{query ? ` for “${query}”` : ''}
+		</p>
+
+		<ol class="divide-border border-border ds-edge bg-card divide-y rounded-lg border">
+			{#each results as result (result.id)}
+				<li>
+					<article class="flex items-start gap-4 px-4 py-3.5">
+						<div class="min-w-0 flex-1">
+							{#if resultHref}
+								<a
+									href={resultHref(result)}
+									class="font-medium hover:underline"
+									onclick={() => onOpen?.(result)}
+								>
+									{result.title}
+								</a>
+							{:else if onOpen}
+								<button
+									type="button"
+									class="text-left font-medium hover:underline"
+									onclick={() => onOpen(result)}
+								>
+									{result.title}
+								</button>
+							{:else}
+								<span class="font-medium">{result.title}</span>
+							{/if}
+
+							{#if result.source || result.meta}
+								<div class="text-muted-foreground mt-0.5 flex flex-wrap items-center gap-2 text-xs">
+									{#if result.source}
+										<span class="bg-surface-2 rounded px-1.5 py-0.5 font-medium">
+											{result.source}
+										</span>
+									{/if}
+									{#if result.meta}
+										<span>{result.meta}</span>
+									{/if}
+								</div>
+							{/if}
+
+							{#if result.snippet}
+								<!-- The matched passage. <mark> carries the semantics; the UA's
+								     black-on-yellow default is replaced with a tint of the
+								     app's own accent, so the highlight is skinned by the
+								     consumer's palette like everything else. -->
+								<p class="text-muted-foreground mt-1.5 line-clamp-3 text-sm">
+									{#each segments(result.snippet) as segment, i (i)}
+										{#if segment.highlight}
+											<mark class="bg-primary/15 text-foreground rounded-sm px-0.5 font-medium">
+												{segment.text}
+											</mark>
+										{:else}
+											{segment.text}
+										{/if}
+									{/each}
+								</p>
+							{/if}
+
+							{#if result.badges?.length}
+								<div class="mt-1.5 flex flex-wrap gap-1">
+									<!-- Keyed by index: LibraryBadge carries no id, and two states
+									     can legitimately share a label. -->
+									{#each result.badges as badge, i (i)}
+										<StatusBadge status={badge.status} label={badge.label} />
+									{/each}
+								</div>
+							{/if}
+						</div>
+
+						{#if result.score !== undefined}
+							<span
+								class="text-muted-foreground mt-0.5 flex-none font-mono text-xs tabular-nums"
+								aria-label="Relevance {pct(result.score)} percent"
+							>
+								{pct(result.score)}%
+							</span>
+						{/if}
+					</article>
+				</li>
+			{/each}
+		</ol>
+	{/if}
+</div>

package/dist/components/ui/search-results/search-results.svelte.d.ts

@@ -0,0 +1,44 @@
+/**
+     * SearchResults — a ranked retrieval answer: for each hit, the document's
+     * title, the passage that matched (with the matching spans emphasised), a
+     * source chip, consumer-mapped state, and a relevance figure.
+     *
+     * Designed, not extracted (#30): no in-repo view existed to generalise
+     * from. The shape follows the documentation-search results pattern — title
+     * over highlighted snippet over source — rendered in this package's own
+     * vocabulary: the highlight is a tint of the app's accent so every
+     * consumer's results wear its own palette; the score is a mono, tabular
+     * figure per the machine-value rule; state chips are StatusBadge.
+     *
+     * Fixed props over plain data: the page owns the query and the fetch, and
+     * this only renders the answer. `<ol>` because rank IS the meaning.
+     */
+import type { HTMLAttributes } from 'svelte/elements';
+import { type WithElementRef } from '../../../utils.js';
+import type { LibrarySearchResult } from '../library-browse/types.js';
+type $$ComponentProps = WithElementRef<Omit<HTMLAttributes<HTMLDivElement>, 'results'>> & {
+    /** `Omit` above: svelte/elements declares a legacy `results` HTML
+     *  attribute (number) on every element, and without the omission this
+     *  prop's type silently intersects with it — callers then cannot pass
+     *  an array at all. Caught by CI's svelte-check on the test call sites. */
+    results: LibrarySearchResult[];
+    /** The term the page searched for; shown in the count line and empty copy. */
+    query?: string;
+    /** Total hits when the page truncates; defaults to the rows given. */
+    total?: number;
+    loading?: boolean;
+    error?: string | null;
+    /** Copy for the surface before any search has been made. */
+    promptTitle?: string;
+    promptDescription?: string;
+    /** Copy when a search matched nothing; defaults name the query. */
+    noResultsTitle?: string;
+    noResultsDescription?: string;
+    /** The app's own routed link per hit; this package has no router. */
+    resultHref?: (result: LibrarySearchResult) => string;
+    onOpen?: (result: LibrarySearchResult) => void;
+    onRetry?: () => void;
+};
+declare const SearchResults: import("svelte").Component<$$ComponentProps, {}, "ref">;
+type SearchResults = ReturnType<typeof SearchResults>;
+export default SearchResults;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poodle64/ui",
-  "version": "2026.8.11",
+  "version": "2026.8.13",
   "description": "Household shared component layer: shadcn-svelte primitives (bits-ui) plus the composed page chrome every app builds its routes from, restyled by each app's @poodle64/design-tokens alias layer. One fix reaches every app.",
   "type": "module",
   "license": "MIT",
@@ -40,6 +40,7 @@
     }
   },
   "dependencies": {
+    "@jsonforms/core": "^3.8.0",
     "@lucide/svelte": "^1.25.0",
     "@tanstack/table-core": "^8.21.3",
     "clsx": "^2.1.1",

package/registry/component-map.json

@@ -1,11 +1,11 @@
 {
 	"meta": {
 		"package": "@poodle64/ui",
-		"version": "2026.8.11",
+		"version": "2026.8.13",
 		"generatedBy": "scripts/generate-registry.mjs",
 		"source": "scripts/situations.json + package source (DO NOT EDIT the outputs by hand)",
-		"componentCount": 49,
-		"situationCount": 12
+		"componentCount": 54,
+		"situationCount": 14
 	},
 	"situations": [
 		{
@@ -155,6 +155,55 @@
 				}
 			]
 		},
+		{
+			"key": "server-described-form",
+			"title": "A form the server described",
+			"description": "A config object whose shape arrives at runtime as a JSON Schema plus a JSON Forms UI Schema — the renderer walks both and dispatches to this package's widgets. Anything it cannot dispatch renders flagged, never blank.",
+			"components": [
+				{
+					"name": "SchemaForm",
+					"dir": "schema-form",
+					"import": "@poodle64/ui/schema-form",
+					"props": "schema, value, onChange, uischema?, disabled?, idPrefix?",
+					"insteadOf": "a hand-written renderer over a home-grown hint vocabulary, which is how a field goes missing in silence"
+				}
+			]
+		},
+		{
+			"key": "library-data",
+			"title": "Library data the app fetched",
+			"description": "The estate's shared document-library surfaces — a faceted catalogue, one collection's detail, one document's detail, a ranked search answer — rendered from plain props the app maps its own API responses into. The package never fetches and never routes: the app owns the query, the offset and every link. Configuration is the schema-driven half (SchemaForm); library data is fixed components because its shape is stable.",
+			"components": [
+				{
+					"name": "LibraryBrowse",
+					"dir": "library-browse",
+					"import": "@poodle64/ui/library-browse",
+					"props": "documents, facets?, query?, total?, offset?, limit?, loading?, error?, onQueryChange?, onFacetChange?, onPageChange?, documentHref?, onOpenDocument?, toolbar?",
+					"insteadOf": "a hand-built catalogue page: search box, facet rail, filter chips, results table and pager re-derived per app"
+				},
+				{
+					"name": "CollectionDetail",
+					"dir": "collection-detail",
+					"import": "@poodle64/ui/collection-detail",
+					"props": "collection, stats?, documents?, documentsTotal?, loading?, error?, documentsLoading?, documentsError?, onPageChange?, documentHref?, onOpenDocument?, actions?, children?",
+					"insteadOf": "a bespoke collection page assembled from raw Card, a hand-built table and its own stat rows"
+				},
+				{
+					"name": "DocumentDetail",
+					"dir": "document-detail",
+					"import": "@poodle64/ui/document-detail",
+					"props": "document, loading?, error?, collectionHref?, onOpenCollection?, actions?, children?",
+					"insteadOf": "a bespoke document page: identity dl, locations, tags and memberships hand-laid-out per app"
+				},
+				{
+					"name": "SearchResults",
+					"dir": "search-results",
+					"import": "@poodle64/ui/search-results",
+					"props": "results, query?, total?, loading?, error?, resultHref?, onOpen?, onRetry?",
+					"insteadOf": "a hand-built ranked hit list minting its own highlight and relevance styling"
+				}
+			]
+		},
 		{
 			"key": "page-frame",
 			"title": "The frame every route shares",

package/registry/component-map.md

@@ -1,7 +1,7 @@
 # @poodle64/ui — situation → component map
 
 <!-- GENERATED by scripts/generate-registry.mjs from scripts/situations.json + package source. DO NOT EDIT. -->
-Generated from `@poodle64/ui@2026.8.11`. 49 components, 12 situations.
+Generated from `@poodle64/ui@2026.8.13`. 54 components, 14 situations.
 
 **Read this before writing a `<div>`.** Find the SITUATION you are in below, then compose the component named for it — do not hand-build it from raw `Card` or utility classes. Import is `import { Name } from '<import path>'`. Props marked `?` are optional. This map is the retrieval step the [`frontend-design` skill] makes mandatory; the [CHI 2026 study] measured composing-from-a-registry at 95% design-system compliance against 71% for writing the CSS from a prose style guide.
 
@@ -83,6 +83,25 @@ _The generic titled card every route reaches for — an optional header with ico
 | --- | --- | --- | --- |
 | `Panel` | `@poodle64/ui/panel` | `children, title?, subtitle?, icon?, action?, pad?` | raw Card + CardHeader + CardTitle assembled by hand on every route |
 
+## A form the server described
+
+_A config object whose shape arrives at runtime as a JSON Schema plus a JSON Forms UI Schema — the renderer walks both and dispatches to this package's widgets. Anything it cannot dispatch renders flagged, never blank._
+
+| Component | Import | Key props | Reach for it instead of |
+| --- | --- | --- | --- |
+| `SchemaForm` | `@poodle64/ui/schema-form` | `schema, value, onChange, uischema?, disabled?, idPrefix?` | a hand-written renderer over a home-grown hint vocabulary, which is how a field goes missing in silence |
+
+## Library data the app fetched
+
+_The estate's shared document-library surfaces — a faceted catalogue, one collection's detail, one document's detail, a ranked search answer — rendered from plain props the app maps its own API responses into. The package never fetches and never routes: the app owns the query, the offset and every link. Configuration is the schema-driven half (SchemaForm); library data is fixed components because its shape is stable._
+
+| Component | Import | Key props | Reach for it instead of |
+| --- | --- | --- | --- |
+| `LibraryBrowse` | `@poodle64/ui/library-browse` | `documents, facets?, query?, total?, offset?, limit?, loading?, error?, onQueryChange?, onFacetChange?, onPageChange?, documentHref?, onOpenDocument?, toolbar?` | a hand-built catalogue page: search box, facet rail, filter chips, results table and pager re-derived per app |
+| `CollectionDetail` | `@poodle64/ui/collection-detail` | `collection, stats?, documents?, documentsTotal?, loading?, error?, documentsLoading?, documentsError?, onPageChange?, documentHref?, onOpenDocument?, actions?, children?` | a bespoke collection page assembled from raw Card, a hand-built table and its own stat rows |
+| `DocumentDetail` | `@poodle64/ui/document-detail` | `document, loading?, error?, collectionHref?, onOpenCollection?, actions?, children?` | a bespoke document page: identity dl, locations, tags and memberships hand-laid-out per app |
+| `SearchResults` | `@poodle64/ui/search-results` | `results, query?, total?, loading?, error?, resultHref?, onOpen?, onRetry?` | a hand-built ranked hit list minting its own highlight and relevance styling |
+
 ## The frame every route shares
 
 _The standing chrome — the app shell and its nav, the one page-title treatment, the persistent right-hand context column._