twico-ui 1.9.0 → 1.10.0

package/dist/index.d.cts

@@ -545,6 +545,22 @@ declare function Carousel(props: CarouselProps): React.JSX.Element;
  */
 type ChartDatum<K extends string = "value"> = { label: React.ReactNode } & { [P in K]: number };
 
+/** Payload passed to `onDataClick` when a bar/point (or category, in zoom mode) is clicked. */
+interface ChartClickPayload<K extends string = string> {
+  /** The clicked datum's `label`. */
+  label: React.ReactNode;
+  /** The series key clicked, or `null` when a whole category was clicked (zoom overlay). */
+  series: K | null;
+  /** Index of `series` in the `series` prop, or `-1` for a category click. */
+  seriesIndex: number;
+  /** The clicked value, or `undefined` for a category click. */
+  value: number | undefined;
+  /** Index of the datum in the full (un-zoomed) `data` array. */
+  index: number;
+  /** The full data row that was clicked. */
+  row: ChartDatum<K>;
+}
+
 /**
  * Cartesian chart — vertical/horizontal bars (grouped or stacked), line, and area
  * (straight / smooth / stepped), single or multi-series, with grid, axes, tooltips,
@@ -554,7 +570,7 @@ type ChartDatum<K extends string = "value"> = { label: React.ReactNode } & { [P
  * scatter/bubble, radar, heatmap, gauge, funnel, treemap, candlestick, boxplot and
  * range charts use the dedicated sibling components.
  *
- * @startingPoint section="Data display" subtitle="Bar / line / area chart (no deps)" viewport="700x280"
+ * @startingPoint section="Charts" subtitle="Bar / line / area chart (no deps)" viewport="700x280"
  */
 interface ChartProps<K extends string = "value"> extends React.HTMLAttributes<HTMLDivElement> {
   /** Chart type. `"column"` is an alias of `"bar"` (vertical bars). @default "bar" */
@@ -579,6 +595,12 @@ interface ChartProps<K extends string = "value"> extends React.HTMLAttributes<HT
   showValues?: boolean;
   /** Play the entrance animation (bars grow, lines draw); respects `prefers-reduced-motion`. @default true */
   animate?: boolean;
+  /** Show a vertical crosshair line at the hovered category (line/area/vertical bars). @default true */
+  crosshair?: boolean;
+  /** Enable drag-to-zoom (+ shift-drag pan, wheel zoom, and a reset button) over the x-axis. @default false */
+  zoomable?: boolean;
+  /** Fires when a bar/point is clicked (or a category, in zoom mode) with the datum + metadata. */
+  onDataClick?: (payload: ChartClickPayload<NoInfer<K>>) => void;
   /** Grid lines. @default true */
   showGrid?: boolean;
   /** Axis labels. @default true */
@@ -609,13 +631,25 @@ interface PieChartDatum {
   color?: string;
 }
 
+/** Payload passed to `onDataClick` when a pie/donut slice is clicked. */
+interface PieChartClickPayload {
+  /** The clicked slice's `label`. */
+  label: React.ReactNode;
+  /** The clicked slice's numeric value (negative inputs are clamped to `0`). */
+  value: number;
+  /** Index of the slice in the `data` array. */
+  index: number;
+  /** The slice's share of the total, as a percentage rounded to one decimal. */
+  percent: number;
+}
+
 /**
  * Pie / donut chart — proportional slices of a whole from a single value series,
  * with per-slice tooltips, an optional legend, optional percentage labels, and a
  * donut center label. Dependency-free inline SVG. For bar/line/area use `Chart`;
  * for other shapes use the dedicated sibling components (gauge, radar, funnel, …).
  *
- * @startingPoint section="Data display" subtitle="Pie / donut chart (no deps)" viewport="700x280"
+ * @startingPoint section="Charts" subtitle="Pie / donut chart (no deps)" viewport="700x280"
  */
 interface PieChartProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "color"> {
   /** Slices to plot; each is a `{ label, value, color? }`. Only positive values contribute a slice. */
@@ -640,6 +674,8 @@ interface PieChartProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "colo
   height?: number;
   /** Per-slice colors (any CSS color), cycled when shorter than `data`. Defaults to the built-in token palette. */
   colors?: string[];
+  /** Fires when a slice is clicked with the slice's label, value, index, and percent share; clicking a slice also toggles a selection that pops the slice outward and dims the rest. */
+  onDataClick?: (payload: PieChartClickPayload) => void;
   /** Accessible name for the `<svg role="img">`. Per-slice values live in the hidden data table, not this label. Defaults to `"pie chart"`/`"donut chart"`; also accepts `aria-label`. */
   ariaLabel?: string;
   /** Render a visually-hidden data table as an accessible text alternative (WCAG 1.1.1). @default true */
@@ -657,7 +693,7 @@ type DonutChartDatum = PieChartDatum;
  * Donut chart — a {@link PieChart} preset rendered as a ring (hollow center).
  * Accepts every PieChart prop; `donut` defaults to `true`.
  *
- * @startingPoint section="Data display" subtitle="Donut chart (no deps)" viewport="700x280"
+ * @startingPoint section="Charts" subtitle="Donut chart (no deps)" viewport="700x280"
  */
 interface DonutChartProps extends PieChartProps {}
 
@@ -673,6 +709,16 @@ interface GaugeSeries {
   color?: string;
 }
 
+/** Payload passed to `onDataClick` when a gauge value arc (ring) is clicked. */
+interface GaugeClickPayload {
+  /** The clicked ring's value. */
+  value: number;
+  /** The clicked ring's label (the `label` prop for a single gauge, or the `series` entry's label). */
+  label?: React.ReactNode;
+  /** Index of the clicked ring (`0` for a single gauge; the `series` index for a multi-ring gauge). */
+  index: number;
+}
+
 /**
  * Radial gauge / radial-bar chart — renders a single `value` as a thick arc that
  * sweeps between `startAngle` and `endAngle`, with the value + an optional caption
@@ -680,7 +726,7 @@ interface GaugeSeries {
  * Dependency-free inline SVG; every color/size is a design token so dark mode is
  * automatic. For bar/line/area use `Chart`; for slices use `PieChart`/`DonutChart`.
  *
- * @startingPoint section="Data display" subtitle="Radial gauge / radial-bar (no deps)" viewport="700x280"
+ * @startingPoint section="Charts" subtitle="Radial gauge / radial-bar (no deps)" viewport="700x280"
  */
 interface GaugeProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "color"> {
   /** The value to display, mapped from `min`..`max` onto the arc sweep. @default 0 */
@@ -711,6 +757,8 @@ interface GaugeProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "color">
   series?: GaugeSeries[];
   /** Show the legend for a multi-ring (`series`) gauge. @default true */
   showLegend?: boolean;
+  /** Fires when a value arc (ring) is clicked, with the ring's value, label, and index; the clicked ring also gains a selection outline. */
+  onDataClick?: (payload: GaugeClickPayload) => void;
   /** Accessible name for the `<svg role="img">`; defaults to a value summary. Also accepts `aria-label`. */
   ariaLabel?: string;
   /** Render a visually-hidden data table as an accessible text alternative (WCAG 1.1.1). @default true */
@@ -727,6 +775,16 @@ declare function Gauge(props: GaugeProps): React.JSX.Element;
  */
 type SparklineDatum = number | { value: number; label?: React.ReactNode };
 
+/** Payload passed to `onDataClick` when a point/bar is clicked. */
+interface SparklineClickPayload {
+  /** The clicked point's numeric value. */
+  value: number;
+  /** Index of the clicked point in the `data` array. */
+  index: number;
+  /** The point's `label` (falls back to its 1-based index). */
+  label: React.ReactNode;
+}
+
 /**
  * Sparkline — a minimal, word-sized trend chart (line, area, or bars) with no
  * axes, grid, ticks, or legend, meant to sit inline beside text or inside a
@@ -734,7 +792,7 @@ type SparklineDatum = number | { value: number; label?: React.ReactNode };
  * vertical space, with an optional emphasised trailing dot. For a full chart
  * with axes, tooltips, and a legend use the `Chart` component.
  *
- * @startingPoint section="Data display" subtitle="Tiny inline trend line (no deps)" viewport="700x280"
+ * @startingPoint section="Charts" subtitle="Tiny inline trend line (no deps)" viewport="700x280"
  */
 interface SparklineProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "color"> {
   /** Data points: bare numbers, or `{ value, label }` objects. */
@@ -761,6 +819,8 @@ interface SparklineProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "col
   max?: number;
   /** Value formatter for tooltips + the hidden data table. @default toLocaleString */
   valueFormat?: (value: number) => string;
+  /** Fires when a point/bar is clicked with its value, index, and label; the clicked mark also toggles a selection outline. */
+  onDataClick?: (payload: SparklineClickPayload) => void;
   /** Accessible name for the `<svg role="img">`; defaults to a spoken summary (point count + first/last/min/max, or +latest when a table is present). Also accepts `aria-label`. */
   ariaLabel?: string;
   /** Render a visually-hidden data table as a text alternative (WCAG 1.1.1); off by default since the summarizing aria-label usually suffices for a sparkline. @default false */
@@ -793,6 +853,24 @@ interface ScatterSeries {
   points: ScatterPoint[];
 }
 
+/** Payload passed to `onDataClick` when a point is clicked. */
+interface ScatterClickPayload {
+  /** The clicked point's x value. */
+  x: number;
+  /** The clicked point's y value. */
+  y: number;
+  /** The clicked point's z (bubble size) value, if any. */
+  z?: number;
+  /** Name of the series the point belongs to (defaults to `"Series N"`). */
+  series: string;
+  /** Index of the point's series in the `series` prop. */
+  seriesIndex: number;
+  /** Index of the point within its series' `points` array. */
+  index: number;
+  /** The original `ScatterPoint` object that was clicked. */
+  point: ScatterPoint;
+}
+
 /**
  * Scatter / bubble chart — plots x/y points across two nice-scaled numeric axes,
  * one or many series, with grid, axis titles, tooltips, an optional legend and a
@@ -801,7 +879,7 @@ interface ScatterSeries {
  * dots stay round. For bars/line/area use `Chart`; for other shapes use the
  * dedicated sibling components.
  *
- * @startingPoint section="Data display" subtitle="Scatter / bubble plot (no deps)" viewport="700x280"
+ * @startingPoint section="Charts" subtitle="Scatter / bubble plot (no deps)" viewport="700x280"
  */
 interface ScatterChartProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "color"> {
   /** The series to plot; each has optional `name`/`color` and a list of `{ x, y, z?, label? }` points. */
@@ -822,6 +900,10 @@ interface ScatterChartProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "
   showGrid?: boolean;
   /** Series legend. Defaults to `true` when there is more than one series. */
   showLegend?: boolean;
+  /** Enable 2-D drag-to-zoom (rectangle-zoom both axes, + shift-drag pan, wheel zoom, and a reset button). @default false */
+  zoomable?: boolean;
+  /** Fires when a point is clicked, with its x/y/z, series metadata, and the original point. */
+  onDataClick?: (payload: ScatterClickPayload) => void;
   /** Formatter for x values in tooltips + the hidden table (defaults to `valueFormat`). */
   xFormat?: (value: number) => string;
   /** Formatter for y values in tooltips + the hidden table (defaults to `valueFormat`). */
@@ -842,7 +924,7 @@ declare function ScatterChart(props: ScatterChartProps): React.JSX.Element;
  * Bubble chart — a {@link ScatterChart} preset that sizes each dot by its point's
  * `z` value. Accepts every ScatterChart prop; `bubble` defaults to `true`.
  *
- * @startingPoint section="Data display" subtitle="Bubble chart (no deps)" viewport="700x280"
+ * @startingPoint section="Charts" subtitle="Bubble chart (no deps)" viewport="700x280"
  */
 interface BubbleChartProps extends ScatterChartProps {}
 
@@ -855,6 +937,18 @@ declare function BubbleChart(props: BubbleChartProps): React.JSX.Element;
  */
 type RadarDatum<K extends string = "value"> = { label: React.ReactNode } & { [P in K]: number };
 
+/** Payload passed to `onDataClick` when a series vertex dot is clicked. */
+interface RadarClickPayload<K extends string = string> {
+  /** The clicked vertex's axis `label`. */
+  label: React.ReactNode;
+  /** The series (polygon) key that was clicked. */
+  series: K;
+  /** The clicked value. */
+  value: number;
+  /** Index of the axis (row) in the `data` array. */
+  index: number;
+}
+
 /**
  * Radar / spider chart — one or more series drawn as closed polygons over a
  * shared set of categorical axes radiating from a center, with concentric grid
@@ -864,7 +958,7 @@ type RadarDatum<K extends string = "value"> = { label: React.ReactNode } & { [P
  * For cartesian bars/lines/areas use `Chart`; for other shapes use the dedicated
  * sibling components.
  *
- * @startingPoint section="Data display" subtitle="Radar / spider chart (no deps)" viewport="700x280"
+ * @startingPoint section="Charts" subtitle="Radar / spider chart (no deps)" viewport="700x280"
  */
 interface RadarChartProps<K extends string = "value"> extends React.HTMLAttributes<HTMLDivElement> {
   /** Data rows — one per **axis**. Each has a `label` + one numeric field per series key. (`K` is inferred from `series`, not from `data`.) */
@@ -887,6 +981,8 @@ interface RadarChartProps<K extends string = "value"> extends React.HTMLAttribut
   valueFormat?: (value: number) => string;
   /** Pixel height; the chart uses a square canvas of this size. @default 300 */
   height?: number;
+  /** Fires when a series vertex dot is clicked, with the axis label, series key, value, and axis index. */
+  onDataClick?: (payload: RadarClickPayload<NoInfer<K>>) => void;
   /** Accessible name for the chart's `<svg role="img">`. Per-point values are exposed via the hidden data table, not this label. Defaults to `"radar chart"`; also accepts `aria-label`. */
   ariaLabel?: string;
   /** Render a visually-hidden data table as an accessible text alternative (WCAG 1.1.1). @default true */
@@ -907,16 +1003,27 @@ interface PolarAreaDatum {
   color?: string;
 }
 
+/** Payload passed to `onDataClick` when a slice is clicked. */
+interface PolarAreaClickPayload {
+  /** The clicked slice's `label`. */
+  label: React.ReactNode;
+  /** The clicked slice's numeric `value`. */
+  value: number;
+  /** Index of the slice in the `data` array. */
+  index: number;
+}
+
 /**
  * Polar-area (Coxcomb / Nightingale rose) chart — equal-angle slices whose
  * *radius* encodes each value, laid over concentric value rings. Radius scales
  * with `√value` so a slice's **area** is proportional to its value (the
  * statistically honest encoding). Dependency-free inline SVG, with per-slice
- * tooltips, an optional legend, and a visually-hidden data table. For plain
+ * tooltips, click + selection (`onDataClick`), a legend whose entries
+ * hover-focus their slice, and a visually-hidden data table. For plain
  * proportional wedges use `PieChart` / `DonutChart`; for a spoked multi-axis
  * shape use `RadarChart`.
  *
- * @startingPoint section="Data display" subtitle="Polar-area / rose chart (no deps)" viewport="700x280"
+ * @startingPoint section="Charts" subtitle="Polar-area / rose chart (no deps)" viewport="700x280"
  */
 interface PolarAreaChartProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Data points — one equal-angle slice each, in order clockwise from `startAngle`. */
@@ -935,6 +1042,8 @@ interface PolarAreaChartProps extends React.HTMLAttributes<HTMLDivElement> {
   height?: number;
   /** Per-slice colors (any CSS color), cycled across slices. Defaults to the built-in token palette. */
   colors?: string[];
+  /** Fires when a slice is clicked with its `label`, `value`, and `index`; the clicked slice also toggles a selected state that pops it outward along its mid-angle and dims the rest. */
+  onDataClick?: (payload: PolarAreaClickPayload) => void;
   /** Accessible name for the chart's `<svg role="img">`. Defaults to `"polar area chart"`; also accepts `aria-label`. */
   ariaLabel?: string;
   /** Render a visually-hidden data table as an accessible text alternative (WCAG 1.1.1). @default true */
@@ -959,6 +1068,16 @@ interface HeatmapDatum {
   value: number;
 }
 
+/** Payload passed to `onDataClick` when a heatmap cell is clicked. */
+interface HeatmapClickPayload {
+  /** The clicked cell's column (`x`) key. */
+  x: string | number;
+  /** The clicked cell's row (`y`) key. */
+  y: string | number;
+  /** The clicked cell's numeric value. */
+  value: number;
+}
+
 /**
  * Heatmap — a matrix of colored cells keyed by (x, y), each shaded by a
  * single-hue intensity scale between `min` and `max`. Ordered X columns and Y
@@ -966,7 +1085,7 @@ interface HeatmapDatum {
  * Dependency-free inline SVG, with per-cell tooltips, a gradient scale legend,
  * and a visually-hidden data table. Dark mode is automatic through tokens.
  *
- * @startingPoint section="Data display" subtitle="Matrix heatmap (no deps)" viewport="700x280"
+ * @startingPoint section="Charts" subtitle="Matrix heatmap (no deps)" viewport="700x280"
  */
 interface HeatmapProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Cells to plot. X columns and Y rows are derived from these in first-seen order. */
@@ -989,8 +1108,17 @@ interface HeatmapProps extends React.HTMLAttributes<HTMLDivElement> {
   yLabel?: React.ReactNode;
   /** Show the low→high gradient scale legend below the grid. @default true */
   showLegend?: boolean;
+  /**
+   * Enable a 2-D drag/wheel zoom over the cell grid: drag a rectangle to zoom to
+   * that sub-range of the ordered X columns and Y rows, shift-drag to pan, scroll
+   * to zoom about the cursor, and a Reset button restores the full matrix. Needs
+   * at least two columns and two rows. @default false
+   */
+  zoomable?: boolean;
   /** Value formatter for tooltips, printed cell values, and the hidden table. @default fmtNumber */
   valueFormat?: (value: number) => string;
+  /** Fires when a cell is clicked with its `{ x, y, value }`; the clicked cell also toggles a selection outline. */
+  onDataClick?: (payload: HeatmapClickPayload) => void;
   /** Pixel height of the chart. @default 300 */
   height?: number;
   /** Accessible name for the chart's `<svg role="img">`. Per-cell values are exposed via the hidden data table, not this label. Defaults to `"heatmap"`; also accepts `aria-label`. */
@@ -1013,6 +1141,18 @@ interface FunnelDatum {
   color?: string;
 }
 
+/** Payload passed to `onDataClick` when a funnel stage is clicked. */
+interface FunnelClickPayload {
+  /** The clicked stage's `label`. */
+  label: React.ReactNode;
+  /** The clicked stage's numeric value. */
+  value: number;
+  /** Index of the stage in the `data` array. */
+  index: number;
+  /** The stage's percentage of the first (top) stage. */
+  percent: number;
+}
+
 /**
  * Funnel chart — descending stages drawn as centered trapezoids that taper from
  * each stage's value to the next, for conversion / drop-off flows. Each band is
@@ -1021,7 +1161,7 @@ interface FunnelDatum {
  * and a visually-hidden data table. For bars/lines/areas use `Chart`; for part-of-whole
  * shares use `PieChart`.
  *
- * @startingPoint section="Data display" subtitle="Descending funnel stages (no deps)" viewport="700x280"
+ * @startingPoint section="Charts" subtitle="Descending funnel stages (no deps)" viewport="700x280"
  */
 interface FunnelChartProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Funnel stages, ordered from the widest/top stage to the narrowest. */
@@ -1038,6 +1178,8 @@ interface FunnelChartProps extends React.HTMLAttributes<HTMLDivElement> {
   height?: number;
   /** Per-stage colors (any CSS color), cycled when shorter than `data`. Defaults to the token palette. */
   colors?: string[];
+  /** Fires when a stage is clicked with its label, value, index, and percent-of-top; also toggles a selection outline on the clicked stage. */
+  onDataClick?: (payload: FunnelClickPayload) => void;
   /** Value formatter for captions, tooltips, and the hidden data-table cells. @default toLocaleString */
   valueFormat?: (value: number) => string;
   /** Accessible name for the chart's `<svg role="img">`; per-stage values live in the hidden table. Defaults to `"funnel chart"`; also accepts `aria-label`. */
@@ -1060,6 +1202,18 @@ interface TreemapDatum {
   color?: string;
 }
 
+/** Payload passed to `onDataClick` when a treemap tile is clicked. */
+interface TreemapClickPayload {
+  /** The clicked tile's `label`. */
+  label: React.ReactNode;
+  /** The clicked tile's (non-negative) value. */
+  value: number;
+  /** Index of the tile in the original `data` array. */
+  index: number;
+  /** The tile's fraction of the total, `0`–`1` (`0` when the total is `0`). */
+  share: number;
+}
+
 /**
  * Treemap — a squarified partition of a rectangle into tiles sized in proportion
  * to a flat list of values (Bruls/Huizing/van Wijk squarified layout), packed to
@@ -1067,7 +1221,7 @@ interface TreemapDatum {
  * labels, hover tooltips, and a visually-hidden data table. Good for showing the
  * relative weight of parts within a whole (spend by category, storage by bucket).
  *
- * @startingPoint section="Data display" subtitle="Squarified treemap (no deps)" viewport="700x280"
+ * @startingPoint section="Charts" subtitle="Squarified treemap (no deps)" viewport="700x280"
  */
 interface TreemapProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Tiles to lay out. Each has a `label`, a non-negative `value`, and an optional `color`. */
@@ -1082,6 +1236,8 @@ interface TreemapProps extends React.HTMLAttributes<HTMLDivElement> {
   colors?: string[];
   /** Gap in px inset between adjacent tiles. @default 2 */
   gap?: number;
+  /** Fires when a tile is clicked with the tile's label, value, index, and share; the clicked tile also toggles a selection outline. */
+  onDataClick?: (payload: TreemapClickPayload) => void;
   /** Accessible name for the chart's `<svg role="img">`. Per-tile values are exposed via the hidden data table, not this label. Defaults to `"treemap"`; also accepts `aria-label`. */
   ariaLabel?: string;
   /** Render a visually-hidden data table (value + share) as an accessible text alternative (WCAG 1.1.1). @default true */
@@ -1109,6 +1265,22 @@ interface CandlestickDatum {
   close: number;
 }
 
+/** Payload passed to `onDataClick` when a candle is clicked. */
+interface CandlestickClickPayload {
+  /** The clicked candle's `label`. */
+  label: React.ReactNode;
+  /** Opening price for the clicked period. */
+  open: number;
+  /** Highest price reached in the clicked period. */
+  high: number;
+  /** Lowest price reached in the clicked period. */
+  low: number;
+  /** Closing price for the clicked period. */
+  close: number;
+  /** Index of the candle in the full (un-zoomed) `data` array. */
+  index: number;
+}
+
 /**
  * Candlestick (OHLC) chart — one candle per period with a high→low wick and an
  * open→close body, colored by direction (up vs. down), plus a shared value axis,
@@ -1116,7 +1288,7 @@ interface CandlestickDatum {
  * SVG. For bars/lines/areas use `Chart`; for other shapes use the dedicated
  * sibling chart components.
  *
- * @startingPoint section="Data display" subtitle="OHLC candlestick chart (no deps)" viewport="700x280"
+ * @startingPoint section="Charts" subtitle="OHLC candlestick chart (no deps)" viewport="700x280"
  */
 interface CandlestickProps extends React.HTMLAttributes<HTMLDivElement> {
   /** OHLC data points, one candle each, in chronological order. */
@@ -1131,6 +1303,10 @@ interface CandlestickProps extends React.HTMLAttributes<HTMLDivElement> {
   showGrid?: boolean;
   /** Value axis + category labels. @default true */
   showAxis?: boolean;
+  /** Enable drag-to-zoom (+ shift-drag pan, wheel zoom, and a reset button) over the candles. @default false */
+  zoomable?: boolean;
+  /** Fires when a candle is clicked with the OHLC values + its index in the full data array. */
+  onDataClick?: (payload: CandlestickClickPayload) => void;
   /** Tooltip value formatter (also formats the hidden data-table cells). @default toLocaleString */
   valueFormat?: (value: number) => string;
   /** Accessible name for the chart's `<svg role="img">`. Defaults to `"candlestick chart"`; also accepts `aria-label`. */
@@ -1164,6 +1340,24 @@ interface BoxplotDatum {
   outliers?: number[];
 }
 
+/** Payload passed to `onDataClick` when a box is clicked. */
+interface BoxplotClickPayload {
+  /** The clicked box's `label`. */
+  label: React.ReactNode;
+  /** Lower whisker end (distribution minimum). */
+  min: number;
+  /** First quartile — the bottom edge of the box. */
+  q1: number;
+  /** Median — the bold line inside the box. */
+  median: number;
+  /** Third quartile — the top edge of the box. */
+  q3: number;
+  /** Upper whisker end (distribution maximum). */
+  max: number;
+  /** Index of the box in the `data` array. */
+  index: number;
+}
+
 /**
  * Box-and-whisker chart — one box per category summarising a five-number
  * distribution (min, Q1, median, Q3, max) with whiskers, a bold median line,
@@ -1171,7 +1365,7 @@ interface BoxplotDatum {
  * design tokens. For bar/line/area use `Chart`; for other shapes use the
  * dedicated sibling components.
  *
- * @startingPoint section="Data display" subtitle="Box-and-whisker distribution chart" viewport="700x280"
+ * @startingPoint section="Charts" subtitle="Box-and-whisker distribution chart" viewport="700x280"
  */
 interface BoxplotProps extends React.HTMLAttributes<HTMLDivElement> {
   /** The boxes to plot, one per category, each a five-number summary. */
@@ -1184,8 +1378,12 @@ interface BoxplotProps extends React.HTMLAttributes<HTMLDivElement> {
   showGrid?: boolean;
   /** Value axis and category labels. @default true */
   showAxis?: boolean;
+  /** Enable drag-to-zoom over the category axis: drag an x-range to zoom into those boxes (re-fitting the value scale), shift-drag to pan, mouse-wheel to zoom, plus a Reset button. @default false */
+  zoomable?: boolean;
   /** Tooltip/table value formatter. @default toLocaleString */
   valueFormat?: (value: number) => string;
+  /** Fires when a box is clicked, with the five-number summary + its index. */
+  onDataClick?: (payload: BoxplotClickPayload) => void;
   /** Accessible name for the chart's `<svg role="img">`. Per-box values are exposed via the hidden data table, not this label. @default "box plot" */
   ariaLabel?: string;
   /** Render a visually-hidden data table as an accessible text alternative (WCAG 1.1.1). @default true */
@@ -1212,14 +1410,27 @@ interface RangeDatum {
   color?: string;
 }
 
+/** Payload passed to `onDataClick` when a range bar/band segment is clicked. */
+interface RangeChartClickPayload {
+  /** The clicked segment's `label`. */
+  label: React.ReactNode;
+  /** Lower bound of the clicked range. */
+  min: number;
+  /** Upper bound of the clicked range. */
+  max: number;
+  /** Index of the segment in the full (un-zoomed) `data` array. */
+  index: number;
+}
+
 /**
  * Range chart — horizontal range bars (a timeline / Gantt of one min→max band
  * per row) or a range area (a shaded band between a per-category min line and
- * max line), with a shared value axis, grid, tooltips and an accessible data
- * table. Dependency-free inline SVG. For bars/lines/areas use `Chart`; for other
+ * max line), with a shared value axis, grid, tooltips, click (`onDataClick`) +
+ * selection, optional drag/wheel zoom, and an accessible data table.
+ * Dependency-free inline SVG. For bars/lines/areas use `Chart`; for other
  * shapes use the dedicated sibling chart components.
  *
- * @startingPoint section="Data display" subtitle="Range bar / range area chart (no deps)" viewport="700x280"
+ * @startingPoint section="Charts" subtitle="Range bar / range area chart (no deps)" viewport="700x280"
  */
 interface RangeChartProps extends React.HTMLAttributes<HTMLDivElement> {
   /** `"bar"` = horizontal range bars (timeline/Gantt); `"area"` = a band between a min and max line. @default "bar" */
@@ -1232,6 +1443,10 @@ interface RangeChartProps extends React.HTMLAttributes<HTMLDivElement> {
   showGrid?: boolean;
   /** Value axis + category labels. @default true */
   showAxis?: boolean;
+  /** Enable drag-to-zoom over the category axis (+ shift-drag pan, wheel zoom, and a reset button). @default false */
+  zoomable?: boolean;
+  /** Fires when a range bar/band segment is clicked with its label, bounds and full-data index; also toggles a selection outline on that segment. */
+  onDataClick?: (payload: RangeChartClickPayload) => void;
   /** Palette for bar fills / the area band, cycled by index. Defaults to the built-in token palette. */
   colors?: string[];
   /** Tooltip value formatter (also formats the hidden data-table cells). @default toLocaleString */