@vamos-ui/react 0.0.0-stage → 0.2.0

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;

package/dist/charts/heatmap.js

@@ -0,0 +1,338 @@
+"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, useLocale } from "../lib/locale.js";
+import { useLabels } from "../lib/labels.js";
+import { Chart } from "./chart-shell.js";
+import { formatValue, quantileBreaks, resolveChartColor } from "./utils.js";
+export const heatmapLabels = {
+    less: "Less",
+    more: "More",
+    cell: "{label}: {value}",
+    noData: "no data",
+    date: "Date",
+    value: "Value",
+    calendarSummary: "{from} – {to}. {total} in total; busiest day {maxAt} with {max}.",
+    matrixSummary: "Highest: {maxAt} with {max}. Lowest: {minAt} with {min}.",
+};
+const DAY = 86_400_000;
+const pad = (n) => String(n).padStart(2, "0");
+const toDay = (v) => {
+    if (v instanceof Date)
+        return Math.floor(Date.UTC(v.getFullYear(), v.getMonth(), v.getDate()) / DAY);
+    const [y, m, d] = v.split("-").map(Number);
+    return Math.floor(Date.UTC(y, (m ?? 1) - 1, d ?? 1) / DAY);
+};
+const fromDay = (n) => {
+    const d = new Date(n * DAY);
+    return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())}`;
+};
+const weekdayOf = (n) => new Date(n * DAY).getUTCDay();
+const SUNDAY_START = new Set(["US", "CA", "MX", "BR", "JP", "IL", "KR", "TW", "PH", "IN", "ZA", "SA", "AU"]);
+/** First day of the week for a locale: 0 = Sunday … 6 = Saturday. */
+export function weekStartOf(locale) {
+    try {
+        const l = new Intl.Locale(locale);
+        const info = l.getWeekInfo?.() ?? l.weekInfo;
+        if (info?.firstDay)
+            return info.firstDay % 7;
+        const region = l.maximize().region;
+        if (region)
+            return SUNDAY_START.has(region) ? 0 : 1;
+    }
+    catch {
+        /* fall through */
+    }
+    return 1;
+}
+/**
+ * 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 function Heatmap({ mode, data, range, xLabels: xLabelsProp, yLabels: yLabelsProp, scale = "sequential", categories, steps = 5, domain, color = "chart-1", format = "integer", valueLabel, tooltip, onCellClick, cellSize = "auto", title, weekStart: weekStartProp, today: todayProp, showLegend = true, tableToggle, state, summary, labels, className, ...props }) {
+    const f = useFormat();
+    const { locale, dir } = useLocale();
+    const t = useLabels("heatmap", heatmapLabels, labels);
+    const weekStart = weekStartProp ?? weekStartOf(locale);
+    const [today, setToday] = React.useState(todayProp ?? null);
+    React.useEffect(() => {
+        if (todayProp !== undefined)
+            return setToday(todayProp);
+        const parts = new Intl.DateTimeFormat("en-CA", { timeZone: f.timeZone, year: "numeric", month: "2-digit", day: "2-digit" }).format(new Date());
+        setToday(parts);
+    }, [todayProp, f.timeZone]);
+    /* ----- layout ----- */
+    const layout = React.useMemo(() => {
+        if (mode === "calendar") {
+            const byDay = new Map();
+            for (const c of data)
+                byDay.set(toDay(c.x), c);
+            const days = [...byDay.keys()];
+            const from = range ? toDay(range.from) : days.length ? Math.min(...days) : toDay(new Date());
+            const to = range ? toDay(range.to) : days.length ? Math.max(...days) : from;
+            const gridStart = from - ((weekdayOf(from) - weekStart + 7) % 7);
+            const cols = Math.floor((to - gridStart) / 7) + 1;
+            const rows = Array.from({ length: 7 }, () => []);
+            for (let col = 0; col < cols; col++) {
+                for (let row = 0; row < 7; row++) {
+                    const day = gridStart + col * 7 + row;
+                    const iso = fromDay(day);
+                    const inRange = day >= from && day <= to;
+                    rows[row].push({
+                        key: iso,
+                        row,
+                        col,
+                        day,
+                        cell: inRange ? (byDay.get(day) ?? { x: iso, value: null }) : null,
+                        label: f.date(iso, { weekday: "long", month: "long", day: "numeric", year: "numeric" }),
+                        placeholder: !inRange,
+                    });
+                }
+            }
+            const weekdays = Array.from({ length: 7 }, (_, row) => {
+                const day = gridStart + row;
+                return { short: f.date(fromDay(day), { weekday: "short" }), long: f.date(fromDay(day), { weekday: "long" }) };
+            });
+            const months = [];
+            let lastMonth = -1;
+            for (let col = 0; col < cols; col++) {
+                const day = Math.max(from, gridStart + col * 7);
+                const m = new Date(day * DAY).getUTCMonth();
+                if (m !== lastMonth && (col === 0 || new Date((gridStart + col * 7) * DAY).getUTCDate() <= 7)) {
+                    months.push({ col, label: f.date(fromDay(day), { month: "short" }) });
+                    lastMonth = m;
+                }
+            }
+            return { rows, cols, rowLabels: weekdays, colLabels: null, months: months, from, to };
+        }
+        const xs = xLabelsProp ?? [...new Set(data.map((c) => String(c.x)))];
+        const ys = yLabelsProp ?? [...new Set(data.map((c) => c.y ?? ""))];
+        const lookup = new Map(data.map((c) => [`${c.y ?? ""}|${String(c.x)}`, c]));
+        const rows = ys.map((y, row) => xs.map((x, col) => ({ key: `${y}|${x}`, row, col, cell: lookup.get(`${y}|${x}`) ?? { x, y, value: null }, label: `${y}, ${x}` })));
+        return { rows, cols: xs.length, rowLabels: ys.map((y) => ({ short: y, long: y })), colLabels: xs, months: [], from: 0, to: 0 };
+    }, [mode, data, range, weekStart, xLabelsProp, yLabelsProp, f]);
+    /* ----- scale ----- */
+    const values = React.useMemo(() => data.map((c) => c.value).filter((v) => typeof v === "number" && Number.isFinite(v)), [data]);
+    const bucketOf = React.useMemo(() => {
+        if (scale === "diverging") {
+            const m = domain ? Math.max(Math.abs(domain[0]), Math.abs(domain[1])) : Math.max(0, ...values.map(Math.abs)) || 1;
+            const mid = (steps - 1) / 2;
+            return (v) => Math.max(0, Math.min(steps - 1, Math.round(mid + (v / m) * mid)));
+        }
+        if (domain) {
+            const [lo, hi] = domain;
+            return (v) => (v <= lo ? 0 : Math.max(1, Math.min(steps - 1, Math.ceil(((v - lo) / (hi - lo || 1)) * (steps - 1)))));
+        }
+        const breaks = quantileBreaks(values, steps);
+        return (v) => {
+            if (v <= 0)
+                return 0;
+            let b = 1;
+            for (const br of breaks)
+                if (v > br)
+                    b++;
+            return Math.min(steps - 1, b);
+        };
+    }, [scale, domain, values, steps]);
+    const stepColor = React.useCallback((i) => {
+        if (scale === "diverging") {
+            const mid = (steps - 1) / 2;
+            if (i === mid)
+                return "var(--track)";
+            const tone = i < mid ? "var(--danger)" : "var(--success)";
+            const p = 18 + (Math.abs(i - mid) / mid) * 72;
+            return `color-mix(in oklch, ${tone} ${p}%, var(--surface-solid, var(--surface)))`;
+        }
+        if (steps === 5 && color === "chart-1")
+            return `var(--chart-seq-${i})`;
+        const p = 10 + (i / (steps - 1)) * 90;
+        return `color-mix(in oklch, ${resolveChartColor(color)} ${p}%, var(--surface-solid, var(--surface)))`;
+    }, [scale, steps, color]);
+    const catMap = React.useMemo(() => new Map((categories ?? []).map((c) => [c.value, c])), [categories]);
+    const fillOf = (c) => {
+        if (!c)
+            return {};
+        if (scale === "categorical") {
+            const cat = c.category ? catMap.get(c.category) : undefined;
+            return cat ? { bg: resolveChartColor(cat.color) } : {};
+        }
+        if (c.value === null)
+            return {};
+        const step = bucketOf(c.value);
+        return { bg: stepColor(step), step };
+    };
+    const valueText = (c) => {
+        if (!c)
+            return "";
+        if (scale === "categorical")
+            return c.category ? (catMap.get(c.category)?.label ?? c.category) : t("noData");
+        if (c.value === null)
+            return t("noData");
+        const v = formatValue(f, format, c.value);
+        return valueLabel ? `${v} ${valueLabel.toLocaleLowerCase(locale)}` : v;
+    };
+    /* ----- keyboard ----- */
+    const focusable = React.useMemo(() => layout.rows.flat().filter((g) => !g.placeholder), [layout]);
+    const [active, setActive] = React.useState(null);
+    const [hover, setHover] = React.useState(null);
+    const activeKey = active ?? focusable[focusable.length - 1]?.key ?? null;
+    const gridRef = React.useRef(null);
+    const byKey = React.useMemo(() => new Map(focusable.map((g) => [g.key, g])), [focusable]);
+    const focusKey = (key) => {
+        if (!key || !byKey.has(key))
+            return;
+        setActive(key);
+        gridRef.current?.querySelector(`[data-key="${CSS.escape(key)}"]`)?.focus();
+    };
+    const onKeyDown = (e, g) => {
+        const rtl = dir === "rtl";
+        const h = rtl ? -1 : 1;
+        let next;
+        if (mode === "calendar" && g.day !== undefined) {
+            const go = (d) => {
+                const clamped = Math.max(layout.from, Math.min(layout.to, d));
+                return fromDay(clamped);
+            };
+            const rowCells = layout.rows[g.row].filter((c) => !c.placeholder);
+            switch (e.key) {
+                case "ArrowUp":
+                    next = go(g.day - 1);
+                    break;
+                case "ArrowDown":
+                    next = go(g.day + 1);
+                    break;
+                case "ArrowLeft":
+                    next = go(g.day - 7 * h);
+                    break;
+                case "ArrowRight":
+                    next = go(g.day + 7 * h);
+                    break;
+                case "Home":
+                    next = rowCells[0]?.key;
+                    break;
+                case "End":
+                    next = rowCells[rowCells.length - 1]?.key;
+                    break;
+                case "PageUp":
+                    next = go(g.day - 28);
+                    break;
+                case "PageDown":
+                    next = go(g.day + 28);
+                    break;
+            }
+        }
+        else {
+            const at = (r, c) => layout.rows[Math.max(0, Math.min(layout.rows.length - 1, r))]?.[Math.max(0, Math.min(layout.cols - 1, c))]?.key;
+            switch (e.key) {
+                case "ArrowUp":
+                    next = at(g.row - 1, g.col);
+                    break;
+                case "ArrowDown":
+                    next = at(g.row + 1, g.col);
+                    break;
+                case "ArrowLeft":
+                    next = at(g.row, g.col - h);
+                    break;
+                case "ArrowRight":
+                    next = at(g.row, g.col + h);
+                    break;
+                case "Home":
+                    next = e.ctrlKey ? at(0, 0) : at(g.row, 0);
+                    break;
+                case "End":
+                    next = e.ctrlKey ? at(layout.rows.length - 1, layout.cols - 1) : at(g.row, layout.cols - 1);
+                    break;
+                case "PageUp":
+                    next = at(0, g.col);
+                    break;
+                case "PageDown":
+                    next = at(layout.rows.length - 1, g.col);
+                    break;
+            }
+        }
+        if (next) {
+            e.preventDefault();
+            focusKey(next);
+            return;
+        }
+        if ((e.key === "Enter" || e.key === " ") && onCellClick && g.cell) {
+            e.preventDefault();
+            onCellClick(g.cell);
+        }
+    };
+    /* ----- table + summary ----- */
+    const table = React.useMemo(() => {
+        if (mode === "calendar") {
+            const rows = focusable.filter((g) => g.cell && (g.cell.value !== null || g.cell.category)).map((g) => ({ date: g.key, value: scale === "categorical" ? valueText(g.cell) : g.cell.value }));
+            return { columns: [{ key: "date", label: t("date"), header: true }, { key: "value", label: valueLabel ?? t("value"), format: scale === "categorical" ? undefined : format }], rows };
+        }
+        const cols = layout.colLabels ?? [];
+        return {
+            columns: [{ key: "__y", label: title, header: true }, ...cols.map((c) => ({ key: c, label: c, format }))],
+            rows: layout.rows.map((r, i) => Object.fromEntries([["__y", layout.rowLabels[i]?.long ?? ""], ...r.map((g) => [g.cell ? String(g.cell.x) : g.key, g.cell?.value ?? null])])),
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [mode, focusable, layout, format, valueLabel, t, scale, title]);
+    const summaryText = React.useMemo(() => {
+        if (summary)
+            return summary;
+        const withValues = focusable.filter((g) => typeof g.cell?.value === "number");
+        if (!withValues.length)
+            return "";
+        let max = withValues[0];
+        let min = withValues[0];
+        let total = 0;
+        for (const g of withValues) {
+            const v = g.cell.value;
+            total += v;
+            if (v > max.cell.value)
+                max = g;
+            if (v < min.cell.value)
+                min = g;
+        }
+        const fmt = (v) => formatValue(f, format, v);
+        if (mode === "calendar")
+            return t("calendarSummary", { from: f.date(fromDay(layout.from), "medium"), to: f.date(fromDay(layout.to), "medium"), total: fmt(total), maxAt: max.label, max: fmt(max.cell.value) });
+        return t("matrixSummary", { maxAt: max.label, max: fmt(max.cell.value), minAt: min.label, min: fmt(min.cell.value) });
+    }, [summary, focusable, f, format, mode, t, layout]);
+    /* ----- render ----- */
+    const fixed = typeof cellSize === "number";
+    const colTemplate = fixed ? `repeat(${layout.cols}, ${cellSize}px)` : `repeat(${layout.cols}, minmax(0, 1fr))`;
+    const shown = hover ?? null;
+    const shownCell = shown ? byKey.get(shown) : undefined;
+    const legendSteps = scale === "categorical" ? [] : Array.from({ length: steps }, (_, i) => i);
+    const legendNode = showLegend && (scale !== "categorical" || categories?.length) ? (_jsx("div", { "aria-hidden": true, className: "flex flex-wrap items-center justify-end gap-x-3 gap-y-1 text-[11.5px] text-fg-muted", children: scale === "categorical" ? (categories.map((c) => (_jsxs("span", { className: "inline-flex items-center gap-1.5", children: [_jsx("span", { className: "vui-heatmap-swatch", style: { background: resolveChartColor(c.color) } }), c.label] }, c.value)))) : (_jsxs("span", { className: "inline-flex items-center gap-1", children: [_jsx("span", { className: "me-1", children: t("less") }), legendSteps.map((i) => (_jsx("span", { className: "vui-heatmap-swatch", "data-step": i, style: { background: stepColor(i) } }, i))), _jsx("span", { className: "ms-1", children: t("more") })] })) })) : null;
+    return (_jsx(Chart, { title: title, data: table.rows, config: { value: { label: valueLabel ?? t("value"), format } }, table: table, summary: summaryText, height: "auto", legend: "none", skeleton: "grid", tableToggle: tableToggle, state: state ?? (data.length === 0 ? { status: "empty" } : { status: "ready" }), labels: labels, className: className, ...props, children: _jsxs("div", { className: "vui-heatmap grid gap-2", "data-mode": mode, "data-scale": scale, children: [_jsxs("div", { className: cn("relative", fixed && "overflow-x-auto pb-1"), children: [_jsxs("div", { className: "grid w-full", style: { gridTemplateColumns: "auto minmax(0, 1fr)", columnGap: 8 }, children: [_jsx("span", {}), mode === "calendar" ? (_jsx("div", { "aria-hidden": true, className: "relative mb-1 h-4 text-[11px] text-fg-subtle", style: { display: "grid", gridTemplateColumns: colTemplate, gap: "var(--hm-gap)" }, children: layout.months.map((m) => (_jsx("span", { className: "whitespace-nowrap", style: { gridColumnStart: m.col + 1 }, children: m.label }, m.col))) })) : (_jsx("span", {})), _jsxs("div", { ref: gridRef, role: "grid", "aria-label": title, "aria-readonly": true, className: "col-span-2 grid", style: { gridTemplateColumns: "subgrid", rowGap: "var(--hm-gap)" }, onMouseLeave: () => setHover(null), children: [mode === "matrix" ? (_jsxs("div", { role: "row", className: "col-span-2 grid", style: { gridTemplateColumns: "subgrid" }, children: [_jsx("span", { role: "columnheader", children: _jsx("span", { className: "sr-only", children: title }) }), _jsx("div", { className: "grid", style: { gridTemplateColumns: colTemplate, gap: "var(--hm-gap)" }, children: (layout.colLabels ?? []).map((c, i) => (_jsx("span", { role: "columnheader", className: "overflow-hidden text-center text-[11px] whitespace-nowrap text-fg-subtle", children: _jsx("span", { className: cn(layout.cols > 12 && i % 3 !== 0 && "sr-only"), children: c }) }, c))) })] })) : null, layout.rows.map((row, ri) => (_jsxs("div", { role: "row", className: "col-span-2 grid items-center", style: { gridTemplateColumns: "subgrid" }, children: [_jsx("span", { role: "rowheader", className: "pe-1 text-end text-[11px] leading-none whitespace-nowrap text-fg-subtle", children: _jsx("span", { className: cn(mode === "calendar" && ri % 2 === 0 && "sr-only"), children: layout.rowLabels[ri]?.short }) }), _jsx("div", { className: "grid", style: { gridTemplateColumns: colTemplate, gap: "var(--hm-gap)" }, children: row.map((g) => {
+                                                        if (g.placeholder)
+                                                            return _jsx("span", { role: "presentation", className: "vui-heatmap-cell", "data-placeholder": "" }, g.key);
+                                                        const { bg, step } = fillOf(g.cell);
+                                                        const text = t("cell", { label: g.label, value: valueText(g.cell) });
+                                                        const isToday = mode === "calendar" && today === g.key;
+                                                        return (_jsx("div", { role: "gridcell", "data-key": g.key, "data-step": step, "data-empty": bg ? undefined : "", "data-today": isToday ? "" : undefined, "aria-label": text, "aria-current": isToday ? "date" : undefined, tabIndex: g.key === activeKey ? 0 : -1, onFocus: () => {
+                                                                setActive(g.key);
+                                                                setHover(g.key);
+                                                            }, onBlur: () => setHover((h) => (h === g.key ? null : h)), onMouseEnter: () => setHover(g.key), onKeyDown: (e) => onKeyDown(e, g), onClick: onCellClick && g.cell ? () => onCellClick(g.cell) : undefined, className: cn("vui-heatmap-cell focus-ring", onCellClick && "cursor-pointer"), style: bg ? { background: bg } : undefined }, g.key));
+                                                    }) })] }, ri)))] })] }), shownCell ? _jsx(HeatmapTooltip, { gridRef: gridRef, cellKey: shownCell.key, content: tooltip && shownCell.cell ? tooltip(shownCell.cell) : _jsxs(_Fragment, { children: [_jsx("span", { className: "text-fg-muted", children: shownCell.label }), _jsx("span", { className: "font-mono text-fg tabular", children: valueText(shownCell.cell) })] }) }) : null] }), legendNode] }) }));
+}
+/** Floating cell tooltip, positioned above the cell (decorative — the cell carries the full label). */
+function HeatmapTooltip({ gridRef, cellKey, content }) {
+    const ref = React.useRef(null);
+    const [pos, setPos] = React.useState(null);
+    React.useLayoutEffect(() => {
+        const grid = gridRef.current;
+        const cell = grid?.querySelector(`[data-key="${CSS.escape(cellKey)}"]`);
+        const host = ref.current?.offsetParent;
+        if (!cell || !host)
+            return;
+        const a = cell.getBoundingClientRect();
+        const b = host.getBoundingClientRect();
+        setPos({ x: a.left - b.left + a.width / 2, y: a.top - b.top });
+    }, [gridRef, cellKey]);
+    return (_jsx("div", { ref: ref, "aria-hidden": true, className: "vui-chart-tooltip pointer-events-none absolute z-10 flex -translate-x-1/2 -translate-y-full flex-col gap-0.5 rounded-ui-sm px-2.5 py-1.5 text-[12px] whitespace-nowrap", style: { left: pos?.x ?? 0, top: (pos?.y ?? 0) - 6, visibility: pos ? "visible" : "hidden" }, children: content }));
+}

package/dist/charts/index.d.ts

@@ -0,0 +1,12 @@
+export { CHART_HEIGHTS, resolveChartColor, seriesPalette, seriesColor, seriesVarName, resolveSeries, patternDash, formatValue, formatCategory, summarizeSeries, seriesStats, alignZeroDomains, niceStep, quantileBreaks, type ChartColor, type ChartDatePreset, type FormatSpec, type SeriesConfig, type SeriesPattern, type ChartConfig, type ChartState, type ChartHeight, type ResolvedSeries, type SeriesStats, } from "./utils.js";
+export { Chart, useChart, useOptionalChart, chartLabels, ChartLegendContent, ChartIndicator, ChartSkeleton, ChartRefreshBar, ChartEmpty, ChartError, ChartDataTable, type ChartProps, type ChartLabels, type ChartContextValue, type ChartSkeletonKind, type ChartTableColumn, type ChartTableSpec, type ChartLegendContentProps, type ChartDataTableProps, } from "./chart-shell.js";
+export { ChartFrame, ChartTooltip, ChartTooltipContent, ChartGrid, ChartXAxis, ChartYAxis, ChartReferenceLine, useValueAxisWidth, usePointClick, type ChartFrameProps, type ChartTooltipProps, type ChartTooltipContentProps, } from "./chart.js";
+export { AreaChart, type AreaChartProps, type ChartReference } from "./area-chart.js";
+export { BarChart, type BarChartProps } from "./bar-chart.js";
+export { BarList, type BarListProps, type BarListItem } from "./bar-list.js";
+export { LineChart, type LineChartProps } from "./line-chart.js";
+export { DonutChart, type DonutChartProps } from "./donut-chart.js";
+export { ComboChart, type ComboChartProps } from "./combo-chart.js";
+export { Funnel, funnelLabels, type FunnelProps, type FunnelStep, type FunnelLabels } from "./funnel.js";
+export { Gauge, ProgressRing, gaugeLabels, type GaugeProps, type ProgressRingProps, type GaugeThreshold, type GaugeLabels } from "./gauge.js";
+export { Heatmap, heatmapLabels, weekStartOf, type HeatmapProps, type HeatmapCell, type HeatmapCategory, type HeatmapLabels } from "./heatmap.js";

package/dist/charts/index.js

@@ -0,0 +1,14 @@
+// Public API of @vamos-ui/react/charts — owned by the charts group.
+// Recharts is only reachable through this subpath; pages without charts never load it.
+export { CHART_HEIGHTS, resolveChartColor, seriesPalette, seriesColor, seriesVarName, resolveSeries, patternDash, formatValue, formatCategory, summarizeSeries, seriesStats, alignZeroDomains, niceStep, quantileBreaks, } from "./utils.js";
+export { Chart, useChart, useOptionalChart, chartLabels, ChartLegendContent, ChartIndicator, ChartSkeleton, ChartRefreshBar, ChartEmpty, ChartError, ChartDataTable, } from "./chart-shell.js";
+export { ChartFrame, ChartTooltip, ChartTooltipContent, ChartGrid, ChartXAxis, ChartYAxis, ChartReferenceLine, useValueAxisWidth, usePointClick, } from "./chart.js";
+export { AreaChart } from "./area-chart.js";
+export { BarChart } from "./bar-chart.js";
+export { BarList } from "./bar-list.js";
+export { LineChart } from "./line-chart.js";
+export { DonutChart } from "./donut-chart.js";
+export { ComboChart } from "./combo-chart.js";
+export { Funnel, funnelLabels } from "./funnel.js";
+export { Gauge, ProgressRing, gaugeLabels } from "./gauge.js";
+export { Heatmap, heatmapLabels, weekStartOf } from "./heatmap.js";

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

@@ -0,0 +1,21 @@
+import * as React from "react";
+import { type ChartProps } from "./chart-shell.js";
+import type { ChartReference } from "./area-chart.js";
+export interface LineChartProps<T extends object> extends Omit<ChartProps<T>, "children"> {
+    series?: string[];
+    curve?: "monotone" | "linear" | "step";
+    /** Point markers. Default `"last"` (the latest value stands out). */
+    dots?: "none" | "last" | "all";
+    reference?: ChartReference[];
+    /** Series names written at the end of each line instead of a legend (≤ 4 series). */
+    endLabels?: boolean;
+}
+/**
+ * Multi-series trends and rates. With 3+ series prefer `endLabels` — direct labels do not rely on
+ * colour.
+ *
+ * ```tsx
+ * <LineChart title="Win rate by rep" data={rows} x="month" config={{ ada: { label: "Ada", format: "percent" } }} endLabels />
+ * ```
+ */
+export declare function LineChart<T extends object>({ series, curve, dots, reference, endLabels, legend, ...props }: LineChartProps<T>): React.JSX.Element;

package/dist/charts/line-chart.js

@@ -0,0 +1,36 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Line, LineChart as RLineChart } from "recharts";
+import { Chart, useChart } from "./chart-shell.js";
+import { ChartFrame, ChartGrid, ChartReferenceLine, ChartTooltip, ChartXAxis, ChartYAxis, usePointClick } from "./chart.js";
+import { patternDash, seriesColor } from "./utils.js";
+/**
+ * Multi-series trends and rates. With 3+ series prefer `endLabels` — direct labels do not rely on
+ * colour.
+ *
+ * ```tsx
+ * <LineChart title="Win rate by rep" data={rows} x="month" config={{ ada: { label: "Ada", format: "percent" } }} endLabels />
+ * ```
+ */
+export function LineChart({ series, curve = "monotone", dots = "last", reference, endLabels, legend, ...props }) {
+    return (_jsx(Chart, { skeleton: "line", legend: legend ?? (endLabels ? "none" : undefined), ...props, children: _jsx(LinePlot, { series: series, curve: curve, dots: dots, reference: reference, endLabels: endLabels }) }));
+}
+function LinePlot({ series: keys, curve, dots, reference, endLabels }) {
+    const chart = useChart();
+    const onClick = usePointClick();
+    const all = chart.series.filter((s) => (keys ? keys.includes(s.key) : true));
+    const lastIndex = chart.data.length - 1;
+    const type = curve === "step" ? "stepAfter" : curve;
+    if (process.env.NODE_ENV !== "production" && all.length > 6) {
+        console.warn("[vamos-ui] LineChart: more than 6 series — group the tail into \"Other\" or use small multiples.");
+    }
+    const labelRoom = endLabels ? Math.min(140, Math.max(...all.map((s) => s.label.length), 0) * 7 + 14) : 18;
+    return (_jsx(ChartFrame, { children: _jsxs(RLineChart, { data: chart.data, margin: { top: 8, right: labelRoom, bottom: 0, left: 0 }, onClick: onClick, style: onClick ? { cursor: "pointer" } : undefined, children: [_jsx(ChartGrid, {}), _jsx(ChartXAxis, {}), _jsx(ChartYAxis, { keys: all.map((s) => s.key) }), _jsx(ChartTooltip, { indicator: "line" }), reference?.map((r, i) => _jsx(ChartReferenceLine, { y: r.y, label: r.label, color: r.color, labelPosition: r.labelPosition }, i)), all.map((s) => (_jsx(Line, { dataKey: s.key, name: s.label, type: type, hide: chart.isHidden(s.key), stroke: seriesColor(s.key), strokeWidth: 2, strokeDasharray: patternDash(s.pattern), connectNulls: false, dot: (p) => {
+                        const show = dots === "all" || (dots === "last" && p.index === lastIndex) || chart.data.length === 1;
+                        if (!show || p.cx === undefined || p.cy === undefined)
+                            return _jsx("g", {}, `${s.key}-${p.index}`);
+                        return _jsx("circle", { cx: p.cx, cy: p.cy, r: 3, fill: seriesColor(s.key), stroke: "var(--chart-tooltip)", strokeWidth: 1.5 }, `${s.key}-${p.index}`);
+                    }, activeDot: { r: 4, strokeWidth: 2, stroke: "var(--chart-tooltip)", fill: seriesColor(s.key) }, label: endLabels
+                        ? (p) => p.index === lastIndex ? (_jsx("text", { x: Number(p.x) + 8, y: Number(p.y), dy: "0.32em", className: "vui-chart-end-label", fill: seriesColor(s.key), children: s.label }, `${s.key}-label`)) : (_jsx("g", {}, `${s.key}-l-${p.index}`))
+                        : undefined, isAnimationActive: chart.animate, animationDuration: 600 }, s.key)))] }) }));
+}

package/dist/charts/test-utils.d.ts

@@ -0,0 +1,2 @@
+/** Makes every ResizeObserver report a fixed size, so ResponsiveContainer renders its chart. */
+export declare function mockChartSize(width?: number, height?: number): () => void;