@poodle64/ui 2026.8.10 → 2026.8.12

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>

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

@@ -0,0 +1,34 @@
+/**
+     * 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 { type WithElementRef } from '../../../utils.js';
+import type { LibraryDocumentDetail, LibraryMembership } from '../library-browse/types.js';
+type $$ComponentProps = 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;
+};
+declare const DocumentDetail: import("svelte").Component<$$ComponentProps, {}, "ref">;
+type DocumentDetail = ReturnType<typeof DocumentDetail>;
+export default DocumentDetail;

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

@@ -0,0 +1,3 @@
+export { default as DocumentDetail } from './document-detail.svelte';
+export { default } from './document-detail.svelte';
+export type { LibraryBadge, LibraryDocumentDetail, LibraryField, LibraryLocation, LibraryMembership } from '../library-browse/types.js';

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

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

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

@@ -0,0 +1,101 @@
+<script lang="ts">
+	// The one catalogue table, shared by LibraryBrowse and CollectionDetail so
+	// the two surfaces cannot drift apart. Columns come and go with the data —
+	// a consumer that passes no `collections` never sees an empty column —
+	// which is what lets one table serve both the whole-catalogue view and a
+	// single collection's slice.
+	import {
+		Table as TableRoot,
+		TableBody,
+		TableCell,
+		TableHead,
+		TableHeader,
+		TableRow
+	} from '../table/index.js';
+	import StatusBadge from '../status-badge/status-badge.svelte';
+	import type { LibraryDocument } from './types.js';
+
+	let {
+		documents,
+		documentHref,
+		onOpen
+	}: {
+		documents: LibraryDocument[];
+		/** The app's own routed link per row; this package has no router of its own. */
+		documentHref?: (doc: LibraryDocument) => string;
+		onOpen?: (doc: LibraryDocument) => void;
+	} = $props();
+
+	const hasTags = $derived(documents.some((d) => d.tags?.length));
+	const hasCollections = $derived(documents.some((d) => d.collections?.length));
+	const hasBadges = $derived(documents.some((d) => d.badges?.length));
+</script>
+
+<div class="rounded-md border">
+	<TableRoot>
+		<TableHeader>
+			<TableRow>
+				<TableHead>Title</TableHead>
+				{#if hasTags}
+					<TableHead class="w-40">Tags</TableHead>
+				{/if}
+				{#if hasCollections}
+					<TableHead class="w-40">Collections</TableHead>
+				{/if}
+				{#if hasBadges}
+					<TableHead class="w-40 text-center">Status</TableHead>
+				{/if}
+			</TableRow>
+		</TableHeader>
+		<TableBody>
+			{#each documents as doc (doc.id)}
+				<TableRow>
+					<TableCell>
+						{#if documentHref}
+							<a
+								href={documentHref(doc)}
+								class="font-medium hover:underline"
+								onclick={() => onOpen?.(doc)}
+							>
+								{doc.title}
+							</a>
+						{:else if onOpen}
+							<button
+								type="button"
+								class="text-left font-medium hover:underline"
+								onclick={() => onOpen(doc)}
+							>
+								{doc.title}
+							</button>
+						{:else}
+							<span class="font-medium">{doc.title}</span>
+						{/if}
+					</TableCell>
+					{#if hasTags}
+						<TableCell class="text-muted-foreground text-xs">
+							{doc.tags?.join(', ') || '—'}
+						</TableCell>
+					{/if}
+					{#if hasCollections}
+						<TableCell class="text-muted-foreground text-xs">
+							{doc.collections?.join(', ') || '—'}
+						</TableCell>
+					{/if}
+					{#if hasBadges}
+						<TableCell class="text-center">
+							<div class="flex flex-wrap justify-center gap-1">
+								<!-- Keyed by index: LibraryBadge carries no id, and two memberships
+								     can legitimately map to the same label+status. -->
+								{#each doc.badges ?? [] as badge, i (i)}
+									<StatusBadge status={badge.status} label={badge.label} />
+								{:else}
+									<span class="text-muted-foreground text-xs">—</span>
+								{/each}
+							</div>
+						</TableCell>
+					{/if}
+				</TableRow>
+			{/each}
+		</TableBody>
+	</TableRoot>
+</div>

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

@@ -0,0 +1,10 @@
+import type { LibraryDocument } from './types.js';
+type $$ComponentProps = {
+    documents: LibraryDocument[];
+    /** The app's own routed link per row; this package has no router of its own. */
+    documentHref?: (doc: LibraryDocument) => string;
+    onOpen?: (doc: LibraryDocument) => void;
+};
+declare const DocumentTable: import("svelte").Component<$$ComponentProps, {}, "">;
+type DocumentTable = ReturnType<typeof DocumentTable>;
+export default DocumentTable;

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

@@ -0,0 +1,62 @@
+<script lang="ts">
+	// The facet rail beside the catalogue. Selection state belongs to the page
+	// (the app re-queries its own backend on change); this only renders the
+	// dimensions it is given and hands the next selection back.
+	import type { LibraryFacet } from './types.js';
+
+	let {
+		facets,
+		onChange
+	}: {
+		facets: LibraryFacet[];
+		onChange?: (key: string, selected: string[]) => void;
+	} = $props();
+
+	function toggle(facet: LibraryFacet, value: string) {
+		const has = facet.selected.includes(value);
+		if (facet.multiple) {
+			onChange?.(
+				facet.key,
+				has ? facet.selected.filter((v) => v !== value) : [...facet.selected, value]
+			);
+		} else {
+			onChange?.(facet.key, has ? [] : [value]);
+		}
+	}
+</script>
+
+<div class="space-y-4">
+	{#each facets as facet (facet.key)}
+		<div>
+			<h3 class="text-muted-foreground text-2xs mb-1 font-semibold tracking-wide uppercase">
+				{facet.label}
+			</h3>
+			{#if facet.options.length === 0}
+				<p class="text-muted-foreground text-xs">Populates once the catalogue holds documents.</p>
+			{:else}
+				<ul class="space-y-0.5">
+					{#each facet.options as option (option.value)}
+						{@const active = facet.selected.includes(option.value)}
+						<li>
+							<button
+								type="button"
+								aria-pressed={active}
+								class="hover:bg-muted flex w-full items-center justify-between rounded px-1.5 py-1 text-left text-sm {active
+									? 'bg-muted font-medium'
+									: ''}"
+								onclick={() => toggle(facet, option.value)}
+							>
+								<span class="truncate">{option.label ?? option.value}</span>
+								{#if option.count !== undefined}
+									<span class="text-muted-foreground font-mono text-xs tabular-nums">
+										{option.count}
+									</span>
+								{/if}
+							</button>
+						</li>
+					{/each}
+				</ul>
+			{/if}
+		</div>
+	{/each}
+</div>

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

@@ -0,0 +1,8 @@
+import type { LibraryFacet } from './types.js';
+type $$ComponentProps = {
+    facets: LibraryFacet[];
+    onChange?: (key: string, selected: string[]) => void;
+};
+declare const FacetRail: import("svelte").Component<$$ComponentProps, {}, "">;
+type FacetRail = ReturnType<typeof FacetRail>;
+export default FacetRail;

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

@@ -0,0 +1,3 @@
+export { default as LibraryBrowse } from './library-browse.svelte';
+export { default } from './library-browse.svelte';
+export type { LibraryBadge, LibraryDocument, LibraryFacet, LibraryFacetOption, LibraryField, LibraryLocation, LibraryMembership, LibraryDocumentDetail, LibraryCollection, LibrarySearchResult, SearchSnippetSegment } from './types.js';

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

@@ -0,0 +1,2 @@
+export { default as LibraryBrowse } from './library-browse.svelte';
+export { default } from './library-browse.svelte';