@poodle64/ui 2026.8.11 → 2026.8.13

package/README.md

@@ -74,30 +74,35 @@ the one-owner-per-key note below). It becomes a candidate the day two apps want
 the same chart palette; until then a shared chart component would be a shared
 disagreement.
 
-**Composed components** (20). Primitives are not what makes an app look like an
+**Composed components** (24). Primitives are not what makes an app look like an
 app — the page chrome is. These are the cross-cutting surfaces every route
 composes from, so a household app gets its layout language from the package
 rather than rebuilding it:
 
-| Import                                          | What it is                                                                                                                                                                                                                                                                                                                                               |
-| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `page-header`                                   | The only page-title pattern: optional `breadcrumbs` snippet, eyebrow, an optional title, one clamped subtitle, an `info` tooltip, an `actions` slot. Omit `title` for a header that is a breadcrumb bar.                                                                                                                                                 |
-| `panel`                                         | The generic titled card: optional icon, subtitle and trailing actions over a body that can opt out of padding.                                                                                                                                                                                                                                           |
-| `detail-panel`                                  | The entity-detail surface: header with icon/eyebrow/title/`StatusBadge`/close, scrollable body, footer of actions.                                                                                                                                                                                                                                       |
-| `context-column`                                | The persistent right-hand column: a standing `StatList` plus an optional detail that flows in on select.                                                                                                                                                                                                                                                 |
-| `app-dialog`                                    | The dialogue frame: titled header, scrollable body, footer action bar, five sizes (`xs`…`xl`), and an `onOpenChange` for the dismissals the caller did not drive.                                                                                                                                                                                        |
-| `dialog-section`                                | One section of a dialogue body; adjacent sections are divided automatically.                                                                                                                                                                                                                                                                             |
-| `stat-card`                                     | A single metric that earns its space (label, value, unit, sub, status dot, and `valueTone` to colour the figure itself).                                                                                                                                                                                                                                 |
-| `stat-list`                                     | A route's low-context integers as a label→value list. Zero-aware: `muted` keeps a healthy zero quiet.                                                                                                                                                                                                                                                    |
-| `arc-gauge`                                     | A radial capacity/percentage ring for a single 0–100 metric, in a footprint too compact for a `stat-card`.                                                                                                                                                                                                                                               |
-| `bar-row`                                       | A labelled horizontal bar with a trailing tabular value, for a ranked list (usage, rank, token burn).                                                                                                                                                                                                                                                    |
-| `scorecard`                                     | A compact 0/1/2 dot-row health strip for several independent checks read at a glance.                                                                                                                                                                                                                                                                    |
-| `sparkline`                                     | An inline multi-series area+line trend for a row or card with room for a trend but not a full chart.                                                                                                                                                                                                                                                     |
-| `status` / `status-badge`                       | The fixed five-state vocabulary (`success \| warning \| error \| info \| neutral`) and the one state chip, with `pulse` for a state still in motion and `class` for placement. `status-badge` alone also accepts `'primary'`, a brand-emphasis extension outside the shared vocabulary — `stat-card`, `stat-list` and `data-table-toolbar` never see it. |
-| `empty-state` / `error-state` / `loading-state` | The shared blank, error and loading surfaces. Never hand-roll one.                                                                                                                                                                                                                                                                                       |
-| `info-tip`                                      | One tooltip pattern: a small info trigger, or wrap an existing affordance as children.                                                                                                                                                                                                                                                                   |
-| `data-table-toolbar`                            | Search field plus filter-chip groups for a TanStack table. Owns no state; fires callbacks.                                                                                                                                                                                                                                                               |
-| `data-table-tanstack`                           | The TanStack-backed table: global search, column filters, master-detail row select, opt-in bulk selection, responsive column hiding, a first-class empty branch.                                                                                                                                                                                         |
+| Import                                          | What it is                                                                                                                                                                                                                                                                                                                                                  |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `page-header`                                   | The only page-title pattern: optional `breadcrumbs` snippet, eyebrow, an optional title, one clamped subtitle, an `info` tooltip, an `actions` slot. Omit `title` for a header that is a breadcrumb bar.                                                                                                                                                    |
+| `panel`                                         | The generic titled card: optional icon, subtitle and trailing actions over a body that can opt out of padding.                                                                                                                                                                                                                                              |
+| `detail-panel`                                  | The entity-detail surface: header with icon/eyebrow/title/`StatusBadge`/close, scrollable body, footer of actions.                                                                                                                                                                                                                                          |
+| `context-column`                                | The persistent right-hand column: a standing `StatList` plus an optional detail that flows in on select.                                                                                                                                                                                                                                                    |
+| `app-dialog`                                    | The dialogue frame: titled header, scrollable body, footer action bar, five sizes (`xs`…`xl`), and an `onOpenChange` for the dismissals the caller did not drive.                                                                                                                                                                                           |
+| `dialog-section`                                | One section of a dialogue body; adjacent sections are divided automatically.                                                                                                                                                                                                                                                                                |
+| `stat-card`                                     | A single metric that earns its space (label, value, unit, sub, status dot, and `valueTone` to colour the figure itself).                                                                                                                                                                                                                                    |
+| `stat-list`                                     | A route's low-context integers as a label→value list. Zero-aware: `muted` keeps a healthy zero quiet.                                                                                                                                                                                                                                                       |
+| `arc-gauge`                                     | A radial capacity/percentage ring for a single 0–100 metric, in a footprint too compact for a `stat-card`.                                                                                                                                                                                                                                                  |
+| `bar-row`                                       | A labelled horizontal bar with a trailing tabular value, for a ranked list (usage, rank, token burn).                                                                                                                                                                                                                                                       |
+| `scorecard`                                     | A compact 0/1/2 dot-row health strip for several independent checks read at a glance.                                                                                                                                                                                                                                                                       |
+| `sparkline`                                     | An inline multi-series area+line trend for a row or card with room for a trend but not a full chart.                                                                                                                                                                                                                                                        |
+| `status` / `status-badge`                       | The fixed five-state vocabulary (`success \| warning \| error \| info \| neutral`) and the one state chip, with `pulse` for a state still in motion and `class` for placement. `status-badge` alone also accepts `'primary'`, a brand-emphasis extension outside the shared vocabulary — `stat-card`, `stat-list` and `data-table-toolbar` never see it.    |
+| `empty-state` / `error-state` / `loading-state` | The shared blank, error and loading surfaces. Never hand-roll one.                                                                                                                                                                                                                                                                                          |
+| `info-tip`                                      | One tooltip pattern: a small info trigger, or wrap an existing affordance as children.                                                                                                                                                                                                                                                                      |
+| `data-table-toolbar`                            | Search field plus filter-chip groups for a TanStack table. Owns no state; fires callbacks.                                                                                                                                                                                                                                                                  |
+| `schema-form`                                   | The renderer for a config object the server described: a JSON Schema plus a JSON Forms UI Schema in, a form out. Anything it cannot dispatch renders flagged, never blank; see [Server-described forms](#server-described-forms) below.                                                                                                                     |
+| `data-table-tanstack`                           | The TanStack-backed table: global search, column filters, master-detail row select, opt-in bulk selection, responsive column hiding, a first-class empty branch.                                                                                                                                                                                            |
+| `library-browse`                                | The faceted catalogue index: search, facet rail, active filter chips, the document table and a pager, all over plain props (`LibraryDocument[]`, `LibraryFacet[]`). The page fetches, maps and routes; the component renders. Library data is fixed components because its shape is stable; configuration is `schema-form` because its shape changes (#30). |
+| `collection-detail`                             | One collection's surface: identity (`detail-panel`), an at-a-glance `stat-list`, and the documents it holds, with `actions` and `children` slots for the app-specific rest.                                                                                                                                                                                 |
+| `document-detail`                               | One document's surface: identity fields, locations, tags and collection memberships, each section present exactly when its data is. Membership links are the app's own via `collectionHref`.                                                                                                                                                                |
+| `search-results`                                | A ranked retrieval answer: title, the matched passage with accent-tinted highlights, source chip, mapped state and a mono relevance figure per hit; plus the before-any-search and matched-nothing empties.                                                                                                                                                 |
 
 **The application shell** (`app-shell`, `command-palette`). Page chrome is not
 what makes an app feel like an app either — the shell is. Five household
@@ -503,6 +508,145 @@ but the same class on the `<th>` collapses the heading over its neighbour:
 { accessorKey: 'filename', header: 'Document', meta: { class: 'w-full', cellClass: 'max-w-0' } }
 ```
 
+## Server-described forms
+
+`<SchemaForm>` renders a config object whose shape arrives at runtime. It is the
+estate's one mechanism for that, and this README is where its contract lives.
+
+Two standard documents go in. A **JSON Schema** says what the value is; a **JSON
+Forms UI Schema** says how it is laid out — a tree of layouts, Controls
+addressed by JSON Pointer `scope`, and declarative `rule: { effect, condition }`
+for conditional visibility. Both are published standards, which is the point:
+the renderer is replaceable without a server changing anything.
+
+```svelte
+<script lang="ts">
+	import SchemaForm from '@poodle64/ui/schema-form';
+
+	let { schema, uischema } = $props(); // fetched by the app, not by this package
+	let value = $state({});
+</script>
+
+<SchemaForm {schema} {uischema} {value} onChange={(next) => (value = next)} />
+```
+
+| Prop       | Purpose                                                                                                                                 |
+| ---------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `schema`   | The JSON Schema. Scopes resolve against it, `$ref` included, and it drives validation.                                                  |
+| `uischema` | The JSON Forms UI Schema. Omit it and one is generated from the schema, the only mode in which no field can be missing from the layout. |
+| `value`    | The current value. The component is controlled and never mutates what it is given.                                                      |
+| `onChange` | `(next, { path, value })`. `next` is a fresh object with every untouched branch structurally intact.                                    |
+| `disabled` | Disables every control.                                                                                                                 |
+| `idPrefix` | Prefix for generated element ids, when two forms share a page.                                                                          |
+
+### It knows nothing about any app
+
+No HTTP client, no `fetch`, no endpoint string, no service name, no
+app-specific type. Consumers fetch the two documents and map the result
+themselves. That invariant is load-bearing: it is what lets the engine behind
+the schema be swapped later without touching a consumer, and what stopped three
+apps' renderers from being three different components.
+
+### An unrecognised control renders LOUDLY
+
+**This is the non-negotiable rule.** The three hand-rolled renderers this
+replaces failed silently: a `widget: "dropdown"` hint rendered no input at all,
+three whole top-level config groups never rendered because their names were
+absent from a hardcoded `GROUP_ORDER`, and nested hints were inert. Every one
+of those made a field VANISH, and a form with a field missing looks exactly like
+a form. They shipped that way for months.
+
+So nothing here renders as nothing. Eight failure shapes each produce a
+visibly-flagged block carrying `data-schema-form-unknown` and a
+`data-unknown-reason`, which names what could not be done, quotes the pointer so
+the fix is a copy-paste, shows the value that would otherwise have been lost,
+and keeps it editable wherever a text box cannot destroy structure:
+
+| `data-unknown-reason` | Raised when                                                                       |
+| --------------------- | --------------------------------------------------------------------------------- |
+| `unknown-widget`      | `options.format` / `options.widget` names a widget this package does not ship.    |
+| `unknown-element`     | A UI schema element `type` outside the vocabulary below.                          |
+| `unresolved-scope`    | A Control's `scope` resolves to nothing in the JSON Schema.                       |
+| `missing-scope`       | A Control carries no `scope` at all.                                              |
+| `no-options`          | A `select` or `radio` over a subschema that declares no `enum` or `oneOf`.        |
+| `object-control`      | A Control points at an object, which needs a layout rather than one control.      |
+| `unsupported-array`   | An array whose items are not primitives, so `tags` cannot represent it.           |
+| `not-in-layout`       | The JSON Schema describes a property no Control anywhere in the layout addresses. |
+
+A primitive value stays editable; an object or an array is shown read-only,
+because a text box over structured data is a data-loss affordance rather than a
+fallback. An unrecognised hint is never quietly swapped for the widget it
+probably meant — `dropdown` almost certainly meant `select`, and guessing would
+restore the field while hiding the fact that the two documents disagree.
+
+`not-in-layout` is reported once per unaddressed subtree, at the subtree, so a
+forgotten group is one loud entry rather than forty. There is no prop to silence
+any of this. The way to stop a field being flagged is to put a Control for it in
+the UI schema.
+
+`src/test/schema-form-loud-unknown.test.ts` pins all eight reasons, and
+`harness/drive.mjs` proves in a real engine that each flag has real size and a
+resolved, visible warning border. "Renders loudly" is a claim about paint, and
+a fallback styled into invisibility would satisfy every jsdom assertion while
+reproducing the original defect exactly.
+
+### The widget dispatch table
+
+An explicit hint wins; otherwise the widget is derived from the subschema.
+`options.format` is the JSON Forms spelling and `options.widget` is accepted
+alongside it, so a server migrating off a home-grown hint vocabulary does not
+have to change both documents at once. Any hint outside this table is
+`unknown-widget`.
+
+| Widget     | Chosen when                                     | Rendered by                       |
+| ---------- | ----------------------------------------------- | --------------------------------- |
+| `text`     | `string` (the default)                          | `input`                           |
+| `textarea` | `options.multi: true`, or the hint              | `textarea`                        |
+| `password` | `format: "password"`, or the hint               | `input[type=password]`            |
+| `date`     | `format: "date"`                                | `input[type=date]`                |
+| `time`     | `format: "time"`                                | `input[type=time]`                |
+| `datetime` | `format: "date-time"`                           | `input[type=datetime-local]`      |
+| `number`   | `number` / `integer`                            | `input[type=number]`              |
+| `slider`   | `options.slider: true` on a number, or the hint | composed here (native `range`)    |
+| `select`   | `enum`, or `oneOf: [{ const, title }]`          | `select`                          |
+| `radio`    | the hint, on the same closed value sets         | composed here (native `radio`)    |
+| `switch`   | `boolean` (the default)                         | `switch`                          |
+| `checkbox` | the hint, on a boolean                          | `checkbox`                        |
+| `tags`     | `array` of `string` / `number` / `integer`      | composed here (`badge` + `input`) |
+
+Three of those — `slider`, `radio` and `tags` — had no primitive in this package
+and are composed inside `schema-form/widgets/`. They are deliberately not
+top-level exports: their only caller is the renderer, and a widget promoted to
+the catalogue before a second consumer wants it is a shape nobody agreed to.
+
+### The layout vocabulary
+
+`VerticalLayout`, `HorizontalLayout`, `Group` (a `Panel`), `Categorization` /
+`Category` (a `Tabs` set), `Control` and `Label`. Anything else is
+`unknown-element`.
+
+`rule` is evaluated on every element, not only on Controls, so a rule on a Group
+takes the whole group with it — which is what an author writing one means.
+`SHOW` / `HIDE` decide whether the element renders at all; `ENABLE` / `DISABLE`
+and `options.readonly` disable the control instead.
+
+### The engine
+
+`@jsonforms/core` is used **headless**: JSON Pointer scope resolution, rule
+evaluation and the Ajv instance, nothing else. The renderers are this package's
+own and dispatch to this package's own widgets. There is no official Svelte
+renderer for JSON Forms and the community one carries no external validation, so
+neither is used.
+
+JSON Forms was chosen over RJSF and `@sjsf/form` on one deciding fact: the
+upstream config models carry 36 conditional-visibility rules, and JSON Forms'
+`rule` model maps onto them 1:1, while RJSF has no standard conditional-
+visibility directive. `@jsonforms/core@3.8.0` was verified working headless
+under Svelte 5 in this package before it was adopted, on 21/08/2026 — scope
+resolution through `$ref`, `SHOW`/`HIDE`/`DISABLE` evaluation, and
+`Generate.uiSchema` all exercised live. It is the package's only runtime
+dependency beyond what was already here.
+
 ## Consuming the package
 
 Published to public npm under the `@poodle64` scope, same as `@poodle64/design-tokens`

package/dist/components/ui/collection-detail/collection-detail.svelte

@@ -0,0 +1,169 @@
+<script lang="ts">
+	/**
+	 * CollectionDetail — one collection's surface: its identity (name, meta,
+	 * state), an at-a-glance stat list, and the documents it holds.
+	 *
+	 * Fixed props over plain data (#30): the page fetches, maps its responses
+	 * into the shared library vocabulary, and owns the pager offset. Anything
+	 * app-specific — a config form, an operations tab, action buttons — comes
+	 * in through `actions` (the identity panel's footer) and `children`
+	 * (sections rendered after the documents), so the app extends the surface
+	 * without forking it.
+	 */
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { cn, type WithElementRef } from '../../../utils.js';
+	import Button from '../button/button.svelte';
+	import DetailPanel from '../detail-panel/detail-panel.svelte';
+	import Panel from '../panel/panel.svelte';
+	import StatList from '../stat-list/stat-list.svelte';
+	import type { StatItem } from '../stat-list/stat-list.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 DocumentTable from '../library-browse/document-table.svelte';
+	import type { LibraryCollection, LibraryDocument } from '../library-browse/types.js';
+
+	let {
+		collection,
+		stats = [],
+		documents = [],
+		documentsTotal,
+		offset = 0,
+		limit = 25,
+		loading = false,
+		error = null,
+		documentsLoading = false,
+		documentsError = null,
+		emptyTitle = 'No documents in this collection yet',
+		emptyDescription,
+		notFoundTitle = 'Collection not found',
+		notFoundDescription,
+		onPageChange,
+		onRetry,
+		documentHref,
+		onOpenDocument,
+		actions,
+		children,
+		ref = $bindable(null),
+		class: className,
+		...restProps
+	}: WithElementRef<HTMLAttributes<HTMLDivElement>> & {
+		collection: LibraryCollection | null;
+		/** At-a-glance figures for the collection (document count, indexed, …). */
+		stats?: StatItem[];
+		documents?: LibraryDocument[];
+		/** Total documents across all pages; defaults to the rows given. */
+		documentsTotal?: number;
+		offset?: number;
+		limit?: number;
+		/** The collection itself is still loading. */
+		loading?: boolean;
+		error?: string | null;
+		/** The document list loads independently of the identity. */
+		documentsLoading?: boolean;
+		documentsError?: string | null;
+		emptyTitle?: string;
+		emptyDescription?: string;
+		notFoundTitle?: string;
+		notFoundDescription?: string;
+		onPageChange?: (offset: number) => void;
+		onRetry?: () => void;
+		documentHref?: (doc: LibraryDocument) => string;
+		onOpenDocument?: (doc: LibraryDocument) => void;
+		/** App-specific controls, rendered in the identity panel's footer. */
+		actions?: Snippet;
+		/** App-specific sections rendered after the documents. */
+		children?: Snippet;
+	} = $props();
+
+	const shownTotal = $derived(documentsTotal ?? 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}>
+	{#if loading}
+		<LoadingState message="Loading the collection…" />
+	{:else if error}
+		<ErrorState message={error}>
+			{#snippet action()}
+				{#if onRetry}
+					<Button variant="outline" onclick={onRetry}>Retry</Button>
+				{/if}
+			{/snippet}
+		</ErrorState>
+	{:else if !collection}
+		<EmptyState title={notFoundTitle} description={notFoundDescription} />
+	{:else}
+		<DetailPanel
+			eyebrow="Collection"
+			title={collection.name}
+			titleFace="display"
+			status={collection.badge?.status}
+			statusLabel={collection.badge?.label}
+			footer={actions}
+		>
+			{#if collection.subtitle}
+				<p class="text-muted-foreground text-sm">{collection.subtitle}</p>
+			{/if}
+			{#if collection.description}
+				<p class="mt-2 max-w-prose text-sm">{collection.description}</p>
+			{/if}
+			{#if !collection.subtitle && !collection.description}
+				<p class="text-muted-foreground text-sm">No description recorded.</p>
+			{/if}
+		</DetailPanel>
+
+		{#if stats.length > 0}
+			<StatList items={stats} />
+		{/if}
+
+		{#if documentsLoading}
+			<LoadingState message="Loading the documents…" />
+		{:else if documentsError}
+			<ErrorState message={documentsError}>
+				{#snippet action()}
+					{#if onRetry}
+						<Button variant="outline" onclick={onRetry}>Retry</Button>
+					{/if}
+				{/snippet}
+			</ErrorState>
+		{:else if documents.length === 0}
+			<EmptyState title={emptyTitle} description={emptyDescription} />
+		{:else}
+			<Panel title="Documents" subtitle="{shownTotal} document{shownTotal === 1 ? '' : 's'}">
+				<div class="flex flex-col gap-3">
+					<DocumentTable {documents} {documentHref} onOpen={onOpenDocument} />
+					{#if onPageChange && shownTotal > pageSize}
+						<div class="flex flex-wrap items-center justify-end 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>
+			</Panel>
+		{/if}
+
+		{#if children}
+			{@render children()}
+		{/if}
+	{/if}
+</div>

package/dist/components/ui/collection-detail/collection-detail.svelte.d.ts

@@ -0,0 +1,47 @@
+/**
+     * CollectionDetail — one collection's surface: its identity (name, meta,
+     * state), an at-a-glance stat list, and the documents it holds.
+     *
+     * Fixed props over plain data (#30): the page fetches, maps its responses
+     * into the shared library vocabulary, and owns the pager offset. Anything
+     * app-specific — a config form, an operations tab, action buttons — comes
+     * in through `actions` (the identity panel's footer) and `children`
+     * (sections rendered after the documents), so the app extends the surface
+     * without forking it.
+     */
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type WithElementRef } from '../../../utils.js';
+import type { StatItem } from '../stat-list/stat-list.svelte';
+import type { LibraryCollection, LibraryDocument } from '../library-browse/types.js';
+type $$ComponentProps = WithElementRef<HTMLAttributes<HTMLDivElement>> & {
+    collection: LibraryCollection | null;
+    /** At-a-glance figures for the collection (document count, indexed, …). */
+    stats?: StatItem[];
+    documents?: LibraryDocument[];
+    /** Total documents across all pages; defaults to the rows given. */
+    documentsTotal?: number;
+    offset?: number;
+    limit?: number;
+    /** The collection itself is still loading. */
+    loading?: boolean;
+    error?: string | null;
+    /** The document list loads independently of the identity. */
+    documentsLoading?: boolean;
+    documentsError?: string | null;
+    emptyTitle?: string;
+    emptyDescription?: string;
+    notFoundTitle?: string;
+    notFoundDescription?: string;
+    onPageChange?: (offset: number) => void;
+    onRetry?: () => void;
+    documentHref?: (doc: LibraryDocument) => string;
+    onOpenDocument?: (doc: LibraryDocument) => void;
+    /** App-specific controls, rendered in the identity panel's footer. */
+    actions?: Snippet;
+    /** App-specific sections rendered after the documents. */
+    children?: Snippet;
+};
+declare const CollectionDetail: import("svelte").Component<$$ComponentProps, {}, "ref">;
+type CollectionDetail = ReturnType<typeof CollectionDetail>;
+export default CollectionDetail;

package/dist/components/ui/collection-detail/index.d.ts

@@ -0,0 +1,3 @@
+export { default as CollectionDetail } from './collection-detail.svelte';
+export { default } from './collection-detail.svelte';
+export type { LibraryBadge, LibraryCollection, LibraryDocument } from '../library-browse/types.js';

package/dist/components/ui/collection-detail/index.js

@@ -0,0 +1,2 @@
+export { default as CollectionDetail } from './collection-detail.svelte';
+export { default } from './collection-detail.svelte';

package/dist/components/ui/document-detail/document-detail.svelte

@@ -0,0 +1,184 @@
+<script lang="ts">
+	/**
+	 * DocumentDetail — one document's surface: its identity fields, recorded
+	 * locations, tags, and collection memberships.
+	 *
+	 * Fixed props over plain data (#30). Sections render only when their data
+	 * is present, so a consumer whose documents carry no locations never shows
+	 * an empty heading. App-specific work — retract/re-extract buttons, an
+	 * operations history — comes in through `actions` (the panel's footer) and
+	 * `children` (sections after the panel); membership links are the app's
+	 * own routed links via `collectionHref`, because this package has no
+	 * router.
+	 */
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { cn, type WithElementRef } from '../../../utils.js';
+	import Button from '../button/button.svelte';
+	import { Badge } from '../badge/index.js';
+	import DetailPanel from '../detail-panel/detail-panel.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 { LibraryDocumentDetail, LibraryMembership } from '../library-browse/types.js';
+
+	let {
+		document,
+		loading = false,
+		error = null,
+		notFoundTitle = 'Document not found',
+		notFoundDescription = 'This document is not in the catalogue.',
+		collectionHref,
+		onOpenCollection,
+		onRetry,
+		actions,
+		children,
+		ref = $bindable(null),
+		class: className,
+		...restProps
+	}: WithElementRef<HTMLAttributes<HTMLDivElement>> & {
+		document: LibraryDocumentDetail | null;
+		loading?: boolean;
+		error?: string | null;
+		notFoundTitle?: string;
+		notFoundDescription?: string;
+		/** The app's own routed link per membership. */
+		collectionHref?: (membership: LibraryMembership) => string;
+		onOpenCollection?: (membership: LibraryMembership) => void;
+		onRetry?: () => void;
+		/** App-specific controls, rendered in the panel's footer. */
+		actions?: Snippet;
+		/** App-specific sections rendered after the panel. */
+		children?: Snippet;
+	} = $props();
+</script>
+
+<div bind:this={ref} class={cn('flex flex-col gap-4', className)} {...restProps}>
+	{#if loading}
+		<LoadingState message="Loading the document…" />
+	{:else if error}
+		<ErrorState message={error}>
+			{#snippet action()}
+				{#if onRetry}
+					<Button variant="outline" onclick={onRetry}>Retry</Button>
+				{/if}
+			{/snippet}
+		</ErrorState>
+	{:else if !document}
+		<EmptyState title={notFoundTitle} description={notFoundDescription} />
+	{:else}
+		<DetailPanel eyebrow="Document" title={document.title} titleFace="display" footer={actions}>
+			<div class="grid gap-4 sm:grid-cols-2">
+				{#if document.fields?.length}
+					<div>
+						<h3 class="text-muted-foreground text-2xs mb-2 font-semibold tracking-wide uppercase">
+							Details
+						</h3>
+						<dl class="space-y-1 text-sm">
+							{#each document.fields as field (field.label)}
+								<div class="flex justify-between gap-4">
+									<dt class="text-muted-foreground">{field.label}</dt>
+									<dd class={field.mono ? 'truncate font-mono text-xs' : 'text-right'}>
+										{field.value}
+									</dd>
+								</div>
+							{/each}
+						</dl>
+					</div>
+				{/if}
+
+				{#if document.locations?.length}
+					<div>
+						<h3 class="text-muted-foreground text-2xs mb-2 font-semibold tracking-wide uppercase">
+							Locations
+						</h3>
+						<ul class="space-y-1 text-sm">
+							{#each document.locations as location (location.path)}
+								<li class="flex items-center justify-between gap-2">
+									<span class="truncate font-mono text-xs">{location.path}</span>
+									<div class="flex shrink-0 items-center gap-1">
+										{#if location.primary}
+											<Badge variant="secondary">primary</Badge>
+										{/if}
+										{#if location.badge}
+											<StatusBadge status={location.badge.status} label={location.badge.label} />
+										{/if}
+									</div>
+								</li>
+							{/each}
+						</ul>
+					</div>
+				{/if}
+
+				{#if document.tags?.length}
+					<div>
+						<h3 class="text-muted-foreground text-2xs mb-2 font-semibold tracking-wide uppercase">
+							Tags
+						</h3>
+						<div class="flex flex-wrap gap-1.5">
+							{#each document.tags as tag (tag)}
+								<Badge variant="outline">{tag}</Badge>
+							{/each}
+						</div>
+					</div>
+				{/if}
+
+				{#if document.memberships?.length}
+					<div>
+						<h3 class="text-muted-foreground text-2xs mb-2 font-semibold tracking-wide uppercase">
+							Collections
+						</h3>
+						<div class="flex flex-wrap gap-1.5">
+							{#each document.memberships as membership (membership.id)}
+								{#if collectionHref}
+									<a
+										href={collectionHref(membership)}
+										class="inline-flex items-center gap-1"
+										onclick={() => onOpenCollection?.(membership)}
+									>
+										<Badge variant="outline">{membership.name}</Badge>
+										{#if membership.badge}
+											<StatusBadge
+												status={membership.badge.status}
+												label={membership.badge.label}
+											/>
+										{/if}
+									</a>
+								{:else if onOpenCollection}
+									<button
+										type="button"
+										class="inline-flex items-center gap-1"
+										onclick={() => onOpenCollection(membership)}
+									>
+										<Badge variant="outline">{membership.name}</Badge>
+										{#if membership.badge}
+											<StatusBadge
+												status={membership.badge.status}
+												label={membership.badge.label}
+											/>
+										{/if}
+									</button>
+								{:else}
+									<span class="inline-flex items-center gap-1">
+										<Badge variant="outline">{membership.name}</Badge>
+										{#if membership.badge}
+											<StatusBadge
+												status={membership.badge.status}
+												label={membership.badge.label}
+											/>
+										{/if}
+									</span>
+								{/if}
+							{/each}
+						</div>
+					</div>
+				{/if}
+			</div>
+		</DetailPanel>
+
+		{#if children}
+			{@render children()}
+		{/if}
+	{/if}
+</div>