@liggi/figkit 0.5.0 → 0.6.0

package/GUIDE.md

@@ -37,9 +37,13 @@ what?", "walk me through it") is answered with a picture first, not with numbere
   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.
+- "How does X fit together?", "what are all the parts of X?", "give me the map of X": when the question really is
+  about the whole system and it has more than 5 parts worth naming, draw a `map` spec (below): every part in its
+  subsystem and every link, laid out by figkit. Follow it with a plain `fig` of the part the question is about,
+  so the reader knows where to look; a map alone answers "what exists", not "what matters here".
+- Otherwise 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: 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. A system of more than 5 parts is a `map`, not a hand-placed `fig detail`.
 - Under each figure, write only what it cannot show: why, the exceptions, what to do. Never retell it as steps.
 - Put a real instance in each box, with its kind as the smaller line: "Refunds over £500" over "Approval rule",
   not a box that says only "Rule".
@@ -50,7 +54,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, one sequence or one lifecycle 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, one lifecycle or one system map 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.
 
@@ -366,6 +370,57 @@ A states picture holds 7 states, not the 5 boxes of other figures: each state is
 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.
 
+`map`: a whole system, its parts grouped by subsystem and the links between them, laid out by figkit. Use it when
+the question is about the whole system ("how does X fit together?", "what are all the parts?"); for one path through
+it use `sequence`, and for one corner of it a plain `fig`. 2 to 6 `subsystems`, each an `id`, a `name` and an optional
+`kind` (the folder or team it belongs to). 6 to 24 `parts`, each an `id`, a `name` in the reader's words, a `kind` as
+the smaller line (the file, the service, what it is: "lib/detectors/gate.ts", "Postgres") and `in`, the subsystem it
+belongs to; something outside the system, such as GitHub or a database another team runs, still goes in a subsystem,
+"Outside". At most 8 parts in one subsystem. Up to 30 `links`, each `from` the part that calls, reads or sends `to`
+the part called, read or written, with an optional `label` of a few words ("writes scores", "pick lists"). Label the
+links the question is about and leave the obvious ones bare: every label is one more thing to place in a crowded
+picture. A label sits on its own line, never beside it, because between subsystems lines run side by side and a word
+beside one reads as naming its neighbour; figkit moves it along the line to a clear spot and refuses the figure when
+there is none, naming the label to drop. A real map of 23 parts kept 18 of its 21 labels. Draw a link one way only, from the part that starts the exchange; the reply is implied. `"tone": "accent"` on the parts and links the question
+is about, the same ones the title names.
+
+figkit lays the parts out in layers inside each subsystem, packs the subsystems into rows that read largest on a full
+screen, and routes every link around the boxes. With links accented, it places the accented path first: the subsystems
+it passes through go one after another, lined up so the path runs as one straight line, or steps aside where a part is
+in the way, and the other subsystems go beside it, routed around it. It refuses a map whose accented path still turns
+back on itself, and names any grey link that crosses it. Accent links that follow one another in one direction.
+A map with an accented path holds 28 links, and at most 3 grey links on any part of the path: the path takes a part's
+top and bottom, so grey links come in from the sides. Measured on a real map of 24 parts, its path stayed one straight
+run with no grey link crossing it at 15 to 26 links, and failed at 27 (4 grey links on one part of the path), 29 and
+30 (lines on top of each other, or 17 to 21 crossings); a second real map held at 28 links. The phone layout draws each subsystem as one box listing its parts,
+with the number of links between subsystems on the arrows. It refuses an id that names no part or subsystem, a part in
+no subsystem, a part or subsystem with no link or no parts, two links between the same parts, either way, a link from
+a part to itself, and two parts with the same name. After drawing it reports labels that collide and links that run on
+top of each other; up to one crossing per 2 links is allowed and named in a note.
+
+```json
+{ "type": "map", "title": "Every order passes through the order service before stores see it",
+  "subsystems": [ { "id": "shop", "name": "Storefront" }, { "id": "orders", "name": "Orders" },
+                  { "id": "stores", "name": "Store fulfilment" } ],
+  "parts": [ { "id": "web", "name": "Shop website", "kind": "Next.js app", "in": "shop" },
+             { "id": "basket", "name": "Basket service", "kind": "Go service", "in": "shop" },
+             { "id": "order", "name": "Order service", "kind": "Go service", "in": "orders", "tone": "accent" },
+             { "id": "events", "name": "Order events", "kind": "Kafka topic", "in": "orders" },
+             { "id": "planner", "name": "Picking planner", "kind": "nightly batch", "in": "stores" },
+             { "id": "picker", "name": "Picker app", "kind": "handheld scanner", "in": "stores" } ],
+  "links": [ { "from": "web", "to": "basket" },
+             { "from": "basket", "to": "order", "label": "checkout", "tone": "accent" },
+             { "from": "order", "to": "events", "label": "publishes" },
+             { "from": "events", "to": "planner" }, { "from": "planner", "to": "picker", "label": "pick lists" } ] }
+```
+
+A map holds 24 parts, not the 5 boxes of other figures, because it is opened full screen and read region by region,
+not taken in at a glance. 24 parts and 30 links is where real systems stop reading: drawn from their code, two systems
+of 23 and 24 parts with 28 and 30 links crossed 9 and 11 times and could be followed full screen; at 32 links one of
+them crossed anywhere from 12 to 20 times as small changes moved its regions, and at 31 to 34 parts and 45 to 48 links
+they crossed 28 to 49 times and could not be followed. More than 24 is two maps: the subsystems with the busiest one merged to a few parts, then
+that subsystem as its own map. The title still claims one thing the map shows.
+
 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`; when one thing's states are the point, use `states`.
 
@@ -394,8 +449,8 @@ things happen in is the point, use `sequence`; when one thing's states are the p
 
 - 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 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.
+- `fig detail` is 1360 wide, for a flow the reader asked for and opens full screen; to explain a system, use
+  several `fig` figures or a `map` spec 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.
 - Height follows the content. There is no fixed canvas to fill.
 - Text must be at least 15px; the theme's sizes all pass. The phone line the command prints is information, and only the problems list needs fixing.

package/THIRD_PARTY_NOTICES.md

@@ -1,6 +1,6 @@
 # Third-party notices
 
-`dist/viz.iife.js` bundles Observable Plot and the d3 modules it uses. Their licences follow. The fonts (Newsreader, Geist Sans, Geist Mono, under the SIL Open Font License 1.1), Playwright (Apache-2.0), d3 (ISC) and Zod (MIT) are installed as ordinary dependencies and are not copied into this package.
+`dist/viz.iife.js` bundles Observable Plot and the d3 modules it uses, and dagre with its graphlib for laying out maps. Their licences follow. The fonts (Newsreader, Geist Sans, Geist Mono, under the SIL Open Font License 1.1), Playwright (Apache-2.0), d3 (ISC) and Zod (MIT) are installed as ordinary dependencies and are not copied into this package.
 
 ## @observablehq/plot
 
@@ -630,3 +630,50 @@ TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
 THIS SOFTWARE.
 ```
 
+## @dagrejs/dagre
+
+```
+Copyright (c) 2012-2014 Chris Pettitt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```
+
+## @dagrejs/graphlib
+
+```
+Copyright (c) 2012-2014 Chris Pettitt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```

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' : spec.spec.type === 'states' ? 'states-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' : spec.spec.type === 'map' ? 'detail map-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 .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') }));
+    const r = await page.evaluate(() => ({ problems: window.fig.problems, notes: window.fig.notes ?? [], info: window.fig.info, sides: !!document.querySelector('.fig .sides, .fig .map, .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'), map: !!document.querySelector('.fig .map'), 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,12 +116,14 @@ 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.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`);
+  if (mob) lines.push(`Phone layout: ${phonePng}  (${mob.info.width * 2}×${mob.info.height * 2}), ${desk.map ? 'each subsystem as one box' : 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`);
   if (sizes.length) lines.push(`Inline on a phone: ${sizes.join(', ')}; under about 6px only reads after a tap to zoom.`);
   if (!mob && info.unmarked) lines.push('Its columns sit side by side and will shrink on a phone. If they are two sides to compare, add class "sides" to the row or grid that holds them, and a stacked phone layout is drawn too.');
+  for (const n of desk.notes) lines.push(`Note: ${n}`);
+  for (const n of mob?.notes ?? []) lines.push(`Phone layout note: ${n}`);
   const all = [...desk.problems, ...(mob?.problems ?? []).map((p) => `Phone layout: ${p}`)];
   lines.push(all.length ? `\n${all.length} problem${all.length === 1 ? '' : 's'}:` : '\nNo problems found by the checks.');
   for (const p of all) lines.push(`  - ${p}`);