@vamos-ui/react 0.0.0-stage → 0.3.0

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, stackOffset: startStacked && startDomain[0] < 0 ? "sign" : undefined, 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>>;

package/dist/charts/gauge.js

@@ -0,0 +1,104 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { useFormat } from "../lib/locale.js";
+import { useLabels } from "../lib/labels.js";
+import { formatValue, resolveChartColor } from "./utils.js";
+export const gaugeLabels = {
+    valueText: "{value} of {max}",
+    valueTextWithLabel: "{value} of {max}, {label}",
+    target: "Target {value}",
+    noValue: "No value",
+};
+const SIZES = { xs: 20, sm: 36, md: 96, lg: 160 };
+function pickThreshold(value, thresholds) {
+    if (value === null || !thresholds?.length)
+        return undefined;
+    return [...thresholds].sort((a, b) => a.at - b.at).filter((t) => value >= t.at).pop();
+}
+function useGaugeText(value, max, format, threshold, labels) {
+    const f = useFormat();
+    const t = useLabels("gauge", gaugeLabels, labels);
+    const fmt = (v) => (format === "percent" ? f.percent(v / max) : formatValue(f, format, v));
+    const display = value === null ? "—" : fmt(value);
+    const maxText = format === "percent" ? f.percent(1) : formatValue(f, format, max);
+    const valueText = value === null ? t("noValue") : threshold?.label ? t("valueTextWithLabel", { value: fmt(value), max: maxText, label: threshold.label }) : t("valueText", { value: fmt(value), max: maxText });
+    return { display, valueText, t, fmt };
+}
+function a11yProps(semantic, value, max, valueText, label) {
+    return {
+        role: semantic === "meter" ? "meter" : "progressbar",
+        "aria-label": label,
+        "aria-valuemin": 0,
+        "aria-valuemax": max,
+        "aria-valuenow": value === null ? undefined : Math.min(value, max),
+        "aria-valuetext": valueText,
+    };
+}
+/**
+ * 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 const ProgressRing = React.forwardRef(function ProgressRing({ value, max = 100, size = "md", thickness, color = "chart-1", thresholds, label, format, semantic = "progress", labels, className, style, "aria-label": ariaLabel, ...props }, ref) {
+    const px = typeof size === "number" ? size : SIZES[size];
+    const sw = thickness ?? Math.max(2.5, Math.round(px * 0.09 * 10) / 10);
+    const threshold = pickThreshold(value, thresholds);
+    const { display, valueText } = useGaugeText(value, max, format, threshold, labels);
+    const ratio = value === null ? 0 : Math.max(0, Math.min(1, value / max));
+    const stroke = resolveChartColor(color === "auto" ? (threshold?.color ?? "chart-1") : color);
+    const r = (px - sw) / 2;
+    const c = 2 * Math.PI * r;
+    const showLabel = px >= 64 && label !== null;
+    return (_jsxs("div", { ref: ref, "data-slot": "progress-ring", ...a11yProps(semantic, value, max, valueText, ariaLabel), className: cn("relative inline-grid shrink-0 place-items-center align-middle", className), style: { width: px, height: px, ...style }, ...props, children: [_jsxs("svg", { width: px, height: px, viewBox: `0 0 ${px} ${px}`, "aria-hidden": true, "data-ring": "", className: "vui-gauge-arc -rotate-90", children: [_jsx("circle", { cx: px / 2, cy: px / 2, r: r, fill: "none", stroke: "var(--track)", strokeWidth: sw }), ratio > 0 ? (_jsx("circle", { cx: px / 2, cy: px / 2, r: r, fill: "none", stroke: stroke, strokeWidth: sw, strokeLinecap: ratio >= 1 ? "butt" : "round", strokeDasharray: `${c * ratio} ${c}`, className: "vui-gauge-value" })) : null] }), showLabel ? (_jsx("div", { "aria-hidden": true, className: "absolute inset-0 flex flex-col items-center justify-center text-center", children: label ?? (_jsxs(_Fragment, { children: [_jsx("span", { className: cn("font-mono leading-none font-medium tracking-[-0.02em] text-fg tabular", px >= 140 ? "text-[30px]" : "text-[17px]"), children: display }), threshold?.label && px >= 120 ? _jsx("span", { className: "mt-1.5 text-[12px] text-fg-muted", children: threshold.label }) : null] })) })) : null] }));
+});
+/**
+ * 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 const Gauge = React.forwardRef(function Gauge({ value, max = 100, size = "lg", thickness, color = "chart-1", thresholds, label, format, semantic = "meter", arc = 270, showThresholdBands, target, labels, className, style, "aria-label": ariaLabel, ...props }, ref) {
+    const px = typeof size === "number" ? size : SIZES[size];
+    const sw = thickness ?? Math.max(3, Math.round(px * 0.075 * 10) / 10);
+    const threshold = pickThreshold(value, thresholds);
+    const { display, valueText, t, fmt } = useGaugeText(value, max, format, threshold, labels);
+    const ratio = value === null ? 0 : Math.max(0, Math.min(1, value / max));
+    const over = value !== null && value > max;
+    const stroke = resolveChartColor(color === "auto" ? (threshold?.color ?? "chart-1") : color);
+    const band = showThresholdBands && thresholds?.length ? sw * 0.35 : 0;
+    const gap = band ? 3 : 0;
+    const cx = px / 2;
+    const r = (px - sw) / 2 - band - gap;
+    const rb = (px - band) / 2;
+    const sweep = arc;
+    const start = arc === 180 ? 180 : 135; // degrees, clockwise from +x
+    const height = arc === 180 ? Math.ceil(px / 2 + sw / 2 + 2) : Math.ceil(px / 2 + Math.sin(Math.PI / 4) * (px / 2) + 2);
+    const len = (rad) => (2 * Math.PI * rad * sweep) / 360;
+    const C = (rad) => 2 * Math.PI * rad;
+    const point = (deg, rad) => [cx + rad * Math.cos((deg * Math.PI) / 180), cx + rad * Math.sin((deg * Math.PI) / 180)];
+    const sorted = thresholds ? [...thresholds].sort((a, b) => a.at - b.at) : [];
+    const targetDeg = target !== undefined ? start + (Math.max(0, Math.min(1, target / max)) * sweep) : undefined;
+    return (_jsxs("div", { ref: ref, "data-slot": "gauge", "data-arc": arc, ...a11yProps(semantic, value, max, valueText + (target !== undefined ? `, ${t("target", { value: fmt(target) })}` : ""), ariaLabel), className: cn("relative inline-block shrink-0 align-middle", className), style: { width: px, height, ...style }, ...props, children: [_jsxs("svg", { width: px, height: height, viewBox: `0 0 ${px} ${height}`, "aria-hidden": true, className: "vui-gauge-arc overflow-visible", children: [_jsxs("g", { transform: `rotate(${start} ${cx} ${cx})`, children: [_jsx("circle", { cx: cx, cy: cx, r: r, fill: "none", stroke: "var(--track)", strokeWidth: sw, strokeLinecap: "round", strokeDasharray: `${len(r)} ${C(r)}` }), ratio > 0 ? (_jsx("circle", { cx: cx, cy: cx, r: r, fill: "none", stroke: stroke, strokeWidth: sw, strokeLinecap: "round", strokeDasharray: `${len(r) * ratio} ${C(r)}`, className: "vui-gauge-value" })) : null, band
+                                ? sorted.map((th, i) => {
+                                    const from = Math.max(0, th.at / max);
+                                    const to = Math.min(1, (sorted[i + 1]?.at ?? max) / max);
+                                    if (to <= from)
+                                        return null;
+                                    return (_jsx("circle", { cx: cx, cy: cx, r: rb, fill: "none", stroke: `color-mix(in oklch, ${resolveChartColor(th.color)} 55%, transparent)`, strokeWidth: band, strokeDasharray: `${Math.max(0, len(rb) * (to - from) - 1.5)} ${C(rb)}`, strokeDashoffset: -len(rb) * from }, i));
+                                })
+                                : null] }), targetDeg !== undefined ? ((() => {
+                        const [x1, y1] = point(targetDeg, r - sw / 2 - 3);
+                        const [x2, y2] = point(targetDeg, r + sw / 2 + 3);
+                        return _jsx("line", { x1: x1, y1: y1, x2: x2, y2: y2, stroke: "var(--fg)", strokeWidth: 2, strokeLinecap: "round" });
+                    })()) : null, over ? ((() => {
+                        const [x, y] = point(start + sweep, r);
+                        return _jsx("circle", { cx: x, cy: y, r: sw / 2 + 1.5, fill: "none", stroke: "var(--fg)", strokeWidth: 1.5 });
+                    })()) : null] }), label !== null && px >= 64 ? (_jsx("div", { "aria-hidden": true, className: cn("absolute inset-x-0 flex flex-col items-center text-center", arc === 180 ? "bottom-0" : "top-0 bottom-[12%] justify-center"), children: label ?? (_jsxs(_Fragment, { children: [_jsx("span", { className: cn("font-mono leading-none font-medium tracking-[-0.03em] text-fg tabular", px >= 140 ? "text-[32px]" : "text-[18px]"), children: display }), threshold?.label || target !== undefined ? (_jsx("span", { className: "mt-1.5 text-[12px] text-fg-muted", children: threshold?.label ?? t("target", { value: fmt(target) }) })) : null] })) })) : null] }));
+});

package/dist/charts/heatmap.d.ts

@@ -0,0 +1,81 @@
+import * as React from "react";
+import { type ChartLabels } from "./chart-shell.js";
+import { type ChartColor, type ChartState, type FormatSpec } from "./utils.js";
+export declare const heatmapLabels: {
+    less: string;
+    more: string;
+    cell: string;
+    noData: string;
+    date: string;
+    value: string;
+    calendarSummary: string;
+    matrixSummary: string;
+};
+export type HeatmapLabels = typeof heatmapLabels;
+export interface HeatmapCell {
+    /** Calendar: `"YYYY-MM-DD"` (or a Date). Matrix: the column label. */
+    x: string | Date;
+    /** Matrix: the row label. */
+    y?: string;
+    value: number | null;
+    /** Categorical scale: the category value of this cell. */
+    category?: string;
+    meta?: unknown;
+}
+export interface HeatmapCategory {
+    value: string;
+    label: string;
+    color: ChartColor;
+}
+export interface HeatmapProps extends Omit<React.HTMLAttributes<HTMLElement>, "title" | "onClick"> {
+    /** `calendar`: weeks × weekdays (activity, attendance). `matrix`: rows × columns (weekday × hour). */
+    mode: "calendar" | "matrix";
+    data: HeatmapCell[];
+    /** Calendar range. Default: first to last date in `data`. */
+    range?: {
+        from: string | Date;
+        to: string | Date;
+    };
+    /** Matrix column order. Default: order of appearance. */
+    xLabels?: string[];
+    /** Matrix row order. Default: order of appearance. */
+    yLabels?: string[];
+    scale?: "sequential" | "diverging" | "categorical";
+    categories?: HeatmapCategory[];
+    /** Colour steps. Default 5. */
+    steps?: 4 | 5 | 7;
+    /** Linear breaks between these values. Default: quantile breaks (equal-count buckets). */
+    domain?: [number, number];
+    /** Base colour (sequential). Default `chart-1` — follows the accent. */
+    color?: ChartColor;
+    format?: FormatSpec;
+    /** Name of the measured thing, for table header and cell labels ("Posts"). */
+    valueLabel?: string;
+    tooltip?: (cell: HeatmapCell) => React.ReactNode;
+    onCellClick?: (cell: HeatmapCell) => void;
+    /** `auto` fills the width; a number fixes the cell size in px (scrolls when wider). */
+    cellSize?: "auto" | number;
+    /** Accessible name of the grid and the table caption. */
+    title: string;
+    /** Override the week start (0 = Sunday … 6 = Saturday). Default: from the locale. */
+    weekStart?: number;
+    /** Ring this day (`YYYY-MM-DD`). Default: today in the provider's time zone (set after mount). */
+    today?: string | null;
+    showLegend?: boolean;
+    tableToggle?: boolean;
+    state?: ChartState;
+    summary?: string;
+    labels?: Partial<HeatmapLabels & ChartLabels>;
+}
+/** First day of the week for a locale: 0 = Sunday … 6 = Saturday. */
+export declare function weekStartOf(locale: string): number;
+/**
+ * Density patterns as a grid of tinted cells: a **calendar** (weeks × weekdays, like a contribution
+ * graph) or a **matrix** (weekday × hour, channel × week). Plain DOM — no chart library. An ARIA grid
+ * with arrow keys, Home / End and PageUp / PageDown, plus a data-table alternative.
+ *
+ * ```tsx
+ * <Heatmap mode="calendar" title="Posts published" data={days} valueLabel="Posts" />
+ * ```
+ */
+export declare function Heatmap({ mode, data, range, xLabels: xLabelsProp, yLabels: yLabelsProp, scale, categories, steps, domain, color, format, valueLabel, tooltip, onCellClick, cellSize, title, weekStart: weekStartProp, today: todayProp, showLegend, tableToggle, state, summary, labels, className, ...props }: HeatmapProps): React.JSX.Element;