@jarenjs/charts 0.34.0

package/src/transforms/benchmark-adapter.js

@@ -0,0 +1,298 @@
+//@ts-check
+/**
+ * @file Benchmark interop: pure functions from the published benchmark
+ * data shapes (the jaren website's generated `benchmarks/*.json`) to
+ * `compileChart`-shaped `{config, data}` pairs. No formatting, no
+ * vnodes, no fetching — data in, chart definition out, so every
+ * function is unit-testable against a vendored slice of the real data.
+ *
+ * The suite-wide ratio convention holds: ratio > 1 means "Jaren is N×
+ * faster", and the win/loss semantic tones follow it.
+ */
+
+/**
+ * @typedef {{config: Record<string, any>, data: Record<string, any>}} ChartPair
+ */
+
+/**
+ * The ratio-distribution bar chart: success-only tests bucketed by
+ * ratio. Buckets carry their own predicate and tone.
+ * @param {{ratio: number|null, isSuccessTest?: boolean}[]} results
+ * @param {{label: string, test: (r: number) => boolean, tone: 'win'|'loss'}[]} buckets
+ * @param {string} [title]
+ * @returns {ChartPair}
+ */
+export function ratioDistributionBars(results, buckets, title) {
+  const success = results.filter((r) => r.ratio !== null && r.isSuccessTest !== false);
+  const counts = buckets.map(() => 0);
+  for (const r of success) {
+    const index = buckets.findIndex((b) => b.test(/** @type {number} */(r.ratio)));
+    if (index >= 0) counts[index] += 1;
+  }
+  return {
+    config: { type: 'bar', title: title ?? null, orient: 'h', valLabel: 'tests' },
+    data: {
+      categories: buckets.map((b) => b.label),
+      series: [{ name: 'tests', values: counts, tones: buckets.map((b) => b.tone) }],
+    },
+  };
+}
+
+/**
+ * The ratio scatter: every success-only test as one point, ranked
+ * fastest-ratio first, log-scale y, reference line at parity.
+ * @param {{ratio: number|null, isSuccessTest?: boolean}[]} results
+ * @param {string} [title]
+ * @returns {ChartPair}
+ */
+export function ratioScatter(results, title) {
+  const success = results
+    .filter((r) => r.ratio !== null && r.isSuccessTest !== false)
+    .map((r) => /** @type {number} */(r.ratio))
+    .sort((a, b) => b - a);
+  return {
+    config: {
+      type: 'scatter',
+      title: title ?? null,
+      yLog: true,
+      refY: 1,
+      refLabel: '1× (parity)',
+      xLabel: 'tests, fastest ratio first',
+      yLabel: 'ratio (log)',
+    },
+    data: {
+      points: success.map((ratio, i) => ({
+        x: i + 1,
+        y: ratio,
+        tone: ratio >= 1 ? 'win' : 'loss',
+      })),
+    },
+  };
+}
+
+/**
+ * Per-draft conformance: grouped bars of passed tests per engine.
+ * @param {Record<string, Record<string, {passed: number}>>} engineStats
+ *   engine → draft → {passed, failed, errors}
+ * @param {string} [title]
+ * @returns {ChartPair}
+ */
+export function conformanceBars(engineStats, title) {
+  const engines = Object.keys(engineStats);
+  const drafts = Object.keys(engineStats[engines[0]] ?? {});
+  return {
+    config: { type: 'bar', title: title ?? null, valLabel: 'tests passed' },
+    data: {
+      categories: drafts,
+      series: engines.map((engine) => ({
+        name: engine,
+        values: drafts.map((draft) => engineStats[engine]?.[draft]?.passed ?? null),
+      })),
+    },
+  };
+}
+
+/**
+ * Generic engine-comparison bars over `{name, results: {engine: value}}`
+ * profile rows (the toml/markdown/mermaid profile shape).
+ * @param {{name: string, results: Record<string, number>}[]} rows
+ * @param {string[]} engines series order (first = jaren)
+ * @param {{title?: string, log?: boolean, valLabel?: string}} [options]
+ * @returns {ChartPair}
+ */
+export function profileBars(rows, engines, options = {}) {
+  return {
+    config: {
+      type: 'bar',
+      title: options.title ?? null,
+      log: options.log === true,
+      valLabel: options.valLabel ?? null,
+    },
+    data: {
+      categories: rows.map((r) => r.name),
+      series: engines.map((engine) => ({
+        name: engine,
+        values: rows.map((r) => r.results?.[engine] ?? null),
+      })),
+    },
+  };
+}
+
+/**
+ * Scenario-matrix bars over `{scenario|title, engines: {key: nsPerOp}}`
+ * rows (the jsonquery/jslt shape). Log axis — rival engines span orders
+ * of magnitude.
+ * @param {{scenario?: string, title?: string, engines: Record<string, number>}[]} rows
+ * @param {{title?: string, valLabel?: string}} [options]
+ * @returns {ChartPair}
+ */
+export function matrixBars(rows, options = {}) {
+  const keys = [];
+  for (const row of rows) {
+    for (const key of Object.keys(row.engines ?? {})) {
+      if (!keys.includes(key)) keys.push(key);
+    }
+  }
+  keys.sort((a, b) => (a === 'jaren' ? -1 : b === 'jaren' ? 1 : 0));
+  return {
+    config: {
+      type: 'bar',
+      title: options.title ?? null,
+      log: true,
+      valLabel: options.valLabel ?? 'ns/op (log)',
+    },
+    data: {
+      categories: rows.map((r) => r.scenario ?? r.title ?? ''),
+      series: keys.map((key) => ({
+        name: key,
+        values: rows.map((r) => r.engines?.[key] ?? null),
+      })),
+    },
+  };
+}
+
+/**
+ * Suite pass-count bars over an `{engine: {pass, total}}` map (the
+ * toml-compliance / markdown-scorecard shape); the highlighted engine
+ * (ours) carries the win tone.
+ * @param {Record<string, {pass: number, total: number}>} scorecard
+ * @param {{title?: string, highlight?: string, valLabel?: string}} [options]
+ * @returns {ChartPair}
+ */
+export function passCountBars(scorecard, options = {}) {
+  const engines = Object.keys(scorecard);
+  return {
+    config: {
+      type: 'bar',
+      title: options.title ?? null,
+      orient: 'h',
+      valLabel: options.valLabel ?? 'tests passed',
+    },
+    data: {
+      categories: engines,
+      series: [{
+        name: 'passing',
+        values: engines.map((engine) => scorecard[engine]?.pass ?? null),
+        tones: engines.map((engine) => engine === options.highlight ? 'win' : null),
+      }],
+    },
+  };
+}
+
+/**
+ * The jsonpath per-query profile: horizontal grouped bars for the
+ * top-N queries by jaren-vs-rival spread (the rest stay in the table).
+ * @param {{name: string, engines: Record<string, number>}[]} rows
+ * @param {string} rival the comparison engine key (e.g. 'json-p3')
+ * @param {number} topN
+ * @param {string} [title]
+ * @returns {ChartPair}
+ */
+export function querySpreadBars(rows, rival, topN, title) {
+  const ranked = rows
+    .filter((r) => r.engines?.jaren > 0 && r.engines?.[rival] > 0)
+    .map((r) => ({ ...r, spread: r.engines[rival] / r.engines.jaren }))
+    .sort((a, b) => b.spread - a.spread)
+    .slice(0, topN);
+  return {
+    config: {
+      type: 'bar',
+      title: title ?? null,
+      orient: 'h',
+      log: true,
+      valLabel: 'ns/op (log)',
+    },
+    data: {
+      categories: ranked.map((r) => r.name),
+      series: [
+        { name: 'jaren', values: ranked.map((r) => r.engines.jaren) },
+        { name: rival, values: ranked.map((r) => r.engines[rival]) },
+      ],
+    },
+  };
+}
+
+/**
+ * Bars over a pointer/patch-style result table:
+ * `{columns, rows: [{name, results: number[]}]}`.
+ * @param {{title?: string, columns: string[], rows: {name: string, results: number[]}[]}} table
+ * @param {{title?: string, log?: boolean, valLabel?: string}} [options]
+ * @returns {ChartPair}
+ */
+export function resultTableBars(table, options = {}) {
+  return {
+    config: {
+      type: 'bar',
+      title: options.title ?? table.title ?? null,
+      log: options.log === true,
+      valLabel: options.valLabel ?? 'ns/op',
+    },
+    data: {
+      categories: table.rows.map((r) => r.name),
+      series: table.columns.map((column, i) => ({
+        name: column,
+        values: table.rows.map((r) => r.results?.[i] ?? null),
+      })),
+    },
+  };
+}
+
+/**
+ * Horizontal bars over `{label, ns}` timing rows (the view/charts
+ * benchmark shape). One series in one color: the bars are *nominal*
+ * categories — engines or scenarios — so their identity comes from the
+ * axis label, not from a hue, and the length is the whole message.
+ * Semantic win/loss tones are deliberately not used: on a timing chart
+ * "ours" is not automatically good, and docs/DESIGN.md reserves those tokens
+ * for genuine status.
+ * @param {{label: string, ns: number}[]} rows
+ * @param {{title?: string, log?: boolean, valLabel?: string}} [options]
+ * @returns {ChartPair}
+ */
+export function timingBars(rows, options = {}) {
+  return {
+    config: {
+      type: 'bar',
+      title: options.title ?? null,
+      orient: 'h',
+      log: options.log === true,
+      valLabel: options.valLabel ?? 'ns/op',
+    },
+    data: {
+      categories: rows.map((r) => r.label),
+      series: [{
+        name: options.valLabel ?? 'ns/op',
+        values: rows.map((r) => (Number.isFinite(r.ns) ? r.ns : null)),
+      }],
+    },
+  };
+}
+
+/**
+ * Cross-suite ratio bars for the benchmarks overview: one bar per suite
+ * headline, tone by which side of parity it lands on — here the tones
+ * ARE semantic (a ratio below 1 is a genuine loss, reported as one).
+ * @param {{key: string, label: string, ratio: number|null}[]} headlines
+ * @param {{title?: string}} [options]
+ * @returns {ChartPair}
+ */
+export function headlineRatioBars(headlines, options = {}) {
+  const usable = headlines.filter((h) => Number.isFinite(h.ratio) && h.ratio > 0);
+  return {
+    config: {
+      type: 'bar',
+      title: options.title ?? null,
+      orient: 'h',
+      log: true,
+      valLabel: '× vs the fastest rival (log)',
+    },
+    data: {
+      categories: usable.map((h) => h.label),
+      series: [{
+        name: 'ratio',
+        values: usable.map((h) => h.ratio),
+        tones: usable.map((h) => (h.ratio >= 1 ? 'win' : 'loss')),
+      }],
+    },
+  };
+}

package/src/transforms/mermaid-adapter.js

@@ -0,0 +1,19 @@
+//@ts-check
+/**
+ * @file Mermaid interop: map a mermaid pie AST (`{title, showData,
+ * slices}`) onto a chart definition + data pair. Lives in charts so the
+ * dependency arrow stays one-way — `@jarenjs/mermaid` imports this,
+ * never the reverse; nothing here touches mermaid code.
+ */
+
+/**
+ * Convert a mermaid pie AST to `compileChart`-shaped inputs.
+ * @param {{title?: string|null, showData?: boolean, slices: {label: string, value: number}[]}} ast
+ * @returns {{config: {type: 'pie', title: string|null}, data: {slices: {label: string, value: number}[]}}}
+ */
+export function mermaidPieToChartAST(ast) {
+  return {
+    config: { type: 'pie', title: ast.title ?? null },
+    data: { slices: ast.slices },
+  };
+}

package/src/types/bar.js

@@ -0,0 +1,276 @@
+//@ts-check
+/**
+ * @file The bar chart type: grouped or stacked, vertical or horizontal,
+ * linear or log value axis. Data shape:
+ *
+ *   data   = { categories: string[],
+ *              series: [{ name, values: number[],
+ *                         tone?: 'win'|'loss', tones?: (('win'|'loss'|null)[]) }] }
+ *   config = { type:'bar', title?, stacked?, log?, orient?: 'v'|'h',
+ *              catLabel?, valLabel? }
+ *
+ * The AST is orientation-agnostic: `u` runs along the category axis,
+ * `v` along the value axis; the render maps them to x/y per `orient`.
+ * Category lookups are hoisted out of the series loop (index-driven,
+ * never `categories.indexOf` per cell — that is O(n²) for wide charts).
+ */
+
+import { svgRoot, coord } from '@jarenjs/view/helpers';
+import { clamp01 } from '@jarenjs/core/math';
+import { scaleLinear, scaleLog, scaleBand } from '../core/scale.js';
+import { axisTicksLinear, axisTicksLog, niceStep, formatTickValue } from '../core/axis.js';
+import { cartesianFrame, toneColor, annotateChart } from '../core/cartesian.js';
+import { CATEGORICAL } from '../core/palette.js';
+import { normalizeTooltip, valueMark } from '../core/marks.js';
+
+/**
+ * @typedef {object} BarAST
+ * @property {'bar'} type
+ * @property {string|null} title
+ * @property {'v'|'h'} orient
+ * @property {{ticks: {pos:number,label:string}[], label: string|null}} cat
+ * @property {{ticks: {pos:number,label:string}[], label: string|null}} val
+ * @property {{name: string, swatch: number}[]|null} legend
+ * @property {BarMarkAST[]} bars
+ * @property {number} count number of categories
+ * @property {[number, number]} domain resolved value-axis bounds
+ */
+/**
+ * @typedef {object} BarMarkAST
+ * @property {number} u0 @property {number} u1 category-axis band
+ * @property {number} v0 @property {number} v1 value-axis extent
+ * @property {number} series series index
+ * @property {'win'|'loss'|null} tone
+ * @property {string} label the category this bar stands in
+ * @property {string} name the series name
+ * @property {number} value the drawn value (hover text reports it exactly)
+ */
+
+/**
+ * Scan the drawn values for the extremes the value axis is resolved
+ * from: the largest bar (a stacked chart's per-category total) and the
+ * smallest positive value a log axis needs for its bottom decade.
+ *
+ * Exported because the incremental session must reach the same bounds
+ * decision from the same numbers — one implementation, no drift.
+ * @param {any} data
+ * @param {boolean} stacked @param {boolean} log
+ * @returns {{maxVal: number, minPos: number}}
+ */
+export function scanBarExtremes(data, stacked, log) {
+  const categories = data?.categories ?? [];
+  const series = (data?.series ?? []).filter((s) => Array.isArray(s.values));
+  let maxVal = 0;
+  let minPos = Infinity;
+  for (let ci = 0; ci < categories.length; ci++) {
+    let sum = 0;
+    for (const s of series) {
+      const v = s.values[ci];
+      if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0) continue;
+      sum += v;
+      if (!stacked && v > maxVal) maxVal = v;
+      if (v < minPos) minPos = v;
+    }
+    if (stacked && sum > maxVal) maxVal = sum;
+  }
+  if (maxVal === 0) maxVal = 1;
+  if (!Number.isFinite(minPos)) minPos = log ? 0.1 : 0;
+  return { maxVal, minPos };
+}
+
+/**
+ * Resolve the value-axis bounds and tick values from the scanned
+ * extremes: a nice-number top over a zero base, or whole decades under
+ * `log`. The AST records the bounds so a later build — or the session —
+ * can detect "unchanged".
+ * @param {{maxVal: number, minPos: number}} ext
+ * @param {boolean} log
+ * @returns {{domain: [number, number], tickValues: number[]}}
+ */
+export function resolveBarDomains(ext, log) {
+  if (log) {
+    const lo = Math.pow(10, Math.floor(Math.log10(ext.minPos)));
+    const raw = Math.pow(10, Math.ceil(Math.log10(ext.maxVal)));
+    const hi = raw === lo ? lo * 10 : raw;
+    return { domain: [lo, hi], tickValues: axisTicksLog(lo, hi) };
+  }
+  const step = niceStep(ext.maxVal, 5);
+  const top = step * Math.ceil(ext.maxVal / step);
+  return { domain: [0, top], tickValues: axisTicksLinear(0, top, 5) };
+}
+
+/**
+ * The value scale over a resolved domain — reconstructable by the
+ * session from the AST's domain alone.
+ * @param {[number, number]} domain @param {boolean} log
+ * @returns {(v: number) => number}
+ */
+export function barScale(domain, log) {
+  return log ? scaleLog(domain[0], domain[1]) : scaleLinear(domain[0], domain[1]);
+}
+
+/**
+ * Build the geometry-free bar AST.
+ * @param {any} data
+ * @param {any} [config]
+ * @returns {BarAST}
+ */
+export function buildBarAST(data, config = {}) {
+  const categories = data?.categories ?? [];
+  const series = (data?.series ?? []).filter((s) => Array.isArray(s.values));
+  const stacked = config.stacked === true;
+  const log = config.log === true;
+
+  const domains = resolveBarDomains(scanBarExtremes(data, stacked, log), log);
+  const scale = barScale(domains.domain, log);
+  const valTicks = domains.tickValues;
+
+  const band = scaleBand(categories, 0.25);
+  const groups = stacked ? 1 : Math.max(1, series.length);
+  const sub = band.bandwidth / groups;
+  const bars = [];
+  const running = stacked ? new Array(categories.length).fill(0) : null;
+  for (let si = 0; si < series.length; si++) {
+    const s = series[si];
+    for (let ci = 0; ci < categories.length; ci++) {
+      const v = s.values[ci];
+      if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0) continue;
+      const start = band(categories[ci]);
+      let u0;
+      let u1;
+      let v0;
+      let v1;
+      if (stacked) {
+        u0 = start;
+        u1 = start + band.bandwidth;
+        const base = running[ci];
+        running[ci] = base + v;
+        v0 = base === 0 ? 0 : clamp01(scale(base));
+        v1 = clamp01(scale(running[ci]));
+      }
+      else {
+        u0 = start + si * sub + sub * 0.06;
+        u1 = start + (si + 1) * sub - sub * 0.06;
+        v0 = 0;
+        v1 = clamp01(scale(v));
+      }
+      bars.push({
+        u0, u1, v0, v1,
+        series: si,
+        tone: s.tones?.[ci] ?? s.tone ?? null,
+        label: String(categories[ci]),
+        name: String(s.name ?? ''),
+        value: v,
+      });
+    }
+  }
+
+  return {
+    type: 'bar',
+    title: config.title ?? null,
+    orient: config.orient === 'h' ? 'h' : 'v',
+    cat: {
+      ticks: categories.map((label) => ({ pos: band(label) + band.bandwidth / 2, label: String(label) })),
+      label: config.catLabel ?? null,
+    },
+    val: {
+      ticks: valTicks.map((v) => ({ pos: clamp01(scale(v)), label: formatTickValue(v) })),
+      label: config.valLabel ?? null,
+    },
+    legend: series.length > 1 ? series.map((s, i) => ({ name: s.name, swatch: i })) : null,
+    bars,
+    count: categories.length,
+    domain: domains.domain,
+  };
+}
+
+/**
+ * Render one bar as its `<rect>` value mark — the replaceable unit the
+ * incremental session re-emits when a live count changes.
+ * @param {BarMarkAST} bar
+ * @param {BarAST} ast
+ * @param {{x:number,y:number,w:number,h:number}} plot
+ * @param {{tokens: Record<string,string>}} theme
+ * @param {readonly string[]} palette
+ * @param {import('../core/marks.js').ChartTooltip|null} [tooltip]
+ * @returns {any}
+ */
+export function barMarkRender(bar, ast, plot, theme, palette, tooltip = null) {
+  let x; let y; let w; let h;
+  if (ast.orient === 'h') {
+    x = plot.x + bar.v0 * plot.w;
+    w = (bar.v1 - bar.v0) * plot.w;
+    y = plot.y + bar.u0 * plot.h;
+    h = (bar.u1 - bar.u0) * plot.h;
+  }
+  else {
+    x = plot.x + bar.u0 * plot.w;
+    w = (bar.u1 - bar.u0) * plot.w;
+    y = plot.y + (1 - bar.v1) * plot.h;
+    h = (bar.v1 - bar.v0) * plot.h;
+  }
+  const text = ast.legend !== null
+    ? `${bar.name} — ${bar.label}: ${bar.value}`
+    : `${bar.label}: ${bar.value}`;
+  return valueMark('rect', {
+    x: coord(x), y: coord(y), width: coord(Math.max(0.5, w)), height: coord(Math.max(0.5, h)),
+    fill: toneColor(theme, bar.tone, bar.series, palette), class: 'chart-bar',
+  }, tooltip, text, { type: 'bar', label: bar.label, series: bar.name, value: bar.value });
+}
+
+/**
+ * Render a bar AST and return the svg WITH the geometry a session needs
+ * to replace one bar in place: the plot rect and how many chrome
+ * children precede the bars.
+ * @param {BarAST} 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}}
+ */
+export function buildBarRender(ast, theme, hash, options = {}) {
+  const palette = options.palette ?? CATEGORICAL;
+  const tooltip = normalizeTooltip(options.tooltip);
+  const horizontal = ast.orient === 'h';
+  const frame = cartesianFrame({
+    title: ast.title,
+    legend: ast.legend,
+    xAxis: horizontal ? ast.val : { ...ast.cat, ticks: ast.cat.ticks },
+    yAxis: horizontal ? { ...ast.cat, ticks: ast.cat.ticks.map(flipPos) } : ast.val,
+    grid: horizontal ? 'x' : 'y',
+    width: options.width,
+    plotHeight: horizontal ? Math.max(80, ast.count * 28) : undefined,
+    palette,
+    theme,
+  });
+  const { plot } = frame;
+  const children = frame.children;
+  const chromeLen = children.length;
+  for (const bar of ast.bars)
+    children.push(barMarkRender(bar, ast, plot, theme, palette, tooltip));
+  const svg = svgRoot(options.rootClass ?? 'chart chart-svg chart-bar-chart',
+    frame.width, frame.height, theme, children, (options.keyPrefix ?? 'bar-') + hash);
+  annotateChart(svg, ast.title);
+  return { svg, plot, chromeLen };
+}
+
+/**
+ * Render a bar AST to a pure-vnode SVG. Each bar rect carries a
+ * `<title>` naming its series, category and exact value — the axis
+ * shows the rounded tick scale, the hover text shows the datum.
+ * @param {BarAST} 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 {any}
+ */
+export function renderBarAST(ast, theme, hash, options = {}) {
+  return buildBarRender(ast, theme, hash, options).svg;
+}
+
+/** In horizontal orientation the first category reads at the top. */
+function flipPos(tick) {
+  return { pos: 1 - tick.pos, label: tick.label };
+}