@poodle64/ui 2026.9.23 → 2026.10.1

package/README.md

@@ -82,7 +82,7 @@ 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** (24). Primitives are not what makes an app look like an
+**Composed components.** 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:
@@ -112,6 +112,7 @@ rather than rebuilding it:
 | `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.                                                                                                                                                             |
+| `ledger`                                        | The one ledger every module draws: dated rows of money, coins or units, two lines a row, grouped by the viewer's period, the viewer's columns and running balance. See [The ledger](#the-ledger).                                                                                                                                                                       |
 
 **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
@@ -568,7 +569,7 @@ remembered, not what the house looks like.
 was before the feature existed — gated, not assumed:
 
 ```sh
-node harness/additivity.mjs ui-v2026.8.3
+node harness/additivity.mjs ee0db12   # ui 2026.8.3
 # 15 surface/viewport pairs, 105 compared fields (including the screenshot hash)
 # IDENTICAL on every field and every pixel against an explicit texture="none".
 ```
@@ -854,6 +855,83 @@ 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' } }
 ```
 
+## The ledger
+
+One component for every money list in the household: a property's books, a
+bank account, a wallet, a brokerage. The module brings its rows and the columns
+it offers; the ledger owns the look, the grouping and the viewer's toggles, so
+no module rebuilds them and a need one module finds becomes a toggle for all.
+
+```svelte
+<script lang="ts">
+	import Ledger, { type LedgerColumn, type LedgerRow } from '@poodle64/ui/ledger';
+
+	type Row = LedgerRow & { category: string | null };
+	const columns: LedgerColumn<Row>[] = [
+		{ key: 'title', label: 'Payee' },
+		{ key: 'category', label: 'Category', text: (r) => r.category ?? 'Uncategorised' },
+		{ key: 'balance', label: 'Running balance', head: 'Balance' }
+	];
+	let preferences = $state(saved.ledger); // the app's own persisted preference
+	let selected = $state<number[]>([]);
+	let open = $state<number | null>(null);
+</script>
+
+<Ledger {rows} {columns} title="Transactions" bind:preferences
+        onPreferencesChange={(next) => save('ledger', next)} bind:selected bind:open>
+	{#snippet bulkActions(ticked)}<Button size="sm" onclick={() => review(ticked)}>Mark reviewed</Button>{/snippet}
+	{#snippet editor(row, { close, template, column })}<!-- the module's fields -->{/snippet}
+</Ledger>
+```
+
+| Prop | Purpose |
+| --- | --- |
+| `rows` | `LedgerRow`s, extended with whatever the module's columns read: `id`, `date` (ISO), `title`, `note`, `amount` (signed), `balance`, `review` (`true` or a `Status`), `attachment` (its name), `origins` (a synthetic row's statement lines). Pass every row the view covers, filtered: the ledger sorts newest first, keeps a day's rows in the order given, and mounts only those near the view. |
+| `columns` | The module's columns, in order after the amount. The keys `date`, `title`, `amount` and `balance` are the ledger's own cells: list one to rename or resize it (the title reads "Description" until the module names it), and list `balance` to offer the running balance at all, with `text` saying what it counts (money, a coin, units). A `cell` snippet's links and buttons take their own clicks; the rest of the cell opens the row. |
+| `preferences`, `onPreferencesChange` | The viewer's `{ columns, period }`. Missing fields take the module's defaults (each column's `on`, the balance off, grouped by month); an unknown column key is ignored. The ledger stores nothing. |
+| `fyStart` | The month a financial year starts, 1–12. July by default; anything else groups from July and logs an error in development. |
+| `locale`, `currency` | Every figure, amounts, nets and counts, in this locale (`AU_LOCALE` by default) and currency (AUD). Dates keep the drawn "15 Sep": the ledger's words are English. |
+| `title`, `meta`, `actions` | The toolbar on the page ground: its title, the count beside it, and the module's own actions after the Columns menu. |
+| `selected`, `bulkActions` | Ticking exists only with `bulkActions`, whose snippet gets the ticked rows in the bar that replaces the toolbar. |
+| `open`, `editor` | Opening exists only with `editor`: the row lifts out of its card as its own surface, holding the snippet. Its second argument carries the row's `template` and each column's grid line, so fields can sit under their columns. |
+| `originActions`, `onAttachment` | Split, join and undo under a synthetic row's statement lines; the paperclip as a button. |
+| `noun`, `empty`, `footer`, `layout` | "line" for a printed layer; the empty state; "Show more" after the last group; a forced `phone`/`narrow`/`wide` where the ledger's own width (below 600px, from 1200px) should not decide. |
+
+Settled here, the same in every module, and not props:
+
+- **Two lines a row**, the note under the title, the pair centred on the row; a
+  row with no note centres its title. The checkbox, the review dot, the date and
+  every single-value cell centre too.
+- **One mark per kind.** A review dot at the row's left edge, never a status
+  chip; a synthetic row's "Not as printed" badge leads its second line and
+  opens the row in place to the lines it was made from.
+- **PocketSmith's look.** No panel around the list; a head card exactly as wide
+  as the group cards, its columns on theirs; one rounded card per period with
+  hairlines between rows; the period's label, count and net on the page ground
+  above its card; figures in the body face with tabular numerals, money out
+  bracketed and money in green (`formatCurrency(v, { negative: 'brackets' })`).
+- **The Columns menu** holds every column as a tick, the three fixed ones
+  locked and the running balance last, then the period: financial year,
+  calendar year, month, week (from Monday), day (the date heads the group and
+  its column goes) or none.
+- **Density** is the package's own `data-ds-density`: a row is 3.5rem, 3rem
+  under `compact`. There is no one-line row.
+
+What the module keeps: Find (search, filters, views) in its `ContextColumn`, its
+rows' second layer (a bank's lines as printed) as a scope control that swaps
+the rows and columns it passes, the opened row's fields, and where a choice is
+persisted. Group totals are summed from the rows passed, which is why the module
+passes them all rather than a page.
+
+It fills its parent's height and scrolls its own rows, which is what holds the
+head card at the top: give it a bounded parent (`flex min-h-0 flex-1`). It mounts
+only the rows within about a screen of the view, measuring each as it renders and
+standing in for the rest at their height, so the scroll bar and every card keep
+their true size. Measured in Chromium at 1440x900: 5,000 rows paint their first
+row in about 300ms with some 20 mounted, where mounting them all took 7.6 to 8.6
+seconds and 65,000 nodes. Its look is measured in a real engine at 390, 1000,
+1440 and 3360px, and at 5,000 rows (`harness/drive.md` §"The ledger").
+
 ## Hand-written forms
 
 The shadcn-svelte Formsnap wrapper set, over `sveltekit-superforms`:
@@ -1379,7 +1457,7 @@ pnpm run check         # svelte-check
 pnpm run test:browser  # build the harness and drive it in a real browser
 
 # Before releasing a change that claims to be additive (minutes, not seconds):
-node harness/additivity.mjs ui-v2026.8.3
+node harness/additivity.mjs ee0db12   # ui 2026.8.3
 ```
 
 `pnpm test` includes the gates that compile the built package through the real
@@ -1410,7 +1488,7 @@ non-zero and naming the field on any difference.
 
 1. Change a component; bump `version` in `package.json` (CalVer).
 2. `pnpm build`, which runs `svelte-package` then `publint` (package.json/exports sanity).
-3. Commit, tag `ui-v<version>`, push the tag.
-4. `.github/workflows/publish-kit-typescript.yaml` (repo root) runs on that push and publishes via npm
-   OIDC trusted publishing: `gh run list -R radar-hooves/app-factory --workflow=publish-kit-typescript.yaml`.
+3. Merge to main. No tag.
+4. `.github/workflows/publish-kit-typescript.yaml` (repo root) runs on that push and publishes the new
+   version via npm OIDC trusted publishing: `gh run list -R radar-hooves/app-factory --workflow=publish-kit-typescript.yaml`.
    Confirm with `npm view @poodle64/ui version`.

package/dist/components/settings/index.d.ts

@@ -0,0 +1,3 @@
+import SettingsPage, { type SettingsDocument, type SettingValue } from './settings-page.svelte';
+export { nestSchema, nestValues, settingsLayout } from './nest.js';
+export { SettingsPage, SettingsPage as default, type SettingsDocument, type SettingValue };

package/dist/components/settings/index.js

@@ -0,0 +1,3 @@
+import SettingsPage, {} from './settings-page.svelte';
+export { nestSchema, nestValues, settingsLayout } from './nest.js';
+export { SettingsPage, SettingsPage as default };

package/dist/components/settings/nest.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The settings API is flat, keyed by dotted names (`intelligence.extraction_model`),
+ * and `<SchemaForm>` reads a `.` in a property name as a path. These nest the flat
+ * document along those paths, so every key is addressable, the change it reports
+ * carries the key back as `change.path`, and settings group by their domain. The
+ * form's generated layout does not descend into an object, so `settingsLayout`
+ * gives it one: a Group per domain, a Control per setting.
+ */
+import type { JsonSchema, UISchemaElement } from '../ui/schema-form/index.js';
+/** `{ 'a.b': 1, c: 2 }` → `{ a: { b: 1 }, c: 2 }`. */
+export declare function nestValues(flat: Record<string, unknown>): Record<string, unknown>;
+/** The same nesting for a flat object schema: each path segment becomes an object group. */
+export declare function nestSchema(schema: JsonSchema): JsonSchema;
+/** The layout `<SchemaForm>` renders a nested settings schema with; a group's label is its segment in sentence case. */
+export declare function settingsLayout(schema: JsonSchema): UISchemaElement;

package/dist/components/settings/nest.js

@@ -0,0 +1,58 @@
+/**
+ * The settings API is flat, keyed by dotted names (`intelligence.extraction_model`),
+ * and `<SchemaForm>` reads a `.` in a property name as a path. These nest the flat
+ * document along those paths, so every key is addressable, the change it reports
+ * carries the key back as `change.path`, and settings group by their domain. The
+ * form's generated layout does not descend into an object, so `settingsLayout`
+ * gives it one: a Group per domain, a Control per setting.
+ */
+/** `{ 'a.b': 1, c: 2 }` → `{ a: { b: 1 }, c: 2 }`. */
+export function nestValues(flat) {
+    const root = {};
+    for (const [key, value] of Object.entries(flat)) {
+        const parts = key.split('.');
+        const leaf = parts.pop() ?? key;
+        let node = root;
+        for (const part of parts) {
+            node = (node[part] ??= {});
+        }
+        node[leaf] = value;
+    }
+    return root;
+}
+/** The same nesting for a flat object schema: each path segment becomes an object group. */
+export function nestSchema(schema) {
+    const properties = {};
+    for (const [key, property] of Object.entries(schema.properties ?? {})) {
+        const parts = key.split('.');
+        const leaf = parts.pop() ?? key;
+        let node = properties;
+        for (const part of parts) {
+            node = (node[part] ??= { type: 'object', properties: {} }).properties ??= {};
+        }
+        node[leaf] = property;
+    }
+    return { ...schema, properties };
+}
+/** The layout `<SchemaForm>` renders a nested settings schema with; a group's label is its segment in sentence case. */
+export function settingsLayout(schema) {
+    const layout = {
+        type: 'VerticalLayout',
+        elements: layoutElements(schema, '#')
+    };
+    return layout;
+}
+function layoutElements(schema, scope) {
+    return Object.entries(schema.properties ?? {}).map(([key, child]) => {
+        const childScope = `${scope}/properties/${key}`;
+        if (child.type === 'object' && child.properties) {
+            const label = key.replaceAll('_', ' ');
+            return {
+                type: 'Group',
+                label: label.charAt(0).toUpperCase() + label.slice(1),
+                elements: layoutElements(child, childScope)
+            };
+        }
+        return { type: 'Control', scope: childScope };
+    });
+}

package/dist/components/settings/settings-page.svelte

@@ -0,0 +1,159 @@
+<!--
+	The runtime settings page for app-slices' settings routes: every declared
+	Setting, rendered from the JSON Schema `GET <endpoint>/` returns, nested by
+	dot path and laid out one group per domain (`nest.ts`), so an app that
+	declares a setting adds no code here. `<SchemaForm>` has no per-field reset,
+	so "default versus override, reset in one act" (the operator's own ask) is
+	the panel below it. An app mounts it as its settings route's whole body.
+-->
+<script lang="ts" module>
+	import type { JsonSchema } from '../ui/schema-form/index.js';
+
+	export type SettingValue = boolean | number | string;
+
+	/** What `GET <endpoint>/` answers: app-slices' `SettingsDocument`. */
+	export type SettingsDocument = {
+		schema: JsonSchema;
+		value: Record<string, SettingValue>;
+		defaults: Record<string, SettingValue>;
+	};
+</script>
+
+<script lang="ts">
+	import { onMount } from 'svelte';
+	import { toast } from 'svelte-sonner';
+	import { Button } from '../ui/button/index.js';
+	import { LoadingState } from '../ui/loading-state/index.js';
+	import { PageHeader } from '../ui/page-header/index.js';
+	import { Panel } from '../ui/panel/index.js';
+	import { SchemaForm, type SchemaFormChange } from '../ui/schema-form/index.js';
+	import { nestSchema, nestValues, settingsLayout } from './nest.js';
+
+	let {
+		/** The app's settings routes, defaulting to where the factory mounts them. */
+		endpoint = '/api/settings',
+		title = 'Application',
+		subtitle = "Runtime settings this deployment's operator can change without a code change or a deploy.",
+		/** What a 401 does: the app's own re-authentication (its API client's redirect), since only the app knows its sign-in. */
+		onunauthorized
+	}: {
+		endpoint?: string;
+		title?: string;
+		subtitle?: string;
+		onunauthorized?: () => void;
+	} = $props();
+
+	const TIMEOUT_MS = 30_000;
+
+	let doc = $state<SettingsDocument | null>(null);
+	let loadError = $state<string | null>(null);
+	/** What `<SchemaForm>` renders: the flat document nested by dot path; the flat one stays the state. */
+	let formSchema = $derived(doc ? nestSchema(doc.schema) : null);
+	let formValue = $derived(doc ? nestValues(doc.value) : {});
+	let formLayout = $derived(formSchema ? settingsLayout(formSchema) : undefined);
+	/** Keys whose effective value differs from its default — derived, never a second copy to disagree with the API. */
+	let overridden = $derived(
+		doc ? Object.keys(doc.value).filter((key) => doc!.value[key] !== doc!.defaults[key]) : []
+	);
+
+	/** The body on success, or the household error body's `message` (`{"error", "message"}`). */
+	async function call<T>(
+		path: string,
+		init: RequestInit = {}
+	): Promise<{ data: T } | { failure: string }> {
+		let response: Response;
+		try {
+			response = await fetch(`${endpoint}/${path}`, {
+				...init,
+				credentials: 'include',
+				signal: AbortSignal.timeout(TIMEOUT_MS)
+			});
+		} catch {
+			return { failure: 'The server could not be reached.' };
+		}
+		if (response.status === 401) onunauthorized?.();
+		const body = await response.json().catch(() => null);
+		if (response.ok && body !== null) return { data: body as T };
+		if (response.ok) return { failure: 'The server did not answer with settings.' };
+		return { failure: body?.message ?? `The server answered ${response.status}.` };
+	}
+
+	async function load() {
+		const result = await call<SettingsDocument>('');
+		if ('failure' in result) {
+			loadError = result.failure;
+			return;
+		}
+		loadError = null;
+		doc = result.data;
+	}
+
+	onMount(load);
+
+	async function save(key: string, path: string, init: RequestInit, failure: string) {
+		const result = await call<{ value: SettingValue }>(path, init);
+		if ('failure' in result) {
+			toast.error(failure, { description: result.failure });
+			return false;
+		}
+		doc!.value[key] = result.data.value;
+		return true;
+	}
+
+	async function handleChange(_next: Record<string, unknown>, change: SchemaFormChange) {
+		if (!doc) return;
+		const key = change.path;
+		const previous = doc.value[key];
+		doc.value[key] = change.value as SettingValue;
+		const saved = await save(
+			key,
+			encodeURIComponent(key),
+			{
+				method: 'PATCH',
+				headers: { 'content-type': 'application/json' },
+				body: JSON.stringify({ value: change.value })
+			},
+			'Could not save the setting'
+		);
+		if (!saved && previous !== undefined) doc.value[key] = previous;
+	}
+
+	function reset(key: string) {
+		void save(key, `${encodeURIComponent(key)}/reset`, { method: 'POST' }, 'Could not reset the setting');
+	}
+
+	function label(key: string): string {
+		const properties = (doc!.schema as { properties?: Record<string, { title?: string }> }).properties;
+		return properties?.[key]?.title ?? key;
+	}
+</script>
+
+<PageHeader {title} {subtitle} />
+
+{#if loadError}
+	<Panel title="Could not load settings" tone="destructive">{loadError}</Panel>
+{:else if !doc}
+	<LoadingState message="Loading…" class="mt-16" />
+{:else}
+	<Panel title="Settings">
+		<SchemaForm schema={formSchema!} uischema={formLayout} value={formValue} onChange={handleChange} />
+	</Panel>
+
+	{#if overridden.length}
+		<Panel title="Overridden from default" subtitle="{overridden.length} changed">
+			<ul class="grid gap-2">
+				{#each overridden as key (key)}
+					<li class="flex items-center justify-between gap-4">
+						<span class="text-sm">
+							{label(key)}
+							<span class="text-muted-foreground font-mono text-xs">
+								default: {doc.defaults[key]}
+							</span>
+						</span>
+						<Button variant="outline" size="sm" onclick={() => reset(key)}>Reset</Button>
+					</li>
+				{/each}
+			</ul>
+		</Panel>
+	{/if}
+{/if}

package/dist/components/settings/settings-page.svelte.d.ts

@@ -0,0 +1,17 @@
+import type { JsonSchema } from '../ui/schema-form/index.js';
+export type SettingValue = boolean | number | string;
+/** What `GET <endpoint>/` answers: app-slices' `SettingsDocument`. */
+export type SettingsDocument = {
+    schema: JsonSchema;
+    value: Record<string, SettingValue>;
+    defaults: Record<string, SettingValue>;
+};
+type $$ComponentProps = {
+    endpoint?: string;
+    title?: string;
+    subtitle?: string;
+    onunauthorized?: () => void;
+};
+declare const SettingsPage: import("svelte").Component<$$ComponentProps, {}, "">;
+type SettingsPage = ReturnType<typeof SettingsPage>;
+export default SettingsPage;

package/dist/components/ui/input-group/input-group-input.svelte.d.ts

@@ -2,7 +2,7 @@ declare const InputGroupInput: import("svelte").Component<(Omit<import("svelte/e
     type: "file";
     files?: FileList;
 } | {
-    type?: "number" | "month" | "url" | "hidden" | "color" | "submit" | "reset" | "button" | "search" | "checkbox" | "radio" | (string & {}) | "text" | "tel" | "email" | "week" | "date" | "time" | "image" | "datetime-local" | "password" | "range";
+    type?: "number" | "month" | "url" | "hidden" | "color" | "submit" | "reset" | "button" | "search" | "checkbox" | "radio" | (string & {}) | "text" | "tel" | "email" | "week" | "date" | "time" | "datetime-local" | "image" | "password" | "range";
     files?: undefined;
 })) & {
     ref?: HTMLElement | null | undefined;

package/dist/components/ui/ledger/index.d.ts

@@ -0,0 +1,3 @@
+export { default as Ledger } from './ledger.svelte';
+export { default } from './ledger.svelte';
+export type { LedgerColumn, LedgerOpenContext, LedgerOrigin, LedgerPeriod, LedgerPreferences, LedgerRow } from './types.js';

package/dist/components/ui/ledger/index.js

@@ -0,0 +1,2 @@
+export { default as Ledger } from './ledger.svelte';
+export { default } from './ledger.svelte';

package/dist/components/ui/ledger/ledger-columns.svelte

@@ -0,0 +1,107 @@
+<script lang="ts">
+	/**
+	 * The viewer's Columns menu: every column the module offers as a tick (the
+	 * running balance one more, always last), then the period rows group by.
+	 * An icon button named by its tooltip.
+	 */
+	import Columns3 from '@lucide/svelte/icons/columns-3';
+	import { Button, buttonVariants } from '../button/index.js';
+	import { Checkbox } from '../checkbox/index.js';
+	import * as Popover from '../popover/index.js';
+	import { Segmented } from '../segmented/index.js';
+	import * as Tooltip from '../tooltip/index.js';
+	import { cn } from '../../../utils.js';
+	import { LEDGER_PERIODS } from './ledger.js';
+	import type { LedgerPeriod, LedgerPreferences } from './types.js';
+
+	let {
+		offered,
+		preferences,
+		note,
+		onchange,
+		onreset
+	}: {
+		offered: { key: string; label: string; locked: boolean }[];
+		preferences: LedgerPreferences;
+		note?: string;
+		onchange: (next: LedgerPreferences) => void;
+		onreset: () => void;
+	} = $props();
+
+	let open = $state(false);
+
+	const HINT: Record<LedgerPeriod, string> = {
+		fy: 'Each financial year sits under its own header, which opens and closes.',
+		cy: 'Each calendar year sits under its own header, which opens and closes.',
+		month: 'Each month sits under its own header, which opens and closes.',
+		week: 'Each week sits under its own header, which opens and closes.',
+		day: 'The date heads each day’s rows, so the Date column goes.',
+		none: 'One list, newest first, under the column head.'
+	};
+
+	function tick(key: string, on: boolean) {
+		const next = on ? [...preferences.columns, key] : preferences.columns.filter((k) => k !== key);
+		onchange({
+			...preferences,
+			columns: offered.map((c) => c.key).filter((k) => next.includes(k))
+		});
+	}
+
+	const eyebrow = 'text-muted-foreground text-2xs tracking-eyebrow font-semibold uppercase';
+</script>
+
+<Popover.Root bind:open>
+	<Tooltip.Provider delayDuration={150}>
+		<Tooltip.Root>
+			<Tooltip.Trigger>
+				{#snippet child({ props })}
+					<Popover.Trigger
+						{...props}
+						class={buttonVariants({ variant: open ? 'outline' : 'ghost', size: 'icon-sm' })}
+						aria-label="Columns, balance and grouping"
+						data-slot="ledger-columns-trigger"
+					>
+						<Columns3 />
+					</Popover.Trigger>
+				{/snippet}
+			</Tooltip.Trigger>
+			<Tooltip.Content side="bottom">Columns, balance and grouping</Tooltip.Content>
+		</Tooltip.Root>
+	</Tooltip.Provider>
+	<Popover.Content align="end" class="w-80 p-0" data-slot="ledger-columns">
+		<div class="flex flex-col px-2 pt-2.5 pb-2">
+			<span class={cn(eyebrow, 'px-1.5 pb-1.5')}>Columns</span>
+			{#each offered as c (c.key)}
+				{@const on = c.locked || preferences.columns.includes(c.key)}
+				<label
+					class={cn(
+						'flex min-h-8 items-center gap-2.5 rounded-md px-1.5 text-sm',
+						c.locked ? 'text-muted-foreground' : 'hover:bg-accent/50 cursor-pointer'
+					)}
+				>
+					<Checkbox
+						checked={on}
+						disabled={c.locked}
+						onCheckedChange={(v) => tick(c.key, v === true)}
+					/>
+					<span class="min-w-0 flex-1">{c.label}</span>
+					{#if c.locked}<span class="text-xs">Always shown</span>{/if}
+				</label>
+			{/each}
+		</div>
+		<div class="border-border flex flex-col gap-2 border-t px-3.5 pt-2.5 pb-3">
+			<span class={eyebrow}>Group by</span>
+			<Segmented
+				label="Group by"
+				options={LEDGER_PERIODS}
+				bind:value={() => preferences.period, (period) => onchange({ ...preferences, period })}
+				class="grid w-full grid-cols-2"
+			/>
+			<span class="text-muted-foreground text-xs">{HINT[preferences.period]}</span>
+		</div>
+		<div class="bg-surface-2 border-border flex items-center gap-2 border-t py-2 pr-2 pl-3.5">
+			<span class="text-muted-foreground min-w-0 flex-1 text-xs">{note ?? ''}</span>
+			<Button variant="ghost" size="sm" onclick={onreset}>Reset</Button>
+		</div>
+	</Popover.Content>
+</Popover.Root>

package/dist/components/ui/ledger/ledger-columns.svelte.d.ts

@@ -0,0 +1,15 @@
+import type { LedgerPreferences } from './types.js';
+type $$ComponentProps = {
+    offered: {
+        key: string;
+        label: string;
+        locked: boolean;
+    }[];
+    preferences: LedgerPreferences;
+    note?: string;
+    onchange: (next: LedgerPreferences) => void;
+    onreset: () => void;
+};
+declare const LedgerColumns: import("svelte").Component<$$ComponentProps, {}, "">;
+type LedgerColumns = ReturnType<typeof LedgerColumns>;
+export default LedgerColumns;

package/dist/components/ui/ledger/ledger.d.ts

@@ -0,0 +1,77 @@
+import type { LedgerPeriod, LedgerRow } from './types.js';
+export declare const LEDGER_PERIODS: readonly {
+    value: LedgerPeriod;
+    label: string;
+}[];
+/** "15 Sep", or "15 Sep 2026" with the year. */
+export declare function ledgerDate(iso: string, withYear?: boolean): string;
+/** The group a date falls in: sortable, so newer keys sort later. */
+export declare function periodKey(iso: string, period: LedgerPeriod, fyStart?: number): string;
+/** A group's label: "FY 2025–26", "2026", "September 2026", "15 to 21 Sep 2026", "Tuesday 15 Sep 2026". */
+export declare function periodLabel(key: string, period: LedgerPeriod, fyStart?: number, withYear?: boolean): string;
+/** "Jul 2025 to Jun 2026", or "Jul 2026 to now" for the year still open on `today`. */
+export declare function fySpan(key: string, fyStart?: number, today?: string): string;
+/** Rows newest first, a day's rows in the order given, grouped by period. */
+export declare function groupRows<R extends LedgerRow>(rows: readonly R[], period: LedgerPeriod, fyStart?: number): {
+    key: string;
+    rows: R[];
+}[];
+/** Whole cents, so a group's sum carries no float error. */
+export declare function cents(value: number | string | null | undefined): number;
+/** Money as the ledger prints it: in plain, out in brackets. */
+export declare function ledgerMoney(value: number | string, currency?: string, locale?: string): string;
+/** One thing the list stacks: a group's head, a row on its card, or a row opened out of it. */
+export type LedgerItem<R extends LedgerRow> = {
+    kind: 'head';
+    key: string;
+    group: number;
+} | {
+    kind: 'row';
+    key: string;
+    row: R;
+    group: number;
+    groupKey: string;
+    run: number;
+    first: boolean;
+    last: boolean;
+} | {
+    kind: 'open';
+    key: string;
+    row: R;
+    group: number;
+};
+/** Every group's head and rows in order; a run of rows on one card breaks where a row is open. */
+export declare function ledgerItems<R extends LedgerRow>(groups: readonly {
+    key: string;
+    rows: readonly R[];
+}[], opts: {
+    heads: boolean;
+    closed: (key: string) => boolean;
+    open: R['id'] | null;
+}): LedgerItem<R>[];
+/** The first and last items overlapping `[top, bottom)`, given each item's start (and the end last). */
+export declare function windowOf(starts: ArrayLike<number>, top: number, bottom: number): [number, number];
+/** What renders for items `a..b`: heads, opened rows, and cards cut where the window cuts them. */
+export type LedgerBlock<R extends LedgerRow> = {
+    kind: 'head';
+    key: string;
+    group: number;
+} | {
+    kind: 'open';
+    key: string;
+    row: R;
+    group: number;
+} | {
+    kind: 'card';
+    key: string;
+    group: number;
+    run: number;
+    rows: {
+        row: R;
+        first: boolean;
+        key: string;
+    }[];
+    cutTop: boolean;
+    cutBottom: boolean;
+};
+export declare function blocksOf<R extends LedgerRow>(items: readonly LedgerItem<R>[], a: number, b: number): LedgerBlock<R>[];