flowfig 0.6.0 → 0.8.0

package/dist/rail.js

@@ -1,8 +1,5 @@
 import { edgeId, isGroup, labelPillW, str, toBeat } from './model.js';
 import { textWidth } from './text.js';
-// band: the band-label line; cols: the column-label row; bandInset: a band's inset from its outer column edges, so two adjacent
-// bands keep 16 px between them; clear: the space between a phase label or counter and a line; inset: the space a parallel band
-// leaves around its arrows and pills.
 export const RAIL = {
     gap: 24,
     band: 20,
@@ -16,9 +13,7 @@ export const RAIL = {
     inset: 6,
     maxOpen: 10,
 };
-/** The folded phase text. Both renderers and the layout use it, so the measured width matches the drawn width. */
 export const foldedLabel = (row) => `▸ ${row.label} · ${row.messages} messages`;
-/** Rail columns follow this order, so a reader meets the boxes in the same order on the rail as on the map. */
 const order = (item) => isGroup(item)
     ? [...(item.id ? [{ id: item.id, label: str(item.label) }] : []), ...item.children.flatMap(order)]
     : [{ id: item.id, label: str(item.label) }];
@@ -51,15 +46,12 @@ export function layoutRail(fig, mapWidth) {
     const used = new Set(msgs.flatMap((m) => [edges.get(m.edge).from, edges.get(m.edge).to]));
     const cols = order(fig.layout).filter((c) => used.has(c.id));
     const index = new Map(cols.map((c, i) => [c.id, i]));
-    // Every column gets the same width: at least RAIL.minCol, wide enough for each label and pill, and together as wide as the map.
-    // A column label also needs room for the band inset on each side.
     let need = RAIL.minCol;
     for (const c of cols)
         need = Math.max(need, textWidth(c.label, 12) + 16 + RAIL.bandInset * 2);
     for (const m of msgs)
         if (m.text)
             need = Math.max(need, labelPillW(m.text) + 16);
-    // The phase labels start at RAIL.pad and the counters end at width - RAIL.pad. No band border comes within RAIL.clear of them.
     const folds = msgs.length > RAIL.maxOpen;
     const labelW = (text) => textWidth(text, 13, true);
     const counterW = (() => {
@@ -70,8 +62,6 @@ export function layoutRail(fig, mapWidth) {
         const label = str(steps[si].label);
         return labelW(folds ? foldedLabel({ label, messages: b.flat().length }) : label);
     }));
-    // Bands: each labeled group around the columns it holds, RAIL.bandInset inside their outer edges; a nested group sits 4 px inside
-    // its parent and one label line (RAIL.band) below it. The height comes later.
     const place = (left, right, colW) => {
         const width = left + colW * cols.length + right;
         const columns = cols.map((c, i) => ({ id: c.id, label: c.label, x: left + colW * (i + 0.5), w: colW }));
@@ -90,7 +80,6 @@ export function layoutRail(fig, mapWidth) {
         };
         walk(fig.layout, 0);
         const borders = bands.flatMap((b) => [b.rect.x, b.rect.x + b.rect.w]);
-        // How far the columns must move in from each side, so every band border clears the label and the counter.
         const dl = Math.max(0, RAIL.pad + widest + RAIL.clear - Math.min(Infinity, ...borders));
         const dr = Math.max(0, Math.max(-Infinity, ...borders) - (width - RAIL.pad - counterW - RAIL.clear));
         return { width, columns, bands, dl, dr };
@@ -102,14 +91,12 @@ export function layoutRail(fig, mapWidth) {
     for (let k = 0; placed.dl > 0.01 || placed.dr > 0.01; k++) {
         left += placed.dl;
         right += placed.dr;
-        // Narrower columns keep the rail as wide as the map. After a few tries the columns keep their width, and the rail grows.
         if (k < 8)
             colW = spread(left, right);
         placed = place(left, right, colW);
     }
     const { width, columns, bands } = placed;
     const head = (bands.length ? Math.max(...bands.map((b) => b.rect.y)) + RAIL.band : 0) + RAIL.cols;
-    // Rows: a phase header per step, then one row per message.
     const rows = [];
     const groups = [];
     let n = 0;
@@ -145,7 +132,6 @@ export function layoutRail(fig, mapWidth) {
             }
         }
     });
-    // Above maxOpen messages, only the playing step shows its rows; the others shrink to their phase header.
     const states = steps.map((_, open) => {
         let y = head;
         return rows.map((row) => {
@@ -159,7 +145,7 @@ export function layoutRail(fig, mapWidth) {
     const bottom = (s) => s.reduce((m, st, i) => (st.shown ? Math.max(m, st.y + (rows[i].kind === 'phase' ? RAIL.phase : RAIL.row)) : m), 0);
     const height = Math.max(...states.map(bottom)) + 8;
     for (const b of bands)
-        b.rect.h = height - b.rect.y - (b.rect.y / RAIL.band) * 4; // the bottom edge keeps the 4 px nesting inset
+        b.rect.h = height - b.rect.y - (b.rect.y / RAIL.band) * 4;
     return { width, head, height, columns, bands, rows, groups, total: n, folds, states };
 }
 /** A parallel band around its rows, relative to the y of its first row: RAIL.inset around every arrow and pill it holds. */
@@ -171,6 +157,6 @@ export function groupBox(rail, g) {
         return [rail.columns[r.from].x, rail.columns[r.to].x, ...(r.pill ? [r.pill.x, r.pill.x + r.pill.w] : [])];
     });
     const x = Math.min(...xs) - RAIL.inset;
-    const top = (RAIL.row - 18) / 2 - RAIL.inset; // 18: the pill height
+    const top = (RAIL.row - 18) / 2 - RAIL.inset;
     return { x, y: top, w: Math.max(...xs) + RAIL.inset - x, h: g.rows.length * RAIL.row - top * 2 };
 }

package/dist/scene.d.ts

@@ -1,5 +1,5 @@
 import type { Pt, Rect } from './geometry.ts';
-/** One line of text in a box. `need` is the measured width; without it, the check estimates the width. */
+/** `need` is the measured width; without it, `check` estimates it. */
 export type TextRun = {
     text: string;
     fontSize: number;
@@ -12,34 +12,34 @@ export type SceneBox = {
     rect: Rect;
     texts: TextRun[];
 };
-/** `step` marks a rail row: rows of two steps never show at the same time, so their labels cannot overlap. */
-/** `behind` marks an edge drawn under the boxes (a timeline dependency): `check` skips its crossing test. */
-/** `pts` are the corners of an edge drawn as straight runs (a cross-block lanes edge): `check` tests them in place of `curve`. */
 export type SceneEdge = {
     id: string;
     from: string;
     to: string;
     curve: [Pt, Pt, Pt, Pt];
+    /** Corners of a straight-run edge (cross-block lanes). `check` tests them, not `curve`. */
     pts?: Pt[];
     label?: Rect;
+    /** A rail row: rows of two steps never show together, so labels cannot overlap. */
     step?: number;
+    /** Drawn under the boxes (a timeline dependency): `check` skips the crossing test. */
     behind?: true;
-    /** The corners of a timeline elbow. `check` tests a `behind` edge against the boxes only when it has them. */
+    /** Timeline elbow corners. `check` tests a `behind` edge only when it has them. */
     elbow?: Pt[];
 };
-/** `minFont` is the smallest reading text in px, before any scale. Group frames are not boxes. */
-/** `lanes` are the lane bands of a swimlanes figure, one per lane and block, named by the lane label. A stub pill stays inside one. */
 export type Scene = {
     width: number;
     boxes: SceneBox[];
     edges: SceneEdge[];
+    /** The smallest reading text in px, before any scale. */
     minFont: number;
+    /** The lane bands of a swimlanes figure. A stub pill stays inside one. */
     lanes?: {
         id: string;
         rect: Rect;
     }[];
 };
-/** One fault that `flowfig check` found. `rule` names the check, for example `unknown-id`, `text-overflow`, `edge-crosses-box`, `label-overlap`, `small-text`, `low-contrast`. `ids` are the boxes or edges it names. */
+/** One fault that `flowfig check` found. `ids` name the boxes or edges. */
 export type Finding = {
     rule: string;
     severity: 'error' | 'warning';

package/dist/source.d.ts

@@ -4,7 +4,6 @@ export declare function parseSource(s: string): {
     path: string;
     symbol?: string;
 } | null;
-/** The GitHub anchor of a heading: lower case, only letters, digits, spaces and hyphens, spaces to hyphens. */
 export declare const headingSlug: (text: string) => string;
 export type Link = {
     owner: string;
@@ -13,6 +12,6 @@ export type Link = {
     symbol?: string;
 };
 /** Every box, edge and hop with its raw `source`, well-formed or not. The one owner list that `links` and `checkSpec` share. */
-export declare function owners(fig: FlowProps): [string, string | undefined][];
+export declare function owners(fig: FlowProps): [string, string | undefined, string | undefined][];
 /** Every well-formed link in the figure, with the box, edge or hop that carries it. `bad-source` covers the rest. */
 export declare function links(fig: FlowProps): Link[];

package/dist/source.js

@@ -1,4 +1,4 @@
-// Code links, pure: no Node import, so the React and SVG entries stay browser-safe. `verify` in verify.ts reads the disk.
+// No Node import: the React and SVG entries must stay browser-safe.
 import { edgeId, nodes, toBeat } from './model.js';
 /** `path` or `path#symbol`. No spaces, one `#` at most, both parts non-empty. `null` for a bad form. */
 export function parseSource(s) {
@@ -7,7 +7,7 @@ export function parseSource(s) {
         return null;
     return m[2] ? { path: m[1], symbol: m[2] } : { path: m[1] };
 }
-/** The GitHub anchor of a heading: lower case, only letters, digits, spaces and hyphens, spaces to hyphens. */
+// GitHub anchor rules: drop other characters, then spaces become hyphens.
 export const headingSlug = (text) => text
     .toLowerCase()
     .replace(/[^\p{L}\p{N} -]/gu, '')
@@ -15,9 +15,9 @@ export const headingSlug = (text) => text
 /** Every box, edge and hop with its raw `source`, well-formed or not. The one owner list that `links` and `checkSpec` share. */
 export function owners(fig) {
     return [
-        ...nodes(fig.layout).map((n) => [`box "${n.id}"`, n.source]),
-        ...fig.edges.map((e) => [`edge "${edgeId(e)}"`, e.source]),
-        ...(fig.steps ?? []).flatMap((s) => s.flow.flatMap((b) => toBeat(b).hops.map((h) => [`hop on "${h.edge}"`, h.source]))),
+        ...nodes(fig.layout).map((n) => [`box "${n.id}"`, n.source, undefined]),
+        ...fig.edges.map((e) => [`edge "${edgeId(e)}"`, e.source, e.via]),
+        ...(fig.steps ?? []).flatMap((s) => s.flow.flatMap((b) => toBeat(b).hops.map((h) => [`hop on "${h.edge}"`, h.source, h.via]))),
     ];
 }
 /** Every well-formed link in the figure, with the box, edge or hop that carries it. `bad-source` covers the rest. */

package/dist/svg.d.ts

@@ -9,25 +9,22 @@ import { type FigTheme, type FlowProps } from './model.ts';
 export { LIGHT, DARK } from './model.ts';
 /** Options for `toSvg`, `render` and `check`. */
 export type SvgOptions = {
-    /** Milliseconds a packet takes to cross one edge, in place of `FlowProps.speed`. Default: `FlowProps.speed`, else 900. */
+    /** Milliseconds a packet takes to cross one edge. Default: `FlowProps.speed`, else 900. */
     speed?: number;
     /** Space around the figure in px. Default: 24. */
     padding?: number;
-    /** Colors, in place of `FlowProps.theme`. Default: `FlowProps.theme`. */
+    /** Colors. Default: `FlowProps.theme`. */
     theme?: FigTheme;
-    /** Lanes: the page width and the smallest text that decide when the time columns wrap into blocks. Default: 830 and 10, as in `check`. */
+    /** Lanes: page width and smallest text size that set the wrap. Default: 830 and 10. */
     width?: number;
     minText?: number;
 };
-/**
- * The SVG string, and the scene it drew. The scene lets `flowfig check` test the same layout the SVG uses.
- * The scene is for tools, and its shape may change. Use `toSvg` if you only need the SVG.
- */
+/** The SVG string and the scene it drew. The scene shape may change; use `toSvg` for the SVG only. */
 export declare function render(fig: FlowProps, opts?: SvgOptions): {
     svg: string;
     scene: Scene;
 };
 /** One self-contained animated SVG string for the figure. Needs no React and no browser. */
 export declare function toSvg(fig: FlowProps, opts?: SvgOptions): string;
-/** Every fault `flowfig check` knows about, for this figure as the SVG lays it out. A `Finding` has a `rule` name, a `severity`, the ids it names and a message. */
+/** Every fault `flowfig check` knows about, for this figure as the SVG lays it out. */
 export declare function check(fig: FlowProps, opts?: SvgOptions & CheckOptions): Finding[];