@liqweed/motion-kit 0.2.0 → 0.4.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 +74 -7
- package/adapters/astro/AnimatedDiagram.astro +150 -24
- package/adapters/element/README.md +49 -0
- package/adapters/element/motion-diagram.mjs +124 -0
- package/adapters/page/README.md +3 -2
- package/adapters/slidev/AnimatedDiagram.vue +24 -0
- package/cli/motion-kit.mjs +77 -79
- package/docs/spec/technique.md +102 -44
- package/lib/build.mjs +26 -12
- package/lib/bundle.mjs +9 -2
- package/lib/check.mjs +15 -2
- package/lib/export.mjs +33 -11
- package/lib/gate.mjs +88 -0
- package/lib/load.mjs +49 -19
- package/package.json +1 -1
- package/runtime/bake.mjs +18 -4
- package/runtime/kit.mjs +59 -0
- package/runtime/page.mjs +52 -0
- package/runtime/player.mjs +375 -127
- package/runtime/scene.mjs +80 -5
- package/runtime/style.mjs +2 -0
- package/runtime/types/hub-spoke.mjs +5 -5
- package/runtime/types/sequence.mjs +3 -3
- package/skills/animated-diagram/SKILL.md +3 -1
- package/skills/animated-diagram/references/custom-scenes.md +58 -8
- package/skills/animated-diagram/references/interactivity.md +50 -7
- package/skills/animated-diagram/references/qc.md +2 -2
- package/skills/animated-diagram/references/targets.md +7 -5
- package/skills/animated-diagram/references/technique.md +5 -0
- package/skills/motion-render/SKILL.md +18 -2
package/runtime/scene.mjs
CHANGED
|
@@ -9,18 +9,36 @@
|
|
|
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
|
+
* @typedef {{ id: string, width: number, height: number, duration: number, title: string, description: string, steps: Step[], frame: (t: number, ctx: FrameContext) => string, stepLabelsInFrame?: boolean, type?: string, format?: string, locale?: string }} Scene
|
|
40
|
+
*/
|
|
41
|
+
|
|
24
42
|
/** Formats: name → viewBox. Layouts are computed per format, never cropped. */
|
|
25
43
|
export const FORMATS = {
|
|
26
44
|
"16:9": { width: 960, height: 540 },
|
|
@@ -41,21 +59,72 @@ export function localize(value, locale = "en") {
|
|
|
41
59
|
return first;
|
|
42
60
|
}
|
|
43
61
|
|
|
62
|
+
/**
|
|
63
|
+
* A valid, CSS-safe id token from any string: letters, digits, "_" and "-",
|
|
64
|
+
* starting with a letter. Ids that already are one come back unchanged.
|
|
65
|
+
* @param {unknown} value
|
|
66
|
+
* @returns {string}
|
|
67
|
+
*/
|
|
68
|
+
export function safeId(value) {
|
|
69
|
+
const s = String(value).replace(/[^A-Za-z0-9_-]+/g, "-");
|
|
70
|
+
return /^[A-Za-z]/.test(s) ? s : `mk-${s}`;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* Throw unless `scene` meets the contract; returns it unchanged.
|
|
75
|
+
* @template {Scene} S
|
|
76
|
+
* @param {S} scene
|
|
77
|
+
* @returns {S}
|
|
78
|
+
*/
|
|
44
79
|
export function validateScene(scene) {
|
|
45
80
|
for (const k of ["id", "width", "height", "duration", "title", "description", "steps", "frame"]) {
|
|
46
81
|
if (scene[k] === undefined || scene[k] === "") throw new Error(`scene ${scene.id ?? "?"} is missing "${k}"`);
|
|
47
82
|
}
|
|
48
83
|
if (!scene.steps.length) throw new Error(`scene ${scene.id}: needs at least one step`);
|
|
49
84
|
let prev = -Infinity;
|
|
85
|
+
const ids = new Set();
|
|
50
86
|
for (const s of scene.steps) {
|
|
51
87
|
if (!(s.at > prev)) throw new Error(`scene ${scene.id}: steps must be strictly increasing in time`);
|
|
52
88
|
if (s.at > scene.duration + 1e-9) throw new Error(`scene ${scene.id}: step "${s.label}" is after the duration`);
|
|
53
89
|
if (!s.label) throw new Error(`scene ${scene.id}: every step needs a label`);
|
|
90
|
+
if (s.id !== undefined) {
|
|
91
|
+
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`);
|
|
92
|
+
if (ids.has(s.id)) throw new Error(`scene ${scene.id}: two steps share the id "${s.id}"`);
|
|
93
|
+
ids.add(s.id);
|
|
94
|
+
}
|
|
54
95
|
prev = s.at;
|
|
55
96
|
}
|
|
56
97
|
return scene;
|
|
57
98
|
}
|
|
58
99
|
|
|
100
|
+
/**
|
|
101
|
+
* `step` with `id` added when one is given (scene types pass a spec's ids on).
|
|
102
|
+
* @template {Step} S
|
|
103
|
+
* @param {S} step
|
|
104
|
+
* @param {unknown} id
|
|
105
|
+
* @returns {S}
|
|
106
|
+
*/
|
|
107
|
+
export function withId(step, id) {
|
|
108
|
+
return id == null ? step : { ...step, id: /** @type {string} */ (id) };
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* The index of a step given by index or by id. Throws RangeError for an
|
|
113
|
+
* index outside the steps, or an id no step has.
|
|
114
|
+
* @param {{ steps: Step[] }} scene
|
|
115
|
+
* @param {number | string} ref
|
|
116
|
+
* @returns {number}
|
|
117
|
+
*/
|
|
118
|
+
export function stepIndex(scene, ref) {
|
|
119
|
+
if (typeof ref === "string") {
|
|
120
|
+
const i = scene.steps.findIndex((s) => s.id === ref);
|
|
121
|
+
if (i < 0) throw new RangeError(`Unknown step id: ${ref}`);
|
|
122
|
+
return i;
|
|
123
|
+
}
|
|
124
|
+
if (!Number.isInteger(ref) || ref < 0 || ref >= scene.steps.length) throw new RangeError(`Invalid step index: ${ref}`);
|
|
125
|
+
return ref;
|
|
126
|
+
}
|
|
127
|
+
|
|
59
128
|
/**
|
|
60
129
|
* Complete, accessible <svg> for `scene` at time t (clamped to the scene).
|
|
61
130
|
*
|
|
@@ -65,12 +134,18 @@ export function validateScene(scene) {
|
|
|
65
134
|
* style style object or "neutral"
|
|
66
135
|
* background paint the style's bg colour behind the diagram (video, PNG for slides)
|
|
67
136
|
* scale width/height multiplier for standalone output
|
|
68
|
-
* idPrefix
|
|
137
|
+
* idPrefix prefix for every id in the output: <title>/<desc>, and the scene's
|
|
138
|
+
* own ids through frame(t, { idPrefix }). Unique per instance on a
|
|
139
|
+
* page; made a safe id token (safeId). Default: scene.id
|
|
140
|
+
* @param {Scene} scene
|
|
141
|
+
* @param {number} t
|
|
142
|
+
* @param {{ standalone?: boolean, theme?: string, style?: any, background?: boolean, scale?: number, idPrefix?: string, live?: boolean }} [options]
|
|
143
|
+
* @returns {string}
|
|
69
144
|
*/
|
|
70
145
|
export function renderSvg(scene, t, options = {}) {
|
|
71
146
|
const style = normalizeStyle(options.style);
|
|
72
147
|
const time = Math.min(Math.max(t, 0), scene.duration);
|
|
73
|
-
const id =
|
|
148
|
+
const id = safeId(options.idPrefix ?? scene.id);
|
|
74
149
|
const scale = options.scale ?? 1;
|
|
75
150
|
const size = options.standalone ? ` width="${num(scene.width * scale)}" height="${num(scene.height * scale)}"` : "";
|
|
76
151
|
const vars = options.standalone ? "" : ` style="${cssVars(style, options.theme ?? "light")}"`;
|
|
@@ -81,7 +156,7 @@ export function renderSvg(scene, t, options = {}) {
|
|
|
81
156
|
`<title id="${id}-title">${esc(scene.title)}</title>` +
|
|
82
157
|
`<desc id="${id}-desc">${esc(scene.description)}</desc>` +
|
|
83
158
|
bg +
|
|
84
|
-
scene.frame(time) +
|
|
159
|
+
scene.frame(time, { idPrefix: id }) +
|
|
85
160
|
`</svg>`;
|
|
86
161
|
return options.standalone ? resolveTokens(markup, style, options.theme ?? "light") : markup;
|
|
87
162
|
}
|
package/runtime/style.mjs
CHANGED
|
@@ -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}`);
|
|
@@ -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
20
|
import { boxNode, FONT_MIN, rectEdge } from "../parts.mjs";
|
|
21
|
-
import { FORMATS, localize } from "../scene.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";
|
|
@@ -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
|
};
|
|
@@ -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
20
|
import { circleNode, FONT_MIN, stateLabel } from "../parts.mjs";
|
|
21
|
-
import { FORMATS, localize } from "../scene.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";
|
|
@@ -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
|
}
|
|
@@ -63,11 +63,13 @@ Node ≥ 22. PNG/video need `@resvg/resvg-js` (`npm install` in `$MK`) and `ffmp
|
|
|
63
63
|
mk() { node "$MK/cli/motion-kit.mjs" "$@"; }
|
|
64
64
|
mk types; mk formats
|
|
65
65
|
mk check diagram.json # all formats × locales
|
|
66
|
+
mk check flow.scene.mjs -l en -l nl --options labels.mjs # a custom module, with its text from the caller
|
|
66
67
|
mk build diagram.json -o diagram.html -f wide -l nl # Craft Page / standalone
|
|
67
68
|
mk export diagram.json -o out/ --png --qc # slides + review sheet
|
|
68
69
|
mk bake diagram.json -o diagram.svg -f wide # zero-JS animated SVG
|
|
69
70
|
mk video diagram.json -f 9:16 -o reel.mp4 --sheet sheet.png
|
|
70
|
-
mk vendor <repo>/components/motion-kit --adapter slidev # or astro / page
|
|
71
|
+
mk vendor <repo>/components/motion-kit --adapter slidev # or astro / page / element
|
|
72
|
+
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
|
|
71
73
|
```
|
|
72
74
|
|
|
73
75
|
Vendoring includes the full MIT `LICENSE`. Keep that file and the SPDX
|
|
@@ -18,8 +18,10 @@ export default function make({ format = "16:9", locale = "en" } = {}) {
|
|
|
18
18
|
duration: 4.2,
|
|
19
19
|
title: localize({ en: "…", nl: "…" }, locale),
|
|
20
20
|
description: localize({ en: "…", nl: "…" }, locale),
|
|
21
|
-
steps: [{ at: 1.2, label: "…", detail: "…" }, …],
|
|
22
|
-
frame(t
|
|
21
|
+
steps: [{ at: 1.2, label: "…", detail: "…", id: "request" }, …],
|
|
22
|
+
frame(t, { idPrefix }) {
|
|
23
|
+
// inner SVG markup for time t; ids are `${idPrefix}-…`
|
|
24
|
+
},
|
|
23
25
|
};
|
|
24
26
|
}
|
|
25
27
|
```
|
|
@@ -30,6 +32,12 @@ Rules:
|
|
|
30
32
|
no module-level mutable state.
|
|
31
33
|
- Colours only via `tok()`; numbers in strings via `num()`.
|
|
32
34
|
- Use `fade()`/`el()` so invisible elements disappear; `drawOn()` for lines.
|
|
35
|
+
- Ids (clip paths, gradients, masks, markers, filters) MUST be built from
|
|
36
|
+
`idPrefix`, the second argument's field: `${idPrefix}-clip`, referenced as
|
|
37
|
+
`url(#${idPrefix}-clip)`. Every render gets a prefix unique to its instance,
|
|
38
|
+
so two copies on one page never share an id. The gate refuses fixed ids.
|
|
39
|
+
- Give steps an `id` when page scripts or links address them
|
|
40
|
+
(`controller.playToStep("request")`); ids are unique within the scene.
|
|
33
41
|
- Lay out per format; throw if labels don't fit (`wrapLabel`).
|
|
34
42
|
- Gate: `motion-kit check my-diagram.scene.mjs` (all formats you support; pass
|
|
35
43
|
`--format` to limit).
|
|
@@ -38,11 +46,53 @@ Rules:
|
|
|
38
46
|
- If the same shape is needed twice, promote it to a scene type in
|
|
39
47
|
`runtime/types/` with a spec and tests.
|
|
40
48
|
|
|
49
|
+
## Scene options: text and views from the caller
|
|
50
|
+
|
|
51
|
+
Every caller builds a module through `sceneFromModule` (`runtime/kit.mjs`):
|
|
52
|
+
|
|
53
|
+
```js
|
|
54
|
+
make({ ...options, format, locale, kit })
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
`options` are the caller's serializable scene options, passed unchanged: a
|
|
58
|
+
site's dictionary entry (`labels`), a `view` to draw. `format`, `locale` and
|
|
59
|
+
`kit` are reserved. The same module, options, format and locale give the same
|
|
60
|
+
scene in the gate, the exporters and the browser.
|
|
61
|
+
|
|
62
|
+
```js
|
|
63
|
+
export default function make({ format = "16:9", labels, view = "full" }) {
|
|
64
|
+
// labels: { title, description, steps: [{ id, label, detail }] } from the caller
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
- CLI: `--options` takes inline JSON, a `.json` file, or an `.mjs` whose
|
|
69
|
+
default export is the options or `({ format, locale }) => options`, so the
|
|
70
|
+
gate checks each locale with that locale's text:
|
|
71
|
+
|
|
72
|
+
```js
|
|
73
|
+
// labels.mjs
|
|
74
|
+
import en from "../i18n/en.json" with { type: "json" };
|
|
75
|
+
import nl from "../i18n/nl.json" with { type: "json" };
|
|
76
|
+
export default ({ locale }) => ({ labels: { en, nl }[locale].flow });
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
motion-kit check flow.scene.mjs -l en -l nl --options labels.mjs --style brand.json
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
A vendored copy runs the same gate: `node <vendored>/check.mjs` takes the
|
|
84
|
+
same files and flags.
|
|
85
|
+
- Astro adapter: `<AnimatedDiagram module="/src/diagrams/flow.scene.mjs"
|
|
86
|
+
options={{ labels: t.flow }} locale={lang} format="wide" />`. The module
|
|
87
|
+
lives under `src/` and ends in `.scene.mjs` or `.scene.js`; the adapter
|
|
88
|
+
renders it on the server and loads it in the browser on demand. Only the
|
|
89
|
+
page's locale's text ships.
|
|
90
|
+
|
|
41
91
|
## Scenes outside this repository: `kit`
|
|
42
92
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
93
|
+
`kit` is the whole runtime in one flat namespace (`runtime/kit.mjs` `KIT`). A
|
|
94
|
+
scene file kept in another repository can destructure what it needs instead of
|
|
95
|
+
importing:
|
|
46
96
|
|
|
47
97
|
```js
|
|
48
98
|
export default function make({ format = "1:1", kit }) {
|
|
@@ -51,6 +101,6 @@ export default function make({ format = "1:1", kit }) {
|
|
|
51
101
|
}
|
|
52
102
|
```
|
|
53
103
|
|
|
54
|
-
Every
|
|
55
|
-
`
|
|
56
|
-
imports
|
|
104
|
+
Every command supports this, `motion-kit build` included (it bundles the whole
|
|
105
|
+
runtime and passes it as `kit`). A module that imports instead must use
|
|
106
|
+
relative imports to a vendored runtime.
|
|
@@ -2,23 +2,66 @@
|
|
|
2
2
|
|
|
3
3
|
## The player (`runtime/player.mjs`, used by `build`, the Astro adapter, Craft Pages)
|
|
4
4
|
|
|
5
|
-
- Starts on the **final frame
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
5
|
+
- Starts on the **final frame**. A server render can emit the player's whole
|
|
6
|
+
first state with `playerMarkup(scene, { id, … })`, `PLAYER_CSS` and
|
|
7
|
+
`themeCss(selector, style, theme)`: the final frame, the step list and the
|
|
8
|
+
colours without JavaScript, with the controls inert, and nothing moves when
|
|
9
|
+
the player mounts. The Astro adapter and `build` do this.
|
|
10
|
+
- Replays once when ~40 % of the diagram, or 40 % of the viewport, shows, so a
|
|
11
|
+
diagram taller than the screen starts too; then holds. While the diagram is
|
|
12
|
+
out of view or not rendered (`display: none`), its clock waits and nothing
|
|
13
|
+
is drawn; it resumes where it stopped.
|
|
14
|
+
- Controls: play/pause (always present, WCAG 2.2.2), one button per step (jumps
|
|
15
|
+
by default), optional scrubber, caption with the active step's `detail`.
|
|
16
|
+
Every control is at least 44 × 44 px. The caption and the play button keep
|
|
17
|
+
the size of their longest text, so playback does not move the page.
|
|
18
|
+
- Keyboard on the diagram (a focusable group named by the title, described by
|
|
19
|
+
a hint, `labels.keys`): ← / → step, Home / End, Space play/pause.
|
|
10
20
|
- `prefers-reduced-motion`: final frame, no autoplay, no play button.
|
|
11
|
-
- `prefers-color-scheme`: light/dark tokens switch live.
|
|
21
|
+
- `prefers-color-scheme`: light/dark tokens switch live, unless `theme` is set.
|
|
22
|
+
Tokens are set one property at a time, so CSS on the container stays.
|
|
12
23
|
- Screen readers: `role="img"` + `<title>`/`<desc>`, a visually hidden ordered
|
|
13
24
|
list of all steps with details; the visible caption is `aria-hidden`.
|
|
25
|
+
- Ids: every player renders with its own id prefix (`options.id`, else the
|
|
26
|
+
scene id plus a counter), so scenes that define ids can share a page.
|
|
27
|
+
- The stylesheet is added to the document whenever a player mounts and none is
|
|
28
|
+
there, so a page swap (Astro view transitions) cannot leave players unstyled.
|
|
14
29
|
- Capture hook: `window.__motionKit[id].seek(t)` (for Playwright/HyperFrames-
|
|
15
30
|
style renderers).
|
|
16
31
|
|
|
32
|
+
Steps are addressed by zero-based index or by step `id` (a spec node's or
|
|
33
|
+
spoke's `id`, or a custom scene's `steps[i].id`): ids survive steps being added
|
|
34
|
+
or reordered. `controller.seekStep(ref)` jumps; `controller.playToStep(ref)`
|
|
35
|
+
plays forward from the current time and stops at the step's exact settled time.
|
|
36
|
+
Backward and same-step calls jump, and reduced motion always jumps. A new call
|
|
37
|
+
replaces the previous target; `pause()` holds the current frame, `seek(t)`
|
|
38
|
+
cancels playback, and `play()` continues to the end. An invalid index or an
|
|
39
|
+
unknown id throws `RangeError`.
|
|
40
|
+
|
|
41
|
+
Pass `{ animateSteps: true }` to `mountPlayer(container, scene, options)` to
|
|
42
|
+
enable this behavior for the step buttons and arrow/Home/End keys. The default
|
|
43
|
+
keeps instant navigation. Call `controller.destroy()` before removing or
|
|
44
|
+
replacing a player: it cancels playback, visibility observation, theme listening
|
|
45
|
+
and its capture-hook entry.
|
|
46
|
+
|
|
47
|
+
Reaching a player from page scripts: `mountPlayer` returns the controller; the
|
|
48
|
+
`<motion-diagram>` element and the Astro adapter's root element expose it as
|
|
49
|
+
`.controller` and dispatch `motion-ready` (bubbling, `detail.controller`) once
|
|
50
|
+
it is mounted. The player may already be mounted when your script runs, so use
|
|
51
|
+
whichever comes first. Give an Astro diagram an `id` to find it:
|
|
52
|
+
|
|
53
|
+
```js
|
|
54
|
+
const el = document.getElementById("flow");
|
|
55
|
+
const go = (c) => c.playToStep("payment");
|
|
56
|
+
el.controller ? go(el.controller) : el.addEventListener("motion-ready", (e) => go(e.detail.controller), { once: true });
|
|
57
|
+
```
|
|
58
|
+
|
|
17
59
|
## Patterns worth adding per diagram (in the page around the player)
|
|
18
60
|
|
|
19
61
|
- **Hover/focus linking:** terms in the surrounding text highlight the matching
|
|
20
62
|
part of the diagram (and back). Wrap the term in
|
|
21
|
-
`<span data-mk-step="
|
|
63
|
+
`<span data-mk-step="payment">`; on hover and on focus,
|
|
64
|
+
`controller.seekStep("payment")`. Use step ids, not positions.
|
|
22
65
|
- **Scroll-driven steps:** for long-form explainers, map section visibility to
|
|
23
66
|
steps (IntersectionObserver per text section → `seekStep(i)`). Don't scrub
|
|
24
67
|
continuously on scroll; jump to settled steps.
|
|
@@ -10,8 +10,8 @@ Model screenshots are evidence, not approval. **A human signs off on the look.**
|
|
|
10
10
|
2. **Timing:** QC frames 0.2 s before/after each step: overlapping text, abrupt
|
|
11
11
|
jumps, elements vanishing, half-drawn lines, stray dots. Regular sampling
|
|
12
12
|
misses broken transitions; look *around* the transitions.
|
|
13
|
-
3. **Phone size:** the 360 px row in the sheet
|
|
14
|
-
text under 14 px at 1×.
|
|
13
|
+
3. **Phone size:** the 360 px row in the sheet (the scene's `tall` layout); the
|
|
14
|
+
`9:16` layout; no text under 14 px at 1×.
|
|
15
15
|
4. **Brand and facts:** tokens only, approved style, approved copy, no invented
|
|
16
16
|
numbers or superlatives, every locale checked.
|
|
17
17
|
5. **Final file:**
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
| **Craft in-chat preview** | **no** (`html-preview` iframe blocks scripts) | baked SVG, or step PNGs | `bake -o x.svg` → `image-preview`; or `export --png` → `image-preview` items |
|
|
7
7
|
| **Slidev** (stagewright, docomply-presentations) | yes | one step per click (component registers its own clicks; composes with `v-click`) | `vendor <deck>/components/motion-kit --adapter slidev` → `<AnimatedDiagram :spec="spec" />`; `maxHeight` (default 380px fits under a title) |
|
|
8
8
|
| **Marp / PowerPoint / Keynote** | no | one slide per step, same position; transition None/Dissolve/Morph | `export --png --scale 2` (Marp, Google Slides) or the SVGs (PowerPoint 365, Keynote) |
|
|
9
|
-
| **Website** (Astro, React, static) | yes | server-rendered final frame + player | `vendor <repo>/src/motion-kit --adapter astro`; wide + tall instances switched with CSS |
|
|
9
|
+
| **Website** (Astro, React, static) | yes | server-rendered first state (final frame, step list, colours) + player | `vendor <repo>/src/motion-kit --adapter astro`; `<AnimatedDiagram spec={…}>` or `module="/src/…/x.scene.mjs" options={…}`; `theme`, `style`; wide + tall instances switched with CSS; CI runs the vendored `check.mjs` |
|
|
10
10
|
| **README / Obsidian / email / docs** | no | baked SVG (animated) or a GIF | `bake` (CSS animation inside SVG: works in browsers and GitHub `<img>`); `video -o x.gif` for email |
|
|
11
11
|
| **Video** (social, demos, talks) | n/a | MP4/WebM/GIF | `video -f 9:16 -o reel.mp4`; see motion-render |
|
|
12
12
|
|
|
@@ -19,9 +19,11 @@
|
|
|
19
19
|
- **Slides:** frames from one scene share a viewBox, so consecutive step slides
|
|
20
20
|
register exactly. Fonts in standalone SVG fall back to the viewer's system
|
|
21
21
|
font: send PNGs for decks that travel.
|
|
22
|
-
- **Websites:** pass serializable props (spec
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
22
|
+
- **Websites:** pass serializable props (a spec, or a module path and its
|
|
23
|
+
options) to islands; pass the page's locale's text as options, so the other
|
|
24
|
+
dictionaries stay out of client bundles; mount wide and tall, switch with CSS
|
|
25
|
+
(`display:none` also removes the hidden one from the a11y tree and stops its
|
|
26
|
+
clock). The server render reserves the controls' space: mounting causes no
|
|
27
|
+
layout shift.
|
|
26
28
|
- **Brand repos** keep their own style file next to their specs; motion-kit
|
|
27
29
|
ships only `neutral`.
|
|
@@ -37,6 +37,11 @@ Video maps frame `f` at `fps` to `t = f / fps` (30 fps × 25 s = 750 frames).
|
|
|
37
37
|
11. Visibility decisions use rounded values: an element whose opacity rounds to
|
|
38
38
|
0 is dropped, and an opacity that rounds to 1 is omitted, so frames that
|
|
39
39
|
look identical are byte-identical (`fade()`, `el()` do this).
|
|
40
|
+
12. Ids come from the instance: anything in `<defs>` (clip path, gradient,
|
|
41
|
+
mask, marker, filter) is named `${idPrefix}-name`, with `idPrefix` from
|
|
42
|
+
`frame(t, { idPrefix })`. Two instances on one page (wide and tall, or the
|
|
43
|
+
same diagram twice) then never share an id. The gate renders with two
|
|
44
|
+
prefixes and refuses an id both share.
|
|
40
45
|
|
|
41
46
|
## 3. Authoring a timeline
|
|
42
47
|
|
|
@@ -32,8 +32,8 @@ animated-diagram skill, `references/targets.md`.
|
|
|
32
32
|
```bash
|
|
33
33
|
mk export spec.json -o out/review --png --qc
|
|
34
34
|
```
|
|
35
|
-
`index.html` holds the steps, frames 0.2 s before and after each step, a phone-size row
|
|
36
|
-
review checklist. Fill in the review report (animated-diagram
|
|
35
|
+
`index.html` holds the steps, frames 0.2 s before and after each step, a phone-size row (the
|
|
36
|
+
scene's `tall` layout at 360 px, as a phone shows it) and the review checklist. Fill in the review report (animated-diagram
|
|
37
37
|
`references/qc.md`) and get a human approval line before delivery.
|
|
38
38
|
|
|
39
39
|
## Video
|
|
@@ -53,6 +53,22 @@ mk build spec.json -o out/page.html -f wide # Craft Page / standalone in
|
|
|
53
53
|
mk bake spec.json -o out/diagram.svg -f wide --fps 12 # zero-JS animated SVG
|
|
54
54
|
```
|
|
55
55
|
|
|
56
|
+
A custom module whose text comes from the caller (a site's dictionary) takes
|
|
57
|
+
scene options: `--options labels.json`, inline JSON, or an `.mjs` whose default
|
|
58
|
+
export is `({ format, locale }) => options`. `check`, `export`, `build`, `bake`,
|
|
59
|
+
`video` and `icon` pass them to the module's factory unchanged.
|
|
60
|
+
|
|
61
|
+
For plain HTML or a framework-independent live embed, use
|
|
62
|
+
`mk vendor public/motion-kit --adapter element`, then load
|
|
63
|
+
`./motion-kit/adapter/motion-diagram.mjs` with `type="module"` and place
|
|
64
|
+
`<motion-diagram src="./spec.json" format="wide">` around a final-frame SVG
|
|
65
|
+
or image fallback. Copy the spec to `public/spec.json` and serve over HTTP.
|
|
66
|
+
Inline JSON (`spec` attribute or child
|
|
67
|
+
`script[type="application/json"]`), `locale`, `theme` and JSON `style-spec`
|
|
68
|
+
are supported; the normal `style` attribute stays CSS. The element exposes
|
|
69
|
+
`controller` after `motion-ready`, preserves the fallback during loading or
|
|
70
|
+
errors, and cleans up on disconnect. Full usage: `adapters/element/README.md`.
|
|
71
|
+
|
|
56
72
|
## Delivery package
|
|
57
73
|
|
|
58
74
|
```
|