plotto 0.0.0-stage → 0.3.0

package/src/facets.js

@@ -0,0 +1,54 @@
+// Facets: splits the rows of each layer into panels and places the panels on a grid.
+import { naturalOrder } from "./scales.js";
+
+// Returns { kind, nrow, ncol, panels }. Each panel has row, col, labels and rows[layerIndex] (row numbers).
+export function facetPanels(ns) {
+  const f = ns.facet;
+  if (!f) return { kind: "none", nrow: 1, ncol: 1, panels: [panel(ns, 0, 0, {}, {})] };
+  if (f.kind === "wrap") {
+    const keys = levels(ns, f.by);
+    const ncol = f.ncol ?? wrapColumns(keys.length);
+    const panels = keys.map((k, i) => panel(ns, Math.floor(i / ncol), i % ncol, { [f.by]: k }, { top: k }));
+    return { kind: "wrap", nrow: Math.ceil(keys.length / ncol), ncol, panels };
+  }
+  const rowKeys = f.rows ? levels(ns, f.rows) : [null];
+  const colKeys = f.cols ? levels(ns, f.cols) : [null];
+  const panels = [];
+  rowKeys.forEach((rk, r) =>
+    colKeys.forEach((ck, c) => {
+      const match = {};
+      if (f.rows) match[f.rows] = rk;
+      if (f.cols) match[f.cols] = ck;
+      panels.push(panel(ns, r, c, match, { top: r === 0 ? ck : null, right: c === colKeys.length - 1 ? rk : null }));
+    })
+  );
+  return { kind: "grid", nrow: rowKeys.length, ncol: colKeys.length, panels };
+}
+
+// Number of columns of a facet wrap, the same rule as ggplot (grDevices::n2mfrow).
+function wrapColumns(n) {
+  if (n <= 3) return n;
+  if (n <= 6) return Math.ceil(n / 2);
+  if (n <= 12) return Math.ceil(n / 3);
+  return Math.ceil(Math.sqrt(n));
+}
+
+function levels(ns, column) {
+  const col = ns.tables[0].columns[column];
+  if (col.levels) return col.levels.filter((v) => col.values.includes(v));
+  return [...new Set(col.values.filter((v) => v !== null).map(String))].sort(naturalOrder);
+}
+
+// A layer without columns (for example hline(y=0)) has one row in each panel.
+// A layer table without the facet column repeats in each panel, as in ggplot.
+function panel(ns, row, col, match, strips) {
+  const rows = ns.layers.map((layer) => {
+    const t = ns.tables[layer.table];
+    if (!Object.values(layer.channels).some((c) => c.column)) return [0];
+    const tests = Object.entries(match).filter(([name]) => name in t.columns);
+    const all = Array.from({ length: t.n }, (_, i) => i);
+    if (!tests.length) return all;
+    return all.filter((i) => tests.every(([name, key]) => String(t.columns[name].values[i]) === key));
+  });
+  return { row, col, strips, rows };
+}

package/src/figure.js

@@ -0,0 +1,199 @@
+// Figure: computes the views, scales and layout, then draws the title, info table, strips, legend and panels as one SVG.
+// Observable Plot draws each panel. drawPanels() draws them again after a zoom or a legend click.
+import * as Plot from "@observablehq/plot";
+import * as d3 from "d3";
+import { facetPanels } from "./facets.js";
+import { drawInfo, infoModel } from "./info.js";
+import { LAYERS } from "./layers.js";
+import { drawLegend, legendModel } from "./legend.js";
+import { place, TICK } from "./layout.js";
+import { AXIS_CHANNELS, axisKind, colorScale, ticks, trainDomain } from "./scales.js";
+import { normalize } from "./spec.js";
+import { svgElement, svgText } from "./svg.js";
+import { fontSizes } from "./theme.js";
+import { layerEdges, makeView } from "./views.js";
+
+const NARROW = 560; // px: below this width, a right legend moves to the bottom
+const MIN_HEIGHT = 240; // px: the smallest height of a reflowed figure
+
+// options: document (the browser or jsdom), width (lay out at this width), domains and hidden (keep a view after a resize).
+export function figure(spec, { document: doc = globalThis.document, width, domains, hidden = new Set() } = {}) {
+  const ns = normalize(spec);
+  const theme = ns.theme;
+  const W = Math.round(width ?? theme.width);
+  const reflowed = width && theme.reflow && !theme.fixedHeight;
+  const H = reflowed ? Math.max(MIN_HEIGHT, Math.round((W * theme.height) / theme.width)) : theme.height;
+  if (theme.legend === "right" && W < NARROW) theme.legend = "bottom";
+  const fonts = fontSizes(theme);
+  const grid = facetPanels(ns);
+  const kind = { x: axisKind(ns, "x"), y: axisKind(ns, "y") };
+  const color = colorScale(ns);
+  const ctx = { ns, kind, colorLevels: color.domain ?? [], edges: layerEdges(ns) };
+  for (const p of grid.panels) p.views = ns.layers.map((layer, li) => makeView(ctx, layer, p.rows[li], new Set()));
+  const home = homeDomains(ns, grid, kind);
+  const horizontal = theme.legend === "bottom";
+  const info = infoModel(ns, fonts, { W, H, narrow: W < NARROW });
+  const above = info?.position === "right" ? info.height + fonts.base : 0; // the info card sits above a right legend
+  const legend = legendModel(ns, color, fonts, { horizontal, maxWidth: W * 0.9, maxHeight: H * 0.8 - above });
+  const layout = place({ ns, grid, kind, home, legend, info, fonts, W, H });
+
+  const svg = svgElement(doc, "svg", {
+    xmlns: "http://www.w3.org/2000/svg",
+    width: W,
+    height: H,
+    viewBox: `0 0 ${W} ${H}`,
+    "font-family": theme.font,
+    "font-size": fonts.base,
+    style: `color:${theme.ink}`,
+  });
+  svg.append(svgElement(doc, "rect", { width: W, height: H, fill: theme.background }));
+  for (const t of layout.texts) svg.append(svgText(doc, t.text, t.attrs));
+  if (info) svg.append(drawInfo(doc, info, theme, layout.info));
+  for (const s of layout.strips) svg.append(strip(doc, s, theme, fonts));
+  const state = { spec, ns, doc, svg, theme, fonts, grid, kind, color, ctx, legend, info, layout, home, W, H };
+  state.domains = domains ?? home;
+  state.hidden = hidden;
+  state.panelLayer = svg.appendChild(svgElement(doc, "g", { class: "pt-panels" }));
+  if (legend) state.legendG = svg.appendChild(placedLegend(state));
+  drawPanels(state);
+  return state;
+}
+
+export function toSVG(spec, options) {
+  return figure(spec, options).svg.outerHTML;
+}
+
+// Draws every panel with state.domains and state.hidden (the legend values that are switched off).
+export function drawPanels(state) {
+  const { ns, grid, ctx, hidden } = state;
+  if (hidden.size || state.filtered) {
+    for (const p of grid.panels) p.views = ns.layers.map((layer, li) => makeView(ctx, layer, p.rows[li], hidden));
+    state.filtered = hidden.size > 0;
+  }
+  state.panelLayer.replaceChildren();
+  state.panels = grid.panels.map((p, i) => drawPanel(state, p, i));
+  if (state.legendG) state.legendG.replaceWith((state.legendG = placedLegend(state)));
+}
+
+function placedLegend(state) {
+  const g = drawLegend(state.doc, state.legend, state.theme, state.fonts, state.hidden);
+  g.setAttribute("transform", `translate(${state.layout.legend.x},${state.layout.legend.y})`);
+  return g;
+}
+
+function drawPanel(state, p, i) {
+  const { ns, doc, theme, fonts, kind, color } = state;
+  const box = state.layout.panels[i];
+  const domain = { x: plotDomain(kind.x, state.domains[i].x), y: plotDomain(kind.y, state.domains[i].y) };
+  const bandwidth = { x: kind.x === "category" ? (box.innerW / (domain.x.length + 0.2)) * 0.8 : 0 };
+  const layers = ns.layers.map((layer, li) => {
+    const view = p.views[li];
+    const c = context({ view, layer, kind, color, theme, fonts, domain, bandwidth });
+    return { layer, view, c, marks: view.n ? LAYERS[layer.type](c) : [] };
+  });
+  const axis = (k) => {
+    const t = ticks(kind[k], state.domains[i][k], box.count[k], ns.scales[k]?.format);
+    const inside = (v) => kind[k] === "category" || (+v >= +domain[k][0] && +v <= +domain[k][1]);
+    return { major: t.major.filter(inside), minor: t.minor, format: t.format };
+  };
+  const ax = axis("x");
+  const ay = axis("y");
+  const gridStyle = (minor) => ({ stroke: minor ? theme.gridMinor : theme.grid, strokeOpacity: 1, strokeWidth: minor ? 0.6 : 0.9 });
+  const axisStyle = { tickSize: TICK.size, tickPadding: TICK.padding, fontSize: fonts.tick, stroke: theme.tick, fill: theme.muted, label: null };
+  const marks = [];
+  if (kind.x !== "category") marks.push(Plot.gridX(ax.minor, gridStyle(true)), Plot.gridX(ax.major, gridStyle(false)));
+  if (kind.y !== "category") marks.push(Plot.gridY(ay.minor, gridStyle(true)), Plot.gridY(ay.major, gridStyle(false)));
+  marks.push(...layers.flatMap((l) => l.marks));
+  if (box.showX) {
+    const rotate = box.rotateX ? { tickRotate: -40, textAnchor: "end" } : {};
+    marks.push(Plot.axisX(ax.major, { ...axisStyle, ...rotate, anchor: "bottom", tickFormat: ax.format }));
+  }
+  if (box.showY) marks.push(Plot.axisY(ay.major, { ...axisStyle, anchor: "left", tickFormat: ay.format }));
+  const plot = Plot.plot({
+    document: doc,
+    width: box.w,
+    height: box.h,
+    marginLeft: box.ml,
+    marginRight: 0,
+    marginTop: 0,
+    marginBottom: box.mb,
+    x: scaleOptions(kind.x, domain.x),
+    y: scaleOptions(kind.y, domain.y),
+    color: { type: "identity" },
+    marks,
+  });
+  const g = svgElement(doc, "g", { class: "pt-panel", "data-panel": i, transform: `translate(${box.x},${box.y})`, fill: "currentColor", "text-anchor": "middle" });
+  for (const child of [...plot.childNodes]) if (child.nodeName.toLowerCase() !== "style") g.append(child);
+  state.panelLayer.append(g);
+  return { g, plot, box, layers };
+}
+
+// Channel accessors of one layer view in one panel, for layers.js. Time values become Date objects.
+function context({ view, layer, kind, color, theme, fonts, domain, bandwidth }) {
+  const axisOf = (ch) => (AXIS_CHANNELS.x.includes(ch) ? "x" : AXIS_CHANNELS.y.includes(ch) ? "y" : null);
+  const cache = {};
+  const v = (ch) => {
+    if (ch in cache) return cache[ch];
+    let values = view.cols[ch];
+    if (values && kind[axisOf(ch)] === "time") values = values.map((t) => (t === null ? null : new Date(t)));
+    return (cache[ch] = values);
+  };
+  const colorCh = layer.channels.color;
+  return {
+    index: d3.range(view.n),
+    v,
+    options: layer.options,
+    colors: (fallback) => (!colorCh ? fallback : "value" in colorCh ? colorCh.value : v("color").map(color.apply)),
+    groups: () => v("group") ?? (colorCh?.column ? v("color") : undefined),
+    kind,
+    theme,
+    fonts,
+    domain,
+    bandwidth,
+  };
+}
+
+function plotDomain(kind, d) {
+  return kind === "time" ? d.map((t) => new Date(t)) : d;
+}
+
+function scaleOptions(kind, domain) {
+  const type = { linear: "linear", log: "log", time: "utc", category: "band" }[kind];
+  return { type, domain, axis: null, ...(kind === "category" ? { padding: 0.2, round: false } : {}) };
+}
+
+// The first view of each panel. A free axis has one domain per panel (wrap) or per row or column (grid).
+function homeDomains(ns, grid, kind) {
+  const free = ns.facet?.free ?? { x: false, y: false };
+  const groupOf = (axis, p, i) => (!free[axis] ? "all" : grid.kind === "grid" ? (axis === "x" ? `c${p.col}` : `r${p.row}`) : `p${i}`);
+  const domains = grid.panels.map(() => ({}));
+  for (const axis of ["x", "y"]) {
+    const groups = d3.group(grid.panels.map((p, i) => [p, i]), ([p, i]) => groupOf(axis, p, i));
+    for (const members of groups.values()) {
+      const d = homeDomain(ns, axis, kind[axis], members.map(([p]) => p));
+      for (const [, i] of members) domains[i][axis] = d;
+    }
+  }
+  return domains;
+}
+
+// Set limits win; a null bound (or no limits) takes the trained bound, with its 5% space.
+// On a category axis, the limits are the categories and their order.
+function homeDomain(ns, axis, kind, panels) {
+  const limits = ns.scales[axis]?.limits;
+  if (limits && (kind === "category" || limits.every((v) => v !== null))) return limits;
+  const trained = trainDomain(ns, axis, kind, panels);
+  return limits ? [limits[0] ?? trained[0], limits[1] ?? trained[1]] : trained;
+}
+
+function strip(doc, s, theme, fonts) {
+  const g = svgElement(doc, "g", { class: "pt-strip" });
+  g.append(svgElement(doc, "rect", { x: s.x, y: s.y, width: s.w, height: s.h, fill: theme.strip }));
+  const attrs = s.vertical
+    ? { transform: `translate(${s.x + s.w / 2},${s.y + s.h / 2}) rotate(90)`, dy: "0.35em" }
+    : { x: s.x + s.w / 2, y: s.y + s.h / 2, dy: "0.35em" };
+  const text = svgText(doc, s.text, { ...attrs, "text-anchor": "middle", "font-weight": "bold", "font-size": fonts.strip, fill: theme.ink });
+  if (s.text !== String(s.full)) text.append(svgText(doc, s.full, {}, "title"));
+  g.append(text);
+  return g;
+}

package/src/hover.js

@@ -0,0 +1,296 @@
+// Hover: finds what is under the pointer in one panel, and the content of its label box. One mode per kind of layer:
+// - lines and areas (line, step, area, density, smooth, ribbon): every series at the nearest x, with a crosshair;
+// - bars and bins: the whole stack (or dodge group) at that x, with the total of a stack;
+// - box: the quartiles of the box; tile: the value of the cell;
+// - points (and error bars): the nearest point. It stays picked until another point is clearly nearer.
+import * as d3 from "d3";
+import { hoverFormat } from "./scales.js";
+
+const RADIUS = 40; // px: the largest distance to a point or a line
+const CLOSE = 10; // px: a point this close wins over the lines
+const SNAP = 6; // px: series whose nearest x is this close to the snapped x share the label
+const KEEP = 4; // px: a new point must be this much nearer to replace the picked one
+const MAX_ROWS = 6; // more series than this at one x: the label shows only the series under the pointer
+const UNIFIED = ["line", "step", "area", "density", "smooth", "ribbon"];
+const SHAPES = ["bar", "hist", "tile", "box"];
+const POINTS = ["point", "path", "errorbar"];
+
+// (x, y): px inside panel i. previous: the last hit (for hysteresis). Returns a hit or null.
+export function pick(state, i, x, y, previous) {
+  const panel = state.panels[i];
+  const sx = panel.plot.scale("x");
+  const sy = panel.plot.scale("y");
+  const px = (v) => sx.apply(v) + (sx.bandwidth ?? 0) / 2;
+  const py = (v) => sy.apply(v) + (sy.bandwidth ?? 0) / 2;
+  const ctx = { state, sx, sy, px, py };
+  const box = boxUnderAny(ctx, panel, x);
+  if (box) return { ...box, panel: i };
+  const point = nearestPoint(ctx, panel, x, y, previous?.panel === i ? previous : null);
+  if (point && point.d <= CLOSE) return { ...pointHit(ctx, point), panel: i };
+  const lines = unified(ctx, panel, x, y, previous?.panel === i ? previous : null);
+  if (lines) return { ...lines, panel: i };
+  const shape = shapeUnder(ctx, panel, x, y);
+  if (shape) return { ...shape, panel: i };
+  if (point) return { ...pointHit(ctx, point), panel: i };
+  return null;
+}
+
+function seriesColor(state, layer, view, c, k) {
+  const ch = layer.channels.color;
+  if (!ch) return layer.type === "smooth" ? state.theme.accent : state.theme.palette[0];
+  return "value" in ch ? ch.value : state.color.apply(view.cols.color[k]);
+}
+
+function fmt(state, axis, v) {
+  if (v === null || v === undefined || Number.isNaN(v)) return "–";
+  if (axis && state.kind[axis] === "time") return timeFormat(state, axis)(v);
+  if (axis && state.kind[axis] === "category") return String(v);
+  return typeof v === "number" ? hoverFormat.number(v) : String(v);
+}
+
+// The time format of the hover label follows the data: months, days, minutes or seconds.
+function timeFormat(state, axis) {
+  state.timeFormats ??= {};
+  if (state.timeFormats[axis]) return state.timeFormats[axis];
+  const values = state.grid.panels.flatMap((p) => p.views.flatMap((v) => v.cols[axis] ?? [])).filter((t) => t !== null);
+  const all = (test) => values.every((t) => test(new Date(t)));
+  const pattern = all((d) => d.getUTCDate() === 1 && d.getUTCHours() === 0 && d.getUTCMinutes() === 0)
+    ? "%Y-%m"
+    : all((d) => d.getUTCHours() === 0 && d.getUTCMinutes() === 0)
+      ? "%Y-%m-%d"
+      : all((d) => d.getUTCSeconds() === 0)
+        ? "%m-%d %H:%M"
+        : "%m-%d %H:%M:%S";
+  return (state.timeFormats[axis] = d3.utcFormat(pattern));
+}
+
+function fieldText(state, f, k) {
+  return f.values2 ? `${fmt(state, f.axis, f.values[k])} – ${fmt(state, f.axis, f.values2[k])}` : fmt(state, f.axis, f.values[k]);
+}
+
+// --- points ---------------------------------------------------------------------------------
+
+function nearestPoint({ px, py }, panel, x, y, previous) {
+  let best = null;
+  let kept = null;
+  for (const { layer, view, c } of panel.layers) {
+    if (!POINTS.includes(layer.type) || !view.hover || !view.n) continue;
+    const { hx, hy } = view.hover;
+    for (let k = 0; k < view.n; k++) {
+      if (hx[k] === null || hy[k] === null) continue;
+      const d = Math.hypot(px(hx[k]) - x, py(hy[k]) - y);
+      if (d > RADIUS) continue;
+      const hit = { layer, view, c, k, d, x: px(hx[k]), y: py(hy[k]) };
+      if (!best || d < best.d) best = hit;
+      if (previous?.layer === layer && previous.k === k) kept = hit;
+    }
+  }
+  return kept && best && best.d > kept.d - KEEP ? kept : best;
+}
+
+function pointHit({ state }, { layer, view, c, k, x, y, d }) {
+  const color = seriesColor(state, layer, view, c, k);
+  const name = layer.channels.color?.column ? fmt(state, null, view.cols.color[k]) : null;
+  // A row that repeats the header (x and color map the same column) is left out.
+  const rows = view.hover.fields.map((f) => ({ label: f.label, value: fieldText(state, f, k) })).filter((r) => r.value !== name);
+  return { layer, k, d, color, header: name, rows, marks: [{ x, y, color }], anchor: { x, y } };
+}
+
+// --- lines and areas: every series at the nearest x -------------------------------------------
+
+function unified({ state, px, py }, panel, x, y, previous) {
+  const candidates = [];
+  for (const { layer, view, c } of panel.layers) {
+    if (!UNIFIED.includes(layer.type) || !view.hover || !view.n) continue;
+    const { hx, hy } = view.hover;
+    const series = c.groups() ?? [];
+    const nearest = new Map(); // series → candidate
+    for (let k = 0; k < view.n; k++) {
+      if (hx[k] === null || hy[k] === null) continue;
+      const dx = Math.abs(px(hx[k]) - x);
+      const key = series[k] ?? "";
+      if (dx <= RADIUS && (!nearest.has(key) || dx < nearest.get(key).dx)) nearest.set(key, { layer, view, c, k, dx, series: key });
+    }
+    candidates.push(...nearest.values());
+  }
+  if (!candidates.length) return null;
+  const snap = d3.least(candidates, (m) => m.dx);
+  const snapX = px(snap.view.hover.hx[snap.k]);
+  const members = candidates.filter((m) => Math.abs(px(m.view.hover.hx[m.k]) - snapX) <= SNAP);
+  for (const m of members) m.y = py(m.view.hover.hy[m.k]);
+  // The series under the pointer. It stays picked until another series is clearly nearer (noisy, crossing lines).
+  let strong = d3.least(members, (m) => Math.abs(m.y - y));
+  const kept = previous?.series !== undefined && members.find((m) => m.layer === previous.layer && m.series === previous.series);
+  if (kept && Math.abs(kept.y - y) < Math.abs(strong.y - y) + KEEP) strong = kept;
+  const name = (m) =>
+    m.layer.channels.color?.column ? fmt(state, null, m.view.cols.color[m.k]) : m.series !== "" ? String(m.series) : (m.view.hover.fields[1]?.label ?? m.layer.type);
+  const color = (m) => seriesColor(state, m.layer, m.view, m.c, m.k);
+  const xField = snap.view.hover.fields[0];
+  const xText = fmt(state, "x", snap.view.hover.hx[snap.k]);
+  const base = { crosshair: snapX, anchor: { x: snapX, y }, layer: strong.layer, series: strong.series };
+
+  // Many series: only the one under the pointer, like a single line; the others are counted.
+  if (members.length === 1 || members.length > MAX_ROWS) {
+    const rows = [{ label: xField?.label ?? "x", value: xText }, { label: strong.view.hover.fields[1]?.label ?? "y", value: unifiedValue(state, strong.layer, strong.view, strong.k) }];
+    const others = members.length - 1;
+    return { ...base, color: color(strong), header: name(strong), rows, note: others ? `${others} other series at this x` : null, marks: [{ x: snapX, y: strong.y, color: color(strong) }] };
+  }
+
+  // A few series: one row each, in the legend order; the one under the pointer in bold.
+  const order = seriesOrder(state);
+  members.sort((a, b) => order(a) - order(b) || a.y - b.y);
+  const rows = members.map((m) => ({ swatch: color(m), label: name(m), value: unifiedValue(state, m.layer, m.view, m.k), strong: m === strong }));
+  return {
+    ...base,
+    color: state.theme.ink,
+    header: xField ? `${xField.label}  ${xText}` : xText,
+    rows,
+    marks: members.map((m) => ({ x: snapX, y: m.y, color: color(m) })),
+  };
+}
+
+// A sort key of a series: the legend position of its color, its color value (a number), or the plot order.
+function seriesOrder(state) {
+  const { color } = state;
+  return (m) => {
+    const v = m.layer.channels.color?.column ? m.view.cols.color[m.k] : null;
+    if (v === null) return state.ns.layers.indexOf(m.layer);
+    if (color.kind === "ordinal") return color.domain.indexOf(v);
+    return typeof v === "number" ? v : 0;
+  };
+}
+
+function unifiedValue(state, layer, view, k) {
+  const f = view.hover.fields;
+  if (layer.type === "smooth" && f[2]) return `${fieldText(state, f[1], k)}  (${fieldText(state, f[2], k)})`;
+  return fieldText(state, f[1], k);
+}
+
+// --- bars, bins, tiles and boxes ------------------------------------------------------------
+
+// A box wins over the points drawn with it (a box with jittered points).
+function boxUnderAny(ctx, panel, x) {
+  for (const { layer, view, c } of panel.layers) if (layer.type === "box" && view.n) return boxUnder(ctx, layer, view, c, x);
+  return null;
+}
+
+// Bars and bins: the column under the pointer (gaps between columns included), the segment under the pointer
+// or else the top one. Tiles: the cell under the pointer (band padding included).
+function shapeUnder(ctx, panel, x, y) {
+  const { state, sx, sy } = ctx;
+  for (const { layer, view, c } of panel.layers) {
+    if (!SHAPES.includes(layer.type) || layer.type === "box" || !view.n) continue;
+    const tile = layer.type === "tile";
+    let best = null;
+    for (let k = 0; k < view.n; k++) {
+      const [x0, x1] = shapeX(layer, view, k, sx);
+      // Tiles: the cell itself plus its padding. Bars: the nearest column, up to one bar width away (gaps included).
+      const dx = Math.abs((x0 + x1) / 2 - x);
+      if (tile ? x < x0 - pad(sx, x1 - x0) || x > x1 + pad(sx, x1 - x0) : dx > x1 - x0) continue;
+      const [ya, yb] = shapeY(layer, view, k, sy);
+      const [y0, y1] = [Math.min(ya, yb), Math.max(ya, yb)];
+      const padY = tile ? pad(sy, y1 - y0) : 0;
+      const inside = y >= y0 - padY && y <= y1 + padY;
+      if (tile && !inside) continue;
+      // The nearest column first; in it, the segment under the pointer, or else the top segment.
+      const score = Math.round(dx) * 1e6 + (inside ? 0 : 1e5 + y0);
+      if (!best || score < best.score) best = { k, score, rect: { x: x0, y: y0, width: x1 - x0, height: y1 - y0 } };
+    }
+    if (!best) continue;
+    const { k, rect } = best;
+    const color = seriesColor(state, layer, view, c, k);
+    if (tile) {
+      const label = state.ns.labels.color ?? layer.channels.color?.column ?? "value";
+      const value = layer.channels.color?.column ? fmt(state, null, view.cols.color[k]) : null;
+      const rows = view.hover.fields.filter((f) => f.label !== label).map((f) => ({ label: f.label, value: fieldText(state, f, k) }));
+      return { color, header: value !== null ? `${label}  ${value}` : null, rows, marks: [{ rect, color: state.theme.ink }], anchor: { x: rect.x + rect.width, y } };
+    }
+    return stackHit(state, layer, view, c, k, rect);
+  }
+  return null;
+}
+
+// Half of the free space around a band (category) cell, in px.
+function pad(scale, size) {
+  return scale.bandwidth !== undefined ? (scale.step - scale.bandwidth) / 2 || size * 0.125 : 0.5;
+}
+
+// All segments at the x of segment k: one row per color, the hovered one in bold, and the total of a stack.
+function stackHit(state, layer, view, c, k, rect) {
+  const sameX = layer.type === "hist" ? (j) => view.cols.xmin[j] === view.cols.xmin[k] : (j) => String(view.cols.x[j]) === String(view.cols.x[k]);
+  const at = d3.range(view.n).filter(sameX);
+  const colored = !!layer.channels.color?.column;
+  const rows = at
+    .sort((a, b) => (colored && state.color.kind === "ordinal" ? state.color.domain.indexOf(view.cols.color[a]) - state.color.domain.indexOf(view.cols.color[b]) : view.cols.ymax[b] - view.cols.ymax[a]))
+    .map((j) => ({
+      swatch: seriesColor(state, layer, view, c, j),
+      label: colored ? fmt(state, null, view.cols.color[j]) : view.hover.fields[1].label,
+      value: fmt(state, null, view.cols.value[j]),
+      strong: j === k && at.length > 1,
+    }));
+  const position = layer.options.position ?? "stack";
+  if (position === "stack" && at.length > 1) rows.push({ label: "total", value: fmt(state, null, d3.sum(at, (j) => view.cols.value[j])), strong: false, total: true });
+  const xf = view.hover.fields[0];
+  return { color: seriesColor(state, layer, view, c, k), header: `${xf.label}  ${fieldText(state, xf, k)}`, rows, marks: [{ rect, color: state.theme.ink }], anchor: { x: rect.x + rect.width, y: rect.y } };
+}
+
+function boxUnder({ state, sx }, layer, view, c, x) {
+  if (sx.bandwidth === undefined) return null;
+  const k = d3.range(view.n).find((j) => {
+    const x0 = sx.apply(view.cols.x[j]);
+    return x >= x0 && x <= x0 + sx.bandwidth;
+  });
+  if (k === undefined) return null;
+  const key = String(view.cols.x[k]);
+  const values = d3.range(view.n).filter((j) => String(view.cols.x[j]) === key).map((j) => view.cols.y[j]).filter((v) => v !== null).sort(d3.ascending);
+  const [q1, median, q3] = [0.25, 0.5, 0.75].map((p) => d3.quantile(values, p));
+  const iqr = q3 - q1;
+  const low = d3.min(values.filter((v) => v >= q1 - 1.5 * iqr));
+  const high = d3.max(values.filter((v) => v <= q3 + 1.5 * iqr));
+  const outliers = values.filter((v) => v < low || v > high).length;
+  const f = (v) => fmt(state, "y", v);
+  const rows = [
+    { label: "max (whisker)", value: f(high) },
+    { label: "q3", value: f(q3) },
+    { label: "median", value: f(median), strong: true },
+    { label: "q1", value: f(q1) },
+    { label: "min (whisker)", value: f(low) },
+    { label: "n", value: String(values.length) },
+  ];
+  if (outliers) rows.push({ label: "outliers", value: String(outliers) });
+  const x0 = sx.apply(view.cols.x[k]);
+  const color = layer.channels.color?.column ? seriesColor(state, layer, view, c, k) : state.theme.ink;
+  return { color, header: `${view.hover.fields[0].label}  ${key}`, rows, marks: [], anchor: { x: x0 + sx.bandwidth, y: null } };
+}
+
+function shapeX(layer, view, k, sx) {
+  if (view.cols.xmin && layer.type !== "tile") return [sx.apply(view.cols.xmin[k]), sx.apply(view.cols.xmax[k])];
+  if (sx.bandwidth !== undefined) {
+    const slots = view.cols.slots?.[k] ?? 1;
+    const slice = sx.bandwidth / slots;
+    const x0 = sx.apply(view.cols.x[k]) + (view.cols.slot?.[k] ?? 0) * slice;
+    return [x0, x0 + slice];
+  }
+  const half = halfStep(view.cols.x, sx);
+  const cx = sx.apply(view.cols.x[k]);
+  return [cx - half, cx + half];
+}
+
+function shapeY(layer, view, k, sy) {
+  if (layer.type === "tile") {
+    if (sy.bandwidth !== undefined) return [sy.apply(view.cols.y[k]), sy.apply(view.cols.y[k]) + sy.bandwidth];
+    const half = halfStep(view.cols.y, sy);
+    const cy = sy.apply(view.cols.y[k]);
+    return [cy - half, cy + half];
+  }
+  return [sy.apply(view.cols.ymin[k]), sy.apply(view.cols.ymax[k])];
+}
+
+// Half of the smallest step between values, in px.
+function halfStep(values, scale) {
+  const sorted = [...new Set(values.map(Number))].sort((a, b) => a - b);
+  let step = Infinity;
+  for (let i = 1; i < sorted.length; i++) step = Math.min(step, sorted[i] - sorted[i - 1]);
+  if (!Number.isFinite(step)) return 6;
+  return Math.abs(scale.apply(sorted[0] + step) - scale.apply(sorted[0])) / 2;
+}

package/src/index.js

@@ -0,0 +1,4 @@
+// Public API: plot (the builder), draw (browser output), toSVG (static SVG string).
+export { plot } from "./builder.js";
+export { draw } from "./interact.js";
+export { toSVG } from "./figure.js";

package/src/info.js

@@ -0,0 +1,83 @@
+// Info table: the key/value entries of info(), as a card in the right column or below the plot.
+import * as d3 from "d3";
+import { svgElement, svgText } from "./svg.js";
+import { fitText, textWidth, wrapText } from "./text.js";
+
+const VALUE_LINES = 3; // a long value wraps to this many lines
+const KEY_SHARE = 0.45; // the key column takes at most this share of the table width
+const MAX_WIDTH = { right: 0.3, bottom: 0.9 }; // share of the figure width
+const MAX_HEIGHT = { right: 0.6, bottom: 0.3 }; // share of the figure height; the rest of the entries become "+N more"
+const MAX_COLUMNS = 3; // columns of entries in a bottom card
+
+// The info model with its position and size. narrow: a right placement moves to the bottom.
+export function infoModel(ns, fonts, { W, H, narrow }) {
+  if (!ns.info) return null;
+  const position = narrow ? "bottom" : ns.info.position;
+  return model(ns, fonts, ns.info.entries, position, W, H * MAX_HEIGHT[position]);
+}
+
+function model(ns, fonts, entries, position, W, maxHeight) {
+  const metrics = ns.theme.metrics;
+  const size = fonts.legend;
+  const pad = Math.round(size * 0.8);
+  const lineH = size * 1.35;
+  const keyGap = size;
+  const colGap = size * 2;
+  const all = entries.map(([key, value]) => ({ key: String(key), value: value === null ? "–" : String(value) }));
+  const width = (t) => textWidth(t, size, false, metrics);
+
+  // One column of rows, at most maxWidth wide: the keys on the left, the values wrapped on the right.
+  const column = (items, maxWidth) => {
+    const keyW = Math.min(d3.max(items, (r) => width(r.key)) ?? 0, maxWidth * KEY_SHARE);
+    const valueMax = Math.max(size * 3, maxWidth - keyW - keyGap);
+    let y = 0;
+    const laid = items.map((r) => {
+      const lines = wrapText(r.value, size, valueMax, false, metrics, VALUE_LINES);
+      const row = { key: fitText(r.key, size, keyW, false, metrics), full: r.key, lines, y };
+      y += lines.length * lineH;
+      return row;
+    });
+    const valueW = d3.max(laid, (r) => d3.max(r.lines, width)) ?? 0;
+    return { rows: laid, keyW, width: keyW + keyGap + valueW, height: y };
+  };
+
+  const inner = W * MAX_WIDTH[position] - 2 * pad;
+  const table = (rows) => {
+    let columns;
+    if (position === "bottom") {
+      const natural = d3.max(rows, (r) => width(r.key) + keyGap + width(r.value)) ?? 0;
+      const k = Math.max(1, Math.min(MAX_COLUMNS, rows.length, Math.floor((inner + colGap) / (natural + colGap))));
+      const perColumn = Math.ceil(rows.length / k);
+      const colW = (inner - colGap * (k - 1)) / k;
+      columns = d3.range(k).map((j) => column(rows.slice(j * perColumn, (j + 1) * perColumn), colW));
+    } else columns = [column(rows, inner)];
+    let x = pad;
+    for (const c of columns) (c.x = x), (x += c.width + colGap);
+    return { columns, width: x - colGap + pad, height: (d3.max(columns, (c) => c.height) ?? 0) + 2 * pad };
+  };
+  // Drop entries from the end until the table fits; the last row tells how many are not shown.
+  let kept = all.length;
+  let t = table(all);
+  while (t.height > maxHeight && kept > 1) {
+    kept--;
+    t = table([...all.slice(0, kept), { key: `+${all.length - kept} more`, value: "" }]);
+  }
+  return { position, size, pad, lineH, keyGap, ...t };
+}
+
+// The table as an SVG group at (x, y): keys in the muted color, values in the ink color, on a strip-colored card.
+export function drawInfo(doc, model, theme, { x, y }) {
+  const g = svgElement(doc, "g", { class: "pt-info", transform: `translate(${x},${y})`, "font-size": model.size });
+  g.append(svgElement(doc, "rect", { width: model.width, height: model.height, fill: theme.strip }));
+  const baseline = model.lineH * 0.75;
+  for (const c of model.columns) {
+    for (const r of c.rows) {
+      const top = model.pad + r.y + baseline;
+      const key = svgText(doc, r.key, { x: c.x, y: top, fill: theme.muted, "text-anchor": "start" });
+      if (r.key !== r.full) key.append(svgText(doc, r.full, {}, "title"));
+      g.append(key);
+      r.lines.forEach((line, i) => g.append(svgText(doc, line, { x: c.x + c.keyW + model.keyGap, y: top + i * model.lineH, fill: theme.ink, "text-anchor": "start" })));
+    }
+  }
+  return g;
+}