@liggi/figkit 0.3.0 → 0.4.0

package/examples/charts/bars-range.json

@@ -0,0 +1,6 @@
+{ "type": "bars", "style": "report", "title": "The new reply check catches more, but the ranges still overlap",
+  "note": "Share of unsafe replies caught, on the same test set", "unit": "%", "max": 100,
+  "range": "likely range (95%)", "each": "replies",
+  "bars": [ { "label": "Current check", "value": 64, "low": 53, "high": 74, "n": 72 },
+            { "label": "New check", "value": 78, "low": 67, "high": 86, "n": 72, "tone": "accent" } ],
+  "source": "Invented example data" }

package/examples/charts/dots.json

@@ -0,0 +1,6 @@
+{ "type": "dots", "style": "report", "title": "Most builds finish in four minutes; a few take over ten",
+  "note": "One dot per build: minutes from push to result", "unit": " min", "summary": "median", "zero": true, "each": "builds",
+  "groups": [ { "label": "Main branch", "values": [3.8,4.1,3.6,4.4,3.9,4.0,4.2,3.7,4.6,3.9,4.3,11.8,4.0,3.5,4.1,4.8,3.9,4.2,12.6,4.0,3.8,4.4,4.1,3.7,4.5,3.9,10.4,4.2] },
+              { "label": "Pull requests", "values": [4.9,5.2,4.6,5.8,5.1,4.8,6.2,5.0,5.5,4.7,5.3,5.9,5.0,4.9,6.4,5.2,5.6,4.8,5.1,5.4], "tone": "accent" } ],
+  "mark": { "group": "Main branch", "value": 12.6, "label": "12.6 min, cache miss" },
+  "source": "Invented example data" }

package/examples/charts/scatter.json

@@ -0,0 +1,6 @@
+{ "type": "scatter", "style": "report", "title": "Bigger pull requests wait longer for review",
+  "note": "One dot per merged pull request", "x": { "label": "Lines changed", "log": true }, "y": { "label": "Time to first review", "time": "hours", "zero": true },
+  "points": [ {"x":12,"y":1.5},{"x":30,"y":2.1},{"x":8,"y":0.6},{"x":45,"y":3.2},{"x":120,"y":5.5},{"x":260,"y":9.1},{"x":75,"y":2.8},
+              {"x":18,"y":1.1},{"x":540,"y":22.0,"label":"Search rewrite","tone":"accent"},{"x":95,"y":6.0},{"x":160,"y":4.2},{"x":22,"y":3.9},
+              {"x":64,"y":2.2},{"x":310,"y":12.5},{"x":40,"y":1.8},{"x":5,"y":0.4},{"x":210,"y":7.7},{"x":880,"y":30.5},{"x":15,"y":0.9},{"x":130,"y":3.6} ],
+  "source": "Invented example data" }

package/examples/charts/sequence.json

@@ -0,0 +1,67 @@
+{
+  "type": "sequence",
+  "title": "The shopper has an order number before the receipt is sent",
+  "participants": [
+    {
+      "id": "app",
+      "name": "Shop app",
+      "kind": "browser"
+    },
+    {
+      "id": "api",
+      "name": "Checkout API"
+    },
+    {
+      "id": "pay",
+      "name": "Card processor"
+    },
+    {
+      "id": "mail",
+      "name": "Email queue"
+    }
+  ],
+  "messages": [
+    {
+      "from": "app",
+      "to": "api",
+      "label": "Place order"
+    },
+    {
+      "from": "api",
+      "to": "api",
+      "label": "Check stock and price"
+    },
+    {
+      "from": "api",
+      "to": "pay",
+      "label": "Charge the card",
+      "tone": "accent"
+    },
+    {
+      "from": "pay",
+      "to": "api",
+      "label": "Approved or declined",
+      "reply": true,
+      "tone": "accent"
+    },
+    {
+      "from": "api",
+      "to": "app",
+      "label": "Order number",
+      "reply": true
+    },
+    {
+      "from": "api",
+      "to": "mail",
+      "label": "Send the receipt",
+      "note": "within a minute"
+    }
+  ],
+  "repeats": [
+    {
+      "from": 3,
+      "to": 4,
+      "label": "Up to 3 tries"
+    }
+  ]
+}

package/examples/charts/series-range.json

@@ -0,0 +1,6 @@
+{ "type": "series", "style": "report", "title": "The weekly pass rate dipped in week 6, beyond its usual range",
+  "note": "Share of test runs that passed, each week", "unit": "%", "zero": false, "range": "likely range (95%)",
+  "points": [ {"x":1,"y":91,"low":86,"high":94}, {"x":2,"y":93,"low":88,"high":96}, {"x":3,"y":90,"low":85,"high":94},
+              {"x":4,"y":92,"low":87,"high":95}, {"x":5,"y":91,"low":86,"high":95}, {"x":6,"y":79,"low":72,"high":85},
+              {"x":7,"y":89,"low":84,"high":93}, {"x":8,"y":92,"low":87,"high":95} ],
+  "mark": { "x": 6, "label": "79%, week 6" }, "source": "Invented example data" }

package/examples/charts/units.json

@@ -0,0 +1,4 @@
+{ "type": "units", "style": "report", "title": "11 of the 29 flagged days were real problems",
+  "note": "One square per day the monitor flagged in October", "total": 29,
+  "parts": [ { "label": "real problems", "count": 11 } ], "rest": "false alarms",
+  "source": "Invented example data" }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liggi/figkit",
-  "version": "0.3.0",
+  "version": "0.4.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

@@ -218,3 +218,59 @@ fig-bars .fb-sub { font-weight: 400; color: var(--soft); font-size: var(--small)
 .fig .hm-key { display: flex; flex-wrap: wrap; align-items: center; gap: 10px; font-size: var(--small); color: var(--muted); margin: 0 0 12px; }
 .fig .hm-key i { display: inline-block; width: 160px; height: 14px; border-radius: 3px; }
 .fig.phone .hm-key i { width: 84px; }
+
+/* ---------- sequence: who calls whom, in order (a spec of type "sequence") ---------- */
+.fig .sequence { position: relative; }
+.fig .sequence > svg { position: absolute; left: 0; top: 0; overflow: visible; }
+.fig .seq-lanes { position: relative; }
+.fig .seq-who { position: absolute; }
+.fig .seq-who { text-align: center; align-items: center; justify-content: center; }
+.fig.phone .seq-who { padding: 10px 8px; }
+.fig.phone .seq-who > h3 { font-size: var(--body); }
+/* The paper shows only behind the words themselves, line by line, so a line passing a label stops just at its text. */
+.fig .seq-msg { position: absolute; box-sizing: border-box; width: max-content; display: flex; gap: 10px; align-items: baseline; padding: 1px 6px; }
+.fig .seq-ink { background: var(--paper); box-decoration-break: clone; -webkit-box-decoration-break: clone; padding: 1px 0; }
+.fig .seq-n { font-size: var(--small); font-variant-numeric: tabular-nums; color: var(--soft); flex: 0 0 auto; min-width: 2ch; text-align: right; }
+.fig .seq-text { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
+.fig .seq-note { font-size: var(--small); color: var(--muted); }
+.fig .seq-msg.reply .seq-text { color: var(--muted); }
+.fig .seq-msg.accent .seq-text, .fig .seq-msg.accent .seq-n { color: var(--accent); }
+.fig .seq-msg.accent .seq-text { font-weight: 600; }
+.fig .seq-msg.accent .seq-note { font-weight: 400; }
+.fig .seq-frame-label { position: absolute; white-space: nowrap; background: var(--paper); padding: 0 8px; font-size: var(--small); font-weight: 600; color: var(--muted); }
+.fig .seq-lanes.tight .seq-who { padding: 8px 4px; }
+.fig .seq-lanes.tight .seq-who > h3 { font-size: var(--small); }
+
+/* ranges: what they are, said once under the reading line; on bars a line with end caps across the bar's end */
+.fig .range-key { display: flex; flex-wrap: wrap; column-gap: 28px; row-gap: 6px; margin: 2px 0 0; font-size: var(--small); color: var(--muted); }
+.fig .range-key > span { display: inline-flex; align-items: center; gap: 10px; }
+.fig .range-key i { flex: 0 0 auto; }
+.fig .range-key i.dash { width: 34px; height: 0; border-top: 2px dashed var(--ink); }
+.fig .range-key i.whisker { position: relative; width: 34px; height: 14px; border-left: 2px solid var(--ink); border-right: 2px solid var(--ink); }
+.fig .range-key i.whisker::after { content: ''; position: absolute; left: 0; right: 0; top: 6px; border-top: 2px solid var(--ink); }
+.fig .range-key i.median { width: 34px; height: 4px; border-radius: 2px; }
+.fig .range-key i.band { width: 34px; height: 14px; border-radius: 2px; background: var(--fill); opacity: .45; }
+fig-bars .fb-track { position: relative; }
+fig-bars .fb-range { --tone: var(--ink); position: absolute; top: 50%; height: 12px; margin-top: -6px; border-left: 2px solid var(--tone); border-right: 2px solid var(--tone); pointer-events: none; }
+fig-bars .fb-range::after { content: ''; position: absolute; left: 0; right: 0; top: 4.5px; border-top: 3px solid var(--tone); }
+fig-bars .fb-bar.dim { opacity: .4; }
+fig-bars .fb-val .fb-sub + .fb-sub { margin-left: 10px; }
+fig-bars .fb-label .fb-n { display: block; font-size: var(--small); color: var(--soft); }
+
+/* dots: the count of a single group, above its dots */
+.fig .dots-n { margin: 0 0 4px; font-size: var(--small); color: var(--muted); }
+
+/* units: one square per thing counted */
+.fig .units { display: flex; flex-direction: column; gap: 22px; }
+.fig .un-grid { display: grid; }
+.fig .un-grid i { width: var(--un); height: var(--un); border-radius: 4px; }
+.fig .un-grid i.empty, .fig .un-key i.empty { background: var(--hair); }
+.fig .un-key { display: flex; flex-wrap: wrap; column-gap: 28px; row-gap: 8px; font-size: var(--body); color: var(--muted); }
+.fig .un-key span { display: inline-flex; align-items: center; gap: 8px; }
+.fig .un-key i { width: 18px; height: 18px; border-radius: 3px; display: inline-block; }
+.fig .un-key b { color: var(--ink); font-weight: 600; font-variant-numeric: tabular-nums; }
+
+/* bars on a phone: the name and count above each bar, so the bar and its range get the full width */
+.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; }

package/runtime/fig.js

@@ -567,6 +567,13 @@
       for (const b of marks.slice(i + 1)) if (overlap(a.r, b.r) && !a.e.contains(b.e) && !b.e.contains(a.e)) P.push(`Chart labels overlap: "${a.e.textContent.trim()}" and "${b.e.textContent.trim()}".`);
     }
 
+    // Chart labels over dots: a label drawn across a dot hides the value it sits on.
+    const dots = [...R.querySelectorAll('.chart svg circle')].filter(visible).map(rectOf).map((r) => grow(r, -1.5));
+    for (const a of marks) {
+      const hit = dots.filter((d) => overlap(grow(a.r, -1), d)).length;
+      if (hit) P.push(`Chart label covers ${hit === 1 ? 'a dot' : hit + ' dots'}: "${a.e.textContent.trim()}".`);
+    }
+
     // 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()))))) {

package/viz/build.mjs

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const HOME = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
-const SOURCES = ['viz/draw.js', 'package.json'].map((f) => path.join(HOME, f));
+const SOURCES = [...fs.readdirSync(path.join(HOME, 'viz')).filter((f) => f.endsWith('.js')).map((f) => 'viz/' + f), 'package.json'].map((f) => path.join(HOME, f));
 const OUT = path.join(HOME, 'dist/viz.iife.js');
 
 const mtime = (f) => (fs.existsSync(f) ? fs.statSync(f).mtimeMs : 0);

package/viz/draw.js

@@ -1,5 +1,6 @@
 /* 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';
 const NS = 'http://www.w3.org/2000/svg';
 const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
 
@@ -79,21 +80,44 @@ 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) {
+  const top = max ?? Math.max(...bars.map((b) => Math.max(b.value, b.high ?? 0)));
   host.innerHTML = '';
   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', 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))`;
+  }
+}
+
+/** 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 ? `<span><i class="dash"></i>${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 +197,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 +213,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 +316,26 @@ 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', '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 === '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 === '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) {
@@ -311,9 +351,12 @@ export function drawSpec(spec, main) {
     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);
   };
   draw();
   return { chart, draw };
@@ -372,12 +415,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 +442,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 +471,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 });
@@ -474,3 +518,230 @@ export function drawHeatmap(host, spec) {
   key.style.marginLeft = labelW + 'px';
   host.prepend(key);
 }
+
+// ---------- 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);
+}