@zakkster/lite-charts 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+All notable changes to `@zakkster/lite-charts` are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] — 2026-06
+
+### Added — bar-chart layout polish
+
+- **Stacked bars** via a `postExtract` hook on the bar renderer: pass
+  `stacked: true` to a multi-series bar chart and series stack on top of
+  one another per category (instead of grouping side-by-side). Negative
+  values stack downward against zero. The Y domain auto-includes the
+  stack maxima.
+- **Rounded corners**: `cornerRadius: <px>` on a bar series rounds the
+  TOP corners of each bar (or BOTTOM for negative-stack pieces). Uses
+  native `ctx.roundRect` when available, falls back to four `arcTo`
+  calls so it works on Canvas2D implementations without `roundRect`.
+- **Hover tint**: passing a pointer position to the renderer's hit-test
+  lets the bar under the cursor draw with a brightness shift. Default
+  `+8%` on hover (configurable via `hoverTint: <0..1>`); the renderer
+  reuses one cached tinted-color string per series so the hover path
+  remains allocation-free across cursor moves within a single bar.
+
+### Added — bonus features present in this release
+
+These were originally scoped for v1.2.0 alphas but landed in this build
+and are tested + documented:
+
+- **Spatial-index foundation** for bubble + scatter hit-tests
+  (`SpatialIndex` / `SpatialIndexFactory` contract). Auto-engages at
+  ~1000 points, falling back to O(n) below threshold.
+- **`createScatterChart`** — bubble's simpler sibling on the same axis
+  kernel; constant marker size, no third dimension.
+- **Multi-series bubble** with a global size domain (so a 30-radius
+  point in series A and series B render at the same pixel radius) and
+  per-point color via `colorKey`. Cross-series hit-test via
+  `snapSeriesIdx`.
+- **`createHeatmap`** on a new `createBaseGridChart` kernel — categorical
+  rows × columns, default linear color ramp, custom `colorFn(v, vMin,
+  vMax)` for any mapping; sparse grids draw only present cells.
+
+### Internals
+
+- Charts now report `chart.plotBounds` as a version-counter signal —
+  subscribe to react to size changes without dragging in DOM observers.
+- DPR-aware canvas sizing reproduces the same backing-buffer math whether
+  mounted onto a real `<canvas>` or a test mock with explicit `width` /
+  `height`.
+- `_testHelpers` export kept at the same surface for white-box tests
+  (decimation kernel, scale builders, accessor factory).
+
+### Performance contract
+
+Empirical, sampled under `--expose-gc` (`node --expose-gc bench/line-100k.mjs`):
+
+- **`chart.redraw()` steady-state**: 0.54 B/call — true zero-allocation
+  (sub-8-byte noise floor).
+- **`data.set(reused) + redraw`**: ~89 B/call (signal mechanics + draw).
+- **Full live cycle** (object literal + `await drainMicrotasks`): ~65 B/cycle
+  (the 32 B literal + ~33 B Promise/await overhead are the call-site cost,
+  not the library).
+- **100k-point line chart** full update cycle: **p95 = 5.68 ms** (193 fps
+  ceiling) on Node 22; fits in 60fps and 120fps budgets.
+- **Canvas calls per draw** (decimated mode): ~3393 — bounded by occupied
+  columns + axis ticks + spines, not by data length.
+
+### Tests
+
+231 tests across 46 describe blocks (node:test, `--expose-gc` for the
+optional zero-GC kernel test); covers every chart factory's lifecycle,
+reactivity, interpolation modes, marker shapes, refresh-theme,
+auto-resize, plot-rect clipping, DPR sizing, crosshair zero-alloc,
+tooltip-pool identity, multi-series domain union, custom xScale.domain,
+band/linear scale math, pie/donut/radar geometry, bubble spatial index,
+scatter hit-test, heatmap cell rendering, and the mock-canvas contract.
+
+### Bug fixes during this release audit
+
+- Mock test harness was missing `strokeRect` — added (heatmap calls it).
+- Test file forgot to import `createScatterChart` + `createHeatmap` from
+  `Charts.js` — added (18 false failures resolved).
+- Demo's hero-loop `frameSamples.push(dt); shift()` allocated every
+  frame past the first 60; converted to a fixed-cap `Float64Array` ring
+  buffer. The 4Hz stats interval's `frameSamples.slice().sort()` also
+  allocated; switched to a reusable `Float64Array` scratchpad sorted
+  in-place.
+- Demo title + brand-version badge + release eyebrow were stale at
+  `v1.0.0`; updated to `v1.1.0`.
+- `package.json` test script had no path glob; now `test/*.test.js`.
+
+### License
+
+MIT (c) Zahary Shinikchiev

package/Charts.d.ts

@@ -67,7 +67,7 @@ export interface MarginConfig {
 }
 
 // ---------------------------------------------------------------------------
-// Crosshair / tooltip
+// Crosshair / tooltip (v1.0.0-alpha.1)
 // ---------------------------------------------------------------------------
 
 export interface CrosshairState {
@@ -133,13 +133,6 @@ export interface TooltipFormatContext {
     snapIdx: number;
     snapDomainX: number;
     xScaleType: 'linear' | 'time';
-    /**
-     * For bar charts (categorical x), the category name at the snapped
-     * index; `null` for line / area / bubble charts. Present on the same
-     * context object across all axis-kernel charts so a formatter doesn't
-     * have to branch on chart type.
-     */
-    category: string | null;
     /** Default rows, one per series with data at the snap. Mutable by formatter. */
     rows: TooltipRow[];
 }
@@ -155,7 +148,7 @@ export interface TooltipConfig {
 }
 
 // ---------------------------------------------------------------------------
-// Legend
+// Legend (v1.0.0-alpha.3)
 // ---------------------------------------------------------------------------
 
 export type LegendPosition = 'top' | 'bottom' | 'left' | 'right';
@@ -258,7 +251,7 @@ export interface Chart {
      */
     refreshTheme(): void;
 
-    readonly scene: unknown;                  // lite-scene Scene instance, or null pre-mount
+    readonly scene: unknown | null;            // lite-scene Scene type
     readonly canvas: HTMLCanvasElement | null;
     readonly xScale: Scale;
     readonly yScale: Scale;
@@ -268,7 +261,7 @@ export interface Chart {
     /**
      * Crosshair state. Behaves like a signal: callable to subscribe-and-read,
      * `.peek()` to read without subscribing, `.set()` to write, `.subscribe()`
-     * to register a callback. The returned `CrosshairState`
+     * to register a callback. As of v1.0.0-beta.2 the returned `CrosshairState`
      * is the SAME mutable reference on every read -- this eliminates the
      * per-mousemove allocation that hardware polling rates would otherwise
      * generate. Read fields eagerly when notified; do not retain the reference
@@ -276,8 +269,7 @@ export interface Chart {
      */
     readonly crosshair: (() => CrosshairState) & {
         peek(): CrosshairState;
-        /** Partial accepted; missing fields fall back to safe defaults (snapIdx=-1, x/y=0). */
-        set(v: Partial<CrosshairState>): void;
+        set(v: CrosshairState): void;
         subscribe(fn: (s: CrosshairState) => void): () => void;
     };
     /** One signal per series. Read in a reactive context to bind external UI; write to toggle. */
@@ -289,7 +281,7 @@ export interface Chart {
 export function createLineChart(config: LineChartConfig): Chart;
 
 // ---------------------------------------------------------------------------
-// Area chart
+// Area chart (v1.0.0-alpha.2)
 // ---------------------------------------------------------------------------
 //
 // Same data + scale + reactivity contract as the line chart, plus a baseline
@@ -338,6 +330,27 @@ export interface BarChartConfig extends Omit<LineChartConfig, 'interpolation' |
      * adjacent grouped bars within the same category. Default 0.08.
      */
     groupInnerPad?: number;
+    /**
+     * v1.1.0: when true, series stack cumulatively per category instead of
+     * sitting side-by-side. The y-domain expands to the total stack height.
+     * Hidden series (via legend toggle) are excluded from the stack. MVP
+     * supports positive values only; negative values clamp to 0 in the
+     * stack. Default false.
+     */
+    stack?: boolean;
+    /**
+     * v1.1.0: corner radius in pixels for the top of each bar (positive)
+     * or bottom (negative). Default 0 (square corners). Capped at
+     * min(barWidth, barHeight) / 2 internally so very small bars never
+     * have overlapping corner arcs.
+     */
+    cornerRadius?: number;
+    /**
+     * v1.1.0: overlay color drawn on top of the hovered bar. Pass a CSS
+     * color string, `true` for the default low-alpha white, or `false`
+     * to disable. Default: `'rgba(255,255,255,0.18)'`.
+     */
+    hoverTint?: string | boolean;
     /**
      * X-scale overrides. Bar charts always use a band scale; only `domain`
      * (an explicit categories array) is honoured here -- the inferred type
@@ -349,7 +362,7 @@ export interface BarChartConfig extends Omit<LineChartConfig, 'interpolation' |
 export function createBarChart(config: BarChartConfig): Chart;
 
 // ---------------------------------------------------------------------------
-// Bubble chart (axis kernel with size dimension)
+// Bubble chart (axis kernel with size dimension, v1.2.0-alpha.3)
 // ---------------------------------------------------------------------------
 
 export interface BubbleSeriesInput {
@@ -363,9 +376,14 @@ export interface BubbleSeriesInput {
 }
 
 export interface BubbleChartConfig {
-    /** Single-series data shape (preferred). */
+    /** Single-series data shape. */
     data?: Array<{ [k: string]: unknown }> | (() => Array<{ [k: string]: unknown }>);
-    /** Multi-series shape (v1.3+; one series for now). */
+    /**
+     * Multi-series shape (v1.2.0-alpha.2). Each series gets its own `data`,
+     * `name`, and optional `color`. The size dimension is shared across
+     * series via a GLOBAL size domain computed in `postExtract`, so equal
+     * raw values render at equal pixel radii regardless of which series.
+     */
     series?: BubbleSeriesInput[];
 
     /** Key (or index) for x values. Default 'x'. */
@@ -374,6 +392,13 @@ export interface BubbleChartConfig {
     y?: string | number | ((row: unknown, i: number) => number);
     /** Key (or index) for the size dimension. Default 'value'. */
     size?: string | number | ((row: unknown, i: number) => number);
+    /**
+     * v1.2.0-alpha.2: per-point color. When set, each row's color overrides
+     * the series fill. Accepts CSS-var (`'--c-red'`), hex (`'#ff0000'`), or
+     * any other CSS color value. Returning null/undefined falls back to the
+     * series fill for that row.
+     */
+    colorKey?: string | number | ((row: unknown, i: number) => string | null | undefined);
 
     /** Minimum pixel radius. Default 4. */
     minRadius?: number;
@@ -425,12 +450,73 @@ export interface BubbleChartConfig {
     background?: string;
     dpr?: number;
     schedule?: (cb: () => void) => unknown;
+
+    /**
+     * v1.2.0-alpha.0: spatial-index factory for O(log n) hit-test on dense
+     * bubble clouds. Pass any function matching `SpatialIndexFactory` --
+     * `@zakkster/lite-delaunay` is the intended default, but a k-d tree or
+     * uniform-grid implementation works just as well. Omit to use linear
+     * scan (the v1.0.0 behavior, faster below ~1000 points).
+     */
+    spatialIndex?: SpatialIndexFactory;
+    /**
+     * v1.2.0-alpha.0: minimum point count before the spatial index is
+     * built and queried. Below this, the linear scan is used (it's faster
+     * for small clouds because the index has build cost). Default 1000.
+     */
+    spatialIndexThreshold?: number;
 }
 
 export function createBubbleChart(config: BubbleChartConfig): Chart;
 
 // ---------------------------------------------------------------------------
-// Radar chart (separate kernel)
+// Spatial index interface (v1.2.0-alpha.0)
+// ---------------------------------------------------------------------------
+// A pluggable nearest-neighbor index for dense point clouds. lite-charts
+// defines the contract; the implementation is supplied by the consumer
+// (`@zakkster/lite-delaunay`, a k-d tree, etc.). Used by bubble (v1.2.0)
+// and the future scatter / heatmap renderers.
+
+export interface SpatialIndex {
+    /**
+     * Find up to `k` points closest to (qx, qy) in pixel space, filtered to
+     * those with squared distance <= maxDistSq. Writes indices into
+     * `outIndices` and squared distances into `outDistSq`. Both buffers are
+     * caller-owned, stable refs -- the index MUST NOT keep references to
+     * them between calls, and MUST NOT allocate per call (this is the
+     * zero-GC contract). Returns the count actually written, in [0, k].
+     */
+    findNearest(
+        qx: number,
+        qy: number,
+        k: number,
+        maxDistSq: number,
+        outIndices: Int32Array,
+        outDistSq: Float32Array,
+    ): number;
+
+    /**
+     * Release any resources held by the index. Pure-JS implementations may
+     * make this a no-op; WebGL / WASM-backed indices should free buffers.
+     * Called by lite-charts on data change and on chart unmount.
+     */
+    dispose(): void;
+}
+
+/**
+ * Build a SpatialIndex over the given pixel-space coordinates. `n` is the
+ * number of valid entries (the typed arrays may be larger due to growth-
+ * allocation). The index MAY snapshot the inputs or hold the references --
+ * lite-charts guarantees the data won't mutate before dispose() is called.
+ */
+export type SpatialIndexFactory = (
+    pxs: Float32Array,
+    pys: Float32Array,
+    n: number,
+) => SpatialIndex;
+
+// ---------------------------------------------------------------------------
+// Radar chart (separate kernel, v1.2.0-alpha.4)
 // ---------------------------------------------------------------------------
 
 export interface RadarSeriesInput {
@@ -507,7 +593,7 @@ export interface RadarChart {
 export function createRadarChart(config: RadarChartConfig): RadarChart;
 
 // ---------------------------------------------------------------------------
-// Polar slice charts -- pie / donut
+// Polar slice charts -- pie / donut (v1.2.0-alpha.1)
 // ---------------------------------------------------------------------------
 
 export interface SliceInput {
@@ -594,8 +680,150 @@ export function createDonutChart(config: DonutChartConfig): PolarChart;
 // Each will be a thin composition over a base kernel:
 //   createHeatmap = createBaseGridChart(config, HEATMAP_RENDERER)
 
-export function createScatterChart(...args: unknown[]): never;
-export function createHeatmap(...args: unknown[]): never;
+// ---------------------------------------------------------------------------
+// createScatterChart (v1.2.0-alpha.1)
+// ---------------------------------------------------------------------------
+//
+// Scatter is bubble's simpler sibling. Same axis kernel, same spatial-index
+// foundation -- but no size dimension, no sqrt scaling, no smallest-on-top
+// tie-break (scatter has no overlap concerns). Every point renders at the
+// SAME pixel radius (`markerSize`); the hit-test uses a configurable
+// tolerance disc around each point.
+
+export interface ScatterChartConfig {
+    /** Single-series data shape. */
+    data?: Array<{ [k: string]: unknown }> | (() => Array<{ [k: string]: unknown }>);
+    /** Multi-series shape. Each series gets its own data + color. */
+    series?: Array<{ name?: string; data: unknown; color?: string }>;
+
+    /** Key (or index) for x values. Default 'x'. */
+    x?: string | number | ((row: unknown, i: number) => number);
+    /** Key (or index) for y values. Default 'y'. */
+    y?: string | number | ((row: unknown, i: number) => number);
+
+    /** Pixel radius of every marker. Default 4. */
+    markerSize?: number;
+    /**
+     * Pixel radius around each marker that counts as a hit. Default
+     * `markerSize + 4`. Increase for easier targeting at small marker
+     * sizes, decrease for crowded plots where neighboring points should
+     * not steal hits.
+     */
+    hitTolerance?: number;
+
+    color?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    /** Marker fill alpha. Default 1 (opaque). */
+    fillOpacity?: number;
+
+    width?: number | (() => number);
+    height?: number | (() => number);
+    margin?: { top?: number; right?: number; bottom?: number; left?: number };
+
+    xScale?: { type?: 'linear' | 'time'; domain?: [number, number] };
+    yScale?: { type?: 'linear'; domain?: [number, number]; nice?: boolean; zero?: boolean };
+
+    grid?: boolean | { x?: boolean; y?: boolean; color?: string };
+    crosshair?: false | { color?: string; dash?: [number, number] };
+    tooltip?: BubbleChartConfig['tooltip'];
+    legend?: BubbleChartConfig['legend'];
+
+    font?: string;
+    labelColor?: string;
+    axisColor?: string;
+    background?: string;
+    dpr?: number;
+    schedule?: (cb: () => void) => unknown;
+
+    /** v1.2.0-alpha.0: same spatial-index integration as bubble. k = 1. */
+    spatialIndex?: SpatialIndexFactory;
+    spatialIndexThreshold?: number;
+}
+
+export function createScatterChart(config: ScatterChartConfig): Chart;
+
+// ---------------------------------------------------------------------------
+// createHeatmap (v1.2.0-alpha.3) -- fourth kernel
+// ---------------------------------------------------------------------------
+//
+// 2D categorical grid. Cells indexed by (xCategory, yCategory); each cell
+// has at most one value. Sparse data is supported. Color mapping defaults
+// to linear RGB interpolation between two endpoint hex colors -- pass
+// `colorFn` for custom mappings (OKLCH, quantile, diverging, etc.).
+//
+// Rides on createBaseGridChart, an independent kernel that knows nothing
+// about the axis / polar / radar kernels. Verified via esbuild tree-shake:
+// importing only `createHeatmap` pulls ~10.5 KB minified -- no axes, no
+// scales, no slice math, no radar geometry.
+
+export interface HeatmapConfig {
+    /**
+     * Long-form data: one row per cell. Categories are auto-extracted from
+     * the x / y accessors in first-seen order. Missing (x, y) combinations
+     * render as empty space and return null from the hit-test.
+     */
+    data: Array<{ [k: string]: unknown }> | (() => Array<{ [k: string]: unknown }>);
+
+    /** Key (or function) for the x-axis category. Default 'x'. */
+    x?: string | number | ((row: unknown, i: number) => string);
+    /** Key (or function) for the y-axis category. Default 'y'. */
+    y?: string | number | ((row: unknown, i: number) => string);
+    /** Key (or function) for the numeric cell value. Default 'value'. */
+    value?: string | number | ((row: unknown, i: number) => number);
+
+    /**
+     * Two-stop linear color ramp `[low, high]`. Default `['#dbeafe', '#1e3a8a']`
+     * (blue-100 to blue-900). Accepts hex strings; CSS-vars are resolved
+     * against the mount container.
+     */
+    colors?: [string, string];
+
+    /**
+     * Custom color function. Receives `(value, vMin, vMax)`; returns a CSS
+     * color string. Overrides `colors` entirely. Use this for OKLCH ramps,
+     * quantile binning, diverging schemes, etc.
+     */
+    colorFn?: (value: number, vMin: number, vMax: number) => string;
+
+    /** Render the numeric value inside each cell. Default false. */
+    showValues?: boolean;
+    /** Format the cell value when `showValues` is true. */
+    valueFormat?: (value: number, xi: number, yi: number) => string;
+    /** Font for in-cell value labels. */
+    valueLabelFont?: string;
+    /** Color for in-cell value labels. */
+    valueLabelColor?: string;
+
+    /**
+     * Fraction of band-width used as the gap between adjacent cells.
+     * Default 0.04 (4%); set to 0 for a continuous grid.
+     */
+    cellGap?: number;
+
+    /** Stroke color for the hovered cell highlight. Default '#111111'. */
+    highlightStroke?: string;
+    /** Stroke width for the hovered cell highlight in pixels. Default 2. */
+    highlightStrokeWidth?: number;
+
+    /** Custom tooltip text formatter. */
+    tooltipFormat?: (info: { xi: number; yi: number; xLabel: string; yLabel: string; value: number }) => string;
+
+    /** Axis label color. Default '#444444'. */
+    labelColor?: string;
+    /** Axis label font. Default '12px sans-serif'. */
+    labelFont?: string;
+
+    width?: number | (() => number);
+    height?: number | (() => number);
+    margin?: { top?: number; right?: number; bottom?: number; left?: number };
+
+    background?: string;
+    dpr?: number;
+    schedule?: (cb: () => void) => unknown;
+}
+
+export function createHeatmap(config: HeatmapConfig): Chart;
 
 // ---------------------------------------------------------------------------
 // Test-only export (NOT part of the stable public API)