plotto 0.0.0-stage → 0.3.0

package/src/legend.js

@@ -0,0 +1,104 @@
+// Legend: color swatches (a string column) or a color ramp (a number or time column), as SVG.
+import * as d3 from "d3";
+import { ticks } from "./scales.js";
+import { svgElement, svgText } from "./svg.js";
+import { fitText, textWidth } from "./text.js";
+
+const KEY = 18; // swatch width, px
+const GAP = 6;
+const RAMP = { thick: 12, long: 150, slices: 48 };
+const LINE_LAYERS = ["line", "path", "step", "density", "smooth", "hline", "vline", "abline", "segment", "errorbar"];
+const FILL_LAYERS = ["bar", "hist", "area", "ribbon", "rect", "tile", "box"];
+
+// The legend model with its size. horizontal: below the plot. maxWidth, maxHeight: the space for it.
+export function legendModel(ns, color, fonts, { horizontal, maxWidth, maxHeight }) {
+  if (color.kind === "none" || ns.theme.legend === "none") return null;
+  const metrics = ns.theme.metrics;
+  const width = (t, size, bold) => textWidth(t, size, bold, metrics);
+  const title = ns.labels.color === null ? null : (ns.labels.color ?? color.column);
+  const titleH = title ? fonts.legend * 1.8 : 0;
+  const titleW = title ? width(title, fonts.legend + 1, true) : 0;
+
+  if (color.kind === "continuous") {
+    const t = ticks(color.type === "time" ? "time" : "linear", color.domain, 4);
+    const labels = t.major.map(t.format);
+    const labelW = d3.max(labels, (l) => width(l, fonts.legend)) ?? 0;
+    const long = Math.min(RAMP.long, horizontal ? maxWidth : maxHeight - titleH - 4);
+    const [w, h] = horizontal ? [long, RAMP.thick + fonts.legend * 1.6] : [RAMP.thick + GAP + labelW, long];
+    return { kind: "ramp", title, titleH, color, long, ticks: t.major, labels, width: Math.max(titleW, w), height: titleH + h, horizontal };
+  }
+
+  const mapped = ns.layers.filter((l) => l.channels.color?.column);
+  const key = mapped.some((l) => FILL_LAYERS.includes(l.type)) ? "square" : mapped.some((l) => LINE_LAYERS.includes(l.type)) ? "line" : "point";
+  const rowH = Math.round(fonts.legend * 1.75);
+  const maxLabel = Math.max(80, (horizontal ? maxWidth : 220) - KEY - GAP);
+  const items = color.domain.map((value) => {
+    const label = fitText(value, fonts.legend, maxLabel, false, metrics);
+    return { value, label, color: color.apply(value), w: KEY + GAP + width(label, fonts.legend) };
+  });
+  if (!horizontal) {
+    // Columns of rows, so that a long legend fits the panel height.
+    const perColumn = Math.max(1, Math.floor((maxHeight - titleH) / rowH));
+    const columns = d3.range(Math.ceil(items.length / perColumn)).map((k) => items.slice(k * perColumn, (k + 1) * perColumn));
+    let x = 0;
+    for (const column of columns) {
+      column.forEach((it, i) => Object.assign(it, { x, y: titleH + i * rowH }));
+      x += (d3.max(column, (it) => it.w) ?? 0) + fonts.legend;
+    }
+    const rows = Math.min(items.length, perColumn);
+    return { kind: "swatches", title, titleH, key, rowH, items, width: Math.max(titleW, x - fonts.legend), height: titleH + rows * rowH, horizontal };
+  }
+  let x = 0;
+  let y = titleH;
+  for (const it of items) {
+    if (x > 0 && x + it.w > maxWidth) [x, y] = [0, y + rowH];
+    Object.assign(it, { x, y });
+    x += it.w + fonts.legend * 1.5;
+  }
+  const w = Math.max(titleW, d3.max(items, (it) => it.x + it.w) ?? 0);
+  return { kind: "swatches", title, titleH, key, rowH, items, width: w, height: y + rowH, horizontal };
+}
+
+export function drawLegend(doc, model, theme, fonts, hidden = new Set()) {
+  const g = svgElement(doc, "g", { class: "pt-legend", "font-size": fonts.legend });
+  if (model.title) g.append(svgText(doc, model.title, { y: fonts.legend, "font-weight": "bold", "font-size": fonts.legend + 1, fill: theme.ink }));
+  if (model.kind === "ramp") drawRamp(doc, g, model, theme, fonts);
+  else model.items.forEach((it, i) => g.append(swatch(doc, model, it, i, theme, hidden.has(it.value))));
+  return g;
+}
+
+function swatch(doc, model, it, i, theme, off) {
+  const mid = model.rowH / 2;
+  const g = svgElement(doc, "g", { class: "pt-key", "data-index": i, transform: `translate(${it.x},${it.y})`, opacity: off ? 0.35 : 1 });
+  const hit = svgElement(doc, "rect", { width: it.w, height: model.rowH, fill: "transparent" });
+  const mark =
+    model.key === "line"
+      ? svgElement(doc, "line", { x1: 1, x2: KEY - 1, y1: mid, y2: mid, stroke: it.color, "stroke-width": Math.max(2.5, theme.line + 1) })
+      : model.key === "point"
+        ? svgElement(doc, "circle", { cx: KEY / 2, cy: mid, r: Math.max(3.5, theme.point + 1), fill: it.color })
+        : svgElement(doc, "rect", { x: 3, y: mid - 6, width: 12, height: 12, fill: it.color });
+  const label = svgText(doc, it.label, { x: KEY + GAP, y: mid, dy: "0.35em", fill: theme.muted, "text-decoration": off ? "line-through" : null });
+  g.append(hit, mark, label);
+  return g;
+}
+
+function drawRamp(doc, g, model, theme, fonts) {
+  const { color, horizontal, long } = model;
+  const [lo, hi] = color.domain.map(Number);
+  const at = (v) => (Number(v) - lo) / (hi - lo || 1); // 0..1 along the ramp
+  const top = model.titleH;
+  for (let i = 0; i < RAMP.slices; i++) {
+    const t0 = i / RAMP.slices;
+    const size = long / RAMP.slices + 0.5; // overlap a little, so no gaps show
+    const fill = color.ramp(horizontal ? t0 : 1 - t0);
+    const rect = horizontal ? { x: t0 * long, y: top, width: size, height: RAMP.thick } : { x: 0, y: top + t0 * long, width: RAMP.thick, height: size };
+    g.append(svgElement(doc, "rect", { ...rect, fill }));
+  }
+  model.ticks.forEach((v, i) => {
+    const p = at(v) * long;
+    const attrs = horizontal
+      ? { x: p, y: top + RAMP.thick + fonts.legend * 1.2, "text-anchor": "middle" }
+      : { x: RAMP.thick + GAP, y: top + long - p, dy: "0.35em" };
+    g.append(svgText(doc, model.labels[i], { ...attrs, fill: theme.muted }));
+  });
+}

package/src/metrics.js

@@ -0,0 +1,2 @@
+// Generated by scripts/font_metrics.py. Advance widths in em of the characters 32-126, per theme font.
+export const METRICS = {"arial": {"regular": [0.278, 0.278, 0.355, 0.556, 0.556, 0.889, 0.667, 0.191, 0.333, 0.333, 0.389, 0.584, 0.278, 0.333, 0.278, 0.278, 0.556, 0.556, 0.556, 0.556, 0.556, 0.556, 0.556, 0.556, 0.556, 0.556, 0.278, 0.278, 0.584, 0.584, 0.584, 0.556, 1.015, 0.667, 0.667, 0.722, 0.722, 0.667, 0.611, 0.778, 0.722, 0.278, 0.5, 0.667, 0.556, 0.833, 0.722, 0.778, 0.667, 0.778, 0.722, 0.667, 0.611, 0.722, 0.667, 0.944, 0.667, 0.667, 0.611, 0.278, 0.278, 0.278, 0.469, 0.556, 0.333, 0.556, 0.556, 0.5, 0.556, 0.556, 0.278, 0.556, 0.556, 0.222, 0.222, 0.5, 0.222, 0.833, 0.556, 0.556, 0.556, 0.556, 0.333, 0.5, 0.278, 0.556, 0.5, 0.722, 0.5, 0.5, 0.5, 0.334, 0.26, 0.334, 0.584], "bold": [0.278, 0.333, 0.474, 0.556, 0.556, 0.889, 0.722, 0.238, 0.333, 0.333, 0.389, 0.584, 0.278, 0.333, 0.278, 0.278, 0.556, 0.556, 0.556, 0.556, 0.556, 0.556, 0.556, 0.556, 0.556, 0.556, 0.333, 0.333, 0.584, 0.584, 0.584, 0.611, 0.975, 0.722, 0.722, 0.722, 0.722, 0.667, 0.611, 0.778, 0.722, 0.278, 0.556, 0.722, 0.611, 0.833, 0.722, 0.778, 0.667, 0.778, 0.722, 0.667, 0.611, 0.722, 0.667, 0.944, 0.667, 0.667, 0.611, 0.333, 0.278, 0.333, 0.584, 0.556, 0.333, 0.556, 0.611, 0.556, 0.611, 0.556, 0.333, 0.611, 0.611, 0.278, 0.278, 0.556, 0.278, 0.889, 0.611, 0.611, 0.611, 0.611, 0.389, 0.556, 0.333, 0.611, 0.556, 0.778, 0.556, 0.556, 0.5, 0.389, 0.28, 0.389, 0.584]}, "mplus": {"regular": [0.29, 0.363, 0.4, 0.678, 0.605, 0.847, 0.712, 0.237, 0.385, 0.385, 0.527, 0.733, 0.304, 0.457, 0.283, 0.507, 0.62, 0.62, 0.62, 0.62, 0.62, 0.62, 0.62, 0.62, 0.62, 0.62, 0.363, 0.384, 0.667, 0.753, 0.667, 0.611, 0.823, 0.693, 0.598, 0.695, 0.682, 0.587, 0.572, 0.745, 0.71, 0.317, 0.527, 0.633, 0.585, 0.857, 0.713, 0.793, 0.6, 0.785, 0.62, 0.573, 0.653, 0.683, 0.693, 0.953, 0.65, 0.67, 0.637, 0.47, 0.507, 0.47, 0.653, 0.583, 0.278, 0.548, 0.578, 0.522, 0.578, 0.552, 0.522, 0.573, 0.573, 0.307, 0.347, 0.562, 0.307, 0.805, 0.568, 0.57, 0.573, 0.573, 0.453, 0.497, 0.512, 0.558, 0.557, 0.81, 0.553, 0.557, 0.547, 0.513, 0.343, 0.513, 0.69], "bold": [0.304, 0.425, 0.478, 0.692, 0.625, 0.901, 0.753, 0.291, 0.426, 0.426, 0.536, 0.735, 0.351, 0.471, 0.338, 0.546, 0.64, 0.64, 0.64, 0.64, 0.64, 0.64, 0.64, 0.64, 0.64, 0.64, 0.418, 0.431, 0.681, 0.755, 0.681, 0.628, 0.818, 0.715, 0.62, 0.703, 0.696, 0.601, 0.586, 0.756, 0.735, 0.351, 0.558, 0.678, 0.6, 0.878, 0.735, 0.798, 0.628, 0.798, 0.651, 0.608, 0.668, 0.705, 0.715, 0.971, 0.678, 0.698, 0.651, 0.501, 0.546, 0.501, 0.695, 0.609, 0.336, 0.576, 0.606, 0.54, 0.606, 0.57, 0.543, 0.601, 0.605, 0.335, 0.378, 0.603, 0.335, 0.843, 0.6, 0.585, 0.601, 0.601, 0.485, 0.525, 0.533, 0.59, 0.581, 0.831, 0.585, 0.585, 0.568, 0.535, 0.381, 0.535, 0.705]}};

package/src/render.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+// Static export in Node: spec → SVG (jsdom) → PNG (resvg). The same figure code runs in the browser.
+//   node src/render.mjs spec.json out.svg|out.png [scale]   one file
+//   plotto-render --serve                                     (the npm bin)
+//   node src/render.mjs --serve                              JSON lines on stdin/stdout (python/plotto/output.py)
+import { Resvg } from "@resvg/resvg-js";
+import { readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { fileURLToPath } from "node:url";
+import { JSDOM } from "jsdom";
+import { toSVG } from "./figure.js";
+import { firstFamily, resolveTheme } from "./theme.js";
+
+const { document } = new JSDOM("").window;
+
+export function renderSVG(spec) {
+  return toSVG(spec, { document });
+}
+
+export function renderPNG(spec, scale = 2) {
+  const svg = renderSVG(spec);
+  const font = firstFamily(resolveTheme(spec.theme).font);
+  const resvg = new Resvg(svg, { fitTo: { mode: "zoom", value: scale }, font: { loadSystemFonts: true, defaultFontFamily: font } });
+  return resvg.render().asPng();
+}
+
+// The browser bundle: src/ as one ES module that sets window.plotto.
+// cdn = true loads d3 and Plot from the CDN (notebook outputs); cdn = false puts them in the bundle (offline pages, tests).
+// format "iife" gives a classic script, which also loads from a file:// page.
+const bundleCache = {};
+export async function bundle({ cdn = true, format = "esm" } = {}) {
+  const key = `${cdn}-${format}`;
+  if (bundleCache[key]) return bundleCache[key];
+  const esbuild = await import("esbuild");
+  const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url)));
+  const urls = {
+    d3: `https://cdn.jsdelivr.net/npm/d3@${pkg.dependencies.d3}/+esm`,
+    "@observablehq/plot": `https://cdn.jsdelivr.net/npm/@observablehq/plot@${pkg.dependencies["@observablehq/plot"]}/+esm`,
+  };
+  const fromCDN = {
+    name: "cdn",
+    setup(build) {
+      build.onResolve({ filter: /^(d3|@observablehq\/plot)$/ }, (args) => ({ path: urls[args.path], external: true }));
+    },
+  };
+  const result = await esbuild.build({
+    entryPoints: [fileURLToPath(new URL("./browser.js", import.meta.url))],
+    bundle: true,
+    write: false,
+    format: cdn ? "esm" : format,
+    minify: true,
+    plugins: cdn ? [fromCDN] : [],
+  });
+  return (bundleCache[key] = result.outputFiles[0].text);
+}
+
+async function handle(request) {
+  if (request.op === "svg") return { svg: renderSVG(request.spec) };
+  if (request.op === "png") return { png: Buffer.from(renderPNG(request.spec, request.scale)).toString("base64") };
+  if (request.op === "bundle") return { js: await bundle({ cdn: request.cdn ?? true, format: request.format }) };
+  throw new Error(`unknown op "${request.op}"`);
+}
+
+// Run as a command (directly, or through the npm bin link, which is a symlink to this file).
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [arg, out, scale] = process.argv.slice(2);
+  if (arg === "--serve") {
+    for await (const line of createInterface({ input: process.stdin })) {
+      const request = JSON.parse(line);
+      try {
+        process.stdout.write(JSON.stringify({ id: request.id, ...(await handle(request)) }) + "\n");
+      } catch (e) {
+        process.stdout.write(JSON.stringify({ id: request.id, error: e.message }) + "\n");
+      }
+    }
+  } else {
+    const spec = JSON.parse(readFileSync(arg, "utf8"));
+    writeFileSync(out, out.endsWith(".png") ? renderPNG(spec, Number(scale ?? 2)) : renderSVG(spec));
+  }
+}

package/src/scales.js

@@ -0,0 +1,159 @@
+// Scales: axis types, domains, ticks, tick labels and the color scale.
+// Time values are wall-clock epoch ms, drawn with UTC functions, so the labels show the clock time of the data.
+import * as d3 from "d3";
+import { colorOf, interpolator, palette } from "./theme.js";
+
+export const AXIS_CHANNELS = { x: ["x", "xmin", "xmax", "xend"], y: ["y", "ymin", "ymax", "yend"] };
+const EXPAND = 0.05; // 5% space on each side of a continuous axis, as in ggplot
+const DAY = 86_400_000;
+
+// "linear", "log", "time" or "category": the scale type, or else the type of the first mapped column.
+export function axisKind(ns, axis) {
+  const type = ns.scales[axis]?.type;
+  if (type) return type;
+  for (const layer of ns.layers) {
+    for (const ch of AXIS_CHANNELS[axis]) {
+      const col = layer.channels[ch]?.column;
+      if (!col) continue;
+      const t = ns.tables[layer.table].columns[col].type;
+      return t === "time" ? "time" : t === "string" ? "category" : "linear";
+    }
+  }
+  return "linear";
+}
+
+// The values of one channel for the given rows of the layer table; a constant repeats for each row.
+export function channelValues(ns, layer, ch, rows) {
+  const c = layer.channels[ch];
+  if (!c) return undefined;
+  if ("value" in c) return rows.map(() => c.value);
+  const values = ns.tables[layer.table].columns[c.column].values;
+  return rows.map((i) => values[i]);
+}
+
+// The domain of one axis over the views of a set of panels. Continuous domains get the 5% expansion.
+export function trainDomain(ns, axis, kind, panels) {
+  const values = [];
+  for (const p of panels) {
+    for (const view of p.views) {
+      for (const ch of AXIS_CHANNELS[axis]) {
+        const v = view.cols[ch];
+        if (v) for (const x of v) if (x !== null && x !== undefined && (kind === "category" || Number.isFinite(x))) values.push(x);
+      }
+    }
+  }
+  if (kind === "category") return categories(ns, axis, values);
+  const domain = d3.extent(values.filter((v) => kind !== "log" || v > 0));
+  if (domain[0] === undefined) return kind === "log" ? [1, 10] : [0, 1];
+  return expand(domain, kind);
+}
+
+function categories(ns, axis, values) {
+  const levels = ns.layers.map((l) => l.channels[axis]?.column && ns.tables[l.table].columns[l.channels[axis].column].levels).find(Boolean);
+  const seen = new Set(values.map(String));
+  return levels ? levels.filter((v) => seen.has(v)) : [...seen].sort(naturalOrder);
+}
+
+export function naturalOrder(a, b) {
+  return String(a).localeCompare(String(b), undefined, { numeric: true });
+}
+
+export function expand([lo, hi], kind) {
+  if (kind === "log") {
+    const [a, b] = expand([Math.log10(lo), Math.log10(hi)], "linear");
+    return [10 ** a, 10 ** b];
+  }
+  const pad = hi > lo ? (hi - lo) * EXPAND : kind === "time" ? 3_600_000 : Math.abs(lo) * EXPAND || 1;
+  return [lo - pad, hi + pad];
+}
+
+// Major ticks, minor ticks (midpoints, as ggplot) and the label format of one axis.
+export function ticks(kind, domain, count, format) {
+  if (kind === "category") return { major: domain, minor: [], format: String };
+  const [lo, hi] = domain;
+  if (kind === "time") {
+    const major = d3.scaleUtc().domain([new Date(lo), new Date(hi)]).ticks(count);
+    const pattern = format ?? timePattern(major, hi - lo);
+    return { major, minor: midpoints(major, domain, (d) => +d).map((t) => new Date(t)), format: d3.utcFormat(pattern) };
+  }
+  if (kind === "log") {
+    const decades = d3.range(Math.ceil(Math.log10(lo)), Math.floor(Math.log10(hi)) + 1).map((e) => 10 ** e);
+    // Less than two decades in view: 1, 2 and 5 times the powers of ten.
+    const major = decades.length >= 2 ? decades : d3.scaleLog().domain(domain).ticks(count).filter((v) => [1, 2, 5].includes(Math.round(v / 10 ** Math.floor(Math.log10(v) + 1e-9))));
+    const minor = decades.flatMap((d) => d3.range(2, 10).map((k) => (d / 10) * k)).filter((v) => v > lo && v < hi);
+    return { major, minor, format: d3.format(format ?? "~g") };
+  }
+  const major = d3.ticks(lo, hi, count);
+  return { major, minor: midpoints(major, domain, Number), format: format ? d3.format(format) : d3.tickFormat(lo, hi, count) };
+}
+
+function midpoints(major, [lo, hi], num) {
+  if (major.length < 2) return [];
+  const step = num(major[1]) - num(major[0]);
+  const out = [num(major[0]) - step / 2, ...major.map((t) => num(t) + step / 2)];
+  return out.filter((v) => v > lo && v < hi);
+}
+
+// One-line date labels: the shortest pattern that still shows the tick step.
+function timePattern(major, span) {
+  const step = major.length >= 2 ? major[1] - major[0] : span;
+  if (step >= 28 * DAY) return "%Y-%m";
+  if (step >= DAY) return "%m-%d";
+  if (step >= 60_000) return span > DAY ? "%m-%d %H:%M" : "%H:%M";
+  return "%H:%M:%S";
+}
+
+// Hover label formats: 4 significant digits in decimal notation (with thousands separators), and short dates.
+const significant = d3.format(",.4~r");
+export const hoverFormat = {
+  number: (v) => (v === null || v === undefined ? "–" : Math.abs(v) >= 1e15 || (v !== 0 && Math.abs(v) < 1e-4) ? d3.format(".3~e")(v) : significant(v)),
+  time: d3.utcFormat("%m-%d %H:%M"),
+  string: (v) => (v === null || v === undefined ? "–" : String(v)),
+};
+
+// The color scale of the plot: "none", "ordinal" (a string column) or "continuous" (a number or time column).
+// apply(value) → color; ramp(t) → the color at t ∈ [0, 1] of the legend ramp.
+export function colorScale(ns) {
+  const theme = ns.theme;
+  const opts = ns.scales.color ?? {};
+  const mapped = ns.layers.filter((l) => l.channels.color?.column);
+  if (!mapped.length) return { kind: "none" };
+  const column = mapped[0].channels.color.column;
+  const other = mapped.find((l) => l.channels.color.column !== column);
+  if (other) throw new Error(`plotto: color maps "${column}" and "${other.channels.color.column}". Map color to one column only`);
+  const cols = mapped.map((l) => ns.tables[l.table].columns[column]);
+  const type = cols[0].type;
+  const all = cols.flatMap((c) => c.values).filter((v) => v !== null);
+  const resolve = (c) => colorOf(theme, c) ?? c;
+
+  if (type === "string") {
+    const levels = cols.find((c) => c.levels)?.levels;
+    const seen = new Set(all);
+    const domain = opts.limits ?? (levels ? levels.filter((v) => seen.has(v)) : [...seen].sort(naturalOrder));
+    const colors = opts.palette ? palette(theme, opts.palette) : theme.palette;
+    const values = opts.values;
+    const pick = Array.isArray(values)
+      ? (v, i) => resolve(values[i % values.length])
+      : values
+        ? (v, i) => resolve(values[v] ?? colors[i % colors.length])
+        : (v, i) => colors[i % colors.length];
+    const map = new Map(domain.map((v, i) => [v, pick(v, i)]));
+    return { kind: "ordinal", column, domain, apply: (v) => map.get(v) ?? theme.muted };
+  }
+
+  const [lo, hi] = limitsOf(opts.limits, d3.extent(all));
+  const interpolate = interpolator(theme, opts.values ?? opts.scheme ?? theme.scheme);
+  // mid: a diverging scale, with mid at the center of the scheme.
+  const mid = opts.mid;
+  const t = (v) => (mid === undefined ? (v - lo) / (hi - lo || 1) : v < mid ? 0.5 * ((v - lo) / (mid - lo || 1)) : 0.5 + 0.5 * ((v - mid) / (hi - mid || 1)));
+  const inside = (v) => v >= lo && v <= hi;
+  const apply = (v) => (v === null ? theme.muted : opts.clamp || inside(v) ? interpolate(Math.max(0, Math.min(1, t(v)))) : theme.muted);
+  const ramp = (u) => apply(lo + u * (hi - lo));
+  return { kind: "continuous", column, domain: [lo, hi], type, interpolate, apply, ramp };
+}
+
+// Limits with null bounds: a null bound takes the data bound.
+export function limitsOf(limits, data) {
+  if (!limits) return data;
+  return [limits[0] ?? data[0], limits[1] ?? data[1]];
+}

package/src/spec.js

@@ -0,0 +1,64 @@
+// Validates a spec and adds the defaults. This is the only file that knows the defaults.
+// Output: tables, layers with resolved channels ({column} or {value}), facet, scales, labels, info and theme.
+import GRAMMAR from "../grammar.json" with { type: "json" };
+import { colorOf, colorTokens, resolveTheme } from "./theme.js";
+
+export function normalize(spec, overrides = {}) {
+  if (typeof spec?.spec === "function") spec = spec.spec(); // a builder
+  if (spec?.version !== 1) throw new Error("plotto: unknown spec version");
+  const theme = resolveTheme({ ...spec.theme, ...overrides });
+  const tables = spec.data.map(toTable);
+  const layers = spec.layers.map((l) => resolveLayer(l, spec.mapping ?? {}, tables, theme));
+  if (!layers.length) throw new Error("plotto: the plot has no layers. Add one, for example .line() or .point()");
+  const facet = resolveFacet(spec.facet);
+  const labels = { ...defaultLabels(layers), ...spec.labels };
+  const info = spec.info?.entries?.length ? { entries: spec.info.entries, position: spec.info.position ?? "right" } : null;
+  return { tables, layers, facet, scales: spec.scales ?? {}, labels, info, theme };
+}
+
+function toTable({ columns }) {
+  const names = Object.keys(columns);
+  const n = names.length ? columns[names[0]].values.length : 1;
+  return { columns, n };
+}
+
+function resolveLayer(layer, plotMapping, tables, theme) {
+  const def = GRAMMAR.layers[layer.type];
+  if (!def) throw new Error(`plotto: unknown layer type "${layer.type}". Valid: ${Object.keys(GRAMMAR.layers).join(", ")}`);
+  const table = layer.data ?? 0;
+  const columns = tables[table].columns;
+  const channels = {};
+  for (const ch of def.channels) {
+    if (layer.mapping?.[ch] !== undefined) channels[ch] = { column: layer.mapping[ch] };
+    else if (layer.set?.[ch] !== undefined) channels[ch] = { value: layer.set[ch] };
+    else if (def.inherit !== false && plotMapping[ch] in columns) channels[ch] = { column: plotMapping[ch] };
+  }
+  const missing = def.requires.filter((ch) => !channels[ch]);
+  if (missing.length) throw new Error(`${layer.type}(): set ${missing.join(" and ")}, as a column name or a value`);
+  if (channels.color && "value" in channels.color) {
+    const color = colorOf(theme, channels.color.value);
+    if (!color) throw new Error(`${layer.type}(): "${channels.color.value}" is not a column or a color. Theme colors: ${colorTokens(theme).join(", ")}`);
+    channels.color = { value: color };
+  }
+  const options = {};
+  for (const opt of def.options) if (layer.set?.[opt] !== undefined) options[opt] = layer.set[opt];
+  return { type: layer.type, table, channels, options };
+}
+
+function resolveFacet(facet) {
+  if (!facet) return null;
+  const free = { x: ["x", "both"].includes(facet.free), y: ["y", "both"].includes(facet.free) };
+  if (facet.wrap) return { kind: "wrap", by: facet.wrap, ncol: facet.ncol ?? null, free };
+  return { kind: "grid", rows: facet.rows ?? null, cols: facet.cols ?? null, free };
+}
+
+// Axis and legend titles default to the first mapped column name. Stat layers name their computed y.
+function defaultLabels(layers) {
+  const first = (names) => {
+    for (const l of layers) for (const n of names) if (l.channels[n]?.column) return l.channels[n].column;
+    return undefined;
+  };
+  const stat = layers.find((l) => l.type === "hist" || l.type === "density");
+  const y = first(["y", "ymin", "yend"]) ?? (stat ? (stat.type === "density" || stat.options.density ? "density" : "count") : undefined);
+  return { x: first(["x", "xmin", "xend"]), y, color: first(["color"]) };
+}

package/src/stats.js

@@ -0,0 +1,187 @@
+// Statistics of the stat layers: summary, stack and dodge, bins, density and smooth.
+// Input and output are columns: { x: [...], y: [...], color: [...], ... }. Times are epoch ms numbers.
+import * as d3 from "d3";
+
+const GRID = 80; // points of a smooth or density curve
+
+// Rows grouped by the values of the given columns, in first-seen order: [{ key: [...], idx: [...] }].
+export function groupRows(cols, names, n) {
+  const groups = new Map();
+  for (let i = 0; i < n; i++) {
+    const key = names.map((k) => cols[k]?.[i] ?? null);
+    const id = JSON.stringify(key);
+    if (!groups.has(id)) groups.set(id, { key, idx: [] });
+    groups.get(id).idx.push(i);
+  }
+  return [...groups.values()];
+}
+
+// One row per (x, color, group): y is the summary of the group values.
+export function summarize(cols, n, fn) {
+  const reduce = { mean: d3.mean, median: d3.median, min: d3.min, max: d3.max, sum: d3.sum }[fn];
+  const out = { x: [], y: [], color: [], group: [] };
+  for (const { key, idx } of groupRows(cols, ["x", "color", "group"], n)) {
+    if (key[0] === null) continue;
+    out.x.push(key[0]);
+    out.y.push(reduce(idx, (i) => cols.y[i]));
+    out.color.push(key[1]);
+    out.group.push(key[2]);
+  }
+  return out;
+}
+
+// Stacks y within each x, in the order of the color levels: positive values up, negative values down.
+// overlay: no stack (ymin = 0). dodge: each color gets a slot k of nk at the same x.
+export function position(cols, n, mode, colorLevels) {
+  const order = (i) => (cols.color ? colorLevels.indexOf(cols.color[i]) : 0);
+  const present = cols.color ? colorLevels.filter((v) => cols.color.includes(v)) : [null];
+  const out = { ...cols, ymin: new Array(n), ymax: new Array(n), value: cols.y.slice(), slot: new Array(n), slots: new Array(n) };
+  // Dodge stacks within (x, color), so that each color has its own column of bars.
+  for (const { idx } of groupRows(cols, mode === "dodge" ? ["x", "color"] : ["x"], n)) {
+    idx.sort((a, b) => order(a) - order(b));
+    let up = 0;
+    let down = 0;
+    idx.forEach((i, k) => {
+      const v = cols.y[i] ?? 0;
+      if (mode !== "overlay") {
+        const base = v >= 0 ? up : down;
+        [out.ymin[i], out.ymax[i]] = [base, base + v];
+        if (v >= 0) up += v;
+        else down += v;
+      } else [out.ymin[i], out.ymax[i]] = [0, v];
+      out.slot[i] = mode === "dodge" && cols.color ? present.indexOf(cols.color[i]) : 0;
+      out.slots[i] = mode === "dodge" ? present.length : 1;
+    });
+  }
+  out.y = out.ymax;
+  return out;
+}
+
+// x intervals for bars on a continuous x: 90% of the data resolution, split into the dodge slots.
+export function barIntervals(cols, n) {
+  const xs = [...new Set(cols.x.filter((v) => v !== null))].sort((a, b) => a - b);
+  const step = d3.min(d3.pairs(xs), ([a, b]) => b - a) ?? 1;
+  const w = step * 0.9;
+  const xmin = [];
+  const xmax = [];
+  for (let i = 0; i < n; i++) {
+    const slice = w / cols.slots[i];
+    xmin.push(cols.x[i] - w / 2 + cols.slot[i] * slice);
+    xmax.push(cols.x[i] - w / 2 + (cols.slot[i] + 1) * slice);
+  }
+  return { ...cols, xmin, xmax };
+}
+
+// Shared bin edges for all panels and colors: about `bins` bins on nice values.
+export function binEdges(values, bins) {
+  const finite = values.filter((v) => v !== null && Number.isFinite(v));
+  const [lo, hi] = d3.extent(finite);
+  if (lo === undefined) return [0, 1];
+  if (lo === hi) return [lo - 0.5, hi + 0.5];
+  const edges = d3.ticks(...d3.nice(lo, hi, bins), bins);
+  if (edges[0] > lo) edges.unshift(edges[0] - (edges[1] - edges[0]));
+  if (edges.at(-1) < hi) edges.push(edges.at(-1) + (edges[1] - edges[0]));
+  return edges;
+}
+
+// Counts (or densities) per bin and color: one row per (bin, color), with x = the bin center.
+export function bin(cols, n, edges, density) {
+  const out = { x: [], xmin: [], xmax: [], y: [], color: [] };
+  const binner = d3.bin().domain([edges[0], edges.at(-1)]).thresholds(edges.slice(1, -1));
+  for (const { key, idx } of groupRows(cols, ["color"], n)) {
+    const values = idx.map((i) => cols.x[i]).filter((v) => v !== null && Number.isFinite(v));
+    for (const b of binner(values)) {
+      const count = b.length;
+      out.x.push((b.x0 + b.x1) / 2);
+      out.xmin.push(b.x0);
+      out.xmax.push(b.x1);
+      out.y.push(density ? count / (values.length * (b.x1 - b.x0) || 1) : count);
+      out.color.push(key[0]);
+    }
+  }
+  return out;
+}
+
+// Gaussian kernel density per color, with the Silverman bandwidth, on a grid that covers the data ± 3 bandwidths.
+export function density(cols, n) {
+  const out = { x: [], y: [], color: [], group: [] };
+  for (const { key, idx } of groupRows(cols, ["color"], n)) {
+    const v = idx.map((i) => cols.x[i]).filter((x) => x !== null && Number.isFinite(x));
+    if (v.length < 2) continue;
+    const sd = d3.deviation(v);
+    const iqr = d3.quantile(v, 0.75) - d3.quantile(v, 0.25);
+    const bw = 0.9 * Math.min(sd, iqr / 1.34 || sd) * v.length ** -0.2 || 1;
+    const [lo, hi] = d3.extent(v);
+    for (const x of d3.range(GRID).map((k) => lo - 3 * bw + ((hi - lo + 6 * bw) * k) / (GRID - 1))) {
+      const y = d3.sum(v, (xi) => Math.exp(-0.5 * ((x - xi) / bw) ** 2)) / (v.length * bw * Math.sqrt(2 * Math.PI));
+      out.x.push(x);
+      out.y.push(y);
+      out.color.push(key[0]);
+      out.group.push(key[0]);
+    }
+  }
+  return out;
+}
+
+// A smooth curve per color: "lm" (least squares, with a 95% confidence band) or "loess" (local linear, tricube weights).
+export function smooth(cols, n, { method = "lm", span = 0.75, band = true }) {
+  const out = { x: [], y: [], ymin: [], ymax: [], color: [], group: [] };
+  for (const { key, idx } of groupRows(cols, ["color"], n)) {
+    const pts = idx.map((i) => [cols.x[i], cols.y[i]]).filter(([x, y]) => x !== null && y !== null && Number.isFinite(x) && Number.isFinite(y));
+    if (pts.length < 3) continue;
+    pts.sort((a, b) => a[0] - b[0]);
+    const [lo, hi] = [pts[0][0], pts.at(-1)[0]];
+    const grid = d3.range(GRID).map((k) => lo + ((hi - lo) * k) / (GRID - 1));
+    const fit = method === "loess" ? loess(pts, grid, span) : linear(pts, grid);
+    fit.forEach(({ x, y, se }) => {
+      const t = tQuantile(pts.length - 2);
+      out.x.push(x);
+      out.y.push(y);
+      out.ymin.push(band && se !== undefined ? y - t * se : null);
+      out.ymax.push(band && se !== undefined ? y + t * se : null);
+      out.color.push(key[0]);
+      out.group.push(key[0]);
+    });
+  }
+  return out;
+}
+
+function linear(pts, grid) {
+  const n = pts.length;
+  const mx = d3.mean(pts, (p) => p[0]);
+  const my = d3.mean(pts, (p) => p[1]);
+  const sxx = d3.sum(pts, (p) => (p[0] - mx) ** 2) || 1;
+  const b = d3.sum(pts, (p) => (p[0] - mx) * (p[1] - my)) / sxx;
+  const a = my - b * mx;
+  const s = Math.sqrt(d3.sum(pts, (p) => (p[1] - a - b * p[0]) ** 2) / Math.max(1, n - 2));
+  return grid.map((x) => ({ x, y: a + b * x, se: s * Math.sqrt(1 / n + (x - mx) ** 2 / sxx) }));
+}
+
+function loess(pts, grid, span) {
+  const k = Math.max(3, Math.ceil(span * pts.length));
+  return grid.map((x) => {
+    const near = pts.map(([px, py]) => [Math.abs(px - x), px, py]).sort((a, b) => a[0] - b[0]).slice(0, k);
+    const dmax = near.at(-1)[0] || 1;
+    let [sw, swx, swy, swxx, swxy] = [0, 0, 0, 0, 0];
+    for (const [d, px, py] of near) {
+      const w = (1 - (d / dmax) ** 3) ** 3;
+      sw += w;
+      swx += w * px;
+      swy += w * py;
+      swxx += w * px * px;
+      swxy += w * px * py;
+    }
+    const det = sw * swxx - swx * swx;
+    const b = Math.abs(det) < 1e-12 ? 0 : (sw * swxy - swx * swy) / det;
+    const a = (swy - b * swx) / sw;
+    return { x, y: a + b * x };
+  });
+}
+
+// 97.5% quantile of Student's t (two-sided 95%), from a short table.
+function tQuantile(df) {
+  const table = [12.71, 4.3, 3.18, 2.78, 2.57, 2.45, 2.36, 2.31, 2.26, 2.23, 2.2, 2.18, 2.16, 2.14, 2.13, 2.12, 2.11, 2.1, 2.09, 2.09];
+  if (df < 1) return NaN;
+  if (df <= table.length) return table[df - 1];
+  return df <= 30 ? 2.05 : df <= 60 ? 2.0 : 1.96;
+}

package/src/svg.js

@@ -0,0 +1,14 @@
+// SVG element helpers. All elements come from the given document (the browser or jsdom).
+export const SVG_NS = "http://www.w3.org/2000/svg";
+
+export function svgElement(doc, tag, attrs = {}) {
+  const el = doc.createElementNS(SVG_NS, tag);
+  for (const [k, v] of Object.entries(attrs)) if (v !== undefined && v !== null) el.setAttribute(k, String(v));
+  return el;
+}
+
+export function svgText(doc, text, attrs, tag = "text") {
+  const el = svgElement(doc, tag, attrs);
+  el.textContent = text;
+  return el;
+}

package/src/text.js

@@ -0,0 +1,44 @@
+// Text width estimate from the font tables in metrics.js. Node and the browser get the same numbers,
+// so the layout (margins, legend, strips) is the same in every output.
+import { METRICS } from "./metrics.js";
+
+const CJK_START = 0x2e80; // CJK, kana and full-width forms are one em wide.
+
+export function textWidth(text, size, bold = false, metrics = "arial") {
+  const table = METRICS[metrics][bold ? "bold" : "regular"];
+  let em = 0;
+  for (const ch of String(text)) {
+    const code = ch.codePointAt(0);
+    if (code >= 32 && code < 127) em += table[code - 32];
+    else em += code >= CJK_START ? 1 : 0.6;
+  }
+  return em * size;
+}
+
+// The text cut with an ellipsis so that it fits in maxWidth.
+export function fitText(text, size, maxWidth, bold, metrics) {
+  text = String(text);
+  if (textWidth(text, size, bold, metrics) <= maxWidth) return text;
+  const chars = [...text];
+  while (chars.length > 1 && textWidth(chars.join("") + "…", size, bold, metrics) > maxWidth) chars.pop();
+  return chars.join("") + "…";
+}
+
+// Greedy word wrap into at most maxLines lines; the last line gets an ellipsis if the text is longer.
+export function wrapText(text, size, maxWidth, bold, metrics, maxLines = 2) {
+  const words = String(text).split(/\s+/);
+  const lines = [];
+  let line = "";
+  for (const word of words) {
+    const next = line ? `${line} ${word}` : word;
+    if (line && textWidth(next, size, bold, metrics) > maxWidth) {
+      lines.push(line);
+      line = word;
+    } else line = next;
+  }
+  lines.push(line);
+  if (lines.length <= maxLines) return lines;
+  const kept = lines.slice(0, maxLines);
+  kept[maxLines - 1] = fitText(lines.slice(maxLines - 1).join(" "), size, maxWidth, bold, metrics);
+  return kept;
+}