@shapesos/clay 0.10.0 → 0.12.0

package/dist/chart.d.ts

@@ -0,0 +1,439 @@
+import { ReactNode, ReactElement, CSSProperties } from 'react';
+import { C as ChartSeries } from './types-B2aYk82c.js';
+export { a as ChartVariant } from './types-B2aYk82c.js';
+
+interface BarChartProps {
+    /** Rows to plot. Each row should carry the `xKey` column and one column per `series[].key`. */
+    data: ReadonlyArray<Record<string, unknown>>;
+    /** CSV/data column to use for the categorical x-axis (e.g. `"month"`, `"quarter"`). */
+    xKey: string;
+    /** One descriptor per bar series. Length 1 = single-series chart; 2+ = grouped or stacked. */
+    series: ChartSeries[];
+    /**
+     * When true, all series stack on one stack-id (vertical sum). When false (default), bars
+     * group side-by-side per x-tick.
+     */
+    stacked?: boolean;
+    /** Container height. Number = px, string = any CSS length. Default 320. */
+    height?: number | string;
+    /** Container width. Default `"100%"`. */
+    width?: number | string;
+    /** Optional className on the outer container. */
+    className?: string;
+    /** Override the default palette (`CHART_PALETTE`). Colors are assigned by series index. */
+    palette?: readonly string[];
+    /** Show the tooltip on hover. Default true. */
+    showTooltip?: boolean;
+    /**
+     * Show the legend at the top. **Default behavior**: auto-hidden for single-series charts
+     * (the legend would just label the one and only color, which is noise). Pass `true` to force
+     * the legend even with one series; pass `false` to suppress for multi-series.
+     */
+    showLegend?: boolean;
+    /** Show horizontal dashed grid lines. Default true. */
+    showGrid?: boolean;
+    /** Show the x-axis. Default true. */
+    showXAxis?: boolean;
+    /** Show the y-axis. Default true. */
+    showYAxis?: boolean;
+    /**
+     * Show numeric value labels above each bar. **Default behavior**: auto-on for single
+     * non-stacked series (labels stay readable); auto-off for stacked or multi-series bars
+     * (labels overlap and clutter). Pass explicitly to override.
+     */
+    showValueLabels?: boolean;
+    /**
+     * Recharts XAxis tick `interval`. Default `0` — every category gets a label (no info loss
+     * from auto-skipping). Use `"preserveStartEnd"` to let recharts drop colliding labels but
+     * keep the first and last. For long category names, prefer `xAxisAngle` to rotate the labels
+     * rather than dropping them.
+     */
+    xAxisInterval?: number | "preserveStart" | "preserveEnd" | "preserveStartEnd";
+    /**
+     * Rotate x-axis tick labels by this many degrees. **Default**: auto — `0` (horizontal) for
+     * ≤7 categories; `-30` for 8+ categories so longer labels fit diagonally without overlapping
+     * their neighbours. Pass `0` explicitly to force horizontal labels even at high counts; pass
+     * any other number to set a custom angle.
+     *
+     * When the resolved angle is non-zero the chart auto-bumps its bottom margin and right-
+     * anchors the labels so they don't run off the axis. The container `height` budget should
+     * accommodate the angled labels (~40-60px more).
+     */
+    xAxisAngle?: number;
+    /**
+     * Custom formatter for x-axis tick labels. **Default**: clay auto-truncates labels based on
+     * the number of categories so no labels overlap (see `getDefaultTickFormatter`). Pass an
+     * explicit formatter to override — e.g. for word-boundary truncation, locale-aware
+     * abbreviations, or to opt out of truncation entirely with `(v) => String(v)`.
+     *
+     * The tooltip continues to show the full unformatted value on hover regardless.
+     */
+    xAxisTickFormatter?: (value: unknown) => string;
+}
+/**
+ * Pre-composed bar chart. Single-call usage for the common case; for custom recharts trees
+ * compose `<ChartContainer>` + recharts primitives directly.
+ *
+ * ```tsx
+ * <BarChart
+ *   data={[{ month: "Jan", us: 120, uk: 60 }, { month: "Feb", us: 132, uk: 64 }]}
+ *   xKey="month"
+ *   series={[
+ *     { key: "us", label: "US" },
+ *     { key: "uk", label: "UK" },
+ *   ]}
+ *   stacked
+ * />
+ * ```
+ *
+ * **Smart defaults**: legend auto-hides for single-series charts; value labels auto-show for
+ * single non-stacked series; all x-axis ticks are shown by default (no recharts auto-skip).
+ * Override any of these via the named props.
+ *
+ * Numeric coercion: `data` rows may carry string values for the series columns (e.g. when
+ * derived from CSV) — recharts needs numbers, so we coerce in-place. Already-numeric data
+ * passes through unchanged.
+ */
+declare function BarChart({ data, xKey, series, stacked, height, width, className, palette, showTooltip, showLegend, showGrid, showXAxis, showYAxis, showValueLabels, xAxisInterval, xAxisAngle, xAxisTickFormatter, }: BarChartProps): ReactNode;
+
+interface LineChartProps {
+    /** Rows to plot. Each row should carry the `xKey` column and one column per `series[].key`. */
+    data: ReadonlyArray<Record<string, unknown>>;
+    /** Data column for the categorical/temporal x-axis. */
+    xKey: string;
+    /** One descriptor per line series. */
+    series: ChartSeries[];
+    /** Render monotone-curve lines instead of straight segments. **Default true** — smooth
+     * curves look cleaner for typical chat / dashboard usage. Pass `false` for true linear
+     * interpolation (e.g. step-like data where the literal value at each point matters). */
+    smooth?: boolean;
+    /** Show data-point dots. **Default true** — dots anchor each bin of the line so the viewer
+     * can read individual values at a glance. Pass `false` for a pure trend line (dense data sets
+     * where dots would crowd, or styling preference for unembellished strokes). */
+    showDots?: boolean;
+    /** Line stroke width in px. Default 2. */
+    strokeWidth?: number;
+    /** Container height. Default 320. */
+    height?: number | string;
+    /** Container width. Default `"100%"`. */
+    width?: number | string;
+    /** Optional className on the outer container. */
+    className?: string;
+    /** Override the default palette. Colors are assigned by series index. */
+    palette?: readonly string[];
+    /** Show the tooltip on hover. Default true. */
+    showTooltip?: boolean;
+    /**
+     * Show the legend at the top. **Default behavior**: auto-hidden for single-series charts
+     * (the legend would just label the one and only color, which is noise). Pass `true` to force
+     * the legend even with one series; pass `false` to suppress for multi-series.
+     */
+    showLegend?: boolean;
+    /** Show horizontal dashed grid lines. Default true. */
+    showGrid?: boolean;
+    /** Show the x-axis. Default true. */
+    showXAxis?: boolean;
+    /** Show the y-axis. Default true. */
+    showYAxis?: boolean;
+    /**
+     * Show numeric value labels next to each data point. **Default off** — for line charts with
+     * many data points (12+ months × N series) labels overlap quickly. Set `true` for single-series
+     * charts with sparse data (e.g. ≤8 points) where the labels stay readable.
+     */
+    showValueLabels?: boolean;
+    /**
+     * Recharts XAxis tick `interval`. **Default**: `0` (every tick rendered) — clay's tick
+     * formatter blanks out non-key labels so the visible labels stay evenly distributed.
+     * Override to a fixed number to force "every Nth label", or to a recharts string preset
+     * like `"preserveStartEnd"` to let recharts pick.
+     */
+    xAxisInterval?: number | "preserveStart" | "preserveEnd" | "preserveStartEnd";
+    /**
+     * Rotate x-axis tick labels by this many degrees. Negative values tilt up-and-right (e.g.
+     * `-30`). Default `0`. When non-zero, the chart auto-bumps its bottom margin.
+     */
+    xAxisAngle?: number;
+    /**
+     * Custom formatter for x-axis tick labels. **Default**: clay shows only ~5 evenly-distributed
+     * labels (first + last + ~3 middle), and auto-truncates each shown label so dense datasets
+     * stay readable. Pass an explicit formatter to override the per-label rendering — to also
+     * change which labels are visible, pass `xAxisInterval` and a formatter that returns the
+     * value for every index.
+     *
+     * The tooltip continues to show the full unformatted value on hover regardless.
+     */
+    xAxisTickFormatter?: (value: unknown) => string;
+}
+/**
+ * Pre-composed line chart. Single-call usage for the common case; for custom recharts trees
+ * compose `<ChartContainer>` + recharts primitives directly.
+ *
+ * ```tsx
+ * <LineChart
+ *   data={[{ month: "Jan", value: 120 }, { month: "Feb", value: 132 }]}
+ *   xKey="month"
+ *   series={[{ key: "value", label: "Headcount" }]}
+ *   smooth
+ * />
+ * ```
+ *
+ * **Smart defaults**: legend auto-hides for single-series; value labels default off (turn on
+ * for sparse single-series charts); x-axis shows every tick by default.
+ */
+declare function LineChart({ data, xKey, series, smooth, showDots, strokeWidth, height, width, className, palette, showTooltip, showLegend, showGrid, showXAxis, showYAxis, showValueLabels, xAxisInterval, xAxisAngle, xAxisTickFormatter, }: LineChartProps): ReactNode;
+
+interface PieChartProps {
+    /** Rows to plot. Each row maps to one slice. */
+    data: ReadonlyArray<Record<string, unknown>>;
+    /** Data column used as the slice label / legend entry. */
+    categoryKey: string;
+    /** Data column used as the slice numeric value. */
+    valueKey: string;
+    /** Container height. Default 320. */
+    height?: number | string;
+    /** Container width. Default `"100%"`. */
+    width?: number | string;
+    /** Optional className on the outer container. */
+    className?: string;
+    /** Override the default palette. Default `CHART_PALETTE` — the shared blue + indigo graduated
+     * palette every chart variant uses. Override per-instance for brand-specific colours. */
+    palette?: readonly string[];
+    /** Show value labels next to each slice. Default true. */
+    showLabels?: boolean;
+    /** Show the tooltip on hover. Default true. */
+    showTooltip?: boolean;
+    /** Show the legend (category names). Default true. Position controlled by `legendPosition`. */
+    showLegend?: boolean;
+    /** Inner radius — `0` (default) for a pie; `>0` (e.g. `"40%"`) for a donut. */
+    innerRadius?: number | string;
+    /** Outer radius. Default `"68%"` — leaves room for outside value labels. */
+    outerRadius?: number | string;
+    /**
+     * Category labels treated as the "Others" bucket (case-insensitive match). Matching slices are
+     * pinned to the end of the sweep regardless of value and rendered in neutral grey
+     * (`OTHERS_SLICE_COLOR`).
+     *
+     * **Default**: `DEFAULT_OTHERS_CATEGORY_LABELS` (English "Others" / "Other"). Pass a localized
+     * list in non-English UIs — e.g. `["אחרים"]` for Hebrew or `["Otros", "Otro"]` for Spanish.
+     * Pass `[]` to disable Others detection entirely (every slice colored from the palette).
+     */
+    othersCategoryLabels?: readonly string[];
+}
+/**
+ * Pre-composed pie chart. One slice per row, colored by row index from the palette. Outside
+ * value labels (no connector line); legend at the top. Set `innerRadius` to make a donut.
+ *
+ * **Sweep**: starts at 12 o'clock and proceeds clockwise (`startAngle={90}` / `endAngle={-270}`).
+ * Recharts' default starts at 3 o'clock counter-clockwise, which feels arbitrary for a
+ * data-first composition.
+ *
+ * **"Others" bucket**: any slice whose category label matches "Others" / "Other"
+ * (case-insensitive — see `isOthersCategory`) is pinned to the end of the sweep regardless of
+ * value, and rendered in neutral grey (`OTHERS_SLICE_COLOR`) so it reads as "unattributed
+ * leftover" rather than a peer category. Other slices retain their incoming order.
+ *
+ * ```tsx
+ * <PieChart
+ *   data={[
+ *     { department: "Engineering", headcount: 42 },
+ *     { department: "Sales", headcount: 18 },
+ *     { department: "Others", headcount: 5 },
+ *   ]}
+ *   categoryKey="department"
+ *   valueKey="headcount"
+ * />
+ *
+ * // Donut variant
+ * <PieChart data={...} categoryKey="..." valueKey="..." innerRadius="40%" />
+ * ```
+ */
+declare function PieChart({ data, categoryKey, valueKey, height, width, className, palette, showLabels, showTooltip, showLegend, innerRadius, outerRadius, othersCategoryLabels, }: PieChartProps): ReactNode;
+
+interface ChartContainerProps {
+    /** A single recharts chart element — `<LineChart>`, `<BarChart>`, `<PieChart>`, etc. */
+    children: ReactElement;
+    /**
+     * Container height. Recharts' `ResponsiveContainer` measures its parent, so we need a
+     * concrete value here (not "auto"). Accepts a number (px) or any CSS length string.
+     * Defaults to `320` — a sensible mid-density chart height.
+     */
+    height?: number | string;
+    /**
+     * Container width. Defaults to `"100%"` so the chart flexes to its parent. Pass a fixed
+     * number when embedding in a layout that doesn't have a definite width (e.g. an auto-sized
+     * flex column).
+     */
+    width?: number | string;
+    /** Optional className spread on the outer wrapper. */
+    className?: string;
+    /** Optional inline style merged into the outer wrapper. `width`/`height` here take precedence. */
+    style?: CSSProperties;
+}
+/**
+ * The composable foundation for every clay chart. Wraps recharts' `ResponsiveContainer` in a
+ * sized `<div>` so the chart has a definite parent box to measure against — without this, charts
+ * silently collapse to 0×0 inside flex containers (see the `flex-basis` gotcha documented in
+ * the chart-artifact orchestrator).
+ *
+ * Use directly when composing a chart from recharts primitives:
+ *
+ * ```tsx
+ * <ChartContainer height={320}>
+ *   <LineChart data={data} margin={{ top: 8, right: 16, left: 0, bottom: 4 }}>
+ *     <CartesianGrid {...CHART_GRID_PROPS} />
+ *     <XAxis dataKey="month" {...CHART_AXIS_PROPS} />
+ *     <YAxis {...CHART_AXIS_PROPS} />
+ *     <Tooltip content={<ChartTooltipContent />} />
+ *     <Legend content={<ChartLegendContent />} />
+ *     <Line dataKey="value" stroke={CHART_PALETTE[0]} />
+ *   </LineChart>
+ * </ChartContainer>
+ * ```
+ *
+ * For common shapes, prefer the pre-composed `<BarChart>` / `<LineChart>` / `<PieChart>` —
+ * they call `ChartContainer` under the hood with sensible defaults.
+ */
+declare function ChartContainer({ children, height, width, className, style, }: ChartContainerProps): ReactNode;
+
+/**
+ * Single entry in recharts' tooltip payload — one per series at the hovered x-tick.
+ * Typed locally because recharts' `TooltipProps['payload']` is overly tagged-generic for this use.
+ */
+interface TooltipPayloadEntry {
+    name?: string | number;
+    value?: number | string;
+    color?: string;
+    dataKey?: string | number;
+}
+/**
+ * Recharts injects `active`, `payload`, and `label` at runtime when this component is used as
+ * the `content` slot on `<Tooltip>`. Consumer-facing props (`className`, `showLabel`,
+ * `formatValue`) survive the cloneElement merge.
+ */
+interface ChartTooltipContentProps {
+    /** Set by recharts at runtime — true when the tooltip is hovered open. */
+    active?: boolean;
+    /** Set by recharts at runtime — one entry per series. */
+    payload?: TooltipPayloadEntry[];
+    /** Set by recharts at runtime — the x-tick label for the hovered column. */
+    label?: string | number;
+    /** Optional className merged onto the tooltip card. */
+    className?: string;
+    /** When false, the row label (typically the x-tick value) is hidden. Default true. */
+    showLabel?: boolean;
+    /** Override the formatter used on each entry's value. Defaults to `String(value)`. */
+    formatValue?: (value: number | string | undefined, name: string | undefined) => string;
+}
+/**
+ * The default tooltip card for clay charts. Drop into any recharts `<Tooltip>`:
+ *
+ * ```tsx
+ * <Tooltip content={<ChartTooltipContent />} />
+ * <Tooltip content={<ChartTooltipContent formatValue={(v) => `$${v}`} />} />
+ * ```
+ *
+ * Renders a soft brown card with one row per series, swatch left, name center, value right.
+ * Returns `null` when recharts says the tooltip is inactive — recharts mounts the content
+ * component unconditionally and toggles it via the `active` prop.
+ */
+declare function ChartTooltipContent({ active, payload, label, className, showLabel, formatValue, }: ChartTooltipContentProps): ReactNode;
+
+/**
+ * Single entry in recharts' legend payload — one per series. Typed locally because recharts'
+ * `LegendProps['payload']` is overly tagged-generic.
+ */
+interface LegendPayloadEntry {
+    value?: string | number;
+    color?: string;
+    dataKey?: string | number;
+    type?: string;
+}
+/**
+ * Recharts injects `payload` at runtime when this component is used as the `content` slot on
+ * `<Legend>`. Consumer-facing props (`className`, `iconType`) survive the cloneElement merge.
+ */
+interface ChartLegendContentProps {
+    /** Set by recharts at runtime — one entry per series. */
+    payload?: LegendPayloadEntry[];
+    /** Optional className merged onto the legend list. */
+    className?: string;
+    /** Visual indicator next to each label. `square` for bars/pies; `line` for line/area. Default `square`. */
+    iconType?: "square" | "line";
+}
+/**
+ * The default legend body for clay charts. Drop into any recharts `<Legend>`:
+ *
+ * ```tsx
+ * <Legend content={<ChartLegendContent iconType="square" />} />
+ * <Legend content={<ChartLegendContent iconType="line" />} />
+ * ```
+ *
+ * Recharts also accepts `verticalAlign` / `align` on `<Legend>` itself for positioning —
+ * `<ChartLegendContent>` is just the body. Style stays consistent regardless of position.
+ */
+declare function ChartLegendContent({ payload, className, iconType }: ChartLegendContentProps): ReactNode;
+
+/**
+ * Spreadable defaults for `<XAxis>` and `<YAxis>` — no axis line, no tick line, soft brown ticks.
+ * Pass `dataKey` explicitly on `<XAxis>`; leave it off `<YAxis>`. Override anything per-instance.
+ */
+declare const CHART_AXIS_PROPS: {
+    readonly stroke: "#CFCBC4";
+    readonly tick: {
+        readonly fill: "#73716D";
+        readonly fontSize: 12;
+        readonly fontWeight: 500;
+    };
+    readonly tickLine: false;
+    readonly axisLine: false;
+};
+/**
+ * Spreadable defaults for `<CartesianGrid>` — horizontal dashed lines only.
+ */
+declare const CHART_GRID_PROPS: {
+    readonly stroke: "#E6E2DA";
+    readonly strokeDasharray: "3 3";
+    readonly vertical: false;
+};
+
+/**
+ * Single ordered color palette shared by every chart variant (`BarChart`, `LineChart`,
+ * `PieChart`). A graduated walk down the blue family (`blue-600` → `blue-400` → `blue-300` →
+ * `blue-100`), pivot into the indigo family (`indigo-400` → `indigo-500` → `indigo-600` →
+ * `indigo-800`), and close on the deepest blue (`blue-800`).
+ *
+ * Design intent: every chart in the product sits in the same cool blue / indigo family so
+ * adjacent charts on a dashboard read as a unified system rather than a kaleidoscope. The
+ * deliberately narrow hue range (blue + indigo only — no warm accents) is the point: it
+ * forecloses on rainbow-coded multi-series charts where the visual noise outweighs the
+ * series-distinction it tries to provide.
+ *
+ * **Same palette for pie too**: pie slices read as parts of a whole, but they also share a
+ * dashboard with bar/line charts — keeping one palette across every variant means a single
+ * chat surface containing all three variants looks like one design system, not three.
+ *
+ * Nine entries — the v1 series cap. The palette cycles modulo its length for series counts
+ * past nine via `colorForSeriesIndex`.
+ */
+declare const CHART_PALETTE: readonly ["#2563EB", "#60A5FA", "#93C5FD", "#DBEAFE", "#818CF8", "#6366F1", "#4F46E5", "#3730A3", "#1E40AF"];
+/**
+ * Resolves the color for a series at `index`. Cycles deterministically past the palette length
+ * so configurations with more series than colors still render rather than throwing. Pass an
+ * alternate `palette` (e.g. a brand-specific override) to use something other than the default
+ * `CHART_PALETTE`.
+ */
+declare function colorForSeriesIndex(index: number, palette?: readonly string[]): string;
+
+/**
+ * Returns a shallow copy of `rows` with the `numericKeys` columns coerced to `number`.
+ * Cells that can't be parsed become `NaN`; `null` / `undefined` cells pass through untouched;
+ * columns NOT in `numericKeys` pass through unchanged.
+ *
+ * Recharts needs `number` on `dataKey` resolution for `<Line>` / `<Bar>` / `<Pie>` — already-
+ * numeric data is a no-op. The function exists for the CSV-derived case where values arrive
+ * as strings. `NaN` propagates to recharts as a missing data point (zero-height bar, gap in
+ * line, zero-area slice).
+ */
+declare function coerceNumericColumns(rows: ReadonlyArray<Record<string, unknown>>, numericKeys: ReadonlyArray<string>): Array<Record<string, unknown>>;
+
+export { BarChart, type BarChartProps, CHART_AXIS_PROPS, CHART_GRID_PROPS, CHART_PALETTE, ChartContainer, type ChartContainerProps, ChartLegendContent, type ChartLegendContentProps, ChartSeries, ChartTooltipContent, type ChartTooltipContentProps, LineChart, type LineChartProps, PieChart, type PieChartProps, coerceNumericColumns, colorForSeriesIndex };

package/dist/chart.js

@@ -0,0 +1,32 @@
+import {
+  BarChart,
+  CHART_AXIS_PROPS,
+  CHART_GRID_PROPS,
+  CHART_PALETTE,
+  ChartContainer,
+  ChartLegendContent,
+  ChartTooltipContent,
+  LineChart,
+  PieChart,
+  coerceNumericColumns,
+  colorForSeriesIndex
+} from "./chunk-QXGYMDIA.js";
+import "./chunk-C77QMQNT.js";
+import "./chunk-SV24ONND.js";
+import "./chunk-P6GUNIAE.js";
+import "./chunk-JF3P66JF.js";
+import "./chunk-5WRI5ZAA.js";
+export {
+  BarChart,
+  CHART_AXIS_PROPS,
+  CHART_GRID_PROPS,
+  CHART_PALETTE,
+  ChartContainer,
+  ChartLegendContent,
+  ChartTooltipContent,
+  LineChart,
+  PieChart,
+  coerceNumericColumns,
+  colorForSeriesIndex
+};
+//# sourceMappingURL=chart.js.map

package/dist/chart.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}