@poodle64/ui 2026.8.14 → 2026.8.17

package/dist/format.js

@@ -0,0 +1,422 @@
+/**
+ * The household's Australian value formatters.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Two apps had hand-rolled the same job — `godswood/frontend/src/lib/utils/
+ * formatters.ts` and `pebblestone/frontend/src/lib/utils/format.ts` — and had
+ * already drifted on every decision that matters: whether a percentage arrives
+ * as `4.5` or `0.045`, whether money arrives as dollars or as integer cents,
+ * whether a date renders `19 Dec 2024` or `19/12/2024`, and whether a missing
+ * value reads `N/A` or `-`. All four are user-visible, and the fleet is
+ * entirely Australian, so the disagreement bought nothing.
+ *
+ * WHAT IS IN AND WHAT IS NOT
+ * --------------------------
+ * In: every formatter for a value class BOTH apps format — money, dates and
+ * times, percentages, plain numbers — including the variants only one app has
+ * today, because a value class the package owns it owns completely. Splitting
+ * money across two homes is how the drift started.
+ *
+ * Out: formatters for a value class only ONE app has, which are a domain
+ * vocabulary rather than a shared value class — loan repayment frequencies and
+ * AI model IDs (godswood), file sizes (godswood), pager arithmetic and the
+ * per-line GST recompute for bill approvals (pebblestone, and bound to Xero tax
+ * codes besides). Relative time ("2 hours ago") is out too: it lives on
+ * `date-fns` in the one app that has it, and a display formatter is not worth
+ * making that a dependency of every consumer of this package.
+ *
+ * THE CONVENTIONS THESE ENCODE
+ * ----------------------------
+ * - `en-AU`, AUD, and `Australia/Brisbane` wherever a timezone is implied. The
+ *   zone is pinned rather than taken from the browser: the household's books
+ *   are kept in AEST, so a laptop in another zone should not renumber them.
+ * - Dates render `DD Mon YYYY` or, on request, `DD/MM/YYYY` — both sanctioned
+ *   Australian forms.
+ * - A negative amount carries its sign OUTSIDE the symbol: `-$1,234.56`, never
+ *   `$-1,234.56`.
+ * - A missing value renders `N/A`, and every formatter takes a `fallback` to
+ *   say otherwise. `-` is deliberately not the default: beside a money column
+ *   it reads as a minus sign, which is the one wrong meaning available.
+ *
+ * No dependencies, no DOM: this module is `Intl` and arithmetic.
+ */
+/** The one locale every household app formats in. */
+export const AU_LOCALE = 'en-AU';
+/** The one timezone the household's records are kept in. */
+export const AU_TIME_ZONE = 'Australia/Brisbane';
+/** What a formatter renders when it has nothing to render. */
+const FALLBACK = 'N/A';
+/**
+ * Coerce an API value to a finite number, or null.
+ *
+ * `Number` rather than `parseFloat`, deliberately: `parseFloat('12abc')` is 12,
+ * which renders corrupt data as a plausible figure. A value that is not wholly
+ * numeric falls back instead.
+ */
+function toFiniteNumber(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return null;
+    const num = Number(trimmed);
+    return Number.isFinite(num) ? num : null;
+}
+/**
+ * Format a DOLLAR value as currency.
+ *
+ * @example
+ * formatCurrency(1234.56)                      // '$1,234.56'
+ * formatCurrency('1234.56', { decimals: 0 })   // '$1,235'
+ * formatCurrency(-500, { decimals: 0 })        // '-$500'
+ * formatCurrency(null)                         // 'N/A'
+ */
+export function formatCurrency(value, options = {}) {
+    const { decimals = 2, fallback = FALLBACK, currency = 'AUD' } = options;
+    const num = toFiniteNumber(value);
+    if (num === null)
+        return fallback;
+    return new Intl.NumberFormat(AU_LOCALE, {
+        style: 'currency',
+        currency,
+        minimumFractionDigits: decimals,
+        maximumFractionDigits: decimals
+    }).format(num);
+}
+/**
+ * Format an INTEGER-CENTS value as currency.
+ *
+ * Money held as integer cents is the correct storage for money, and the app
+ * that does it should not have to divide by 100 at every call site and hope
+ * the float lands.
+ *
+ * @example
+ * formatCurrencyFromCents(123456)                    // '$1,234.56'
+ * formatCurrencyFromCents(-123456, { decimals: 0 })  // '-$1,235'
+ * formatCurrencyFromCents(null)                      // 'N/A'
+ */
+export function formatCurrencyFromCents(cents, options = {}) {
+    if (cents === null || cents === undefined || !Number.isFinite(cents)) {
+        return options.fallback ?? FALLBACK;
+    }
+    return formatCurrency(cents / 100, options);
+}
+/** Convert a dollar value to whole cents. */
+export function dollarsToCents(dollars) {
+    return Math.round(dollars * 100);
+}
+/**
+ * The currency prefix `formatCurrency` would use — `$` for AUD, `USD ` for
+ * USD — so the compact form and the full form never disagree about the symbol.
+ */
+function currencyPrefix(currency) {
+    const parts = new Intl.NumberFormat(AU_LOCALE, {
+        style: 'currency',
+        currency,
+        minimumFractionDigits: 0,
+        maximumFractionDigits: 0
+    }).formatToParts(0);
+    let prefix = '';
+    for (const part of parts) {
+        if (part.type === 'integer')
+            break;
+        if (part.type === 'currency' || part.type === 'literal')
+            prefix += part.value;
+    }
+    return prefix;
+}
+/**
+ * Abbreviate a money value for a chart axis or a dense tile.
+ *
+ * A y-axis tick has room for four or five characters, not for `$1,109,057.64`.
+ * Full precision belongs in the tooltip and the table; the axis exists to tell
+ * the reader which order of magnitude they are looking at.
+ *
+ * @example
+ * compactCurrency(1_109_057.64)  // '$1.1m'
+ * compactCurrency(-1_500_000)    // '-$1.5m'
+ * compactCurrency(12_400)        // '$12k'
+ */
+export function compactCurrency(value, options = {}) {
+    const { currency = 'AUD', fallback = FALLBACK } = options;
+    if (value === null || value === undefined || !Number.isFinite(value))
+        return fallback;
+    const prefix = currencyPrefix(currency);
+    // Sign outside the symbol, as everywhere else here: `-$1.5m`, not `$-1.5m`.
+    const sign = value < 0 ? '-' : '';
+    const abs = Math.abs(value);
+    if (abs >= 1_000_000)
+        return `${sign}${prefix}${(abs / 1_000_000).toFixed(1)}m`;
+    if (abs >= 1_000)
+        return `${sign}${prefix}${Math.round(abs / 1_000)}k`;
+    return `${sign}${prefix}${Math.round(abs)}`;
+}
+/**
+ * Format a money figure that arrives as a STRING, without ever parsing it to a
+ * JS number.
+ *
+ * A securities tax P&L reaches a tax return, so a figure must render with the
+ * exact digits the API sent — `parseFloat` rounds at 2^53 and quietly changes
+ * cents on a nine-figure total. This groups the integer part with thousands
+ * separators and preserves the fractional part verbatim, so the displayed
+ * string is faithful to the source decimal whatever its magnitude.
+ *
+ * @example
+ * formatCurrencyString('1234.56')     // '$1,234.56'
+ * formatCurrencyString('-1234567.89') // '-$1,234,567.89'
+ * formatCurrencyString('0')           // '$0'
+ * formatCurrencyString(null)          // 'N/A'
+ */
+export function formatCurrencyString(value, options = {}) {
+    const { fallback = FALLBACK } = options;
+    if (value === null || value === undefined)
+        return fallback;
+    const trimmed = String(value).trim();
+    if (trimmed === '' || trimmed === 'NaN')
+        return fallback;
+    let negative = false;
+    let body = trimmed;
+    if (body.startsWith('-')) {
+        negative = true;
+        body = body.slice(1);
+    }
+    else if (body.startsWith('+')) {
+        body = body.slice(1);
+    }
+    const [rawInt, rawFrac] = body.split('.');
+    const intPart = (rawInt ?? '').replace(/[^0-9]/g, '') || '0';
+    const grouped = intPart.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+    let out = grouped;
+    if (rawFrac !== undefined)
+        out += `.${rawFrac}`;
+    return `${negative ? '-' : ''}$${out}`;
+}
+/**
+ * Report the sign of a money value without parsing a string to a number — the
+ * float-free companion to `formatCurrencyString`, for choosing a tone class.
+ */
+export function isNegativeMoney(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value === 'number')
+        return value < 0;
+    return value.trim().startsWith('-');
+}
+// --------------------------------------------------------------------------- //
+//  Numbers and percentages                                                     //
+// --------------------------------------------------------------------------- //
+/**
+ * Format a number with thousands separators.
+ *
+ * @example
+ * formatNumber(1234567)                  // '1,234,567'
+ * formatNumber(1234.567, { decimals: 2 }) // '1,234.57'
+ * formatNumber(null)                      // 'N/A'
+ */
+export function formatNumber(value, options = {}) {
+    const { decimals = 0, fallback = FALLBACK } = options;
+    const num = toFiniteNumber(value);
+    if (num === null)
+        return fallback;
+    return new Intl.NumberFormat(AU_LOCALE, {
+        minimumFractionDigits: decimals,
+        maximumFractionDigits: decimals
+    }).format(num);
+}
+/**
+ * Format a value that is ALREADY in percentage points: `4.5` renders `4.5%`.
+ *
+ * Its counterpart for a 0–1 ratio is `formatRatioAsPercentage`. The two are
+ * named apart on purpose — the apps disagreed about which one `formatPercent`
+ * meant, and picking either spelling for both would make a 100x error a
+ * one-character mistake.
+ *
+ * @example
+ * formatPercentage(4.5)                    // '4.5%'
+ * formatPercentage('4.5', { decimals: 2 }) // '4.50%'
+ * formatPercentage(null)                   // 'N/A'
+ */
+export function formatPercentage(value, options = {}) {
+    const { decimals = 1, fallback = FALLBACK } = options;
+    const num = toFiniteNumber(value);
+    if (num === null)
+        return fallback;
+    return `${num.toFixed(decimals)}%`;
+}
+/**
+ * Format a 0–1 RATIO as a percentage: `0.045` renders `4.5%`.
+ *
+ * @example
+ * formatRatioAsPercentage(0.045)  // '4.5%'
+ * formatRatioAsPercentage(1)      // '100.0%'
+ * formatRatioAsPercentage(null)   // 'N/A'
+ */
+export function formatRatioAsPercentage(value, options = {}) {
+    const { decimals = 1, fallback = FALLBACK } = options;
+    const num = toFiniteNumber(value);
+    if (num === null)
+        return fallback;
+    return `${(num * 100).toFixed(decimals)}%`;
+}
+// --------------------------------------------------------------------------- //
+//  Dates and times                                                             //
+// --------------------------------------------------------------------------- //
+// Intl `en-AU` short months are not uniformly three characters: June, July and
+// Sept come back four. Force a canonical abbreviation so a date column aligns.
+const SHORT_MONTHS = [
+    'Jan',
+    'Feb',
+    'Mar',
+    'Apr',
+    'May',
+    'Jun',
+    'Jul',
+    'Aug',
+    'Sep',
+    'Oct',
+    'Nov',
+    'Dec'
+];
+const LONG_MONTHS = [
+    'January',
+    'February',
+    'March',
+    'April',
+    'May',
+    'June',
+    'July',
+    'August',
+    'September',
+    'October',
+    'November',
+    'December'
+];
+const DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
+/**
+ * Parse a timestamp the API returned.
+ *
+ * A backend that stores naive UTC (`datetime.now(UTC).replace(tzinfo=None)`)
+ * and serialises it with no offset hands JavaScript a string it reads as LOCAL
+ * time: in Brisbane that lands every stored moment ten hours early, so anything
+ * after 2pm shows the wrong DAY, not merely the wrong hour. An offset-less
+ * value carrying a time is therefore read as UTC; one that carries an offset is
+ * left alone, and a date-only value is left alone too (appending a `Z` to it
+ * produces an Invalid Date).
+ */
+export function parseApiDate(iso) {
+    const hasTime = iso.includes('T');
+    const hasOffset = /([zZ]|[+-]\d{2}:?\d{2})$/.test(iso);
+    return new Date(hasTime && !hasOffset ? `${iso}Z` : iso);
+}
+/** The calendar fields of an instant, as read in `timeZone`. */
+function zonedParts(date, timeZone) {
+    const parts = new Intl.DateTimeFormat(AU_LOCALE, {
+        timeZone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+        hour: '2-digit',
+        minute: '2-digit',
+        hourCycle: 'h23'
+    }).formatToParts(date);
+    const value = (type) => parts.find((part) => part.type === type)?.value ?? '';
+    return {
+        day: Number(value('day')),
+        month: Number(value('month')),
+        year: Number(value('year')),
+        hour: value('hour'),
+        minute: value('minute')
+    };
+}
+/** Render already-resolved calendar fields in one of the three date shapes. */
+function renderDate(day, month, year, format) {
+    const dd = String(day).padStart(2, '0');
+    if (format === 'numeric') {
+        return `${dd}/${String(month).padStart(2, '0')}/${year}`;
+    }
+    const name = (format === 'long' ? LONG_MONTHS : SHORT_MONTHS)[month - 1];
+    return `${dd} ${name} ${year}`;
+}
+/**
+ * Format a date for an Australian reader.
+ *
+ * A date-only value (`YYYY-MM-DD`) renders the day it NAMES, with no timezone
+ * conversion — a date is not an instant, and converting one is how a booking
+ * dated the 1st shows as the 31st. A value carrying a time is an instant, and
+ * is read in `timeZone` (`Australia/Brisbane` by default, not the browser's
+ * zone, so the same record reads the same on a laptop in another country).
+ *
+ * A string that will not parse is returned unchanged rather than hidden behind
+ * the fallback: an unexpected date format is worth seeing.
+ *
+ * @example
+ * formatDate('2024-12-19')                        // '19 Dec 2024'
+ * formatDate('2024-12-19', { format: 'long' })    // '19 December 2024'
+ * formatDate('2024-12-19', { format: 'numeric' }) // '19/12/2024'
+ * formatDate(null)                                // 'N/A'
+ */
+export function formatDate(value, options = {}) {
+    const { format = 'short', fallback = FALLBACK, timeZone = AU_TIME_ZONE } = options;
+    if (value === null || value === undefined)
+        return fallback;
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed === '')
+            return fallback;
+        const dateOnly = DATE_ONLY.exec(trimmed);
+        if (dateOnly) {
+            const year = Number(dateOnly[1]);
+            const month = Number(dateOnly[2]);
+            const day = Number(dateOnly[3]);
+            // A well-shaped but impossible date (2024-13-45) is returned as sent.
+            if (month < 1 || month > 12 || day < 1 || day > 31)
+                return trimmed;
+            return renderDate(day, month, year, format);
+        }
+        const parsed = parseApiDate(trimmed);
+        if (Number.isNaN(parsed.getTime()))
+            return trimmed;
+        const parts = zonedParts(parsed, timeZone);
+        return renderDate(parts.day, parts.month, parts.year, format);
+    }
+    if (Number.isNaN(value.getTime()))
+        return fallback;
+    const parts = zonedParts(value, timeZone);
+    return renderDate(parts.day, parts.month, parts.year, format);
+}
+/**
+ * Format a timestamp as a date and a 24-hour time: `19 Dec 2024, 14:05`.
+ *
+ * 24 hours, not `2:05 pm`: it is unambiguous and it aligns in a column, which
+ * is where a timestamp almost always sits.
+ *
+ * @example
+ * formatDateTime('2024-12-19T04:05:00')                   // '19 Dec 2024, 14:05'
+ * formatDateTime('2024-12-19T04:05:00Z', { format: 'numeric' }) // '19/12/2024, 14:05'
+ * formatDateTime(null)                                    // 'N/A'
+ */
+export function formatDateTime(value, options = {}) {
+    const { format = 'short', fallback = FALLBACK, timeZone = AU_TIME_ZONE } = options;
+    if (value === null || value === undefined)
+        return fallback;
+    let instant;
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (trimmed === '')
+            return fallback;
+        instant = parseApiDate(trimmed);
+        if (Number.isNaN(instant.getTime()))
+            return trimmed;
+    }
+    else {
+        instant = value;
+        if (Number.isNaN(instant.getTime()))
+            return fallback;
+    }
+    const parts = zonedParts(instant, timeZone);
+    const date = renderDate(parts.day, parts.month, parts.year, format);
+    return `${date}, ${parts.hour}:${parts.minute}`;
+}

package/dist/styles.css

@@ -198,7 +198,16 @@
 	--color-secondary: var(--secondary, var(--ds-color-surface-1));
 	--color-secondary-foreground: var(--secondary-foreground, var(--ds-color-foreground));
 	--color-muted: var(--muted, var(--ds-color-surface-1));
-	--color-accent: var(--accent, var(--ds-color-surface-2));
+	/* A SELECTION tint, not a surface rung (design-system#24). It was
+	   --ds-color-surface-2 — the same rung --color-card resolves to — which made
+	   `hover:bg-accent/50` on a card a no-op BY CONSTRUCTION: mixing a colour at
+	   any opacity over a ground it is identical to cannot change a pixel. It also
+	   left the menu/select/command highlight, the only thing this package's own
+	   components use `bg-accent` for, at 1.03:1 against the popover it sits on in
+	   light mode. A translucent tint of the accent composites over whatever
+	   ground it lands on, so one value serves both, and it is the idiom this
+	   package already ships for the SearchResults match highlight. */
+	--color-accent: var(--accent, color-mix(in oklch, var(--ds-color-primary) 12%, transparent));
 	--color-accent-foreground: var(--accent-foreground, var(--ds-color-foreground));
 	--color-input: var(--input, var(--ds-color-border));
 
@@ -788,22 +797,187 @@
 	   the measure rather than outside it. That is the same arithmetic as the
 	   `mx-auto max-w-4xl px-6` idiom this replaces, and keeping it means one
 	   element rather than a second wrapper nobody asked for. */
-	.ds-shell-measure {
-		margin-inline: auto;
-	}
-
+	/* Two classes, because the MEASURE and the CENTRING are two decisions and
+	   only the shell's content box wants both (design-system#22).
+
+	   `.ds-measure` caps the width and nothing else. It is for a block INSIDE a
+	   page — the paragraph of explanatory prose on a route legitimately set to
+	   `wide`, which would otherwise inherit a 120rem measure and run to ~123
+	   characters a line. `.ds-shell-measure` is that plus `margin-inline: auto`,
+	   which is right for the content box and wrong for a block within a page:
+	   applied to a set of left-anchored paragraphs it indented them ~207px away
+	   from their own label, measured in a consumer and reverted.
+
+	   Same attribute, same custom properties, so a block retunes with the shell
+	   rather than drifting from it. That is the whole point: the alternative an
+	   app reaches for is a local `max-w-prose` or `max-w-[72ch]`, which is a
+	   number typed once that never hears about a retune — four apps had written
+	   ten of them between them, and not one matched this package's own 72ch. */
+	.ds-measure[data-measure='prose'],
 	.ds-shell-measure[data-measure='prose'] {
 		max-width: var(--ds-shell-measure-prose);
 	}
 
+	.ds-measure[data-measure='page'],
 	.ds-shell-measure[data-measure='page'] {
 		max-width: var(--ds-shell-measure-page);
 	}
 
+	.ds-measure[data-measure='wide'],
 	.ds-shell-measure[data-measure='wide'] {
 		max-width: var(--ds-shell-measure-wide);
 	}
 
+	.ds-shell-measure {
+		margin-inline: auto;
+	}
+
+	/* ── The prose face (design-system#32) ────────────────────────────────────
+	   Styling for HTML the app did NOT author — rendered markdown, an extracted
+	   document body, a description field that arrives as rich text.
+
+	   Three consumers had built one of these, by three different mechanisms: a
+	   hand-written token-based block, the Tailwind typography plugin, and a
+	   second hand-written block that one of them had already duplicated inside
+	   itself. Every consumer that renders a document body would otherwise derive
+	   it a fourth time, and typography degrades worse than most things when it
+	   is re-derived per app.
+
+	   The package styles it and does NOT render it: sanitising untrusted HTML is
+	   a security boundary, and a package cannot see the inputs the boundary is
+	   protecting. The app owns the markdown-to-HTML seam and hands the result in.
+
+	   It carries no measure. A reading measure and a reading face are two
+	   decisions, and an app composes them:
+
+	       <div class="ds-prose ds-measure" data-measure="prose">…</div>
+
+	   Nothing here reaches for a colour or a length that is not a --ds-* token,
+	   so a palette or a retune moves the whole face with it. */
+	.ds-prose {
+		color: var(--ds-color-foreground);
+		line-height: 1.7;
+	}
+
+	.ds-prose h1,
+	.ds-prose h2,
+	.ds-prose h3,
+	.ds-prose h4 {
+		font-family: var(--ds-font-display);
+		font-weight: 600;
+		line-height: 1.25;
+		margin-block: var(--ds-spacing-lg) var(--ds-spacing-sm);
+	}
+
+	/* `em` rather than the type scale: these headings sit INSIDE a document, so
+	   they are relative to the body copy around them, not to the page's own
+	   heading ramp. An <h1> in rendered content is not the page's <h1>. */
+	.ds-prose h1 {
+		font-size: 1.5em;
+	}
+
+	.ds-prose h2 {
+		font-size: 1.25em;
+	}
+
+	.ds-prose h3,
+	.ds-prose h4 {
+		font-size: 1.1em;
+	}
+
+	.ds-prose p,
+	.ds-prose ul,
+	.ds-prose ol,
+	.ds-prose blockquote {
+		margin-block: var(--ds-spacing-sm);
+	}
+
+	.ds-prose ul,
+	.ds-prose ol {
+		padding-inline-start: var(--ds-spacing-lg);
+	}
+
+	/* Restored explicitly: the preflight reset strips list markers, and rendered
+	   content is the one place a bullet carries meaning. */
+	.ds-prose ul {
+		list-style: disc;
+	}
+
+	.ds-prose ol {
+		list-style: decimal;
+	}
+
+	.ds-prose a {
+		color: var(--ds-color-primary);
+		text-decoration: underline;
+		text-underline-offset: 2px;
+	}
+
+	.ds-prose strong {
+		font-weight: 600;
+	}
+
+	.ds-prose code {
+		font-family: var(--ds-font-code);
+		font-size: 0.9em;
+	}
+
+	.ds-prose pre {
+		background: var(--ds-color-surface-1);
+		border: 1px solid var(--ds-color-border);
+		border-radius: var(--ds-radius-sm);
+		overflow-x: auto;
+		padding: var(--ds-spacing-sm);
+	}
+
+	.ds-prose blockquote {
+		border-inline-start: 2px solid var(--ds-color-border-strong);
+		color: var(--ds-color-muted-foreground);
+		padding-inline-start: var(--ds-spacing-sm);
+	}
+
+	.ds-prose hr {
+		border: 0;
+		border-block-start: 1px solid var(--ds-color-border);
+		margin-block: var(--ds-spacing-lg);
+	}
+
+	/* A table in an extracted document is routinely wider than the measure around
+	   it. It scrolls in its OWN box rather than pushing the page sideways — the
+	   same rule the library surfaces learned at 390px. */
+	.ds-prose table {
+		border-collapse: collapse;
+		display: block;
+		font-size: 0.9em;
+		margin-block: var(--ds-spacing-md);
+		max-width: 100%;
+		overflow-x: auto;
+	}
+
+	.ds-prose th,
+	.ds-prose td {
+		border: 1px solid var(--ds-color-border);
+		padding: var(--ds-spacing-xs) var(--ds-spacing-sm);
+		text-align: start;
+	}
+
+	.ds-prose th {
+		color: var(--ds-color-muted-foreground);
+		font-weight: 600;
+	}
+
+	/* A figure in a document is evidence, so it gets the surface and border a
+	   plate deserves, and never exceeds its column. */
+	.ds-prose img {
+		background: var(--ds-color-surface-2);
+		border: 1px solid var(--ds-color-border);
+		border-radius: var(--ds-radius-sm);
+		display: block;
+		height: auto;
+		margin-block: var(--ds-spacing-md);
+		max-width: 100%;
+	}
+
 	/* The content texture: the house atmosphere, painted once by the shell on its
 	   own scrolling content region.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poodle64/ui",
-  "version": "2026.8.14",
+  "version": "2026.8.17",
   "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",
@@ -20,6 +20,10 @@
       "types": "./dist/utils.d.ts",
       "svelte": "./dist/utils.js"
     },
+    "./format": {
+      "types": "./dist/format.d.ts",
+      "svelte": "./dist/format.js"
+    },
     "./*": {
       "types": "./dist/components/ui/*/index.d.ts",
       "svelte": "./dist/components/ui/*/index.js"
@@ -27,9 +31,11 @@
   },
   "peerDependencies": {
     "bits-ui": "^2.18.1",
+    "formsnap": "^2.0.1",
     "mode-watcher": "^1.1.0",
     "svelte": "^5.33.0",
-    "svelte-sonner": "^1.1.1"
+    "svelte-sonner": "^1.1.1",
+    "sveltekit-superforms": "^2.30.0"
   },
   "peerDependenciesMeta": {
     "mode-watcher": {
@@ -37,6 +43,12 @@
     },
     "svelte-sonner": {
       "optional": true
+    },
+    "formsnap": {
+      "optional": true
+    },
+    "sveltekit-superforms": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -58,6 +70,7 @@
     "@testing-library/svelte": "^5.4.2",
     "@types/node": "^22.20.1",
     "bits-ui": "^2.18.1",
+    "formsnap": "^2.0.1",
     "jsdom": "^29.1.1",
     "mode-watcher": "^1.1.0",
     "playwright": "^1.62.0",
@@ -65,6 +78,7 @@
     "svelte": "^5.56.2",
     "svelte-check": "^4.6.0",
     "svelte-sonner": "^1.1.1",
+    "sveltekit-superforms": "^2.30.2",
     "tailwindcss": "^4.3.2",
     "typescript": "^6.0.3",
     "vite": "^8.0.16",