@cascivo/charts 0.5.1 → 0.7.0

package/dist/index.d.ts

@@ -249,11 +249,31 @@ interface BarChartProps<Datum = {
   y: (d: Datum) => number;
   title: string;
   description?: string;
+  /**
+   * Layout orientation of the component.
+   *
+   * @defaultValue `vertical`
+   * @see the component manifest
+   */
   orientation?: 'vertical' | 'horizontal';
   mode?: 'grouped' | 'stacked' | 'percent';
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   * @see the component manifest
+   */
   width?: number;
   height?: number;
   xTicks?: number;
+  /**
+   * Approximate number of ticks on the y-axis.
+   *
+   * @defaultValue `5`
+   * @see the component manifest
+   */
   yTicks?: number;
   /** Show every Nth category label (and always the last) to thin a crowded x-axis. */
   xLabelEvery?: number;
@@ -262,7 +282,12 @@ interface BarChartProps<Datum = {
   /** Custom tooltip formatter. Stacked default lists "label · total" + per-layer values. */
   tooltipFormat?: (p: ChartPoint) => string;
   className?: string;
-  /** Render only the marks — no axes, grid lines, or legend. For micro/inline charts. */
+  /**
+   * Marks only — no axes, grid lines, or legend. For micro/inline charts.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   plain?: boolean;
   /**
    * Reference lines, bands, and markers drawn over the plot. Geometric axes: `y` is the
@@ -273,7 +298,12 @@ interface BarChartProps<Datum = {
   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. */
+  /**
+   * Bar fill style — solid, a gradient, or a pattern.
+   *
+   * @defaultValue `solid`
+   * @see the component manifest
+   */
   fill?: FillKind;
   /** Pattern motif when `fill="pattern"`. */
   patternKind?: PatternKind;
@@ -887,17 +917,42 @@ declare const PLAIN_MARGINS: {
   readonly bottom: 2;
   readonly left: 2;
 };
+/**
+ * Approximate advance width (px) of one axis-label character at the 11px axis font.
+ * A conservative average across digits, separators, and short month names — good
+ * enough to reserve room without measuring text (no DOM in SSR/tests).
+ */
+declare const AXIS_CHAR_PX = 6.5;
 /**
  * Left margin sized to the widest left-axis label so wide ticks (e.g. `40,000`)
  * aren't clipped past the SVG's `0` origin. The default 36px only fits ~4 glyphs;
  * a 6-glyph thousands label needs ~45px. `plain` charts keep their tiny margin.
  */
 declare function leftMarginForLabels(leftAxisLabels: readonly string[], plain: boolean | undefined): number;
+/**
+ * Right margin sized so the axis chrome on the right-hand side isn't clipped by the SVG
+ * edge. Two independent causes, both of which the default 8px margin failed:
+ *
+ * - a **right-hand value axis** (`secondAxis`) needs the full width of its widest label,
+ *   which renders *outside* the plot via `Axis orientation="y-right"`;
+ * - the **final bottom-axis label** is centred on the last tick, which sits at the plot's
+ *   right edge, so half of it overhangs (`7/26/2026` → `7/26/202`).
+ *
+ * Pass whichever apply; the larger wins. `plain` charts keep their tiny margin.
+ */
+declare function rightMarginForLabels(options?: {
+  /** Labels of a right-hand value axis, if the chart has one. */rightAxisLabels?: readonly string[]; /** Labels of the bottom axis — only the last one's overhang matters. */
+  bottomAxisLabels?: readonly string[];
+  plain?: boolean | undefined;
+}): number;
 /**
  * Stride for a crowded categorical (band) axis: render every Nth label so they stop
  * colliding (e.g. 14 `Jul 1`…`Jul 14` dates in a narrow chart). Returns `undefined`
  * when every label fits — callers pass that straight to `Axis.labelEvery` (all shown).
  * An explicit `xLabelEvery` from the caller always overrides this.
+ *
+ * `Axis` always draws the final label, and drops the strided label before it when the two
+ * would collide — so a stride that doesn't divide the domain evenly is safe.
  */
 declare function autoLabelStride(labels: readonly string[], axisLength: number): number | undefined;
 /**
@@ -963,11 +1018,24 @@ declare function download(content: Blob | string, filename: string): void;
 type AnyScale = LinearScale | BandScale | LogScale | TimeScale;
 interface AxisProps {
   scale: AnyScale;
-  orientation: 'x' | 'y';
+  /**
+   * `x` — horizontal axis, labels below the line.
+   * `y` — vertical axis on the **left**, labels outside to the left.
+   * `y-right` — vertical axis on the **right**, labels outside to the right.
+   *
+   * A right-hand axis MUST use `y-right`: a `y` axis translated to the plot's right edge
+   * draws its labels at `x: -8` with `text-anchor: end`, i.e. *inside the plot*, on top of
+   * the marks. That was the actual rendering of every right axis in the catalog.
+   */
+  orientation: 'x' | 'y' | 'y-right';
   length: number;
   format?: (value: number | string | Date) => string;
   tickCount?: number;
-  /** For band scales: render every Nth category label (and always the last) to avoid crowding. */
+  /**
+   * For band scales: render every Nth category label to avoid crowding. The final label is
+   * always drawn, and a strided label that would collide with it is dropped —
+   * see `autoLabelStride`, which computes this for you. Pass explicitly only to override.
+   */
   labelEvery?: number | undefined;
   transform?: string;
 }
@@ -1193,34 +1261,90 @@ interface LineChartProps<Datum = {
   y: (d: Datum) => number;
   title: string;
   description?: string;
+  /**
+   * Line interpolation curve
+   *
+   * @defaultValue `monotone`
+   * @see the component manifest
+   */
   curve?: Curve;
   width?: number;
+  /**
+   * SVG height in px
+   *
+   * @defaultValue `300`
+   * @see the component manifest
+   */
   height?: number;
+  /**
+   * Approximate number of X-axis ticks
+   *
+   * @defaultValue `5`
+   * @see the component manifest
+   */
   xTicks?: number;
+  /**
+   * Approximate number of Y-axis ticks
+   *
+   * @defaultValue `5`
+   * @see the component manifest
+   */
   yTicks?: number;
   legend?: boolean;
   tooltip?: boolean;
   formatTooltip?: (datum: Datum, series: LineChartSeries<Datum>) => string;
   className?: string;
-  /** Render only the marks — no axes, grid lines, or legend. For micro/inline charts. */
+  /**
+   * Marks only — no axes, grid lines, or legend. For micro/inline charts.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   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). */
+  /**
+   * Bridge non-finite y gaps instead of breaking the line at them.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   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. */
+  /**
+   * Show a keyboard-operable Brush below the plot to subset (zoom) the series to a window.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   brush?: boolean;
-  /** Show a DataZoom slider below the plot — a Brush whose body also pans the window. */
+  /**
+   * Show a DataZoom slider below the plot — a Brush whose body also pans the window.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   dataZoom?: boolean;
-  /** Enable in-plot wheel/drag/keyboard zoom-pan (`+`/`-`/`0`) over the series index window. */
+  /**
+   * Enable in-plot wheel/drag/keyboard zoom-pan (+/-/0) over the series index window, with a
+   * reset control and re-ticked axes.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   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). */
+  /**
+   * Tooltip trigger — item (nearest point) or axis (a crosshair + a shared tooltip listing
+   * every series at the hovered x).
+   *
+   * @defaultValue `item`
+   * @see the component manifest
+   */
   tooltipMode?: 'item' | 'axis';
   /** Add a right-hand y-axis for series with `axis: 'right'` (e.g. bandwidth vs requests/sec). */
   secondAxis?: {
@@ -1322,19 +1446,55 @@ interface AreaChartProps<Datum = {
   title: string;
   description?: string;
   stacked?: boolean;
+  /**
+   * Line/area interpolation curve.
+   *
+   * @defaultValue `monotone`
+   * @see the component manifest
+   */
   curve?: Curve;
-  /** Area fill style: solid (default), a top→bottom gradient, or a pattern. */
+  /**
+   * Area fill style — solid, a top→bottom gradient, or a pattern.
+   *
+   * @defaultValue `solid`
+   * @see the component manifest
+   */
   fill?: FillKind;
   /** Pattern motif when `fill="pattern"`. */
   patternKind?: PatternKind;
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   * @see the component manifest
+   */
   width?: number;
   height?: number;
+  /**
+   * Approximate number of ticks on the x-axis.
+   *
+   * @defaultValue `5`
+   * @see the component manifest
+   */
   xTicks?: number;
+  /**
+   * Approximate number of ticks on the y-axis.
+   *
+   * @defaultValue `5`
+   * @see the component manifest
+   */
   yTicks?: number;
   legend?: boolean;
   tooltip?: boolean;
   className?: string;
-  /** Render only the marks — no axes, grid lines, or legend. For micro/inline charts. */
+  /**
+   * Marks only — no axes, grid lines, or legend. For micro/inline charts.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   plain?: boolean;
   /** Reference lines, shaded bands, and markers drawn over the plot (target/threshold annotations). */
   annotations?: readonly Annotation[];
@@ -1342,15 +1502,37 @@ interface AreaChartProps<Datum = {
   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. */
+  /**
+   * Show a keyboard-operable Brush below the plot to subset the series to a window.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   brush?: boolean;
-  /** Show a DataZoom slider below the plot — a Brush whose body also pans the window. */
+  /**
+   * Show a DataZoom slider below the plot — a Brush whose body also pans the window.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   dataZoom?: boolean;
-  /** Enable in-plot wheel/drag/keyboard zoom-pan (`+`/`-`/`0`) over the series index window. */
+  /**
+   * Enable in-plot wheel/drag/keyboard zoom-pan (+/-/0) over the series index window, with a
+   * reset control and re-ticked axes.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   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). */
+  /**
+   * Tooltip trigger — item (nearest point) or axis (a crosshair + a shared tooltip listing
+   * every series at the hovered x).
+   *
+   * @defaultValue `item`
+   * @see the component manifest
+   */
   tooltipMode?: 'item' | 'axis';
   /** Add a right-hand y-axis for series with `axis: 'right'` (non-stacked only). */
   secondAxis?: {
@@ -1423,6 +1605,8 @@ interface PieChartProps {
   centerSlot?: ReactNode;
   /** Visible placeholder text when data is empty. Defaults to the i18n built-in ("No data"). */
   emptyLabel?: string;
+  /** Show tooltips (default `true`). Parity with Area/Bar/Line/Combo, which all take this. */
+  tooltip?: boolean;
   /** Custom tooltip formatter. Defaults to "value (pct%)". Receives ChartPoint.percent. */
   tooltipFormat?: (p: ChartPoint) => string;
   legend?: boolean;
@@ -1448,6 +1632,7 @@ declare function PieChart({
   centerLabel,
   centerSlot,
   emptyLabel,
+  tooltip,
   tooltipFormat,
   legend,
   className,
@@ -1458,6 +1643,12 @@ declare function PieChart({
 interface ScatterDatum {
   x: number;
   y: number;
+  /**
+   * Point radius or accessor
+   *
+   * @defaultValue `4`
+   * @see the component manifest
+   */
   r?: number;
 }
 interface ScatterChartSeries {
@@ -1471,14 +1662,39 @@ interface ScatterChartProps {
   title: string;
   description?: string;
   r?: number | ((d: ScatterDatum) => number);
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   * @see the component manifest
+   */
   width?: number;
   height?: number;
+  /**
+   * Approximate number of ticks on the x-axis.
+   *
+   * @defaultValue `5`
+   * @see the component manifest
+   */
   xTicks?: number;
+  /**
+   * Approximate number of ticks on the y-axis.
+   *
+   * @defaultValue `5`
+   * @see the component manifest
+   */
   yTicks?: number;
   legend?: boolean;
   tooltip?: boolean;
   className?: string;
-  /** Render only the marks — no axes, grid lines, or legend. For micro/inline charts. */
+  /**
+   * Marks only — no axes, grid lines, or legend. For micro/inline charts.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   plain?: boolean;
   /** Reference lines, shaded bands, and markers drawn over the plot (target/threshold annotations). */
   annotations?: readonly Annotation[];
@@ -1486,7 +1702,13 @@ interface ScatterChartProps {
   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 (default), canvas (force), or auto (canvas past ~2000 points). Canvas
+   * keeps the full a11y fallback table + keyboard layer.
+   *
+   * @defaultValue `svg`
+   * @see the component manifest
+   */
   renderer?: 'svg' | 'canvas' | 'auto';
   /** Map each point's y → CVD-safe colour and/or size via a legend that filters the range. */
   visualMap?: VisualMapOptions;
@@ -1513,19 +1735,42 @@ declare function ScatterChart({
   visualMap,
   toolbox
 }: ScatterChartProps): import("react").JSX.Element;
-interface SparklineProps {
+interface SparklineBaseProps {
   data: readonly number[];
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   *
+   * @defaultValue `80`
+   * @see the component manifest
+   */
   width?: number;
   height?: number;
-  label: string;
   color?: string;
   endDot?: boolean;
 }
+/**
+ * Exactly one of `label` / `ariaLabel` is required — a chart with no accessible name is a
+ * bug, so this stays enforced by the type. `ariaLabel` is the catalog's convention for an
+ * invisible accessible name (here, the SVG `<title>`); `Sparkline` predates it and shipped
+ * `label`, so both work and neither is deprecated.
+ */
+type SparklineProps = SparklineBaseProps & ({
+  label: string;
+  ariaLabel?: never;
+} | {
+  ariaLabel: string;
+  label?: never;
+});
 declare function Sparkline({
   data,
   width,
   height,
   label,
+  ariaLabel,
   color,
   endDot
 }: SparklineProps): import("react").JSX.Element;
@@ -1535,11 +1780,37 @@ interface MeterThresholds {
 }
 interface MeterProps {
   value: number;
+  /**
+   * Minimum allowed value.
+   *
+   * @defaultValue `0`
+   * @see the component manifest
+   */
   min?: number;
+  /**
+   * Maximum allowed value.
+   *
+   * @defaultValue `100`
+   * @see the component manifest
+   */
   max?: number;
   label: string;
+  /**
+   * Selects the visual style variant.
+   *
+   * @defaultValue `bar`
+   * @see the component manifest
+   */
   variant?: 'bar' | 'gauge';
   thresholds?: MeterThresholds;
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   * @see the component manifest
+   */
   width?: number;
   height?: number;
 }
@@ -1556,7 +1827,19 @@ declare function Meter({
 interface KpiProps {
   value: string | number;
   label: string;
+  /**
+   * The change to show beside the value, as a **number** — `Kpi` owns the formatting
+   * (sign, arrow, colour, unit). Its sibling `Stat` takes a pre-formatted `string` and
+   * leaves formatting to you; that is the whole difference between the two tiles.
+   */
   delta?: number;
+  /**
+   * How to render `delta`. `'number'` (default) is locale-formatted with a sign.
+   * `'percent'` treats `delta` as already being in percentage points and appends `%`
+   * (`25.6` → `+25.6%`) — it does NOT multiply by 100. Pass a function for anything else;
+   * it receives the raw number and owns the entire string, sign included.
+   */
+  deltaFormat?: 'number' | 'percent' | ((delta: number) => string);
   deltaLabel?: string;
   icon?: ReactNode;
   sparkline?: readonly number[];
@@ -1566,6 +1849,7 @@ declare function Kpi({
   value,
   label,
   delta,
+  deltaFormat,
   deltaLabel,
   icon,
   sparkline,
@@ -1577,10 +1861,23 @@ interface HistogramProps {
   title: string;
   label: string;
   description?: string;
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   * @see the component manifest
+   */
   width?: number;
   height?: number;
   className?: string;
-  /** Render only the marks — no axes or grid lines. For micro/inline charts. */
+  /**
+   * Marks only — no axes, grid lines, or legend. For micro/inline charts.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   plain?: boolean;
 }
 declare function Histogram({
@@ -1603,10 +1900,23 @@ interface BoxplotProps {
   series: BoxplotSeries[];
   title: string;
   description?: string;
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   * @see the component manifest
+   */
   width?: number;
   height?: number;
   className?: string;
-  /** Render only the marks — no axes. For micro/inline charts. */
+  /**
+   * Marks only — no axes, grid lines, or legend. For micro/inline charts.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   plain?: boolean;
 }
 declare function Boxplot({
@@ -1631,11 +1941,24 @@ interface BubbleChartProps {
   series: BubbleSeries[];
   title: string;
   description?: string;
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   * @see the component manifest
+   */
   width?: number;
   height?: number;
   tooltip?: boolean;
   className?: string;
-  /** Render only the marks — no axes or grid lines. For micro/inline charts. */
+  /**
+   * Marks only — no axes, grid lines, or legend. For micro/inline charts.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   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);
@@ -1656,20 +1979,56 @@ interface ComboChartBar {
   value: number;
 }
 interface ComboChartPoint {
+  /** Index into `bars` — point `i` is drawn at the centre of bar `i`. */
   x: number;
   y: number;
 }
 interface ComboChartProps {
+  /** Bar series — one entry per category, in x order. */
   bars: ComboChartBar[];
+  /**
+   * Line series, correlated with `bars` **by array index**: `line[i]` is drawn over
+   * `bars[i]`. Pass the same number of points as bars — a length mismatch is a data bug
+   * and warns in dev.
+   */
   line: ComboChartPoint[];
   title: string;
   description?: string;
+  /** Measure the line on its own right-hand axis (use when the two metrics differ in scale). */
   secondAxis?: boolean;
+  /** Legend label for the bar series. Defaults to `'Bars'`. */
+  barsLabel?: string;
+  /** Legend label for the line series. Defaults to `'Line'`. */
+  lineLabel?: string;
+  /**
+   * Show the legend. Defaults to **on** when both series have data — a two-metric chart
+   * with nothing naming the two metrics is unreadable.
+   */
+  legend?: boolean;
+  /**
+   * Render every Nth category label. **Omit this — it is auto-computed** from the label
+   * widths and the plot width; pass it only to override the automatic stride.
+   */
+  xLabelEvery?: number;
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   * @see the component manifest
+   */
   width?: number;
+  /** SVG height in px (default 320). Unlike `width`, this does not track the container. */
   height?: number;
   tooltip?: boolean;
   className?: string;
-  /** Render only the marks — no axes or grid lines. For micro/inline charts. */
+  /**
+   * Marks only — no axes, grid lines, or legend. For micro/inline charts.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   plain?: boolean;
   /** Reference lines, bands, and markers. `y` maps to the bar value axis. */
   annotations?: readonly Annotation[];
@@ -1680,6 +2039,10 @@ declare function ComboChart({
   title,
   description,
   secondAxis,
+  barsLabel,
+  lineLabel,
+  legend,
+  xLabelEvery,
   width: fixedWidth,
   height,
   tooltip,
@@ -1696,10 +2059,23 @@ interface HeatmapProps {
   data: HeatmapDatum[];
   title: string;
   description?: string;
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   * @see the component manifest
+   */
   width?: number;
   height?: number;
   className?: string;
-  /** Render only the marks — no axes. For micro/inline charts. */
+  /**
+   * Marks only — no axes, grid lines, or legend. For micro/inline charts.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   plain?: boolean;
   /** Map cell value → CVD-safe colour via a continuous/piecewise legend that filters the range. */
   visualMap?: VisualMapOptions;
@@ -1726,10 +2102,23 @@ interface TreemapProps {
   data: TreemapDatum[];
   title: string;
   description?: string;
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   * @see the component manifest
+   */
   width?: number;
   height?: number;
   className?: string;
-  /** Render only the colored rects — no text labels. For micro/inline charts. */
+  /**
+   * Marks only — no axes, grid lines, or legend. For micro/inline charts.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   plain?: boolean;
 }
 declare function Treemap({
@@ -1752,10 +2141,23 @@ interface RadarProps {
   max?: number;
   title: string;
   description?: string;
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   * @see the component manifest
+   */
   width?: number;
   height?: number;
   className?: string;
-  /** Render only the data polygons — no rings, spokes, or axis labels. For micro/inline charts. */
+  /**
+   * Marks only — no axes, grid lines, or legend. For micro/inline charts.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   plain?: boolean;
 }
 declare function Radar({
@@ -1774,8 +2176,24 @@ interface BulletProps {
   target: number;
   ranges: number[];
   label: string;
+  /**
+   * Minimum allowed value.
+   *
+   * @defaultValue `0`
+   * @see the component manifest
+   */
   min?: number;
   max?: number;
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   *
+   * @defaultValue `300`
+   * @see the component manifest
+   */
   width?: number;
   height?: number;
   className?: string;
@@ -1804,11 +2222,24 @@ interface RadialBarProps {
   description?: string;
   /** Square shorthand: sets width === height. Explicit width/height win. */
   size?: number;
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   * @see the component manifest
+   */
   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 angle in degrees (270 = a gauge arc; 360 = a full ring).
+   *
+   * @defaultValue `270`
+   * @see the component manifest
+   */
   sweep?: number;
   /** Center value text rendered in the hole. */
   centerValue?: string;
@@ -1819,7 +2250,12 @@ interface RadialBarProps {
   tooltip?: boolean;
   legend?: boolean;
   className?: string;
-  /** Render only the marks — no legend. For micro/inline charts. */
+  /**
+   * Marks only — no legend. For micro/inline charts.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   plain?: boolean;
 }
 /**
@@ -1854,13 +2290,31 @@ interface FunnelProps {
   data: readonly FunnelStage[];
   title: string;
   description?: string;
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   * @see the component manifest
+   */
   width?: number;
   height?: number;
-  /** Show per-stage conversion: value + % of the first stage. */
+  /**
+   * Append each stage’s % of the first stage to its label.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   showConversion?: boolean;
   tooltip?: boolean;
   className?: string;
-  /** Render only the marks — no labels. For micro/inline charts. */
+  /**
+   * Marks only — no labels. For micro/inline charts.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   plain?: boolean;
 }
 /**
@@ -1892,14 +2346,39 @@ interface StreamProps {
   categories: readonly (string | number)[];
   title: string;
   description?: string;
-  /** `silhouette` (centered streamgraph, default) or `zero` (baseline stack). */
+  /**
+   * silhouette centers the stack (streamgraph); zero is a baseline stack.
+   *
+   * @defaultValue `silhouette`
+   * @see the component manifest
+   */
   offset?: StreamOffset;
+  /**
+   * Interpolation curve.
+   *
+   * @defaultValue `basis`
+   * @see the component manifest
+   */
   curve?: Curve;
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   * @see the component manifest
+   */
   width?: number;
   height?: number;
   legend?: boolean;
   tooltip?: boolean;
   className?: string;
+  /**
+   * When true, renders a minimal variant without chart chrome.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   plain?: boolean;
 }
 /** A streamgraph — stacked areas on a flowing (centered) baseline. */
@@ -1923,10 +2402,24 @@ interface SunburstProps {
   title: string;
   description?: string;
   size?: number;
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   * @see the component manifest
+   */
   width?: number;
   height?: number;
   tooltip?: boolean;
   className?: string;
+  /**
+   * When true, renders a minimal variant without chart chrome.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   plain?: boolean;
 }
 /** A sunburst — a radial partition of a tree; each node is an annular segment. */
@@ -1946,10 +2439,24 @@ interface SankeyProps {
   links: readonly SankeyLink[];
   title: string;
   description?: string;
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   * @see the component manifest
+   */
   width?: number;
   height?: number;
   tooltip?: boolean;
   className?: string;
+  /**
+   * When true, renders a minimal variant without chart chrome.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   plain?: boolean;
 }
 /** A Sankey flow diagram — ranked nodes with throughput-sized link ribbons. */
@@ -1975,10 +2482,24 @@ interface CalendarProps {
   /** Range start/end (ISO string or Date). Defaults to the data's min/max day. */
   from?: string | Date;
   to?: string | Date;
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   * @see the component manifest
+   */
   width?: number;
   height?: number;
   tooltip?: boolean;
   className?: string;
+  /**
+   * When true, renders a minimal variant without chart chrome.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   plain?: boolean;
   /** Map day value → CVD-safe colour via a continuous/piecewise legend that filters the range. */
   visualMap?: VisualMapOptions;
@@ -2004,15 +2525,34 @@ interface CandlestickDatum {
   high: number;
   low: number;
   close: number;
-  /** Optional traded volume for the secondary axis. */
+  /**
+   * Render volume bars beneath the candles.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   volume?: number;
 }
 interface CandlestickProps {
   data: readonly CandlestickDatum[];
   title: string;
   description?: string;
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   * @see the component manifest
+   */
   width?: number;
   height?: number;
+  /**
+   * Approximate number of ticks on the y-axis.
+   *
+   * @defaultValue `5`
+   * @see the component manifest
+   */
   yTicks?: number;
   /** Colour for up candles (close ≥ open). */
   upColor?: string;
@@ -2022,6 +2562,12 @@ interface CandlestickProps {
   volume?: boolean;
   tooltip?: boolean;
   className?: string;
+  /**
+   * Marks only — no axes. For micro/inline charts.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   plain?: boolean;
   /** Reference lines, shaded bands, and markers over the plot (e.g. a last-price rule). */
   annotations?: readonly Annotation[];
@@ -2033,7 +2579,12 @@ interface CandlestickProps {
   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). */
+  /**
+   * item (nearest candle) or axis (crosshair + OHLC at the hovered x).
+   *
+   * @defaultValue `item`
+   * @see the component manifest
+   */
   tooltipMode?: 'item' | 'axis';
 }
 declare function Candlestick({
@@ -2065,16 +2616,40 @@ interface PolarProps {
   data: readonly PolarDatum[];
   title: string;
   description?: string;
-  /** Plot bars (a rose), or a polar line / filled area. */
+  /**
+   * Bars (rose), a polar line, or a filled polar area.
+   *
+   * @defaultValue `bar`
+   * @see the component manifest
+   */
   mode?: 'bar' | 'line' | 'area';
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   * @see the component manifest
+   */
   width?: number;
   height?: number;
-  /** Radial ring count. */
+  /**
+   * Radial ring count.
+   *
+   * @defaultValue `4`
+   * @see the component manifest
+   */
   rings?: number;
   /** Domain top (full radius). Defaults to the largest value. */
   max?: number;
   tooltip?: boolean;
   className?: string;
+  /**
+   * Marks only — no rings or labels. For micro/inline charts.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   plain?: boolean;
 }
 declare function Polar({
@@ -2097,21 +2672,57 @@ interface GaugeThreshold {
 }
 interface GaugeProps {
   value: number;
+  /**
+   * Minimum allowed value.
+   *
+   * @defaultValue `0`
+   * @see the component manifest
+   */
   min?: number;
+  /**
+   * Maximum allowed value.
+   *
+   * @defaultValue `100`
+   * @see the component manifest
+   */
   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). */
+  /**
+   * Total sweep angle in degrees (270 = a speedometer arc).
+   *
+   * @defaultValue `270`
+   * @see the component manifest
+   */
   sweep?: number;
-  /** Major tick count (labels at min…max). */
+  /**
+   * Major tick count.
+   *
+   * @defaultValue `5`
+   * @see the component manifest
+   */
   ticks?: number;
   title: string;
   description?: string;
+  /**
+   * Fixed SVG width in px. ⚠ **Omit for a responsive chart** — the chart fills and tracks
+   * its container via a ResizeObserver; there is no correct pixel number in a responsive
+   * grid. A fixed width is clamped to the container (max-inline-size: 100%) so it can never
+   * overflow its card, but it also stops the chart growing. `useChartSize` is NOT needed for
+   * this — charts call it internally.
+   * @see the component manifest
+   */
   width?: number;
   height?: number;
   className?: string;
+  /**
+   * Marks only — no ticks/labels. For micro/inline charts.
+   *
+   * @defaultValue `false`
+   * @see the component manifest
+   */
   plain?: boolean;
 }
 declare function Gauge({
@@ -2129,4 +2740,4 @@ declare function Gauge({
   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, autoLabelStride, bandScale, bin, binValues, bindStream, boxStats, cellPath, decimate$1 as decimate, divergingRamp, download, encode, encodeCategory, extent, fillFor, filter, getSyncGroup, glyphPath, gradientId, isZoomed, leftMarginForLabels, linePath, linearScale, linkPath, logScale, lttb, mapVisual, maxDepth, minmax, nearestIndex, niceTicks, panWindow, partition, patternId, pieceIndex, polarPoint, quantize, 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 };
+export { AXIS_CHAR_PX, 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, autoLabelStride, bandScale, bin, binValues, bindStream, boxStats, cellPath, decimate$1 as decimate, divergingRamp, download, encode, encodeCategory, extent, fillFor, filter, getSyncGroup, glyphPath, gradientId, isZoomed, leftMarginForLabels, linePath, linearScale, linkPath, logScale, lttb, mapVisual, maxDepth, minmax, nearestIndex, niceTicks, panWindow, partition, patternId, pieceIndex, polarPoint, quantize, radiusScale, rampLightness, rampOf, rampStops, regression, releaseSyncGroup, renderAnnotation, renderAnnotations, resolveColor, resolveLabels, rightMarginForLabels, sankeyLayout, sequentialRamp, serializeSvg, sort, splitDefined, sqrtScale, squarify, stackSeries, streamExtent, streamLayout, sumValue, svgToPngBlob, timeScale, toStackedSeries, useChartSize, useStreamSeries, visualVisible, voronoiCells, voronoiFind, wrapText, zoomWindow };