@cascivo/charts 0.3.3 → 0.3.8

package/dist/index.d.ts

@@ -1,5 +1,6 @@
+import { ReadonlySignal, Signal } from "@cascivo/core";
 import { ReactNode } from "react";
-import { Signal } from "@preact/signals-react";
+import { Signal as Signal$1 } from "@preact/signals-react";
 
 interface LinearScale {
   domain: [number, number];
@@ -39,10 +40,139 @@ interface TimeScale {
 }
 declare function timeScale(domain: [Date, Date], range: [number, number]): TimeScale;
 type Point = readonly [x: number, y: number];
-declare function linePath(points: readonly Point[], curve?: 'linear' | 'monotone'): string;
-declare function areaPath(points: readonly Point[], baseline: number, curve?: 'linear' | 'monotone'): string;
+/**
+ * Split a list of points (where `null` marks a gap / missing value) into
+ * contiguous defined runs. With `connectNulls`, drops the gaps and returns one
+ * run bridging them. A series `[a, null, b]` yields `[[a], [b]]` by default,
+ * or `[[a, b]]` when connecting — so a gap renders as a real break, not an
+ * invented straight segment.
+ */
+declare function splitDefined(points: readonly (Point | null)[], connectNulls?: boolean): Point[][];
+/** Curve interpolations supported by linePath / areaPath. */
+type Curve = 'linear' | 'monotone' | 'step' | 'stepBefore' | 'stepAfter' | 'natural' | 'basis' | 'cardinal' | 'catmullRom';
+declare function linePath(points: readonly Point[], curve?: Curve): string;
+declare function areaPath(points: readonly Point[], baseline: number, curve?: Curve): string;
 declare function arcPath(cx: number, cy: number, outerRadius: number, innerRadius: number, startAngle: number, endAngle: number): string;
 declare function stackSeries(series: readonly (readonly number[])[]): [number, number][][];
+/** A scale that maps a domain value to a pixel position within the plot area. */
+interface AnnotationScale {
+  map: (value: never) => number | undefined;
+  /** Band scales place a category at its start; add half the bandwidth to center. */
+  bandwidth?: number;
+}
+/**
+ * A declarative chart annotation. `line` draws a threshold/target rule across the
+ * plot; `area` shades a band between two values; `dot` marks a single point.
+ */
+type Annotation = {
+  kind: 'line'; /** Which axis the `value` is measured on. */
+  axis: 'x' | 'y';
+  value: number | string | Date;
+  label?: string;
+  color?: string; /** Dashed rule (default) vs solid. */
+  dash?: boolean;
+} | {
+  kind: 'area';
+  axis: 'x' | 'y';
+  from: number | string | Date;
+  to: number | string | Date;
+  label?: string;
+  color?: string;
+} | {
+  kind: 'dot';
+  x: number | string | Date;
+  y: number;
+  label?: string;
+  color?: string;
+} | {
+  /** A subject marker at (x, y) with a connector/leader line to an offset note label. */kind: 'note';
+  x: number | string | Date;
+  y: number;
+  label: string; /** Label offset from the subject, in px (default up-right). */
+  dx?: number;
+  dy?: number;
+  color?: string;
+} | {
+  /** Shade the region above/below a y value — a difference-from-threshold band. */kind: 'threshold';
+  value: number;
+  side: 'above' | 'below';
+  label?: string;
+  color?: string;
+};
+interface AnnotationContext {
+  xScale: AnnotationScale;
+  yScale: AnnotationScale;
+  innerW: number;
+  innerH: number;
+}
+/** Render a single annotation against the resolved scales. Returns null if it maps off-scale. */
+declare function renderAnnotation(annotation: Annotation, ctx: AnnotationContext, key: number): ReactNode;
+/** Render every annotation in the list against the resolved scales. */
+declare function renderAnnotations(annotations: readonly Annotation[] | undefined, ctx: AnnotationContext): ReactNode;
+/** Short human summary of an annotation, for the chart description / a11y tree. */
+declare function annotationSummary(a: Annotation): string;
+/**
+ * Opt-in value labels printed at each mark. `true` uses the defaults; an object
+ * tunes the formatter and placement. Labels are decorative (`aria-hidden`) — the
+ * value is already in the a11y tree via the fallback table and the aria-live tooltip.
+ */
+type LabelOptions = boolean | {
+  /** Format the raw value (default: `toLocaleString`). */format?: (value: number) => string; /** Where to place the label relative to its mark. `auto` flips above→inside when it won't fit. */
+  position?: 'auto' | 'above' | 'inside' | 'outside';
+};
+interface ResolvedLabelOptions {
+  format: (value: number) => string;
+  position: 'auto' | 'above' | 'inside' | 'outside';
+}
+/** Normalize the `labels` prop into resolved options, or `null` when disabled. */
+declare function resolveLabels(labels: LabelOptions | undefined): ResolvedLabelOptions | null;
+interface DataLabelProps {
+  x: number;
+  y: number;
+  text: string;
+  /** `muted` for inside-the-mark labels (on a colored fill), default otherwise. */
+  tone?: 'default' | 'muted';
+  anchor?: 'start' | 'middle' | 'end';
+}
+/** A single decorative value label. Always `aria-hidden` (value is in the a11y tree elsewhere). */
+declare function DataLabel({
+  x,
+  y,
+  text,
+  tone,
+  anchor
+}: DataLabelProps): ReactNode;
+type FillKind = 'solid' | 'gradient' | 'pattern';
+type PatternKind = 'dots' | 'lines' | 'cross';
+interface DefSeries {
+  id: string;
+  color: string;
+}
+declare function gradientId(prefix: string, seriesId: string): string;
+declare function patternId(prefix: string, seriesId: string): string;
+/**
+ * Resolve a series' fill: a `url(#id)` referencing a `<ChartDefs>` gradient/pattern,
+ * or the solid color when `fill === 'solid'`.
+ */
+declare function fillFor(prefix: string, seriesId: string, fill: FillKind, color: string): string;
+interface ChartDefsProps {
+  /** Unique per-chart prefix — pass a `useId()` so two charts on a page don't collide. */
+  prefix: string;
+  series: readonly DefSeries[];
+  fill: FillKind;
+  patternKind?: PatternKind | undefined;
+}
+/**
+ * Mint theme-derived SVG `<defs>` for the given series. Gradients fade the series
+ * color top→bottom; patterns stroke a dot/line/cross motif in the series color over
+ * a faint tint. All colors come from the resolved palette, so they stay CVD-safe.
+ */
+declare function ChartDefs({
+  prefix,
+  series,
+  fill,
+  patternKind
+}: ChartDefsProps): ReactNode;
 /** A single focusable data point for the chart tooltip system.
  * cx/cy are absolute SVG coordinates (already include margin offsets). */
 interface ChartPoint {
@@ -72,6 +202,12 @@ interface TooltipModel {
   points: ChartPoint[];
   /** Custom formatter — defaults to "label: value" */
   format?: (p: ChartPoint) => string;
+  /**
+   * Hit-test + presentation mode. `item` (default): nearest point in 2-D, one datum
+   * per tooltip. `axis`: nearest x-bucket, a vertical crosshair, and one tooltip
+   * listing every series at that x (carried as the point's `segments`).
+   */
+  mode?: 'item' | 'axis';
 }
 interface BarChartSeries<Datum> {
   id: string;
@@ -89,7 +225,7 @@ interface BarChartProps<Datum = {
   title: string;
   description?: string;
   orientation?: 'vertical' | 'horizontal';
-  mode?: 'grouped' | 'stacked';
+  mode?: 'grouped' | 'stacked' | 'percent';
   width?: number;
   height?: number;
   xTicks?: number;
@@ -103,6 +239,19 @@ interface BarChartProps<Datum = {
   className?: string;
   /** Render only the marks — no axes, grid lines, or legend. For micro/inline charts. */
   plain?: boolean;
+  /**
+   * Reference lines, bands, and markers drawn over the plot. Geometric axes: `y` is the
+   * vertical axis (a threshold on a vertical bar chart's value), `x` is horizontal.
+   */
+  annotations?: readonly Annotation[];
+  /** Print each bar's value as a label. `true` for defaults, or tune format/position. */
+  labels?: LabelOptions;
+  /** Fired when a point is clicked or activated (Enter/Space) — for drill-down. */
+  onSelect?: (point: ChartPoint) => void;
+  /** Bar fill style: solid (default), a gradient, or a pattern. */
+  fill?: FillKind;
+  /** Pattern motif when `fill="pattern"`. */
+  patternKind?: PatternKind;
 }
 declare function BarChart<Datum = {
   x: string;
@@ -124,7 +273,12 @@ declare function BarChart<Datum = {
   tooltip,
   tooltipFormat,
   className,
-  plain
+  plain,
+  annotations,
+  labels,
+  onSelect,
+  fill,
+  patternKind
 }: BarChartProps<Datum>): import("react").JSX.Element;
 /** One layer of a stacked bar at a category. */
 interface StackedSegment {
@@ -165,6 +319,28 @@ declare function toStackedSeries(rows: readonly StackedRow[]): {
 };
 /** Binary search for the index of the nearest value in a sorted array. */
 declare function nearestIndex(values: readonly number[], target: number): number;
+type Vec = readonly [x: number, y: number];
+interface Rect {
+  x0: number;
+  y0: number;
+  x1: number;
+  y1: number;
+}
+/**
+ * Index of the nearest site to (x, y) — i.e. which Voronoi cell the point falls in.
+ * Euclidean; returns -1 for an empty set. This is the precise nearest-point lookup
+ * for dense scatter/line hover.
+ */
+declare function voronoiFind(sites: readonly Vec[], x: number, y: number): number;
+/**
+ * Compute each site's Voronoi cell polygon by clipping `bounds` with the
+ * perpendicular bisector against every other site. O(n²) but correct and
+ * dependency-free — fine for the hundreds-of-points hover-mesh use case.
+ * Returns one polygon (array of points) per site, in site order.
+ */
+declare function voronoiCells(sites: readonly Vec[], bounds: Rect): Vec[][];
+/** Render a cell polygon as an SVG path `d` (closed). */
+declare function cellPath(cell: Vec[]): string;
 /** Statistical helpers for histogram and boxplot charts. */
 interface Bin {
   x0: number;
@@ -205,6 +381,356 @@ interface TreemapRect {
  * Returns rectangles positioned within [0, width] × [0, height].
  */
 declare function squarify(nodes: TreemapNode[], width: number, height: number): TreemapRect[];
+type StreamOffset = 'zero' | 'silhouette';
+/**
+ * Stacked `[y0, y1]` bands per series with a baseline offset. `zero` is a standard
+ * stack; `silhouette` centers each category's stack on a flowing baseline (the
+ * classic streamgraph). Dependency-free, built on `stackSeries`.
+ */
+declare function streamLayout(values: readonly (readonly number[])[], offset?: StreamOffset): [number, number][][];
+/** Min/max y across all bands — for the value-axis domain. */
+declare function streamExtent(bands: readonly (readonly [number, number])[][]): [number, number];
+interface HierNode {
+  id?: string;
+  label: string;
+  value?: number;
+  color?: string;
+  children?: HierNode[];
+}
+interface PartitionedNode {
+  node: HierNode;
+  depth: number;
+  /** Start/end angle in radians (0 = top, clockwise). */
+  a0: number;
+  a1: number;
+  value: number;
+}
+/** Sum a node's value bottom-up (a leaf's own value, or the sum of its children). */
+declare function sumValue(n: HierNode): number;
+/**
+ * Radial partition of a tree: each node gets an angular slice proportional to its
+ * value, nested by depth. Dependency-free; the radial sibling of the squarified
+ * treemap. Returns a flat list (root first) for easy rendering.
+ */
+declare function partition(root: HierNode, fullAngle?: number): PartitionedNode[];
+declare function maxDepth(nodes: readonly PartitionedNode[]): number;
+interface SankeyNode {
+  id: string;
+  label: string;
+  color?: string;
+}
+interface SankeyLink {
+  source: string;
+  target: string;
+  value: number;
+}
+interface LaidNode extends SankeyNode {
+  rank: number;
+  value: number;
+  x0: number;
+  x1: number;
+  y0: number;
+  y1: number;
+}
+interface LaidLink {
+  source: LaidNode;
+  target: LaidNode;
+  value: number;
+  /** Y at the source's right edge and target's left edge (band centers' tops). */
+  sy: number;
+  ty: number;
+  width: number;
+}
+interface SankeyLayout {
+  nodes: LaidNode[];
+  links: LaidLink[];
+}
+interface SankeyOptions {
+  width: number;
+  height: number;
+  nodeWidth?: number;
+  nodePadding?: number;
+}
+/**
+ * A dependency-free Sankey layout: rank nodes by longest path from a source,
+ * stack them within each rank sized by throughput, and route links as ribbons.
+ * No crossing-minimization sweep (stable input order) — good for the common
+ * small/medium flow diagram.
+ */
+declare function sankeyLayout(nodes: readonly SankeyNode[], links: readonly SankeyLink[], {
+  width,
+  height,
+  nodeWidth,
+  nodePadding
+}: SankeyOptions): SankeyLayout;
+/** Cubic ribbon path for one link (a filled band from source edge to target edge). */
+declare function linkPath(l: LaidLink): string;
+/**
+ * CVD-safe colour ramps for data→colour encoding. Colours are interpolated in
+ * **oklch** between perceptually ordered anchors:
+ * - `sequential` runs light→dark with monotonically decreasing lightness, so the
+ *   ordering survives any colour-vision deficiency (luminance carries the signal).
+ * - `diverging` runs a CVD-safe blue→neutral→orange pair, symmetric in lightness.
+ * Returned values are CSS `oklch()` strings — no `var()`, so they serialize cleanly
+ * for export and render identically across themes.
+ */
+type RampKind = 'sequential' | 'diverging';
+/** Sequential ramp (light→dark) at `t ∈ [0,1]`; clamps out-of-range. */
+declare function sequentialRamp(t: number): string;
+/** Diverging ramp (blue→neutral→orange) at `t ∈ [0,1]`; clamps out-of-range. */
+declare function divergingRamp(t: number): string;
+/** The ramp function for a kind. */
+declare function rampOf(kind: RampKind): (t: number) => string;
+/** `n` evenly-spaced ramp colours (for piecewise buckets + the legend gradient). */
+declare function rampStops(n: number, kind?: RampKind): string[];
+/** Read the lightness (L) component out of an `oklch(L C H)` string — test/util helper. */
+declare function rampLightness(color: string): number;
+/** Convert a polar (radius, angle) around a centre to cartesian (x, y). */
+declare function polarPoint(cx: number, cy: number, radius: number, angle: number): [number, number];
+interface AngleBand<T extends string = string> {
+  /** Start angle (radians) of a category's band. */
+  map: (v: T) => number | undefined;
+  /** Centre angle (radians) of a category's band. */
+  center: (v: T) => number | undefined;
+  /** Angular width of one band (radians). */
+  bandwidth: number;
+  /** Step between band starts (radians) — equals bandwidth for a gapless ring. */
+  step: number;
+}
+/**
+ * A band scale over the circle: maps categories to equal angular slices spanning
+ * `[a0, a1]` (radians, default a full turn).
+ */
+declare function angleBand<T extends string>(domain: readonly T[], range?: [number, number]): AngleBand<T>;
+/** A linear radius scale: value domain → `[innerR, outerR]` pixels. */
+declare function radiusScale(domain: [number, number], range: [number, number]): LinearScale;
+/**
+ * Pure, composable data-pipeline helpers — cascivo's answer to ECharts' dataset
+ * `transform`s. Each is a dependency-free `(rows) => rows` (or `rows → aggregated`)
+ * function meant to be chained left-to-right before handing the result to `encode`
+ * (see `dataset.ts`). No React, no signals; safe to run anywhere.
+ */
+type Row = Record<string, unknown>;
+/** Keep rows for which `pred` is true (stable order preserved). */
+declare function filter<T>(rows: readonly T[], pred: (row: T, index: number) => boolean): T[];
+type SortKey<T> = keyof T | ((row: T) => unknown);
+/** Stable sort by a field or accessor, ascending (default) or descending. */
+declare function sort<T>(rows: readonly T[], key: SortKey<T>, dir?: 'asc' | 'desc'): T[];
+type AggOp = 'sum' | 'mean' | 'min' | 'max' | 'count' | 'median';
+interface AggregateSpec {
+  /** Field(s) to group by. */
+  groupBy: string | readonly string[];
+  /** Map of output field → aggregation op applied to that field's numeric values. */
+  ops: Record<string, AggOp>;
+}
+/**
+ * Group rows by `groupBy` and aggregate each configured field. Output rows carry the
+ * group key fields plus one field per `ops` entry. Group order is first-seen (stable).
+ */
+declare function aggregate(rows: readonly Row[], spec: AggregateSpec): Row[];
+interface HistogramBin {
+  x0: number;
+  x1: number;
+  count: number;
+  values: number[];
+}
+/**
+ * Partition numeric values into evenly-spaced histogram buckets. Buckets are
+ * `[x0, x1)` except the last, which is closed so the maximum lands inside.
+ */
+declare function bin(values: readonly number[], opts?: {
+  bins?: number;
+  range?: [number, number];
+}): HistogramBin[];
+type RegressionType = 'linear' | 'exponential' | {
+  type: 'polynomial';
+  order: number;
+};
+interface RegressionResult {
+  predict: (x: number) => number;
+  /** Fitted points at each input x (sorted by x). */
+  points: [number, number][];
+  /** Coefficient of determination R² against the input y. */
+  r2: number;
+  /** Model coefficients (linear: [intercept, slope]; polynomial: [c0..cN]). */
+  coefficients: number[];
+}
+/**
+ * Least-squares regression. `linear` fits y = m·x + b; `exponential` fits y = a·e^(b·x)
+ * (over points with y > 0); `polynomial(order)` fits a degree-N curve. Returns a
+ * `predict`, the fitted points, R², and the coefficients. Degenerate inputs (fewer than
+ * two points) yield a constant fit rather than throwing.
+ */
+declare function regression(points: readonly [number, number][], opts?: {
+  type?: RegressionType;
+}): RegressionResult;
+interface EncodeMapping {
+  /** Field for the x value. */
+  x: string;
+  /** Field for the y value. */
+  y: string;
+  /** Optional field whose distinct values split rows into separate series. */
+  series?: string;
+  /** Optional label for the single-series case (default: the `y` field name). */
+  label?: string;
+}
+interface EncodedSeries {
+  id: string;
+  label: string;
+  data: {
+    x: unknown;
+    y: number;
+  }[];
+}
+interface EncodedResult {
+  series: EncodedSeries[];
+  x: (d: {
+    x: unknown;
+    y: number;
+  }) => unknown;
+  y: (d: {
+    x: unknown;
+    y: number;
+  }) => number;
+}
+/**
+ * Encode a flat table into chart-ready series. Without a `series` key the whole table
+ * becomes one series; with one, rows are split by that field's distinct values
+ * (first-seen order). Missing `x`/`y` fields yield `undefined`/`NaN` rather than throwing.
+ */
+declare function encode(rows: readonly Row[], mapping: EncodeMapping): EncodedResult;
+interface CategoryMapping {
+  /** Field for the slice/bar label. */
+  category: string;
+  /** Field for the numeric value. */
+  value: string;
+}
+interface CategoryDatum {
+  label: string;
+  value: number;
+}
+/** Encode a table into `{ label, value }[]` for pie/single-series bar charts. */
+declare function encodeCategory(rows: readonly Row[], mapping: CategoryMapping): CategoryDatum[];
+/**
+ * Downsampling for dense series — render thousands of points fast without losing
+ * visual shape. `lttb` (Largest-Triangle-Three-Buckets) preserves the perceived
+ * curve; `minmax` preserves spikes (keeps each bucket's extremes). Both are pure,
+ * dependency-free, and no-ops when the input already fits the threshold. The chart's
+ * fallback `<table>` keeps the full data, so a11y is unaffected by decimation.
+ */
+type Pt = readonly [number, number];
+/**
+ * Largest-Triangle-Three-Buckets. Returns at most `threshold` points, always keeping
+ * the first and last, choosing the point in each bucket that forms the largest
+ * triangle with the previously kept point and the next bucket's average.
+ */
+declare function lttb(points: readonly Pt[], threshold: number): Pt[];
+/**
+ * Min-max decimation. Splits into ~threshold/2 buckets and keeps each bucket's min and
+ * max y (emitted in x order), plus the first and last point — so spikes survive.
+ */
+declare function minmax(points: readonly Pt[], threshold: number): Pt[];
+type DecimateMethod = 'lttb' | 'minmax';
+/** Decimate with the chosen method (default LTTB); no-op below the threshold. */
+declare function decimate$1(points: readonly Pt[], threshold: number, method?: DecimateMethod): Pt[];
+/**
+ * A live source: call `push(point)` for each new datum; return an unsubscribe.
+ * This is the seam a polling loop, an `EventSource` (SSE), or a WebSocket plugs
+ * into — the helper never opens a connection itself.
+ */
+type StreamSource<P> = (push: (point: P) => void) => () => void;
+interface StreamDecimate<P> {
+  /** Cap the rendered point count at this many. */
+  to: number;
+  /** Numeric value used to choose which points to keep. */
+  y: (point: P) => number;
+  /** LTTB (default, shape-preserving) or min-max (spike-preserving). */
+  method?: DecimateMethod;
+}
+interface StreamSeriesOptions<P> {
+  /** Maximum retained points. Oldest evicted past this (O(1) ring buffer). */
+  capacity: number;
+  /** The live source feeding the buffer. */
+  source: StreamSource<P>;
+  /** Optionally downsample the window so the rendered series never exceeds `to`. */
+  decimate?: StreamDecimate<P>;
+}
+/**
+ * Feed a live `source` into a bounded, O(1) ring buffer and expose the current
+ * window as a signal for `LineChart`/`AreaChart`. Optionally decimate so a fast
+ * stream never blows the rendered point count. Component-scoped: the
+ * subscription starts on mount and tears down (unsubscribe + cancel flush) on
+ * unmount. No `useState`/`useEffect`.
+ */
+declare function useStreamSeries<P>(options: StreamSeriesOptions<P>): ReadonlySignal<readonly P[]>;
+interface BoundStream<P> {
+  signal: ReadonlySignal<readonly P[]>;
+  stop: () => void;
+}
+/**
+ * Non-hook form of {@link useStreamSeries} for imperative callers (outside a
+ * component). Returns the window signal plus a `stop()` that unsubscribes the
+ * source and cancels any pending flush.
+ */
+declare function bindStream<P>(options: StreamSeriesOptions<P>): BoundStream<P>;
+interface CanvasSize {
+  width: number;
+  height: number;
+}
+type CanvasPaint = (ctx: CanvasRenderingContext2D, size: CanvasSize) => void;
+interface CanvasLayerProps {
+  /** Getter that reads the (possibly signal-backed) size so a resize repaints. */
+  size: () => CanvasSize;
+  paint: CanvasPaint;
+}
+/**
+ * A `<canvas>` painted via `useSignalEffect`, positioned to overlay the plot. The
+ * size getter reads the chart's size signals, so a resize (or any signal the paint
+ * reads) repaints. Decorative — `aria-hidden`; the data lives in the SVG/DOM a11y
+ * tree above it. devicePixelRatio-scaled for crisp marks.
+ */
+declare function CanvasLayer({
+  size,
+  paint
+}: CanvasLayerProps): ReactNode;
+/** Resolve a CSS custom property (e.g. `--cascivo-chart-1`) to a concrete color via the canvas element. */
+declare function resolveColor(ctx: CanvasRenderingContext2D, cssValue: string): string;
+interface ToolboxOptions {
+  /** Export the chart as a PNG (default true). */
+  png?: boolean;
+  /** Export the chart as a standalone SVG (default true). */
+  svg?: boolean;
+  /** Toggle a readable data `<table>` (default true). */
+  dataView?: boolean;
+  /** Reset zoom / visualMap / legend filters (default true). */
+  restore?: boolean;
+}
+interface ToolboxProps {
+  options: ToolboxOptions;
+  onPng: () => void;
+  onSvg: () => void;
+  onToggleData: () => void;
+  onRestore: () => void;
+  showData: boolean;
+}
+/**
+ * The chart's utility belt — real `<button>`s (keyboard + focus-visible, ≥44px under
+ * coarse pointers) to export a PNG/SVG, toggle a data-view table, and restore the
+ * default view. Rendered in the chart's corner by `ChartFrame`.
+ */
+declare function Toolbox({
+  options,
+  onPng,
+  onSvg,
+  onToggleData,
+  onRestore,
+  showData
+}: ToolboxProps): import("react").JSX.Element;
+/** In-plot zoom-pan config: a shared index window + the total item count. */
+interface ZoomConfig {
+  window: Signal<[number, number]>;
+  count: number;
+}
 interface ChartFrameProps {
   title: string;
   description?: string | undefined;
@@ -228,6 +754,40 @@ interface ChartFrameProps {
     width: number;
     height: number;
   }) => TooltipModel | undefined) | undefined;
+  /** Fired when the focused/hovered point is clicked or activated (Enter/Space). */
+  onSelect?: ((point: ChartPoint) => void) | undefined;
+  /** Hover hit-test strategy: `rect` (default, nearest by x/y) or `voronoi` (precise cell membership). */
+  hover?: 'rect' | 'voronoi' | undefined;
+  /** When `'canvas'` and `paint` is given, dense marks paint to a `<canvas>` under the SVG chrome. */
+  renderer?: 'svg' | 'canvas' | undefined;
+  /** Canvas paint callback (marks only) — used when `renderer === 'canvas'`. */
+  paint?: CanvasPaint | undefined;
+  /** Enable in-plot wheel/drag zoom-pan + keyboard (`+`/`-`/`0`) bound to an index window. */
+  zoom?: ZoomConfig | undefined;
+  /** Render a toolbox (PNG/SVG export, data-view toggle, restore). `true` enables all tools. */
+  toolbox?: boolean | ToolboxOptions | undefined;
+  /** Extra reset run by the toolbox's Restore (e.g. clearing a visualMap filter). */
+  onRestore?: (() => void) | undefined;
+  /**
+   * Tune the (reduced-motion-gated) enter/update transitions. `false` disables them;
+   * an object sets `duration` (ms), `easing`, and the transitioned `properties`. Unset
+   * keeps the defaults. Always fully suppressed under `prefers-reduced-motion`.
+   */
+  transition?: boolean | {
+    duration?: number;
+    easing?: string;
+    properties?: string[];
+  } | undefined;
+  /** Render custom SVG behind the marks (a watermark, a region) — a lightweight extension seam. */
+  onBeforeDraw?: ((ctx: {
+    width: number;
+    height: number;
+  }) => ReactNode) | undefined;
+  /** Render custom SVG over the marks (an overlay, an extra series) — a lightweight extension seam. */
+  onAfterDraw?: ((ctx: {
+    width: number;
+    height: number;
+  }) => ReactNode) | undefined;
 }
 declare function ChartFrame({
   title,
@@ -240,7 +800,17 @@ declare function ChartFrame({
   'data-state': dataState,
   emptyLabel,
   plain,
-  tooltip
+  tooltip,
+  onSelect,
+  hover,
+  renderer,
+  paint,
+  zoom,
+  toolbox,
+  onRestore,
+  transition,
+  onBeforeDraw,
+  onAfterDraw
 }: ChartFrameProps): import("react").JSX.Element;
 interface ChartSize {
   width: number;
@@ -264,6 +834,66 @@ declare const PLAIN_MARGINS: {
   readonly bottom: 2;
   readonly left: 2;
 };
+/**
+ * Pure index-window math shared by the DataZoom slider and the in-plot wheel/drag
+ * zoom-pan. A "window" is an inclusive `[startIndex, endIndex]` over a series of
+ * `count` items; charts slice their data to it so the axes re-tick for free.
+ */
+/**
+ * Zoom a window toward an anchor expressed as a fraction (0–1) across the current
+ * window. `factor < 1` zooms in (narrows), `factor > 1` zooms out (widens). The
+ * result is rounded to integer indices and clamped to `[0, count-1]` with a
+ * minimum span.
+ */
+declare function zoomWindow(win: readonly [number, number], count: number, factor: number, anchorFraction: number): [number, number];
+/**
+ * Pan a window by a (possibly fractional) index delta, preserving its width and
+ * clamping to `[0, count-1]`.
+ */
+declare function panWindow(win: readonly [number, number], count: number, deltaIdx: number): [number, number];
+/** Whether a window is anything other than the full `[0, count-1]` range. */
+declare function isZoomed(win: readonly [number, number], count: number): boolean;
+/**
+ * A shared zoom window + hovered-x index for a group of connected charts. Charts
+ * passing the same `syncId` mirror each other's zoom and hover through this group.
+ * `null` means "unset" (use each chart's full range / no hover).
+ */
+interface SyncGroup {
+  window: Signal<[number, number] | null>;
+  hoverX: Signal<number | null>;
+}
+/**
+ * Get (lazily creating) the shared group for an id and increment its ref count.
+ * Every `getSyncGroup` must be paired with a `releaseSyncGroup` on teardown.
+ */
+declare function getSyncGroup(id: string): SyncGroup;
+/** Decrement an id's ref count; drop the group from the registry when it hits zero. */
+declare function releaseSyncGroup(id: string): void;
+/** Test-only: number of live sync groups. */
+declare function _syncGroupCount(): number;
+/**
+ * Chart export helpers — serialize the live `<svg>` to a standalone file (with the
+ * chart's resolved paint inlined so it renders without the page's CSS), rasterize it
+ * to a PNG at devicePixelRatio, and trigger a download. All guard SSR/jsdom: they
+ * no-op (returning null / doing nothing) when the DOM APIs are unavailable.
+ */
+/**
+ * Serialize an SVG element to a standalone string, inlining each element's resolved
+ * `fill`/`stroke`/`stop-color` (so `var(--cascivo-*)` tokens become concrete colours
+ * that render outside the page). Literal colours pass straight through.
+ */
+declare function serializeSvg(svg: SVGSVGElement): string;
+/**
+ * Rasterize a serialized SVG string to a PNG `Blob` at `width × height × dpr`.
+ * Resolves `null` when canvas/Image isn't available (SSR) or the image fails to load.
+ */
+declare function svgToPngBlob(svgString: string, opts: {
+  width: number;
+  height: number;
+  dpr?: number;
+}): Promise<Blob | null>;
+/** Trigger a browser download of a Blob (or string) under `filename`. No-op in SSR. */
+declare function download(content: Blob | string, filename: string): void;
 type AnyScale = LinearScale | BandScale | LogScale | TimeScale;
 interface AxisProps {
   scale: AnyScale;
@@ -298,6 +928,159 @@ declare function GridLines({
   tickCount,
   transform
 }: GridLinesProps): import("react").JSX.Element;
+type GlyphShape = 'circle' | 'square' | 'diamond' | 'triangle' | 'cross' | 'star';
+/**
+ * Centered path `d` for a glyph of the given pixel `size` (full width/height).
+ * `circle` returns an empty string — render a `<circle>` for crispness instead.
+ */
+declare function glyphPath(shape: GlyphShape, size: number): string;
+interface GlyphProps {
+  shape: GlyphShape;
+  x: number;
+  y: number;
+  size: number;
+  color: string;
+  opacity?: number;
+  stroke?: string;
+  strokeWidth?: number;
+}
+/** A single point glyph, centered at (x, y). Decorative — the value lives in the a11y tree. */
+declare function Glyph({
+  shape,
+  x,
+  y,
+  size,
+  color,
+  opacity,
+  stroke,
+  strokeWidth
+}: GlyphProps): ReactNode;
+/** Greedily wrap `text` to lines no wider than `maxWidth` (px) at the given font size. */
+declare function wrapText(text: string, maxWidth: number, fontSize: number): string[];
+interface TextProps {
+  x: number;
+  y: number;
+  children: string;
+  /** Max line width in px; when set, the text wraps into `<tspan>` lines. */
+  width?: number;
+  fontSize?: number;
+  anchor?: 'start' | 'middle' | 'end';
+  fill?: string;
+  lineHeight?: number;
+  className?: string;
+}
+/**
+ * An SVG text primitive that wraps to a max width (canvas-measured, with a char
+ * fallback). The `@visx/text` analogue — used by `Axis` for long category labels
+ * and available to custom charts.
+ */
+declare function Text({
+  x,
+  y,
+  children,
+  width,
+  fontSize,
+  anchor,
+  fill,
+  lineHeight,
+  className
+}: TextProps): ReactNode;
+interface BrushProps {
+  /** Total number of selectable items (data length). */
+  count: number;
+  /** Track height in px. */
+  height?: number;
+  /** [startIndex, endIndex] window, inclusive. The brush mutates this signal. */
+  window: Signal<[number, number]>;
+  /** Accessible label for the range group. */
+  label?: string;
+}
+/**
+ * A keyboard-operable range selector. Two handles bound to a `[start, end]` window
+ * signal; pointer-drag or Arrow/Home/End move them. Resolution-independent (0–100
+ * viewBox stretched to the container width) so it tracks the chart's responsive size.
+ */
+declare function Brush({
+  count,
+  height,
+  window: win,
+  label
+}: BrushProps): import("react").JSX.Element;
+interface DataZoomProps {
+  /** Total number of selectable items (data length). */
+  count: number;
+  /** Track height in px. */
+  height?: number;
+  /** [startIndex, endIndex] window, inclusive. The control mutates this signal. */
+  window: Signal<[number, number]>;
+  /** Accessible label for the range group. */
+  label?: string;
+}
+/**
+ * A dataZoom slider — the v52 Brush plus a draggable **body** that pans the whole
+ * window (drag it, or Arrow it with the body focused) while the two handles resize
+ * it. Bound to a `[start, end]` window signal; resolution-independent (0–100 viewBox).
+ */
+declare function DataZoom({
+  count,
+  height,
+  window: win,
+  label
+}: DataZoomProps): import("react").JSX.Element;
+type VisualChannel = 'color' | 'size' | 'both';
+type VisualMode = 'continuous' | 'piecewise';
+interface VisualMapOptions {
+  /** Domain minimum (value mapped to ramp t=0). */
+  min: number;
+  /** Domain maximum (value mapped to ramp t=1). */
+  max: number;
+  /** `continuous` ramp (default) or `piecewise` buckets. */
+  mode?: VisualMode;
+  /** Which visual channel(s) the value drives. Default `color`. */
+  channel?: VisualChannel;
+  /** Ramp family — CVD-safe `sequential` (default) or `diverging`. */
+  ramp?: RampKind;
+  /** Bucket count for `piecewise` (default 5). */
+  pieces?: number;
+  /** [min, max] mark radius in px for the `size` channel (default [3, 14]). */
+  sizeRange?: [number, number];
+}
+interface VisualResult {
+  color?: string;
+  size?: number;
+}
+/** Piecewise bucket index (0…pieces-1) a value falls into. */
+declare function pieceIndex(value: number, o: VisualMapOptions): number;
+/** Resolve a value to its `{ color?, size? }` on the configured channel(s). */
+declare function mapVisual(value: number, o: VisualMapOptions): VisualResult;
+/**
+ * Whether a value passes the legend filter — within the continuous `range`, or in a
+ * non-hidden piecewise bucket. Charts dim/hide marks for which this is false.
+ */
+declare function visualVisible(value: number, o: VisualMapOptions, range: [number, number] | null, hidden: ReadonlySet<number> | null): boolean;
+interface VisualMapProps {
+  options: VisualMapOptions;
+  /** Continuous filter window in value space (mutated by the thumbs). */
+  range?: Signal<[number, number]>;
+  /** Piecewise hidden bucket indices (toggled by the swatches). */
+  hidden?: Signal<Set<number>>;
+  /** Accessible label for the legend group. */
+  label?: string;
+  /** Value formatter for tick/swatch labels. */
+  format?: (v: number) => string;
+}
+/**
+ * The visualMap legend. `continuous` → a CVD-safe gradient bar with two draggable,
+ * keyboard-operable thumbs that filter the visible range. `piecewise` → a row of
+ * clickable swatches that toggle their bucket. Resolution-independent (0–100 viewBox).
+ */
+declare function VisualMap({
+  options,
+  range,
+  hidden,
+  label,
+  format
+}: VisualMapProps): import("react").JSX.Element;
 interface LegendSeries {
   id: string;
   label: string;
@@ -305,17 +1088,23 @@ interface LegendSeries {
 }
 interface LegendProps {
   series: readonly LegendSeries[];
-  hidden: Signal<Set<string>>;
+  hidden: Signal$1<Set<string>>;
 }
 declare function Legend({
   series,
   hidden
 }: LegendProps): import("react").JSX.Element;
+interface DecimateOptions {
+  method?: DecimateMethod;
+  threshold?: number;
+}
 interface LineChartSeries<Datum> {
   id: string;
   label: string;
   data: readonly Datum[];
   color?: string;
+  /** Which y-axis this series is measured against. Default 'left'. */
+  axis?: 'left' | 'right';
 }
 interface LineChartProps<Datum = {
   x: number;
@@ -326,7 +1115,7 @@ interface LineChartProps<Datum = {
   y: (d: Datum) => number;
   title: string;
   description?: string;
-  curve?: 'linear' | 'monotone';
+  curve?: Curve;
   width?: number;
   height?: number;
   xTicks?: number;
@@ -337,12 +1126,55 @@ interface LineChartProps<Datum = {
   className?: string;
   /** Render only the marks — no axes, grid lines, or legend. For micro/inline charts. */
   plain?: boolean;
+  /** Reference lines, shaded bands, and markers drawn over the plot (target/threshold annotations). */
+  annotations?: readonly Annotation[];
+  /** Print each point's value as a label above the mark. */
+  labels?: LabelOptions;
+  /** Bridge `null`/non-finite y gaps instead of breaking the line at them (default: break). */
+  connectNulls?: boolean;
+  /** Fired when a point is clicked or activated (Enter/Space) — for drill-down. */
+  onSelect?: (point: ChartPoint) => void;
+  /** Show a keyboard-operable Brush below the plot to subset (zoom) the series to a window. */
+  brush?: boolean;
+  /** Show a DataZoom slider below the plot — a Brush whose body also pans the window. */
+  dataZoom?: boolean;
+  /** Enable in-plot wheel/drag/keyboard zoom-pan (`+`/`-`/`0`) over the series index window. */
+  zoom?: boolean;
+  /** Connect this chart to others sharing the same id — they mirror zoom window + hovered x. */
+  syncId?: string;
+  /** Tooltip trigger: `item` (default, nearest point) or `axis` (crosshair + all series at the hovered x). */
+  tooltipMode?: 'item' | 'axis';
+  /** Add a right-hand y-axis for series with `axis: 'right'` (e.g. bandwidth vs requests/sec). */
+  secondAxis?: {
+    label?: string;
+    format?: (value: number) => string;
+  };
+  /** Downsample dense series before drawing (LTTB/min-max). The fallback table keeps full data. */
+  decimate?: boolean | DecimateOptions;
+  /** Render a toolbox (PNG/SVG export, data-view toggle, restore). `true` enables all tools. */
+  toolbox?: boolean | ToolboxOptions;
+  /** Tune the reduced-motion-gated transitions: `false` disables; an object sets duration/easing/properties. */
+  transition?: boolean | {
+    duration?: number;
+    easing?: string;
+    properties?: string[];
+  };
+  /** Render custom SVG behind the marks (watermark/region) — a lightweight extension seam. */
+  onBeforeDraw?: (ctx: {
+    width: number;
+    height: number;
+  }) => ReactNode;
+  /** Render custom SVG over the marks (overlay/extra series) — a lightweight extension seam. */
+  onAfterDraw?: (ctx: {
+    width: number;
+    height: number;
+  }) => ReactNode;
 }
 declare function LineChart<Datum = {
   x: number;
   y: number;
 }>({
-  series,
+  series: rawSeries,
   x,
   y,
   title,
@@ -356,13 +1188,34 @@ declare function LineChart<Datum = {
   tooltip,
   formatTooltip,
   className,
-  plain
+  plain,
+  annotations,
+  labels,
+  connectNulls,
+  onSelect,
+  brush,
+  dataZoom,
+  zoom,
+  syncId,
+  tooltipMode,
+  secondAxis,
+  decimate,
+  toolbox,
+  transition,
+  onBeforeDraw,
+  onAfterDraw
 }: LineChartProps<Datum>): import("react").JSX.Element;
+interface AreaDecimateOptions {
+  method?: DecimateMethod;
+  threshold?: number;
+}
 interface AreaChartSeries<Datum> {
   id: string;
   label: string;
   data: readonly Datum[];
   color?: string;
+  /** Which y-axis this series is measured against (ignored when `stacked`). Default 'left'. */
+  axis?: 'left' | 'right';
 }
 interface AreaChartProps<Datum = {
   x: number;
@@ -374,7 +1227,11 @@ interface AreaChartProps<Datum = {
   title: string;
   description?: string;
   stacked?: boolean;
-  curve?: 'linear' | 'monotone';
+  curve?: Curve;
+  /** Area fill style: solid (default), a top→bottom gradient, or a pattern. */
+  fill?: FillKind;
+  /** Pattern motif when `fill="pattern"`. */
+  patternKind?: PatternKind;
   width?: number;
   height?: number;
   xTicks?: number;
@@ -384,18 +1241,45 @@ interface AreaChartProps<Datum = {
   className?: string;
   /** Render only the marks — no axes, grid lines, or legend. For micro/inline charts. */
   plain?: boolean;
+  /** Reference lines, shaded bands, and markers drawn over the plot (target/threshold annotations). */
+  annotations?: readonly Annotation[];
+  /** Print each point's value as a label above the top edge. */
+  labels?: LabelOptions;
+  /** Fired when a point is clicked or activated (Enter/Space) — for drill-down. */
+  onSelect?: (point: ChartPoint) => void;
+  /** Show a keyboard-operable Brush below the plot to subset the series to a window. */
+  brush?: boolean;
+  /** Show a DataZoom slider below the plot — a Brush whose body also pans the window. */
+  dataZoom?: boolean;
+  /** Enable in-plot wheel/drag/keyboard zoom-pan (`+`/`-`/`0`) over the series index window. */
+  zoom?: boolean;
+  /** Connect this chart to others sharing the same id — they mirror zoom window + hovered x. */
+  syncId?: string;
+  /** Tooltip trigger: `item` (default, nearest point) or `axis` (crosshair + all series at the hovered x). */
+  tooltipMode?: 'item' | 'axis';
+  /** Add a right-hand y-axis for series with `axis: 'right'` (non-stacked only). */
+  secondAxis?: {
+    label?: string;
+    format?: (value: number) => string;
+  };
+  /** Downsample dense (non-stacked) series before drawing (LTTB/min-max). The fallback table keeps full data. */
+  decimate?: boolean | AreaDecimateOptions;
+  /** Render a toolbox (PNG/SVG export, data-view toggle, restore). `true` enables all tools. */
+  toolbox?: boolean | ToolboxOptions;
 }
 declare function AreaChart<Datum = {
   x: number;
   y: number;
 }>({
-  series,
+  series: rawSeries,
   x,
   y,
   title,
   description,
   stacked,
   curve,
+  fill,
+  patternKind,
   width: fixedWidth,
   height,
   xTicks,
@@ -403,7 +1287,18 @@ declare function AreaChart<Datum = {
   legend,
   tooltip,
   className,
-  plain
+  plain,
+  annotations,
+  labels,
+  onSelect,
+  brush,
+  dataZoom,
+  zoom,
+  syncId,
+  tooltipMode,
+  secondAxis,
+  decimate,
+  toolbox
 }: AreaChartProps<Datum>): import("react").JSX.Element;
 interface PieChartDatum {
   id: string;
@@ -439,6 +1334,10 @@ interface PieChartProps {
   className?: string;
   /** Render only the marks — no legend. For micro/inline charts. */
   plain?: boolean;
+  /** Label each slice. Defaults to its percentage; pass `{ format }` to show the value instead. */
+  labels?: LabelOptions;
+  /** Fired when a point is clicked or activated (Enter/Space) — for drill-down. */
+  onSelect?: (point: ChartPoint) => void;
 }
 declare function PieChart({
   data,
@@ -457,7 +1356,9 @@ declare function PieChart({
   tooltipFormat,
   legend,
   className,
-  plain
+  plain,
+  labels,
+  onSelect
 }: PieChartProps): import("react").JSX.Element;
 interface ScatterDatum {
   x: number;
@@ -484,6 +1385,18 @@ interface ScatterChartProps {
   className?: string;
   /** Render only the marks — no axes, grid lines, or legend. For micro/inline charts. */
   plain?: boolean;
+  /** Reference lines, shaded bands, and markers drawn over the plot (target/threshold annotations). */
+  annotations?: readonly Annotation[];
+  /** Fired when a point is clicked or activated (Enter/Space) — for drill-down. */
+  onSelect?: (point: ChartPoint) => void;
+  /** Point glyph shape — a fixed shape, or a function to encode a category by shape. Defaults to a circle. */
+  glyph?: GlyphShape | ((d: ScatterDatum, seriesId: string) => GlyphShape);
+  /** Renderer: `svg` (default), `canvas` (force), or `auto` (canvas past ~2000 points). */
+  renderer?: 'svg' | 'canvas' | 'auto';
+  /** Map each point's y → CVD-safe colour and/or size via a legend that filters the range. */
+  visualMap?: VisualMapOptions;
+  /** Render a toolbox (PNG/SVG export, data-view toggle, restore). `true` enables all tools. */
+  toolbox?: boolean | ToolboxOptions;
 }
 declare function ScatterChart({
   series,
@@ -497,7 +1410,13 @@ declare function ScatterChart({
   legend,
   tooltip,
   className,
-  plain
+  plain,
+  annotations,
+  onSelect,
+  glyph,
+  renderer,
+  visualMap,
+  toolbox
 }: ScatterChartProps): import("react").JSX.Element;
 interface SparklineProps {
   data: readonly number[];
@@ -623,6 +1542,8 @@ interface BubbleChartProps {
   className?: string;
   /** Render only the marks — no axes or grid lines. For micro/inline charts. */
   plain?: boolean;
+  /** Point glyph shape — a fixed shape, or a function to encode a category by shape. Defaults to a circle. */
+  glyph?: GlyphShape | ((d: BubbleDatum, seriesName: string) => GlyphShape);
 }
 declare function BubbleChart({
   series,
@@ -632,7 +1553,8 @@ declare function BubbleChart({
   height,
   tooltip,
   className,
-  plain
+  plain,
+  glyph
 }: BubbleChartProps): import("react").JSX.Element;
 interface ComboChartBar {
   label: string;
@@ -654,6 +1576,8 @@ interface ComboChartProps {
   className?: string;
   /** Render only the marks — no axes or grid lines. For micro/inline charts. */
   plain?: boolean;
+  /** Reference lines, bands, and markers. `y` maps to the bar value axis. */
+  annotations?: readonly Annotation[];
 }
 declare function ComboChart({
   bars,
@@ -665,7 +1589,8 @@ declare function ComboChart({
   height,
   tooltip,
   className,
-  plain
+  plain,
+  annotations
 }: ComboChartProps): import("react").JSX.Element;
 interface HeatmapDatum {
   x: string;
@@ -681,6 +1606,10 @@ interface HeatmapProps {
   className?: string;
   /** Render only the marks — no axes. For micro/inline charts. */
   plain?: boolean;
+  /** Map cell value → CVD-safe colour via a continuous/piecewise legend that filters the range. */
+  visualMap?: VisualMapOptions;
+  /** Render a toolbox (PNG/SVG export, data-view toggle, restore). `true` enables all tools. */
+  toolbox?: boolean | ToolboxOptions;
 }
 declare function Heatmap({
   data,
@@ -689,7 +1618,9 @@ declare function Heatmap({
   width: fixedWidth,
   height,
   className,
-  plain
+  plain,
+  visualMap,
+  toolbox
 }: HeatmapProps): import("react").JSX.Element;
 interface TreemapDatum {
   id: string;
@@ -765,4 +1696,342 @@ declare function Bullet({
   height,
   className
 }: BulletProps): import("react").JSX.Element;
-export { AreaChart, AreaChartProps, AreaChartSeries, Axis, AxisProps, BandScale, BarChart, BarChartProps, BarChartSeries, Bin, BoxStats, Boxplot, BoxplotProps, BoxplotSeries, BubbleChart, BubbleChartProps, BubbleDatum, BubbleSeries, Bullet, BulletProps, ChartFrame, ChartFrameProps, ChartSize, ComboChart, ComboChartBar, ComboChartPoint, ComboChartProps, DEFAULT_MARGINS, GridLines, GridLinesProps, Heatmap, HeatmapDatum, HeatmapProps, Histogram, HistogramProps, Kpi, KpiProps, Legend, LegendProps, LegendSeries, LineChart, LineChartProps, LineChartSeries, LinearScale, LogScale, Meter, MeterProps, MeterThresholds, PLAIN_MARGINS, PieChart, PieChartDatum, PieChartProps, Point, Radar, RadarProps, RadarSeries, ScatterChart, ScatterChartProps, ScatterChartSeries, ScatterDatum, Sparkline, SparklineProps, StackedRow, StackedSegment, TimeScale, Treemap, TreemapDatum, TreemapNode, TreemapProps, TreemapRect, arcPath, areaPath, bandScale, binValues, boxStats, extent, linePath, linearScale, logScale, nearestIndex, niceTicks, sqrtScale, squarify, stackSeries, timeScale, toStackedSeries, useChartSize };
+interface RadialBarDatum {
+  id: string;
+  label: string;
+  value: number;
+  /** CSS color overriding the positional palette for this ring. */
+  color?: string;
+}
+interface RadialBarProps {
+  data: readonly RadialBarDatum[];
+  title: string;
+  description?: string;
+  /** Square shorthand: sets width === height. Explicit width/height win. */
+  size?: number;
+  width?: number;
+  height?: number;
+  /** Domain top — the value a full sweep represents. Defaults to the largest datum. */
+  max?: number;
+  /** Sweep angle in degrees (default 270 — a gauge arc). */
+  sweep?: number;
+  /** Center value text rendered in the hole. */
+  centerValue?: string;
+  /** Center label text rendered below the value. */
+  centerLabel?: string;
+  /** Arbitrary content rendered in the hole; takes precedence over centerValue/centerLabel. */
+  centerSlot?: ReactNode;
+  tooltip?: boolean;
+  legend?: boolean;
+  className?: string;
+  /** Render only the marks — no legend. For micro/inline charts. */
+  plain?: boolean;
+}
+/**
+ * Concentric radial bars — a circular gauge family. Each datum is a ring whose
+ * filled sweep is proportional to its value over `max`. Reuses the pie arc math.
+ */
+declare function RadialBar({
+  data,
+  title,
+  description,
+  size,
+  width: fixedWidth,
+  height,
+  max,
+  sweep,
+  centerValue,
+  centerLabel,
+  centerSlot,
+  tooltip,
+  legend,
+  className,
+  plain
+}: RadialBarProps): import("react").JSX.Element;
+interface FunnelStage {
+  id: string;
+  label: string;
+  value: number;
+  /** CSS color overriding the positional palette for this stage. */
+  color?: string;
+}
+interface FunnelProps {
+  data: readonly FunnelStage[];
+  title: string;
+  description?: string;
+  width?: number;
+  height?: number;
+  /** Show per-stage conversion: value + % of the first stage. */
+  showConversion?: boolean;
+  tooltip?: boolean;
+  className?: string;
+  /** Render only the marks — no labels. For micro/inline charts. */
+  plain?: boolean;
+}
+/**
+ * A vertical funnel — each stage is a trapezoid whose top width is its value and
+ * bottom width is the next stage's value, so the silhouette narrows down the
+ * stages. Useful for conversion / drop-off flows.
+ */
+declare function Funnel({
+  data,
+  title,
+  description,
+  width: fixedWidth,
+  height,
+  showConversion,
+  tooltip,
+  className,
+  plain
+}: FunnelProps): import("react").JSX.Element;
+interface StreamSeries {
+  id: string;
+  label: string;
+  /** One value per category, aligned with `categories`. */
+  values: number[];
+  color?: string;
+}
+interface StreamProps {
+  series: readonly StreamSeries[];
+  /** X-axis category labels, aligned with each series' `values`. */
+  categories: readonly (string | number)[];
+  title: string;
+  description?: string;
+  /** `silhouette` (centered streamgraph, default) or `zero` (baseline stack). */
+  offset?: StreamOffset;
+  curve?: Curve;
+  width?: number;
+  height?: number;
+  legend?: boolean;
+  tooltip?: boolean;
+  className?: string;
+  plain?: boolean;
+}
+/** A streamgraph — stacked areas on a flowing (centered) baseline. */
+declare function Stream({
+  series,
+  categories,
+  title,
+  description,
+  offset,
+  curve,
+  width: fixedWidth,
+  height,
+  legend,
+  tooltip,
+  className,
+  plain
+}: StreamProps): import("react").JSX.Element;
+interface SunburstProps {
+  /** Root of the hierarchy. Leaves carry `value`; parents sum their children. */
+  data: HierNode;
+  title: string;
+  description?: string;
+  size?: number;
+  width?: number;
+  height?: number;
+  tooltip?: boolean;
+  className?: string;
+  plain?: boolean;
+}
+/** A sunburst — a radial partition of a tree; each node is an annular segment. */
+declare function Sunburst({
+  data,
+  title,
+  description,
+  size,
+  width: fixedWidth,
+  height,
+  tooltip,
+  className,
+  plain
+}: SunburstProps): import("react").JSX.Element;
+interface SankeyProps {
+  nodes: readonly SankeyNode[];
+  links: readonly SankeyLink[];
+  title: string;
+  description?: string;
+  width?: number;
+  height?: number;
+  tooltip?: boolean;
+  className?: string;
+  plain?: boolean;
+}
+/** A Sankey flow diagram — ranked nodes with throughput-sized link ribbons. */
+declare function Sankey({
+  nodes,
+  links,
+  title,
+  description,
+  width: fixedWidth,
+  height,
+  tooltip,
+  className,
+  plain
+}: SankeyProps): import("react").JSX.Element;
+interface CalendarDatum {
+  day: string | Date;
+  value: number;
+}
+interface CalendarProps {
+  data: readonly CalendarDatum[];
+  title: string;
+  description?: string;
+  /** Range start/end (ISO string or Date). Defaults to the data's min/max day. */
+  from?: string | Date;
+  to?: string | Date;
+  width?: number;
+  height?: number;
+  tooltip?: boolean;
+  className?: string;
+  plain?: boolean;
+  /** Map day value → CVD-safe colour via a continuous/piecewise legend that filters the range. */
+  visualMap?: VisualMapOptions;
+}
+/** A calendar heatmap — a week-column grid of day cells colored by value. */
+declare function Calendar({
+  data,
+  title,
+  description,
+  from,
+  to,
+  width: fixedWidth,
+  height,
+  tooltip,
+  className,
+  plain,
+  visualMap
+}: CalendarProps): import("react").JSX.Element;
+interface CandlestickDatum {
+  /** Period label (date string or index). */
+  t: string;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  /** Optional traded volume for the secondary axis. */
+  volume?: number;
+}
+interface CandlestickProps {
+  data: readonly CandlestickDatum[];
+  title: string;
+  description?: string;
+  width?: number;
+  height?: number;
+  yTicks?: number;
+  /** Colour for up candles (close ≥ open). */
+  upColor?: string;
+  /** Colour for down candles (close < open). */
+  downColor?: string;
+  /** Render volume bars beneath the candles. */
+  volume?: boolean;
+  tooltip?: boolean;
+  className?: string;
+  plain?: boolean;
+  /** Reference lines, shaded bands, and markers over the plot (e.g. a last-price rule). */
+  annotations?: readonly Annotation[];
+  /** Show a keyboard-operable Brush below the plot to subset (zoom) the candles to a window. */
+  brush?: boolean;
+  /** Show a DataZoom slider below the plot — a Brush whose body also pans the window. */
+  dataZoom?: boolean;
+  /** Enable in-plot wheel/drag/keyboard zoom-pan (`+`/`-`/`0`) over the candle index window. */
+  zoom?: boolean;
+  /** Connect this chart to others sharing the same id — they mirror the zoom window. */
+  syncId?: string;
+  /** Tooltip trigger: `item` (default, nearest candle) or `axis` (crosshair + OHLC at hovered x). */
+  tooltipMode?: 'item' | 'axis';
+}
+declare function Candlestick({
+  data: rawData,
+  title,
+  description,
+  width: fixedWidth,
+  height,
+  yTicks,
+  upColor,
+  downColor,
+  volume,
+  tooltip,
+  className,
+  plain,
+  annotations,
+  brush,
+  dataZoom,
+  zoom,
+  syncId,
+  tooltipMode
+}: CandlestickProps): import("react").JSX.Element;
+interface PolarDatum {
+  label: string;
+  value: number;
+  color?: string;
+}
+interface PolarProps {
+  data: readonly PolarDatum[];
+  title: string;
+  description?: string;
+  /** Plot bars (a rose), or a polar line / filled area. */
+  mode?: 'bar' | 'line' | 'area';
+  width?: number;
+  height?: number;
+  /** Radial ring count. */
+  rings?: number;
+  /** Domain top (full radius). Defaults to the largest value. */
+  max?: number;
+  tooltip?: boolean;
+  className?: string;
+  plain?: boolean;
+}
+declare function Polar({
+  data,
+  title,
+  description,
+  mode,
+  width: fixedWidth,
+  height,
+  rings,
+  max,
+  tooltip,
+  className,
+  plain
+}: PolarProps): import("react").JSX.Element;
+interface GaugeThreshold {
+  /** Upper bound of this coloured zone (in value units). */
+  upTo: number;
+  color: string;
+}
+interface GaugeProps {
+  value: number;
+  min?: number;
+  max?: number;
+  /** Coloured zones from `min` upward; the last should reach `max`. */
+  thresholds?: readonly GaugeThreshold[];
+  /** Unit suffix shown after the centre value. */
+  unit?: string;
+  /** Total sweep in degrees (default 270 — a speedometer arc). */
+  sweep?: number;
+  /** Major tick count (labels at min…max). */
+  ticks?: number;
+  title: string;
+  description?: string;
+  width?: number;
+  height?: number;
+  className?: string;
+  plain?: boolean;
+}
+declare function Gauge({
+  value,
+  min,
+  max,
+  thresholds,
+  unit,
+  sweep,
+  ticks,
+  title,
+  description,
+  width: fixedWidth,
+  height,
+  className,
+  plain
+}: GaugeProps): import("react").JSX.Element;
+export { AggOp, AggregateSpec, AngleBand, Annotation, AnnotationContext, AnnotationScale, AreaChart, AreaChartProps, AreaChartSeries, AreaDecimateOptions, Axis, AxisProps, BandScale, BarChart, BarChartProps, BarChartSeries, Bin, BoundStream, BoxStats, Boxplot, BoxplotProps, BoxplotSeries, Brush, BrushProps, BubbleChart, BubbleChartProps, BubbleDatum, BubbleSeries, Bullet, BulletProps, Calendar, CalendarDatum, CalendarProps, Candlestick, CandlestickDatum, CandlestickProps, CanvasLayer, CanvasLayerProps, CanvasPaint, CanvasSize, CategoryDatum, CategoryMapping, ChartDefs, ChartDefsProps, ChartFrame, ChartFrameProps, ChartSize, ComboChart, ComboChartBar, ComboChartPoint, ComboChartProps, Curve, DEFAULT_MARGINS, DataLabel, DataLabelProps, DataZoom, DataZoomProps, DecimateMethod, DecimateOptions, DefSeries, EncodeMapping, EncodedResult, EncodedSeries, FillKind, Funnel, FunnelProps, FunnelStage, Gauge, GaugeProps, GaugeThreshold, Glyph, GlyphProps, GlyphShape, GridLines, GridLinesProps, Heatmap, HeatmapDatum, HeatmapProps, HierNode, Histogram, HistogramBin, HistogramProps, Kpi, KpiProps, LabelOptions, LaidLink, LaidNode, Legend, LegendProps, LegendSeries, LineChart, LineChartProps, LineChartSeries, LinearScale, LogScale, Meter, MeterProps, MeterThresholds, PLAIN_MARGINS, PartitionedNode, PatternKind, PieChart, PieChartDatum, PieChartProps, Point, Polar, PolarDatum, PolarProps, Pt, Radar, RadarProps, RadarSeries, RadialBar, RadialBarDatum, RadialBarProps, RampKind, Rect, RegressionResult, RegressionType, ResolvedLabelOptions, Row, Sankey, SankeyLayout, SankeyLink, SankeyNode, SankeyOptions, SankeyProps, ScatterChart, ScatterChartProps, ScatterChartSeries, ScatterDatum, Sparkline, SparklineProps, StackedRow, StackedSegment, Stream, StreamDecimate, StreamOffset, StreamProps, StreamSeries, StreamSeriesOptions, StreamSource, Sunburst, SunburstProps, SyncGroup, Text, TextProps, TimeScale, Toolbox, ToolboxOptions, ToolboxProps, Treemap, TreemapDatum, TreemapNode, TreemapProps, TreemapRect, Vec, VisualChannel, VisualMap, VisualMapOptions, VisualMapProps, VisualMode, VisualResult, ZoomConfig, _syncGroupCount, aggregate, angleBand, annotationSummary, arcPath, areaPath, bandScale, bin, binValues, bindStream, boxStats, cellPath, decimate$1 as decimate, divergingRamp, download, encode, encodeCategory, extent, fillFor, filter, getSyncGroup, glyphPath, gradientId, isZoomed, linePath, linearScale, linkPath, logScale, lttb, mapVisual, maxDepth, minmax, nearestIndex, niceTicks, panWindow, partition, patternId, pieceIndex, polarPoint, radiusScale, rampLightness, rampOf, rampStops, regression, releaseSyncGroup, renderAnnotation, renderAnnotations, resolveColor, resolveLabels, sankeyLayout, sequentialRamp, serializeSvg, sort, splitDefined, sqrtScale, squarify, stackSeries, streamExtent, streamLayout, sumValue, svgToPngBlob, timeScale, toStackedSeries, useChartSize, useStreamSeries, visualVisible, voronoiCells, voronoiFind, wrapText, zoomWindow };