flowfig 0.1.0

package/dist/rail.js

@@ -0,0 +1,162 @@
+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,
+    cols: 28,
+    phase: 30,
+    row: 34,
+    minCol: 120,
+    pad: 24,
+    bandInset: 8,
+    clear: 12,
+    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) }];
+export function railState(rail, step) {
+    return rail.states[Math.min(step, rail.states.length - 1)] ?? rail.states[0];
+}
+export function layoutRail(fig, mapWidth) {
+    const steps = fig.steps ?? [];
+    const edges = new Map(fig.edges.map((e) => [edgeId(e), e]));
+    const layoutIds = new Set(order(fig.layout).map((o) => o.id));
+    const perStep = steps.map((s, si) => s.flow.map(toBeat).map((b, bi) => b.hops
+        .filter((h) => {
+        if (!edges.has(h.edge))
+            return false;
+        const e = edges.get(h.edge);
+        return layoutIds.has(e.from) && layoutIds.has(e.to);
+    })
+        .map((h) => ({
+        step: si,
+        beat: bi,
+        edge: h.edge,
+        back: h.back,
+        text: str(h.data) || str(edges.get(h.edge).label),
+        async: h.async === true,
+    }))));
+    const msgs = perStep.flat(2);
+    if (!msgs.length)
+        return null;
+    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 = (() => {
+        const text = `${msgs.length} of ${msgs.length}`;
+        return textWidth(text, 11) + 0.04 * 11 * text.length; // the frame style adds .04em letter spacing
+    })();
+    const widest = Math.max(...perStep.map((b, si) => {
+        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 }));
+        const bands = [];
+        const walk = (g, depth) => {
+            const ids = new Set(order(g).map((o) => o.id));
+            const inside = columns.filter((c) => ids.has(c.id));
+            if (g.label != null && inside.length) {
+                const l = Math.min(...inside.map((c) => c.x - c.w / 2)) + RAIL.bandInset + depth * 4;
+                const r = Math.max(...inside.map((c) => c.x + c.w / 2)) - RAIL.bandInset - depth * 4;
+                bands.push({ id: g.id ?? str(g.label), label: str(g.label), rect: { x: l, y: depth * RAIL.band, w: r - l, h: 0 } });
+            }
+            for (const c of g.children)
+                if (isGroup(c))
+                    walk(c, depth + (g.label != null ? 1 : 0));
+        };
+        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 };
+    };
+    const spread = (left, right) => Math.max(need, (mapWidth - left - right) / cols.length);
+    let [left, right] = [RAIL.pad, RAIL.pad];
+    let colW = spread(left, right);
+    let placed = place(left, right, colW);
+    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;
+    perStep.forEach((stepBeats, si) => {
+        const label = str(steps[si].label), messages = stepBeats.flat().length;
+        const after = (text) => RAIL.pad + labelW(text) + RAIL.clear;
+        const line = { open: after(label), folded: after(foldedLabel({ label, messages })), end: width - RAIL.pad - counterW - RAIL.clear };
+        rows.push({ kind: 'phase', step: si, label, messages, line });
+        for (const beatMsgs of stepBeats) {
+            const group = beatMsgs.length > 1 ? groups.push({ step: si, rows: [] }) - 1 : undefined;
+            for (const m of beatMsgs) {
+                const e = edges.get(m.edge);
+                const [a, b] = m.back ? [e.to, e.from] : [e.from, e.to];
+                const from = index.get(a), to = index.get(b);
+                const mid = (columns[from].x + columns[to].x) / 2;
+                const pill = m.text ? { x: mid - labelPillW(m.text) / 2, w: labelPillW(m.text) } : undefined;
+                if (group != null)
+                    groups[group].rows.push(rows.length);
+                rows.push({ kind: 'message', step: si, beat: m.beat, n: ++n, edge: m.edge, from, to, text: m.text, async: m.async, pill, group });
+            }
+        }
+    });
+    // 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) => {
+            const shown = !folds || row.kind === 'phase' || row.step === open;
+            const s = { y, shown };
+            if (shown)
+                y += row.kind === 'phase' ? RAIL.phase : RAIL.row;
+            return s;
+        });
+    });
+    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
+    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. */
+export function groupBox(rail, g) {
+    const xs = g.rows.flatMap((k) => {
+        const r = rail.rows[k];
+        if (r.kind !== 'message')
+            return [];
+        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
+    return { x, y: top, w: Math.max(...xs) + RAIL.inset - x, h: g.rows.length * RAIL.row - top * 2 };
+}

package/dist/scene.d.ts

@@ -0,0 +1,35 @@
+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. */
+export type TextRun = {
+    text: string;
+    fontSize: number;
+    room: number;
+    need?: number;
+    mono?: boolean;
+};
+export type SceneBox = {
+    id: string;
+    rect: Rect;
+    texts: TextRun[];
+};
+export type SceneEdge = {
+    id: string;
+    from: string;
+    to: string;
+    curve: [Pt, Pt, Pt, Pt];
+    label?: Rect;
+};
+/** `minFont` is the smallest reading text in px, before any scale. Group frames are not boxes. */
+export type Scene = {
+    width: number;
+    boxes: SceneBox[];
+    edges: SceneEdge[];
+    minFont: number;
+};
+/** 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. */
+export type Finding = {
+    rule: string;
+    severity: 'error' | 'warning';
+    ids: string[];
+    message: string;
+};

package/dist/scene.js

@@ -0,0 +1 @@
+export {};

package/dist/svg.d.ts

@@ -0,0 +1,28 @@
+import { type CheckOptions } from './check.ts';
+import type { Finding, Scene } from './scene.ts';
+export type { CheckOptions } from './check.ts';
+export type { Finding, Scene } from './scene.ts';
+export type * from './model.ts';
+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. */
+    speed?: number;
+    /** Space around the figure in px. Default: 24. */
+    padding?: number;
+    /** Colors, in place of `FlowProps.theme`. Default: `FlowProps.theme`. */
+    theme?: FigTheme;
+};
+/**
+ * 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.
+ */
+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. */
+export declare function check(fig: FlowProps, opts?: SvgOptions & CheckOptions): Finding[];