@jarenjs/charts 0.34.0

package/src/types/heatmap.js

@@ -0,0 +1,176 @@
+//@ts-check
+/**
+ * @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".
+ */
+
+import { svgRoot, coord } from '@jarenjs/view/helpers';
+import { clamp01 } from '@jarenjs/core/math';
+import { formatTickValue } from '../core/axis.js';
+import { cartesianFrame, annotateChart } from '../core/cartesian.js';
+import { SEQUENTIAL, sequentialColor } from '../core/palette.js';
+import { normalizeTooltip, valueMark } from '../core/marks.js';
+
+/**
+ * @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 function buildHeatmapAST(data, config = {}) {
+  const xLabels = (data?.xLabels ?? []).map((l) => String(l));
+  const yLabels = (data?.yLabels ?? []).map((l) => String(l));
+  const values = Array.isArray(data?.values) ? data.values : [];
+  const log = config.log === true;
+
+  let min = Infinity;
+  let max = -Infinity;
+  for (let yi = 0; yi < yLabels.length; yi++) {
+    const row = values[yi];
+    if (!Array.isArray(row)) continue;
+    for (let xi = 0; xi < xLabels.length; xi++) {
+      const v = row[xi];
+      if (typeof v !== 'number' || !Number.isFinite(v)) continue;
+      if (log && v <= 0) continue;
+      if (v < min) min = v;
+      if (v > max) max = v;
+    }
+  }
+  const domain = Number.isFinite(min) ? { min, max } : null;
+  const span = domain === null ? 0
+    : log ? Math.log10(max) - Math.log10(min)
+      : max - min;
+
+  const xStep = xLabels.length === 0 ? 1 : 1 / xLabels.length;
+  const yStep = yLabels.length === 0 ? 1 : 1 / yLabels.length;
+  const cells = [];
+  if (domain !== null) {
+    for (let yi = 0; yi < yLabels.length; yi++) {
+      const row = values[yi];
+      if (!Array.isArray(row)) continue;
+      for (let xi = 0; xi < xLabels.length; xi++) {
+        const v = row[xi];
+        if (typeof v !== 'number' || !Number.isFinite(v)) continue;
+        if (log && v <= 0) continue;
+        const t = span === 0 ? 0.5
+          : log ? (Math.log10(v) - Math.log10(min)) / span
+            : (v - min) / span;
+        cells.push({
+          xi, yi,
+          u0: xi * xStep,
+          u1: (xi + 1) * xStep,
+          // yLabels[0] is the top row; v = 0 sits at the plot bottom.
+          v0: 1 - (yi + 1) * yStep,
+          v1: 1 - yi * yStep,
+          t: clamp01(t),
+          value: v,
+        });
+      }
+    }
+  }
+
+  return {
+    type: 'heatmap',
+    title: config.title ?? null,
+    xLabels,
+    yLabels,
+    x: {
+      ticks: xLabels.map((label, xi) => ({ pos: (xi + 0.5) * xStep, label })),
+      label: config.xLabel ?? null,
+    },
+    y: {
+      ticks: yLabels.map((label, yi) => ({ pos: 1 - (yi + 0.5) * yStep, label })),
+      label: config.yLabel ?? null,
+    },
+    cells,
+    domain,
+  };
+}
+
+/**
+ * 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 function renderHeatmapAST(ast, theme, hash, options = {}) {
+  const ramp = options.ramp ?? SEQUENTIAL;
+  const tooltip = normalizeTooltip(options.tooltip);
+  // The ramp key rides the frame's legend mechanism: five sequential
+  // stops as swatches, the extent values as the end labels.
+  const rampStops = [0, 0.25, 0.5, 0.75, 1].map((t) => sequentialColor(t, ramp));
+  const legend = ast.domain === null ? null : rampStops.map((_, i) => ({
+    name: i === 0 ? formatTickValue(ast.domain.min)
+      : i === rampStops.length - 1 ? formatTickValue(ast.domain.max) : '',
+    swatch: i,
+  }));
+  const frame = cartesianFrame({
+    title: ast.title,
+    legend,
+    xAxis: ast.x,
+    yAxis: ast.y,
+    grid: 'none',
+    width: options.width,
+    plotHeight: Math.max(80, ast.yLabels.length * 26),
+    palette: rampStops,
+    theme,
+  });
+  const { plot } = frame;
+  const children = frame.children;
+  const inset = 1;
+  for (const cell of ast.cells) {
+    const x = plot.x + cell.u0 * plot.w + inset;
+    const y = plot.y + (1 - cell.v1) * plot.h + inset;
+    const w = (cell.u1 - cell.u0) * plot.w - 2 * inset;
+    const h = (cell.v1 - cell.v0) * plot.h - 2 * inset;
+    children.push(valueMark('rect', {
+      x: coord(x), y: coord(y),
+      width: coord(Math.max(0.5, w)), height: coord(Math.max(0.5, h)),
+      fill: sequentialColor(cell.t, ramp), class: 'chart-heat-cell',
+    }, tooltip,
+    `${ast.xLabels[cell.xi]} × ${ast.yLabels[cell.yi]}: ${formatTickValue(cell.value)}`,
+    {
+      type: 'heatmap', x: ast.xLabels[cell.xi], y: ast.yLabels[cell.yi], value: cell.value,
+    }));
+  }
+  const svg = svgRoot(options.rootClass ?? 'chart chart-svg chart-heatmap-chart',
+    frame.width, frame.height, theme, children, (options.keyPrefix ?? 'heat-') + hash);
+  return annotateChart(svg, ast.title);
+}

package/src/types/line.js

@@ -0,0 +1,349 @@
+//@ts-check
+/**
+ * @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.
+ */
+
+import { svgRoot, path as svgPath, circle, polylinePath, coord } from '@jarenjs/view/helpers';
+import { clamp01 } from '@jarenjs/core/math';
+import { scaleLinear, scaleLog, scaleTime } from '../core/scale.js';
+import {
+  axisTicksLinear, axisTicksLog, axisTicksTime, niceTimeStep,
+  formatTickValue, formatTimeTick,
+} from '../core/axis.js';
+import { cartesianFrame, annotateChart } from '../core/cartesian.js';
+import { numOf } from '../core/stream-adapter.js';
+import {
+  normalizeDomainPolicy, resolveWindowX, resolveStepY, resolveStepYLog, resolvePinnedY,
+} from '../core/domain.js';
+import { CATEGORICAL, seriesColor } from '../core/palette.js';
+import { normalizeTooltip, markProps } from '../core/marks.js';
+
+/**
+ * @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 function scanLineExtremes(input, policy, log) {
+  let x0 = Infinity;
+  let x1 = -Infinity;
+  let y0 = Infinity;
+  let y1 = -Infinity;
+  for (const s of input) {
+    for (const p of s.points) {
+      const px = numOf(p?.x);
+      const py = numOf(p?.y);
+      if (!Number.isFinite(px) || !Number.isFinite(py)) continue;
+      if (px < x0) x0 = px;
+      if (px > x1) x1 = px;
+      if (log && py <= 0) continue;
+      if (py < y0) y0 = py;
+      if (py > y1) y1 = py;
+    }
+  }
+  if (policy.window !== null) {
+    const [wLo] = resolveWindowX(x1, policy.window, policy.slide);
+    y0 = Infinity;
+    y1 = -Infinity;
+    for (const s of input) {
+      for (const p of s.points) {
+        const px = numOf(p?.x);
+        const py = numOf(p?.y);
+        if (!Number.isFinite(px) || !Number.isFinite(py) || px < wLo) continue;
+        if (log && py <= 0) continue;
+        if (py < y0) y0 = py;
+        if (py > y1) y1 = py;
+      }
+    }
+  }
+  return { x0, x1, y0, y1 };
+}
+
+/**
+ * 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 function resolveLineDomains(ext, policy, time, log) {
+  let { x0, x1, y0, y1 } = ext;
+  let xDrop = null;
+  if (policy.window !== null) {
+    const [wLo, wHi] = resolveWindowX(x1, policy.window, policy.slide);
+    xDrop = wLo;
+    x0 = wLo;
+    x1 = wHi;
+  }
+  if (!Number.isFinite(x0)) { x0 = 0; x1 = 1; }
+  if (!Number.isFinite(y0)) { y0 = log ? 0.1 : 0; y1 = log ? 1 : 1; }
+
+  let yTickValues;
+  let yLo;
+  let yHi;
+  if (log) {
+    if (policy.step) [yLo, yHi] = resolveStepYLog(y0, y1);
+    else if (policy.pin !== null) [yLo, yHi] = resolvePinnedY(y0, y1, policy.pin, true);
+    else { yLo = y0; yHi = y1; }
+    if (yHi === yLo) yHi = yLo * 10;
+    yTickValues = axisTicksLog(yLo, yHi);
+  }
+  else if (policy.step || policy.pin !== null) {
+    [yLo, yHi] = policy.step ? resolveStepY(y0, y1) : resolvePinnedY(y0, y1, policy.pin, false);
+    if (yHi === yLo) yHi = yLo + 1;
+    yTickValues = axisTicksLinear(yLo, yHi, 5);
+  }
+  else {
+    yTickValues = axisTicksLinear(y0, y1, 5);
+    const lo = Math.min(y0, yTickValues[0] ?? y0);
+    const hi = Math.max(y1, yTickValues[yTickValues.length - 1] ?? y1);
+    yLo = lo;
+    yHi = hi === lo ? lo + 1 : hi;
+  }
+  return {
+    x: [x0, x1],
+    y: [yLo, yHi],
+    xDrop,
+    xTickValues: time ? axisTicksTime(x0, x1, 4) : axisTicksLinear(x0, x1, 5),
+    // the step the ticks were chosen on, so the labels can match it
+    xTickStep: time ? niceTimeStep(x1 - x0, 4) : null,
+    yTickValues,
+  };
+}
+
+/**
+ * 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 function lineScales(domains, time, log) {
+  return {
+    xScale: time ? scaleTime(domains.x[0], domains.x[1]) : scaleLinear(domains.x[0], domains.x[1]),
+    yScale: log ? scaleLog(domains.y[0], domains.y[1]) : scaleLinear(domains.y[0], domains.y[1]),
+  };
+}
+
+/**
+ * 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 function lineVertex(p, xDrop, xScale, yScale) {
+  const px = numOf(p?.x);
+  const py = numOf(p?.y);
+  if (!Number.isFinite(px) || !Number.isFinite(py)) return null;
+  if (xDrop !== null && px < xDrop) return null;
+  const v = yScale(py);
+  return Number.isFinite(v) ? { u: xScale(px), v: clamp01(v) } : null;
+}
+
+/**
+ * Build the geometry-free line AST.
+ * @param {any} data
+ * @param {any} [config]
+ * @returns {LineAST}
+ */
+export function buildLineAST(data, config = {}) {
+  const input = (data?.series ?? []).filter((s) => Array.isArray(s.points));
+  const time = config.x === 'time';
+  const log = config.log === true;
+  const policy = normalizeDomainPolicy(config.domain);
+  const domains = resolveLineDomains(scanLineExtremes(input, policy, log), policy, time, log);
+  const { xScale, yScale } = lineScales(domains, time, log);
+
+  const series = input.map((s) => ({
+    name: String(s.name ?? ''),
+    points: s.points.map((p) => lineVertex(p, domains.xDrop, xScale, yScale)),
+  }));
+
+  return {
+    type: 'line',
+    title: config.title ?? null,
+    x: {
+      ticks: domains.xTickValues.map((v) => ({
+        pos: clamp01(xScale(v)),
+        label: time ? formatTimeTick(v, domains.xTickStep) : formatTickValue(v),
+      })),
+      label: config.xLabel ?? null,
+    },
+    y: {
+      ticks: domains.yTickValues.map((v) => ({ pos: clamp01(yScale(v)), label: formatTickValue(v) })),
+      label: config.yLabel ?? null,
+    },
+    domain: { x: domains.x, y: domains.y },
+    legend: series.length > 1 ? series.map((s, i) => ({ name: s.name, swatch: i })) : null,
+    series,
+    markers: config.markers === true,
+  };
+}
+
+/**
+ * @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 function lineSeriesChildren(name, d, dots, color) {
+  const children = [];
+  if (name !== '') children.push(['title', {}, name]);
+  if (d !== '')
+    children.push(svgPath(d, { stroke: color, 'stroke-width': 2, fill: 'none', class: 'chart-line' }));
+  children.push(...dots);
+  return children;
+}
+
+/**
+ * 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 function lineSeriesRender(s, si, plot, palette, markers, tooltip = null) {
+  const color = seriesColor(si, palette);
+  const name = String(s.name ?? '');
+  const pixels = s.points.map((p) => p === null ? null : {
+    x: coord(plot.x + p.u * plot.w),
+    y: coord(plot.y + (1 - p.v) * plot.h),
+  });
+  const d = polylinePath(pixels);
+  const dots = [];
+  if (markers) {
+    for (const p of pixels) {
+      if (p !== null) dots.push(circle(p.x, p.y, 2.5, { fill: color, class: 'chart-dot' }));
+    }
+  }
+  const props = markProps({ key: `ls${si}`, class: 'chart-series' },
+    tooltip, name, { type: 'line', series: name });
+  return {
+    group: ['g', props, ...lineSeriesChildren(name, d, dots, color)],
+    d,
+    pen: s.points.length !== 0 && s.points[s.points.length - 1] !== null,
+    dots,
+    color,
+    name,
+  };
+}
+
+/**
+ * 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 function buildLineRender(ast, theme, hash, options = {}) {
+  const palette = options.palette ?? CATEGORICAL;
+  const tooltip = normalizeTooltip(options.tooltip);
+  const frame = cartesianFrame({
+    title: ast.title,
+    legend: ast.legend,
+    xAxis: ast.x,
+    yAxis: ast.y,
+    grid: 'y',
+    width: options.width,
+    palette,
+    theme,
+  });
+  const { plot } = frame;
+  const chromeLen = frame.children.length;
+  const children = frame.children;
+  const series = [];
+  for (let si = 0; si < ast.series.length; si++) {
+    const parts = lineSeriesRender(ast.series[si], si, plot, palette, ast.markers, tooltip);
+    series.push(parts);
+    children.push(parts.group);
+  }
+  const svg = svgRoot(options.rootClass ?? 'chart chart-svg chart-line-chart',
+    frame.width, frame.height, theme, children, (options.keyPrefix ?? 'line-') + hash);
+  annotateChart(svg, ast.title);
+  return { svg, plot, chromeLen, series };
+}
+
+/**
+ * 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 function renderLineAST(ast, theme, hash, options = {}) {
+  return buildLineRender(ast, theme, hash, options).svg;
+}