@svgrid/grid 1.0.2 → 1.1.0

package/dist/chart.d.ts

@@ -8,12 +8,16 @@
  * (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';
-/** A clicked bar / point / slice - the payload of `SvGridChart`'s `onSelect`. */
+export type ChartType = 'bar' | 'line' | 'area' | 'pie' | 'scatter' | 'heatmap' | 'waterfall' | 'funnel' | 'radar' | 'calendar' | 'gauge' | 'treemap' | 'sankey';
+/** 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 = {
@@ -22,6 +26,14 @@ export type ScatterPoint = {
     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';
 export type ChartSeries = {
     label: string;
     values: number[];
@@ -32,6 +44,44 @@ export type ChartSeries = {
     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 = {
@@ -71,6 +121,231 @@ export type ChartSpec = {
     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;
+    };
+    /** 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;
 };
 export type ChartBar = {
     x: number;
@@ -98,6 +373,9 @@ export type ChartLine = {
     color: string;
     label: string;
     points: ChartLinePoint[];
+    /** Confidence-band path (between upperValues + lowerValues) for this
+     *  series, when both arrays are supplied. Empty otherwise. */
+    bandPath?: string;
 };
 export type ChartPieSlice = {
     path: string;
@@ -185,6 +463,61 @@ export type ChartGeometry = {
     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[];
 };
 export declare const DEFAULT_PALETTE: string[];
 export type NiceScale = {
@@ -193,9 +526,39 @@ export type NiceScale = {
     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;
+/** 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. */
+/** 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;
+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;
-export declare function buildChart(spec: ChartSpec): ChartGeometry;
+export declare function buildChart(spec: ChartSpec, theme?: 'light' | 'dark'): ChartGeometry;
 /**
  * Aggregate flat rows into a chart spec. Group by a category field, reduce a
  * value field per group. Three multi-series shapes:
@@ -223,4 +586,8 @@ export declare function rowsToChartSpec<T extends Record<string, unknown>>(rows:
     topN?: number;
     /** Label for the bucketed remainder. Default "Other". */
     otherLabel?: string;
+    /** Field carrying each row's stable id. When set, the resulting spec's
+     *  series carry `rowIds` arrays so click handlers can drill back to
+     *  the source rows. */
+    idField?: keyof T & string;
 }): ChartSpec;