@poodle64/ui 2026.10.0 → 2026.10.1

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

@@ -0,0 +1,78 @@
+/**
+     * The household ledger: one component for every money list, read the same
+     * way in every module. The consumer brings its rows and the columns it
+     * offers; the ledger owns the look (PocketSmith's: a head card, one card per
+     * period, the group's label on the page ground), the grouping and the
+     * viewer's toggles, which it emits for the consumer to keep.
+     *
+     * 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` in a
+     * full-height page). Width picks the layout: a phone's list below 600px, the
+     * wide column widths from 1200px.
+     */
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { LedgerColumn, LedgerOpenContext, LedgerPreferences, LedgerRow } from './types.js';
+declare function $$render<R extends LedgerRow>(): {
+    props: Omit<HTMLAttributes<HTMLDivElement>, "title"> & {
+        rows: readonly R[];
+        /** The module's columns, in order after the amount. See `LedgerColumn`. */
+        columns?: LedgerColumn<R>[];
+        /** The viewer's columns and period. Missing fields take the module's defaults. */
+        preferences?: Partial<LedgerPreferences>;
+        onPreferencesChange?: (next: LedgerPreferences) => void;
+        /** The Columns menu's footnote: where the choice is kept. */
+        preferencesNote?: string;
+        /** The month a financial year starts, 1–12. July by default. */
+        fyStart?: number;
+        currency?: string;
+        /** BCP 47 locale for every figure: amounts, nets and counts. */
+        locale?: string;
+        /** What a row is called, one and many: a printed layer's "line". */
+        noun?: [string, string];
+        title?: string;
+        /** Beside the title. Defaults to the row count. */
+        meta?: string;
+        /** The toolbar's own actions, after the Columns menu: export, add. */
+        actions?: Snippet;
+        /** The ticked rows' ids. Ticking needs `bulkActions`. */
+        selected?: R["id"][];
+        /** What the ticked rows allow, in the bar that replaces the toolbar. */
+        bulkActions?: Snippet<[R[]]>;
+        /** The row opened in place. Opening needs `editor`. */
+        open?: R["id"] | null;
+        onOpenChange?: (id: R["id"] | null) => void;
+        /** The opened row's content. */
+        editor?: Snippet<[R, LedgerOpenContext]>;
+        /** Under a synthetic row's statement lines: split, join, undo. */
+        originActions?: Snippet<[R]>;
+        /** Makes the paperclip a button. */
+        onAttachment?: (row: R) => void;
+        empty?: Snippet;
+        /** After the last group, inside the scroll: "Show more". */
+        footer?: Snippet;
+        layout?: "auto" | "phone" | "narrow" | "wide";
+        class?: string;
+    };
+    exports: {};
+    bindings: "open" | "selected" | "preferences";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<R extends LedgerRow> {
+    props(): ReturnType<typeof $$render<R>>['props'];
+    events(): ReturnType<typeof $$render<R>>['events'];
+    slots(): ReturnType<typeof $$render<R>>['slots'];
+    bindings(): "open" | "selected" | "preferences";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <R extends LedgerRow>(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 LedgerRow>(internal: unknown, props: ReturnType<__sveltets_Render<R>['props']> & {}): ReturnType<__sveltets_Render<R>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const Ledger: $$IsomorphicComponent;
+type Ledger<R extends LedgerRow> = InstanceType<typeof Ledger<R>>;
+export default Ledger;

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

@@ -0,0 +1,79 @@
+import type { Snippet } from 'svelte';
+import type { Status } from '../status/index.js';
+/** How the viewer groups rows. `fy` honours the ledger's `fyStart`. */
+export type LedgerPeriod = 'fy' | 'cy' | 'month' | 'week' | 'day' | 'none';
+/** One statement line a synthetic row (a split, a join) was made from. */
+export interface LedgerOrigin {
+    /** ISO `YYYY-MM-DD`. */
+    date: string;
+    /** The line as the statement printed it. */
+    description: string;
+    /** Where it was printed: "Statement 23, line 14". */
+    source?: string;
+    amount: number | string;
+}
+/** What the ledger reads off a row. A consumer extends it with its own fields for its columns. */
+export interface LedgerRow {
+    id: string | number;
+    /** ISO `YYYY-MM-DD`. */
+    date: string;
+    /** Line one: the counterparty the money moved with, the asset, the security. */
+    title: string;
+    /** Line two, under the title. */
+    note?: string | null;
+    /** Signed: money in is positive, money out negative. */
+    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. */
+    review?: boolean | Status;
+    /** 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. */
+    origins?: {
+        summary?: string;
+        lines: LedgerOrigin[];
+    } | null;
+}
+/**
+ * A column the module offers. The keys `date`, `title`, `amount` and `balance`
+ * are the ledger's own cells: list one to rename or resize it (and, for
+ * `balance`, to offer the running balance at all, with `text` saying what it
+ * counts). Date, title and amount always show, first and in that order; the
+ * balance is always last. Every other key is the module's, in its order.
+ */
+export interface LedgerColumn<R extends LedgerRow = LedgerRow> {
+    key: string;
+    /** Its name in the Columns menu, and its head unless `head` is shorter. */
+    label: string;
+    head?: string;
+    /** A grid track, or one for a narrow ledger and one for a wide one. */
+    width?: string | {
+        narrow: string;
+        wide: string;
+    };
+    align?: 'start' | 'end';
+    /** Ticked until the viewer chooses. Defaults to true, and to false for `balance`. */
+    on?: boolean;
+    /** A plain cell. */
+    text?: (row: R) => string;
+    /**
+     * A cell of the module's own markup. On a row that opens, a click passes
+     * through the cell to the row; a control inside takes `pointer-events-auto`.
+     */
+    cell?: Snippet<[R]>;
+}
+/** The viewer's own choices, which the consumer persists. */
+export interface LedgerPreferences {
+    /** The ticked columns' keys, `balance` included. */
+    columns: string[];
+    period: LedgerPeriod;
+}
+/** What an opened row's content gets, to line its fields up under the columns. */
+export interface LedgerOpenContext {
+    close: () => void;
+    /** The row's `grid-template-columns`, gutter first. */
+    template: string;
+    /** A column's grid line, 1-based with the gutter at 1; 0 when it is not shown. */
+    column: (key: string) => number;
+}

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

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

package/dist/format.d.ts

@@ -61,6 +61,13 @@ export interface CurrencyOptions {
      * must not confuse the two.
      */
     currency?: string;
+    /**
+     * How a negative reads. `sign` (the default) is `-$500`; `brackets` is the
+     * accountant's `($500)`, which a ledger's amount column wants.
+     */
+    negative?: 'sign' | 'brackets';
+    /** BCP 47 locale for the digits and separators. Defaults to `AU_LOCALE`. */
+    locale?: string;
 }
 /**
  * Format a DOLLAR value as currency.
@@ -69,6 +76,7 @@ export interface CurrencyOptions {
  * formatCurrency(1234.56)                      // '$1,234.56'
  * formatCurrency('1234.56', { decimals: 0 })   // '$1,235'
  * formatCurrency(-500, { decimals: 0 })        // '-$500'
+ * formatCurrency(-500, { negative: 'brackets' }) // '($500.00)'
  * formatCurrency(null)                         // 'N/A'
  */
 export declare function formatCurrency(value: string | number | null | undefined, options?: CurrencyOptions): string;

package/dist/format.js

@@ -72,19 +72,25 @@ function toFiniteNumber(value) {
  * formatCurrency(1234.56)                      // '$1,234.56'
  * formatCurrency('1234.56', { decimals: 0 })   // '$1,235'
  * formatCurrency(-500, { decimals: 0 })        // '-$500'
+ * formatCurrency(-500, { negative: 'brackets' }) // '($500.00)'
  * formatCurrency(null)                         // 'N/A'
  */
 export function formatCurrency(value, options = {}) {
-    const { decimals = 2, fallback = FALLBACK, currency = 'AUD' } = options;
+    const { decimals = 2, fallback = FALLBACK, currency = 'AUD', negative = 'sign', locale = AU_LOCALE } = options;
     const num = toFiniteNumber(value);
     if (num === null)
         return fallback;
-    return new Intl.NumberFormat(AU_LOCALE, {
+    const format = new Intl.NumberFormat(locale, {
         style: 'currency',
         currency,
         minimumFractionDigits: decimals,
         maximumFractionDigits: decimals
-    }).format(num);
+    });
+    if (negative !== 'brackets' || num >= 0)
+        return format.format(num);
+    // A negative that rounds to nothing is not money out: no brackets around a zero.
+    const magnitude = format.format(-num);
+    return magnitude === format.format(0) ? magnitude : `(${magnitude})`;
 }
 /**
  * Format an INTEGER-CENTS value as currency.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@poodle64/ui",
-	"version": "2026.10.0",
+	"version": "2026.10.1",
 	"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",
@@ -83,6 +83,7 @@
 		"@lucide/svelte": "^1.25.0",
 		"@tanstack/table-core": "^8.21.3",
 		"clsx": "^2.1.1",
+		"esm-env": "^1.2.2",
 		"html-to-image": "^1.11.13",
 		"tailwind-merge": "^3.6.0",
 		"tailwind-variants": "^3.2.2",

package/registry/component-map.json

@@ -1,11 +1,11 @@
 {
 	"meta": {
 		"package": "@poodle64/ui",
-		"version": "2026.10.0",
+		"version": "2026.10.1",
 		"generatedBy": "scripts/generate-registry.mjs",
 		"source": "scripts/situations.json + package source (DO NOT EDIT the outputs by hand)",
-		"componentCount": 61,
-		"situationCount": 17
+		"componentCount": 62,
+		"situationCount": 18
 	},
 	"situations": [
 		{
@@ -148,6 +148,20 @@
 				}
 			]
 		},
+		{
+			"key": "ledger",
+			"title": "A ledger of what moved",
+			"description": "Dated rows of money, coins or units moving — a bank account, a property's books, a wallet, a brokerage — read the same way in every module: two lines a row, grouped by the period the viewer picks, the viewer's own columns and running balance. The module brings its rows and offers its columns; the look, the grouping and the toggles are the ledger's.",
+			"components": [
+				{
+					"name": "Ledger",
+					"dir": "ledger",
+					"import": "@poodle64/ui/ledger",
+					"props": "rows, columns?, preferences?, onPreferencesChange?, title?, actions?, selected?, bulkActions?, open?, editor?",
+					"insteadOf": "a DataTableTanstack of transactions, or a hand-built grouped list with its own period headers and column picker"
+				}
+			]
+		},
 		{
 			"key": "sectioning-card",
 			"title": "A titled section of a route",

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.0`. 61 components, 17 situations.
+Generated from `@poodle64/ui@2026.10.1`. 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.
 
@@ -76,6 +76,14 @@ _An index of many peer items — a responsive tile wall, or a sortable/filterabl
 | `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 |
 
+## A ledger of what moved
+
+_Dated rows of money, coins or units moving — a bank account, a property's books, a wallet, a brokerage — read the same way in every module: two lines a row, grouped by the period the viewer picks, the viewer's own columns and running balance. The module brings its rows and offers its columns; the look, the grouping and the toggles are the ledger's._
+
+| 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 |
+
 ## A titled section of a route
 
 _The generic titled card every route reaches for — an optional header with icon, subtitle and actions over a body. The default answer to 'I need a card here'._