@liqweed/motion-kit 0.6.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,402 @@
1
+ /** @import { Scene } from "../scene.mjs" */
2
+ /** @import { Style } from "../style.mjs" */
3
+ // SPDX-License-Identifier: MIT
4
+ // Copyright (c) 2026 Ophir Radnitz
5
+ /**
6
+ * motion-kit · scene type "flowchart".
7
+ *
8
+ * Helps the viewer understand: a process with branches and joins, as drawn in
9
+ * a flowchart. Storyboard: the whole chart appears rank by rank in pending
10
+ * colours, so the structure is visible first; then the nodes fill accent one
11
+ * at a time in flow order, each incoming connector drawing on in accent just
12
+ * before its node fills, and an emphasis outline marks the node just reached.
13
+ *
14
+ * The layout is data: every node carries a `rank` (its layer along the flow)
15
+ * and a `pos` (its place across the flow, in node pitches), and an edge that
16
+ * spans ranks carries a waypoint per rank between (`via`). `motion-kit import`
17
+ * computes them once at build time from a Mermaid flowchart (lib/layout.mjs);
18
+ * this module only scales them to each format and never lays the graph out.
19
+ *
20
+ * Spec:
21
+ * { type: "flowchart", id, title, description,
22
+ * direction?: "down" | "up" | "right" | "left", // default "down"
23
+ * nodes: [{ id, label, rank, pos, shape?, detail? }], // 2–12 nodes
24
+ * edges: [{ from, to, label?, via?: [[rank, pos], …], dashed?, arrow? }], // 1–20 edges
25
+ * fontSize? }
26
+ * shape: "box" (default) | "round" | "pill" | "decision".
27
+ * Strings may be localized objects: { en: "...", nl: "..." }.
28
+ */
29
+ import { easeOut, easeStandard, progress } from "../motion.mjs";
30
+ import { FONT_MIN, maxFontSize, rectEdge } from "../parts.mjs";
31
+ import { FORMATS, localize, withId } from "../scene.mjs";
32
+ import { NEUTRAL, tok } from "../style.mjs";
33
+ import { drawOn, el, fade, num, polyline, text, translate } from "../svg.mjs";
34
+ import { estimateWidth, wrapLabel } from "../wrap.mjs";
35
+
36
+ export const FLOWCHART_SHAPES = ["box", "round", "pill", "decision"];
37
+ export const FLOWCHART_DIRECTIONS = ["down", "up", "right", "left"];
38
+
39
+ // Timeline (seconds). Steps settle: a step's fill ends at its `at`, and the
40
+ // next connector starts drawing BEAT later.
41
+ const ENTER_GAP = 0.1;
42
+ const ENTER = 0.4;
43
+ const DRAW = 0.35;
44
+ const FILL = 0.25;
45
+ const BEAT = 0.05;
46
+ const PERIOD = DRAW + FILL + BEAT;
47
+ const TAIL = 0.4;
48
+
49
+ const BOX_MAX = 220;
50
+ const GAP_Y = 20; // between neighbouring boxes across a horizontal flow
51
+ const MAX_LINES = 3;
52
+ const RING = 5; // emphasis outline distance from the node
53
+
54
+ /**
55
+ * @typedef {{ x: number, y: number }} Pt
56
+ * @typedef {{ x0: number, y0: number, x1: number, y1: number }} Box
57
+ */
58
+
59
+ /** @param {Box} a @param {Box} b */
60
+ const overlaps = (a, b) => a.x0 < b.x1 && b.x0 < a.x1 && a.y0 < b.y1 && b.y0 < a.y1;
61
+
62
+ /**
63
+ * Does segment a–b pass through box r? (Liang–Barsky clipping.)
64
+ * @param {Pt} a @param {Pt} b @param {Box} r
65
+ */
66
+ function segmentHits(a, b, r) {
67
+ let lo = 0;
68
+ let hi = 1;
69
+ const dx = b.x - a.x;
70
+ const dy = b.y - a.y;
71
+ for (const [p, q] of [[-dx, a.x - r.x0], [dx, r.x1 - a.x], [-dy, a.y - r.y0], [dy, r.y1 - a.y]]) {
72
+ if (p === 0) {
73
+ if (q < 0) return false;
74
+ } else {
75
+ const s = q / p;
76
+ if (p < 0) lo = Math.max(lo, s);
77
+ else hi = Math.min(hi, s);
78
+ if (lo > hi) return false;
79
+ }
80
+ }
81
+ return true;
82
+ }
83
+
84
+ /**
85
+ * @param {any} spec
86
+ * @param {{ format?: string, locale?: string }} [opts]
87
+ * @returns {Scene}
88
+ */
89
+ export function flowchart(spec, { format = "16:9", locale = "en" } = {}) {
90
+ const name = `flowchart "${spec.id}"`;
91
+ /** @param {string} why @returns {never} */
92
+ const fail = (why) => {
93
+ throw new Error(`${name}: ${why}`);
94
+ };
95
+ const f = FORMATS[format];
96
+ if (!f) throw new Error(`unknown format "${format}"`);
97
+ const nodes = spec.nodes;
98
+ const edges = spec.edges;
99
+ if (!Array.isArray(nodes) || nodes.length < 2 || nodes.length > 12) fail(`needs 2–12 nodes, got ${Array.isArray(nodes) ? nodes.length : "none"}`);
100
+ if (!Array.isArray(edges) || edges.length < 1 || edges.length > 20) fail(`needs 1–20 edges, got ${Array.isArray(edges) ? edges.length : "none"}`);
101
+ const direction = spec.direction ?? "down";
102
+ if (!FLOWCHART_DIRECTIONS.includes(direction)) fail(`direction must be one of ${FLOWCHART_DIRECTIONS.join(", ")}`);
103
+
104
+ /** @type {Map<string, number>} */
105
+ const index = new Map();
106
+ const labels = nodes.map((node, i) => {
107
+ if (!node || typeof node.id !== "string" || !node.id || index.has(node.id)) fail(`node ${i + 1} needs a unique non-empty id`);
108
+ index.set(node.id, i);
109
+ const label = localize(node.label, locale);
110
+ if (!label) fail(`node ${node.id} needs a label`);
111
+ if (!Number.isInteger(node.rank) || node.rank < 0) fail(`node ${node.id}: rank must be a whole number ≥ 0`);
112
+ if (!Number.isFinite(node.pos) || node.pos < 0) fail(`node ${node.id}: pos must be a number ≥ 0`);
113
+ if (node.shape !== undefined && !FLOWCHART_SHAPES.includes(node.shape)) fail(`node ${node.id}: shape must be one of ${FLOWCHART_SHAPES.join(", ")}`);
114
+ return label;
115
+ });
116
+ const minRank = Math.min(...nodes.map((n) => n.rank));
117
+ const maxRank = Math.max(...nodes.map((n) => n.rank));
118
+ const R = maxRank - minRank + 1;
119
+ const edgeLabels = edges.map((edge, i) => {
120
+ const what = `edge ${i + 1} (${edge?.from} → ${edge?.to})`;
121
+ if (!edge || !index.has(edge.from) || !index.has(edge.to)) fail(`${what} has an unknown from/to node`);
122
+ if (edge.from === edge.to) fail(`${what} is a self-loop; flowcharts draw none`);
123
+ for (const key of ["dashed", "arrow"]) if (edge[key] !== undefined && typeof edge[key] !== "boolean") fail(`${what}: ${key} must be boolean`);
124
+ const via = edge.via ?? [];
125
+ if (!Array.isArray(via) || via.some((p) => !Array.isArray(p) || p.length !== 2 || !Number.isInteger(p[0]) || !Number.isFinite(p[1]) || p[1] < 0)) fail(`${what}: via must be a list of [rank, pos] pairs`);
126
+ const ranks = [nodes[index.get(edge.from) ?? 0].rank, ...via.map((p) => p[0]), nodes[index.get(edge.to) ?? 0].rank];
127
+ const sign = Math.sign(ranks[1] - ranks[0]);
128
+ if (!sign || ranks.some((r, k) => k > 0 && r - ranks[k - 1] !== sign)) fail(`${what}: from, via and to must be on consecutive ranks (one waypoint per rank between)`);
129
+ return localize(edge.label, locale);
130
+ });
131
+ // Positions must leave room: boxes on a rank one pitch apart, waypoints
132
+ // clear of boxes.
133
+ for (let i = 0; i < nodes.length; i++) {
134
+ for (let j = i + 1; j < nodes.length; j++) {
135
+ if (nodes[i].rank === nodes[j].rank && Math.abs(nodes[i].pos - nodes[j].pos) < 1 - 1e-6) fail(`nodes ${nodes[i].id} and ${nodes[j].id} overlap on rank ${nodes[i].rank} (pos must differ by ≥ 1)`);
136
+ }
137
+ for (const edge of edges) {
138
+ for (const [r, p] of edge.via ?? []) {
139
+ if (r === nodes[i].rank && Math.abs(p - nodes[i].pos) < 0.5 - 1e-6) fail(`edge ${edge.from} → ${edge.to} passes through node ${nodes[i].id} on rank ${r}`);
140
+ }
141
+ }
142
+ }
143
+ const minPos = Math.min(...nodes.map((n) => n.pos), ...edges.flatMap((e) => (e.via ?? []).map((p) => p[1])));
144
+ const P = Math.max(...nodes.map((n) => n.pos), ...edges.flatMap((e) => (e.via ?? []).map((p) => p[1]))) - minPos;
145
+ const shapes = nodes.map((n) => n.shape ?? "box");
146
+ const anyEdgeLabel = edgeLabels.some(Boolean);
147
+
148
+ // Step order: along the flow, then across it.
149
+ const order = nodes.map((_, i) => i).sort((a, b) => nodes[a].rank - nodes[b].rank || nodes[a].pos - nodes[b].pos || a - b);
150
+ const stepOf = new Array(nodes.length);
151
+ order.forEach((v, k) => (stepOf[v] = k));
152
+
153
+ const vertical = direction === "down" || direction === "up";
154
+ const narrow = format === "tall" || (f.height > 0 && f.width / f.height < 0.8);
155
+ const tries = narrow || vertical ? [true, false] : [false, true];
156
+ const maxFs = maxFontSize(spec, f.height ? 20 : 16, name);
157
+
158
+ /**
159
+ * Place the chart with the flow vertical or horizontal at font size fs.
160
+ * Throws a reason when it does not fit.
161
+ * @param {boolean} down flow runs vertically
162
+ * @param {number} fs
163
+ */
164
+ function place(down, fs) {
165
+ const W = f.width;
166
+ // Phone widths keep a smaller margin and gap, so three boxes fit side by side.
167
+ const PAD = narrow ? 16 : 24;
168
+ const GAP_X = narrow ? 14 : 24; // between neighbouring boxes across a vertical flow
169
+ const lineH = fs * 1.25;
170
+ const labelW = Math.max(0, ...edgeLabels.map((s) => (s ? estimateWidth(s, fs) + 8 : 0)));
171
+ const labelH = lineH + 4;
172
+ const flowGap = down ? (anyEdgeLabel ? labelH + 28 : 36) : anyEdgeLabel ? labelW + 28 : 40;
173
+ const bw = Math.min(BOX_MAX, down ? (W - 2 * PAD - P * GAP_X) / (P + 1) : (W - 2 * PAD - (R - 1) * flowGap) / R);
174
+ const inset = fs * 0.8;
175
+ // A decision's pointed ends and a pill's round ends take one inset of the text width.
176
+ const chars = (/** @type {number} */ i) => Math.floor((bw - 16 - (shapes[i] === "decision" || shapes[i] === "pill" ? inset : 0)) / (fs * 0.56));
177
+ if (nodes.some((_, i) => chars(i) < 6)) throw new Error(`boxes would be ${Math.floor(bw)}px wide`);
178
+ const wrapped = labels.map((s, i) => wrapLabel(s, chars(i), MAX_LINES));
179
+ const bh = Math.max(...wrapped.map((l) => l.length)) * lineH + 18;
180
+ /** @type {number} */ let H;
181
+ /** @type {number} */ let flowPitch;
182
+ /** @type {number} */ let crossUnit;
183
+ if (down) {
184
+ crossUnit = P ? Math.min((W - 2 * PAD - bw) / P, bw + 64) : 0;
185
+ if (f.height) {
186
+ H = f.height;
187
+ flowPitch = Math.min((H - 2 * PAD - bh) / (R - 1), bh + 96);
188
+ if (flowPitch - bh < flowGap) throw new Error(`needs ${Math.ceil((R - 1) * (bh + flowGap) + bh + 2 * PAD)}px height`);
189
+ } else {
190
+ flowPitch = bh + Math.max(flowGap, 48);
191
+ H = Math.ceil(2 * PAD + (R - 1) * flowPitch + bh);
192
+ }
193
+ } else {
194
+ flowPitch = R > 1 ? Math.min((W - 2 * PAD - bw) / (R - 1), bw + flowGap + 64) : 0;
195
+ if (f.height) {
196
+ H = f.height;
197
+ crossUnit = P ? Math.min((H - 2 * PAD - bh) / P, bh + 48) : 0;
198
+ if (P && crossUnit < bh + GAP_Y) throw new Error(`needs ${Math.ceil(P * (bh + GAP_Y) + bh + 2 * PAD)}px height`);
199
+ } else {
200
+ crossUnit = bh + GAP_Y + 4;
201
+ H = Math.ceil(2 * PAD + P * crossUnit + bh);
202
+ }
203
+ }
204
+ const flowSpan = (R - 1) * flowPitch;
205
+ const crossSpan = P * crossUnit;
206
+ const reverse = direction === "up" || direction === "left";
207
+ /** @param {number} rank @param {number} pos @returns {Pt} */
208
+ const at = (rank, pos) => {
209
+ const r = reverse ? maxRank - rank : rank - minRank;
210
+ const along = r * flowPitch - flowSpan / 2;
211
+ const across = (pos - minPos) * crossUnit - crossSpan / 2;
212
+ return down ? { x: W / 2 + across, y: H / 2 + along } : { x: W / 2 + along, y: H / 2 + across };
213
+ };
214
+ const centres = nodes.map((n) => at(n.rank, n.pos));
215
+ const boxes = centres.map((c) => ({ x0: c.x - bw / 2, y0: c.y - bh / 2, x1: c.x + bw / 2, y1: c.y + bh / 2 }));
216
+
217
+ // Connectors: centre → waypoints → centre, trimmed to the boxes. Edges
218
+ // joining the same two nodes run side by side.
219
+ const pairCount = new Map();
220
+ const pairKey = (/** @type {any} */ e) => [e.from, e.to].sort().join("\u0000");
221
+ edges.forEach((e) => pairCount.set(pairKey(e), (pairCount.get(pairKey(e)) ?? 0) + 1));
222
+ const pairSeen = new Map();
223
+ const paths = edges.map((e) => {
224
+ const a = /** @type {number} */ (index.get(e.from));
225
+ const b = /** @type {number} */ (index.get(e.to));
226
+ const key = pairKey(e);
227
+ const k = pairSeen.get(key) ?? 0;
228
+ pairSeen.set(key, k + 1);
229
+ const shift = (k - ((pairCount.get(key) ?? 1) - 1) / 2) * 12;
230
+ const off = (/** @type {Pt} */ p) => (down ? { x: p.x + shift, y: p.y } : { x: p.x, y: p.y + shift });
231
+ const pts = [off(centres[a]), ...(e.via ?? []).map((/** @type {number[]} */ p) => off(at(p[0], p[1]))), off(centres[b])];
232
+ const start = rectEdge(pts[0].x, pts[0].y, bw / 2, bh / 2, pts[1], 2);
233
+ const end = rectEdge(pts[pts.length - 1].x, pts[pts.length - 1].y, bw / 2, bh / 2, pts[pts.length - 2], 3);
234
+ return [start, ...pts.slice(1, -1), end];
235
+ });
236
+ // Every connector stays clear of the boxes it does not join.
237
+ edges.forEach((e, i) => {
238
+ const ends = [index.get(e.from), index.get(e.to)];
239
+ const pts = paths[i];
240
+ boxes.forEach((box, j) => {
241
+ if (ends.includes(j)) return;
242
+ const inner = { x0: box.x0 + 2, y0: box.y0 + 2, x1: box.x1 - 2, y1: box.y1 - 2 };
243
+ if (pts.some((p, s) => s > 0 && segmentHits(pts[s - 1], p, inner))) throw new Error(`edge ${e.from} → ${e.to} crosses node ${nodes[j].id}`);
244
+ });
245
+ });
246
+ // Edge labels sit beside the first segment, on the outside of the turn.
247
+ /** @type {({ x: number, y: number, box: Box } | null)[]} */
248
+ const tags = edges.map((e, i) => {
249
+ const s = edgeLabels[i];
250
+ if (!s) return null;
251
+ const [a, b] = paths[i];
252
+ const m = { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 };
253
+ const w = estimateWidth(s, fs) + 4;
254
+ let box;
255
+ if (down) {
256
+ const slope = Math.abs(b.y - a.y) < 1e-6 ? 0 : Math.abs((b.x - a.x) / (b.y - a.y));
257
+ const reach = slope * labelH / 2 + 6;
258
+ const left = b.x < a.x - 0.5;
259
+ box = left ? { x0: m.x - reach - w, x1: m.x - reach } : { x0: m.x + reach, x1: m.x + reach + w };
260
+ box = { ...box, y0: m.y - labelH / 2, y1: m.y + labelH / 2 };
261
+ } else {
262
+ const slope = Math.abs(b.x - a.x) < 1e-6 ? 0 : Math.abs((b.y - a.y) / (b.x - a.x));
263
+ const reach = slope * w / 2 + 4;
264
+ const below = b.y > a.y + 0.5;
265
+ box = below ? { y0: m.y + reach, y1: m.y + reach + labelH } : { y0: m.y - reach - labelH, y1: m.y - reach };
266
+ box = { ...box, x0: m.x - w / 2, x1: m.x + w / 2 };
267
+ }
268
+ return { x: (box.x0 + box.x1) / 2, y: (box.y0 + box.y1) / 2, box };
269
+ });
270
+ tags.forEach((tag, i) => {
271
+ if (!tag) return;
272
+ const { box } = tag;
273
+ if (box.x0 < 2 || box.y0 < 2 || box.x1 > W - 2 || box.y1 > H - 2) throw new Error(`the label of edge ${edges[i].from} → ${edges[i].to} leaves the canvas`);
274
+ boxes.forEach((nb, j) => {
275
+ if (overlaps(box, { x0: nb.x0 - 3, y0: nb.y0 - 3, x1: nb.x1 + 3, y1: nb.y1 + 3 })) throw new Error(`the label of edge ${edges[i].from} → ${edges[i].to} covers node ${nodes[j].id}`);
276
+ });
277
+ tags.forEach((other, j) => {
278
+ if (j > i && other && overlaps(box, other.box)) throw new Error(`the labels of edges ${edges[i].from} → ${edges[i].to} and ${edges[j].from} → ${edges[j].to} overlap`);
279
+ });
280
+ paths.forEach((pts, j) => {
281
+ if (j !== i && pts.some((p, s) => s > 0 && segmentHits(pts[s - 1], p, box))) throw new Error(`the label of edge ${edges[i].from} → ${edges[i].to} crosses edge ${edges[j].from} → ${edges[j].to}`);
282
+ });
283
+ });
284
+ return { fs, W, H, bw, bh, inset, wrapped, centres, paths: paths.map((pts) => ({ pts, line: polyline(pts) })), tags };
285
+ }
286
+
287
+ let L;
288
+ let why = "";
289
+ for (const down of tries) {
290
+ for (let fs = maxFs; fs >= FONT_MIN && !L; fs--) {
291
+ try {
292
+ L = place(down, fs);
293
+ } catch (e) {
294
+ why ||= e instanceof Error ? e.message : String(e);
295
+ }
296
+ }
297
+ if (L) break;
298
+ }
299
+ if (!L) fail(`does not fit ${format} at ≥ ${FONT_MIN}px (${why}); use fewer nodes or ranks, shorter labels or a larger format`);
300
+ const G = L;
301
+
302
+ // Each connector turns accent at the later of its two nodes' steps: before
303
+ // that node fills when it is the target, while it fills when it is the source.
304
+ const edgeStep = edges.map((e) => Math.max(stepOf[index.get(e.from) ?? 0], stepOf[index.get(e.to) ?? 0]));
305
+ const backward = edges.map((e, i) => stepOf[index.get(e.to) ?? 0] !== edgeStep[i]);
306
+ const rankIndex = (/** @type {number} */ r) => r - minRank;
307
+ const START = ENTER_GAP * (R - 1) + ENTER + 0.1;
308
+ const stepAt = (/** @type {number} */ k) => START + DRAW + FILL + k * PERIOD;
309
+ const fillStart = (/** @type {number} */ k) => stepAt(k) - FILL;
310
+ const drawStart = (/** @type {number} */ k) => fillStart(k) - DRAW;
311
+ const duration = stepAt(nodes.length - 1) + TAIL;
312
+ const n = nodes.length;
313
+
314
+ /**
315
+ * Node outline for its shape, grown by `grow` px (the emphasis outline).
316
+ * @param {number} i @param {number} grow @param {number} radius the style's corner radius
317
+ * @param {Record<string, string | number>} attrs
318
+ */
319
+ function shapeAt(i, grow, radius, attrs) {
320
+ const c = G.centres[i];
321
+ const w = G.bw + 2 * grow;
322
+ const h = G.bh + 2 * grow;
323
+ const x = c.x - w / 2;
324
+ const y = c.y - h / 2;
325
+ if (shapes[i] === "decision") {
326
+ const k = Math.min(h / 2, G.inset + grow);
327
+ const pts = [[x + k, y], [x + w - k, y], [x + w, c.y], [x + w - k, y + h], [x + k, y + h], [x, c.y]];
328
+ return el("polygon", { points: pts.map(([px, py]) => `${num(px)},${num(py)}`).join(" "), "stroke-linejoin": "round", ...attrs });
329
+ }
330
+ const rx = shapes[i] === "pill" ? h / 2 : shapes[i] === "round" ? Math.min(h / 2, Math.max(radius, 14) + grow) : radius + grow;
331
+ return el("rect", { x, y, width: w, height: h, rx, ...attrs });
332
+ }
333
+
334
+ /** @param {number} t @param {{ style?: Style }} [ctx] */
335
+ function frame(t, { style = NEUTRAL } = {}) {
336
+ const enter = (/** @type {number} */ r) => progress(t, rankIndex(r) * ENTER_GAP, ENTER, easeOut);
337
+ const out = [];
338
+ const drawn = edges.map((_, i) => progress(t, backward[i] ? fillStart(edgeStep[i]) - 0.1 : drawStart(edgeStep[i]), backward[i] ? DRAW - 0.05 : DRAW, easeStandard));
339
+ edges.forEach((e, i) => {
340
+ const shown = Math.min(enter(nodes[index.get(e.from) ?? 0].rank), enter(nodes[index.get(e.to) ?? 0].rank));
341
+ if (shown <= 0) return;
342
+ const { pts, line } = G.paths[i];
343
+ const common = { d: line.d, fill: "none", "stroke-linecap": "round", "stroke-linejoin": "round", "stroke-dasharray": e.dashed ? "6 5" : undefined };
344
+ out.push(el("path", { ...common, stroke: tok("line"), "stroke-width": style.stroke, opacity: shown }));
345
+ // A dashed connector turns accent whole; a solid one draws on.
346
+ if (e.dashed) {
347
+ if (drawn[i] > 0) out.push(el("path", { ...common, stroke: tok("accent"), "stroke-width": style.stroke * 1.5, opacity: drawn[i] }));
348
+ } else {
349
+ const dash = drawOn(line.length, drawn[i]);
350
+ if (dash) out.push(el("path", { ...common, stroke: tok("accent"), "stroke-width": style.stroke * 1.5, ...dash }));
351
+ }
352
+ if (e.arrow !== false) {
353
+ const tip = pts[pts.length - 1];
354
+ const prev = pts[pts.length - 2];
355
+ const len = Math.hypot(tip.x - prev.x, tip.y - prev.y) || 1;
356
+ const ux = (tip.x - prev.x) / len;
357
+ const uy = (tip.y - prev.y) / len;
358
+ const d = `M${num(tip.x - 8 * ux - 5 * uy)} ${num(tip.y - 8 * uy + 5 * ux)} L${num(tip.x)} ${num(tip.y)} L${num(tip.x - 8 * ux + 5 * uy)} ${num(tip.y - 8 * uy - 5 * ux)}`;
359
+ const head = { d, fill: "none", "stroke-linecap": "round", "stroke-linejoin": "round" };
360
+ const on = progress(t, (backward[i] ? fillStart(edgeStep[i]) - 0.1 : drawStart(edgeStep[i])) + DRAW * 0.6, DRAW * 0.3, easeStandard);
361
+ out.push(fade(shown * (1 - on), {}, el("path", { ...head, stroke: tok("line"), "stroke-width": style.stroke })));
362
+ out.push(fade(on, {}, el("path", { ...head, stroke: tok("accent"), "stroke-width": style.stroke * 1.5 })));
363
+ }
364
+ const tag = G.tags[i];
365
+ if (tag) {
366
+ const attrs = { x: tag.x, y: tag.y, "text-anchor": "middle", "dominant-baseline": "central", "font-size": G.fs, "font-weight": 500 };
367
+ out.push(fade(shown, {}, fade(1 - drawn[i], {}, text({ ...attrs, fill: tok("muted") }, edgeLabels[i])), fade(drawn[i], {}, text({ ...attrs, fill: tok("ink") }, edgeLabels[i]))));
368
+ }
369
+ });
370
+ nodes.forEach((node, i) => {
371
+ const shown = enter(node.rank);
372
+ if (shown <= 0) return;
373
+ const active = progress(t, fillStart(stepOf[i]), FILL, easeStandard);
374
+ const c = G.centres[i];
375
+ const label = (/** @type {string} */ fill) => text({ x: c.x, y: c.y, "text-anchor": "middle", "dominant-baseline": "central", "font-size": G.fs, "font-weight": 500, fill }, G.wrapped[i]);
376
+ const pending = el("g", {}, shapeAt(i, 0, style.radius, { fill: tok("surface"), stroke: tok("line"), "stroke-width": style.stroke }), label(tok("ink")));
377
+ const on = el("g", {}, shapeAt(i, 0, style.radius, { fill: tok("accent"), stroke: tok("accent"), "stroke-width": style.stroke }), label(tok("onAccent")));
378
+ const dy = (1 - shown) * 8;
379
+ out.push(fade(shown, { transform: dy > 0.004 ? translate(0, dy) : undefined }, fade(1 - active, {}, pending), fade(active, {}, on)));
380
+ });
381
+ // Emphasis: an outline on the node reached last.
382
+ order.forEach((v, k) => {
383
+ const opacity = progress(t, fillStart(k), FILL, easeOut) * (k + 1 < n ? 1 - progress(t, drawStart(k + 1), FILL, easeStandard) : 1);
384
+ if (opacity > 0) out.push(fade(opacity, {}, shapeAt(v, RING, style.radius, { fill: "none", stroke: tok("emphasis"), "stroke-width": style.stroke * 1.5 })));
385
+ });
386
+ return out.join("");
387
+ }
388
+
389
+ return {
390
+ id: `${spec.id}-${format.replace(":", "x")}`,
391
+ type: "flowchart",
392
+ format,
393
+ locale,
394
+ width: G.W,
395
+ height: G.H,
396
+ duration,
397
+ title: localize(spec.title, locale),
398
+ description: localize(spec.description, locale),
399
+ steps: order.map((v, k) => withId({ at: stepAt(k), label: labels[v], detail: localize(nodes[v].detail, locale) }, nodes[v].id)),
400
+ frame,
401
+ };
402
+ }
@@ -10,6 +10,7 @@
10
10
  * export is (opts) → scene (see examples/custom-*.scene.mjs).
11
11
  */
12
12
  import { validateScene } from "../scene.mjs";
13
+ import { flowchart } from "./flowchart.mjs";
13
14
  import { hubSpoke } from "./hub-spoke.mjs";
14
15
  import { sequence } from "./sequence.mjs";
15
16
  import { stack } from "./stack.mjs";
@@ -23,6 +24,7 @@ export const SCENE_TYPES = {
23
24
  stack,
24
25
  "state-machine": walk,
25
26
  "request-journey": walk,
27
+ flowchart,
26
28
  };
27
29
 
28
30
  export function createScene(spec, opts = {}) {
@@ -53,8 +53,11 @@ from the system's package manager (`brew install ffmpeg`, `apt install ffmpeg`).
53
53
  Write the spec, then render the step contact sheet and show it:
54
54
  `motion-kit export spec.json -o <scratch>/sb --png --qc` → open `index.html`
55
55
  or show the PNGs. Get a yes on the *story* before polishing.
56
- 3. **Build.** Spec-driven types first (`sequence`, `hub-spoke`, `timeline`, `stack`). Only write a
57
- custom scene module when no type fits (`references/custom-scenes.md`).
56
+ 3. **Build.** Spec-driven types first (`sequence`, `hub-spoke`, `timeline`, `stack`,
57
+ `state-machine`, `request-journey`, `flowchart`). The user has a Mermaid
58
+ flowchart? `motion-kit import flow.mmd --out flow.json` writes the spec
59
+ (layout computed once). Only write a custom scene module when no type fits
60
+ (`references/custom-scenes.md`).
58
61
  4. **Gate.** `motion-kit check spec.json` must pass in every format/locale
59
62
  shipped: deterministic, settled steps, rounded numbers, token-only colours,
60
63
  escaped labels, labels fit, holds the final frame.
@@ -84,12 +87,14 @@ from the system's package manager (`brew install ffmpeg`, `apt install ffmpeg`).
84
87
  mk() { node "$MK/cli/motion-kit.mjs" "$@"; }
85
88
  mk types; mk formats
86
89
  mk check diagram.json # all formats × locales
90
+ mk import flow.mmd -o flow.json # Mermaid flowchart → sequence or flowchart spec, then checked
87
91
  mk check flow.scene.mjs -l en -l nl --options labels.mjs # a custom module, with its text from the caller
88
92
  mk build diagram.json -o diagram.html -f wide -l nl # Craft Page / standalone
89
93
  mk export diagram.json -o out/ --png --qc # slides + review sheet
90
94
  mk bake diagram.json -o diagram.svg -f wide # zero-JS animated SVG
91
95
  mk video diagram.json -f 9:16 -o reel.mp4 --sheet sheet.png
92
96
  mk vendor <repo>/components/motion-kit --adapter slidev # or astro / page / element
97
+ mk outdated <repo>/components/motion-kit # newer release on npm? exit 1 + the re-vendor command
93
98
  node <repo>/components/motion-kit/check.mjs flow.scene.mjs -l en -l nl --style brand.json --options labels.mjs # the vendored gate, same checks
94
99
  ```
95
100
 
@@ -9,8 +9,8 @@ Checked Nov 2026. Re-verify licences before commercial use.
9
9
  | **GSAP** (incl. DrawSVG, MorphSVG, MotionPath, SplitText) | free incl. commercial since 3.13 (not for competing no-code builders) | Rich page motion, morphing, text splitting | Paused timelines are seekable (`tl.seek(t)`), so determinism holds. ~70 KB must be inlined for Craft Pages. Use for website polish; keep explainers in motion-kit |
10
10
  | **Motion Canvas / Revideo** | MIT | Hand-crafted technical explainer *videos* with generator timelines | Good for one-off videos; no live-page reuse |
11
11
  | **Manim CE** | MIT | Mathematics and science visuals, equations | Python; video only |
12
- | **Mermaid** | MIT | Static diagrams from text; quick structure | Use as *input notation* (flowchart/state), then lay out and animate in motion-kit |
13
- | **ELK.js / dagre** | EPL-2.0 / MIT | Automatic layout of larger graphs | Run at build time in Node, store coordinates in the spec |
12
+ | **Mermaid** | MIT | Static diagrams from text; quick structure | Flowcharts import directly: `motion-kit import flow.mmd` (layout at build time). State diagrams: write a `state-machine` spec |
13
+ | **ELK.js / dagre** | EPL-2.0 / MIT | Automatic layout of graphs larger than a scene's 12 nodes | `motion-kit import` has its own small layered layout; for more, run one at build time in Node and store coordinates in the spec |
14
14
  | **Lottie / Rive** | MIT runtimes | Designer-authored animation assets | Embed as media; not data-driven |
15
15
  | **resvg-js** | MPL-2.0 | SVG → PNG without a browser | motion-kit's rasterizer |
16
16
 
@@ -138,6 +138,65 @@ separate enclosures with the same name. Hops with `async: true` stay dashed,
138
138
  including after activation. Return paths are ordinary hops in the opposite
139
139
  direction. See `examples/checkout.json`.
140
140
 
141
+ ### `flowchart`: a process with branches and joins
142
+
143
+ Usually imported from Mermaid rather than written by hand:
144
+
145
+ ```bash
146
+ motion-kit import flow.mmd --out flow.json # also checks flow.json in every format (or only the --format ones)
147
+ ```
148
+
149
+ ```json
150
+ { "type": "flowchart", "id": "pull-request",
151
+ "title": "…", "description": "…",
152
+ "direction": "down", // "up", "right", "left"
153
+ "nodes": [ { "id": "ci", "label": "CI passes?", "shape": "decision", "rank": 1, "pos": 0.25 }, … ],
154
+ "edges": [ { "from": "ci", "to": "fix", "label": "No" },
155
+ { "from": "a", "to": "d", "via": [[1, 0.75]] },
156
+ { "from": "login", "to": "auth", "dashed": true }, … ] }
157
+ ```
158
+
159
+ 2–12 nodes, 1–20 edges. The layout is stored in the spec: `rank` is a node's
160
+ layer along the flow (whole numbers), `pos` its place across the flow in node
161
+ pitches (nodes on one rank ≥ 1 apart), and an edge spanning several ranks has
162
+ one `via` waypoint per rank between. The importer computes these once at build
163
+ time (`lib/layout.mjs`, a layered layout); the scene type only scales them to
164
+ each format, so the runtime never lays a graph out. Shapes: `box` (default),
165
+ `round`, `pill`, `decision`. Edges may carry a short one-line `label`, be
166
+ `dashed`, or have no arrowhead (`"arrow": false`). Nodes may carry `detail`.
167
+
168
+ Storyboard: the chart appears rank by rank in pending colours → nodes fill
169
+ accent one at a time in flow order (rank, then across), each incoming connector
170
+ drawing on in accent just before its node fills → an emphasis outline marks the
171
+ node just reached. A connector that points back (a retry loop) turns accent
172
+ while its source fills. Steps = one per node; step ids are the node ids.
173
+ `direction` is the flow in wide formats; 9:16 and `tall` flow downward, and a
174
+ format falls back to the other axis when the preferred one does not fit. Throws
175
+ when labels, edge labels or connectors would collide: shorter labels, fewer
176
+ ranks or a larger format. See `examples/pull-request.mmd` and its spec.
177
+
178
+ ### Importing Mermaid
179
+
180
+ `motion-kit import <file.mmd | ->` turns a Mermaid flowchart into a spec
181
+ (stdout, or `--out`; `--id`, `--title`, `--description` override what the
182
+ chart says). A plain chain (each node one link in and one out, no link labels,
183
+ no dotted links) becomes a `sequence`; anything else becomes a `flowchart`.
184
+
185
+ - Read: `flowchart`/`graph` with `TB`/`TD`/`BT`/`LR`/`RL`; `[box]`, `(round)`,
186
+ `([pill])`, `{decision}`, `{{decision}}`; quoted labels, `<br>`, `#quot;`
187
+ codes; `-->`, `---`, `-.->`, `-.-`, `==>`, `===` with `|text|` or
188
+ `-- text -->` labels; chains and `&` groups; `accTitle`, `accDescr`, a
189
+ front-matter `title`. The title and description become the scene's
190
+ accessible name and description; without `accDescr` the description lists
191
+ every link in words.
192
+ - Ignored with a warning (colours come from the motion-kit style): `classDef`,
193
+ `class`, `style`, `linkStyle`, `:::name`, `%%{init}%%`, front-matter `config`.
194
+ - Errors naming the line: subgraphs and `direction`, `click`, other shapes
195
+ (circle, database, subroutine, parallelogram, …), `@{ shape }`, two-way,
196
+ circle and cross links, `~~~`, link ids, self-loops, markdown strings, HTML
197
+ in labels, and more than 12 nodes or 20 links. Sequence, state and ER
198
+ diagrams are not converted.
199
+
141
200
  ## Storyboards for types not built yet
142
201
 
143
202
  Build these as custom scenes (`custom-scenes.md`) first. Promote one to a type
@@ -149,7 +208,7 @@ once it has been used twice.
149
208
  | `comparison` | option A vs B on criteria | two columns appear → criteria rows fill one at a time → the deciding row emphasised |
150
209
  | `funnel` / `data-flow` | volume or data narrowing/merging | sources appear → streams draw on and merge → result fills |
151
210
 
152
- Auto-layout for larger graphs: lay out with ELK.js or dagre once (Node, at
153
- build time), store coordinates in the spec, then animate. Mermaid flowchart or
154
- state syntax can serve as input notation (parse nodes/edges, recompute layout).
155
- Don't convert sequence or ER diagrams lossily.
211
+ Auto-layout happens at build time, never in `frame()`: `motion-kit import`
212
+ lays out Mermaid flowcharts as `flowchart` specs (above). State diagrams are
213
+ not imported yet; write a `state-machine` spec. Don't convert sequence or ER
214
+ diagrams lossily.