@liggi/figkit 0.3.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
@@ -159,6 +161,74 @@ when there is room. Columns label themselves at even steps, so give hours as "12
   "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`
@@ -183,7 +253,35 @@ 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.
@@ -320,7 +418,8 @@ A few numbers compared:
 ```
 
 Grouped bars, several lines, small multiples and heat maps have specs (`groups`, `lines`, `panels`, `heatmap`); use
-them when the chart is the whole figure. Anything else (dots, intervals, distributions, a chart beside boxes) is
+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

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,7 +39,7 @@ 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)
@@ -47,7 +47,7 @@ npx figkit order.html --out order.png
 ## A chart from a spec
 
 For one chart of a known type (`split`, `bars`, `before-after`, `dumbbell`, `series`, `groups`, `lines`, `panels`,
-`heatmap`), or an `entities` picture of records and the references between them, give the data and figkit does the
+`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
@@ -59,7 +59,7 @@ rest, including the layout. Add `"style": "report"` for a light chart that sits
 ```
 
 ```
-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

@@ -46,7 +46,7 @@ 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);
   }
-  const cls = [spec.spec.type === 'entities' ? 'entities-fig' : 'chart', spec.spec.type === 'panels' ? 'panels-fig' : '', spec.spec.style ?? ''].filter(Boolean).join(' ');
+  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();
@@ -101,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, .fig .panels, .fig.report'), entities: !!document.querySelector('.fig .entities'), panels: !!document.querySelector('.fig .panels'), stack: !!document.querySelector('.fig .sides') }));
+    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] };
@@ -116,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' : desk.panels ? 'the panels stacked' : desk.stack ? 'the sides stacked' : 'at phone width'}, 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`);