@liggi/figkit 0.1.0 → 0.3.0

package/viz/draw.js

@@ -108,7 +108,7 @@ export function drawChange(host, spec) {
 
 const themeOf = (host) => {
   const css = (n) => getComputedStyle(host).getPropertyValue(n).trim();
-  return { css, ink: css('--ink'), muted: css('--muted'), soft: css('--soft'), line: css('--line'), accent: css('--accent'), second: css('--second'), good: css('--good'), bad: css('--bad'), small: parseFloat(css('--small')) || 15, body: parseFloat(css('--body')) || 16, sans: css('--sans') };
+  return { css, ink: css('--ink'), muted: css('--muted'), soft: css('--soft'), fill: css('--fill'), fill2: css('--fill2'), hair: css('--hair'), paper: css('--paper'), line: css('--line'), accent: css('--accent'), second: css('--second'), good: css('--good'), bad: css('--bad'), small: parseFloat(css('--small')) || 15, body: parseFloat(css('--body')) || 16, sans: css('--sans') };
 };
 const toX = (v) => (typeof v === 'number' ? v : new Date(v));
 const num = (n) => (Math.abs(n) >= 100 ? Math.round(n) : Math.round(n * 10) / 10).toLocaleString('en-GB');
@@ -153,7 +153,7 @@ export function drawDumbbell(host, spec) {
     marks: [
       Plot.text(rows, { y: 'label', text: 'label', frameAnchor: 'left', dx: -(Math.ceil(labelW) + 28), textAnchor: 'start', fill: t.ink, fontSize: t.body }),
       Plot.link(rows, { x1: 'a', x2: 'b', y1: 'label', y2: 'label', stroke: 'color', strokeWidth: 3 }),
-      Plot.dot(rows, { x: 'a', y: 'label', r: 6.5, fill: t.soft }),
+      Plot.dot(rows, { x: 'a', y: 'label', r: 6.5, fill: t.fill }),
       // A fixed-size head at the end, pointing the way the row moved.
       // A fixed-size head whose tip, not its middle, sits on the end value.
       Plot.dot(rows.filter((r) => r.b >= r.a), { x: 'b', y: 'label', symbol: 'triangle2', r: 7.5, dx: -5, fill: 'color', rotate: 90 }),
@@ -165,6 +165,7 @@ export function drawDumbbell(host, spec) {
   const key = document.createElement('p');
   key.className = 'fd-key';
   key.innerHTML = `<span class="fd-from"><i></i>${esc(spec.fromLabel)}</span><span class="fd-to${rows.every((r) => r.b < r.a) ? ' back' : ''}" style="color:${t.accent}"><i></i>${esc(spec.toLabel)}</span>`;
+  key.style.marginLeft = labelW + 'px';
   host.prepend(key);
 }
 
@@ -194,19 +195,107 @@ export function drawSeries(host, spec) {
     y: { label: null, grid: true, ticks: 4, tickSize: 0, domain: zero ? [bottom, top * 1.04] : undefined, tickFormat: fmt },
     marks: [
       zero ? Plot.ruleY([0], { stroke: t.line }) : null,
-      Plot.lineY(pts, { x: 'x', y: 'y', stroke: t.soft, strokeWidth: 2.5 }),
+      Plot.lineY(pts, { x: 'x', y: 'y', stroke: t.fill, strokeWidth: 2.5 }),
       Plot.dot([mark], { x: 'x', y: 'y', r: 6.5, fill: t.accent }),
       Plot.text([mark], { x: 'x', y: 'y', text: () => spec.mark.label, dx: right ? 14 : -14, dy, textAnchor: right ? 'start' : 'end', fill: t.accent, fontWeight: 600, fontSize: t.body }),
     ],
   });
 }
 
-const HOSTS = { split: 'fig-split', bars: 'fig-bars', 'before-after': 'fig-change', dumbbell: 'div', series: 'div' };
+/**
+ * Where each record sits: every arrangement of the records over a few small grids is scored, and the best kept.
+ * A score counts references that cross, references that pass over another record, long references, and records drawn
+ * above what they point at (a reference reads upward, to the thing it names). A phone gets at most two columns.
+ */
+export function placeRecords(records, refs, phone) {
+  const n = records.length;
+  const shapes = [];
+  for (let rows = 1; rows <= 3; rows++) for (let cols = 1; cols <= (phone ? 2 : 3); cols++) {
+    if (rows * cols >= n && rows * cols - n < Math.min(rows, cols)) shapes.push([rows, cols]);
+  }
+  const idx = new Map(records.map((r, i) => [r.id, i]));
+  const edges = refs.map((r) => [idx.get(r.from), idx.get(r.to)]);
+  const cross = (a, b, c, d) => {
+    const o = (p, q, r) => Math.sign((q[0] - p[0]) * (r[1] - p[1]) - (q[1] - p[1]) * (r[0] - p[0]));
+    return o(a, b, c) * o(a, b, d) < 0 && o(c, d, a) * o(c, d, b) < 0;
+  };
+  // A record's cell is about 1.6 times as wide as it is tall, gaps included.
+  const pt = ([r, c]) => [c * 1.6, r];
+  const over = (a, b, cell) => {
+    const [x1, y1] = pt(a), [x2, y2] = pt(b), [cx, cy] = pt(cell);
+    const hw = 0.55, hh = 0.32;
+    for (let t = 0.04; t < 1; t += 0.04) { const x = x1 + (x2 - x1) * t, y = y1 + (y2 - y1) * t; if (Math.abs(x - cx) < hw && Math.abs(y - cy) < hh) return true; }
+    return false;
+  };
+  let best = null;
+  for (const [rows, cols] of shapes) {
+    const cells = [];
+    for (let r = 0; r < rows; r++) for (let c = 0; c < cols; c++) cells.push([r, c]);
+    const used = new Array(cells.length).fill(false), at = new Array(n);
+    const score = () => {
+      let s = rows * 0.6 + cols * 0.3;
+      const pos = at.map((k) => cells[k]);
+      edges.forEach(([f, t], i) => {
+        const a = pos[f], b = pos[t];
+        const [x1, y1] = pt(a), [x2, y2] = pt(b);
+        s += Math.hypot(x2 - x1, y2 - y1) * 1.2;
+        if (a[0] !== b[0] && a[1] !== b[1]) s += 1.5;
+        if (a[0] < b[0]) s += 3;
+        pos.forEach((p, k) => { if (k !== f && k !== t && over(a, b, p)) s += 12; });
+        for (const [g, u] of edges.slice(i + 1)) if (g !== f && g !== t && u !== f && u !== t && cross(pt(a), pt(b), pt(pos[g]), pt(pos[u]))) s += 8;
+      });
+      // An empty cell in the middle of a row reads as something missing.
+      for (let r = 0; r < rows; r++) for (let c = 1; c < cols - 1; c++) if (!pos.some((p) => p[0] === r && p[1] === c) && pos.some((p) => p[0] === r)) s += 4;
+      return s;
+    };
+    const walk = (i) => {
+      if (i === n) { const s = score(); if (!best || s < best.s - 1e-9) best = { s, rows, cols, pos: at.map((k) => cells[k]) }; return; }
+      for (let k = 0; k < cells.length; k++) if (!used[k]) { used[k] = true; at[i] = k; walk(i + 1); used[k] = false; }
+    };
+    walk(0);
+  }
+  return best;
+}
+
+/** Records and the references between them into the figure: boxes on a grid figkit chose, and <fig-arrow ref> lines. */
+function drawEntities(spec, main) {
+  const phone = main.classList.contains('phone');
+  const { rows, cols, pos } = placeRecords(spec.records, spec.refs, phone);
+  const grid = document.createElement('div');
+  grid.className = 'entities';
+  grid.style.cssText = `grid-template-columns: repeat(${cols}, minmax(0, 1fr)); grid-template-rows: repeat(${rows}, auto);`;
+  spec.records.forEach((r, i) => {
+    const fields = r.fields ?? [];
+    const box = document.createElement('div');
+    box.className = 'node record' + (r.tone ? ' accent' : '');
+    box.id = 'rec-' + r.id;
+    box.style.gridArea = `${pos[i][0] + 1} / ${pos[i][1] + 1}`;
+    box.innerHTML = `<h3>${esc(r.name)}</h3>${fields.length ? `<ul>${fields.map((f) => `<li>${esc(f)}</li>`).join('')}</ul>` : ''}`;
+    grid.appendChild(box);
+  });
+  main.appendChild(grid);
+  for (const ref of spec.refs) {
+    const a = document.createElement('fig-arrow');
+    a.setAttribute('from', 'rec-' + ref.from);
+    a.setAttribute('to', 'rec-' + ref.to);
+    a.setAttribute('ref', ref.count);
+    if (ref.optional) a.setAttribute('dashed', '');
+    main.appendChild(a);
+  }
+}
+
+const HOSTS = { split: 'fig-split', bars: 'fig-bars', 'before-after': 'fig-change', dumbbell: 'div', series: 'div', groups: 'div', lines: 'div', panels: 'div', heatmap: 'div' };
 
 /** A checked spec drawn into a figure: header, chart and footer, as figkit's own markup. */
 export function drawSpec(spec, main) {
   const header = document.createElement('header');
   header.innerHTML = `<h1>${esc(spec.title)}</h1>${spec.note ? `<p class="read">${esc(spec.note)}</p>` : ''}`;
+  if (spec.type === 'entities') {
+    main.append(header);
+    drawEntities(spec, main);
+    if (spec.source) { const footer = document.createElement('footer'); footer.innerHTML = `<p>${esc(spec.source)}</p>`; main.append(footer); }
+    return { chart: main.querySelector('.entities'), draw: () => {} };
+  }
   const chart = document.createElement(HOSTS[spec.type]);
   main.append(header, chart);
   if (spec.source) {
@@ -218,6 +307,10 @@ export function drawSpec(spec, main) {
     if (spec.type === 'before-after') return drawChange(chart, spec);
     if (spec.type === 'dumbbell') return drawDumbbell(chart, spec);
     if (spec.type === 'series') return drawSeries(chart, spec);
+    if (spec.type === 'groups') return drawGroups(chart, spec, { unit: spec.unit, max: spec.max });
+    if (spec.type === 'lines') return drawLines(chart, spec, { unit: spec.unit, xTicks: spec.xTicks });
+    if (spec.type === 'panels') return drawPanels(chart, spec);
+    if (spec.type === 'heatmap') return drawHeatmap(chart, spec);
     const items = (spec.parts ?? spec.bars).map((x) => ({ ...x, text: String(x.value), label: esc(x.label) }));
     if (spec.type === 'split') drawSplit(chart, items, spec.unit);
     else drawBars(chart, items, spec.unit, spec.max);
@@ -225,3 +318,159 @@ export function drawSpec(spec, main) {
   draw();
   return { chart, draw };
 }
+
+// ---------- grouped bars, several lines, panels, heat maps ----------
+
+const hex = (c) => { const m = /^#?([0-9a-f]{6})$/i.exec(c.trim()); return m ? [0, 2, 4].map((i) => parseInt(m[1].slice(i, i + 2), 16)) : null; };
+/** a mixed with b, p of the way to b, as #rrggbb; a when either is not a plain hex colour. */
+function mix(a, b, p) {
+  const x = hex(a), y = hex(b);
+  if (!x || !y) return a;
+  return '#' + x.map((v, i) => Math.round(v + (y[i] - v) * p).toString(16).padStart(2, '0')).join('');
+}
+const phoneOf = (host) => !!host.closest('.phone');
+
+/**
+ * Bars in groups into a .chart: a heading per group, a row per series labelled with its name, so no legend is needed.
+ * opts.max fixes the end of the axis (panels share one), opts.unit follows each number.
+ */
+export function drawGroups(host, data, opts = {}) {
+  const t = themeOf(host);
+  const width = Math.floor(host.clientWidth) || 640, phone = phoneOf(host) || width < 420;
+  const { series, groups, accent } = data;
+  const tone = t[accent.tone ?? 'accent'];
+  const rows = groups.flatMap((g) => series.map((s, i) => ({ g: g.label, s, v: g.values[i], hi: (accent.series === undefined || accent.series === s) && (accent.group === undefined || accent.group === g.label) })));
+  const fmt = (v) => num(v) + (opts.unit ?? '');
+  const top = opts.max ?? Math.max(...rows.map((r) => r.v));
+  const indent = 0;
+  const labelW = Math.ceil(Math.max(widest(host, series, t.body) + indent, widest(host, groups.map((g) => g.label), t.body, 600))) + 14;
+  const valueW = Math.ceil(widest(host, rows.map((r) => fmt(r.v)), t.body, 600)) + 12;
+  // A group's heading sits close above its own bars, with more room above it, so the groups read as blocks.
+  const rowH = Math.max(phone ? 34 : 38, Math.ceil(t.body * 1.75)), headH = Math.max(30, Math.ceil(t.body * 1.7)), above = 22;
+  const step = series.length * rowH + headH + above;
+  plotInto(host, t, {
+    width, height: groups.length * step - above + 8, marginLeft: labelW, marginRight: valueW, marginTop: headH, marginBottom: 8,
+    // Every bar carries its number, so an axis would only repeat it; the zero line is kept.
+    x: { domain: [0, top], axis: null },
+    y: { domain: series, axis: null, padding: 0.18 },
+    fy: { domain: groups.map((g) => g.label), axis: null, paddingInner: (headH + above) / step, paddingOuter: 0 },
+    marks: [
+      Plot.ruleX([0], { stroke: t.line }),
+      Plot.barX(rows, { x: 'v', y: 's', fy: 'g', fill: (r) => (r.hi ? tone : t.fill), rx: 2 }),
+      Plot.text(rows, { x: 'v', y: 's', fy: 'g', text: (r) => fmt(r.v), dx: 6, textAnchor: 'start', fill: (r) => (r.hi ? tone : t.ink), fontWeight: (r) => (r.hi ? 600 : 400), fontSize: t.body }),
+      Plot.text(rows, { x: 0, y: 's', fy: 'g', text: 's', dx: -labelW + indent, textAnchor: 'start', fill: t.ink, fontSize: t.body }),
+      Plot.text(groups.map((g) => g.label), { fy: (d) => d, frameAnchor: 'top-left', dx: -labelW, dy: -headH + 2, text: (d) => d, textAnchor: 'start', lineAnchor: 'top', fill: opts.quietGroups ? t.muted : t.ink, fontWeight: 600, fontSize: t.body * 1.06 }),
+    ],
+  });
+}
+
+/**
+ * Two or three lines on one axis into a .chart. Each is named at its right end in its own colour; the accent line is
+ * drawn last and thicker, the others in two greys. opts.domain fixes the y axis (panels share one).
+ */
+export function drawLines(host, data, opts = {}) {
+  const t = themeOf(host);
+  const width = Math.floor(host.clientWidth) || 640, phone = phoneOf(host) || width < 420;
+  const greys = [t.fill2, t.fill];
+  const lines = data.series.map((l) => ({ ...l, pts: l.points.map((p) => ({ x: toX(p.x), y: p.y, s: l.label })) }));
+  const others = lines.filter((l) => l.label !== data.accent);
+  others.forEach((l, i) => { l.color = greys[i % 2]; l.w = 2.25; });
+  const hi = lines.find((l) => l.label === data.accent);
+  hi.color = t.accent; hi.w = 3.25;
+  const ys = lines.flatMap((l) => l.pts.map((p) => p.y));
+  const zero = data.zero ?? true;
+  const domain = opts.domain ?? [zero ? Math.min(0, ...ys) : Math.min(...ys), Math.max(...ys) * 1.04];
+  const fmt = (d) => num(d) + (opts.unit ?? '');
+  const height = phone ? 260 : 300, mt = data.mark ? 28 : 10, mb = 36;
+  const ends = [...others, hi].map((l) => ({ l, last: l.pts[l.pts.length - 1] }));
+  const labelW = Math.ceil(widest(host, ends.map((e) => e.l.label), t.small, 600)) + 14;
+  // Each name sits level with its line's last point, pushed apart when two would overlap.
+  const py = (v) => mt + (1 - (v - domain[0]) / (domain[1] - domain[0])) * (height - mt - mb);
+  const placed = ends.map((e) => ({ ...e, y: py(e.last.y) })).sort((a, b) => a.y - b.y);
+  const gap = t.small * 1.3;
+  for (let i = 1; i < placed.length; i++) placed[i].y = Math.max(placed[i].y, placed[i - 1].y + gap);
+  for (let i = placed.length - 2; i >= 0; i--) placed[i].y = Math.min(placed[i].y, placed[i + 1].y - gap);
+  const tickW = Math.ceil(widest(host, [fmt(domain[1]), fmt(domain[0])], t.small)) + 12;
+  const markPt = data.mark && hi.pts.find((p) => +p.x === +toX(data.mark.x));
+  plotInto(host, t, {
+    width, height, marginLeft: tickW, marginRight: labelW, marginTop: mt, marginBottom: mb,
+    x: opts.xTicks ? { label: null, insetLeft: 18, ticks: opts.xTicks.map((k) => toX(k.x)), tickFormat: (d) => opts.xTicks.find((k) => +toX(k.x) === +d)?.label ?? '' }
+      : { label: null, insetLeft: 18, ticks: width < 520 ? 3 : 5, tickFormat: typeof lines[0].pts[0].x === 'number' ? (d) => num(d) : undefined },
+    y: { domain, nice: false, label: null, grid: true, ticks: 4, tickSize: 0, tickFormat: fmt },
+    marks: [
+      zero ? Plot.ruleY([0], { stroke: t.line }) : null,
+      ...[...others, hi].map((l) => Plot.lineY(l.pts, { x: 'x', y: 'y', stroke: l.color, strokeWidth: l.w })),
+      Plot.text(placed, { x: (e) => e.last.x, y: (e) => domain[0] + (1 - (e.y - mt) / (height - mt - mb)) * (domain[1] - domain[0]), text: (e) => e.l.label, dx: 8, textAnchor: 'start', fill: (e) => (e.l === hi ? t.accent : t.muted), fontWeight: 600, fontSize: t.small }),
+      markPt ? Plot.dot([markPt], { x: 'x', y: 'y', r: 6, fill: t.accent }) : null,
+      markPt ? Plot.text([markPt], { x: 'x', y: 'y', text: () => data.mark.label, dy: -16, fill: t.accent, fontWeight: 600, fontSize: t.small }) : null,
+    ],
+  });
+}
+
+/** The same chart for each part, side by side on one scale; stacked on a phone. */
+export function drawPanels(host, spec) {
+  host.className = 'panels';
+  host.innerHTML = '';
+  const charts = spec.panels.map((p) => {
+    const box = document.createElement('div');
+    box.className = 'panel';
+    box.innerHTML = `<h2>${esc(p.label)}</h2>`;
+    const chart = document.createElement('div');
+    box.appendChild(chart);
+    host.appendChild(box);
+    return { p, chart };
+  });
+  if (spec.chart === 'groups') {
+    const max = spec.max ?? Math.max(...spec.panels.flatMap((p) => p.groups.flatMap((g) => g.values)));
+    for (const { p, chart } of charts) {
+      const accent = spec.accent.group && !p.groups.some((g) => g.label === spec.accent.group) ? { ...spec.accent, series: '\u0000' } : spec.accent;
+      drawGroups(chart, { series: spec.series, groups: p.groups, accent }, { unit: spec.unit, max, quietGroups: true });
+    }
+  } else {
+    const ys = spec.panels.flatMap((p) => p.series.flatMap((l) => l.points.map((q) => q.y)));
+    const zero = spec.zero ?? true;
+    const domain = [zero ? Math.min(0, ...ys) : Math.min(...ys), Math.max(...ys) * 1.04];
+    for (const { p, chart } of charts) drawLines(chart, { series: p.series, accent: spec.accent, zero }, { unit: spec.unit, domain, xTicks: spec.xTicks });
+  }
+}
+
+/**
+ * A heat map into a .chart: the colour runs from pale to the accent, one hue, so darker is always more. The scale is
+ * drawn above the grid at readable size. A marked cell is outlined and named in the scale line.
+ */
+export function drawHeatmap(host, spec) {
+  const t = themeOf(host);
+  const width = Math.floor(host.clientWidth) || 640, phone = phoneOf(host) || width < 420;
+  const cells = spec.rows.flatMap((r, i) => spec.columns.map((c, j) => ({ r: String(r), c: String(c), v: spec.values[i][j] })));
+  const vs = cells.map((d) => d.v), lo = Math.min(...vs), hi = Math.max(...vs);
+  // One hue, near white to dark: darker is always more, and busy does not read as alarm the way red does.
+  const scale = Plot.scale({ color: { type: 'linear', scheme: 'blues', domain: [lo - (hi - lo) * 0.08, hi] } });
+  const colour = (v) => scale.apply(v);
+  const ramp = [0, 0.25, 0.5, 0.75, 1].map((p) => colour(lo + (hi - lo) * p)).join(', ');
+  const fmt = (v) => num(v) + (spec.unit ?? '');
+  const cols = spec.columns.map(String), rows = spec.rows.map(String);
+  const labelW = Math.ceil(widest(host, rows, t.small)) + 12;
+  const cellW = (width - labelW - 8) / cols.length;
+  const show = cellW >= 48 && cells.length <= 72;
+  // Label every k-th column, k a divisor of the count where one exists, so 24 hours read 12am, 6am, 12pm, 6pm.
+  const most = phone ? 5 : 9, steps = [1, 2, 3, 4, 5, 6, 8, 10, 12].filter((k) => cols.length / k <= most);
+  const every = steps.find((k) => cols.length % k === 0) ?? steps[0] ?? Math.ceil(cols.length / most);
+  const rowH = phone ? 30 : 36;
+  const key = document.createElement('p');
+  key.className = 'hm-key';
+  key.innerHTML = `<span>${esc(fmt(lo))}</span><i style="background:linear-gradient(90deg, ${ramp})"></i><span>${esc(fmt(hi))}</span>`
+    + (spec.mark ? `<span style="margin-left:14px;white-space:nowrap;display:inline-flex;align-items:center;gap:8px;color:${t.ink};font-weight:600"><i style="width:16px;height:16px;border:2.5px solid ${t.accent};border-radius:2px;background:none"></i>${esc(spec.mark.label)}</span>` : '');
+  plotInto(host, t, {
+    width, height: rows.length * rowH + 36, marginLeft: labelW, marginRight: 8, marginTop: 0, marginBottom: 36,
+    x: { domain: cols, label: null, tickSize: 0, tickFormat: (d, i) => (i % every === 0 ? d : '') , padding: 0.06 },
+    y: { domain: rows, label: null, tickSize: 0, padding: 0.08 },
+    marks: [
+      Plot.cell(cells, { x: 'c', y: 'r', fill: (d) => colour(d.v), inset: 0.5 }),
+      show ? Plot.text(cells, { x: 'c', y: 'r', text: (d) => fmt(d.v), fill: (d) => ((d.v - lo) / (hi - lo || 1) > 0.55 ? '#ffffff' : t.ink), fontSize: t.small }) : null,
+      // The marked cell: an accent ring, the one thing in the chart that is not the scale.
+      spec.mark ? Plot.cell([{ r: String(spec.mark.row), c: String(spec.mark.column) }], { x: 'c', y: 'r', fill: 'none', stroke: t.accent, strokeWidth: 2.5 }) : null,
+    ],
+  });
+  key.style.marginLeft = labelW + 'px';
+  host.prepend(key);
+}

package/viz/spec.js

@@ -10,6 +10,7 @@ const common = {
   note: z.string().trim().max(160, 'keep the note to 160 characters').optional(),
   unit: z.string().max(8).optional(),
   source: z.string().trim().max(120).optional(),
+  style: z.enum(['report'], { error: 'style: "report" for a light chart that sits in a page, or leave it out' }).optional(),
 };
 const value = z.number({ error: 'must be a number' }).finite();
 
@@ -84,14 +85,159 @@ export const SeriesSpec = z.object({
   zero: z.boolean().optional(),
 }).strict();
 
-export const Spec = z.discriminatedUnion('type', [SplitSpec, BarsSpec, BeforeAfterSpec, DumbbellSpec, SeriesSpec]);
-export const TYPES = { split: SplitSpec, bars: BarsSpec, 'before-after': BeforeAfterSpec, dumbbell: DumbbellSpec, series: SeriesSpec };
 
-const items = (s) => s.parts ?? s.bars ?? s.rows ?? (s.after ? [s.after] : []);
+const seriesName = label.max(28, 'keep series names to 28 characters');
+const TONE_ONE = z.enum(['accent', 'good', 'bad'], { error: 'tone: "accent", or "good" or "bad" when it is a result' });
+
+/** Bars in groups: each group a few bars, one per series, read across the groups. */
+const groupRow = z.object({
+  label: label.max(32, 'keep group labels to 32 characters'),
+  values: z.array(value.nonnegative('must be 0 or more: bars start at zero')),
+}).strict();
+const groupsData = {
+  series: z.array(seriesName).min(2, 'at least 2 series; one bar per group is a "bars" chart').max(4, 'at most 4 series; more is too many bars to read'),
+  groups: z.array(groupRow).min(2, 'at least 2 groups; one group is a "bars" chart').max(6, 'at most 6 groups'),
+  accent: z.object({
+    series: z.string().optional(),
+    group: z.string().optional(),
+    tone: TONE_ONE.optional(),
+  }, { error: 'required: what to notice, { "series" } for a whole series, or { "series", "group" } for one bar' }).strict(),
+  max: z.number().positive().optional(),
+};
+export const GroupsSpec = z.object({ type: z.literal('groups'), ...common, ...groupsData }).strict();
+
+/** Two or three lines on one axis, each named at its end; one is the line to notice. */
+const linePoint = z.object({ x: point, y: value }).strict();
+const linesData = {
+  series: z.array(z.object({
+    label: seriesName,
+    points: z.array(linePoint).min(3, 'a line needs at least 3 points').max(2000),
+  }).strict()).min(2, 'at least 2 lines; one line is a "series" chart').max(3, 'at most 3 lines on one axis; more is small multiples ("panels")'),
+  accent: z.string({ error: 'required: the label of the line to notice' }),
+  mark: z.object({ x: point, label: z.string().trim().min(1).max(32, 'keep the mark label to 32 characters') }).strict().optional(),
+  zero: z.boolean().optional(),
+  xTicks: z.array(z.object({ x: point, label: z.string().trim().min(1).max(12, 'keep tick labels to 12 characters') }).strict()).min(2).max(8, 'at most 8 ticks').optional(),
+};
+export const LinesSpec = z.object({ type: z.literal('lines'), ...common, ...linesData }).strict();
+
+/** The same chart drawn once per part, side by side on one scale. */
+export const PanelsSpec = z.object({
+  type: z.literal('panels'),
+  ...common,
+  chart: z.enum(['groups', 'lines'], { error: 'chart: "groups" or "lines", the chart each panel draws' }),
+  series: groupsData.series.optional(),
+  accent: z.union([z.string(), groupsData.accent]),
+  max: z.number().positive().optional(),
+  zero: z.boolean().optional(),
+  xTicks: linesData.xTicks,
+  panels: z.array(z.object({
+    label: label.max(32, 'keep panel labels to 32 characters'),
+    groups: z.array(groupRow).min(1).max(6, 'at most 6 groups').optional(),
+    series: linesData.series.optional(),
+  }).strict()).min(2, 'at least 2 panels').max(4, 'at most 4 panels; more is two figures'),
+}).strict();
+
+/** A grid of values coloured from pale to strong: where something is high or low across two dimensions. */
+const axisLabel = z.union([z.string().trim().min(1).max(16, 'keep row and column labels to 16 characters'), z.number().finite()]);
+export const HeatmapSpec = z.object({
+  type: z.literal('heatmap'),
+  ...common,
+  note: z.string({ error: 'required: what the colour counts, e.g. "People active per hour"' }).trim().min(1).max(160, 'keep the note to 160 characters'),
+  rows: z.array(axisLabel).min(2).max(12, 'at most 12 rows'),
+  columns: z.array(axisLabel).min(2).max(31, 'at most 31 columns'),
+  values: z.array(z.array(value)),
+  mark: z.object({ row: axisLabel, column: axisLabel, label: z.string().trim().min(1).max(32, 'keep the mark label to 32 characters') }).strict().optional(),
+}).strict();
+
+const slug = z.string({ error: 'needs an id, e.g. "order"' }).regex(/^[a-z][a-z0-9-]{0,23}$/, 'ids are short lowercase words, e.g. "order" or "order-line"');
+
+/**
+ * What the things are and which points at which: records, and references from one record to another. A reference is
+ * a pointer one record holds (a foreign key, an id field), never a step in the order work happens.
+ */
+export const EntitiesSpec = z.object({
+  type: z.literal('entities'),
+  title,
+  note: common.note,
+  source: common.source,
+  style: common.style,
+  records: z.array(z.object({
+    id: slug,
+    name: label.max(32, 'keep record names to 32 characters'),
+    table: z.never({ error: 'no table: name the record in words; if the table name matters to the reader, put it in fields' }).optional(),
+    fields: z.array(z.string().trim().min(1).max(36, 'keep each field to 36 characters')).max(4, 'at most 4 fields: the ones that explain the picture').optional(),
+    tone: z.literal('accent', { error: 'tone: only "accent", on the one record to notice' }).optional(),
+  }).strict()).min(2, 'at least 2 records').max(5, 'at most 5 records; more is two figures (the core, then one corner of it), not one'),
+  refs: z.array(z.object({
+    from: slug,
+    to: slug,
+    field: z.never({ error: 'no field: the line is the reference, so its column is not written out' }).optional(),
+    count: z.enum(['many', 'one'], { error: 'count: "many" or "one": how many "from" records can point at one "to" record' }).default('many'),
+    optional: z.boolean().optional(),
+  }).strict()).min(1, 'at least 1 reference').max(8, 'at most 8 references; more is two figures, not a reference left out'),
+}).strict();
+
+export const Spec = z.discriminatedUnion('type', [SplitSpec, BarsSpec, BeforeAfterSpec, DumbbellSpec, SeriesSpec, EntitiesSpec, GroupsSpec, LinesSpec, PanelsSpec, HeatmapSpec]);
+export const TYPES = { split: SplitSpec, bars: BarsSpec, 'before-after': BeforeAfterSpec, dumbbell: DumbbellSpec, series: SeriesSpec, entities: EntitiesSpec, groups: GroupsSpec, lines: LinesSpec, panels: PanelsSpec, heatmap: HeatmapSpec };
+
+const items = (s) => s.parts ?? s.bars ?? s.rows ?? s.records ?? (s.after ? [s.after] : []);
 const kind = (v) => (typeof v === 'number' ? 'number' : 'date');
 
+
+function groupsChecks(s, at = '') {
+  const out = [];
+  s.groups.forEach((g, i) => { if (g.values.length !== s.series.length) out.push(`${at}groups[${i}].values: one value per series, ${s.series.length}, not ${g.values.length}`); });
+  if (s.accent.series !== undefined && !s.series.includes(s.accent.series)) out.push(`accent.series: must be one of ${s.series.map((x) => `"${x}"`).join(', ')}`);
+  if (s.accent.group !== undefined && !s.groups.some((g) => g.label === s.accent.group)) out.push(`${at}accent.group: must be the label of one of the groups`);
+  if (s.accent.series === undefined && s.accent.group === undefined) out.push('accent: name the series to notice, or a series and a group for one bar');
+  if (s.max !== undefined && s.groups.some((g) => g.values.some((v) => v > s.max))) out.push('max: every value must be at most max');
+  return out;
+}
+function linesChecks(s, at = '') {
+  const out = [];
+  const xs = s.series.flatMap((l) => l.points.map((p) => p.x));
+  if (new Set(xs.map(kind)).size > 1) out.push(`${at}series: x values must be all numbers or all dates, not both`);
+  const t = (x) => (typeof x === 'number' ? x : Date.parse(x));
+  s.series.forEach((l, i) => { for (let j = 1; j < l.points.length; j++) if (t(l.points[j].x) <= t(l.points[j - 1].x)) { out.push(`${at}series[${i}].points[${j}].x: points must be in order of x`); break; } });
+  const names = s.series.map((l) => l.label);
+  if (new Set(names).size < names.length) out.push(`${at}series: two lines have the same label`);
+  if (!names.includes(s.accent)) out.push(`accent: must be the label of one of the lines, ${names.map((x) => `"${x}"`).join(', ')}`);
+  if (s.mark) { const line = s.series.find((l) => l.label === s.accent); if (line && !line.points.some((p) => t(p.x) === t(s.mark.x))) out.push(`mark.x: must be the x of one of the points on the "${s.accent}" line`); }
+  return out;
+}
+
 /** Rules that span fields: x values of one kind, in order, and a mark that is one of the points. */
 function crossChecks(s) {
+  if (s.type === 'groups') return groupsChecks(s);
+  if (s.type === 'lines') return linesChecks(s);
+  if (s.type === 'panels') {
+    const out = [];
+    s.panels.forEach((p, i) => {
+      const at = `panels[${i}].`;
+      if (s.chart === 'groups') {
+        if (!p.groups || p.series) { out.push(`${at}: a groups panel has "groups" and no "series"`); return; }
+        if (!s.series) { out.push('series: a groups chart names its series once, at the top'); return; }
+        if (typeof s.accent !== 'object') { out.push('accent: { "series" } or { "series", "group" } for a groups chart'); return; }
+        out.push(...groupsChecks({ series: s.series, groups: p.groups, accent: { ...s.accent, group: undefined }, max: s.max }, at));
+        if (s.accent.group !== undefined && !s.panels.some((q) => q.groups?.some((g) => g.label === s.accent.group))) out.push('accent.group: must be the label of a group in a panel');
+      } else {
+        if (!p.series || p.groups) { out.push(`${at}: a lines panel has "series" and no "groups"`); return; }
+        if (typeof s.accent !== 'string') { out.push('accent: the label of the line to notice, the same in every panel'); return; }
+        out.push(...linesChecks({ series: p.series, accent: s.accent }, at));
+        const names = (q) => q.series.map((l) => l.label).join('|');
+        if (names(p) !== names(s.panels[0])) out.push(`${at}series: every panel has the same lines, in the same order, so a line is one colour throughout`);
+      }
+    });
+    return [...new Set(out)];
+  }
+  if (s.type === 'heatmap') {
+    const out = [];
+    if (s.values.length !== s.rows.length) out.push(`values: one row of values per row label, ${s.rows.length}, not ${s.values.length}`);
+    s.values.forEach((r, i) => { if (r.length !== s.columns.length) out.push(`values[${i}]: one value per column, ${s.columns.length}, not ${r.length}`); });
+    if (s.mark && !s.rows.includes(s.mark.row)) out.push('mark.row: must be one of the row labels');
+    if (s.mark && !s.columns.includes(s.mark.column)) out.push('mark.column: must be one of the column labels');
+    return out;
+  }
   if (s.type === 'dumbbell') {
     const kinds = new Set(s.rows.flatMap((r) => [kind(r.from), kind(r.to)]));
     if (kinds.size > 1) return ['rows: use all numbers or all dates, not both'];
@@ -103,6 +249,24 @@ function crossChecks(s) {
     for (let i = 1; i < s.points.length; i++) if (at(s.points[i].x) <= at(s.points[i - 1].x)) return [`points[${i}].x: points must be in order of x, each later than the one before`];
     if (!s.points.some((p) => at(p.x) === at(s.mark.x))) return [`mark.x: must be the x of one of the points, not ${JSON.stringify(s.mark.x)}`];
   }
+  if (s.type === 'entities') {
+    const ids = s.records.map((r) => r.id);
+    const dup = ids.find((id, i) => ids.indexOf(id) !== i);
+    if (dup) return [`records: two records have the id "${dup}"`];
+    const out = [];
+    const pairs = new Set();
+    s.refs.forEach((r, i) => {
+      for (const end of ['from', 'to']) if (!ids.includes(r[end])) out.push(`refs[${i}].${end}: no record has the id "${r[end]}"; the ids are ${ids.map((x) => `"${x}"`).join(', ')}`);
+      if (r.from === r.to) out.push(`refs[${i}]: a record pointing at itself; say it in its fields instead`);
+      const key = r.from + '>' + r.to;
+      if (pairs.has(key)) out.push(`refs[${i}]: a second reference from "${r.from}" to "${r.to}"; make it one reference`);
+      pairs.add(key);
+    });
+    if (s.records.filter((r) => r.tone).length > 1) out.push('records: accent at most one record, the one to notice');
+    const loose = ids.filter((id) => !s.refs.some((r) => r.from === id || r.to === id));
+    if (loose.length) out.push(`records: ${loose.map((x) => `"${x}"`).join(', ')} ${loose.length === 1 ? 'is' : 'are'} not in any reference; leave ${loose.length === 1 ? 'it' : 'them'} out or add the reference`);
+    return out;
+  }
   return [];
 }