@tulipfarm/sprout 0.3.0 → 0.4.0

package/dist/internal/chart-kit.d.ts

@@ -0,0 +1,142 @@
+import { type ComponentProps, type ComponentType, type ReactNode } from 'react';
+import { ResponsiveContainer, Tooltip, type BarShapeProps, type DefaultLegendContentProps, type DefaultTooltipContentProps, type TooltipValueType } from 'recharts';
+/** Theme names a `ChartConfig` entry can color, and the selector each one uses. */
+declare const THEMES: {
+    readonly light: "";
+    readonly dark: ".dark";
+};
+export declare const chartIndicatorNames: readonly ["dot", "line", "dashed"];
+export type ChartIndicator = (typeof chartIndicatorNames)[number];
+export type ChartConfig = Record<string, {
+    label?: ReactNode;
+    icon?: ComponentType;
+} & ({
+    color?: string;
+    theme?: never;
+} | {
+    color?: never;
+    theme: Record<keyof typeof THEMES, string>;
+})>;
+/**
+ * The CSS variable a `ChartContainer` sets for one config key. Pass it as a
+ * series `fill` or `stroke`, for example `fill={chartColor("tasks")}`.
+ */
+export declare function chartColor(key: string): string;
+export type ChartContainerProps = ComponentProps<'div'> & {
+    config: ChartConfig;
+    children: ComponentProps<typeof ResponsiveContainer>['children'];
+    /** Size used before the container is measured, and on the server. */
+    initialDimension?: {
+        width: number;
+        height: number;
+    };
+};
+/**
+ * Sizes a Recharts chart to its box and turns `config` into series colors
+ * and labels for the tooltip and legend. The box is 16:9 unless `className`
+ * or `style` gives it a height.
+ */
+export declare function ChartContainer({ id, className, children, config, initialDimension, ...props }: ChartContainerProps): import("react").JSX.Element;
+/**
+ * Writes `--sprout-chart-color-<key>` for every colored config entry, with a
+ * dark value for entries that pass `theme`. `ChartContainer` renders it.
+ */
+export declare function ChartStyle({ id, config }: {
+    id: string;
+    config: ChartConfig;
+}): import("react").JSX.Element | null;
+export type ChartTooltipProps = ComponentProps<typeof Tooltip>;
+/**
+ * Recharts' `Tooltip`, moving in 160ms. Pass `content={<ChartTooltipContent />}`.
+ * It stays still when reduced motion is on.
+ */
+export declare function ChartTooltip(props: ChartTooltipProps): import("react").JSX.Element;
+type TooltipNameType = number | string;
+export type ChartTooltipContentProps = ComponentProps<typeof Tooltip> & ComponentProps<'div'> & {
+    hideLabel?: boolean;
+    hideIndicator?: boolean;
+    indicator?: ChartIndicator;
+    nameKey?: string;
+    labelKey?: string;
+    /** Formats each row's number, for example as currency. */
+    valueFormatter?: ValueFormatter;
+} & Omit<DefaultTooltipContentProps<TooltipValueType, TooltipNameType>, 'accessibilityLayer'>;
+/**
+ * The tooltip card: a label, then one row per series with its indicator,
+ * config label, and value. Recharts passes `active`, `payload`, and `label`.
+ */
+export declare function ChartTooltipContent({ active, payload, className, indicator, hideLabel, hideIndicator, label, labelFormatter, labelClassName, formatter, color, nameKey, labelKey, valueFormatter, }: ChartTooltipContentProps): import("react").JSX.Element | null;
+/** Recharts' `Legend`. Pass `content={<ChartLegendContent />}`. */
+export declare const ChartLegend: import("react").MemoExoticComponent<(outsideProps: import("recharts").LegendProps) => React.ReactPortal | null>;
+export type ChartLegendContentProps = ComponentProps<'div'> & {
+    hideIcon?: boolean;
+    nameKey?: string;
+} & DefaultLegendContentProps;
+/** A centered row of swatches and config labels, one per series. */
+export declare function ChartLegendContent({ className, hideIcon, payload, verticalAlign, nameKey, }: ChartLegendContentProps): import("react").JSX.Element | null;
+/** One series: its data key, legend and tooltip label, and color. */
+export type ChartSeries = {
+    key: string;
+    label: string;
+    color: string;
+};
+export type UsageSeries = ChartSeries;
+/** One data row: a category or label key plus a number per series key. */
+export type ChartRow = Record<string, number | string | null | undefined>;
+/** Turns a number into the text an axis tick or tooltip shows. */
+export type ValueFormatter = (value: number) => string;
+export declare const formatNumber: ValueFormatter;
+/** The five chart colors, in order. */
+export declare const chartPalette: string[];
+/** The color for parts past the fifth, folded into one "N more" part. */
+export declare const chartOtherColor = "var(--sprout-muted)";
+/** The palette color for a part, or the muted color past the fifth. */
+export declare const partColor: (index: number) => string;
+/**
+ * One of `steps` shades of `color`, mixed with the surface so it reads in
+ * light and dark. Step 1 is lightest; the last step is `color` itself.
+ */
+export declare const chartShade: (color: string, step: number, steps?: number) => string;
+export type ChartPart = {
+    name: string;
+    value: number;
+    fill: string;
+};
+/**
+ * Sorts rows by `value`, keeps the top `limit` as colored parts, and folds the
+ * rest into one muted "N more" part.
+ */
+export declare function foldParts(rows: ChartRow[], category: string, value: string, limit?: number): ChartPart[];
+/** A config entry per part, so the tooltip and legend show part names. */
+export declare const partConfig: (parts: ChartPart[]) => ChartConfig;
+/** Shared props for every ready chart. */
+export interface ReadyChartProps {
+    /** Names the chart for screen readers. */
+    title?: string;
+    /** Formats axis ticks and tooltip values, for example as currency. */
+    valueFormatter?: ValueFormatter;
+    className?: string;
+}
+export declare const seriesConfig: (series: ChartSeries[]) => ChartConfig;
+export declare const tooltipCursor: {
+    fill: string;
+};
+/** Axis props every ready chart shares: no tick marks, no axis line. */
+export declare const quietAxis: {
+    readonly tickLine: false;
+    readonly axisLine: false;
+};
+/** How series pile up: side by side, stacked, or stacked to 100%. */
+export type ChartStack = 'none' | 'stacked' | 'percent';
+export declare const stackOffset: (stack: ChartStack) => "expand" | undefined;
+export declare const formatPercent: ValueFormatter;
+/** A short day label, like "Oct 17", for a `YYYY-MM-DD` string or a time. */
+export declare const dayLabel: (value: unknown, locale?: string) => string;
+/**
+ * Legend content listing every config entry, for charts whose marks are not
+ * one series each. Pass it as `<ChartLegend content={configLegend(config)} />`.
+ */
+export declare const configLegend: (config: ChartConfig) => () => import("react").JSX.Element;
+/** A bar shape that takes its color from the row's `fill`. */
+export declare const rowFillShape: (props: BarShapeProps) => import("react").JSX.Element;
+export {};

package/dist/internal/chart-kit.js

@@ -0,0 +1,200 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { createContext, useContext, useId, useMemo, } from 'react';
+import { Legend, Rectangle, ResponsiveContainer, Tooltip, } from 'recharts';
+import { cn } from './classes.js';
+/** Theme names a `ChartConfig` entry can color, and the selector each one uses. */
+const THEMES = { light: '', dark: '.dark' };
+const INITIAL_DIMENSION = { width: 320, height: 200 };
+export const chartIndicatorNames = ['dot', 'line', 'dashed'];
+const cssKey = (key) => key.replace(/[^\w-]/g, '_');
+/**
+ * The CSS variable a `ChartContainer` sets for one config key. Pass it as a
+ * series `fill` or `stroke`, for example `fill={chartColor("tasks")}`.
+ */
+export function chartColor(key) {
+    return `var(--sprout-chart-color-${cssKey(key)})`;
+}
+const ChartContext = createContext(null);
+function useChart() {
+    const context = useContext(ChartContext);
+    if (!context)
+        throw new Error('useChart must be used within a <ChartContainer />');
+    return context;
+}
+/**
+ * Sizes a Recharts chart to its box and turns `config` into series colors
+ * and labels for the tooltip and legend. The box is 16:9 unless `className`
+ * or `style` gives it a height.
+ */
+export function ChartContainer({ id, className, children, config, initialDimension = INITIAL_DIMENSION, ...props }) {
+    const uniqueId = useId();
+    const chartId = `chart-${cssKey(id ?? uniqueId)}`;
+    const value = useMemo(() => ({ config }), [config]);
+    return (_jsx(ChartContext.Provider, { value: value, children: _jsxs("div", { "data-slot": "chart", "data-chart": chartId, className: cn('sprout-chart', className), ...props, children: [_jsx(ChartStyle, { id: chartId, config: config }), _jsx(ResponsiveContainer, { initialDimension: initialDimension, children: children })] }) }));
+}
+/**
+ * Writes `--sprout-chart-color-<key>` for every colored config entry, with a
+ * dark value for entries that pass `theme`. `ChartContainer` renders it.
+ */
+export function ChartStyle({ id, config }) {
+    const colorConfig = Object.entries(config).filter(([, item]) => item.theme ?? item.color);
+    if (!colorConfig.length)
+        return null;
+    const rules = (theme) => colorConfig
+        .map(([key, item]) => {
+        const color = item.theme?.[theme] ?? item.color;
+        return color ? `  --sprout-chart-color-${cssKey(key)}: ${color};` : null;
+    })
+        .filter(Boolean)
+        .join('\n');
+    const scope = `[data-chart="${cssKey(id)}"]`;
+    const themed = colorConfig.some(([, item]) => item.theme);
+    const css = [
+        `${scope} {\n${rules('light')}\n}`,
+        themed ? `${THEMES.dark} ${scope} {\n${rules('dark')}\n}` : '',
+        themed
+            ? `@media (prefers-color-scheme: dark) {\n:root:not(.light):not(.dark) ${scope} {\n${rules('dark')}\n}\n}`
+            : '',
+    ]
+        .filter(Boolean)
+        .join('\n');
+    return _jsx("style", { dangerouslySetInnerHTML: { __html: css } });
+}
+/**
+ * Recharts' `Tooltip`, moving in 160ms. Pass `content={<ChartTooltipContent />}`.
+ * It stays still when reduced motion is on.
+ */
+export function ChartTooltip(props) {
+    return _jsx(Tooltip, { animationDuration: 160, ...props });
+}
+/**
+ * The tooltip card: a label, then one row per series with its indicator,
+ * config label, and value. Recharts passes `active`, `payload`, and `label`.
+ */
+export function ChartTooltipContent({ active, payload, className, indicator = 'dot', hideLabel = false, hideIndicator = false, label, labelFormatter, labelClassName, formatter, color, nameKey, labelKey, valueFormatter = formatNumber, }) {
+    const { config } = useChart();
+    const tooltipLabel = useMemo(() => {
+        if (hideLabel || !payload?.length)
+            return null;
+        const [item] = payload;
+        const key = `${labelKey ?? item?.dataKey ?? item?.name ?? 'value'}`;
+        const itemConfig = getPayloadConfigFromPayload(config, item, key);
+        const value = !labelKey && typeof label === 'string' ? (config[label]?.label ?? label) : itemConfig?.label;
+        if (labelFormatter)
+            return _jsx("div", { className: cn('sprout-chart-tooltip-label', labelClassName), children: labelFormatter(value, payload) });
+        if (!value)
+            return null;
+        return _jsx("div", { className: cn('sprout-chart-tooltip-label', labelClassName), children: value });
+    }, [label, labelFormatter, payload, hideLabel, labelClassName, config, labelKey]);
+    if (!active || !payload?.length)
+        return null;
+    const nestLabel = payload.length === 1 && indicator !== 'dot';
+    return (_jsxs("div", { "data-slot": "chart-tooltip", "data-indicator": indicator, className: cn('sprout-chart-tooltip', className), children: [!nestLabel ? tooltipLabel : null, _jsx("div", { className: "sprout-chart-tooltip-items", children: payload
+                    .filter(item => item.type !== 'none')
+                    .map((item, index) => {
+                    const key = `${nameKey ?? item.name ?? item.dataKey ?? 'value'}`;
+                    const itemConfig = getPayloadConfigFromPayload(config, item, key);
+                    const indicatorColor = color ?? item.payload?.fill ?? item.color;
+                    return (_jsx("div", { "data-slot": "chart-tooltip-item", className: "sprout-chart-tooltip-item", children: formatter && item?.value !== undefined && item.name ? (formatter(item.value, item.name, item, index, item.payload)) : (_jsxs(_Fragment, { children: [itemConfig?.icon ? (_jsx(itemConfig.icon, {})) : (!hideIndicator && (_jsx("span", { "aria-hidden": "true", "data-slot": "chart-tooltip-indicator", className: "sprout-chart-tooltip-indicator", style: {
+                                        '--sprout-chart-indicator': indicatorColor,
+                                    } }))), _jsxs("div", { className: "sprout-chart-tooltip-row", "data-nested": nestLabel || undefined, children: [_jsxs("div", { className: "sprout-chart-tooltip-name", children: [nestLabel ? tooltipLabel : null, _jsx("span", { children: itemConfig?.label ?? item.name })] }), item.value != null && (_jsx("span", { className: "sprout-chart-tooltip-value", children: typeof item.value === 'number' ? valueFormatter(item.value) : String(item.value) }))] })] })) }, index));
+                }) })] }));
+}
+/** Recharts' `Legend`. Pass `content={<ChartLegendContent />}`. */
+export const ChartLegend = Legend;
+/** A centered row of swatches and config labels, one per series. */
+export function ChartLegendContent({ className, hideIcon = false, payload, verticalAlign = 'bottom', nameKey, }) {
+    const { config } = useChart();
+    if (!payload?.length)
+        return null;
+    return (_jsx("div", { "data-slot": "chart-legend", "data-align": verticalAlign === 'top' ? 'top' : 'bottom', className: cn('sprout-chart-legend', className), children: payload
+            .filter(item => item.type !== 'none')
+            .map((item, index) => {
+            const key = `${nameKey ?? item.dataKey ?? 'value'}`;
+            const itemConfig = getPayloadConfigFromPayload(config, item, key);
+            return (_jsxs("div", { "data-slot": "chart-legend-item", className: "sprout-chart-legend-item", children: [itemConfig?.icon && !hideIcon ? (_jsx(itemConfig.icon, {})) : (_jsx("span", { "aria-hidden": "true", className: "sprout-chart-legend-swatch", style: { backgroundColor: item.color } })), itemConfig?.label] }, index));
+        }) }));
+}
+function getPayloadConfigFromPayload(config, payload, key) {
+    if (typeof payload !== 'object' || payload === null)
+        return undefined;
+    const inner = 'payload' in payload && typeof payload.payload === 'object' && payload.payload !== null
+        ? payload.payload
+        : undefined;
+    const outer = payload;
+    let configLabelKey = key;
+    if (typeof outer[key] === 'string')
+        configLabelKey = outer[key];
+    else if (inner && typeof inner[key] === 'string')
+        configLabelKey = inner[key];
+    return configLabelKey in config ? config[configLabelKey] : config[key];
+}
+export const formatNumber = value => value.toLocaleString();
+/** The five chart colors, in order. */
+export const chartPalette = [1, 2, 3, 4, 5].map(step => `var(--sprout-chart-${step})`);
+/** The color for parts past the fifth, folded into one "N more" part. */
+export const chartOtherColor = 'var(--sprout-muted)';
+/** The palette color for a part, or the muted color past the fifth. */
+export const partColor = (index) => chartPalette[index] ?? chartOtherColor;
+/**
+ * One of `steps` shades of `color`, mixed with the surface so it reads in
+ * light and dark. Step 1 is lightest; the last step is `color` itself.
+ */
+export const chartShade = (color, step, steps = 5) => `color-mix(in oklab, ${color} ${Math.round((step / steps) * 100)}%, var(--sprout-surface))`;
+/**
+ * Sorts rows by `value`, keeps the top `limit` as colored parts, and folds the
+ * rest into one muted "N more" part.
+ */
+export function foldParts(rows, category, value, limit = chartPalette.length) {
+    const parts = rows
+        .map(row => ({
+        name: String(row[category] ?? ''),
+        value: Number(row[value]) || 0,
+    }))
+        .filter(part => part.value > 0)
+        .sort((a, b) => b.value - a.value);
+    const kept = parts.slice(0, limit);
+    const rest = parts.slice(kept.length);
+    const colored = kept.map((part, index) => ({
+        ...part,
+        fill: partColor(index),
+    }));
+    if (!rest.length)
+        return colored;
+    return [
+        ...colored,
+        {
+            name: `${rest.length} more`,
+            value: rest.reduce((sum, part) => sum + part.value, 0),
+            fill: chartOtherColor,
+        },
+    ];
+}
+/** A config entry per part, so the tooltip and legend show part names. */
+export const partConfig = (parts) => Object.fromEntries(parts.map(part => [part.name, { label: part.name, color: part.fill }]));
+export const seriesConfig = (series) => Object.fromEntries(series.map(item => [item.key, { label: item.label, color: item.color }]));
+export const tooltipCursor = { fill: 'var(--sprout-hover)' };
+/** Axis props every ready chart shares: no tick marks, no axis line. */
+export const quietAxis = { tickLine: false, axisLine: false };
+export const stackOffset = (stack) => (stack === 'percent' ? 'expand' : undefined);
+export const formatPercent = value => `${Math.round(value * 100)}%`;
+/** A short day label, like "Oct 17", for a `YYYY-MM-DD` string or a time. */
+export const dayLabel = (value, locale) => new Date(typeof value === 'number' || value instanceof Date ? value : `${String(value)}T00:00:00Z`).toLocaleDateString(locale, {
+    month: 'short',
+    day: 'numeric',
+    timeZone: 'UTC',
+});
+/**
+ * Legend content listing every config entry, for charts whose marks are not
+ * one series each. Pass it as `<ChartLegend content={configLegend(config)} />`.
+ */
+export const configLegend = (config) => function ConfigLegend() {
+    return (_jsx(ChartLegendContent, { payload: Object.keys(config).map(key => ({
+            value: key,
+            dataKey: key,
+            color: chartColor(key),
+        })) }));
+};
+/** A bar shape that takes its color from the row's `fill`. */
+export const rowFillShape = (props) => (_jsx(Rectangle, { ...props, fill: props.payload.fill }));

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

@@ -0,0 +1,61 @@
+import { type ChartRow, type ChartSeries, type ChartStack, type ReadyChartProps, type UsageSeries } from '../chart-kit.js';
+export type UsageDay = {
+    date: string;
+} & Record<string, number | string | null>;
+export interface UsageChartProps {
+    /** One row per UTC day (`YYYY-MM-DD`), keyed by series. */
+    days: UsageDay[];
+    series: UsageSeries[];
+    /** Names the chart for screen readers. */
+    title?: string;
+    /** Locale for day labels. Defaults to the reader's. */
+    locale?: string;
+    className?: string;
+}
+/**
+ * Stacked daily bars, 256px tall. Days are rows keyed by series; a missing or
+ * null value keeps that series out of the day's tooltip. The top series gets
+ * rounded corners.
+ */
+export declare function UsageChart({ days, series, title, locale, className }: UsageChartProps): import("react").JSX.Element;
+export interface CategoryChartProps extends ReadyChartProps {
+    /** One row per category, keyed by `category` and by each series key. */
+    rows: ChartRow[];
+    /** The row key whose value names each group of bars. */
+    category: string;
+    series: ChartSeries[];
+    /** Bars grow sideways, one row per category. Good for long names. */
+    horizontal?: boolean;
+    /** `stacked` piles series in one bar; `percent` stacks them to 100%. */
+    stack?: ChartStack;
+}
+/**
+ * Bars per category with a legend in series order, 288px tall. Negative
+ * values hang below a zero line, for profit and loss.
+ */
+export declare function CategoryChart({ rows, category, series, horizontal, stack, title, valueFormatter, className, }: CategoryChartProps): import("react").JSX.Element;
+export interface WaterfallChartProps extends ReadyChartProps {
+    /** One row per step. `value` is the change that step adds or takes away. */
+    rows: ChartRow[];
+    /** The row key whose value names each step. */
+    category: string;
+    /** The row key holding each step's change. */
+    value: string;
+    /**
+     * Steps drawn as a full bar from zero, like a start or end balance. A total
+     * with a value starts the running total there; one without shows the
+     * running total so far.
+     */
+    totals?: string[];
+    /** Legend labels for rises, falls, and totals. */
+    labels?: {
+        increase?: string;
+        decrease?: string;
+        total?: string;
+    };
+}
+/**
+ * A running total, step by step: green bars rise, red bars fall, and blue
+ * totals stand on zero. 288px tall.
+ */
+export declare function WaterfallChart({ rows, category, value, totals, labels, title, valueFormatter, className, }: WaterfallChartProps): import("react").JSX.Element;

package/dist/internal/charts/bars.js

@@ -0,0 +1,86 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { Bar, BarChart, CartesianGrid, ReferenceLine, XAxis, YAxis } from 'recharts';
+import { cn } from '../classes.js';
+import { ChartContainer, ChartLegend, ChartLegendContent, ChartTooltip, ChartTooltipContent, chartColor, configLegend, dayLabel, formatNumber, formatPercent, quietAxis, rowFillShape, seriesConfig, stackOffset, tooltipCursor, } from '../chart-kit.js';
+/**
+ * Stacked daily bars, 256px tall. Days are rows keyed by series; a missing or
+ * null value keeps that series out of the day's tooltip. The top series gets
+ * rounded corners.
+ */
+export function UsageChart({ days, series, title = 'Usage by day', locale, className }) {
+    const config = useMemo(() => seriesConfig(series), [series]);
+    const usageDay = (date) => dayLabel(date, locale);
+    return (_jsx(ChartContainer, { "data-variant": "usage", className: cn('sprout-chart-usage', className), config: config, children: _jsxs(BarChart, { data: days, accessibilityLayer: true, title: title, barCategoryGap: "20%", children: [_jsx(CartesianGrid, { vertical: false }), _jsx(XAxis, { dataKey: "date", tickFormatter: usageDay, ...quietAxis, minTickGap: 24 }), _jsx(YAxis, { width: 40, ...quietAxis, allowDecimals: false }), _jsx(ChartTooltip, { cursor: tooltipCursor, content: _jsx(ChartTooltipContent, { labelFormatter: usageDay }) }), series.map((item, index) => (_jsx(Bar, { dataKey: item.key, stackId: "usage", fill: chartColor(item.key), radius: index === series.length - 1 ? [3, 3, 0, 0] : 0, isAnimationActive: false }, item.key)))] }) }));
+}
+const hasNegative = (rows, series) => rows.some(row => series.some(item => Number(row[item.key]) < 0));
+/**
+ * Bars per category with a legend in series order, 288px tall. Negative
+ * values hang below a zero line, for profit and loss.
+ */
+export function CategoryChart({ rows, category, series, horizontal = false, stack = 'none', title, valueFormatter = formatNumber, className, }) {
+    const config = useMemo(() => seriesConfig(series), [series]);
+    const name = title ?? `${series.map(item => item.label).join(', ')} by ${category}`;
+    const stacked = stack !== 'none';
+    const end = horizontal ? [0, 3, 3, 0] : [3, 3, 0, 0];
+    const tick = stack === 'percent' ? formatPercent : valueFormatter;
+    const categoryAxis = { dataKey: category, ...quietAxis };
+    const valueAxis = { ...quietAxis, tickFormatter: tick };
+    return (_jsx(ChartContainer, { "data-variant": "category", className: cn('sprout-chart-category', className), config: config, children: _jsxs(BarChart, { data: rows, accessibilityLayer: true, title: name, layout: horizontal ? 'vertical' : 'horizontal', stackOffset: stackOffset(stack), barCategoryGap: "24%", children: [_jsx(CartesianGrid, { vertical: horizontal, horizontal: !horizontal }), horizontal ? (_jsxs(_Fragment, { children: [_jsx(XAxis, { type: "number", ...valueAxis }), _jsx(YAxis, { type: "category", width: "auto", ...categoryAxis, interval: 0 })] })) : (_jsxs(_Fragment, { children: [_jsx(XAxis, { ...categoryAxis, minTickGap: 16 }), _jsx(YAxis, { width: "auto", ...valueAxis, allowDecimals: stack === 'percent' })] })), hasNegative(rows, series) ? (_jsx(ReferenceLine, { ...(horizontal ? { x: 0 } : { y: 0 }), stroke: "var(--sprout-border-strong)" })) : null, _jsx(ChartTooltip, { cursor: tooltipCursor, content: _jsx(ChartTooltipContent, { valueFormatter: valueFormatter }) }), _jsx(ChartLegend, { itemSorter: null, content: _jsx(ChartLegendContent, {}) }), series.map((item, index) => (_jsx(Bar, { dataKey: item.key, stackId: stacked ? 'category' : undefined, fill: chartColor(item.key), radius: !stacked || index === series.length - 1 ? end : 0, isAnimationActive: false }, item.key)))] }) }));
+}
+const waterfallColors = {
+    increase: 'var(--sprout-green)',
+    decrease: 'var(--sprout-red)',
+    total: 'var(--sprout-blue)',
+};
+/**
+ * A running total, step by step: green bars rise, red bars fall, and blue
+ * totals stand on zero. 288px tall.
+ */
+export function WaterfallChart({ rows, category, value, totals = [], labels, title = 'Running total by step', valueFormatter = formatNumber, className, }) {
+    const steps = useMemo(() => {
+        let running = 0;
+        return rows.map(row => {
+            const name = String(row[category] ?? '');
+            const raw = row[value];
+            const change = Number(raw) || 0;
+            if (totals.includes(name)) {
+                if (raw != null && raw !== '')
+                    running = change;
+                return {
+                    name,
+                    kind: 'total',
+                    range: [0, running],
+                    amount: running,
+                    fill: waterfallColors.total,
+                };
+            }
+            const from = running;
+            running += change;
+            const kind = change < 0 ? 'decrease' : 'increase';
+            return {
+                name,
+                kind,
+                range: [from, running],
+                amount: change,
+                fill: waterfallColors[kind],
+            };
+        });
+    }, [rows, category, value, totals]);
+    const config = useMemo(() => ({
+        increase: {
+            label: labels?.increase ?? 'Increase',
+            color: waterfallColors.increase,
+        },
+        decrease: {
+            label: labels?.decrease ?? 'Decrease',
+            color: waterfallColors.decrease,
+        },
+        total: { label: labels?.total ?? 'Total', color: waterfallColors.total },
+    }), [labels]);
+    return (_jsx(ChartContainer, { "data-variant": "waterfall", className: cn('sprout-chart-waterfall', className), config: config, children: _jsxs(BarChart, { data: steps, accessibilityLayer: true, title: title, barCategoryGap: "16%", children: [_jsx(CartesianGrid, { vertical: false }), _jsx(XAxis, { dataKey: "name", ...quietAxis, minTickGap: 8 }), _jsx(YAxis, { width: "auto", ...quietAxis, tickFormatter: valueFormatter }), _jsx(ReferenceLine, { y: 0, stroke: "var(--sprout-border-strong)" }), _jsx(ChartLegend, { content: configLegend(config) }), _jsx(ChartTooltip, { cursor: tooltipCursor, content: props => (_jsx(ChartTooltipContent, { active: props.active, label: props.label, nameKey: "kind", valueFormatter: valueFormatter, payload: props.payload?.map(item => ({
+                            ...item,
+                            value: item.payload.amount,
+                        })) })) }), _jsx(Bar, { dataKey: "range", radius: 3, shape: rowFillShape, isAnimationActive: false })] }) }));
+}

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

@@ -0,0 +1,67 @@
+import { type ChartRow, type ChartSeries, type ChartStack, type ReadyChartProps, type ValueFormatter } from '../chart-kit.js';
+export type TrendCurve = 'smooth' | 'linear' | 'step';
+/** A series for `ComboChart`: drawn as bars or a line, on the left or right axis. */
+export type ComboSeries = ChartSeries & {
+    kind?: 'bar' | 'line';
+    axis?: 'left' | 'right';
+};
+interface TrendBaseProps extends ReadyChartProps {
+    /** One row per point on the x axis, keyed by `category` and each series. */
+    rows: ChartRow[];
+    /** The row key for the x axis, such as a date or month. */
+    category: string;
+    series: ChartSeries[];
+    /** `smooth` curves, `linear` straight segments, or `step` stairs. */
+    curve?: TrendCurve;
+    /** Draws a dot at every point. */
+    dots?: boolean;
+    /** Formats x axis ticks and the tooltip label, for example dates. */
+    categoryFormatter?: (value: unknown) => string;
+}
+export type TrendChartProps = TrendBaseProps;
+/** Lines over time, one per series, 288px tall. A legend shows past one series. */
+export declare function TrendChart({ curve, dots, ...props }: TrendChartProps): import("react").JSX.Element;
+export interface AreaTrendChartProps extends TrendBaseProps {
+    /** `stacked` piles series; `percent` stacks them to 100%. */
+    stack?: ChartStack;
+}
+/**
+ * Filled areas over time with a soft gradient, 288px tall. Stack them to show
+ * a total, or to 100% to show shares.
+ */
+export declare function AreaTrendChart({ curve, dots, stack, ...props }: AreaTrendChartProps): import("react").JSX.Element;
+export interface ComboChartProps extends ReadyChartProps {
+    /** One row per category, keyed by `category` and each series. */
+    rows: ChartRow[];
+    category: string;
+    /** Bars by default. Set `kind: "line"` and `axis: "right"` for a rate. */
+    series: ComboSeries[];
+    /** Formats the right axis and its series in the tooltip, such as percent. */
+    rightValueFormatter?: ValueFormatter;
+    categoryFormatter?: (value: unknown) => string;
+    /** Stacks the bar series. */
+    stacked?: boolean;
+}
+/**
+ * Bars and lines on one chart, like revenue with its growth rate, 288px tall.
+ * Series on `axis: "right"` get their own scale.
+ */
+export declare function ComboChart({ stacked, ...props }: ComboChartProps): import("react").JSX.Element;
+export interface SparklineProps {
+    /** The points, oldest first. */
+    values: number[];
+    /** Names the trend for screen readers, such as "MRR, last 12 weeks". */
+    title: string;
+    /** Any CSS color. Defaults to `--sprout-chart-1`. */
+    color?: string;
+    /** Fills under the line. */
+    area?: boolean;
+    valueFormatter?: ValueFormatter;
+    className?: string;
+}
+/**
+ * A tiny trend line for a stat tile, 40px tall and as wide as its box. No
+ * axes; hover shows the value.
+ */
+export declare function Sparkline({ values, title, color, area, valueFormatter, className, }: SparklineProps): import("react").JSX.Element;
+export {};

package/dist/internal/charts/lines.js

@@ -0,0 +1,70 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId, useMemo } from 'react';
+import { Area, Bar, CartesianGrid, ComposedChart, Line, XAxis, YAxis } from 'recharts';
+import { cn } from '../classes.js';
+import { ChartContainer, ChartLegend, ChartLegendContent, ChartTooltip, ChartTooltipContent, chartColor, formatNumber, formatPercent, quietAxis, seriesConfig, stackOffset, tooltipCursor, } from '../chart-kit.js';
+const curveType = {
+    smooth: 'monotone',
+    linear: 'linear',
+    step: 'step',
+};
+function SeriesPlot({ variant, rows, category, series, mark, curve, dots, stack, title, valueFormatter = formatNumber, rightValueFormatter = valueFormatter, categoryFormatter, className, }) {
+    const config = useMemo(() => seriesConfig(series), [series]);
+    const gradient = `sprout-area-${useId().replace(/:/g, '')}`;
+    const stacked = stack !== 'none';
+    const right = series.some(item => item.axis === 'right');
+    const anyBar = series.some(item => mark(item) === 'bar');
+    const tick = stack === 'percent' ? formatPercent : valueFormatter;
+    const format = (key) => series.find(item => item.key === key)?.axis === 'right' ? rightValueFormatter : valueFormatter;
+    const name = title ?? `${series.map(item => item.label).join(', ')} by ${category}`;
+    const type = curveType[curve];
+    return (_jsx(ChartContainer, { "data-variant": variant, className: cn(`sprout-chart-${variant}`, className), config: config, children: _jsxs(ComposedChart, { data: rows, accessibilityLayer: true, title: name, stackOffset: stackOffset(stack), barCategoryGap: "24%", margin: { top: 4, right: right ? 0 : 12, bottom: 0, left: 0 }, children: [_jsx("defs", { children: series.map(item => (_jsxs("linearGradient", { id: `${gradient}-${item.key}`, x1: "0", y1: "0", x2: "0", y2: "1", children: [_jsx("stop", { offset: "5%", stopColor: chartColor(item.key), stopOpacity: 0.4 }), _jsx("stop", { offset: "95%", stopColor: chartColor(item.key), stopOpacity: 0.04 })] }, item.key))) }), _jsx(CartesianGrid, { vertical: false }), _jsx(XAxis, { dataKey: category, tickFormatter: categoryFormatter, ...quietAxis, minTickGap: 16 }), _jsx(YAxis, { yAxisId: "left", width: "auto", tickFormatter: tick, ...quietAxis }), right ? (_jsx(YAxis, { yAxisId: "right", orientation: "right", width: "auto", tickFormatter: rightValueFormatter, ...quietAxis })) : null, _jsx(ChartTooltip, { cursor: anyBar ? tooltipCursor : true, content: props => (_jsx(ChartTooltipContent, { active: props.active, label: props.label, indicator: anyBar ? 'dot' : 'line', labelFormatter: categoryFormatter
+                            ? (_, payload) => categoryFormatter(payload[0]?.payload?.[category])
+                            : undefined, payload: props.payload?.map(item => ({
+                            ...item,
+                            value: typeof item.value === 'number' ? format(String(item.dataKey))(item.value) : item.value,
+                        })) })) }), series.length > 1 ? (_jsx(ChartLegend, { verticalAlign: "top", itemSorter: null, content: _jsx(ChartLegendContent, {}) })) : null, series.map((item, index) => {
+                    const color = chartColor(item.key);
+                    const shared = {
+                        dataKey: item.key,
+                        yAxisId: item.axis ?? 'left',
+                        stackId: stacked ? 'series' : undefined,
+                        isAnimationActive: false,
+                    };
+                    const kind = mark(item);
+                    if (kind === 'bar')
+                        return (_jsx(Bar, { ...shared, fill: color, radius: !stacked || index === series.length - 1 ? [3, 3, 0, 0] : 0 }, item.key));
+                    if (kind === 'area')
+                        return (_jsx(Area, { ...shared, type: type, stroke: color, strokeWidth: 2, fill: `url(#${gradient}-${item.key})`, dot: dots ? { r: 3, fill: color } : false, activeDot: { r: 4 } }, item.key));
+                    return (_jsx(Line, { ...shared, type: type, stroke: color, strokeWidth: 2, dot: dots ? { r: 3, fill: color } : false, activeDot: { r: 4 } }, item.key));
+                })] }) }));
+}
+/** Lines over time, one per series, 288px tall. A legend shows past one series. */
+export function TrendChart({ curve = 'smooth', dots = false, ...props }) {
+    return _jsx(SeriesPlot, { variant: "trend", mark: () => 'line', curve: curve, dots: dots, stack: "none", ...props });
+}
+/**
+ * Filled areas over time with a soft gradient, 288px tall. Stack them to show
+ * a total, or to 100% to show shares.
+ */
+export function AreaTrendChart({ curve = 'smooth', dots = false, stack = 'none', ...props }) {
+    return _jsx(SeriesPlot, { variant: "area", mark: () => 'area', curve: curve, dots: dots, stack: stack, ...props });
+}
+/**
+ * Bars and lines on one chart, like revenue with its growth rate, 288px tall.
+ * Series on `axis: "right"` get their own scale.
+ */
+export function ComboChart({ stacked = false, ...props }) {
+    return (_jsx(SeriesPlot, { variant: "combo", mark: item => item.kind ?? 'bar', curve: "smooth", dots: true, stack: stacked ? 'stacked' : 'none', ...props }));
+}
+/**
+ * A tiny trend line for a stat tile, 40px tall and as wide as its box. No
+ * axes; hover shows the value.
+ */
+export function Sparkline({ values, title, color = 'var(--sprout-chart-1)', area = false, valueFormatter = formatNumber, className, }) {
+    const rows = useMemo(() => values.map((value, index) => ({ index, value })), [values]);
+    const config = useMemo(() => ({ value: { label: title, color } }), [title, color]);
+    const gradient = `sprout-spark-${useId().replace(/:/g, '')}`;
+    return (_jsx(ChartContainer, { "data-variant": "sparkline", className: cn('sprout-chart-sparkline', className), config: config, initialDimension: { width: 120, height: 40 }, children: _jsxs(ComposedChart, { data: rows, accessibilityLayer: true, title: title, margin: { top: 4, right: 4, bottom: 4, left: 4 }, children: [_jsx("defs", { children: _jsxs("linearGradient", { id: gradient, x1: "0", y1: "0", x2: "0", y2: "1", children: [_jsx("stop", { offset: "5%", stopColor: chartColor('value'), stopOpacity: 0.3 }), _jsx("stop", { offset: "95%", stopColor: chartColor('value'), stopOpacity: 0 })] }) }), _jsx(YAxis, { hide: true, domain: ['dataMin', 'dataMax'] }), _jsx(ChartTooltip, { cursor: false, content: _jsx(ChartTooltipContent, { hideLabel: true, indicator: "line", valueFormatter: valueFormatter }) }), _jsx(Area, { dataKey: "value", type: "monotone", stroke: chartColor('value'), strokeWidth: 1.5, fill: area ? `url(#${gradient})` : 'none', dot: false, activeDot: { r: 3 }, isAnimationActive: false })] }) }));
+}