@liggi/figkit 0.1.0 → 0.3.0

package/GUIDE.md

@@ -28,6 +28,11 @@ 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 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
+  at them: draw the pointers it holds, not the steps it runs. Draw every pointer a record holds, even when another
+  line reaches the same record by a longer way; leaving one out says the column is not there.
 - Each figure is a plain `fig` with at most 5 boxes and no `group`. More than that is two or three figures in a row,
   not one map: what exists, then one case through it, then what changes. A process or machine the code runs in is a
   `tag` on the box, not a box around it. Use `fig detail` only when the reader asked for the whole map.
@@ -39,9 +44,9 @@ what?", "walk me through it") is answered with a picture first, not with numbere
   three arrows; one shared copy is one box fanning out to the three. "How many" must be visible without reading.
 - Name each thing once, and use that name in the title, the boxes and your prose.
 
-## Charts from a spec
+## Charts and entities from a spec
 
-When the whole figure is one chart of a type below, write a JSON spec instead of HTML. You give the data; figkit
+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
 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.
 
@@ -100,9 +105,90 @@ 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" } }
+```
+
+`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`
+records can point at one `to` (`"many"`, the default, or `"one"`), and `"optional": true` when the pointer may be
+empty. figkit places the records (what is pointed at sits above what points at it) and draws each reference as a line
+joined at the records' names: a dot on the record named, and on the holder a crow's foot when many can point at one or
+a short bar when only one can; dashed when it may be empty; never an arrow, never a key. It draws a two-column layout
+for a phone. Every record must be in a reference. Accent at most one record: the one the title is about. The title
+claims only what the lines show; if it says "everything names X", every record has a line to X. Names and fields are
+in plain words, not in-house terms or button labels.
+
+```json
+{ "type": "entities", "title": "Every order line names one product and one order",
+  "records": [ { "id": "order", "name": "Order", "fields": ["placed at"] },
+               { "id": "line", "name": "Order line", "fields": ["quantity"], "tone": "accent" },
+               { "id": "product", "name": "Product", "fields": ["sku"] },
+               { "id": "payment", "name": "Payment" } ],
+  "refs": [ { "from": "line", "to": "order" },
+            { "from": "line", "to": "product" },
+            { "from": "payment", "to": "order", "count": "one", "optional": true } ] }
+```
+
+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.
 
 - `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.
@@ -112,7 +198,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>
@@ -123,7 +209,7 @@ Flows (boxes and arrows) have no spec: write them in HTML, below.
 ```
 
 - In the `<h1>`, `<em>` turns the words accent-coloured italic and `<br>` sets a line break.
-- `fig` is a glance figure, 960 wide: one point, big type, reads inline on a phone. At most 8 boxes, 8 arrows and 70 words.
+- `fig` is a glance figure, 960 wide: one point, big type, reads inline on a phone. At most 5 boxes, 8 arrows and 70 words.
 - `fig detail` is 1360 wide, for a flow or map the reader asked for and opens full screen; to explain a system, use
   several `fig` figures instead (see Explaining a system). At most 18 boxes, 18 arrows and 190 words.
   Widen it with `style="--w: 1560px"` only when a row will not fit.
@@ -196,7 +282,8 @@ never nudge with margins.
 
 Put them anywhere inside the figure; `from` and `to` are element ids. Any element can be an end: a node, a group, a
 `mark` on a screenshot, a `<span>` of text. Arrows keep clear of boxes and loose text, and arrows sharing an end and
-a colour share a trunk.
+a colour share a trunk. When a label has no free place, figkit opens the gap between the two boxes (or widens the
+figure a little) and draws again; keep labels to a few words so it rarely has to.
 
 - colour: `accent`, `second`, `good`, `bad`; `dashed`; `weight="3"`; `both` for two heads; `head="none"`
 - `blocked`: a route that does not exist. The line stops short of the target at a cross, with no arrowhead
@@ -232,7 +319,9 @@ 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. Anything else (dots, intervals, distributions, a chart beside boxes) is
+Observable Plot, already loaded with d3:
 
 ```html
 <div id="chart"></div>
@@ -249,7 +338,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

@@ -46,8 +46,9 @@ 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`) give the data and figkit does
-the rest. Save this as `checkout.json`:
+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
+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",

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 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' : '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') }));
+    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') }));
     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}), 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.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`);