goro-charts 1.0.0

package/dist/charts/chart-base.d.ts

@@ -0,0 +1,248 @@
+/**
+ * @file Abstract chart orchestrator shared by every chart type.
+ *
+ * Owns cross-cutting concerns: the data stores (one per series), the canvas
+ * surface, the dirty flag and rAF coalescing, pointer interaction state, the
+ * ResizeObserver, and the draw sequence (static layer → offscreen, blit,
+ * crosshair overlay). All data lives in {@link SeriesStore} instances; all
+ * pixels are produced by the `render/` functions.
+ *
+ * Multi-series: a {@link SeriesStore} is created for each
+ * {@link SeriesConfig} entry. The series extent is computed as a union over
+ * all stores so grid ticks span every visible series. Each store is rendered
+ * independently by the subclass's {@link renderSeries}, receiving per-series
+ * colour/style overrides merged from its config entry.
+ *
+ * Dual-Y: when any series opts into `yAxis: 'right'` the chart maintains
+ * left and right grid domains independently. Left-axis series share the left
+ * domain; right-axis series share the right. Tick labels appear on both sides
+ * and the crosshair reads the correct axis per series.
+ */
+import { SeriesStore } from '../data/series-store.js';
+import { Surface } from '../render/surface.js';
+import type { ChartOpts, ResolvedOpts, SeriesConfig, SeriesView, PlotRect } from '../types.js';
+import type { SeriesHit } from '../render/crosshair.js';
+/** Abstract base for all chart types. */
+export declare abstract class ChartBase {
+    protected opts: ResolvedOpts;
+    protected surface: Surface;
+    protected stores: SeriesStore[];
+    protected seriesConfigs: SeriesConfig[];
+    private gridDomainLeft;
+    private gridDomainRight;
+    private gridPinned;
+    private hasRightAxis;
+    /**
+     * Cached stack-group detection. `seriesConfigs` is immutable after the
+     * constructor (validateOpts is the last writer), so groups are computed
+     * once and reused every draw instead of rebuilt each frame.
+     */
+    private stackGroupsAll;
+    private stackGroupsByAxis;
+    private dirty;
+    private cursorX;
+    private cursorY;
+    private showCrosshair;
+    private autoDraw;
+    private rafScheduled;
+    private suspendCount;
+    private syncTargets;
+    private resizeObserver;
+    protected destroyed: boolean;
+    private liveRegion;
+    private readonly handleResize;
+    private readonly handleMouseMove;
+    private readonly handleMouseLeave;
+    private readonly handleKeyDown;
+    constructor(canvas: HTMLCanvasElement, opts?: ChartOpts);
+    /**
+     * Validate and normalize constructor options.
+     * Warns on suspicious values and clamps/repairs where possible.
+     */
+    private validateOpts;
+    /**
+     * Detect system accessibility preferences and adjust visual styles.
+     * - prefers-reduced-motion → disable rAF coalescing (synchronous draws)
+     * - prefers-contrast: more → increase colour opacity
+     * - forced-colors: active → use system CSS system colours
+     */
+    private applySystemTheme;
+    /**
+     * Ensure an aria-live region exists for screen-reader announcements
+     * of crosshair position values.
+     */
+    private ensureLiveRegion;
+    /**
+     * Update the canvas aria-label with a summary of visible data.
+     * Called once per static redraw.
+     */
+    private updateAriaLabel;
+    /**
+     * Handle keyboard navigation for the crosshair.
+     * - ArrowLeft / ArrowRight: move crosshair by 1 point (Shift: 10 points)
+     * - Escape: hide crosshair
+     */
+    private onKeyDown;
+    /** Reusable crosshair-sync helpers used by both mouse and keyboard handlers. */
+    private notifySyncCrosshair;
+    private notifySyncCrosshairLeave;
+    /** Draw the series shape. Implemented by {@link LineChart} / {@link AreaChart}. */
+    protected abstract renderSeries(ctx: CanvasRenderingContext2D, view: SeriesView, plot: PlotRect, opts: ResolvedOpts): void;
+    /**
+     * Snapshot mode: replace the series at `index` (O(n) extent).
+     * @param index - Series index (0-based)
+     * @param x - X values, must be monotonically increasing
+     * @param y - Y values, must have the same length as x
+     * @throws {Error} if `index` is out of range, or x/y length mismatch
+     */
+    setData(index: number, x: Float64Array<ArrayBufferLike>, y: Float64Array<ArrayBufferLike>): void;
+    /**
+     * Ring mode: append one sample to series `index`.
+     * @param index - Series index (0-based)
+     * @param x - X value (must be monotonically increasing)
+     * @param y - Y value
+     * @throws {Error} if ring mode is not active (maxPoints not set)
+     * @throws {Error} if `index` is out of range
+     */
+    append(index: number, x: number, y: number): void;
+    /**
+     * Ring mode: append a batch of samples to series `index`.
+     * @param index - Series index (0-based)
+     * @param xs - X values (must be monotonically increasing)
+     * @param ys - Y values, must have the same length as xs
+     * @throws {Error} if ring mode is not active
+     * @throws {Error} if `index` is out of range or xs/ys length mismatch
+     */
+    appendBatch(index: number, xs: ArrayLike<number>, ys: ArrayLike<number>): void;
+    /**
+     * Resize the streaming window (applies to all series).
+     * Preserves the most recent samples in each series.
+     * @param maxPoints - New window size (must be >= 1)
+     */
+    setMaxPoints(maxPoints: number): void;
+    /** Empty all series and reset grid domain. */
+    clear(): void;
+    /** Number of series configured. */
+    get seriesCount(): number;
+    /**
+     * Total points rendered across all series in the last draw.
+     * Useful for debug/performance monitoring (e.g. to verify decimation is active).
+     */
+    get renderedPointCount(): number;
+    /**
+     * Number of points currently in the window for series `index`.
+     * @param index - Series index (0-based)
+     */
+    pointCount(index: number): number;
+    /**
+     * Current window y minimum for series `index` (O(1)).
+     * @param index - Series index (0-based)
+     */
+    extentMin(index: number): number;
+    /**
+     * Current window y maximum for series `index` (O(1)).
+     * @param index - Series index (0-based)
+     */
+    extentMax(index: number): number;
+    /**
+     * Most recent y value for series `index`, or NaN if empty.
+     * @param index - Series index (0-based)
+     */
+    lastValue(index: number): number;
+    /**
+     * Pause rAF-coalesced drawing. Nestable — call {@link resumeDraw} the
+     * same number of times to re-enable. Useful for bulk-loading data without
+     * intermediate paints.
+     */
+    suspendDraw(): void;
+    /** Resume drawing after a matching {@link suspendDraw}. Draws immediately if dirty. */
+    resumeDraw(): void;
+    /**
+     * Export the current canvas as a PNG data URL.
+     * @returns A `data:image/png` URL string
+     */
+    toImage(): string;
+    /**
+     * Bidirectionally sync crosshair position with `other`. When the mouse
+     * moves on one chart, crosshair overlay is injected on all synced charts
+     * at the matching x coordinate.
+     * @param other - Another chart instance to sync with
+     */
+    sync(other: ChartBase): void;
+    /**
+     * External callback for hover events. Called on `mousemove` with the
+     * interpolated data for every visible series. Use to build custom DOM
+     * tooltips or bind to framework state — the Canvas tooltip still draws
+     * unless suppressed externally.
+     */
+    onHover?: (hits: SeriesHit[]) => void;
+    /** Paint the chart. Cheap to call repeatedly: returns early when clean. */
+    draw(): void;
+    /** Detach observers/listeners and release buffers. Idempotent. */
+    destroy(): void;
+    /** Render the static layer (background, grid, axes, series, legend) to offscreen. */
+    private renderStatic;
+    /** Render a single series. */
+    private renderOne;
+    /** Cached per-axis stack groups (computed once in the constructor). */
+    private detectStackGroupsOnAxis;
+    /**
+     * Compute stack groups for a given axis. Returns the group map and a set
+     * of series indices that belong to groups with 2+ members.
+     */
+    private computeStackGroupsOnAxis;
+    /** Cached all-axis stack groups (computed once in the constructor). */
+    private detectAllStackGroups;
+    /**
+     * Compute all stack groups across all axes.
+     * Unlike {@link computeStackGroupsOnAxis}, this ignores the yAxis setting
+     * and returns every group that has 2+ members.
+     */
+    private computeAllStackGroups;
+    /**
+     * Compute accumulated Y values across a stack group.
+     * Returns the cumulative Y array (length = n), or null if all stores are empty.
+     */
+    private accumulateStackGroup;
+    /**
+     * Update the grid Y domain.
+     *
+     * Two regimes:
+     *  - **Snapshot mode:** anchor the grid so it only expands, never shrinks.
+     *    The domain snaps to the union extent on the first draw and stays frozen
+     *    until a series exceeds it, then expands with a 10 % margin — a stable
+     *    visual anchor for static data.
+     *  - **Ring (streaming) mode:** the window slides, so the true extent both
+     *    grows and shrinks as samples enter and leave. Here we recompute the
+     *    domain from the current window every tick (via {@link initDomain}) so
+     *    the grid tracks the visible data instead of drifting or letting stacked
+     *    bands overflow the frame.
+     *
+     * If the user supplied `yMin` / `yMax` those are hard bounds that override
+     * the auto logic in either regime.
+     */
+    private updateGridDomain;
+    /**
+     * Compute the domain for one axis from the current window.
+     * @param margin optional fraction of the Y range to pad on each side
+     *   (used in streaming mode so peaks/troughs don't touch the frame).
+     */
+    private initDomain;
+    private expandDomain;
+    /**
+     * Recompute the shared X domain from all non-empty series so grid ticks
+     * and renderers always map fresh X positions. Called every draw.
+     */
+    private refreshXDomain;
+    /** Compute the plot rectangle from canvas size minus padding. */
+    private plotRect;
+    /** Mark dirty and schedule/perform a draw per the autoDraw policy. */
+    private invalidate;
+    private storeAt;
+    private injectCursor;
+    private injectCursorLeave;
+    private attachEvents;
+    private onResize;
+    private onMouseMove;
+    private onMouseLeave;
+}

package/dist/charts/line-chart.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @file Line chart — the default series drawn as a single batched polyline.
+ *
+ * Supports the decimation auto-switch: dense data collapses to a per-pixel
+ * min/max envelope ribbon; sparse data draws the real polyline. For the
+ * full algorithm details see {@link renderLine}.
+ */
+import { ChartBase } from './chart-base.js';
+import type { SeriesView, PlotRect, ResolvedOpts } from '../types.js';
+/** High-performance Canvas 2D line chart. */
+export declare class LineChart extends ChartBase {
+    protected renderSeries(ctx: CanvasRenderingContext2D, view: SeriesView, plot: PlotRect, opts: ResolvedOpts): void;
+}

package/dist/charts/scatter-chart.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @file Scatter chart — one filled circle per (sampled) point.
+ *
+ * Uses stride thinning via {@link renderScatter}: when the dataset exceeds
+ * `maxDots` every Nth point is drawn so the chart stays responsive. The
+ * thinning step is `floor(n / maxDots)`.
+ */
+import { ChartBase } from './chart-base.js';
+import type { SeriesView, PlotRect, ResolvedOpts } from '../types.js';
+/** High-performance Canvas 2D scatter chart. */
+export declare class ScatterChart extends ChartBase {
+    protected renderSeries(ctx: CanvasRenderingContext2D, view: SeriesView, plot: PlotRect, opts: ResolvedOpts): void;
+}

package/dist/data/monotonic-extent.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @file Sliding-window min & max in O(1) amortized per push.
+ *
+ * Maintains two monotonic deques backed by circular Float64Arrays (no object
+ * allocation): the min-deque is strictly increasing front→back, the max-deque
+ * strictly decreasing, so each window extreme sits at its deque's front.
+ *
+ * Each push runs three steps in the canonical order — evict expired from
+ * front, pop dominated from back, append — which is what guarantees a deque
+ * never exceeds capacity. `seq` is a globally increasing sample id and
+ * `windowStart` is the oldest seq still inside the window; an entry expires
+ * once its seq < windowStart.
+ */
+/** Incremental sliding-window extent tracker. */
+export declare class MonotonicExtent {
+    private cap;
+    private vMin;
+    private sMin;
+    private hMin;
+    private nMin;
+    private vMax;
+    private sMax;
+    private hMax;
+    private nMax;
+    constructor(cap: number);
+    /** Reset to empty (keeps allocated buffers). */
+    clear(): void;
+    /**
+     * Record a new sample and slide the window forward.
+     * @param value the sample value
+     * @param seq globally increasing sample id
+     * @param windowStart oldest seq still inside the window
+     */
+    push(value: number, seq: number, windowStart: number): void;
+    /** Current window minimum. */
+    get min(): number;
+    /** Current window maximum. */
+    get max(): number;
+}

package/dist/data/ring-buffer.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @file Fixed-capacity ring buffer of parallel (x, y) Float64Arrays.
+ *
+ * Append is O(1) with no memmove: once the window is full the oldest sample is
+ * overwritten in place and `head` advances. y-extent is maintained
+ * incrementally by a {@link MonotonicExtent}, so min/max are O(1) too.
+ *
+ * Logical order (oldest→newest) is `head, head+1, … head+count-1` (mod cap).
+ * x is assumed monotonically increasing in push order, so it stays sorted in
+ * logical order — which the crosshair's binary search relies on.
+ */
+/** Sliding-window columnar store for streaming (ring) mode. */
+export declare class RingBuffer {
+    cap: number;
+    x: Float64Array;
+    y: Float64Array;
+    head: number;
+    count: number;
+    private seq;
+    private ext;
+    constructor(cap: number);
+    /** Current window y minimum (O(1)). */
+    get yMin(): number;
+    /** Current window y maximum (O(1)). */
+    get yMax(): number;
+    /** x of the oldest sample. */
+    get xFirst(): number;
+    /** x of the newest sample. */
+    get xLast(): number;
+    /** y of the newest sample. */
+    get lastY(): number;
+    /** Map a logical index [0, count) to its physical slot. */
+    physOf(logical: number): number;
+    /** Append one sample. x must be ≥ the previous x (monotonic). */
+    push(xv: number, yv: number): void;
+    /** Reset to empty (keeps allocated buffers). */
+    clear(): void;
+    /**
+     * Resize the window, preserving the most recent samples. Rare and O(keep):
+     * the retained tail is copied out, fresh buffers allocated, then re-pushed so
+     * the extent deque rebuilds correctly.
+     */
+    resize(newCap: number): void;
+}

package/dist/data/series-store.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @file Unified data model behind both chart modes, implementing SeriesView.
+ *
+ * Snapshot mode (setData) holds caller-owned arrays directly with head=0.
+ * Ring mode (append/appendBatch) delegates storage to a {@link RingBuffer} and
+ * mirrors its O(1) cached geometry into local fields each tick. Either way the
+ * store exposes the same logical window `[0, count)` plus `physOf` /
+ * `bracketLogical` addressing, so renderers consume one stable contract.
+ *
+ * The store is purely about data: it never touches the canvas or scheduling.
+ */
+import type { SeriesView } from '../types.js';
+/** Owns the series data and computes/caches its extents. */
+export declare class SeriesStore implements SeriesView {
+    xArr: Float64Array<ArrayBufferLike>;
+    yArr: Float64Array<ArrayBufferLike>;
+    head: number;
+    count: number;
+    cap: number;
+    xMin: number;
+    xMax: number;
+    yMin: number;
+    yMax: number;
+    private ring;
+    /** Whether ring (streaming) mode is active. */
+    get isRing(): boolean;
+    /**
+     * Create the ring up front (used when constructed with maxPoints).
+     * @throws {Error} if maxPoints < 1
+     */
+    initRing(maxPoints: number): void;
+    /**
+     * Snapshot mode: replace the whole series. Extents computed once in O(n).
+     * Disables any active ring mode.
+     * @throws {Error} if x and y have different lengths
+     * @throws {Error} if x is empty
+     */
+    setData(x: Float64Array<ArrayBufferLike>, y: Float64Array<ArrayBufferLike>): void;
+    /**
+     * Ring mode: append one sample (x must be monotonically increasing).
+     * @throws {Error} if ring mode is not active (maxPoints not set)
+     */
+    append(x: number, y: number): void;
+    /**
+     * Ring mode: append a batch of parallel samples. O(k).
+     * @throws {Error} if ring mode is not active
+     * @throws {Error} if xs and ys have different lengths
+     */
+    appendBatch(xs: ArrayLike<number>, ys: ArrayLike<number>): void;
+    /** Resize the streaming window, keeping the most recent samples. */
+    setMaxPoints(maxPoints: number): void;
+    /** Empty the current data (works in both modes). */
+    clear(): void;
+    /** Most recent y value, or NaN if empty. */
+    get lastValue(): number;
+    physOf(logical: number): number;
+    bracketLogical(target: number): number;
+    private requireRing;
+    /** Point the store's logical window at the ring's physical storage. */
+    private bindRing;
+    /** Mirror the ring's O(1) cached geometry into the store's fields. */
+    private syncFromRing;
+    /** Store y-extent, expanding a degenerate (flat) range so the line shows. */
+    private applyExtent;
+}

package/dist/defaults.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @file Default options merged over any user-supplied {@link ChartOpts}.
+ *
+ * The top-level colour / width fields are per-series fallbacks — each series
+ * config entry provides its own colour and optional overrides. `maxPoints: 0`
+ * is a sentinel meaning "snapshot mode" (no ring); the constructor activates
+ * ring mode only when the user passes a positive value.
+ *
+ * `yMin: 0 / yMax: 0` are sentinels meaning "auto" — the grid domain
+ * expands from data unless the user sets non-zero values.
+ */
+import type { ResolvedOpts } from './types.js';
+export declare const CHART_DEFAULTS: ResolvedOpts;