@jarenjs/charts 0.34.0

package/dist/types/types/candlestick.d.ts

@@ -0,0 +1,218 @@
+/**
+ * @file The candlestick chart type: OHLC records on a time x-scale and
+ * a linear y-scale. Up/down candles use the win/loss semantic pair —
+ * gain and loss are exactly what the tokens mean, and the pair is
+ * host-linked (`--ok`/`--fail`) like every semantic color. Data shape:
+ *
+ *   data   = { candles: [{t, open, high, low, close}] }
+ *   config = { type:'candlestick', title?, xLabel?, yLabel?, domain? }
+ *
+ * Candle width comes from the band-width math: an equal share of the
+ * axis per candle (klines arrive at a fixed interval, so equal bands
+ * and true time positions coincide).
+ *
+ * `config.domain` declares a domain-stability policy (`core/domain.js`):
+ * a quantized sliding `x` window (candles older than it are dropped —
+ * a clamped candle would misstate its prices), pinned or
+ * step-quantized `y` bounds. The AST records the resolved domain so a
+ * later build — or the incremental session — can detect "unchanged".
+ *
+ * The extremes scan, domain resolution and per-candle mapping are
+ * exported (`scanCandleExtremes` / `resolveCandleDomains` /
+ * `candleUnit`) because the session must make the same decisions from
+ * the same numbers. Each candle renders as one keyed
+ * `<g class="chart-candle">` (wick line, then body rect) — the candle
+ * is the replaceable unit a kline upsert patches; `buildCandlestickRender`
+ * is the render variant that also returns that geometry.
+ */
+export type CandleAST = {
+    /**
+     * open time (epoch ms — the candle's identity)
+     */
+    t: number;
+    /**
+     * center position (0..1)
+     */
+    u: number;
+    /**
+     * body width (0..1)
+     */
+    w: number;
+    openV: number;
+    closeV: number;
+    highV: number;
+    lowV: number;
+    open: number;
+    high: number;
+    low: number;
+    /**
+     * raw prices, which the
+     * hover text reports (a clamped unit value cannot be read back to one)
+     */
+    close: number;
+    /**
+     * close >= open
+     */
+    up: boolean;
+};
+export type CandlestickAST = {
+    type: 'candlestick';
+    title: string | null;
+    x: {
+        ticks: {
+            pos: number;
+            label: string;
+        }[];
+        label: string | null;
+    };
+    y: {
+        ticks: {
+            pos: number;
+            label: string;
+        }[];
+        label: string | null;
+    };
+    /**
+     * resolved scale bounds
+     */
+    domain: {
+        x: [number, number];
+        y: [number, number];
+    };
+    candles: CandleAST[];
+};
+/**
+ * @typedef {object} CandleAST
+ * @property {number} t open time (epoch ms — the candle's identity)
+ * @property {number} u center position (0..1)
+ * @property {number} w body width (0..1)
+ * @property {number} openV @property {number} closeV
+ * @property {number} highV @property {number} lowV
+ * @property {number} open @property {number} high
+ * @property {number} low @property {number} close raw prices, which the
+ *  hover text reports (a clamped unit value cannot be read back to one)
+ * @property {boolean} up close >= open
+ */
+/**
+ * @typedef {object} CandlestickAST
+ * @property {'candlestick'} type
+ * @property {string|null} title
+ * @property {{ticks: {pos:number,label:string}[], label: string|null}} x
+ * @property {{ticks: {pos:number,label:string}[], label: string|null}} y
+ * @property {{x: [number, number], y: [number, number]}} domain resolved scale bounds
+ * @property {CandleAST[]} candles
+ */
+/**
+ * Scan the candle extremes the domain resolution needs: t bounds over
+ * every well-formed candle, price bounds over the candles a window
+ * keeps — and the kept list itself (windowed-out candles are dropped
+ * entirely; a candle clamped to the edge would misstate its prices).
+ * @param {any[]} rawCandles
+ * @param {import('../core/domain.js').DomainPolicy} policy
+ * @returns {{t0:number, t1:number, lo:number, hi:number, kept: any[]}}
+ */
+export declare function scanCandleExtremes(rawCandles: any[], policy: import('../core/domain.js').DomainPolicy): {
+    t0: number;
+    t1: number;
+    lo: number;
+    hi: number;
+    kept: any[];
+};
+/**
+ * Resolve the scale domains (and their tick values) from the scanned
+ * extremes under the domain policy — the single place the candlestick
+ * type decides its bounds.
+ * @param {{t0:number, t1:number, lo:number, hi:number}} ext
+ * @param {import('../core/domain.js').DomainPolicy} policy
+ * @returns {{x: [number,number], y: [number,number],
+ *   xTickValues: number[], yTickValues: number[]}}
+ */
+export declare function resolveCandleDomains(ext: {
+    t0: number;
+    t1: number;
+    lo: number;
+    hi: number;
+}, policy: import('../core/domain.js').DomainPolicy): {
+    x: [number, number];
+    y: [number, number];
+    xTickValues: number[];
+    yTickValues: number[];
+};
+/**
+ * Map one OHLC record onto its unit-space candle — the per-candle half
+ * of the build, shared with the session.
+ * @param {any} c a well-formed `{t, open, high, low, close}` record
+ * @param {(v:number)=>number} xScale @param {(v:number)=>number} yScale
+ * @param {number} w candle width (0..1)
+ * @returns {CandleAST}
+ */
+export declare function candleUnit(c: any, xScale: (v: number) => number, yScale: (v: number) => number, w: number): CandleAST;
+/**
+ * Build the geometry-free candlestick AST.
+ * @param {any} data
+ * @param {any} [config]
+ * @returns {CandlestickAST}
+ */
+export declare function buildCandlestickAST(data: any, config?: any): CandlestickAST;
+/**
+ * Render one candle as its keyed `<g>` group: an OHLC hover `<title>`,
+ * then the wick line under the body rect, up/down tones from the
+ * theme's win/loss pair.
+ * @param {CandleAST} c
+ * @param {{x:number,y:number,w:number,h:number}} plot
+ * @param {{tokens: Record<string,string>}} theme
+ * @param {import('../core/marks.js').ChartTooltip|null} [tooltip]
+ * @returns {any}
+ */
+export declare function candleRender(c: CandleAST, plot: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}, theme: {
+    tokens: Record<string, string>;
+}, tooltip?: import('../core/marks.js').ChartTooltip | null): any;
+/**
+ * Render a candlestick AST and return the svg WITH the geometry a
+ * session needs to patch it per candle.
+ * @param {CandlestickAST} ast
+ * @param {{tokens: Record<string,string>, cssVars: Record<string,string>}} theme
+ * @param {string} hash
+ * @param {{rootClass?: string, keyPrefix?: string, width?: number,
+ *   tooltip?: import('../core/marks.js').ChartTooltipSpec}} [options]
+ * @returns {{svg: any, plot: {x:number,y:number,w:number,h:number}, chromeLen: number}}
+ */
+export declare function buildCandlestickRender(ast: CandlestickAST, theme: {
+    tokens: Record<string, string>;
+    cssVars: Record<string, string>;
+}, hash: string, options?: {
+    rootClass?: string;
+    keyPrefix?: string;
+    width?: number;
+    tooltip?: import('../core/marks.js').ChartTooltipSpec;
+}): {
+    svg: any;
+    plot: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    chromeLen: number;
+};
+/**
+ * Render a candlestick AST to a pure-vnode SVG.
+ * @param {CandlestickAST} ast
+ * @param {{tokens: Record<string,string>, cssVars: Record<string,string>}} theme
+ * @param {string} hash
+ * @param {{rootClass?: string, keyPrefix?: string, width?: number}} [options]
+ * @returns {any}
+ */
+export declare function renderCandlestickAST(ast: CandlestickAST, theme: {
+    tokens: Record<string, string>;
+    cssVars: Record<string, string>;
+}, hash: string, options?: {
+    rootClass?: string;
+    keyPrefix?: string;
+    width?: number;
+}): any;

package/dist/types/types/gauge.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @file The gauge chart type: a single value on a semicircular dial —
+ * the "how full is it" headline mark. Data shape:
+ *
+ *   data   = { value: number }
+ *   config = { type:'gauge', title?, min?, max?, unit?, tone? }
+ *
+ * The domain is `[min, max]` (0..100 when unset); the AST carries the
+ * clamped fill fraction and tick fractions only — the dial radius and
+ * stroke widths are render decisions. `tone` colors the fill through
+ * the semantic win/loss pair; the default is the first categorical
+ * anchor (the brand blue).
+ */
+export type GaugeAST = {
+    type: 'gauge';
+    title: string | null;
+    value: number;
+    unit: string | null;
+    min: number;
+    max: number;
+    /**
+     * clamped fill fraction (0..1)
+     */
+    frac: number;
+    ticks: {
+        frac: number;
+        label: string;
+    }[];
+    tone: 'win' | 'loss' | null;
+};
+/**
+ * @typedef {object} GaugeAST
+ * @property {'gauge'} type
+ * @property {string|null} title
+ * @property {number} value
+ * @property {string|null} unit
+ * @property {number} min @property {number} max
+ * @property {number} frac clamped fill fraction (0..1)
+ * @property {{frac: number, label: string}[]} ticks
+ * @property {'win'|'loss'|null} tone
+ */
+/**
+ * Build the geometry-free gauge AST.
+ * @param {any} data
+ * @param {any} [config]
+ * @returns {GaugeAST}
+ */
+export declare function buildGaugeAST(data: any, config?: any): GaugeAST;
+/**
+ * Render a gauge AST to a pure-vnode SVG: a semicircular track, the
+ * value arc over it, outward tick marks with labels, and the value as
+ * the headline figure in the dial's mouth.
+ * @param {GaugeAST} ast
+ * @param {{tokens: Record<string,string>, cssVars: Record<string,string>}} theme
+ * @param {string} hash
+ * @param {{rootClass?: string, keyPrefix?: string, palette?: readonly string[],
+ *   tooltip?: import('../core/marks.js').ChartTooltipSpec}} [options]
+ * @returns {any}
+ */
+export declare function renderGaugeAST(ast: GaugeAST, theme: {
+    tokens: Record<string, string>;
+    cssVars: Record<string, string>;
+}, hash: string, options?: {
+    rootClass?: string;
+    keyPrefix?: string;
+    palette?: readonly string[];
+    tooltip?: import('../core/marks.js').ChartTooltipSpec;
+}): any;

package/dist/types/types/heatmap.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @file The heatmap chart type: a category × category matrix of
+ * magnitudes on the sequential blue ramp — the alternative reading of
+ * the benchmark scenario matrices that ship as grouped bars. Data
+ * shape:
+ *
+ *   data   = { xLabels: string[], yLabels: string[],
+ *              values: number[][] }               // values[yi][xi], row-major
+ *   config = { type:'heatmap', title?, xLabel?, yLabel?, log? }
+ *
+ * The AST is unit-space cell bands plus a normalized magnitude `t` per
+ * cell; the color (the sequential ramp), the cell inset and the ramp
+ * legend are render decisions. Rows read top-down: `yLabels[0]` is the
+ * top row. Non-finite cells (and non-positive ones under `log`) are
+ * simply absent — the surface shows through, which is the honest
+ * rendering of "no measurement".
+ */
+export type HeatCellAST = {
+    xi: number;
+    yi: number;
+    u0: number;
+    u1: number;
+    v0: number;
+    v1: number;
+    /**
+     * normalized magnitude (0..1)
+     */
+    t: number;
+    value: number;
+};
+export type HeatmapAST = {
+    type: 'heatmap';
+    title: string | null;
+    xLabels: string[];
+    yLabels: string[];
+    x: {
+        ticks: {
+            pos: number;
+            label: string;
+        }[];
+        label: string | null;
+    };
+    y: {
+        ticks: {
+            pos: number;
+            label: string;
+        }[];
+        label: string | null;
+    };
+    cells: HeatCellAST[];
+    /**
+     * finite-value extent (null = no data)
+     */
+    domain: {
+        min: number;
+        max: number;
+    } | null;
+};
+/**
+ * @typedef {object} HeatCellAST
+ * @property {number} xi @property {number} yi
+ * @property {number} u0 @property {number} u1
+ * @property {number} v0 @property {number} v1
+ * @property {number} t normalized magnitude (0..1)
+ * @property {number} value
+ */
+/**
+ * @typedef {object} HeatmapAST
+ * @property {'heatmap'} type
+ * @property {string|null} title
+ * @property {string[]} xLabels @property {string[]} yLabels
+ * @property {{ticks: {pos:number,label:string}[], label: string|null}} x
+ * @property {{ticks: {pos:number,label:string}[], label: string|null}} y
+ * @property {HeatCellAST[]} cells
+ * @property {{min: number, max: number}|null} domain finite-value extent (null = no data)
+ */
+/**
+ * Build the geometry-free heatmap AST.
+ * @param {any} data
+ * @param {any} [config]
+ * @returns {HeatmapAST}
+ */
+export declare function buildHeatmapAST(data: any, config?: any): HeatmapAST;
+/**
+ * Render a heatmap AST to a pure-vnode SVG: inset cell rects colored by
+ * the sequential ramp, a labeled min→max ramp key in the legend slot,
+ * and a `<title>` per cell with the exact value.
+ * @param {HeatmapAST} ast
+ * @param {{tokens: Record<string,string>, cssVars: Record<string,string>}} theme
+ * @param {string} hash
+ * @param {{rootClass?: string, keyPrefix?: string, ramp?: readonly string[], width?: number,
+ *   tooltip?: import('../core/marks.js').ChartTooltipSpec}} [options]
+ * @returns {any}
+ */
+export declare function renderHeatmapAST(ast: HeatmapAST, theme: {
+    tokens: Record<string, string>;
+    cssVars: Record<string, string>;
+}, hash: string, options?: {
+    rootClass?: string;
+    keyPrefix?: string;
+    ramp?: readonly string[];
+    width?: number;
+    tooltip?: import('../core/marks.js').ChartTooltipSpec;
+}): any;

package/dist/types/types/line.d.ts

@@ -0,0 +1,272 @@
+/**
+ * @file The line chart type: multi-series polylines over a linear or
+ * time x axis, linear or log y axis, optional point markers. This is
+ * the streaming-critical type — a live feed re-renders it per snapshot
+ * — so build and render stay allocation-light (one pass per series,
+ * `polylinePath` breaks the line on unplottable samples instead of
+ * filtering arrays). Data shape:
+ *
+ *   data   = { series: [{ name, points: [{x, y}] }] }
+ *   config = { type:'line', title?, x?: 'linear'|'time', log?,
+ *              markers?, xLabel?, yLabel?, domain? }
+ *
+ * `config.domain` declares a domain-stability policy (`core/domain.js`)
+ * so most streaming ticks keep the scales still: a quantized sliding
+ * `x` window (samples older than it become null vertices), pinned or
+ * step-quantized `y` bounds. The AST records the resolved domain so a
+ * later build — or the incremental session — can detect "unchanged".
+ *
+ * The extremes scan, domain resolution and scale construction are
+ * exported (`scanLineExtremes` / `resolveLineDomains` / `lineScales`)
+ * because the incremental session must make the SAME decisions from
+ * the same numbers — one implementation, no drift. Each series
+ * renders as one `<g class="chart-series">` (path, then marker dots),
+ * so a session — and the view patcher — can treat a series as one
+ * replaceable unit; `buildLineRender` is the render variant that also
+ * returns that per-series geometry.
+ */
+export type LineAST = {
+    type: 'line';
+    title: string | null;
+    x: {
+        ticks: {
+            pos: number;
+            label: string;
+        }[];
+        label: string | null;
+    };
+    y: {
+        ticks: {
+            pos: number;
+            label: string;
+        }[];
+        label: string | null;
+    };
+    /**
+     * resolved scale bounds
+     */
+    domain: {
+        x: [number, number];
+        y: [number, number];
+    };
+    legend: {
+        name: string;
+        swatch: number;
+    }[] | null;
+    series: {
+        name: string;
+        points: ({
+            u: number;
+            v: number;
+        } | null)[];
+    }[];
+    markers: boolean;
+};
+/**
+ * @typedef {object} LineAST
+ * @property {'line'} type
+ * @property {string|null} title
+ * @property {{ticks: {pos:number,label:string}[], label: string|null}} x
+ * @property {{ticks: {pos:number,label:string}[], label: string|null}} y
+ * @property {{x: [number, number], y: [number, number]}} domain resolved scale bounds
+ * @property {{name: string, swatch: number}[]|null} legend
+ * @property {{name: string, points: ({u:number,v:number}|null)[]}[]} series
+ * @property {boolean} markers
+ */
+/**
+ * Scan the data extremes the domain resolution needs: raw x bounds
+ * over every finite sample, y bounds over the samples a window keeps
+ * (windowed-out samples must not pin the value axis). Under `log`,
+ * non-positive y values never join the y extremes (they still extend
+ * x, as unplottable vertices on a real time axis do).
+ * @param {{points: any[]}[]} input series with array points
+ * @param {import('../core/domain.js').DomainPolicy} policy
+ * @param {boolean} log
+ * @returns {{x0:number, x1:number, y0:number, y1:number}}
+ */
+export declare function scanLineExtremes(input: {
+    points: any[];
+}[], policy: import('../core/domain.js').DomainPolicy, log: boolean): {
+    x0: number;
+    x1: number;
+    y0: number;
+    y1: number;
+};
+/**
+ * Resolve the scale domains (and their tick values) from the scanned
+ * extremes under the domain policy — the single place the line type
+ * decides its bounds; the incremental session compares the result
+ * against the AST's recorded domain to detect a still frame.
+ * @param {{x0:number, x1:number, y0:number, y1:number}} ext
+ * @param {import('../core/domain.js').DomainPolicy} policy
+ * @param {boolean} time
+ * @param {boolean} log
+ * @returns {{x: [number,number], y: [number,number], xDrop: number|null,
+ *   xTickValues: number[], yTickValues: number[]}}
+ */
+export declare function resolveLineDomains(ext: {
+    x0: number;
+    x1: number;
+    y0: number;
+    y1: number;
+}, policy: import('../core/domain.js').DomainPolicy, time: boolean, log: boolean): {
+    x: [number, number];
+    y: [number, number];
+    xDrop: number | null;
+    xTickValues: number[];
+    yTickValues: number[];
+};
+/**
+ * Unit scales over a resolved domain — the same closures the build
+ * uses, reconstructable by the session from the AST's domain alone.
+ * @param {{x: [number,number], y: [number,number]}} domains
+ * @param {boolean} time
+ * @param {boolean} log
+ * @returns {{xScale: (v:number)=>number, yScale: (v:number)=>number}}
+ */
+export declare function lineScales(domains: {
+    x: [number, number];
+    y: [number, number];
+}, time: boolean, log: boolean): {
+    xScale: (v: number) => number;
+    yScale: (v: number) => number;
+};
+/**
+ * Map one sample onto a unit vertex (or null for an unplottable one) —
+ * the per-point half of the build, shared with the session.
+ * @param {any} p the `{x, y}` sample
+ * @param {number|null} xDrop window low bound (drop older samples)
+ * @param {(v:number)=>number} xScale @param {(v:number)=>number} yScale
+ * @returns {{u:number, v:number}|null}
+ */
+export declare function lineVertex(p: any, xDrop: number | null, xScale: (v: number) => number, yScale: (v: number) => number): {
+    u: number;
+    v: number;
+} | null;
+/**
+ * Build the geometry-free line AST.
+ * @param {any} data
+ * @param {any} [config]
+ * @returns {LineAST}
+ */
+export declare function buildLineAST(data: any, config?: any): LineAST;
+export type LineSeriesRender = {
+    /**
+     * the series' `<g>` vnode
+     */
+    group: any;
+    /**
+     * the polyline path data
+     */
+    d: string;
+    /**
+     * true when the last vertex was drawable (the
+     * next appended token is an `L`, not an `M`)
+     */
+    pen: boolean;
+    /**
+     * marker circle vnodes (empty when markers off)
+     */
+    dots: any[];
+    /**
+     * the series color
+     */
+    color: string;
+    /**
+     * the series name (its hover text)
+     */
+    name: string;
+};
+/**
+ * @typedef {object} LineSeriesRender
+ * @property {any} group the series' `<g>` vnode
+ * @property {string} d the polyline path data
+ * @property {boolean} pen true when the last vertex was drawable (the
+ *  next appended token is an `L`, not an `M`)
+ * @property {any[]} dots marker circle vnodes (empty when markers off)
+ * @property {string} color the series color
+ * @property {string} name the series name (its hover text)
+ */
+/**
+ * The children of one series `<g>`: the hover `<title>`, the polyline
+ * path (when it has one), then the marker dots. The series — not the
+ * individual sample — is the value mark here: a live line carries tens
+ * of thousands of vertices, and a `<title>` per vertex would put a
+ * label allocation on the streaming path for text no reader can aim at.
+ * Shared with the incremental session, which rebuilds these children in
+ * place, so the two cannot drift.
+ * @param {string} name @param {string} d @param {any[]} dots @param {string} color
+ * @returns {any[]}
+ */
+export declare function lineSeriesChildren(name: string, d: string, dots: any[], color: string): any[];
+/**
+ * Render one series as its `<g>` group.
+ * @param {{name?: string, points: ({u:number,v:number}|null)[]}} s
+ * @param {number} si series index
+ * @param {{x:number,y:number,w:number,h:number}} plot
+ * @param {readonly string[]} palette
+ * @param {boolean} markers
+ * @param {import('../core/marks.js').ChartTooltip|null} [tooltip]
+ * @returns {LineSeriesRender}
+ */
+export declare function lineSeriesRender(s: {
+    name?: string;
+    points: ({
+        u: number;
+        v: number;
+    } | null)[];
+}, si: number, plot: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}, palette: readonly string[], markers: boolean, tooltip?: import('../core/marks.js').ChartTooltip | null): LineSeriesRender;
+/**
+ * Render a line AST and return the svg WITH the geometry a session
+ * needs to patch it incrementally: the plot rect, how many chrome
+ * children precede the series groups, and each series' render parts.
+ * @param {LineAST} ast
+ * @param {{tokens: Record<string,string>, cssVars: Record<string,string>}} theme
+ * @param {string} hash
+ * @param {{rootClass?: string, keyPrefix?: string, palette?: readonly string[], width?: number,
+ *   tooltip?: import('../core/marks.js').ChartTooltipSpec}} [options]
+ * @returns {{svg: any, plot: {x:number,y:number,w:number,h:number},
+ *   chromeLen: number, series: LineSeriesRender[]}}
+ */
+export declare function buildLineRender(ast: LineAST, theme: {
+    tokens: Record<string, string>;
+    cssVars: Record<string, string>;
+}, hash: string, options?: {
+    rootClass?: string;
+    keyPrefix?: string;
+    palette?: readonly string[];
+    width?: number;
+    tooltip?: import('../core/marks.js').ChartTooltipSpec;
+}): {
+    svg: any;
+    plot: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    chromeLen: number;
+    series: LineSeriesRender[];
+};
+/**
+ * Render a line AST to a pure-vnode SVG.
+ * @param {LineAST} ast
+ * @param {{tokens: Record<string,string>, cssVars: Record<string,string>}} theme
+ * @param {string} hash
+ * @param {{rootClass?: string, keyPrefix?: string, palette?: readonly string[], width?: number}} [options]
+ * @returns {any}
+ */
+export declare function renderLineAST(ast: LineAST, theme: {
+    tokens: Record<string, string>;
+    cssVars: Record<string, string>;
+}, hash: string, options?: {
+    rootClass?: string;
+    keyPrefix?: string;
+    palette?: readonly string[];
+    width?: number;
+}): any;