@poodle64/ui 2026.8.10 → 2026.8.12

package/dist/components/ui/library-browse/library-browse.svelte

@@ -0,0 +1,235 @@
+<script lang="ts">
+	/**
+	 * LibraryBrowse — the faceted catalogue index: search, facet rail, active
+	 * filter chips, the document table, and a pager.
+	 *
+	 * Fixed props over plain data, deliberately — library data is stable in
+	 * shape, so it gets a fixed component; configuration is the schema-driven
+	 * half and lives in <SchemaForm> (#30). The component fetches nothing and
+	 * routes nothing: the page owns the query, the facet selections and the
+	 * offset, re-queries its own backend on every callback, and supplies its
+	 * own routed link per row via `documentHref`.
+	 */
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { cn, type WithElementRef } from '../../../utils.js';
+	import Search from '@lucide/svelte/icons/search';
+	import LibraryIcon from '@lucide/svelte/icons/library';
+	import X from '@lucide/svelte/icons/x';
+	import { Input } from '../input/index.js';
+	import Button from '../button/button.svelte';
+	import { Badge } from '../badge/index.js';
+	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 DocumentTable from './document-table.svelte';
+	import FacetRail from './facet-rail.svelte';
+	import type { LibraryDocument, LibraryFacet } from './types.js';
+
+	let {
+		documents,
+		facets = [],
+		query = '',
+		total,
+		offset = 0,
+		limit = 25,
+		loading = false,
+		error = null,
+		searchPlaceholder = 'Search the catalogue…',
+		emptyTitle = 'The catalogue is empty',
+		emptyDescription,
+		onQueryChange,
+		onFacetChange,
+		onPageChange,
+		onRetry,
+		documentHref,
+		onOpenDocument,
+		toolbar,
+		ref = $bindable(null),
+		class: className,
+		...restProps
+	}: WithElementRef<HTMLAttributes<HTMLDivElement>> & {
+		documents: LibraryDocument[];
+		facets?: LibraryFacet[];
+		/** The current search term. The page owns it; typing fires `onQueryChange`. */
+		query?: string;
+		/** Total matches across all pages; defaults to the rows given. */
+		total?: number;
+		offset?: number;
+		limit?: number;
+		loading?: boolean;
+		error?: string | null;
+		searchPlaceholder?: string;
+		/** Copy for a catalogue that is genuinely empty (no filter active). */
+		emptyTitle?: string;
+		emptyDescription?: string;
+		onQueryChange?: (query: string) => void;
+		onFacetChange?: (key: string, selected: string[]) => void;
+		/** Called with the next offset when the pager is used. */
+		onPageChange?: (offset: number) => void;
+		onRetry?: () => void;
+		/** The app's own routed link per row; this package has no router. */
+		documentHref?: (doc: LibraryDocument) => string;
+		onOpenDocument?: (doc: LibraryDocument) => void;
+		/** Trailing controls beside the search field (e.g. a saved-search menu). */
+		toolbar?: Snippet;
+	} = $props();
+
+	interface Chip {
+		key: string;
+		label: string;
+		remove: () => void;
+	}
+
+	// Chips are derived, never state: the page owns query and selections, so a
+	// chip's removal is just the matching callback with the value taken out.
+	const chips = $derived.by((): Chip[] => {
+		const out: Chip[] = [];
+		if (query) out.push({ key: 'q', label: `“${query}”`, remove: () => onQueryChange?.('') });
+		for (const facet of facets) {
+			for (const value of facet.selected) {
+				out.push({
+					key: `${facet.key}:${value}`,
+					label: `${facet.label.toLowerCase()}: ${value}`,
+					remove: () =>
+						onFacetChange?.(
+							facet.key,
+							facet.selected.filter((v) => v !== value)
+						)
+				});
+			}
+		}
+		return out;
+	});
+	const filtered = $derived(chips.length > 0);
+
+	function clearAll() {
+		if (query) onQueryChange?.('');
+		for (const facet of facets) {
+			if (facet.selected.length) onFacetChange?.(facet.key, []);
+		}
+	}
+
+	const shownTotal = $derived(total ?? documents.length);
+	// Floored at 1 so a consumer's limit: 0 cannot put Infinity in the pager.
+	const pageSize = $derived(Math.max(1, limit));
+	const pageCount = $derived(Math.max(1, Math.ceil(shownTotal / pageSize)));
+	const page = $derived(Math.floor(offset / pageSize) + 1);
+</script>
+
+<div bind:this={ref} class={cn('flex flex-col gap-4', className)} {...restProps}>
+	<div class="flex flex-wrap items-center gap-2">
+		<form
+			class="relative w-full flex-none sm:w-80"
+			onsubmit={(e) => {
+				e.preventDefault();
+				onQueryChange?.(query);
+			}}
+		>
+			<Search
+				class="text-muted-foreground pointer-events-none absolute top-1/2 left-2.5 size-4 -translate-y-1/2"
+			/>
+			<Input
+				type="search"
+				value={query}
+				placeholder={searchPlaceholder}
+				class="pl-8"
+				oninput={(e) => onQueryChange?.((e.target as HTMLInputElement).value)}
+			/>
+		</form>
+		{#if toolbar}
+			<div class="flex items-center gap-2">{@render toolbar()}</div>
+		{/if}
+	</div>
+
+	{#if chips.length > 0}
+		<div class="flex flex-wrap items-center gap-2">
+			{#each chips as chip (chip.key)}
+				<Badge variant="secondary" class="gap-1">
+					{chip.label}
+					<button
+						type="button"
+						aria-label="Remove filter {chip.label}"
+						class="hover:opacity-70"
+						onclick={chip.remove}
+					>
+						<X class="size-3" />
+					</button>
+				</Badge>
+			{/each}
+			<Button variant="ghost" size="sm" onclick={clearAll}>Clear all</Button>
+		</div>
+	{/if}
+
+	<div
+		class={facets.length > 0 ? 'grid gap-6 md:grid-cols-[220px_minmax(0,1fr)]' : 'grid gap-6'}
+	>
+		{#if facets.length > 0}
+			<aside class="hidden md:block" aria-label="Filters">
+				<FacetRail {facets} onChange={onFacetChange} />
+			</aside>
+		{/if}
+
+		<!-- min-w-0: a grid item defaults to min-width:auto, so without it this
+		     column stretches to the table's intrinsic width and the table's own
+		     scroller never gets a bounded box — the excess lands on the shell's
+		     scroller instead (measured in the first consumer). minmax(0,1fr) on
+		     the track carries the same guarantee at the grid level. -->
+		<div class="flex min-w-0 flex-col gap-3">
+			{#if loading}
+				<LoadingState message="Loading the catalogue…" />
+			{:else if error}
+				<ErrorState message={error}>
+					{#snippet action()}
+						{#if onRetry}
+							<Button variant="outline" onclick={onRetry}>Retry</Button>
+						{/if}
+					{/snippet}
+				</ErrorState>
+			{:else if documents.length === 0}
+				{#if filtered}
+					<EmptyState
+						icon={LibraryIcon}
+						title="No documents match this search"
+						description="Try a different term, or clear the filters to see the whole catalogue."
+					>
+						{#snippet action()}
+							<Button variant="outline" onclick={clearAll}>Clear filters</Button>
+						{/snippet}
+					</EmptyState>
+				{:else}
+					<EmptyState icon={LibraryIcon} title={emptyTitle} description={emptyDescription} />
+				{/if}
+			{:else}
+				<DocumentTable {documents} {documentHref} onOpen={onOpenDocument} />
+
+				<div class="flex flex-wrap items-center justify-between gap-2">
+					<p class="text-muted-foreground text-xs">
+						{shownTotal} document{shownTotal === 1 ? '' : 's'}
+					</p>
+					{#if onPageChange && shownTotal > pageSize}
+						<div class="flex items-center gap-2">
+							<Button
+								variant="outline"
+								size="sm"
+								disabled={offset === 0}
+								onclick={() => onPageChange(Math.max(0, offset - pageSize))}
+							>
+								Previous
+							</Button>
+							<span class="text-muted-foreground text-xs">Page {page} of {pageCount}</span>
+							<Button
+								variant="outline"
+								size="sm"
+								disabled={offset + pageSize >= shownTotal}
+								onclick={() => onPageChange(offset + pageSize)}
+							>
+								Next
+							</Button>
+						</div>
+					{/if}
+				</div>
+			{/if}
+		</div>
+	</div>
+</div>

package/dist/components/ui/library-browse/library-browse.svelte.d.ts

@@ -0,0 +1,44 @@
+/**
+     * LibraryBrowse — the faceted catalogue index: search, facet rail, active
+     * filter chips, the document table, and a pager.
+     *
+     * Fixed props over plain data, deliberately — library data is stable in
+     * shape, so it gets a fixed component; configuration is the schema-driven
+     * half and lives in <SchemaForm> (#30). The component fetches nothing and
+     * routes nothing: the page owns the query, the facet selections and the
+     * offset, re-queries its own backend on every callback, and supplies its
+     * own routed link per row via `documentHref`.
+     */
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type WithElementRef } from '../../../utils.js';
+import type { LibraryDocument, LibraryFacet } from './types.js';
+type $$ComponentProps = WithElementRef<HTMLAttributes<HTMLDivElement>> & {
+    documents: LibraryDocument[];
+    facets?: LibraryFacet[];
+    /** The current search term. The page owns it; typing fires `onQueryChange`. */
+    query?: string;
+    /** Total matches across all pages; defaults to the rows given. */
+    total?: number;
+    offset?: number;
+    limit?: number;
+    loading?: boolean;
+    error?: string | null;
+    searchPlaceholder?: string;
+    /** Copy for a catalogue that is genuinely empty (no filter active). */
+    emptyTitle?: string;
+    emptyDescription?: string;
+    onQueryChange?: (query: string) => void;
+    onFacetChange?: (key: string, selected: string[]) => void;
+    /** Called with the next offset when the pager is used. */
+    onPageChange?: (offset: number) => void;
+    onRetry?: () => void;
+    /** The app's own routed link per row; this package has no router. */
+    documentHref?: (doc: LibraryDocument) => string;
+    onOpenDocument?: (doc: LibraryDocument) => void;
+    /** Trailing controls beside the search field (e.g. a saved-search menu). */
+    toolbar?: Snippet;
+};
+declare const LibraryBrowse: import("svelte").Component<$$ComponentProps, {}, "ref">;
+type LibraryBrowse = ReturnType<typeof LibraryBrowse>;
+export default LibraryBrowse;

package/dist/components/ui/library-browse/types.d.ts

@@ -0,0 +1,101 @@
+import type { Status } from '../status/index.js';
+/**
+ * The shared library-data vocabulary — plain shapes a consuming app maps its
+ * own API responses into. This package holds no HTTP client, no endpoint
+ * string, and no knowledge of any backend or app; that is what lets the
+ * backend be replaced without touching a consumer, and it is not negotiable
+ * for convenience (#30). An app's own state vocabulary (whatever its wire
+ * format says) is mapped by the app onto the shared five-state `Status`
+ * before it arrives here, as a `LibraryBadge`.
+ */
+/** A consumer-mapped state chip: one of the five shared states plus the app's label. */
+export interface LibraryBadge {
+    status: Status;
+    label: string;
+}
+/** One catalogue row. */
+export interface LibraryDocument {
+    id: string;
+    title: string;
+    /** Free labels on the document. */
+    tags?: string[];
+    /** Names of the collections it belongs to. */
+    collections?: string[];
+    /** Consumer-mapped state chips (e.g. one per collection's index state). */
+    badges?: LibraryBadge[];
+}
+/** One choice inside a facet. */
+export interface LibraryFacetOption {
+    value: string;
+    /** Documents carrying it; omit to render no count. */
+    count?: number;
+    /** Display label when the wire value is not presentable; defaults to `value`. */
+    label?: string;
+}
+/** One facet dimension in the browse rail. The page owns the selection state. */
+export interface LibraryFacet {
+    /** Stable key handed back through `onFacetChange`. */
+    key: string;
+    label: string;
+    options: LibraryFacetOption[];
+    /** Currently selected wire values. */
+    selected: string[];
+    /** Allow several selections at once (default: a single toggle). */
+    multiple?: boolean;
+}
+/** A label→value row in a document's field list. */
+export interface LibraryField {
+    label: string;
+    value: string;
+    /** Render the value in the code/data face (a hash, a path, a machine value). */
+    mono?: boolean;
+}
+/** One recorded location of a document. */
+export interface LibraryLocation {
+    path: string;
+    primary?: boolean;
+    badge?: LibraryBadge;
+}
+/** One collection membership of a document. */
+export interface LibraryMembership {
+    id: string;
+    name: string;
+    badge?: LibraryBadge;
+}
+/** The full detail of one document. */
+export interface LibraryDocumentDetail {
+    id: string;
+    title: string;
+    fields?: LibraryField[];
+    tags?: string[];
+    locations?: LibraryLocation[];
+    memberships?: LibraryMembership[];
+}
+/** The identity of one collection. */
+export interface LibraryCollection {
+    id: string;
+    name: string;
+    /** One already-formatted meta line (owner · pipeline · state). */
+    subtitle?: string;
+    description?: string;
+    badge?: LibraryBadge;
+}
+/** A snippet segment; `highlight` marks the part that matched the query. */
+export interface SearchSnippetSegment {
+    text: string;
+    highlight?: boolean;
+}
+/** One ranked search hit. */
+export interface LibrarySearchResult {
+    id: string;
+    title: string;
+    /** The matched passage: plain text, or segments carrying highlights. */
+    snippet?: string | SearchSnippetSegment[];
+    /** Relevance in [0, 1]; rendered as a percentage. */
+    score?: number;
+    /** Where the hit came from — a collection or corpus name. */
+    source?: string;
+    badges?: LibraryBadge[];
+    /** One already-formatted trailing meta line (a date, a type). */
+    meta?: string;
+}

package/dist/components/ui/library-browse/types.js

@@ -0,0 +1 @@
+export {};

package/dist/components/ui/schema-form/context.d.ts

@@ -0,0 +1,31 @@
+import type { createAjv, JsonSchema } from '@jsonforms/core';
+/**
+ * The Ajv instance `@jsonforms/core` builds. Typed through its own factory so
+ * this package never names `ajv` — a transitive dependency of the engine, not
+ * a dependency of ours.
+ */
+export type FormAjv = ReturnType<typeof createAjv>;
+/**
+ * The form-wide facts every nested element needs, published once by
+ * `<SchemaForm>` rather than drilled through a recursive component tree.
+ * Everything reactive is exposed as a getter, so a context read stays live
+ * under Svelte 5's signals.
+ */
+export interface SchemaFormContext {
+    /** The root JSON Schema every scope resolves against. */
+    readonly schema: JsonSchema;
+    /** The whole current value; rules and every widget read from here. */
+    readonly data: Record<string, unknown>;
+    /** Whether the whole form is disabled. */
+    readonly disabled: boolean;
+    /** Prefix for generated element ids. */
+    readonly idPrefix: string;
+    /** Validation messages by dot path, from the schema itself. */
+    readonly errors: Record<string, string[]>;
+    /** The shared Ajv instance rule conditions are evaluated with. */
+    readonly ajv: FormAjv;
+    /** Commit one field. */
+    change: (path: string, value: unknown) => void;
+}
+export declare const setSchemaFormContext: (context: SchemaFormContext) => SchemaFormContext;
+export declare const getSchemaFormContext: () => SchemaFormContext;

package/dist/components/ui/schema-form/context.js

@@ -0,0 +1,10 @@
+import { getContext, setContext } from 'svelte';
+const KEY = Symbol('poodle64-schema-form');
+export const setSchemaFormContext = (context) => setContext(KEY, context);
+export const getSchemaFormContext = () => {
+    const context = getContext(KEY);
+    if (!context) {
+        throw new Error('@poodle64/ui: a schema-form part was rendered outside <SchemaForm>. Render the form, not its internals.');
+    }
+    return context;
+};

package/dist/components/ui/schema-form/data.d.ts

@@ -0,0 +1,42 @@
+import { type JsonSchema, type UISchemaElement } from '@jsonforms/core';
+import type { UnknownReason } from './types.js';
+/**
+ * Reading and writing a value at a dot path, and the walk that decides which
+ * schema properties the layout never mentioned.
+ *
+ * Dot paths are JSON Forms' own addressing (`toDataPath('#/properties/a/properties/b')`
+ * → `a.b`), so a property name containing a literal `.` is not addressable —
+ * the same limitation the wire format itself carries.
+ */
+export declare const scopeToPath: (scope: string) => string;
+/** Read the value at a dot path, or `undefined`. */
+export declare function getAt(data: unknown, path: string): unknown;
+/**
+ * Return a copy of `data` with `path` set to `value`. Every object along the
+ * way is copied, so a consumer holding the previous value still holds the
+ * previous value — a `$state` consumer and an immutable store both work.
+ */
+export declare function setAt(data: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>;
+/** Every UI schema element in the tree, depth first. */
+export declare function walkElements(element: UISchemaElement | undefined): UISchemaElement[];
+/** The dot paths every Control in the tree addresses. */
+export declare function addressedPaths(uischema: UISchemaElement | undefined): Set<string>;
+export interface UnmappedField {
+    /** Dot path of the property nothing in the layout addresses. */
+    path: string;
+    /** JSON Pointer scope, so the fix is a copy-paste into the UI schema. */
+    scope: string;
+    schema: JsonSchema;
+    reason: UnknownReason;
+}
+/**
+ * Every schema property no Control addresses.
+ *
+ * This is the check that would have caught the estate's live defect: three
+ * whole top-level config groups never rendered because their names were absent
+ * from a hardcoded GROUP_ORDER, and a missing group produced no output and no
+ * error. Here a group nothing addresses is reported ONCE, at the group — the
+ * walk does not descend into a subtree the layout ignores entirely, so an
+ * unmentioned group is one loud entry rather than forty.
+ */
+export declare function unmappedFields(root: JsonSchema, addressed: Set<string>, node?: JsonSchema, scope?: string, path?: string): UnmappedField[];

package/dist/components/ui/schema-form/data.js

@@ -0,0 +1,97 @@
+import { resolveSchema, toDataPath } from '@jsonforms/core';
+/**
+ * Reading and writing a value at a dot path, and the walk that decides which
+ * schema properties the layout never mentioned.
+ *
+ * Dot paths are JSON Forms' own addressing (`toDataPath('#/properties/a/properties/b')`
+ * → `a.b`), so a property name containing a literal `.` is not addressable —
+ * the same limitation the wire format itself carries.
+ */
+export const scopeToPath = (scope) => toDataPath(scope);
+/** Read the value at a dot path, or `undefined`. */
+export function getAt(data, path) {
+    if (!path)
+        return data;
+    let node = data;
+    for (const key of path.split('.')) {
+        if (node === null || typeof node !== 'object')
+            return undefined;
+        node = node[key];
+    }
+    return node;
+}
+/**
+ * Return a copy of `data` with `path` set to `value`. Every object along the
+ * way is copied, so a consumer holding the previous value still holds the
+ * previous value — a `$state` consumer and an immutable store both work.
+ */
+export function setAt(data, path, value) {
+    const keys = path.split('.');
+    const root = { ...data };
+    let node = root;
+    for (let i = 0; i < keys.length - 1; i++) {
+        const key = keys[i];
+        const child = node[key];
+        node[key] = child && typeof child === 'object' && !Array.isArray(child)
+            ? { ...child }
+            : {};
+        node = node[key];
+    }
+    node[keys[keys.length - 1]] = value;
+    return root;
+}
+/** Every UI schema element in the tree, depth first. */
+export function walkElements(element) {
+    if (!element)
+        return [];
+    const children = element.elements ?? [];
+    return [element, ...children.flatMap(walkElements)];
+}
+/** The dot paths every Control in the tree addresses. */
+export function addressedPaths(uischema) {
+    const paths = new Set();
+    for (const element of walkElements(uischema)) {
+        const scope = element.scope;
+        if (element.type === 'Control' && typeof scope === 'string' && scope.startsWith('#')) {
+            paths.add(scopeToPath(scope));
+        }
+    }
+    return paths;
+}
+/**
+ * Every schema property no Control addresses.
+ *
+ * This is the check that would have caught the estate's live defect: three
+ * whole top-level config groups never rendered because their names were absent
+ * from a hardcoded GROUP_ORDER, and a missing group produced no output and no
+ * error. Here a group nothing addresses is reported ONCE, at the group — the
+ * walk does not descend into a subtree the layout ignores entirely, so an
+ * unmentioned group is one loud entry rather than forty.
+ */
+export function unmappedFields(root, addressed, node = root, scope = '#', path = '') {
+    const properties = node.properties;
+    if (!properties)
+        return [];
+    const found = [];
+    for (const [key, raw] of Object.entries(properties)) {
+        const childPath = path ? `${path}.${key}` : key;
+        const childScope = `${scope}/properties/${key}`;
+        // `resolveSchema` follows any $ref, so a property behind a definition is
+        // judged on the schema it actually resolves to.
+        const child = resolveSchema(root, childScope, root) ?? raw;
+        // Addressed BY ITSELF: a Control points at this property. Whatever it does
+        // with it is that Control's business — do not descend and second-guess it.
+        if (addressed.has(childPath))
+            continue;
+        // Addressed BELOW: some Control points inside it, so the layout knows about
+        // this subtree and only some of its leaves are missing.
+        if ([...addressed].some((addressedPath) => addressedPath.startsWith(`${childPath}.`))) {
+            found.push(...unmappedFields(root, addressed, child, childScope, childPath));
+            continue;
+        }
+        // Addressed nowhere: report it here, once, and do not descend — an
+        // unmentioned group is one loud entry, not forty.
+        found.push({ path: childPath, scope: childScope, schema: child, reason: 'not-in-layout' });
+    }
+    return found;
+}

package/dist/components/ui/schema-form/dispatch.d.ts

@@ -0,0 +1,35 @@
+import type { JsonSchema } from '@jsonforms/core';
+import { type UnknownReason, type WidgetKind } from './types.js';
+/**
+ * Control → widget resolution, as a pure function so the table can be asserted
+ * without rendering anything.
+ *
+ * THE RULE THIS FILE EXISTS FOR: every branch that cannot produce a real widget
+ * returns `{ widget: 'unknown', reason }`. There is no branch that returns
+ * nothing, and no branch that quietly substitutes a default for a hint it did
+ * not understand. The estate's previous home-grown renderer had both, and a
+ * `widget: "dropdown"` hint therefore rendered no input at all for months
+ * without anyone noticing.
+ */
+export interface WidgetChoice {
+    widget: WidgetKind;
+    /** Present exactly when `widget === 'unknown'`. */
+    reason?: UnknownReason;
+    /** Human-readable specifics for the flagged render, e.g. the rejected hint. */
+    detail?: string;
+}
+/** The first `type` a subschema declares (JSON Schema allows an array of them). */
+export declare function schemaType(schema: JsonSchema | undefined): string | undefined;
+/** Does this subschema carry a closed set of values a select can list? */
+export declare function enumOptions(schema: JsonSchema | undefined): {
+    value: unknown;
+    label: string;
+}[] | null;
+/**
+ * Resolve a Control to a widget.
+ *
+ * @param schema  the subschema the Control's scope resolved to, or `undefined`
+ *                if the scope resolved to nothing at all.
+ * @param options the Control's `options` object from the UI schema.
+ */
+export declare function pickWidget(schema: JsonSchema | undefined, options?: Record<string, unknown>): WidgetChoice;