@liqweed/motion-kit 0.3.0 → 0.5.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.
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +1 -1
- package/README.md +63 -10
- package/adapters/astro/AnimatedDiagram.astro +150 -24
- package/adapters/element/README.md +6 -1
- package/adapters/element/motion-diagram.mjs +4 -3
- package/adapters/page/README.md +8 -2
- package/adapters/slidev/AnimatedDiagram.vue +24 -0
- package/cli/motion-kit.mjs +85 -81
- package/docs/spec/technique.md +166 -63
- package/examples/custom-pulse.scene.mjs +3 -0
- package/examples/incident.json +18 -0
- package/examples/web-stack.json +17 -0
- package/lib/build.mjs +26 -12
- package/lib/bundle.mjs +9 -2
- package/lib/check.mjs +219 -15
- package/lib/export.mjs +135 -16
- package/lib/gate.mjs +90 -0
- package/lib/load.mjs +49 -19
- package/package.json +6 -3
- package/runtime/bake.mjs +18 -4
- package/runtime/kit.mjs +59 -0
- package/runtime/links.mjs +314 -0
- package/runtime/page.mjs +52 -0
- package/runtime/parts.mjs +15 -0
- package/runtime/patch.mjs +297 -0
- package/runtime/player.mjs +334 -130
- package/runtime/scene.mjs +82 -5
- package/runtime/style.mjs +64 -16
- package/runtime/types/hub-spoke.mjs +7 -7
- package/runtime/types/index.mjs +4 -0
- package/runtime/types/sequence.mjs +5 -5
- package/runtime/types/stack.mjs +227 -0
- package/runtime/types/timeline.mjs +405 -0
- package/skills/animated-diagram/SKILL.md +30 -7
- package/skills/animated-diagram/references/custom-scenes.md +64 -9
- package/skills/animated-diagram/references/interactivity.md +150 -15
- package/skills/animated-diagram/references/qc.md +5 -2
- package/skills/animated-diagram/references/scene-types.md +45 -2
- package/skills/animated-diagram/references/styles.md +45 -5
- package/skills/animated-diagram/references/targets.md +7 -5
- package/skills/animated-diagram/references/technique.md +14 -4
- package/skills/motion-render/SKILL.md +31 -8
- package/skills/motion-render/references/formats.md +8 -8
- package/skills/project-logo/SKILL.md +15 -4
- package/styles/neutral.json +2 -2
package/runtime/scene.mjs
CHANGED
|
@@ -9,18 +9,38 @@
|
|
|
9
9
|
* id, width, height, // viewBox
|
|
10
10
|
* duration, // seconds until the final state
|
|
11
11
|
* title, description, // accessible name + description
|
|
12
|
-
* steps: [{ at, label, detail? }], // build steps; last = finished diagram
|
|
13
|
-
* frame(t) → string
|
|
12
|
+
* steps: [{ at, label, detail?, id? }], // build steps; last = finished diagram
|
|
13
|
+
* frame(t, { idPrefix }) → string // inner SVG markup at time t
|
|
14
14
|
* }
|
|
15
15
|
*
|
|
16
16
|
* frame(t) may depend on nothing but t and the scene's own constants: no Date,
|
|
17
17
|
* no Math.random(), no performance.now(), no state from earlier frames. That is
|
|
18
18
|
* what lets a player jump anywhere, an exporter write exactly the frame a slide
|
|
19
19
|
* needs, and a video renderer sample frame f at t = f / fps.
|
|
20
|
+
*
|
|
21
|
+
* Every render passes an `idPrefix` unique to that instance on the page. A
|
|
22
|
+
* scene that defines ids (clip paths, gradients, masks, markers, filters) MUST
|
|
23
|
+
* build them from it (`${idPrefix}-clip`), so two instances never share an id.
|
|
20
24
|
*/
|
|
21
25
|
import { esc, num } from "./svg.mjs";
|
|
22
26
|
import { normalizeStyle, cssVars, resolveTokens } from "./style.mjs";
|
|
23
27
|
|
|
28
|
+
/**
|
|
29
|
+
* One build step. `at` is a settled time; `id` is an optional stable name that
|
|
30
|
+
* page scripts can use instead of the step's index.
|
|
31
|
+
* @typedef {{ at: number, label: string, detail?: string, id?: string }} Step
|
|
32
|
+
*/
|
|
33
|
+
/**
|
|
34
|
+
* What `renderSvg` passes to `frame` besides the time.
|
|
35
|
+
* @typedef {{ idPrefix: string }} FrameContext
|
|
36
|
+
*/
|
|
37
|
+
/**
|
|
38
|
+
* An animated diagram as a pure function of time (see the module comment).
|
|
39
|
+
* `contrastPairs`: token pairs the scene draws beyond CONTRAST_PAIRS
|
|
40
|
+
* (runtime/style.mjs), which the gate checks the style against.
|
|
41
|
+
* @typedef {{ id: string, width: number, height: number, duration: number, title: string, description: string, steps: Step[], frame: (t: number, ctx: FrameContext) => string, stepLabelsInFrame?: boolean, contrastPairs?: { fg: string, bg: string, min: number, use?: string }[], type?: string, format?: string, locale?: string }} Scene
|
|
42
|
+
*/
|
|
43
|
+
|
|
24
44
|
/** Formats: name → viewBox. Layouts are computed per format, never cropped. */
|
|
25
45
|
export const FORMATS = {
|
|
26
46
|
"16:9": { width: 960, height: 540 },
|
|
@@ -41,21 +61,72 @@ export function localize(value, locale = "en") {
|
|
|
41
61
|
return first;
|
|
42
62
|
}
|
|
43
63
|
|
|
64
|
+
/**
|
|
65
|
+
* A valid, CSS-safe id token from any string: letters, digits, "_" and "-",
|
|
66
|
+
* starting with a letter. Ids that already are one come back unchanged.
|
|
67
|
+
* @param {unknown} value
|
|
68
|
+
* @returns {string}
|
|
69
|
+
*/
|
|
70
|
+
export function safeId(value) {
|
|
71
|
+
const s = String(value).replace(/[^A-Za-z0-9_-]+/g, "-");
|
|
72
|
+
return /^[A-Za-z]/.test(s) ? s : `mk-${s}`;
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* Throw unless `scene` meets the contract; returns it unchanged.
|
|
77
|
+
* @template {Scene} S
|
|
78
|
+
* @param {S} scene
|
|
79
|
+
* @returns {S}
|
|
80
|
+
*/
|
|
44
81
|
export function validateScene(scene) {
|
|
45
82
|
for (const k of ["id", "width", "height", "duration", "title", "description", "steps", "frame"]) {
|
|
46
83
|
if (scene[k] === undefined || scene[k] === "") throw new Error(`scene ${scene.id ?? "?"} is missing "${k}"`);
|
|
47
84
|
}
|
|
48
85
|
if (!scene.steps.length) throw new Error(`scene ${scene.id}: needs at least one step`);
|
|
49
86
|
let prev = -Infinity;
|
|
87
|
+
const ids = new Set();
|
|
50
88
|
for (const s of scene.steps) {
|
|
51
89
|
if (!(s.at > prev)) throw new Error(`scene ${scene.id}: steps must be strictly increasing in time`);
|
|
52
90
|
if (s.at > scene.duration + 1e-9) throw new Error(`scene ${scene.id}: step "${s.label}" is after the duration`);
|
|
53
91
|
if (!s.label) throw new Error(`scene ${scene.id}: every step needs a label`);
|
|
92
|
+
if (s.id !== undefined) {
|
|
93
|
+
if (typeof s.id !== "string" || !s.id) throw new Error(`scene ${scene.id}: step "${s.label}" has an id that is not a non-empty string`);
|
|
94
|
+
if (ids.has(s.id)) throw new Error(`scene ${scene.id}: two steps share the id "${s.id}"`);
|
|
95
|
+
ids.add(s.id);
|
|
96
|
+
}
|
|
54
97
|
prev = s.at;
|
|
55
98
|
}
|
|
56
99
|
return scene;
|
|
57
100
|
}
|
|
58
101
|
|
|
102
|
+
/**
|
|
103
|
+
* `step` with `id` added when one is given (scene types pass a spec's ids on).
|
|
104
|
+
* @template {Step} S
|
|
105
|
+
* @param {S} step
|
|
106
|
+
* @param {unknown} id
|
|
107
|
+
* @returns {S}
|
|
108
|
+
*/
|
|
109
|
+
export function withId(step, id) {
|
|
110
|
+
return id == null ? step : { ...step, id: /** @type {string} */ (id) };
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* The index of a step given by index or by id. Throws RangeError for an
|
|
115
|
+
* index outside the steps, or an id no step has.
|
|
116
|
+
* @param {{ steps: Step[] }} scene
|
|
117
|
+
* @param {number | string} ref
|
|
118
|
+
* @returns {number}
|
|
119
|
+
*/
|
|
120
|
+
export function stepIndex(scene, ref) {
|
|
121
|
+
if (typeof ref === "string") {
|
|
122
|
+
const i = scene.steps.findIndex((s) => s.id === ref);
|
|
123
|
+
if (i < 0) throw new RangeError(`Unknown step id: ${ref}`);
|
|
124
|
+
return i;
|
|
125
|
+
}
|
|
126
|
+
if (!Number.isInteger(ref) || ref < 0 || ref >= scene.steps.length) throw new RangeError(`Invalid step index: ${ref}`);
|
|
127
|
+
return ref;
|
|
128
|
+
}
|
|
129
|
+
|
|
59
130
|
/**
|
|
60
131
|
* Complete, accessible <svg> for `scene` at time t (clamped to the scene).
|
|
61
132
|
*
|
|
@@ -65,12 +136,18 @@ export function validateScene(scene) {
|
|
|
65
136
|
* style style object or "neutral"
|
|
66
137
|
* background paint the style's bg colour behind the diagram (video, PNG for slides)
|
|
67
138
|
* scale width/height multiplier for standalone output
|
|
68
|
-
* idPrefix
|
|
139
|
+
* idPrefix prefix for every id in the output: <title>/<desc>, and the scene's
|
|
140
|
+
* own ids through frame(t, { idPrefix }). Unique per instance on a
|
|
141
|
+
* page; made a safe id token (safeId). Default: scene.id
|
|
142
|
+
* @param {Scene} scene
|
|
143
|
+
* @param {number} t
|
|
144
|
+
* @param {{ standalone?: boolean, theme?: string, style?: any, background?: boolean, scale?: number, idPrefix?: string, live?: boolean }} [options]
|
|
145
|
+
* @returns {string}
|
|
69
146
|
*/
|
|
70
147
|
export function renderSvg(scene, t, options = {}) {
|
|
71
148
|
const style = normalizeStyle(options.style);
|
|
72
149
|
const time = Math.min(Math.max(t, 0), scene.duration);
|
|
73
|
-
const id =
|
|
150
|
+
const id = safeId(options.idPrefix ?? scene.id);
|
|
74
151
|
const scale = options.scale ?? 1;
|
|
75
152
|
const size = options.standalone ? ` width="${num(scene.width * scale)}" height="${num(scene.height * scale)}"` : "";
|
|
76
153
|
const vars = options.standalone ? "" : ` style="${cssVars(style, options.theme ?? "light")}"`;
|
|
@@ -81,7 +158,7 @@ export function renderSvg(scene, t, options = {}) {
|
|
|
81
158
|
`<title id="${id}-title">${esc(scene.title)}</title>` +
|
|
82
159
|
`<desc id="${id}-desc">${esc(scene.description)}</desc>` +
|
|
83
160
|
bg +
|
|
84
|
-
scene.frame(time) +
|
|
161
|
+
scene.frame(time, { idPrefix: id }) +
|
|
85
162
|
`</svg>`;
|
|
86
163
|
return options.standalone ? resolveTokens(markup, style, options.theme ?? "light") : markup;
|
|
87
164
|
}
|
package/runtime/style.mjs
CHANGED
|
@@ -40,7 +40,7 @@ export const NEUTRAL = Object.freeze({
|
|
|
40
40
|
ink: "#111827",
|
|
41
41
|
muted: "#4b5563",
|
|
42
42
|
line: "#8b929c",
|
|
43
|
-
accent: "#
|
|
43
|
+
accent: "#1d36a8",
|
|
44
44
|
onAccent: "#ffffff",
|
|
45
45
|
emphasis: "#d97706",
|
|
46
46
|
}),
|
|
@@ -52,7 +52,7 @@ export const NEUTRAL = Object.freeze({
|
|
|
52
52
|
line: "#6b7280",
|
|
53
53
|
accent: "#2563eb",
|
|
54
54
|
onAccent: "#ffffff",
|
|
55
|
-
emphasis: "#
|
|
55
|
+
emphasis: "#fbbf24",
|
|
56
56
|
}),
|
|
57
57
|
});
|
|
58
58
|
|
|
@@ -72,6 +72,8 @@ export function normalizeStyle(style) {
|
|
|
72
72
|
light: { ...NEUTRAL.light, ...(style.light ?? {}) },
|
|
73
73
|
dark: { ...NEUTRAL.dark, ...(style.dark ?? style.light ?? {}) },
|
|
74
74
|
};
|
|
75
|
+
// The font goes into CSS and markup: a family list never needs these characters.
|
|
76
|
+
if (typeof out.font !== "string" || /[<>{};\\]/.test(out.font)) throw new Error(`style "${out.name}": font must be a CSS font-family list, got ${JSON.stringify(out.font)}`);
|
|
75
77
|
for (const theme of ["light", "dark"]) {
|
|
76
78
|
for (const key of Object.keys(out[theme])) {
|
|
77
79
|
if (!TOKENS.includes(key)) throw new Error(`style "${out.name}": unknown token "${key}" in ${theme}`);
|
|
@@ -115,25 +117,71 @@ export function contrast(a, b) {
|
|
|
115
117
|
}
|
|
116
118
|
|
|
117
119
|
/**
|
|
118
|
-
*
|
|
120
|
+
* Two tokens drawn one against the other, and the contrast the pair needs in
|
|
121
|
+
* both themes: 4.5 for text (WCAG 1.4.3), 3 for shapes and strokes (WCAG
|
|
122
|
+
* 1.4.11). `use` says where it is drawn.
|
|
123
|
+
* @typedef {{ fg: string, bg: string, min: number, use?: string }} ContrastPair
|
|
124
|
+
*/
|
|
125
|
+
/**
|
|
126
|
+
* A token pair the check leaves out on purpose, and why.
|
|
127
|
+
* @typedef {{ fg: string, bg: string, why: string }} ContrastExemption
|
|
128
|
+
*/
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* Every token pair the scene types and shared parts draw where the pair
|
|
132
|
+
* carries meaning in a step frame (runtime/types/*, runtime/parts.mjs). A
|
|
133
|
+
* scene that draws other pairs declares them in `scene.contrastPairs`; the
|
|
134
|
+
* gate checks those too (lib/check.mjs).
|
|
135
|
+
* @type {readonly ContrastPair[]}
|
|
136
|
+
*/
|
|
137
|
+
export const CONTRAST_PAIRS = Object.freeze([
|
|
138
|
+
{ fg: "ink", bg: "bg", min: 4.5, use: "labels of reached nodes, on the canvas (stateLabel)" },
|
|
139
|
+
{ fg: "ink", bg: "surface", min: 4.5, use: "labels inside pending boxes (boxNode)" },
|
|
140
|
+
{ fg: "muted", bg: "bg", min: 4.5, use: "labels of pending nodes, on the canvas (stateLabel)" },
|
|
141
|
+
{ fg: "muted", bg: "surface", min: 4.5, use: "glyphs and icons inside pending circles (circleNode)" },
|
|
142
|
+
{ fg: "onAccent", bg: "accent", min: 4.5, use: "labels, glyphs and icons inside reached nodes (boxNode, circleNode)" },
|
|
143
|
+
{ fg: "line", bg: "bg", min: 3, use: "connectors and the outlines of pending nodes" },
|
|
144
|
+
{ fg: "accent", bg: "bg", min: 3, use: "reached nodes and drawn connectors" },
|
|
145
|
+
{ fg: "emphasis", bg: "bg", min: 3, use: "the emphasis ring (sequence) and dot (hub-spoke) on the canvas" },
|
|
146
|
+
{
|
|
147
|
+
fg: "emphasis",
|
|
148
|
+
bg: "accent",
|
|
149
|
+
min: 3,
|
|
150
|
+
use: "the emphasis ring around the reached node it marks (sequence): 3.5 units apart, so adjacent at phone size. It tells the current node from the reached ones without relying on hue",
|
|
151
|
+
},
|
|
152
|
+
]);
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* Pairs that are drawn (by the scene types, only in motion; or by the
|
|
156
|
+
* motion-kit logo) but that CONTRAST_PAIRS leaves out, and why.
|
|
157
|
+
* @type {readonly ContrastExemption[]}
|
|
158
|
+
*/
|
|
159
|
+
export const CONTRAST_EXEMPT = Object.freeze([
|
|
160
|
+
{ fg: "line", bg: "surface", why: "a pending node's outline is its edge: it is told from the canvas outside it (line on bg), not from the node's own fill (WCAG 1.4.11)" },
|
|
161
|
+
{ fg: "accent", bg: "surface", why: "the reached layer covers the pending one only while a node fills; never side by side in a step frame. A scene that draws accent on surface (a bar on a track) declares the pair" },
|
|
162
|
+
{ fg: "emphasis", bg: "surface", why: "the sequence ring crosses pending nodes only mid-hop: in motion, never in a step frame" },
|
|
163
|
+
{ fg: "accent", bg: "line", why: "a connector's accent draw-on covers its pending line; they meet only at the moving tip, mid-draw" },
|
|
164
|
+
{ fg: "onAccent", bg: "emphasis", why: "no scene type draws it; the motion-kit logo's end keyframe does, and logos are exempt from WCAG 1.4.11" },
|
|
165
|
+
]);
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* WCAG contrast checks a style must pass, in both themes.
|
|
169
|
+
* @param {any} style style data or "neutral"; normalizeStyle fills the rest
|
|
170
|
+
* @param {readonly ContrastPair[]} [pairs] default CONTRAST_PAIRS; a scene's
|
|
171
|
+
* own pairs (`scene.contrastPairs`) are checked with the same function
|
|
119
172
|
* @returns {string[]} problems (empty = ok)
|
|
120
173
|
*/
|
|
121
|
-
export function checkContrast(style) {
|
|
174
|
+
export function checkContrast(style, pairs = CONTRAST_PAIRS) {
|
|
122
175
|
const s = normalizeStyle(style);
|
|
123
|
-
|
|
124
|
-
const rules = [
|
|
125
|
-
["ink", "bg", 4.5],
|
|
126
|
-
["ink", "surface", 4.5],
|
|
127
|
-
["muted", "bg", 4.5],
|
|
128
|
-
["muted", "surface", 4.5],
|
|
129
|
-
["onAccent", "accent", 4.5],
|
|
130
|
-
["line", "bg", 3],
|
|
131
|
-
["accent", "bg", 3],
|
|
132
|
-
["emphasis", "bg", 3],
|
|
133
|
-
];
|
|
176
|
+
if (!Array.isArray(pairs)) return [`${s.name}: contrast pairs must be an array of { fg, bg, min }`];
|
|
134
177
|
const problems = [];
|
|
178
|
+
for (const [i, p] of pairs.entries()) {
|
|
179
|
+
const bad = !p || typeof p !== "object" ? "is not an object" : !TOKENS.includes(p.fg) ? `has unknown fg token "${p.fg}"` : !TOKENS.includes(p.bg) ? `has unknown bg token "${p.bg}"` : !(typeof p.min === "number" && p.min >= 1 && p.min <= 21) ? "needs a min contrast between 1 and 21" : "";
|
|
180
|
+
if (bad) problems.push(`${s.name}: contrast pair ${i} ${bad}`);
|
|
181
|
+
}
|
|
182
|
+
if (problems.length) return problems;
|
|
135
183
|
for (const theme of ["light", "dark"]) {
|
|
136
|
-
for (const
|
|
184
|
+
for (const { fg, bg, min } of pairs) {
|
|
137
185
|
const r = contrast(s[theme][fg], s[theme][bg]);
|
|
138
186
|
if (r < min) problems.push(`${s.name} ${theme}: ${fg} on ${bg} is ${r.toFixed(2)}:1, needs ${min}:1`);
|
|
139
187
|
}
|
|
@@ -11,14 +11,14 @@
|
|
|
11
11
|
*
|
|
12
12
|
* Spec:
|
|
13
13
|
* { type: "hub-spoke", id, title, description,
|
|
14
|
-
* hub: { label, detail? },
|
|
15
|
-
* spokes: [{ label, detail? }],
|
|
14
|
+
* hub: { label, detail?, id? }, // id names the step
|
|
15
|
+
* spokes: [{ label, detail?, id? }], // 2–10
|
|
16
16
|
* direction?: "out" | "in", // default "out"
|
|
17
17
|
* fontSize?: number }
|
|
18
18
|
*/
|
|
19
19
|
import { easeOut, easeStandard, progress, window01 } from "../motion.mjs";
|
|
20
|
-
import { boxNode, FONT_MIN, rectEdge } from "../parts.mjs";
|
|
21
|
-
import { FORMATS, localize } from "../scene.mjs";
|
|
20
|
+
import { boxNode, FONT_MIN, maxFontSize, rectEdge } from "../parts.mjs";
|
|
21
|
+
import { FORMATS, localize, withId } from "../scene.mjs";
|
|
22
22
|
import { tok } from "../style.mjs";
|
|
23
23
|
import { drawOn, el, pointOnLine } from "../svg.mjs";
|
|
24
24
|
import { wrapLabel } from "../wrap.mjs";
|
|
@@ -96,7 +96,7 @@ export function hubSpoke(spec, { format = "16:9", locale = "en" } = {}) {
|
|
|
96
96
|
const hubLabel = localize(spec.hub.label, locale);
|
|
97
97
|
const labels = spokesSpec.map((s) => localize(s.label, locale));
|
|
98
98
|
// Largest font (≤ max) at which the layout fits and every label wraps.
|
|
99
|
-
const maxFs = spec
|
|
99
|
+
const maxFs = maxFontSize(spec, f.height > 0 ? 20 : 16, `hub-spoke "${spec.id}"`);
|
|
100
100
|
let L;
|
|
101
101
|
let fs;
|
|
102
102
|
let hubLines;
|
|
@@ -207,8 +207,8 @@ export function hubSpoke(spec, { format = "16:9", locale = "en" } = {}) {
|
|
|
207
207
|
title: localize(spec.title, locale),
|
|
208
208
|
description: localize(spec.description, locale),
|
|
209
209
|
steps: [
|
|
210
|
-
{ at: HUB_ON + FILL, label: hubLabel, detail: localize(spec.hub.detail, locale) },
|
|
211
|
-
...spokes.map((s, i) => ({ at: stepAt(i), label: s.label, detail: s.detail })),
|
|
210
|
+
withId({ at: HUB_ON + FILL, label: hubLabel, detail: localize(spec.hub.detail, locale) }, spec.hub.id),
|
|
211
|
+
...spokes.map((s, i) => withId({ at: stepAt(i), label: s.label, detail: s.detail }, spokesSpec[i].id)),
|
|
212
212
|
],
|
|
213
213
|
frame,
|
|
214
214
|
};
|
package/runtime/types/index.mjs
CHANGED
|
@@ -12,10 +12,14 @@
|
|
|
12
12
|
import { validateScene } from "../scene.mjs";
|
|
13
13
|
import { hubSpoke } from "./hub-spoke.mjs";
|
|
14
14
|
import { sequence } from "./sequence.mjs";
|
|
15
|
+
import { stack } from "./stack.mjs";
|
|
16
|
+
import { timeline } from "./timeline.mjs";
|
|
15
17
|
|
|
16
18
|
export const SCENE_TYPES = {
|
|
17
19
|
sequence,
|
|
18
20
|
"hub-spoke": hubSpoke,
|
|
21
|
+
timeline,
|
|
22
|
+
stack,
|
|
19
23
|
};
|
|
20
24
|
|
|
21
25
|
export function createScene(spec, opts = {}) {
|
|
@@ -11,14 +11,14 @@
|
|
|
11
11
|
*
|
|
12
12
|
* Spec:
|
|
13
13
|
* { type: "sequence", id, title, description,
|
|
14
|
-
* nodes: [{ label, detail?, glyph?, icon? }],
|
|
14
|
+
* nodes: [{ label, detail?, glyph?, icon?, id? }], // 2–12 nodes; id names the node's step
|
|
15
15
|
* glyphs?: "numbers" | "none" // default "numbers"
|
|
16
16
|
* fontSize?: number }
|
|
17
17
|
* Strings may be localized objects: { en: "...", nl: "..." }.
|
|
18
18
|
*/
|
|
19
19
|
import { easeOut, easeStandard, progress } from "../motion.mjs";
|
|
20
|
-
import { circleNode, FONT_MIN, stateLabel } from "../parts.mjs";
|
|
21
|
-
import { FORMATS, localize } from "../scene.mjs";
|
|
20
|
+
import { circleNode, FONT_MIN, maxFontSize, stateLabel } from "../parts.mjs";
|
|
21
|
+
import { FORMATS, localize, withId } from "../scene.mjs";
|
|
22
22
|
import { tok } from "../style.mjs";
|
|
23
23
|
import { drawOn, el, polyline, trimSegment } from "../svg.mjs";
|
|
24
24
|
import { wrapLabel } from "../wrap.mjs";
|
|
@@ -126,7 +126,7 @@ export function sequence(spec, { format = "16:9", locale = "en" } = {}) {
|
|
|
126
126
|
const f = typeof format === "string" ? { name: format, ...FORMATS[format] } : format;
|
|
127
127
|
if (!f.width) throw new Error(`unknown format "${format}"`);
|
|
128
128
|
const n = nodes.length;
|
|
129
|
-
const maxFs = spec
|
|
129
|
+
const maxFs = maxFontSize(spec, f.height > 0 ? 22 : 16, `sequence "${spec.id}"`);
|
|
130
130
|
let fitted;
|
|
131
131
|
try {
|
|
132
132
|
fitted = fit(f, nodes, locale, maxFs);
|
|
@@ -195,7 +195,7 @@ export function sequence(spec, { format = "16:9", locale = "en" } = {}) {
|
|
|
195
195
|
duration,
|
|
196
196
|
title: localize(spec.title, locale),
|
|
197
197
|
description: localize(spec.description, locale),
|
|
198
|
-
steps: items.map((it, k) => ({ at: stepAt(k), label: it.label, detail: it.detail })),
|
|
198
|
+
steps: items.map((it, k) => withId({ at: stepAt(k), label: it.label, detail: it.detail }, nodes[k].id)),
|
|
199
199
|
frame,
|
|
200
200
|
};
|
|
201
201
|
}
|
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
// SPDX-License-Identifier: MIT
|
|
2
|
+
// Copyright (c) 2026 Ophir Radnitz
|
|
3
|
+
/**
|
|
4
|
+
* motion-kit · scene type "stack".
|
|
5
|
+
*
|
|
6
|
+
* Helps the viewer understand: layers that build on each other (an
|
|
7
|
+
* architecture, security layers, a protocol stack), and what passes through
|
|
8
|
+
* them. Storyboard: the layers rise into place bottom-up (skeleton first),
|
|
9
|
+
* then a packet (the one emphasis element) enters on a rail beside the stack
|
|
10
|
+
* and travels layer to layer; each layer it reaches fills with the accent
|
|
11
|
+
* colour, and the rail behind the packet turns accent.
|
|
12
|
+
*
|
|
13
|
+
* Spec:
|
|
14
|
+
* { type: "stack", id, title, description,
|
|
15
|
+
* layers: [{ label, detail?, id? }], // 2–8, listed top to bottom; id names the step
|
|
16
|
+
* direction?: "down" | "up", // default "down": the packet enters at the top
|
|
17
|
+
* fontSize?: number }
|
|
18
|
+
* Strings may be localized objects: { en: "...", nl: "..." }.
|
|
19
|
+
*
|
|
20
|
+
* Layout: one column of full-width layers with the rail on their right, in
|
|
21
|
+
* every format; layers get taller (up to a limit) where the format has room.
|
|
22
|
+
*/
|
|
23
|
+
import { easeOut, easeStandard, lerp, progress } from "../motion.mjs";
|
|
24
|
+
import { FONT_MIN, maxFontSize } from "../parts.mjs";
|
|
25
|
+
import { FORMATS, localize, withId } from "../scene.mjs";
|
|
26
|
+
import { tok } from "../style.mjs";
|
|
27
|
+
import { drawOn, el, fade, num, text, translate } from "../svg.mjs";
|
|
28
|
+
import { wrapLabel } from "../wrap.mjs";
|
|
29
|
+
|
|
30
|
+
/** @import { Scene } from "../scene.mjs" */
|
|
31
|
+
|
|
32
|
+
// Timeline (seconds). Steps are settled because PERIOD ≥ HOP + FILL.
|
|
33
|
+
const RISE_GAP = 0.1;
|
|
34
|
+
const RISE = 0.4;
|
|
35
|
+
const RAIL = 0.45;
|
|
36
|
+
const APPEAR = 0.25;
|
|
37
|
+
const HOP = 0.4;
|
|
38
|
+
const FILL = 0.25;
|
|
39
|
+
const PERIOD = HOP + FILL + 0.05;
|
|
40
|
+
const TAIL = 0.4;
|
|
41
|
+
|
|
42
|
+
const PAD = 24;
|
|
43
|
+
const CHAR = 0.56;
|
|
44
|
+
const GAP = 10; // between two layers
|
|
45
|
+
const RAIL_GAP = 26; // layer edge → rail
|
|
46
|
+
const LEAD = 34; // rail beyond the outer layers, where the packet enters and leaves
|
|
47
|
+
const DOT = 7;
|
|
48
|
+
const MAX_LAYERS = 8;
|
|
49
|
+
const RISE_BY = 14; // a layer rises this far into place
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* One layer in three states, cross-faded: pending (surface), current (accent
|
|
53
|
+
* fill) and passed (surface with an accent outline), so the finished stack
|
|
54
|
+
* shows the packet's path without a wall of accent.
|
|
55
|
+
* @param {{ x: number, y: number, w: number, h: number }} b
|
|
56
|
+
* @param {string[]} lines
|
|
57
|
+
* @param {number} fs
|
|
58
|
+
* @param {number} enter
|
|
59
|
+
* @param {number} active
|
|
60
|
+
* @param {number} passed
|
|
61
|
+
*/
|
|
62
|
+
function layer(b, lines, fs, enter, active, passed) {
|
|
63
|
+
if (enter <= 0) return "";
|
|
64
|
+
const dy = (1 - enter) * RISE_BY;
|
|
65
|
+
const label = (fill) => text({ x: b.x + b.w / 2, y: b.y + b.h / 2, "text-anchor": "middle", "dominant-baseline": "central", "font-size": fs, "font-weight": 500, fill }, lines);
|
|
66
|
+
const box = (fill, stroke, width) => el("rect", { x: b.x, y: b.y, width: b.w, height: b.h, rx: 10, fill, stroke, "stroke-width": width });
|
|
67
|
+
return fade(
|
|
68
|
+
enter,
|
|
69
|
+
{ transform: dy > 0.004 ? translate(0, dy) : undefined },
|
|
70
|
+
fade(1 - active, {}, box(tok("surface"), tok("line"), 2), label(tok("ink"))),
|
|
71
|
+
fade(active * (1 - passed), {}, box(tok("accent"), tok("accent"), 2), label(tok("onAccent"))),
|
|
72
|
+
fade(passed, {}, box(tok("surface"), tok("accent"), 3), label(tok("ink"))),
|
|
73
|
+
);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* Geometry for `n` layers at font size `fs` with up to `maxLines` label lines,
|
|
78
|
+
* or the reason it does not fit.
|
|
79
|
+
* @param {{ name: string, width: number, height: number }} f
|
|
80
|
+
* @param {number} n
|
|
81
|
+
* @param {number} fs
|
|
82
|
+
* @param {number} maxLines
|
|
83
|
+
*/
|
|
84
|
+
function layout(f, n, fs, maxLines) {
|
|
85
|
+
const W = f.width;
|
|
86
|
+
const fixed = f.height > 0;
|
|
87
|
+
const lineH = fs * 1.25;
|
|
88
|
+
const minH = maxLines * lineH + 20;
|
|
89
|
+
const railSpace = RAIL_GAP + DOT + 2;
|
|
90
|
+
const boxW = Math.min(W - 2 * PAD - railSpace, fs * 24);
|
|
91
|
+
let boxH = minH;
|
|
92
|
+
if (fixed) {
|
|
93
|
+
const room = (f.height - 2 * PAD - 2 * LEAD - (n - 1) * GAP) / n;
|
|
94
|
+
if (room < minH) return { problem: `${n} layers of ${maxLines} line(s) need ${Math.ceil(n * minH + (n - 1) * GAP + 2 * LEAD + 2 * PAD)}px of height, the format has ${f.height}` };
|
|
95
|
+
boxH = Math.min(room, Math.max(minH, fs * 3.4));
|
|
96
|
+
}
|
|
97
|
+
const stackH = n * boxH + (n - 1) * GAP;
|
|
98
|
+
const H = fixed ? f.height : Math.ceil(stackH + 2 * LEAD + 2 * PAD);
|
|
99
|
+
const x = (W - (boxW + railSpace)) / 2;
|
|
100
|
+
const top = (H - stackH) / 2;
|
|
101
|
+
const boxes = Array.from({ length: n }, (_, i) => ({ x, y: top + i * (boxH + GAP), w: boxW, h: boxH }));
|
|
102
|
+
const railX = x + boxW + RAIL_GAP;
|
|
103
|
+
return { W, H, fs, lineH, maxLines, boxes, railX, railTop: top - LEAD, railBottom: top + stackH + LEAD, maxChars: Math.floor((boxW - 24) / (fs * CHAR)) };
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
/**
|
|
107
|
+
* Build a stack scene from its spec.
|
|
108
|
+
* @param {any} spec
|
|
109
|
+
* @param {{ format?: string | { name: string, width: number, height: number }, locale?: string }} [opts]
|
|
110
|
+
* @returns {Scene}
|
|
111
|
+
*/
|
|
112
|
+
export function stack(spec, { format = "16:9", locale = "en" } = {}) {
|
|
113
|
+
const name = `stack "${spec.id}"`;
|
|
114
|
+
const f = typeof format === "string" ? { name: format, ...FORMATS[format] } : format;
|
|
115
|
+
if (!f.width) throw new Error(`unknown format "${format}"`);
|
|
116
|
+
const layers = spec.layers;
|
|
117
|
+
if (!Array.isArray(layers)) throw new Error(`${name}: needs "layers", a list of { label }, top to bottom`);
|
|
118
|
+
const n = layers.length;
|
|
119
|
+
if (n < 2 || n > MAX_LAYERS) throw new Error(`${name}: needs 2–${MAX_LAYERS} layers, got ${n}`);
|
|
120
|
+
const direction = spec.direction ?? "down";
|
|
121
|
+
if (direction !== "down" && direction !== "up") throw new Error(`${name}: "direction" must be "down" or "up", got ${JSON.stringify(spec.direction)}`);
|
|
122
|
+
const labels = layers.map((l, i) => {
|
|
123
|
+
const label = localize(l?.label, locale);
|
|
124
|
+
if (!label) throw new Error(`${name}: layer ${i + 1} needs a "label"`);
|
|
125
|
+
return label;
|
|
126
|
+
});
|
|
127
|
+
|
|
128
|
+
// Largest font (≤ max) at which every label wraps; one line before two.
|
|
129
|
+
const maxFs = maxFontSize(spec, f.height > 0 ? 22 : 16, name);
|
|
130
|
+
let L;
|
|
131
|
+
let lines;
|
|
132
|
+
let why = "";
|
|
133
|
+
search: for (let fs = maxFs; fs >= FONT_MIN; fs--) {
|
|
134
|
+
for (const maxLines of [1, 2]) {
|
|
135
|
+
const cand = layout(f, n, fs, maxLines);
|
|
136
|
+
if ("problem" in cand) {
|
|
137
|
+
why = cand.problem ?? why;
|
|
138
|
+
continue;
|
|
139
|
+
}
|
|
140
|
+
try {
|
|
141
|
+
lines = labels.map((l) => wrapLabel(l, cand.maxChars, maxLines));
|
|
142
|
+
L = cand;
|
|
143
|
+
break search;
|
|
144
|
+
} catch (e) {
|
|
145
|
+
why = e instanceof Error ? e.message : String(e);
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
if (!L || !lines) throw new Error(`${name}: ${n} layers do not fit format ${f.name} at ≥ ${FONT_MIN}px (${why}); use fewer layers, shorter labels or a larger format`);
|
|
150
|
+
const fitted = L;
|
|
151
|
+
const wrapped = lines;
|
|
152
|
+
|
|
153
|
+
// Travel order: the packet visits layers top → bottom ("down") or bottom → top ("up").
|
|
154
|
+
const order = direction === "down" ? labels.map((_, i) => i) : labels.map((_, i) => n - 1 - i);
|
|
155
|
+
const visit = new Array(n); // layer index → position in the travel order
|
|
156
|
+
order.forEach((li, k) => (visit[li] = k));
|
|
157
|
+
const centerY = (li) => fitted.boxes[li].y + fitted.boxes[li].h / 2;
|
|
158
|
+
const entryY = direction === "down" ? fitted.railTop : fitted.railBottom;
|
|
159
|
+
const exitY = direction === "down" ? fitted.railBottom : fitted.railTop;
|
|
160
|
+
const stops = [entryY, ...order.map(centerY)];
|
|
161
|
+
|
|
162
|
+
// Rise bottom-up; then the packet appears at the entry and hops.
|
|
163
|
+
const riseAt = (li) => (n - 1 - li) * RISE_GAP;
|
|
164
|
+
const START = RISE_GAP * (n - 1) + RISE + 0.1;
|
|
165
|
+
const hopStart = (k) => START + APPEAR + 0.05 + k * PERIOD;
|
|
166
|
+
const fillStart = (k) => hopStart(k) + HOP;
|
|
167
|
+
const stepAt = (k) => fillStart(k) + FILL;
|
|
168
|
+
const duration = stepAt(n - 1) + TAIL;
|
|
169
|
+
|
|
170
|
+
function packetY(t) {
|
|
171
|
+
let y = stops[0];
|
|
172
|
+
for (let k = 0; k < n; k++) {
|
|
173
|
+
const p = progress(t, hopStart(k), HOP, easeStandard);
|
|
174
|
+
if (p <= 0) break;
|
|
175
|
+
y = lerp(stops[k], stops[k + 1], p);
|
|
176
|
+
}
|
|
177
|
+
return y;
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
const vline = (x, y0, y1, attrs) => el("path", { d: `M${num(x)} ${num(y0)} V${num(y1)}`, fill: "none", "stroke-linecap": "round", ...attrs });
|
|
181
|
+
|
|
182
|
+
function frame(t) {
|
|
183
|
+
const out = [];
|
|
184
|
+
const { railX } = fitted;
|
|
185
|
+
// Rail: draws on from the entry end while the layers rise; an arrowhead marks the exit.
|
|
186
|
+
const railLen = Math.abs(exitY - entryY);
|
|
187
|
+
const railDash = drawOn(railLen, progress(t, 0.2, RAIL, easeStandard));
|
|
188
|
+
if (railDash) out.push(vline(railX, entryY, exitY, { stroke: tok("line"), "stroke-width": 2, ...railDash }));
|
|
189
|
+
const head = progress(t, 0.2 + RAIL - 0.15, 0.2, easeOut);
|
|
190
|
+
if (head > 0) {
|
|
191
|
+
const s = direction === "down" ? -1 : 1;
|
|
192
|
+
out.push(el("path", { d: `M${num(railX - 6)} ${num(exitY + s * 9)} L${num(railX)} ${num(exitY)} L${num(railX + 6)} ${num(exitY + s * 9)}`, fill: "none", stroke: tok("line"), "stroke-width": 2, "stroke-linecap": "round", "stroke-linejoin": "round", opacity: head }));
|
|
193
|
+
}
|
|
194
|
+
const y = packetY(t);
|
|
195
|
+
if (Math.abs(y - entryY) > 0.5) out.push(vline(railX, entryY, y, { stroke: tok("accent"), "stroke-width": 3 }));
|
|
196
|
+
fitted.boxes.forEach((b, li) => {
|
|
197
|
+
const enter = progress(t, riseAt(li), RISE, easeOut);
|
|
198
|
+
const k = visit[li];
|
|
199
|
+
const active = progress(t, fillStart(k), FILL, easeStandard);
|
|
200
|
+
// Once the packet moves on, the layer keeps an accent outline.
|
|
201
|
+
const passed = k < n - 1 ? progress(t, hopStart(k + 1), FILL, easeStandard) : 0;
|
|
202
|
+
// Tick from the layer to the rail: pending once the layer is in, accent once reached.
|
|
203
|
+
const cy = b.y + b.h / 2;
|
|
204
|
+
if (enter > 0) out.push(el("path", { d: `M${num(b.x + b.w + 4)} ${num(cy)} H${num(railX - 4)}`, stroke: tok("line"), "stroke-width": 2, "stroke-linecap": "round", opacity: enter * (1 - active) }));
|
|
205
|
+
if (active > 0) out.push(el("path", { d: `M${num(b.x + b.w + 4)} ${num(cy)} H${num(railX - 4)}`, stroke: tok("accent"), "stroke-width": 3, "stroke-linecap": "round", opacity: active }));
|
|
206
|
+
out.push(layer(b, wrapped[li], fitted.fs, enter, active, passed));
|
|
207
|
+
});
|
|
208
|
+
// The packet: appears at the entry, then rides the rail.
|
|
209
|
+
const appear = progress(t, START, APPEAR, easeOut);
|
|
210
|
+
if (appear > 0) out.push(el("circle", { cx: railX, cy: y, r: DOT * (0.6 + 0.4 * appear), fill: tok("emphasis"), opacity: appear }));
|
|
211
|
+
return out.join("");
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
return {
|
|
215
|
+
id: `${spec.id}-${f.name.replace(":", "x")}`,
|
|
216
|
+
type: "stack",
|
|
217
|
+
format: f.name,
|
|
218
|
+
locale,
|
|
219
|
+
width: fitted.W,
|
|
220
|
+
height: fitted.H,
|
|
221
|
+
duration,
|
|
222
|
+
title: localize(spec.title, locale),
|
|
223
|
+
description: localize(spec.description, locale),
|
|
224
|
+
steps: order.map((li, k) => withId({ at: stepAt(k), label: labels[li], detail: localize(layers[li].detail, locale) }, layers[li].id)),
|
|
225
|
+
frame,
|
|
226
|
+
};
|
|
227
|
+
}
|