flowfig 0.4.0 → 0.5.0

package/dist/model.js

@@ -1,4 +1,4 @@
-import { textWidth } from './text.js';
+import { textWidth, wrap } from './text.js';
 export const toBeat = (b) => {
     const isBeat = typeof b === 'object' && !Array.isArray(b) && !('edge' in b);
     const { edges, ...rest } = isBeat ? b : { edges: b };
@@ -110,6 +110,254 @@ export function laneColumns(fig) {
             cols.set(n.id, n.at);
     return cols;
 }
+/** The side of an SVG frame, and the width limits of a box with no card. The lane split measures with them. */
+export const FRAME_SIDE = 18, NODE_MIN_W = 100, NODE_MAX_W = 190;
+/** The gap between two blocks of wrapped lanes. */
+export const LANE_BLOCK_GAP = 40;
+/** The length of a stub line between a box and its pill, the clear space past a pill, and the room a lane grows by for a pill. */
+export const STUB = 12, STUB_CLEAR = 8, STUB_ROOM = 30;
+/** The width of a box as the SVG draws it, before a diamond adds its 70 px. */
+export function nodeWidth(item, carded) {
+    if (item.width != null)
+        return item.width;
+    if (carded)
+        return CARD_WIDTH;
+    const label = textWidth(str(item.label), 14) + 32;
+    const sub = textWidth(str(item.sub), 12) + 32;
+    return Math.min(NODE_MAX_W, Math.max(NODE_MIN_W, label, sub));
+}
+/** The room a diamond of size w by h gives a text line whose far edge sits `far` px from the center: the width of the outline there, less 8 px. */
+export const diamondRoom = (w, h, far) => w * Math.max(0, 1 - far / (h / 2)) - 8;
+/** The lines of a diamond with no card. The sub wraps to the room the outline gives its last line; the diamond grows taller by 15 px
+ * for each line until the lines fit. `dy` is the baseline of each line below the center, as the SVG draws it: the label sits 2 px
+ * above the center over a one-line sub, and 5 px below it with no sub. `far` is the distance from the center to the far edge of the text. */
+export function diamondLines(item, w) {
+    const sub = item.sub ? str(item.sub) : '';
+    for (let n = sub ? 1 : 0;; n++) {
+        const h = 62 + 15 * n;
+        const dy0 = n ? -2 - 7.5 * (n - 1) : 5;
+        const at = (dy, size) => Math.max(Math.abs(dy - 0.75 * size), dy + 0.25 * size);
+        const last = n ? at(dy0 + 15 * n, 12) : 0;
+        const lines = n ? wrap(sub, diamondRoom(w, h, last), 12) : [];
+        if (lines.length <= n || n >= 6)
+            return {
+                h,
+                label: { dy: dy0, far: at(dy0, 14) },
+                subs: lines.map((text, k) => ({ text, dy: dy0 + 15 * (k + 1), far: at(dy0 + 15 * (k + 1), 12) })),
+            };
+    }
+}
+/** The lane copies (`laneIndex@block`) that hold a stub end with no place clear of every edge path. A renderer grows each by
+ * STUB_ROOM and routes again: the pill then fits under or over its box, inside the band. Both renderers call it with their routes. */
+export function tightCopies(lanes, ends, edges, routed) {
+    const laneOf = (id) => lanes.findIndex((l) => l.id === id || l.children.some((b) => b.id === id));
+    const out = new Set();
+    for (const r of routed) {
+        const e = edges.find((x) => edgeId(x) === r.id);
+        const [fb, tb] = ends.get(r.id) ?? [];
+        if (!e || !r.stub)
+            continue;
+        if (r.stub.tight[0] && fb != null)
+            out.add(`${laneOf(e.from)}@${fb}`);
+        if (r.stub.tight[1] && tb != null)
+            out.add(`${laneOf(e.to)}@${tb}`);
+    }
+    return out;
+}
+/** The width of the label gutter of lanes and of a timeline: the widest track label plus the frame sides. */
+export const laneGutter = (lanes) => Math.max(0, ...lanes.map((l) => textWidth(str(l.label).toUpperCase(), 12))) + FRAME_SIDE * 2;
+/** The block of a time column, from the block starts of a plan. */
+export const laneBlock = (starts, c) => {
+    let k = 0;
+    while (k < starts.length - 2 && c >= starts[k + 1])
+        k++;
+    return k;
+};
+/** The pill texts of a cross-block edge: "label → Target" at the source, "from Source" at the target, and "→ Target", a
+ * shorter source text for a pill that has no place for the long one. */
+export const stubTexts = (label, from, to) => [
+    `${str(label) ? str(label) + ' ' : ''}→ ${str(to)}`,
+    `from ${str(from)}`,
+    ...(str(label) ? [`→ ${str(to)}`] : []),
+];
+/**
+ * The wrap of a lanes figure. If all the time columns do not fit `width` with text at `minText` or more, the lanes wrap like a
+ * line of text: block 1 holds columns 0..n-1, block 2 holds n..2n-1. n is the largest count that fits; it is 1 at least.
+ * The text test is the one `check` runs: the smallest text (11 px, or 10.5 px with a mono card row) times width / figure width.
+ * If the wrap cannot make the text readable, the lanes do not wrap: the smallest font is under `minText`, or `floor` (the least
+ * width of the rest of the figure, such as the rail) is already too wide.
+ * The blocks share the columns as evenly as they can, and a block holds 2 columns at least: if 2 do not fit, the lanes keep
+ * one block. An edge between two blocks becomes two stubs with pills. A pill takes no room of its own, so n depends on the boxes.
+ */
+export function lanePlan(fig, { width = 830, minText = 10, padding = 24, floor = 0 } = {}) {
+    const cols = laneColumns(fig);
+    const n = Math.max(-1, ...cols.values()) + 1;
+    const shown = (fig.steps ?? []).flatMap((s) => s.flow.flatMap((b) => Object.entries(toBeat(b).show ?? {})));
+    const carded = new Set(shown.map(([id]) => id));
+    const mono = shown.some(([, c]) => isRows(c) && c.some((r) => r.mono));
+    const colW = Array.from({ length: n }, () => 0);
+    const byId = new Map(nodes(fig.layout).map((b) => [b.id, b]));
+    for (const b of byId.values()) {
+        const c = cols.get(b.id);
+        colW[c] = Math.max(colW[c], nodeWidth(b, carded.has(b.id)) + (b.shape === 'decision' ? 70 : 0));
+    }
+    const font = mono ? 10.5 : 11;
+    const limit = (width * font) / minText;
+    const room = limit - padding * 2;
+    const lanes = fig.layout.children;
+    const laneOf = new Map(lanes.filter((l) => l.id != null).map((l) => [l.id, l]));
+    const gutter = laneGutter(lanes);
+    const plan = (count) => {
+        // count blocks share the n columns evenly; the first n % count blocks take one column more.
+        const starts = [0];
+        for (let k = 0; k < count; k++)
+            starts.push(starts[k] + Math.floor(n / count) + (k < n % count ? 1 : 0));
+        const colBlock = (c) => laneBlock(starts, c);
+        const blockOf = (id) => colBlock(cols.get(id));
+        const held = [...new Set([...byId.keys()].map(blockOf))].sort((a, b) => a - b);
+        const blocks = held.length ? held : [0];
+        const wrapped = blocks.length > 1;
+        // The blocks that show a lane: a wrapped block shows only the lanes with a box in it.
+        const showing = (l) => wrapped ? [...new Set(l.children.map((b) => blockOf(b.id)))].sort((a, b) => a - b) : blocks;
+        const stubs = new Map();
+        const ends = new Map();
+        const lost = [];
+        fig.edges.forEach((e) => {
+            const id = edgeId(e);
+            const [fl, tl] = [laneOf.get(e.from), laneOf.get(e.to)];
+            if (!(byId.has(e.from) || fl) || !(byId.has(e.to) || tl))
+                return;
+            // A lane source takes the last block at or before the target that shows it; a lane target the first at or after the source.
+            let miss = false;
+            const near = (l, k, after) => {
+                const ks = showing(l);
+                const hit = after ? ks.find((b) => b >= k) : ks.findLast((b) => b <= k);
+                if (hit != null)
+                    return hit;
+                miss = true;
+                return after ? ks.at(-1) : ks[0];
+            };
+            let fb, tb;
+            if (!fl)
+                fb = blockOf(e.from);
+            if (!tl)
+                tb = blockOf(e.to);
+            if (fl && tl)
+                fb = showing(fl)[0];
+            if (fl && !tl)
+                fb = near(fl, tb, false);
+            if (tl)
+                tb = near(tl, fb, true);
+            if (fb == null || tb == null)
+                return void (wrapped && lost.push(id));
+            if (miss)
+                lost.push(id);
+            ends.set(id, [fb, tb]);
+            if (fb === tb)
+                return;
+            const texts = stubTexts(e.label, (byId.get(e.from) ?? fl).label, (byId.get(e.to) ?? tl).label);
+            stubs.set(id, texts);
+        });
+        // A pill takes no room of its own: the route puts it in free space (route() in geometry.ts), so n depends on the boxes only.
+        // A label on an edge between two next columns of one block sits in the gap between them. A label too wide for the gap would
+        // cover a box, so that gap grows to the label plus 8 px. A label that fits keeps the gap of 0.4.0.
+        const label = Array.from({ length: n }, () => 0);
+        for (const e of fig.edges) {
+            const [a, b] = [cols.get(e.from), cols.get(e.to)];
+            if (e.label == null || a == null || b == null || Math.abs(a - b) !== 1 || colBlock(a) !== colBlock(b))
+                continue;
+            const w = labelPillW(str(e.label));
+            if (w - 2 > LANE_GAP)
+                label[Math.min(a, b)] = Math.max(label[Math.min(a, b)], w + 8);
+        }
+        const gaps = colW.map((_, c) => (c === starts[colBlock(c) + 1] - 1 ? FRAME_SIDE : Math.max(LANE_GAP, label[c])));
+        const per = Math.max(...starts.slice(1).map((e, k) => e - starts[k]));
+        const lead = Array.from({ length: count }, () => 0);
+        // A pill takes free room only: a gap next to a stub end grows for its pill while the block still fits the width. So the
+        // block count never depends on a pill. A pill with no room finds a free place in route() (geometry.ts).
+        const want = (text) => STUB + labelPillW(text) + STUB_CLEAR;
+        const fit = blocks.every((k) => widthOf(starts[k], starts[k + 1], gaps, 0) <= room);
+        const out = new Map(), inn = new Map();
+        const roomOut = new Set(), roomIn = new Set();
+        for (const [id, texts] of stubs) {
+            const e = fig.edges.find((x) => edgeId(x) === id);
+            const [a, b] = [cols.get(e.from), cols.get(e.to)];
+            if (a != null)
+                out.set(a, Math.max(out.get(a) ?? 0, want(texts[0])));
+            if (b != null)
+                inn.set(b, Math.max(inn.get(b) ?? 0, want(texts[1])));
+        }
+        for (const k of blocks) {
+            const [c0, end] = [starts[k], starts[k + 1]];
+            let free = room - widthOf(c0, end, gaps, 0);
+            const grow = (extra, apply) => {
+                if (extra > 0 && extra <= free) {
+                    free -= extra;
+                    apply();
+                }
+            };
+            grow(inn.get(c0) ?? 0, () => (lead[k] = inn.get(c0)));
+            if (!inn.has(c0) || lead[k])
+                roomIn.add(c0);
+            for (let c = c0; c < end; c++) {
+                const need = (out.get(c) ?? 0) + (c < end - 1 ? (inn.get(c + 1) ?? 0) : 0);
+                grow(need - gaps[c], () => (gaps[c] = need));
+                if (gaps[c] >= need)
+                    roomOut.add(c).add(-1 - (c + 1)); // -1 - c marks room before column c
+            }
+        }
+        // A stub end with no room beside its box makes its lane taller in that block: the pill then fits under the box, inside the band.
+        const laneIndex = (id) => lanes.findIndex((l) => l.id === id || l.children.some((b) => b.id === id));
+        const tall = new Set();
+        for (const [id] of stubs) {
+            const e = fig.edges.find((x) => edgeId(x) === id);
+            const [a, b] = [cols.get(e.from), cols.get(e.to)];
+            const [fb, tb] = ends.get(id);
+            if (a == null || !roomOut.has(a))
+                tall.add(`${laneIndex(e.from)}@${fb}`);
+            if (b == null || !(b === starts[tb] ? roomIn.has(b) : roomOut.has(-1 - b)))
+                tall.add(`${laneIndex(e.to)}@${tb}`);
+        }
+        const laneOfBox = new Map(lanes.flatMap((l) => l.children.map((b) => [b.id, l])));
+        const around = new Set(fig.edges
+            .filter((e) => {
+            const [a, b, l] = [cols.get(e.from), cols.get(e.to), laneOfBox.get(e.from)];
+            if (e.around || a == null || b == null || !l || l !== laneOfBox.get(e.to) || colBlock(a) !== colBlock(b))
+                return false;
+            return l.children.some((x) => cols.get(x.id) > Math.min(a, b) && cols.get(x.id) < Math.max(a, b));
+        })
+            .map(edgeId));
+        return [{ cols, starts, per, blocks, gutter, gaps, lead, ends, stubs, around, tall, lost }, fit];
+    };
+    const widthOf = (c, end, gaps, lead) => gutter + lead + colW.slice(c, end).reduce((a, w) => a + w, 0) + gaps.slice(c, end).reduce((a, g) => a + g, 0);
+    // The wrap only narrows the lanes. If the text stays too small at any width, keep one block, and check reports small-text.
+    if (font < minText || floor > limit)
+        return plan(1)[0];
+    // A block has 2 columns at least: one column per block reads as a list, not as lanes. If 2 do not fit, keep one block.
+    // The fit uses the boxes and the label gaps only, before a pill takes free room.
+    for (let count = 1; count <= Math.max(1, Math.floor(n / 2)); count++) {
+        const [p, fit] = plan(count);
+        if (fit)
+            return p;
+    }
+    return plan(1)[0];
+}
+/**
+ * The rect id that an edge end routes to in wrapped lanes. A box keeps its id. A lane has one band per block, so a lane end names
+ * the band in the block from the plan (`band` finds it). A stub end at a lane is a point inside that band: the source at the band
+ * end, past the room for its pill, and the target at the first column of the block. The function adds the rect it names to `rects`.
+ */
+export function laneEnd(plan, edge, id, start, band, rects) {
+    const k = plan.ends.get(edge)?.[start ? 0 : 1];
+    const b = k == null ? undefined : band(id, k);
+    if (plan.blocks.length < 2 || plan.cols.has(id) || !b)
+        return id;
+    const texts = plan.stubs.get(edge);
+    const key = texts ? `${edge}@${start ? 's' : 't'}` : `${id}@${k}`;
+    const x = start ? b.x + b.w - (STUB + labelPillW(texts?.[0] ?? '') + STUB_CLEAR) : b.x + plan.gutter + plan.lead[k];
+    rects[key] = texts ? { x, y: b.y, w: 0, h: b.h } : b;
+    return key;
+}
 /** Timeline constants, shared by both renderers: the bar height, the gap between rows, the least bar width, the milestone width,
  * the axis strip height and the axis width of the SVG. */
 export const TL_BAR_H = 28, TL_ROW_GAP = 8, TL_MIN_BAR = 24, TL_DIAMOND = 14, TL_AXIS_H = 28, TL_AXIS_W = 640;

package/dist/scene.d.ts

@@ -14,21 +14,28 @@ export type SceneBox = {
 };
 /** `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];
+    pts?: Pt[];
     label?: Rect;
     step?: number;
     behind?: true;
 };
 /** `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[];
     minFont: number;
+    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. */
 export type Finding = {

package/dist/svg.d.ts

@@ -15,6 +15,9 @@ export type SvgOptions = {
     padding?: number;
     /** Colors, in place of `FlowProps.theme`. 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`. */
+    width?: number;
+    minText?: number;
 };
 /**
  * The SVG string, and the scene it drew. The scene lets `flowfig check` test the same layout the SVG uses.