@liggi/figkit 0.4.0 → 0.5.0

package/examples/charts/bars-ref.json

@@ -0,0 +1,6 @@
+{ "type": "bars", "title": "Two of the four new layouts beat the current page",
+  "note": "Share of visitors who finished checkout", "unit": "%",
+  "ref": { "label": "Current page", "value": 61 },
+  "bars": [ { "label": "One-page form", "value": 68 }, { "label": "Saved cards first", "value": 64 },
+            { "label": "Address lookup", "value": 60 }, { "label": "Guest by default", "value": 57 } ],
+  "source": "Invented data, for illustration." }

package/examples/charts/estimates.json

@@ -0,0 +1,7 @@
+{ "type": "estimates", "title": "Free delivery lifts orders in two regions; the north's range includes zero",
+  "note": "Change in orders per 100 visitors, free delivery minus paid", "range": "95% interval",
+  "sides": { "below": "Paid better", "above": "Free better" },
+  "rows": [ { "label": "South", "value": 2.4, "low": 1.1, "high": 3.7 },
+            { "label": "Midlands", "value": 1.8, "low": 0.6, "high": 3.0 },
+            { "label": "North", "value": 0.7, "low": -0.9, "high": 2.3 } ],
+  "source": "Invented data, for illustration." }

package/examples/charts/heatmap-signed.json

@@ -0,0 +1,5 @@
+{ "type": "heatmap", "title": "The new menu helped every region except the north",
+  "note": "Change in weekly orders per store after the new menu", "unit": "%",
+  "rows": ["South", "Midlands", "North"], "columns": ["Wk 1", "Wk 2", "Wk 3", "Wk 4"],
+  "values": [ [3.1, 4.4, 5.0, 4.8], [1.2, 2.6, 3.3, 3.9], [-2.4, -3.8, -1.9, -2.7] ],
+  "source": "Invented data, for illustration." }

package/examples/charts/states.json

@@ -0,0 +1,71 @@
+{
+  "type": "states",
+  "title": "An order waits after a declined card until a new card is added",
+  "entry": "Shopper checks out",
+  "states": [
+    {
+      "id": "waiting",
+      "name": "Awaiting payment",
+      "start": true
+    },
+    {
+      "id": "declined",
+      "name": "Card declined",
+      "note": "Shopper emailed",
+      "tone": "accent"
+    },
+    {
+      "id": "paid",
+      "name": "Paid"
+    },
+    {
+      "id": "packed",
+      "name": "Packed"
+    },
+    {
+      "id": "shipped",
+      "name": "Shipped",
+      "end": true
+    },
+    {
+      "id": "cancelled",
+      "name": "Cancelled",
+      "end": true
+    }
+  ],
+  "moves": [
+    {
+      "from": "waiting",
+      "to": "paid",
+      "label": "Charge succeeds"
+    },
+    {
+      "from": "waiting",
+      "to": "declined",
+      "label": "Charge fails"
+    },
+    {
+      "from": "declined",
+      "to": "waiting",
+      "label": "New card added"
+    },
+    {
+      "from": "paid",
+      "to": "packed",
+      "label": "Warehouse picks"
+    },
+    {
+      "from": "packed",
+      "to": "shipped",
+      "label": "Carrier collects"
+    },
+    {
+      "from": [
+        "paid",
+        "packed"
+      ],
+      "to": "cancelled",
+      "label": "Shopper cancels"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liggi/figkit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Explanatory figures for agents and people: write a little HTML or a chart spec, get a laid-out PNG and a list of what is wrong with it.",
   "license": "MIT",
   "type": "module",

package/runtime/fig.css

@@ -274,3 +274,42 @@ fig-bars .fb-label .fb-n { display: block; font-size: var(--small); color: var(-
 .fig.phone fig-bars { grid-template-columns: minmax(0, 1fr); row-gap: 4px; }
 .fig.phone fig-bars .fb-label { margin-top: 10px; }
 .fig.phone fig-bars .fb-label .fb-n { display: inline; margin-left: 8px; }
+
+/* estimates: signed values with ranges around a zero line; what each side of zero means under the axis */
+.fig .estimates { position: relative; }
+
+.fig .range-key i.est-dot { width: 14px; height: 14px; border-radius: 50%; border: 2.5px solid; box-sizing: border-box; }
+.fig .est-sides { position: relative; height: calc(var(--small) * 1.4); margin-top: -6px; font-size: var(--small); color: var(--muted); }
+.fig .est-sides span { position: absolute; top: 0; white-space: nowrap; }
+
+/* bars with a reference: its own first row in the second colour, and a dashed line from its end through the rest */
+fig-bars.has-ref { position: relative; }
+fig-bars .fb-label.ref { color: var(--second); }
+fig-bars .fb-refline { position: absolute; width: 0; border-left: 2px dashed var(--second); pointer-events: none; }
+.fig .range-key i.swatch { width: 18px; height: 14px; border-radius: 2px; background: var(--accent); }
+fig-bars.has-ref .fb-label.ref + .fb-track .fb-bar { opacity: .55; }
+/* on a phone the names sit above the bars, so the reference line stops at each name rather than crossing it */
+.fig.phone fig-bars.has-ref .fb-label { position: relative; z-index: 1; justify-self: start; background: var(--paper); padding-right: 8px; }
+.fig .hm-key i.hm-signed { position: relative; margin-bottom: calc(var(--small) * 1.3); }
+.fig .hm-key i.hm-signed b { font-style: normal; position: absolute; top: 100%; transform: translateX(-50%); font-weight: 400; color: var(--muted); padding-top: 2px; line-height: 1; }
+.fig .hm-key i.hm-signed b::before { content: ''; position: absolute; left: 50%; top: -14px; height: 14px; border-left: 2px solid var(--paper); }
+fig-bars.has-ref .fb-val:not(.lead) { color: var(--muted); }
+/* Against a reference, a bar that clears it is solid accent (a faded orange reads as brown on dark); its range is drawn in ink on top. */
+fig-bars.has-ref .fb-bar.dim.accent { opacity: 1; }
+fig-bars.has-ref .fb-range.accent { --tone: var(--ink); }
+
+/* ---------- states: what one thing moves through (a spec of type "states") ---------- */
+.fig .states { display: grid; column-gap: 120px; row-gap: 76px; align-items: stretch; justify-content: start; }
+.fig.phone .states { column-gap: 64px; row-gap: 68px; }
+.fig.phone .state { padding: 12px 10px; }
+.fig.phone .state > h3 { font-size: var(--body); }
+.fig .state { text-align: center; align-items: center; justify-content: center; justify-self: stretch; }
+.fig .state > p { margin-top: 4px; }
+.fig .state > .st-stayed { color: var(--ink); }
+.fig .node.bare.st-dot { width: 22px; height: 22px; padding: 0; border-radius: 50%; background: var(--line); justify-self: center; align-self: center; }
+.fig .fig-wire-label .fig-wire-sub { display: block; font-weight: 400; font-variant-numeric: tabular-nums; }
+.fig .st-key { font-size: var(--small); }
+.fig .state.mid { align-self: center; }
+/* the bracket beside the states that share one move, which leads to it with one arrow */
+.fig .node.bare.st-bracket { justify-self: end; width: 14px; margin-right: -30px; padding: 0; border: 1.5px solid var(--line); border-left: 0; border-radius: 0 4px 4px 0; background: none; }
+.fig.phone .node.bare.st-bracket { margin-right: -24px; width: 10px; }

package/runtime/fig.js

@@ -42,7 +42,7 @@
   function obstacles() {
     const out = [];
     const solid = [...root().querySelectorAll(SOLID)].filter(visible);
-    for (const el of solid) if (!el.classList.contains('bare')) out.push({ el, r: rectOf(el) });
+    for (const el of solid) if (!el.classList.contains('bare') || el.classList.contains('st-bracket')) out.push({ el, r: rectOf(el) });
     const walker = document.createTreeWalker(root(), NodeFilter.SHOW_TEXT);
     const seen = new Set();
     for (let n = walker.nextNode(); n; n = walker.nextNode()) {
@@ -370,7 +370,7 @@
       fig.wires.push({ from, to, pts, mode, ref });
 
       const text = ref ? '' : tag.getAttribute('label') ?? tag.textContent.trim();
-      if (text) labels.push({ text, tone, color, pts, at: labelAt, want: tag.getAttribute('label-at'), from, to });
+      if (text) labels.push({ text, sub: tag.getAttribute('sub'), tone, color, pts, at: labelAt, want: tag.getAttribute('label-at'), from, to });
     }
     return placeLabels(labels, obs);
   }
@@ -467,6 +467,8 @@
       const lab = document.createElement('div');
       lab.className = 'fig-wire-label';
       lab.textContent = L.text;
+      // Further lines under the label, such as a count: one span each.
+      for (const t of (L.sub ?? '').split('\n').filter(Boolean)) { const e = document.createElement('span'); e.className = 'fig-wire-sub'; e.textContent = t; lab.appendChild(e); }
       if (L.tone !== 'line') lab.style.color = L.color;
       lab.dataset.arrow = `${L.from} → ${L.to}`;
       R.appendChild(lab);
@@ -553,10 +555,66 @@
   });
 
   // ---------- checks ----------
+  /** The colour as [r, g, b, a] (0–255, alpha 0–1), or null when it is not a plain colour (none, a gradient, a pattern). */
+  function rgba(c) {
+    const m = /^rgba?\(([\d.]+),\s*([\d.]+),\s*([\d.]+)(?:,\s*([\d.]+))?\)$/.exec((c || '').trim());
+    if (m) return [+m[1], +m[2], +m[3], m[4] === undefined ? 1 : +m[4]];
+    const s = /^color\(srgb ([\d.e-]+) ([\d.e-]+) ([\d.e-]+)(?: \/ ([\d.]+))?\)$/.exec((c || '').trim());
+    return s ? [+s[1] * 255, +s[2] * 255, +s[3] * 255, s[4] === undefined ? 1 : +s[4]] : null;
+  }
+  const lumOf = ([r, g, b]) => [r, g, b].map((v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4; }).reduce((s, v, i) => s + v * [0.2126, 0.7152, 0.0722][i], 0);
+  const over = (top, under) => [0, 1, 2].map((i) => top[i] * top[3] + under[i] * (1 - top[3])).concat(1);
+  function opacityOf(el) { let o = 1; for (let x = el; x && x !== document.documentElement; x = x.parentElement) o *= parseFloat(getComputedStyle(x).opacity); return o; }
+  /** The colour an element paints over its own area, with its opacity, or undefined when it paints nothing there. */
+  function paintOf(el) {
+    const cs = getComputedStyle(el);
+    if (el instanceof SVGElement) {
+      if (!/^(rect|path|circle|ellipse|polygon)$/.test(el.tagName)) return undefined;
+      if (cs.fill === 'none') return undefined;
+      const c = rgba(cs.fill);
+      return c ? [c[0], c[1], c[2], c[3] * parseFloat(cs.fillOpacity) * opacityOf(el)] : null;
+    }
+    if (cs.backgroundImage !== 'none') return null;
+    const c = rgba(cs.backgroundColor);
+    if (!c) return null;
+    return c[3] === 0 ? undefined : [c[0], c[1], c[2], c[3] * opacityOf(el)];
+  }
+  /** Contrast between a text element and what lies under its middle, as a WCAG ratio; null when it cannot be told. */
+  function contrastOf(el) {
+    const b = el.getBoundingClientRect();
+    if (b.top < 0 || b.bottom > innerHeight || b.left < 0 || b.right > innerWidth) el.scrollIntoView({ block: 'center', inline: 'center' });
+    const r = el.tagName === 'text' ? el.getBoundingClientRect() : (() => { const t = textRect(el), o = R0(); return { x: t.x + o.x, y: t.y + o.y, width: t.w, height: t.h }; })();
+    const stack = document.elementsFromPoint(r.x + r.width / 2, r.y + r.height / 2);
+    let i = stack.findIndex((x) => x === el || x.contains(el));
+    if (i < 0) return null;
+    if (el.tagName === 'text') i++;
+    const layers = [];
+    for (; i < stack.length; i++) {
+      const p = paintOf(stack[i]);
+      if (p === null) return null;
+      if (p === undefined) continue;
+      layers.push(p);
+      if (p[3] >= 0.99) break;
+    }
+    let bg = [255, 255, 255, 1];
+    for (const l of layers.reverse()) bg = over(l, bg);
+    const cs = getComputedStyle(el);
+    const fg = rgba(el.tagName === 'text' ? cs.fill : cs.color);
+    if (!fg) return null;
+    const ink = over([fg[0], fg[1], fg[2], fg[3] * opacityOf(el)], bg);
+    const la = lumOf(ink), lb = lumOf(bg);
+    return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+  }
+  const R0 = () => { const b = root().getBoundingClientRect(); return { x: b.x, y: b.y }; };
+
   function check() {
     const R = root(), P = fig.problems;
     const W = R.offsetWidth, H = R.offsetHeight;
     const detail = R.classList.contains('detail');
+    // A phone layout is 560px wide (fig.css); opening gaps for labels can widen it past that.
+    const phoneW = R.classList.contains('phone') ? 560 : 0;
+    const wide = Math.max(W, R.scrollWidth, R.getBoundingClientRect().width);
+    if (phoneW && wide > phoneW + 1) P.push(`The figure is ${Math.round(wide)}px wide on a phone, wider than ${phoneW}px; shorten the widest labels.`);
     const minText = detail ? 13 : 15;
     const obs = obstacles();
 
@@ -574,6 +632,15 @@
       if (hit) P.push(`Chart label covers ${hit === 1 ? 'a dot' : hit + ' dots'}: "${a.e.textContent.trim()}".`);
     }
 
+    // Text that cannot be read against what is drawn behind it, such as white numbers on a pale cell.
+    for (const e of [...R.querySelectorAll('*')].filter((x) => !x.closest('svg') || x.tagName === 'text')) {
+      if (e.tagName !== 'text' && ![...e.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim())) continue;
+      if (!e.textContent.trim() || !visible(e) || e.matches('script, style')) continue;
+      const ratio = contrastOf(e);
+      if (ratio !== null && ratio < 3) P.push(`Text cannot be read against what is behind it: "${e.textContent.trim().replace(/\s+/g, ' ')}" (contrast ${ratio.toFixed(1)} to 1; it needs 3).`);
+    }
+    window.scrollTo(0, 0);
+
     // Text: too small, cut off, or past its box.
     const small = [];
     for (const o of obs.flatMap((b) => (b.text ? [b.el] : [...b.el.querySelectorAll('*')].filter((e) => [...e.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim()))))) {
@@ -626,6 +693,7 @@
     const crossings = new Set(crossingPairs().map(([u, w]) => `${u.from} → ${u.to} and ${w.from} → ${w.to}`));
     if (crossings.size) P.push(R.querySelector('.entities')
       ? `References cross: ${[...crossings].join('; ')}. Split the records over two figures; do not leave a reference out.`
+      : R.querySelector('.states') ? `Moves cross: ${[...crossings].join('; ')}. figkit could not lay them out apart; draw the side branch as a second figure.`
       : `Arrows cross: ${[...crossings].join('; ')}. Reorder the boxes so they do not, or drop an arrow.`);
 
     // Neighbours that almost line up.
@@ -647,7 +715,9 @@
     const outside = R.querySelector('.panels') ? [...R.children].filter((c) => !c.matches('script, style') && !c.querySelector('.panels') && !c.matches('.panels')).map((c) => c.innerText).join(' ') : null;
     const words = (panelText !== null ? outside + ' ' + panelText : R.innerText).split(/\s+/).filter(Boolean).length;
     const nodes = R.querySelectorAll('.node:not(.bare), .decision').length, arrows = (fig.wires ?? []).length;
-    const budget = detail ? { words: 190, nodes: 18, arrows: 18 } : { words: 70, nodes: 5, arrows: 8 };
+    // A states picture reads down one path of short names, so it holds up to 7 states (see the states spec).
+    const states = !!R.querySelector('.states');
+    const budget = detail ? { words: 190, nodes: 18, arrows: 18 } : states ? { words: 90, nodes: 7, arrows: 12 } : { words: 70, nodes: 5, arrows: 8 };
     if (words > budget.words) P.push(`${words} words; a ${detail ? 'detail' : 'glance'} figure holds about ${budget.words}. Cut sentences that explain, and keep labels.`);
     if (nodes > budget.nodes) P.push(`${nodes} boxes; more than ${budget.nodes} stops reading as one picture. ${detail ? 'Split it into two figures or merge boxes.' : 'Split it into two or three figures in a row (what exists, one case through it, what changes), or merge boxes.'}`);
     if (arrows > budget.arrows) P.push(`${arrows} arrows; more than ${budget.arrows} tangles. Show the main path and drop the rest.`);

package/viz/draw.js

@@ -1,6 +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]);
 
@@ -84,11 +85,15 @@ 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 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) {
-  const top = max ?? Math.max(...bars.map((b) => Math.max(b.value, b.high ?? 0)));
+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 + (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 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 : '';
     const ranged = b.low !== undefined;
@@ -109,6 +114,20 @@ export function drawBars(host, bars, unit, max, each) {
     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. */
@@ -116,7 +135,8 @@ 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 ? `<span><i class="dash"></i>${esc(spec.ref.label)}</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;
 }
 
@@ -316,20 +336,33 @@ 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', dots: 'div', scatter: 'div', units: '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.range || spec.ref) header.appendChild(rangeKey(spec));
+  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);
@@ -346,6 +379,7 @@ 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 });
@@ -356,7 +390,7 @@ export function drawSpec(spec, main) {
     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, spec.each);
+    else drawBars(chart, items, spec.unit, spec.max, spec.each, spec.ref && { ...spec.ref, label: esc(spec.ref.label) });
   };
   draw();
   return { chart, draw };
@@ -484,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;
@@ -502,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,
@@ -510,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,
     ],
@@ -519,6 +565,101 @@ export function drawHeatmap(host, spec) {
   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 ----------
 
 /**