@ripple-ui/svelte 0.0.0-stage → 0.8.2

package/dist/widgets/data-kit/StageRail.svelte

@@ -0,0 +1,166 @@
+<!--
+  widgets/data-kit/StageRail.svelte — the stage indicator for multistep data
+  widgets (menu-order, booking; design doc 2026-10-09 §3.3, §3.4). It wears
+  intent/ChainProgress.svelte's stepper look (muted pills, a numbered circle,
+  1px connectors) and adds what a
+  widget's own stages need: every stage named up front, done stages marked
+  with a check, and done stages clickable through `onselect` to go back. The
+  current stage keeps the muted pill with full-strength ink and an accent
+  numbered circle, so the rail reads as progress, never as a row of filter
+  pills (the accent fill stays free for a widget's own active control).
+  `disabled` keeps it inert until card.final. Below 360px of container width
+  done stages drop their label (the check and aria-label carry it) and the
+  chips tighten, so the steps ahead stay named on a phone.
+-->
+<script lang="ts">
+	import Check from '@lucide/svelte/icons/check';
+	import { plain } from './format.js';
+
+	interface Props {
+		stages: readonly string[];
+		current: number;
+		onselect?: (index: number) => void;
+		disabled?: boolean;
+		class?: string;
+	}
+
+	let { stages, current, onselect, disabled = false, class: className }: Props = $props();
+
+	const names = $derived((Array.isArray(stages) ? stages : []).map((s) => plain(s)));
+	const at = $derived(Math.min(Math.max(Math.trunc(Number(current) || 0), 0), Math.max(names.length - 1, 0)));
+</script>
+
+<nav class={['stage-rail', className]} aria-label="Progress">
+	<ol class="stage-rail__list">
+		{#each names as name, i}
+			{@const step = i < at ? 'done' : i === at ? 'current' : 'todo'}
+			<li class="stage-rail__item" data-state={step} aria-current={step === 'current' ? 'step' : undefined}>
+				{#if step === 'done' && onselect}
+					<button type="button" class="stage-rail__chip" aria-label={name} {disabled} onclick={() => onselect(i)}>
+						<span class="stage-rail__num"><Check size={10} strokeWidth={3} aria-hidden="true" /></span>
+						<span class="stage-rail__label">{name}</span>
+					</button>
+				{:else}
+					<span class="stage-rail__chip">
+						<span class="stage-rail__num">
+							{#if step === 'done'}<Check size={10} strokeWidth={3} aria-hidden="true" />{:else}{i + 1}{/if}
+						</span>
+						<span class="stage-rail__label">{name}</span>
+					</span>
+				{/if}
+			</li>
+		{/each}
+	</ol>
+</nav>
+
+<style>
+	.stage-rail {
+		container-type: inline-size;
+	}
+
+	.stage-rail__list {
+		display: flex;
+		align-items: center;
+		gap: 0.25rem;
+		margin: 0;
+		padding: 0;
+		list-style: none;
+		overflow-x: auto;
+		scrollbar-width: none;
+	}
+
+	.stage-rail__list::-webkit-scrollbar {
+		display: none;
+	}
+
+	.stage-rail__item {
+		display: flex;
+		align-items: center;
+		gap: 0.25rem;
+		flex-shrink: 0;
+	}
+
+	/* ChainProgress's connector, drawn before every stage but the first. */
+	.stage-rail__item + .stage-rail__item::before {
+		content: '';
+		width: 0.5rem;
+		height: 1px;
+		background: var(--ripple-border);
+	}
+
+	.stage-rail__chip {
+		display: inline-flex;
+		align-items: center;
+		gap: 0.35rem;
+		padding: 0.2rem 0.55rem;
+		border: 0;
+		border-radius: 9999px;
+		font: inherit;
+		font-size: 0.72rem;
+		font-weight: 500;
+		background: var(--ripple-muted);
+		color: var(--ripple-muted-foreground);
+		transition: background-color 160ms var(--ripple-ease-out);
+	}
+
+	button.stage-rail__chip {
+		cursor: pointer;
+	}
+
+	button.stage-rail__chip:hover:not(:disabled) {
+		background: color-mix(in oklch, var(--ripple-accent) 12%, var(--ripple-muted));
+	}
+
+	button.stage-rail__chip:focus-visible {
+		outline: 2px solid var(--ripple-ring);
+		outline-offset: 2px;
+	}
+
+	button.stage-rail__chip:disabled {
+		cursor: default;
+	}
+
+	[data-state='current'] .stage-rail__chip {
+		color: var(--ripple-surface-foreground);
+		font-weight: 600;
+	}
+
+	.stage-rail__num {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		width: 1rem;
+		height: 1rem;
+		border-radius: 9999px;
+		font-size: 0.62rem;
+		font-weight: 600;
+		font-variant-numeric: tabular-nums;
+		background: color-mix(in oklch, var(--ripple-accent) 12%, transparent);
+	}
+
+	[data-state='current'] .stage-rail__num {
+		background: var(--ripple-accent);
+		color: var(--ripple-accent-foreground);
+	}
+
+	.stage-rail__label {
+		max-width: 7rem;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+
+	@container (max-width: 359px) {
+		.stage-rail__item[data-state='done'] .stage-rail__label {
+			display: none;
+		}
+
+		.stage-rail__chip {
+			padding-inline: 0.4rem;
+		}
+
+		.stage-rail__item + .stage-rail__item::before {
+			width: 0.25rem;
+		}
+	}
+</style>

package/dist/widgets/data-kit/StageRail.svelte.d.ts

@@ -0,0 +1,10 @@
+interface Props {
+    stages: readonly string[];
+    current: number;
+    onselect?: (index: number) => void;
+    disabled?: boolean;
+    class?: string;
+}
+declare const StageRail: import("svelte").Component<Props, {}, "">;
+type StageRail = ReturnType<typeof StageRail>;
+export default StageRail;

package/dist/widgets/data-kit/StatChip.svelte

@@ -0,0 +1,67 @@
+<!--
+  widgets/data-kit/StatChip.svelte — one stat as an inset tile: label, value
+  with its unit, then status and trend (design doc 2026-10-09 §2.3, the Stat
+  type in §3). Value, judgement and direction in one tile. A number renders
+  through num() (non-finite is 'n/a'); a string renders as written, so money
+  arrives pre-formatted with money(). A trend is coloured only when `good`
+  says which way is good; otherwise it is neutral ink. An inset border edge
+  keeps the tile apart from a card of nearly the same tone (light theme).
+  `statusLabel` replaces the status's default word with a domain word
+  ("Goal met", "Under").
+-->
+<script lang="ts">
+	import type { LucideIcon } from '@lucide/svelte';
+	import ArrowUp from '@lucide/svelte/icons/arrow-up';
+	import ArrowDown from '@lucide/svelte/icons/arrow-down';
+	import Minus from '@lucide/svelte/icons/minus';
+	import { num, plain } from './format.js';
+	import StatusPill from './StatusPill.svelte';
+	import type { Status, Trend } from './types.js';
+
+	interface Props {
+		label?: string;
+		value?: number | string | null;
+		unit?: string;
+		status?: Status;
+		/** The pill's word in place of the status default ("Goal met"). */
+		statusLabel?: string;
+		trend?: Trend;
+		icon?: LucideIcon;
+		class?: string;
+	}
+
+	let { label, value, unit, status, statusLabel, trend, icon: Icon, class: className }: Props = $props();
+
+	const shown = $derived(typeof value === 'string' && value.trim() ? plain(value) : num(value));
+	const dir = $derived(trend?.dir === 'up' || trend?.dir === 'down' ? trend.dir : 'flat');
+	const tone = $derived(
+		dir === 'flat' || !trend?.good
+			? 'text-ripple-muted-foreground'
+			: dir === trend.good
+				? 'text-ripple-success-text'
+				: 'text-ripple-error-text'
+	);
+	const TrendIcon = $derived(dir === 'up' ? ArrowUp : dir === 'down' ? ArrowDown : Minus);
+</script>
+
+<div class={['flex min-w-0 flex-col gap-1 rounded-md bg-ripple-muted px-3 py-2.5 ring-1 ring-ripple-border ring-inset', className]}>
+	<div class="flex min-w-0 items-center gap-1.5 text-ripple-muted-foreground">
+		{#if Icon}<Icon size={14} strokeWidth={1.75} aria-hidden="true" class="shrink-0" />{/if}
+		<span class="truncate text-footnote">{plain(label)}</span>
+	</div>
+	<div class="flex min-w-0 items-baseline gap-1">
+		<span class="truncate text-headline tabular-nums text-ripple-surface-foreground">{shown}</span>
+		{#if unit}<span class="text-footnote text-ripple-muted-foreground">{plain(unit)}</span>{/if}
+	</div>
+	{#if status || trend}
+		<div class="flex flex-wrap items-center gap-1.5">
+			{#if status}<StatusPill {status} label={statusLabel} />{/if}
+			{#if trend}
+				<span class={['inline-flex items-center gap-0.5 text-footnote tabular-nums', tone]} data-trend={dir}>
+					<TrendIcon size={12} strokeWidth={2} aria-hidden="true" />
+					{#if trend.text}{plain(trend.text)}{:else}<span class="sr-only">{dir}</span>{/if}
+				</span>
+			{/if}
+		</div>
+	{/if}
+</div>

package/dist/widgets/data-kit/StatChip.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { LucideIcon } from '@lucide/svelte';
+import type { Status, Trend } from './types.js';
+interface Props {
+    label?: string;
+    value?: number | string | null;
+    unit?: string;
+    status?: Status;
+    /** The pill's word in place of the status default ("Goal met"). */
+    statusLabel?: string;
+    trend?: Trend;
+    icon?: LucideIcon;
+    class?: string;
+}
+declare const StatChip: import("svelte").Component<Props, {}, "">;
+type StatChip = ReturnType<typeof StatChip>;
+export default StatChip;

package/dist/widgets/data-kit/StatusPill.svelte

@@ -0,0 +1,37 @@
+<!--
+  widgets/data-kit/StatusPill.svelte — a status as icon + word on a 12% tint
+  (design doc 2026-10-09 §2.2). Never colour alone: the icon and the word
+  always render; `label` is the domain word ("elevated", "Full") and the
+  status's default word stands in when there is none. Unknown status is
+  neutral. Internal kit part, not a registered widget.
+-->
+<script lang="ts">
+	import { plain } from './format.js';
+	import { STATUS_CLASS, STATUS_ICONS, STATUS_WORDS, toStatus } from './status.js';
+	import type { Status } from './types.js';
+
+	interface Props {
+		status?: Status | (string & {});
+		label?: string;
+		class?: string;
+	}
+
+	let { status, label, class: className }: Props = $props();
+
+	const s = $derived(toStatus(status));
+	const Icon = $derived(STATUS_ICONS[s]);
+	const text = $derived(plain(label) || STATUS_WORDS[s]);
+</script>
+
+<span
+	class={[
+		'inline-flex max-w-full items-center gap-1 rounded-md px-1.5 py-0.5 text-subheadline font-medium whitespace-nowrap',
+		STATUS_CLASS[s].tint,
+		STATUS_CLASS[s].text,
+		className
+	]}
+	data-status={s}
+>
+	<Icon size={12} strokeWidth={2} aria-hidden="true" class="shrink-0" />
+	<span class="truncate">{text}</span>
+</span>

package/dist/widgets/data-kit/StatusPill.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { Status } from './types.js';
+interface Props {
+    status?: Status | (string & {});
+    label?: string;
+    class?: string;
+}
+declare const StatusPill: import("svelte").Component<Props, {}, "">;
+type StatusPill = ReturnType<typeof StatusPill>;
+export default StatusPill;

package/dist/widgets/data-kit/VerdictLine.svelte

@@ -0,0 +1,29 @@
+<!--
+  widgets/data-kit/VerdictLine.svelte — the answer up front (design doc
+  2026-10-09 §2.1), rendered first in every data widget: a status dot and the
+  model's one sentence. The widget never invents the sentence; with no text
+  this renders nothing and the widget shows its derived headline instead. The
+  dot is decoration; the status word is there for screen readers.
+-->
+<script lang="ts">
+	import { plain } from './format.js';
+	import { STATUS_CLASS, STATUS_WORDS, toStatus } from './status.js';
+	import type { Verdict } from './types.js';
+
+	interface Props {
+		verdict?: Verdict | null;
+		class?: string;
+	}
+
+	let { verdict, class: className }: Props = $props();
+
+	const text = $derived(plain(verdict?.text));
+	const s = $derived(toStatus(verdict?.status));
+</script>
+
+{#if text}
+	<p class={['flex items-start gap-2 text-body-emph text-ripple-surface-foreground', className]} data-status={s}>
+		<span class={['mt-[4px] size-2 shrink-0 rounded-full', STATUS_CLASS[s].fill]} aria-hidden="true"></span>
+		<span class="min-w-0 text-pretty"><span class="sr-only">{STATUS_WORDS[s]}: </span>{text}</span>
+	</p>
+{/if}

package/dist/widgets/data-kit/VerdictLine.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { Verdict } from './types.js';
+interface Props {
+    verdict?: Verdict | null;
+    class?: string;
+}
+declare const VerdictLine: import("svelte").Component<Props, {}, "">;
+type VerdictLine = ReturnType<typeof VerdictLine>;
+export default VerdictLine;

package/dist/widgets/data-kit/edit.d.ts

@@ -0,0 +1,14 @@
+/** A widget-side edit of a prop: the edited value and the value it was made from. */
+export interface Edit<T> {
+    from: string;
+    value: T;
+}
+/**
+ * Whether the edit still stands: `incoming` is the edit itself (assigned
+ * locally, or echoed by a bound parent) or the value the edit was made from
+ * (a host re-rendering the same spec re-sends the original). Anything else
+ * is new data, and the edit gives way.
+ */
+export declare function holds<T>(edit: Edit<T> | null, incoming: unknown): edit is Edit<T>;
+/** The next edit; a chain of edits stays anchored to the value the first one was made from. */
+export declare function nextEdit<T>(edit: Edit<T> | null, incoming: unknown, value: T): Edit<T>;

package/dist/widgets/data-kit/edit.js

@@ -0,0 +1,27 @@
+// widgets/data-kit/edit.ts — a widget's own edit of a prop the host also sends
+// (a meal swap, a ticked step, a rate slider). A host that re-renders the same
+// spec (say on a bound field's change) re-sends the original values for every
+// other prop; an Edit survives that re-send and gives way only to a genuinely
+// new value. A new value that happens to equal the original is
+// indistinguishable from a re-send, so the edit holds.
+const sig = (v) => {
+    try {
+        return JSON.stringify(v) ?? '';
+    }
+    catch {
+        return '';
+    }
+};
+/**
+ * Whether the edit still stands: `incoming` is the edit itself (assigned
+ * locally, or echoed by a bound parent) or the value the edit was made from
+ * (a host re-rendering the same spec re-sends the original). Anything else
+ * is new data, and the edit gives way.
+ */
+export function holds(edit, incoming) {
+    return edit !== null && (incoming === edit.value || sig(incoming) === edit.from);
+}
+/** The next edit; a chain of edits stays anchored to the value the first one was made from. */
+export function nextEdit(edit, incoming, value) {
+    return { from: holds(edit, incoming) ? edit.from : sig(incoming), value };
+}

package/dist/widgets/data-kit/format.d.ts

@@ -0,0 +1,53 @@
+/** A finite number from a number or a numeric string, else undefined. */
+export declare function finite(v: unknown): number | undefined;
+/** A percentage from 42, "42" or "42%", clamped to 0..100; anything else is undefined. */
+export declare function percent(v: unknown): number | undefined;
+/**
+ * A plain number for display; non-finite input renders 'n/a'. `sign: true`
+ * prints '+4' / '-4' / '0' for deltas; `compact: true` prints '12.8M'.
+ */
+export declare function num(v: unknown, opts?: {
+    locale?: string;
+    digits?: number;
+    sign?: boolean;
+    compact?: boolean;
+}): string;
+/** Sum of the finite values; anything else drops out instead of poisoning the total. */
+export declare function sum(values: unknown): number;
+/**
+ * Money through Intl. `currency` is ISO 4217 from the widget (default USD);
+ * a malformed code or locale falls back to USD instead of throwing a
+ * RangeError into the widget. `sign: true` prints '+$8.00' for deltas.
+ * `whole: true` drops the cents of a whole amount ('$1,890', still '$19.50'),
+ * the way pricing-table prints prices; bills and invoices keep the cents.
+ * `compact: true` prints '$45.2K' for a narrow tile.
+ */
+export declare function money(v: unknown, currency?: unknown, opts?: {
+    locale?: string;
+    sign?: boolean;
+    whole?: boolean;
+    compact?: boolean;
+}): string;
+/**
+ * Plain text from a prop: paired `**bold**` / `__bold__` markers and a leading
+ * `- ` per line are stripped, so a model's markdown habit never shows raw.
+ * There is no markdown renderer; long text belongs in structured `points[]`.
+ */
+export declare function plain(v: unknown): string;
+/** Sort key for an ISO date or datetime, else undefined. Never display it. */
+export declare function dateKey(v: unknown): number | undefined;
+/**
+ * A date as the reader should see it. Labels ("Next Tuesday", "Fri 16 Oct")
+ * come back as written; a valid ISO day is formatted from its own digits in
+ * UTC ("2026-10-16" → "Fri, Oct 16"); an impossible ISO day ("2026-02-31")
+ * comes back as written. Missing input is ''.
+ */
+export declare function dateLabel(v: unknown, locale?: string): string;
+/** A whole number inside the range; junk falls back to the default. Timers use it for seconds and minutes. */
+export declare function clampSec(v: unknown, r: {
+    min: number;
+    max: number;
+    fallback: number;
+}): number;
+/** A countdown in seconds as "0:40", "12:05", "25:00". */
+export declare function clock(sec: number): string;

package/dist/widgets/data-kit/format.js

@@ -0,0 +1,132 @@
+// widgets/data-kit/format.ts — the data-hygiene helpers every data widget
+// renders values through (design doc 2026-10-09 §2.8). Props are model output:
+// text carries markdown habits, numbers arrive as NaN or strings, a currency
+// code can be '$', a date can be "next Tuesday". Each helper returns a display
+// string (or a sortable number) and never throws, so a bad value shows as
+// 'n/a' or as written, never as an error box or "Invalid Date".
+//
+// Dates: dateLabel shows what the writer wrote. The one thing it formats is an
+// ISO calendar day (YYYY-MM-DD, optionally followed by a time), and it formats
+// that day's own digits in UTC, so no timezone can move it to the day before.
+// dateKey is for sorting only and accepts ISO strings only (V8 reads
+// "Fri 16 Oct" as the year 2001).
+import { asText } from '@ripple-ui/core';
+/** A finite number from a number or a numeric string, else undefined. */
+export function finite(v) {
+    const n = typeof v === 'string' && v.trim() !== '' ? Number(v) : v;
+    return typeof n === 'number' && Number.isFinite(n) ? n : undefined;
+}
+/** A percentage from 42, "42" or "42%", clamped to 0..100; anything else is undefined. */
+export function percent(v) {
+    const n = finite(typeof v === 'string' ? v.trim().replace(/%$/, '') : v);
+    return n === undefined ? undefined : Math.min(100, Math.max(0, n));
+}
+/**
+ * A plain number for display; non-finite input renders 'n/a'. `sign: true`
+ * prints '+4' / '-4' / '0' for deltas; `compact: true` prints '12.8M'.
+ */
+export function num(v, opts = {}) {
+    const n = finite(v);
+    if (n === undefined)
+        return 'n/a';
+    const o = {
+        maximumFractionDigits: opts.digits ?? (opts.compact ? 1 : 2),
+        signDisplay: opts.sign ? 'exceptZero' : 'auto',
+        ...(opts.compact ? { notation: 'compact' } : {})
+    };
+    try {
+        return new Intl.NumberFormat(opts.locale, o).format(n);
+    }
+    catch {
+        return String(n);
+    }
+}
+/** Sum of the finite values; anything else drops out instead of poisoning the total. */
+export function sum(values) {
+    let total = 0;
+    if (Array.isArray(values))
+        for (const v of values)
+            total += finite(v) ?? 0;
+    return total;
+}
+/**
+ * Money through Intl. `currency` is ISO 4217 from the widget (default USD);
+ * a malformed code or locale falls back to USD instead of throwing a
+ * RangeError into the widget. `sign: true` prints '+$8.00' for deltas.
+ * `whole: true` drops the cents of a whole amount ('$1,890', still '$19.50'),
+ * the way pricing-table prints prices; bills and invoices keep the cents.
+ * `compact: true` prints '$45.2K' for a narrow tile.
+ */
+export function money(v, currency = 'USD', opts = {}) {
+    const n = finite(v);
+    if (n === undefined)
+        return 'n/a';
+    const base = { style: 'currency', signDisplay: opts.sign ? 'exceptZero' : 'auto' };
+    if (opts.whole && Number.isInteger(n))
+        Object.assign(base, { minimumFractionDigits: 0, maximumFractionDigits: 0 });
+    if (opts.compact)
+        Object.assign(base, { notation: 'compact', minimumFractionDigits: 0, maximumFractionDigits: 1 });
+    const code = typeof currency === 'string' && currency.trim() ? currency.trim().toUpperCase() : 'USD';
+    try {
+        return new Intl.NumberFormat(opts.locale, { ...base, currency: code }).format(n);
+    }
+    catch {
+        return new Intl.NumberFormat(undefined, { ...base, currency: 'USD' }).format(n);
+    }
+}
+/**
+ * Plain text from a prop: paired `**bold**` / `__bold__` markers and a leading
+ * `- ` per line are stripped, so a model's markdown habit never shows raw.
+ * There is no markdown renderer; long text belongs in structured `points[]`.
+ */
+export function plain(v) {
+    return asText(v)
+        .replace(/\*\*([^*\s](?:[^*]*[^*\s])?)\*\*/g, '$1')
+        .replace(/__([^_\s](?:[^_]*[^_\s])?)__/g, '$1')
+        // Single *x* and _x_ emphasis, only at word edges: 2*3*4 and snake_case_names stay.
+        .replace(/(^|[^\w*])\*([^*\s](?:[^*]*[^*\s])?)\*(?![\w*])/g, '$1$2')
+        .replace(/(^|[^\w_])_([^_\s](?:[^_]*[^_\s])?)_(?![\w_])/g, '$1$2')
+        .replace(/^[ \t]*- +/gm, '')
+        .trim();
+}
+const ISO_DAY = /^(\d{4}-\d{2}-\d{2})(?:$|[T ])/;
+/** Sort key for an ISO date or datetime, else undefined. Never display it. */
+export function dateKey(v) {
+    if (typeof v !== 'string' || !ISO_DAY.test(v.trim()))
+        return undefined;
+    const t = Date.parse(v.trim());
+    return Number.isNaN(t) ? undefined : t;
+}
+/**
+ * A date as the reader should see it. Labels ("Next Tuesday", "Fri 16 Oct")
+ * come back as written; a valid ISO day is formatted from its own digits in
+ * UTC ("2026-10-16" → "Fri, Oct 16"); an impossible ISO day ("2026-02-31")
+ * comes back as written. Missing input is ''.
+ */
+export function dateLabel(v, locale) {
+    const s = plain(v);
+    const day = ISO_DAY.exec(s)?.[1];
+    if (!day)
+        return s;
+    const t = Date.parse(day);
+    // Date.parse rolls 2026-02-31 over to March 3; the round trip catches it.
+    if (Number.isNaN(t) || new Date(t).toISOString().slice(0, 10) !== day)
+        return s;
+    const opts = { weekday: 'short', month: 'short', day: 'numeric', timeZone: 'UTC' };
+    try {
+        return new Intl.DateTimeFormat(locale, opts).format(t);
+    }
+    catch {
+        return new Intl.DateTimeFormat(undefined, opts).format(t);
+    }
+}
+/** A whole number inside the range; junk falls back to the default. Timers use it for seconds and minutes. */
+export function clampSec(v, r) {
+    const n = finite(v);
+    return n === undefined ? r.fallback : Math.min(Math.max(Math.round(n), r.min), r.max);
+}
+/** A countdown in seconds as "0:40", "12:05", "25:00". */
+export function clock(sec) {
+    const s = Math.max(0, Math.ceil(sec));
+    return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}`;
+}