@link-foundation/ui-animation 0.0.0-stage → 0.1.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/LICENSE +24 -0
- package/README.md +454 -2
- package/package.json +77 -4
- package/src/backgrounds/README.md +131 -0
- package/src/backgrounds/beams.d.ts +21 -0
- package/src/backgrounds/beams.js +140 -0
- package/src/backgrounds/common.d.ts +23 -0
- package/src/backgrounds/common.js +322 -0
- package/src/backgrounds/grid.d.ts +16 -0
- package/src/backgrounds/grid.js +122 -0
- package/src/backgrounds/nebula.d.ts +9 -0
- package/src/backgrounds/nebula.js +57 -0
- package/src/backgrounds/rain-cleanup.js +77 -0
- package/src/backgrounds/rain.d.ts +33 -0
- package/src/backgrounds/rain.js +238 -0
- package/src/backgrounds/shader.d.ts +14 -0
- package/src/backgrounds/shader.js +151 -0
- package/src/backgrounds/sprites.js +72 -0
- package/src/backgrounds/starfield.d.ts +38 -0
- package/src/backgrounds/starfield.js +168 -0
- package/src/clock.js +98 -0
- package/src/compile-waapi.js +147 -0
- package/src/diagnostics.js +51 -0
- package/src/easing.js +327 -0
- package/src/effects/decipher.js +83 -0
- package/src/effects.js +44 -0
- package/src/index.d.ts +581 -0
- package/src/index.js +74 -0
- package/src/layers.js +88 -0
- package/src/model.js +636 -0
- package/src/player.js +267 -0
- package/src/random.js +62 -0
- package/src/recorder/buffer.js +40 -0
- package/src/recorder/clock.js +2 -0
- package/src/recorder/format.js +125 -0
- package/src/recorder/input.js +53 -0
- package/src/recorder/recorder.js +183 -0
- package/src/recorder/redact.js +43 -0
- package/src/recorder/replay.js +115 -0
- package/src/recorder/state-at.js +62 -0
- package/src/recorder/store.js +92 -0
- package/src/recorder/to-playwright.js +113 -0
- package/src/recorder/verify.js +49 -0
- package/src/run.js +283 -0
- package/src/sample.js +160 -0
- package/src/timeline.js +115 -0
- package/src/timing.js +172 -0
- package/src/tokens.js +32 -0
- package/src/types.js +130 -0
- package/src/validate.js +218 -0
- package/src/values.js +331 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
This is free and unencumbered software released into the public domain.
|
|
2
|
+
|
|
3
|
+
Anyone is free to copy, modify, publish, use, compile, sell, or
|
|
4
|
+
distribute this software, either in source code form or as a compiled
|
|
5
|
+
binary, for any purpose, commercial or non-commercial, and by any
|
|
6
|
+
means.
|
|
7
|
+
|
|
8
|
+
In jurisdictions that recognize copyright laws, the author or authors
|
|
9
|
+
of this software dedicate any and all copyright interest in the
|
|
10
|
+
software to the public domain. We make this dedication for the benefit
|
|
11
|
+
of the public at large and to the detriment of our heirs and
|
|
12
|
+
successors. We intend this dedication to be an overt act of
|
|
13
|
+
relinquishment in perpetuity of all present and future rights to this
|
|
14
|
+
software under copyright law.
|
|
15
|
+
|
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
17
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
18
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
19
|
+
IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
|
|
20
|
+
OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
|
|
21
|
+
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
|
22
|
+
OTHER DEALINGS IN THE SOFTWARE.
|
|
23
|
+
|
|
24
|
+
For more information, please refer to <https://unlicense.org>
|
package/README.md
CHANGED
|
@@ -1,3 +1,455 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @link-foundation/ui-animation
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Animations of the associative UI framework, written in Links Notation. The
|
|
4
|
+
package has four parts:
|
|
5
|
+
|
|
6
|
+
1. **a model** (`loadAnimations`): `animation` links with keyframe tracks,
|
|
7
|
+
easings, springs and procedural effects, `timeline` links with `at`,
|
|
8
|
+
`sequence`, `parallel` and `stagger`, and `(on STATE ...)` triggers;
|
|
9
|
+
2. **a pure sampler** (`sample`, `sampleLayers`): the values of an animation
|
|
10
|
+
at a time, as a function of `(animation, t, seed)` only, so animations
|
|
11
|
+
can be scrubbed, recorded and tested;
|
|
12
|
+
3. **a WAAPI compiler** (`toWaapi`): keyframes and options for
|
|
13
|
+
`element.animate()`;
|
|
14
|
+
4. **a player** (`createPlayer`): it runs CSS properties on the Web
|
|
15
|
+
Animations API and effects and non-CSS properties on a frame loop
|
|
16
|
+
driven by an injectable clock, follows reduced motion and plays the
|
|
17
|
+
triggers of a [ui-store](../ui-store/README.md) document.
|
|
18
|
+
|
|
19
|
+
Safety is part of the model: `validateAnimation` reports fills that leave
|
|
20
|
+
`clip-path` or transforms on an element, photosensitive flashes (WCAG 2.3.1)
|
|
21
|
+
and movement without a reduced-motion variant.
|
|
22
|
+
|
|
23
|
+
Text is read only by the `parse` function of
|
|
24
|
+
[`@link-foundation/ui-core`](../ui-core/README.md), the official
|
|
25
|
+
`links-notation` parser. That is the only runtime dependency.
|
|
26
|
+
|
|
27
|
+
```js
|
|
28
|
+
import {
|
|
29
|
+
loadAnimations,
|
|
30
|
+
validateAnimations,
|
|
31
|
+
createPlayer,
|
|
32
|
+
} from '@link-foundation/ui-animation';
|
|
33
|
+
import { mountDocument } from '@link-foundation/ui-dom';
|
|
34
|
+
|
|
35
|
+
const { store, handle } = mountDocument(app, documentText);
|
|
36
|
+
const model = loadAnimations(animationsText); // { animations, timelines, triggers, diagnostics }
|
|
37
|
+
validateAnimations(model, { resolveToken }); // [] when it is safe
|
|
38
|
+
|
|
39
|
+
const player = createPlayer(handle, { animations: model, resolveToken });
|
|
40
|
+
player.bindTriggers(store); // (on pressed ...) plays when `pressed` turns on
|
|
41
|
+
await player.play('intro').finished;
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
The [example](../../examples/animation/index.html) plays an intro timeline
|
|
45
|
+
on a ui-dom document and has a reduced-motion toggle.
|
|
46
|
+
|
|
47
|
+
## Model
|
|
48
|
+
|
|
49
|
+
```lino
|
|
50
|
+
panel-enter: animation
|
|
51
|
+
duration 300ms
|
|
52
|
+
easing
|
|
53
|
+
cubic-bezier 0.2 0 0 1
|
|
54
|
+
fill backwards
|
|
55
|
+
track opacity
|
|
56
|
+
key 0 0
|
|
57
|
+
key 1 1
|
|
58
|
+
track translate
|
|
59
|
+
key 0 '0 8px'
|
|
60
|
+
key 1 '0 0'
|
|
61
|
+
reduced-motion
|
|
62
|
+
duration 0ms
|
|
63
|
+
bounce: animation
|
|
64
|
+
duration 600ms
|
|
65
|
+
easing
|
|
66
|
+
spring
|
|
67
|
+
stiffness 300
|
|
68
|
+
damping 20
|
|
69
|
+
mass 1
|
|
70
|
+
track scale
|
|
71
|
+
key 0 0.9
|
|
72
|
+
key 1 1
|
|
73
|
+
title-reveal: animation
|
|
74
|
+
target title
|
|
75
|
+
duration 900ms
|
|
76
|
+
effect decipher
|
|
77
|
+
seed 42
|
|
78
|
+
press-feedback: animation
|
|
79
|
+
target ok
|
|
80
|
+
duration
|
|
81
|
+
token motion.duration.short
|
|
82
|
+
easing standard
|
|
83
|
+
track scale
|
|
84
|
+
key 0 1
|
|
85
|
+
key 0.5 0.96
|
|
86
|
+
key 1 1
|
|
87
|
+
on pressed
|
|
88
|
+
intro: timeline
|
|
89
|
+
at 0ms
|
|
90
|
+
play panel-enter
|
|
91
|
+
target sidebar
|
|
92
|
+
at 120ms
|
|
93
|
+
stagger 50ms
|
|
94
|
+
play bounce
|
|
95
|
+
targets item-1 item-2 item-3
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Write one top-level link per line: Links Notation joins the links of one
|
|
99
|
+
line into a single link.
|
|
100
|
+
|
|
101
|
+
### `animation`
|
|
102
|
+
|
|
103
|
+
| Part | Values | Default |
|
|
104
|
+
| ----------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------- |
|
|
105
|
+
| `(target ID)` | the store ID of the element it plays on | the `target` of `play` |
|
|
106
|
+
| `(duration TIME)` | `300ms`, `0.3s`, `(token motion.duration.short)` | the settle time of a spring, else 0 |
|
|
107
|
+
| `(delay TIME)` | as `duration` | `0ms` |
|
|
108
|
+
| `(iterations N)` | a number or `infinite` | `1` |
|
|
109
|
+
| `(direction D)` | `normal`, `reverse`, `alternate`, `alternate-reverse` | `normal` |
|
|
110
|
+
| `(fill F)` | `none`, `forwards`, `backwards`, `both`, `auto` | `none` |
|
|
111
|
+
| `(composite C)` | `replace`, `add`, `accumulate` | `replace` |
|
|
112
|
+
| `(easing E)` | see [Easings](#easings) | `linear` |
|
|
113
|
+
| `(track PROPERTY (key OFFSET VALUE [EASING])...)` | keyframes of one property; offsets 0–1, sorted | |
|
|
114
|
+
| `(effect NAME (seed S) (PARAM V)...)` | a registered procedural effect | |
|
|
115
|
+
| `(envelope bell\|sustain [(attack TIME)] [(release TIME)])` | the weight of an additive layer over its run | none |
|
|
116
|
+
| `(persist true)` | allows a final `clip-path` or transform to stay (see [Safety](#safety)) | `false` |
|
|
117
|
+
| `(on STATE [(play ID [(target ID)])])` | plays this animation (or `ID`) when its target enters `STATE` | |
|
|
118
|
+
| `(reduced-motion PART...)` | the parts that replace these under reduced motion | opacity tracks only, duration 0 |
|
|
119
|
+
|
|
120
|
+
**Values.** A key value is a number (`0.96`), a length or any CSS text with
|
|
121
|
+
units (`'0 8px'`, `'inset(0 100% 0 0)'`, `'45deg'`), a colour (`'#FF0000'`,
|
|
122
|
+
`(oklch ...)`, `(rgb ...)`, mixed in OKLCH) or `(token PATH)`. Texts with the
|
|
123
|
+
same shape are mixed number by number; other values switch at the middle.
|
|
124
|
+
|
|
125
|
+
**Properties.** Any CSS property runs on WAAPI. `text`, `label`, `value`,
|
|
126
|
+
`title`, `placeholder` and `progress` are not CSS: the player writes them
|
|
127
|
+
on every frame (`text` as the text content, `value` as the form value, the
|
|
128
|
+
others as attributes) and restores them when the animation no longer
|
|
129
|
+
applies (after its end without a fill).
|
|
130
|
+
|
|
131
|
+
**States.** A trigger state is `hover`, `focus`, `pressed` or `disabled`: a
|
|
132
|
+
store property of that name whose value is not `false`. An element can
|
|
133
|
+
also play animations on others: `(ok: button (on hover (play glow (target
|
|
134
|
+
help))))`.
|
|
135
|
+
|
|
136
|
+
### Easings
|
|
137
|
+
|
|
138
|
+
- a name: `linear`, `ease`, `ease-in`, `ease-out`, `ease-in-out`,
|
|
139
|
+
`step-start`, `step-end`, or a theme easing such as `standard` or
|
|
140
|
+
`emphasized`, read from the token `motion.easing.NAME` when the theme
|
|
141
|
+
has it;
|
|
142
|
+
- `(cubic-bezier x1 y1 x2 y2)`;
|
|
143
|
+
- `(steps n [start|end|jump-both|jump-none])`;
|
|
144
|
+
- `(spring (stiffness k) (damping c) (mass m))`: a closed-form damped
|
|
145
|
+
oscillator. Without `(duration ...)` the animation lasts until the spring
|
|
146
|
+
settles within 0.05% of its target; on WAAPI it runs as a CSS `linear()`
|
|
147
|
+
(`toCssLinear`).
|
|
148
|
+
|
|
149
|
+
A key may carry the easing of the segment that starts at it:
|
|
150
|
+
`(key 0 1 ease-out)`. Key offsets are literal fractions of the iteration duration, after delay and
|
|
151
|
+
playback direction. Animation easing is the default for each segment; a key's
|
|
152
|
+
explicit easing overrides it for the segment starting there. With no easing,
|
|
153
|
+
interpolation is linear. Thus the unchanged `press-feedback` sample reaches
|
|
154
|
+
scale `0.96` at 50% even with `easing standard`. See the normative
|
|
155
|
+
[timing contract](../../docs/spec/animation-timing.md) resolving #52 and #57.
|
|
156
|
+
Procedural effects have no key segments and retain whole-iteration easing.
|
|
157
|
+
|
|
158
|
+
### `timeline`
|
|
159
|
+
|
|
160
|
+
```
|
|
161
|
+
(NAME: timeline ITEM...)
|
|
162
|
+
ITEM = (play ID [(target ID)] [(targets ID...)])
|
|
163
|
+
| (at TIME ITEM...) starts its items TIME after its parent
|
|
164
|
+
| (sequence ITEM...) starts each item when the one before ends
|
|
165
|
+
| (parallel ITEM...) starts its items together
|
|
166
|
+
| (stagger STEP ITEM... [(targets ID...)])
|
|
167
|
+
the i-th target (or item) starts i * STEP later
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
`(play ID)` can play another timeline. A timeline that plays itself is a
|
|
171
|
+
`timeline-cycle` diagnostic. `flattenTimeline(model, id)` returns the flat
|
|
172
|
+
schedule `[{ start, id, target }]`.
|
|
173
|
+
|
|
174
|
+
### Diagnostics
|
|
175
|
+
|
|
176
|
+
`loadAnimations(text).diagnostics` and the validators use the ui-core shape
|
|
177
|
+
`{ code, severity, message, at }`:
|
|
178
|
+
|
|
179
|
+
| Code | Severity | When |
|
|
180
|
+
| ------------------------ | -------- | ------------------------------------------------------------------------------------- |
|
|
181
|
+
| `anonymous-animation` | warning | an `animation` or `timeline` has no id |
|
|
182
|
+
| `unknown-sublink` | warning | a part the model does not know |
|
|
183
|
+
| `invalid-value` | error | a value of the wrong type (`(duration fast)`) |
|
|
184
|
+
| `unknown-easing` | error | an easing that is not a name, bezier, steps or spring (a warning for an unknown name) |
|
|
185
|
+
| `empty-track` | error | a track without keys |
|
|
186
|
+
| `key-offset-range` | error | a key offset outside 0–1 |
|
|
187
|
+
| `key-offset-order` | error | key offsets that are not sorted |
|
|
188
|
+
| `unknown-effect` | warning | an effect that is not registered |
|
|
189
|
+
| `unknown-state` | warning | `(on STATE)` with a state that is not one of the four |
|
|
190
|
+
| `unknown-animation` | error | `play` of an id that is not an animation or timeline |
|
|
191
|
+
| `timeline-cycle` | error | a timeline that plays itself |
|
|
192
|
+
| `persistent-fill` | error | see [Safety](#safety) |
|
|
193
|
+
| `flash` | error | see [Safety](#safety) |
|
|
194
|
+
| `missing-reduced-motion` | warning | see [Safety](#safety) |
|
|
195
|
+
|
|
196
|
+
## Safety
|
|
197
|
+
|
|
198
|
+
`validateAnimation(animation, { resolveToken })` and
|
|
199
|
+
`validateAnimations(model, options)` check three rules. They come from
|
|
200
|
+
regressions found in [immortality](https://github.com/konard/immortality/tree/main/docs/case-studies/issue-7).
|
|
201
|
+
|
|
202
|
+
- **Fill (`persistent-fill`, error).** `(fill both)` or `(fill forwards)` on
|
|
203
|
+
a `clip-path`, `transform`, `translate`, `scale` or `rotate` track keeps
|
|
204
|
+
the final value on the element after the animation ends, which clipped
|
|
205
|
+
and shifted panels. Use `(fill none)` or `(fill backwards)`, or write
|
|
206
|
+
`(persist true)` when the end state must stay.
|
|
207
|
+
- **Flash (`flash`, error).** WCAG 2.3.1 Three Flashes or Below Threshold.
|
|
208
|
+
`opacity`, `background-color` and `color` tracks are sampled at 60 Hz. A
|
|
209
|
+
change is a swing of relative luminance of at least 0.1 whose darker side
|
|
210
|
+
is below 0.8 (opacity is taken as the luminance of a white layer over
|
|
211
|
+
black, the worst case), and a flash is a pair of opposing changes. More
|
|
212
|
+
than 3 flashes in any one-second window is an error: an 8 Hz
|
|
213
|
+
`(steps 1)` opacity flicker fails, a 0.5 Hz breathing glow passes.
|
|
214
|
+
- **Reduced motion (`missing-reduced-motion`, warning).** A `translate`,
|
|
215
|
+
`scale`, `rotate` or `transform` track that runs for more than 0 ms
|
|
216
|
+
without a `(reduced-motion ...)` block. Under reduced motion such an
|
|
217
|
+
animation keeps only its opacity tracks, with duration 0.
|
|
218
|
+
|
|
219
|
+
The player follows reduced motion with `defaultMotion(element)`: it is
|
|
220
|
+
`reduced` when the closest `[data-motion]` ancestor says `reduced`, or when
|
|
221
|
+
the user agent prefers reduced motion. It then plays the
|
|
222
|
+
`(reduced-motion ...)` variant (`reducedMotionVariant`). Timeline `at`
|
|
223
|
+
offsets stay as written.
|
|
224
|
+
|
|
225
|
+
Randomness comes only from `seededRandom(seed)`: the package never calls
|
|
226
|
+
the global random source, so every frame is reproducible.
|
|
227
|
+
|
|
228
|
+
## GSAP is not used
|
|
229
|
+
|
|
230
|
+
This package uses the Web Animations API and its own sampler. **GSAP must
|
|
231
|
+
never be added**, not even as an optional or development dependency: its
|
|
232
|
+
[standard licence](https://gsap.com/community/standard-license/) forbids
|
|
233
|
+
its use in tools that compete with its no-code animation products, which
|
|
234
|
+
a Links Notation animation editor is. `npm ls gsap` must stay empty (see
|
|
235
|
+
[existing solutions](../../docs/case-studies/issue-1/research/existing-solutions.md)).
|
|
236
|
+
Motion (MIT) may come later as an optional adapter.
|
|
237
|
+
|
|
238
|
+
## API
|
|
239
|
+
|
|
240
|
+
### Model
|
|
241
|
+
|
|
242
|
+
- `loadAnimations(text)` → `{ animations: Map, timelines: Map, triggers, diagnostics }`.
|
|
243
|
+
- `ANIMATION_STATES`, `ANIMATION_DEFAULTS`.
|
|
244
|
+
|
|
245
|
+
### Sampling
|
|
246
|
+
|
|
247
|
+
- `sample(animation, tMs, { resolveToken, seed, input })` → `{ scale: 0.96, … }`:
|
|
248
|
+
CSS values as numbers or strings, effect output under its property. Pure:
|
|
249
|
+
the same arguments always give the same values.
|
|
250
|
+
- `sampleTyped(animation, tMs, options)` → `{ active, values, effects }` with
|
|
251
|
+
typed values.
|
|
252
|
+
- `sampleLayers(layers, tMs, options)`: sums `(composite add)` and
|
|
253
|
+
`(composite accumulate)` layers onto the `replace` layers below them, each
|
|
254
|
+
weighted by its envelope (`bell` is sin²(πp); `sustain` rises over its
|
|
255
|
+
attack, holds and falls over its release, 20% of the run each by
|
|
256
|
+
default), so nothing snaps. A layer is an animation or
|
|
257
|
+
`{ animation, start, seed, input }`.
|
|
258
|
+
- `envelopeWeight(envelope, progress, duration)`.
|
|
259
|
+
|
|
260
|
+
### Easing
|
|
261
|
+
|
|
262
|
+
`linear`, `cubicBezier(x1, y1, x2, y2)`, `steps(n, position)`,
|
|
263
|
+
`spring({ stiffness, damping, mass })` → `{ at(tMs), settleTime }`,
|
|
264
|
+
`springEasing(spring)`, `toCssLinear(fn, samples = 40)`,
|
|
265
|
+
`easingFunction(easing, resolveToken)`, `easingCss(easing, resolveToken)`,
|
|
266
|
+
`NAMED_EASINGS`, `SPRING_TOLERANCE`.
|
|
267
|
+
|
|
268
|
+
### Effects
|
|
269
|
+
|
|
270
|
+
- `registerEffect(name, fn, { property = 'text' })`, where `fn` is a pure
|
|
271
|
+
`(input, progress, seed, params) => output`; `getEffect(name)`,
|
|
272
|
+
`effectNames()`.
|
|
273
|
+
- `decipher(input, progress, seed)`: the text appears from random glyphs,
|
|
274
|
+
one character at a time in a seeded order. It is ported from
|
|
275
|
+
[immortality `textEffects.ts`](https://github.com/konard/immortality/blob/main/app/src/textEffects.ts)
|
|
276
|
+
(Unlicense).
|
|
277
|
+
- `seededRandom(seed)` (mulberry32), `seedNumber`, `hashString`, `mix`.
|
|
278
|
+
|
|
279
|
+
### WAAPI
|
|
280
|
+
|
|
281
|
+
`toWaapi(animation, { resolveToken })` → `{ keyframes, options }`. For the
|
|
282
|
+
sample `press-feedback` with the sample tokens:
|
|
283
|
+
|
|
284
|
+
```js
|
|
285
|
+
({
|
|
286
|
+
keyframes: [
|
|
287
|
+
{ offset: 0, easing: 'cubic-bezier(0.2, 0, 0, 1)', scale: '1' },
|
|
288
|
+
{ offset: 0.5, easing: 'cubic-bezier(0.2, 0, 0, 1)', scale: '0.96' },
|
|
289
|
+
{ offset: 1, easing: 'cubic-bezier(0.2, 0, 0, 1)', scale: '1' },
|
|
290
|
+
],
|
|
291
|
+
options: {
|
|
292
|
+
duration: 150,
|
|
293
|
+
easing: 'linear',
|
|
294
|
+
fill: 'none',
|
|
295
|
+
composite: 'replace',
|
|
296
|
+
},
|
|
297
|
+
});
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
Only CSS tracks become keyframes (`isCssProperty`, `NON_CSS_PROPERTIES`).
|
|
301
|
+
|
|
302
|
+
### Player
|
|
303
|
+
|
|
304
|
+
```js
|
|
305
|
+
const player = createPlayer(handle, {
|
|
306
|
+
animations, // LiNo text or a loaded model
|
|
307
|
+
resolveToken, // tokenResolver(resolveTokens(sets, 'material3'))
|
|
308
|
+
clock, // default: requestAnimationFrame and performance.now()
|
|
309
|
+
motion, // 'full' | 'reduced' | (element) => ...; default: defaultMotion
|
|
310
|
+
animate, // default: (element, keyframes, options) => element.animate(...)
|
|
311
|
+
seed, // the seed of effects without (seed ...)
|
|
312
|
+
});
|
|
313
|
+
|
|
314
|
+
const control = player.play('intro', { target, seed, input });
|
|
315
|
+
control.seek(75); // every run at 75 ms, paused
|
|
316
|
+
control.pause();
|
|
317
|
+
control.play();
|
|
318
|
+
control.cancel(); // restores the values from before and rejects `finished`
|
|
319
|
+
await control.finished;
|
|
320
|
+
|
|
321
|
+
const unsubscribe = player.bindTriggers(store);
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
`handle` is a ui-dom handle (`nodeFor(id)`), a function of the id, or
|
|
325
|
+
`null`. `createManualClock()` gives a clock that only moves on
|
|
326
|
+
`advance(ms)`, so tests are deterministic; `systemClock()` is the default.
|
|
327
|
+
`triggersFor(model, store, id, state)` lists what plays when an element
|
|
328
|
+
enters a state.
|
|
329
|
+
|
|
330
|
+
## Tests
|
|
331
|
+
|
|
332
|
+
```sh
|
|
333
|
+
node --test packages/ui-animation/tests/*.test.js
|
|
334
|
+
npx playwright test tests/e2e/animation.spec.js --project=chromium
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
The Playwright spec checks that `panel-enter` leaves the computed
|
|
338
|
+
`translate` and `clip-path` of the panel as they were before it, that the
|
|
339
|
+
intro timeline runs with its offsets and stagger, the reduced-motion
|
|
340
|
+
toggle, the `pressed` trigger, and the accessibility of the example.
|
|
341
|
+
|
|
342
|
+
## License
|
|
343
|
+
|
|
344
|
+
[Unlicense](LICENSE) (public domain).
|
|
345
|
+
|
|
346
|
+
## Recording format
|
|
347
|
+
|
|
348
|
+
The recorder stores the clock, inputs, store operations and animation starts,
|
|
349
|
+
not pixels. The initial `snapshot` is the store's LiNo operation log, inserting
|
|
350
|
+
all roots with their stable IDs and exact property lists. `set` is the readable
|
|
351
|
+
form of `setProp`; structural events use the merged store's operation syntax.
|
|
352
|
+
Other updates (`removeProp`, positional edits, duplicate properties and rename)
|
|
353
|
+
use `set` with an `operation` child carrying the original operation. No store
|
|
354
|
+
methods are patched and no fake snapshot/restore API is required.
|
|
355
|
+
|
|
356
|
+
```js
|
|
357
|
+
import {
|
|
358
|
+
createRecorder,
|
|
359
|
+
replay,
|
|
360
|
+
stateAt,
|
|
361
|
+
animationsAt,
|
|
362
|
+
verifyReplay,
|
|
363
|
+
toPlaywright,
|
|
364
|
+
} from '@link-foundation/ui-animation';
|
|
365
|
+
|
|
366
|
+
const recorder = createRecorder({ store, player, root, handle, seed: 42 });
|
|
367
|
+
recorder.start();
|
|
368
|
+
recorder.mark('saved once');
|
|
369
|
+
const text = recorder.stop(); // detaches store, player and DOM listeners
|
|
370
|
+
const playback = replay(text, { store, player });
|
|
371
|
+
playback.seek(990);
|
|
372
|
+
playback.seek(0); // restores the initial snapshot, then applies due diffs
|
|
373
|
+
await playback.play();
|
|
374
|
+
const spec = toPlaywright(text, { url: '/examples/animation/' });
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
```lino
|
|
378
|
+
session-7: recording
|
|
379
|
+
started '2026-11-01T12:00:00Z'
|
|
380
|
+
seed 42
|
|
381
|
+
viewport 1280 800
|
|
382
|
+
document app
|
|
383
|
+
redacted true
|
|
384
|
+
event 0ms
|
|
385
|
+
set ok label OK
|
|
386
|
+
event 840ms
|
|
387
|
+
input pointer down ok
|
|
388
|
+
at 12 8
|
|
389
|
+
event 841ms
|
|
390
|
+
play press-feedback
|
|
391
|
+
target ok
|
|
392
|
+
event 990ms
|
|
393
|
+
set ok label Saved
|
|
394
|
+
```
|
|
395
|
+
|
|
396
|
+
`parseRecording` accepts the official parser's nested and parenthesized forms;
|
|
397
|
+
`serializeRecording` writes the canonical nested form and preserves header and
|
|
398
|
+
event order. Event times are nonnegative integer milliseconds relative to
|
|
399
|
+
`start()`, with file order breaking ties. `started` is the wall-clock origin;
|
|
400
|
+
set `started` explicitly alongside an injected monotonic `clock` for fixtures.
|
|
401
|
+
Viewport and document ID are inferred from the root, or supplied explicitly.
|
|
402
|
+
`stateAt(text, ms)` returns a pure LiNo snapshot. `animationsAt(text, ms)` lists
|
|
403
|
+
uncancelled plays with local time and seed; pass `{ model, resolveToken }` to
|
|
404
|
+
filter completed animations and timelines before sampling them.
|
|
405
|
+
|
|
406
|
+
DOM listeners are passive and capture-phase. The render handle maps targets to
|
|
407
|
+
stable IDs, and pointer coordinates are relative to the target box. Pointer
|
|
408
|
+
moves retain at most one event per 1/60-second bucket for the session. Adjacent
|
|
409
|
+
text edits to the same field merge into the final value; intervening diffs or
|
|
410
|
+
other events preserve causal order. Password and `(sensitive true)` values are
|
|
411
|
+
redacted as `***` in the initial snapshot, insertions, updates and input events
|
|
412
|
+
by default. `redact: false` explicitly opts out. A DOM password target is also
|
|
413
|
+
remembered for subsequent store updates. `maxEvents` defaults to 100,000;
|
|
414
|
+
overflow retains the latest events in a ring and adds `truncated true`. Such
|
|
415
|
+
recordings can be inspected, but replay, verification and export reject them
|
|
416
|
+
because their missing prefix cannot be reproduced faithfully.
|
|
417
|
+
|
|
418
|
+
The shared `createManualClock()` runs timers at their exact due times, preserving
|
|
419
|
+
insertion order for ties. `advance(ms)` drives replay and player frames without
|
|
420
|
+
real time. `replay` applies recorded diffs and seeded animations; it does not
|
|
421
|
+
redispatch inputs. `pause()` resolves the pending `play()` call, and `seek()`
|
|
422
|
+
pauses playback. Store-triggered animations ignore operations with origin
|
|
423
|
+
`replay`, so recorded play events are not fired twice.
|
|
424
|
+
|
|
425
|
+
`verifyReplay(text, { createApp })` builds a fresh app with `createApp(seed,
|
|
426
|
+
clock)`. Return `{ store, dispatchInput(event), dispose?() }`: the verifier
|
|
427
|
+
restores the initial snapshot, dispatches only recorded inputs at their recorded
|
|
428
|
+
times, then compares resulting store diffs (including timestamps and order).
|
|
429
|
+
The injected clock must drive the app's timers too. The asynchronous result
|
|
430
|
+
contains `ok` and `{ time, expected, actual }` mismatches. Redacted recordings
|
|
431
|
+
can only verify handlers whose observable output is independent of the removed
|
|
432
|
+
secret values; a mismatch is reported rather than assuming those values.
|
|
433
|
+
|
|
434
|
+
Keyboard events use Playwright’s native keyboard API, including default button
|
|
435
|
+
activation. Text events skip a fill when the preceding key already produced the
|
|
436
|
+
recorded value, avoiding duplicate input notifications. Redacted keys remain
|
|
437
|
+
synthetic because their original character is unavailable.
|
|
438
|
+
|
|
439
|
+
`toPlaywright(text, { url })` exports a Playwright spec with a controlled clock,
|
|
440
|
+
viewport, stable `data-link-id` selectors, pointer/key/wheel/text/focus inputs,
|
|
441
|
+
property assertions and named `test.step` markers. DOM properties such as labels
|
|
442
|
+
and values are asserted directly. For store-only properties such as `pressed`, the page
|
|
443
|
+
exposes `window.uiRecordingState(id, name)` returning the property's raw values
|
|
444
|
+
(the animation example demonstrates the hook). The exported test includes no
|
|
445
|
+
runtime recorder dependency. Redacted text remains `***`; it cannot reconstruct
|
|
446
|
+
secrets. No rrweb code or dependency ships in this package.
|
|
447
|
+
|
|
448
|
+
Run the example at `/examples/animation/`: Record, interact with OK, Stop, then
|
|
449
|
+
Replay or move the labelled time scrubber. The `<pre>` shows the sharable LiNo.
|
|
450
|
+
|
|
451
|
+
## Background layers
|
|
452
|
+
|
|
453
|
+
Independent decorative canvas, WebGL and CSS entry points are documented in
|
|
454
|
+
[backgrounds](src/backgrounds/README.md), with a runnable all-layer example,
|
|
455
|
+
original nebula preset, host glyph hooks and reduced-motion/CSS fallbacks.
|
package/package.json
CHANGED
|
@@ -1,6 +1,79 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@link-foundation/ui-animation",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Animations of the associative UI framework written in Links Notation: a declarative model of keyframe tracks, easings, springs, timelines and state triggers, a pure seeded sampler, safety validators and a WAAPI player",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"exports": {
|
|
7
|
+
".": {
|
|
8
|
+
"types": "./src/index.d.ts",
|
|
9
|
+
"default": "./src/index.js"
|
|
10
|
+
},
|
|
11
|
+
"./backgrounds/starfield": {
|
|
12
|
+
"types": "./src/backgrounds/starfield.d.ts",
|
|
13
|
+
"default": "./src/backgrounds/starfield.js"
|
|
14
|
+
},
|
|
15
|
+
"./backgrounds/shader": {
|
|
16
|
+
"types": "./src/backgrounds/shader.d.ts",
|
|
17
|
+
"default": "./src/backgrounds/shader.js"
|
|
18
|
+
},
|
|
19
|
+
"./backgrounds/nebula": {
|
|
20
|
+
"types": "./src/backgrounds/nebula.d.ts",
|
|
21
|
+
"default": "./src/backgrounds/nebula.js"
|
|
22
|
+
},
|
|
23
|
+
"./backgrounds/beams": {
|
|
24
|
+
"types": "./src/backgrounds/beams.d.ts",
|
|
25
|
+
"default": "./src/backgrounds/beams.js"
|
|
26
|
+
},
|
|
27
|
+
"./backgrounds/rain": {
|
|
28
|
+
"types": "./src/backgrounds/rain.d.ts",
|
|
29
|
+
"default": "./src/backgrounds/rain.js"
|
|
30
|
+
},
|
|
31
|
+
"./backgrounds/grid": {
|
|
32
|
+
"types": "./src/backgrounds/grid.d.ts",
|
|
33
|
+
"default": "./src/backgrounds/grid.js"
|
|
34
|
+
}
|
|
35
|
+
},
|
|
36
|
+
"types": "./src/index.d.ts",
|
|
37
|
+
"files": [
|
|
38
|
+
"src/",
|
|
39
|
+
"README.md",
|
|
40
|
+
"LICENSE"
|
|
41
|
+
],
|
|
42
|
+
"keywords": [
|
|
43
|
+
"ui",
|
|
44
|
+
"links-notation",
|
|
45
|
+
"animation",
|
|
46
|
+
"waapi",
|
|
47
|
+
"easing",
|
|
48
|
+
"spring",
|
|
49
|
+
"timeline",
|
|
50
|
+
"reduced-motion"
|
|
51
|
+
],
|
|
52
|
+
"license": "Unlicense",
|
|
53
|
+
"repository": {
|
|
54
|
+
"type": "git",
|
|
55
|
+
"url": "git+https://github.com/link-foundation/ui.git",
|
|
56
|
+
"directory": "packages/ui-animation"
|
|
57
|
+
},
|
|
58
|
+
"homepage": "https://github.com/link-foundation/ui/tree/main/packages/ui-animation#readme",
|
|
59
|
+
"bugs": {
|
|
60
|
+
"url": "https://github.com/link-foundation/ui/issues"
|
|
61
|
+
},
|
|
62
|
+
"engines": {
|
|
63
|
+
"node": ">=20"
|
|
64
|
+
},
|
|
65
|
+
"dependencies": {
|
|
66
|
+
"@link-foundation/ui-core": "^0.1.0",
|
|
67
|
+
"@link-foundation/ui-store": "^0.1.0",
|
|
68
|
+
"@link-foundation/ui-themes": "^0.1.0"
|
|
69
|
+
},
|
|
70
|
+
"devDependencies": {
|
|
71
|
+
"@link-foundation/ui-tokens": "^0.1.0",
|
|
72
|
+
"esbuild": "0.27.0",
|
|
73
|
+
"jsdom": "^30.1.3",
|
|
74
|
+
"test-anywhere": "^0.8.48"
|
|
75
|
+
},
|
|
76
|
+
"publishConfig": {
|
|
77
|
+
"access": "public"
|
|
78
|
+
}
|
|
79
|
+
}
|