@vamos-ui/react 0.0.0-stage → 0.2.0

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;

package/dist/charts/combo-chart.js

@@ -0,0 +1,47 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Area, Bar, ComposedChart, Line } from "recharts";
+import { useLocale } from "../lib/locale.js";
+import { Chart, useChart } from "./chart-shell.js";
+import { ChartFrame, ChartGrid, ChartTooltip, ChartXAxis, ChartYAxis, useValueAxisWidth } from "./chart.js";
+import { alignZeroDomains, extent, patternDash, seriesColor } from "./utils.js";
+/**
+ * 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 function ComboChart({ bars, lines, areas = [], endAxisFormat, endAxis = true, stackBars, startAxisLabel, endAxisLabel, ...props }) {
+    return (_jsx(Chart, { skeleton: "bar", ...props, children: _jsx(ComboPlot, { bars: bars, lines: lines, areas: areas, endAxisFormat: endAxisFormat, endAxis: endAxis, stackBars: stackBars, startAxisLabel: startAxisLabel, endAxisLabel: endAxisLabel }) }));
+}
+function ComboPlot({ bars, lines, areas = [], endAxisFormat, endAxis, stackBars, startAxisLabel, endAxisLabel }) {
+    const chart = useChart();
+    const rtl = useLocale().dir === "rtl";
+    const axisOf = (key, fallback) => chart.config[key]?.axis ?? fallback;
+    const visible = (k) => !chart.isHidden(k);
+    const startKeys = [...bars.filter((k) => axisOf(k, "start") === "start"), ...lines.filter((k) => axisOf(k, "end") === "start"), ...areas.filter((k) => axisOf(k, "start") === "start")].filter(visible);
+    const endKeys = [...bars.filter((k) => axisOf(k, "start") === "end"), ...lines.filter((k) => axisOf(k, "end") === "end"), ...areas.filter((k) => axisOf(k, "start") === "end")].filter(visible);
+    const startStacked = Boolean(stackBars);
+    const endFormat = endAxisFormat ?? chart.config[endKeys[0] ?? ""]?.format;
+    const startFormat = chart.config[startKeys[0] ?? ""]?.format ?? chart.yFormat;
+    const [startDomain, endDomain] = React.useMemo(() => {
+        const a = extent(chart.data, startKeys, startStacked);
+        const b = extent(chart.data, endKeys);
+        return alignZeroDomains(a, b);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [chart.data, startKeys.join(), endKeys.join(), startStacked]);
+    // Non-negative data: four equal steps on both axes, so the grid lines serve both scales.
+    const ticksOf = (d) => (d[0] === 0 ? [0, 1, 2, 3, 4].map((i) => Number(((d[1] * i) / 4).toPrecision(12))) : undefined);
+    const startWidth = useValueAxisWidth(startKeys, { stacked: startStacked, format: startFormat });
+    const endWidth = useValueAxisWidth(endKeys, { format: endFormat });
+    const left = rtl ? "end" : "start";
+    const yId = (key, fallback) => axisOf(key, fallback);
+    const titleProps = (value, side) => value ? { value, angle: -90, position: side === "left" ? "insideLeft" : "insideRight", className: "vui-chart-axis-title", offset: 0, style: { textAnchor: "middle" } } : undefined;
+    return (_jsx(ChartFrame, { children: _jsxs(ComposedChart, { data: chart.data, margin: { top: 8, right: 4, bottom: 0, left: 4 }, barCategoryGap: "30%", children: [_jsx(ChartGrid, { yAxisId: "start" }), _jsx(ChartXAxis, {}), _jsx(ChartYAxis, { yAxisId: "start", orientation: left === "start" ? "left" : "right", domain: startDomain, ticks: ticksOf(startDomain), width: startWidth + (startAxisLabel ? 16 : 0), tickFormatter: (v) => chart.formatTick(v, startFormat), label: titleProps(startAxisLabel, left === "start" ? "left" : "right"), keys: startKeys }), _jsx(ChartYAxis, { yAxisId: "end", orientation: left === "start" ? "right" : "left", domain: endDomain, ticks: ticksOf(endDomain), hide: !endAxis || endKeys.length === 0, width: endWidth + (endAxisLabel ? 16 : 0), tickFormatter: (v) => chart.formatTick(v, endFormat), label: titleProps(endAxisLabel, left === "start" ? "right" : "left"), keys: endKeys }), _jsx(ChartTooltip, { cursor: { fill: "var(--hover)" } }), areas.map((key) => (_jsx(Area, { yAxisId: yId(key, "start"), dataKey: key, name: chart.config[key]?.label, hide: chart.isHidden(key), type: "monotone", stroke: seriesColor(key), strokeWidth: 1.5, fill: `color-mix(in oklch, ${seriesColor(key)} 16%, transparent)`, isAnimationActive: chart.animate }, key))), bars.map((key, i) => (_jsx(Bar, { yAxisId: yId(key, "start"), dataKey: key, name: chart.config[key]?.label, hide: chart.isHidden(key), stackId: stackBars ? "bars" : undefined, fill: seriesColor(key), radius: stackBars && i < bars.length - 1 ? 0 : [4, 4, 0, 0], maxBarSize: 40, isAnimationActive: chart.animate }, key))), lines.map((key) => {
+                    const s = chart.series.find((x) => x.key === key);
+                    return (_jsx(Line, { yAxisId: yId(key, "end"), dataKey: key, name: s?.label, hide: chart.isHidden(key), type: "monotone", stroke: seriesColor(key), strokeWidth: 2, strokeDasharray: patternDash(s?.pattern), dot: { r: 2.5, fill: seriesColor(key), stroke: "var(--chart-tooltip)", strokeWidth: 1.5 }, activeDot: { r: 4, strokeWidth: 2, stroke: "var(--chart-tooltip)", fill: seriesColor(key) }, isAnimationActive: chart.animate }, key));
+                })] }) }));
+}

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

@@ -0,0 +1,33 @@
+import * as React from "react";
+import { type ChartProps } from "./chart-shell.js";
+import { type FormatSpec } from "./utils.js";
+export interface DonutChartProps<T extends object> extends Omit<ChartProps<T>, "children" | "x" | "legend" | "height" | "aspect" | "aside" | "table"> {
+    /** Row key holding the slice id (matches config keys). */
+    nameKey: keyof T & string;
+    /** Row key holding the slice value. */
+    valueKey: keyof T & string;
+    /** Centre content: the visible total (default), your own node, or nothing. Hovering a slice shows that slice. */
+    center?: React.ReactNode | "total" | "none";
+    /** Label under the centre total. Default "Total". */
+    centerLabel?: string;
+    /** Slices beyond this count merge into "Other" (`fg-subtle`). Default 5. */
+    maxSlices?: number;
+    variant?: "donut" | "pie" | "half";
+    /** Legend list with value + share: beside the ring (default), under it, or none. */
+    legend?: "side" | "bottom" | "none";
+    size?: "sm" | "md" | "lg" | number;
+    /** Format of the values. Default: the first config entry's format, else `"number"`. */
+    format?: FormatSpec;
+    /** Controlled active slice (hover / legend focus). */
+    activeKey?: string | null;
+    onActiveChange?: (key: string | null) => void;
+}
+/**
+ * Parts of a whole (≤ 6 slices). The legend is a real list with value and share, so the chart never
+ * relies on colour alone; focusing an item highlights its slice and the centre shows its numbers.
+ *
+ * ```tsx
+ * <DonutChart title="Leads by source" data={rows} nameKey="source" valueKey="leads" config={{ organic: { label: "Organic search" } }} />
+ * ```
+ */
+export declare function DonutChart<T extends object>({ data, nameKey, valueKey, config, center, centerLabel, maxSlices, variant, legend, size, format, activeKey, onActiveChange, summary, ...props }: DonutChartProps<T>): React.JSX.Element;

package/dist/charts/donut-chart.js

@@ -0,0 +1,113 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { Cell, Pie, PieChart, Sector } from "recharts";
+import { cn } from "../lib/cn.js";
+import { useControllableState } from "../lib/use-controllable-state.js";
+import { useLabels } from "../lib/labels.js";
+import { Chart, ChartIndicator, chartLabels, useChart } from "./chart-shell.js";
+import { useFormat } from "../lib/locale.js";
+import { formatValue, seriesColor } from "./utils.js";
+const SIZES = { sm: 120, md: 180, lg: 240 };
+const OTHER_KEY = "__other";
+/**
+ * Parts of a whole (≤ 6 slices). The legend is a real list with value and share, so the chart never
+ * relies on colour alone; focusing an item highlights its slice and the centre shows its numbers.
+ *
+ * ```tsx
+ * <DonutChart title="Leads by source" data={rows} nameKey="source" valueKey="leads" config={{ organic: { label: "Organic search" } }} />
+ * ```
+ */
+export function DonutChart({ data, nameKey, valueKey, config, center = "total", centerLabel, maxSlices = 5, variant = "donut", legend = "side", size = "md", format, activeKey, onActiveChange, summary, ...props }) {
+    const rows = data;
+    const f = useFormat();
+    const t = useLabels("chart", chartLabels, props.labels);
+    const valueFormat = format ?? Object.values(config)[0]?.format;
+    const [active, setActive] = useControllableState({ value: activeKey, defaultValue: null, onChange: onActiveChange, name: "DonutChart" });
+    const px = typeof size === "number" ? size : SIZES[size];
+    const height = variant === "half" ? Math.round(px / 2) + 10 : px;
+    const { slices, effectiveConfig } = React.useMemo(() => {
+        const raw = rows.map((r) => ({ key: String(r[nameKey]), value: Math.max(0, Number(r[valueKey]) || 0) }));
+        let list = raw;
+        if (raw.length > maxSlices) {
+            const sorted = [...raw].sort((a, b) => b.value - a.value);
+            const keep = new Set(sorted.slice(0, maxSlices - 1).map((s) => s.key));
+            const rest = raw.filter((s) => !keep.has(s.key));
+            list = [...raw.filter((s) => keep.has(s.key)), { key: OTHER_KEY, value: rest.reduce((s, r) => s + r.value, 0) }];
+        }
+        const cfg = {};
+        for (const s of list)
+            cfg[s.key] = s.key === OTHER_KEY ? { label: config[OTHER_KEY]?.label ?? "", color: "fg-subtle", format } : { ...config[s.key], label: config[s.key]?.label ?? s.key, format: valueFormat };
+        return { slices: list, effectiveConfig: cfg };
+    }, [rows, nameKey, valueKey, maxSlices, config, valueFormat]);
+    const total = slices.reduce((s, r) => s + r.value, 0);
+    const otherLabel = t("other");
+    const labelOf = (k) => (k === OTHER_KEY ? effectiveConfig[k]?.label || otherLabel : (effectiveConfig[k]?.label ?? k));
+    const table = {
+        columns: [
+            { key: "label", label: t("category"), header: true },
+            { key: "value", label: t("value"), format: valueFormat },
+            { key: "share", label: t("share"), format: "percent" },
+        ],
+        rows: slices.map((s) => ({ label: labelOf(s.key), value: s.value, share: total ? s.value / total : 0 })),
+    };
+    const summaryText = summary ?? (total ? slices.map((s) => `${labelOf(s.key)} ${f.percent(s.value / total)} (${formatValue(f, valueFormat, s.value)})`).join(", ") + "." : "");
+    const ctx = React.useMemo(() => ({ active, setActive, raw: slices }), [active, setActive, slices]);
+    return (_jsx(DonutContext.Provider, { value: ctx, children: _jsx(Chart, { ...props, data: slices, config: effectiveConfig, height: height, legend: "none", skeleton: "donut", summary: summaryText, table: table, state: props.state ?? (rows.length === 0 ? { status: "empty" } : undefined), aside: legend === "none" ? undefined : _jsx(DonutLegend, {}), asidePosition: legend === "bottom" ? "bottom" : "side", children: _jsx(DonutPlot, { px: px, height: height, variant: variant, center: center, centerLabel: centerLabel }) }) }));
+}
+const DonutContext = React.createContext(null);
+const useDonut = () => React.useContext(DonutContext);
+function useSlices(slices) {
+    const chart = useChart();
+    return React.useMemo(() => {
+        const visible = slices.filter((s) => !chart.isHidden(s.key));
+        const total = visible.reduce((s, r) => s + r.value, 0);
+        return slices.map((s) => ({
+            key: s.key,
+            label: s.key === OTHER_KEY ? chart.config[s.key]?.label || chart.t("other") : (chart.config[s.key]?.label ?? s.key),
+            value: s.value,
+            share: total && !chart.isHidden(s.key) ? s.value / total : 0,
+        }));
+    }, [slices, chart]);
+}
+function DonutPlot({ px, height, variant, center, centerLabel, }) {
+    const chart = useChart();
+    const { active, setActive, raw } = useDonut();
+    const slices = useSlices(raw);
+    const visible = slices.filter((s) => !chart.isHidden(s.key) && s.value > 0);
+    const total = visible.reduce((s, r) => s + r.value, 0);
+    const half = variant === "half";
+    const outer = half ? px / 2 - 4 : px / 2 - 4;
+    const inner = variant === "pie" ? 0 : outer * (px < 140 ? 0.66 : 0.72);
+    const activeSlice = active ? slices.find((s) => s.key === active && !chart.isHidden(s.key)) : undefined;
+    const fmt = (v) => chart.formatSeries(raw[0]?.key ?? "", v);
+    let centerNode = null;
+    if (variant !== "pie" && center !== "none") {
+        if (activeSlice)
+            centerNode = (_jsxs(_Fragment, { children: [_jsx("span", { className: "max-w-[80%] truncate text-[11.5px] text-fg-muted", children: activeSlice.label }), _jsx("span", { className: cn("font-mono leading-none font-medium tracking-[-0.02em] text-fg tabular", px >= 180 ? "text-[22px]" : "text-[17px]"), children: fmt(activeSlice.value) }), _jsx("span", { className: "font-mono text-[11.5px] text-fg-subtle tabular", children: chart.f.percent(activeSlice.share) })] }));
+        else if (center === "total" || center === undefined)
+            centerNode = (_jsxs(_Fragment, { children: [_jsx("span", { className: cn("font-mono leading-none font-medium tracking-[-0.02em] text-fg tabular", px >= 180 ? "text-[24px]" : "text-[17px]"), children: fmt(total) }), _jsx("span", { className: "text-[11.5px] text-fg-muted", children: centerLabel ?? chart.t("total") })] }));
+        else
+            centerNode = center;
+    }
+    const shape = (p) => {
+        const key = String(p.payload?.key ?? "");
+        const isActive = key === active;
+        const dim = active && !isActive;
+        const { key: _key, ...sector } = p;
+        void _key;
+        return _jsx(Sector, { ...sector, outerRadius: (p.outerRadius ?? outer) + (isActive ? 4 : 0), fillOpacity: dim ? 0.45 : 1, style: { transition: "fill-opacity 160ms" } });
+    };
+    return (_jsx("div", { className: "flex size-full items-center justify-center", onMouseLeave: () => setActive(null), children: _jsxs("div", { className: "relative", style: { width: px, height }, children: [_jsx(PieChart, { width: px, height: height, accessibilityLayer: false, margin: { top: 0, right: 0, bottom: 0, left: 0 }, children: total === 0 ? (_jsx(Pie, { data: [{ key: "empty", value: 1 }], dataKey: "value", cx: "50%", cy: half ? height - 6 : "50%", innerRadius: inner, outerRadius: outer, startAngle: half ? 180 : 90, endAngle: half ? 0 : -270, stroke: "none", isAnimationActive: false, rootTabIndex: -1, children: _jsx(Cell, { fill: "var(--track)" }) })) : (_jsx(Pie, { data: visible, dataKey: "value", nameKey: "label", cx: "50%", cy: half ? height - 6 : "50%", innerRadius: inner, outerRadius: outer, startAngle: half ? 180 : 90, endAngle: half ? 0 : -270, paddingAngle: visible.length > 1 ? (variant === "pie" ? 0.8 : 1.6) : 0, cornerRadius: variant === "pie" ? 0 : 3, stroke: variant === "pie" ? "var(--chart-tooltip)" : "none", strokeWidth: variant === "pie" ? 1.5 : 0, shape: shape, isAnimationActive: chart.animate, animationDuration: 600, rootTabIndex: -1, onMouseEnter: (d) => setActive(d.payload?.key ?? null), children: visible.map((s) => (_jsx(Cell, { fill: seriesColor(s.key) }, s.key))) })) }), centerNode ? (_jsx("div", { "aria-hidden": true, className: cn("pointer-events-none absolute inset-x-0 flex flex-col items-center gap-1 text-center", half ? "bottom-1.5" : "inset-y-0 justify-center"), children: total === 0 && !activeSlice ? _jsx("span", { className: "text-[12px] text-fg-muted", children: chart.t("empty") }) : centerNode })) : null] }) }));
+}
+/** Legend list for a donut: a `<ul>` with swatch, label, value and share. Click hides a slice; focus highlights it. */
+function DonutLegend() {
+    const chart = useChart();
+    const { active, setActive, raw } = useDonut();
+    const slices = useSlices(raw);
+    return (_jsx("ul", { "data-slot": "donut-legend", "aria-label": chart.t("legend"), className: "grid gap-0.5", children: slices.map((s) => {
+            const hidden = chart.isHidden(s.key);
+            const locked = !hidden && chart.visibleSeries.length <= 1;
+            return (_jsx("li", { children: _jsxs("button", { type: "button", "aria-pressed": !hidden, "aria-disabled": locked || undefined, onClick: () => chart.toggleSeries(s.key), onFocus: () => setActive(hidden ? null : s.key), onBlur: () => setActive(null), onMouseEnter: () => setActive(hidden ? null : s.key), onMouseLeave: () => setActive(null), className: cn("flex h-8 w-full items-center gap-2.5 rounded-ui-sm px-2 text-start text-[13px] transition-[background-color,opacity] focus-ring hover:bg-hover", active === s.key && "bg-hover", hidden && "opacity-50"), children: [_jsx(ChartIndicator, { color: seriesColor(s.key) }), _jsx("span", { className: cn("me-auto truncate text-fg", hidden && "line-through decoration-fg-subtle"), children: s.label }), _jsx("span", { className: "font-mono text-[12.5px] text-fg tabular", children: chart.formatSeries(s.key, s.value) }), _jsx("span", { className: "w-11 text-end font-mono text-[12px] text-fg-subtle tabular", children: hidden ? "—" : chart.f.percent(s.share) })] }) }, s.key));
+        }) }));
+}

package/dist/charts/funnel.d.ts

@@ -0,0 +1,51 @@
+import * as React from "react";
+import { type ChartColor, type FormatSpec } from "./utils.js";
+export declare const funnelLabels: {
+    conversion: string;
+    overall: string;
+    dropoff: string;
+    stage: string;
+    stageWithConversion: string;
+    compare: string;
+    points: string;
+    loading: string;
+    empty: string;
+};
+export type FunnelLabels = typeof funnelLabels;
+export interface FunnelStep {
+    key: string;
+    label: string;
+    value: number;
+    /** Money (or any second number) per stage, e.g. pipeline value. */
+    amount?: number;
+    href?: string;
+}
+export interface FunnelProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onClick"> {
+    steps: FunnelStep[];
+    /** `horizontal` = stage columns (falls back to rows in a narrow container); `vertical` = stacked rows (mobile). */
+    orientation?: "horizontal" | "vertical";
+    format?: FormatSpec;
+    /** Format of `amount`. Default compact currency. */
+    amountFormat?: FormatSpec;
+    /** Metrics under each stage. Default `["conversion", "dropoff"]`. */
+    show?: ("conversion" | "overall" | "dropoff")[];
+    /** Base colour; later stages fade. Default `chart-1`. */
+    color?: ChartColor;
+    /** The same stages for a previous period — adds a marker and the conversion change. */
+    compareTo?: FunnelStep[];
+    onStepClick?: (step: FunnelStep) => void;
+    size?: "sm" | "md";
+    loading?: boolean;
+    /** Accessible name of the list. */
+    title?: string;
+    labels?: Partial<FunnelLabels>;
+}
+/**
+ * Stage-by-stage conversion as aligned bars: value, conversion from the previous stage, drop-off and
+ * an optional amount. Drop-off is muted, not red — losing leads between stages is normal.
+ *
+ * ```tsx
+ * <Funnel title="Sales pipeline" steps={[{ key: "leads", label: "Leads", value: 1240 }, …]} />
+ * ```
+ */
+export declare const Funnel: React.ForwardRefExoticComponent<FunnelProps & React.RefAttributes<HTMLDivElement>>;

package/dist/charts/funnel.js

@@ -0,0 +1,69 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { CornerDownRight } from "lucide-react";
+import { cn } from "../lib/cn.js";
+import { useFormat } from "../lib/locale.js";
+import { useLabels } from "../lib/labels.js";
+import { Skeleton } from "../components/skeleton.js";
+import { formatValue, resolveChartColor } from "./utils.js";
+export const funnelLabels = {
+    conversion: "{percent} of {previous}",
+    overall: "{percent} overall",
+    dropoff: "−{count}",
+    stage: "{label}: {value}",
+    stageWithConversion: "{label}: {value} ({percent} of {previous})",
+    compare: "{delta} vs previous period",
+    points: "{value} pt",
+    loading: "Loading…",
+    empty: "No stages yet",
+};
+/**
+ * Stage-by-stage conversion as aligned bars: value, conversion from the previous stage, drop-off and
+ * an optional amount. Drop-off is muted, not red — losing leads between stages is normal.
+ *
+ * ```tsx
+ * <Funnel title="Sales pipeline" steps={[{ key: "leads", label: "Leads", value: 1240 }, …]} />
+ * ```
+ */
+export const Funnel = React.forwardRef(function Funnel({ steps, orientation = "horizontal", format = "integer", amountFormat = "currency", show = ["conversion", "dropoff"], color = "chart-1", compareTo, onStepClick, size = "md", loading, title, labels, className, style, ...props }, ref) {
+    const f = useFormat();
+    const t = useLabels("funnel", funnelLabels, labels);
+    const first = steps[0]?.value ?? 0;
+    const max = Math.max(first, ...steps.map((s) => s.value), 1);
+    const base = resolveChartColor(color);
+    if (process.env.NODE_ENV !== "production") {
+        steps.forEach((s, i) => {
+            if (i > 0 && s.value > steps[i - 1].value)
+                console.warn(`[vamos-ui] Funnel: stage "${s.key}" is larger than the stage before it.`);
+        });
+    }
+    if (loading)
+        return (_jsxs("div", { ref: ref, "aria-busy": true, className: cn("grid gap-3", className), ...props, children: [_jsx("span", { role: "status", className: "sr-only", children: t("loading") }), [100, 72, 48, 30, 18].map((w, i) => (_jsxs("div", { className: "grid gap-1.5", children: [_jsx(Skeleton, { shape: "text", className: "w-24 text-[13px]" }), _jsx(Skeleton, { className: "h-6", style: { width: `${w}%` } })] }, i)))] }));
+    if (!steps.length)
+        return _jsx("p", { className: cn("py-6 text-center text-[13px] text-fg-muted", className), children: t("empty") });
+    const pct = (v) => f.percent(v, { maximumFractionDigits: v < 0.1 ? 1 : 0 });
+    const prevSteps = compareTo ? new Map(compareTo.map((s, i) => [s.key, { step: s, prev: compareTo[i - 1] }])) : null;
+    return (_jsx("div", { ref: ref, "data-slot": "funnel", "data-orientation": orientation, "data-size": size, className: cn("vui-funnel @container", className), style: style, ...props, children: _jsx("ol", { "aria-label": title, className: "vui-funnel-list", style: { "--funnel-n": steps.length }, children: steps.map((s, i) => {
+                const prev = steps[i - 1];
+                const conv = prev ? (prev.value > 0 ? s.value / prev.value : null) : null;
+                const overall = first > 0 ? s.value / first : null;
+                const drop = prev ? prev.value - s.value : 0;
+                const valueText = formatValue(f, format, s.value);
+                const convText = conv === null ? "—" : pct(conv);
+                const fade = steps.length > 1 ? 100 - (i / (steps.length - 1)) * 52 : 100;
+                const fill = `color-mix(in oklch, ${base} ${fade}%, var(--surface-solid, var(--surface)))`;
+                const cmp = prevSteps?.get(s.key);
+                const prevConv = cmp?.prev && cmp.prev.value > 0 ? cmp.step.value / cmp.prev.value : null;
+                const convDelta = conv !== null && prevConv !== null ? conv - prevConv : null;
+                const deltaText = convDelta === null ? null : `${convDelta >= 0 ? "+" : "−"}${t("points", { value: f.number(Math.abs(convDelta) * 100, { maximumFractionDigits: 1 }) })}`;
+                const srText = [
+                    prev ? t("stageWithConversion", { label: s.label, value: valueText, percent: convText, previous: prev.label }) : t("stage", { label: s.label, value: valueText }),
+                    s.amount !== undefined ? formatValue(f, amountFormat, s.amount) : null,
+                    deltaText ? t("compare", { delta: deltaText }) : null,
+                ]
+                    .filter(Boolean)
+                    .join(", ");
+                return (_jsxs("li", { className: "vui-funnel-step group/step relative", children: [_jsxs("div", { className: "vui-funnel-head flex min-w-0 items-baseline justify-between gap-3", children: [s.href ? (_jsx("a", { href: s.href, "aria-label": srText, className: "truncate rounded-ui-sm text-[13px] text-fg focus-ring after:absolute after:inset-0 hover:underline hover:underline-offset-4", children: s.label })) : onStepClick ? (_jsx("button", { type: "button", "aria-label": srText, onClick: () => onStepClick(s), className: "truncate rounded-ui-sm text-start text-[13px] text-fg focus-ring after:absolute after:inset-0 group-hover/step:underline group-hover/step:underline-offset-4", children: s.label })) : (_jsxs("span", { className: "truncate text-[13px] text-fg", children: [_jsx("span", { "aria-hidden": true, children: s.label }), _jsx("span", { className: "sr-only", children: srText })] })), _jsx("span", { "aria-hidden": true, className: "vui-funnel-value font-mono text-fg tabular", children: valueText })] }), _jsxs("div", { "aria-hidden": true, className: "vui-funnel-track", children: [_jsx("div", { className: "vui-funnel-fill", style: { "--p": Math.max(1.5, (s.value / max) * 100), background: fill } }), cmp ? _jsx("div", { className: "vui-funnel-marker", style: { "--p": Math.min(100, (cmp.step.value / Math.max(max, compareTo?.[0]?.value ?? 0)) * 100) } }) : null] }), _jsxs("div", { "aria-hidden": true, className: "vui-funnel-meta flex flex-wrap items-center gap-x-2.5 gap-y-0.5 font-mono text-[11.5px] text-fg-muted tabular", children: [s.amount !== undefined ? _jsx("span", { className: "text-fg", children: formatValue(f, amountFormat, s.amount, { compact: true }) }) : null, prev && show.includes("conversion") ? (_jsxs("span", { className: "inline-flex items-center gap-1 text-fg", title: t("conversion", { percent: convText, previous: prev.label }), children: [_jsx(CornerDownRight, { className: "size-3 text-fg-subtle" }), convText] })) : null, prev && show.includes("dropoff") && drop > 0 ? _jsx("span", { className: "text-fg-subtle", children: t("dropoff", { count: formatValue(f, format, drop) }) }) : null, i > 0 && show.includes("overall") && overall !== null ? _jsx("span", { className: "text-fg-subtle", children: t("overall", { percent: pct(overall) }) }) : null, deltaText ? _jsx("span", { className: cn(convDelta >= 0 ? "text-success" : "text-danger"), children: deltaText }) : null] })] }, s.key));
+            }) }) }));
+});

package/dist/charts/gauge.d.ts

@@ -0,0 +1,62 @@
+import * as React from "react";
+import { type ChartColor, type FormatSpec } from "./utils.js";
+export declare const gaugeLabels: {
+    valueText: string;
+    valueTextWithLabel: string;
+    target: string;
+    noValue: string;
+};
+export type GaugeLabels = typeof gaugeLabels;
+export interface GaugeThreshold {
+    /** Applies from this value up. */
+    at: number;
+    color: ChartColor;
+    /** Word for the band ("Fair") — shown under the value and read in `aria-valuetext`. */
+    label?: string;
+}
+export interface ProgressRingProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "color"> {
+    /** Current value. `null` = unknown (empty track, "—"). */
+    value: number | null;
+    /** Default 100. */
+    max?: number;
+    size?: "xs" | "sm" | "md" | "lg" | number;
+    /** Stroke width in px. Default: about a tenth of the size. */
+    thickness?: number;
+    /** Fill token, or `"auto"` to take it from `thresholds`. Default `chart-1`. */
+    color?: ChartColor | "auto";
+    thresholds?: GaugeThreshold[];
+    /** Centre content (md and lg). Default: the formatted value. Pass `null` for none. */
+    label?: React.ReactNode;
+    /** `percent` shows value / max; any other spec formats the value itself. */
+    format?: FormatSpec;
+    /** `progress` (task completion) → role="progressbar"; `meter` (a score) → role="meter". Default `progress`. */
+    semantic?: "progress" | "meter";
+    "aria-label": string;
+    labels?: Partial<GaugeLabels>;
+}
+export interface GaugeProps extends ProgressRingProps {
+    /** Sweep of the arc. Default 270. */
+    arc?: 180 | 270;
+    /** Paint the threshold ranges as a thin outer band. */
+    showThresholdBands?: boolean;
+    /** A marker on the arc (quota, goal). */
+    target?: number;
+}
+/**
+ * A full ring for progress to a target — profile completeness, quota, upload. Plain SVG; `xs` fits
+ * in a table cell.
+ *
+ * ```tsx
+ * <ProgressRing value={85} aria-label="Profile completeness" format="percent" size="md" />
+ * ```
+ */
+export declare const ProgressRing: React.ForwardRefExoticComponent<ProgressRingProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * A score or attainment on a 180° / 270° arc with optional threshold bands and a target marker —
+ * SEO score, quota, NPS. `semantic="meter"` for scores.
+ *
+ * ```tsx
+ * <Gauge value={64} aria-label="SEO score" semantic="meter" thresholds={[{ at: 0, color: "danger", label: "Poor" }, { at: 50, color: "warning", label: "Fair" }, { at: 80, color: "success", label: "Good" }]} color="auto" />
+ * ```
+ */
+export declare const Gauge: React.ForwardRefExoticComponent<GaugeProps & React.RefAttributes<HTMLDivElement>>;