@liqweed/motion-kit 0.12.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.
@@ -189,11 +189,78 @@ 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
195
220
  moving hero is a 3D model's job, not motion-kit's.
196
221
 
222
+ ## Text that sharpens into place, and a highlighter
223
+
224
+ `kit` carries text helpers (`runtime/svg.mjs`), for a label or a quote that
225
+ should arrive as a beat and not just appear. Template:
226
+ `examples/text-reveal.scene.mjs` (three labels reveal in reading order, then a
227
+ quoted line reveals and is marked).
228
+
229
+ | Need | Use |
230
+ |---|---|
231
+ | A reveal | `blurReveal(enter, { id, rise, blur }, ...markup)` with `enter = progress(t, start, 0.4, easings(style.motion).easeOut)`. The markup starts soft, transparent and `rise` units low (default 6) and sharpens into place; `blur` is the starting radius (default 4, at most 12). Any markup works, a `<text>`, a group, a card. The default region holds the blur when the element's painted bounds are at least 12 × `blur` units wide (50 units at the default blur) **and** at least 3 × `blur` units tall (it adds only one element height above and below). For a narrower or shallower element, a short label, a thin rule or an icon, a larger `blur`, or any shape whose stroke or markers reach past its geometry by more than that padding (a thick stroke on a small shape, at any size), pass `box: { x, y, width, height }` covering the painted bounds (all four finite; `width` and `height` positive; `x` and `y` may be anything) |
232
+ | Its filter id | `id: idPrefix + "-reveal-" + i`, one per revealed element. The gate reports ids shared across instances at its sampled times (it can miss a short reveal between samples), so keep the prefix, and every slice of a baked SVG has its own prefix |
233
+ | A highlighter | `highlightSweep(p, { x, y, width, height, token, opacity, radius })`: a band in a token (default `emphasis`) at 30 % that grows from `x` to `x + width` as `p` (eased) goes 0 → 1; its `token` is checked once the band is drawn. Draw it **before** the text; size it from `estimateWidth(line, fontSize)` plus padding each side (the estimate is generous; do not shrink it where wide glyphs such as a capital W may appear, since they can run past a shortened band. `examples/text-reveal.scene.mjs` takes 0.9 of it for its fixed lines only, checked by eye in the rendered frames; the gate does not compare glyph widths with the band) |
234
+
235
+ Rules that keep it inside the canon:
236
+
237
+ - **Settled means bare.** When `enter` reaches 1, `blurReveal` returns your
238
+ markup with no group, no filter and no `<defs>`, so every step frame and the
239
+ final frame are byte-identical to the same text drawn without the reveal, provided the scene finishes the reveal (the gate checks only that those frames are stable).
240
+ Finish each reveal 50 ms or more before the step it belongs to, as with any
241
+ beat; the gate's settled-step rule then holds. Do not wrap the call in your
242
+ own filter or opacity.
243
+ - **Once per element, inside a beat.** A reveal runs 300–600 ms and never
244
+ repeats. Stagger siblings 80–150 ms in reading order. A blinking cursor or any
245
+ other loop is ambient motion and stays out; a static cursor is fine.
246
+ - **Reduced motion** shows the final frame, which is the settled text and the
247
+ full band: no filter, no motion.
248
+ - **Renderers.** The live player (in-place patch), `bake`, PNG export (resvg,
249
+ Chrome) and video use the same helper and filter parameters; the raster blur can vary with renderer, fonts and scale, and only one resvg frame is checked. A consumer that ignores SVG filters
250
+ shows the fade and the rise only, and only mid-reveal; step frames carry no
251
+ filter.
252
+ - **Cost.** A blur is the most expensive thing a frame can ask the browser for.
253
+ Reveal the handful of elements the viewer must watch arrive, not every
254
+ element in a dense diagram; for those, `fade()` is enough
255
+ (`motion-vocabulary.md`, "Blur reveal or plain fade").
256
+ - **Contrast.** Start the band's `opacity` at 0.2–0.4, but the gate checks the
257
+ text against the canvas, not against the tinted band. With a custom style,
258
+ composite the band colour at that opacity over the token actually behind it
259
+ (`bg` for text on the canvas, `surface` for text on a node, `accent` for text
260
+ on an active node) and check every text colour actually drawn there (`ink`, `muted` for
261
+ pending labels, or `onAccent` on an accent fill) against the result (4.5:1), or lower the
262
+ opacity until it holds.
263
+
197
264
  ## Declared locales and narrative steps
198
265
 
199
266
  Export `const locales = ["en", "nl"]` alongside the default factory so both
@@ -25,6 +25,23 @@ custom scene's `frame` rather than importing the constants.
25
25
  | Pause between beats | ≥ 50 ms, so step frames settle |
26
26
  | Whole explainer | aim for ≤ 8 s, then hold; gate limit 12 s |
27
27
 
28
+ ## Blur reveal or plain fade (`blurReveal`, `highlightSweep`)
29
+
30
+ | | Plain fade (`fade`, the node parts' 8-unit rise) | Blur reveal (`blurReveal`) |
31
+ |---|---|---|
32
+ | Use it for | Nodes, connectors, anything in a dense diagram; text that is not the point of the beat | Text the viewer should watch land: a heading, the label of the one thing the beat introduces, a quoted line, a card |
33
+ | Looks like | Appears from transparent, rising a few units | The same, and starts soft: sharpens into place over the same 300–600 ms |
34
+ | Cost | Opacity and transform only | An SVG filter per revealing element, every frame of the reveal. Keep to a few elements at a time |
35
+ | Settled | No opacity or transform left; `fade` still wraps the markup in a `<g>` | No trace: the markup comes back bare, byte-identical |
36
+
37
+ Reveal in reading order, siblings 80–150 ms apart, on the style's entrance
38
+ curve. A reveal that does not carry a beat is decoration: use the fade. A
39
+ `highlightSweep` marks one thing in a scene (it uses the `emphasis` token, and
40
+ there is one emphasis element), grows left to right behind its text over about
41
+ 0.6 s on the entrance curve, and starts while the text is still sharpening or
42
+ once it has. Neither helper loops; a blinking cursor is ambient motion, so a
43
+ cursor stays static.
44
+
28
45
  ## Springs, without breaking random access (derived)
29
46
 
30
47
  Frame-by-frame spring simulation depends on earlier frames. Use the closed form.
@@ -100,6 +117,22 @@ Use 50–100 ms lag. Draw the shape from `trail` to `lead`.
100
117
  the gate's settled-frame rule only catches motion around the sampled step
101
118
  boundaries, so it will not see every repeat.
102
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
+
103
136
  ## Container and text timing
104
137
 
105
138
  - The container (box, card) starts moving immediately; new text appears only