@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/components/sparkline.d.ts

@@ -0,0 +1,54 @@
+import * as React from "react";
+/** A theme colour token, or any CSS colour. Tokens follow every theme axis. */
+export type SparklineColor = "currentColor" | "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5" | "chart-6" | "accent-ink" | "fg" | "fg-muted" | "fg-subtle" | "success" | "warning" | "danger" | "info" | (string & {});
+/** `"chart-2"` → `"var(--chart-2)"`; other values pass through. */
+export declare const sparklineColor: (c?: SparklineColor) => string;
+declare const SIZES: {
+    readonly xs: readonly [64, 20];
+    readonly sm: readonly [96, 32];
+    readonly md: readonly [160, 40];
+};
+export interface SparklineProps extends Omit<React.SVGAttributes<SVGSVGElement>, "values" | "color" | "width" | "height"> {
+    /** Data points, oldest first. `null` leaves a gap. */
+    values: ReadonlyArray<number | null>;
+    /** Default `"line"`. `"winloss"` draws up/down ticks from the sign of each value. */
+    variant?: "line" | "area" | "bars" | "winloss";
+    /** Preset box: xs 64×20 (table cells), sm 96×32, md 160×40. Default `"sm"`. */
+    size?: keyof typeof SIZES;
+    /** Pixel width, or `"100%"` to fill the container (strokes stay crisp). Overrides `size`. */
+    width?: number | "100%";
+    /** Pixel height. Overrides `size`. */
+    height?: number;
+    /** Token (`"chart-2"`, `"success"`…) or CSS colour. Default `currentColor`. */
+    color?: SparklineColor;
+    /** Stroke width of line/area. Default 1.6. */
+    strokeWidth?: number;
+    /** Dot on the last value. */
+    showLast?: boolean;
+    /** Dots on the lowest and highest value. */
+    showMinMax?: boolean;
+    /** Dashed reference line (target, average). */
+    reference?: number;
+    /** Shared scale `[min, max]` — use the same domain for every row of a table. */
+    domain?: readonly [number, number];
+    /** Accessible description. Without it the sparkline is decorative (`aria-hidden`). See `sparklineSummary()`. */
+    label?: string;
+}
+/**
+ * An axis-less mini trend: plain SVG, no chart library, server-component compatible.
+ * Use in Stat, table cells and list rows; decorative unless you pass `label`.
+ *
+ * ```tsx
+ * <Sparkline values={[4, 6, 5, 8, 7, 9, 12]} className="text-accent-ink" />
+ * <Sparkline values={weekly} variant="bars" size="xs" domain={[0, 120]} label={sparklineSummary(weekly)} />
+ * ```
+ */
+export declare const Sparkline: React.ForwardRefExoticComponent<SparklineProps & React.RefAttributes<SVGSVGElement>>;
+/** Direction of a series from its first to its last number: `1` up, `-1` down, `0` flat. */
+export declare function sparklineDirection(values: ReadonlyArray<number | null>): -1 | 0 | 1;
+/**
+ * Plain-English summary for a sparkline's `label`: "Rose from 4 to 14, peak 14".
+ * Pass `format` for locale numbers (`(n) => f.number(n)`), or write your own sentence.
+ */
+export declare function sparklineSummary(values: ReadonlyArray<number | null>, format?: (n: number) => string): string;
+export {};

package/dist/components/sparkline.js

@@ -0,0 +1,122 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+const TOKENS = new Set(["chart-1", "chart-2", "chart-3", "chart-4", "chart-5", "chart-6", "accent-ink", "fg", "fg-muted", "fg-subtle", "success", "warning", "danger", "info"]);
+/** `"chart-2"` → `"var(--chart-2)"`; other values pass through. */
+export const sparklineColor = (c = "currentColor") => (TOKENS.has(c) ? `var(--${c})` : c);
+const SIZES = { xs: [64, 20], sm: [96, 32], md: [160, 40] };
+/**
+ * An axis-less mini trend: plain SVG, no chart library, server-component compatible.
+ * Use in Stat, table cells and list rows; decorative unless you pass `label`.
+ *
+ * ```tsx
+ * <Sparkline values={[4, 6, 5, 8, 7, 9, 12]} className="text-accent-ink" />
+ * <Sparkline values={weekly} variant="bars" size="xs" domain={[0, 120]} label={sparklineSummary(weekly)} />
+ * ```
+ */
+export const Sparkline = React.forwardRef(function Sparkline({ values, variant = "line", size = "sm", width, height, color, strokeWidth = 1.6, showLast, showMinMax, reference, domain, label, className, style, ...props }, ref) {
+    const gradientId = `spark-${React.useId().replace(/:/g, "")}`;
+    const fluid = width === "100%";
+    const w = typeof width === "number" ? width : SIZES[size][0];
+    const h = height ?? SIZES[size][1];
+    const nums = values.filter((v) => typeof v === "number" && Number.isFinite(v));
+    const a11y = label ? { role: "img", "aria-label": label } : { "aria-hidden": true };
+    const svgProps = {
+        ref,
+        "data-slot": "sparkline",
+        "data-variant": variant,
+        viewBox: `0 0 ${w} ${h}`,
+        width: fluid ? "100%" : w,
+        height: h,
+        preserveAspectRatio: fluid ? "none" : undefined,
+        className: cn("block shrink-0 overflow-visible", fluid && "w-full", className),
+        style: { color: color ? sparklineColor(color) : undefined, ...style },
+        focusable: "false",
+        ...a11y,
+        ...props,
+    };
+    if (nums.length === 0) {
+        return (_jsx("svg", { ...svgProps, children: _jsx("line", { x1: 0, x2: w, y1: h / 2, y2: h / 2, stroke: "var(--line)", strokeDasharray: "2 3", vectorEffect: "non-scaling-stroke" }) }));
+    }
+    const pad = variant === "bars" || variant === "winloss" ? 0 : Math.max(2, strokeWidth + 1.5);
+    const base = variant === "bars" ? [Math.min(0, ...nums), Math.max(0, ...nums)] : [Math.min(...nums), Math.max(...nums)];
+    const extra = reference === undefined ? [] : [reference];
+    const lo = domain ? domain[0] : Math.min(base[0], ...extra);
+    const hi = domain ? domain[1] : Math.max(base[1], ...extra);
+    const span = hi - lo || 1;
+    const flat = hi === lo;
+    const y = (v) => (flat ? h / 2 : h - pad - ((Math.min(hi, Math.max(lo, v)) - lo) / span) * (h - pad * 2));
+    const n = values.length;
+    const x = (i) => (n === 1 ? w / 2 : (i / (n - 1)) * w);
+    const stroke = { vectorEffect: "non-scaling-stroke" };
+    // A zero-length round-capped line renders as a true circle even when the SVG is stretched.
+    const dot = (i, v, key, r = 2.25) => (_jsx("path", { d: `M${x(i)} ${y(v)}h0`, stroke: "currentColor", strokeWidth: r * 2, strokeLinecap: "round", ...stroke }, key));
+    if (variant === "bars" || variant === "winloss") {
+        const slot = w / n;
+        const gap = Math.min(2, slot * 0.25);
+        const bw = Math.max(1, slot - gap);
+        const zero = variant === "winloss" ? h / 2 : y(Math.max(lo, Math.min(hi, 0)));
+        return (_jsxs("svg", { ...svgProps, children: [reference !== undefined && variant === "bars" ? (_jsx("line", { x1: 0, x2: w, y1: y(reference), y2: y(reference), stroke: "var(--fg-subtle)", strokeDasharray: "3 3", strokeWidth: 1, ...stroke })) : null, values.map((v, i) => {
+                    if (typeof v !== "number" || !Number.isFinite(v))
+                        return null;
+                    const bx = i * slot + gap / 2;
+                    if (variant === "winloss") {
+                        if (v === 0)
+                            return _jsx("rect", { x: bx, width: bw, y: h / 2 - 0.5, height: 1, fill: "var(--fg-subtle)" }, i);
+                        const up = v > 0;
+                        return _jsx("rect", { x: bx, width: bw, y: up ? 1 : h / 2 + 1, height: h / 2 - 2, rx: Math.min(1.5, bw / 3), fill: up ? "var(--success)" : "var(--danger)" }, i);
+                    }
+                    const top = Math.min(y(v), zero);
+                    const bh = Math.max(1, Math.abs(zero - y(v)));
+                    const last = i === n - 1;
+                    return _jsx("rect", { x: bx, width: bw, y: top, height: bh, rx: Math.min(1.5, bw / 3), fill: "currentColor", opacity: showLast && !last ? 0.45 : 1 }, i);
+                })] }));
+    }
+    // Line / area: split into segments at null gaps.
+    const segments = [];
+    let cur = [];
+    values.forEach((v, i) => {
+        if (typeof v === "number" && Number.isFinite(v))
+            cur.push([x(i), y(v)]);
+        else if (cur.length) {
+            segments.push(cur);
+            cur = [];
+        }
+    });
+    if (cur.length)
+        segments.push(cur);
+    const path = (seg) => seg.length === 1 ? `M${Math.max(0, seg[0][0] - 2)} ${seg[0][1]}H${Math.min(w, seg[0][0] + 2)}` : seg.map(([px, py], i) => `${i ? "L" : "M"}${px.toFixed(2)} ${py.toFixed(2)}`).join("");
+    const lastIdx = values.findLastIndex((v) => typeof v === "number" && Number.isFinite(v));
+    const minIdx = values.indexOf(Math.min(...nums));
+    const maxIdx = values.indexOf(Math.max(...nums));
+    return (_jsxs("svg", { ...svgProps, children: [variant === "area" ? (_jsx("defs", { children: _jsxs("linearGradient", { id: gradientId, x1: "0", y1: "0", x2: "0", y2: "1", children: [_jsx("stop", { offset: "0%", stopColor: "currentColor", stopOpacity: 0.24 }), _jsx("stop", { offset: "100%", stopColor: "currentColor", stopOpacity: 0 })] }) })) : null, reference !== undefined ? (_jsx("line", { "data-slot": "sparkline-reference", x1: 0, x2: w, y1: y(reference), y2: y(reference), stroke: "var(--fg-subtle)", strokeDasharray: "3 3", strokeWidth: 1, ...stroke })) : null, variant === "area"
+                ? segments.map((seg, i) => seg.length > 1 ? _jsx("path", { d: `${path(seg)}L${seg[seg.length - 1][0]} ${h}L${seg[0][0]} ${h}Z`, fill: `url(#${gradientId})`, stroke: "none" }, `a${i}`) : null)
+                : null, segments.map((seg, i) => (_jsx("path", { d: path(seg), fill: "none", stroke: "currentColor", strokeWidth: strokeWidth, strokeLinejoin: "round", strokeLinecap: "round", ...stroke }, `l${i}`))), showMinMax && !flat ? [dot(minIdx, nums.length ? Math.min(...nums) : 0, "min", 1.75), dot(maxIdx, Math.max(...nums), "max", 1.75)] : null, showLast && lastIdx >= 0 ? dot(lastIdx, values[lastIdx], "last") : null] }));
+});
+/** Direction of a series from its first to its last number: `1` up, `-1` down, `0` flat. */
+export function sparklineDirection(values) {
+    const nums = values.filter((v) => typeof v === "number" && Number.isFinite(v));
+    if (nums.length < 2)
+        return 0;
+    const d = nums[nums.length - 1] - nums[0];
+    return d > 0 ? 1 : d < 0 ? -1 : 0;
+}
+/**
+ * Plain-English summary for a sparkline's `label`: "Rose from 4 to 14, peak 14".
+ * Pass `format` for locale numbers (`(n) => f.number(n)`), or write your own sentence.
+ */
+export function sparklineSummary(values, format = (n) => n.toLocaleString("en-US")) {
+    const nums = values.filter((v) => typeof v === "number" && Number.isFinite(v));
+    if (nums.length === 0)
+        return "No data";
+    if (nums.length === 1)
+        return `Single value ${format(nums[0])}`;
+    const first = nums[0];
+    const last = nums[nums.length - 1];
+    const peak = Math.max(...nums);
+    const low = Math.min(...nums);
+    const verb = last > first ? "Rose" : last < first ? "Fell" : "Held";
+    const range = last === first ? `at ${format(first)}` : `from ${format(first)} to ${format(last)}`;
+    const tail = last > first ? `, peak ${format(peak)}` : last < first ? `, low ${format(low)}` : "";
+    return `${verb} ${range}${tail}`;
+}

package/dist/components/spinner.d.ts

@@ -0,0 +1,34 @@
+import * as React from "react";
+import { type VariantProps } from "class-variance-authority";
+declare const SIZES: {
+    readonly xs: 12;
+    readonly sm: 16;
+    readonly md: 20;
+    readonly lg: 28;
+};
+export declare const spinnerVariants: (props?: ({
+    tone?: "accent" | "current" | "muted" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export interface SpinnerProps extends Omit<React.SVGAttributes<SVGSVGElement>, "children">, VariantProps<typeof spinnerVariants> {
+    /** 12 / 16 / 20 / 28 px, or any pixel number. Default `"sm"`. */
+    size?: keyof typeof SIZES | number;
+    /**
+     * Accessible status text ("Saving changes"). When set, the spinner is announced politely
+     * (`role="status"`); without it the spinner is decorative (`aria-hidden`) — use that inside a
+     * button that already has `aria-busy`.
+     */
+    label?: string;
+    /** ms to wait before showing, so fast responses don't flash a spinner. CSS-only. */
+    delay?: number;
+}
+/**
+ * Indeterminate loading indicator: a thin track with a rotating, breathing arc.
+ * Server-compatible. Under `prefers-reduced-motion` it pulses slowly instead of spinning.
+ *
+ * ```tsx
+ * <Spinner label="Loading orders" />
+ * <Button loading>Save</Button>   // uses a decorative Spinner
+ * ```
+ */
+export declare const Spinner: React.ForwardRefExoticComponent<SpinnerProps & React.RefAttributes<SVGSVGElement>>;
+export {};

package/dist/components/spinner.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cva } from "class-variance-authority";
+import { cn } from "../lib/cn.js";
+const SIZES = { xs: 12, sm: 16, md: 20, lg: 28 };
+const STROKE = { xs: 3, sm: 2.75, md: 2.5, lg: 2.25 };
+export const spinnerVariants = cva("ui-spinner inline-block shrink-0 align-middle", {
+    variants: {
+        tone: {
+            /** Inherits the text colour — the default inside buttons. */
+            current: "text-current",
+            accent: "text-accent-ink",
+            muted: "text-fg-muted",
+        },
+    },
+    defaultVariants: { tone: "current" },
+});
+/**
+ * Indeterminate loading indicator: a thin track with a rotating, breathing arc.
+ * Server-compatible. Under `prefers-reduced-motion` it pulses slowly instead of spinning.
+ *
+ * ```tsx
+ * <Spinner label="Loading orders" />
+ * <Button loading>Save</Button>   // uses a decorative Spinner
+ * ```
+ */
+export const Spinner = React.forwardRef(function Spinner({ size = "sm", tone, label, delay, className, style, ...props }, ref) {
+    const px = typeof size === "number" ? size : SIZES[size];
+    const stroke = typeof size === "number" ? (size <= 14 ? 3 : size >= 26 ? 2.25 : 2.5) : STROKE[size];
+    const svg = (_jsxs("svg", { ref: ref, "data-slot": "spinner", viewBox: "0 0 24 24", width: px, height: px, fill: "none", "aria-hidden": true, focusable: "false", className: cn(spinnerVariants({ tone }), delay ? "ui-spinner-delayed" : undefined, className), style: delay ? { ...style, "--spinner-delay": `${delay}ms` } : style, ...props, children: [_jsx("circle", { cx: "12", cy: "12", r: "9.25", stroke: "currentColor", strokeOpacity: 0.18, strokeWidth: stroke }), _jsx("circle", { className: "ui-spinner-arc", cx: "12", cy: "12", r: "9.25", stroke: "currentColor", strokeWidth: stroke, strokeLinecap: "round", transform: "rotate(-90 12 12)" })] }));
+    if (!label)
+        return svg;
+    return (_jsxs("span", { role: "status", "aria-live": "polite", "data-slot": "spinner-status", className: "inline-flex items-center", children: [svg, _jsx("span", { className: "sr-only", children: label })] }));
+});

package/dist/components/stat.d.ts

@@ -0,0 +1,135 @@
+import * as React from "react";
+import { type LucideIcon } from "lucide-react";
+import type { statLabels } from "../lib/data-islands.js";
+import type { ValueFormat } from "../lib/value-format.js";
+export type { ValueFormat } from "../lib/value-format.js";
+/** Which direction is good news. Decides the delta colour, never the arrow. */
+export type StatIntent = "higher-is-better" | "lower-is-better" | "neutral";
+export type StatLabels = Partial<typeof statLabels>;
+export interface DeltaProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "children"> {
+    /** The change. `kind="percent"` takes a ratio: `0.124` → "+12.4%". `null` → "—". */
+    value: number | null | undefined;
+    /** Default `"percent"`. */
+    kind?: "percent" | "number" | "currency";
+    /** ISO 4217 code for `kind="currency"`. Default: the LocaleProvider currency. */
+    currency?: string;
+    /** Default `"higher-is-better"`. With `"lower-is-better"` a drop is green (response time, churn). */
+    intent?: StatIntent;
+    /** `"text"` (default) or a soft `"badge"`. */
+    variant?: "text" | "badge";
+    /** Max fraction digits. */
+    precision?: number;
+    /** Full screen-reader sentence. Default "Up 12.4%" / "Down 4.1%" / "No change". */
+    srLabel?: string;
+    /** Appended to the spoken text, e.g. "vs last month". */
+    comparison?: string;
+    labels?: StatLabels;
+}
+/**
+ * A signed change with an arrow and a semantic colour. Arrow + sign carry the meaning, colour
+ * only reinforces it. Server-component compatible; also used in table cells and list rows.
+ *
+ * ```tsx
+ * <Delta value={0.124} />                                  // ↗ +12.4%  (green)
+ * <Delta value={-0.18} intent="lower-is-better" />          // ↘ −18%    (green: faster replies)
+ * <Delta value={1250} kind="currency" variant="badge" />
+ * ```
+ */
+export declare const Delta: React.ForwardRefExoticComponent<DeltaProps & React.RefAttributes<HTMLSpanElement>>;
+export interface StatProps extends Omit<React.HTMLAttributes<HTMLElement>, "title"> {
+    /** What is measured ("Visitors"). */
+    label?: React.ReactNode;
+    /** Numbers are formatted with `format`; strings are shown as they are ("2:47"); `null` → "—" + "No data". */
+    value?: number | string | null;
+    /** How a numeric value is formatted. Default `"number"`. */
+    format?: ValueFormat;
+    /** Change vs the comparison period. See `Delta` (`deltaKind="percent"` takes a ratio). */
+    delta?: number | null;
+    deltaKind?: DeltaProps["kind"];
+    /** Delta as text or soft badge. Default `"text"`. */
+    deltaVariant?: DeltaProps["variant"];
+    /** Which direction is good. Default `"higher-is-better"`. */
+    intent?: StatIntent;
+    /** "vs previous 30 days" — shown in the footer and appended to the spoken delta (when a string). */
+    comparison?: React.ReactNode;
+    /** Mini trend, oldest first. */
+    trend?: ReadonlyArray<number | null>;
+    /** Default `"line"`. */
+    trendVariant?: "line" | "area" | "bars";
+    /** Progress-to-goal bar. */
+    target?: {
+        value: number;
+        label?: React.ReactNode;
+    };
+    /** Small icon next to the label (a Lucide icon component). */
+    icon?: LucideIcon;
+    /** Makes the whole stat a link (drill-down). */
+    href?: string;
+    /** Skeleton sized to label + value; sets `aria-busy`. */
+    loading?: boolean;
+    /** Error message in place of the value. */
+    error?: React.ReactNode;
+    /** Slot next to the error (e.g. a Retry button — only when the Stat is not a link). */
+    errorAction?: React.ReactNode;
+    /** `card` (own surface), `plain` (a cell inside StatGroup/Card) or `inline` (no padding). Default `"card"`. */
+    variant?: "card" | "plain" | "inline";
+    /** Value size 20 / 28 / 40px. Default `"md"`. */
+    size?: "sm" | "md" | "lg";
+    labels?: StatLabels;
+}
+/**
+ * One metric: label, value, change and a mini trend. Renders a `<dl>` (label = `dt`, value and
+ * change = `dd`); the sparkline is decorative and summarised for screen readers. Server-component
+ * compatible — no chart library, no count-up animation.
+ *
+ * ```tsx
+ * <Stat label="Visitors" value={28412} delta={0.124} trend={[4, 6, 5, 8, 7, 9, 12, 11, 14]} comparison="vs previous 30 days" />
+ * <Stat label="Avg. response" value={4320} format="duration" delta={-0.18} intent="lower-is-better" />
+ * ```
+ *
+ * Compose for custom layouts: `<Stat><StatLabel/><StatValue/><StatDelta/><StatTrend/><StatFooter/></Stat>`.
+ */
+export declare const Stat: React.ForwardRefExoticComponent<StatProps & React.RefAttributes<HTMLElement>>;
+/** The metric name (`<dt>`). */
+export declare function StatLabel({ className, ...props }: React.HTMLAttributes<HTMLElement>): React.JSX.Element;
+export interface StatValueProps extends Omit<React.HTMLAttributes<HTMLElement>, "children"> {
+    value?: number | string | null;
+    format?: ValueFormat;
+    /** Id of a text that describes the value (the trend summary). */
+    describedBy?: string;
+    labels?: StatLabels;
+    children?: React.ReactNode;
+}
+/** The big number (`<dd>`): mono, tabular, sized by the Stat `size`. */
+export declare function StatValue({ value, format, describedBy, labels, className, children, ...props }: StatValueProps): React.JSX.Element;
+/** Wrapper (`<dd>`) for a Delta at the top end. */
+export declare function StatDelta({ className, ...props }: React.HTMLAttributes<HTMLElement>): React.JSX.Element;
+/** Wrapper (`<dd>`) for the mini trend at the bottom end. */
+export declare function StatTrend({ className, ...props }: React.HTMLAttributes<HTMLElement>): React.JSX.Element;
+/** Secondary line under the value ("vs previous 30 days"). */
+export declare function StatFooter({ className, ...props }: React.HTMLAttributes<HTMLElement>): React.JSX.Element;
+export interface StatTargetProps {
+    value: number;
+    target: number;
+    /** Caption override; default "Goal $46,800" + percent. */
+    label?: React.ReactNode;
+    format?: ValueFormat;
+    labels?: StatLabels;
+    className?: string;
+}
+/** Progress-to-goal bar under the value. Turns success-coloured once the goal is reached. */
+export declare function StatTarget({ value, target, label, format, labels, className }: StatTargetProps): React.JSX.Element;
+export interface StatGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Max columns; fewer on narrow containers (container queries). Default 4. */
+    columns?: 2 | 3 | 4;
+    /**
+     * `"cards"` (default): separate Stat cards with a gap.
+     * `"plain"`: one surface with hairline dividers — put `variant="plain"` Stats inside.
+     */
+    variant?: "cards" | "plain";
+}
+/**
+ * A responsive row of Stats. Columns follow the container width, not the viewport, so the same
+ * row works in a page, a sheet or a dashboard widget.
+ */
+export declare const StatGroup: React.ForwardRefExoticComponent<StatGroupProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/stat.js

@@ -0,0 +1,130 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { ArrowDownRight, ArrowUpRight, Minus } from "lucide-react";
+import { cva } from "class-variance-authority";
+import { cn } from "../lib/cn.js";
+import { DataLabel, DeltaText, StatGoalText, ValueText } from "../lib/data-islands.js";
+import { cardVariants } from "./card.js";
+import { Skeleton } from "./skeleton.js";
+import { Sparkline, sparklineDirection } from "./sparkline.js";
+/* ------------------------------------------------------------------ */
+/* Delta                                                                */
+/* ------------------------------------------------------------------ */
+const deltaVariants = cva("inline-flex shrink-0 items-center gap-0.5 whitespace-nowrap font-medium leading-none [&_svg]:shrink-0", {
+    variants: {
+        variant: {
+            text: "text-xs [&_svg]:size-3.5",
+            badge: "h-5 rounded-full px-1.5 text-[11px] [--tone-mix:16%] glass:[--tone-mix:20%] tone-soft [&_svg]:size-3",
+        },
+        tone: {
+            positive: "tone-success text-success",
+            negative: "tone-danger text-danger",
+            neutral: "tone-neutral text-fg-muted",
+        },
+    },
+    defaultVariants: { variant: "text", tone: "neutral" },
+});
+/**
+ * A signed change with an arrow and a semantic colour. Arrow + sign carry the meaning, colour
+ * only reinforces it. Server-component compatible; also used in table cells and list rows.
+ *
+ * ```tsx
+ * <Delta value={0.124} />                                  // ↗ +12.4%  (green)
+ * <Delta value={-0.18} intent="lower-is-better" />          // ↘ −18%    (green: faster replies)
+ * <Delta value={1250} kind="currency" variant="badge" />
+ * ```
+ */
+export const Delta = React.forwardRef(function Delta({ value, kind = "percent", currency, intent = "higher-is-better", variant, precision, srLabel, comparison, labels, className, ...props }, ref) {
+    const has = typeof value === "number" && Number.isFinite(value);
+    const dir = has ? Math.sign(value) : 0;
+    const good = intent === "neutral" || dir === 0 ? 0 : intent === "higher-is-better" ? dir : -dir;
+    const tone = good > 0 ? "positive" : good < 0 ? "negative" : "neutral";
+    const Icon = dir > 0 ? ArrowUpRight : dir < 0 ? ArrowDownRight : Minus;
+    return (_jsx("span", { ref: ref, "data-slot": "delta", "data-trend": dir > 0 ? "up" : dir < 0 ? "down" : "flat", "data-tone": tone, className: cn(deltaVariants({ variant, tone }), className), ...props, children: has ? (_jsxs(_Fragment, { children: [_jsx(Icon, { "aria-hidden": true, strokeWidth: 2.25 }), _jsx(DeltaText, { value: value, kind: kind, currency: currency, precision: precision, srLabel: srLabel, srSuffix: comparison, labels: labels })] })) : (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": true, children: "\u2014" }), _jsx("span", { className: "sr-only", children: _jsx(DataLabel, { ns: "stat", id: "noData", override: labels }) })] })) }));
+});
+/* ------------------------------------------------------------------ */
+/* Stat parts                                                           */
+/* ------------------------------------------------------------------ */
+const statVariants = cva("group/stat relative grid min-w-0 grid-cols-[minmax(0,1fr)_auto] content-start items-start gap-x-3 [grid-template-areas:'label_delta'_'value_trend'_'target_target'_'foot_foot']" +
+    // without a sparkline the value may use the full width (a wide delta must not squeeze "$3,815,400.00")
+    " [&:not(:has([data-slot=stat-trend]))_[data-slot=stat-value]]:[grid-column:1/-1]", {
+    variants: {
+        variant: {
+            card: "p-(--stat-p)",
+            plain: "p-(--stat-p)",
+            inline: "gap-y-0.5",
+        },
+        size: {
+            sm: "[--stat-p:calc(var(--gap)*0.8)] [--stat-value:1.25rem]",
+            md: "[--stat-p:var(--gap)] [--stat-value:1.75rem]",
+            lg: "[--stat-p:calc(var(--gap)*1.2)] [--stat-value:2.5rem]",
+        },
+    },
+    defaultVariants: { variant: "card", size: "md" },
+});
+/**
+ * One metric: label, value, change and a mini trend. Renders a `<dl>` (label = `dt`, value and
+ * change = `dd`); the sparkline is decorative and summarised for screen readers. Server-component
+ * compatible — no chart library, no count-up animation.
+ *
+ * ```tsx
+ * <Stat label="Visitors" value={28412} delta={0.124} trend={[4, 6, 5, 8, 7, 9, 12, 11, 14]} comparison="vs previous 30 days" />
+ * <Stat label="Avg. response" value={4320} format="duration" delta={-0.18} intent="lower-is-better" />
+ * ```
+ *
+ * Compose for custom layouts: `<Stat><StatLabel/><StatValue/><StatDelta/><StatTrend/><StatFooter/></Stat>`.
+ */
+export const Stat = React.forwardRef(function Stat({ label, value, format, delta, deltaKind = "percent", deltaVariant, intent = "higher-is-better", comparison, trend, trendVariant = "line", target, icon: Icon, href, loading, error, errorAction, variant = "card", size = "md", labels, className, children, ...props }, ref) {
+    const trendId = React.useId();
+    const dir = trend ? sparklineDirection(trend) : 0;
+    const good = intent === "neutral" || dir === 0 ? 0 : intent === "higher-is-better" ? dir : -dir;
+    const count = trend ? trend.filter((v) => typeof v === "number").length : 0;
+    let content = children;
+    if (children === undefined) {
+        content = loading ? (_jsxs(_Fragment, { children: [_jsxs("dt", { className: "[grid-area:label]", children: [_jsx(Skeleton, { shape: "text", className: "h-3 w-24" }), _jsx("span", { className: "sr-only", children: label })] }), _jsxs("dd", { className: "mt-3 [grid-area:value]", children: [_jsx(Skeleton, { className: "h-(--stat-value) w-28" }), _jsx("span", { className: "sr-only", children: _jsx(DataLabel, { ns: "stat", id: "noData", override: labels }) })] })] })) : (_jsxs(_Fragment, { children: [_jsxs(StatLabel, { children: [Icon ? _jsx(Icon, { "aria-hidden": true, className: "size-3.5 shrink-0 text-fg-subtle" }) : null, label] }), error ? (_jsxs("dd", { "data-slot": "stat-error", className: "mt-3 flex flex-wrap items-center gap-2 text-[13px] text-danger [grid-column:1/-1] [grid-row:2]", children: [_jsx("span", { children: error }), errorAction] })) : (_jsx(StatValue, { value: value, format: format, labels: labels, describedBy: trend && count > 1 ? trendId : undefined })), !error && delta !== undefined ? (_jsx(StatDelta, { children: _jsx(Delta, { value: delta, kind: deltaKind, intent: intent, variant: deltaVariant, labels: labels, comparison: typeof comparison === "string" ? comparison : undefined }) })) : null, !error && trend && count > 0 ? (_jsxs(StatTrend, { children: [_jsx(Sparkline, { values: trend, variant: trendVariant, className: good > 0 || (intent === "neutral" && dir !== 0) ? "text-accent-ink" : "text-fg-subtle", showLast: trendVariant === "bars" }), _jsx("span", { id: trendId, className: "sr-only", children: _jsx(DataLabel, { ns: "stat", id: dir > 0 ? "trendUp" : dir < 0 ? "trendDown" : "trendFlat", override: labels, vars: { count } }) })] })) : null, !error && target && typeof value === "number" ? _jsx(StatTarget, { value: value, target: target.value, label: target.label, format: format, labels: labels }) : null, comparison && !error ? _jsx(StatFooter, { children: comparison }) : null] }));
+    }
+    const classes = cn(statVariants({ variant, size }), variant === "card" && !href && "surface rounded-ui-lg", className);
+    if (href) {
+        return (_jsx("a", { ref: ref, href: href, "data-slot": "stat-link", className: cn("block min-w-0 rounded-ui-lg", variant === "card" ? cardVariants({ variant: "surface", interactive: true }) : "transition-colors hover:bg-hover focus-ring"), children: _jsx("dl", { "data-slot": "stat", "data-variant": variant, "aria-busy": loading || undefined, className: classes, ...props, children: content }) }));
+    }
+    return (_jsx("dl", { ref: ref, "data-slot": "stat", "data-variant": variant, "aria-busy": loading || undefined, className: classes, ...props, children: content }));
+});
+/** The metric name (`<dt>`). */
+export function StatLabel({ className, ...props }) {
+    return _jsx("dt", { "data-slot": "stat-label", className: cn("flex min-w-0 items-center gap-1.5 text-[13px] leading-5 text-fg-muted [grid-area:label]", className), ...props });
+}
+/** The big number (`<dd>`): mono, tabular, sized by the Stat `size`. */
+export function StatValue({ value, format, describedBy, labels, className, children, ...props }) {
+    const empty = children === undefined && (value === null || value === undefined || value === "");
+    return (_jsx("dd", { "data-slot": "stat-value", "aria-describedby": describedBy, className: cn("mt-3 min-w-0 self-end truncate font-mono text-(length:--stat-value) leading-none font-medium tracking-[-0.03em] text-fg tabular [grid-area:value]", empty && "text-fg-subtle", className), ...props, children: children ?? (empty ? (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": true, children: "\u2014" }), _jsx("span", { className: "sr-only", children: _jsx(DataLabel, { ns: "stat", id: "noData", override: labels }) })] })) : typeof value === "number" || (format && typeof value === "string" && /^-?\d+(\.\d+)?$/.test(value)) ? (_jsx(ValueText, { value: value, format: format })) : (value)) }));
+}
+/** Wrapper (`<dd>`) for a Delta at the top end. */
+export function StatDelta({ className, ...props }) {
+    return _jsx("dd", { "data-slot": "stat-delta", className: cn("flex justify-end leading-5 [grid-area:delta]", className), ...props });
+}
+/** Wrapper (`<dd>`) for the mini trend at the bottom end. */
+export function StatTrend({ className, ...props }) {
+    return _jsx("dd", { "data-slot": "stat-trend", className: cn("mt-3 flex items-end justify-end self-end [grid-area:trend]", className), ...props });
+}
+/** Secondary line under the value ("vs previous 30 days"). */
+export function StatFooter({ className, ...props }) {
+    return _jsx("dd", { "data-slot": "stat-footer", className: cn("mt-3 text-xs text-fg-subtle [grid-area:foot]", className), ...props });
+}
+/** Progress-to-goal bar under the value. Turns success-coloured once the goal is reached. */
+export function StatTarget({ value, target, label, format, labels, className }) {
+    const ratio = target > 0 ? Math.max(0, value / target) : 0;
+    const reached = ratio >= 1;
+    return (_jsxs("dd", { "data-slot": "stat-target", "data-reached": reached ? "" : undefined, className: cn("mt-4 [grid-area:target]", className), children: [_jsx("div", { "aria-hidden": true, className: "h-1.5 overflow-hidden rounded-full bg-track", children: _jsx("div", { className: cn("h-full rounded-full transition-[width] duration-500 motion-reduce:transition-none", reached ? "bg-success" : "bg-accent"), style: { width: `${Math.min(100, ratio * 100)}%` } }) }), _jsx("div", { className: "mt-2 flex justify-between gap-3 text-xs text-fg-subtle", children: label ? (_jsxs(_Fragment, { children: [_jsx("span", { children: label }), _jsxs("span", { className: "tabular", children: [Math.round(ratio * 100), "%"] })] })) : (_jsx(StatGoalText, { value: value, target: target, format: format, labels: labels })) })] }));
+}
+const columnClasses = {
+    2: "@md:grid-cols-2",
+    3: "@md:grid-cols-2 @3xl:grid-cols-3",
+    4: "@md:grid-cols-2 @4xl:grid-cols-4",
+};
+/**
+ * A responsive row of Stats. Columns follow the container width, not the viewport, so the same
+ * row works in a page, a sheet or a dashboard widget.
+ */
+export const StatGroup = React.forwardRef(function StatGroup({ columns = 4, variant = "cards", className, children, ...props }, ref) {
+    return (_jsx("div", { ref: ref, "data-slot": "stat-group", className: cn("@container", className), ...props, children: _jsx("div", { className: cn("grid grid-cols-1", columnClasses[columns], variant === "cards" ? "gap-(--gap)" : "surface overflow-hidden rounded-ui-lg [&>*]:shadow-[-1px_-1px_0_0_var(--line)]"), children: children }) }));
+});

package/dist/components/status-picker.d.ts

@@ -0,0 +1,107 @@
+import * as React from "react";
+export type StatusCategory = "todo" | "active" | "done" | "cancelled";
+export type StatusTone = "neutral" | "accent" | "success" | "warning" | "danger" | "info";
+/** One status of a workflow. Labels are your data (localise them in the app). */
+export interface StatusDef {
+    value: string;
+    label: string;
+    /** Drives the default icon, tone and grouping. */
+    category: StatusCategory;
+    /** Semantic colour. Default from the category (todo neutral, active info, done success, cancelled neutral). */
+    tone?: StatusTone;
+    /** Any CSS colour (user-defined pipeline stages). Overrides `tone`. */
+    color?: string;
+    /** Replace the category icon. */
+    icon?: React.ReactNode;
+    description?: string;
+}
+/** What `confirm` returns to ask before a transition. */
+export interface StatusConfirm {
+    title: string;
+    description?: string;
+    /** Ask for a note (a rejection reason). Passed to `onValueChange` as `meta.note`. */
+    requireNote?: boolean;
+    /** Note field label. Default "Note". */
+    noteLabel?: string;
+    confirmLabel?: string;
+    /** `"danger"` for destructive transitions (reject, cancel). */
+    tone?: "default" | "danger";
+}
+declare const statusPickerLabels: {
+    change: string;
+    status: string;
+    notAllowed: string;
+    note: string;
+    notePlaceholder: string;
+    saving: string;
+    saved: string;
+    failed: string;
+    placeholder: string;
+    todo: string;
+    active: string;
+    done: string;
+    cancelled: string;
+    confirm: string;
+};
+export type StatusPickerLabels = typeof statusPickerLabels;
+export interface StatusPickerProps {
+    statuses: StatusDef[];
+    value?: string | null;
+    defaultValue?: string | null;
+    /** Return a promise for an optimistic save: the badge switches at once, shows a spinner and reverts if it rejects. */
+    onValueChange?: (value: string, previous: string | null, meta: {
+        note?: string;
+    }) => void | Promise<unknown>;
+    /** Allowed next statuses per status. Others stay visible but disabled with the reason. */
+    transitions?: Record<string, string[]>;
+    /** Ask before moving to `next` (return `false` to skip). */
+    confirm?: (next: StatusDef, current: StatusDef | null) => false | StatusConfirm;
+    /** Called after an async save failed and the value reverted (show a toast). */
+    onError?: (error: unknown, attempted: StatusDef) => void;
+    /** `"badge"` (inline in tables, record headers) or `"field"` (forms). Default `"badge"`. */
+    trigger?: "badge" | "field";
+    /** Group options under category headings. Default `true` when there are more than 5 statuses. */
+    groupByCategory?: boolean;
+    /** Hidden native select for form posts. */
+    name?: string;
+    size?: "sm" | "md";
+    disabled?: boolean;
+    /** Shows the badge, can't be changed. */
+    readOnly?: boolean;
+    /** External busy state (a save you run yourself). */
+    loading?: boolean;
+    /** What is being set, for the accessible name ("Stage: Proposal. Change"). Default "Status". */
+    fieldLabel?: string;
+    labels?: Partial<StatusPickerLabels>;
+    id?: string;
+    className?: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+    "aria-invalid"?: boolean | "true" | "false";
+}
+/** Default category icons — shape, not only colour, carries the meaning. */
+export declare function StatusIcon({ category, className }: {
+    category: StatusCategory;
+    className?: string;
+}): React.JSX.Element;
+/** A status rendered as a badge (no picker) — table cells, read-only views, activity entries. */
+export declare function StatusBadge({ status, size, className }: {
+    status: StatusDef;
+    size?: "sm" | "md";
+    className?: string;
+}): React.JSX.Element;
+/**
+ * Change a record's status inside a workflow: task To do → In progress → Done, deal stages,
+ * content Draft → Review → Published, leave Pending → Approved / Rejected. The trigger is the
+ * status badge itself; transitions not allowed from the current status stay visible with the
+ * reason; a transition can ask for confirmation (and a note); async saves are optimistic and revert.
+ *
+ * ```tsx
+ * <StatusPicker statuses={taskStatuses} value={task.status} onValueChange={(v) => save({ status: v })} />
+ * <StatusPicker statuses={leave} transitions={{ pending: ["approved", "rejected"] }}
+ *   confirm={(s) => s.value === "rejected" && { title: "Reject request?", requireNote: true, tone: "danger" }} />
+ * ```
+ */
+export declare const StatusPicker: React.ForwardRefExoticComponent<StatusPickerProps & React.RefAttributes<HTMLButtonElement>>;
+export {};