@svgrid/grid 3.0.1 → 3.0.3

package/dist/chart.d.ts

@@ -1,14 +1,27 @@
-/**
- * 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.
- *
- * 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 type ChartType = 'bar' | 'line' | 'area' | 'pie' | 'scatter' | 'heatmap' | 'waterfall' | 'funnel' | 'radar' | 'calendar' | 'gauge' | 'treemap' | 'sankey';
+/** 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
@@ -40,7 +53,43 @@ export type ChartSeries = {
     values: number[];
     color?: string;
     /** Per-series chart type, for combo charts. Defaults to the spec `type`. */
-    type?: 'bar' | 'line' | 'area';
+    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'`). */
@@ -114,6 +163,16 @@ export type ChartSpec = {
     /** 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). */
@@ -135,8 +194,18 @@ export type ChartSpec = {
     innerRadius?: number;
     /** Horizontal target / goal / average lines. */
     referenceLines?: ChartReferenceLine[];
-    /** Treat `categories` as dates -> time-scaled x positions + date ticks. */
-    xType?: 'category' | 'time';
+    /**
+     * 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;
@@ -203,6 +272,13 @@ export type ChartSpec = {
         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'`. */
@@ -367,6 +443,95 @@ export type ChartHeatmapCell = {
     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.
+ *
+ * Returns `null` for an empty sample, so a category with no observations is a
+ * gap rather than a box drawn at zero.
+ */
+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;
@@ -467,7 +632,41 @@ export type ChartGeometry = {
         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[];
@@ -580,6 +779,37 @@ export declare function pickContrastText(bgHex: string): string;
  *  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;
+};
+/**
+ * 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.
+ */
+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. */
@@ -604,19 +834,62 @@ export declare function computeOverlay(values: number[], spec: SeriesOverlay): n
 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;
+};
 /**
  * Format a numeric value for display, honouring an optional `valueFormat`.
- * Builds on the compact `1.2k` / `1.2M` base: currency prefixes `$` (sign
- * outside), percent multiplies by 100 and suffixes `%`. Unset / `'number'` /
- * `'compact'` = the plain compact form.
+ *
+ * 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.
  */
-export declare function formatChartValue(n: number, format?: ChartValueFormat): string;
+export declare function ordinalDateTicks(times: number[], target?: number): number[];
 /**
  * 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;
+/**
+ * Narrow a spec to the category window `[lo, hi]`, keeping every
+ * category-parallel array in step.
+ *
+ * This is the zoom / brush slice. It lives here rather than in the renderer
+ * because getting it wrong is a MODEL bug, not a paint bug, and it was wrong:
+ * the component used to slice `categories`, `values` and `rowIds` by hand and
+ * spread the rest of the series through untouched. `upperValues` and
+ * `lowerValues` therefore kept their full length, the equality guard on the
+ * confidence band (see `buildChart`) stopped matching, and the band silently
+ * disappeared the moment anyone zoomed.
+ *
+ * The lesson generalises: every array here is indexed by category, so each one
+ * added in future has to be sliced too. Keeping them in one function is what
+ * makes that a single place to remember rather than a scattered convention.
+ */
+export declare function sliceChartWindow(spec: ChartSpec, lo: number, hi: number): ChartSpec;
 /**
  * Aggregate flat rows into a chart spec. Group by a category field, reduce a
  * value field per group. Three multi-series shapes:
@@ -649,3 +922,122 @@ export declare function rowsToChartSpec<T extends Record<string, unknown>>(rows:
      *  the source rows. */
     idField?: keyof T & string;
 }): ChartSpec;
+/**
+ * Reshape an aggregated spec into a tree-map hierarchy.
+ *
+ * One series gives a flat set of leaves. Several (a split-by) give two levels,
+ * category above series, which is the shape people expect from "sales by
+ * region, split by channel".
+ */
+export declare function specToTreemap(spec: ChartSpec, rootName?: string): TreeNode;
+/**
+ * Reshape an aggregated spec into calendar samples.
+ *
+ * Categories that do not parse as a date are dropped rather than rendered at
+ * epoch zero, which would put a stray cell in 1970 and rescale the whole year.
+ */
+export declare function specToCalendar(spec: ChartSpec): Array<{
+    date: string;
+    value: number;
+}>;
+/**
+ * Reshape a pivoted spec into sankey nodes and links.
+ *
+ * The pivot `rowsToChartSpec` already performs is exactly an edge list read
+ * sideways: categories are sources, series are targets, and each cell is the
+ * flow between them. Zero cells and self-edges are dropped, the first because
+ * a zero-width ribbon is not a flow and the second because the layout has no
+ * meaningful place to put one.
+ */
+export declare function specToSankey(spec: ChartSpec): {
+    nodes: Array<{
+        id: string;
+        label?: string;
+    }>;
+    links: Array<{
+        source: string;
+        target: string;
+        value: number;
+    }>;
+};
+/**
+ * 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
+ * `rowsToChartSpec` and its reduce / sort / topN / "Other" pipeline.
+ *
+ * One entry point rather than a branch per type in the caller, because the
+ * caller is the grid controller and the controller is in the BASE bundle: every
+ * type named there is bytes paid by grids that never chart. Here it is in the
+ * lazy chart chunk, next to the builders it dispatches to, and adding a fourth
+ * direct type costs a grid nothing.
+ */
+export declare function rowsToDirectSpec<T extends Record<string, unknown>>(type: ChartType, rows: ReadonlyArray<T>, opts: {
+    category?: string;
+    /** The measure. For scatter this is X. */
+    value?: string;
+    /** Scatter's Y measure. */
+    value2?: string;
+    series?: string;
+    reduce?: 'sum' | 'avg' | 'count';
+    palette?: string[];
+}): ChartSpec | null;
+/**
+ * Build a box plot spec straight from rows: group by a category, then reduce
+ * each group to a five-number summary.
+ *
+ * This is the one aggregate the panel's `sum | avg | count` cannot express, and
+ * that is the point of it. Every other chart answers "how much"; a box plot
+ * answers "how spread out", which needs the whole sample per group rather than
+ * one number, so it cannot go through `rowsToChartSpec`.
+ *
+ * `values` comes out as the medians, so tooltips, CSV and overlays work with no
+ * box-specific code - the same contract `ohlc` follows.
+ */
+export declare function rowsToBoxSpec<T extends Record<string, unknown>>(rows: ReadonlyArray<T>, opts: {
+    category: keyof T & string;
+    value: keyof T & string;
+    /** One box series per distinct value of this field, side by side. */
+    series?: keyof T & string;
+    seriesLabel?: string;
+    /** Whisker length in IQRs. Default 1.5. */
+    whisker?: number;
+    width?: number;
+    height?: number;
+}): ChartSpec;
+/**
+ * Build a scatter / bubble spec straight from rows.
+ *
+ * Unlike the adapters above this cannot reuse `rowsToChartSpec`: a scatter
+ * point is one row, not one group, so there is nothing to reduce. `series`
+ * colours the points by a categorical field.
+ */
+export declare function rowsToScatterSpec<T extends Record<string, unknown>>(rows: ReadonlyArray<T>, opts: {
+    x: keyof T & string;
+    y: keyof T & string;
+    /** Bubble radius field. Omit for a plain scatter. */
+    r?: keyof T & string;
+    /** Group points into one series per distinct value. */
+    series?: keyof T & string;
+    /** Per-point label, shown in the tooltip. */
+    label?: keyof T & string;
+    palette?: string[];
+    width?: number;
+    height?: number;
+}): ChartSpec;
+/**
+ * Reduce rows to the single number a gauge shows.
+ *
+ * There is no category axis here, which is why this cannot go through
+ * `rowsToChartSpec`. The dial ends on a nice round number rather than exactly
+ * the value, so the needle never sits pinned at the far end of the arc.
+ */
+export declare function rowsToGaugeSpec<T extends Record<string, unknown>>(rows: ReadonlyArray<T>, opts: {
+    value: keyof T & string;
+    reduce?: 'sum' | 'avg' | 'count';
+    min?: number;
+    max?: number;
+    unit?: string;
+    target?: number;
+    width?: number;
+    height?: number;
+}): ChartSpec;