@liggi/figkit 0.4.0 → 0.5.0

package/GUIDE.md

@@ -30,6 +30,8 @@ what?", "walk me through it") is answered with a picture first, not with numbere
 
 - "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's the lifecycle of X?" and "what states can it be in?" are a `states` spec (below): the states one thing
+  moves through and what moves it on, not boxes and arrows in HTML.
 - "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
@@ -48,7 +50,7 @@ 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, one entities picture or one sequence 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, one sequence or one lifecycle 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.
 
@@ -76,6 +78,21 @@ and embed the PNG, as for any figure.
   "bars": [ { "label": "Current checkout", "value": 86 }, { "label": "New checkout", "value": 41, "tone": "good" } ] }
 ```
 
+A bar chart that compares every bar with one level, such as production or the current version, takes `ref`: the
+level's `value` and a `label` naming it in words ("Production (ash-prod-27b)", never a bare number). figkit draws it as
+its own first row in the second colour, with a dashed line from its end down through every bar; bars above it are
+accented and the rest are grey, and the key says what the colour means. The colours are figkit's, so a `tone` on a bar
+is refused, and `note` is required so the reader knows what the level's number counts. With ranges, a bar counts as
+above only when its whole range is above. `show` on the ref replaces its printed value, e.g. `"50%, a tie"`.
+
+```json
+{ "type": "bars", "title": "Two of the four new layouts beat the current page",
+  "note": "Share of visitors who finished checkout", "unit": "%",
+  "ref": { "label": "Current page", "value": 61 },
+  "bars": [ { "label": "One-page form", "value": 68 }, { "label": "Saved cards first", "value": 64 },
+            { "label": "Address lookup", "value": 60 }, { "label": "Guest by default", "value": 57 } ] }
+```
+
 `before-after`: one measure that changed, the two values side by side on one scale; `note` (required) says what
 the number counts. For several things changing,
 use `bars` or `dumbbell`.
@@ -148,7 +165,9 @@ different things on the same scale.
 ```
 
 `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
+is always more. When any value is below zero (a change, a gap, a correlation), the grid is signed and the colour runs
+from orange below zero through pale at zero to blue above, equally strong at equal distances from zero, with the
+numbers printed with their sign; the scale shows 0 between the two halves. Numbers keep the decimal places you give. 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,
@@ -185,6 +204,28 @@ the things counted (`"each": "runs"`), else "n = 14"; give every bar one or none
 
 The title claims only what the ranges allow: when they overlap, "catches more" needs a "but".
 
+`estimates`: signed results with their ranges, one row each around a zero line (a forest plot): a gap between two
+groups, a change against control, a correlation. Use it when the sign is the point and each number has a range: "+7.4
+(+2.7 to +12.4)". For numbers counted up from zero, use `bars`; for a move from one value to another, `dumbbell`. Every
+row needs `low` and `high`, and `range` says once what they are. `note` (required) says what the number is and which
+way round ("matched minus not matched"). `sides` names what each side of zero means, printed under the axis and meeting at zero; keep each to two or three words, or figkit reports it. figkit
+chooses the colours: a row whose range clears zero is filled in the accent colour, one whose range includes zero is a
+hollow grey dot, and the key says so; a `tone` is refused. With `"better": "higher"` or `"lower"`, a row clear of zero
+is `good` or `bad` instead. Up to 12 rows; `n` and `each` as on `bars`. Numbers keep the decimal places you give, with
+their sign. A range that does not contain its value, or a range of no width, is refused.
+
+```json
+{ "type": "estimates", "title": "Free delivery lifts orders in two regions; the north's range includes zero",
+  "note": "Change in orders per 100 visitors, free delivery minus paid", "range": "95% interval",
+  "sides": { "below": "Paid better", "above": "Free better" },
+  "rows": [ { "label": "South", "value": 2.4, "low": 1.1, "high": 3.7 },
+            { "label": "Midlands", "value": 1.8, "low": 0.6, "high": 3.0 },
+            { "label": "North", "value": 0.7, "low": -0.9, "high": 2.3 } ] }
+```
+
+The title says a result only for rows whose range clears zero; a row whose range includes zero is "no clear change",
+not a small gain.
+
 `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`
@@ -280,12 +321,57 @@ steps show.
 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.
 
+`states`: the states one thing moves through and what moves it on: a pull request, an order, a ticket, a person
+in a study. Use it for "what's the lifecycle of X?", "what states can it be in?", "what happens after it's
+approved?": the question is about one thing and where it can go next. A `sequence` is about several parts taking turns;
+a flow is about what connects to what. 2 to 7 `states`, each an `id`, a `name` and an optional one-line `note` (a rule
+that holds there: "A restart needs a new review"). Mark the one state things begin in `"start": true`, and the states
+they stop in `"end": true`: nothing ever leaves an end, so a mark that comes and goes on a state (the current
+default, a pin) is that state's `note`, not an end. `entry` labels the way in ("Card created"). 1 to 10 `moves`, each `from` one state `to`
+another with a `label` saying what makes the move happen. figkit draws the longest run from the start down one
+column, the other states beside it, and a move back to an earlier state as a loop up the left side. `from` can be a
+list of states for one move any of them can make (retire, cancel), drawn as one bracket beside them and one arrow; `back` names the same
+move the other way (`"back": "Restore"`), drawn with a head at both ends.
+
+Counts: `count` on every move is how many of the things made that move at least once, `each` names them
+(`"people"`), and the start's `count` is how many entered. `stayed` on a state that is not an end is how many went no further
+than it. `"shares": true` adds each move's share of those who
+reached the state it leaves; a loop back brings nothing new into that base. figkit says what the counts mean under
+the reading line, and refuses counts on only some moves, a move counted higher than reached the state it leaves,
+moves out of a state passed through once adding up to more than reached it, and a share of fewer than 10.
+
+It also refuses a lifecycle with no start or two, an end with a way out, a state nothing leaves that is not marked
+end, a state the start cannot reach, a move to its own state (put that in the state's `note`), and two moves between
+the same states the same way. Accent one state or the moves the title is about. The title claims only what the moves
+show.
+
+```json
+{ "type": "states", "title": "An order waits after a declined card until a new card is added",
+  "entry": "Shopper checks out",
+  "states": [ {"id": "waiting", "name": "Awaiting payment", "start": true},
+              {"id": "declined", "name": "Card declined", "note": "Shopper emailed", "tone": "accent"},
+              {"id": "paid", "name": "Paid"},
+              {"id": "packed", "name": "Packed"},
+              {"id": "shipped", "name": "Shipped", "end": true},
+              {"id": "cancelled", "name": "Cancelled", "end": true} ],
+  "moves": [ {"from": "waiting", "to": "paid", "label": "Charge succeeds"},
+             {"from": "waiting", "to": "declined", "label": "Charge fails"},
+             {"from": "declined", "to": "waiting", "label": "New card added"},
+             {"from": "paid", "to": "packed", "label": "Warehouse picks"},
+             {"from": "packed", "to": "shipped", "label": "Carrier collects"},
+             {"from": ["paid", "packed"], "to": "cancelled", "label": "Shopper cancels"} ] }
+```
+
+A states picture holds 7 states, not the 5 boxes of other figures: each state is a short name read in order down one
+path, and an ordinary lifecycle is four or five steps plus one or two ways off it. More than 7 is two figures: the
+main path with the side branches merged into one state, then the branch that needs detail.
+
 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`.
+things happen in is the point, use `sequence`; when one thing's states are the point, use `states`.
 
 - `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.
+  It also draws a phone layout, `chart.phone.png`, as do `estimates`, `heatmap` and `bars` with a `ref` in either style. 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.
@@ -418,8 +504,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. 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
+them when the chart is the whole figure. Dots, ranges, signed estimates, scatters and small counts have specs too
+(`dots`, `estimates`, `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
@@ -452,7 +538,8 @@ notice in `accent`, and label it directly on the chart; no legends. Start bar ax
 
 ## What the checks catch, and what they cannot
 
-Measured in the rendered page: text past its box or the frame, text too small, boxes and labels that overlap, arrows
+Measured in the rendered page: text past its box or the frame, text too small, text too faint against what is drawn
+behind it (a contrast under 3 to 1), boxes and labels that overlap, arrows
 through boxes, arrows crossing, edges that almost line up, too many words, boxes, arrows or colours, facts strung
 together with separators, a missing or long title.
 

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' : spec.spec.type === 'sequence' ? 'sequence-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' : spec.spec.type === 'states' ? 'states-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 .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') }));
+    const r = await page.evaluate(() => ({ problems: window.fig.problems, info: window.fig.info, sides: !!document.querySelector('.fig .sides, .fig .entities, .fig .sequence, .fig .states, .fig .panels, .fig .estimates, .fig .heatmap, .fig fig-bars.has-ref, .fig.report'), states: !!document.querySelector('.fig .states'), 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.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`);
+  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.states ? 'the states 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`);