@liggi/figkit 0.3.0 → 0.5.0

package/viz/draw.js

@@ -1,5 +1,7 @@
 /* The chart types, drawn into a host element styled by runtime/fig.css. Figures use them through runtime/fig.js. */
 import * as Plot from '@observablehq/plot';
+import { drawSequence } from './sequence.js';
+import { drawStates } from './states.js';
 const NS = 'http://www.w3.org/2000/svg';
 const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
 
@@ -79,21 +81,63 @@ export function drawSplit(host, parts, unit) {
   }
 }
 
-/** A few numbers compared into a <fig-bars>, on an axis from zero to max (default: the largest value). */
-export function drawBars(host, bars, unit, max) {
-  const top = max ?? Math.max(...bars.map((b) => b.value));
+/**
+ * A few numbers compared into a <fig-bars>, on an axis from zero to max (default: the largest value or high). A bar
+ * with `low` and `high` gets a range drawn across its end, and its number moves past the range; `n` goes under its label.
+ */
+export function drawBars(host, bars, unit, max, each, ref) {
+  const top = max ?? Math.max(...bars.map((b) => Math.max(b.value, b.high ?? 0)), ref?.value ?? 0);
   host.innerHTML = '';
+  host.classList.toggle('has-ref', !!ref);
+  // A reference is its own first row, in the second colour; a bar above it (its whole range, when it has one) is
+  // accented and every other bar is grey.
+  if (ref) bars = [{ ...ref, text: String(ref.value), tone: 'second', isRef: true }, ...bars.map((b) => ({ ...b, tone: (b.low ?? b.value) > ref.value ? 'accent' : undefined }))];
   const fills = bars.map((b) => {
-    const label = Object.assign(document.createElement('div'), { className: 'fb-label', innerHTML: b.label });
+    const label = Object.assign(document.createElement('div'), { className: 'fb-label' + (b.isRef ? ' ref' : ''), innerHTML: b.label + (b.n !== undefined ? `<span class="fb-n">${each ? `${esc(b.n.toLocaleString('en-GB'))} ${esc(each)}` : `n = ${esc(b.n.toLocaleString('en-GB'))}`}</span>` : '') });
     const track = Object.assign(document.createElement('div'), { className: 'fb-track' });
     const tone = b.tone ? ' ' + b.tone : '';
-    track.innerHTML = `<div class="fb-bar${tone}"></div><div class="fb-val${b.tone ? ' lead ' + b.tone : ''}">${esc(shown(b, unit))}${b.note ? `<span class="fb-sub">${esc(b.note)}</span>` : ''}</div>`;
+    const ranged = b.low !== undefined;
+    // With a range, the bar steps back and the range, in the bar's colour, leads; its ends are printed after the value.
+    const ends = ranged ? `<span class="fb-sub">${esc(num(b.low))}–${esc(num(b.high))}${esc(unit ?? '')}</span>` : '';
+    track.innerHTML = `<div class="fb-bar${tone}${ranged ? ' dim' : ''}"></div>${ranged ? `<div class="fb-range${tone}"></div>` : ''}<div class="fb-val${b.tone ? ' lead ' + b.tone : ''}">${esc(shown(b, unit))}${ends}${b.note ? `<span class="fb-sub">${esc(b.note)}</span>` : ''}</div>`;
     host.append(label, track);
-    return { bar: track.firstChild, ratio: top > 0 ? Math.max(0, b.value) / top : 0 };
+    const r = (v) => (top > 0 ? Math.max(0, v) / top : 0);
+    return { b, bar: track.firstChild, range: track.querySelector('.fb-range'), val: track.querySelector('.fb-val'), ratio: r(b.value), lo: r(b.low ?? 0), hi: r(b.high ?? 0) };
   });
-  // The longest bar leaves room for the widest value and note, so no label runs past the edge.
+  // The longest bar or range leaves room for the widest value and note, so no label runs past the edge.
   const room = Math.max(...[...host.querySelectorAll('.fb-val')].map((v) => v.offsetWidth)) + 12;
-  for (const f of fills) f.bar.style.width = `calc((100% - ${room}px) * ${f.ratio})`;
+  const at = (ratio) => `calc((100% - ${room}px) * ${ratio})`;
+  for (const f of fills) {
+    f.bar.style.width = at(f.ratio);
+    if (!f.range) continue;
+    f.range.style.left = at(f.lo);
+    f.range.style.width = at(f.hi - f.lo);
+    f.val.style.marginLeft = `max(0px, calc((100% - ${room}px) * ${f.hi - f.ratio} - 3px))`;
+  }
+  if (!ref) return;
+  // The reference level as a dashed line from the end of its bar down through every other row; a value that would
+  // sit on the line is moved past it.
+  const line = document.createElement('div');
+  line.className = 'fb-refline';
+  host.appendChild(line);
+  const hostBox = host.getBoundingClientRect();
+  const refBar = fills[0].bar.getBoundingClientRect(), last = fills[fills.length - 1].bar.parentElement.getBoundingClientRect();
+  const x = refBar.right - hostBox.left;
+  Object.assign(line.style, { left: `${x - 1}px`, top: `${refBar.bottom - hostBox.top}px`, height: `${last.bottom - refBar.bottom}px` });
+  for (const f of fills.slice(1)) {
+    const v = f.val.getBoundingClientRect();
+    if (v.left - hostBox.left < x + 8 && v.right - hostBox.left > x - 8) f.val.style.marginLeft = `${parseFloat(getComputedStyle(f.val).marginLeft) + (x + 10 - (v.left - hostBox.left))}px`;
+  }
+}
+
+/** What the ranges are, as a key line under the reading line: the mark as drawn, then the words. */
+function rangeKey(spec) {
+  const p = document.createElement('p');
+  p.className = 'range-key';
+  p.innerHTML = (spec.range ? `<span><i class="${spec.type === 'bars' ? 'whisker' : 'band'}"></i>${esc(spec.range)}</span>` : '')
+    + (spec.ref && spec.type !== 'bars' ? `<span><i class="dash"></i>${esc(spec.ref.label)}</span>` : '')
+    + (spec.ref && spec.type === 'bars' && spec.bars.some((b) => (b.low ?? b.value) > spec.ref.value) ? `<span><i class="swatch"></i>${spec.range ? 'whole range ' : ''}above ${esc(spec.ref.label)}</span>` : '');
+  return p;
 }
 
 const ARROW = '<svg width="56" height="24" viewBox="0 0 56 24" aria-hidden="true"><path d="M2 12 H48 M38 3 L50 12 L38 21" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/></svg>';
@@ -173,12 +217,13 @@ export function drawDumbbell(host, spec) {
 export function drawSeries(host, spec) {
   const t = themeOf(host);
   const width = Math.floor(host.clientWidth) || 640;
-  const pts = spec.points.map((p) => ({ x: toX(p.x), y: p.y }));
+  const pts = spec.points.map((p) => ({ x: toX(p.x), y: p.y, low: p.low, high: p.high }));
+  const band = pts[0].low !== undefined;
   const i = pts.findIndex((p) => +p.x === +toX(spec.mark.x));
   const mark = pts[i];
   const near = pts.slice(Math.max(0, i - 3), i + 4).map((p) => p.y);
   const high = mark.y >= near.reduce((s, y) => s + y, 0) / near.length;
-  const ys = pts.map((p) => p.y), zero = spec.zero ?? true;
+  const ys = [...pts.flatMap((p) => (band ? [p.y, p.low, p.high] : [p.y])), ...(spec.ref ? [spec.ref.y] : [])], zero = spec.zero ?? true;
   const top = Math.max(...ys), bottom = zero ? Math.min(0, ...ys) : Math.min(...ys);
   const fmt = (d) => num(d) + (spec.unit ?? '');
   const tickW = widest(host, [fmt(top), fmt(bottom)], t.small);
@@ -188,16 +233,23 @@ export function drawSeries(host, spec) {
   const right = at + 14 + widest(host, [spec.mark.label], t.body, 600) <= width - 20;
   // Above a high point; level with a low one, lifted clear of the axis when it sits near the bottom.
   const lift = zero ? ((mark.y - bottom) / (top * 1.04 - bottom)) * (340 - 30 - 40) : Infinity;
-  const dy = high ? -12 : Math.min(0, lift - 18);
+  let dy = high ? -12 : Math.min(0, lift - 18);
+  // A label to the left of its point sits on the side away from the line coming in: above it when the previous
+  // point is lower, below when higher.
+  if (!right && i > 0) dy = pts[i - 1].y <= mark.y ? -18 : 20;
+  // Above or below, the label ends just past the point, so it does not reach back over the line.
+  const dx = right ? 14 : i > 0 ? 8 : -14;
   plotInto(host, t, {
     width, height: 340, marginLeft: left0, marginRight: 20, marginTop: 30, marginBottom: 40,
     x: { label: null, ticks: width < 600 ? 4 : 5, insetLeft: 18 },
     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.fill, strokeWidth: 2.5 }),
+      band ? Plot.areaY(pts, { x: 'x', y1: 'low', y2: 'high', fill: t.fill, fillOpacity: 0.3 }) : null,
+      spec.ref ? Plot.ruleY([spec.ref.y], { stroke: t.soft, strokeWidth: 1.5, strokeDasharray: '5,4' }) : null,
+      Plot.lineY(pts, { x: 'x', y: 'y', stroke: band ? t.muted : 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 }),
+      Plot.text([mark], { x: 'x', y: 'y', text: () => spec.mark.label, dx, dy, textAnchor: right ? 'start' : 'end', fill: t.accent, fontWeight: 600, fontSize: t.body }),
     ],
   });
 }
@@ -284,18 +336,39 @@ function drawEntities(spec, main) {
   }
 }
 
-const HOSTS = { split: 'fig-split', bars: 'fig-bars', 'before-after': 'fig-change', dumbbell: 'div', series: 'div', groups: 'div', lines: 'div', panels: 'div', heatmap: 'div' };
+const HOSTS = { split: 'fig-split', bars: 'fig-bars', estimates: 'div', 'before-after': 'fig-change', dumbbell: 'div', series: 'div', groups: 'div', lines: 'div', panels: 'div', heatmap: 'div', dots: 'div', scatter: 'div', units: '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>` : ''}`;
+  // What the ranges and a reference line are, said once under the reading line: there they never sit on the data.
+  if (spec.type === 'estimates') header.appendChild(estimatesKey(spec));
+  else if (spec.range || spec.ref) header.appendChild(rangeKey(spec));
   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: () => {} };
   }
+  if (spec.type === 'states') {
+    if (spec.moves.some((m) => m.count != null)) {
+      const key = document.createElement('p');
+      key.className = 'read st-key';
+      key.textContent = `Counts are ${spec.each} who made each move at least once${spec.shares ? '; % of those who reached the state it leaves' : ''}.`;
+      header.appendChild(key);
+    }
+    main.append(header);
+    const chart = drawStates(spec, main);
+    if (spec.source) { const footer = document.createElement('footer'); footer.innerHTML = `<p>${esc(spec.source)}</p>`; main.append(footer); }
+    return { chart, draw: () => {} };
+  }
+  if (spec.type === 'sequence') {
+    main.append(header);
+    const chart = drawSequence(spec, main);
+    if (spec.source) { const footer = document.createElement('footer'); footer.innerHTML = `<p>${esc(spec.source)}</p>`; main.append(footer); }
+    return { chart, draw: () => {} };
+  }
   const chart = document.createElement(HOSTS[spec.type]);
   main.append(header, chart);
   if (spec.source) {
@@ -306,14 +379,18 @@ export function drawSpec(spec, main) {
   const draw = () => {
     if (spec.type === 'before-after') return drawChange(chart, spec);
     if (spec.type === 'dumbbell') return drawDumbbell(chart, spec);
+    if (spec.type === 'estimates') return drawEstimates(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);
+    if (spec.type === 'dots') return drawDots(chart, spec);
+    if (spec.type === 'scatter') return drawScatter(chart, spec);
+    if (spec.type === 'units') return drawUnits(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);
+    else drawBars(chart, items, spec.unit, spec.max, spec.each, spec.ref && { ...spec.ref, label: esc(spec.ref.label) });
   };
   draw();
   return { chart, draw };
@@ -372,12 +449,12 @@ 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 lines = data.series.map((l) => ({ ...l, band: l.points[0].low !== undefined, pts: l.points.map((p) => ({ x: toX(p.x), y: p.y, low: p.low, high: p.high, 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 ys = lines.flatMap((l) => l.pts.flatMap((p) => (l.band ? [p.y, p.low, p.high] : [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 ?? '');
@@ -399,6 +476,7 @@ export function drawLines(host, data, opts = {}) {
     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].filter((l) => l.band).map((l) => Plot.areaY(l.pts, { x: 'x', y1: 'low', y2: 'high', fill: l.color, fillOpacity: l === hi ? 0.22 : 0.18 })),
       ...[...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,
@@ -427,7 +505,7 @@ export function drawPanels(host, spec) {
       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 ys = spec.panels.flatMap((p) => p.series.flatMap((l) => l.points.flatMap((q) => (q.low !== undefined ? [q.y, q.low, q.high] : [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 });
@@ -440,14 +518,26 @@ export function drawPanels(host, spec) {
  */
 export function drawHeatmap(host, spec) {
   const t = themeOf(host);
+  host.classList.add('heatmap');
   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 ?? '');
+  // Any value below zero makes the grid signed: a diverging scale around zero, orange below and blue above, equal
+  // distances from zero equally strong. Otherwise one hue, near white to dark: darker is always more.
+  const diverging = lo < 0;
+  const places = placesOf(vs);
+  const fmt = (v) => (diverging ? signed(v, places) : Number(v.toFixed(places)).toLocaleString('en-GB', { minimumFractionDigits: places })) + (spec.unit ?? '');
+  const scale = diverging ? null : Plot.scale({ color: { type: 'linear', scheme: 'blues', domain: [lo - (hi - lo) * 0.08, hi] } });
+  const MID = '#f2f2f0', NEG = '#a63603', POS = '#08519c', far = Math.max(-lo, hi) || 1;
+  const colour = (v) => (!diverging ? scale.apply(v) : v < 0 ? mix(MID, NEG, -v / far) : mix(MID, POS, v / far));
+  // Cell text in dark or white, whichever reads against the cell, whatever the theme's ink.
+  const lum = (c) => { const m = /rgb\((\d+), (\d+), (\d+)\)/.exec(c); const x = m ? m.slice(1).map(Number) : hex(c) ?? [0, 0, 0]; const [r, g, b] = x.map((v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4; }); return 0.2126 * r + 0.7152 * g + 0.0722 * b; };
+  const textOn = (v) => { const L = lum(colour(v)); return (L + 0.05) / (lum('#1d2130') + 0.05) >= 1.05 / (L + 0.05) ? '#1d2130' : '#ffffff'; };
+  const K = phone ? 120 : 200, z = Math.round((100 * -lo) / (hi - lo || 1));
+  // Signed: one bar through zero, with 0 marked where it falls on the scale.
+  const ramp = diverging
+    ? `<span>${esc(fmt(lo))}</span><i class="hm-signed" style="width:${K}px;background:linear-gradient(90deg, ${colour(lo)}, ${MID} ${z}%, ${colour(Math.max(hi, 0))})"><b style="left:${z}%">0</b></i><span>${esc(fmt(hi))}</span>`
+    : `<span>${esc(fmt(lo))}</span><i style="background:linear-gradient(90deg, ${[0, 0.25, 0.5, 0.75, 1].map((p) => colour(lo + (hi - lo) * p)).join(', ')})"></i><span>${esc(fmt(hi))}</span>`;
   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;
@@ -458,7 +548,7 @@ export function drawHeatmap(host, spec) {
   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>`
+  key.innerHTML = ramp
     + (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,
@@ -466,7 +556,7 @@ export function drawHeatmap(host, spec) {
     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,
+      show ? Plot.text(cells, { x: 'c', y: 'r', text: (d) => fmt(d.v), fill: (d) => textOn(d.v), 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,
     ],
@@ -474,3 +564,325 @@ export function drawHeatmap(host, spec) {
   key.style.marginLeft = labelW + 'px';
   host.prepend(key);
 }
+
+// ---------- signed estimates with ranges around zero (a forest plot) ----------
+
+/** Decimal places the author wrote, at most 3, so -0.18 is not printed as -0.2. */
+const placesOf = (vs) => Math.min(3, Math.max(0, ...vs.map((v) => { const m = /\.(\d+)/.exec(String(v)); return m ? m[1].length : 0; })));
+/** A signed number with a true minus sign: +7.4, −0.7, 0. */
+const signed = (v, places) => { const r = Math.abs(v).toFixed(places); return (+r === 0 ? '' : v > 0 ? '+' : '−') + r; };
+
+/**
+ * One row per estimate into a .chart: a dot at the value, a line across its range and a zero line through all of
+ * them. A row whose range clears zero is coloured; one whose range includes zero is grey with a hollow dot. Each row's
+ * value and range are printed in a column at the right; on a phone they go on a line above the row with its label.
+ */
+export function drawEstimates(host, spec) {
+  const t = themeOf(host);
+  host.classList.add('estimates');
+  const width = Math.floor(host.clientWidth) || 640;
+  const places = placesOf(spec.rows.flatMap((r) => [r.value, r.low, r.high]));
+  const u = spec.unit ?? '';
+  const rows = spec.rows.map((r, i) => {
+    const clear = r.low > 0 || r.high < 0;
+    const good = spec.better ? (r.value > 0) === (spec.better === 'higher') : null;
+    const color = !clear ? t.soft : good === null ? t.accent : good ? t.good : t.bad;
+    const n = r.n === undefined ? '' : spec.each ? `${r.n.toLocaleString('en-GB')} ${spec.each}` : `n = ${r.n.toLocaleString('en-GB')}`;
+    return { ...r, i, clear, color, n, val: signed(r.value, places) + u, span: `${signed(r.low, places)} to ${signed(r.high, places)}` };
+  });
+  // Zero always shows, with room on its empty side, so the line it is measured from is never the frame's edge.
+  const lo0 = Math.min(0, ...rows.map((r) => r.low)), hi0 = Math.max(0, ...rows.map((r) => r.high));
+  const room = (hi0 - lo0 || 1) * 0.1;
+  let lo = Math.min(lo0 - room * 0.5, -room), hi = Math.max(hi0 + room * 0.5, room);
+  const spanW = Math.ceil(widest(host, rows.map((r) => r.span), t.small));
+  const labelW = Math.ceil(widest(host, rows.map((r) => r.label), t.body));
+  const side = 12, plotW = width - 2 * side, ticks = Math.max(3, Math.min(6, Math.floor(plotW / 120)));
+  // Room each side of zero for the words saying what that side means, so they meet at the zero line.
+  if (spec.sides) {
+    const need = (txt) => Math.min(plotW * 0.35, widest(host, [txt], t.small) + 24);
+    const nb = need('← ' + spec.sides.below), na = need(spec.sides.above + ' →');
+    if (-lo / (hi - lo) * plotW < nb) lo = -(nb * hi) / (plotW - nb);
+    if (hi / (hi - lo) * plotW < na) hi = (na * -lo) / (plotW - na);
+  }
+  // Each row is a line of text (its label at the left, its value and range at the right) over its range. y runs in
+  // row units from the top: the text sits at a third of the row, the range at 0.72 of it.
+  const rowH = 84, T = 0.32, M = 0.72;
+  const halo = { stroke: t.paper, strokeWidth: 8, paintOrder: 'stroke' };
+  const tick = (d) => signed(d, Math.max(0, places - 1)) + (u.length <= 2 ? u : '');
+  const raw = (hi - lo) / ticks, mag = 10 ** Math.floor(Math.log10(raw)), step = [1, 2, 2.5, 5, 10].map((k) => k * mag).find((k) => (hi - lo) / k <= ticks + 1);
+  const tickVals = []; for (let v = Math.ceil(lo / step) * step; v <= hi + 1e-9; v += step) tickVals.push(+v.toFixed(10));
+  // The grid and the zero line run from just under each row's text to the next row, never through text.
+  const spans = rows.map((r) => ({ y1: r.i + 0.5, y2: r.i + 1 }));
+  const nW = rows[0].n ? Math.ceil(widest(host, rows.map((r) => r.n), t.small)) : 0;
+  plotInto(host, t, {
+    width, height: rows.length * rowH + 40, marginLeft: side, marginRight: side, marginTop: 0, marginBottom: 40,
+    x: { domain: [lo, hi], ticks: tickVals, label: null, tickFormat: tick, tickSize: 0 },
+    y: { domain: [0, rows.length], range: [0, rows.length * rowH], axis: null },
+    marks: [
+      ...tickVals.filter((v) => v !== 0).map((v) => Plot.ruleX(spans, { x: () => v, y1: 'y1', y2: 'y2', stroke: t.hair })),
+      Plot.ruleX(spans, { x: () => 0, y1: 'y1', y2: 'y2', stroke: t.ink, strokeWidth: 1.5 }),
+      Plot.link(rows, { x1: 'low', x2: 'high', y1: (r) => r.i + M, y2: (r) => r.i + M, stroke: 'color', strokeWidth: 3 }),
+      Plot.ruleX(rows.flatMap((r) => [{ ...r, x: r.low }, { ...r, x: r.high }]), { x: 'x', y1: (r) => r.i + M - 9 / rowH, y2: (r) => r.i + M + 9 / rowH, stroke: 'color', strokeWidth: 3 }),
+      Plot.dot(rows, { x: 'value', y: (r) => r.i + M, r: 7.5, fill: (r) => (r.clear ? r.color : t.paper), stroke: 'color', strokeWidth: 2.5 }),
+      Plot.text(rows, { y: (r) => r.i + T, frameAnchor: 'left', dx: -side, text: 'label', textAnchor: 'start', fill: t.ink, fontSize: t.body, ...halo }),
+      nW ? Plot.text(rows, { y: (r) => r.i + T, frameAnchor: 'left', dx: -side + labelW + 12, text: 'n', textAnchor: 'start', fill: t.soft, fontSize: t.small, ...halo }) : null,
+      Plot.text(rows, { y: (r) => r.i + T, frameAnchor: 'right', dx: side - spanW - 12, text: 'val', textAnchor: 'end', fill: (r) => (r.clear ? r.color : t.muted), fontWeight: (r) => (r.clear ? 600 : 400), fontSize: t.body, ...halo }),
+      Plot.text(rows, { y: (r) => r.i + T, frameAnchor: 'right', dx: side, text: 'span', textAnchor: 'end', fill: t.muted, fontSize: t.small, ...halo }),
+    ],
+  });
+  // What each side of zero means, under the axis, each reading away from the zero line.
+  if (spec.sides) {
+    const x0 = host.querySelector('svg').scale('x').apply(0);
+    const p = document.createElement('div');
+    p.className = 'est-sides';
+    p.innerHTML = `<span>← ${esc(spec.sides.below)}</span><span>${esc(spec.sides.above)} →</span>`;
+    host.appendChild(p);
+    const [below, above] = p.children;
+    const bw = below.offsetWidth, aw = above.offsetWidth;
+    if (x0 - 12 - bw < 0) window.fig?.problems.push(`sides.below: "${spec.sides.below}" is too long to end at the zero line; shorten it`);
+    if (x0 + 12 + aw > width) window.fig?.problems.push(`sides.above: "${spec.sides.above}" is too long to start at the zero line; shorten it`);
+    const bLeft = Math.max(0, x0 - 12 - bw);
+    const aLeft = Math.min(width - aw, Math.max(x0 + 12, bLeft + bw + 24));
+    below.style.left = `${bLeft}px`;
+    above.style.left = `${aLeft}px`;
+  }
+}
+
+/** The estimates key, under the reading line: what the ranges are, and what a filled or hollow dot says. */
+function estimatesKey(spec) {
+  const clear = spec.rows.map((r) => r.low > 0 || r.high < 0);
+  const p = document.createElement('p');
+  p.className = 'range-key';
+  const ink = spec.better ? 'var(--ink)' : 'var(--accent)';
+  p.innerHTML = `<span><i class="whisker"></i>${esc(spec.range)}</span>`
+    + (clear.some(Boolean) ? `<span><i class="est-dot" style="background:${ink};border-color:${ink}"></i>clear of 0</span>` : '')
+    + (clear.some((c) => !c) ? '<span><i class="est-dot" style="border-color:var(--soft)"></i>includes 0</span>' : '');
+  return p;
+}
+
+// ---------- every value as a dot, two measures against each other, small counts as units ----------
+
+/**
+ * Offsets that stack dots of radius r along a row so none overlaps another, nearest the middle first (a beeswarm).
+ * xs are pixel positions; returns a pixel offset from the row's centre line for each.
+ */
+export function swarm(xs, r) {
+  const d = 2 * r + 1, order = xs.map((x, i) => i).sort((a, b) => xs[a] - xs[b]);
+  const out = new Array(xs.length), placed = [];
+  for (const i of order) {
+    const x = xs[i], near = placed.filter((p) => Math.abs(p.x - x) < d);
+    const free = (y) => near.every((p) => (p.x - x) ** 2 + (p.y - y) ** 2 >= d * d - 1e-6);
+    const tries = [0, ...near.flatMap((p) => { const h = Math.sqrt(Math.max(0, d * d - (p.x - x) ** 2)); return [p.y + h, p.y - h]; })]
+      .sort((a, b) => Math.abs(a) - Math.abs(b) || b - a);
+    const y = tries.find(free) ?? 0;
+    out[i] = y;
+    placed.push({ x, y });
+  }
+  return out;
+}
+
+const middle = (vs) => { const s = [...vs].sort((a, b) => a - b), m = s.length >> 1; return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2; };
+
+/**
+ * Every value as a dot into a .chart: one row per group on a shared axis, dots stacked where they would overlap.
+ * The group's name and count sit to the left (above, on a phone); a median or mean is a line across the row.
+ */
+export function drawDots(host, spec) {
+  const t = themeOf(host);
+  const width = Math.floor(host.clientWidth) || 640, phone = phoneOf(host) || width < 460;
+  const fmt = (v) => num(v) + (spec.unit ?? '');
+  const all = spec.groups.flatMap((g) => g.values);
+  const lo = spec.zero ? 0 : Math.min(...all), hi = spec.max ?? Math.max(...all);
+  const counts = spec.groups.map((g) => (spec.each ? `${g.values.length.toLocaleString('en-GB')} ${spec.each}` : `n = ${g.values.length.toLocaleString('en-GB')}`));
+  const many = spec.groups.length > 1;
+  const labelW = phone || !many ? 0 : Math.ceil(Math.max(widest(host, spec.groups.map((g) => g.label), t.body, 600), widest(host, counts, t.small))) + 24;
+  // Room for half the first tick label, so "0 min" does not stick out past the text edge.
+  const ml = Math.max(labelW + 10, Math.ceil(widest(host, [fmt(lo)], t.small) / 2) + 2), mr = 18;
+  const x = Plot.scale({ x: { domain: [lo, hi === lo ? lo + 1 : hi], range: [ml, width - mr], nice: true } });
+  // As many ticks as fit with a clear gap between their labels.
+  const nt = Math.max(2, Math.min(6, Math.floor((width - ml - mr) / (widest(host, x.domain.map(fmt), t.small) + 32))));
+  // The largest dots that keep the tallest stack within reach of the row.
+  const most = phone ? 56 : 64;
+  let r = phone ? 6 : 7.5, offs;
+  for (;;) {
+    offs = spec.groups.map((g) => swarm(g.values.map((v) => x.apply(v)), r));
+    const tallest = Math.max(...offs.flat().map(Math.abs));
+    if (tallest <= most || r <= 2.5) break;
+    r -= 0.5;
+  }
+  const sumName = spec.summary, dots = [], rows = [];
+  // A single group needs no name in the chart: the title and note say what it is.
+  const head = (phone && many ? Math.ceil(t.small * 2.7) : 0) + (sumName ? Math.ceil(t.small * 1.6) : 0);
+  let y = 6;
+  spec.groups.forEach((g, gi) => {
+    const half = Math.max(...offs[gi].map(Math.abs)) + r;
+    const top = y + head, mid = top + half;
+    const s = sumName === 'mean' ? g.values.reduce((a, v) => a + v, 0) / g.values.length : sumName ? middle(g.values) : null;
+    const colour = g.tone ? t[g.tone] : t.fill;
+    g.values.forEach((v, i) => dots.push({ v, y: mid + offs[gi][i], colour, g: g.label }));
+    rows.push({ g, top, mid, bottom: mid + half, s, label: g.label, count: counts[gi], colour, tone: g.tone });
+    y = mid + half + (phone ? 22 : 26);
+  });
+  const height = y - (phone ? 22 : 26) + 8 + 40;
+  const mark = spec.mark && dots.find((d) => d.g === spec.mark.group && d.v === spec.mark.value);
+  // The mark's label sits above its dot, reaching away from the nearer edge, so it never covers the dots beside it.
+  const markEnd = mark && x.apply(mark.v) + widest(host, [spec.mark.label], t.small, 600) > width - mr;
+  plotInto(host, t, {
+    width, height, marginLeft: ml, marginRight: mr, marginTop: 0, marginBottom: 40,
+    x: { domain: x.domain, nice: false, label: null, ticks: nt, tickFormat: fmt },
+    y: { type: 'identity', axis: null },
+    marks: [
+      Plot.gridX({ ticks: nt, stroke: t.hair, strokeOpacity: 1, y1: 0, y2: height - 40 }),
+      // The summary line runs behind the dots and out past both ends of the row, so it shows without cutting a dot.
+      sumName ? Plot.ruleX(rows, { x: 's', y1: (d) => d.top - 6, y2: (d) => d.bottom + 6, stroke: t.ink, strokeWidth: 2.5 }) : null,
+      Plot.dot(dots, { x: 'v', y: 'y', r, fill: 'colour', stroke: t.paper, strokeWidth: 1 }),
+      sumName ? Plot.text(rows, { x: 's', y: (d) => d.top - 10, text: (d) => `${sumName} ${fmt(d.s)}`, lineAnchor: 'bottom', fill: t.muted, fontSize: t.small, stroke: t.paper, strokeWidth: 6, paintOrder: 'stroke' }) : null,
+      many && !phone ? Plot.text(rows, { frameAnchor: 'left', y: (d) => d.mid - t.small * 0.6, text: 'label', textAnchor: 'start', dx: -ml, fill: (d) => (d.tone ? t[d.tone] : t.ink), fontWeight: 600, fontSize: t.body }) : null,
+      many && !phone ? Plot.text(rows, { frameAnchor: 'left', y: (d) => d.mid + t.small * 0.7, text: 'count', textAnchor: 'start', dx: -ml, fill: t.muted, fontSize: t.small }) : null,
+      many && phone ? Plot.text(rows, { frameAnchor: 'left', y: (d) => d.top - head + 2, text: 'label', textAnchor: 'start', lineAnchor: 'top', dx: -ml, fill: (d) => (d.tone ? t[d.tone] : t.ink), fontWeight: 600, fontSize: t.small, stroke: t.paper, strokeWidth: 6, paintOrder: 'stroke' }) : null,
+      many && phone ? Plot.text(rows, { frameAnchor: 'left', y: (d) => d.top - head + 2 + t.small * 1.3, text: 'count', textAnchor: 'start', lineAnchor: 'top', dx: -ml, fill: t.muted, fontSize: t.small, stroke: t.paper, strokeWidth: 6, paintOrder: 'stroke' }) : null,
+      mark ? Plot.dot([mark], { x: 'v', y: 'y', r: r + 3.5, stroke: t.accent, strokeWidth: 2.5, fill: 'none' }) : null,
+      mark ? Plot.text([mark], { x: 'v', y: (d) => d.y - r - 9, text: () => spec.mark.label, dx: markEnd ? r + 3.5 : -(r + 3.5), lineAnchor: 'bottom', textAnchor: markEnd ? 'end' : 'start', fill: t.accent, fontWeight: 600, fontSize: t.small }) : null,
+    ],
+  });
+  if (!many) {
+    const p = document.createElement('p');
+    p.className = 'dots-n';
+    p.textContent = counts[0];
+    host.prepend(p);
+  }
+}
+
+const SECONDS = { seconds: 1, minutes: 60, hours: 3600, days: 86400 };
+const SPANS = [[1, '1 s', 1], [10, '10 s', 2], [60, '1 min', 1], [600, '10 min', 2], [3600, '1 h', 1], [21600, '6 h', 2], [86400, '1 day', 1], [604800, '1 wk', 1], [2592000, '1 mo', 1], [31536000, '1 yr', 1]];
+/** A duration in seconds as the reader says it: 40 s, 12 min, 5 h, 3 days. */
+function said(sec) {
+  const at = (n, u) => `${num(n)} ${u}`;
+  if (sec === 0) return '0';
+  if (sec < 60) return at(sec, 's');
+  if (sec < 3600) return at(sec / 60, 'min');
+  if (sec < 172800) return at(sec / 3600, 'h');
+  return at(sec / 86400, 'days');
+}
+
+/**
+ * One scatter axis: its domain, ticks and labels. A log axis runs to whole powers of ten (or, for time, to the
+ * nearest of 1 min, 1 h, 1 day...) beyond the data, so every dot sits inside a labelled tick.
+ */
+function scatterAxis(a, vs, host, t, room) {
+  const lo = Math.min(...vs), hi = Math.max(...vs);
+  const mult = a.time ? SECONDS[a.time] : 1;
+  const fmt = a.time ? (v) => said(v * mult) : (v) => (Math.abs(v) > 0 && Math.abs(v) < 1 ? String(+v.toPrecision(2)) : num(v)) + (a.unit ?? '');
+  if (a.log && a.time) {
+    const s0 = lo * mult, s1 = hi * mult;
+    const from = [...SPANS].reverse().find(([v]) => v <= s0) ?? SPANS[0];
+    const to = SPANS.find(([v]) => v >= s1) ?? SPANS[SPANS.length - 1];
+    let ticks = SPANS.filter(([v]) => v >= from[0] && v <= to[0]);
+    if (ticks.length > 7) ticks = ticks.filter((k) => k[2] === 1 || k === from || k === to);
+    return { type: 'log', domain: [from[0] / mult, to[0] / mult], ticks: ticks.map(([v]) => v / mult), fmt: (v) => SPANS.find(([s]) => Math.abs(s - v * mult) < 1e-6)?.[1] ?? said(v * mult) };
+  }
+  if (a.log) {
+    const e0 = Math.floor(Math.log10(lo)), e1 = Math.ceil(Math.log10(hi));
+    const ms = e1 - e0 > 3 ? [1] : [1, 3], ticks = [];
+    for (let e = e0; e <= e1; e++) for (const m of ms) if (m * 10 ** e <= 10 ** e1) ticks.push(m * 10 ** e);
+    return { type: 'log', domain: [10 ** e0, 10 ** e1], ticks, fmt };
+  }
+  const domain = a.zero ? [Math.min(0, lo), hi] : [lo, hi];
+  const n = Math.max(2, Math.min(6, Math.floor(room / (widest(host, domain.map(fmt), t.small) + 32))));
+  return { type: 'linear', domain, ticks: n, fmt, nice: true };
+}
+
+/**
+ * Two measures against each other into a .chart: a dot per thing, the named ones in colour and labelled beside them.
+ * With `medians`, the median y of each band of x is drawn across that band: the relation, without fitting a model.
+ */
+export function drawScatter(host, spec) {
+  const t = themeOf(host);
+  const width = Math.floor(host.clientWidth) || 640, phone = phoneOf(host) || width < 460;
+  const pts = [...spec.points].sort((a, b) => (a.tone || a.label ? 1 : 0) - (b.tone || b.label ? 1 : 0));
+  const Y = scatterAxis(spec.y, pts.map((p) => p.y), host, t, 300);
+  const tickW = Math.ceil(widest(host, (Array.isArray(Y.ticks) ? Y.ticks : Y.domain).map(Y.fmt), t.small)) + 14;
+  const X = scatterAxis(spec.x, pts.map((p) => p.x), host, t, width - tickW - 16);
+  // A log axis is drawn as a linear axis over log10 of the values, with figkit's own ticks: Plot's log axis blanks
+  // every tick label that is not a power of ten, whatever the format.
+  const lin = (A) => (A.type === 'log' ? { ...A, type: 'linear', domain: A.domain.map(Math.log10), ticks: A.ticks.map(Math.log10), fmt: (l) => A.fmt(10 ** l), at: Math.log10 } : { ...A, at: (v) => v });
+  const XL = lin(X), YL = lin(Y);
+  const dots = pts.map((p) => ({ ...p, px: XL.at(p.x), py: YL.at(p.y) }));
+  const height = phone ? 340 : 420;
+  const r = (pts.length > 300 ? 3.5 : pts.length > 80 ? 4.5 : 6) * (phone ? 0.8 : 1);
+  const faint = pts.length > 150 ? 0.45 : 0.7;
+  // A label reads away from the nearer side of the plot: points in the right half are labelled to their left.
+  const f = (v) => (X.type === 'log' ? Math.log10(v) : v), [x0, x1] = X.domain.map(f);
+  const leftward = (p) => f(p.x) > (x0 + x1) / 2;
+  let bands = [];
+  if (spec.medians) {
+    const edges = X.type === 'log'
+      ? Array.from({ length: Math.round(x1 - x0) + 1 }, (_, i) => 10 ** (x0 + i))
+      : Array.from({ length: 6 }, (_, i) => X.domain[0] + ((X.domain[1] - X.domain[0]) * i) / 5);
+    for (let i = 0; i + 1 < edges.length; i++) {
+      const inside = pts.filter((p) => p.x >= edges[i] && (i + 2 === edges.length ? p.x <= edges[i + 1] : p.x < edges[i + 1]));
+      if (inside.length < 5) continue;
+      const ys = inside.map((p) => p.y).sort((u, v) => u - v), q = (k) => ys[Math.min(ys.length - 1, Math.max(0, Math.round(k * (ys.length - 1))))];
+      // Each band spans its own dots, so a band with few dots at its near end does not reach across empty space.
+      bands.push({ a: Math.min(...inside.map((p) => p.x)), b: Math.max(...inside.map((p) => p.x)), m: middle(ys), q1: q(0.25), q3: q(0.75) });
+    }
+  }
+  const mt = Math.ceil(t.small * 1.4) + 20, mb = Math.ceil(t.small * 2.6) + 14;
+  // Room for half the last x tick label, so "10,000" ends inside the card.
+  const last = Array.isArray(XL.ticks) ? XL.fmt(XL.ticks[XL.ticks.length - 1]) : XL.fmt(XL.domain[1]);
+  const mr = Math.max(16, Math.ceil(widest(host, [last], t.small) / 2) - r - 4);
+  plotInto(host, t, {
+    width, height, marginLeft: tickW, marginRight: mr, marginTop: mt, marginBottom: mb,
+    x: { domain: XL.domain, nice: XL.nice ?? false, inset: r + 6, label: null, ticks: XL.ticks, tickFormat: XL.fmt },
+    y: { domain: YL.domain, nice: YL.nice ?? false, inset: r + 6, label: null, grid: true, ticks: YL.ticks, tickSize: 0, tickFormat: YL.fmt },
+    marks: [
+      Plot.dot(dots, { x: 'px', y: 'py', r, fill: (p) => (p.tone ? t[p.tone] : t.fill), fillOpacity: (p) => (p.tone ? 1 : faint) }),
+      bands.length ? Plot.rect(bands, { x1: (d) => XL.at(d.a), x2: (d) => XL.at(d.b), y1: (d) => YL.at(d.q1), y2: (d) => YL.at(d.q3), fill: t.accent, fillOpacity: 0.14, insetLeft: 2, insetRight: 2 }) : null,
+      bands.length ? Plot.ruleY(bands, { y: (d) => YL.at(d.m), x1: (d) => XL.at(d.a), x2: (d) => XL.at(d.b), stroke: t.accent, strokeWidth: 4, insetLeft: 2, insetRight: 2 }) : null,
+      Plot.text(dots.filter((p) => p.label && !leftward(p)), { x: 'px', y: 'py', text: 'label', dx: r + 8, textAnchor: 'start', fill: (p) => (p.tone ? t[p.tone] : t.ink), fontWeight: 600, fontSize: t.small }),
+      Plot.text(dots.filter((p) => p.label && leftward(p)), { x: 'px', y: 'py', text: 'label', dx: -(r + 8), textAnchor: 'end', fill: (p) => (p.tone ? t[p.tone] : t.ink), fontWeight: 600, fontSize: t.small }),
+      // What each axis measures, written along it: the y label above its axis, the x label under the ticks at the right.
+      Plot.text([spec.y.label], { frameAnchor: 'top-left', dx: -tickW, dy: -mt + 2, text: (d) => d, textAnchor: 'start', lineAnchor: 'top', fill: t.muted, fontWeight: 600, fontSize: t.small }),
+      Plot.text([spec.x.label], { frameAnchor: 'bottom-right', dy: mb - 4, text: (d) => d, textAnchor: 'end', lineAnchor: 'bottom', fill: t.muted, fontWeight: 600, fontSize: t.small }),
+    ],
+  });
+  if (bands.length) {
+    const key = document.createElement('p');
+    key.className = 'range-key';
+    key.innerHTML = `<span><i class="median" style="background:${t.accent}"></i>median of each band of ${esc(spec.x.label.toLowerCase())}</span><span><i class="band" style="background:${t.accent};opacity:.3"></i>its middle half</span>`;
+    key.style.marginBottom = '14px';
+    host.prepend(key);
+  }
+}
+
+/**
+ * A small count as squares into a .chart: rows of ten, filled column by column so each part is one solid block from the
+ * left. No gutters: a gap between squares would read as a split the data does not have.
+ */
+export function drawUnits(host, spec) {
+  const t = themeOf(host);
+  const width = Math.floor(host.clientWidth) || 640, phone = phoneOf(host) || width < 460;
+  const cols = Math.min(10, spec.total), rows = Math.ceil(spec.total / cols), gap = phone ? 5 : 7;
+  const size = Math.min(phone ? 34 : 48, Math.floor((width - gap * (cols - 1)) / cols));
+  const greys = [t.fill, t.fill2];
+  let g = 0;
+  const parts = spec.parts.map((p, i) => ({ ...p, colour: p.tone ? t[p.tone] : i === 0 ? t.accent : greys[g++ % 2] }));
+  host.className = 'units';
+  host.innerHTML = '';
+  const grid = document.createElement('div');
+  grid.className = 'un-grid';
+  grid.style.cssText = `grid-template-columns: repeat(${cols}, ${size}px); grid-template-rows: repeat(${rows}, ${size}px); grid-auto-flow: column; gap: ${gap}px; --un: ${size}px;`;
+  const cells = parts.flatMap((p) => Array(p.count).fill(p.colour));
+  for (let i = 0; i < spec.total; i++) {
+    const c = document.createElement('i');
+    if (cells[i]) c.style.background = cells[i];
+    else c.className = 'empty';
+    grid.appendChild(c);
+  }
+  const rest = spec.total - cells.length;
+  const key = document.createElement('div');
+  key.className = 'un-key';
+  key.innerHTML = parts.map((p) => `<span><i style="background:${p.colour}"></i><b style="color:${p.colour === t.accent || p.tone ? p.colour : t.ink}">${p.count}</b>${esc(p.label)}</span>`).join('')
+    + `<span><i class="empty"></i><b style="color:${t.muted}">${rest}</b>${esc(spec.rest)}</span>`;
+  host.append(grid, key);
+}