@liggi/figkit 0.2.0 → 0.4.0

package/GUIDE.md

@@ -5,7 +5,7 @@ work out coordinates or text widths: boxes size to their text, arrows route them
 measure the real result.
 
 ```
-npx figkit figure.html [--out figure.png]
+npx @liggi/figkit figure.html [--out figure.png]
 ```
 
 The file is just the `<main>` below; no doctype or `<head>` needed. Without `--out` the PNG goes to a temporary folder; the command prints where.
@@ -28,6 +28,8 @@ the images and look, then embed the PNG: `![what it shows](/abs/path.png)`.
 A question about structure ("what are the entities?", "where does X live?", "how do these relate?", "what loads
 what?", "walk me through it") is answered with a picture first, not with numbered steps.
 
+- "What happens when…?", "walk me through a run" and "who calls whom?" are a `sequence` spec (below): the steps in
+  order between the parts, not a numbered list or a table of steps.
 - "What are the entities and how do they relate?" is an `entities` spec (below), not boxes and arrows in HTML. It
   draws references: which record holds a pointer to which. The order work happens in (approve, then label, then
   train) is not a reference; it goes in prose, a list or a separate flow. A record that creates others still points
@@ -46,12 +48,12 @@ what?", "walk me through it") is answered with a picture first, not with numbere
 
 ## Charts and entities from a spec
 
-When the whole figure is one chart or one entities picture of a type below, write a JSON spec instead of HTML. You give the data; figkit
+When the whole figure is one chart, one entities picture or one sequence of a type below, write a JSON spec instead of HTML. You give the data; figkit
 does the layout, colours and labels. Use HTML (the rest of this guide) for anything else, including a chart that sits
 beside boxes or arrows.
 
 ```
-npx figkit chart.json [--out chart.png]
+npx @liggi/figkit chart.json [--out chart.png]
 ```
 
 A spec that breaks a rule is refused with one line per problem; fix them and run it again. Then look at the images
@@ -105,6 +107,128 @@ mark's `x` must be one of them. The y axis starts at zero unless `"zero": false`
   "mark": { "x": "2026-10-14", "label": "212, launch day" } }
 ```
 
+`groups`: a few things measured for each of 2 to 6 groups, 2 to 4 series, one bar per series in each group, all
+from zero. Use it when the point is a difference that shows in some groups and not others (before and after, one
+segment against another); for one number per thing, use `bars`. Each group gets a heading and each bar its series
+name and number, so there is no legend and no axis. `accent` is required: `{ "series" }` colours that series in every
+group, `{ "series", "group" }` colours one bar; `"tone": "bad"` or `"good"` when the bar is a result.
+
+```json
+{ "type": "groups", "title": "Only the new carrier got slower in December",
+  "note": "Median days from dispatch to doorstep", "unit": " days",
+  "series": ["Old carrier", "New carrier"],
+  "groups": [ { "label": "November", "values": [2.2, 2.1] }, { "label": "December", "values": [2.4, 3.6] } ],
+  "accent": { "series": "New carrier", "group": "December", "tone": "bad" } }
+```
+
+`lines`: 2 or 3 lines on one axis, each named at its right end in its own colour. `accent` (required) names the
+line the title is about; the others are grey. `mark` labels one point on the accent line. `xTicks` sets the axis
+labels, e.g. hours as 12am, 6am, 12pm, 6pm, rather than 0 to 23. More than 3 lines is `panels`.
+
+```json
+{ "type": "lines", "title": "Weekday orders peak at noon", "note": "Orders per hour",
+  "series": [ { "label": "Weekdays", "points": [ { "x": 0, "y": 3 }, { "x": 12, "y": 30 }, { "x": 23, "y": 4 } ] },
+              { "label": "Weekends", "points": [ { "x": 0, "y": 4 }, { "x": 12, "y": 22 }, { "x": 23, "y": 6 } ] } ],
+  "accent": "Weekdays", "mark": { "x": 12, "label": "30 at noon" },
+  "xTicks": [ { "x": 0, "label": "12am" }, { "x": 12, "label": "12pm" } ] }
+```
+
+`panels`: small multiples, the same `groups` or `lines` chart drawn for 2 to 4 parts side by side, on one shared
+scale so the panels compare; stacked on a phone. `chart` says which. For `groups`, `series` and `accent` are given once
+at the top and each panel has its `groups`; for `lines`, `accent` is the line's label and every panel has the same
+lines in the same order. Use it when one chart would need more than 3 lines or 4 series, or the parts measure
+different things on the same scale.
+
+```json
+{ "type": "panels", "chart": "groups", "title": "The cheaper plan answers almost as fast as the premium one",
+  "note": "Share of tickets answered within an hour", "unit": "%", "max": 100,
+  "series": ["Basic", "Standard", "Premium"], "accent": { "series": "Standard" },
+  "panels": [ { "label": "Email", "groups": [ { "label": "Weekdays", "values": [61, 84, 89] } ] },
+              { "label": "Chat", "groups": [ { "label": "Weekdays", "values": [72, 91, 94] } ] } ] }
+```
+
+`heatmap`: a grid of values over two dimensions (day by hour, team by week), coloured from pale to dark blue: darker
+is always more. Up to 12 `rows` and 31 `columns`; `values` is one array per row. `note` (required) says what the
+colour counts, and the scale is drawn above the grid. Here the colour is the measure, so the one-accent rule moves:
+`mark` outlines the one cell to notice in the accent colour and names it beside the scale. Cells show their numbers
+when there is room. Columns label themselves at even steps, so give hours as "12am", "1am", … and they read 12am,
+6am, 12pm, 6pm.
+
+```json
+{ "type": "heatmap", "title": "The help desk is busiest midweek mornings", "note": "Tickets opened per hour",
+  "rows": ["Mon", "Tue", "Wed"], "columns": ["9am", "10am", "11am", "12pm"],
+  "values": [ [22, 25, 27, 28], [23, 26, 29, 30], [24, 27, 30, 32] ],
+  "mark": { "row": "Wed", "column": "12pm", "label": "Busiest: Wed noon" } }
+```
+
+### How sure a number is
+
+Most numbers are counted from a sample: 71% of 75 days is not 71% of 7,500. When the reader will compare such
+numbers, draw how sure each one is.
+
+Ranges on `bars`, `series` and `lines`: give each bar or point a `low` and a `high` around its value, and say once
+in `range` what they are, in the reader's words ("likely range (95%)", "lowest to highest week"); it is printed under
+the reading line beside the mark it describes. A bar steps back to a pale fill, its range is drawn across its end in
+the bar's colour and the range's ends are printed after the value; a series or line gets a band. Accent the bar whose
+range the title is about. Give every item a
+range or none, since one without reads as certain. figkit refuses a range that does not contain its value, a range
+with no `range` text, and a bar range below zero. `n` on a bar prints its sample size under its label, as "14 runs" when `each` names
+the things counted (`"each": "runs"`), else "n = 14"; give every bar one or none. `ref` on a `series`,
+`{ "y": 67, "label": "Jul to mid-Oct: 67%" }`, draws a dashed level to compare the line with, named in the key line. A percentage of fewer than 10 things is refused: show it as a count (`"show": "3 of 6"`) or draw `units`.
+
+```json
+{ "type": "bars", "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" } ] }
+```
+
+The title claims only what the ranges allow: when they overlap, "catches more" needs a "but".
+
+`dots`: every value as a dot, for a sample small enough to look at one by one (up to 300 a group, 600 in all), in 1
+to 6 groups on one axis. Use it instead of a bar of the average when the spread or a few odd values are the point.
+Dots that would overlap stack upward and downward, so none hides another, and each group's count is printed. `note`
+(required) says what one dot is. `each` names what a dot is, so counts read "50 runs". `summary` draws the `"median"` or `"mean"` as a line across each group, labelled;
+`mark` rings one value and labels it; `zero` starts the axis at zero; `tone` on a group colours its dots.
+
+```json
+{ "type": "dots", "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, 11.8, 4.0, 12.6, 4.2] },
+              { "label": "Pull requests", "values": [4.9, 5.2, 4.6, 5.8, 5.1], "tone": "accent" } ],
+  "mark": { "group": "Main branch", "value": 12.6, "label": "12.6 min, cache miss" } }
+```
+
+`scatter`: two measures against each other, one dot per thing measured, up to 1000. It is its own type, not a mode
+of `dots`, because it takes pairs and answers a different question: whether one measure moves with the other. `x`
+and `y` each need a `label` saying what they measure, and take `unit`, `"log": true` for measures that span several
+powers of ten (every value above zero; the axis runs to whole powers of ten), `zero`, and `time` (`"seconds"`,
+`"minutes"`, `"hours"` or `"days"`, the unit the values are in) so ticks read 1 min, 1 h, 1 day, 1 wk.
+`"medians": true` draws the median y of each band of x (each power of ten on a log axis, else fifths) in the accent
+colour, with the middle half of the band's dots shaded behind it, for bands with 5 or more dots: the relation, or its
+absence, drawn without fitting a model. `label` names a point beside it, at most 5; `tone` colours it.
+figkit draws no fitted trend line: it claims more than dots do. Say the relation in the title only when the dots or
+the medians show it, and "barely" when they mostly do not.
+
+```json
+{ "type": "scatter", "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": 120, "y": 5.5 }, { "x": 540, "y": 22, "label": "Search rewrite", "tone": "accent" } ] }
+```
+
+`units`: a small count made concrete, "11 of 29" as 29 squares with 11 filled. `total` is at most 100: beyond that
+the squares cannot be counted by eye, and a `split` bar of the shares reads better. Squares sit ten to a row and fill
+column by column, so each part is one block from the left. The blocks show counts, not order: if when things happened
+matters, draw it over time instead. Up to 3 `parts` fill squares in order (the first in the accent colour
+unless it has a `tone`); `rest` (required) names the empty squares, so at least one is left. Counts are whole things.
+
+```json
+{ "type": "units", "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" }
+```
+
 `entities`: what the things are and which points at which. 2 to 5 `records`, each with an `id` you use in `refs`,
 a `name` in the reader's words, and up to 4 `fields` that say what it holds (put a table name here only if the reader
 needs it). Each of up to 8 `refs` is a pointer the `from` record holds to the `to` record: `count` is how many `from`
@@ -129,9 +253,40 @@ in plain words, not in-house terms or button labels.
 
 More than 5 records is two figures: the core records, then one corner of it with the core record it hangs off.
 
-Flows (boxes and arrows) have no spec: write them in HTML, below.
+`sequence`: who calls whom, in order. Use it when the question is "what happens when…", "walk me through a run",
+"who starts what": the order is the point and more than one part takes part. A table of steps (step, who starts it,
+who is involved) is this picture without the shape; draw it instead. A flow of boxes and arrows shows what connects
+to what, not when; use it for structure. 2 to 5 `participants`, left to right in the order the reader meets them, each
+an `id`, a `name` and an optional `kind` (where it runs: "GitHub Actions", "Cloud Run job"). 2 to 12 `messages` in
+the order they happen, each from one participant to another with a `label` saying what is asked for or sent. figkit
+numbers the steps, so your prose can say "step 4". `"reply": true` is the answer to an earlier call, drawn dashed;
+leave replies out when nothing comes back that the reader needs. A message from a participant to itself is work it
+does on its own. `note` adds one short line under a step: a condition ("only if the tests pass"), a wait ("up to an
+hour"). `repeats` frames steps `from` to `to` (numbered from 1) that run more than once, with a `label` such as "For
+each model". Accent one participant, or the steps the title is about, not both. The title claims only what the
+steps show.
+
+```json
+{ "type": "sequence", "title": "A failed card charge is retried before the shopper hears anything",
+  "participants": [ { "id": "app", "name": "Shop app", "kind": "browser" }, { "id": "api", "name": "Checkout API" },
+                    { "id": "pay", "name": "Card processor" } ],
+  "messages": [ { "from": "app", "to": "api", "label": "Place order" },
+                { "from": "api", "to": "pay", "label": "Charge the card", "tone": "accent" },
+                { "from": "pay", "to": "api", "label": "Approved or declined", "reply": true },
+                { "from": "api", "to": "app", "label": "Order number", "reply": true } ],
+  "repeats": [ { "from": 2, "to": 3, "label": "Up to 3 tries" } ] }
+```
+
+More than 5 participants or 12 steps is two figures: the whole run with minor parts merged into one participant, then
+the stage that needs detail. Leave out steps that only log or record what happened unless the question is about them.
+
+Flows (boxes and arrows) have no spec: write them in HTML, below. A flow says what connects to what; when the order
+things happen in is the point, use `sequence`.
 
 - `title` (required) is the point, 14 words at most. `note` is the reading line under it; `source` a footer.
+- `"style": "report"` draws a light chart in one sans font, for a chart that sits in a page: a research report, a doc.
+  It also draws a phone layout, `chart.phone.png`. Leave it out for the default dark figure for a dark chat.
+- Keep `note` to what is measured, and "lower is better" where it applies; dates and method go in `source`.
 - `unit` is printed straight after each number. `show` on an item replaces its printed value, e.g. `"11 of 29"`.
 - `tone` is `accent` for what to notice, `good` or `bad` when it is a result; at most two tones in a chart. Leave the rest grey.
 - `bars` takes `max` to fix the end of the axis (e.g. 100 for percentages) and a short `note` per bar.
@@ -141,7 +296,7 @@ Flows (boxes and arrows) have no spec: write them in HTML, below.
 ## The page
 
 ```html
-<main class="fig">                 <!-- add "detail" for a map to open and read; "paper" for a light figure for docs -->
+<main class="fig">                 <!-- add "detail" for a map to open and read; "paper" for a light figure for docs; "report" for a light chart in a page, in one sans font -->
   <header>
     <h1>The point, stated. <em>The part to notice</em></h1>
     <p class="read">How to read it. <b class="t-accent">Orange</b> means code.</p>
@@ -262,7 +417,10 @@ A few numbers compared:
 </fig-bars>
 ```
 
-Anything else (lines, dots, intervals, distributions, small multiples) is Observable Plot, already loaded with d3:
+Grouped bars, several lines, small multiples and heat maps have specs (`groups`, `lines`, `panels`, `heatmap`); use
+them when the chart is the whole figure. Dots, ranges, scatters and small counts have specs too
+(`dots`, `scatter`, ranges on `bars` and `series`, `units`). Anything else (a distribution of thousands, a chart beside boxes) is
+Observable Plot, already loaded with d3:
 
 ```html
 <div id="chart"></div>
@@ -279,7 +437,7 @@ Anything else (lines, dots, intervals, distributions, small multiples) is Observ
 </script>
 ```
 
-`theme` has `ink`, `muted`, `soft`, `line`, `accent`, `second`, `good`, `bad`. Draw the series in `soft`, the thing to
+`theme` has `ink`, `muted`, `soft`, `fill`, `fill2`, `line`, `accent`, `second`, `good`, `bad`. Draw the series in `fill`, the thing to
 notice in `accent`, and label it directly on the chart; no legends. Start bar axes at zero.
 
 ## Screenshots

package/README.md

@@ -16,7 +16,7 @@ Node 20 or later, and a Chromium-based browser: figkit uses Chrome or Edge if on
 
 ```
 npm install @liggi/figkit
-npx figkit guide        # prints GUIDE.md, the rules for writing figures
+npx @liggi/figkit guide        # prints GUIDE.md, the rules for writing figures
 ```
 
 ## A figure from HTML
@@ -39,15 +39,16 @@ Save this as `order.html`:
 ```
 
 ```
-npx figkit order.html --out order.png
+npx @liggi/figkit order.html --out order.png
 ```
 
 ![An order is checked before it is charged: Basket, then Fraud check, then Charge the card](docs/readme-flow.png)
 
 ## A chart from a spec
 
-For one chart of a known type (`split`, `bars`, `before-after`, `dumbbell`, `series`), or an `entities` picture of
-records and the references between them, give the data and figkit does the rest, including the layout. Save this as `checkout.json`:
+For one chart of a known type (`split`, `bars`, `before-after`, `dumbbell`, `series`, `groups`, `lines`, `panels`,
+`heatmap`, `dots`, `scatter`, `units`), or an `entities` picture of records and the references between them, give the data and figkit does the
+rest, including the layout. Add `"style": "report"` for a light chart that sits in a page. Save this as `checkout.json`:
 
 ```json
 { "type": "bars", "title": "The new checkout halves the time to pay",
@@ -58,7 +59,7 @@ records and the references between them, give the data and figkit does the rest,
 ```
 
 ```
-npx figkit checkout.json --out checkout.png
+npx @liggi/figkit checkout.json --out checkout.png
 ```
 
 ![Bar chart: the current checkout takes 86 seconds, the new one 41](docs/readme-bars.png)

package/bin/fig.mjs

@@ -7,6 +7,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { createRequire } from 'node:module';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { chromium } from 'playwright-core';
 import { ensureBuilt } from '../viz/build.mjs';
@@ -14,6 +15,12 @@ import { parseSpec } from '../viz/spec.js';
 
 const HOME = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
 const url = (...p) => pathToFileURL(path.join(HOME, ...p)).href;
+/** A dependency's file, wherever npm put the package: figkit's own node_modules, or one hoisted above it. */
+const dep = (name, ...p) => {
+  const dir = createRequire(import.meta.url).resolve.paths(name).map((d) => path.join(d, name)).find((d) => fs.existsSync(d));
+  if (!dir) { console.error(`figkit: cannot find ${name}; run npm install in the figkit folder.`); process.exit(1); }
+  return pathToFileURL(path.join(dir, ...p)).href;
+};
 const args = process.argv.slice(2);
 
 if (args.length === 0 || args[0] === '-h' || args[0] === '--help') {
@@ -39,18 +46,19 @@ if (/\.json$/i.test(src)) {
     console.log(`This chart spec has ${spec.problems.length} problem${spec.problems.length === 1 ? '' : 's'}:\n${spec.problems.map((p) => `  - ${p}`).join('\n')}`);
     process.exit(1);
   }
-  body = `<main class="fig ${spec.spec.type === 'entities' ? 'entities-fig' : 'chart'}"><script type="application/json" id="figkit-spec">${JSON.stringify(spec.spec).replace(/</g, '\\u003c')}</script></main>`;
+  const cls = [spec.spec.type === 'entities' ? 'entities-fig' : spec.spec.type === 'sequence' ? 'sequence-fig' : 'chart', spec.spec.type === 'panels' ? 'panels-fig' : '', spec.spec.style ?? ''].filter(Boolean).join(' ');
+  body = `<main class="fig ${cls}"><script type="application/json" id="figkit-spec">${JSON.stringify(spec.spec).replace(/</g, '\\u003c')}</script></main>`;
 } else if (!/class="[^"]*\bfig\b/.test(body)) body = `<main class="fig">\n${body}\n</main>`;
 await ensureBuilt();
 
 const fonts = ['newsreader/400.css', 'newsreader/400-italic.css', 'geist-sans/400.css', 'geist-sans/500.css', 'geist-sans/600.css', 'geist-mono/400.css', 'geist-mono/500.css']
-  .map((f) => `<link rel="stylesheet" href="${url('node_modules/@fontsource', f)}">`).join('\n');
+  .map((f) => `<link rel="stylesheet" href="${dep('@fontsource/' + f.split('/')[0], f.split('/')[1])}">`).join('\n');
 const page_html = `<!doctype html><html><head><meta charset="utf-8">
 <base href="${pathToFileURL(path.dirname(src) + path.sep).href}">
 ${fonts}
 <link rel="stylesheet" href="${url('runtime/fig.css')}">
-<script src="${url('node_modules/d3/dist/d3.min.js')}"></script>
-<script src="${url('node_modules/@observablehq/plot/dist/plot.umd.min.js')}"></script>
+<script src="${dep('d3', 'dist/d3.min.js')}"></script>
+<script src="${dep('@observablehq/plot', 'dist/plot.umd.min.js')}"></script>
 <script src="${url('dist/viz.iife.js')}"></script>
 <script src="${url('runtime/fig.js')}"></script>
 <style>body { display: inline-block; }</style>
@@ -93,7 +101,7 @@ try {
     if (phone) await page.addInitScript(() => { window.__figPhone = true; });
     await page.goto(pathToFileURL(wrapped).href);
     await page.waitForFunction('window.__figDone === true', null, { timeout: 30000 });
-    const r = await page.evaluate(() => ({ problems: window.fig.problems, info: window.fig.info, sides: !!document.querySelector('.fig .sides, .fig .entities'), entities: !!document.querySelector('.fig .entities') }));
+    const r = await page.evaluate(() => ({ problems: window.fig.problems, info: window.fig.info, sides: !!document.querySelector('.fig .sides, .fig .entities, .fig .sequence, .fig .panels, .fig.report'), entities: !!document.querySelector('.fig .entities'), sequence: !!document.querySelector('.fig .sequence'), panels: !!document.querySelector('.fig .panels'), stack: !!document.querySelector('.fig .sides') }));
     await page.locator('.fig').first().screenshot({ path: shot });
     await page.close();
     return { ...r, problems: [...errors.map((e) => `Script error: ${e}`), ...r.problems] };
@@ -108,7 +116,7 @@ try {
 
   const { info } = desk;
   const lines = [`Figure:       ${png}  (${info.width * 2}×${info.height * 2})`];
-  if (mob) lines.push(`Phone layout: ${phonePng}  (${mob.info.width * 2}×${mob.info.height * 2}), ${desk.entities ? 'the records in two columns' : 'the sides stacked'}, for a viewer to show on a phone`);
+  if (mob) lines.push(`Phone layout: ${phonePng}  (${mob.info.width * 2}×${mob.info.height * 2}), ${desk.entities ? 'the records in two columns' : desk.sequence ? 'the participants narrower' : desk.panels ? 'the panels stacked' : desk.stack ? 'the sides stacked' : 'at phone width'}, for a viewer to show on a phone`);
   lines.push(`Phone inline: ${inline}  (preview only)`);
   const ph = (mob ?? desk).info.phone;
   const sizes = [['the title', ph?.title], ['headings', ph?.heading], ['body', ph?.body]].filter(([, v]) => v != null).map(([k, v]) => `${k} ${v}px`);