@cascivo/charts 0.7.0 → 0.16.0

package/dist/charts.css

@@ -1,2 +1,2 @@
-@layer cascivo.component{._frame_1kt6d_2{inline-size:100%;min-inline-size:0;position:relative}._frame_1kt6d_2>svg{block-size:auto;max-inline-size:100%}@media (prefers-reduced-motion:no-preference){._frame_1kt6d_2>svg{animation:_cascivo-chart-in_1kt6d_1 var(--cascivo-chart-anim-dur,.32s) var(--cascivo-chart-anim-ease,ease-out) both}@keyframes _cascivo-chart-in_1kt6d_1{0%{opacity:0;transform:translateY(4px)}to{opacity:1;transform:translateY(0)}}._frame_1kt6d_2 svg :is(path,rect,circle,line)[data-series],._frame_1kt6d_2 svg path[data-link],._frame_1kt6d_2 svg path[data-depth],._frame_1kt6d_2 svg rect[data-day]{transition-property:var(--cascivo-chart-anim-props,opacity, fill, fill-opacity);transition-duration:var(--cascivo-chart-anim-dur,.24s);transition-timing-function:var(--cascivo-chart-anim-ease,ease)}._frame_1kt6d_2[data-no-anim]>svg{animation:none}._frame_1kt6d_2[data-no-anim] svg :is(path,rect,circle,line)[data-series],._frame_1kt6d_2[data-no-anim] svg path[data-link],._frame_1kt6d_2[data-no-anim] svg path[data-depth],._frame_1kt6d_2[data-no-anim] svg rect[data-day]{transition:none}}._fallback_1kt6d_67{clip-path:inset(50%);white-space:nowrap;block-size:1px;inline-size:1px;position:absolute;inset-inline-start:-9999px;overflow:hidden}._legend_zczeh_2{gap:var(--cascivo-space-2);padding-block:var(--cascivo-space-2);flex-wrap:wrap;display:flex}._item_zczeh_9{align-items:center;gap:var(--cascivo-space-1);padding:var(--cascivo-space-1) var(--cascivo-space-2);border:1px solid var(--cascivo-color-border);border-radius:var(--cascivo-radius-sm);cursor:pointer;font-size:var(--cascivo-font-size-sm);color:var(--cascivo-color-text);transition:opacity var(--cascivo-duration-150,.15s) ease;background:0 0;display:flex}._item_zczeh_9[data-state=off]{opacity:.4}._swatch_zczeh_27{border-radius:2px;flex-shrink:0;block-size:12px;inline-size:12px;display:inline-block}._kpi_1k88k_7{gap:var(--cascivo-space-2);padding:var(--cascivo-kpi-padding,var(--cascivo-space-4));border-radius:var(--cascivo-radius-surface);border:1px solid var(--cascivo-color-border);background:var(--cascivo-color-surface);flex-direction:column;min-inline-size:0;display:flex}._head_1k88k_19{justify-content:space-between;align-items:center;gap:var(--cascivo-space-2);min-inline-size:0;display:flex}._label_1k88k_27{font-size:var(--cascivo-text-sm);color:var(--cascivo-color-foreground-muted);overflow-wrap:anywhere;min-inline-size:0}._valueRow_1k88k_34{align-items:flex-end;gap:var(--cascivo-space-2);min-inline-size:0;display:flex}._value_1k88k_34{font-size:var(--cascivo-text-2xl);font-weight:var(--cascivo-font-bold);line-height:var(--cascivo-leading-none);color:var(--cascivo-color-foreground);font-variant-numeric:tabular-nums}._delta_1k88k_49{font-size:var(--cascivo-text-sm);font-weight:var(--cascivo-font-medium);white-space:nowrap;color:var(--cascivo-color-foreground-muted)}._delta_1k88k_49[data-trend=up]{color:var(--cascivo-color-success-foreground)}._delta_1k88k_49[data-trend=down]{color:var(--cascivo-color-destructive-foreground)}}
+@layer cascivo.component{._frame_1kt6d_2{inline-size:100%;min-inline-size:0;position:relative}._frame_1kt6d_2>svg{block-size:auto;max-inline-size:100%}@media (prefers-reduced-motion:no-preference){._frame_1kt6d_2>svg{animation:_cascivo-chart-in_1kt6d_1 var(--cascivo-chart-anim-dur,.32s) var(--cascivo-chart-anim-ease,ease-out) both}@keyframes _cascivo-chart-in_1kt6d_1{0%{opacity:0;transform:translateY(4px)}to{opacity:1;transform:translateY(0)}}._frame_1kt6d_2 svg :is(path,rect,circle,line)[data-series],._frame_1kt6d_2 svg path[data-link],._frame_1kt6d_2 svg path[data-depth],._frame_1kt6d_2 svg rect[data-day]{transition-property:var(--cascivo-chart-anim-props,opacity, fill, fill-opacity);transition-duration:var(--cascivo-chart-anim-dur,.24s);transition-timing-function:var(--cascivo-chart-anim-ease,ease)}._frame_1kt6d_2[data-no-anim]>svg{animation:none}._frame_1kt6d_2[data-no-anim] svg :is(path,rect,circle,line)[data-series],._frame_1kt6d_2[data-no-anim] svg path[data-link],._frame_1kt6d_2[data-no-anim] svg path[data-depth],._frame_1kt6d_2[data-no-anim] svg rect[data-day]{transition:none}}._fallback_1kt6d_67{clip-path:inset(50%);white-space:nowrap;block-size:1px;inline-size:1px;position:absolute;inset-inline-start:-9999px;overflow:hidden}._legend_1pign_2{gap:var(--cascivo-space-2);padding-block:var(--cascivo-space-2);flex-wrap:wrap;display:flex}._item_1pign_9{align-items:center;gap:var(--cascivo-space-1);padding:var(--cascivo-space-1) var(--cascivo-space-2);border:1px solid var(--cascivo-color-border);border-radius:var(--cascivo-radius-sm);cursor:pointer;font-size:var(--cascivo-text-sm);color:var(--cascivo-color-text);transition:opacity var(--cascivo-duration-150,.15s) ease;background:0 0;display:flex}._item_1pign_9[data-state=off]{opacity:.4}._swatch_1pign_27{border-radius:2px;flex-shrink:0;block-size:12px;inline-size:12px;display:inline-block}._kpi_nrb8p_7{gap:var(--cascivo-space-2);padding:var(--cascivo-kpi-padding,var(--cascivo-space-4));border-radius:var(--cascivo-radius-surface);border:1px solid var(--cascivo-color-border);background:var(--cascivo-color-surface);flex-direction:column;min-inline-size:0;display:flex}._head_nrb8p_19{justify-content:space-between;align-items:center;gap:var(--cascivo-space-2);min-inline-size:0;display:flex}._label_nrb8p_27{font-size:var(--cascivo-text-sm);color:var(--cascivo-color-foreground-muted);overflow-wrap:anywhere;min-inline-size:0}._valueRow_nrb8p_34{align-items:flex-end;gap:var(--cascivo-space-2);min-inline-size:0;display:flex}._value_nrb8p_34{font-size:var(--cascivo-text-2xl);font-weight:var(--cascivo-font-bold);line-height:var(--cascivo-leading-none);color:var(--cascivo-color-foreground);font-variant-numeric:tabular-nums}._delta_nrb8p_49{font-size:var(--cascivo-text-sm);font-weight:var(--cascivo-font-medium);white-space:nowrap;color:var(--cascivo-color-foreground-muted)}._delta_nrb8p_49[data-sentiment=good]{color:var(--cascivo-color-success-foreground)}._delta_nrb8p_49[data-sentiment=bad]{color:var(--cascivo-color-destructive-foreground)}}
 /*$vite$: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
@@ -247,6 +284,20 @@ interface BarChartProps<Datum = {
    * only; to plot multiple fields from one row, give each series its own `y`.
    */
   y: (d: Datum) => number;
+  /**
+   * ⚠ **Not rendered as a visible heading.** This becomes the chart's accessible name
+   * (the SVG `<caption>` / `aria-label`), which is why it is required — a chart with no
+   * accessible name is unusable with a screen reader.
+   *
+   * For a visible heading, put a `CardTitle`/`Heading` above the chart. The prop name
+   * promises a heading and an adopter wrote one, saw nothing, and ended up with a
+   * redundant `CardTitle` on every chart anyway.
+   *
+   * It is NOT renamed to `ariaLabel` (the catalog's name for an invisible accessible name)
+   * because an alias would have to make both optional, which drops the compile-time
+   * guarantee that every chart has an accessible name. The requirement is worth more than
+   * the naming consistency; this warning is the compensation.
+   */
   title: string;
   description?: string;
   /**
@@ -267,16 +318,63 @@ interface BarChartProps<Datum = {
    */
   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`
-   * @see the component manifest
+   * @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. */
@@ -307,6 +405,14 @@ interface BarChartProps<Datum = {
   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;
@@ -323,7 +429,10 @@ declare function BarChart<Datum = {
   height,
   xTicks,
   yTicks,
+  valueAxisTicks,
+  categoryAxisTicks,
   xLabelEvery,
+  categoryLabelEvery,
   legend,
   tooltip,
   tooltipFormat,
@@ -333,7 +442,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 {
@@ -942,19 +1052,38 @@ declare function leftMarginForLabels(leftAxisLabels: readonly string[], plain: b
  */
 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[];
+  bottomAxisLabels?: readonly string[]; /** Whether the right axis also draws a rotated title outside its tick labels. */
+  rightAxisTitle?: boolean;
   plain?: boolean | undefined;
 }): number;
+/**
+ * Approximate block size (px) of one axis label at the 11px axis font — the line box
+ * plus a little separation. What crowds labels stacked down a y-axis is their *height*,
+ * not the length of the text.
+ */
+declare const AXIS_LINE_PX = 14;
 /**
  * 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.
  *
+ * `direction` says which way the labels are laid out along the axis, and therefore which
+ * dimension of the label competes for the band:
+ *
+ * - `'horizontal'` (a bottom category axis) — labels sit side by side, so the constraint
+ *   is text *width*, estimated from the character count.
+ * - `'vertical'` (a horizontal bar chart's category axis, which runs down the y-axis) —
+ *   labels stack, so the constraint is line *height*, which is the same for every label.
+ *
+ * Measuring the vertical case against text width is the bug this parameter fixes: seven
+ * categories down a 240px axis were strided away as "crowded" because one of them was
+ * eight characters long, which is not a fact about vertical space at all.
+ *
  * `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;
+declare function autoLabelStride(labels: readonly string[], axisLength: number, direction?: 'horizontal' | 'vertical'): number | undefined;
 /**
  * Pure index-window math shared by the DataZoom slider and the in-plot wheel/drag
  * zoom-pan. A "window" is an inclusive `[startIndex, endIndex]` over a series of
@@ -1037,6 +1166,21 @@ interface AxisProps {
    * see `autoLabelStride`, which computes this for you. Pass explicitly only to override.
    */
   labelEvery?: number | undefined;
+  /**
+   * Axis title, drawn outside the tick labels — rotated for a vertical axis.
+   *
+   * On a dual-axis chart this is the whole mechanism for saying which series belongs to
+   * which scale. `secondAxis.label` was typed on `AreaChart`/`LineChart` for months and
+   * rendered nothing, so a two-series chart was unreadable without a legend workaround.
+   */
+  title?: string | undefined;
+  /**
+   * Distance from the axis line to the title, in px. Should clear the widest tick label;
+   * callers already compute that width for their margins.
+   *
+   * @defaultValue `36`
+   */
+  titleOffset?: number | undefined;
   transform?: string;
 }
 declare function Axis({
@@ -1046,6 +1190,8 @@ declare function Axis({
   format,
   tickCount,
   labelEvery,
+  title,
+  titleOffset,
   transform
 }: AxisProps): import("react").JSX.Element;
 interface GridLinesProps {
@@ -1236,6 +1382,12 @@ interface LineChartSeries<Datum> {
   id: string;
   label: string;
   data: readonly Datum[];
+  /**
+   * Series colour. **Omit it** — the Nth series automatically takes `--cascivo-chart-N`,
+   * eight distinct hues per theme in both light and dark, so a multi-series chart
+   * differentiates itself with no configuration. Set this only to override the position,
+   * e.g. to keep "errors" red wherever it lands in the array.
+   */
   color?: string;
   /** Which y-axis this series is measured against. Default 'left'. */
   axis?: 'left' | 'right';
@@ -1259,6 +1411,20 @@ interface LineChartProps<Datum = {
    * plot multiple fields from one row, give each series its own `y`.
    */
   y: (d: Datum) => number;
+  /**
+   * ⚠ **Not rendered as a visible heading.** This becomes the chart's accessible name
+   * (the SVG `<caption>` / `aria-label`), which is why it is required — a chart with no
+   * accessible name is unusable with a screen reader.
+   *
+   * For a visible heading, put a `CardTitle`/`Heading` above the chart. The prop name
+   * promises a heading and an adopter wrote one, saw nothing, and ended up with a
+   * redundant `CardTitle` on every chart anyway.
+   *
+   * It is NOT renamed to `ariaLabel` (the catalog's name for an invisible accessible name)
+   * because an alias would have to make both optional, which drops the compile-time
+   * guarantee that every chart has an accessible name. The requirement is worth more than
+   * the naming consistency; this warning is the compensation.
+   */
   title: string;
   description?: string;
   /**
@@ -1290,6 +1456,25 @@ interface LineChartProps<Datum = {
    * @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;
@@ -1386,6 +1571,7 @@ declare function LineChart<Datum = {
   height,
   xTicks,
   yTicks,
+  format: xFormat,
   legend,
   tooltip,
   formatTooltip,
@@ -1415,6 +1601,12 @@ interface AreaChartSeries<Datum> {
   id: string;
   label: string;
   data: readonly Datum[];
+  /**
+   * Series colour. **Omit it** — the Nth series automatically takes `--cascivo-chart-N`,
+   * eight distinct hues per theme in both light and dark, so a multi-series chart
+   * differentiates itself with no configuration. Set this only to override the position,
+   * e.g. to keep "errors" red wherever it lands in the array.
+   */
   color?: string;
   /** Which y-axis this series is measured against (ignored when `stacked`). Default 'left'. */
   axis?: 'left' | 'right';
@@ -1443,6 +1635,20 @@ interface AreaChartProps<Datum = {
    * plot multiple fields from one row, give each series its own `y`.
    */
   y: (d: Datum) => number;
+  /**
+   * ⚠ **Not rendered as a visible heading.** This becomes the chart's accessible name
+   * (the SVG `<caption>` / `aria-label`), which is why it is required — a chart with no
+   * accessible name is unusable with a screen reader.
+   *
+   * For a visible heading, put a `CardTitle`/`Heading` above the chart. The prop name
+   * promises a heading and an adopter wrote one, saw nothing, and ended up with a
+   * redundant `CardTitle` on every chart anyway.
+   *
+   * It is NOT renamed to `ariaLabel` (the catalog's name for an invisible accessible name)
+   * because an alias would have to make both optional, which drops the compile-time
+   * guarantee that every chart has an accessible name. The requirement is worth more than
+   * the naming consistency; this warning is the compensation.
+   */
   title: string;
   description?: string;
   stacked?: boolean;
@@ -1543,6 +1749,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;
@@ -1575,7 +1791,8 @@ declare function AreaChart<Datum = {
   tooltipMode,
   secondAxis,
   decimate,
-  toolbox
+  toolbox,
+  format: xFormat
 }: AreaChartProps<Datum>): import("react").JSX.Element;
 interface PieChartDatum {
   id: string;
@@ -1714,6 +1931,16 @@ interface ScatterChartProps {
   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,
@@ -1733,7 +1960,8 @@ declare function ScatterChart({
   glyph,
   renderer,
   visualMap,
-  toolbox
+  toolbox,
+  format
 }: ScatterChartProps): import("react").JSX.Element;
 interface SparklineBaseProps {
   data: readonly number[];
@@ -1840,6 +2068,19 @@ interface KpiProps {
    * it receives the raw number and owns the entire string, sign included.
    */
   deltaFormat?: 'number' | 'percent' | ((delta: number) => string);
+  /**
+   * Which direction is *good* for this metric — the colour, independent of the arrow.
+   *
+   * The arrow follows the sign of `delta`; this says whether that movement is welcome.
+   * They coincide only for metrics where up is better, and assuming that made every
+   * error-rate, latency, cost and churn tile render its worst news in green. Negating
+   * `delta` to fix the colour also flips the arrow, so there was no correct answer.
+   *
+   * `'neutral'` keeps the arrow and drops the sentiment colour.
+   *
+   * @defaultValue `up`
+   */
+  goodDirection?: 'up' | 'down' | 'neutral';
   deltaLabel?: string;
   icon?: ReactNode;
   sparkline?: readonly number[];
@@ -1850,6 +2091,7 @@ declare function Kpi({
   label,
   delta,
   deltaFormat,
+  goodDirection,
   deltaLabel,
   icon,
   sparkline,
@@ -1879,6 +2121,16 @@ interface HistogramProps {
    * @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,
@@ -1889,7 +2141,8 @@ declare function Histogram({
   width: fixedWidth,
   height,
   className,
-  plain
+  plain,
+  format
 }: HistogramProps): import("react").JSX.Element;
 interface BoxplotSeries {
   id: string;
@@ -1918,6 +2171,14 @@ interface BoxplotProps {
    * @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,
@@ -1926,7 +2187,8 @@ declare function Boxplot({
   width: fixedWidth,
   height,
   className,
-  plain
+  plain,
+  format
 }: BoxplotProps): import("react").JSX.Element;
 interface BubbleDatum {
   x: number;
@@ -1962,6 +2224,16 @@ interface BubbleChartProps {
   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,
@@ -1972,7 +2244,8 @@ declare function BubbleChart({
   tooltip,
   className,
   plain,
-  glyph
+  glyph,
+  format
 }: BubbleChartProps): import("react").JSX.Element;
 interface ComboChartBar {
   label: string;
@@ -2032,6 +2305,16 @@ interface ComboChartProps {
   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,
@@ -2048,7 +2331,8 @@ declare function ComboChart({
   tooltip,
   className,
   plain,
-  annotations
+  annotations,
+  format
 }: ComboChartProps): import("react").JSX.Element;
 interface HeatmapDatum {
   x: string;
@@ -2081,6 +2365,14 @@ interface HeatmapProps {
   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,
@@ -2091,7 +2383,8 @@ declare function Heatmap({
   className,
   plain,
   visualMap,
-  toolbox
+  toolbox,
+  format
 }: HeatmapProps): import("react").JSX.Element;
 interface TreemapDatum {
   id: string;
@@ -2380,6 +2673,14 @@ interface StreamProps {
    * @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({
@@ -2394,7 +2695,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. */
@@ -2471,12 +2773,12 @@ declare function Sankey({
   className,
   plain
 }: SankeyProps): import("react").JSX.Element;
-interface CalendarDatum {
+interface CalendarHeatmapDatum {
   day: string | Date;
   value: number;
 }
-interface CalendarProps {
-  data: readonly CalendarDatum[];
+interface CalendarHeatmapProps {
+  data: readonly CalendarHeatmapDatum[];
   title: string;
   description?: string;
   /** Range start/end (ISO string or Date). Defaults to the data's min/max day. */
@@ -2505,7 +2807,7 @@ interface CalendarProps {
   visualMap?: VisualMapOptions;
 }
 /** A calendar heatmap — a week-column grid of day cells colored by value. */
-declare function Calendar({
+declare function CalendarHeatmap({
   data,
   title,
   description,
@@ -2517,7 +2819,7 @@ declare function Calendar({
   className,
   plain,
   visualMap
-}: CalendarProps): import("react").JSX.Element;
+}: CalendarHeatmapProps): import("react").JSX.Element;
 interface CandlestickDatum {
   /** Period label (date string or index). */
   t: string;
@@ -2586,6 +2888,16 @@ interface CandlestickProps {
    * @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,
@@ -2605,7 +2917,8 @@ declare function Candlestick({
   dataZoom,
   zoom,
   syncId,
-  tooltipMode
+  tooltipMode,
+  format: xFormat
 }: CandlestickProps): import("react").JSX.Element;
 interface PolarDatum {
   label: string;
@@ -2740,4 +3053,4 @@ declare function Gauge({
   className,
   plain
 }: GaugeProps): import("react").JSX.Element;
-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 };
+export { AXIS_CHAR_PX, AXIS_LINE_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, CalendarHeatmap, CalendarHeatmapDatum, CalendarHeatmapProps, 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 };