@liqweed/motion-kit 0.13.0 → 0.14.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 +8 -1
- package/docs/spec/technique.md +63 -2
- package/examples/bars.scene.mjs +114 -0
- package/package.json +2 -2
- package/runtime/bars.mjs +226 -0
- package/runtime/kit.mjs +3 -1
- package/skills/animated-diagram/SKILL.md +4 -3
- package/skills/animated-diagram/references/custom-scenes.md +25 -0
- package/skills/animated-diagram/references/motion-vocabulary.md +16 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "motion-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.14.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
|
@@ -28,6 +28,11 @@ README and follow your GitHub theme. Regenerate with `npm run media`.
|
|
|
28
28
|
<img src="docs/media/smart-home-light.svg" alt="smart-home: a hub-and-spoke scene" width="720">
|
|
29
29
|
</picture>
|
|
30
30
|
|
|
31
|
+
<picture>
|
|
32
|
+
<source media="(prefers-color-scheme: dark)" srcset="docs/media/bars-dark.svg">
|
|
33
|
+
<img src="docs/media/bars-light.svg" alt="bars: a three-row benchmark chart comparing cached 0.8 s, incremental 2.4 s, and clean 6.5 s builds" width="720">
|
|
34
|
+
</picture>
|
|
35
|
+
|
|
31
36
|
The interactive player (scrubber, steps, captions) needs scripts, which
|
|
32
37
|
GitHub does not run: `node cli/motion-kit.mjs build examples/order-flow.json -o out/order.html`
|
|
33
38
|
and open the file.
|
|
@@ -59,6 +64,7 @@ runtime/ dependency-free ES modules (browser + Node)
|
|
|
59
64
|
svg.mjs escaping, rounding, el/text/fade, polyline + Bézier arc-length, drawOn, several tokens, blur reveal, highlighter sweep
|
|
60
65
|
iso.mjs isometric kit for custom scenes: camera, solids (rounded too), depth order, grid backdrop, content on faces, label anchors and pills
|
|
61
66
|
connectors.mjs dashed connectors, diamond junctions and single-pass light pulses for custom scenes
|
|
67
|
+
bars.mjs hatched tracks, rounded bars on the style's curve and rolling values for custom scenes
|
|
62
68
|
wrap.mjs label wrapping with hard budgets
|
|
63
69
|
style.mjs tokens, neutral style, contrast checks, token resolution
|
|
64
70
|
scene.mjs scene contract, formats, renderSvg
|
|
@@ -76,7 +82,8 @@ examples/ order-flow (sequence), smart-home (hub-spoke), incident (timelin
|
|
|
76
82
|
isometric-swivel (custom module: isometric kit, several tokens),
|
|
77
83
|
isometric-platform (custom module: rounded slabs, grid backdrop, mark on a top face, pill tags),
|
|
78
84
|
connectors (custom module: connectors, diamond junctions, pulses),
|
|
79
|
-
text-reveal (custom module: blur-and-fade reveal, highlighter sweep)
|
|
85
|
+
text-reveal (custom module: blur-and-fade reveal, highlighter sweep),
|
|
86
|
+
bars (custom module: hatched tracks, bars, rolling values)
|
|
80
87
|
bench/ heavy scene for npm run bench:player (live-player frame cost)
|
|
81
88
|
brand/ logo scene (built with motion-kit); renders go to assets/ + .idea/ (npm run media)
|
|
82
89
|
assets/ generated project icon: icon.svg, icon.png, icon-animated.svg
|
package/docs/spec/technique.md
CHANGED
|
@@ -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`, `connectors` 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`, `bars` 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
|
|
@@ -359,7 +359,6 @@ functions; a colour is a token name (G4 applies).
|
|
|
359
359
|
its target has filled, and nothing repeats while a step rests, so the
|
|
360
360
|
settled-frame rule (G6) holds. Several pulses may run in one beat.
|
|
361
361
|
|
|
362
|
-
|
|
363
362
|
### 4.11 Text reveal and highlighter sweep (`runtime/svg.mjs`)
|
|
364
363
|
|
|
365
364
|
- `blurReveal(enter, {id, rise = 6, blur = 4}, ...children)` draws `children`
|
|
@@ -414,6 +413,68 @@ functions; a colour is a token name (G4 applies).
|
|
|
414
413
|
reveals three labels in reading order, then a quoted line with one band per
|
|
415
414
|
wrapped line swept first line to last.
|
|
416
415
|
|
|
416
|
+
### 4.12 Bars with values (`runtime/bars.mjs`)
|
|
417
|
+
|
|
418
|
+
For custom scenes that chart a few values; handed to them in `kit`. Pure
|
|
419
|
+
functions; a colour is a token name (G4 applies).
|
|
420
|
+
|
|
421
|
+
- **Hatch.** `hatchPattern({idPrefix, name, stroke, spacing, width})` returns
|
|
422
|
+
`{id, fill, markup}`: a `<pattern>` of lines at 45°, rising to the right,
|
|
423
|
+
`spacing` px apart (default 7) and `width` px wide (default 1.5), in the token
|
|
424
|
+
`stroke` (default `line`). Its id is `${safeId(idPrefix)}-hatch-${name}` (`name` defaults to
|
|
425
|
+
`hatch`), so its hatch namespace cannot collide with clip paths generated by `drawBar`; a scene that draws several hatchings gives each
|
|
426
|
+
its own `name`, of letters, digits and `_` only. Prefixes must be unique after `safeId` normalizes them. `name` also cannot be `title` or `desc`,
|
|
427
|
+
which `renderSvg` reserves. `markup` is a `<defs>` the frame emits once, before the tracks,
|
|
428
|
+
on every frame; `fill` is `url(#id)`. The pattern is in the user space of the element that references it (picture
|
|
429
|
+
units for tracks drawn at the top level, which scale with the SVG), so
|
|
430
|
+
tracks that share it show one continuous hatch, and in the player, in `bake`
|
|
431
|
+
and in a PNG or video export it draws the same. It makes the `idPrefix` a safe id token as `renderSvg` does; it throws for an
|
|
432
|
+
empty `idPrefix`, a `name` that is not a safe id token or is reserved, a `spacing` of 0 or less, and a `width` of
|
|
433
|
+
0 or less or not below the spacing after SVG number rounding. A hatch must come from `hatchPattern`; a frozen hatch from another vendored runtime copy works too, if its `fill` is an own data property `url(#id)` (a getter or an inherited `fill` is refused).
|
|
434
|
+
- **Track.** `drawTrack({x, y, width, height, hatch, fill, radius, opacity, id})`
|
|
435
|
+
is an empty bar: a rounded rect filled with the token `fill` (default
|
|
436
|
+
`surface`, `null` for none) and the `hatch` over it. It needs one of the two.
|
|
437
|
+
`radius` defaults to half the height and is never more than half a side. It
|
|
438
|
+
throws for a size of 0 or less (including after SVG number rounding) and for a hatch that is not frozen or whose `fill` is not `url(#id)`. It emits only the hatch's `fill`; putting its `markup` in the frame is the scene's job, and a hatch whose `<defs>` is missing paints nothing.
|
|
439
|
+
- **Bar.** `drawBar({x, y, width, height, p, fill, radius, trackRadius, opacity, idPrefix, id, trackWidth})` draws a
|
|
440
|
+
bar from `x` that is `width * p` long (`width` is its length when done, a share
|
|
441
|
+
of the track's, `p` the eased
|
|
442
|
+
progress 0..1 of its growth), rounded at both ends all the way, so it grows as
|
|
443
|
+
a pill. Nothing for `p ≤ 0`; `p ≥ 1` is the bar it rests as. `fill` is a token
|
|
444
|
+
(default `accent`). Give `trackWidth`, the frame's `idPrefix`, and a local safe
|
|
445
|
+
`id` (letters, digits and `_`, except `title` and `desc`) to clip a short bar to its rounded track; clip IDs use a separate `-clip-` namespace. Use
|
|
446
|
+
`trackRadius` whenever the track sets a `radius` explicitly (the clip otherwise defaults to half the track height, whatever the bar's own `radius`).
|
|
447
|
+
- **Growth.** `barProgress(t, {start, duration}, style)` is the bar's `p`: 0
|
|
448
|
+
before `start` and exactly 1 from `barEnd(run)` = `start + duration` on, on the
|
|
449
|
+
style's movement curve (`style.motion.move`, through `easings`, so it settles
|
|
450
|
+
whatever curve the style names), the default curve for no style. `style` is the
|
|
451
|
+
one `frame(t, {idPrefix, style})` receives. A run has a finite `start` and a
|
|
452
|
+
finite, positive `duration` and a finite end strictly after its start; invalid
|
|
453
|
+
runs throw rather than producing an invalid end time.
|
|
454
|
+
- **Value.** `rollingValue(from, to, p)` is `from` at `p ≤ 0`, `to` itself, not a
|
|
455
|
+
sum that rounds to it, at `p ≥ 1`, and between them a straight line in `p`, so
|
|
456
|
+
the raw number and the bar, which `p` has already eased, arrive together (a
|
|
457
|
+
`format` that rounds may show its final digits before the bar settles).
|
|
458
|
+
`drawValue({x, y, to, from, p, format, fontSize, anchor, fill, weight, family,
|
|
459
|
+
opacity, id})` draws `format(rollingValue(from, to, p))` as text (default
|
|
460
|
+
`from` 0, `format` rounding to a whole number, `anchor` `start`, `fill` the
|
|
461
|
+
token `ink`, `dominant-baseline` central on `y`). `format` is the caller's and
|
|
462
|
+
carries the units, decimals and locale; it must return a string, which is
|
|
463
|
+
escaped. It throws for a `format` that is not a function or returns another
|
|
464
|
+
type, and for a non-finite number. Until the monospace face of the style
|
|
465
|
+
lands, a scene sets its own `family` to keep the digits from jittering.
|
|
466
|
+
- **Canon.** A bar grows once, in a step's beat, and rests (§4.8): every bar of
|
|
467
|
+
the beat has settled (`barEnd`) at least 50 ms before the step's `at`, and from
|
|
468
|
+
then its value is exactly `format(to)`, so the step frame is the settled
|
|
469
|
+
frame (G6). G6 compares the whole frame up to 45 ms after `at`, so the track's
|
|
470
|
+
own entrance also finishes 50 ms or more before `at`, and the next motion
|
|
471
|
+
starts no earlier than 50 ms after it. Nothing repeats. A value that updates live beside footage is not
|
|
472
|
+
this part. A scene that draws the bar's accent on the track's colour declares
|
|
473
|
+
the pairs in `contrastPairs` (G12), for example `accent` on `surface` at 3 and
|
|
474
|
+
`line` on `surface` at 2.5 for decorative hatch texture. Informative hatching
|
|
475
|
+
is a shape and needs 3:1; the opaque bar itself is adjacent to `surface`, not
|
|
476
|
+
to the hatch beneath it.
|
|
477
|
+
|
|
417
478
|
|
|
418
479
|
## 5. Markup
|
|
419
480
|
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Example custom scene: three rows of a small benchmark, revealed top to bottom,
|
|
3
|
+
* one step each.
|
|
4
|
+
*
|
|
5
|
+
* Shows the bar parts (runtime/bars.mjs): an empty track filled with diagonal
|
|
6
|
+
* hatching, a rounded bar that grows over it on the style's movement curve, and
|
|
7
|
+
* a number beside it that rolls up with the bar and shows exactly its end value
|
|
8
|
+
* once the bar has settled. The hatch's id is built from the frame's `idPrefix`,
|
|
9
|
+
* so two instances on a page never share one. Each bar grows once, inside its
|
|
10
|
+
* step's beat, and is settled (`barEnd`) before the step's time, so every step
|
|
11
|
+
* frame is settled. Nothing loops: the scene plays once and holds its last frame.
|
|
12
|
+
* Pure: frame(t) depends only on t and constants.
|
|
13
|
+
*/
|
|
14
|
+
import { barEnd, barProgress, drawBar, drawTrack, drawValue, hatchPattern } from "../runtime/bars.mjs";
|
|
15
|
+
import { easings, progress } from "../runtime/motion.mjs";
|
|
16
|
+
import { FORMATS, localize } from "../runtime/scene.mjs";
|
|
17
|
+
import { sharedPairs, tok } from "../runtime/style.mjs";
|
|
18
|
+
import { fade, text } from "../runtime/svg.mjs";
|
|
19
|
+
import { wrapLabel } from "../runtime/wrap.mjs";
|
|
20
|
+
|
|
21
|
+
export const locales = ["en", "nl"];
|
|
22
|
+
|
|
23
|
+
const COPY = {
|
|
24
|
+
title: { en: "Build time, three ways", nl: "Bouwtijd, op drie manieren" },
|
|
25
|
+
description: {
|
|
26
|
+
en: "Three bars over hatched tracks show how long a build takes: cached, incremental and clean. Each bar grows while its time counts up.",
|
|
27
|
+
nl: "Drie balken over gearceerde banen tonen hoe lang een build duurt: uit cache, incrementeel en schoon. Elke balk groeit terwijl de tijd oploopt.",
|
|
28
|
+
},
|
|
29
|
+
unit: { en: "s", nl: "s" },
|
|
30
|
+
rows: [
|
|
31
|
+
{ label: { en: "Cached", nl: "Uit cache" }, value: 0.8, detail: { en: "Nothing changed, so the build is read back.", nl: "Er is niets veranderd, dus de build wordt teruggelezen." } },
|
|
32
|
+
{ label: { en: "Incremental", nl: "Incrementeel" }, value: 2.4, detail: { en: "Only what changed is built again.", nl: "Alleen wat veranderd is wordt opnieuw gebouwd." } },
|
|
33
|
+
{ label: { en: "Clean", nl: "Schoon" }, value: 6.5, detail: { en: "Everything is built from scratch.", nl: "Alles wordt vanaf nul gebouwd." } },
|
|
34
|
+
],
|
|
35
|
+
};
|
|
36
|
+
|
|
37
|
+
// Timeline, in seconds. Row i starts at START + i·PERIOD: its track fades in,
|
|
38
|
+
// then its bar grows while the value rolls, and the step comes 100 ms after the
|
|
39
|
+
// bar has settled. The next row starts well after that.
|
|
40
|
+
const START = 0.2;
|
|
41
|
+
const PERIOD = 1.4;
|
|
42
|
+
const ENTER = 0.4;
|
|
43
|
+
const GROW = { delay: 0.25, duration: 0.7 };
|
|
44
|
+
const SETTLE = 0.1;
|
|
45
|
+
const SCALE = 8; // the track's full length is this many seconds
|
|
46
|
+
const MONO = "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace";
|
|
47
|
+
|
|
48
|
+
/** @param {number} i */
|
|
49
|
+
const rowStart = (i) => START + i * PERIOD;
|
|
50
|
+
/** @param {number} i */
|
|
51
|
+
const growRun = (i) => ({ start: rowStart(i) + GROW.delay, duration: GROW.duration });
|
|
52
|
+
|
|
53
|
+
export default function make({ format = "16:9", locale = "en" } = {}) {
|
|
54
|
+
const f = FORMATS[format];
|
|
55
|
+
if (!f) throw new Error(`unknown format "${format}"`);
|
|
56
|
+
const W = f.width;
|
|
57
|
+
const fs = 17;
|
|
58
|
+
const barH = 26;
|
|
59
|
+
const gap = 8; // between a row's label and its track
|
|
60
|
+
const rowGap = 26;
|
|
61
|
+
const pad = 32;
|
|
62
|
+
const valueW = 92;
|
|
63
|
+
const rowH = fs * 1.25 + gap + barH;
|
|
64
|
+
const total = COPY.rows.length * rowH + (COPY.rows.length - 1) * rowGap;
|
|
65
|
+
const H = f.height || Math.round(total + 2 * pad);
|
|
66
|
+
const top = (H - total) / 2;
|
|
67
|
+
const trackX = pad;
|
|
68
|
+
const trackW = W - 2 * pad - valueW - 12;
|
|
69
|
+
const valueX = W - pad;
|
|
70
|
+
const number = new Intl.NumberFormat(locale, { minimumFractionDigits: 1, maximumFractionDigits: 1 });
|
|
71
|
+
const format1 = (/** @type {number} */ v) => `${number.format(v)} ${localize(COPY.unit, locale)}`;
|
|
72
|
+
const labels = COPY.rows.map((r) => wrapLabel(localize(r.label, locale), Math.floor((W - 2 * pad) / (fs * 0.56)), 1));
|
|
73
|
+
|
|
74
|
+
/** @param {number} t @param {{ idPrefix: string, style?: any }} ctx */
|
|
75
|
+
function frame(t, { idPrefix, style }) {
|
|
76
|
+
const hatch = hatchPattern({ idPrefix, stroke: "line" });
|
|
77
|
+
const { easeOut } = easings(style?.motion);
|
|
78
|
+
const out = [hatch.markup];
|
|
79
|
+
COPY.rows.forEach((row, i) => {
|
|
80
|
+
const enter = progress(t, rowStart(i), ENTER, easeOut);
|
|
81
|
+
if (enter <= 0) return;
|
|
82
|
+
const y = top + i * (rowH + rowGap);
|
|
83
|
+
const ty = y + fs * 1.25 + gap;
|
|
84
|
+
const p = barProgress(t, growRun(i), style);
|
|
85
|
+
out.push(
|
|
86
|
+
fade(enter, {}, text({ x: pad, y: y + (fs * 1.25) / 2, "dominant-baseline": "central", "font-size": fs, "font-weight": 600, fill: tok("ink") }, labels[i])),
|
|
87
|
+
drawTrack({ x: trackX, y: ty, width: trackW, height: barH, hatch, opacity: enter, id: `row-${i}` }),
|
|
88
|
+
drawBar({ x: trackX, y: ty, width: trackW * (row.value / SCALE), trackWidth: trackW, height: barH, p, idPrefix, id: `row_${i}` }),
|
|
89
|
+
drawValue({ x: valueX, y: ty + barH / 2, to: row.value, p, format: format1, fontSize: 20, anchor: "end", family: MONO, opacity: enter, id: `row-${i}` }),
|
|
90
|
+
);
|
|
91
|
+
});
|
|
92
|
+
return out.join("");
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
const steps = COPY.rows.map((row, i) => ({
|
|
96
|
+
at: barEnd(growRun(i)) + SETTLE,
|
|
97
|
+
label: localize(row.label, locale),
|
|
98
|
+
detail: `${localize(row.detail, locale)} ${format1(row.value)}`,
|
|
99
|
+
}));
|
|
100
|
+
|
|
101
|
+
return {
|
|
102
|
+
id: `bars-${format.replace(":", "x")}`,
|
|
103
|
+
width: W,
|
|
104
|
+
height: H,
|
|
105
|
+
duration: steps[steps.length - 1].at + 0.4,
|
|
106
|
+
title: localize(COPY.title, locale),
|
|
107
|
+
description: localize(COPY.description, locale),
|
|
108
|
+
// The pairs this scene draws: the labels and values on the canvas, and the
|
|
109
|
+
// bar's accent fill on its track.
|
|
110
|
+
contrastPairs: [...sharedPairs("ink/bg"), { fg: "accent", bg: "surface", min: 3, use: "the bar's fill on its track" }, { fg: "line", bg: "surface", min: 2.5, use: "the hatching on the track: texture that marks the empty track, not data" }],
|
|
111
|
+
steps,
|
|
112
|
+
frame,
|
|
113
|
+
};
|
|
114
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@liqweed/motion-kit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.14.0",
|
|
4
4
|
"description": "Deterministic animated diagrams: scenes as pure functions of time, for live pages, slides, baked SVG and video.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"animation",
|
|
@@ -47,7 +47,7 @@
|
|
|
47
47
|
"prepare": "lefthook install || true",
|
|
48
48
|
"test": "node --test test/*.test.mjs",
|
|
49
49
|
"typecheck": "tsc -p .",
|
|
50
|
-
"check": "node cli/motion-kit.mjs check examples/order-flow.json examples/smart-home.json examples/release-pipeline.json examples/agent-loop.json examples/integrations.json examples/incident.json examples/web-stack.json examples/custom-pulse.scene.mjs examples/isometric-swivel.scene.mjs examples/connectors.scene.mjs examples/isometric-platform.scene.mjs examples/text-reveal.scene.mjs brand/logo.scene.mjs examples/player-states.json examples/checkout.json examples/connection.json examples/pull-request.json",
|
|
50
|
+
"check": "node cli/motion-kit.mjs check examples/order-flow.json examples/smart-home.json examples/release-pipeline.json examples/agent-loop.json examples/integrations.json examples/incident.json examples/web-stack.json examples/custom-pulse.scene.mjs examples/isometric-swivel.scene.mjs examples/connectors.scene.mjs examples/isometric-platform.scene.mjs examples/text-reveal.scene.mjs examples/bars.scene.mjs brand/logo.scene.mjs examples/player-states.json examples/checkout.json examples/connection.json examples/pull-request.json",
|
|
51
51
|
"media": "scripts/render-media.sh",
|
|
52
52
|
"media:check": "scripts/render-media.sh --check",
|
|
53
53
|
"site": "npm run -w website build",
|
package/runtime/bars.mjs
ADDED
|
@@ -0,0 +1,226 @@
|
|
|
1
|
+
// SPDX-License-Identifier: MIT
|
|
2
|
+
// Copyright (c) 2026 Ophir Radnitz
|
|
3
|
+
/**
|
|
4
|
+
* motion-kit · bars with values, for custom scenes (`kit`).
|
|
5
|
+
*
|
|
6
|
+
* Parts for a row of a benchmark-style chart, as pure functions of time:
|
|
7
|
+
*
|
|
8
|
+
* - a **hatch**: a pattern of diagonal lines at 45° in a token colour, whose id
|
|
9
|
+
* is built from the frame's `idPrefix` (`hatchPattern`);
|
|
10
|
+
* - a **track**: a rounded, empty bar filled with that hatching (`drawTrack`);
|
|
11
|
+
* - a **bar**: a rounded bar that grows over the track from its start
|
|
12
|
+
* (`drawBar`), on the style's movement curve (`barProgress`);
|
|
13
|
+
* - a **value**: a number that rolls from a start value to its end value with
|
|
14
|
+
* the bar's progress, formatted by the caller (`drawValue`, `rollingValue`).
|
|
15
|
+
*
|
|
16
|
+
* Nothing here repeats. A bar grows once inside its step's beat and rests; its
|
|
17
|
+
* value shows exactly its end value from the moment the bar has settled, so a
|
|
18
|
+
* step frame is the settled frame (`barEnd` says when). Colours are token
|
|
19
|
+
* names, never literals.
|
|
20
|
+
*
|
|
21
|
+
* Imports stay single-line named imports: lib/bundle.mjs inlines only that form.
|
|
22
|
+
*/
|
|
23
|
+
import { clamp01, easings, lerp, progress } from "./motion.mjs";
|
|
24
|
+
import { safeId } from "./scene.mjs";
|
|
25
|
+
import { tok } from "./style.mjs";
|
|
26
|
+
import { el, fade, num, text } from "./svg.mjs";
|
|
27
|
+
|
|
28
|
+
/** @import { Style } from "./style.mjs" */
|
|
29
|
+
|
|
30
|
+
/** @param {number} n */
|
|
31
|
+
const finite = (n) => typeof n === "number" && Number.isFinite(n);
|
|
32
|
+
/** What may stand in an id: the characters `safeId` leaves. */
|
|
33
|
+
const ID_PART = /^[A-Za-z0-9_]+$/;
|
|
34
|
+
/** Names `renderSvg` already uses for ids (`${id}-title`, `${id}-desc`). */
|
|
35
|
+
const RESERVED_NAMES = new Set(["title", "desc"]);
|
|
36
|
+
/** @param {unknown} value */
|
|
37
|
+
const renderedFinite = (value) => typeof value === "number" && finite(value) && finite(Number(num(value)));
|
|
38
|
+
/**
|
|
39
|
+
* The paint `drawTrack` emits for a hatch: `fill`, read once as a data property of a frozen
|
|
40
|
+
* object (so a getter or a later write cannot change it) and shaped `url(#id)`. It is the only
|
|
41
|
+
* hatch value `drawTrack` emits; `markup` is the `<defs>` the scene puts in its own frame, so
|
|
42
|
+
* it is not checked here (a hatch must come from `hatchPattern`, from any vendored copy).
|
|
43
|
+
* @param {unknown} hatch
|
|
44
|
+
* @returns {string | null}
|
|
45
|
+
*/
|
|
46
|
+
const hatchFill = (hatch) => {
|
|
47
|
+
if (!hatch || typeof hatch !== "object" || !Object.isFrozen(hatch)) return null;
|
|
48
|
+
const field = Object.getOwnPropertyDescriptor(hatch, "fill");
|
|
49
|
+
if (!field || !("value" in field)) return null;
|
|
50
|
+
return typeof field.value === "string" && /^url\(#[A-Za-z][A-Za-z0-9_-]*\)$/.test(field.value) ? field.value : null;
|
|
51
|
+
};
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* @typedef {{ readonly id: string, readonly fill: string, readonly markup: string }} Hatch
|
|
55
|
+
* `markup` is the `<defs>` holding the pattern: put it in the frame once,
|
|
56
|
+
* before any track that uses it, every frame. `fill` is the paint to refer to
|
|
57
|
+
* it, `url(#id)`.
|
|
58
|
+
*/
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* Diagonal hatching: lines at 45°, rising to the right, `spacing` pixels apart
|
|
62
|
+
* (measured across the lines) and `width` pixels wide, in the token `stroke`.
|
|
63
|
+
* The pattern is anchored to the picture, not to a track, so tracks that use it
|
|
64
|
+
* show one continuous hatch. Its id is `<prefix>-hatch-<name>`; `idPrefix` is normalized with `safeId`, so prefixes must
|
|
65
|
+
* be unique after that normalization: the frame's prefix keeps two instances on a page separate, and a scene that draws
|
|
66
|
+
* several hatchings gives each its own `name`.
|
|
67
|
+
* @param {{ idPrefix: string, name?: string, stroke?: string, spacing?: number, width?: number }} o
|
|
68
|
+
* @returns {Hatch}
|
|
69
|
+
*/
|
|
70
|
+
export function hatchPattern({ idPrefix, name = "hatch", stroke = "line", spacing = 7, width = 1.5 }) {
|
|
71
|
+
if (typeof idPrefix !== "string" || idPrefix === "") throw new Error(`hatchPattern: idPrefix must be the frame's idPrefix, a non-empty string, got ${JSON.stringify(idPrefix)}`);
|
|
72
|
+
if (typeof name !== "string" || !ID_PART.test(name)) throw new Error(`hatchPattern: name must use letters, digits and "_" (no "-", which ends the prefix in the id), got ${JSON.stringify(name)}`);
|
|
73
|
+
if (RESERVED_NAMES.has(name)) throw new Error(`hatchPattern: name "${name}" is reserved for the picture's own ids`);
|
|
74
|
+
if (!finite(spacing) || spacing <= 0) throw new Error(`hatchPattern: spacing must be a finite positive number, got ${spacing}`);
|
|
75
|
+
if (!finite(width) || width <= 0 || width >= spacing) throw new Error(`hatchPattern: width must be finite, more than 0 and less than the spacing, got ${width} of ${spacing}`);
|
|
76
|
+
const drawnSpacing = Number(num(spacing));
|
|
77
|
+
const drawnWidth = Number(num(width));
|
|
78
|
+
if (!finite(drawnSpacing) || drawnSpacing <= 0) throw new Error(`hatchPattern: spacing must remain finite and positive after SVG rounding, got ${spacing}`);
|
|
79
|
+
if (!finite(drawnWidth) || drawnWidth <= 0 || drawnWidth >= drawnSpacing) throw new Error(`hatchPattern: width must remain finite, more than 0 and less than the spacing after SVG rounding, got ${width} of ${spacing}`);
|
|
80
|
+
const id = `${safeId(idPrefix)}-hatch-${name}`; // normalized here so a direct call with a raw prefix (as in the tests) matches what renderSvg passes
|
|
81
|
+
// One vertical line in the middle of a square tile, turned 45° by the pattern.
|
|
82
|
+
const line = el("path", { d: `M${num(spacing / 2)} 0 V${num(spacing)}`, fill: "none", stroke: tok(stroke), "stroke-width": width });
|
|
83
|
+
const pattern = el("pattern", { id, width: spacing, height: spacing, patternUnits: "userSpaceOnUse", patternTransform: "rotate(45)" }, line);
|
|
84
|
+
const hatch = Object.freeze({ id, fill: `url(#${id})`, markup: el("defs", {}, pattern) });
|
|
85
|
+
return hatch;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/** @param {string} who @param {{ x: number, y: number, width: number, height: number }} r */
|
|
89
|
+
function checkRect(who, { x, y, width, height }, allowEmpty = false) {
|
|
90
|
+
if (![x, y, width, height].every(renderedFinite)) throw new Error(`${who}: x, y, width and height must remain finite after SVG rounding`);
|
|
91
|
+
if (allowEmpty && width === 0 && height > 0) return;
|
|
92
|
+
if (width <= 0 || height <= 0) throw new Error(`${who}: width and height must be positive, got ${width} × ${height}`);
|
|
93
|
+
if ((!allowEmpty && Number(num(width)) <= 0) || Number(num(height)) <= 0) throw new Error(`${who}: width and height must remain positive after SVG rounding, got ${width} × ${height}`);
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/** The corner radius for a rect `w` × `h`: `radius`, never more than half of either side. */
|
|
97
|
+
const corner = (/** @type {number | undefined} */ radius, /** @type {number} */ w, /** @type {number} */ h) => {
|
|
98
|
+
const r = radius ?? h / 2;
|
|
99
|
+
if (!finite(r) || r < 0) throw new Error(`radius must be a finite number of 0 or more, got ${radius}`);
|
|
100
|
+
return Math.min(r, w / 2, h / 2);
|
|
101
|
+
};
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* An empty track: a rounded bar of `width` × `height` at (`x`, `y`), filled with
|
|
105
|
+
* the token `fill` (default `surface`; `null` for none) and, over it, with the
|
|
106
|
+
* `hatch` when one is given. A track needs one of the two. `radius` defaults to
|
|
107
|
+
* half the height, a pill.
|
|
108
|
+
* @param {{ x: number, y: number, width: number, height: number, hatch?: Hatch, fill?: string | null, radius?: number, opacity?: number, id?: string }} o
|
|
109
|
+
* @returns {string}
|
|
110
|
+
*/
|
|
111
|
+
export function drawTrack({ x, y, width, height, hatch, fill = "surface", radius, opacity = 1, id }) {
|
|
112
|
+
checkRect("drawTrack", { x, y, width, height });
|
|
113
|
+
const hatchPaint = hatch === undefined ? null : hatchFill(hatch);
|
|
114
|
+
if (hatch !== undefined && !hatchPaint) throw new Error("drawTrack: hatch must be a frozen hatchPattern result with a url(#id) fill");
|
|
115
|
+
if (!hatchPaint && fill === null) throw new Error("drawTrack: a track needs a fill or a hatch");
|
|
116
|
+
const rx = corner(radius, width, height);
|
|
117
|
+
const rect = (/** @type {string} */ paint) => el("rect", { x, y, width, height, rx, fill: paint });
|
|
118
|
+
return fade(opacity, id ? { "data-track": id } : {}, fill === null ? "" : rect(tok(fill)), hatchPaint ? rect(hatchPaint) : "");
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* A bar `width` long when it is done (its end value's share of the track, 0 for a zero value), drawn
|
|
123
|
+
* up to fraction `p` of it from its start at (`x`, `y`): `p` is the eased progress of its
|
|
124
|
+
* growth (`barProgress`), and the bar is rounded at both ends all the way, so
|
|
125
|
+
* it grows as a pill. Nothing for `p` ≤ 0; `p` ≥ 1 is the full bar it rests as.
|
|
126
|
+
* `trackWidth` clips a short bar to its track's silhouette; with it, `idPrefix`
|
|
127
|
+
* is the frame instance prefix and `id` is a safe, instance-local key.
|
|
128
|
+
* @param {{ x: number, y: number, width: number, height: number, p: number, fill?: string, radius?: number, trackRadius?: number, opacity?: number, id?: string, idPrefix?: string, trackWidth?: number }} o
|
|
129
|
+
* @returns {string}
|
|
130
|
+
*/
|
|
131
|
+
export function drawBar({ x, y, width, height, p, fill = "accent", radius, trackRadius, opacity = 1, id, idPrefix, trackWidth }) {
|
|
132
|
+
checkRect("drawBar", { x, y, width, height }, true); // a zero value is a zero-width bar: nothing to draw
|
|
133
|
+
if (!finite(p)) throw new Error(`drawBar: p must be a finite number, got ${p}`);
|
|
134
|
+
if (trackWidth !== undefined && (!renderedFinite(trackWidth) || trackWidth <= 0 || trackWidth < width)) throw new Error(`drawBar: trackWidth must remain finite and at least the bar width, got ${trackWidth}`);
|
|
135
|
+
if (trackWidth !== undefined && (typeof idPrefix !== "string" || idPrefix === "" || typeof id !== "string" || !ID_PART.test(id) || RESERVED_NAMES.has(id))) throw new Error("drawBar: trackWidth needs the frame idPrefix and a non-reserved id using letters, digits and _");
|
|
136
|
+
const share = clamp01(p);
|
|
137
|
+
if (share <= 0) return "";
|
|
138
|
+
const w = width * share;
|
|
139
|
+
if (w <= 0) return "";
|
|
140
|
+
if (Number(num(w)) <= 0) return "";
|
|
141
|
+
if (!renderedFinite(w)) throw new Error(`drawBar: rendered width must remain finite, got ${w}`);
|
|
142
|
+
const bar = el("rect", { x, y, width: w, height, rx: corner(radius, w, height), fill: tok(fill) });
|
|
143
|
+
if (trackWidth === undefined) return fade(opacity, id ? { "data-bar": id } : {}, bar);
|
|
144
|
+
const clipId = `${safeId(idPrefix)}-clip-${id}`;
|
|
145
|
+
const clip = el("defs", {}, el("clipPath", { id: clipId }, el("rect", { x, y, width: trackWidth, height, rx: corner(trackRadius, trackWidth, height) })));
|
|
146
|
+
return fade(opacity, { "data-bar": id }, clip, el("g", { "clip-path": `url(#${clipId})` }, bar));
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
/**
|
|
150
|
+
* One bar's growth: it starts at `start` s and takes `duration` s.
|
|
151
|
+
* @typedef {{ start: number, duration: number }} BarRun
|
|
152
|
+
*/
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* The eased progress of a bar's growth at time `t`, 0 before it starts and
|
|
156
|
+
* exactly 1 once it has ended, on the style's movement curve (`style.motion`,
|
|
157
|
+
* or the default curve for no style), so a bar moves as the rest of the diagram
|
|
158
|
+
* does on the page's own curve. `style` is the one `frame(t, { idPrefix, style })`
|
|
159
|
+
* is given.
|
|
160
|
+
* @param {number} t
|
|
161
|
+
* @param {BarRun} run
|
|
162
|
+
* @param {Pick<Style, "motion"> | null} [style]
|
|
163
|
+
* @returns {number}
|
|
164
|
+
*/
|
|
165
|
+
export function barProgress(t, run, style) {
|
|
166
|
+
checkRun(run);
|
|
167
|
+
if (!finite(t)) throw new Error(`barProgress: t must be finite, got ${t}`);
|
|
168
|
+
if (t >= barEnd(run)) return 1;
|
|
169
|
+
return progress(t, run.start, run.duration, easings(style?.motion).easeStandard);
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
/**
|
|
173
|
+
* The time a bar has settled and its value shows its end value: `start +
|
|
174
|
+
* duration`. A scene's step comes at least 50 ms after this for every bar of
|
|
175
|
+
* its beat.
|
|
176
|
+
* @param {BarRun} run
|
|
177
|
+
* @returns {number}
|
|
178
|
+
*/
|
|
179
|
+
export function barEnd(run) {
|
|
180
|
+
checkRun(run);
|
|
181
|
+
const end = run.start + run.duration;
|
|
182
|
+
if (!finite(end) || end <= run.start) throw new Error(`bar run: end must be finite and after start, got ${run.start} + ${run.duration}`);
|
|
183
|
+
return end;
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
/** @param {BarRun} run */
|
|
187
|
+
function checkRun(run) {
|
|
188
|
+
if (!run || !finite(run.start) || !finite(run.duration) || run.duration <= 0) throw new Error(`bar run: start must be finite and duration must be finite and above 0, got ${JSON.stringify(run)}`);
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/**
|
|
192
|
+
* The value a number shows at progress `p` of its bar: `from` at 0, `to` at
|
|
193
|
+
* the end, and in between a straight line (the bar's easing already shapes
|
|
194
|
+
* it), so the number and the bar arrive together. At `p` ≥ 1 it is `to` itself,
|
|
195
|
+
* exactly, never a rounded sum.
|
|
196
|
+
* @param {number} from
|
|
197
|
+
* @param {number} to
|
|
198
|
+
* @param {number} p
|
|
199
|
+
* @returns {number}
|
|
200
|
+
*/
|
|
201
|
+
export function rollingValue(from, to, p) {
|
|
202
|
+
if (!finite(from) || !finite(to) || !finite(p)) throw new Error(`rollingValue: from, to and p must be finite numbers, got ${from}, ${to}, ${p}`);
|
|
203
|
+
if (p >= 1) return to;
|
|
204
|
+
if (p <= 0) return from;
|
|
205
|
+
const v = lerp(from, to, p);
|
|
206
|
+
return finite(v) ? v : from * (1 - p) + to * p; // to - from overflowed: weigh each end instead
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
/**
|
|
210
|
+
* The number that rolls beside a bar: `format(rollingValue(from, to, p))` as
|
|
211
|
+
* text at (`x`, `y`), vertically centred on `y`. `format` is the caller's
|
|
212
|
+
* (units, decimals, locale: `(v) => new Intl.NumberFormat(locale, …).format(v)`)
|
|
213
|
+
* and must return a string; the default rounds to a whole number. Set `family`
|
|
214
|
+
* to a monospace face so the digits do not jitter as they change, and `anchor`
|
|
215
|
+
* to `"end"` at a fixed x so the number grows leftward, or `"start"` beside the
|
|
216
|
+
* bar's end.
|
|
217
|
+
* @param {{ x: number, y: number, to: number, from?: number, p: number, format?: (value: number) => string, fontSize?: number, anchor?: "start" | "middle" | "end", fill?: string, weight?: number, family?: string, opacity?: number, id?: string }} o
|
|
218
|
+
* @returns {string}
|
|
219
|
+
*/
|
|
220
|
+
export function drawValue({ x, y, to, from = 0, p, format = (v) => num(v, 0), fontSize = 16, anchor = "start", fill = "ink", weight = 600, family, opacity = 1, id }) {
|
|
221
|
+
if (![x, y, fontSize, weight].every(renderedFinite) || fontSize <= 0 || Number(num(fontSize)) <= 0) throw new Error("drawValue: x, y, fontSize and weight must remain finite and the size positive after SVG rounding");
|
|
222
|
+
if (typeof format !== "function") throw new Error("drawValue: format must be a function (number) => string");
|
|
223
|
+
const shown = format(rollingValue(from, to, p));
|
|
224
|
+
if (typeof shown !== "string") throw new Error(`drawValue: format must return a string, got ${typeof shown}`);
|
|
225
|
+
return fade(opacity, id ? { "data-value": id } : {}, text({ x, y, "text-anchor": anchor, "dominant-baseline": "central", "font-size": fontSize, "font-weight": weight, "font-family": family, fill: tok(fill) }, shown));
|
|
226
|
+
}
|
package/runtime/kit.mjs
CHANGED
|
@@ -26,12 +26,13 @@ import { FORMATS, localize, renderSvg, safeId, stepIndex, stepIndexAt, stepTimes
|
|
|
26
26
|
import { CONTRAST_EXEMPT, CONTRAST_PAIRS, NEUTRAL, TOKENS, checkContrast, contrast, contrastReport, cssVars, normalizeStyle, resolveTokens, sharedPairs, tok } from "./style.mjs";
|
|
27
27
|
import { CAMERA_ISOMETRIC, CAMERA_PLAN, ISO_ELEVATION, box, camera, drawGrid, drawOnPlane, drawSolid, drawSolids, fitCamera, labelAnchor, labelPill, labelProblems, lerpCamera, orderSolids, path3, planeMatrix, prism, project, projector, regularPolygon, roundedBox, roundedSlab, slab } from "./iso.mjs";
|
|
28
28
|
import { attrString, blurReveal, cubic, dist, drawOn, el, esc, fade, highlightSweep, num, pointOnLine, polyline, scaleAbout, text, tokenPoints, tokensAlong, translate, trimSegment } from "./svg.mjs";
|
|
29
|
+
import { barEnd, barProgress, drawBar, drawTrack, drawValue, hatchPattern, rollingValue } from "./bars.mjs";
|
|
29
30
|
import { PULSE_LAG, connectorPath, drawConnector, drawJunction, drawPulse, pulseEnd, pulseHead } from "./connectors.mjs";
|
|
30
31
|
import { estimateWidth, wrapLabel } from "./wrap.mjs";
|
|
31
32
|
|
|
32
33
|
/**
|
|
33
34
|
* The runtime, flat, handed to custom scene modules as `opts.kit`: the exports
|
|
34
|
-
* of motion, scene, style, svg, iso, connectors and wrap (not the scene types or the player).
|
|
35
|
+
* of motion, scene, style, svg, iso, connectors, bars and wrap (not the scene types or the player).
|
|
35
36
|
* Named imports, because lib/bundle.mjs inlines only that form; a new export
|
|
36
37
|
* in one of those modules is added here (test/runtime.test.mjs checks).
|
|
37
38
|
*/
|
|
@@ -42,6 +43,7 @@ export const KIT = Object.freeze({
|
|
|
42
43
|
...{ attrString, blurReveal, cubic, dist, drawOn, el, esc, fade, highlightSweep, num, pointOnLine, polyline, scaleAbout, text, tokenPoints, tokensAlong, translate, trimSegment },
|
|
43
44
|
...{ CAMERA_ISOMETRIC, CAMERA_PLAN, ISO_ELEVATION, box, camera, drawGrid, drawOnPlane, drawSolid, drawSolids, fitCamera, labelAnchor, labelPill, labelProblems, lerpCamera, orderSolids, path3, planeMatrix, prism, project, projector, regularPolygon, roundedBox, roundedSlab, slab },
|
|
44
45
|
...{ PULSE_LAG, connectorPath, drawConnector, drawJunction, drawPulse, pulseEnd, pulseHead },
|
|
46
|
+
...{ barEnd, barProgress, drawBar, drawTrack, drawValue, hatchPattern, rollingValue },
|
|
45
47
|
...{ estimateWidth, wrapLabel },
|
|
46
48
|
});
|
|
47
49
|
|
|
@@ -59,8 +59,9 @@ from the system's package manager (`brew install ffmpeg`, `apt install ffmpeg`).
|
|
|
59
59
|
(layout computed once). Only write a custom scene module when no type fits
|
|
60
60
|
(`references/custom-scenes.md`): that file also covers an isometric view
|
|
61
61
|
(camera, solids, depth order, label anchors), several tokens moving at once, dashed
|
|
62
|
-
connectors with diamond junctions and light pulses,
|
|
63
|
-
with a highlighter sweep (`blurReveal`, `highlightSweep`)
|
|
62
|
+
connectors with diamond junctions and light pulses, text that sharpens into place
|
|
63
|
+
with a highlighter sweep (`blurReveal`, `highlightSweep`), and hatched bar tracks
|
|
64
|
+
with bars that grow and values that roll.
|
|
64
65
|
4. **Gate.** `motion-kit check spec.json` must pass in every format/locale
|
|
65
66
|
shipped: deterministic, settled steps, rounded numbers, token-only colours,
|
|
66
67
|
escaped labels, labels fit, holds the final frame.
|
|
@@ -115,7 +116,7 @@ headers when redistributing the vendored runtime and adapters.
|
|
|
115
116
|
| `references/targets.md` | Where it will be shown and what each target allows |
|
|
116
117
|
| `references/styles.md` | Neutral default, style files, brand presets, contrast |
|
|
117
118
|
| `references/qc.md` | Review stages, checklist, review-report template |
|
|
118
|
-
| `references/custom-scenes.md` | Writing a one-off scene module, including isometric views, several tokens at once,
|
|
119
|
+
| `references/custom-scenes.md` | Writing a one-off scene module, including isometric views, several tokens at once, connectors with pulses, and bars with rolling values |
|
|
119
120
|
| `references/ecosystem.md` | When GSAP, HyperFrames, Remotion, Motion Canvas, Manim, Mermaid or ELK are the better tool |
|
|
120
121
|
|
|
121
122
|
For rendering, slide packaging and video, see the **motion-render** skill.
|
|
@@ -189,6 +189,31 @@ at a fraction `f` of the path is reached at `run.start + f * run.duration`).
|
|
|
189
189
|
A pulse never repeats while a step rests: a connector that pulses on a loop is
|
|
190
190
|
ambient motion, which the canon rules out.
|
|
191
191
|
|
|
192
|
+
## Bars with rolling values
|
|
193
|
+
|
|
194
|
+
`kit` also draws a row of a benchmark chart (`runtime/bars.mjs`). Template:
|
|
195
|
+
`examples/bars.scene.mjs` (three rows that reveal top to bottom, one step each).
|
|
196
|
+
|
|
197
|
+
| Need | Use |
|
|
198
|
+
|---|---|
|
|
199
|
+
| A hatched fill | `hatchPattern({ idPrefix, name?, stroke?, spacing?, width? })` returns `{ id, fill, markup }`: lines at 45° in a token colour (default `line`). Its id is `${safeId(idPrefix)}-hatch-${name}`, separate from clip-path IDs, so pass the `idPrefix` from `frame(t, { idPrefix, style })` and ensure prefixes stay unique after normalization; give each hatching its own `name` (letters, digits and `_`; no `-`, `title` or `desc`). Put `markup` (a `<defs>`) in the frame once, first, on every frame |
|
|
200
|
+
| An empty track | `drawTrack({ x, y, width, height, hatch, fill?, radius?, opacity?, id? })`: a rounded rect in the token `fill` (default `surface`) with the hatch over it |
|
|
201
|
+
| A bar | `drawBar({ x, y, width, height, p, fill?, radius?, trackRadius?, opacity?, idPrefix?, id?, trackWidth? })`: `width` is the bar's length when done (its value's share of the track's), the bar is `width * p` long and rounded at both ends as it grows. Pass the frame's `idPrefix`, a local safe row `id` (letters, digits and `_`, except `title` and `desc`), and the track's width to clip a short bar inside its pill; pass the track's `radius` as `trackRadius` whenever the track sets one explicitly. `p` is `barProgress(t, { start, duration }, style)`, which runs on the style's movement curve and is exactly 1 from `barEnd(run)` on |
|
|
202
|
+
| A value | `drawValue({ x, y, to, from?, p, format?, fontSize?, anchor?, family?, opacity?, id? })` draws `format(rollingValue(from, to, p))`: it shares the bar's raw progress, and exactly `to` once the bar has settled. A formatter may round to its final display early, so do not claim intermediate visible digits are synchronized. Without `format`, it rounds to a whole number (`to: 0.8` settles as `1`). `format` is yours (units, decimals, locale: `(v) => new Intl.NumberFormat(locale, { maximumFractionDigits: 1 }).format(v) + " s"`) and returns a string |
|
|
203
|
+
|
|
204
|
+
Anchor the value at a fixed x with `anchor: "end"` so the digits do not push the
|
|
205
|
+
text sideways, and set `family` to a monospace face so they do not jitter as
|
|
206
|
+
they change (the style's own monospace face is a separate piece of work). The
|
|
207
|
+
bar's accent sits on the track's colour: declare `{ fg: "accent", bg: "surface",
|
|
208
|
+
min: 3, use: "the bar's fill on its track" }` and `{ fg: "line", bg: "surface",
|
|
209
|
+
min: 2.5, use: "decorative hatching on the track" }` in `contrastPairs`. Hatching that conveys information is a shape and needs 3:1.
|
|
210
|
+
|
|
211
|
+
**Bars settle inside each beat.** A bar grows once and rests, and its value
|
|
212
|
+
rolls with it, within a beat; several bars may share one. Put the step's `at` at least 50 ms after the last motion in the beat (including track entrance and every `barEnd(run)`), and start the next motion no earlier than 50 ms after `at`; the settled-frame rule in the
|
|
213
|
+
gate then holds. A value that keeps updating beside live footage is not this
|
|
214
|
+
part, and a bar that grows again or pulses while a step rests is ambient motion,
|
|
215
|
+
which the canon rules out.
|
|
216
|
+
|
|
192
217
|
Canon: no loops, no ambient motion, no continuous scrubbing, 12 s hard limit
|
|
193
218
|
(8 s target). An isometric scene plays once and holds its last frame, like any
|
|
194
219
|
other, and under reduced motion the player shows that frame. A constantly
|
|
@@ -117,6 +117,22 @@ Use 50–100 ms lag. Draw the shape from `trail` to `lead`.
|
|
|
117
117
|
the gate's settled-frame rule only catches motion around the sampled step
|
|
118
118
|
boundaries, so it will not see every repeat.
|
|
119
119
|
|
|
120
|
+
## Bars and rolling values (derived)
|
|
121
|
+
|
|
122
|
+
- **Bar:** grows from the start of its track over 0.5–0.8 s on `easeStandard`
|
|
123
|
+
(the style's movement curve), as a pill. The track starts first (0.3–0.4 s);
|
|
124
|
+
the bar follows after about 0.25 s and may begin while the track finishes fading.
|
|
125
|
+
- **Value:** rolls from its start value to its end value with the bar's own
|
|
126
|
+
eased progress, so the raw number and the bar arrive together (a formatter
|
|
127
|
+
that rounds may show its final digits earlier), and shows exactly the end value
|
|
128
|
+
once the bar has settled. Never a separate timer; never a count that finishes
|
|
129
|
+
after the bar.
|
|
130
|
+
- **Timing rule:** the bar has settled (`barEnd`), and the value with it, ≥ 50 ms
|
|
131
|
+
before the step. Rows reveal one at a time, one step each, the next row's
|
|
132
|
+
entrance starting no earlier than 50 ms after the step.
|
|
133
|
+
- **Never** a bar or a number that keeps moving while a step rests: a value that
|
|
134
|
+
updates live is footage, not part of the diagram.
|
|
135
|
+
|
|
120
136
|
## Container and text timing
|
|
121
137
|
|
|
122
138
|
- The container (box, card) starts moving immediately; new text appears only
|