@poodle64/ui 2026.10.4 → 2026.10.5

package/dist/components/ui/record-list/record-list.svelte.d.ts

@@ -0,0 +1,89 @@
+/**
+     * The ledger's look for a list that is not money: properties, managers,
+     * tools, the lines of a profit and loss. The same bar, head card, row cards
+     * and group labels on the ground as the Ledger, so every list in an app
+     * reads one way. The consumer brings its rows and the columns it offers; the
+     * list owns the look, the grouping, the sort and the viewer's columns,
+     * which it emits for the consumer to keep.
+     *
+     * A row is its thumbnail, its title and a second line of flags and a note,
+     * then the module's columns. It opens by its link (`href`) or by `onOpen`,
+     * which marks the row `open` names, for a detail beside the list.
+     *
+     * It fills its parent's height and scrolls its own rows, so the head card
+     * stays at the top: give it a bounded parent (`flex-1 min-h-0`). Width picks
+     * the layout, as the Ledger's does: a phone's list below 600px, the wide
+     * tracks and the `'wide'` columns from 1200px. On a phone a row is its
+     * thumbnail, title and lines, with the first end-aligned column's value
+     * beside the title.
+     */
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { ListAction, ListIconAction } from '../list-toolbar/types.js';
+import type { IconComponent } from '../app-shell/types.js';
+import type { RecordListColumn, RecordListPreferences, RecordListRow } from './types.js';
+declare function $$render<R extends RecordListRow>(): {
+    props: Omit<HTMLAttributes<HTMLDivElement>, "title"> & {
+        rows: readonly R[];
+        /** The module's columns, in order after the title. See `RecordListColumn`. */
+        columns?: RecordListColumn<R>[];
+        /** The viewer's columns. Missing, the module's defaults. */
+        preferences?: Partial<RecordListPreferences>;
+        onPreferencesChange?: (next: RecordListPreferences) => void;
+        /** The Columns menu's footnote: where the choice is kept. */
+        preferencesNote?: string;
+        /** What a row is, one and many: "property", "properties". */
+        noun?: [string, string];
+        title?: string;
+        /** Beside the title. Defaults to the row count. */
+        meta?: string;
+        /** Before the title: a switch between views of the same list. */
+        leading?: Snippet;
+        /** The bar's own controls, after the Columns menu. */
+        toolbar?: Snippet;
+        /** The bar's icon actions, each named by its tooltip. */
+        tools?: ListIconAction[];
+        /** The bar's one labelled action, last. */
+        action?: ListAction;
+        /** A row's group, by its label: groups show in the order their first rows come. */
+        group?: (row: R) => string;
+        /** Names a card after the rows with each column's total over every row: "All three". */
+        totalLabel?: string;
+        /** The head card. A list whose columns need no heads drops it. */
+        head?: boolean;
+        /** The tile a row without a photo or its own icon shows. With it every row has a thumbnail. */
+        icon?: IconComponent;
+        /** Where a row leads. */
+        href?: (row: R) => string | undefined;
+        /** A row's click, for a detail beside the list. */
+        onOpen?: (row: R) => void;
+        /** The row whose detail is open, marked. */
+        open?: R["id"] | null;
+        empty?: Snippet;
+        /** After the last row, inside the scroll. */
+        footer?: Snippet;
+        layout?: "auto" | "phone" | "narrow" | "wide";
+        class?: string;
+    };
+    exports: {};
+    bindings: "preferences";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<R extends RecordListRow> {
+    props(): ReturnType<typeof $$render<R>>['props'];
+    events(): ReturnType<typeof $$render<R>>['events'];
+    slots(): ReturnType<typeof $$render<R>>['slots'];
+    bindings(): "preferences";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <R extends RecordListRow>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<R>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<R>['props']>, ReturnType<__sveltets_Render<R>['events']>, ReturnType<__sveltets_Render<R>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<R>['bindings']>;
+    } & ReturnType<__sveltets_Render<R>['exports']>;
+    <R extends RecordListRow>(internal: unknown, props: ReturnType<__sveltets_Render<R>['props']> & {}): ReturnType<__sveltets_Render<R>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const RecordList: $$IsomorphicComponent;
+type RecordList<R extends RecordListRow> = InstanceType<typeof RecordList<R>>;
+export default RecordList;

package/dist/components/ui/record-list/thumbnail.svelte

@@ -0,0 +1,32 @@
+<script lang="ts">
+	/**
+	 * A record's picture at a fixed size: its photo, or a quiet tile with the
+	 * module's icon when it has none or the photo fails to load. Decorative:
+	 * the record's name always sits beside it.
+	 */
+	import type { IconComponent } from '../app-shell/types.js';
+	import { cn } from '../../../utils.js';
+
+	let {
+		src,
+		icon: Icon,
+		class: className
+	}: { src?: string | null; icon?: IconComponent; class?: string } = $props();
+
+	let failed = $state<string | null>(null);
+</script>
+
+<span
+	class={cn(
+		'bg-surface-2 border-border/60 grid flex-none place-items-center overflow-hidden rounded-md border',
+		className
+	)}
+	aria-hidden="true"
+	data-slot="record-thumbnail"
+>
+	{#if src && failed !== src}
+		<img {src} alt="" loading="lazy" class="size-full object-cover" onerror={() => (failed = src)} />
+	{:else if Icon}
+		<Icon class="text-primary size-1/2" />
+	{/if}
+</span>

package/dist/components/ui/record-list/thumbnail.svelte.d.ts

@@ -0,0 +1,14 @@
+/**
+     * A record's picture at a fixed size: its photo, or a quiet tile with the
+     * module's icon when it has none or the photo fails to load. Decorative:
+     * the record's name always sits beside it.
+     */
+import type { IconComponent } from '../app-shell/types.js';
+type $$ComponentProps = {
+    src?: string | null;
+    icon?: IconComponent;
+    class?: string;
+};
+declare const Thumbnail: import("svelte").Component<$$ComponentProps, {}, "">;
+type Thumbnail = ReturnType<typeof Thumbnail>;
+export default Thumbnail;

package/dist/components/ui/record-list/types.d.ts

@@ -0,0 +1,40 @@
+import type { IconComponent } from '../app-shell/types.js';
+import type { ListColumn } from '../ledger/types.js';
+import type { Status } from '../status/index.js';
+/** Something on file that wants the viewer: a chip on the row's second line. */
+export interface RecordFlag {
+    status: Status;
+    label: string;
+}
+/** What the list reads off a row. A consumer extends it with its own fields for its columns. */
+export interface RecordListRow {
+    id: string | number;
+    /** Line one: the record's name. */
+    title: string;
+    /** Line two, after any flags. */
+    note?: string | null;
+    /** A thumbnail before the title. Without one, `icon` or the list's `icon` stands in. */
+    image?: string | null;
+    /** The row's own tile, where each row is a kind of thing (a tool) rather than a photo. */
+    icon?: IconComponent;
+    /**
+     * What wants the viewer, first first. Line two shows the first as a chip
+     * and "+N more" naming the rest on hover; a phone's row shows every one.
+     */
+    flags?: readonly RecordFlag[] | null;
+}
+/**
+ * A column the module offers. The key `title` is the list's own cell (the
+ * thumbnail, the title, the flags and the note): list it to rename or resize
+ * it, or to draw it yourself with `cell`. It always shows, first. Every other
+ * key is the module's, in its order.
+ */
+export interface RecordListColumn<R extends RecordListRow = RecordListRow> extends ListColumn<R> {
+    /** The column's total over some rows: each group's on its label, all rows' in the total card. */
+    total?: (rows: readonly R[]) => string;
+}
+/** The viewer's own choices, which the consumer persists. */
+export interface RecordListPreferences {
+    /** The ticked columns' keys. */
+    columns: string[];
+}

package/dist/components/ui/record-list/types.js

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

package/dist/components/ui/record-switcher/index.d.ts

@@ -0,0 +1,3 @@
+export { default as RecordSwitcher } from './record-switcher.svelte';
+export { default } from './record-switcher.svelte';
+export type { RecordPage, RecordSwitcherGroup, RecordSwitcherItem } from './types.js';

package/dist/components/ui/record-switcher/index.js

@@ -0,0 +1,2 @@
+export { default as RecordSwitcher } from './record-switcher.svelte';
+export { default } from './record-switcher.svelte';

package/dist/components/ui/record-switcher/record-switcher.svelte

@@ -0,0 +1,167 @@
+<script lang="ts">
+	/**
+	 * The open record's whole name as the top bar's control: a raised button
+	 * with its chevron inside, after the section's name. Its menu finds a
+	 * record by name, lists them under their headings (owned, then sold) with
+	 * a thumbnail each, and ends with the way to all of them, so it still
+	 * works at fifty. The record's own pages follow as tabs.
+	 *
+	 * It places nothing itself: put it inside `ShellControls` with whatever
+	 * else the page sets in the bar.
+	 *
+	 *     <ShellControls>
+	 *       <RecordSwitcher name="4. Banksia" current={4} groups={[owned, sold]}
+	 *         noun="property" icon={House} all={{ label: 'All properties', href: '/property' }}
+	 *         pages={[{ label: 'Overview', href: '/property/4', current: true }, …]} />
+	 *     </ShellControls>
+	 */
+	import { Command as CommandPrimitive, computeCommandScore } from 'bits-ui';
+	import Check from '@lucide/svelte/icons/check';
+	import ChevronDown from '@lucide/svelte/icons/chevron-down';
+	import { buttonVariants } from '../button/index.js';
+	import * as Command from '../command/index.js';
+	import * as Popover from '../popover/index.js';
+	import type { IconComponent } from '../app-shell/types.js';
+	import Thumbnail from '../record-list/thumbnail.svelte';
+	import { cn } from '../../../utils.js';
+	import type { RecordPage, RecordSwitcherGroup, RecordSwitcherItem } from './types.js';
+
+	let {
+		name,
+		current,
+		groups,
+		noun = 'record',
+		placeholder = `Find a ${noun}`,
+		icon,
+		all,
+		pages = [],
+		separator = true,
+		open = $bindable(false),
+		class: className
+	}: {
+		/** The open record's whole name. */
+		name: string;
+		/** The open record's id, ticked in the menu. */
+		current?: string | number;
+		groups: readonly RecordSwitcherGroup[];
+		/** What a record is, for the control's name and the search's prompt. */
+		noun?: string;
+		placeholder?: string;
+		/** The tile a record without a photo shows. With it every record has a thumbnail. */
+		icon?: IconComponent;
+		/** The menu's last line: every record, on its list. */
+		all?: { label: string; href: string };
+		/** The open record's own pages, as tabs after its name. */
+		pages?: readonly RecordPage[];
+		/** The "/" after the section's name. Off where it is not in the bar. */
+		separator?: boolean;
+		open?: boolean;
+		class?: string;
+	} = $props();
+
+	const thumbs = $derived(!!icon || groups.some((g) => g.items.some((i) => i.image)));
+	/** An item's key in the menu; the search reads its name and note, never this. */
+	const valueOf = (item: RecordSwitcherItem) => `record:${item.id}`;
+	const words = $derived(
+		new Map(groups.flatMap((g) => g.items).map((i) => [valueOf(i), `${i.label} ${i.note ?? ''}`]))
+	);
+	const filter = (value: string, search: string) =>
+		computeCommandScore(words.get(value) ?? value, search);
+	const here = () => {
+		const item = groups.flatMap((g) => g.items).find((i) => i.id === current);
+		return item ? valueOf(item) : '';
+	};
+	/**
+	 * The highlighted record: the open one, set as the menu opens, before the
+	 * list mounts, or the list would start on its first row.
+	 */
+	// svelte-ignore state_referenced_locally
+	let highlighted = $state(here());
+	const eyebrow = 'text-muted-foreground text-2xs tracking-eyebrow font-semibold uppercase';
+</script>
+
+<div class={cn('flex min-w-0 items-center gap-2 sm:gap-3', className)} data-slot="record-switcher">
+	{#if separator}<span class="text-shell-muted-foreground flex-none" aria-hidden="true">/</span>{/if}
+	<Popover.Root bind:open onOpenChange={(o) => o && (highlighted = here())}>
+		<Popover.Trigger
+			class={cn(
+				buttonVariants({ variant: 'outline', size: 'sm' }),
+				'bg-card min-w-0 gap-1.5 text-sm font-semibold'
+			)}
+			aria-label="{name}: switch to another {noun}"
+			data-slot="record-switcher-trigger"
+		>
+			<span class="truncate">{name}</span>
+			<ChevronDown class="text-muted-foreground" />
+		</Popover.Trigger>
+		<Popover.Content align="start" class="w-[min(24rem,calc(100vw-2rem))] p-0">
+			<Command.Root class="rounded-md!" label={placeholder} {filter} loop bind:value={highlighted}>
+				<Command.Input {placeholder} />
+				<Command.List class="max-h-[min(28rem,60vh)] px-1 pt-1">
+					<Command.Empty class="text-muted-foreground py-5">No {noun} by that name</Command.Empty>
+					{#each groups as g, gi (g.label ?? gi)}
+						<CommandPrimitive.Group class="pb-1" value={g.label ?? `group-${gi}`}>
+							{#if g.label}
+								<CommandPrimitive.GroupHeading class={cn(eyebrow, 'px-2 pt-2 pb-1.5')}>
+									{g.label}
+								</CommandPrimitive.GroupHeading>
+							{/if}
+							<CommandPrimitive.GroupItems>
+								{#each g.items as item (item.id)}
+									{@const on = item.id === current}
+									<Command.LinkItem
+										href={item.href}
+										value={valueOf(item)}
+										onSelect={() => (open = false)}
+										onclick={() => (open = false)}
+										aria-current={on ? 'page' : undefined}
+										class={cn('gap-3 rounded-md py-1.5', on && 'bg-primary/10')}
+										data-slot="record-switcher-item"
+									>
+										{#if thumbs}<Thumbnail src={item.image} {icon} class="size-10" />{/if}
+										<span class="flex min-w-0 flex-1 flex-col">
+											<span class="text-foreground truncate font-medium">{item.label}</span>
+											{#if item.note}
+												<span class="text-muted-foreground truncate text-xs">{item.note}</span>
+											{/if}
+										</span>
+										{#if on}<Check class="text-primary size-4" /><span class="sr-only">, open now</span>{/if}
+									</Command.LinkItem>
+								{/each}
+							</CommandPrimitive.GroupItems>
+						</CommandPrimitive.Group>
+					{/each}
+				</Command.List>
+				{#if all}
+					<div class="border-border border-t p-1">
+						<a
+							href={all.href}
+							class="text-foreground hover:bg-accent focus-visible:ring-ring/50 block rounded-md px-2 py-2 text-sm underline underline-offset-4 focus-visible:ring-3 focus-visible:outline-none"
+							onclick={() => (open = false)}
+							data-slot="record-switcher-all">{all.label}</a
+						>
+					</div>
+				{/if}
+			</Command.Root>
+		</Popover.Content>
+	</Popover.Root>
+
+	{#if pages.length}
+		<nav aria-label="Pages of {name}" class="ml-1 flex items-stretch gap-1 self-stretch sm:ml-3">
+			{#each pages as p (p.href)}
+				<a
+					href={p.href}
+					aria-current={p.current ? 'page' : undefined}
+					class={cn(
+						'flex items-center border-b-2 px-2 text-sm transition-colors sm:px-3',
+						p.current
+							? 'border-primary text-foreground font-semibold'
+							: 'text-muted-foreground hover:text-foreground border-transparent'
+					)}
+				>
+					{p.label}
+				</a>
+			{/each}
+		</nav>
+	{/if}
+</div>

package/dist/components/ui/record-switcher/record-switcher.svelte.d.ts

@@ -0,0 +1,28 @@
+import type { IconComponent } from '../app-shell/types.js';
+import type { RecordPage, RecordSwitcherGroup } from './types.js';
+type $$ComponentProps = {
+    /** The open record's whole name. */
+    name: string;
+    /** The open record's id, ticked in the menu. */
+    current?: string | number;
+    groups: readonly RecordSwitcherGroup[];
+    /** What a record is, for the control's name and the search's prompt. */
+    noun?: string;
+    placeholder?: string;
+    /** The tile a record without a photo shows. With it every record has a thumbnail. */
+    icon?: IconComponent;
+    /** The menu's last line: every record, on its list. */
+    all?: {
+        label: string;
+        href: string;
+    };
+    /** The open record's own pages, as tabs after its name. */
+    pages?: readonly RecordPage[];
+    /** The "/" after the section's name. Off where it is not in the bar. */
+    separator?: boolean;
+    open?: boolean;
+    class?: string;
+};
+declare const RecordSwitcher: import("svelte").Component<$$ComponentProps, {}, "open">;
+type RecordSwitcher = ReturnType<typeof RecordSwitcher>;
+export default RecordSwitcher;

package/dist/components/ui/record-switcher/types.d.ts

@@ -0,0 +1,22 @@
+/** A record another can be switched to. */
+export interface RecordSwitcherItem {
+    id: string | number;
+    /** Its whole name, as the switcher shows it when it is the one open. */
+    label: string;
+    /** Under the name: where it is, what it is worth, when it was sold. */
+    note?: string | null;
+    href: string;
+    /** Its thumbnail. Without one the switcher's `icon` stands in. */
+    image?: string | null;
+}
+/** A run of records under a heading: owned, then sold. */
+export interface RecordSwitcherGroup {
+    label?: string;
+    items: readonly RecordSwitcherItem[];
+}
+/** One of the open record's own pages, a tab beside its name. */
+export interface RecordPage {
+    label: string;
+    href: string;
+    current?: boolean;
+}

package/dist/components/ui/record-switcher/types.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@poodle64/ui",
-	"version": "2026.10.4",
+	"version": "2026.10.5",
 	"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",

package/registry/component-map.json

@@ -1,10 +1,10 @@
 {
 	"meta": {
 		"package": "@poodle64/ui",
-		"version": "2026.10.4",
+		"version": "2026.10.5",
 		"generatedBy": "scripts/generate-registry.mjs",
 		"source": "scripts/situations.json + package source (DO NOT EDIT the outputs by hand)",
-		"componentCount": 62,
+		"componentCount": 66,
 		"situationCount": 18
 	},
 	"situations": [
@@ -125,6 +125,20 @@
 			"title": "A catalogue of like things",
 			"description": "An index of many peer items — a responsive tile wall, or a sortable/filterable table of records.",
 			"components": [
+				{
+					"name": "RecordList",
+					"dir": "record-list",
+					"import": "@poodle64/ui/record-list",
+					"props": "rows, columns?, preferences?, onPreferencesChange?, title?, tools?, action?, group?, totalLabel?, icon?, href?, onOpen?, open?",
+					"insteadOf": "a DataTableTanstack, or a boxed Table, for a module's own records (properties, managers, tools, a P&L's lines): the ledger's look (head card, row cards, group labels on the ground) for rows that are not money, so every list in an app reads one way"
+				},
+				{
+					"name": "ListToolbar",
+					"dir": "list-toolbar",
+					"import": "@poodle64/ui/list-toolbar",
+					"props": "title?, meta?, leading?, children?, tools?, action?",
+					"insteadOf": "a hand-built title, count and button row above a list; the Ledger and the RecordList draw theirs with it"
+				},
 				{
 					"name": "TileGrid",
 					"dir": "tile-grid",
@@ -157,7 +171,7 @@
 					"name": "Ledger",
 					"dir": "ledger",
 					"import": "@poodle64/ui/ledger",
-					"props": "rows, columns?, preferences?, onPreferencesChange?, title?, actions?, selected?, bulkActions?, open?, editor?",
+					"props": "rows, columns?, preferences?, onPreferencesChange?, title?, actions?, tools?, action?, selected?, bulkActions?, open?, editor?",
 					"insteadOf": "a DataTableTanstack of transactions, or a hand-built grouped list with its own period headers and column picker"
 				}
 			]
@@ -171,7 +185,7 @@
 					"name": "Panel",
 					"dir": "panel",
 					"import": "@poodle64/ui/panel",
-					"props": "children, title?, subtitle?, description?, icon?, action?, footer?, tone?, pad?",
+					"props": "children, title?, subtitle?, description?, icon?, action?, footer?, tone?, pad?, scroll?",
 					"insteadOf": "raw Card + CardHeader + CardTitle assembled by hand on every route; also the settings section — there is no separate SettingsSection, `description` wraps, `footer` carries Save/Cancel, `tone=\"destructive\"` is the danger zone"
 				}
 			]
@@ -306,6 +320,13 @@
 					"import": "@poodle64/ui/page-canvas",
 					"props": "pageCount, page, currentPage?, regions?, lookedRegions?, activeRegionId?, focusedRegionId?, zoom?",
 					"insteadOf": "a hand-built page viewer per app (godswood's DocumentViewer, pebblestone's PdfViewer) each re-deriving fit/zoom/pan, now with no way to outline what was read (#839)"
+				},
+				{
+					"name": "DocumentPane",
+					"dir": "document-pane",
+					"import": "@poodle64/ui/document-pane",
+					"props": "title, subtitle?, pages?, pageCount?, page?, currentPage?, zoom?, actions?, onClose?",
+					"insteadOf": "a PageCanvas framed by hand with its own title row, download and close; the pane the record page opens a document in, beside the column or in its place"
 				}
 			]
 		},
@@ -342,12 +363,19 @@
 					"props": "title?, eyebrow?, breadcrumbs?, icon?, subtitle?, info?, meta?, actions?",
 					"insteadOf": "a hand-written <h1> and title bar (the drift gate fails this)"
 				},
+				{
+					"name": "RecordSwitcher",
+					"dir": "record-switcher",
+					"import": "@poodle64/ui/record-switcher",
+					"props": "name, groups, current?, noun?, placeholder?, icon?, all?, pages?, separator?",
+					"insteadOf": "a bare record name beside a small chevrons button in the top bar, and a dropdown of names with no search, groups or thumbnails; the record's own page tabs come with it"
+				},
 				{
 					"name": "ContextColumn",
 					"dir": "context-column",
 					"import": "@poodle64/ui/context-column",
-					"props": "stats, statsTitle?, statsInfo?, detail?, ariaLabel?",
-					"insteadOf": "a hand-built right-hand <aside> with a stat card and a detail pane"
+					"props": "stats?, statsTitle?, statsInfo?, detail?, title?, subtitle?, onClose?, children?, documentPane?, ariaLabel?",
+					"insteadOf": "a hand-built right-hand <aside> with a stat card and a detail pane; on a record page, the one opened item (title, close, an inner scroll) and its DocumentPane, in the column's place or beside it once the page's row has room"
 				},
 				{
 					"name": "ListShell",

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.10.4`. 62 components, 18 situations.
+Generated from `@poodle64/ui@2026.10.5`. 66 components, 18 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.
 
@@ -72,6 +72,8 @@ _An index of many peer items — a responsive tile wall, or a sortable/filterabl
 
 | Component | Import | Key props | Reach for it instead of |
 | --- | --- | --- | --- |
+| `RecordList` | `@poodle64/ui/record-list` | `rows, columns?, preferences?, onPreferencesChange?, title?, tools?, action?, group?, totalLabel?, icon?, href?, onOpen?, open?` | a DataTableTanstack, or a boxed Table, for a module's own records (properties, managers, tools, a P&L's lines): the ledger's look (head card, row cards, group labels on the ground) for rows that are not money, so every list in an app reads one way |
+| `ListToolbar` | `@poodle64/ui/list-toolbar` | `title?, meta?, leading?, children?, tools?, action?` | a hand-built title, count and button row above a list; the Ledger and the RecordList draw theirs with it |
 | `TileGrid` | `@poodle64/ui/tile-grid` | `children, min?, gap?, tag?` | a grid with fixed sm:grid-cols-* breakpoints you maintain per page |
 | `DataTableTanstack` | `@poodle64/ui/data-table-tanstack` | `table, selectable?, selectedId?, onSelect?, emptyMessage?` | a hand-built <table>, or the raw Table primitive wired to TanStack by hand |
 | `DataTableToolbar` | `@poodle64/ui/data-table-toolbar` | `searchValue, onSearch, searchPlaceholder?, chipGroups?, trailing?` | a hand-built search + filter-chip bar above a table |
@@ -82,7 +84,7 @@ _Dated rows of money, coins or units moving — a bank account, a property's boo
 
 | Component | Import | Key props | Reach for it instead of |
 | --- | --- | --- | --- |
-| `Ledger` | `@poodle64/ui/ledger` | `rows, columns?, preferences?, onPreferencesChange?, title?, actions?, selected?, bulkActions?, open?, editor?` | a DataTableTanstack of transactions, or a hand-built grouped list with its own period headers and column picker |
+| `Ledger` | `@poodle64/ui/ledger` | `rows, columns?, preferences?, onPreferencesChange?, title?, actions?, tools?, action?, selected?, bulkActions?, open?, editor?` | a DataTableTanstack of transactions, or a hand-built grouped list with its own period headers and column picker |
 
 ## A titled section of a route
 
@@ -90,7 +92,7 @@ _The generic titled card every route reaches for — an optional header with ico
 
 | Component | Import | Key props | Reach for it instead of |
 | --- | --- | --- | --- |
-| `Panel` | `@poodle64/ui/panel` | `children, title?, subtitle?, description?, icon?, action?, footer?, tone?, pad?` | raw Card + CardHeader + CardTitle assembled by hand on every route; also the settings section — there is no separate SettingsSection, `description` wraps, `footer` carries Save/Cancel, `tone="destructive"` is the danger zone |
+| `Panel` | `@poodle64/ui/panel` | `children, title?, subtitle?, description?, icon?, action?, footer?, tone?, pad?, scroll?` | raw Card + CardHeader + CardTitle assembled by hand on every route; also the settings section — there is no separate SettingsSection, `description` wraps, `footer` carries Save/Cancel, `tone="destructive"` is the danger zone |
 
 ## A form the app itself describes
 
@@ -134,6 +136,7 @@ _One page at a time, fitted to its pane both ways so an A4 statement and a tall
 | Component | Import | Key props | Reach for it instead of |
 | --- | --- | --- | --- |
 | `PageCanvas` | `@poodle64/ui/page-canvas` | `pageCount, page, currentPage?, regions?, lookedRegions?, activeRegionId?, focusedRegionId?, zoom?` | a hand-built page viewer per app (godswood's DocumentViewer, pebblestone's PdfViewer) each re-deriving fit/zoom/pan, now with no way to outline what was read (#839) |
+| `DocumentPane` | `@poodle64/ui/document-pane` | `title, subtitle?, pages?, pageCount?, page?, currentPage?, zoom?, actions?, onClose?` | a PageCanvas framed by hand with its own title row, download and close; the pane the record page opens a document in, beside the column or in its place |
 
 ## The frame every route shares
 
@@ -145,7 +148,8 @@ _The standing chrome — the app shell and its nav, the one page-title treatment
 | `ShellControls` | `@poodle64/ui/app-shell` | `children` | a scope row (entity, financial year, chart/table) hand-placed above the page body; the shell's top bar carries it |
 | `Segmented` | `@poodle64/ui/segmented` | `value, options, label, size?` | a hand-built row of aria-pressed buttons for a small fixed choice |
 | `PageHeader` | `@poodle64/ui/page-header` | `title?, eyebrow?, breadcrumbs?, icon?, subtitle?, info?, meta?, actions?` | a hand-written <h1> and title bar (the drift gate fails this) |
-| `ContextColumn` | `@poodle64/ui/context-column` | `stats, statsTitle?, statsInfo?, detail?, ariaLabel?` | a hand-built right-hand <aside> with a stat card and a detail pane |
+| `RecordSwitcher` | `@poodle64/ui/record-switcher` | `name, groups, current?, noun?, placeholder?, icon?, all?, pages?, separator?` | a bare record name beside a small chevrons button in the top bar, and a dropdown of names with no search, groups or thumbnails; the record's own page tabs come with it |
+| `ContextColumn` | `@poodle64/ui/context-column` | `stats?, statsTitle?, statsInfo?, detail?, title?, subtitle?, onClose?, children?, documentPane?, ariaLabel?` | a hand-built right-hand <aside> with a stat card and a detail pane; on a record page, the one opened item (title, close, an inner scroll) and its DocumentPane, in the column's place or beside it once the page's row has room |
 | `ListShell` | `@poodle64/ui/list-shell` | `title, children, label?, open?, actions?` | a module hand-rolling its own foldable second column beside the rail — a queue, an inbox, a working list |
 | `AppIdentity` | `@poodle64/ui/app-identity` | `user, workspace?, role?, entitlements?, onSignOut, onAccountSettings?, onSwitchTheme?` | a hand-rolled account/avatar dropdown wired to raw DropdownMenu.* + Avatar.* |