@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.
@@ -7,7 +7,7 @@
7
7
  "name": "motion-kit",
8
8
  "source": "./",
9
9
  "description": "animated-diagram, motion-render and project-logo skills and the motion-kit runtime/CLI",
10
- "version": "0.13.0"
10
+ "version": "0.14.0"
11
11
  }
12
12
  ]
13
13
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "motion-kit",
3
- "version": "0.13.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
@@ -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.13.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",
@@ -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, and text that sharpens into place
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, and connectors with pulses |
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