@liggi/figkit 0.2.0 → 0.4.0

package/viz/sequence.js

@@ -0,0 +1,171 @@
+/* The "sequence" spec drawn: participants across the top, each message a numbered step down the page. */
+const NS = 'http://www.w3.org/2000/svg';
+const esc = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+
+function svgEl(tag, attrs, parent) {
+  const el = document.createElementNS(NS, tag);
+  for (const [k, v] of Object.entries(attrs)) el.setAttribute(k, v);
+  parent.appendChild(el);
+  return el;
+}
+
+/**
+ * Participants side by side in boxes, a line down from each, and the messages in order: a solid arrow for a call, a
+ * dashed one for a reply, a loop for work a participant does itself. Each label sits on the paper above its arrow,
+ * numbered, so prose can say "step 4". Repeated steps sit in a dashed frame named at its top.
+ */
+export function drawSequence(spec, main) {
+  const phone = main.classList.contains('phone');
+  const host = document.createElement('div');
+  host.className = 'sequence';
+  main.appendChild(host);
+  const css = (n) => getComputedStyle(host).getPropertyValue(n).trim();
+  const ink = { line: css('--line'), soft: css('--soft'), accent: css('--accent'), hair: css('--hair'), muted: css('--muted') };
+
+  const lanes = document.createElement('div');
+  lanes.className = 'seq-lanes';
+  host.appendChild(lanes);
+  const svg = document.createElementNS(NS, 'svg');
+  host.prepend(svg);
+  const W = host.clientWidth, n = spec.participants.length;
+  const SEP = phone ? 12 : 24;
+  const boxes = spec.participants.map((p) => {
+    const box = document.createElement('div');
+    box.className = 'node seq-who' + (p.tone ? ' accent' : '');
+    box.id = 'who-' + p.id;
+    box.innerHTML = `<h3>${esc(p.name)}</h3>${p.kind ? `<p>${esc(p.kind)}</p>` : ''}`;
+    lanes.appendChild(box);
+    return box;
+  });
+  // Lanes share the width equally. When a name's longest word will not fit, lanes widen for the names that need it
+  // and narrow for the ones that don't; then the names drop a size; only then do the boxes alternate between two rows.
+  const set = (box, left, width) => Object.assign(box.style, { left: left + 'px', width: width + 'px' });
+  let edge = spec.participants.map((_, i) => (W / n) * i).concat(W);
+  const layout = () => boxes.forEach((b, i) => set(b, edge[i] + SEP / 2, edge[i + 1] - edge[i] - SEP));
+  const over = () => boxes.some((b) => b.scrollWidth > b.clientWidth + 1);
+  const fit = () => {
+    const need = boxes.map((b) => { b.style.width = 'min-content'; return b.offsetWidth + SEP; });
+    const spare = W - need.reduce((a, v) => a + v, 0);
+    if (spare < 0) return false;
+    edge = [0];
+    need.forEach((v) => edge.push(edge[edge.length - 1] + v + spare / n));
+    return true;
+  };
+  layout();
+  let stagger = false;
+  if (over()) {
+    if (!fit()) { lanes.classList.add('tight'); if (!fit()) { edge = spec.participants.map((_, i) => (W / n) * i).concat(W); stagger = n > 2; } }
+    layout();
+    if (stagger) {
+      boxes.forEach((b, i) => {
+        const lo = i > 0 ? (edge[i - 1] + edge[i]) / 2 + SEP / 2 : 0, hi = i < n - 1 ? (edge[i + 1] + edge[i + 2]) / 2 - SEP / 2 : W;
+        set(b, lo, hi - lo);
+      });
+    }
+  }
+  const x = {};
+  spec.participants.forEach((p, i) => { x[p.id] = (edge[i] + edge[i + 1]) / 2; });
+  const L = Math.min(...spec.participants.map((_, i) => edge[i + 1] - edge[i]));
+  const tall = Math.max(...boxes.map((b) => b.offsetHeight));
+  const ROW2 = tall + (phone ? 14 : 18);
+  const bottom = {};
+  boxes.forEach((b, i) => {
+    const down = stagger && i % 2 === 1;
+    Object.assign(b.style, { height: tall + 'px', top: (down ? ROW2 : 0) + 'px' });
+    bottom[spec.participants[i].id] = (down ? ROW2 : 0) + tall;
+  });
+  const top = Math.max(...Object.values(bottom));
+  lanes.style.height = top + 'px';
+  const GAP = phone ? 20 : 24, LIFT = 8, LOOP = phone ? 26 : 32, HEAD = 10;
+  const reps = spec.repeats ?? [];
+  const frames = [];
+  let y = top + (phone ? 26 : 30);
+  const label = (m, i) => {
+    const el = document.createElement('div');
+    el.className = 'seq-msg' + (m.reply ? ' reply' : '') + (m.tone ? ' accent' : '');
+    el.innerHTML = `<span class="seq-n"><span class="seq-ink">${i + 1}</span></span><span class="seq-text"><span class="seq-ink">${esc(m.label)}</span>${m.note ? `<span class="seq-note"><span class="seq-ink">${esc(m.note)}</span></span>` : ''}</span>`;
+    host.appendChild(el);
+    return el;
+  };
+  const place = (el, maxW) => {
+    el.style.maxWidth = Math.max(80, Math.floor(maxW)) + 'px';
+    el.style.left = '0px';
+    return el.offsetWidth;
+  };
+
+  spec.messages.forEach((m, i) => {
+    const rep = reps.find((r) => r.from === i + 1);
+    if (rep) {
+      const tab = document.createElement('div');
+      tab.className = 'seq-frame-label';
+      tab.textContent = rep.label;
+      host.appendChild(tab);
+      // The frame covers only the lanes its steps touch, edge to edge between lines, widened for any label past them.
+      const idx = spec.messages.slice(rep.from - 1, rep.to).flatMap((q) => [q.from, q.to]).map((id) => spec.participants.findIndex((p) => p.id === id));
+      tab.style.top = y + 'px';
+      frames.push({ rep, tab, top: y + tab.offsetHeight / 2, lo: x[spec.participants[Math.min(...idx)].id], hi: x[spec.participants[Math.max(...idx)].id], labels: [] });
+      y += tab.offsetHeight + 10;
+    }
+    const el = label(m, i);
+    const color = m.tone ? ink.accent : m.reply ? ink.soft : ink.line;
+    if (m.from === m.to) {
+      // Work a participant does itself: a loop out to the side of its line, the label beside the loop.
+      const lx = x[m.from];
+      const roomRight = W - (lx + LOOP + 14), roomLeft = lx - LOOP - 14;
+      const right = roomRight >= Math.min(roomLeft, 260) || roomRight >= 200;
+      const ids = spec.participants.map((p) => x[p.id]);
+      const next = right ? Math.min(...ids.filter((v) => v > lx), Infinity) - (lx + LOOP + 14) - 10 : (lx - LOOP - 14) - Math.max(...ids.filter((v) => v < lx), -Infinity) - 10;
+      const w = place(el, Math.min(right ? roomRight : roomLeft, next >= (phone ? 130 : 150) ? next : Infinity));
+      const h = el.offsetHeight;
+      const loopH = Math.max(h, 30);
+      el.style.left = (right ? lx + LOOP + 14 : lx - LOOP - 14 - w) + 'px';
+      el.style.top = y + (loopH - h) / 2 + 'px';
+      const side = right ? 1 : -1, x1 = lx + side * LOOP;
+      svgEl('path', { d: `M${lx},${y} H${x1} V${y + loopH} H${lx + side * (HEAD + 2)}`, fill: 'none', stroke: color, 'stroke-width': 2.25, 'stroke-linejoin': 'round' }, svg);
+      head(lx, y + loopH, -side, color);
+      y += loopH + GAP;
+    } else {
+      const a = x[m.from], b = x[m.to], dir = Math.sign(b - a);
+      // A label starts just inside the arrow's left end, the same for every arrow, and wraps to stay between the
+      // arrow's two lines. Where that is too narrow to read, it reaches at most halfway to the next line out.
+      const lo = Math.min(a, b), hi = Math.max(a, b), MIN = phone ? 150 : 180;
+      const next = Math.min(...Object.values(x).filter((v) => v > hi), Infinity);
+      const inside = hi - lo - 14 >= (phone ? 160 : 140);
+      const reach = inside ? hi - lo - 14 : Math.max(MIN, (next === Infinity ? W : (hi + next) / 2 - 6) - (lo + 6));
+      const w = place(el, Math.min(W, reach));
+      const left = Math.max(0, Math.min(W - w, lo + 6));
+      el.style.left = left + 'px';
+      el.style.top = y + 'px';
+      const ay = y + el.offsetHeight + LIFT;
+      svgEl('line', { x1: a, y1: ay, x2: b - dir * (HEAD + 1), y2: ay, stroke: color, 'stroke-width': 2.25, ...(m.reply ? { 'stroke-dasharray': '7 6' } : {}) }, svg);
+      head(b, ay, dir, color);
+      y = ay + GAP;
+    }
+    for (const f of frames) if (i + 1 >= f.rep.from && i + 1 <= f.rep.to) f.labels.push(el);
+    const open = frames.find((f) => f.rep.to === i + 1);
+    if (open) { open.bottom = y - GAP + 14; y += 14; }
+  });
+  const H = y - GAP + 24;
+  host.style.height = H + 'px';
+  svg.setAttribute('width', W); svg.setAttribute('height', H);
+  // Lines down from each participant and the frames round repeated steps, behind the arrows.
+  const back = document.createElementNS(NS, 'g');
+  svg.prepend(back);
+  // Every frame keeps the same inset outside its first and last lines: the widest any of them needs.
+  let pad = Math.min(L / 2 - 4, 40);
+  for (const f of frames) for (const el of f.labels) pad = Math.max(pad, f.lo - el.offsetLeft + 8, el.offsetLeft + el.offsetWidth + 8 - f.hi);
+  for (const f of frames) {
+    // The same inset outside the first and last lines, wide enough for every label inside.
+    f.left = Math.max(1, f.lo - pad); f.right = Math.min(W - 1, f.hi + pad);
+    // The name starts just past the first line inside the frame, so it covers no line.
+    f.tab.style.left = Math.max(f.left + 14, Math.min(f.lo + 6, f.right - 14 - f.tab.offsetWidth)) + 'px';
+  }
+  for (const f of frames) svgEl('rect', { x: f.left, y: f.top, width: f.right - f.left, height: f.bottom - f.top, rx: 10, fill: 'none', stroke: ink.muted, 'stroke-opacity': 0.55, 'stroke-width': 1.5, 'stroke-dasharray': '6 6' }, back);
+  for (const p of spec.participants) svgEl('line', { x1: x[p.id], y1: bottom[p.id], x2: x[p.id], y2: H, stroke: ink.hair, 'stroke-width': 2 }, back);
+
+  function head(tipX, tipY, dir, color) {
+    const back = tipX - dir * (HEAD + 2);
+    svgEl('path', { d: `M${tipX - dir * 1},${tipY} L${back},${tipY - 6.5} L${back},${tipY + 6.5} Z`, fill: color }, svg);
+  }
+  return host;
+}

package/viz/spec.js

@@ -1,5 +1,6 @@
 /* The named visualisations: one Zod schema per type. An agent picks a type and gives data; it never writes markup. */
 import { z } from 'zod';
+import { sequenceShape, sequenceChecks } from './sequence-spec.js';
 
 const TONE = z.enum(['accent', 'second', 'good', 'bad']);
 const label = z.string({ error: 'needs a label' }).trim().min(1, 'needs a label').max(40, 'keep labels to 40 characters');
@@ -10,8 +11,15 @@ const common = {
   note: z.string().trim().max(160, 'keep the note to 160 characters').optional(),
   unit: z.string().max(8).optional(),
   source: z.string().trim().max(120).optional(),
+  style: z.enum(['report'], { error: 'style: "report" for a light chart that sits in a page, or leave it out' }).optional(),
 };
 const value = z.number({ error: 'must be a number' }).finite();
+/** What the low-to-high ranges are, printed beside a drawn range: required whenever a chart has ranges. */
+const range = z.string().trim().min(1).max(40, 'keep the range description to 40 characters, e.g. "95% interval"').optional();
+const bound = z.number({ error: 'must be a number' }).finite().optional();
+/** The plural noun one counted item is, so a count reads "14 runs" rather than "n = 14". */
+const each = z.string().trim().min(1).max(16, 'keep it to 16 characters, a plural noun such as "runs"').optional();
+const sample = z.number({ error: 'the sample size, a whole number' }).int('the sample size, a whole number').positive('must be more than 0').optional();
 
 /** Parts of a whole, as one bar cut into segments. */
 export const SplitSpec = z.object({
@@ -36,9 +44,14 @@ export const BarsSpec = z.object({
     tone: TONE.optional(),
     show: z.string().max(24).optional(),
     note: z.string().trim().max(40).optional(),
+    low: bound,
+    high: bound,
+    n: sample,
   }).strict()).min(1).max(12, 'at most 12 bars'),
+  range,
+  each,
 }).strict()
-  .refine((s) => s.max === undefined || s.bars.every((b) => b.value <= s.max), { message: 'every value must be at most max', path: ['max'] });
+  .refine((s) => s.max === undefined || s.bars.every((b) => Math.max(b.value, b.high ?? 0) <= s.max), { message: 'every value and every high must be at most max', path: ['max'] });
 
 const side = z.object({
   label: z.string({ error: 'needs a label: when it was' }).trim().min(1, 'needs a label: when it was').max(24, 'keep it to 24 characters'),
@@ -79,11 +92,136 @@ export const DumbbellSpec = z.object({
 export const SeriesSpec = z.object({
   type: z.literal('series'),
   ...common,
-  points: z.array(z.object({ x: point, y: value }).strict()).min(3, 'a series needs at least 3 points').max(2000),
+  points: z.array(z.object({ x: point, y: value, low: bound, high: bound }).strict()).min(3, 'a series needs at least 3 points').max(2000),
+  range,
+  ref: z.object({ y: value, label: z.string().trim().min(1).max(32, 'keep the reference label to 32 characters') }, { error: 'ref: { "y", "label" }, a level to compare the line with' }).strict().optional(),
   mark: z.object({ x: point, label: z.string().trim().min(1).max(32, 'keep the mark label to 32 characters') }, { error: 'required: the one point to notice, { "x", "label" }' }).strict(),
   zero: z.boolean().optional(),
 }).strict();
 
+
+const seriesName = label.max(28, 'keep series names to 28 characters');
+const TONE_ONE = z.enum(['accent', 'good', 'bad'], { error: 'tone: "accent", or "good" or "bad" when it is a result' });
+
+/** Bars in groups: each group a few bars, one per series, read across the groups. */
+const groupRow = z.object({
+  label: label.max(32, 'keep group labels to 32 characters'),
+  values: z.array(value.nonnegative('must be 0 or more: bars start at zero')),
+}).strict();
+const groupsData = {
+  series: z.array(seriesName).min(2, 'at least 2 series; one bar per group is a "bars" chart').max(4, 'at most 4 series; more is too many bars to read'),
+  groups: z.array(groupRow).min(2, 'at least 2 groups; one group is a "bars" chart').max(6, 'at most 6 groups'),
+  accent: z.object({
+    series: z.string().optional(),
+    group: z.string().optional(),
+    tone: TONE_ONE.optional(),
+  }, { error: 'required: what to notice, { "series" } for a whole series, or { "series", "group" } for one bar' }).strict(),
+  max: z.number().positive().optional(),
+};
+export const GroupsSpec = z.object({ type: z.literal('groups'), ...common, ...groupsData }).strict();
+
+/** Two or three lines on one axis, each named at its end; one is the line to notice. */
+const linePoint = z.object({ x: point, y: value, low: bound, high: bound }).strict();
+const linesData = {
+  series: z.array(z.object({
+    label: seriesName,
+    points: z.array(linePoint).min(3, 'a line needs at least 3 points').max(2000),
+  }).strict()).min(2, 'at least 2 lines; one line is a "series" chart').max(3, 'at most 3 lines on one axis; more is small multiples ("panels")'),
+  accent: z.string({ error: 'required: the label of the line to notice' }),
+  mark: z.object({ x: point, label: z.string().trim().min(1).max(32, 'keep the mark label to 32 characters') }).strict().optional(),
+  zero: z.boolean().optional(),
+  range,
+  xTicks: z.array(z.object({ x: point, label: z.string().trim().min(1).max(12, 'keep tick labels to 12 characters') }).strict()).min(2).max(8, 'at most 8 ticks').optional(),
+};
+export const LinesSpec = z.object({ type: z.literal('lines'), ...common, ...linesData }).strict();
+
+/** The same chart drawn once per part, side by side on one scale. */
+export const PanelsSpec = z.object({
+  type: z.literal('panels'),
+  ...common,
+  chart: z.enum(['groups', 'lines'], { error: 'chart: "groups" or "lines", the chart each panel draws' }),
+  series: groupsData.series.optional(),
+  accent: z.union([z.string(), groupsData.accent]),
+  max: z.number().positive().optional(),
+  zero: z.boolean().optional(),
+  range,
+  xTicks: linesData.xTicks,
+  panels: z.array(z.object({
+    label: label.max(32, 'keep panel labels to 32 characters'),
+    groups: z.array(groupRow).min(1).max(6, 'at most 6 groups').optional(),
+    series: linesData.series.optional(),
+  }).strict()).min(2, 'at least 2 panels').max(4, 'at most 4 panels; more is two figures'),
+}).strict();
+
+/** A grid of values coloured from pale to strong: where something is high or low across two dimensions. */
+const axisLabel = z.union([z.string().trim().min(1).max(16, 'keep row and column labels to 16 characters'), z.number().finite()]);
+export const HeatmapSpec = z.object({
+  type: z.literal('heatmap'),
+  ...common,
+  note: z.string({ error: 'required: what the colour counts, e.g. "People active per hour"' }).trim().min(1).max(160, 'keep the note to 160 characters'),
+  rows: z.array(axisLabel).min(2).max(12, 'at most 12 rows'),
+  columns: z.array(axisLabel).min(2).max(31, 'at most 31 columns'),
+  values: z.array(z.array(value)),
+  mark: z.object({ row: axisLabel, column: axisLabel, label: z.string().trim().min(1).max(32, 'keep the mark label to 32 characters') }).strict().optional(),
+}).strict();
+
+/** Every value as a dot: one row per group, the dots stacked where they would overlap, so none hides another. */
+export const DotsSpec = z.object({
+  type: z.literal('dots'),
+  ...common,
+  note: z.string({ error: 'required: what each dot is and what it measures, e.g. "One dot per run: minutes to finish"' }).trim().min(1).max(160, 'keep the note to 160 characters'),
+  groups: z.array(z.object({
+    label: label.max(28, 'keep group labels to 28 characters'),
+    values: z.array(value).min(1).max(300, 'at most 300 dots in a group; more is a distribution, not dots to look at one by one'),
+    tone: TONE.optional(),
+  }).strict()).min(1).max(6, 'at most 6 groups'),
+  each,
+  summary: z.enum(['median', 'mean'], { error: 'summary: "median" or "mean", drawn as a line across each group' }).optional(),
+  mark: z.object({ group: z.string(), value, label: z.string().trim().min(1).max(32, 'keep the mark label to 32 characters') }).strict().optional(),
+  zero: z.boolean().optional(),
+  max: z.number().finite().optional(),
+}).strict();
+
+/** Two measures against each other, a dot per thing measured. Both axes say what they measure. */
+const axis = z.object({
+  label: z.string({ error: 'required: what this axis measures' }).trim().min(1, 'required: what this axis measures').max(40, 'keep axis labels to 40 characters'),
+  unit: z.string().max(8).optional(),
+  log: z.boolean().optional(),
+  zero: z.boolean().optional(),
+  time: z.enum(['seconds', 'minutes', 'hours', 'days'], { error: 'time: "seconds", "minutes", "hours" or "days", the unit the values are in; ticks then read 1 min, 1 h, 1 day' }).optional(),
+}, { error: 'required: { "label" } saying what this axis measures' }).strict();
+export const ScatterSpec = z.object({
+  type: z.literal('scatter'),
+  title: common.title,
+  note: z.string({ error: 'required: what each dot is, e.g. "One dot per merged pull request"' }).trim().min(1).max(160, 'keep the note to 160 characters'),
+  source: common.source,
+  style: common.style,
+  x: axis,
+  y: axis,
+  medians: z.boolean().optional(),
+  points: z.array(z.object({
+    x: value, y: value,
+    label: z.string().trim().min(1).max(32, 'keep point labels to 32 characters').optional(),
+    tone: TONE.optional(),
+  }).strict()).min(3, 'at least 3 points').max(1000, 'at most 1000 points'),
+}).strict();
+
+/** A small count made concrete: one square per thing counted, the ones that matter filled. */
+export const UnitsSpec = z.object({
+  type: z.literal('units'),
+  title: common.title,
+  note: common.note,
+  source: common.source,
+  style: common.style,
+  total: z.number({ error: 'how many things there are, a whole number' }).int('a whole number; units are things, not fractions').min(2).max(100, 'at most 100 units; more cannot be counted by eye, so use a "split" bar of the shares'),
+  parts: z.array(z.object({
+    label: label.max(32, 'keep part labels to 32 characters'),
+    count: z.number({ error: 'a whole number' }).int('a whole number; units are things, not fractions').positive('more than 0'),
+    tone: TONE.optional(),
+  }).strict()).min(1).max(3, 'at most 3 filled parts; the rest are the empty squares'),
+  rest: label.max(32, 'keep the rest label to 32 characters'),
+}).strict();
+
 const slug = z.string({ error: 'needs an id, e.g. "order"' }).regex(/^[a-z][a-z0-9-]{0,23}$/, 'ids are short lowercase words, e.g. "order" or "order-line"');
 
 /**
@@ -95,6 +233,7 @@ export const EntitiesSpec = z.object({
   title,
   note: common.note,
   source: common.source,
+  style: common.style,
   records: z.array(z.object({
     id: slug,
     name: label.max(32, 'keep record names to 32 characters'),
@@ -111,19 +250,137 @@ export const EntitiesSpec = z.object({
   }).strict()).min(1, 'at least 1 reference').max(8, 'at most 8 references; more is two figures, not a reference left out'),
 }).strict();
 
-export const Spec = z.discriminatedUnion('type', [SplitSpec, BarsSpec, BeforeAfterSpec, DumbbellSpec, SeriesSpec, EntitiesSpec]);
-export const TYPES = { split: SplitSpec, bars: BarsSpec, 'before-after': BeforeAfterSpec, dumbbell: DumbbellSpec, series: SeriesSpec, entities: EntitiesSpec };
+/** Who calls whom, in order: participants side by side and numbered messages between them. */
+export const SequenceSpec = z.object({ type: z.literal('sequence'), title, note: common.note, source: common.source, style: common.style, ...sequenceShape }).strict();
+
+export const Spec = z.discriminatedUnion('type', [SplitSpec, BarsSpec, BeforeAfterSpec, DumbbellSpec, SeriesSpec, EntitiesSpec, GroupsSpec, LinesSpec, PanelsSpec, HeatmapSpec, DotsSpec, ScatterSpec, UnitsSpec, SequenceSpec]);
+export const TYPES = { split: SplitSpec, bars: BarsSpec, 'before-after': BeforeAfterSpec, dumbbell: DumbbellSpec, series: SeriesSpec, entities: EntitiesSpec, groups: GroupsSpec, lines: LinesSpec, panels: PanelsSpec, heatmap: HeatmapSpec, dots: DotsSpec, scatter: ScatterSpec, units: UnitsSpec, sequence: SequenceSpec };
 
-const items = (s) => s.parts ?? s.bars ?? s.rows ?? s.records ?? (s.after ? [s.after] : []);
+const items = (s) => s.parts ?? s.bars ?? s.rows ?? s.records ?? s.messages ?? (s.type === 'scatter' ? s.points : s.type === 'dots' ? s.groups : (s.after ? [s.after] : []));
 const kind = (v) => (typeof v === 'number' ? 'number' : 'date');
 
+
+/**
+ * Ranges: a low and a high together, around their value, on every item or none (a value with no range among ones
+ * with ranges reads as certain), and said what they are. `of` gives each item's value.
+ */
+function rangeChecks(items, of, desc, at) {
+  const out = [];
+  const has = items.map((x) => x.low !== undefined || x.high !== undefined);
+  items.forEach((x, i) => {
+    if (has[i] && (x.low === undefined || x.high === undefined)) out.push(`${at}[${i}]: a range needs both "low" and "high"`);
+    else if (has[i] && !(x.low <= of(x) && of(x) <= x.high)) out.push(`${at}[${i}]: the range ${x.low} to ${x.high} does not contain its value ${of(x)}; low ≤ value ≤ high`);
+  });
+  if (has.some(Boolean) && !has.every(Boolean)) out.push(`${at}: give every item a range or none; one without reads as certain`);
+  if (has.some(Boolean) && !desc) out.push('range: required with ranges: say what they are, e.g. "95% interval" or "lowest to highest run"');
+  if (!has.some(Boolean) && desc) out.push('range: there are no ranges to describe; give items "low" and "high", or leave "range" out');
+  return out;
+}
+
+function groupsChecks(s, at = '') {
+  const out = [];
+  s.groups.forEach((g, i) => { if (g.values.length !== s.series.length) out.push(`${at}groups[${i}].values: one value per series, ${s.series.length}, not ${g.values.length}`); });
+  if (s.accent.series !== undefined && !s.series.includes(s.accent.series)) out.push(`accent.series: must be one of ${s.series.map((x) => `"${x}"`).join(', ')}`);
+  if (s.accent.group !== undefined && !s.groups.some((g) => g.label === s.accent.group)) out.push(`${at}accent.group: must be the label of one of the groups`);
+  if (s.accent.series === undefined && s.accent.group === undefined) out.push('accent: name the series to notice, or a series and a group for one bar');
+  if (s.max !== undefined && s.groups.some((g) => g.values.some((v) => v > s.max))) out.push('max: every value must be at most max');
+  return out;
+}
+function linesChecks(s, at = '') {
+  const out = [];
+  const xs = s.series.flatMap((l) => l.points.map((p) => p.x));
+  if (new Set(xs.map(kind)).size > 1) out.push(`${at}series: x values must be all numbers or all dates, not both`);
+  const t = (x) => (typeof x === 'number' ? x : Date.parse(x));
+  s.series.forEach((l, i) => { for (let j = 1; j < l.points.length; j++) if (t(l.points[j].x) <= t(l.points[j - 1].x)) { out.push(`${at}series[${i}].points[${j}].x: points must be in order of x`); break; } });
+  const names = s.series.map((l) => l.label);
+  if (new Set(names).size < names.length) out.push(`${at}series: two lines have the same label`);
+  if (!names.includes(s.accent)) out.push(`accent: must be the label of one of the lines, ${names.map((x) => `"${x}"`).join(', ')}`);
+  if (s.mark) { const line = s.series.find((l) => l.label === s.accent); if (line && !line.points.some((p) => t(p.x) === t(s.mark.x))) out.push(`mark.x: must be the x of one of the points on the "${s.accent}" line`); }
+  const ranged = s.series.filter((l) => l.points.some((p) => p.low !== undefined || p.high !== undefined));
+  s.series.forEach((l, i) => { if (ranged.includes(l)) out.push(...rangeChecks(l.points, (p) => p.y, s.range ?? 'given', `${at}series[${i}].points`)); });
+  if (!ranged.length && s.range) out.push('range: there are no ranges to describe; give points "low" and "high", or leave "range" out');
+  if (ranged.length && !s.range) out.push('range: required with ranges: say what they are, e.g. "95% interval"');
+  return out;
+}
+
 /** Rules that span fields: x values of one kind, in order, and a mark that is one of the points. */
 function crossChecks(s) {
+  if (s.type === 'sequence') return sequenceChecks(s);
+  if (s.type === 'groups') return groupsChecks(s);
+  if (s.type === 'lines') return linesChecks(s);
+  if (s.type === 'panels') {
+    const out = [];
+    s.panels.forEach((p, i) => {
+      const at = `panels[${i}].`;
+      if (s.chart === 'groups') {
+        if (!p.groups || p.series) { out.push(`${at}: a groups panel has "groups" and no "series"`); return; }
+        if (!s.series) { out.push('series: a groups chart names its series once, at the top'); return; }
+        if (typeof s.accent !== 'object') { out.push('accent: { "series" } or { "series", "group" } for a groups chart'); return; }
+        out.push(...groupsChecks({ series: s.series, groups: p.groups, accent: { ...s.accent, group: undefined }, max: s.max }, at));
+        if (s.accent.group !== undefined && !s.panels.some((q) => q.groups?.some((g) => g.label === s.accent.group))) out.push('accent.group: must be the label of a group in a panel');
+      } else {
+        if (!p.series || p.groups) { out.push(`${at}: a lines panel has "series" and no "groups"`); return; }
+        if (typeof s.accent !== 'string') { out.push('accent: the label of the line to notice, the same in every panel'); return; }
+        out.push(...linesChecks({ series: p.series, accent: s.accent, range: s.range }, at));
+        const names = (q) => q.series.map((l) => l.label).join('|');
+        if (names(p) !== names(s.panels[0])) out.push(`${at}series: every panel has the same lines, in the same order, so a line is one colour throughout`);
+      }
+    });
+    return [...new Set(out)];
+  }
+  if (s.type === 'heatmap') {
+    const out = [];
+    if (s.values.length !== s.rows.length) out.push(`values: one row of values per row label, ${s.rows.length}, not ${s.values.length}`);
+    s.values.forEach((r, i) => { if (r.length !== s.columns.length) out.push(`values[${i}]: one value per column, ${s.columns.length}, not ${r.length}`); });
+    if (s.mark && !s.rows.includes(s.mark.row)) out.push('mark.row: must be one of the row labels');
+    if (s.mark && !s.columns.includes(s.mark.column)) out.push('mark.column: must be one of the column labels');
+    return out;
+  }
   if (s.type === 'dumbbell') {
     const kinds = new Set(s.rows.flatMap((r) => [kind(r.from), kind(r.to)]));
     if (kinds.size > 1) return ['rows: use all numbers or all dates, not both'];
   }
+  if (s.type === 'bars') {
+    const out = rangeChecks(s.bars, (b) => b.value, s.range, 'bars');
+    s.bars.forEach((b, i) => { if (b.low !== undefined && b.low < 0) out.push(`bars[${i}].low: bars start at zero, so the range cannot go below it`); });
+    const ns = s.bars.map((b) => b.n !== undefined);
+    if (ns.some(Boolean) && !ns.every(Boolean)) out.push('bars: give every bar an "n" or none');
+    s.bars.forEach((b, i) => { if (b.n !== undefined && b.show === undefined && s.unit === '%' && b.n < 10) out.push(`bars[${i}].n: a percentage of ${b.n} things says more than it knows; show it as a count with "show", e.g. "${Math.round((b.value / 100) * b.n)} of ${b.n}", or draw a "units" chart`); });
+    return out;
+  }
+  if (s.type === 'dots') {
+    const out = [];
+    const names = s.groups.map((g) => g.label);
+    if (new Set(names).size < names.length) out.push('groups: two groups have the same label');
+    if (s.groups.reduce((a, g) => a + g.values.length, 0) > 600) out.push('groups: at most 600 dots in all');
+    if (s.mark) {
+      const g = s.groups.find((x) => x.label === s.mark.group);
+      if (!g) out.push(`mark.group: must be one of ${names.map((x) => `"${x}"`).join(', ')}`);
+      else if (!g.values.includes(s.mark.value)) out.push(`mark.value: must be one of the values in "${g.label}"`);
+    }
+    if (s.max !== undefined && s.groups.some((g) => g.values.some((v) => v > s.max))) out.push('max: every value must be at most max');
+    if (s.zero && s.groups.some((g) => g.values.some((v) => v < 0))) out.push('zero: an axis from zero cannot show values below it');
+    return out;
+  }
+  if (s.type === 'scatter') {
+    const out = [];
+    for (const k of ['x', 'y']) {
+      if (s[k].log && s.points.some((p) => p[k] <= 0)) out.push(`${k}.log: a log axis needs every ${k} above 0`);
+      if (s[k].log && s[k].zero) out.push(`${k}: a log axis has no zero; leave out "zero"`);
+    }
+    if (s.points.filter((p) => p.label).length > 5) out.push('points: label at most 5 points; the title is about one or two');
+    for (const k of ['x', 'y']) if (s[k].time && s[k].unit) out.push(`${k}: a time axis writes its own units (1 min, 1 h); leave out "unit"`);
+    return out;
+  }
+  if (s.type === 'units') {
+    const filled = s.parts.reduce((a, p) => a + p.count, 0);
+    if (filled > s.total) return [`parts: the counts add up to ${filled}, more than the total of ${s.total}`];
+    if (filled === s.total) return [`parts: the counts fill all ${s.total}; "rest" names the empty squares, so at least one must be left. For all of them, say so in the title`];
+    return [];
+  }
   if (s.type === 'series') {
+    const ranged = rangeChecks(s.points, (p) => p.y, s.range, 'points');
+    if (ranged.length) return ranged;
     const kinds = new Set(s.points.map((p) => kind(p.x)));
     if (kinds.size > 1) return ['points: x values must be all numbers or all dates, not both'];
     const at = (x) => (typeof x === 'number' ? x : Date.parse(x));