@overdoser/react-toolkit 0.0.6 → 0.0.8

package/AGENTS.md

@@ -54,6 +54,15 @@ For exhaustive component reference (every prop, every variant, every signature),
   - All data in memory → don't pass `onSort`; pass `pagination` (without `totalRows`) for client-side paging.
   - Data from a server → pass `sortConfig` + `onSort`, and `pagination` with `totalRows`.
 
+- **Need a chart?**
+  - Time series / trend → `<LineChart>` or `<AreaChart>` (use Area when the magnitude matters more than the precise line).
+  - Categorical comparison → `<BarChart>`.
+  - Share-of-whole / proportion → `<PieChart>` (donut variant via `innerRadius`).
+  - Multi-dimensional comparison across a fixed set of axes → `<RadarChart>` (spider chart).
+  - OHLCV / financial markets → `<TradingChart>` (canvas-rendered; plug-in `Datafeed`, pan + zoom + indicators).
+  - Tiny inline trend (table cell, KPI tile) → `<Sparkline>`.
+  - Axis-based charts share a `config` object: `{ [dataKey]: { label, color } }`. `PieChart` uses `nameKey` + `valueKey` (+ optional `colorKey`) instead. Colors via `var(--crk-chart-1)` … `var(--crk-chart-5)`.
+
 - **Multi-step / wizard form?** Use one `useForm()` per step OR a single `<Form>` wrapping all steps with conditional rendering. The toolkit doesn't ship a stepper.
 
 ## Common shapes (copy-paste)
@@ -97,6 +106,12 @@ Full copy-paste-able files live alongside this doc. Each is one self-contained f
 - [recipes/confirm-modal.tsx](./recipes/confirm-modal.tsx) — Reusable destructive-action confirm dialog.
 - [recipes/searchable-multi-select.tsx](./recipes/searchable-multi-select.tsx) — Multi-select with search and form integration.
 - [recipes/dropdown-menu.tsx](./recipes/dropdown-menu.tsx) — Row action menu with `Dropdown` + `DropdownItem`.
+- [recipes/dashboard-charts.tsx](./recipes/dashboard-charts.tsx) — Multi-chart dashboard layout with KPI tiles + Sparkline.
+- [recipes/interactive-bar-chart.tsx](./recipes/interactive-bar-chart.tsx) — Series-toggle pattern for `BarChart` (one series visible at a time) with three selector UIs exported: `InteractiveBarChartTiles`, `InteractiveBarChartNavigator`, `InteractiveBarChartDropdown`.
+- [recipes/interactive-line-chart.tsx](./recipes/interactive-line-chart.tsx) — Series-toggle pattern (one series visible at a time) with three selector UIs exported: `InteractiveLineChartTiles`, `InteractiveLineChartNavigator`, `InteractiveLineChartDropdown`.
+- [recipes/interactive-area-chart.tsx](./recipes/interactive-area-chart.tsx) — Data-range filter (not series toggle): all series stay visible, the selector picks the time window. Three selector UIs exported: `InteractiveAreaChartTiles`, `InteractiveAreaChartNavigator`, `InteractiveAreaChartDropdown`.
+- [recipes/interactive-pie-chart.tsx](./recipes/interactive-pie-chart.tsx) — Metric/period filter for `PieChart`: all slices stay visible, the selector picks which metric drives the pie. Three exports: `InteractivePieChartTiles`, `InteractivePieChartNavigator`, `InteractivePieChartDropdown`.
+- [recipes/trading-chart.tsx](./recipes/trading-chart.tsx) — Full-stack `TradingChart` with a resolution selector, in-memory datafeed adapter, and the SMA/EMA/Bollinger/RSI/Volume indicator stack. Swap `createMemoryDatafeed` for your own REST/WebSocket adapter; everything else carries over.
 
 ## Anti-patterns to refuse
 

package/components/Button/Button.d.ts

@@ -19,6 +19,19 @@ export interface ButtonProps extends ComponentPropsWithRef<'button'> {
     loadingStyle?: 'dots' | 'shimmer' | 'border';
     /** Stretch the button to fill its container's width. @default false */
     fullWidth?: boolean;
+    /**
+     * Square the button — for buttons whose only child is an icon (prev/next
+     * arrows, close, add, etc.). Width matches the same `size`'s normal-button
+     * height so icon and text buttons line up in a toolbar. SVG children are
+     * auto-sized to `1em`. Always pair with `aria-label`.
+     *
+     * Use inline SVG for icons rather than unicode glyphs (`‹` `›` `×` `+`) —
+     * SVG paths center geometrically; font glyphs depend on font metrics and
+     * may sit a hair above/below the visual centre.
+     *
+     * @default false
+     */
+    iconOnly?: boolean;
 }
 /**
  * Styled `<button>` with variants, sizes, and three loading-state animations.

package/components/Chart/AreaChart.d.ts

@@ -0,0 +1,85 @@
+import { CSSProperties, ReactNode } from 'react';
+import { ChartClasses, ChartConfig, ChartMargin } from './types';
+export interface AreaChartProps<T extends Record<string, unknown>> {
+    /** Row data. Each row must include `xKey` plus every key referenced in `config`. */
+    data: T[];
+    /** Data field providing the category labels on the X axis. */
+    xKey: keyof T & string;
+    /** Series configuration keyed by data-field name. */
+    config: ChartConfig;
+    /** Width-to-height ratio. @default 16 / 9 */
+    aspectRatio?: number;
+    /** Fixed pixel height. Overrides `aspectRatio`. */
+    height?: number;
+    /**
+     * Interpolation between points.
+     * - `'monotone'` (default): smooth Catmull-Rom-to-Bezier curve.
+     * - `'linear'`: straight segments.
+     * - `'step'`: step-after — value holds until the next x, then jumps.
+     * @default 'monotone'
+     */
+    curve?: 'linear' | 'monotone' | 'step';
+    /**
+     * Stack series on top of each other instead of overlaying them. Each row's
+     * series stack in `config` insertion order, bottom to top.
+     * @default false
+     */
+    stacked?: boolean;
+    /**
+     * How stacked series are offset. Only applies when `stacked` is true.
+     * - `'none'`: stack at raw values.
+     * - `'expand'`: normalize each row to sum to 1 (percentage stack).
+     * @default 'none'
+     */
+    stackOffset?: 'none' | 'expand';
+    /** Use a vertical linear gradient (opaque top → transparent bottom) for each series' fill. @default false */
+    fillGradient?: boolean;
+    /** Show horizontal grid lines. @default true */
+    showGrid?: boolean;
+    /** Show the X axis. @default true */
+    showXAxis?: boolean;
+    /** Show the Y axis. @default true */
+    showYAxis?: boolean;
+    /** Show the legend below the chart. @default true */
+    showLegend?: boolean;
+    /** Show the hover tooltip. @default true */
+    showTooltip?: boolean;
+    /** Approximate Y tick count. @default 5 */
+    yTickCount?: number;
+    /** Format Y axis tick labels. */
+    yFormat?: (v: number) => string;
+    /** Format X axis tick labels. */
+    xFormat?: (v: string) => string;
+    /** Format numeric values inside the default tooltip. */
+    valueFormat?: (v: number) => string;
+    /** Custom tooltip body. */
+    renderTooltip?: (row: T) => ReactNode;
+    /** Override the auto-computed plot margins. */
+    margin?: Partial<ChartMargin>;
+    /** Content rendered when `data` is empty. @default 'No data' */
+    emptyMessage?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /** Override class names on internal elements. */
+    classes?: Partial<ChartClasses>;
+}
+/**
+ * Themeable, responsive area chart. Covers the shadcn area-chart family via
+ * composable props:
+ * - **default / linear / step**: `curve`.
+ * - **legend / axes**: `showLegend`, `showXAxis`, `showYAxis` (all default true).
+ * - **stacked**: `stacked`.
+ * - **stacked-expand**: `stacked` + `stackOffset="expand"` (normalizes each row to 100%).
+ * - **gradient**: `fillGradient`.
+ * - **icons**: set `icon` on each entry in `config` (rendered in the legend in place of the swatch).
+ * - **interactive**: keep multiple series in `data`, pass only the active series to `config`. See `recipes/interactive-area-chart.tsx`.
+ *
+ * @example
+ * <AreaChart
+ *   data={data}
+ *   xKey="month"
+ *   config={{ visits: { label: 'Visits', color: 'var(--crk-chart-1)' } }}
+ *   fillGradient
+ * />
+ */
+export declare function AreaChart<T extends Record<string, unknown>>({ data, xKey, config, aspectRatio, height, curve, stacked, stackOffset, fillGradient, showGrid, showXAxis, showYAxis, showLegend, showTooltip, yTickCount, yFormat, xFormat, valueFormat, renderTooltip, margin: marginOverride, emptyMessage, className, style, classes, }: AreaChartProps<T>): import("react/jsx-runtime").JSX.Element;

package/components/Chart/Axis.d.ts

@@ -0,0 +1,30 @@
+import { ChartClasses } from './types';
+export interface YAxisProps {
+    /** Pixel positions and tick values for the Y axis. */
+    ticks: {
+        value: number;
+        y: number;
+    }[];
+    /** X coordinate of the axis line. */
+    x: number;
+    /** Plot width — used to draw horizontal grid lines. */
+    plotWidth: number;
+    format?: (v: number) => string;
+    showGrid?: boolean;
+    classes?: Partial<ChartClasses>;
+}
+/** Y axis with optional horizontal grid lines. */
+export declare function YAxis({ ticks, x, plotWidth, format, showGrid, classes }: YAxisProps): import("react/jsx-runtime").JSX.Element;
+export interface XAxisProps {
+    /** Pixel positions and labels for the X axis. */
+    ticks: {
+        label: string;
+        x: number;
+    }[];
+    /** Y coordinate of the axis line. */
+    y: number;
+    format?: (label: string) => string;
+    classes?: Partial<ChartClasses>;
+}
+/** X axis labels along the bottom of the plot. */
+export declare function XAxis({ ticks, y, format, classes }: XAxisProps): import("react/jsx-runtime").JSX.Element;

package/components/Chart/BarChart.d.ts

@@ -0,0 +1,111 @@
+import { CSSProperties, ReactNode } from 'react';
+import { ChartClasses, ChartConfig, ChartMargin } from './types';
+export interface BarLabelArgs<T> {
+    row: T;
+    value: number;
+    seriesKey: string;
+    index: number;
+}
+export interface BarClickArgs<T> {
+    row: T;
+    value: number;
+    seriesKey: string;
+    index: number;
+}
+export interface BarChartProps<T extends Record<string, unknown>> {
+    /** Row data. Each row must include `xKey` plus every key referenced in `config`. */
+    data: T[];
+    /** Data field providing the category labels. */
+    xKey: keyof T & string;
+    /** Series configuration keyed by data-field name. */
+    config: ChartConfig;
+    /** Bar layout direction. `'horizontal'` swaps the axes so bars extend left→right. @default 'vertical' */
+    orientation?: 'vertical' | 'horizontal';
+    /** Stack series within each category instead of placing them side-by-side. Ignored with a single series. @default false */
+    stacked?: boolean;
+    /** Width-to-height ratio. @default 16 / 9 */
+    aspectRatio?: number;
+    /** Fixed pixel height. Overrides `aspectRatio`. */
+    height?: number;
+    /** Inner padding between category groups, fraction of band width. @default 0.2 */
+    groupPadding?: number;
+    /** Inner padding between bars within a grouped group, fraction of bar width. Ignored when stacked. @default 0.1 */
+    barPadding?: number;
+    /** Corner radius applied to the value-end of each bar. @default 4 */
+    barRadius?: number;
+    /** Show grid lines along the value axis. @default true */
+    showGrid?: boolean;
+    /** Show the legend. @default true */
+    showLegend?: boolean;
+    /** Show the hover tooltip. @default true */
+    showTooltip?: boolean;
+    /** Render numeric labels on bars. @default false */
+    showValues?: boolean;
+    /**
+     * Where to render value labels relative to each bar.
+     * - `'outside'`: beyond the value end.
+     * - `'inside'`: inside the bar at the value end, no rotation.
+     * - `'inside-start'`: inside the bar at the start (baseline). On vertical bars,
+     *   the text is rotated ±90° so it reads along the bar's length.
+     * @default 'outside'
+     */
+    valuePosition?: 'outside' | 'inside' | 'inside-start';
+    /** Custom label content. Return `null` to skip a bar. Overrides `valueFormat` for labels. */
+    renderLabel?: (args: BarLabelArgs<T>) => ReactNode;
+    /**
+     * Bar coloring strategy.
+     * - `'series'` (default): uses `config[seriesKey].color`.
+     * - `'index'`: uses `colors[rowIndex % colors.length]`, ignoring series-config colors.
+     *   Useful for single-series "one color per category" charts.
+     * @default 'series'
+     */
+    colorBy?: 'series' | 'index';
+    /** Palette used when `colorBy='index'`. @default the 5 `--crk-chart-N` tokens */
+    colors?: string[];
+    /** Override color applied to bar segments whose value is negative. */
+    negativeColor?: string;
+    /** Highlight one category index; other groups fade. Pair with `onBarClick` for click-to-select UIs. */
+    activeIndex?: number;
+    /** Called when a bar is clicked. */
+    onBarClick?: (args: BarClickArgs<T>) => void;
+    /** Approximate value-axis tick count. @default 5 */
+    yTickCount?: number;
+    /** Format value-axis tick labels. */
+    yFormat?: (v: number) => string;
+    /** Format category-axis tick labels. */
+    xFormat?: (v: string) => string;
+    /** Format numeric values inside the default tooltip and inside labels (when `renderLabel` is not set). */
+    valueFormat?: (v: number) => string;
+    /** Custom tooltip body. */
+    renderTooltip?: (row: T) => ReactNode;
+    /** Override the auto-computed plot margins. */
+    margin?: Partial<ChartMargin>;
+    /** Content rendered when `data` is empty. @default 'No data' */
+    emptyMessage?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /** Override class names on internal elements. */
+    classes?: Partial<ChartClasses>;
+}
+/**
+ * Themeable, responsive bar chart that handles the full set of shadcn-style
+ * variants through composable props:
+ * - **default / multiple**: grouped vertical bars (no special props).
+ * - **horizontal**: `orientation="horizontal"`.
+ * - **stacked**: `stacked`.
+ * - **label / label-custom**: `showValues`, `valuePosition`, `renderLabel`.
+ * - **mixed**: `colorBy="index"` (+ optional `colors`).
+ * - **negative**: works out of the box; pair with `negativeColor` to recolor below zero.
+ * - **active / interactive**: `activeIndex` + `onBarClick`.
+ *
+ * @example
+ * <BarChart
+ *   data={data}
+ *   xKey="month"
+ *   config={{
+ *     revenue: { label: 'Revenue', color: 'var(--crk-chart-1)' },
+ *     costs:   { label: 'Costs',   color: 'var(--crk-chart-2)' },
+ *   }}
+ * />
+ */
+export declare function BarChart<T extends Record<string, unknown>>({ data, xKey, config, orientation, stacked, aspectRatio, height, groupPadding, barPadding, barRadius, showGrid, showLegend, showTooltip, showValues, valuePosition, renderLabel, colorBy, colors, negativeColor, activeIndex, onBarClick, yTickCount, yFormat, xFormat, valueFormat, renderTooltip, margin: marginOverride, emptyMessage, className, style, classes, }: BarChartProps<T>): import("react/jsx-runtime").JSX.Element;

package/components/Chart/ChartContainer.d.ts

@@ -0,0 +1,33 @@
+import { CSSProperties, ReactNode } from 'react';
+import { ChartClasses } from './types';
+export interface ChartContainerProps {
+    /**
+     * Width-to-height ratio. The container fills its parent width, then sets
+     * height = width / aspectRatio. Ignored when `height` is set.
+     * @default 16 / 9
+     */
+    aspectRatio?: number;
+    /** Fixed pixel height. Overrides `aspectRatio`. */
+    height?: number;
+    className?: string;
+    style?: CSSProperties;
+    classes?: Partial<ChartClasses>;
+    /** Optional legend rendered below the SVG. */
+    legend?: ReactNode;
+    /** Optional HTML overlay (e.g., tooltip) absolutely positioned over the SVG. */
+    overlay?: ReactNode;
+    /** Renders the SVG body given the observed plot size. */
+    children: (size: {
+        width: number;
+        height: number;
+    }) => ReactNode;
+}
+/**
+ * Responsive wrapper used by every chart in the toolkit.
+ *
+ * Tracks its rendered width via `ResizeObserver`, computes height from
+ * `aspectRatio` or uses an explicit `height`, and exposes the resulting size
+ * to its render-function child. Renders a `<svg>` at that size and provides
+ * an absolutely-positioned overlay slot for tooltips.
+ */
+export declare const ChartContainer: import('react').ForwardRefExoticComponent<ChartContainerProps & import('react').RefAttributes<HTMLDivElement>>;

package/components/Chart/ChartLegend.d.ts

@@ -0,0 +1,9 @@
+import { ChartClasses, ChartConfig } from './types';
+export interface ChartLegendProps {
+    config: ChartConfig;
+    /** Optional ordering — defaults to the order of `Object.keys(config)`. */
+    order?: string[];
+    classes?: Partial<ChartClasses>;
+}
+/** Renders a horizontal swatch + label for each entry in `config`. */
+export declare function ChartLegend({ config, order, classes }: ChartLegendProps): import("react/jsx-runtime").JSX.Element;

package/components/Chart/ChartTooltip.d.ts

@@ -0,0 +1,32 @@
+import { ReactNode } from 'react';
+import { ChartClasses, ChartConfig } from './types';
+export interface ChartTooltipProps<T> {
+    /** Row at the active index. */
+    row: T | null;
+    /** Container-relative pixel position. */
+    x: number;
+    y: number;
+    /** Width of the parent SVG, used to flip the tooltip when near the right edge. */
+    containerWidth: number;
+    /** Chart config — drives series rendering inside the default tooltip. */
+    config: ChartConfig;
+    /** Render-prop override for the body content. */
+    render?: (row: T) => ReactNode;
+    /** Format numeric values in the default body. @default `String` */
+    valueFormat?: (v: number) => string;
+    /** Format the title (defaults to a `xKey` lookup). */
+    titleKey?: string;
+    /**
+     * Resolve the bullet color for a given series in the active row.
+     * Return `undefined` to fall back to `config[seriesKey].color`.
+     * Lets charts that vary bar/segment color per row (negative-value
+     * overrides, `colorBy='index'`, etc.) keep the tooltip swatch in sync.
+     */
+    resolveColor?: (seriesKey: string) => string | undefined;
+    classes?: Partial<ChartClasses>;
+}
+/**
+ * Floating HTML tooltip rendered as an overlay over the chart SVG.
+ * Positions itself near `(x, y)` and flips horizontally when close to the right edge.
+ */
+export declare function ChartTooltip<T extends Record<string, unknown>>({ row, x, y, containerWidth, config, render, valueFormat, titleKey, resolveColor, classes, }: ChartTooltipProps<T>): import("react/jsx-runtime").JSX.Element | null;

package/components/Chart/LineChart.d.ts

@@ -0,0 +1,112 @@
+import { CSSProperties, ReactNode } from 'react';
+import { ChartClasses, ChartConfig, ChartMargin } from './types';
+export interface LineLabelArgs<T> {
+    row: T;
+    value: number;
+    seriesKey: string;
+    index: number;
+}
+export interface LineDotArgs<T> {
+    row: T;
+    value: number;
+    seriesKey: string;
+    index: number;
+    /** SVG-space coordinate of the point. */
+    x: number;
+    y: number;
+    /** Color the default dot would have used (resolved through `dotColorKey` if set). */
+    color: string;
+    /** Whether this point is the currently-active (hovered or controlled) point. */
+    active: boolean;
+}
+export interface LinePointClickArgs<T> {
+    row: T;
+    value: number;
+    seriesKey: string;
+    index: number;
+}
+export interface LineChartProps<T extends Record<string, unknown>> {
+    /** Row data. Each row must include `xKey` plus every key referenced in `config`. */
+    data: T[];
+    /** Data field providing the category labels on the X axis. */
+    xKey: keyof T & string;
+    /** Series configuration keyed by data-field name. */
+    config: ChartConfig;
+    /** Width-to-height ratio. @default 16 / 9 */
+    aspectRatio?: number;
+    /** Fixed pixel height. Overrides `aspectRatio`. */
+    height?: number;
+    /**
+     * Interpolation between points.
+     * - `'monotone'` (default): smooth Catmull-Rom-to-Bezier curve.
+     * - `'linear'`: straight segments.
+     * - `'step'`: stepped line (value holds horizontally until the next x).
+     * @default 'monotone'
+     */
+    curve?: 'linear' | 'monotone' | 'step';
+    /** Draw a dot at every data point. @default true */
+    showPoints?: boolean;
+    /**
+     * Data field whose value provides the dot color (per row). When set, each
+     * dot's fill comes from `row[dotColorKey]` instead of the series color.
+     * The line itself keeps the series color.
+     */
+    dotColorKey?: keyof T & string;
+    /** Custom dot renderer. Replaces the default `<circle>` per point. */
+    renderDot?: (args: LineDotArgs<T>) => ReactNode;
+    /** Render numeric labels next to each point. @default false */
+    showValues?: boolean;
+    /** Where to place the value labels. @default 'top' */
+    valuePosition?: 'top' | 'bottom';
+    /** Custom label content. Overrides `valueFormat` for labels. Return `null` to skip. */
+    renderLabel?: (args: LineLabelArgs<T>) => ReactNode;
+    /** Highlight a specific point index; non-active points fade. Pair with `onPointClick` for click-to-select UIs. */
+    activeIndex?: number;
+    /** Called when a point (or the area around it) is clicked. */
+    onPointClick?: (args: LinePointClickArgs<T>) => void;
+    /** Show horizontal grid lines. @default true */
+    showGrid?: boolean;
+    /** Show the legend below the chart. @default true */
+    showLegend?: boolean;
+    /** Show the hover tooltip. @default true */
+    showTooltip?: boolean;
+    /** Approximate Y tick count. @default 5 */
+    yTickCount?: number;
+    /** Format Y axis tick labels. */
+    yFormat?: (v: number) => string;
+    /** Format X axis tick labels. */
+    xFormat?: (v: string) => string;
+    /** Format numeric values inside the default tooltip and inside value labels (when `renderLabel` is not set). */
+    valueFormat?: (v: number) => string;
+    /** Custom tooltip body. */
+    renderTooltip?: (row: T) => ReactNode;
+    /** Override the auto-computed plot margins. */
+    margin?: Partial<ChartMargin>;
+    /** Content rendered when `data` is empty. @default 'No data' */
+    emptyMessage?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /** Override class names on internal elements. */
+    classes?: Partial<ChartClasses>;
+}
+/**
+ * Themeable, responsive line chart. One component covers the full shadcn
+ * line-chart family via composable props:
+ * - **default / multiple / linear / step**: `curve` + multiple keys in `config`.
+ * - **dots**: `showPoints` (on by default).
+ * - **dots-custom**: `renderDot`.
+ * - **dots-colors**: `dotColorKey` (each row's `[dotColorKey]` field is the dot's fill).
+ * - **label / label-custom**: `showValues` + `valuePosition`, or `renderLabel`.
+ * - **interactive**: `activeIndex` + `onPointClick`.
+ *
+ * @example
+ * <LineChart
+ *   data={[{ month: 'Jan', revenue: 100, costs: 50 }]}
+ *   xKey="month"
+ *   config={{
+ *     revenue: { label: 'Revenue', color: 'var(--crk-chart-1)' },
+ *     costs:   { label: 'Costs',   color: 'var(--crk-chart-2)' },
+ *   }}
+ * />
+ */
+export declare function LineChart<T extends Record<string, unknown>>({ data, xKey, config, aspectRatio, height, curve, showPoints, dotColorKey, renderDot, showValues, valuePosition, renderLabel, activeIndex, onPointClick, showGrid, showLegend, showTooltip, yTickCount, yFormat, xFormat, valueFormat, renderTooltip, margin: marginOverride, emptyMessage, className, style, classes, }: LineChartProps<T>): import("react/jsx-runtime").JSX.Element;

package/components/Chart/PieChart.d.ts

@@ -0,0 +1,100 @@
+import { CSSProperties, ReactNode } from 'react';
+import { ChartClasses } from './types';
+export interface PieLabelArgs<T> {
+    row: T;
+    value: number;
+    /** Slice share of the total (0–1). */
+    fraction: number;
+    index: number;
+}
+export interface PieSliceClickArgs<T> {
+    row: T;
+    value: number;
+    index: number;
+}
+export interface PieChartProps<T extends Record<string, unknown>> {
+    /** Row data — one slice per row. */
+    data: T[];
+    /** Row field providing the numeric slice value. */
+    valueKey: keyof T & string;
+    /** Row field providing the slice label (used in legend, tooltip, labels). */
+    nameKey: keyof T & string;
+    /** Optional row field whose value is used as the slice fill (CSS color string). Falls back to `colors`. */
+    colorKey?: keyof T & string;
+    /** Color palette indexed by row order. @default the five `--crk-chart-N` tokens */
+    colors?: string[];
+    /** Width-to-height ratio. @default 1 (square) */
+    aspectRatio?: number;
+    /** Fixed pixel height. Overrides `aspectRatio`. */
+    height?: number;
+    /**
+     * Inner radius — `0` for a pie, `>0` for a donut. Accepts a number (pixels)
+     * or a percentage string (`'50%'`). @default 0
+     */
+    innerRadius?: number | string;
+    /**
+     * Outer radius. Accepts a number (pixels) or a percentage string.
+     * @default '90%'
+     */
+    outerRadius?: number | string;
+    /** Slice separator stroke width. Set to `0` for the "separator-none" look. @default 2 */
+    strokeWidth?: number;
+    /** Stroke color (between slices). @default 'var(--crk-color-bg)' */
+    strokeColor?: string;
+    /** Gap between slices, in degrees (purely visual). @default 0 */
+    padAngle?: number;
+    /** Render slice labels (the row's nameKey by default; override with `renderLabel`). @default false */
+    showLabels?: boolean;
+    /** Label position relative to its slice. @default 'outside' */
+    valuePosition?: 'outside' | 'inside';
+    /**
+     * Draw a thin leader line from each slice edge to its outside label. Has
+     * no effect when `valuePosition` is `'inside'`. @default true
+     */
+    showLabelLines?: boolean;
+    /** Custom label content. Return `null` to skip a slice. */
+    renderLabel?: (args: PieLabelArgs<T>) => ReactNode;
+    /** Content rendered in the centre of the chart — typical pattern for donut summaries. */
+    centerLabel?: ReactNode;
+    /** Highlight one slice (pulls it outward); other slices fade. */
+    activeIndex?: number;
+    /** Fires when a slice is clicked. */
+    onSliceClick?: (args: PieSliceClickArgs<T>) => void;
+    /** Show the legend below the chart. @default true */
+    showLegend?: boolean;
+    /** Show the hover tooltip. @default true */
+    showTooltip?: boolean;
+    /** Format the numeric value inside the tooltip and labels. */
+    valueFormat?: (v: number) => string;
+    /** Custom tooltip body. */
+    renderTooltip?: (row: T) => ReactNode;
+    /** Content rendered when `data` is empty. @default 'No data' */
+    emptyMessage?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /** Override class names on internal elements. */
+    classes?: Partial<ChartClasses>;
+}
+/**
+ * Responsive pie / donut chart. Covers the shadcn pie-chart family:
+ * - **simple / donut**: `innerRadius` (0 → pie, > 0 → donut).
+ * - **legend**: `showLegend` (on by default).
+ * - **separator-none**: `strokeWidth={0}`.
+ * - **label / label-custom**: `showLabels` + `valuePosition`, or `renderLabel`.
+ * - **donut-text**: `centerLabel` (any ReactNode rendered at the centre).
+ * - **donut-active**: `activeIndex={n}` (pulls the slice outward, fades others).
+ * - **interactive**: data-filter pattern — see `recipes/interactive-pie-chart.tsx`.
+ *
+ * Stacked / nested-rings (shadcn's "stacked" variant) is not currently
+ * supported by this component.
+ *
+ * @example
+ * <PieChart
+ *   data={[{ browser: 'Chrome', visitors: 275 }, { browser: 'Safari', visitors: 200 }]}
+ *   nameKey="browser"
+ *   valueKey="visitors"
+ *   innerRadius="60%"
+ *   centerLabel={<strong>475</strong>}
+ * />
+ */
+export declare function PieChart<T extends Record<string, unknown>>({ data, valueKey, nameKey, colorKey, colors, aspectRatio, height, innerRadius, outerRadius, strokeWidth, strokeColor, padAngle, showLabels, valuePosition, showLabelLines, renderLabel, centerLabel, activeIndex, onSliceClick, showLegend, showTooltip, valueFormat, renderTooltip, emptyMessage, className, style, classes, }: PieChartProps<T>): import("react/jsx-runtime").JSX.Element;

package/components/Chart/RadarChart.d.ts

@@ -0,0 +1,86 @@
+import { CSSProperties, ReactNode } from 'react';
+import { ChartClasses, ChartConfig } from './types';
+export interface RadarAxisLabelArgs<T> {
+    row: T;
+    /** Row index = vertex index. */
+    index: number;
+    /** Vertex angle in degrees (0 = top, clockwise). */
+    angle: number;
+    /** Pixel coordinates of the outer-ring vertex. */
+    x: number;
+    y: number;
+    /** Suggested SVG `text-anchor` based on which side of the chart this vertex sits on. */
+    textAnchor: 'start' | 'middle' | 'end';
+}
+export interface RadarChartProps<T extends Record<string, unknown>> {
+    /** Row data — one vertex per row. */
+    data: T[];
+    /** Row field providing the axis (vertex) label. */
+    axisKey: keyof T & string;
+    /** Series configuration keyed by data-field name. */
+    config: ChartConfig;
+    /** Width-to-height ratio. @default 1 (square) */
+    aspectRatio?: number;
+    /** Fixed pixel height. Overrides `aspectRatio`. */
+    height?: number;
+    /** Grid ring shape. @default 'polygon' */
+    gridType?: 'polygon' | 'circle';
+    /** Show concentric grid rings. @default true */
+    showGrid?: boolean;
+    /** Show radial spokes from center to each axis vertex. @default true */
+    showRadialLines?: boolean;
+    /** Show the categorical axis labels at each vertex. @default true */
+    showAxisLabels?: boolean;
+    /** Show the radius (value) axis labels along the top spoke. @default false */
+    showRadiusAxis?: boolean;
+    /** Approximate number of concentric grid rings / radius ticks. @default 5 */
+    levels?: number;
+    /** Draw a dot at every series vertex. @default true */
+    showPoints?: boolean;
+    /** Fill opacity for each series polygon. Pass `0` for the "lines-only" look. @default 0.4 */
+    fillOpacity?: number;
+    /** Stroke width for each series polygon outline. @default 2 */
+    strokeWidth?: number;
+    /** Custom axis-label renderer. Return `null` to skip a vertex. */
+    renderAxisLabel?: (args: RadarAxisLabelArgs<T>) => ReactNode;
+    /** Format the axis label text in the default renderer. */
+    axisFormat?: (label: string) => string;
+    /** Format numeric values inside the default tooltip and the radius axis labels. */
+    valueFormat?: (v: number) => string;
+    /** Custom tooltip body. */
+    renderTooltip?: (row: T) => ReactNode;
+    /** Show the legend below the chart. @default true */
+    showLegend?: boolean;
+    /** Show the hover tooltip. @default true */
+    showTooltip?: boolean;
+    /** Content rendered when `data` is empty. @default 'No data' */
+    emptyMessage?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /** Override class names on internal elements. */
+    classes?: Partial<ChartClasses>;
+}
+/**
+ * Themeable, responsive radar (spider) chart. Covers the full shadcn
+ * radar-chart family via composable props:
+ * - **default / multiple / legend**: base (multiple keys in `config`).
+ * - **dots**: `showPoints` (on by default).
+ * - **lines-only**: `fillOpacity={0}`.
+ * - **grid-circle / grid-circle-fill / grid-circle-no-lines**: `gridType="circle"` (+ `showRadialLines={false}` for the third).
+ * - **grid-fill / grid-custom**: defaults; theme via `classes` and the chart tokens.
+ * - **grid-none**: `showGrid={false}`.
+ * - **icons**: set `icon` on each entry in `config` (rendered in the legend).
+ * - **label-custom**: `renderAxisLabel`.
+ * - **radius**: `showRadiusAxis`.
+ *
+ * @example
+ * <RadarChart
+ *   data={[{ month: 'Jan', desktop: 186, mobile: 80 }]}
+ *   axisKey="month"
+ *   config={{
+ *     desktop: { label: 'Desktop', color: 'var(--crk-chart-1)' },
+ *     mobile:  { label: 'Mobile',  color: 'var(--crk-chart-2)' },
+ *   }}
+ * />
+ */
+export declare function RadarChart<T extends Record<string, unknown>>({ data, axisKey, config, aspectRatio, height, gridType, showGrid, showRadialLines, showAxisLabels, showRadiusAxis, levels, showPoints, fillOpacity, strokeWidth, renderAxisLabel, axisFormat, valueFormat, renderTooltip, showLegend, showTooltip, emptyMessage, className, style, classes, }: RadarChartProps<T>): import("react/jsx-runtime").JSX.Element;