@liqweed/motion-kit 0.9.1 → 0.11.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 +3 -1
- package/cli/motion-kit.mjs +15 -1
- package/docs/spec/technique.md +76 -20
- package/examples/connectors.scene.mjs +199 -0
- package/examples/custom-pulse.scene.mjs +9 -4
- package/lib/check.mjs +14 -14
- package/lib/gate.mjs +27 -12
- package/package.json +2 -2
- package/runtime/connectors.mjs +243 -0
- package/runtime/kit.mjs +5 -3
- package/runtime/scene.mjs +5 -3
- package/runtime/style.mjs +86 -21
- package/runtime/types/flowchart.mjs +9 -1
- package/runtime/types/hub-spoke.mjs +9 -1
- package/runtime/types/index.mjs +24 -6
- package/runtime/types/sequence.mjs +9 -1
- package/runtime/types/stack.mjs +9 -1
- package/runtime/types/timeline.mjs +9 -1
- package/runtime/types/walk.mjs +9 -1
- package/skills/animated-diagram/SKILL.md +3 -2
- package/skills/animated-diagram/references/custom-scenes.md +34 -4
- package/skills/animated-diagram/references/motion-vocabulary.md +19 -0
- package/skills/animated-diagram/references/styles.md +26 -7
- package/skills/motion-render/SKILL.md +1 -1
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "motion-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.11.0",
|
|
4
4
|
"description": "Deterministic animated diagrams: scenes as pure functions of time for live pages, Slidev, slide frames, baked SVG and video; plus project logos/icons.",
|
|
5
5
|
"author": { "name": "Ophir Radnitz" },
|
|
6
6
|
"repository": "https://github.com/liqweed/motion-kit",
|
package/README.md
CHANGED
|
@@ -58,6 +58,7 @@ runtime/ dependency-free ES modules (browser + Node)
|
|
|
58
58
|
motion.mjs easing (exact cubic-bezier), progress, critically damped spring, retarget, split edges
|
|
59
59
|
svg.mjs escaping, rounding, el/text/fade, polyline + Bézier arc-length, drawOn, several tokens
|
|
60
60
|
iso.mjs isometric kit for custom scenes: camera, solids, depth order, label anchors
|
|
61
|
+
connectors.mjs dashed connectors, diamond junctions and single-pass light pulses for custom scenes
|
|
61
62
|
wrap.mjs label wrapping with hard budgets
|
|
62
63
|
style.mjs tokens, neutral style, contrast checks, token resolution
|
|
63
64
|
scene.mjs scene contract, formats, renderSvg
|
|
@@ -72,7 +73,8 @@ adapters/ slidev (Vue), astro, element (custom element), page (README)
|
|
|
72
73
|
skills/ animated-diagram, motion-render, project-logo (Claude Code / Craft skills)
|
|
73
74
|
examples/ order-flow (sequence), smart-home (hub-spoke), incident (timeline),
|
|
74
75
|
web-stack (stack), custom-pulse (custom module),
|
|
75
|
-
isometric-swivel (custom module: isometric kit, several tokens)
|
|
76
|
+
isometric-swivel (custom module: isometric kit, several tokens),
|
|
77
|
+
connectors (custom module: connectors, diamond junctions, pulses)
|
|
76
78
|
bench/ heavy scene for npm run bench:player (live-player frame cost)
|
|
77
79
|
brand/ logo scene (built with motion-kit); renders go to assets/ + .idea/ (npm run media)
|
|
78
80
|
assets/ generated project icon: icon.svg, icon.png, icon-animated.svg
|
package/cli/motion-kit.mjs
CHANGED
|
@@ -30,6 +30,7 @@ import { fileURLToPath } from "node:url";
|
|
|
30
30
|
import { parseArgs } from "node:util";
|
|
31
31
|
import { bake, bakeStats } from "../runtime/bake.mjs";
|
|
32
32
|
import { FORMATS } from "../runtime/scene.mjs";
|
|
33
|
+
import { checkContrast, sharedPairs } from "../runtime/style.mjs";
|
|
33
34
|
import { SCENE_TYPES } from "../runtime/types/index.mjs";
|
|
34
35
|
import { checkScene } from "../lib/check.mjs";
|
|
35
36
|
import { checkFiles } from "../lib/gate.mjs";
|
|
@@ -79,6 +80,10 @@ function fail(msg) {
|
|
|
79
80
|
console.error(`motion-kit: ${msg}`);
|
|
80
81
|
process.exit(1);
|
|
81
82
|
}
|
|
83
|
+
/** Contrast the scene does not draw but the style misses: said, never failed (G12). @param {string[]} warnings */
|
|
84
|
+
function warnAll(warnings) {
|
|
85
|
+
for (const w of warnings) console.error(`motion-kit: warning: contrast: ${w}`);
|
|
86
|
+
}
|
|
82
87
|
function need(v, what) {
|
|
83
88
|
if (!v) fail(`${cmd}: ${what} is required`);
|
|
84
89
|
return v;
|
|
@@ -124,6 +129,11 @@ async function main() {
|
|
|
124
129
|
const loaded = await loadScene(file, sopts);
|
|
125
130
|
const r = checkScene(loaded.scene, { style });
|
|
126
131
|
if (!r.ok) fail(`scene fails the gate:\n - ${r.problems.join("\n - ")}`);
|
|
132
|
+
warnAll(r.warnings);
|
|
133
|
+
// The page also paints the player: button text and borders, the selected step,
|
|
134
|
+
// captions, the focus outline, and (unless --no-heading) the heading on the canvas.
|
|
135
|
+
const player = checkContrast(style, sharedPairs(...(a["no-heading"] ? [] : ["ink/bg"]), "ink/surface", "onAccent/accent", "muted/bg", "emphasis/bg", "line/bg", "accent/bg"));
|
|
136
|
+
if (player.length) fail(`the player in the page fails the gate:\n - ${player.join("\n - ")}`);
|
|
127
137
|
const html = buildHtml(loaded, { style, ...where, options: sopts.options, scrubber: !a["no-scrubber"], heading: !a["no-heading"] });
|
|
128
138
|
if (/<\/script/i.test(html.slice(html.indexOf("<script>") + 8, html.lastIndexOf("</script>")))) fail("bundled code contains </script>");
|
|
129
139
|
const out = need(a.out, "--out");
|
|
@@ -138,6 +148,7 @@ async function main() {
|
|
|
138
148
|
const { scene } = await loadScene(file, sopts);
|
|
139
149
|
const r = checkScene(scene, { style });
|
|
140
150
|
if (!r.ok) fail(`scene fails the gate:\n - ${r.problems.join("\n - ")}`);
|
|
151
|
+
warnAll(r.warnings);
|
|
141
152
|
if (a.png && !(await rasterizer())) fail("--png needs @resvg/resvg-js or Chrome");
|
|
142
153
|
// The contact sheet's phone row shows the tall layout, as a phone does.
|
|
143
154
|
/** @type {{ scene?: any, error?: string }} */
|
|
@@ -159,6 +170,7 @@ async function main() {
|
|
|
159
170
|
const { scene } = await loadScene(file, await sceneOpts(file));
|
|
160
171
|
const gate = checkScene(scene, { style });
|
|
161
172
|
if (!gate.ok) fail(`scene fails the gate:\n - ${gate.problems.join("\n - ")}`);
|
|
173
|
+
warnAll(gate.warnings);
|
|
162
174
|
const svg = bake(scene, { fps: Number(a.fps ?? 15), style, theme: a.theme, background: a.background });
|
|
163
175
|
const out = need(a.out, "--out");
|
|
164
176
|
writeFileSync(out, svg);
|
|
@@ -171,6 +183,7 @@ async function main() {
|
|
|
171
183
|
const { scene } = await loadScene(file, await sceneOpts(file));
|
|
172
184
|
const gate = checkScene(scene, { style });
|
|
173
185
|
if (!gate.ok) fail(`scene fails the gate:\n - ${gate.problems.join("\n - ")}`);
|
|
186
|
+
warnAll(gate.warnings);
|
|
174
187
|
const out = need(a.out, "--out");
|
|
175
188
|
const r = await renderVideo(scene, {
|
|
176
189
|
out,
|
|
@@ -192,6 +205,7 @@ async function main() {
|
|
|
192
205
|
const { scene } = await loadScene(file, await sceneOpts(file, { ...where, format: format ?? "1:1" }));
|
|
193
206
|
const r = checkScene(scene, { style });
|
|
194
207
|
if (!r.ok) fail(`scene fails the gate:\n - ${r.problems.join("\n - ")}`);
|
|
208
|
+
warnAll(r.warnings);
|
|
195
209
|
const png = !a["no-png"];
|
|
196
210
|
if (png && !(await rasterizer())) fail("icon PNG needs @resvg/resvg-js or Chrome (or pass --no-png)");
|
|
197
211
|
const root = resolve(need(a.out, "--out"));
|
|
@@ -297,7 +311,7 @@ const VENDOR_CHECK = `#!/usr/bin/env node
|
|
|
297
311
|
//
|
|
298
312
|
// Every format unless --format; for a spec every locale its strings carry, for
|
|
299
313
|
// a custom module its exported locales (default "en"), unless --locale. The style (neutral by default) must
|
|
300
|
-
// pass the contrast
|
|
314
|
+
// pass the contrast of the pairs each scene draws (G12). --options passes scene options to custom modules:
|
|
301
315
|
// a .json file, inline JSON, or an .mjs module exporting ({ format, locale }) => options.
|
|
302
316
|
// Exits 1 if anything fails; a file that cannot be loaded fails on its own.
|
|
303
317
|
import { parseArgs } from "node:util";
|
package/docs/spec/technique.md
CHANGED
|
@@ -38,7 +38,7 @@ A scene is a plain object (`runtime/scene.mjs:1-18`).
|
|
|
38
38
|
| `steps` | `{at, label, detail?, id?}[]` | MUST | ≥ 1 step; `at` strictly increasing; `at ≤ duration` (+1e-9); every `label` non-empty; an `id`, if present, is a non-empty string unique within the scene [throws] (`validateScene`). The last step is the finished diagram. Page scripts address steps by `id` (§10.2); scene types copy a spec node's, hub's or spoke's `id`. |
|
|
39
39
|
| `frame(t, ctx)` | `(number, {idPrefix}) → string` | MUST | Inner SVG markup at `t` (§2). `ctx.idPrefix` is unique to the rendered instance; every id the frame defines (clip paths, gradients, masks, markers, filters) MUST start with it, as `${idPrefix}-name` [gate] G14. A frame that defines no ids MAY ignore `ctx`. |
|
|
40
40
|
| `stepLabelsInFrame` | boolean | MAY | `false` declares narrative steps whose labels are not drawn; exempts the scene from gate rule G10 (`lib/check.mjs:74`; used by `examples/custom-pulse.scene.mjs:137`, `brand/logo.scene.mjs:108`). |
|
|
41
|
-
| `contrastPairs` | `{fg, bg, min, use?}[]` | MAY |
|
|
41
|
+
| `contrastPairs` | `{fg, bg, min, use?}[]` | MAY | The token pairs the scene draws (§6). The gate holds the style to exactly these in both themes, and only warns about the shared pairs (`CONTRAST_PAIRS`) the list leaves out; a scene that declares none is held to every shared pair [gate] G12 (`lib/check.mjs`, `contrastReport`; used by `examples/custom-pulse.scene.mjs`; every registered scene type sets it). Tokens MUST be known and `min` in [1, 21]. |
|
|
42
42
|
| `labelBoxes(t)` | `(number) → LabelBox[]` | MAY | The box of every label `frame(t)` draws, in the scene's own coordinates (`{id, x, y, width, height, stem?, opacity?}`; `labelAnchor` returns one, §4.9). Must be a function [throws]. The gate fails a scene whose labels overlap, whose stems cross a label or that leave the picture [gate] G15 (`lib/check.mjs`, rule 9; each box MUST be `{id, x, y, width, height}` with finite numbers [gate]; used by `examples/isometric-swivel.scene.mjs`). |
|
|
43
43
|
| `type`, `format`, `locale` | string | MAY | Set by scene types; recorded in the export manifest (`lib/export.mjs:75-77`). |
|
|
44
44
|
|
|
@@ -48,7 +48,7 @@ A scene is a plain object (`runtime/scene.mjs:1-18`).
|
|
|
48
48
|
`sceneFromModule` (`runtime/kit.mjs`) with
|
|
49
49
|
`opts = { ...options, format, locale, kit }`. `options` are the caller's
|
|
50
50
|
serializable scene options, passed unchanged; option names `format`,
|
|
51
|
-
`locale` and `kit` throw. `kit` is the flat exports of the `motion`, `svg`, `iso`, `style`, `scene` and `wrap` runtime modules (`KIT`); it has no `createScene`, scene types or player. Both paths
|
|
51
|
+
`locale` and `kit` throw. `kit` is the flat exports of the `motion`, `svg`, `iso`, `style`, `scene`, `connectors` and `wrap` runtime modules (`KIT`); it has no `createScene`, scene types or player. Both paths
|
|
52
52
|
run `validateScene`. The CLI (`--options`), the vendored gate and the Astro
|
|
53
53
|
adapter call `sceneFromModule`, so one module with the same options, format
|
|
54
54
|
and locale gives the same scene everywhere. A `build` page calls the factory
|
|
@@ -270,6 +270,48 @@ functions; a colour is a token name, resolved with `tok()` (G4 applies).
|
|
|
270
270
|
does when its progress is linear (`tokenPoints` defaults to `easeStandard`;
|
|
271
271
|
pass `ease: linear`).
|
|
272
272
|
|
|
273
|
+
### 4.10 Connectors (`runtime/connectors.mjs`)
|
|
274
|
+
|
|
275
|
+
For custom scenes that tie pieces together; handed to them in `kit`. Pure
|
|
276
|
+
functions; a colour is a token name (G4 applies).
|
|
277
|
+
|
|
278
|
+
- **Path.** `connectorPath(points, {camera?})` is a route through flat points
|
|
279
|
+
(picture pixels) or, with a `camera`, through world points projected by it.
|
|
280
|
+
`at(f)`, `cut(f)` (the picture points up to `f`) and `tip(f)` (the point and
|
|
281
|
+
the direction of travel, in radians) go by distance along the path, in the
|
|
282
|
+
world under a camera, so a pulse on a linear `ease` keeps a constant world
|
|
283
|
+
speed whatever the camera does. It throws for fewer than two points, a
|
|
284
|
+
non-finite coordinate or a path of no length.
|
|
285
|
+
- **Connector.** `drawConnector(path, p, {stroke, width, dash, arrow,
|
|
286
|
+
arrowSize, opacity, id})` draws the path up to fraction `p` (the eased
|
|
287
|
+
progress of a draw-on) as a dashed polyline: nothing for `p ≤ 0`; the dash
|
|
288
|
+
pattern (default `6 5`) starts at the path's start, so dashes stand still as
|
|
289
|
+
the line grows, and `p ≥ 1` is the dashed line it rests as. An open-V
|
|
290
|
+
arrowhead (default on) rides the leading end and fades in over the first
|
|
291
|
+
tenth of `p`.
|
|
292
|
+
- **Junction.** `drawJunction({at, camera?, plane, size, lit, fill, stroke,
|
|
293
|
+
litFill, litStroke, strokeWidth, opacity, id})` draws a diamond, a square
|
|
294
|
+
turned 45°, `size` pixels from centre to corner. `plane: "screen"` stands on
|
|
295
|
+
the picture; `"floor"` lies in the floor plane of an iso view: the same
|
|
296
|
+
diamond flattened by `sin(elevation)`, full in plan view. `lit` (0..1)
|
|
297
|
+
cross-fades the reached layer over the resting one. It throws for a size of
|
|
298
|
+
0 or less and for another plane.
|
|
299
|
+
- **Pulse.** `drawPulse(path, t, run, {color, radius})` is a light that
|
|
300
|
+
travels the connector once. `run` is `{start, duration, lag?, ease?, hold?}`:
|
|
301
|
+
the head takes `duration` s on `ease` (default `easeStandard`) and the tail
|
|
302
|
+
follows `lag` s later (default `PULSE_LAG`, 0.12 s) on the same curve, so the
|
|
303
|
+
light stretches in flight and gathers at the end (split edges, §4.5). The
|
|
304
|
+
head has a glow (three halos of one token, fainter outward) and the tail
|
|
305
|
+
fades toward its trailing end. It grows in over the first tenth of its life
|
|
306
|
+
and, unless held, fades over the last sixth. It draws nothing before `start`
|
|
307
|
+
and, without `hold`, from `pulseEnd(run)` = `start + duration + lag` on; with
|
|
308
|
+
`hold` the head stays lit at the end of the connector. `pulseHead(t, run)` is
|
|
309
|
+
the head's fraction of the path, for lighting a target as the pulse passes.
|
|
310
|
+
- **Canon.** A pulse runs once, in a step's beat, like a token (§4.8): every
|
|
311
|
+
pulse of the beat is over (`pulseEnd`) at least 50 ms before the step's `at`,
|
|
312
|
+
its target has filled, and nothing repeats while a step rests, so the
|
|
313
|
+
settled-frame rule (G6) holds. Several pulses may run in one beat.
|
|
314
|
+
|
|
273
315
|
## 5. Markup
|
|
274
316
|
|
|
275
317
|
- Text and attribute values MUST be escaped (`& < > " '`) via `esc`, `text` or
|
|
@@ -312,21 +354,34 @@ functions; a colour is a token name, resolved with `tok()` (G4 applies).
|
|
|
312
354
|
literal (`runtime/scene.mjs:84`, `runtime/style.mjs:86-93`), because slide
|
|
313
355
|
apps, rasterizers and image viewers ignore CSS variables; an unresolvable
|
|
314
356
|
token throws.
|
|
315
|
-
- **Contrast** (`runtime/style.mjs`, `checkContrast`, WCAG
|
|
316
|
-
luminance)
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
`
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
`line` on `
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
`
|
|
328
|
-
|
|
329
|
-
|
|
357
|
+
- **Contrast** (`runtime/style.mjs`, `checkContrast`, `contrastReport`, WCAG
|
|
358
|
+
relative luminance). WCAG judges what a scene draws, not a palette: text
|
|
359
|
+
needs 4.5:1 against what is behind it (1.4.3), the parts of a graphic that
|
|
360
|
+
carry meaning 3:1 against the colours adjacent to them (1.4.11). So the gate
|
|
361
|
+
holds a scene to the token pairs it draws, in both themes, and no others.
|
|
362
|
+
`CONTRAST_PAIRS` is the shared list of what the scene types and shared parts
|
|
363
|
+
draw where the pair carries meaning in a step frame: text ≥ 4.5:1 —
|
|
364
|
+
`ink`/`muted` on `bg` and `surface`, `onAccent` on `accent`; shapes ≥ 3:1 —
|
|
365
|
+
`line`, `accent`, `emphasis` on `bg`, and `emphasis` on `accent` (the ring
|
|
366
|
+
marking the current node sits 3.5 units from the reached node it surrounds,
|
|
367
|
+
and tells "here" from "reached" without hue). Each registered scene type
|
|
368
|
+
records which of them it draws (`contrastPairs` on its scenes,
|
|
369
|
+
`SCENE_TYPE_PAIRS` in `runtime/types/index.mjs`): a `hub-spoke` draws no text
|
|
370
|
+
on the canvas, a `sequence` draws no `ink` on `surface`.
|
|
371
|
+
A custom scene states what it draws in `contrastPairs` (§1; an empty list counts as none; `sharedPairs`
|
|
372
|
+
picks shared ones by name, others are written out). The pairs it declares
|
|
373
|
+
are the gate's problems; the shared pairs it leaves out are only warnings,
|
|
374
|
+
named with their ratio and threshold in both themes. A scene that declares
|
|
375
|
+
nothing is held to every shared pair, so no scene loses a check by saying
|
|
376
|
+
nothing. `CONTRAST_EXEMPT` lists, with a reason each, the pairs no scene
|
|
377
|
+
type draws or draws only in motion: `line` on `surface` (an outline is told
|
|
378
|
+
from the canvas outside it), `accent` on `surface` and `emphasis` on
|
|
379
|
+
`surface` and `accent` on `line` (only in motion), `onAccent` on `emphasis`
|
|
380
|
+
(only the logo; logos are exempt from WCAG 1.4.11). `motion-kit check` MUST
|
|
381
|
+
fail a scene whose style violates a pair it draws [gate] G12
|
|
382
|
+
(`lib/check.mjs`) and MUST report, once per run, every shared pair the style
|
|
383
|
+
misses with the scene types that draw it (`lib/gate.mjs`), without failing
|
|
384
|
+
on it. `neutral` MUST pass every shared pair (`test/runtime.test.mjs`).
|
|
330
385
|
- motion-kit ships only `neutral` (`styles/neutral.json`); brand styles MUST
|
|
331
386
|
live in the consumer repo.
|
|
332
387
|
|
|
@@ -592,8 +647,8 @@ that removes every listener, observer and mark they added.
|
|
|
592
647
|
`motion-kit check` and the vendored `check.mjs` both run `checkFiles`
|
|
593
648
|
(`lib/gate.mjs`): every file × format (all six unless `--format`, repeatable)
|
|
594
649
|
× locale (`--locale`, repeatable; else every locale a spec's strings carry, and
|
|
595
|
-
`en` for a module, §7), with `--options` for modules, plus the style contrast
|
|
596
|
-
|
|
650
|
+
`en` for a module, §7), with `--options` for modules, plus the style contrast check of the pairs each scene draws and a once-per-run warning
|
|
651
|
+
for the shared pairs the style misses. A file that cannot be read, parsed or built fails on its own and the
|
|
597
652
|
remaining files are still checked; the exit code is 1 on any failure. `npm run gate` = unit tests +
|
|
598
653
|
`check` over `examples/` and `brand/` (`package.json:15-18`).
|
|
599
654
|
|
|
@@ -610,7 +665,7 @@ remaining files are still checked; the exit code is 1 on any failure. `npm run g
|
|
|
610
665
|
| G9 | `duration ≤ 12` s. | `:68` | Hard limit; authoring target ≤ 8 s. |
|
|
611
666
|
| G10 | Every word of every step label (escaped, trailing `/` stripped) appears in the final frame's text, unless `stepLabelsInFrame === false`. | `:72-77` | Step buttons and slides refer to things the viewer can see. Word-level, so it does not prove the label is contiguous. |
|
|
612
667
|
| G11 | Every sampled frame MUST render the same bytes under two stubbed clocks as under the real one: `Date`, `performance.now`, `Temporal.Now` and `Math.random` fixed at 1970 and 0, then at 2100 and ≈ 1, the globals restored afterwards. `frame.toString()` MUST NOT contain `Date.now`, `new Date`, `Math.random`, `performance.now`, `Temporal.Now`. | `lib/check.mjs` (rules 1 and 6) | T1. The stubbed render catches reads in the helpers a frame calls; the source scan, code paths the samples miss. A reference taken before the check runs (`const D = Date` at import) escapes the stub. |
|
|
613
|
-
| G12 |
|
|
668
|
+
| G12 | The style passes WCAG contrast in both themes for each pair the scene draws: its `contrastPairs`, which the scene types set to the shared pairs they draw, else every pair in `CONTRAST_PAIRS`. Shared pairs it does not draw are warnings, never failures; the run reports every shared pair the style misses once. | `lib/check.mjs`, `lib/gate.mjs` (`styleWarnings`), `runtime/style.mjs` (`contrastReport`) | Legibility in light and dark, for the pairs actually drawn (WCAG 1.4.3 and 1.4.11 judge rendered content, §6). |
|
|
614
669
|
| G13 | Scene construction succeeds for the format × locale (validation, fit, collisions, wrapping). | `lib/gate.mjs` | Reject, don't invent: a broken picture never renders. |
|
|
615
670
|
| G14 | Rendered with two different `idPrefix` values, sampled frames share no `id`. | `lib/check.mjs` (rule 7) | Two instances on one page (wide and tall, or one diagram twice) must not share ids: `url(#x)` resolves to the first element with that id, and WCAG 2.1 SC 4.1.1 forbids duplicates. |
|
|
616
671
|
| G15 | If the scene defines `labelBoxes`, at each sampled time and each step time: no two boxes with `opacity` > 0 are closer than 4 px, no stem crosses another box and every box lies inside the picture (`0, 0, width, height`). `labelBoxes` MUST return an array and not throw. Each problem is reported once, at its first time. | `lib/check.mjs` (rule 9), `runtime/iso.mjs` (`labelProblems`) | Labels placed in a projected view move with the camera; nothing else checks them against one another. Opacity 0 is not drawn, so a scene hides labels while the camera moves. |
|
|
@@ -634,6 +689,7 @@ Recorded 2026-11-18 for [#12](https://github.com/liqweed/motion-kit/issues/12):
|
|
|
634
689
|
| Motion tokens | A style MAY set `motion.enter` (entrances) and `motion.move` (movement between visible states) as four numbers, a CSS `cubic-bezier(x1, y1, x2, y2)`, each from 0 to 1: no curve overshoots. Defaults: `(0, 0, .2, 1)` and `(.4, 0, .2, 1)`. Built-in scene types read them through `easings(style.motion)`; durations, delays and step times stay fixed, so a curve changes how a move travels and never when a step settles. A curve that is still moving near its end (a linear one) would leave a step frame unsettled, so `easings` finishes it in the first 95 % of each move and holds it at 1 for the last 5 %; a curve that ends flat (both defaults) is the exact CSS curve. Custom scenes MAY do the same. |
|
|
635
690
|
| Vendored parity | CLI and vendored checks MUST call the same `lib/gate.mjs` and `lib/check.mjs`, including contrast, locales and caller options. |
|
|
636
691
|
| Neutral contrast | Keep emphasis-on-accent at 3:1, the darker light accent and lighter dark emphasis. The site chrome follows the corresponding neutral tokens. |
|
|
692
|
+
| Drawn pairs only | Recorded 2026-11-21 for [#72](https://github.com/liqweed/motion-kit/issues/72), after [#45](https://github.com/liqweed/motion-kit/issues/45) made every shared pair a failure for every scene. WCAG 1.4.3 and 1.4.11 judge what a scene draws against the colours next to it, so a pair that never meets in a scene is not a requirement for it: the gate fails the pairs a scene draws and warns about the other shared ones. Built-in types record the pairs they draw; a custom scene that declares `contrastPairs` is held to those, one that declares nothing to all shared pairs (no check is lost by saying nothing). `emphasis` on `accent` stays a failure for the types whose ring or dot touches the reached colour (`sequence`, `flowchart`, and the dots of `hub-spoke`, `stack` and the walks), though it rests on WCAG 1.4.1 and the shape already meets it, because the library's own call is to keep it. Thresholds and `neutral` are unchanged; detecting drawn pairs from the rendered SVG is left open. [#65](https://github.com/liqweed/motion-kit/issues/65) (logos) reuses the mechanism. |
|
|
637
693
|
|
|
638
694
|
The controller also exposes `onStep(callback) → unsubscribe`, with an immediate
|
|
639
695
|
current index and subsequent changed indices (`-1` before the first step).
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Example custom scene: a request fans out through a diamond splitter, then a
|
|
3
|
+
* result rides an isometric feeder line through three junctions.
|
|
4
|
+
*
|
|
5
|
+
* Shows the connector parts (runtime/connectors.mjs): dashed connectors that
|
|
6
|
+
* draw on and rest as dashed lines, with open-V arrowheads; diamond junctions,
|
|
7
|
+
* flat on the picture and lying in the floor plane of an isometric view, that
|
|
8
|
+
* light when a pulse reaches them; and light pulses with a glow and a fading
|
|
9
|
+
* tail. A pulse runs once, inside its step's beat, and is over (`pulseEnd`)
|
|
10
|
+
* before the step's time, so every step frame is settled. Nothing loops: the
|
|
11
|
+
* scene plays once and holds its last frame. Pure: frame(t) depends only on
|
|
12
|
+
* t and constants.
|
|
13
|
+
*/
|
|
14
|
+
import { easeOut, easeStandard, linear, progress } from "../runtime/motion.mjs";
|
|
15
|
+
import { CAMERA_ISOMETRIC, box, drawSolid, fitCamera, labelAnchor, orderSolids, slab } from "../runtime/iso.mjs";
|
|
16
|
+
import { connectorPath, drawConnector, drawJunction, drawPulse, pulseEnd } from "../runtime/connectors.mjs";
|
|
17
|
+
import { FORMATS, localize } from "../runtime/scene.mjs";
|
|
18
|
+
import { tok } from "../runtime/style.mjs";
|
|
19
|
+
import { el, fade, text } from "../runtime/svg.mjs";
|
|
20
|
+
import { wrapLabel } from "../runtime/wrap.mjs";
|
|
21
|
+
|
|
22
|
+
export const locales = ["en", "nl"];
|
|
23
|
+
|
|
24
|
+
const COPY = {
|
|
25
|
+
title: { en: "A request fans out, then rides the feeder", nl: "Een verzoek splitst en volgt de aanvoerlijn" },
|
|
26
|
+
description: {
|
|
27
|
+
en: "A request crosses a diamond splitter and fans out to three services; a result then rides an isometric feeder line through three junctions to the shelf.",
|
|
28
|
+
nl: "Een verzoek passeert een ruitvormige splitser en waaiert uit naar drie diensten; een resultaat volgt daarna een isometrische aanvoerlijn langs drie knooppunten naar het schap.",
|
|
29
|
+
},
|
|
30
|
+
source: { en: "Request", nl: "Verzoek" },
|
|
31
|
+
targets: [
|
|
32
|
+
{ en: "Search", nl: "Zoeken" },
|
|
33
|
+
{ en: "Cache", nl: "Cache" },
|
|
34
|
+
{ en: "Audit", nl: "Logboek" },
|
|
35
|
+
],
|
|
36
|
+
stations: [
|
|
37
|
+
{ en: "Intake", nl: "Intake" },
|
|
38
|
+
{ en: "Shelf", nl: "Schap" },
|
|
39
|
+
],
|
|
40
|
+
steps: [
|
|
41
|
+
{ label: { en: "Request reaches the splitter", nl: "Verzoek bereikt de splitser" }, detail: { en: "One pulse crosses the first connector and lights the diamond.", nl: "Eén puls steekt de eerste verbinding over en laat de ruit oplichten." } },
|
|
42
|
+
{ label: { en: "It fans out", nl: "Het waaiert uit" }, detail: { en: "Three pulses leave the splitter together and light their services.", nl: "Drie pulsen verlaten de splitser tegelijk en laten hun diensten oplichten." } },
|
|
43
|
+
{ label: { en: "The feeder delivers", nl: "De aanvoerlijn levert" }, detail: { en: "A pulse rides the isometric feeder through three junctions to the shelf.", nl: "Een puls volgt de isometrische aanvoerlijn langs drie knooppunten naar het schap." } },
|
|
44
|
+
],
|
|
45
|
+
};
|
|
46
|
+
|
|
47
|
+
// Timeline, in seconds. Every pulse is over, and its target has lit, before the
|
|
48
|
+
// step that follows it; the gate checks the step frames are settled.
|
|
49
|
+
const ENTER = 0.4;
|
|
50
|
+
const DRAW = 0.5;
|
|
51
|
+
const FILL = 0.25;
|
|
52
|
+
const IN = { start: 2, duration: 0.6 };
|
|
53
|
+
const OUT = { start: 3.2, duration: 0.7 };
|
|
54
|
+
const FEED = { start: 4.5, duration: 1.6, ease: linear };
|
|
55
|
+
const STEP_SPLIT = pulseEnd(IN) + FILL + 0.1;
|
|
56
|
+
const STEP_FAN = pulseEnd(OUT) + FILL + 0.1;
|
|
57
|
+
const STEP_FEED = pulseEnd(FEED) + FILL + 0.1;
|
|
58
|
+
const DURATION = STEP_FEED + 0.35;
|
|
59
|
+
|
|
60
|
+
// The feeder, in world units: a floor, two stations and a path with three turns.
|
|
61
|
+
const FLOOR = { w: 10, d: 6.4, h: 0.3 };
|
|
62
|
+
const TOP = FLOOR.h;
|
|
63
|
+
const STATIONS = [
|
|
64
|
+
{ x: -3.6, y: -1.8, w: 1.6, d: 1.6, h: 0.8 },
|
|
65
|
+
{ x: 1.8, y: 1.9, w: 1.6, d: 1.6, h: 0.8 },
|
|
66
|
+
];
|
|
67
|
+
const FEEDER = [
|
|
68
|
+
{ x: -2.6, y: -1.8 },
|
|
69
|
+
{ x: -0.6, y: -1.8 },
|
|
70
|
+
{ x: -0.6, y: -0.4 },
|
|
71
|
+
{ x: 1.8, y: -0.4 },
|
|
72
|
+
{ x: 1.8, y: 0.9 },
|
|
73
|
+
].map((p) => ({ ...p, z: TOP }));
|
|
74
|
+
const TURNS = [1, 2, 3];
|
|
75
|
+
|
|
76
|
+
export default function make({ format = "16:9", locale = "en" } = {}) {
|
|
77
|
+
const f = FORMATS[format];
|
|
78
|
+
if (!f) throw new Error(`unknown format "${format}"`);
|
|
79
|
+
const W = f.width;
|
|
80
|
+
const H = f.height || (format === "tall" ? 640 : 360);
|
|
81
|
+
const fs = 15;
|
|
82
|
+
|
|
83
|
+
// Two panels, one above the other: the flat fan-out, then the isometric feeder.
|
|
84
|
+
const split = Math.round(H * 0.4);
|
|
85
|
+
const flat = { x: 16, y: 12, w: W - 32, h: split - 16 };
|
|
86
|
+
const iso = { x: 16, y: split + 4, w: W - 32, h: H - split - 16 };
|
|
87
|
+
|
|
88
|
+
/* ---- the flat fan-out ---- */
|
|
89
|
+
const along = flat.w / flat.h >= 1.4 ? "x" : "y"; // the direction the flow runs
|
|
90
|
+
const span = along === "x" ? flat.w : flat.h;
|
|
91
|
+
const cross = along === "x" ? flat.h : flat.w;
|
|
92
|
+
const gap = along === "x" ? Math.min(64, (cross - 40) / 2.4) : Math.min(170, (cross - 16) / 3); // between targets, across the flow
|
|
93
|
+
const nodeAcross = along === "x" ? 40 : Math.min(150, gap - 12);
|
|
94
|
+
const nodeAlong = along === "x" ? Math.min(150, span * 0.22) : 40;
|
|
95
|
+
const nodeW = along === "x" ? nodeAlong : nodeAcross;
|
|
96
|
+
const nodeH = along === "x" ? nodeAcross : nodeAlong;
|
|
97
|
+
/** @param {number} a along the flow, from the panel's start @param {number} b across it, from its middle */
|
|
98
|
+
const at = (a, b) => (along === "x" ? { x: flat.x + a, y: flat.y + flat.h / 2 + b } : { x: flat.x + flat.w / 2 + b, y: flat.y + a });
|
|
99
|
+
const ha = nodeAlong / 2;
|
|
100
|
+
const aSource = ha + 6;
|
|
101
|
+
const aSplit = span * 0.42;
|
|
102
|
+
const aTarget = span - ha - 6;
|
|
103
|
+
const spread = [-gap, 0, gap];
|
|
104
|
+
const MARK = 4; // clearance between a connector's end and a node
|
|
105
|
+
|
|
106
|
+
const toSplit = connectorPath([at(aSource + ha + MARK, 0), at(aSplit, 0)]);
|
|
107
|
+
const fan = spread.map((b) => connectorPath(b === 0 ? [at(aSplit, 0), at(aTarget - ha - MARK, 0)] : [at(aSplit, 0), at(aSplit, b), at(aTarget - ha - MARK, b)]));
|
|
108
|
+
const names = [COPY.source, ...COPY.targets].map((s) => wrapLabel(localize(s, locale), Math.floor((nodeW - 16) / (fs * 0.56)), 1));
|
|
109
|
+
const nodes = [at(aSource, 0), ...spread.map((b) => at(aTarget, b))];
|
|
110
|
+
|
|
111
|
+
/* ---- the isometric feeder ---- */
|
|
112
|
+
const extent = [
|
|
113
|
+
...[-1, 1].flatMap((sx) => [-1, 1].map((sy) => ({ x: (sx * FLOOR.w) / 2, y: (sy * FLOOR.d) / 2, z: 0 }))),
|
|
114
|
+
...STATIONS.flatMap((s) => [-1, 1].flatMap((dx) => [-1, 1].map((dy) => ({ x: s.x + (dx * s.w) / 2, y: s.y + (dy * s.d) / 2, z: TOP + s.h })))),
|
|
115
|
+
];
|
|
116
|
+
const fitted = fitCamera(extent, CAMERA_ISOMETRIC, { width: iso.w, height: iso.h, margin: { top: 70, right: 8, bottom: 8, left: 8 } });
|
|
117
|
+
const cam = { ...fitted, pan: { x: fitted.pan.x + iso.x, y: fitted.pan.y + iso.y } };
|
|
118
|
+
const feeder = connectorPath(FEEDER, { camera: cam });
|
|
119
|
+
// A junction lights when the pulse reaches it, at a constant speed (`ease: linear`).
|
|
120
|
+
let travelled = 0;
|
|
121
|
+
const reach = FEEDER.map((p, i) => {
|
|
122
|
+
if (i > 0) travelled += Math.hypot(p.x - FEEDER[i - 1].x, p.y - FEEDER[i - 1].y);
|
|
123
|
+
return travelled;
|
|
124
|
+
}).map((d) => FEED.start + (d / travelled) * FEED.duration);
|
|
125
|
+
const stationNames = COPY.stations.map((s) => wrapLabel(localize(s, locale), 12, 2));
|
|
126
|
+
|
|
127
|
+
/** A flat node: pending, with the reached layer cross-faded over it. */
|
|
128
|
+
function node(/** @type {{ x: number, y: number }} */ c, /** @type {string[]} */ lines, /** @type {number} */ lit) {
|
|
129
|
+
const layer = (/** @type {string} */ fill, /** @type {string} */ stroke, /** @type {string} */ ink) =>
|
|
130
|
+
el(
|
|
131
|
+
"g",
|
|
132
|
+
{},
|
|
133
|
+
el("rect", { x: c.x - nodeW / 2, y: c.y - nodeH / 2, width: nodeW, height: nodeH, rx: 8, fill: tok(fill), stroke: tok(stroke), "stroke-width": 2 }),
|
|
134
|
+
text({ x: c.x, y: c.y, "text-anchor": "middle", "dominant-baseline": "central", "font-size": fs, "font-weight": 600, fill: tok(ink) }, lines),
|
|
135
|
+
);
|
|
136
|
+
return layer("surface", "line", "ink") + fade(lit, {}, layer("accent", "accent", "onAccent"));
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/** The feeder's stations at time t: pending, and the reached layer over the last. */
|
|
140
|
+
function stations(/** @type {number} */ t) {
|
|
141
|
+
const enter = progress(t, 0.2, ENTER, easeOut);
|
|
142
|
+
const lit = [0, progress(t, FEED.start + FEED.duration, FILL, easeStandard)];
|
|
143
|
+
const make = STATIONS.map((s, i) => ({ base: box({ x: s.x, y: s.y, w: s.w, d: s.d, h: s.h, z: TOP, fill: "surface", opacity: enter, id: String(i) }), on: box({ x: s.x, y: s.y, w: s.w, d: s.d, h: s.h, z: TOP, fill: "accent", id: String(i) }), lit: lit[i] }));
|
|
144
|
+
return make;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
function labels(/** @type {number} */ t) {
|
|
148
|
+
const opacity = progress(t, 0.5, ENTER);
|
|
149
|
+
return STATIONS.map((s, i) => labelAnchor(cam, { id: `station-${i}`, at: { x: s.x, y: s.y, z: TOP + s.h }, lines: stationNames[i], fontSize: fs, lift: 30, opacity }));
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
function frame(/** @type {number} */ t) {
|
|
153
|
+
const out = [];
|
|
154
|
+
// The flat fan-out: connectors, then the splitter and its elbows, nodes, and the pulses on top.
|
|
155
|
+
const nodeIn = (/** @type {number} */ i) => progress(t, i * 0.1, ENTER, easeOut);
|
|
156
|
+
const litAt = (/** @type {number} */ from) => progress(t, from, FILL, easeStandard);
|
|
157
|
+
const lit = [0, ...fan.map(() => litAt(OUT.start + OUT.duration))];
|
|
158
|
+
nodes.forEach((c, i) => out.push(fade(nodeIn(i), {}, node(c, names[i], lit[i]))));
|
|
159
|
+
out.push(drawConnector(toSplit, progress(t, 0.35, DRAW, easeStandard)));
|
|
160
|
+
fan.forEach((c, i) => out.push(drawConnector(c, progress(t, 0.7 + i * 0.05, DRAW, easeStandard))));
|
|
161
|
+
spread.forEach((b, i) => {
|
|
162
|
+
if (b !== 0) out.push(drawJunction({ at: at(aSplit, b), size: 5, opacity: progress(t, 0.7 + i * 0.05, ENTER, easeOut) }));
|
|
163
|
+
});
|
|
164
|
+
out.push(drawJunction({ at: at(aSplit, 0), size: 10, lit: litAt(IN.start + IN.duration), opacity: progress(t, 0.3, ENTER, easeOut) }));
|
|
165
|
+
out.push(drawPulse(toSplit, t, IN));
|
|
166
|
+
fan.forEach((c) => out.push(drawPulse(c, t, OUT)));
|
|
167
|
+
|
|
168
|
+
// The isometric feeder: floor, stations far to near, the line, its junctions on the floor, the pulse.
|
|
169
|
+
out.push(drawSolid(slab({ x: 0, y: 0, w: FLOOR.w, d: FLOOR.d, h: FLOOR.h, fill: "bg", opacity: progress(t, 0, ENTER) }), cam));
|
|
170
|
+
const st = stations(t);
|
|
171
|
+
for (const base of orderSolids(st.map((s) => s.base), cam)) {
|
|
172
|
+
const s = st[Number(base.id)];
|
|
173
|
+
out.push(drawSolid(base, cam), s.lit > 0 ? fade(s.lit, {}, drawSolid(s.on, cam)) : "");
|
|
174
|
+
}
|
|
175
|
+
out.push(drawConnector(feeder, progress(t, 0.9, 0.9, easeStandard)));
|
|
176
|
+
for (const i of TURNS) out.push(drawJunction({ at: FEEDER[i], camera: cam, plane: "floor", size: 9, lit: progress(t, reach[i], FILL, easeStandard), opacity: progress(t, 1 + i * 0.1, ENTER, easeOut) }));
|
|
177
|
+
out.push(drawPulse(feeder, t, FEED));
|
|
178
|
+
out.push(...labels(t).map((l) => l.markup));
|
|
179
|
+
return out.join("");
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
return {
|
|
183
|
+
id: `connectors-${format.replace(":", "x")}`,
|
|
184
|
+
width: W,
|
|
185
|
+
height: H,
|
|
186
|
+
duration: DURATION,
|
|
187
|
+
title: localize(COPY.title, locale),
|
|
188
|
+
description: localize(COPY.description, locale),
|
|
189
|
+
// Steps are beats of the story: their labels live in the player's controls, not in the drawing.
|
|
190
|
+
stepLabelsInFrame: false,
|
|
191
|
+
steps: [
|
|
192
|
+
{ at: STEP_SPLIT, ...COPY.steps[0] },
|
|
193
|
+
{ at: STEP_FAN, ...COPY.steps[1] },
|
|
194
|
+
{ at: STEP_FEED, ...COPY.steps[2] },
|
|
195
|
+
].map((s) => ({ at: s.at, label: localize(s.label, locale), detail: localize(s.detail, locale) })),
|
|
196
|
+
labelBoxes: (/** @type {number} */ t) => labels(t).map((l) => l.box),
|
|
197
|
+
frame,
|
|
198
|
+
};
|
|
199
|
+
}
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
*/
|
|
9
9
|
import { easeOut, easeStandard, progress, splitEdge, springTo } from "../runtime/motion.mjs";
|
|
10
10
|
import { FORMATS, localize } from "../runtime/scene.mjs";
|
|
11
|
-
import { tok } from "../runtime/style.mjs";
|
|
11
|
+
import { sharedPairs, tok } from "../runtime/style.mjs";
|
|
12
12
|
import { cubic, drawOn, el, fade, num, text } from "../runtime/svg.mjs";
|
|
13
13
|
import { wrapLabel } from "../runtime/wrap.mjs";
|
|
14
14
|
|
|
@@ -137,9 +137,14 @@ export default function make({ format = "16:9", locale = "en" } = {}) {
|
|
|
137
137
|
// Steps here are events, not nodes: their labels live in the player's
|
|
138
138
|
// step buttons and captions, not in the drawing.
|
|
139
139
|
stepLabelsInFrame: false,
|
|
140
|
-
//
|
|
141
|
-
//
|
|
142
|
-
|
|
140
|
+
// The pairs this scene draws, and the only ones the gate holds the style
|
|
141
|
+
// to (the shared pairs it leaves out, text on the canvas for one, are
|
|
142
|
+
// warnings): the shared ones its nodes, links and comet use, and the
|
|
143
|
+
// progress bar's accent fill on its surface track.
|
|
144
|
+
contrastPairs: [
|
|
145
|
+
...sharedPairs("ink/surface", "onAccent/accent", "line/bg", "accent/bg", "emphasis/bg", "emphasis/accent"),
|
|
146
|
+
{ fg: "accent", bg: "surface", min: 3, use: "the progress bar's fill on its track" },
|
|
147
|
+
],
|
|
143
148
|
steps: steps.map((s) => ({ at: s.at, label: localize(s.label, locale), detail: localize(s.detail, locale) })),
|
|
144
149
|
frame,
|
|
145
150
|
};
|
package/lib/check.mjs
CHANGED
|
@@ -4,13 +4,13 @@
|
|
|
4
4
|
* motion-kit · scene gate. Every scene, every format/locale it ships in, must
|
|
5
5
|
* pass these before anything is exported or mounted.
|
|
6
6
|
*
|
|
7
|
-
* checkScene(scene, { style }) → { ok, problems: string[] }
|
|
7
|
+
* checkScene(scene, { style }) → { ok, problems: string[], warnings: string[] }
|
|
8
8
|
*
|
|
9
9
|
* Over files, formats and locales (the CLI and the vendored gate): lib/gate.mjs.
|
|
10
10
|
*/
|
|
11
11
|
import { labelProblems } from "../runtime/iso.mjs";
|
|
12
12
|
import { renderSvg, validateScene } from "../runtime/scene.mjs";
|
|
13
|
-
import {
|
|
13
|
+
import { contrastReport, normalizeStyle } from "../runtime/style.mjs";
|
|
14
14
|
|
|
15
15
|
const SAMPLES = 120;
|
|
16
16
|
|
|
@@ -191,16 +191,20 @@ export const SETTLE_AFTER = Object.freeze([0.001, 0.015, 0.03, 0.045]);
|
|
|
191
191
|
* Run the scene gate on one built scene.
|
|
192
192
|
* @param {import("../runtime/scene.mjs").Scene} scene
|
|
193
193
|
* @param {{ samples?: number, style?: any }} [options]
|
|
194
|
-
* style: what the scene's
|
|
195
|
-
* if
|
|
196
|
-
*
|
|
197
|
-
* @returns {{ ok: boolean, problems: string[] }}
|
|
194
|
+
* style: what the scene's pairs are checked against (neutral if absent): its
|
|
195
|
+
* own `contrastPairs` if it declares them, else all of CONTRAST_PAIRS. The
|
|
196
|
+
* shared pairs a declaring scene leaves out come back as `warnings`.
|
|
197
|
+
* @returns {{ ok: boolean, problems: string[], warnings: string[] }}
|
|
198
198
|
*/
|
|
199
199
|
export function checkScene(scene, { samples = SAMPLES, style } = {}) {
|
|
200
200
|
const problems = [];
|
|
201
201
|
style = normalizeStyle(style);
|
|
202
|
-
try { validateScene(scene); } catch (e) { return { ok: false, problems: [e instanceof Error ? e.message : String(e)] }; }
|
|
203
|
-
|
|
202
|
+
try { validateScene(scene); } catch (e) { return { ok: false, problems: [e instanceof Error ? e.message : String(e)], warnings: [] }; }
|
|
203
|
+
// The style against the pairs this scene draws (G12): all the shared ones
|
|
204
|
+
// unless it declares its own (`scene.contrastPairs`), which then stand in
|
|
205
|
+
// for them; the shared pairs it leaves out are only warnings.
|
|
206
|
+
const { problems: contrastProblems, warnings } = contrastReport(style, scene.contrastPairs);
|
|
207
|
+
for (const p of contrastProblems) problems.push(`contrast: ${p}`);
|
|
204
208
|
const render = (/** @type {number} */ t) => renderSvg(scene, t, { style });
|
|
205
209
|
const at = (/** @type {number} */ i) => (scene.duration * i) / samples;
|
|
206
210
|
|
|
@@ -284,11 +288,7 @@ export function checkScene(scene, { samples = SAMPLES, style } = {}) {
|
|
|
284
288
|
}
|
|
285
289
|
for (const id of fixed) problems.push(`fixed id "${id}": build ids from frame(t, { idPrefix }), e.g. \`\${idPrefix}-${id}\``);
|
|
286
290
|
|
|
287
|
-
// 8.
|
|
288
|
-
// (scene.contrastPairs) meet their contrast in the style, both themes.
|
|
289
|
-
if (scene.contrastPairs !== undefined) {
|
|
290
|
-
for (const p of checkContrast(style, scene.contrastPairs)) problems.push(`contrast: ${p}`);
|
|
291
|
-
}
|
|
291
|
+
// 8. (Contrast, G12: checked first, above, by contrastReport.)
|
|
292
292
|
|
|
293
293
|
// 9. Labels the scene declares (scene.labelBoxes): at the sampled times, each
|
|
294
294
|
// step and the end, no two overlap, no stem crosses another label and none
|
|
@@ -322,5 +322,5 @@ export function checkScene(scene, { samples = SAMPLES, style } = {}) {
|
|
|
322
322
|
}
|
|
323
323
|
}
|
|
324
324
|
|
|
325
|
-
return { ok: problems.length === 0, problems };
|
|
325
|
+
return { ok: problems.length === 0, problems, warnings };
|
|
326
326
|
}
|
package/lib/gate.mjs
CHANGED
|
@@ -6,18 +6,22 @@
|
|
|
6
6
|
*
|
|
7
7
|
* checkFiles(files, { formats, locales, style, options }) → number of failures
|
|
8
8
|
*
|
|
9
|
-
* - The style must pass the contrast check for the pairs every scene draws
|
|
10
|
-
* (G12, CONTRAST_PAIRS), once.
|
|
11
9
|
* - Every file × format (all of FORMATS unless given) × locale passes
|
|
12
|
-
* checkScene, which
|
|
13
|
-
*
|
|
14
|
-
*
|
|
10
|
+
* checkScene, which holds the style to the contrast pairs that scene draws
|
|
11
|
+
* (G12): the pairs its scene type draws, its own `contrastPairs`, or, if it
|
|
12
|
+
* declares none, all of CONTRAST_PAIRS. Locales: the given ones; else, for a
|
|
13
|
+
* spec, every locale its strings carry, and a module’s exported `locales`
|
|
14
|
+
* (default `en`).
|
|
15
|
+
* - The style's other shared pairs are reported once, as warnings, with the
|
|
16
|
+
* scene types they would fail: a style author sees every shared pair's
|
|
17
|
+
* result, and no scene fails on a pair it does not draw.
|
|
15
18
|
* - A file that cannot be read, parsed or built is a failure for that file
|
|
16
19
|
* only; the remaining files are still checked.
|
|
17
20
|
*/
|
|
18
21
|
import { readFileSync } from "node:fs";
|
|
19
22
|
import { FORMATS } from "../runtime/scene.mjs";
|
|
20
|
-
import { checkContrast } from "../runtime/style.mjs";
|
|
23
|
+
import { CONTRAST_PAIRS, checkContrast } from "../runtime/style.mjs";
|
|
24
|
+
import { SCENE_TYPE_PAIRS } from "../runtime/types/index.mjs";
|
|
21
25
|
import { checkScene } from "./check.mjs";
|
|
22
26
|
import { isModule, loadScene, moduleLocales } from "./load.mjs";
|
|
23
27
|
|
|
@@ -45,17 +49,28 @@ export function detectLocales(spec) {
|
|
|
45
49
|
return found.size ? [...found] : ["en"];
|
|
46
50
|
}
|
|
47
51
|
|
|
52
|
+
/**
|
|
53
|
+
* Every shared contrast pair the style misses, each with who draws it: the
|
|
54
|
+
* scene types that fail on it, and any custom scene that declares no pairs of
|
|
55
|
+
* its own (it is held to all of them).
|
|
56
|
+
* @param {any} style
|
|
57
|
+
* @returns {string[]}
|
|
58
|
+
*/
|
|
59
|
+
export function styleWarnings(style) {
|
|
60
|
+
return CONTRAST_PAIRS.flatMap((pair) => {
|
|
61
|
+
const types = Object.entries(SCENE_TYPE_PAIRS).filter(([, pairs]) => pairs.some((p) => p.fg === pair.fg && p.bg === pair.bg)).map(([t]) => t);
|
|
62
|
+
return checkContrast(style, [pair]).map((problem) => `${problem} (held against: ${[...types, "custom scenes that declare no or empty contrastPairs, or name this pair"].join(", ")}; a warning for any other scene)`);
|
|
63
|
+
});
|
|
64
|
+
}
|
|
65
|
+
|
|
48
66
|
/**
|
|
49
67
|
* @param {string[]} files specs (.json) and custom modules (.mjs)
|
|
50
|
-
* @param {{ formats?: string[], locales?: string[], style?: any, options?: import("./load.mjs").OptionsSource, log?: (line: string) => void, error?: (line: string) => void }} [o]
|
|
68
|
+
* @param {{ formats?: string[], locales?: string[], style?: any, options?: import("./load.mjs").OptionsSource, log?: (line: string) => void, error?: (line: string) => void, warn?: (line: string) => void }} [o]
|
|
51
69
|
* @returns {Promise<number>} failures (0 = the gate passes)
|
|
52
70
|
*/
|
|
53
|
-
export async function checkFiles(files, { formats, locales, style, options, log = console.log, error = console.error } = {}) {
|
|
71
|
+
export async function checkFiles(files, { formats, locales, style, options, log = console.log, error = console.error, warn = console.warn } = {}) {
|
|
54
72
|
let bad = 0;
|
|
55
|
-
for (const p of
|
|
56
|
-
bad++;
|
|
57
|
-
error(`✗ style: ${p}`);
|
|
58
|
-
}
|
|
73
|
+
for (const p of styleWarnings(style)) warn(`⚠ style: ${p}`);
|
|
59
74
|
for (const file of files) {
|
|
60
75
|
const module = isModule(file);
|
|
61
76
|
let fileLocales = locales?.length ? locales : ["en"];
|