@poodle64/ui 2026.10.1 → 2026.10.2

package/README.md

@@ -886,8 +886,8 @@ no module rebuilds them and a need one module finds becomes a toggle for all.
 
 | 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. |
+| `rows` | `LedgerRow`s, extended with whatever the module's columns read: `id`, `date` (ISO), `title`, `note`, `amount` (signed), `balance`, `review` (`true` or a `Status`) with `reviewLabel` (the chip's words, "Review" by default), `conversion` (a swap inside the account: plain amount, in no total), `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. A column's `sort` gives the real value its head sorts by (a number, not its text); a `text` column sorts by its text without one, a `cell`-only column does not sort, and the balance never does. |
 | `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. |
@@ -900,16 +900,22 @@ no module rebuilds them and a need one module finds becomes a toggle for all.
 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
+  row with no note centres its title. The checkbox, the review chip, 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
+- **One mark per kind.** A review chip (StatusBadge's dot and label on a tint)
+  beside the title on line one, which truncates before the chip does; 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' })`).
+- **Sorting and the groups' one control.** Click a column head to sort by it,
+  largest or newest first; click again to reverse. A sorted list is one flat
+  run with no group heads and shows the Date column even by day. Until the
+  viewer sorts, rows sit newest first in their groups. A chevron in the head's
+  gutter opens or closes every group at once; where rows tick, the gutter
+  widens to hold it beside the select-all checkbox.
 - **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

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

@@ -16,6 +16,11 @@ export declare function groupRows<R extends LedgerRow>(rows: readonly R[], perio
     key: string;
     rows: R[];
 }[];
+/**
+ * The rows ordered by a column's value, `dir` 1 ascending and -1 descending;
+ * rows without a value come last either way, and equal values keep newest first.
+ */
+export declare function sortRows<R extends LedgerRow>(rows: readonly R[], value: (row: R) => number | string | null | undefined, dir: 1 | -1): 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. */

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

@@ -122,6 +122,23 @@ export function groupRows(rows, period, fyStart = 7) {
     }
     return out;
 }
+/**
+ * The rows ordered by a column's value, `dir` 1 ascending and -1 descending;
+ * rows without a value come last either way, and equal values keep newest first.
+ */
+export function sortRows(rows, value, dir) {
+    const keyed = (groupRows(rows, 'none')[0]?.rows ?? []).map((row) => ({ row, v: value(row) }));
+    const missing = (v) => v === null || v === undefined || v === '';
+    keyed.sort((a, b) => {
+        if (missing(a.v) || missing(b.v))
+            return Number(missing(a.v)) - Number(missing(b.v));
+        const cmp = typeof a.v === 'number' && typeof b.v === 'number'
+            ? a.v - b.v
+            : String(a.v).localeCompare(String(b.v), undefined, { numeric: true, sensitivity: 'base' });
+        return dir * cmp;
+    });
+    return keyed.map((k) => k.row);
+}
 /** Whole cents, so a group's sum carries no float error. */
 export function cents(value) {
     const n = Number(value);

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

@@ -18,11 +18,13 @@
 	import { DEV } from 'esm-env';
 	import ChevronDown from '@lucide/svelte/icons/chevron-down';
 	import ChevronRight from '@lucide/svelte/icons/chevron-right';
+	import ChevronUp from '@lucide/svelte/icons/chevron-up';
 	import Paperclip from '@lucide/svelte/icons/paperclip';
 	import X from '@lucide/svelte/icons/x';
 	import Button from '../button/button.svelte';
 	import { Checkbox } from '../checkbox/index.js';
 	import EmptyState from '../empty-state/empty-state.svelte';
+	import StatusBadge from '../status-badge/status-badge.svelte';
 	import LedgerColumns from './ledger-columns.svelte';
 	import { AU_LOCALE } from '../../../format.js';
 	import { cn } from '../../../utils.js';
@@ -36,6 +38,7 @@
 		ledgerItems,
 		ledgerMoney,
 		periodLabel,
+		sortRows,
 		windowOf
 	} from './ledger.js';
 	import type { LedgerColumn, LedgerOpenContext, LedgerPreferences, LedgerRow } from './types.js';
@@ -109,12 +112,18 @@
 	} = $props();
 
 	const BUILT_IN: Record<string, Omit<LedgerColumn<R>, 'key'>> = {
-		date: { label: 'Date', width: { narrow: '4.25rem', wide: '7rem' } },
+		date: { label: 'Date', width: { narrow: '4.25rem', wide: '7rem' }, sort: (r) => r.date.slice(0, 10) },
 		title: {
 			label: 'Description',
+			sort: (r) => r.title,
 			width: { narrow: 'minmax(0, 1fr)', wide: 'minmax(16rem, 1.5fr)' }
 		},
-		amount: { label: 'Amount', width: { narrow: '7.25rem', wide: '9.5rem' }, align: 'end' },
+		amount: {
+			label: 'Amount',
+			width: { narrow: '7.25rem', wide: '9.5rem' },
+			align: 'end',
+			sort: (r) => cents(r.amount)
+		},
 		balance: {
 			label: 'Running balance',
 			head: 'Balance',
@@ -123,7 +132,9 @@
 			on: false
 		}
 	};
+	/** Ticking adds a checkbox to the gutter, so it widens to hold the chevron beside it. */
 	const GUTTER = '2.5rem';
+	const GUTTER_TICKS = '3.5rem';
 	const CELL = 'min-w-0 truncate px-2';
 	const END = 'pr-5 text-right';
 	/** The row's height rides the package's density ramp: 3.5rem, 3rem compact. */
@@ -202,7 +213,27 @@
 	);
 	const WIDE = $derived(mode === 'wide');
 	const PHONE = $derived(mode === 'phone');
-	const BY_DAY = $derived(prefs.period === 'day');
+
+	const selectable = $derived(!!bulkActions && !PHONE);
+	// ── Sorting: the viewer's own, kept here until a head is clicked again ──
+	let sort = $state<{ key: string; dir: 1 | -1 } | null>(null);
+	/** What a column sorts by; the running balance depends on the order, so never it. */
+	const sorter = (c: { key: string; sort?: LedgerColumn<R>['sort']; text?: LedgerColumn<R>['text'] }) =>
+		c.key === 'balance' ? undefined : (c.sort ?? c.text);
+	/** Click a head to sort by it, largest or newest first; again to reverse. */
+	function sortBy(key: string) {
+		sort = sort?.key === key ? { key, dir: sort.dir === 1 ? -1 : 1 } : { key, dir: -1 };
+	}
+	/** The sort in force: a column the viewer has since unticked no longer sorts. */
+	const activeSort = $derived.by(() => {
+		const col = sort && resolved.find((c) => c.key === sort!.key);
+		return sort && col && sorter(col) && (col.locked || prefs.columns.includes(col.key))
+			? sort
+			: null;
+	});
+	/** Until the viewer sorts, rows sit newest first in their period's groups. */
+	const grouped = $derived(prefs.period !== 'none' && !activeSort);
+	const BY_DAY = $derived(grouped && prefs.period === 'day');
 
 	const shown = $derived(
 		resolved.filter(
@@ -210,7 +241,7 @@
 		)
 	);
 	const template = $derived(
-		`${GUTTER} ${shown.map((c) => (WIDE ? c.track.wide : c.track.narrow)).join(' ')}`
+		`${selectable ? GUTTER_TICKS : GUTTER} ${shown.map((c) => (WIDE ? c.track.wide : c.track.narrow)).join(' ')}`
 	);
 	/** A column's grid line, the gutter being 1; 0 when it is not shown. */
 	const column = (key: string) => {
@@ -229,7 +260,11 @@
 		if (DEV && !validStart)
 			console.error(`Ledger: fyStart is a month from 1 to 12, not ${fyStart}; grouping from July.`);
 	});
-	const groups = $derived(groupRows(rows, prefs.period, fy));
+	const groups = $derived.by(() => {
+		const by = activeSort && sorter(resolved.find((c) => c.key === activeSort.key)!);
+		if (activeSort && by) return [{ key: '', rows: sortRows(rows, by, activeSort.dir) }];
+		return groupRows(rows, prefs.period, fy);
+	});
 	/** Closed groups, keyed with their period so a new period starts open. */
 	const closed = new SvelteSet<string>();
 	const groupId = (key: string) => `${prefs.period}:${key}`;
@@ -241,6 +276,17 @@
 		else set.add(value);
 	}
 
+	const allOpen = $derived(groups.every((g) => !closed.has(groupId(g.key))));
+	/** One control for every group: open them all, or close them all. */
+	function toggleAll() {
+		const closing = allOpen;
+		if (closing && open !== null) setOpen(null);
+		for (const g of groups) {
+			if (closing) closed.add(groupId(g.key));
+			else closed.delete(groupId(g.key));
+		}
+	}
+
 	/** Closing a group closes the row open in it, and says so. */
 	function toggleGroup(g: { key: string; rows: readonly R[] }) {
 		const id = groupId(g.key);
@@ -249,7 +295,6 @@
 	}
 
 	// ── Selection and the opened row ──
-	const selectable = $derived(!!bulkActions && !PHONE);
 	const openable = $derived(!!editor);
 	const ticked = $derived(new Set<Id>(selected));
 	const tickedRows = $derived(groups.flatMap((g) => g.rows).filter((r) => ticked.has(r.id)));
@@ -287,7 +332,7 @@
 	// bar, the cards and the head keep their true geometry.
 	const items = $derived(
 		ledgerItems(groups, {
-			heads: prefs.period !== 'none',
+			heads: grouped,
 			closed: (key) => closed.has(groupId(key)),
 			open: openable ? open : null
 		})
@@ -301,7 +346,7 @@
 	let measured = $state(0);
 	let rowEstimate = $state(REM * 3.5);
 	let headEstimate = $state(REM * 3.125);
-	const sizeKey = (key: string) => `${mode}|${prefs.period}|${key}`;
+	const sizeKey = (key: string) => `${mode}|${grouped ? prefs.period : 'flat'}|${key}`;
 
 	const starts = $derived.by(() => {
 		void measured;
@@ -367,6 +412,7 @@
 		let inn = 0;
 		let out = 0;
 		for (const r of rs) {
+			if (r.conversion) continue;
 			const c = cents(r.amount);
 			if (c > 0) inn += c;
 			else out += c;
@@ -378,6 +424,8 @@
 	const number = (n: number) => n.toLocaleString(locale);
 	const count = (n: number) => `${number(n)} ${n === 1 ? noun[0] : noun[1]}`;
 	const income = (value: number | string | null | undefined) => cents(value) > 0;
+	/** Green for money in; a conversion is neither in nor out, so plain. */
+	const isIncome = (r: R) => !r.conversion && income(r.amount);
 	const reviewOf = (r: R) => (r.review === true ? 'warning' : r.review || null);
 	const balanceText = (r: R) =>
 		balanceColumn?.text ? balanceColumn.text(r) : r.balance == null ? '' : money(r.balance);
@@ -431,19 +479,12 @@
 	</button>
 {/snippet}
 
-{#snippet dot(r: R, beside: boolean)}
+{#snippet chip(r: R)}
 	{@const status = reviewOf(r)}
 	{#if status}
-		<span
-			class={cn(
-				'ds-dot size-1.5',
-				`ds-dot-${status}`,
-				beside && 'absolute top-1/2 right-[calc(50%+0.75rem)] -translate-y-1/2'
-			)}
-			role="img"
-			aria-label="Needs review"
-			data-slot="ledger-review"
-		></span>
+		<span class="flex-none" data-slot="ledger-review">
+			<StatusBadge {status} label={r.reviewLabel ?? 'Review'} />
+		</span>
 	{/if}
 {/snippet}
 
@@ -467,6 +508,7 @@
 				<span class="flex min-w-0 items-center gap-1.5">
 					<span class="min-w-0 truncate">{r.title}</span>
 					{#if r.attachment}{@render clip(r)}{/if}
+					{@render chip(r)}
 				</span>
 				{#if r.note || r.origins}
 					<span class="text-muted-foreground flex min-w-0 items-center gap-2 text-xs font-normal">
@@ -482,7 +524,7 @@
 					END,
 					through,
 					'self-center tabular-nums',
-					income(r.amount) && 'text-status-success'
+					isIncome(r) && 'text-status-success'
 				)}
 				{style}
 				data-slot="ledger-amount"
@@ -611,9 +653,9 @@
 			{/if}
 			<span class="pointer-events-none flex min-w-0 flex-col justify-center gap-0.5">
 				<span class="flex min-w-0 items-center gap-1.5">
-					{@render dot(r, false)}
 					<span class="min-w-0 truncate font-medium">{r.title}</span>
 					{#if r.attachment}{@render clip(r)}{/if}
+					{@render chip(r)}
 				</span>
 				{#if two || r.origins}
 					<span class="text-muted-foreground flex min-w-0 items-center gap-2 text-xs">
@@ -623,7 +665,7 @@
 				{/if}
 			</span>
 			<span class="pointer-events-none flex flex-col items-end justify-center gap-0.5 tabular-nums">
-				<span class={cn(income(r.amount) && 'text-status-success')} data-slot="ledger-amount"
+				<span class={cn(isIncome(r) && 'text-status-success')} data-slot="ledger-amount"
 					>{money(r.amount)}</span
 				>
 				{#if balanceOn && balanceText(r)}<span class="text-muted-foreground text-xs"
@@ -643,7 +685,6 @@
 			data-slot="ledger-row"
 		>
 			<span class="relative flex items-center justify-center" style="grid-column: 1; grid-row: 1;">
-				{@render dot(r, selectable)}
 				{#if selectable}
 					<Checkbox
 						checked={on}
@@ -732,7 +773,10 @@
 		<span class="min-w-0 flex-1 truncate">{metaText}</span>
 		<span class={cn('tabular-nums', netTone)}>{net}</span>
 	{:else}
-		<span class="grid place-items-center" style="grid-column: 1;">
+		<span
+			class={cn('grid place-items-center', selectable && 'justify-items-start pl-[5px]')}
+			style="grid-column: 1;"
+		>
 			{#if !BY_DAY}<ChevronRight
 					class={cn('size-3.5 transition-transform', isOpen && 'rotate-90')}
 				/>{/if}
@@ -776,7 +820,7 @@
 			<span class="text-sm font-semibold whitespace-nowrap">{number(tickedRows.length)} ticked</span
 			>
 			<span class="text-muted-foreground mr-2 text-xs whitespace-nowrap tabular-nums">
-				net {money(tickedRows.reduce((s, r) => s + cents(r.amount), 0) / 100)}
+				net {money(tickedRows.reduce((s, r) => s + (r.conversion ? 0 : cents(r.amount)), 0) / 100)}
 			</span>
 			{@render bulkActions?.(tickedRows)}
 			<span class="flex-1"></span>
@@ -829,7 +873,23 @@
 					style:grid-template-columns={template}
 					data-slot="ledger-head"
 				>
-					<span class="grid place-items-center">
+					<span class="relative grid place-items-center">
+						{#if grouped && !BY_DAY && groups.length}
+							<button
+								type="button"
+								class={cn(
+									'text-muted-foreground hover:text-foreground absolute top-1/2 z-10 grid size-4 -translate-y-1/2 cursor-pointer place-items-center rounded-md',
+									selectable ? 'left-1' : 'left-1/2 -translate-x-1/2',
+									RING
+								)}
+								aria-label={allOpen ? 'Collapse every group' : 'Expand every group'}
+								aria-expanded={allOpen}
+								onclick={toggleAll}
+								data-slot="ledger-all-groups"
+							>
+								<ChevronRight class={cn('size-3.5 transition-transform', allOpen && 'rotate-90')} />
+							</button>
+						{/if}
 						{#if selectable}
 							<Checkbox
 								checked={allTicked}
@@ -844,15 +904,46 @@
 						{/if}
 					</span>
 					{#each shown as c (c.key)}
-						<span
-							class={cn(
-								CELL,
-								'text-muted-foreground text-2xs tracking-eyebrow font-semibold uppercase',
-								c.align === 'end' && END
-							)}
-						>
-							{c.head ?? c.label}
-						</span>
+						{@const sortable = !!sorter(c)}
+						{@const mine = activeSort?.key === c.key ? activeSort : null}
+						{@const label = c.head ?? c.label}
+						{@const headClass = cn(
+							CELL,
+							'text-muted-foreground text-2xs tracking-eyebrow font-semibold uppercase',
+							c.align === 'end' && END
+						)}
+						{#if sortable}
+							<button
+								type="button"
+								class={cn(
+									headClass,
+									'group flex cursor-pointer items-center gap-0.5 rounded-md hover:text-foreground',
+									RING_INSET,
+									c.align === 'end' && 'justify-end',
+									mine && 'text-foreground'
+								)}
+								aria-label={mine
+									? `Sorted by ${c.label}, ${mine.dir === -1 ? 'descending' : 'ascending'}. Click to reverse`
+									: `Sort by ${c.label}`}
+								onclick={() => sortBy(c.key)}
+								data-slot="ledger-sort"
+								data-sort={mine ? (mine.dir === -1 ? 'desc' : 'asc') : undefined}
+							>
+								<span class="truncate">{label}</span>
+								{#if mine?.dir === 1}
+									<ChevronUp class="size-3 flex-none" />
+								{:else}
+									<ChevronDown
+										class={cn(
+											'size-3 flex-none',
+											!mine && 'opacity-0 group-hover:opacity-50 group-focus-visible:opacity-50'
+										)}
+									/>
+								{/if}
+							</button>
+						{:else}
+							<span class={headClass}>{label}</span>
+						{/if}
 					{/each}
 				</div>
 			</div>

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

@@ -25,8 +25,17 @@ export interface LedgerRow {
     amount: number | string;
     /** What the running balance counts after this row: money, a coin, units. */
     balance?: number | string | null;
-    /** A dot at the row's left edge. `true` is a warning. */
+    /** A chip beside the title, on line one. `true` is a warning. */
     review?: boolean | Status;
+    /** The review chip's words, in the module's own voice. Defaults to "Review". */
+    reviewLabel?: string;
+    /**
+     * The amount is a conversion inside the account (dollars swapped for a
+     * coin, so what the account is worth does not change). It shows plain,
+     * neither income green nor the muted outgoing tone, and counts in no
+     * group's in, out or net, nor the ticked rows' net.
+     */
+    conversion?: boolean;
     /** The attachment's name: a paperclip after the title, the name on hover. */
     attachment?: string | null;
     /** A row not as printed: the statement lines it was made from. */
@@ -55,6 +64,13 @@ export interface LedgerColumn<R extends LedgerRow = LedgerRow> {
     align?: 'start' | 'end';
     /** Ticked until the viewer chooses. Defaults to true, and to false for `balance`. */
     on?: boolean;
+    /**
+     * What a click on the head sorts this column by: the real value, a number
+     * rather than its display text. Without it a column with `text` sorts by
+     * that text and a `cell`-only column does not sort. The running balance
+     * never sorts, since it depends on the order.
+     */
+    sort?: (row: R) => number | string | null | undefined;
     /** A plain cell. */
     text?: (row: R) => string;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@poodle64/ui",
-	"version": "2026.10.1",
+	"version": "2026.10.2",
 	"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,7 +1,7 @@
 {
 	"meta": {
 		"package": "@poodle64/ui",
-		"version": "2026.10.1",
+		"version": "2026.10.2",
 		"generatedBy": "scripts/generate-registry.mjs",
 		"source": "scripts/situations.json + package source (DO NOT EDIT the outputs by hand)",
 		"componentCount": 62,

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.1`. 62 components, 18 situations.
+Generated from `@poodle64/ui@2026.10.2`. 62 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.