@poodle64/ui 2026.8.15 → 2026.8.17

package/dist/components/ui/form/form-label.svelte

@@ -0,0 +1,25 @@
+<script lang="ts">
+	import * as FormPrimitive from 'formsnap';
+	import { Label } from '../label/index.js';
+	import { cn } from '../../../utils.js';
+	import type { WithoutChild } from '../../../utils.js';
+
+	let {
+		ref = $bindable(null),
+		children,
+		class: className,
+		...restProps
+	}: WithoutChild<FormPrimitive.LabelProps> = $props();
+</script>
+
+<FormPrimitive.Label {...restProps} bind:ref>
+	{#snippet child({ props })}
+		<Label
+			{...props}
+			data-slot="form-label"
+			class={cn('data-[fs-error]:text-destructive', className)}
+		>
+			{@render children?.()}
+		</Label>
+	{/snippet}
+</FormPrimitive.Label>

package/dist/components/ui/form/form-label.svelte.d.ts

@@ -0,0 +1,4 @@
+import * as FormPrimitive from 'formsnap';
+declare const FormLabel: import("svelte").Component<Omit<FormPrimitive.LabelProps, "child">, {}, "ref">;
+type FormLabel = ReturnType<typeof FormLabel>;
+export default FormLabel;

package/dist/components/ui/form/form-legend.svelte

@@ -0,0 +1,17 @@
+<script lang="ts">
+	import * as FormPrimitive from 'formsnap';
+	import { cn } from '../../../utils.js';
+	import type { WithoutChild } from '../../../utils.js';
+
+	let {
+		ref = $bindable(null),
+		class: className,
+		...restProps
+	}: WithoutChild<FormPrimitive.LegendProps> = $props();
+</script>
+
+<FormPrimitive.Legend
+	bind:ref
+	class={cn('data-[fs-error]:text-destructive text-sm leading-none font-medium', className)}
+	{...restProps}
+/>

package/dist/components/ui/form/form-legend.svelte.d.ts

@@ -0,0 +1,4 @@
+import * as FormPrimitive from 'formsnap';
+declare const FormLegend: import("svelte").Component<Omit<FormPrimitive.LegendProps, "child">, {}, "ref">;
+type FormLegend = ReturnType<typeof FormLegend>;
+export default FormLegend;

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

@@ -0,0 +1,11 @@
+import * as FormPrimitive from 'formsnap';
+import Description from './form-description.svelte';
+import Label from './form-label.svelte';
+import FieldErrors from './form-field-errors.svelte';
+import Field from './form-field.svelte';
+import Fieldset from './form-fieldset.svelte';
+import Legend from './form-legend.svelte';
+import ElementField from './form-element-field.svelte';
+import Button from './form-button.svelte';
+declare const Control: import("svelte").Component<FormPrimitive.ControlProps, {}, "">;
+export { Field, Control, Label, Button, FieldErrors, Description, Fieldset, Legend, ElementField, Field as FormField, Control as FormControl, Description as FormDescription, Label as FormLabel, FieldErrors as FormFieldErrors, Fieldset as FormFieldset, Legend as FormLegend, ElementField as FormElementField, Button as FormButton };

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

@@ -0,0 +1,13 @@
+import * as FormPrimitive from 'formsnap';
+import Description from './form-description.svelte';
+import Label from './form-label.svelte';
+import FieldErrors from './form-field-errors.svelte';
+import Field from './form-field.svelte';
+import Fieldset from './form-fieldset.svelte';
+import Legend from './form-legend.svelte';
+import ElementField from './form-element-field.svelte';
+import Button from './form-button.svelte';
+const Control = FormPrimitive.Control;
+export { Field, Control, Label, Button, FieldErrors, Description, Fieldset, Legend, ElementField, 
+//
+Field as FormField, Control as FormControl, Description as FormDescription, Label as FormLabel, FieldErrors as FormFieldErrors, Fieldset as FormFieldset, Legend as FormLegend, ElementField as FormElementField, Button as FormButton };

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" | "hidden" | "color" | "submit" | "reset" | "button" | "search" | "checkbox" | "radio" | (string & {}) | "text" | "tel" | "url" | "email" | "date" | "time" | "image" | "datetime-local" | "month" | "password" | "range" | "week";
+    type?: "number" | "month" | "hidden" | "color" | "submit" | "reset" | "button" | "search" | "checkbox" | "radio" | (string & {}) | "text" | "tel" | "url" | "email" | "date" | "time" | "image" | "datetime-local" | "password" | "range" | "week";
     files?: undefined;
 })) & {
     ref?: HTMLElement | null | undefined;

package/dist/components/ui/page-header/page-header.svelte

@@ -27,13 +27,22 @@
 	 * of routed links, and a package with no SvelteKit runtime of its own cannot
 	 * own those (the same reasoning that makes AppShell take `currentPath` as a
 	 * prop rather than importing `$app/state`).
+	 *
+	 * `icon` and `meta` are snippets for the same reason and earn their place the
+	 * same way `breadcrumbs` did: three apps had hand-rolled the meta row and two
+	 * the icon square, one of them across 38 of its 49 page headers in a full
+	 * local reimplementation of this component. The app supplies the GLYPH and
+	 * the ITEMS; the package owns the treatment — the tinted square, its size,
+	 * and the row's spacing — because the treatment is the half that drifts.
 	 */
 	let {
 		eyebrow,
 		breadcrumbs,
+		icon,
 		title,
 		subtitle,
 		info,
+		meta,
 		actions,
 		ref = $bindable(null),
 		class: className,
@@ -43,10 +52,14 @@
 		eyebrow?: string;
 		/** The trail above the title — the app's own routed links. */
 		breadcrumbs?: Snippet;
+		/** The glyph alone. The tinted square around it is this component's. */
+		icon?: Snippet;
 		/** Omit for a header that is a breadcrumb bar with actions. */
 		title?: string;
 		subtitle?: string;
 		info?: string;
+		/** Facts about the page, under the title: badges, dates, a status. */
+		meta?: Snippet;
 		actions?: Snippet;
 	} = $props();
 </script>
@@ -56,43 +69,67 @@
 	class={cn('mb-6 flex flex-wrap items-start justify-between gap-4', className)}
 	{...restProps}
 >
-	<div class="min-w-0">
-		{#if breadcrumbs}
-			<div class="text-muted-foreground mb-1.5 flex min-w-0 items-center text-sm">
-				{@render breadcrumbs()}
-			</div>
-		{/if}
-		{#if eyebrow}
-			<div class="text-primary text-2xs tracking-eyebrow mb-1 font-medium uppercase">
-				{eyebrow}
-			</div>
+	<div class="flex min-w-0 items-start gap-3">
+		{#if icon}
+			<!-- aria-hidden: the glyph restates the title beside it, so a reader
+			     already has the fact. `shrink-0` so it never collapses when the
+			     title is long, and the square is the package's rather than the
+			     app's precisely so two apps cannot pick two sizes for it. -->
+			<span
+				class="bg-primary/10 text-primary mt-0.5 inline-flex size-10 shrink-0 items-center justify-center rounded-lg [&_svg]:size-5"
+				aria-hidden="true"
+			>
+				{@render icon()}
+			</span>
 		{/if}
-		{#if title}
-			<div class="flex items-center gap-2">
-				<h1 class="font-display text-display leading-tight font-semibold tracking-[-0.02em]">
-					{title}
-				</h1>
-				{#if info}
+		<div class="min-w-0">
+			{#if breadcrumbs}
+				<div class="text-muted-foreground mb-1.5 flex min-w-0 items-center text-sm">
+					{@render breadcrumbs()}
+				</div>
+			{/if}
+			{#if eyebrow}
+				<div class="text-primary text-2xs tracking-eyebrow mb-1 font-medium uppercase">
+					{eyebrow}
+				</div>
+			{/if}
+			{#if title}
+				<div class="flex items-center gap-2">
+					<h1 class="font-display text-display leading-tight font-semibold tracking-[-0.02em]">
+						{title}
+					</h1>
+					{#if info}
+						<InfoTip
+							text={info}
+							class="text-muted-foreground/50 hover:text-muted-foreground mt-0.5 size-4 transition-colors"
+						/>
+					{/if}
+				</div>
+			{:else if info}
+				<!-- Title-less, but the page still has something to explain. The tip
+				     keeps a row of its own rather than being dropped along with the
+				     heading it usually sits beside. -->
+				<div class="flex items-center gap-2">
 					<InfoTip
 						text={info}
-						class="text-muted-foreground/50 hover:text-muted-foreground mt-0.5 size-4 transition-colors"
+						class="text-muted-foreground/50 hover:text-muted-foreground size-4 transition-colors"
 					/>
-				{/if}
-			</div>
-		{:else if info}
-			<!-- Title-less, but the page still has something to explain. The tip
-			     keeps a row of its own rather than being dropped along with the
-			     heading it usually sits beside. -->
-			<div class="flex items-center gap-2">
-				<InfoTip
-					text={info}
-					class="text-muted-foreground/50 hover:text-muted-foreground size-4 transition-colors"
-				/>
-			</div>
-		{/if}
-		{#if subtitle}
-			<p class="text-muted-foreground mt-1.5 line-clamp-1 max-w-4xl text-sm">{subtitle}</p>
-		{/if}
+				</div>
+			{/if}
+			{#if subtitle}
+				<p class="text-muted-foreground mt-1.5 line-clamp-1 max-w-4xl text-sm">{subtitle}</p>
+			{/if}
+			{#if meta}
+				<!-- `min-w-0` for the reason the actions row carries it: this is a flex
+				     item and would otherwise floor at its own min-content width, which
+				     wrapping cannot get below. -->
+				<div
+					class="text-muted-foreground mt-2 flex min-w-0 flex-wrap items-center gap-x-4 gap-y-1.5 text-xs"
+				>
+					{@render meta()}
+				</div>
+			{/if}
+		</div>
 	</div>
 	{#if actions}
 		<!--

package/dist/components/ui/page-header/page-header.svelte.d.ts

@@ -6,10 +6,14 @@ type $$ComponentProps = WithElementRef<HTMLAttributes<HTMLDivElement>> & {
     eyebrow?: string;
     /** The trail above the title — the app's own routed links. */
     breadcrumbs?: Snippet;
+    /** The glyph alone. The tinted square around it is this component's. */
+    icon?: Snippet;
     /** Omit for a header that is a breadcrumb bar with actions. */
     title?: string;
     subtitle?: string;
     info?: string;
+    /** Facts about the page, under the title: badges, dates, a status. */
+    meta?: Snippet;
     actions?: Snippet;
 };
 declare const PageHeader: import("svelte").Component<$$ComponentProps, {}, "ref">;

package/dist/format.d.ts

@@ -0,0 +1,222 @@
+/**
+ * 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 declare const AU_LOCALE = "en-AU";
+/** The one timezone the household's records are kept in. */
+export declare const AU_TIME_ZONE = "Australia/Brisbane";
+export interface CurrencyOptions {
+    /**
+     * Fraction digits. Defaults to 2: dropping cents is a loss of fidelity the
+     * caller should have to ask for, not the default that quietly rounds
+     * $1,234.56 up to $1,235. Pass `0` for a dashboard figure.
+     */
+    decimals?: number;
+    /** Rendered when the value is null, undefined, empty or not a number. */
+    fallback?: string;
+    /**
+     * ISO 4217 code. Defaults to AUD, which renders as a bare `$`; a non-AUD
+     * currency renders disambiguated (`USD 1,234.56`) rather than as another
+     * `$`, because an app that holds a foreign account is exactly the app that
+     * must not confuse the two.
+     */
+    currency?: string;
+}
+/**
+ * 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 declare function formatCurrency(value: string | number | null | undefined, options?: CurrencyOptions): string;
+/**
+ * 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 declare function formatCurrencyFromCents(cents: number | null | undefined, options?: CurrencyOptions): string;
+/** Convert a dollar value to whole cents. */
+export declare function dollarsToCents(dollars: number): number;
+/**
+ * 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 declare function compactCurrency(value: number | null | undefined, options?: {
+    currency?: string;
+    fallback?: string;
+}): string;
+/**
+ * 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 declare function formatCurrencyString(value: string | null | undefined, options?: {
+    fallback?: string;
+}): string;
+/**
+ * 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 declare function isNegativeMoney(value: string | number | null | undefined): boolean;
+/**
+ * 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 declare function formatNumber(value: number | string | null | undefined, options?: {
+    decimals?: number;
+    fallback?: string;
+}): string;
+/**
+ * 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 declare function formatPercentage(value: number | string | null | undefined, options?: {
+    decimals?: number;
+    fallback?: string;
+}): string;
+/**
+ * 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 declare function formatRatioAsPercentage(value: number | string | null | undefined, options?: {
+    decimals?: number;
+    fallback?: string;
+}): string;
+/** `19 Dec 2024`, `19 December 2024`, or `19/12/2024`. */
+export type DateFormat = 'short' | 'long' | 'numeric';
+export interface DateOptions {
+    format?: DateFormat;
+    /** Rendered when the value is null, undefined or empty. */
+    fallback?: string;
+    /** IANA zone a timestamp is read in. Defaults to `Australia/Brisbane`. */
+    timeZone?: string;
+}
+/**
+ * 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 declare function parseApiDate(iso: string): Date;
+/**
+ * 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 declare function formatDate(value: string | Date | null | undefined, options?: DateOptions): string;
+/**
+ * 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 declare function formatDateTime(value: string | Date | null | undefined, options?: DateOptions): string;