flowfig 0.9.0 → 0.11.0

package/dist/coverage.js

@@ -3,12 +3,12 @@ import { readFileSync } from 'node:fs';
 import { posix, resolve } from 'node:path';
 import { langOf, readFile } from './code.js';
 import { loadSpec, specOf } from './load.js';
-import { links, verifyReport } from './verify.js';
-const MARK = '<metadata id="figure-spec">';
+import { detailFindings, links, SPEC_MARK, verifyReport } from './verify.js';
 const globRe = (glob) => new RegExp(`^${glob
     .replace(/^\.\//, '')
     .replace(/[.+^${}()|[\]\\]/g, '\\$&')
     .replace(/\*\*\/|\*\*|\*|\?/g, (t) => (t === '**/' ? '(?:.*/)?' : t === '**' ? '.*' : t === '*' ? '[^/]*' : '[^/]'))}$`);
+const isTest = (p) => /(^|\/)(__tests__|tests|src\/test)\//.test(p) || /\.(test|spec)\.[^/]+$|(^|\/)test_[^/]*\.py$|_test\.(py|go)$|Tests?\.(java|cs)$/.test(p);
 const day = (t) => (t === Infinity ? 'now' : new Date(t * 1000).toISOString().slice(0, 10));
 const count = (k, word) => `${k} ${word}${k === 1 ? '' : 's'}`;
 function gitTimes(root) {
@@ -42,7 +42,7 @@ export function coverageReport({ root = process.cwd(), figures = '**/*.svg', ent
     const out = [];
     for (const figure of all.filter((p) => p.endsWith('.svg') && want.test(p))) {
         const text = readFileSync(resolve(root, figure), 'utf8');
-        if (!text.includes(MARK))
+        if (!text.includes(SPEC_MARK))
             continue;
         let fig;
         try {
@@ -54,8 +54,10 @@ export function coverageReport({ root = process.cwd(), figures = '**/*.svg', ent
         }
         const paths = [...new Set(links(fig).map((l) => posix.normalize(l.path)))];
         paths.forEach((p) => covered.add(p));
+        const lost = detailFindings(fig, root).length;
+        const lostText = lost ? `; ${lost} missing-detail` : '';
         if (!paths.length) {
-            out.push({ figure, state: 'none', detail: 'no source links' });
+            out.push({ figure, state: 'none', detail: `no source links${lostText}` });
             continue;
         }
         const { findings, coverage } = verifyReport(fig, { root, cache });
@@ -72,13 +74,14 @@ export function coverageReport({ root = process.cwd(), figures = '**/*.svg', ent
         const newer = time && paths.find((p) => time(p) > mine);
         out.push(newer
             ? { figure, state: 'stale', detail: `${newer} changed ${day(time(newer))}, figure ${day(mine)}` }
-            : { figure, state: 'ok', detail: `${coverage.boxesDefined} of ${coverage.boxes} boxes defined` });
+            : { figure, state: 'ok', detail: `${coverage.boxesDefined} of ${coverage.boxes} boxes defined${lostText}` });
     }
-    const code = all.filter((p) => langOf(p) != null);
+    const code = all.filter((p) => langOf(p) != null && !isTest(p));
     const report = { figures: out, git: time != null };
     if (entries) {
         const re = globRe(entries);
-        const matched = code.filter((p) => re.test(p));
+        const named = entries.replace(/^\.\//, '');
+        const matched = all.filter((p) => langOf(p) != null && re.test(p) && (p === named || !isTest(p)));
         report.entries = { glob: entries, total: matched.length, uncovered: matched.filter((p) => !covered.has(p)) };
     }
     else {

package/dist/diff.d.ts

@@ -7,3 +7,13 @@ export type Change = {
 };
 export declare function diff(before: FlowProps, after: FlowProps): Change[];
 export declare function formatDiff(changes: Change[], as: 'text' | 'md'): string;
+export type DiffMark = 'added' | 'removed' | 'changed';
+export type DiffMarks = {
+    boxes: Record<string, DiffMark>;
+    edges: Record<string, DiffMark>;
+    steps: number;
+};
+export declare function mergeFigures(before: FlowProps, after: FlowProps): {
+    figure: FlowProps;
+    marks: DiffMarks;
+};

package/dist/diff.js

@@ -1,4 +1,4 @@
-import { edgeId, isGroup, str, toBeat } from './model.js';
+import { edgeId, isGroup, laneColumns, nodes, str, toBeat } from './model.js';
 const show = (v) => (v == null ? '(none)' : `"${str(v)}"`);
 const fields = (a, b, names) => names.filter((k) => str(a[k]) !== str(b[k])).map((k) => `${String(k)} ${show(a[k])} -> ${show(b[k])}`);
 function compare(kind, before, after, fieldsOf) {
@@ -29,13 +29,13 @@ const messages = (fig) => {
     })));
     return new Map(ids.map((id) => [id, id]));
 };
+const boxes = (f) => {
+    const m = new Map();
+    const walk = (g, parent) => g.children.forEach((c) => (isGroup(c) ? walk(c, c.label != null ? str(c.label) : c.id) : m.set(c.id, { ...c, group: parent })));
+    walk(f.layout);
+    return m;
+};
 export function diff(before, after) {
-    const boxes = (f) => {
-        const m = new Map();
-        const walk = (g, parent) => g.children.forEach((c) => (isGroup(c) ? walk(c, c.label != null ? str(c.label) : c.id) : m.set(c.id, { ...c, group: parent })));
-        walk(f.layout);
-        return m;
-    };
     const edges = (f) => new Map(f.edges.map((e) => [edgeId(e), e]));
     const steps = (f) => new Map((f.steps ?? []).map((s) => [str(s.label), s]));
     const out = [
@@ -60,3 +60,133 @@ export function formatDiff(changes, as) {
     })
         .join('\n');
 }
+const key = (g) => g.id ?? (g.label != null ? str(g.label) : undefined);
+const cloneGroup = (g) => ({ ...g, children: g.children.map((c) => (isGroup(c) ? cloneGroup(c) : c)) });
+const ids = (g) => (isGroup(g) ? nodes(g).map((n) => n.id) : [g.id]);
+function find(root, hit) {
+    for (const [i, c] of root.children.entries()) {
+        if (hit(c))
+            return { parent: root, i };
+        const inner = isGroup(c) ? find(c, hit) : undefined;
+        if (inner)
+            return inner;
+    }
+}
+export function mergeFigures(before, after) {
+    const was = boxes(before);
+    const now = boxes(after);
+    const gone = (c) => ids(c).every((id) => !now.has(id));
+    const layout = cloneGroup(after.layout);
+    const placed = new Set();
+    const locate = (c) => find(layout, (x) => x === c || (isGroup(c) ? isGroup(x) && key(c) != null && key(x) === key(c) : !isGroup(x) && x.id === c.id));
+    const put = (item, frames, sibs, at) => {
+        const sides = [
+            ...sibs
+                .slice(0, at)
+                .reverse()
+                .map((s) => [s, 1]),
+            ...sibs.slice(at + 1).map((s) => [s, 0]),
+        ];
+        const next = after.layout.auto
+            ? undefined
+            : sides
+                .filter(([s]) => placed.has(s) || !gone(s))
+                .map(([s, off]) => ({ spot: locate(s), off }))
+                .find((x) => x.spot);
+        if (next)
+            next.spot.parent.children.splice(next.spot.i + next.off, 0, item);
+        else {
+            const frame = frames.map(locate).find(Boolean);
+            (frame ? frame.parent.children[frame.i] : layout).children.push(item);
+        }
+        placed.add(item);
+    };
+    const walk = (g, frames) => g.children.forEach((c, i, sibs) => {
+        if (isGroup(c) && !(c.label != null && gone(c) && !locate(c)))
+            walk(c, [c, ...frames]);
+        else if (gone(c))
+            put(c, frames, sibs, i);
+    });
+    walk(before.layout, [before.layout]);
+    const marks = { boxes: {}, edges: {}, steps: diff(before, after).filter((c) => c.kind !== 'box' && c.kind !== 'edge').length };
+    for (const [id, n] of now) {
+        const old = was.get(id);
+        if (!old)
+            marks.boxes[id] = 'added';
+        else if (fields(old, n, ['label', 'sub', 'shape', 'source', 'group']).length)
+            marks.boxes[id] = 'changed';
+    }
+    for (const id of was.keys())
+        if (!now.has(id))
+            marks.boxes[id] = 'removed';
+    const colAt = new Map();
+    if (after.lanes) {
+        const colsAfter = laneColumns(after);
+        const colsBefore = laneColumns(before);
+        const kept = [...now.keys()].filter((id) => was.has(id));
+        const slots = new Map();
+        for (const id of was.keys()) {
+            if (now.has(id))
+                continue;
+            const old = colsBefore.get(id);
+            const prev = kept
+                .filter((k) => colsBefore.get(k) < old)
+                .sort((a, b) => colsBefore.get(b) - colsBefore.get(a) || colsAfter.get(b) - colsAfter.get(a));
+            slots.set(id, { p: prev.length ? colsAfter.get(prev[0]) : -1, old });
+        }
+        const groups = [...new Map([...slots.values()].map((v) => [`${v.p}:${v.old}`, v])).values()].sort((a, b) => a.p - b.p || a.old - b.old);
+        for (const id of now.keys())
+            colAt.set(id, colsAfter.get(id) + groups.filter((g) => g.p < colsAfter.get(id)).length);
+        for (const [id, v] of slots) {
+            const i = groups.findIndex((g) => g.p === v.p && g.old === v.old);
+            colAt.set(id, v.p + 1 + groups.filter((g) => g.p < v.p).length + groups.slice(0, i).filter((g) => g.p === v.p).length);
+        }
+    }
+    const paint = (g) => ({
+        ...g,
+        children: g.children.map((c) => {
+            if (isGroup(c))
+                return paint(c);
+            const n = { ...c };
+            delete n.tone;
+            if (after.lanes)
+                n.at = colAt.get(c.id);
+            const old = was.get(c.id);
+            if (marks.boxes[c.id] === 'changed' && old) {
+                if (str(old.label) !== str(c.label))
+                    n.sub = `was "${str(old.label)}"`;
+                else if (old.group !== now.get(c.id).group)
+                    n.sub = old.group != null ? `was in "${old.group}"` : 'moved';
+            }
+            return n;
+        }),
+    });
+    const oldEdges = new Map(before.edges.map((e) => [edgeId(e), e]));
+    const newEdges = new Map(after.edges.map((e) => [edgeId(e), e]));
+    const same = (a, b) => b != null && a.from === b.from && a.to === b.to;
+    const edges = after.edges.map((e) => {
+        const id = edgeId(e);
+        const old = oldEdges.get(id);
+        if (!same(e, old))
+            marks.edges[id] = 'added';
+        else if (fields(old, e, ['label', 'source']).length) {
+            marks.edges[id] = 'changed';
+            if (str(old.label) !== str(e.label) && old.label != null)
+                return { ...e, label: e.label != null ? `${str(e.label)} (was ${str(old.label)})` : `(was ${str(old.label)})` };
+        }
+        return e;
+    });
+    for (const [id, e] of oldEdges) {
+        if (same(e, newEdges.get(id)))
+            continue;
+        const mid = newEdges.has(id) ? `${id} (old)` : id;
+        marks.edges[mid] = 'removed';
+        const gone = { ...e, id: mid };
+        delete gone.around;
+        edges.push(gone);
+    }
+    const figure = { ...after, layout: paint(layout), edges };
+    delete figure.steps;
+    delete figure.rail;
+    return { figure, marks };
+}

package/dist/geometry.d.ts

@@ -30,6 +30,7 @@ export type Routed = {
     room?: number;
     /** The px an elbow detour goes outside the boxes, for each side. */
     bleed?: Partial<Record<Around, number>>;
+    ends?: [string, string];
 };
 /** A rect that a route keeps clear of. `box` marks a box. */
 export type Avoid = Rect & {
@@ -37,6 +38,7 @@ export type Avoid = Rect & {
 };
 export declare const avoidOf: (boxes: Rect[], extra: Rect[], lanes: boolean) => Avoid[];
 type Around = 'above' | 'below' | 'left' | 'right';
+export declare const samples: (curve: [Pt, Pt, Pt, Pt]) => Pt[];
 export declare const hit: (curve: [Pt, Pt, Pt, Pt], boxes: Rect[], m: number) => Rect[];
 /** Routes edges between measured boxes as curved SVG paths. `elbow` draws right-angle paths; `stub` splits a cross-lane edge in two. */
 export declare function route(edges: {
@@ -46,6 +48,7 @@ export declare function route(edges: {
     around?: Around;
     sides?: [Side, Side];
     elbow?: boolean;
+    drop?: boolean;
     stub?: number[];
     bands?: [Rect | undefined, Rect | undefined];
     labelW?: number;
@@ -53,6 +56,7 @@ export declare function route(edges: {
     bands: Rect[];
     boxes: Rect[];
 }, pad?: number): Routed[];
+export declare const markSide: (id: string, mark: 'start' | 'end', routed: Routed[]) => Side;
 export declare const arcRoom: (routed: Routed[], way: Around) => number;
 export declare function labelAlong(r: Routed, w: number, boxes: Rect[], placed: Rect[], fig?: Rect, lines?: Pt[]): Pt;
 /** True if segment a-b crosses c-d. The ends of a-b are trimmed by 1.5 px. */

package/dist/geometry.js

@@ -52,9 +52,18 @@ const spanOf = (a, b, around) => {
     return [Math.min(p, q), Math.max(p, q)];
 };
 const SIDES = { above: ['t', 't'], below: ['b', 'b'], left: ['l', 'l'], right: ['r', 'r'] };
+export const samples = (curve) => {
+    const hull = curve.slice(1).reduce((s, q, k) => s + Math.hypot(q.x - curve[k].x, q.y - curve[k].y), 0);
+    const n = Math.max(32, Math.ceil(hull / 4));
+    return Array.from({ length: n + 1 }, (_, i) => bezier(curve, i / n));
+};
 export const hit = (curve, boxes, m) => {
-    const pts = Array.from({ length: 33 }, (_, i) => bezier(curve, i / 32));
-    return boxes.filter((r) => pts.some((q) => q.x > r.x - m && q.x < r.x + r.w + m && q.y > r.y - m && q.y < r.y + r.h + m));
+    const xs = curve.map((q) => q.x), ys = curve.map((q) => q.y);
+    const near = boxes.filter((r) => r.x + r.w + m > Math.min(...xs) && r.x - m < Math.max(...xs) && r.y + r.h + m > Math.min(...ys) && r.y - m < Math.max(...ys));
+    if (!near.length)
+        return [];
+    const pts = samples(curve);
+    return near.filter((r) => pts.some((q) => q.x > r.x - m && q.x < r.x + r.w + m && q.y > r.y - m && q.y < r.y + r.h + m));
 };
 /** Routes edges between measured boxes as curved SVG paths. `elbow` draws right-angle paths; `stub` splits a cross-lane edge in two. */
 export function route(edges, rects, tips = new Set(), avoid = [], area, lanes, pad = 24) {
@@ -68,7 +77,7 @@ export function route(edges, rects, tips = new Set(), avoid = [], area, lanes, p
         const others = avoid.filter((r) => r.box && !same(r, a) && !same(r, b));
         const plain = stacked ? (a.y < b.y ? ['b', 't'] : ['t', 'b']) : a.x < b.x ? ['r', 'l'] : ['l', 'r'];
         const past = hit(bend(sideMid(a, plain[0]), sideMid(b, plain[1]), plain[0]), others, -2);
-        const misses = (way, at) => [0.2, 0.5, 0.8].filter((f) => hit(arcLine(sideAt(a, SIDES[way][0], f), sideAt(b, SIDES[way][1], f), way, at), others, -2).length > 0)
+        const misses = (way, at) => [0.2, 0.5, 0.8].filter((f) => hit(arcLine(sideAt(a, SIDES[way][0], f), sideAt(b, SIDES[way][1], f), way, at), others, -6).length > 0)
             .length;
         const blocked = (way, at) => misses(way, at) === 3;
         let around = e.around;
@@ -81,7 +90,10 @@ export function route(edges, rects, tips = new Set(), avoid = [], area, lanes, p
             if (blocked(around, arc))
                 around = undefined;
         }
-        if (!around && !e.sides && !e.stub && !e.elbow && past.length) {
+        const down = e.drop && !hit(bend(sideMid(a, 'b'), sideMid(b, 't'), 'b'), others, -2).length;
+        if (e.drop && !around)
+            elbow = !down;
+        else if (!around && !e.sides && !e.stub && !e.elbow && past.length) {
             const ways = stacked ? ['left', 'right'] : ['above', 'below'];
             const tries = [];
             for (const share of [false, true])
@@ -107,7 +119,7 @@ export function route(edges, rects, tips = new Set(), avoid = [], area, lanes, p
             const [lo, hi] = spanOf(a, b, around);
             arcs.push({ way: around, lo, hi, at: arc });
         }
-        const [sa, sb] = e.sides ?? (e.stub ? ['r', 'l'] : around ? SIDES[around] : plain);
+        const [sa, sb] = e.sides ?? (e.stub ? ['r', 'l'] : down ? ['b', 't'] : around ? SIDES[around] : plain);
         picks.push({ ...e, plain, a, b, sa, sb, around, arc, elbow });
     }
     let anchor = new Map();
@@ -152,10 +164,10 @@ export function route(edges, rects, tips = new Set(), avoid = [], area, lanes, p
         if (!p.around || !s || !e)
             continue;
         const others = avoid.filter((r) => r.box && !same(r, p.a) && !same(r, p.b));
-        if (!hit(arcLine(s, e, p.around, p.arc), others, -2).length)
+        if (!hit(arcLine(s, e, p.around, p.arc), others, -6).length)
             continue;
         const [pa, pb] = p.plain;
-        const straight = hit(bend(sideMid(p.a, pa), sideMid(p.b, pb), pa), others, -2).length > 0;
+        const straight = hit(bend(sideMid(p.a, pa), sideMid(p.b, pb), pa), others, -6).length > 0;
         [p.sa, p.sb, p.around, p.arc, p.elbow, moved] = [pa, pb, undefined, undefined, p.elbow || straight, true];
     }
     if (moved)
@@ -183,7 +195,15 @@ export function route(edges, rects, tips = new Set(), avoid = [], area, lanes, p
     const outside = (way, { x, y }) => (way === 'above' ? y0 - y : way === 'below' ? y - y1 : way === 'left' ? x0 - x : x - x1);
     const roomOf = (way, at, curve, labelW) => Math.max(ARC - 6, lanes || !labelW ? outside(way, { x: at, y: at }) - 6 : outside(way, bezier(curve, 0.5)) + (upright(way) ? labelW / 2 : 9));
     const one = (p) => {
-        const s = anchor.get(p.id + ':s'), e = anchor.get(p.id + ':e');
+        const turn = !p.stub && p.elbow && p.sa === 'l';
+        const [s, e] = [anchor.get(p.id + (turn ? ':e' : ':s')), anchor.get(p.id + (turn ? ':s' : ':e'))];
+        const flip = (r) => {
+            if (!turn)
+                return r;
+            const pts = [...r.elbow].reverse();
+            const d = pts.slice(1).reduce((d, q, k) => d + (q.y === pts[k].y ? ` H ${q.x}` : ` V ${q.y}`), `M ${pts[0].x} ${pts[0].y}`);
+            return { ...r, d, curve: [...r.curve].reverse(), elbow: pts };
+        };
         if (p.stub) {
             const [ow, iw, sw] = p.stub;
             const [sb, tb] = p.bands ?? [];
@@ -336,7 +356,7 @@ export function route(edges, rects, tips = new Set(), avoid = [], area, lanes, p
         }
         if (p.elbow) {
             if (e.x - s.x < 16 && s.y === e.y) {
-                return { id: p.id, d: `M ${s.x} ${s.y} H ${e.x}`, mid: { x: (s.x + e.x) / 2, y: s.y }, curve: [s, s, e, e], elbow: [s, e] };
+                return flip({ id: p.id, d: `M ${s.x} ${s.y} H ${e.x}`, mid: { x: (s.x + e.x) / 2, y: s.y }, curve: [s, s, e, e], elbow: [s, e] });
             }
             const own = (r) => [p.a, p.b].some((q) => same(q, r));
             const all = avoid.filter((r) => !own(r));
@@ -347,14 +367,14 @@ export function route(edges, rects, tips = new Set(), avoid = [], area, lanes, p
                 const mx = s.x + 8, ex = e.x - 8, mid = (s.y + e.y) / 2;
                 const ys = Array.from({ length: Math.floor((y1 - y0 + 24) / 4) + 1 }, (_, i) => y0 - 12 + i * 4).sort((u, w) => Math.abs(u - mid) - Math.abs(w - mid));
                 const my = ys.find((y) => vClear(mx, s.y, y) && hClear(y, ex, mx, all) && vClear(ex, y, e.y)) ?? mid;
-                return {
+                return flip({
                     id: p.id,
                     d: `M ${s.x} ${s.y} H ${mx} V ${my} H ${ex} V ${e.y} H ${e.x}`,
                     mid: { x: (mx + ex) / 2, y: my },
                     curve: [s, { x: mx, y: my }, { x: ex, y: my }, e],
                     elbow: [s, { x: mx, y: s.y }, { x: mx, y: my }, { x: ex, y: my }, { x: ex, y: e.y }, e],
                     bleed: { above: room(y0 - my), below: room(my - y1) },
-                };
+                });
             }
             const mid = (s.x + e.x) / 2;
             const gap = Array.from({ length: Math.floor((e.x - s.x - 16) / 4) + 1 }, (_, i) => s.x + 8 + i * 4).sort((u, w) => Math.abs(u - mid) - Math.abs(w - mid));
@@ -383,7 +403,7 @@ export function route(edges, rects, tips = new Set(), avoid = [], area, lanes, p
                 }
                 if (best) {
                     const { x, y, ex } = best;
-                    return {
+                    return flip({
                         id: p.id,
                         d: `M ${s.x} ${s.y} H ${x} V ${y} H ${ex} V ${e.y} H ${e.x}`,
                         mid: { x: (x + ex) / 2, y },
@@ -395,18 +415,18 @@ export function route(edges, rects, tips = new Set(), avoid = [], area, lanes, p
                             above: room(y0 - y),
                             below: room(y - y1),
                         },
-                    };
+                    });
                 }
             }
             const x = mx ?? mid;
             const c1 = { x, y: s.y }, c2 = { x, y: e.y };
-            return {
+            return flip({
                 id: p.id,
                 d: `M ${s.x} ${s.y} H ${x} V ${e.y} H ${e.x}`,
                 mid: { x, y: (s.y + e.y) / 2 },
                 curve: [s, c1, c2, e],
                 elbow: [s, c1, c2, e],
-            };
+            });
         }
         if (p.around) {
             const curve = arcLine(s, e, p.around, p.arc);
@@ -456,15 +476,23 @@ export function route(edges, rects, tips = new Set(), avoid = [], area, lanes, p
     pills.push(...use.out);
     let k = 0;
     for (const [p, r] of done) {
-        if (p.labelW)
+        if (p.labelW) {
             r.mid = use.mids[k++];
+            const [l, rt] = [x0 - r.mid.x + p.labelW / 2, r.mid.x + p.labelW / 2 - x1];
+            r.bleed = { ...r.bleed, left: Math.max(r.bleed?.left ?? 0, l, 0), right: Math.max(r.bleed?.right ?? 0, rt, 0) };
+        }
         track(Array.from({ length: 33 }, (_, i) => bezier(r.curve, i / 32)));
     }
     for (const p of picks)
         if (p.stub)
             done.set(p, one(p));
-    return picks.map((p) => done.get(p));
+    return picks.map((p) => ({ ...done.get(p), ends: [`${p.from}:${p.sa}`, `${p.to}:${p.sb}`] }));
 }
+export const markSide = (id, mark, routed) => {
+    const used = new Set(routed.flatMap((r) => r.ends ?? []));
+    const order = mark === 'start' ? ['l', 't', 'b', 'r'] : ['r', 'b', 't', 'l'];
+    return order.find((s) => !used.has(`${id}:${s}`)) ?? order[0];
+};
 export const arcRoom = (routed, way) => Math.max(0, ...routed.map((r) => (r.around === way ? r.room : (r.bleed?.[way] ?? 0))));
 // The player pads its root by 4 px on a side with no detour.
 const PLAYER_PAD = 4;

package/dist/index.d.ts

@@ -5,4 +5,4 @@ export { LIGHT, DARK } from './model.ts';
  * The interactive player for one figure. Give it a `FlowProps` spec.
  * Use `toSvg` from `flowfig/svg` for a static animated SVG.
  */
-export declare function Flow({ layout, edges, steps: stepsIn, theme, speed, autoplay, check, rail: withRail, lanes, timeline, today, }: FlowProps): import("react").JSX.Element;
+export declare function Flow(props: FlowProps): import("react").JSX.Element;