@poodle64/ui 2026.10.0 → 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
@@ -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`:

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>[];

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

@@ -0,0 +1,221 @@
+/**
+ * The ledger's reading of dates, periods and money: pure, so the component and
+ * its tests share one. Dates are ISO `YYYY-MM-DD` and are never converted
+ * through a time zone: a date is not an instant.
+ */
+import { formatCurrency } from '../../../format.js';
+export const LEDGER_PERIODS = [
+    { value: 'fy', label: 'Financial year' },
+    { value: 'cy', label: 'Calendar year' },
+    { value: 'month', label: 'Month' },
+    { value: 'week', label: 'Week' },
+    { value: 'day', label: 'Day' },
+    { value: 'none', label: 'None' }
+];
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+const MONTHS_LONG = [
+    'January',
+    'February',
+    'March',
+    'April',
+    'May',
+    'June',
+    'July',
+    'August',
+    'September',
+    'October',
+    'November',
+    'December'
+];
+const WEEKDAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+function parts(iso) {
+    return [Number(iso.slice(0, 4)), Number(iso.slice(5, 7)), Number(iso.slice(8, 10))];
+}
+/** A calendar date `days` on from an ISO date, in UTC so no clock change moves it. */
+function shift(iso, days) {
+    const [y, m, d] = parts(iso);
+    return new Date(Date.UTC(y, m - 1, d + days));
+}
+function isoOf(t) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${t.getUTCFullYear()}-${pad(t.getUTCMonth() + 1)}-${pad(t.getUTCDate())}`;
+}
+/** "15 Sep", or "15 Sep 2026" with the year. */
+export function ledgerDate(iso, withYear = true) {
+    const [y, m, d] = parts(iso);
+    return `${d} ${MONTHS[m - 1]}${withYear ? ` ${y}` : ''}`;
+}
+/** The year a financial year ends in. A January start makes it the calendar year. */
+function fyEnd(iso, fyStart) {
+    const [y, m] = parts(iso);
+    return fyStart > 1 && m >= fyStart ? y + 1 : y;
+}
+/** The group a date falls in: sortable, so newer keys sort later. */
+export function periodKey(iso, period, fyStart = 7) {
+    switch (period) {
+        case 'fy':
+            return String(fyEnd(iso, fyStart));
+        case 'cy':
+            return iso.slice(0, 4);
+        case 'month':
+            return iso.slice(0, 7);
+        case 'week': {
+            const [y, m, d] = parts(iso);
+            const monday = (new Date(Date.UTC(y, m - 1, d)).getUTCDay() + 6) % 7;
+            return isoOf(shift(iso, -monday));
+        }
+        case 'day':
+            return iso.slice(0, 10);
+        default:
+            return '';
+    }
+}
+/** A group's label: "FY 2025–26", "2026", "September 2026", "15 to 21 Sep 2026", "Tuesday 15 Sep 2026". */
+export function periodLabel(key, period, fyStart = 7, withYear = true) {
+    switch (period) {
+        case 'fy': {
+            const end = Number(key);
+            return fyStart > 1 ? `FY ${end - 1}–${String(end).slice(2)}` : `FY ${end}`;
+        }
+        case 'cy':
+            return key;
+        case 'month':
+            return `${MONTHS_LONG[Number(key.slice(5, 7)) - 1]} ${key.slice(0, 4)}`;
+        case 'week': {
+            const end = isoOf(shift(key, 6));
+            const [sy, sm, sd] = parts(key);
+            const [ey, em] = parts(end);
+            const start = `${sd}${sm !== em ? ` ${MONTHS[sm - 1]}` : ''}${sy !== ey ? ` ${sy}` : ''}`;
+            return `${start} to ${ledgerDate(end, withYear || sy !== ey)}`;
+        }
+        case 'day': {
+            const [y, m, d] = parts(key);
+            return `${WEEKDAYS[new Date(Date.UTC(y, m - 1, d)).getUTCDay()]} ${ledgerDate(key, withYear)}`;
+        }
+        default:
+            return '';
+    }
+}
+/** "Jul 2025 to Jun 2026", or "Jul 2026 to now" for the year still open on `today`. */
+export function fySpan(key, fyStart = 7, today = isoOf(new Date())) {
+    const end = Number(key);
+    const from = `${MONTHS[fyStart - 1]} ${fyStart > 1 ? end - 1 : end}`;
+    if (fyEnd(today, fyStart) === end)
+        return `${from} to now`;
+    return `${from} to ${MONTHS[(fyStart + 10) % 12]} ${end}`;
+}
+/** Rows newest first, a day's rows in the order given, grouped by period. */
+export function groupRows(rows, period, fyStart = 7) {
+    const sorted = [...rows].sort((a, b) => a.date.slice(0, 10) < b.date.slice(0, 10)
+        ? 1
+        : a.date.slice(0, 10) > b.date.slice(0, 10)
+            ? -1
+            : 0);
+    const out = [];
+    for (const r of sorted) {
+        const key = periodKey(r.date, period, fyStart);
+        const last = out[out.length - 1];
+        if (last && last.key === key)
+            last.rows.push(r);
+        else
+            out.push({ key, rows: [r] });
+    }
+    return out;
+}
+/** Whole cents, so a group's sum carries no float error. */
+export function cents(value) {
+    const n = Number(value);
+    return Number.isFinite(n) ? Math.round(n * 100) : 0;
+}
+/** Money as the ledger prints it: in plain, out in brackets. */
+export function ledgerMoney(value, currency = 'AUD', locale) {
+    return formatCurrency(value, { currency, locale, negative: 'brackets' });
+}
+/** Every group's head and rows in order; a run of rows on one card breaks where a row is open. */
+export function ledgerItems(groups, opts) {
+    const out = [];
+    groups.forEach((g, group) => {
+        if (opts.heads)
+            out.push({ kind: 'head', key: `h:${g.key}`, group });
+        if (opts.heads && opts.closed(g.key))
+            return;
+        let run = 0;
+        let from = -1;
+        const seal = () => {
+            if (from < 0)
+                return;
+            out[from].first = true;
+            out[out.length - 1].last = true;
+            from = -1;
+        };
+        for (const row of g.rows) {
+            if (row.id === opts.open) {
+                seal();
+                out.push({ kind: 'open', key: `o:${row.id}`, row, group });
+                run++;
+                continue;
+            }
+            if (from < 0)
+                from = out.length;
+            out.push({
+                kind: 'row',
+                key: `r:${row.id}`,
+                row,
+                group,
+                groupKey: g.key,
+                run,
+                first: false,
+                last: false
+            });
+        }
+        seal();
+    });
+    return out;
+}
+/** The first and last items overlapping `[top, bottom)`, given each item's start (and the end last). */
+export function windowOf(starts, top, bottom) {
+    const n = starts.length - 1;
+    const firstAt = (pred) => {
+        let lo = 0;
+        let hi = n;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (pred(mid))
+                hi = mid;
+            else
+                lo = mid + 1;
+        }
+        return lo;
+    };
+    const a = firstAt((i) => starts[i + 1] > top);
+    const b = firstAt((i) => starts[i] >= bottom) - 1;
+    return [a, b];
+}
+export function blocksOf(items, a, b) {
+    const out = [];
+    for (let i = Math.max(0, a); i <= b && i < items.length; i++) {
+        const it = items[i];
+        if (it.kind !== 'row') {
+            out.push(it);
+            continue;
+        }
+        const last = out[out.length - 1];
+        const entry = { row: it.row, first: it.first, key: it.key };
+        if (last?.kind === 'card' && last.group === it.group && last.run === it.run) {
+            last.rows.push(entry);
+            last.cutBottom = !it.last;
+        }
+        else {
+            out.push({
+                kind: 'card',
+                key: `c:${it.groupKey}:${it.run}`,
+                group: it.group,
+                run: it.run,
+                rows: [entry],
+                cutTop: !it.first,
+                cutBottom: !it.last
+            });
+        }
+    }
+    return out;
+}