@cascivo/charts 0.6.0 → 0.7.1

package/dist/index.d.ts

@@ -7,11 +7,31 @@ interface LinearScale {
   range: [number, number];
   map(value: number): number;
   invert(position: number): number;
-  ticks(count?: number): number[];
+  ticks(count?: number, allowDecimals?: boolean): number[];
 }
 declare function linearScale(domain: [number, number], range: [number, number]): LinearScale;
-/** Extended nice-numbers: steps are 1, 2, 2.5 or 5 × 10^k covering [min, max]. */
-declare function niceTicks(min: number, max: number, count?: number): number[];
+/**
+ * Extended nice-numbers: steps are 1, 2, 2.5 or 5 × 10^k covering [min, max].
+ *
+ * `count` is a **density hint**, not a tick count — the step is snapped to the nearest
+ * nice number, so the result may have more or fewer ticks than asked for. That is standard
+ * (d3 behaves the same) and is right for continuous data.
+ *
+ * It is wrong for a whole-number domain. `(max - min) / count` happily produces a
+ * *fractional* step when the requested density is finer than the data's own unit:
+ * `max=1, count=2` → rawStep 0.5 → `[0, 0.5, 1]`; `max=1, count=5` →
+ * `[0, 0.2, 0.4, 0.6, 0.8, 1]`. An incident-count chart with 0–3 incidents per severity
+ * hits this constantly, and the obvious workaround (`yTicks={max + 1}`) lands straight on
+ * it at `max=1` (2026-07-28 report C17a).
+ *
+ * So when every bound is an integer, the step is floored at 1 and snapped to an integer
+ * nice-number unless `allowDecimals` is explicitly `true`. Callers with genuinely
+ * continuous integer-bounded data (a 0–1 ratio axis) opt back in.
+ *
+ * @param allowDecimals Force fractional steps on (`true`) or off (`false`). Omit to
+ *   auto-detect: integer bounds get integer ticks, anything else keeps today's behavior.
+ */
+declare function niceTicks(min: number, max: number, count?: number, allowDecimals?: boolean): number[];
 interface BandScale<T extends string = string> {
   domain: readonly T[];
   range: [number, number];
@@ -226,7 +246,24 @@ interface BarChartSeries<Datum> {
   id: string;
   label: string;
   data: readonly Datum[];
-  color?: string;
+  /**
+   * Bar color. A string colors the whole series; a function colors each bar from its own
+   * datum.
+   *
+   * The per-datum form exists for the common single-series categorical chart whose
+   * categories each carry meaning — incidents by severity, where SEV1 should read as
+   * danger and SEV4 as neutral regardless of which bar is tallest. Before it, the only
+   * route was one single-point series per category with `mode="grouped"`, which renders
+   * *wrong*: the bars overlap and only the first series' category label survives
+   * (2026-07-28 report C18).
+   *
+   * ```tsx
+   * series={[{ id: 'count', label: 'Incidents', data, color: (d) => SEVERITY_COLOR[d.x] }]}
+   * ```
+   *
+   * Each bar is also stamped with `data-x`, so CSS can target one category directly.
+   */
+  color?: string | ((datum: Datum, index: number) => string);
   /**
    * Per-series Y accessor. Overrides the chart-level `y` for this series only —
    * use it to plot two series from one shared `data` row against different fields
@@ -249,20 +286,92 @@ 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;
+  /**
+   * Approximate number of ticks on the x-axis.
+   *
+   * ⚠ **Follows SCREEN position, so its meaning swaps with `orientation`.** On a vertical
+   * chart the x-axis is the category axis; on a horizontal one it is the VALUE axis. Prefer
+   * {@link BarChartProps.valueAxisTicks} / {@link BarChartProps.categoryAxisTicks}, which
+   * name the axis by role and never swap.
+   *
+   * @defaultValue `5`
+   * @deprecated Use `valueAxisTicks` / `categoryAxisTicks`.
+   */
   xTicks?: number;
+  /**
+   * Approximate number of ticks on the y-axis.
+   *
+   * ⚠ **Follows SCREEN position, so its meaning swaps with `orientation`** — see
+   * {@link BarChartProps.xTicks}.
+   *
+   * @defaultValue `5`
+   * @deprecated Use `valueAxisTicks` / `categoryAxisTicks`.
+   */
   yTicks?: number;
-  /** Show every Nth category label (and always the last) to thin a crowded x-axis. */
+  /**
+   * Approximate number of ticks on the **value** axis, whichever way the chart is turned.
+   *
+   * This is the prop you want. `xTicks`/`yTicks` are named for where the axis is *drawn*,
+   * so on `orientation="horizontal"` the value axis moves from screen-y to screen-x and the
+   * controlling prop moves with it — `yTicks={1}` silently does nothing while `xTicks={1}`
+   * works. Meanwhile `xLabelEvery` does NOT swap: it always strides the category axis. Two
+   * conventions in one component, with nothing in the types to say so (2026-07-28 report
+   * C17b). Wins over `xTicks`/`yTicks` when both are given.
+   *
+   * @defaultValue `5`
+   */
+  valueAxisTicks?: number;
+  /**
+   * Approximate number of ticks on the CATEGORY axis, on both orientations. Role-named twin
+   * of valueAxisTicks.
+   *
+   * @defaultValue `5`
+   * @see the component manifest
+   */
+  categoryAxisTicks?: number;
+  /**
+   * Show every Nth category label (and always the last) to thin a crowded axis.
+   *
+   * Always strides the **category** axis (the `x` field of each datum), on both
+   * orientations — unlike `xTicks`/`yTicks`, which follow screen position.
+   * {@link BarChartProps.categoryLabelEvery} is the unambiguous name; this is kept for
+   * compatibility.
+   */
   xLabelEvery?: number;
+  /**
+   * Show every Nth category label (and always the last). Role-named twin of
+   * `xLabelEvery`; wins when both are given.
+   */
+  categoryLabelEvery?: number;
   legend?: boolean;
   tooltip?: boolean;
   /** 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,10 +382,23 @@ 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;
+  /**
+   * Format each category/x-axis tick label. Receives the datum's raw `x` value — a number,
+   * a string, or a `Date`, whichever the series carries.
+   *
+   * Threads through `Axis`'s own `format`, which every chart composing an axis should
+   * surface (2026-07-28 report C16); enforced by `axis-parity.test.ts`.
+   */
+  format?: (value: number | string | Date) => string;
 }
 declare function BarChart<Datum = {
   x: string;
@@ -293,7 +415,10 @@ declare function BarChart<Datum = {
   height,
   xTicks,
   yTicks,
+  valueAxisTicks,
+  categoryAxisTicks,
   xLabelEvery,
+  categoryLabelEvery,
   legend,
   tooltip,
   tooltipFormat,
@@ -303,7 +428,8 @@ declare function BarChart<Datum = {
   labels,
   onSelect,
   fill,
-  patternKind
+  patternKind,
+  format: xFormat
 }: BarChartProps<Datum>): import("react").JSX.Element;
 /** One layer of a stacked bar at a category. */
 interface StackedSegment {
@@ -887,17 +1013,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 +1114,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 +1357,109 @@ 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;
+  /**
+   * Format each X-axis tick label. Receives the datum's raw `x` value — a number, a
+   * string, or a `Date`, whichever the series carries.
+   *
+   * Without it a numeric x renders raw: a `Date.now()`-scale value (the natural shape for
+   * a time series) renders as `1,785,217,000,000`. Passing `Date` objects instead switches
+   * the axis to a time scale, but that format is fixed, so every bucket narrower than a day
+   * collapses to the same label — worse than the epoch number, which at least differed
+   * between buckets. This threads through `Axis`'s existing `format`, mirroring what
+   * `secondAxis.format` already offers on the right (2026-07-28 report C16).
+   *
+   * ```tsx
+   * <LineChart
+   *   series={series}
+   *   format={(x) => new Date(Number(x)).toLocaleTimeString([], { timeStyle: 'short' })}
+   * />
+   * ```
+   */
+  format?: (value: number | string | Date) => string;
   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?: {
@@ -1262,6 +1501,7 @@ declare function LineChart<Datum = {
   height,
   xTicks,
   yTicks,
+  format: xFormat,
   legend,
   tooltip,
   formatTooltip,
@@ -1322,19 +1562,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 +1618,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?: {
@@ -1361,6 +1659,16 @@ interface AreaChartProps<Datum = {
   decimate?: boolean | AreaDecimateOptions;
   /** Render a toolbox (PNG/SVG export, data-view toggle, restore). `true` enables all tools. */
   toolbox?: boolean | ToolboxOptions;
+  /**
+   * Format each X-axis tick label. Receives the datum's raw `x` value — a number, a string,
+   * or a `Date`, whichever the series carries.
+   *
+   * Without it a numeric x renders raw: a `Date.now()`-scale value (the natural shape for a
+   * time series) renders as `1,785,217,000,000`. Passing `Date` objects switches the axis to
+   * a time scale, but that format is fixed, so every bucket narrower than a day collapses to
+   * the same label. Threads through `Axis`'s own `format` (2026-07-28 report C16).
+   */
+  format?: (value: number | string | Date) => string;
 }
 declare function AreaChart<Datum = {
   x: number;
@@ -1393,7 +1701,8 @@ declare function AreaChart<Datum = {
   tooltipMode,
   secondAxis,
   decimate,
-  toolbox
+  toolbox,
+  format: xFormat
 }: AreaChartProps<Datum>): import("react").JSX.Element;
 interface PieChartDatum {
   id: string;
@@ -1423,6 +1732,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 +1759,7 @@ declare function PieChart({
   centerLabel,
   centerSlot,
   emptyLabel,
+  tooltip,
   tooltipFormat,
   legend,
   className,
@@ -1458,6 +1770,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 +1789,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,12 +1829,28 @@ 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;
   /** Render a toolbox (PNG/SVG export, data-view toggle, restore). `true` enables all tools. */
   toolbox?: boolean | ToolboxOptions;
+  /**
+   * Format each X-axis tick label. Receives the datum's raw `x` value — a number, a string,
+   * or a `Date`, whichever the series carries.
+   *
+   * Without it a numeric x renders raw: a `Date.now()`-scale value (the natural shape for a
+   * time series) renders as `1,785,217,000,000`. Passing `Date` objects switches the axis to
+   * a time scale, but that format is fixed, so every bucket narrower than a day collapses to
+   * the same label. Threads through `Axis`'s own `format` (2026-07-28 report C16).
+   */
+  format?: (value: number | string | Date) => string;
 }
 declare function ScatterChart({
   series,
@@ -1511,10 +1870,21 @@ declare function ScatterChart({
   glyph,
   renderer,
   visualMap,
-  toolbox
+  toolbox,
+  format
 }: ScatterChartProps): import("react").JSX.Element;
 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;
   color?: string;
@@ -1548,11 +1918,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;
 }
@@ -1603,11 +1999,34 @@ 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;
+  /**
+   * Format each X-axis tick label. Receives the datum's raw `x` value — a number, a string,
+   * or a `Date`, whichever the series carries.
+   *
+   * Without it a numeric x renders raw: a `Date.now()`-scale value (the natural shape for a
+   * time series) renders as `1,785,217,000,000`. Passing `Date` objects switches the axis to
+   * a time scale, but that format is fixed, so every bucket narrower than a day collapses to
+   * the same label. Threads through `Axis`'s own `format` (2026-07-28 report C16).
+   */
+  format?: (value: number | string | Date) => string;
 }
 declare function Histogram({
   data,
@@ -1618,7 +2037,8 @@ declare function Histogram({
   width: fixedWidth,
   height,
   className,
-  plain
+  plain,
+  format
 }: HistogramProps): import("react").JSX.Element;
 interface BoxplotSeries {
   id: string;
@@ -1629,11 +2049,32 @@ 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;
+  /**
+   * Format each category/x-axis tick label. Receives the datum's raw `x` value — a number,
+   * a string, or a `Date`, whichever the series carries.
+   *
+   * Threads through `Axis`'s own `format`, which every chart composing an axis should
+   * surface (2026-07-28 report C16); enforced by `axis-parity.test.ts`.
+   */
+  format?: (value: number | string | Date) => string;
 }
 declare function Boxplot({
   series,
@@ -1642,7 +2083,8 @@ declare function Boxplot({
   width: fixedWidth,
   height,
   className,
-  plain
+  plain,
+  format
 }: BoxplotProps): import("react").JSX.Element;
 interface BubbleDatum {
   x: number;
@@ -1657,14 +2099,37 @@ 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);
+  /**
+   * Format each X-axis tick label. Receives the datum's raw `x` value — a number, a string,
+   * or a `Date`, whichever the series carries.
+   *
+   * Without it a numeric x renders raw: a `Date.now()`-scale value (the natural shape for a
+   * time series) renders as `1,785,217,000,000`. Passing `Date` objects switches the axis to
+   * a time scale, but that format is fixed, so every bucket narrower than a day collapses to
+   * the same label. Threads through `Axis`'s own `format` (2026-07-28 report C16).
+   */
+  format?: (value: number | string | Date) => string;
 }
 declare function BubbleChart({
   series,
@@ -1675,30 +2140,77 @@ declare function BubbleChart({
   tooltip,
   className,
   plain,
-  glyph
+  glyph,
+  format
 }: BubbleChartProps): import("react").JSX.Element;
 interface ComboChartBar {
   label: string;
   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[];
+  /**
+   * Format each X-axis tick label. Receives the datum's raw `x` value — a number, a string,
+   * or a `Date`, whichever the series carries.
+   *
+   * Without it a numeric x renders raw: a `Date.now()`-scale value (the natural shape for a
+   * time series) renders as `1,785,217,000,000`. Passing `Date` objects switches the axis to
+   * a time scale, but that format is fixed, so every bucket narrower than a day collapses to
+   * the same label. Threads through `Axis`'s own `format` (2026-07-28 report C16).
+   */
+  format?: (value: number | string | Date) => string;
 }
 declare function ComboChart({
   bars,
@@ -1706,12 +2218,17 @@ declare function ComboChart({
   title,
   description,
   secondAxis,
+  barsLabel,
+  lineLabel,
+  legend,
+  xLabelEvery,
   width: fixedWidth,
   height,
   tooltip,
   className,
   plain,
-  annotations
+  annotations,
+  format
 }: ComboChartProps): import("react").JSX.Element;
 interface HeatmapDatum {
   x: string;
@@ -1722,15 +2239,36 @@ 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;
   /** Render a toolbox (PNG/SVG export, data-view toggle, restore). `true` enables all tools. */
   toolbox?: boolean | ToolboxOptions;
+  /**
+   * Format each category/x-axis tick label. Receives the datum's raw `x` value — a number,
+   * a string, or a `Date`, whichever the series carries.
+   *
+   * Threads through `Axis`'s own `format`, which every chart composing an axis should
+   * surface (2026-07-28 report C16); enforced by `axis-parity.test.ts`.
+   */
+  format?: (value: number | string | Date) => string;
 }
 declare function Heatmap({
   data,
@@ -1741,7 +2279,8 @@ declare function Heatmap({
   className,
   plain,
   visualMap,
-  toolbox
+  toolbox,
+  format
 }: HeatmapProps): import("react").JSX.Element;
 interface TreemapDatum {
   id: string;
@@ -1752,10 +2291,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({
@@ -1778,10 +2330,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({
@@ -1800,8 +2365,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;
@@ -1830,11 +2411,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;
@@ -1845,7 +2439,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;
 }
 /**
@@ -1880,13 +2479,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;
 }
 /**
@@ -1918,15 +2535,48 @@ 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;
+  /**
+   * Format each category/x-axis tick label. Receives the datum's raw `x` value — a number,
+   * a string, or a `Date`, whichever the series carries.
+   *
+   * Threads through `Axis`'s own `format`, which every chart composing an axis should
+   * surface (2026-07-28 report C16); enforced by `axis-parity.test.ts`.
+   */
+  format?: (value: number | string | Date) => string;
 }
 /** A streamgraph — stacked areas on a flowing (centered) baseline. */
 declare function Stream({
@@ -1941,7 +2591,8 @@ declare function Stream({
   legend,
   tooltip,
   className,
-  plain
+  plain,
+  format
 }: StreamProps): import("react").JSX.Element;
 interface SunburstProps {
   /** Root of the hierarchy. Leaves carry `value`; parents sum their children. */
@@ -1949,10 +2600,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. */
@@ -1972,10 +2637,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. */
@@ -2001,10 +2680,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;
@@ -2030,15 +2723,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;
@@ -2048,6 +2760,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[];
@@ -2059,8 +2777,23 @@ 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';
+  /**
+   * Format each X-axis tick label. Receives the datum's raw `x` value — a number, a string,
+   * or a `Date`, whichever the series carries.
+   *
+   * Without it a numeric x renders raw: a `Date.now()`-scale value (the natural shape for a
+   * time series) renders as `1,785,217,000,000`. Passing `Date` objects switches the axis to
+   * a time scale, but that format is fixed, so every bucket narrower than a day collapses to
+   * the same label. Threads through `Axis`'s own `format` (2026-07-28 report C16).
+   */
+  format?: (value: number | string | Date) => string;
 }
 declare function Candlestick({
   data: rawData,
@@ -2080,7 +2813,8 @@ declare function Candlestick({
   dataZoom,
   zoom,
   syncId,
-  tooltipMode
+  tooltipMode,
+  format: xFormat
 }: CandlestickProps): import("react").JSX.Element;
 interface PolarDatum {
   label: string;
@@ -2091,16 +2825,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({
@@ -2123,21 +2881,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({
@@ -2155,4 +2949,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 };