@cascivo/charts 0.7.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
@@ -267,16 +304,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 +391,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 +415,10 @@ declare function BarChart<Datum = {
   height,
   xTicks,
   yTicks,
+  valueAxisTicks,
+  categoryAxisTicks,
   xLabelEvery,
+  categoryLabelEvery,
   legend,
   tooltip,
   tooltipFormat,
@@ -333,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 {
@@ -1290,6 +1386,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 +1501,7 @@ declare function LineChart<Datum = {
   height,
   xTicks,
   yTicks,
+  format: xFormat,
   legend,
   tooltip,
   formatTooltip,
@@ -1543,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;
@@ -1575,7 +1701,8 @@ declare function AreaChart<Datum = {
   tooltipMode,
   secondAxis,
   decimate,
-  toolbox
+  toolbox,
+  format: xFormat
 }: AreaChartProps<Datum>): import("react").JSX.Element;
 interface PieChartDatum {
   id: string;
@@ -1714,6 +1841,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 +1870,8 @@ declare function ScatterChart({
   glyph,
   renderer,
   visualMap,
-  toolbox
+  toolbox,
+  format
 }: ScatterChartProps): import("react").JSX.Element;
 interface SparklineBaseProps {
   data: readonly number[];
@@ -1879,6 +2017,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 +2037,8 @@ declare function Histogram({
   width: fixedWidth,
   height,
   className,
-  plain
+  plain,
+  format
 }: HistogramProps): import("react").JSX.Element;
 interface BoxplotSeries {
   id: string;
@@ -1918,6 +2067,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 +2083,8 @@ declare function Boxplot({
   width: fixedWidth,
   height,
   className,
-  plain
+  plain,
+  format
 }: BoxplotProps): import("react").JSX.Element;
 interface BubbleDatum {
   x: number;
@@ -1962,6 +2120,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 +2140,8 @@ declare function BubbleChart({
   tooltip,
   className,
   plain,
-  glyph
+  glyph,
+  format
 }: BubbleChartProps): import("react").JSX.Element;
 interface ComboChartBar {
   label: string;
@@ -2032,6 +2201,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 +2227,8 @@ declare function ComboChart({
   tooltip,
   className,
   plain,
-  annotations
+  annotations,
+  format
 }: ComboChartProps): import("react").JSX.Element;
 interface HeatmapDatum {
   x: string;
@@ -2081,6 +2261,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 +2279,8 @@ declare function Heatmap({
   className,
   plain,
   visualMap,
-  toolbox
+  toolbox,
+  format
 }: HeatmapProps): import("react").JSX.Element;
 interface TreemapDatum {
   id: string;
@@ -2380,6 +2569,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 +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. */
@@ -2586,6 +2784,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 +2813,8 @@ declare function Candlestick({
   dataZoom,
   zoom,
   syncId,
-  tooltipMode
+  tooltipMode,
+  format: xFormat
 }: CandlestickProps): import("react").JSX.Element;
 interface PolarDatum {
   label: string;