@svgrid/grid 3.0.2 → 3.0.4

package/dist/chart-types.d.ts

@@ -0,0 +1,1456 @@
+/**
+ * Every type the chart engine reads or produces. Pure declarations: no code,
+ * no imports, so every other chart module can depend on this one without a
+ * cycle. `chart.ts` re-exports the public ones.
+ */
+/** Every mark this engine can draw. `bar`, `line` and `area` compose (a series
+ *  can override the spec's type for a combo chart); the rest are whole-chart
+ *  types that ignore per-series overrides. */
+export type ChartType = 'bar' | 'line' | 'area' | 'pie' | 'scatter' | 'heatmap' | 'waterfall' | 'funnel' | 'radar' | 'calendar' | 'gauge' | 'treemap' | 'sankey' | 'candlestick' | 'ohlc' | 'boxplot' | 'histogram' | 'range-bar' | 'range-area' | 'lollipop' | 'dumbbell' | 'pareto' | 'stream' | 'sunburst' | 'radial-bar' | 'radial-column' | 'nightingale' | 'chord' | 'bullet';
+/** One open / high / low / close bar. */
+export type OhlcBar = {
+    o: number;
+    h: number;
+    l: number;
+    c: number;
+};
+/** A five-number summary: one box, its whiskers, and anything past them.
+ *  `min` / `max` are the WHISKER ENDS, not the extremes of the sample - with
+ *  the usual 1.5 IQR rule those differ, and the points beyond go in
+ *  `outliers` so they can be drawn individually. */
+export type BoxStats = {
+    min: number;
+    q1: number;
+    median: number;
+    q3: number;
+    max: number;
+    /** Values outside the whiskers, drawn as individual points. */
+    outliers?: number[];
+};
+/** A clicked bar / point / slice - the payload of `SvGridChart`'s `onSelect`.
+ *  `rowIds` is populated when the spec was built from grid rows (via
+ *  `rowsToChartSpec`) and lets a drill handler filter the grid back to the
+ *  source rows for the clicked category / series cell. */
+export type ChartSelection = {
+    category: string;
+    series: string;
+    value: number;
+    rowIds?: Array<string | number>;
+};
+/** A single scatter / bubble point. */
+export type ScatterPoint = {
+    x: number;
+    y: number;
+    r?: number;
+    label?: string;
+};
+/** A statistical / smoothing line drawn on top of a source series.
+ *  - `'linear'`: ordinary least-squares regression line
+ *  - `'sma:N'`: simple moving average over a window of N points
+ *  - `'ema:N'`: exponential moving average with smoothing factor 2/(N+1)
+ *  - `'wma:N'`: weighted moving average, the latest point weighing N
+ *  - `'bb:N:K'`: Bollinger bands, an N-point average with a shaded band K
+ *    standard deviations either side
+ *  - `'vwap'`: volume-weighted average price; needs `ohlc` and `volumes`
+ *  - `'poly:N'`: least-squares polynomial of degree N (2..6)
+ *  - `'exp'`: exponential fit y = a * e^(b x); positive values only
+ *  - `'log'`: logarithmic fit y = a + b * ln(x + 1)
+ *  - `'power'`: power-law fit y = a * (x + 1)^b; positive values only
+ *  The regressions (`linear`, `poly`, `exp`, `log`, `power`) carry their
+ *  R-squared and equation on the overlay line, and the tooltip reads them. */
+export type SeriesOverlay = 'linear' | `sma:${number}` | `ema:${number}` | `wma:${number}` | `bb:${number}:${number}` | 'vwap' | `poly:${number}` | 'exp' | 'log' | 'power';
+/** A texture fill applied in addition to (and on top of) the series color.
+ *  Helps colorblind readers distinguish series at a glance. */
+export type SeriesPattern = 'solid' | 'stripe' | 'crosshatch' | 'dots' | 'diagonal';
+/** One plotted series: its label, its values (one per category), and how to draw it. */
+export type ChartSeries = {
+    label: string;
+    values: number[];
+    color?: string;
+    /** Per-series chart type, for combo charts. Defaults to the spec `type`. */
+    type?: 'bar' | 'line' | 'area' | 'scatter' | 'candlestick' | 'ohlc' | 'boxplot' | 'range-bar' | 'range-area' | 'lollipop' | 'dumbbell';
+    /**
+     * Open / high / low / close per category, parallel to `categories`. `null`
+     * is a gap (a day with no session) and draws nothing.
+     *
+     * Set `values` to the CLOSING prices alongside this. Everything that reads a
+     * series generically reads `values` - the tooltip rows, the CSV export, the
+     * screen-reader table, and `overlay` - so filling it in is what lets a
+     * candlestick series carry a moving average (`overlay: 'sma:20'`) or export
+     * to CSV without a single line of candle-specific code.
+     */
+    ohlc?: Array<OhlcBar | null>;
+    /** Traded volume per category, parallel to `ohlc`. Read by the `'vwap'`
+     *  overlay and the volume / OBV indicator panes. */
+    volumes?: number[];
+    /**
+     * Five-number summaries per category, parallel to `categories`. `null` is a
+     * gap and draws nothing.
+     *
+     * Set `values` to the MEDIANS alongside this, for exactly the reason `ohlc`
+     * sets them to the closes: everything that reads a series generically reads
+     * `values`, so the tooltip rows, the CSV export, the screen-reader table and
+     * `overlay` all keep working with no box-specific code.
+     *
+     * `boxStats()` turns a raw sample into one of these.
+     */
+    boxes?: Array<BoxStats | null>;
+    /**
+     * Symmetric or asymmetric error bars, parallel to `values`. A number is a
+     * symmetric +/- margin; a pair is an explicit low/high; `null` draws nothing.
+     *
+     * These are an ANNOTATION on an existing mark rather than a mark of their
+     * own, so they compose: a bar, line, area or scatter series can carry them
+     * without changing its type. That is the whole reason they are not a
+     * `ChartType` - "bar chart with error bars" should not be a different chart.
+     */
+    errors?: Array<number | {
+        lo: number;
+        hi: number;
+    } | null>;
+    /** Plot against the left (default) or right Y axis. */
+    axis?: 'left' | 'right';
+    /** Scatter / bubble points (used when `type === 'scatter'`). */
+    points?: ScatterPoint[];
+    /** Row IDs contributing to each data point - parallel to `values`. When
+     *  present, click handlers receive these in `ChartSelection.rowIds` so
+     *  callers can drill the grid back to the source rows. */
+    rowIds?: Array<Array<string | number>>;
+    /** Draw a smoothing / trend overlay on top of this series. */
+    overlay?: SeriesOverlay;
+    /** Color for the overlay line. Defaults to the series color. */
+    overlayColor?: string;
+    /** Texture fill (e.g. diagonal stripes) layered over the series color.
+     *  Lets colorblind viewers tell two series apart even at the same hue. */
+    pattern?: SeriesPattern;
+    /** Interpolate the line as a curve instead of polylines. `'monotone'`
+     *  cubic prevents overshoots between points (best default for data);
+     *  `true` is an alias for `'monotone'`. Only meaningful for line/area. */
+    smooth?: boolean | 'monotone';
+    /** Upper envelope (e.g. forecast 95th percentile) parallel to `values`.
+     *  When set alongside `lowerValues`, the chart shades the band between
+     *  the two as a translucent fill in the series color. */
+    upperValues?: number[];
+    /** Lower envelope; pair with `upperValues` for a confidence band. */
+    lowerValues?: number[];
+    /** Marker drawn at every point of a line / area / scatter series. A shape
+     *  name is shorthand for `{ shape }`. Default: a 3px circle. */
+    marker?: ChartMarkerShape | ChartMarker;
+    /** Per-point marker overrides, parallel to `values`. `null` keeps the
+     *  series marker; `{ shape: 'none' }` hides one point's marker. */
+    markers?: Array<ChartMarker | null>;
+    /** Per-point colours, parallel to `values`. `null` keeps the series colour.
+     *  Colours one bar in a series red, or the last point of a line. */
+    colors?: Array<string | null>;
+    /**
+     * Stack this bar series with the others naming the same stack, side by side
+     * with the rest: `{ stack: 'plan' }` on two series and `{ stack: 'actual' }`
+     * on two more draws two stacks per category. Named stacks stack even when
+     * `spec.stacked` is off; with it on, series without a name form the default
+     * stack. Bars and areas: two area series naming the same stack pile on each
+     * other while a third area with another name (or none) sits on the axis,
+     * and `stacked100` / `stackOffset` run per stack.
+     */
+    stack?: string;
+    /** Line width in px for a line / area series. Default 2. */
+    strokeWidth?: number;
+    /** Dash pattern for a line series: an SVG `stroke-dasharray` string or an
+     *  array of lengths. Unset = solid. */
+    dash?: string | number[];
+    /** Opacity of the whole series, 0..1. Default 1. */
+    opacity?: number;
+    /** Start hidden: the legend lists the series switched off and a click shows
+     *  it. For a chart with many series where a few matter first. */
+    visible?: boolean;
+    /** Fade an area fill from the series colour at the top to transparent at
+     *  the baseline (`true`), or between two explicit colours. */
+    gradient?: boolean | {
+        from?: string;
+        to?: string;
+    };
+    /** Draw a line / area as steps instead of straight segments: the step turns
+     *  `'before'` the point, `'after'` it, or in the `'middle'`. */
+    step?: 'before' | 'after' | 'middle';
+    /** Join the points either side of a gap instead of breaking the line. The
+     *  gap still draws no marker. Default false. */
+    connectNulls?: boolean;
+    /** What a `null` / `NaN` value means for this series. Beats the spec's. */
+    nullAs?: 'gap' | 'zero';
+    /**
+     * The LOW end of a range series (`'range-bar'`, `'range-area'`,
+     * `'dumbbell'`), parallel to `values`, which holds the HIGH end. Keeping the
+     * high in `values` is the same contract `ohlc` and `boxes` follow: the
+     * tooltip, the CSV export, the screen-reader table and `overlay` all read
+     * `values` and keep working with no range-specific code.
+     */
+    lowValues?: number[];
+    /** Bullet charts: the target per category, drawn as a tick across the bar. */
+    targets?: number[];
+};
+/** A pinned label drawn over the plot, anchored to a data point or to an
+ *  arbitrary (x, y) in data space. Useful for "Release v1", "Outage", etc. */
+export type ChartAnnotation = {
+    /** Anchor in data space. Provide either `category` + `axis` for a point on
+     *  an existing series, OR raw `x` / `y` numeric coordinates in data space. */
+    at: {
+        category: string;
+        series?: string;
+    } | {
+        x: number;
+        y?: number;
+    };
+    label: string;
+    color?: string;
+    /** Where the label sits relative to the marker. Defaults to 'top'. */
+    placement?: 'top' | 'bottom' | 'left' | 'right';
+    /** The marker: a small `'dot'` (default), a `'flag'` on a pole, a map
+     *  `'pin'`, or a `'square'`. Flags and pins carry the label INSIDE the
+     *  marker, the way earnings and dividend flags read on a price chart. */
+    shape?: 'dot' | 'flag' | 'pin' | 'square';
+    /** Longer text shown in a tooltip when the marker is hovered or focused. */
+    text?: string;
+};
+/**
+ * A reference / target line drawn across the plot.
+ *
+ * Horizontal on the left or right value axis by default. `axis: 'x'` draws it
+ * vertically at a category, a date (ISO string on a time axis) or a number (on
+ * a numeric axis) - "Release v2 shipped here", "budget cut-off".
+ */
+export type ChartReferenceLine = {
+    /** A value on the axis. For `axis: 'x'` this is the category label, an ISO
+     *  date on a time axis, or a number on a numeric axis. */
+    value: number | string;
+    label?: string;
+    axis?: 'left' | 'right' | 'x';
+    color?: string;
+    dashed?: boolean;
+    /** Draw the label as a filled pill on the value axis instead of a caption
+     *  over the line, the way a last-price line reads on a ticker chart. */
+    pill?: boolean;
+};
+/** What a reader can draw on a chart: the kinds the drawing tools offer. */
+export type ChartDrawingKind = 'trend' | 'hray' | 'fib' | 'text' | 'arrow' | 'rect';
+/**
+ * A drawing on a cartesian chart, anchored in DATA space so it survives a
+ * re-layout, a zoom and a resize. `x` follows the reference-line rules (a
+ * category label, an ISO date on a time axis, a number on a numeric axis) and
+ * `y` is a value on the left axis (or the right one with `axis: 'right'`).
+ * Trend lines, arrows, rectangles and Fibonacci retracements take two
+ * points; a horizontal ray and a text label take one.
+ */
+export type ChartDrawing = {
+    id: string;
+    kind: ChartDrawingKind;
+    points: Array<{
+        x: number | string;
+        y: number;
+    }>;
+    text?: string;
+    color?: string;
+    axis?: 'left' | 'right';
+};
+/** A drawing resolved to plot pixels. */
+export type ChartDrawingGeo = {
+    id: string;
+    kind: ChartDrawingKind;
+    points: Array<{
+        x: number;
+        y: number;
+    }>;
+    color: string;
+    text?: string;
+    /** Fibonacci levels between the two points, top to bottom. */
+    levels?: Array<{
+        ratio: number;
+        y: number;
+        label: string;
+    }>;
+    /** The label a horizontal ray carries at the axis: its value. */
+    label?: string;
+};
+/**
+ * A shaded band between two values, behind the marks. On a value axis it is a
+ * horizontal stripe ("target range 80..100"); on `axis: 'x'` a vertical one
+ * ("Q3", "outage window", "weekends"). Values follow the same rules as
+ * {@link ChartReferenceLine.value}.
+ */
+export type ChartReferenceBand = {
+    from: number | string;
+    to: number | string;
+    axis?: 'left' | 'right' | 'x';
+    color?: string;
+    /** Fill opacity, 0..1. Default 0.08. */
+    opacity?: number;
+    label?: string;
+};
+/** The shape drawn at each point of a line / area / scatter series. */
+export type ChartMarkerShape = 'circle' | 'square' | 'diamond' | 'triangle' | 'cross' | 'none';
+/** A point marker: its shape, its size (radius-ish, in px) and its colour. */
+export type ChartMarker = {
+    shape?: ChartMarkerShape;
+    /** Half-size in px. Default 3. */
+    size?: number;
+    /** Overrides the series colour for this marker. */
+    color?: string;
+};
+/**
+ * Per-axis configuration. Every field is optional and additive: the flat
+ * shortcuts on the spec (`yAxisTitle`, `yScale`, `xType`, ...) keep working and
+ * fill the matching field here when it is unset.
+ */
+export type ChartAxisConfig = {
+    /** Pin the low end of the domain. The data still stretches it if a value
+     *  falls outside, unless `nice` is false. */
+    min?: number;
+    /** Pin the high end of the domain. */
+    max?: number;
+    /** Round the domain out to tick boundaries. Default true. `false` uses the
+     *  exact data extent (or `min` / `max`). */
+    nice?: boolean;
+    /** Approximate number of ticks. Default 4. */
+    tickCount?: number;
+    /** Exact spacing between ticks, in data units. Beats `tickCount`. */
+    tickInterval?: number;
+    /** Number format for this axis' labels. Defaults to the spec `valueFormat`. */
+    format?: ChartValueFormat;
+    /** Full control over each tick label. Beats `format`. */
+    formatter?: (value: number, index: number) => string;
+    /** Axis title. Mirrors `xAxisTitle` / `yAxisTitle` / `y2AxisTitle`. */
+    title?: string;
+    /** Draw grid lines across the plot at each tick. Default true for the left
+     *  value axis, false for the x and right axes. */
+    gridLines?: boolean;
+    /** Category-label rotation in degrees. `'auto'` (default) rotates -40 when
+     *  labels are long or many; `0` never rotates. */
+    labelRotation?: number | 'auto';
+    /** Run the axis the other way: values decrease upward (or rightward). */
+    reversed?: boolean;
+    /** Value axes (mirrors `yScale` / `y2Scale`), and a `type: 'number'` x
+     *  axis: `'log'` spaces decades evenly, labels them, and drops categories
+     *  at or below zero. */
+    scale?: 'linear' | 'log';
+    /** X axis only. Mirrors `xType`. `'number'` parses each category as a number
+     *  and positions marks by value, so `['1', '2', '10']` spreads out. */
+    type?: 'category' | 'time' | 'ordinal-time' | 'number';
+    /** Fixed gutter width in px for a value axis, so stacked charts (panes)
+     *  share one left edge. Default: measured. */
+    width?: number;
+    /** Draw the tick labels. Default true. `false` keeps the ticks and grid
+     *  lines but hides the text - what a pane above another pane wants. */
+    labels?: boolean;
+};
+/** Data-label placement and formatting. `dataLabels: true` on the component
+ *  is shorthand for the defaults here. */
+export type ChartDataLabelConfig = {
+    /** Draw the labels at all. Default true when the object is given. */
+    show?: boolean;
+    /** Where a label sits on its mark. `'top'` above a bar / point (default),
+     *  `'inside'` centred in the bar, `'outside'` past the end of a horizontal
+     *  bar, `'center'` at the mark's centre. */
+    placement?: 'top' | 'inside' | 'outside' | 'center';
+    /** Custom label text. Beats the value format. */
+    formatter?: (value: number, ctx: {
+        category: string;
+        series: string;
+    }) => string;
+    /** Hide labels that would overlap an earlier one. Default true. */
+    hideOverlap?: boolean;
+    /** Rotate every label by this many degrees about its anchor (`-45` reads
+     *  up and to the right). The overlap test uses the rotated box. */
+    rotation?: number;
+    /** Instead of hiding a label that would overlap, push it away from its mark
+     *  (up on a vertical chart, right on a horizontal one) until it is clear,
+     *  and draw a leader line from the mark to it. Labels that cannot find
+     *  room within four steps are dropped. Default false. */
+    connector?: boolean;
+};
+/**
+ * How a long line / area series is thinned before layout.
+ *
+ * - `true` / `'auto'`: decimate when there are more points than pixels.
+ * - `false`: never (every point is laid out, however dense).
+ * - object: pick the method and the target point count.
+ */
+export type ChartDecimateConfig = boolean | 'auto' | {
+    /** `'lttb'` (default) keeps the visual shape; `'minmax'` keeps every
+     *  extreme in each pixel bucket, which suits spiky monitoring data. */
+    method?: 'lttb' | 'minmax';
+    /** Points to keep. Default: the plot width in px. */
+    target?: number;
+    /** Only decimate above this many points. Default: `target`. */
+    threshold?: number;
+};
+/** How rows collapse into one number per category in `rowsToChartSpec`. `pN`
+ *  is the Nth percentile (`'p90'`, `'p99'`). */
+export type ChartReducer = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'median' | 'first' | 'last' | 'countDistinct' | `p${number}`;
+/**
+ * What to plot - the input you build and hand to a chart. Categories are the
+ * x-axis labels and every series supplies one value per category.
+ *
+ * {@link buildChart} turns this into a {@link ChartGeometry} for rendering.
+ */
+export type ChartSpec = {
+    /** Default type for series that don't set their own `type`. */
+    type: ChartType;
+    /** X-axis labels (one per data point). */
+    categories: string[];
+    series: ChartSeries[];
+    width?: number;
+    height?: number;
+    /** Palette used when a series has no explicit `color`. */
+    palette?: string[];
+    /** Per-category color overrides (by category label) - for pie / donut slice
+     *  recolouring, where colour follows the category, not a series. */
+    categoryColors?: Record<string, string>;
+    /** Number format for the value axis, tooltips, data labels and reference
+     *  lines. Unset = the default compact `1.2k` / `1.2M` style. */
+    valueFormat?: ChartValueFormat;
+    /** BCP-47 locale for value formatting. Setting this (or `currency`) switches
+     *  formatting to `Intl.NumberFormat`, so thousands separators, the decimal
+     *  mark and the compact suffixes follow the locale rather than the built-in
+     *  English `1.2k` / `1.2M`. Unset = the locale-free default, which is why the
+     *  default output has never changed under anyone's feet. */
+    locale?: string | ReadonlyArray<string>;
+    /** ISO 4217 code for `valueFormat: 'currency'` (`'EUR'`, `'JPY'`, ...). Unset
+     *  means the axis reads `$`, which is wrong everywhere outside the dollar
+     *  zone and was the only currency this chart could draw for a long time. */
+    currency?: string;
+    /** Grouped (nested) category axis: a parent tier spanning consecutive leaf
+     *  categories (spans must sum to `categories.length`). Vertical category
+     *  charts only (ignored for time / horizontal / pie). */
+    categoryGroups?: Array<{
+        label: string;
+        span: number;
+    }>;
+    /** Stack bar / area series (per axis) instead of grouping them. */
+    stacked?: boolean;
+    /** Stack to 100% (each category normalized to its total). Implies stacked. */
+    stacked100?: boolean;
+    /**
+     * Bar orientation. `'horizontal'` swaps the axes - categories run down the
+     * left, bars grow rightward - which suits long category labels. Only applies
+     * when every series is a bar (combo / line / area fall back to vertical).
+     */
+    orientation?: 'vertical' | 'horizontal';
+    /** Pie only: inner radius as a fraction of the outer radius (0..1) -> donut. */
+    innerRadius?: number;
+    /** Horizontal target / goal / average lines. */
+    referenceLines?: ChartReferenceLine[];
+    /**
+     * How to read `categories` along the x axis.
+     *
+     * - `'category'` (default): evenly spaced labels, taken literally.
+     * - `'time'`: parsed as dates and positioned by ACTUAL elapsed time, so an
+     *   irregular gap renders as a proportional gap.
+     * - `'ordinal-time'`: parsed as dates but spaced EVENLY, with date-derived
+     *   ticks. This is what a series of trading sessions or business days needs:
+     *   on a true time axis every weekend opens a hole a third as wide as the
+     *   working week, which is noise rather than information.
+     */
+    xType?: 'category' | 'time' | 'ordinal-time' | 'number';
+    /** Axis titles (reserve gutter space + render). */
+    yAxisTitle?: string;
+    y2AxisTitle?: string;
+    xAxisTitle?: string;
+    /** Y-axis scale. `'log'` plots base-10 logarithmic - values <= 0 are
+     *  treated as missing. Necessary for wide-range data (money, audience
+     *  size, scientific). Default `'linear'`. */
+    yScale?: 'linear' | 'log';
+    /** Right (secondary) Y-axis scale. Default `'linear'`. */
+    y2Scale?: 'linear' | 'log';
+    /** The x axis in full: type, title, tick formatter, label rotation, grid
+     *  lines, reversal. The flat `xType` / `xAxisTitle` fill in what is unset. */
+    xAxis?: ChartAxisConfig;
+    /** The left value axis in full: min / max, tick count or interval, format,
+     *  title, grid lines, reversal, scale. `yAxisTitle` / `yScale` fill in.
+     *  A radar or radial column reads `min` / `max` as its rim. */
+    yAxis?: ChartAxisConfig;
+    /** The right value axis, for series with `axis: 'right'`. */
+    y2Axis?: ChartAxisConfig;
+    /** Chart title, drawn centred above the plot. Reserves its own room. */
+    title?: string;
+    /** Smaller line under the title. */
+    subtitle?: string;
+    /** Small text under the plot, left-aligned: a source, a note, a footnote. */
+    caption?: string;
+    /** Shaded bands behind the marks, on a value axis or across the x axis. */
+    referenceBands?: ChartReferenceBand[];
+    /** What a `null` / `NaN` value means. `'gap'` (default) breaks the line and
+     *  draws no mark; `'zero'` plots it as 0. Per-series `nullAs` beats this. */
+    nullAs?: 'gap' | 'zero';
+    /** Thin long line / area series before layout. Default `'auto'`: only when
+     *  there are more points than pixels. See {@link ChartDecimateConfig}. */
+    decimate?: ChartDecimateConfig;
+    /** Data labels as the spec's own default; the component's `dataLabels`
+     *  prop, when set, replaces it. On a pie, `placement: 'outside'` draws
+     *  callout labels with leader lines instead of percentages on the slices. */
+    dataLabels?: ChartDataLabelConfig;
+    /** Pinned text labels at fixed data-space positions (callouts). */
+    annotations?: ChartAnnotation[];
+    /**
+     * Name each line / area series at its last point, so a reader never has to
+     * match colours against a legend. `true` writes the series label; a
+     * formatter gets the label and the last value. Labels on a crowded right
+     * edge are pushed apart so they stay legible. Cartesian charts only.
+     */
+    seriesLabels?: boolean | {
+        formatter?: (series: string, value: number) => string;
+    };
+    /**
+     * Rules that patch the spec by the rendered size, checked top to bottom,
+     * every matching rule applied in turn (later wins). A rule's `spec` is a
+     * partial spec merged over this one; the axis objects merge one level deep,
+     * everything else replaces. A rule cannot change `width`, `height` or
+     * `responsive` itself. `{ maxWidth: 480, spec: { xAxis: { labelRotation: 90 }, seriesLabels: false } }`
+     * keeps a phone-width chart readable; the `legend` field, when set, moves
+     * or hides `SvChart`'s legend the same way.
+     */
+    responsive?: ChartResponsiveRule[];
+    /** This chart's font, size, background and text / grid colours, over the
+     *  theme tokens. See {@link ChartStyle}. */
+    style?: ChartStyle;
+    /** Reader drawings (trend lines, rays, Fibonacci levels, notes) in data
+     *  space. `SvChart`'s drawing tools produce these; see {@link ChartDrawing}. */
+    drawings?: ChartDrawing[];
+    /** A dashed line at the last close (or the last value of the first
+     *  series) with its value in a pill on the axis, green when the last bar
+     *  closed up and red when it closed down. */
+    lastPriceLine?: boolean | {
+        label?: string;
+        color?: string;
+    };
+    /** When true, automatically cycle through pattern fills for every series
+     *  that doesn't set `pattern` explicitly. Useful as a one-flag colorblind
+     *  fallback. Default false. */
+    patternFallback?: boolean;
+    /** Calendar heatmap: array of date+value samples (one per day). Date
+     *  strings are 'YYYY-MM-DD'. Missing days render as blank cells. */
+    calendarValues?: Array<{
+        date: string;
+        value: number;
+    }>;
+    /** Calendar heatmap: year window. Default: span the data. */
+    calendarStart?: string;
+    calendarEnd?: string;
+    /** Gauge: the value to display. */
+    gaugeValue?: number;
+    /** Gauge: min/max of the dial scale. Defaults [0, 100]. */
+    gaugeMin?: number;
+    gaugeMax?: number;
+    /** Gauge: target marker (the line/notch on the arc). */
+    gaugeTarget?: number;
+    /** Gauge: color bands along the arc (e.g. red/amber/green). */
+    gaugeRanges?: Array<{
+        from: number;
+        to: number;
+        color: string;
+    }>;
+    /** Gauge: unit / suffix shown next to the value (e.g. '%', 'ms'). */
+    gaugeUnit?: string;
+    /** Tree-map: hierarchical root. Leaves have `value`; parents are the
+     *  sum of their children's totals. */
+    treemap?: TreeNode;
+    /** Sankey: nodes + flow links between them. Link `source` / `target`
+     *  reference node ids. */
+    sankeyNodes?: Array<{
+        id: string;
+        label?: string;
+        color?: string;
+    }>;
+    sankeyLinks?: Array<{
+        source: string;
+        target: string;
+        value: number;
+        color?: string;
+    }>;
+    /** Waterfall: per-category flag marking bars as totals / subtotals, drawn
+     *  from 0 to the running sum. A total with a value of 0 shows the sum the
+     *  steps before it reached; a total with a value sets the running sum to
+     *  that value, which is how a bridge opens on "Revenue 4300". Same length
+     *  as `categories`. */
+    waterfallTotals?: boolean[];
+    /** Waterfall: explicit colors for positive/negative/total bars. The
+     *  series color is ignored when this is set. */
+    waterfallColors?: {
+        positive?: string;
+        negative?: string;
+        total?: string;
+    };
+    /** Candlestick / OHLC colors. Direction beats series identity here, the same
+     *  way `waterfallColors` overrides the series color. Defaults to the green /
+     *  red pair from the palette's own vocabulary. */
+    candleColors?: {
+        up?: string;
+        down?: string;
+    };
+    /**
+     * How candles are drawn. `'classic'` (default) fills a down candle and
+     * leaves an up candle hollow. `'hollow'` colours by close vs the PREVIOUS
+     * close and hollows by close vs open, the trader's four-state candle.
+     * `'heikin-ashi'` replaces each candle with the smoothed average form
+     * before drawing, so trends read as runs of one colour.
+     */
+    candleStyle?: 'classic' | 'hollow' | 'heikin-ashi';
+    /** Funnel shape: stacked trapezoids (default), an inverted `'pyramid'`, or
+     *  a `'cone'` that tapers to a point. */
+    funnelShape?: 'trapezoid' | 'pyramid' | 'cone';
+    /**
+     * Baseline for stacked areas. `'zero'` (default) stacks up from the axis;
+     * `'wiggle'` centres the stack on a baseline that minimises the wiggle of
+     * the layers (a stream graph); `'silhouette'` centres it on zero.
+     */
+    stackOffset?: 'zero' | 'wiggle' | 'silhouette';
+    /** Histogram: the bin edges, one more than there are categories. Set by
+     *  `binValues`; the x axis labels the edges rather than the bin centres. */
+    binEdges?: number[];
+    /** Hierarchy for a sunburst. An alias of `treemap`: either field feeds
+     *  either chart. */
+    tree?: TreeNode;
+    /** Bullet chart: qualitative ranges behind the measure bars (poor / ok /
+     *  good), shared by every category. Falls back to `gaugeRanges`. */
+    bulletRanges?: Array<{
+        from: number;
+        to: number;
+        color: string;
+    }>;
+    /** Heatmap color scale. `'sequential'` maps min->max through one hue,
+     *  `'diverging'` runs cold->neutral->warm around 0. A custom array
+     *  (>=2 hex colors) defines an arbitrary gradient. Default `'sequential'`. */
+    colorScale?: 'sequential' | 'diverging' | string[];
+};
+/** A tree-map / sankey / treemap node spec. Used recursively as a tree. */
+export type TreeNode = {
+    name: string;
+    value?: number;
+    color?: string;
+    children?: TreeNode[];
+};
+/** A laid-out tree-map rectangle. */
+export type ChartTreemapCell = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    color: string;
+    textColor: string;
+    name: string;
+    value: number;
+    /** Depth from the root - useful for color cycling per level. */
+    depth: number;
+};
+/** A calendar-heatmap cell (one day). */
+export type ChartCalendarCell = {
+    x: number;
+    y: number;
+    size: number;
+    date: string;
+    value: number;
+    /** Defined when a value was supplied for this day; blank otherwise. */
+    defined: boolean;
+    color: string;
+};
+/** A gauge dial layout. */
+export type ChartGaugeLayout = {
+    cx: number;
+    cy: number;
+    r: number;
+    /** Track arc path (background grey). */
+    trackPath: string;
+    /** Value arc path (filled to the current value). */
+    valuePath: string;
+    /** Optional colored range arcs. */
+    rangePaths: Array<{
+        path: string;
+        color: string;
+        from: number;
+        to: number;
+    }>;
+    /** Pixel position of the target marker (when set). */
+    target: {
+        x1: number;
+        y1: number;
+        x2: number;
+        y2: number;
+    } | null;
+    /** Tick marks around the dial (major ticks are longer). */
+    ticks: Array<{
+        x1: number;
+        y1: number;
+        x2: number;
+        y2: number;
+        major: boolean;
+    }>;
+    /** Pointer needle (a kite shape) + its center hub radius. */
+    needle: {
+        path: string;
+        hubR: number;
+    };
+    /** Status color of the value arc (the band the value falls in), or null to
+     *  fall back to the theme accent. */
+    valueColor: string | null;
+    /** Scale end labels positioned under the two arc ends. */
+    minLabel: {
+        x: number;
+        y: number;
+    };
+    maxLabel: {
+        x: number;
+        y: number;
+    };
+    value: number;
+    min: number;
+    max: number;
+    unit: string;
+};
+/** A sankey node + its laid-out rect + total flow. */
+export type ChartSankeyNode = {
+    id: string;
+    label: string;
+    color: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /** Column (depth) the node was assigned to. */
+    column: number;
+    totalIn: number;
+    totalOut: number;
+};
+/** A sankey link rendered as a curved ribbon. */
+export type ChartSankeyLink = {
+    path: string;
+    color: string;
+    /** Stroke width = link value scaled to pixels. */
+    width: number;
+    source: string;
+    target: string;
+    value: number;
+};
+/** A single funnel segment (trapezoid) in pixel space. */
+export type ChartFunnelSegment = {
+    /** Pre-built SVG path for the trapezoid. */
+    path: string;
+    color: string;
+    label: string;
+    /** Original value (before any percentile normalisation). */
+    value: number;
+    /** Conversion vs. first segment, 0..1. */
+    conversion: number;
+    /** Drop-off from the previous segment, 0..1. */
+    dropoff: number;
+    /** Centre point (label anchor). */
+    cx: number;
+    cy: number;
+    /** Auto-picked black/white contrast color for in-segment labels. */
+    textColor: string;
+};
+/** A radar series' polygon: axis values + the closed polygon path. */
+export type ChartRadarSeries = {
+    label: string;
+    color: string;
+    path: string;
+    /** Per-axis (x, y) endpoints so callers can draw dots / hit targets. */
+    points: Array<{
+        x: number;
+        y: number;
+        value: number;
+        axis: string;
+    }>;
+};
+/** Radar axis spoke + tick info. */
+export type ChartRadarAxis = {
+    label: string;
+    /** Outermost endpoint of the spoke. */
+    x: number;
+    y: number;
+};
+/** A single heatmap rectangle in pixel space. */
+export type ChartHeatmapCell = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    color: string;
+    /** Text color picked for contrast against `color`. */
+    textColor: string;
+    value: number;
+    rowLabel: string;
+    colLabel: string;
+};
+/**
+ * One candlestick / OHLC bar in SVG coordinates.
+ *
+ * Kept apart from {@link ChartBar} rather than folded into it: bars pick up
+ * series pattern fills, data labels and the brush mini-map, and all three are
+ * wrong for a candle. A separate array means every existing loop over `bars`
+ * keeps working untouched, which is the point of this flat geometry.
+ */
+export type ChartCandle = {
+    /** Body rect left edge and width. In OHLC mode, the span of the two ticks. */
+    x: number;
+    w: number;
+    /** Wick line, and the OHLC bar's vertical. */
+    xCenter: number;
+    yOpen: number;
+    yClose: number;
+    yHigh: number;
+    yLow: number;
+    /** Body rect, pre-ordered so the renderer does no min/max of its own. */
+    bodyY: number;
+    bodyH: number;
+    /** Close at or above open. Drives colour and hollow-vs-filled. */
+    up: boolean;
+    /** Draw the body as an outline. Classic style: every up candle; hollow
+     *  style: close above open, whatever the colour. */
+    hollow: boolean;
+    color: string;
+    label: string;
+    series: string;
+    o: number;
+    h: number;
+    l: number;
+    c: number;
+};
+/**
+ * A laid-out box plot, in SVG coordinates. Its own array for the same reason
+ * candles have one: `bars` carries pattern fills, data labels and the brush
+ * mini-map, none of which mean anything for a box.
+ */
+export type ChartBox = {
+    /** Box rect left edge and width. */
+    x: number;
+    w: number;
+    /** Whisker line and the caps, centred on the slot. */
+    xCenter: number;
+    yMin: number;
+    yQ1: number;
+    yMedian: number;
+    yQ3: number;
+    yMax: number;
+    /** Box rect, pre-ordered so the renderer does no min/max of its own. */
+    boxY: number;
+    boxH: number;
+    /** Points beyond the whiskers, already positioned. */
+    outliers: Array<{
+        y: number;
+        value: number;
+    }>;
+    color: string;
+    label: string;
+    series: string;
+    min: number;
+    q1: number;
+    median: number;
+    q3: number;
+    max: number;
+};
+/** One positioned error bar: a vertical span with caps, centred on its mark. */
+export type ChartErrorBar = {
+    xCenter: number;
+    yLo: number;
+    yHi: number;
+    /** Cap half-width, so the renderer draws the same T at both ends. */
+    cap: number;
+    color: string;
+    label: string;
+    series: string;
+    lo: number;
+    hi: number;
+};
+/** A computed bar rectangle in SVG coordinates. Output of {@link buildChart}, not an input. */
+export type ChartBar = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    color: string;
+    /** Category (x label) this bar belongs to - for tooltips + labels. */
+    label: string;
+    /** Series label this bar belongs to. */
+    series: string;
+    value: number;
+    /** Category index. A grouped axis repeats its leaf labels (Q1 to Q4 under
+     *  each year), so the label alone cannot name one bar; this can. */
+    index?: number;
+    /** Series opacity, when the series set one. */
+    opacity?: number;
+    /** The low end of a floating (range) bar, when it does not sit on the axis. */
+    lo?: number;
+};
+/** A lollipop stem (one dot) or a dumbbell (two dots) in SVG coordinates. */
+export type ChartStem = {
+    xCenter: number;
+    /** The stem runs from y0 (the baseline or the low dot) to y1 (the value). */
+    y0: number;
+    y1: number;
+    /** Dot radius. */
+    r: number;
+    color: string;
+    /** Colour of the low dot of a dumbbell; the high dot uses `color`. */
+    color2?: string;
+    label: string;
+    series: string;
+    value: number;
+    /** The low value of a dumbbell. */
+    value2?: number;
+    /** A dumbbell draws a dot at both ends; a lollipop only at y1. */
+    dumbbell: boolean;
+};
+/** One computed point on a line, with whether the series has a value there. */
+export type ChartLinePoint = {
+    x: number;
+    y: number;
+    label: string;
+    value: number;
+    /** False for null / NaN values - the line breaks (gap), no dot is drawn. */
+    defined: boolean;
+    /** The marker to draw here, resolved from the series and per-point config.
+     *  Absent = the default 3px circle in the series colour. */
+    marker?: ChartMarker;
+};
+/** How a line series is stroked and filled. Every field is optional; the
+ *  renderer applies its defaults (2px solid, full opacity, flat fill). */
+export type ChartLineStyle = {
+    strokeWidth?: number;
+    /** Resolved `stroke-dasharray` string. */
+    dash?: string;
+    opacity?: number;
+    /** Resolved gradient stops for the area fill, top to bottom. */
+    gradient?: {
+        from: string;
+        to: string;
+    } | null;
+};
+/** A computed line series: its points and the path drawn through them. */
+export type ChartLine = {
+    path: string;
+    areaPath: string;
+    color: string;
+    label: string;
+    points: ChartLinePoint[];
+    /** Confidence-band path (between upperValues + lowerValues) for this
+     *  series, when both arrays are supplied. Empty otherwise. */
+    bandPath?: string;
+    /** Stroke / fill styling from the series. Absent on synthetic lines
+     *  (waterfall connectors, overlays). */
+    style?: ChartLineStyle;
+    /** How the path was built, so a tween can rebuild it from moved points. */
+    smooth?: boolean;
+    step?: 'before' | 'after' | 'middle';
+    /** A range area: `areaPath` is the band between the low and the high edge
+     *  and `path` strokes both. The band is the mark, so it is drawn at a fill
+     *  an area under a line would not need. */
+    range?: boolean;
+    /** Goodness of fit of a regression overlay (0..1); absent on other lines. */
+    r2?: number;
+    /** The fitted equation of a regression overlay, in x = point index. */
+    equation?: string;
+};
+/**
+ * Per-chart looks that beat the theme tokens: the font, its size, the
+ * background and the text and grid colours. Applied as CSS custom properties
+ * on the chart's host, so an unset field keeps the token and a set one wins
+ * for this chart alone; PNG, SVG and PDF exports read the same values.
+ */
+export type ChartStyle = {
+    /** The font family for every label. Default: inherited. */
+    fontFamily?: string;
+    /** The base type size in px; the chart's labels scale with it (12 is the
+     *  default size, 14 makes every label a sixth larger). */
+    fontSize?: number;
+    /** The plot background. Default: transparent over the page. */
+    background?: string;
+    /** Titles, axis labels and data labels. */
+    textColor?: string;
+    /** Grid lines and axis lines. */
+    gridColor?: string;
+};
+/** One size-conditional patch; see {@link ChartSpec.responsive}. */
+export type ChartResponsiveRule = {
+    /** Applies when the rendered width is at most this many px. */
+    maxWidth?: number;
+    /** Applies when the rendered width is at least this many px. */
+    minWidth?: number;
+    /** Applies when the rendered height is at most this many px. */
+    maxHeight?: number;
+    /** The partial spec to merge in. */
+    spec?: Partial<ChartSpec>;
+    /** Where `SvChart` puts its legend under this rule (`false` hides it). */
+    legend?: boolean | 'top' | 'bottom' | 'left' | 'right';
+};
+/** A series name drawn at a line's last point (`spec.seriesLabels`). */
+export type ChartSeriesLabel = {
+    x: number;
+    y: number;
+    text: string;
+    color: string;
+    series: string;
+};
+/** A computed pie slice, as an SVG arc plus its label placement. */
+export type ChartPieSlice = {
+    path: string;
+    color: string;
+    label: string;
+    value: number;
+    percent: number;
+    /** Centroid - anchor point for a data label. */
+    cx: number;
+    cy: number;
+    /** The arc: start / end angle (radians, clockwise from 12 o'clock), outer
+     *  and inner radius, and the centre. Lets a tween rebuild the path. */
+    arc?: {
+        a0: number;
+        a1: number;
+        r: number;
+        ir: number;
+        cx: number;
+        cy: number;
+    };
+    /** A callout label outside the pie (`dataLabels.placement: 'outside'`): a
+     *  leader from the arc's edge to a horizontal run, then the text. */
+    callout?: {
+        x1: number;
+        y1: number;
+        x2: number;
+        y2: number;
+        x3: number;
+        tx: number;
+        ty: number;
+        anchor: 'start' | 'end';
+        /** How many characters of the label fit between the leader and the
+         *  chart's edge on this side; the renderer truncates to it. */
+        maxChars: number;
+    };
+};
+/** A value-axis tick: the number, where it sits vertically, and its label. */
+export type ChartAxisTick = {
+    value: number;
+    y: number;
+    label: string;
+};
+/** A category-axis tick: the label and its horizontal position. */
+export type ChartCategoryTick = {
+    label: string;
+    x: number;
+};
+/** One legend entry, paired with the series colour it stands for. */
+export type ChartLegendItem = {
+    label: string;
+    color: string;
+};
+/** A computed reference line (target, average, threshold) at its plotted height. */
+export type ChartRefLineGeo = {
+    y: number;
+    label: string;
+    color: string;
+    dashed: boolean;
+    pill?: boolean;
+};
+/** A vertical reference line positioned by `x`: the value axis of a horizontal
+ *  bar chart, or an `axis: 'x'` reference line on any cartesian chart. */
+export type ChartRefLineGeoV = {
+    x: number;
+    label: string;
+    color: string;
+    dashed: boolean;
+};
+/** A shaded reference band, already a rectangle in plot coordinates. */
+export type ChartRefBandGeo = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    color: string;
+    opacity: number;
+    label: string;
+    /** Which way the band runs, so a label can sit at the right edge. */
+    axis: 'x' | 'y';
+};
+/** Title, subtitle and caption placement, plus the vertical room they took. */
+export type ChartFrame = {
+    /** Pixels reserved above the plot for the title / subtitle. */
+    top: number;
+    /** Pixels reserved below the plot for the caption. */
+    bottom: number;
+    title: {
+        x: number;
+        y: number;
+        text: string;
+    } | null;
+    subtitle: {
+        x: number;
+        y: number;
+        text: string;
+    } | null;
+    caption: {
+        x: number;
+        y: number;
+        text: string;
+    } | null;
+};
+/** A computed scatter point in SVG coordinates. */
+export type ChartScatterDot = {
+    cx: number;
+    cy: number;
+    r: number;
+    color: string;
+    label: string;
+    series: string;
+    x: number;
+    y: number;
+};
+/** One arc segment of a polar chart, as a ready SVG path plus its angles and
+ *  radii so a label or a hit test can be placed without redoing the maths. */
+export type ChartArc = {
+    path: string;
+    color: string;
+    textColor: string;
+    /** Category (radial bar / column, nightingale, chord group) or node name (sunburst). */
+    label: string;
+    series: string;
+    value: number;
+    /** Start / end angle in radians, 12 o'clock = -PI/2, clockwise. */
+    a0: number;
+    a1: number;
+    /** Inner / outer radius. */
+    r0: number;
+    r1: number;
+    cx: number;
+    cy: number;
+    /** Sunburst depth from the root (0 = first ring). */
+    depth?: number;
+    /** Sunburst: the path of node names from the root, for drilldown. */
+    nodePath?: string[];
+    /** Centroid, for a label. */
+    lx: number;
+    ly: number;
+    /** Radial bar: the faint full ring behind the value arc. */
+    trackPath?: string;
+};
+/** A chord ribbon between two group arcs. */
+export type ChartChordRibbon = {
+    path: string;
+    color: string;
+    source: string;
+    target: string;
+    value: number;
+};
+/** One bullet row: qualitative ranges, the measure bar and the target tick. */
+export type ChartBullet = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    /** The measure bar, drawn at half height inside the row. */
+    measureW: number;
+    /** The target tick x, or null when the row has no target. */
+    targetX: number | null;
+    ranges: Array<{
+        x: number;
+        w: number;
+        color: string;
+    }>;
+    color: string;
+    label: string;
+    series: string;
+    value: number;
+    target: number | null;
+};
+/**
+ * Everything needed to render a chart: the plot rectangle plus every mark
+ * already positioned in SVG coordinates. Produced by {@link buildChart} from a
+ * {@link ChartSpec}, so a renderer does no maths of its own.
+ */
+export type ChartGeometry = {
+    type: ChartType;
+    width: number;
+    height: number;
+    plot: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    /**
+     * The value domain each axis was actually drawn against, and the slot width
+     * of the category axis. Plain data, deliberately: the geometry stays a
+     * serialisable value object, and `chartScales(geo)` turns this into the
+     * `xOf` / `yOf` functions a custom mark needs.
+     *
+     * Null on the types with no cartesian axes (pie, gauge, treemap, sankey,
+     * calendar, radar, funnel), which is also how a caller can tell whether
+     * drawing into plot coordinates means anything.
+     */
+    axes: {
+        y: {
+            min: number;
+            max: number;
+            log: boolean;
+            reversed?: boolean;
+        };
+        /** The right axis, when a series is plotted against one. */
+        y2: {
+            min: number;
+            max: number;
+            log: boolean;
+            reversed?: boolean;
+        } | null;
+        /** Horizontal room per category, in px. */
+        slot: number;
+        /** Number of categories the axis was laid out for. */
+        count: number;
+        /**
+         * The x axis when it is continuous (`'time'` or `'number'`): its value
+         * domain, so `xOfValue` can place a mark by value rather than by index.
+         * Absent on a category / ordinal axis, where x is a function of the index.
+         */
+        x?: {
+            type: 'time' | 'number';
+            min: number;
+            max: number;
+            reversed?: boolean;
+            /** A logarithmic number axis: positions go through log10. */
+            log?: boolean;
+            /** The parsed value of each category, so `xOf(i)` lands on the mark. */
+            values: number[];
+        };
+        /** A category / ordinal axis drawn right-to-left. */
+        xReversed?: boolean;
+        /** The category labels, so `xOfValue('Mar')` can find its slot. */
+        labels?: string[];
+    } | null;
+    /** Title / subtitle / caption placement and the room they reserved. */
+    frame: ChartFrame;
+    /** Which axes draw grid lines. */
+    grid: {
+        x: boolean;
+        y: boolean;
+    };
+    /** Shaded reference bands, drawn beneath the marks. */
+    referenceBands: ChartRefBandGeo[];
+    bars: ChartBar[];
+    /** Candlestick / OHLC bars. Empty for every other chart type. */
+    candles: ChartCandle[];
+    /** Box plots. Empty for every other chart type. */
+    boxes: ChartBox[];
+    /** Error bars, from any series carrying `errors`. Empty when none do - they
+     *  annotate whatever mark the series already draws. */
+    errorBars: ChartErrorBar[];
+    /** Lollipop stems and dumbbells. Empty unless a series draws one. */
+    stems: ChartStem[];
+    /** Arc segments: sunburst rings, radial bars / columns, nightingale petals
+     *  and chord groups. Empty for every other type. */
+    arcs: ChartArc[];
+    /** Chord ribbons between two group arcs. */
+    chordRibbons: ChartChordRibbon[];
+    /** Bullet rows (type === 'bullet'). */
+    bullets: ChartBullet[];
+    /** Polar axis labels for radial columns / nightingale: one per category at
+     *  the outer edge, plus the ring values drawn as faint circles. */
+    polarAxes: ChartRadarAxis[];
+    polarRings: number[];
+    lines: ChartLine[];
+    slices: ChartPieSlice[];
+    yTicks: ChartAxisTick[];
+    /** Right-axis ticks (combo / dual-axis); empty when there's no right axis. */
+    y2Ticks: ChartAxisTick[];
+    hasRightAxis: boolean;
+    xTicks: ChartCategoryTick[];
+    /** Grouped category axis parent tier: label + span extent (pixels). Empty
+     *  unless `spec.categoryGroups` is set on a vertical category chart. */
+    categoryGroupTicks: Array<{
+        label: string;
+        xCenter: number;
+        x0: number;
+        x1: number;
+    }>;
+    /** True when x labels are long/many and should be rotated. */
+    xLabelRotated: boolean;
+    /** The rotation the x labels are drawn at, in degrees. 0 when upright,
+     *  -40 for the automatic tilt, or whatever `xAxis.labelRotation` asked for. */
+    xLabelAngle: number;
+    legend: ChartLegendItem[];
+    /** Donut centre (pie + innerRadius), for a centre total label. */
+    donut: {
+        cx: number;
+        cy: number;
+        r: number;
+        total: number;
+    } | null;
+    /** Horizontal reference / target lines. */
+    referenceLines: ChartRefLineGeo[];
+    /** Scatter / bubble points (type === 'scatter'). */
+    scatterPoints: ChartScatterDot[];
+    /** Bar orientation. `'horizontal'` uses `valueTicks` / `catTicks` below. */
+    orientation: 'vertical' | 'horizontal';
+    /** Horizontal bars: value-axis ticks along the bottom (label + x). */
+    valueTicks: ChartCategoryTick[];
+    /** Horizontal bars: category labels down the left (label + y; value = index). */
+    catTicks: ChartAxisTick[];
+    /** Horizontal bars: vertical reference / target lines (positioned by x). */
+    referenceLinesV: ChartRefLineGeoV[];
+    /** Trend / moving-average overlay lines (parallel to `lines`). Drawn
+     *  dashed on top of their source series. */
+    overlays: ChartLine[];
+    /** Pinned annotation labels with pre-resolved screen coordinates. */
+    annotations: Array<{
+        x: number;
+        y: number;
+        label: string;
+        color: string;
+        placement: 'top' | 'bottom' | 'left' | 'right';
+        shape: 'dot' | 'flag' | 'pin' | 'square';
+        text?: string;
+    }>;
+    /** Reader drawings resolved to pixels (cartesian charts). */
+    drawings: ChartDrawingGeo[];
+    /** Series names at the lines' last points (`spec.seriesLabels`). */
+    seriesLabels: ChartSeriesLabel[];
+    /** Heatmap cells (type === 'heatmap'). */
+    heatmapCells: ChartHeatmapCell[];
+    /** Heatmap row labels with pre-resolved y positions (left gutter). */
+    heatmapRowTicks: ChartAxisTick[];
+    /** Heatmap column labels (bottom of plot). */
+    heatmapColTicks: ChartCategoryTick[];
+    /** Heatmap color-scale legend: ordered stops with value + color. */
+    heatmapLegend: Array<{
+        value: number;
+        color: string;
+        label: string;
+    }>;
+    /** Funnel segments (type === 'funnel'). */
+    funnelSegments: ChartFunnelSegment[];
+    /** Radar concentric grid rings (centred at `radarCenter`). */
+    radarRings: number[];
+    /** Radar axis labels + spoke endpoints. */
+    radarAxes: ChartRadarAxis[];
+    /** Radar series polygons. */
+    radarSeries: ChartRadarSeries[];
+    /** Centre of the radar / pie. Pre-computed so callers don't re-derive. */
+    radarCenter: {
+        cx: number;
+        cy: number;
+        r: number;
+    } | null;
+    /** Tree-map cells (type === 'treemap'). */
+    treemapCells: ChartTreemapCell[];
+    /** Calendar heatmap (type === 'calendar'). */
+    calendarCells: ChartCalendarCell[];
+    /** Calendar month labels along the top. */
+    calendarMonthTicks: ChartCategoryTick[];
+    /** Calendar legend stops (sequential ramp). */
+    calendarLegend: Array<{
+        value: number;
+        color: string;
+        label: string;
+    }>;
+    /** Gauge layout (type === 'gauge'). Null when not a gauge. */
+    gauge: ChartGaugeLayout | null;
+    /** Sankey nodes (type === 'sankey'). */
+    sankeyNodes: ChartSankeyNode[];
+    /** Sankey links (type === 'sankey'). */
+    sankeyLinks: ChartSankeyLink[];
+};
+/** An axis range rounded to human-friendly bounds and tick spacing. */
+export type NiceScale = {
+    min: number;
+    max: number;
+    step: number;
+    ticks: number[];
+};
+/** The scale functions for a laid-out cartesian chart. See {@link chartScales}. */
+export type ChartScales = {
+    /** Pixel x at the centre of category `i`. Fractional indices interpolate,
+     *  so `xOf(2.5)` is the midpoint between the third and fourth categories. */
+    xOf: (index: number) => number;
+    /** Pixel y for a value on the left axis (or the right, when asked). Returns
+     *  NaN for a value the axis cannot express, e.g. zero on a log scale. */
+    yOf: (value: number, axis?: 'left' | 'right') => number;
+    /** The inverse of `xOf`: which category a pixel x falls on. Clamped. */
+    xInvert: (px: number) => number;
+    /** The inverse of `yOf`. */
+    yInvert: (px: number, axis?: 'left' | 'right') => number;
+    /**
+     * Pixel x for a VALUE on the x axis: a timestamp or ISO date on a time axis,
+     * a number on a numeric axis, a category label on a category axis. NaN when
+     * the value cannot be placed (an unknown label, a non-date on a time axis).
+     */
+    xOfValue: (value: number | string | Date) => number;
+    /** The inverse of `xOfValue`: the data-space x under a pixel. On a category
+     *  axis this is the (fractional) category index. */
+    xInvertValue: (px: number) => number;
+};
+/** Value-axis / tooltip / label number format. */
+export type ChartValueFormat = 'number' | 'currency' | 'percent' | 'compact';
+/** Locale-aware formatting options, a structural subset of `ChartSpec` so a
+ *  caller inside the engine can pass the spec straight through. */
+export type ChartFormatLocale = {
+    locale?: string | ReadonlyArray<string>;
+    currency?: string;
+};
+/** @internal A series after colour, kind and axis are resolved. */
+export type ResolvedSeries = ChartSeries & {
+    color: string;
+    kind: 'bar' | 'line' | 'area' | 'candle' | 'box' | 'scatter' | 'range-bar' | 'range-area' | 'lollipop' | 'dumbbell';
+    axis: 'left' | 'right';
+};
+/**
+ * @internal What every family layout receives from `buildChart`: the spec,
+ * the resolved series, the frame and an `empty` geometry to spread into.
+ */
+export type LayoutCtx = {
+    spec: ChartSpec;
+    theme: 'light' | 'dark';
+    width: number;
+    height: number;
+    palette: string[];
+    stacked: boolean;
+    series: ResolvedSeries[];
+    legend: ChartLegendItem[];
+    empty: ChartGeometry;
+    /** Title / subtitle / caption room, already measured. Every family adds
+     *  `frame.top` to its top pad and `frame.bottom` to its bottom pad. */
+    frame: ChartFrame;
+    /** The three axes with the flat spec shortcuts folded in. */
+    axes: ResolvedAxes;
+};
+/** @internal One axis after `resolveAxes` filled in the defaults. */
+export type ResolvedAxis = ChartAxisConfig & {
+    type: 'category' | 'time' | 'ordinal-time' | 'number';
+    scale: 'linear' | 'log';
+    gridLines: boolean;
+    labels: boolean;
+    nice: boolean;
+    reversed: boolean;
+};
+/** @internal The x, left and right axes a layout reads. */
+export type ResolvedAxes = {
+    x: ResolvedAxis;
+    y: ResolvedAxis;
+    y2: ResolvedAxis;
+};
+/**
+ * The visible category window of a zoomed chart: inclusive indices into the
+ * spec's categories, plus an optional value-axis window for y zoom. `null`
+ * (where a window is expected) means the whole chart.
+ */
+export type ChartZoomWindow = {
+    i0: number;
+    i1: number;
+    /** A value-axis window, when the zoom gesture covered the y axis too. */
+    y?: {
+        min: number;
+        max: number;
+        axis?: 'left' | 'right';
+    };
+};
+/** A point on a chart, addressed by its category and series: what
+ *  `selected` holds and what a selection change reports. `index` is the
+ *  category's position when the chart can tell repeated labels apart (a bar
+ *  under a grouped axis); two refs with an index match only on the same one. */
+export type ChartPointRef = {
+    category: string;
+    series: string;
+    index?: number;
+};