@vamos-ui/react 0.0.0-stage → 0.3.0

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;

package/dist/charts/test-utils.js

@@ -0,0 +1,38 @@
+// Test helpers for the charts subpath: give Recharts a measurable box in jsdom.
+import { vi } from "vitest";
+/** Makes every ResizeObserver report a fixed size, so ResponsiveContainer renders its chart. */
+export function mockChartSize(width = 640, height = 260) {
+    class SizedRO {
+        cb;
+        constructor(cb) {
+            this.cb = cb;
+        }
+        observe(target) {
+            const entry = { target, contentRect: { width, height, top: 0, left: 0, bottom: height, right: width, x: 0, y: 0 }, contentBoxSize: [{ inlineSize: width, blockSize: height }], borderBoxSize: [{ inlineSize: width, blockSize: height }] };
+            this.cb([entry], this);
+        }
+        unobserve() { }
+        disconnect() { }
+    }
+    const prevRO = globalThis.ResizeObserver;
+    globalThis.ResizeObserver = SizedRO;
+    // Only chart containers report a size; text measurement spans stay 0 so ticks are not culled.
+    const realRect = HTMLElement.prototype.getBoundingClientRect;
+    const rect = vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockImplementation(function () {
+        if (this.classList.contains("recharts-responsive-container") || this.dataset.slot === "chart-frame")
+            return { width, height, top: 0, left: 0, bottom: height, right: width, x: 0, y: 0, toJSON() { } };
+        return realRect.call(this);
+    });
+    const ow = vi.spyOn(HTMLElement.prototype, "offsetWidth", "get").mockReturnValue(width);
+    const oh = vi.spyOn(HTMLElement.prototype, "offsetHeight", "get").mockReturnValue(height);
+    const cw = vi.spyOn(HTMLElement.prototype, "clientWidth", "get").mockReturnValue(width);
+    const ch = vi.spyOn(HTMLElement.prototype, "clientHeight", "get").mockReturnValue(height);
+    return () => {
+        globalThis.ResizeObserver = prevRO;
+        rect.mockRestore();
+        ow.mockRestore();
+        oh.mockRestore();
+        cw.mockRestore();
+        ch.mockRestore();
+    };
+}

package/dist/charts/utils.d.ts

@@ -0,0 +1,130 @@
+import type { ComponentType, ReactNode } from "react";
+import type { DatePreset, Formatter } from "../format/core.js";
+/** A colour token a series can use. Never a hex value — the token follows every theme axis. */
+export type ChartColor = "chart-1" | "chart-2" | "chart-3" | "chart-4" | "chart-5" | "chart-6" | "accent" | "accent-ink" | "success" | "warning" | "danger" | "info" | "fg-subtle" | "fg-muted";
+/** Date presets for chart axes and tooltips (the format module's presets + short axis forms). */
+export type ChartDatePreset = DatePreset | "day-month" | "month" | "month-short-year" | "hour" | "weekday-short";
+/**
+ * How a value is written. Strings use the locale formatter; objects pick a currency or a date preset;
+ * a function gets the raw value and the locale.
+ */
+export type FormatSpec = "number" | "integer" | "compact" | "percent" | "currency" | "duration" | "bytes" | {
+    currency: string;
+    compact?: boolean;
+} | {
+    date: ChartDatePreset | Intl.DateTimeFormatOptions;
+    timeZoneName?: "short";
+} | {
+    relative: true;
+} | ((value: unknown, locale: string) => string);
+export type SeriesPattern = "solid" | "dashed" | "dotted";
+export interface SeriesConfig {
+    /** Shown in legend, tooltip, table header and summary. */
+    label: string;
+    /** Colour token. Default: chart-1…chart-6 in config order. */
+    color?: ChartColor;
+    /** How values of this series are written. Default `"number"`. */
+    format?: FormatSpec;
+    /** Value axis side (Combo). Logical: `start` is left in LTR, right in RTL. */
+    axis?: "start" | "end";
+    /** Stroke pattern. Auto-assigned when a chart has more than 3 series (colour-blind safety). */
+    pattern?: SeriesPattern;
+    /** Small icon before the legend label (a lucide icon or any component taking className). */
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    /** Start hidden (the legend can show it again). */
+    hidden?: boolean;
+}
+/** Series key → its settings. Key order is legend and colour order. */
+export type ChartConfig = Record<string, SeriesConfig>;
+export type ChartState = {
+    status: "ready";
+} | {
+    status: "loading";
+} | {
+    status: "refreshing";
+} | {
+    status: "empty";
+    message?: ReactNode;
+    action?: ReactNode;
+} | {
+    status: "error";
+    message?: ReactNode;
+    onRetry?: () => void;
+};
+export type ChartHeight = number | "sm" | "md" | "lg";
+export declare const CHART_HEIGHTS: {
+    readonly sm: 160;
+    readonly md: 260;
+    readonly lg: 360;
+};
+/** `"chart-2"` → `"var(--chart-2)"`. */
+export declare function resolveChartColor(color: ChartColor): string;
+/** The first `n` palette tokens (wraps after 6). */
+export declare function seriesPalette(n: number): ChartColor[];
+/** A CSS-identifier-safe version of a series key, used in `--series-<key>` variables. */
+export declare function seriesVarName(key: string): string;
+/** `var(--series-<key>)` — the colour of a series inside a Chart. */
+export declare function seriesColor(key: string): string;
+export interface ResolvedSeries extends SeriesConfig {
+    key: string;
+    color: ChartColor;
+    pattern: SeriesPattern;
+    index: number;
+}
+/** Fills in colour and pattern defaults for every series of a config. */
+export declare function resolveSeries(config: ChartConfig): ResolvedSeries[];
+/** SVG dash array for a pattern. */
+export declare function patternDash(pattern: SeriesPattern | undefined): string | undefined;
+/**
+ * Writes a value with a FormatSpec. `compact` shortens numbers and money for axis ticks
+ * ("$1.2M", "₺1,2 Mn"); tooltips and tables use the full form. Missing values → "—".
+ */
+export declare function formatValue(f: Formatter, spec: FormatSpec | undefined, value: unknown, options?: {
+    compact?: boolean;
+    compactFrom?: number;
+}): string;
+/** Default x formatter: `YYYY-MM-DD` strings become "Nov 1", everything else is printed as is. */
+export declare function formatCategory(f: Formatter, spec: FormatSpec | undefined, value: unknown, long?: boolean): string;
+/** Estimated pixel width of a y-axis from its longest formatted tick (11px tabular text). */
+export declare function estimateAxisWidth(labels: string[], fontSize?: number): number;
+/** Numeric min / max over some keys of the rows (stacked → per-row sums). */
+export declare function extent(rows: Record<string, unknown>[], keys: string[], stacked?: boolean): [number, number];
+/** Rounds a max up to a "nice" tick (1, 2, 2.5, 5 × 10ⁿ). */
+export declare function niceCeil(v: number): number;
+/** A "nice" tick step at or above `v` (1, 1.5, 2, 2.5, 3, 4, 5, 6, 8 × 10ⁿ). */
+export declare function niceStep(v: number): number;
+/**
+ * Two value-axis domains whose zero lines meet (Combo). Each input is a `[min, max]` extent.
+ * Returns domains with the same negative share, so neither axis exaggerates.
+ */
+export declare function alignZeroDomains(a: [number, number], b: [number, number]): [[number, number], [number, number]];
+export interface SeriesStats {
+    key: string;
+    min: number;
+    max: number;
+    avg: number;
+    minIndex: number;
+    maxIndex: number;
+    count: number;
+}
+/** Min / max / average of one series (nulls skipped). `null` when the series has no numbers. */
+export declare function seriesStats(rows: Record<string, unknown>[], key: string): SeriesStats | null;
+/**
+ * A one-paragraph text summary of a chart for screen readers:
+ * "Nov 1 – Nov 30. Visits: low 812 (Nov 3), high 1,402 (Nov 28), average 1,090."
+ */
+export declare function summarizeSeries(options: {
+    f: Formatter;
+    rows: Record<string, unknown>[];
+    series: Pick<ResolvedSeries, "key" | "label" | "format">[];
+    x?: string;
+    xFormat?: FormatSpec;
+    templates?: {
+        range?: string;
+        series?: string;
+    };
+}): string;
+/** Equal-count (quantile) break points for `steps` buckets. Returns `steps - 1` thresholds. */
+export declare function quantileBreaks(values: number[], steps: number): number[];