@vamos-ui/react 0.0.0-stage → 0.2.0

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 {};

package/dist/components/status-picker.js

@@ -0,0 +1,175 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { Select as SelectPrimitive } from "radix-ui";
+import { Check, ChevronDown } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useFieldControl } from "../lib/field-context.js";
+import { useLabels } from "../lib/labels.js";
+import { Layer } from "../lib/layer.js";
+import { usePortalContainer } from "../lib/theme-scope.js";
+import { useControllableState, useLatest } from "../lib/use-controllable-state.js";
+import { controlVariants, itemSlots, itemVariants } from "../lib/variants.js";
+import { badgeVariants } from "./badge.js";
+import { Spinner } from "./spinner.js";
+import { AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogFooter, AlertDialogHeader, AlertDialogBody } from "./alert-dialog.js";
+import { Textarea } from "./input.js";
+const statusPickerLabels = {
+    change: "{label}: {status}. Change",
+    status: "Status",
+    notAllowed: "Not allowed from {status}",
+    note: "Note",
+    notePlaceholder: "Add a short reason the requester will see",
+    saving: "Saving…",
+    saved: "Status changed to {status}",
+    failed: "Couldn't change the status. It's back to {status}.",
+    placeholder: "Set status",
+    todo: "To do",
+    active: "In progress",
+    done: "Done",
+    cancelled: "Cancelled",
+    confirm: "Confirm",
+};
+const CATEGORY_TONE = { todo: "neutral", active: "info", done: "success", cancelled: "neutral" };
+const CATEGORY_ORDER = ["todo", "active", "done", "cancelled"];
+/** Default category icons — shape, not only colour, carries the meaning. */
+export function StatusIcon({ category, className }) {
+    const cls = cn("size-3.5 shrink-0", className);
+    switch (category) {
+        case "todo":
+            return (_jsx("svg", { viewBox: "0 0 16 16", fill: "none", "aria-hidden": true, focusable: "false", className: cls, "data-category": "todo", children: _jsx("circle", { cx: "8", cy: "8", r: "5.75", stroke: "currentColor", strokeWidth: "1.6", strokeDasharray: "2.6 2.1" }) }));
+        case "active":
+            return (_jsxs("svg", { viewBox: "0 0 16 16", fill: "none", "aria-hidden": true, focusable: "false", className: cls, "data-category": "active", children: [_jsx("circle", { cx: "8", cy: "8", r: "5.75", stroke: "currentColor", strokeWidth: "1.6" }), _jsx("path", { d: "M8 4.25a3.75 3.75 0 0 1 0 7.5z", fill: "currentColor" })] }));
+        case "done":
+            return (_jsxs("svg", { viewBox: "0 0 16 16", fill: "none", "aria-hidden": true, focusable: "false", className: cls, "data-category": "done", children: [_jsx("circle", { cx: "8", cy: "8", r: "6.5", fill: "currentColor" }), _jsx("path", { d: "M5.2 8.2 7.1 10l3.7-4", stroke: "var(--surface-solid, #fff)", strokeWidth: "1.7", strokeLinecap: "round", strokeLinejoin: "round" })] }));
+        default:
+            return (_jsxs("svg", { viewBox: "0 0 16 16", fill: "none", "aria-hidden": true, focusable: "false", className: cls, "data-category": "cancelled", children: [_jsx("circle", { cx: "8", cy: "8", r: "5.75", stroke: "currentColor", strokeWidth: "1.6" }), _jsx("path", { d: "m5.6 10.4 4.8-4.8", stroke: "currentColor", strokeWidth: "1.6", strokeLinecap: "round" })] }));
+    }
+}
+/** Badge tone of a status. Passed into the single `badgeVariants` call so the neutral default never overrides it. */
+function toneStyle(s) {
+    if (!s)
+        return { tone: "outline" };
+    if (s.color)
+        return { tone: "custom", style: { ["--tone"]: s.color } };
+    return { tone: s.tone ?? CATEGORY_TONE[s.category] };
+}
+const TONE_COLOR = {
+    neutral: "var(--fg-muted)",
+    accent: "var(--accent-ink)",
+    success: "var(--success)",
+    warning: "var(--warning)",
+    danger: "var(--danger)",
+    info: "var(--info)",
+};
+/** The ink colour of a status (icon in field triggers and menus). */
+function toneColor(s) {
+    return s.color ?? TONE_COLOR[s.tone ?? CATEGORY_TONE[s.category]];
+}
+/** A status rendered as a badge (no picker) — table cells, read-only views, activity entries. */
+export function StatusBadge({ status, size = "md", className }) {
+    const tone = toneStyle(status);
+    return (_jsxs("span", { "data-slot": "status-badge", "data-category": status.category, className: cn(badgeVariants({ size: size === "sm" ? "sm" : "md", tone: tone.tone }), "gap-1.5", status.category === "cancelled" && "text-fg-muted", className), style: tone.style, children: [status.icon ?? _jsx(StatusIcon, { category: status.category }), status.label] }));
+}
+/**
+ * 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 const StatusPicker = React.forwardRef(function StatusPicker({ statuses, value: valueProp, defaultValue, onValueChange, transitions, confirm, onError, trigger = "badge", groupByCategory, name, size = "md", disabled: disabledProp, readOnly: readOnlyProp, loading, fieldLabel, labels, className, ...rest }, ref) {
+    const t = useLabels("statusPicker", statusPickerLabels, labels);
+    const control = useFieldControl({
+        id: rest.id,
+        name,
+        disabled: disabledProp,
+        readOnly: readOnlyProp,
+        "aria-describedby": rest["aria-describedby"],
+        "aria-labelledby": rest["aria-labelledby"],
+        "aria-invalid": rest["aria-invalid"],
+    });
+    const container = usePortalContainer();
+    const [committed, setCommitted] = useControllableState({ value: valueProp, defaultValue: defaultValue ?? null, name: "StatusPicker" });
+    const [optimistic, setOptimistic] = React.useState(null);
+    const [saving, setSaving] = React.useState(false);
+    const [announce, setAnnounce] = React.useState("");
+    const [pendingConfirm, setPendingConfirm] = React.useState(null);
+    const [note, setNote] = React.useState("");
+    const onChangeRef = useLatest(onValueChange);
+    const noteId = React.useId();
+    const shown = optimistic ?? committed;
+    const byValue = React.useMemo(() => new Map(statuses.map((s) => [s.value, s])), [statuses]);
+    const current = shown ? byValue.get(shown) : undefined;
+    const committedDef = committed ? byValue.get(committed) : undefined;
+    const allowed = committed && transitions ? new Set([committed, ...(transitions[committed] ?? [])]) : null;
+    const disabled = Boolean(control.disabled);
+    const readOnly = Boolean(control.readOnly);
+    const busy = saving || Boolean(loading);
+    const grouped = groupByCategory ?? statuses.length > 5;
+    const commit = async (next, meta) => {
+        const prev = committed;
+        const result = onChangeRef.current?.(next.value, prev, meta);
+        if (result && typeof result.then === "function") {
+            setOptimistic(next.value);
+            setSaving(true);
+            try {
+                await result;
+                setCommitted(next.value);
+                setAnnounce(t("saved", { status: next.label }));
+            }
+            catch (err) {
+                setAnnounce(t("failed", { status: committedDef?.label ?? t("placeholder") }));
+                onError?.(err, next);
+            }
+            finally {
+                setOptimistic(null);
+                setSaving(false);
+            }
+        }
+        else {
+            setCommitted(next.value);
+            setAnnounce(t("saved", { status: next.label }));
+        }
+    };
+    const handleChange = (v) => {
+        const next = byValue.get(v);
+        if (!next || v === committed)
+            return;
+        const config = confirm?.(next, committedDef ?? null);
+        if (config) {
+            setNote("");
+            setPendingConfirm({ next, config });
+            return;
+        }
+        void commit(next, {});
+    };
+    const label = fieldLabel ?? t("status");
+    const accessibleName = rest["aria-label"] ?? (control["aria-labelledby"] ? undefined : t("change", { label, status: current?.label ?? t("placeholder") }));
+    const tone = toneStyle(current);
+    const triggerClass = trigger === "field"
+        ? cn(controlVariants({ size: size === "sm" ? "sm" : "md" }), "justify-start text-start", className)
+        : cn(badgeVariants({ size: size === "sm" ? "sm" : "md", tone: tone.tone }), "gap-1.5 pe-1.5 outline-none transition-[filter,box-shadow] focus-ring", !readOnly && !disabled && "cursor-pointer hover:brightness-95", current?.category === "cancelled" && "text-fg-muted", disabled && "opacity-50", className);
+    const triggerInner = (_jsxs(_Fragment, { children: [busy ? (_jsx(Spinner, { size: "xs", className: trigger === "field" ? "text-fg-muted" : undefined })) : current ? (_jsx("span", { className: "inline-flex", style: trigger === "field" ? { color: toneColor(current) } : undefined, children: current.icon ?? _jsx(StatusIcon, { category: current.category }) })) : null, _jsx("span", { className: cn("truncate", trigger === "field" && "flex-1", !current && "text-fg-subtle"), children: current?.label ?? t("placeholder") }), busy ? _jsx("span", { className: "sr-only", children: t("saving") }) : null, !readOnly ? _jsx(ChevronDown, { "aria-hidden": true, className: cn("shrink-0 opacity-60", trigger === "field" ? "ms-auto size-4" : "size-3") }) : null] }));
+    if (readOnly) {
+        return current ? (_jsx(StatusBadge, { status: current, size: size, className: className })) : (_jsx("span", { className: cn(badgeVariants({ tone: "outline", size: size === "sm" ? "sm" : "md" }), className), children: t("placeholder") }));
+    }
+    const groups = grouped
+        ? CATEGORY_ORDER.map((c) => ({ category: c, items: statuses.filter((s) => s.category === c) })).filter((g) => g.items.length)
+        : [{ category: null, items: statuses }];
+    const renderItem = (s) => {
+        const notAllowed = allowed ? !allowed.has(s.value) : false;
+        const reasonId = `${noteId}-${s.value}`;
+        return (_jsxs(SelectPrimitive.Item, { value: s.value, disabled: notAllowed, "aria-describedby": notAllowed ? reasonId : undefined, className: cn(itemVariants({ size: "md", inset: true }), "items-start py-2"), children: [_jsx("span", { className: cn(itemSlots.indicator, "top-2.5"), children: _jsx(SelectPrimitive.ItemIndicator, { children: _jsx(Check, { className: "size-3.5", strokeWidth: 2.5 }) }) }), _jsx("span", { "aria-hidden": true, className: "mt-0.5 inline-flex [&_svg]:size-4", style: { color: toneColor(s) }, children: s.icon ?? _jsx(StatusIcon, { category: s.category, className: "size-4" }) }), _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx(SelectPrimitive.ItemText, { children: s.label }), notAllowed ? (_jsx("span", { id: reasonId, className: itemSlots.description, children: t("notAllowed", { status: committedDef?.label ?? "" }) })) : s.description ? (_jsx("span", { className: itemSlots.description, children: s.description })) : null] })] }, s.value));
+    };
+    return (_jsxs(_Fragment, { children: [_jsxs(SelectPrimitive.Root, { value: shown ?? "", onValueChange: handleChange, disabled: disabled || busy, name: control.name, children: [_jsx(SelectPrimitive.Trigger, { ref: ref, id: control.id, "data-slot": "status-picker", "data-trigger": trigger, "data-category": current?.category, "aria-label": accessibleName, "aria-labelledby": control["aria-labelledby"], "aria-describedby": control["aria-describedby"], "aria-invalid": control["aria-invalid"], "aria-busy": busy || undefined, className: triggerClass, style: trigger === "badge" ? tone.style : undefined, children: triggerInner }), _jsx(SelectPrimitive.Portal, { container: container, children: _jsx(Layer, { asChild: true, children: _jsx(SelectPrimitive.Content, { position: "popper", sideOffset: 6, collisionPadding: 12, align: "start", "data-slot": "status-picker-content", className: "surface-popover ui-pop z-(--z-popover) max-h-(--radix-select-content-available-height) min-w-56 overflow-hidden rounded-ui-lg", children: _jsx(SelectPrimitive.Viewport, { className: "p-1", children: groups.map((g, i) => g.category ? (_jsxs(SelectPrimitive.Group, { children: [i > 0 ? _jsx(SelectPrimitive.Separator, { className: itemSlots.separator }) : null, _jsx(SelectPrimitive.Label, { className: itemSlots.groupLabel, children: t(g.category) }), g.items.map(renderItem)] }, g.category)) : (_jsx(React.Fragment, { children: g.items.map(renderItem) }, "all"))) }) }) }) })] }), _jsx("span", { role: "status", "aria-live": "polite", className: "sr-only", children: announce }), _jsx(AlertDialog, { open: pendingConfirm !== null, onOpenChange: (o) => !o && setPendingConfirm(null), children: pendingConfirm ? (_jsxs(AlertDialogContent, { tone: pendingConfirm.config.tone ?? "default", children: [_jsx(AlertDialogHeader, { title: pendingConfirm.config.title, description: pendingConfirm.config.description }), pendingConfirm.config.requireNote ? (_jsxs(AlertDialogBody, { className: "grid gap-1.5", children: [_jsx("label", { htmlFor: `${noteId}-note`, className: "text-[13px] font-medium text-fg", children: pendingConfirm.config.noteLabel ?? t("note") }), _jsx(Textarea, { id: `${noteId}-note`, rows: 3, value: note, onChange: (e) => setNote(e.target.value), placeholder: t("notePlaceholder"), required: true, "aria-required": true })] })) : null, _jsxs(AlertDialogFooter, { children: [_jsx(AlertDialogCancel, {}), _jsx(AlertDialogAction, { disabled: Boolean(pendingConfirm.config.requireNote) && note.trim() === "", onClick: () => {
+                                        const p = pendingConfirm;
+                                        setPendingConfirm(null);
+                                        void commit(p.next, { note: p.config.requireNote ? note.trim() : undefined });
+                                    }, children: pendingConfirm.config.confirmLabel ?? t("confirm") })] })] })) : null })] }));
+});