@gntik-ai/charts 0.0.0-stage → 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,642 @@
+
+import { TooltipContentProps } from "recharts";
+import { FocusEvent, ReactNode, Ref, SVGAttributes } from "react";
+import { Theme } from "@gntik-ai/tokens/runtime";
+//#region src/theme.d.ts
+/** Series colour name → brand token. Green primary is the hero; the rest are categorical accents. */
+export declare const SERIES_TOKENS: {
+  readonly primary: "--primary";
+  readonly emerald: "--brand-accent";
+  readonly violet: "--category-violet";
+  readonly cyan: "--category-cyan";
+  readonly amber: "--category-amber";
+  readonly rose: "--category-rose";
+  readonly info: "--info";
+};
+type ChartColor = keyof typeof SERIES_TOKENS;
+/**
+ * Default series order: primary first, then the categorical accents ordered so every adjacent
+ * pair differs in luminance by ≥ 1.5:1 in all three themes (see `palette.ts`).
+ */
+export declare const CHART_COLORS: readonly ChartColor[];
+interface ChartTheme {
+  /** Active theme ("dark" | "light" | "high_contrast"); "dark" on the server and during hydration. */
+  theme: Theme;
+  grid: string;
+  axis: string;
+  text: string;
+  /** Line/area hover cursor. */
+  cursor: string;
+  /** Bar hover band. */
+  barCursor: string;
+  /** Card surface (donut slice separators). */
+  surface: string;
+  /** Colour for a series name, with optional alpha (0–1). */
+  color: (name: ChartColor, alpha?: number) => string;
+}
+interface UseChartThemeOptions {
+  /**
+   * Resolve the tokens to concrete `hsl(h s% l%)` strings (read from the DOM after hydration),
+   * for consumers that cannot use `var()` (canvas, colour maths). Default: `hsl(var(--token))`.
+   */
+  resolved?: boolean;
+}
+/**
+ * Brand colours for Recharts. By default every colour is a `hsl(var(--token))` string: SVG
+ * fill/stroke attributes and inline styles resolve it, so server and client render the same
+ * markup and a theme switch re-skins the chart without re-rendering. `theme` follows the
+ * <html> class after mount. With `{ resolved: true }` colours are read from the live CSS
+ * variables once mounted (the server and hydration render use the `var()` strings).
+ */
+export declare function useChartTheme({ resolved }?: UseChartThemeOptions): ChartTheme;
+//#endregion
+//#region src/format.d.ts
+/** Formats a numeric value for axes, tooltips and legends. */
+type ValueFormatter = (value: number) => string;
+/** Ready-made value formatters (en-US). */
+export declare const chartFmt: {
+  usd: (n: number) => string;
+  usd2: (n: number) => string;
+  usdCompact: (n: number) => string;
+  num: (n: number) => string;
+  compact: (n: number) => string;
+  ms: (n: number) => string;
+  pct: (n: number) => string;
+  /** Ratio (0–1) → percent with up to one decimal: `0.125` → `12.5%`. */
+  percent: (n: number) => string;
+  /** Signed ratio for deltas: `0.042` → `+4.2%`, `-0.1` → `−10%`. */
+  percentDelta: (n: number) => string;
+  /** Milliseconds → the two largest units: `850` → `850 ms`, `2400` → `2.4 s`, `3_723_000` → `1h 2m`. */
+  duration: (n: number) => string;
+  /** Seconds → like `duration`: `90` → `1m 30s`. */
+  durationS: (n: number) => string;
+  /** Bytes → decimal SI units: `1536` → `1.5 kB`, `2_000_000_000` → `2 GB`. */
+  bytes: (n: number) => string;
+};
+//#endregion
+//#region src/states.d.ts
+/** Lifecycle of a chart's data. `ready` with no rows renders the empty state. */
+type ChartState = 'ready' | 'loading' | 'empty' | 'error';
+/** State props shared by every chart. */
+interface ChartStateProps {
+  /** Data lifecycle. Default `ready` (an empty `data` array still shows the empty state). */
+  state?: ChartState;
+  /** Message of the empty state. */
+  emptyMessage?: ReactNode;
+  /** Message of the error state. */
+  errorMessage?: ReactNode;
+  /** Shows a "Retry" button in the error state. */
+  onRetry?: () => void;
+  /** Renders a visually hidden data table (screen-reader fallback of the plotted values). */
+  dataTable?: boolean;
+}
+interface ChartEmptyProps {
+  height?: number;
+  children?: ReactNode;
+  className?: string;
+}
+/** Placeholder for a chart without data. */
+export declare function ChartEmpty({ height, children, className }: ChartEmptyProps): import("react").JSX.Element;
+interface ChartLoadingProps {
+  height?: number;
+  /** Accessible label of the busy region. */
+  label?: string;
+  className?: string;
+}
+/** Skeleton plot (bars over a baseline); the pulse stops under prefers-reduced-motion. */
+export declare function ChartLoading({ height, label, className }: ChartLoadingProps): import("react").JSX.Element;
+interface ChartErrorProps {
+  height?: number;
+  children?: ReactNode;
+  onRetry?: () => void;
+  className?: string;
+}
+/** Error placeholder with an optional retry action. */
+export declare function ChartError({ height, children, onRetry, className }: ChartErrorProps): import("react").JSX.Element;
+interface ChartDataTableProps {
+  caption: string;
+  /** Column headers; the first column is the row header. */
+  columns: readonly string[];
+  rows: ReadonlyArray<readonly ReactNode[]>;
+  /** Show the table instead of hiding it visually. */
+  visible?: boolean;
+}
+/** Plain data table: a screen-reader fallback for a chart (visually hidden by default). */
+export declare function ChartDataTable({ caption, columns, rows, visible }: ChartDataTableProps): import("react").JSX.Element;
+//#endregion
+//#region src/shared.d.ts
+/** Keys of a datum (string keys only). */
+type DataKey<T> = Extract<keyof T, string>;
+/** Props shared by every cartesian chart (Tremor-like API). */
+interface BaseChartProps<T extends object> extends ChartStateProps {
+  data: readonly T[];
+  /** Key of the x-axis (category) field. */
+  index: DataKey<T>;
+  /** Accessible name of the chart. Falls back to `title`, then to a generated summary. */
+  'aria-label'?: string;
+  /** Title rendered inside the SVG (`<title>`), also used as accessible name fallback. */
+  title?: string;
+  /** Longer description rendered inside the SVG (`<desc>`). */
+  description?: string;
+  colors?: readonly ChartColor[];
+  valueFormatter?: ValueFormatter;
+  showLegend?: boolean;
+  showGrid?: boolean;
+  /** Plot height in px (legend excluded). */
+  height?: number;
+  className?: string;
+}
+//#endregion
+//#region src/ChartBrush.d.ts
+/** Inclusive `[start, end]` indices into the chart data. */
+type ChartRange = readonly [number, number];
+/** Clamps a range to `[0, length - 1]`, ordered, at least `minSpan` points wide when possible. */
+export declare function clampRange(range: ChartRange | null | undefined, length: number, minSpan?: number): [number, number];
+interface UseChartRangeOptions {
+  length: number;
+  range?: ChartRange;
+  defaultRange?: ChartRange;
+  onRangeChange?: (range: ChartRange) => void;
+}
+/** Controlled/uncontrolled brush range; `null` inner state means "everything". */
+export declare function useChartRange({ length, range, defaultRange, onRangeChange }: UseChartRangeOptions): readonly [[number, number], (next: ChartRange) => void];
+interface ChartBrushProps {
+  /** Number of data points. */
+  length: number;
+  range: ChartRange;
+  onRangeChange: (range: ChartRange) => void;
+  /** Text of the x value at an index (handles' aria-valuetext and the range summary). */
+  labelOf: (index: number) => string;
+  /** Values of one series, drawn as a faint overview line inside the track. */
+  preview?: readonly number[];
+  /** Accessible name of the brush group. */
+  label?: string;
+  className?: string;
+}
+/**
+ * Range brush under a time-series chart: two keyboard-accessible handles (`role="slider"`,
+ * Arrow keys ±1, PageUp/PageDown ±10%, Home/End) and a draggable window to pan.
+ */
+export declare function ChartBrush({ length, range, onRangeChange, labelOf, preview, label, className }: ChartBrushProps): import("react").JSX.Element | null;
+//#endregion
+//#region src/overlays.d.ts
+/** Semantic tone of a threshold or annotation (maps to a brand token, never a raw colour). */
+type ChartTone = 'neutral' | 'primary' | 'success' | 'warning' | 'destructive' | 'info';
+/** A horizontal reference line on the value axis (an SLO, a budget, a limit). */
+interface ChartThreshold {
+  /** Value on the value axis. */
+  value: number;
+  /** Visible label drawn next to the line (thresholds are never colour-only). */
+  label: string;
+  tone?: ChartTone;
+  /** ComboChart only: the axis the value belongs to (default `left`, the bar axis). */
+  axis?: 'left' | 'right';
+}
+/** A vertical marker at an x (category) value: a deploy, an incident, a release. */
+interface ChartAnnotation {
+  /** Category value on the x axis (must match an `index` value of the data). */
+  x: string | number;
+  /** Short visible label (drawn on the marker and listed under the chart). */
+  label: string;
+  /** Longer text shown in the marker tooltip and read by screen readers. */
+  description?: string;
+  tone?: ChartTone;
+}
+/** Stroke token and contrast-safe text token of each tone. */
+export declare const TONE_TOKENS: Record<ChartTone, {
+  stroke: string;
+  text: string;
+}>;
+interface ChartMarkersProps {
+  thresholds?: readonly ChartThreshold[];
+  annotations?: readonly ChartAnnotation[];
+  /** Formats threshold values (the chart's value formatter). */
+  valueFormatter?: ValueFormatter;
+  /** Key of the annotation highlighted in the plot. */
+  active?: string | null;
+  onActiveChange?: (key: string | null) => void;
+  className?: string;
+}
+/**
+ * Text list of the thresholds and annotations under a chart: the keyboard and screen-reader
+ * route to the same information as the in-plot markers. Focusing or hovering an annotation
+ * highlights its marker and opens its tooltip in the plot.
+ */
+export declare function ChartMarkers({ thresholds, annotations, valueFormatter, active, onActiveChange, className }: ChartMarkersProps): import("react").JSX.Element | null;
+//#endregion
+//#region src/cartesian-extras.d.ts
+/** Thresholds, annotations, brush zoom and animation: shared by Line, Area, Bar and Combo charts. */
+interface CartesianExtrasProps {
+  /** Horizontal reference lines on the value axis, each with a visible label and a tone. */
+  thresholds?: readonly ChartThreshold[];
+  /** Vertical markers at x values (deploys, incidents), with a label and a tooltip. */
+  annotations?: readonly ChartAnnotation[];
+  /** Shows a range brush under the plot to zoom into part of the series. */
+  brush?: boolean;
+  /** Controlled brush range: inclusive `[start, end]` indices into `data`. */
+  range?: ChartRange;
+  /** Initial brush range (uncontrolled). Default: every point. */
+  defaultRange?: ChartRange;
+  onRangeChange?: (range: ChartRange) => void;
+  /** Animate data changes (e.g. a live series). Always off under prefers-reduced-motion. Default false. */
+  animate?: boolean;
+}
+//#endregion
+//#region src/AreaChart.d.ts
+interface AreaChartProps<T extends object> extends CartesianExtrasProps, BaseChartProps<T> {
+  categories: ReadonlyArray<DataKey<T>>;
+  stacked?: boolean;
+  showYAxis?: boolean;
+  curve?: 'monotone' | 'linear' | 'step' | 'natural';
+}
+/** Area chart: flat fills (no gradient), no entry animation, interactive legend. */
+export declare function AreaChart<T extends object>({ data, index, categories, colors, valueFormatter, stacked, showLegend, showGrid, showYAxis, curve, height, title, description, className, 'aria-label': ariaLabel, state, emptyMessage, errorMessage, onRetry, dataTable, thresholds, annotations, brush, range, defaultRange, onRangeChange, animate }: AreaChartProps<T>): import("react").JSX.Element;
+//#endregion
+//#region src/BarChart.d.ts
+interface BarChartProps<T extends object> extends CartesianExtrasProps, BaseChartProps<T> {
+  categories: ReadonlyArray<DataKey<T>>;
+  stacked?: boolean;
+  /** "horizontal" = vertical bars (categories on X); "vertical" = horizontal bars (categories on Y). */
+  layout?: 'horizontal' | 'vertical';
+  showYAxis?: boolean;
+}
+/** Bar chart: vertical, horizontal or stacked; flat fills, no animation. */
+export declare function BarChart<T extends object>({ data, index, categories, colors, valueFormatter, stacked, layout, showLegend, showGrid, showYAxis, height, title, description, className, 'aria-label': ariaLabel, state, emptyMessage, errorMessage, onRetry, dataTable, thresholds, annotations, brush, range, defaultRange, onRangeChange, animate }: BarChartProps<T>): import("react").JSX.Element;
+//#endregion
+//#region src/LineChart.d.ts
+interface LineChartProps<T extends object> extends CartesianExtrasProps, BaseChartProps<T> {
+  categories: ReadonlyArray<DataKey<T>>;
+  showYAxis?: boolean;
+  /** Only label the first and last x ticks. */
+  startEndOnly?: boolean;
+  curve?: 'monotone' | 'linear' | 'step' | 'natural';
+}
+/** Line chart: 2px strokes, no dots until hover, no animation. */
+export declare function LineChart<T extends object>({ data, index, categories, colors, valueFormatter, showLegend, showGrid, showYAxis, startEndOnly, curve, height, title, description, className, 'aria-label': ariaLabel, state, emptyMessage, errorMessage, onRetry, dataTable, thresholds, annotations, brush, range, defaultRange, onRangeChange, animate }: LineChartProps<T>): import("react").JSX.Element;
+//#endregion
+//#region src/ComboChart.d.ts
+interface ComboChartProps<T extends object> extends CartesianExtrasProps, Omit<BaseChartProps<T>, 'colors' | 'valueFormatter'> {
+  /** Series drawn as bars on the left axis. */
+  barSeries: DataKey<T>;
+  /** Series drawn as a line on the right axis. */
+  lineSeries: DataKey<T>;
+  barColor?: ChartColor;
+  lineColor?: ChartColor;
+  barFormatter?: ValueFormatter;
+  lineFormatter?: ValueFormatter;
+}
+/** Combo chart: bars on the left axis, a line on the right axis. */
+export declare function ComboChart<T extends object>({ data, index, barSeries, lineSeries, barColor, lineColor, barFormatter, lineFormatter, showLegend, showGrid, height, title, description, className, 'aria-label': ariaLabel, state, emptyMessage, errorMessage, onRetry, dataTable, thresholds, annotations, brush, range, defaultRange, onRangeChange, animate }: ComboChartProps<T>): import("react").JSX.Element;
+//#endregion
+//#region src/DonutChart.d.ts
+interface DonutChartProps<T extends object> extends ChartStateProps {
+  data: readonly T[];
+  /** Key of the slice name field. */
+  index: DataKey<T>;
+  /** Key of the slice value field. */
+  category: DataKey<T>;
+  colors?: readonly ChartColor[];
+  valueFormatter?: ValueFormatter;
+  variant?: 'donut' | 'pie';
+  showLegend?: boolean;
+  /** Caption under the total in the donut hole (donut variant only). */
+  centerLabel?: string;
+  /** Diameter in px. */
+  height?: number;
+  'aria-label'?: string;
+  title?: string;
+  description?: string;
+  className?: string;
+}
+/** Donut / pie with a clickable value legend; hidden slices drop out of the total. */
+export declare function DonutChart<T extends object>({ data, index, category, colors, valueFormatter, variant, showLegend, centerLabel, height, title, description, className, 'aria-label': ariaLabel, state, emptyMessage, errorMessage, onRetry, dataTable }: DonutChartProps<T>): import("react").JSX.Element;
+//#endregion
+//#region src/BarList.d.ts
+declare const BAR_LIST_BG: {
+  readonly primary: "bg-primary/20";
+  readonly violet: "bg-category-violet/20";
+  readonly cyan: "bg-category-cyan/20";
+  readonly amber: "bg-category-amber/20";
+  readonly rose: "bg-category-rose/20";
+};
+interface BarListProps<T extends object> extends Omit<ChartStateProps, 'dataTable'> {
+  data: readonly T[];
+  index: DataKey<T>;
+  category: DataKey<T>;
+  valueFormatter?: ValueFormatter;
+  color?: keyof typeof BAR_LIST_BG;
+  sortOrder?: 'desc' | 'asc' | 'none';
+  'aria-label'?: string;
+  className?: string;
+}
+/** Axis-less ranked list: label inside a token-tinted bar, value on the right. */
+export declare function BarList<T extends object>({ data, index, category, valueFormatter, color, sortOrder, className, 'aria-label': ariaLabel, state, emptyMessage, errorMessage, onRetry }: BarListProps<T>): import("react").JSX.Element;
+//#endregion
+//#region src/ChartTooltip.d.ts
+/** The subset of a Recharts tooltip payload entry the brand tooltip reads. */
+interface ChartTooltipEntry {
+  name?: string | number;
+  value?: unknown;
+  color?: string;
+  fill?: string;
+  payload?: unknown;
+}
+interface ChartTooltipProps {
+  active?: boolean;
+  payload?: ReadonlyArray<ChartTooltipEntry>;
+  label?: string | number;
+  valueFormatter?: ValueFormatter;
+  /** Per-series formatter; wins over `valueFormatter` (used by ComboChart). */
+  seriesFormatter?: (value: unknown, name: string) => string;
+  labelFormatter?: (label: string | number) => ReactNode;
+}
+/** Brand tooltip card: label header + one row per series, values in mono. */
+export declare function ChartTooltip({ active, payload, label, valueFormatter, seriesFormatter, labelFormatter }: ChartTooltipProps): import("react").JSX.Element | null;
+/** Adapts Recharts 3 `<Tooltip content>` to the brand tooltip: `content={tooltipContent({ valueFormatter })}`. */
+export declare function tooltipContent(options: Omit<ChartTooltipProps, 'active' | 'payload' | 'label'>): (p: TooltipContentProps) => import("react").JSX.Element;
+//#endregion
+//#region src/ChartLegend.d.ts
+interface ChartLegendItem {
+  key: string;
+  label: string;
+  /** Resolved colour (from `useChartTheme().color`). */
+  color: string;
+}
+interface ChartLegendProps {
+  items: readonly ChartLegendItem[];
+  hidden: ReadonlySet<string>;
+  onToggle: (key: string) => void;
+  className?: string;
+}
+/** Interactive legend: each entry is a toggle button that shows/hides its series. */
+export declare function ChartLegend({ items, hidden, onToggle, className }: ChartLegendProps): import("react").JSX.Element;
+/** Legend state: the set of hidden series keys plus a toggle. */
+export declare function useHiddenSeries(): [ReadonlySet<string>, (key: string) => void];
+//#endregion
+//#region src/FunnelChart.d.ts
+interface FunnelChartProps<T extends object> extends ChartStateProps {
+  /** Stages in order, widest first. */
+  data: readonly T[];
+  /** Key of the stage name. */
+  index: DataKey<T>;
+  /** Key of the stage count. */
+  category: DataKey<T>;
+  /** Hue of the stages (a sequential ramp, strongest first). Default `primary`. */
+  color?: ChartColor;
+  valueFormatter?: ValueFormatter;
+  /** Show the stage list with conversion and drop-off. Default `true`. */
+  showStages?: boolean;
+  /** Funnel height in px. */
+  height?: number;
+  'aria-label'?: string;
+  title?: string;
+  description?: string;
+  className?: string;
+}
+interface FunnelStage {
+  name: string;
+  value: number;
+  /** Share of the first stage (0–1). */
+  conversion: number;
+  /** Loss from the previous stage (0–1); 0 for the first stage. */
+  dropOff: number;
+  fill: string;
+}
+/** Stage maths: conversion against the first stage and drop-off against the previous one. */
+export declare function funnelStages(values: ReadonlyArray<{
+  name: string;
+  value: number;
+}>, fills?: readonly string[]): FunnelStage[];
+/** Staged conversion funnel: trapezoids in a one-hue ramp plus a stage list with drop-off. */
+export declare function FunnelChart<T extends object>({ data, index, category, color, valueFormatter, showStages, height, title, description, className, 'aria-label': ariaLabel, state, emptyMessage, errorMessage, onRetry, dataTable }: FunnelChartProps<T>): import("react").JSX.Element;
+//#endregion
+//#region src/SankeyChart.d.ts
+interface SankeyNodeDatum {
+  name: string;
+  /** Series colour of the node (and of its outgoing flows). Default: cycles `colors`. */
+  color?: ChartColor;
+}
+interface SankeyLinkDatum {
+  /** Source node: its name or its index in `nodes`. */
+  source: string | number;
+  /** Target node: its name or its index in `nodes`. */
+  target: string | number;
+  value: number;
+}
+interface SankeyChartProps extends ChartStateProps {
+  nodes: readonly SankeyNodeDatum[];
+  links: readonly SankeyLinkDatum[];
+  colors?: readonly ChartColor[];
+  valueFormatter?: ValueFormatter;
+  /** Plot height in px. */
+  height?: number;
+  nodeWidth?: number;
+  nodePadding?: number;
+  'aria-label'?: string;
+  title?: string;
+  description?: string;
+  className?: string;
+}
+interface ResolvedLink {
+  source: number;
+  target: number;
+  value: number;
+}
+/** Turns name-or-index links into the index links Recharts expects; drops unknown endpoints and non-positive values. */
+export declare function resolveSankeyLinks(nodes: readonly SankeyNodeDatum[], links: readonly SankeyLinkDatum[]): ResolvedLink[];
+/** Flow diagram: nodes as token-coloured bars, links tinted with their source colour. */
+export declare function SankeyChart({ nodes, links, colors, valueFormatter, height, nodeWidth, nodePadding, title, description, className, 'aria-label': ariaLabel, state, emptyMessage, errorMessage, onRetry, dataTable }: SankeyChartProps): import("react").JSX.Element;
+//#endregion
+//#region src/RadarChart.d.ts
+interface RadarChartProps<T extends object> extends Omit<BaseChartProps<T>, 'showGrid'> {
+  /** One key per compared entity (a polygon each). `index` holds the axis names. */
+  categories: ReadonlyArray<DataKey<T>>;
+  /** Upper bound of the radial scale (e.g. 100 for scores). Default: data max. */
+  max?: number;
+  /** Show the concentric grid. Default `true`. */
+  showGrid?: boolean;
+  /** Show the radial scale ticks. Default `false`. */
+  showRadiusAxis?: boolean;
+}
+/** Multi-axis scores: one translucent polygon per category over a polygonal grid. */
+export declare function RadarChart<T extends object>({ data, index, categories, colors, valueFormatter, max, showLegend, showGrid, showRadiusAxis, height, title, description, className, 'aria-label': ariaLabel, state, emptyMessage, errorMessage, onRetry, dataTable }: RadarChartProps<T>): import("react").JSX.Element;
+//#endregion
+//#region src/Heatmap.d.ts
+interface HeatmapProps<T extends object> extends ChartStateProps {
+  /** One row per datum (cohort, day…). */
+  data: readonly T[];
+  /** Key of the row label. */
+  index: DataKey<T>;
+  /** Column keys (weeks, hours…), in display order. Missing / non-numeric values render as empty cells. */
+  categories: ReadonlyArray<DataKey<T>>;
+  /** `sequential` (default) for magnitudes, `diverging` for signed values around `domain[1]`. */
+  scale?: 'sequential' | 'diverging';
+  /** `[min, max]` or, for diverging, `[min, mid, max]`. Default: the data extent (mid 0). */
+  domain?: readonly [number, number] | readonly [number, number, number];
+  /** Number of colour steps. Default 6 (sequential) / 7 (diverging). */
+  steps?: number;
+  /** Hue of the sequential scale. Default `primary`. */
+  color?: ChartColor;
+  valueFormatter?: ValueFormatter;
+  /** Print the value inside each cell. */
+  showValues?: boolean;
+  /** Show the colour scale under the grid. Default `true`. */
+  showScale?: boolean;
+  /** Cell height in px (default 28). Ignored when `height` is set. */
+  cellHeight?: number;
+  /**
+   * Height of the grid in px (column labels included): cells shrink or grow to fill it (16–48 px
+   * each). Use it to match sibling charts, e.g. inside a ChartCard.
+   */
+  height?: number;
+  /** Row header column label (table fallback). Default: `index`. */
+  rowHeader?: string;
+  'aria-label'?: string;
+  title?: string;
+  className?: string;
+}
+/** Cell height that fits `rows` rows in `height` px (clamped to 16–48), or undefined without a height. */
+export declare function cellHeightFor(height: number | undefined, rows: number): number | undefined;
+/**
+ * Cohort / time grid coloured with a sequential or diverging token ramp. The colour grid is
+ * a single keyboard stop (arrow keys move the active cell, Home/End jump within the row) with a
+ * live readout; screen readers get the full data table (`dataTable`, on by default).
+ */
+export declare function Heatmap<T extends object>({ data, index, categories, scale, domain, steps, color, valueFormatter, showValues, showScale, cellHeight: cellHeightProp, height, rowHeader, title, className, 'aria-label': ariaLabel, state, emptyMessage, errorMessage, onRetry, dataTable }: HeatmapProps<T>): import("react").JSX.Element;
+//#endregion
+//#region src/MiniBar.d.ts
+/** Same tones as the `@gntik-ai/ui` Sparkline, so the two can sit side by side in stat cards. */
+type MiniBarTone = 'primary' | 'success' | 'warning' | 'destructive' | 'info' | 'neutral';
+interface MiniBarProps extends Omit<SVGAttributes<SVGSVGElement>, 'className' | 'width' | 'height'> {
+  className?: string;
+  ref?: Ref<SVGSVGElement>;
+  /** The series, oldest first. */
+  data: readonly number[];
+  /** Per-bar labels (e.g. dates) for hover titles and the accessible summary. */
+  labels?: readonly string[];
+  tone?: MiniBarTone;
+  /** Which bar is drawn at full strength; the rest are muted. Default `last`. */
+  highlight?: 'last' | 'max' | 'min' | 'none' | number;
+  width?: number;
+  height?: number;
+  /** What the series measures, used in the generated accessible name ("Deployments"). */
+  label?: string;
+  formatValue?: (value: number) => string;
+}
+/** "Deployments: 12 bars, latest 9, low 2, high 14, total 84". */
+export declare function describeBars(data: readonly number[], label?: string, format?: (v: number) => string): string;
+/**
+ * Sparkline-sized bar chart (pure SVG, no axes): drop-in next to `Sparkline variant="bar"`,
+ * with a highlighted bar, per-bar hover titles and a generated `role="img"` summary.
+ */
+export declare function MiniBar({ data, labels, tone, highlight, width, height, label, formatValue, className, ...props }: MiniBarProps): import("react").JSX.Element;
+//#endregion
+//#region src/palette.d.ts
+/**
+ * Data-viz palette built ONLY from the frozen brand tokens.
+ *
+ * Categorical: `SAFE_CHART_COLORS` orders the five accents so that every adjacent pair differs
+ * in relative luminance by at least 1.5:1 in dark, light and high_contrast (asserted by
+ * `palette.test.ts` against `@gntik-ai/tokens/brand.css`). It is the default `CHART_COLORS`
+ * order of every chart; this name is kept as an alias.
+ *
+ * Colour-blind safety: hue alone is never the only channel. Charts pair colour with position,
+ * labels or the legend text; use at most five categorical series, prefer a sequential ramp
+ * (one hue, varying lightness) for ordered data, and a diverging ramp (destructive ↔ muted ↔
+ * primary, i.e. red ↔ green, which deutan/protan viewers confuse) only together with value
+ * labels, a signed legend or the `dataTable` fallback — lightness still separates the ends.
+ */
+export declare const SAFE_CHART_COLORS: readonly ChartColor[];
+/** A CSS custom property name of a brand token (`--primary`, `--destructive`…). */
+type TokenName = `--${string}`;
+interface SequentialRampOptions {
+  /** Hue of the ramp (series colour name). Default `primary`. */
+  color?: ChartColor;
+  /** Surface the ramp fades into. Default `--card`. */
+  surface?: TokenName;
+  /**
+   * `mix` (default): opaque `color-mix(in oklab, …)` steps — safe for overlapping marks and text on top.
+   * `alpha`: `hsl(var(--token) / a)` steps that let the underlying surface show through.
+   */
+  mode?: 'mix' | 'alpha';
+  /** Strength of the weakest step, 0–1. Default 0.14. */
+  min?: number;
+}
+interface DivergingRampOptions {
+  /** Token for the low end. Default `--destructive`. */
+  negative?: TokenName;
+  /** Token for the high end. Default `--primary`. */
+  positive?: TokenName;
+  /** Token for the neutral midpoint. Default `--muted`. */
+  mid?: TokenName;
+  mode?: 'mix' | 'alpha';
+  /** Strength of the weakest non-neutral step, 0–1. Default 0.18. */
+  min?: number;
+}
+/**
+ * `n` colours from faint to the full token, for ordered magnitudes (heatmaps, choropleths,
+ * funnel stages). Every value is a CSS colour string usable as SVG fill/stroke or inline style.
+ */
+export declare function sequentialRamp(n: number, options?: SequentialRampOptions): string[];
+/**
+ * `n` colours from `negative` (index 0) through the neutral `mid` to `positive` (last index),
+ * for signed values around a meaningful centre (deltas, budgets, sentiment). With an odd `n`
+ * the middle step is the plain neutral token.
+ */
+export declare function divergingRamp(n: number, options?: DivergingRampOptions): string[];
+/**
+ * Index of the ramp step for `value`. `domain` is `[min, max]` (sequential) or
+ * `[min, mid, max]` (diverging: `mid` maps to the centre of the ramp).
+ */
+export declare function rampIndex(value: number, domain: readonly [number, number] | readonly [number, number, number], steps: number): number;
+/** Colour of `value` on `ramp` (see `rampIndex`). */
+export declare function rampColor(value: number, domain: readonly [number, number] | readonly [number, number, number], ramp: readonly string[]): string;
+//#endregion
+//#region src/live.d.ts
+/** `true` when the user asks for reduced motion (false on the server). */
+export declare function usePrefersReducedMotion(): boolean;
+interface UseLiveSeriesOptions<T> {
+  /** Points shown before the first `append`. */
+  initial?: readonly T[];
+  /** Points kept (oldest drop off). Default 60. */
+  windowSize?: number;
+  /** Freeze the plotted data while the pointer is over the chart or focus is inside it (default true). */
+  pauseOnInteraction?: boolean;
+}
+interface LiveSeriesPauseProps {
+  onPointerEnter: () => void;
+  onPointerLeave: () => void;
+  onFocus: () => void;
+  onBlur: (e: FocusEvent<HTMLElement>) => void;
+}
+interface LiveSeries<T> {
+  /** The data to plot: frozen while paused, the latest window otherwise. */
+  data: readonly T[];
+  /** Appends one point or several (keeps the last `windowSize`). Buffered while paused. */
+  append: (points: T | readonly T[]) => void;
+  /** Replaces every point. */
+  reset: (points?: readonly T[]) => void;
+  /** Paused by interaction (hover/focus) or by `pause()`. */
+  paused: boolean;
+  /** Paused with `pause()` / `togglePaused()` (a visible Pause button — WCAG 2.2.2). */
+  manuallyPaused: boolean;
+  pause: () => void;
+  resume: () => void;
+  togglePaused: () => void;
+  /** Points received while paused, shown on resume. */
+  pending: number;
+  /** The user prefers reduced motion: render updates without animation. */
+  reducedMotion: boolean;
+  /** Spread on the element wrapping the chart to pause on hover and focus. */
+  pauseProps: LiveSeriesPauseProps;
+}
+/**
+ * State for a live-updating chart: a sliding window of points, with updates frozen while the
+ * user hovers or focuses the chart (so a tooltip or a value does not move under them) and a
+ * manual pause. Render with `animate={!reducedMotion}` for smooth transitions only when the
+ * user has not asked for reduced motion.
+ */
+export declare function useLiveSeries<T>({ initial, windowSize, pauseOnInteraction }?: UseLiveSeriesOptions<T>): LiveSeries<T>;
+//#endregion
+export type { AreaChartProps, BarChartProps, BarListProps, BaseChartProps, CartesianExtrasProps, ChartAnnotation, ChartBrushProps, ChartColor, ChartDataTableProps, ChartEmptyProps, ChartErrorProps, ChartLegendItem, ChartLegendProps, ChartLoadingProps, ChartMarkersProps, ChartRange, ChartState, ChartStateProps, ChartTheme, ChartThreshold, ChartTone, ChartTooltipEntry, ChartTooltipProps, ComboChartProps, DivergingRampOptions, DonutChartProps, FunnelChartProps, FunnelStage, HeatmapProps, LineChartProps, LiveSeries, LiveSeriesPauseProps, MiniBarProps, MiniBarTone, RadarChartProps, SankeyChartProps, SankeyLinkDatum, SankeyNodeDatum, SequentialRampOptions, TokenName, UseChartRangeOptions, UseChartThemeOptions, UseLiveSeriesOptions, ValueFormatter };
+//# sourceMappingURL=index.d.ts.map