@svgrid/grid 3.0.2 → 3.0.4

package/dist/chart.d.ts

@@ -1,878 +1,53 @@
-/** 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';
-/** 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) */
-export type SeriesOverlay = 'linear' | `sma:${number}` | `ema:${number}`;
-/** 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' | 'candlestick' | 'ohlc' | 'boxplot';
-    /**
-     * 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>;
-    /**
-     * 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[];
-};
-/** 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';
-};
-/** A horizontal reference / target line drawn across the plot. */
-export type ChartReferenceLine = {
-    value: number;
-    label?: string;
-    axis?: 'left' | 'right';
-    color?: string;
-    dashed?: boolean;
-};
-/**
- * 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';
-    /** 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';
-    /** Pinned text labels at fixed data-space positions (callouts). */
-    annotations?: ChartAnnotation[];
-    /** 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 that
-     *  reset the running sum and span from 0. 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;
-    };
-    /** 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;
-    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;
-};
 /**
- * Five-number summary of a raw sample, with the 1.5 IQR whisker rule.
- *
- * Whiskers stop at the last observation INSIDE the fence rather than at the
- * fence itself, which is what makes them read as real data; anything past them
- * comes back in `outliers`. Quartiles use linear interpolation between the two
- * neighbouring order statistics.
+ * Integrated chart geometry. Pure functions that turn categories + numeric
+ * series into SVG primitives - the "chart from a grid range" enterprise
+ * feature without bundling a charting library. The `<SvGridChart>` component
+ * paints the result; this module has no DOM so it is unit-testable.
  *
- * Returns `null` for an empty sample, so a category with no observations is a
- * gap rather than a box drawn at zero.
+ * Supports: grouped + stacked bars, line, area, pie/donut, combo charts
+ * (per-series type), a secondary (right) Y axis, signed Y domains (negative
+ * values drop below a zero baseline), and nice auto-scaled ticks.
  */
-export declare function boxStats(sample: ReadonlyArray<number>, whisker?: number): BoxStats | null;
-/** 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;
-};
-/** 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;
-};
-/** 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;
-};
-/** 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;
-};
-/** 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;
-};
-/** A vertical reference line (horizontal bar charts) positioned by `x`. */
-export type ChartRefLineGeoV = {
-    x: number;
-    label: string;
-    color: string;
-    dashed: boolean;
-};
-/** 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;
-};
+import type { ChartResponsiveRule, ChartStyle, ChartGeometry, ChartMarkerShape, ChartReducer, ChartSpec, ChartType, ChartValueFormat, TreeNode } from './chart-types.js';
+import { type ChartTimeBucket } from './chart-stats.js';
+export type * from './chart-types.js';
+export { DEFAULT_PALETTE, formatChartValue, niceLogScale, niceScale, ordinalDateTicks, pickContrastText, sampleGradient, } from './chart-scale.js';
+export { chartScales } from './chart-axes.js';
+export { decimateSpec, lttb, minMaxIndices, pickCategories, PER_CATEGORY_SERIES_KEYS, PER_CATEGORY_SPEC_KEYS } from './chart-decimate.js';
+export { buildLinePath, layoutDataLabels, markerPath, streamBaseline, type ChartDataLabel } from './chart-cartesian.js';
+export { arcPath } from './chart-polar.js';
+export { pivotResultToChartSpec, pivotChartType, pivotFilterColumn, bucketsToChartSpec, type PivotResultChartOptions, type PivotResultLike } from './chart-pivot.js';
+export { heikinAshi, resampleOhlc, rowsToOhlcSpec, guessOhlcColumns, splitPanelIndicators, ohlcDirectOptions, type OhlcColumns, type ChartPanelIndicator } from './chart-financial.js';
+export { binValues, boxStats, bucketStart, percentile, reduceValues, type ChartBins, type ChartTimeBucket, exponentialMovingAverage, linearTrend, linearFit, polynomialFit, exponentialFit, logarithmicFit, powerFit, rSquared, pearson, type RegressionFit, simpleMovingAverage, } from './chart-stats.js';
+export { computeOverlay, computeOverlayFit, regressionFit, overlayName, bollingerBands, rsi, macd, vwap, atr, stochastic, wma, obv, indicatorPane, type ChartIndicatorSpec, } from './chart-indicators.js';
 /**
- * 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.
+ * The CSS custom properties `spec.style` sets on the chart's host, as one
+ * inline style string (empty when nothing is set). `background` becomes the
+ * chart's `--sg-bg` (exports read it as the page colour), `textColor` the
+ * text tokens, `gridColor` the border token, `fontSize` a scale every label
+ * multiplies (12px is 1), and `fontFamily` the host's font.
  */
-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;
-        };
-        /** The right axis, when a series is plotted against one. */
-        y2: {
-            min: number;
-            max: number;
-            log: boolean;
-        } | null;
-        /** Horizontal room per category, in px. */
-        slot: number;
-        /** Number of categories the axis was laid out for. */
-        count: number;
-    } | null;
-    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[];
-    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;
-    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';
-    }>;
-    /** 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[];
-};
-/** Series colours used when a {@link ChartSeries} sets none, in order. */
-export declare const DEFAULT_PALETTE: string[];
-/** An axis range rounded to human-friendly bounds and tick spacing. */
-export type NiceScale = {
-    min: number;
-    max: number;
-    step: number;
-    ticks: number[];
-};
-/** Sample a hex color from an array of hex stops at fractional position t.
- *  Linearly interpolates between the two nearest stops in RGB space. */
-export declare function sampleGradient(stops: string[], t: number): string;
-/** Pick a black or white text color that has the better contrast against
- *  the given background. Uses the WCAG relative-luminance heuristic. */
-export declare function pickContrastText(bgHex: string): string;
-/** Pick the largest power of 10 that fits at the bottom of [min,max], and
- *  the smallest that covers the top, then enumerate decade boundaries. Used
- *  by log-scale axes (yScale: 'log'). */
-export declare function niceLogScale(min: number, max: number): NiceScale;
-/** 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;
-};
+export declare function chartStyleVars(style: ChartStyle | undefined): string;
 /**
- * Turn a laid-out chart's axes into functions, so a caller can draw its own
- * marks in the same coordinates the built-in ones use.
- *
- * This is the custom-series seam. Rather than a registry of mark types, the
- * chart hands over its geometry and its scales and lets the caller render
- * whatever SVG it likes into the plot - which is the Svelte-shaped answer, and
- * means a custom mark is ordinary markup rather than a plugin.
- *
- * Deriving the scale from `geo.axes` matters: the domain a chart drew against
- * is the NICE-ROUNDED one, stretched to include zero for bar charts and any
- * reference lines. Recomputing it from the data outside would land custom marks
- * a few pixels off the built-in ones, in a way that looks like a rendering bug.
- *
- * Returns `null` for a chart with no cartesian axes (pie, gauge, treemap,
- * sankey, calendar, radar, funnel), where plot coordinates mean nothing.
+ * The responsive rules that apply at a rendered size, in spec order. Pure:
+ * `SvChart` uses it for the legend field, {@link resolveResponsive} for the
+ * spec patches.
  */
-export declare function chartScales(geo: ChartGeometry): ChartScales | null;
-/** Build an SVG path from a list of (x,y) pairs, optionally smoothed via
- *  monotone cubic interpolation (preserves local extrema - no overshoots).
- *  Breaks the path at `defined === false` gaps. */
-export declare function buildLinePath(pts: Array<{
-    x: number;
-    y: number;
-    defined: boolean;
-}>, smooth: boolean): string;
-/** Ordinary least-squares regression on (i, values[i]) pairs (i = x index).
- *  Returns the fitted value at each x index, or NaN where the source value
- *  was non-finite. */
-export declare function linearTrend(values: number[]): number[];
-/** Simple moving average over a window of `period` values. Window centres
- *  trail to the right (typical for time-series). NaN for points before the
- *  window is full. */
-export declare function simpleMovingAverage(values: number[], period: number): number[];
-/** Exponential moving average. Smoothing factor alpha = 2 / (period + 1). */
-export declare function exponentialMovingAverage(values: number[], period: number): number[];
-/** Compute overlay values for a series spec like 'sma:7' / 'ema:14' / 'linear'. */
-export declare function computeOverlay(values: number[], spec: SeriesOverlay): number[];
-/** Round a [min,max] domain out to nice tick boundaries. */
-export declare function niceScale(min: number, max: number, tickCount?: number): NiceScale;
-/** 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;
-};
+export declare function matchResponsiveRules(rules: ChartResponsiveRule[] | undefined, width: number, height: number): ChartResponsiveRule[];
 /**
- * Format a numeric value for display, honouring an optional `valueFormat`.
- *
- * Two modes, on purpose. With no `locale` and no `currency` this is the original
- * locale-free output: the compact `1.2k` / `1.2M` base, currency prefixed with
- * `$` (sign outside), percent multiplied by 100 and suffixed `%`. Set either one
- * and it switches to `Intl.NumberFormat`, so separators, the decimal mark and the
- * compact suffixes all follow the locale.
- *
- * Keeping the old path as the default is deliberate rather than lazy. `Intl`'s
- * compact notation is not the same string even for `en-US` (`1.2K`, capital),
- * so formatting everything through it would silently restyle every axis in every
- * existing chart. Opting in is the only version of this that is not a surprise.
- */
-export declare function formatChartValue(n: number, format?: ChartValueFormat, opts?: ChartFormatLocale): string;
-/**
- * Tick positions for an ordinal (evenly spaced) date axis, as INDICES into
- * `times`.
- *
- * A time axis can put a tick anywhere, because x is a function of the
- * timestamp. An ordinal axis cannot: x is a function of the index, so a tick
- * has to land on a point that exists. This picks the first point of each
- * calendar unit - day, week, month, year, whichever gets closest to `target`
- * ticks without going over - so labels sit on real sessions and a weekend or a
- * holiday never stretches the spacing.
+ * Apply `spec.responsive` for a rendered size: every matching rule's `spec`
+ * is merged over the input in order (later wins), the three axis objects one
+ * level deep. Returns the input itself when nothing matches, so callers can
+ * compare by identity. `width`, `height` and `responsive` in a rule are
+ * ignored; the size is the caller's.
  */
-export declare function ordinalDateTicks(times: number[], target?: number): number[];
+export declare function resolveResponsive(spec: ChartSpec, width: number, height: number): ChartSpec;
 /**
  * Lay out a {@link ChartSpec} into renderable {@link ChartGeometry} - scales,
  * ticks, and the position of every bar, line, slice and dot. Pure: no DOM, so
  * it runs during SSR and can be unit-tested directly.
  */
-export declare function buildChart(spec: ChartSpec, theme?: 'light' | 'dark'): ChartGeometry;
+export declare function buildChart(input: ChartSpec, theme?: 'light' | 'dark'): ChartGeometry;
 /**
  * Narrow a spec to the category window `[lo, hi]`, keeping every
  * category-parallel array in step.
@@ -904,14 +79,25 @@ export declare function rowsToChartSpec<T extends Record<string, unknown>>(rows:
     value: (keyof T & string) | Array<keyof T & string>;
     /** Pivot dimension: one series per distinct value of this field. */
     series?: keyof T & string;
-    reduce?: 'sum' | 'avg' | 'count';
+    /** How each group collapses to one number. Default `'sum'`. See
+     *  {@link ChartReducer} for the full list (min, max, median, p90, ...). */
+    reduce?: ChartReducer;
+    /**
+     * Group a date category by calendar unit instead of by exact value:
+     * `'month'` files every row of March under `2026-03-01`. Categories come
+     * out as ISO dates in chronological order and the spec's x axis is set to
+     * `'ordinal-time'`, so the ticks read as dates. Rows whose category does
+     * not parse as a date are dropped.
+     */
+    bucket?: ChartTimeBucket;
     seriesLabel?: string;
     width?: number;
     height?: number;
     stacked?: boolean;
     stacked100?: boolean;
     palette?: string[];
-    /** Order categories. Defaults to insertion order (or value-desc when topN). */
+    /** Order categories. Defaults to insertion order (or value-desc when topN,
+     *  or chronological when bucketed). */
     sort?: 'value-desc' | 'value-asc' | 'category' | 'none';
     /** Keep only the top N categories; bucket the rest into "Other". */
     topN?: number;
@@ -922,6 +108,49 @@ export declare function rowsToChartSpec<T extends Record<string, unknown>>(rows:
      *  the source rows. */
     idField?: keyof T & string;
 }): ChartSpec;
+/**
+ * The bar-plus-line spec a pareto chart draws: categories sorted by value,
+ * bars for the values, and a cumulative-share line on the right axis pinned to
+ * 0..100 with a reference line at `threshold` (default 80, the "vital few").
+ * `buildChart` calls this for `type: 'pareto'`; call it yourself to get at the
+ * spec, or pass a ready spec whose first series is the values.
+ */
+export declare function paretoSpec(spec: ChartSpec, threshold?: number): ChartSpec;
+/**
+ * Bin one numeric field of the rows into a histogram spec. The categories are
+ * the bin midpoints on a numeric axis and `binEdges` labels the edges, so the
+ * bars touch and the axis reads `0, 10, 20` rather than `5, 15, 25`.
+ * `series` splits the sample into one histogram per distinct value.
+ */
+export declare function rowsToHistogramSpec<T extends Record<string, unknown>>(rows: ReadonlyArray<T>, opts: {
+    value: keyof T & string;
+    series?: keyof T & string;
+    seriesLabel?: string;
+    bins?: number;
+    binWidth?: number;
+    method?: 'sturges' | 'fd' | 'sqrt';
+    min?: number;
+    max?: number;
+    palette?: string[];
+    width?: number;
+    height?: number;
+}): ChartSpec;
+/**
+ * A range (floating) bar or area spec from rows: one row per category with a
+ * low field and a high field, e.g. a day's low and high temperature, or a
+ * salary band. `series` splits into one range per distinct value.
+ */
+export declare function rowsToRangeSpec<T extends Record<string, unknown>>(rows: ReadonlyArray<T>, opts: {
+    type?: 'range-bar' | 'range-area';
+    category: keyof T & string;
+    low: keyof T & string;
+    high: keyof T & string;
+    series?: keyof T & string;
+    seriesLabel?: string;
+    palette?: string[];
+    width?: number;
+    height?: number;
+}): ChartSpec;
 /**
  * Reshape an aggregated spec into a tree-map hierarchy.
  *
@@ -960,6 +189,83 @@ export declare function specToSankey(spec: ChartSpec): {
         value: number;
     }>;
 };
+/**
+ * What the grid panel's chart builder lets a reader change about the LOOK of
+ * a chart, as plain data so it can be saved with the view and applied to the
+ * spec the panel derives on every data change. Every field is optional and
+ * additive; an absent field leaves the derived spec alone. Series are keyed
+ * by label, so a per-series colour survives a re-sort of the categories.
+ */
+export type ChartFormatState = {
+    title?: string;
+    subtitle?: string;
+    caption?: string;
+    /** Where the legend goes; `false` hides it. The panel reads this for the
+     *  component prop, it is not a spec field. */
+    legend?: 'top' | 'bottom' | 'left' | 'right' | false;
+    xAxis?: {
+        title?: string;
+        gridLines?: boolean;
+        labelRotation?: number | 'auto';
+    };
+    yAxis?: {
+        min?: number | null;
+        max?: number | null;
+        title?: string;
+        gridLines?: boolean;
+        format?: ChartValueFormat;
+    };
+    y2Axis?: {
+        min?: number | null;
+        max?: number | null;
+        title?: string;
+        gridLines?: boolean;
+        format?: ChartValueFormat;
+    };
+    /** Per-series overrides, keyed by series label. */
+    series?: Record<string, {
+        color?: string;
+        type?: 'bar' | 'line' | 'area';
+        axis?: 'left' | 'right';
+        marker?: ChartMarkerShape;
+        strokeWidth?: number;
+        dash?: string;
+        smooth?: boolean;
+        /** The stack group a bar or area joins; an empty string leaves the
+         *  group. See {@link ChartSeries.stack}. */
+        stack?: string;
+    }>;
+    /** Where data labels sit; `null` hides them. */
+    dataLabels?: 'inside' | 'outside' | 'top' | 'center' | null;
+    palette?: string[] | null;
+    /** Series names at the end of each line (`spec.seriesLabels`). */
+    seriesLabels?: boolean;
+    /** The axis value pills on the crosshair. A component prop, like
+     *  `legend`: the panel reads it, the engine does not. */
+    crosshairLabels?: boolean;
+    /** Below this rendered width in px the chart goes compact: no series or
+     *  data labels, vertical category labels, no legend. Appended to the
+     *  spec's own `responsive` rules as {@link CHART_RESPONSIVE_PRESETS}.compact. */
+    compactBelow?: number | null;
+    /** Font, size and colours for the whole chart (`spec.style`), merged
+     *  over what the spec carries. */
+    style?: ChartStyle;
+};
+/**
+ * Responsive rules the builder offers by name. `compact(maxWidth)` is the
+ * one the Format tab writes through `compactBelow`: the labels that crowd a
+ * narrow chart go, the category labels turn vertical, and the legend hides.
+ */
+export declare const CHART_RESPONSIVE_PRESETS: {
+    readonly compact: (maxWidth: number) => ChartResponsiveRule;
+};
+/**
+ * Apply a {@link ChartFormatState} to a spec: a new spec with the titles,
+ * axis settings, palette and per-series styling merged in. Pure, so the
+ * panel can run it on every derived spec and a saved format keeps applying
+ * to fresh data. Unknown series labels are ignored.
+ */
+export declare function applyChartFormat(spec: ChartSpec, format: ChartFormatState | null | undefined): ChartSpec;
 /**
  * The chart types that read ROWS directly instead of a grouped grid, behind one
  * call. Returns `null` for every other type, which then goes through
@@ -978,8 +284,23 @@ export declare function rowsToDirectSpec<T extends Record<string, unknown>>(type
     /** Scatter's Y measure. */
     value2?: string;
     series?: string;
-    reduce?: 'sum' | 'avg' | 'count';
+    reduce?: ChartReducer;
     palette?: string[];
+    /** Histogram: how many bins. Default: Sturges' rule. */
+    bins?: number;
+    /** Candlestick / OHLC: the price columns, an optional volume, a calendar
+     *  bucket to roll the bars up to, and the candle style. `category` is
+     *  the date column. */
+    ohlc?: {
+        open: string;
+        high: string;
+        low: string;
+        close: string;
+        volume?: string;
+        bucket?: ChartTimeBucket;
+        candleStyle?: ChartSpec['candleStyle'];
+        lastPriceLine?: boolean;
+    };
 }): ChartSpec | null;
 /**
  * Build a box plot spec straight from rows: group by a category, then reduce
@@ -1033,7 +354,7 @@ export declare function rowsToScatterSpec<T extends Record<string, unknown>>(row
  */
 export declare function rowsToGaugeSpec<T extends Record<string, unknown>>(rows: ReadonlyArray<T>, opts: {
     value: keyof T & string;
-    reduce?: 'sum' | 'avg' | 'count';
+    reduce?: ChartReducer;
     min?: number;
     max?: number;
     unit?: string;