@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/charts/chart-shell.d.ts

@@ -0,0 +1,173 @@
+import * as React from "react";
+import { type LabelFn } from "../lib/labels.js";
+import type { Formatter } from "../format/core.js";
+import { patternDash, type ChartConfig, type ChartHeight, type ChartState, type FormatSpec, type ResolvedSeries } from "./utils.js";
+export declare const chartLabels: {
+    viewTable: string;
+    viewChart: string;
+    legend: string;
+    empty: string;
+    error: string;
+    retry: string;
+    loading: string;
+    refreshing: string;
+    total: string;
+    other: string;
+    otherCount: string;
+    share: string;
+    category: string;
+    value: string;
+    range: string;
+    seriesSummary: string;
+};
+export type ChartLabels = typeof chartLabels;
+export type ChartSkeletonKind = "area" | "line" | "bar" | "bar-horizontal" | "donut" | "grid";
+export interface ChartTableColumn {
+    key: string;
+    label: string;
+    format?: FormatSpec;
+    /** Row header column (first column). */
+    header?: boolean;
+}
+/** Overrides the generated data table (columns + rows). */
+export interface ChartTableSpec {
+    columns: ChartTableColumn[];
+    rows: Record<string, unknown>[];
+}
+type Row = Record<string, unknown>;
+export interface ChartContextValue {
+    config: ChartConfig;
+    series: ResolvedSeries[];
+    visibleSeries: ResolvedSeries[];
+    isHidden: (key: string) => boolean;
+    toggleSeries: (key: string) => void;
+    data: Row[];
+    x?: string;
+    xFormat?: FormatSpec;
+    yFormat?: FormatSpec;
+    /** Full value of a series ("$1,240.00"). */
+    formatSeries: (key: string, value: unknown) => string;
+    /** Compact value-axis tick ("$1.2K"). */
+    formatTick: (value: unknown, spec?: FormatSpec) => string;
+    /** x value; `long` for tooltip headers and tables ("Nov 1, 2026"). */
+    formatX: (value: unknown, long?: boolean) => string;
+    f: Formatter;
+    t: LabelFn<ChartLabels>;
+    /** `animate` resolved against `prefers-reduced-motion`. */
+    animate: boolean;
+    tooltipIndicator: "dot" | "line" | "dashed";
+    onPointClick?: (row: Row, seriesKey: string) => void;
+    height: number | undefined;
+    idPrefix: string;
+}
+/** Chart context: config, formatters and hidden series. Use inside `<Chart>`. */
+export declare function useChart(): ChartContextValue;
+/** Like `useChart`, but `null` outside a Chart. */
+export declare const useOptionalChart: () => ChartContextValue | null;
+export interface ChartProps<T extends object = Row> extends Omit<React.HTMLAttributes<HTMLElement>, "title" | "children" | "onClick"> {
+    data: T[];
+    config: ChartConfig;
+    /** Category / time key of a row. */
+    x?: keyof T & string;
+    /** Header of the x column in the data table. Default: the x key, capitalised. */
+    xLabel?: string;
+    xFormat?: FormatSpec;
+    /** Value axis format. Default: the first series' format, compact. */
+    yFormat?: FormatSpec;
+    /** Plot height: presets sm 160 / md 260 / lg 360 or pixels. Set this or `aspect` (no layout shift). `"auto"` sizes to the content (DOM charts such as Heatmap). */
+    height?: ChartHeight | "auto";
+    /** Width / height ratio instead of a fixed height. */
+    aspect?: number;
+    /** Loading / refreshing / empty / error. Default: empty when `data` is empty, else ready. */
+    state?: ChartState;
+    /** Accessible name and table caption (not shown — put a visible title in the Card header). */
+    title: string;
+    /** Text alternative. Default: generated from the data (range, low, high, average). */
+    summary?: string | ((data: T[]) => string);
+    /** Shows a "View as table" switch. The table is always in the page for screen readers. */
+    tableToggle?: boolean;
+    /** Default `"top"` with 2+ series, `"none"` with one. */
+    legend?: "top" | "bottom" | "none";
+    tooltipIndicator?: "dot" | "line" | "dashed";
+    /** Transitions on data change. Always off under reduced motion. Default `true`. */
+    animate?: boolean;
+    /** Drill-down. Also makes the rows of the visible data table activatable. */
+    onPointClick?: (row: T, seriesKey: string) => void;
+    /** Controlled hidden series. */
+    hiddenSeries?: string[];
+    defaultHiddenSeries?: string[];
+    onHiddenSeriesChange?: (keys: string[]) => void;
+    labels?: Partial<ChartLabels>;
+    /** Replace the generated data table. */
+    table?: ChartTableSpec;
+    /** Content beside (or under) the plot — e.g. the Donut legend list. */
+    aside?: React.ReactNode;
+    asidePosition?: "side" | "bottom";
+    /** Shape of the loading skeleton. Default `"area"`. */
+    skeleton?: ChartSkeletonKind;
+    /** Extra controls at the end of the toolbar (range picker…). */
+    toolbar?: React.ReactNode;
+    /** Plot content: a ready chart's Recharts tree, `<ChartFrame>` with raw Recharts, or any SVG. */
+    children?: React.ReactNode;
+}
+/**
+ * The shell every chart shares: series → token colours (`--series-<key>`), locale formatting,
+ * an interactive legend, loading / refreshing / empty / error states, a generated text summary and
+ * a data-table alternative.
+ *
+ * ```tsx
+ * <Chart title="Visits" data={rows} config={{ visits: { label: "Visits" } }} x="date" height="md">
+ *   <ChartFrame><RAreaChart data={rows}>…</RAreaChart></ChartFrame>
+ * </Chart>
+ * ```
+ */
+export declare function Chart<T extends object>(props: ChartProps<T>): React.JSX.Element;
+export interface ChartLegendContentProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Keys to list. Default: every series of the config. */
+    keys?: string[];
+    /** Click toggles visibility. Default `true`. */
+    interactive?: boolean;
+    /** Swatch shape. Default: a line for line/area patterns, a dot otherwise. */
+    swatch?: "dot" | "line";
+}
+/** The legend: one toggle per series (`aria-pressed`). At least one series always stays visible. */
+export declare function ChartLegendContent({ keys, interactive, swatch, className, ...props }: ChartLegendContentProps): React.JSX.Element;
+/** Swatch used by tooltips and lists: `dot`, `line` or `dashed`. */
+export declare function ChartIndicator({ color, variant, pattern }: {
+    color: string;
+    variant?: "dot" | "line" | "dashed";
+    pattern?: ResolvedSeries["pattern"];
+}): React.JSX.Element;
+/** Chart-shaped loading placeholder (wave, bars, ring or grid) — never a spinner. */
+export declare function ChartSkeleton({ kind, label, className }: {
+    kind?: ChartSkeletonKind;
+    label?: string;
+    className?: string;
+}): React.JSX.Element;
+/** Thin indeterminate bar on top of a chart that is refetching (old data stays, dimmed). */
+export declare function ChartRefreshBar({ label, className }: {
+    label?: string;
+    className?: string;
+}): React.JSX.Element;
+/** Empty state that keeps the chart height: a quiet message and an optional action. */
+export declare function ChartEmpty({ message, action, className }: {
+    message?: React.ReactNode;
+    action?: React.ReactNode;
+    className?: string;
+}): React.JSX.Element;
+/** Error state: icon, message and a retry action. */
+export declare function ChartError({ message, onRetry, retryLabel, className }: {
+    message?: React.ReactNode;
+    onRetry?: () => void;
+    retryLabel?: string;
+    className?: string;
+}): React.JSX.Element;
+export interface ChartDataTableProps extends React.HTMLAttributes<HTMLDivElement> {
+    caption: string;
+    spec: ChartTableSpec;
+    /** Makes each row header a button (drill-down without a pointer). */
+    onRowClick?: (row: Record<string, unknown>) => void;
+}
+/** The accessible alternative of a chart: same numbers, same formatters, as a real `<table>`. */
+export declare function ChartDataTable({ caption, spec, onRowClick, className, ...props }: ChartDataTableProps): React.JSX.Element;
+export { patternDash };

package/dist/charts/chart-shell.js

@@ -0,0 +1,205 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+// The Chart shell — context, legend, states, data-table alternative. No Recharts import here,
+// so SVG/DOM charts (Heatmap) can reuse it without loading the chart library.
+import * as React from "react";
+import { CircleAlert, Table2, ChartColumnBig } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useFormat } from "../lib/locale.js";
+import { useLabels } from "../lib/labels.js";
+import { useControllableState } from "../lib/use-controllable-state.js";
+import { useReducedMotion } from "../lib/use-reduced-motion.js";
+import { Button } from "../components/button.js";
+import { CHART_HEIGHTS, formatCategory, formatValue, patternDash, resolveChartColor, resolveSeries, seriesColor, seriesVarName, summarizeSeries, } from "./utils.js";
+export const chartLabels = {
+    viewTable: "View as table",
+    viewChart: "View as chart",
+    legend: "Series",
+    empty: "No data for this range",
+    error: "This chart couldn't load.",
+    retry: "Try again",
+    loading: "Loading chart…",
+    refreshing: "Updating…",
+    total: "Total",
+    other: "Other",
+    otherCount: "Other ({count})",
+    share: "Share",
+    category: "Category",
+    value: "Value",
+    range: "{from} – {to}.",
+    seriesSummary: "{label}: low {min} ({minAt}), high {max} ({maxAt}), average {avg}.",
+};
+const ChartContext = React.createContext(null);
+/** Chart context: config, formatters and hidden series. Use inside `<Chart>`. */
+export function useChart() {
+    const ctx = React.useContext(ChartContext);
+    if (!ctx)
+        throw new Error("useChart must be used inside <Chart>.");
+    return ctx;
+}
+/** Like `useChart`, but `null` outside a Chart. */
+export const useOptionalChart = () => React.useContext(ChartContext);
+const capitalise = (s) => (s ? s[0].toUpperCase() + s.slice(1) : s);
+/**
+ * The shell every chart shares: series → token colours (`--series-<key>`), locale formatting,
+ * an interactive legend, loading / refreshing / empty / error states, a generated text summary and
+ * a data-table alternative.
+ *
+ * ```tsx
+ * <Chart title="Visits" data={rows} config={{ visits: { label: "Visits" } }} x="date" height="md">
+ *   <ChartFrame><RAreaChart data={rows}>…</RAreaChart></ChartFrame>
+ * </Chart>
+ * ```
+ */
+export function Chart(props) {
+    const { data: dataProp, config, x, xLabel, xFormat, yFormat, height, aspect, state: stateProp, title, summary, tableToggle, legend, tooltipIndicator = "dot", animate = true, onPointClick, hiddenSeries, defaultHiddenSeries, onHiddenSeriesChange, labels, table, aside, asidePosition = "side", skeleton = "area", toolbar, className, style, children, ...rest } = props;
+    const data = dataProp;
+    const f = useFormat();
+    const t = useLabels("chart", chartLabels, labels);
+    const reduced = useReducedMotion();
+    const rawId = React.useId();
+    const idPrefix = `vc${rawId.replace(/[^a-zA-Z0-9]/g, "")}`;
+    const series = React.useMemo(() => resolveSeries(config), [config]);
+    const [hidden, setHidden] = useControllableState({
+        value: hiddenSeries,
+        defaultValue: () => defaultHiddenSeries ?? series.filter((s) => s.hidden).map((s) => s.key),
+        onChange: onHiddenSeriesChange,
+        name: "Chart",
+    });
+    const hiddenSet = React.useMemo(() => new Set(hidden), [hidden]);
+    const visibleSeries = React.useMemo(() => series.filter((s) => !hiddenSet.has(s.key)), [series, hiddenSet]);
+    const toggleSeries = React.useCallback((key) => setHidden((prev) => {
+        if (prev.includes(key))
+            return prev.filter((k) => k !== key);
+        // at least one series stays visible
+        if (series.filter((s) => !prev.includes(s.key)).length <= 1)
+            return prev;
+        return [...prev, key];
+    }), [setHidden, series]);
+    const status = stateProp ?? (data.length === 0 ? { status: "empty" } : { status: "ready" });
+    const [showTable, setShowTable] = React.useState(false);
+    const seriesFormat = React.useCallback((key) => config[key]?.format, [config]);
+    const ctx = React.useMemo(() => ({
+        config,
+        series,
+        visibleSeries,
+        isHidden: (k) => hiddenSet.has(k),
+        toggleSeries,
+        data,
+        x,
+        xFormat,
+        yFormat: yFormat ?? series[0]?.format,
+        formatSeries: (key, v) => formatValue(f, seriesFormat(key), v),
+        formatTick: (v, spec) => formatValue(f, spec ?? yFormat ?? series[0]?.format, v, { compact: true }),
+        formatX: (v, long) => formatCategory(f, xFormat, v, long),
+        f,
+        t,
+        animate: animate && !reduced,
+        tooltipIndicator,
+        onPointClick: onPointClick,
+        height: height === "auto" ? undefined : typeof height === "string" ? CHART_HEIGHTS[height] : height,
+        idPrefix,
+    }), [config, series, visibleSeries, hiddenSet, toggleSeries, data, x, xFormat, yFormat, f, t, animate, reduced, tooltipIndicator, onPointClick, height, idPrefix, seriesFormat]);
+    const vars = React.useMemo(() => {
+        const out = {};
+        for (const s of series)
+            out[seriesVarName(s.key)] = resolveChartColor(s.color);
+        return out;
+    }, [series]);
+    const summaryText = React.useMemo(() => {
+        if (typeof summary === "function")
+            return summary(dataProp);
+        if (typeof summary === "string")
+            return summary;
+        return summarizeSeries({ f, rows: data, series: visibleSeries, x, xFormat, templates: { range: t.labels.range, series: t.labels.seriesSummary } });
+    }, [summary, dataProp, data, f, visibleSeries, x, xFormat, t]);
+    const tableSpec = React.useMemo(() => table ?? {
+        columns: [
+            ...(x ? [{ key: x, label: xLabel ?? capitalise(x), header: true, format: xFormat }] : []),
+            ...series.map((s) => ({ key: s.key, label: s.label, format: s.format })),
+        ],
+        rows: data,
+    }, [table, x, xLabel, xFormat, series, data]);
+    const legendPos = legend ?? (series.length > 1 ? "top" : "none");
+    const summaryId = `${idPrefix}-summary`;
+    const plotHeight = ctx.height;
+    const busy = status.status === "loading" || status.status === "refreshing";
+    const showToolbar = legendPos === "top" || tableToggle || toolbar;
+    let body;
+    if (status.status === "loading")
+        body = _jsx(ChartSkeleton, { kind: skeleton, label: t("loading") });
+    else if (status.status === "empty")
+        body = _jsx(ChartEmpty, { message: status.message ?? t("empty"), action: status.action });
+    else if (status.status === "error")
+        body = _jsx(ChartError, { message: status.message ?? t("error"), onRetry: status.onRetry, retryLabel: t("retry") });
+    else if (showTable)
+        body = _jsx(ChartDataTable, { caption: title, spec: tableSpec, onRowClick: onPointClick ? (row) => onPointClick(row, visibleSeries[0]?.key ?? "") : undefined, className: cn("overflow-auto", height === "auto" ? "max-h-96" : "h-full") });
+    else
+        body = (_jsxs(_Fragment, { children: [status.status === "refreshing" ? _jsx(ChartRefreshBar, { label: t("refreshing") }) : null, _jsx("div", { className: cn("size-full transition-opacity duration-200", status.status === "refreshing" && "opacity-60"), children: children })] }));
+    const plot = (_jsx("div", { "data-slot": "chart-body", "data-state": status.status, "aria-busy": busy || undefined, className: cn("vui-chart-body relative min-w-0", aside && asidePosition === "side" ? "flex-1" : "w-full"), style: height === "auto"
+            ? status.status === "ready" || status.status === "refreshing"
+                ? undefined
+                : { minHeight: CHART_HEIGHTS.sm }
+            : plotHeight !== undefined
+                ? { height: plotHeight }
+                : aspect
+                    ? { aspectRatio: String(aspect) }
+                    : { height: CHART_HEIGHTS.md }, children: body }));
+    return (_jsx(ChartContext.Provider, { value: ctx, children: _jsxs("figure", { "data-slot": "chart", "aria-label": title, "aria-describedby": summaryText ? summaryId : undefined, className: cn("vui-chart m-0 grid min-w-0 gap-3", className), style: { ...vars, ...style }, ...rest, children: [showToolbar ? (_jsxs("div", { "data-slot": "chart-toolbar", className: "flex min-h-7 flex-wrap items-center justify-between gap-x-4 gap-y-2", children: [legendPos === "top" ? _jsx(ChartLegendContent, {}) : _jsx("span", {}), tableToggle || toolbar ? (_jsxs("div", { className: "flex items-center gap-1.5", children: [toolbar, tableToggle ? (_jsxs(Button, { size: "xs", variant: "ghost", "aria-pressed": showTable, onClick: () => setShowTable((v) => !v), className: "text-fg-muted", children: [showTable ? _jsx(ChartColumnBig, { className: "size-3.5" }) : _jsx(Table2, { className: "size-3.5" }), showTable ? t("viewChart") : t("viewTable")] })) : null] })) : null] })) : null, aside ? (_jsx("div", { className: cn("@container"), children: _jsxs("div", { className: cn("flex flex-col gap-5", asidePosition === "side" && "@md:flex-row @md:items-center"), children: [plot, _jsx("div", { "data-slot": "chart-aside", className: cn("min-w-0", asidePosition === "side" && "@md:w-[min(46%,18rem)]"), children: aside })] }) })) : (plot), legendPos === "bottom" ? _jsx(ChartLegendContent, { className: "justify-center" }) : null, summaryText ? (_jsx("p", { id: summaryId, className: "sr-only", children: summaryText })) : null, !showTable && status.status !== "loading" && status.status !== "error" && tableSpec.rows.length ? _jsx(ChartDataTable, { caption: title, spec: tableSpec, className: "sr-only" }) : null] }) }));
+}
+/** The legend: one toggle per series (`aria-pressed`). At least one series always stays visible. */
+export function ChartLegendContent({ keys, interactive = true, swatch, className, ...props }) {
+    const { series, isHidden, toggleSeries, visibleSeries, t } = useChart();
+    const items = keys ? series.filter((s) => keys.includes(s.key)) : series;
+    return (_jsx("div", { role: "group", "aria-label": t("legend"), "data-slot": "chart-legend", className: cn("flex flex-wrap items-center gap-x-1 gap-y-1", className), ...props, children: items.map((s) => {
+            const hidden = isHidden(s.key);
+            const locked = !hidden && visibleSeries.length <= 1;
+            const Icon = s.icon;
+            const content = (_jsxs(_Fragment, { children: [Icon ? _jsx(Icon, { className: "size-3.5" }) : _jsx(LegendSwatch, { color: seriesColor(s.key), pattern: s.pattern, shape: swatch ?? (s.pattern !== "solid" ? "line" : "dot") }), _jsx("span", { className: cn(hidden && "line-through decoration-fg-subtle"), children: s.label })] }));
+            if (!interactive)
+                return (_jsx("span", { className: "inline-flex items-center gap-1.5 px-1.5 text-[12.5px] text-fg-muted", children: content }, s.key));
+            return (_jsx("button", { type: "button", "aria-pressed": !hidden, "aria-disabled": locked || undefined, onClick: () => toggleSeries(s.key), className: cn("inline-flex h-7 items-center gap-1.5 rounded-ui-sm px-2 text-[12.5px] text-fg-muted transition-[color,background-color,opacity] focus-ring hover:bg-hover hover:text-fg", hidden && "opacity-55", locked && "cursor-default hover:bg-transparent"), children: content }, s.key));
+        }) }));
+}
+function LegendSwatch({ color, pattern, shape }) {
+    if (shape === "line")
+        return (_jsx("svg", { width: "14", height: "8", viewBox: "0 0 14 8", "aria-hidden": true, className: "shrink-0", children: _jsx("line", { x1: "1", y1: "4", x2: "13", y2: "4", stroke: color, strokeWidth: "2", strokeLinecap: "round", strokeDasharray: pattern === "dashed" ? "4 3" : pattern === "dotted" ? "0.5 3" : undefined }) }));
+    return _jsx("span", { "aria-hidden": true, className: "size-2 shrink-0 rounded-[3px]", style: { background: color } });
+}
+/** Swatch used by tooltips and lists: `dot`, `line` or `dashed`. */
+export function ChartIndicator({ color, variant = "dot", pattern }) {
+    if (variant === "line" || variant === "dashed")
+        return (_jsx("svg", { width: "12", height: "10", viewBox: "0 0 12 10", "aria-hidden": true, className: "shrink-0", children: _jsx("line", { x1: "1", y1: "5", x2: "11", y2: "5", stroke: color, strokeWidth: "2.25", strokeLinecap: "round", strokeDasharray: variant === "dashed" || pattern === "dashed" ? "3 2.5" : pattern === "dotted" ? "0.5 3" : undefined }) }));
+    return _jsx("span", { "aria-hidden": true, className: "size-2 shrink-0 rounded-[3px]", style: { background: color } });
+}
+/* ------------------------------------------------------------------ */
+/* States                                                              */
+/* ------------------------------------------------------------------ */
+const BAR_HEIGHTS = [42, 64, 50, 78, 58, 88, 70, 54, 82, 66, 92, 60];
+/** Chart-shaped loading placeholder (wave, bars, ring or grid) — never a spinner. */
+export function ChartSkeleton({ kind = "area", label, className }) {
+    return (_jsxs("div", { "data-slot": "chart-skeleton", "data-kind": kind, className: cn("vui-chart-skeleton absolute inset-0 flex", className), children: [label ? (_jsx("span", { role: "status", className: "sr-only", children: label })) : null, kind === "bar" ? (_jsx("div", { "aria-hidden": true, className: "flex size-full items-end gap-[3%] ps-10 pb-6", children: BAR_HEIGHTS.map((h, i) => (_jsx("div", { className: "ui-shimmer flex-1 rounded-t-[4px] bg-skeleton", style: { height: `${h}%` } }, i))) })) : kind === "bar-horizontal" ? (_jsx("div", { "aria-hidden": true, className: "flex size-full flex-col justify-around gap-2 py-2 ps-20", children: [92, 76, 64, 50, 38, 26].map((w, i) => (_jsx("div", { className: "ui-shimmer h-[9%] min-h-2 rounded-e-[4px] bg-skeleton", style: { width: `${w}%` } }, i))) })) : kind === "donut" ? (_jsx("div", { "aria-hidden": true, className: "grid size-full place-items-center", children: _jsx("div", { className: "vui-chart-skeleton-ring ui-shimmer aspect-square h-[82%] max-h-full rounded-full bg-skeleton" }) })) : kind === "grid" ? (_jsx("div", { "aria-hidden": true, className: "vui-chart-skeleton-grid ui-shimmer size-full rounded-ui-sm" })) : (_jsx("div", { "aria-hidden": true, className: "flex size-full flex-col ps-10 pb-6", children: _jsx("div", { className: cn("ui-shimmer mt-auto h-[78%] w-full bg-skeleton", kind === "line" ? "vui-chart-skeleton-line" : "vui-chart-skeleton-wave") }) }))] }));
+}
+/** Thin indeterminate bar on top of a chart that is refetching (old data stays, dimmed). */
+export function ChartRefreshBar({ label, className }) {
+    return (_jsxs("div", { "data-slot": "chart-refresh", className: cn("absolute inset-x-0 top-0 z-10 h-0.5 overflow-hidden rounded-full bg-track", className), children: [label ? (_jsx("span", { role: "status", className: "sr-only", children: label })) : null, _jsx("div", { "aria-hidden": true, className: "vui-chart-refresh-bar h-full w-2/5 rounded-full bg-accent-ink" })] }));
+}
+/** Empty state that keeps the chart height: a quiet message and an optional action. */
+export function ChartEmpty({ message, action, className }) {
+    return (_jsxs("div", { "data-slot": "chart-empty", className: cn("absolute inset-0 grid place-items-center", className), children: [_jsx("div", { "aria-hidden": true, className: "vui-chart-empty-grid absolute inset-0" }), _jsxs("div", { className: "relative flex flex-col items-center gap-2.5 px-6 text-center", children: [_jsx("p", { className: "text-[13px] text-fg-muted", children: message }), action] })] }));
+}
+/** Error state: icon, message and a retry action. */
+export function ChartError({ message, onRetry, retryLabel = "Try again", className }) {
+    return (_jsx("div", { "data-slot": "chart-error", role: "alert", className: cn("absolute inset-0 grid place-items-center", className), children: _jsxs("div", { className: "flex flex-col items-center gap-2.5 px-6 text-center", children: [_jsx(CircleAlert, { "aria-hidden": true, className: "size-5 text-danger" }), _jsx("p", { className: "max-w-xs text-[13px] text-fg-muted", children: message }), onRetry ? (_jsx(Button, { size: "sm", onClick: onRetry, children: retryLabel })) : null] }) }));
+}
+/** The accessible alternative of a chart: same numbers, same formatters, as a real `<table>`. */
+export function ChartDataTable({ caption, spec, onRowClick, className, ...props }) {
+    const f = useFormat();
+    return (_jsx("div", { "data-slot": "chart-table", className: cn("min-w-0", className), ...props, children: _jsxs("table", { className: "w-full border-collapse text-[13px]", children: [_jsx("caption", { className: "sr-only", children: caption }), _jsx("thead", { children: _jsx("tr", { children: spec.columns.map((c, i) => (_jsx("th", { scope: "col", className: cn("sticky top-0 z-[1] border-b border-line bg-[var(--chart-tooltip)] px-3 py-2 text-[12px] font-medium whitespace-nowrap text-fg-muted", i === 0 ? "text-start" : "text-end"), children: c.label }, c.key))) }) }), _jsx("tbody", { children: spec.rows.map((row, ri) => (_jsx("tr", { className: "border-b border-line last:border-b-0", children: spec.columns.map((c, ci) => {
+                            const text = c.header ? formatCategory(f, c.format, row[c.key], true) : formatValue(f, c.format, row[c.key]);
+                            if (ci === 0 || c.header)
+                                return (_jsx("th", { scope: "row", className: "px-3 py-1.5 text-start font-normal whitespace-nowrap text-fg", children: onRowClick ? (_jsx("button", { type: "button", onClick: () => onRowClick(row), className: "rounded-ui-sm text-start text-accent-ink underline-offset-4 focus-ring hover:underline", children: text })) : (text) }, c.key));
+                            return (_jsx("td", { className: "px-3 py-1.5 text-end font-mono text-[12.5px] whitespace-nowrap text-fg tabular", children: text }, c.key));
+                        }) }, ri))) })] }) }));
+}
+export { patternDash };

package/dist/charts/chart.d.ts

@@ -0,0 +1,73 @@
+import * as React from "react";
+import { type CartesianGridProps, type ReferenceLineProps, type TooltipProps, type TooltipValueType as ValueType, type XAxisProps, type YAxisProps } from "recharts";
+import type { NameType } from "recharts/types/component/DefaultTooltipContent";
+import { type ChartColor, type FormatSpec } from "./utils.js";
+export interface ChartFrameProps {
+    /** One Recharts chart element (`<RAreaChart data={…}>…</RAreaChart>`). */
+    children: React.ReactElement;
+    className?: string;
+}
+/**
+ * Sizes a Recharts chart to the Chart body (height from `height` / `aspect` on `<Chart>`), so the
+ * first paint never shifts layout. Use it for raw Recharts inside `<Chart>`.
+ */
+export declare function ChartFrame({ children, className }: ChartFrameProps): React.JSX.Element;
+interface TooltipEntry {
+    dataKey?: unknown;
+    name?: unknown;
+    value?: unknown;
+    type?: string;
+    payload?: unknown;
+}
+export interface ChartTooltipContentProps {
+    /** Injected by Recharts. */
+    active?: boolean;
+    /** Injected by Recharts. */
+    payload?: readonly TooltipEntry[];
+    /** Injected by Recharts. */
+    label?: unknown;
+    indicator?: "dot" | "line" | "dashed";
+    /** Adds a total row (stacked charts). */
+    showTotal?: boolean;
+    /** Percent-stacked charts: show each value's share next to it. */
+    showShare?: boolean;
+    hideLabel?: boolean;
+    /** Custom header text. */
+    labelFormatter?: (label: unknown, payload: readonly TooltipEntry[]) => React.ReactNode;
+    className?: string;
+}
+/**
+ * Tooltip body: opaque `--chart-tooltip` surface (no blur — it re-renders on every pointer move),
+ * formatted header, one row per visible series, optional total.
+ */
+export declare function ChartTooltipContent({ active, payload, label, indicator, showTotal, showShare, hideLabel, labelFormatter, className }: ChartTooltipContentProps): React.JSX.Element | null;
+export type ChartTooltipProps = Omit<TooltipProps<ValueType, NameType>, "content" | "labelFormatter"> & Pick<ChartTooltipContentProps, "indicator" | "showTotal" | "showShare" | "hideLabel" | "labelFormatter">;
+/** Recharts Tooltip wired to `ChartTooltipContent` and the themed cursor. */
+export declare function ChartTooltip({ indicator, showTotal, showShare, hideLabel, labelFormatter, cursor, ...props }: ChartTooltipProps): React.JSX.Element;
+/** Horizontal grid lines in `--chart-grid`. */
+export declare function ChartGrid(props: CartesianGridProps): React.JSX.Element;
+/** Category / time axis: no lines, axis-coloured ticks, density-aware gaps, formatted with `xFormat`. */
+export declare function ChartXAxis({ tickFormatter, ...props }: XAxisProps): React.JSX.Element;
+/** Value axis with compact ticks ("$1.2M") and a width measured from the longest tick. */
+export declare function ChartYAxis({ format, keys, stacked, tickFormatter, width: widthProp, ...props }: YAxisProps & {
+    format?: FormatSpec;
+    keys?: string[];
+    stacked?: boolean;
+}): React.JSX.Element;
+/** A labelled reference line (target, average). Colour is a token. */
+export declare function ChartReferenceLine({ color, label, labelPosition, ...props }: Omit<ReferenceLineProps, "label"> & {
+    color?: ChartColor;
+    label?: string;
+    labelPosition?: "above" | "below";
+}): React.JSX.Element;
+/** Width for a value axis: estimated from every tick it could draw. */
+export declare function useValueAxisWidth(keys: string[], o?: {
+    stacked?: boolean;
+    format?: FormatSpec;
+    percent?: boolean;
+}): number;
+/** Recharts `onClick` → `onPointClick(row, seriesKey)` from the active tooltip index. */
+export declare function usePointClick(seriesKey?: string): ((state: {
+    activeTooltipIndex?: unknown;
+} | null) => void) | undefined;
+export {};

package/dist/charts/chart.js

@@ -0,0 +1,106 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Recharts parts of the Chart frame: responsive plot, themed tooltip, axes and grid.
+import * as React from "react";
+import { CartesianGrid, ReferenceLine, ResponsiveContainer, Tooltip, XAxis, YAxis, } from "recharts";
+import { cn } from "../lib/cn.js";
+import { ChartIndicator, useChart, useOptionalChart } from "./chart-shell.js";
+import { estimateAxisWidth, extent, formatValue, niceCeil, niceStep, resolveChartColor, seriesColor } from "./utils.js";
+/**
+ * Sizes a Recharts chart to the Chart body (height from `height` / `aspect` on `<Chart>`), so the
+ * first paint never shifts layout. Use it for raw Recharts inside `<Chart>`.
+ */
+export function ChartFrame({ children, className }) {
+    return (_jsx("div", { "data-slot": "chart-frame", className: cn("size-full min-w-0", className), children: _jsx(ResponsiveContainer, { width: "100%", height: "100%", minWidth: 0, children: children }) }));
+}
+/**
+ * Tooltip body: opaque `--chart-tooltip` surface (no blur — it re-renders on every pointer move),
+ * formatted header, one row per visible series, optional total.
+ */
+export function ChartTooltipContent({ active, payload, label, indicator, showTotal, showShare, hideLabel, labelFormatter, className }) {
+    const chart = useOptionalChart();
+    if (!active || !payload?.length || !chart)
+        return null;
+    const rows = payload.filter((p) => p.dataKey !== undefined && !chart.isHidden(String(p.dataKey)) && p.type !== "none");
+    if (!rows.length)
+        return null;
+    const ind = indicator ?? chart.tooltipIndicator;
+    const raw = (rows[0]?.payload ?? {});
+    const header = hideLabel ? null : labelFormatter ? labelFormatter(label, rows) : chart.formatX(chart.x ? raw[chart.x] : label, true);
+    const numeric = (k) => {
+        const v = Number(raw[k]);
+        return Number.isFinite(v) ? v : 0;
+    };
+    const total = rows.reduce((sum, p) => sum + numeric(String(p.dataKey)), 0);
+    return (_jsxs("div", { "data-slot": "chart-tooltip", className: cn("vui-chart-tooltip min-w-36 rounded-ui-sm px-2.5 py-2 text-[12px]", className), children: [header ? _jsx("div", { className: "mb-1.5 font-medium text-fg", children: header }) : null, _jsxs("div", { className: "grid gap-1", children: [rows.map((p) => {
+                        const key = String(p.dataKey);
+                        const s = chart.series.find((x) => x.key === key);
+                        return (_jsxs("div", { className: "flex items-center gap-2", children: [_jsx(ChartIndicator, { color: seriesColor(key), variant: ind, pattern: s?.pattern }), _jsx("span", { className: "me-auto text-fg-muted", children: s?.label ?? String(p.name ?? key) }), _jsx("span", { className: "font-mono text-fg tabular", children: chart.formatSeries(key, raw[key] ?? p.value) }), showShare && total ? _jsx("span", { className: "w-11 text-end font-mono text-fg-subtle tabular", children: chart.f.percent(numeric(key) / total) }) : null] }, key));
+                    }), showTotal && rows.length > 1 ? (_jsxs("div", { className: "mt-0.5 flex items-center gap-2 border-t border-line pt-1.5", children: [_jsx("span", { className: "me-auto text-fg-muted", children: chart.t("total") }), _jsx("span", { className: "font-mono font-medium text-fg tabular", children: chart.formatSeries(String(rows[0]?.dataKey), total) })] })) : null] })] }));
+}
+/** Recharts Tooltip wired to `ChartTooltipContent` and the themed cursor. */
+export function ChartTooltip({ indicator, showTotal, showShare, hideLabel, labelFormatter, cursor, ...props }) {
+    return (_jsx(Tooltip, { isAnimationActive: false, cursor: cursor ?? { stroke: "var(--chart-cursor)", strokeWidth: 1 }, content: _jsx(ChartTooltipContent, { indicator: indicator, showTotal: showTotal, showShare: showShare, hideLabel: hideLabel, labelFormatter: labelFormatter }), ...props }));
+}
+/* ------------------------------------------------------------------ */
+/* Axes & grid                                                         */
+/* ------------------------------------------------------------------ */
+const TICK = { fill: "var(--chart-axis)" };
+/** Horizontal grid lines in `--chart-grid`. */
+export function ChartGrid(props) {
+    return _jsx(CartesianGrid, { stroke: "var(--chart-grid)", vertical: false, ...props });
+}
+/** Category / time axis: no lines, axis-coloured ticks, density-aware gaps, formatted with `xFormat`. */
+export function ChartXAxis({ tickFormatter, ...props }) {
+    const chart = useChart();
+    return (_jsx(XAxis, { dataKey: chart.x, tickLine: false, axisLine: false, tick: TICK, tickMargin: 8, minTickGap: 18, interval: "preserveStartEnd", tickFormatter: tickFormatter ?? ((v) => chart.formatX(v)), ...props }));
+}
+/** Value axis with compact ticks ("$1.2M") and a width measured from the longest tick. */
+export function ChartYAxis({ format, keys, stacked, tickFormatter, width: widthProp, ...props }) {
+    const chart = useChart();
+    const axisKeys = keys ?? chart.visibleSeries.map((s) => s.key);
+    const width = useValueAxisWidth(axisKeys, { stacked, format });
+    const compactFrom = axisCompactFrom(extent(chart.data, axisKeys, stacked));
+    const fallback = (v) => formatValue(chart.f, format ?? chart.yFormat, v, { compact: true, compactFrom });
+    return _jsx(YAxis, { niceTicks: "snap125", tickLine: false, axisLine: false, tick: TICK, tickMargin: 6, width: widthProp ?? width, tickFormatter: tickFormatter ?? fallback, ...props });
+}
+/** A labelled reference line (target, average). Colour is a token. */
+export function ChartReferenceLine({ color = "fg-subtle", label, labelPosition = "below", ...props }) {
+    return (_jsx(ReferenceLine, { stroke: resolveChartColor(color), strokeDasharray: "4 4", strokeWidth: 1, ifOverflow: "extendDomain", label: label ? { value: label, position: labelPosition === "above" ? "insideBottomRight" : "insideTopRight", fill: resolveChartColor(color === "fg-subtle" ? "fg-muted" : color), fontSize: 11 } : undefined, ...props }));
+}
+/** Once the top tick reaches 10K, every tick ≥ 1000 is compact too ("5K" next to "10K", never "5,000"). */
+function axisCompactFrom([lo, hi]) {
+    return Math.max(niceCeil(Math.abs(hi)), niceCeil(Math.abs(lo))) >= 10000 ? 1000 : 10000;
+}
+/** Width for a value axis: estimated from every tick it could draw. */
+export function useValueAxisWidth(keys, o = {}) {
+    const chart = useChart();
+    return React.useMemo(() => {
+        if (o.percent)
+            return estimateAxisWidth([chart.f.percent(1)]);
+        const [min, max] = extent(chart.data, keys, o.stacked);
+        const compactFrom = axisCompactFrom([min, max]);
+        // Format every tick the axis could draw (snap125 may stop at 800K while niceCeil says 1M).
+        const lo = Math.min(0, min);
+        const hi = Math.max(0, max);
+        const step = niceStep((hi - lo) / 4) || 1;
+        const values = [niceCeil(Math.abs(hi)), lo < 0 ? -niceCeil(-lo) : 0];
+        for (let v = Math.floor(lo / step) * step, i = 0; v <= hi + step && i < 24; v += step, i++)
+            values.push(Number(v.toPrecision(12)));
+        return estimateAxisWidth(values.map((v) => formatValue(chart.f, o.format ?? chart.yFormat, v, { compact: true, compactFrom })));
+    }, [chart.data, chart.f, chart.yFormat, keys, o.stacked, o.format, o.percent]);
+}
+/** Recharts `onClick` → `onPointClick(row, seriesKey)` from the active tooltip index. */
+export function usePointClick(seriesKey) {
+    const chart = useChart();
+    return React.useMemo(() => {
+        if (!chart.onPointClick)
+            return undefined;
+        return (state) => {
+            const i = Number(state?.activeTooltipIndex);
+            const row = Number.isInteger(i) ? chart.data[i] : undefined;
+            if (row)
+                chart.onPointClick?.(row, seriesKey ?? chart.visibleSeries[0]?.key ?? "");
+        };
+    }, [chart, seriesKey]);
+}

package/dist/charts/combo-chart.d.ts

@@ -0,0 +1,29 @@
+import * as React from "react";
+import { type ChartProps } from "./chart-shell.js";
+import { type FormatSpec } from "./utils.js";
+export interface ComboChartProps<T extends object> extends Omit<ChartProps<T>, "children"> {
+    /** Keys drawn as bars (default axis: start). */
+    bars: string[];
+    /** Keys drawn as lines (default axis: end). */
+    lines: string[];
+    /** Keys drawn as filled areas behind the bars. */
+    areas?: string[];
+    /** Format of the end axis. Default: the first end-axis series' format. */
+    endAxisFormat?: FormatSpec;
+    /** Show the end axis. Hidden: values still appear in the tooltip and table. Default `true`. */
+    endAxis?: boolean;
+    /** Stack the bars. */
+    stackBars?: boolean;
+    /** Axis titles (label + unit) — recommended, two value scales need naming. */
+    startAxisLabel?: string;
+    endAxisLabel?: string;
+}
+/**
+ * Volume and rate on two axes — bars on the start axis, a line on the end axis, zero lines aligned
+ * so neither scale exaggerates. Axis sides are logical and swap in RTL.
+ *
+ * ```tsx
+ * <ComboChart title="Quotes and win rate" data={rows} x="month" bars={["quotes"]} lines={["winRate"]} config={config} />
+ * ```
+ */
+export declare function ComboChart<T extends object>({ bars, lines, areas, endAxisFormat, endAxis, stackBars, startAxisLabel, endAxisLabel, ...props }: ComboChartProps<T>): React.JSX.Element;