@tulipfarm/sprout 0.3.0 → 0.4.0

package/dist/internal/charts/more.d.ts

@@ -0,0 +1,77 @@
+import { type ChartRow, type ChartSeries, type ReadyChartProps, type ValueFormatter } from '../chart-kit.js';
+export interface HeatmapChartProps extends ReadyChartProps {
+    /** One row per cell, keyed by `x`, `y`, and `value`. */
+    rows: ChartRow[];
+    /** The row key naming each column, such as the hour. */
+    x: string;
+    /** The row key naming each row, such as the weekday. */
+    y: string;
+    /** The row key holding each cell's number. */
+    value: string;
+    /** Any CSS color for the darkest cells. Defaults to `--sprout-chart-1`. */
+    color?: string;
+    /** Words at each end of the scale. */
+    scaleLabels?: [low: string, high: string];
+}
+/**
+ * A grid of cells in five shades of one color, like activity by weekday and
+ * hour. Columns and rows keep the order they first appear in `rows`. It is a
+ * real table, so screen readers read every value.
+ */
+export declare function HeatmapChart({ rows, x, y, value, color, scaleLabels, title, valueFormatter, className, }: HeatmapChartProps): import("react").JSX.Element;
+/** A series for `ScatterPlotChart`, with its own rows. */
+export type ScatterSeries = ChartSeries & {
+    rows: ChartRow[];
+};
+export interface ScatterPlotChartProps extends ReadyChartProps {
+    series: ScatterSeries[];
+    /** The row key for the x axis. */
+    x: string;
+    /** The row key for the y axis. */
+    y: string;
+    /** A row key that sizes each dot, for a bubble chart. */
+    size?: string;
+    /** Axis names for the tooltip. Default to the keys. */
+    labels?: {
+        x?: string;
+        y?: string;
+        size?: string;
+    };
+    /** Formats x axis ticks. `valueFormatter` formats the y axis. */
+    xValueFormatter?: ValueFormatter;
+}
+/**
+ * One dot per row on two number axes, 288px tall, to show how two numbers
+ * move together. Pass `size` for bubbles.
+ */
+export declare function ScatterPlotChart({ series, x, y, size, labels, title, valueFormatter, xValueFormatter, className, }: ScatterPlotChartProps): import("react").JSX.Element;
+export interface SankeyChartProps extends ReadyChartProps {
+    /** Every stage, in any order. Links point at them by index. */
+    nodes: {
+        name: string;
+    }[];
+    /** Flows between nodes, by index into `nodes`. */
+    links: {
+        source: number;
+        target: number;
+        value: number;
+    }[];
+}
+/**
+ * Flows between stages, with band width by value, 320px tall. The first five
+ * nodes get chart colors and the rest are muted; each band takes its
+ * source's color.
+ */
+export declare function SankeyChart({ nodes, links, title, valueFormatter, className, }: SankeyChartProps): import("react").JSX.Element;
+export interface RadarScoreChartProps extends ReadyChartProps {
+    /** One row per axis, keyed by `category` and each series. */
+    rows: ChartRow[];
+    /** The row key naming each axis, such as "Speed" or "Price". */
+    category: string;
+    series: ChartSeries[];
+}
+/**
+ * Scores on many axes at once, one filled shape per series, 320px tall.
+ * Good for comparing two or three options.
+ */
+export declare function RadarScoreChart({ rows, category, series, title, valueFormatter, className, }: RadarScoreChartProps): import("react").JSX.Element;

package/dist/internal/charts/more.js

@@ -0,0 +1,68 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { CartesianGrid, PolarAngleAxis, PolarGrid, Radar, RadarChart, Sankey, Scatter, ScatterChart, XAxis, YAxis, ZAxis, } from 'recharts';
+import { cn } from '../classes.js';
+import { ChartContainer, ChartLegend, ChartLegendContent, ChartTooltip, ChartTooltipContent, chartColor, chartShade, configLegend, formatNumber, partColor, quietAxis, seriesConfig, } from '../chart-kit.js';
+const HEAT_STEPS = 5;
+/**
+ * A grid of cells in five shades of one color, like activity by weekday and
+ * hour. Columns and rows keep the order they first appear in `rows`. It is a
+ * real table, so screen readers read every value.
+ */
+export function HeatmapChart({ rows, x, y, value, color = 'var(--sprout-chart-1)', scaleLabels = ['Less', 'More'], title = `${value} by ${y} and ${x}`, valueFormatter = formatNumber, className, }) {
+    const grid = useMemo(() => {
+        const columns = [...new Set(rows.map(row => String(row[x])))];
+        const lines = [...new Set(rows.map(row => String(row[y])))];
+        const cells = new Map(rows.map(row => [`${String(row[y])}\u0000${String(row[x])}`, Number(row[value]) || 0]));
+        const max = Math.max(0, ...cells.values());
+        return { columns, lines, cells, max };
+    }, [rows, x, y, value]);
+    const shade = (step) => (step === 0 ? 'var(--sprout-secondary)' : chartShade(color, step));
+    const step = (amount) => (grid.max > 0 && amount > 0 ? Math.ceil((amount / grid.max) * HEAT_STEPS) : 0);
+    return (_jsxs("div", { "data-slot": "chart", "data-variant": "heatmap", className: cn('sprout-chart-heatmap', className), children: [_jsx("div", { className: "sprout-chart-heatmap-scroll", children: _jsxs("table", { className: "sprout-chart-heatmap-table", style: { '--sprout-heat-columns': grid.columns.length }, children: [_jsx("caption", { className: "sprout-chart-sr-only", children: title }), _jsx("thead", { children: _jsxs("tr", { children: [_jsx("td", {}), grid.columns.map(column => (_jsx("th", { scope: "col", children: column }, column)))] }) }), _jsx("tbody", { children: grid.lines.map(line => (_jsxs("tr", { children: [_jsx("th", { scope: "row", children: line }), grid.columns.map(column => {
+                                        const amount = grid.cells.get(`${line}\u0000${column}`) ?? 0;
+                                        const text = valueFormatter(amount);
+                                        return (_jsx("td", { "data-tip": `${line} · ${column}: ${text}`, style: { backgroundColor: shade(step(amount)) }, children: _jsx("span", { className: "sprout-chart-sr-only", children: text }) }, column));
+                                    })] }, line))) })] }) }), _jsxs("div", { className: "sprout-chart-heatmap-scale", "aria-hidden": "true", children: [_jsx("span", { children: scaleLabels[0] }), Array.from({ length: HEAT_STEPS + 1 }, (_, index) => (_jsx("i", { style: { backgroundColor: shade(index) } }, index))), _jsx("span", { children: scaleLabels[1] })] })] }));
+}
+/**
+ * One dot per row on two number axes, 288px tall, to show how two numbers
+ * move together. Pass `size` for bubbles.
+ */
+export function ScatterPlotChart({ series, x, y, size, labels, title, valueFormatter = formatNumber, xValueFormatter = formatNumber, className, }) {
+    const config = useMemo(() => seriesConfig(series), [series]);
+    return (_jsx(ChartContainer, { "data-variant": "scatter", className: cn('sprout-chart-scatter', className), config: config, children: _jsxs(ScatterChart, { accessibilityLayer: true, title: title ?? `${labels?.y ?? y} by ${labels?.x ?? x}`, margin: { top: 8, right: 12, bottom: 0, left: 0 }, children: [_jsx(CartesianGrid, {}), _jsx(XAxis, { type: "number", dataKey: x, name: labels?.x ?? x, tickFormatter: xValueFormatter, ...quietAxis }), _jsx(YAxis, { type: "number", dataKey: y, name: labels?.y ?? y, width: "auto", tickFormatter: valueFormatter, ...quietAxis }), size ? (_jsx(ZAxis, { type: "number", dataKey: size, name: labels?.size ?? size, range: [40, 480] })) : (_jsx(ZAxis, { range: [48, 48] })), _jsx(ChartTooltip, { cursor: { strokeDasharray: '3 3' }, content: props => (_jsx(ChartTooltipContent, { active: props.active, hideLabel: true, payload: props.payload?.map(item => ({
+                            ...item,
+                            value: typeof item.value === 'number'
+                                ? (item.dataKey === x ? xValueFormatter : valueFormatter)(item.value)
+                                : item.value,
+                        })) })) }), series.length > 1 ? _jsx(ChartLegend, { content: configLegend(config) }) : null, series.map(item => (_jsx(Scatter, { name: item.label, data: item.rows, fill: chartColor(item.key), fillOpacity: 0.8, isAnimationActive: false }, item.key)))] }) }));
+}
+/**
+ * Flows between stages, with band width by value, 320px tall. The first five
+ * nodes get chart colors and the rest are muted; each band takes its
+ * source's color.
+ */
+export function SankeyChart({ nodes, links, title = 'Flow between stages', valueFormatter = formatNumber, className, }) {
+    const data = useMemo(() => ({ nodes, links }), [nodes, links]);
+    const config = useMemo(() => Object.fromEntries(nodes.map((node, index) => [node.name, { label: node.name, color: partColor(index) }])), [nodes]);
+    const node = ({ x, y, width, height, index, payload }) => {
+        // Recharts names a node's outgoing links `targetLinks`.
+        const last = !payload.targetLinks?.length;
+        return (_jsxs("g", { children: [_jsx("rect", { x: x, y: y, width: width, height: height, rx: 2, fill: partColor(index) }), _jsxs("text", { x: last ? x - 8 : x + width + 8, y: y + height / 2, textAnchor: last ? 'end' : 'start', dominantBaseline: "middle", className: "sprout-chart-sankey-label", children: [payload.name, _jsx("tspan", { className: "sprout-chart-sankey-value", dx: 6, children: valueFormatter(payload.value) })] })] }));
+    };
+    const link = ({ sourceX, targetX, sourceY, targetY, sourceControlX, targetControlX, linkWidth, payload, }) => {
+        const source = nodes.findIndex(item => item.name === payload.source.name);
+        return (_jsx("path", { d: `M${sourceX},${sourceY}C${sourceControlX},${sourceY} ${targetControlX},${targetY} ${targetX},${targetY}`, fill: "none", stroke: partColor(source), strokeOpacity: 0.28, strokeWidth: linkWidth, className: "sprout-chart-sankey-link" }));
+    };
+    return (_jsx(ChartContainer, { "data-variant": "sankey", className: cn('sprout-chart-sankey', className), config: config, role: "img", "aria-label": title, children: _jsx(Sankey, { data: data, nodePadding: 24, nodeWidth: 10, margin: { top: 8, right: 8, bottom: 8, left: 8 }, node: node, link: link, children: _jsx(ChartTooltip, { content: _jsx(ChartTooltipContent, { hideLabel: true, valueFormatter: valueFormatter }) }) }) }));
+}
+/**
+ * Scores on many axes at once, one filled shape per series, 320px tall.
+ * Good for comparing two or three options.
+ */
+export function RadarScoreChart({ rows, category, series, title, valueFormatter = formatNumber, className, }) {
+    const config = useMemo(() => seriesConfig(series), [series]);
+    return (_jsx(ChartContainer, { "data-variant": "radar", className: cn('sprout-chart-radar', className), config: config, children: _jsxs(RadarChart, { data: rows, accessibilityLayer: true, title: title ?? `${series.map(item => item.label).join(', ')} by ${category}`, outerRadius: "72%", children: [_jsx(PolarGrid, {}), _jsx(PolarAngleAxis, { dataKey: category }), _jsx(ChartTooltip, { content: _jsx(ChartTooltipContent, { indicator: "line", valueFormatter: valueFormatter }) }), series.length > 1 ? _jsx(ChartLegend, { itemSorter: null, content: _jsx(ChartLegendContent, {}) }) : null, series.map(item => (_jsx(Radar, { dataKey: item.key, stroke: chartColor(item.key), strokeWidth: 2, fill: chartColor(item.key), fillOpacity: 0.18, dot: { r: 3, fillOpacity: 1 }, isAnimationActive: false }, item.key)))] }) }));
+}

package/dist/internal/charts/parts.d.ts

@@ -0,0 +1,54 @@
+import { type ChartRow, type ReadyChartProps } from '../chart-kit.js';
+interface PartChartProps extends ReadyChartProps {
+    /** One row per part, keyed by `category` and `value`. */
+    rows: ChartRow[];
+    /** The row key whose value names each part. */
+    category: string;
+    /** The row key holding each part's number. */
+    value: string;
+}
+export interface DonutChartProps extends PartChartProps {
+    /** `donut` leaves a hole with the total in it; `pie` fills the circle. */
+    variant?: 'donut' | 'pie';
+    /** Words under the total in the hole, such as "Visitors". */
+    totalLabel?: string;
+}
+/**
+ * Shares of a whole as slices, largest first, 288px tall with a legend. The
+ * top five parts get chart colors; the rest fold into one muted "N more".
+ */
+export declare function DonutChart({ rows, category, value, variant, totalLabel, title, valueFormatter, className, }: DonutChartProps): import("react").JSX.Element;
+export interface StepFunnelChartProps extends PartChartProps {
+    /** Any CSS color for the first step. Later steps get lighter shades. */
+    color?: string;
+}
+/**
+ * Drop-off from step to step, as centered bars that narrow like a funnel.
+ * Step names sit on the left; each step's count and share of the first sit
+ * on the right. One 40px row per step.
+ */
+export declare function StepFunnelChart({ rows, category, value, color, title, valueFormatter, className, }: StepFunnelChartProps): import("react").JSX.Element;
+export type TreemapChartProps = PartChartProps;
+/**
+ * Boxes sized by value, largest top left, 288px tall. The top five get chart
+ * colors; the rest fold into one muted "N more" box.
+ */
+export declare function TreemapChart({ rows, category, value, title, valueFormatter, className, }: TreemapChartProps): import("react").JSX.Element;
+export interface GaugeChartProps {
+    /** How far along, in the same unit as `max`. */
+    value: number;
+    /** The goal. Defaults to 100. */
+    max?: number;
+    /** Words under the number, such as "of quota". */
+    label?: string;
+    /** Names the gauge for screen readers, such as "Q3 quota attainment". */
+    title: string;
+    /** Any CSS color. Defaults to `--sprout-chart-1`. */
+    color?: string;
+    /** Formats the number in the middle. Defaults to percent of `max`. */
+    valueFormatter?: (value: number, max: number) => string;
+    className?: string;
+}
+/** Progress toward a goal as a half ring with the number in the middle. */
+export declare function GaugeChart({ value, max, label, title, color, valueFormatter, className, }: GaugeChartProps): import("react").JSX.Element;
+export {};

package/dist/internal/charts/parts.js

@@ -0,0 +1,82 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { Bar, BarChart, Label, Pie, PieChart, PolarAngleAxis, PolarRadiusAxis, RadialBar, RadialBarChart, Treemap, XAxis, YAxis, } from 'recharts';
+import { cn } from '../classes.js';
+import { ChartContainer, ChartLegend, ChartTooltip, ChartTooltipContent, chartShade, configLegend, foldParts, formatNumber, partConfig, quietAxis, rowFillShape, tooltipCursor, } from '../chart-kit.js';
+const centerText = (viewBox, main, sub, lift = 0) => {
+    // A Pie hands its Label the plot box; a polar axis hands it the circle.
+    const box = viewBox;
+    const cx = box?.cx ?? (box?.x ?? 0) + (box?.width ?? NaN) / 2;
+    const cy = box?.cy ?? (box?.y ?? 0) + (box?.height ?? NaN) / 2;
+    if (!Number.isFinite(cx) || !Number.isFinite(cy))
+        return null;
+    const y = cy - lift;
+    return (_jsxs("text", { x: cx, y: y, textAnchor: "middle", dominantBaseline: "middle", className: "sprout-chart-center", children: [_jsx("tspan", { x: cx, y: sub ? y - 8 : y, className: "sprout-chart-center-value", children: main }), sub ? (_jsx("tspan", { x: cx, y: y + 14, className: "sprout-chart-center-label", children: sub })) : null] }));
+};
+/**
+ * Shares of a whole as slices, largest first, 288px tall with a legend. The
+ * top five parts get chart colors; the rest fold into one muted "N more".
+ */
+export function DonutChart({ rows, category, value, variant = 'donut', totalLabel, title, valueFormatter = formatNumber, className, }) {
+    const parts = useMemo(() => foldParts(rows, category, value), [rows, category, value]);
+    const config = useMemo(() => partConfig(parts), [parts]);
+    const total = parts.reduce((sum, part) => sum + part.value, 0);
+    const donut = variant === 'donut';
+    return (_jsx(ChartContainer, { "data-variant": variant, className: cn('sprout-chart-donut', className), config: config, children: _jsxs(PieChart, { accessibilityLayer: true, title: title ?? `${value} by ${category}`, children: [_jsx(ChartTooltip, { content: _jsx(ChartTooltipContent, { hideLabel: true, valueFormatter: valueFormatter }) }), _jsx(ChartLegend, { content: configLegend(config) }), _jsx(Pie, { data: parts, dataKey: "value", nameKey: "name", innerRadius: donut ? '62%' : 0, outerRadius: "92%", paddingAngle: donut && parts.length > 1 ? 2 : 0, cornerRadius: donut ? 3 : 0, stroke: "var(--sprout-surface)", strokeWidth: donut ? 0 : 1, isAnimationActive: false, children: donut ? (_jsx(Label, { position: "center", content: ({ viewBox }) => centerText(viewBox, valueFormatter(total), totalLabel) })) : null })] }) }));
+}
+/**
+ * Drop-off from step to step, as centered bars that narrow like a funnel.
+ * Step names sit on the left; each step's count and share of the first sit
+ * on the right. One 40px row per step.
+ */
+export function StepFunnelChart({ rows, category, value, color = 'var(--sprout-chart-1)', title = 'Conversion by step', valueFormatter = formatNumber, className, }) {
+    const steps = useMemo(() => {
+        const values = rows.map(row => Math.max(0, Number(row[value]) || 0));
+        const top = Math.max(0, ...values);
+        const first = values[0] || 1;
+        return rows.map((row, index) => {
+            const count = values[index] ?? 0;
+            const share = Math.round((count / first) * 100);
+            return {
+                name: String(row[category] ?? ''),
+                detail: `${valueFormatter(count)} · ${share}%`,
+                count,
+                range: [(top - count) / 2, (top + count) / 2],
+                // Fades only to about half, so the last, smallest step stays visible.
+                fill: chartShade(color, rows.length * 2 - index, rows.length * 2),
+            };
+        });
+    }, [rows, category, value, color, valueFormatter]);
+    const config = useMemo(() => ({ count: { label: value, color } }), [value, color]);
+    return (_jsx(ChartContainer, { "data-variant": "funnel", className: cn('sprout-chart-funnel', className), style: { height: `${steps.length * 2.5 + 1}rem` }, config: config, children: _jsxs(BarChart, { data: steps, accessibilityLayer: true, title: title, layout: "vertical", barCategoryGap: "12%", margin: { top: 8, right: 0, bottom: 8, left: 0 }, children: [_jsx(XAxis, { type: "number", hide: true, domain: [0, 'dataMax'] }), _jsx(YAxis, { yAxisId: "name", type: "category", dataKey: "name", width: "auto", ...quietAxis, interval: 0 }), _jsx(YAxis, { yAxisId: "detail", type: "category", dataKey: "detail", orientation: "right", width: "auto", ...quietAxis, interval: 0 }), _jsx(ChartTooltip, { cursor: tooltipCursor, content: props => (_jsx(ChartTooltipContent, { active: props.active, label: props.label, valueFormatter: valueFormatter, payload: props.payload?.map(item => ({
+                            ...item,
+                            name: 'count',
+                            value: item.payload.count,
+                            color,
+                        })) })) }), _jsx(Bar, { yAxisId: "name", dataKey: "range", radius: 4, shape: rowFillShape, isAnimationActive: false })] }) }));
+}
+const treemapBox = (node, format) => {
+    const { x, y, width, height, depth } = node;
+    if (depth !== 1)
+        return _jsx("g", {});
+    const fill = node.fill;
+    const roomy = width > 64 && height > 36;
+    return (_jsxs("g", { children: [_jsx("rect", { x: x, y: y, width: width, height: height, rx: 4, fill: fill, stroke: "var(--sprout-surface)", strokeWidth: 2 }), roomy ? (_jsxs("text", { x: x + 8, y: y + 18, className: "sprout-chart-treemap-label", children: [_jsx("tspan", { x: x + 8, children: node.name }), _jsx("tspan", { x: x + 8, dy: 16, className: "sprout-chart-treemap-value", children: format(node.value) })] })) : null] }));
+};
+/**
+ * Boxes sized by value, largest top left, 288px tall. The top five get chart
+ * colors; the rest fold into one muted "N more" box.
+ */
+export function TreemapChart({ rows, category, value, title, valueFormatter = formatNumber, className, }) {
+    const parts = useMemo(() => foldParts(rows, category, value), [rows, category, value]);
+    const config = useMemo(() => partConfig(parts), [parts]);
+    return (_jsx(ChartContainer, { "data-variant": "treemap", className: cn('sprout-chart-treemap', className), config: config, role: "img", "aria-label": title ?? `${value} by ${category}`, children: _jsx(Treemap, { data: parts, dataKey: "value", nameKey: "name", aspectRatio: 4 / 3, isAnimationActive: false, content: (node) => treemapBox(node, valueFormatter), children: _jsx(ChartTooltip, { content: _jsx(ChartTooltipContent, { hideLabel: true, valueFormatter: valueFormatter }) }) }) }));
+}
+const percentOfMax = (value, max) => `${Math.round((value / (max || 1)) * 100)}%`;
+/** Progress toward a goal as a half ring with the number in the middle. */
+export function GaugeChart({ value, max = 100, label, title, color = 'var(--sprout-chart-1)', valueFormatter = percentOfMax, className, }) {
+    const data = useMemo(() => [{ name: 'value', value: Math.min(Math.max(value, 0), max), fill: color }], [value, max, color]);
+    const config = useMemo(() => ({ value: { label: title, color } }), [title, color]);
+    return (_jsx(ChartContainer, { "data-variant": "gauge", className: cn('sprout-chart-gauge', className), config: config, role: "meter", "aria-label": title, "aria-valuemin": 0, "aria-valuemax": max, "aria-valuenow": data[0].value, "aria-valuetext": valueFormatter(value, max), children: _jsxs(RadialBarChart, { data: data, startAngle: 180, endAngle: 0, cy: "78%", innerRadius: "118%", outerRadius: "158%", children: [_jsx(PolarAngleAxis, { type: "number", domain: [0, max], tick: false }), _jsx(RadialBar, { dataKey: "value", background: true, cornerRadius: 6, isAnimationActive: false }), _jsx(PolarRadiusAxis, { tick: false, axisLine: false, children: _jsx(Label, { content: ({ viewBox }) => centerText(viewBox, valueFormatter(value, max), label, 12) }) })] }) }));
+}

package/dist/internal/charts/timeline-dates.d.ts

@@ -0,0 +1,38 @@
+export declare const timelineZoomNames: readonly ["week", "month", "quarter"];
+/** How much time one timeline window shows. */
+export type TimelineZoom = (typeof timelineZoomNames)[number];
+/** A window's first and last day, both `YYYY-MM-DD` and inclusive. */
+export interface TimelineRange {
+    start: string;
+    end: string;
+}
+export declare const DAY = 86400000;
+/** True for a real calendar date written `YYYY-MM-DD`. */
+export declare const isCalendarDate: (value: unknown) => value is string;
+/** Midnight UTC of a `YYYY-MM-DD` date, in ms. Calendar dates have no time zone. */
+export declare const dayTime: (date: string) => number;
+/** The `YYYY-MM-DD` date of a UTC time in ms. */
+export declare const dayString: (time: number) => string;
+/**
+ * The window of `zoom` that contains `from`: its first and last day,
+ * inclusive. Pure calendar math, so it gives the same answer in every time
+ * zone. Use it for the query too, so the drawn window and the read window
+ * match. Weeks start on Monday unless `weekStartsOn` is 0 (Sunday).
+ */
+export declare function timelineRange(zoom: TimelineZoom, from: string, weekStartsOn?: 0 | 1): TimelineRange;
+/**
+ * The first day of the window before (`-1`) or after (`1`) the one that
+ * contains `from`.
+ */
+export declare function shiftTimeline(zoom: TimelineZoom, from: string, step: -1 | 1, weekStartsOn?: 0 | 1): string;
+/** The window's name: "October 2026", "12–18 Oct 2026", or "Q4 2026". */
+/** ICU versions differ on thin and narrow spaces, so server and browser text would not match. */
+export declare const plainSpaces: (text: string) => string;
+export declare function timelineTitle(zoom: TimelineZoom, from: string, weekStartsOn?: 0 | 1, locale?: string): string;
+/**
+ * The wall-clock time of `time` in `timeZone` (default: the reader's), as ms
+ * read as if it were UTC. It puts timestamps on the same axis as dates.
+ */
+export declare function wallClock(time: number, timeZone?: string): number;
+/** Today as `YYYY-MM-DD` in `timeZone`, or in the reader's time zone. */
+export declare const timelineToday: (timeZone?: string, now?: number) => string;

package/dist/internal/charts/timeline-dates.js

@@ -0,0 +1,113 @@
+export const timelineZoomNames = ['week', 'month', 'quarter'];
+export const DAY = 86_400_000;
+const DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+const utc = (year, month, day) => {
+    const date = new Date(0);
+    date.setUTCFullYear(year, month, day);
+    return date.getTime();
+};
+const parts = (date) => {
+    const match = DATE.exec(date);
+    const [year, month, day] = match ? [Number(match[1]), Number(match[2]) - 1, Number(match[3])] : [];
+    if (year === undefined || month === undefined || day === undefined)
+        throw new RangeError(`Not a YYYY-MM-DD date: ${date}`);
+    const time = utc(year, month, day);
+    const check = new Date(time);
+    if (check.getUTCMonth() !== month || check.getUTCDate() !== day)
+        throw new RangeError(`Not a calendar date: ${date}`);
+    return { year, month, day, time };
+};
+/** True for a real calendar date written `YYYY-MM-DD`. */
+export const isCalendarDate = (value) => {
+    if (typeof value !== 'string' || !DATE.test(value))
+        return false;
+    try {
+        parts(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/** Midnight UTC of a `YYYY-MM-DD` date, in ms. Calendar dates have no time zone. */
+export const dayTime = (date) => parts(date).time;
+/** The `YYYY-MM-DD` date of a UTC time in ms. */
+export const dayString = (time) => {
+    const date = new Date(time);
+    const year = String(date.getUTCFullYear()).padStart(4, '0');
+    const month = String(date.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(date.getUTCDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+};
+/**
+ * The window of `zoom` that contains `from`: its first and last day,
+ * inclusive. Pure calendar math, so it gives the same answer in every time
+ * zone. Use it for the query too, so the drawn window and the read window
+ * match. Weeks start on Monday unless `weekStartsOn` is 0 (Sunday).
+ */
+export function timelineRange(zoom, from, weekStartsOn = 1) {
+    const { year, month, time } = parts(from);
+    if (zoom === 'week') {
+        const offset = (new Date(time).getUTCDay() - weekStartsOn + 7) % 7;
+        const start = time - offset * DAY;
+        return { start: dayString(start), end: dayString(start + 6 * DAY) };
+    }
+    const first = zoom === 'month' ? month : month - (month % 3);
+    const months = zoom === 'month' ? 1 : 3;
+    return { start: dayString(utc(year, first, 1)), end: dayString(utc(year, first + months, 0)) };
+}
+/**
+ * The first day of the window before (`-1`) or after (`1`) the one that
+ * contains `from`.
+ */
+export function shiftTimeline(zoom, from, step, weekStartsOn = 1) {
+    const { start } = timelineRange(zoom, from, weekStartsOn);
+    const { year, month, time } = parts(start);
+    if (zoom === 'week')
+        return dayString(time + step * 7 * DAY);
+    return dayString(utc(year, month + step * (zoom === 'month' ? 1 : 3), 1));
+}
+/** The window's name: "October 2026", "12–18 Oct 2026", or "Q4 2026". */
+/** ICU versions differ on thin and narrow spaces, so server and browser text would not match. */
+export const plainSpaces = (text) => text.replaceAll(/[\u2009\u202f]/g, ' ');
+export function timelineTitle(zoom, from, weekStartsOn = 1, locale) {
+    const range = timelineRange(zoom, from, weekStartsOn);
+    const start = parts(range.start);
+    if (zoom === 'quarter')
+        return `Q${Math.floor(start.month / 3) + 1} ${start.year}`;
+    if (zoom === 'month')
+        return new Intl.DateTimeFormat(locale, { month: 'long', year: 'numeric', timeZone: 'UTC' }).format(start.time);
+    return plainSpaces(new Intl.DateTimeFormat(locale, {
+        day: 'numeric',
+        month: 'short',
+        year: 'numeric',
+        timeZone: 'UTC',
+    }).formatRange(start.time, dayTime(range.end)));
+}
+const clocks = new Map();
+/**
+ * The wall-clock time of `time` in `timeZone` (default: the reader's), as ms
+ * read as if it were UTC. It puts timestamps on the same axis as dates.
+ */
+export function wallClock(time, timeZone) {
+    const key = timeZone ?? '';
+    let clock = clocks.get(key);
+    if (!clock) {
+        clock = new Intl.DateTimeFormat('en-US', {
+            timeZone,
+            hourCycle: 'h23',
+            year: 'numeric',
+            month: 'numeric',
+            day: 'numeric',
+            hour: 'numeric',
+            minute: 'numeric',
+            second: 'numeric',
+        });
+        clocks.set(key, clock);
+    }
+    const part = Object.fromEntries(clock.formatToParts(time).map(item => [item.type, Number(item.value)]));
+    const seconds = ((part.hour ?? 0) * 60 + (part.minute ?? 0)) * 60 + (part.second ?? 0);
+    return (utc(part.year ?? 1970, (part.month ?? 1) - 1, part.day ?? 1) + seconds * 1000 + (((time % 1000) + 1000) % 1000));
+}
+/** Today as `YYYY-MM-DD` in `timeZone`, or in the reader's time zone. */
+export const timelineToday = (timeZone, now = Date.now()) => dayString(Math.floor(wallClock(now, timeZone) / DAY) * DAY);

package/dist/internal/charts/timeline-window.d.ts

@@ -0,0 +1,31 @@
+import type { ReactNode } from 'react';
+import { type TimelineZoom } from './timeline-dates.js';
+export interface TimelineWindowBarProps {
+    /** The window size. */
+    zoom: TimelineZoom;
+    /** Any day in the window, as `YYYY-MM-DD`. */
+    from: string;
+    /** Gets the next size and day after Previous, Today, Next, or a size change. */
+    onChange: (next: {
+        zoom: TimelineZoom;
+        from: string;
+    }) => void;
+    /** Today in the reader's time zone, as `YYYY-MM-DD`. */
+    today: string;
+    /** 1 starts weeks on Monday (default), 0 on Sunday. */
+    weekStartsOn?: 0 | 1 | undefined;
+    /** Locale for the window title. Defaults to the reader's. */
+    locale?: string | undefined;
+    /** Extra controls at the end, such as start and end field pickers. */
+    actions?: ReactNode;
+    /** Turns off every control, for example while the app saves. */
+    disabled?: boolean | undefined;
+    className?: string | undefined;
+}
+/**
+ * Previous, Today, and Next buttons, the window title, and a Week, Month,
+ * Quarter switch for a timeline. The app keeps `zoom` and `from`, for
+ * example in the link, and passes `timelineRange(zoom, from)` to
+ * `TimelineChart` as its `window`.
+ */
+export declare function TimelineWindowBar({ zoom, from, onChange, today, weekStartsOn, locale, actions, disabled, className, }: TimelineWindowBarProps): import("react").JSX.Element;

package/dist/internal/charts/timeline-window.js

@@ -0,0 +1,26 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ChevronLeft } from 'reicon-react/icons/ChevronLeft';
+import { ChevronRight } from 'reicon-react/icons/ChevronRight';
+import { Button } from '../../components/button.js';
+import { ToggleGroup, ToggleGroupItem } from '../../components/toggle-group.js';
+import { cn } from '../classes.js';
+import { shiftTimeline, timelineTitle, timelineZoomNames } from './timeline-dates.js';
+const zoomLabels = {
+    week: 'Week',
+    month: 'Month',
+    quarter: 'Quarter',
+};
+/**
+ * Previous, Today, and Next buttons, the window title, and a Week, Month,
+ * Quarter switch for a timeline. The app keeps `zoom` and `from`, for
+ * example in the link, and passes `timelineRange(zoom, from)` to
+ * `TimelineChart` as its `window`.
+ */
+export function TimelineWindowBar({ zoom, from, onChange, today, weekStartsOn = 1, locale, actions, disabled, className, }) {
+    return (_jsxs("div", { "data-slot": "timeline-window-bar", className: cn('sprout-timeline-window-bar', className), children: [_jsxs("div", { className: "sprout-timeline-window-nav", children: [_jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": `Previous ${zoom}`, disabled: disabled, onClick: () => onChange({ zoom, from: shiftTimeline(zoom, from, -1, weekStartsOn) }), children: _jsx(ChevronLeft, { size: 16, "aria-hidden": "true" }) }), _jsx(Button, { variant: "outline", size: "sm", disabled: disabled, onClick: () => onChange({ zoom, from: today }), children: "Today" }), _jsx(Button, { variant: "outline", size: "icon-sm", "aria-label": `Next ${zoom}`, disabled: disabled, onClick: () => onChange({ zoom, from: shiftTimeline(zoom, from, 1, weekStartsOn) }), children: _jsx(ChevronRight, { size: 16, "aria-hidden": "true" }) })] }), _jsx("p", { className: "sprout-timeline-window-title", "aria-live": "polite", "aria-atomic": "true", children: timelineTitle(zoom, from, weekStartsOn, locale) }), actions ? _jsx("div", { className: "sprout-timeline-window-actions", children: actions }) : null, _jsx(ToggleGroup, { "aria-label": "Window size", variant: "outline", size: "sm", spacing: 0, className: "sprout-timeline-window-zoom", value: [zoom], disabled: disabled, onValueChange: value => {
+                    const next = value[0];
+                    if (next && next !== zoom)
+                        onChange({ zoom: next, from });
+                }, children: timelineZoomNames.map(name => (_jsx(ToggleGroupItem, { value: name, children: zoomLabels[name] }, name))) })] }));
+}

package/dist/internal/charts/timeline.d.ts

@@ -0,0 +1,72 @@
+import { type ReactNode } from 'react';
+import { type ChartRow, type ChartSeries, type ReadyChartProps } from '../chart-kit.js';
+import { type TimelineRange } from './timeline-dates.js';
+/** Rows the app read but could not draw, because their start is empty. */
+export interface TimelineUndated {
+    /** How many rows have no start. A string passes through, such as "1,204". */
+    count: number | string;
+    /** The start field's name, as in "3 rows without Due date". */
+    field: string;
+    /** A link or button, such as one that opens Table filtered to those rows. */
+    action?: ReactNode;
+}
+export type TimelineStatus = 'ready' | 'loading' | 'error';
+export interface TimelineChartProps<T extends ChartRow = ChartRow> extends ReadyChartProps {
+    /** One row per task or record. Rows with no start are not drawn. */
+    rows: T[];
+    /** The row key whose value names each row. */
+    category: string;
+    /** The row key holding the start, as `YYYY-MM-DD` or a time in ms. */
+    start: string;
+    /**
+     * The row key holding the end, in the same form as `start`. Without it,
+     * or when a row's end is empty, the row is a point. An end before the
+     * start is a point marked "End before start".
+     */
+    end?: string | undefined;
+    /** The row key naming each row's series, for color and legend. */
+    seriesKey?: string | undefined;
+    /** Colors and legend labels, matched by `seriesKey`. */
+    series?: ChartSeries[] | undefined;
+    /** Locale for dates. Defaults to the reader's. */
+    locale?: string | undefined;
+    /**
+     * The days to show, both inclusive, from `timelineRange`. Bars are cut at
+     * its edges and the cut ends are marked. Rows outside it are left out.
+     * Without it the axis fits the rows.
+     */
+    window?: TimelineRange | undefined;
+    /** Today as `YYYY-MM-DD`. Draws a line labeled "Today". */
+    today?: string | undefined;
+    /** Time zone for times in ms. Defaults to the reader's when a list or window is shown. */
+    timeZone?: string | undefined;
+    /** The row key holding a stable id. Defaults to the row's position. */
+    rowKey?: string | undefined;
+    /** Title content in the list beside the chart. Defaults to the `category` value. */
+    renderLabel?: ((row: T) => ReactNode) | undefined;
+    /** Actions at the end of each list row, such as an edit button and a menu. */
+    renderActions?: ((row: T) => ReactNode) | undefined;
+    /** Click or Enter on a row. Open your own Sheet or Dialog here. */
+    onRowOpen?: ((row: T) => void) | undefined;
+    /** Counts rows with no start, under the chart. */
+    undated?: TimelineUndated | undefined;
+    /** A line above the chart, such as "Showing the first 100 of 340 rows". */
+    notice?: ReactNode;
+    /** `loading` keeps drawn rows under `aria-busy`, or shows placeholders. */
+    status?: TimelineStatus | undefined;
+    /** What went wrong, under "Couldn't load the timeline". */
+    error?: ReactNode;
+    /** Shows "Try again" on the error. */
+    onRetry?: (() => void) | undefined;
+    /** Replaces the empty message when the window has no rows. */
+    empty?: ReactNode;
+}
+/**
+ * Rows as bars on a time axis, like a project plan. A row with only a start
+ * is a diamond. Give it a `window`, `renderLabel`, `renderActions`, or
+ * `onRowOpen` and it becomes a record timeline: a list of titles and dates
+ * in words beside the chart, in start order, with one tab stop and arrow
+ * keys. Without them it is a plain chart with names on the axis, one 32px
+ * row per task, colored by `seriesKey`.
+ */
+export declare function TimelineChart<T extends ChartRow = ChartRow>({ rows, category, start, end, seriesKey, series, locale, window, today, timeZone, rowKey, renderLabel, renderActions, onRowOpen, undated, notice, status, error, onRetry, empty, title, className, }: TimelineChartProps<T>): import("react").JSX.Element;