@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.
Files changed (51) hide show
  1. package/LICENSE +24 -0
  2. package/README.md +454 -2
  3. package/package.json +77 -4
  4. package/src/backgrounds/README.md +131 -0
  5. package/src/backgrounds/beams.d.ts +21 -0
  6. package/src/backgrounds/beams.js +140 -0
  7. package/src/backgrounds/common.d.ts +23 -0
  8. package/src/backgrounds/common.js +322 -0
  9. package/src/backgrounds/grid.d.ts +16 -0
  10. package/src/backgrounds/grid.js +122 -0
  11. package/src/backgrounds/nebula.d.ts +9 -0
  12. package/src/backgrounds/nebula.js +57 -0
  13. package/src/backgrounds/rain-cleanup.js +77 -0
  14. package/src/backgrounds/rain.d.ts +33 -0
  15. package/src/backgrounds/rain.js +238 -0
  16. package/src/backgrounds/shader.d.ts +14 -0
  17. package/src/backgrounds/shader.js +151 -0
  18. package/src/backgrounds/sprites.js +72 -0
  19. package/src/backgrounds/starfield.d.ts +38 -0
  20. package/src/backgrounds/starfield.js +168 -0
  21. package/src/clock.js +98 -0
  22. package/src/compile-waapi.js +147 -0
  23. package/src/diagnostics.js +51 -0
  24. package/src/easing.js +327 -0
  25. package/src/effects/decipher.js +83 -0
  26. package/src/effects.js +44 -0
  27. package/src/index.d.ts +581 -0
  28. package/src/index.js +74 -0
  29. package/src/layers.js +88 -0
  30. package/src/model.js +636 -0
  31. package/src/player.js +267 -0
  32. package/src/random.js +62 -0
  33. package/src/recorder/buffer.js +40 -0
  34. package/src/recorder/clock.js +2 -0
  35. package/src/recorder/format.js +125 -0
  36. package/src/recorder/input.js +53 -0
  37. package/src/recorder/recorder.js +183 -0
  38. package/src/recorder/redact.js +43 -0
  39. package/src/recorder/replay.js +115 -0
  40. package/src/recorder/state-at.js +62 -0
  41. package/src/recorder/store.js +92 -0
  42. package/src/recorder/to-playwright.js +113 -0
  43. package/src/recorder/verify.js +49 -0
  44. package/src/run.js +283 -0
  45. package/src/sample.js +160 -0
  46. package/src/timeline.js +115 -0
  47. package/src/timing.js +172 -0
  48. package/src/tokens.js +32 -0
  49. package/src/types.js +130 -0
  50. package/src/validate.js +218 -0
  51. package/src/values.js +331 -0
package/src/timing.js ADDED
@@ -0,0 +1,172 @@
1
+ /**
2
+ * Timing of an animation: resolving token durations, the active duration,
3
+ * the Web Animations timing model (phases, iterations, direction, fill) and
4
+ * the reduced-motion variant.
5
+ */
6
+
7
+ import { easingFunction, spring } from './easing.js';
8
+ import { unwrapToken } from './tokens.js';
9
+
10
+ /** Properties that move, scale or reveal an element (not opacity/colour). */
11
+ export const MOVEMENT_PROPERTIES = Object.freeze([
12
+ 'transform',
13
+ 'translate',
14
+ 'scale',
15
+ 'rotate',
16
+ 'left',
17
+ 'top',
18
+ 'right',
19
+ 'bottom',
20
+ 'inset',
21
+ 'clip-path',
22
+ 'offset-distance',
23
+ 'offset-path',
24
+ 'background-position',
25
+ ]);
26
+
27
+ export const isMovement = (property) => MOVEMENT_PROPERTIES.includes(property);
28
+
29
+ /**
30
+ * A model time in ms: a number, or a `(token PATH)` resolved through
31
+ * `resolveToken` (a ui-tokens duration such as `{ type: 'duration',
32
+ * value: 150, unit: 'ms' }`, or a number of ms).
33
+ * @returns {number|null} `null` when the token is unknown
34
+ */
35
+ export function resolveTime(time, resolveToken) {
36
+ if (typeof time === 'number') {
37
+ return time;
38
+ }
39
+ if (time?.type !== 'token') {
40
+ return null;
41
+ }
42
+ const value = unwrapToken(resolveToken?.(time.path));
43
+ if (typeof value === 'number') {
44
+ return value;
45
+ }
46
+ if (value?.type === 'duration') {
47
+ return value.unit === 's' ? value.value * 1000 : value.value;
48
+ }
49
+ return null;
50
+ }
51
+
52
+ /**
53
+ * The iteration duration of an animation (ms): its `duration`, else the
54
+ * settle time of a spring easing, else 0.
55
+ */
56
+ export function resolveDuration(animation, resolveToken) {
57
+ const declared = resolveTime(animation.duration, resolveToken);
58
+ if (declared !== null) {
59
+ return declared;
60
+ }
61
+ if (animation.easing?.type === 'spring') {
62
+ const { settleTime } = spring(animation.easing);
63
+ return Number.isFinite(settleTime) ? settleTime : 0;
64
+ }
65
+ return 0;
66
+ }
67
+
68
+ /**
69
+ * The resolved timing of an animation.
70
+ * @param {import('./types.js').Animation} animation
71
+ * @param {(path: string) => unknown} [resolveToken]
72
+ */
73
+ export function resolveTiming(animation, resolveToken) {
74
+ const duration = resolveDuration(animation, resolveToken);
75
+ const delay = resolveTime(animation.delay ?? 0, resolveToken) ?? 0;
76
+ const iterations = animation.iterations ?? 1;
77
+ return {
78
+ delay,
79
+ duration,
80
+ iterations,
81
+ direction: animation.direction ?? 'normal',
82
+ fill: animation.fill ?? 'none',
83
+ easing: easingFunction(animation.easing, resolveToken),
84
+ active: duration * iterations,
85
+ };
86
+ }
87
+
88
+ /**
89
+ * The time (ms) from the start of an animation to the end of its active
90
+ * interval: `delay + duration * iterations` (Infinity for infinite).
91
+ */
92
+ export function endTime(animation, resolveToken) {
93
+ const { delay, active } = resolveTiming(animation, resolveToken);
94
+ return delay + active;
95
+ }
96
+
97
+ const isReversed = (direction, iteration) => {
98
+ switch (direction) {
99
+ case 'reverse':
100
+ return true;
101
+ case 'alternate':
102
+ return iteration % 2 === 1;
103
+ case 'alternate-reverse':
104
+ return iteration % 2 === 0;
105
+ default:
106
+ return false;
107
+ }
108
+ };
109
+
110
+ /**
111
+ * Where an animation is at local time `tMs` (the Web Animations timing
112
+ * model): `null` when it has no effect (before or after it without fill),
113
+ * else the iteration, the directed progress and the eased progress.
114
+ * @param {ReturnType<typeof resolveTiming>} timing
115
+ * @param {number} tMs
116
+ * @returns {{ iteration: number, progress: number, eased: number, phase: 'before'|'active'|'after' }|null}
117
+ */
118
+ export function timingAt(timing, tMs) {
119
+ const { delay, duration, iterations, direction, fill, active } = timing;
120
+ const local = tMs - delay;
121
+ let phase = 'active';
122
+ let overall;
123
+ if (local < 0) {
124
+ if (fill !== 'backwards' && fill !== 'both') {
125
+ return null;
126
+ }
127
+ phase = 'before';
128
+ overall = 0;
129
+ } else if (local >= active) {
130
+ if (fill !== 'forwards' && fill !== 'both') {
131
+ return null;
132
+ }
133
+ phase = 'after';
134
+ overall = iterations;
135
+ } else {
136
+ overall = duration > 0 ? local / duration : 0;
137
+ }
138
+ let iteration = Math.floor(overall);
139
+ let progress = overall - iteration;
140
+ if (phase === 'after' && progress === 0 && iterations > 0) {
141
+ iteration -= 1;
142
+ progress = 1;
143
+ }
144
+ const directed = isReversed(direction, iteration) ? 1 - progress : progress;
145
+ return {
146
+ iteration,
147
+ progress: directed,
148
+ eased: timing.easing(directed),
149
+ phase,
150
+ };
151
+ }
152
+
153
+ /**
154
+ * The variant to play under reduced motion: the fields of the
155
+ * `(reduced-motion ...)` block replace the animation's (its tracks, when it
156
+ * has any, replace all tracks); without a block only the opacity tracks
157
+ * stay, with duration 0 and one iteration.
158
+ * @param {import('./types.js').Animation} animation
159
+ * @returns {import('./types.js').Animation}
160
+ */
161
+ export function reducedMotionVariant(animation) {
162
+ const base = { ...animation, reducedMotion: null };
163
+ if (animation.reducedMotion) {
164
+ return { ...base, ...animation.reducedMotion };
165
+ }
166
+ return {
167
+ ...base,
168
+ duration: 0,
169
+ iterations: 1,
170
+ tracks: animation.tracks.filter((t) => t.property === 'opacity'),
171
+ };
172
+ }
package/src/tokens.js ADDED
@@ -0,0 +1,32 @@
1
+ /**
2
+ * Token resolution. ui-animation does not depend on ui-tokens: every
3
+ * function takes a `resolveToken(path)` callback. It may return a ui-tokens
4
+ * typed value (`{ type: 'duration', value: 150, unit: 'ms' }`), a resolved
5
+ * ui-tokens entry (`{ path, type, value }`), a number (ms for durations) or
6
+ * `undefined` when the token is unknown.
7
+ */
8
+
9
+ /**
10
+ * The typed value of what `resolveToken` returned (unwraps a ui-tokens
11
+ * entry).
12
+ * @param {unknown} token
13
+ */
14
+ export function unwrapToken(token) {
15
+ if (
16
+ token !== null &&
17
+ typeof token === 'object' &&
18
+ Object.hasOwn(token, 'path') &&
19
+ Object.hasOwn(token, 'value')
20
+ ) {
21
+ return token.value;
22
+ }
23
+ return token;
24
+ }
25
+
26
+ /**
27
+ * A `resolveToken` callback over the map that ui-tokens `resolveTokens`
28
+ * returns (path -> entry).
29
+ * @param {Map<string, { value: unknown }>} tokens
30
+ * @returns {(path: string) => unknown}
31
+ */
32
+ export const tokenResolver = (tokens) => (path) => tokens.get(path)?.value;
package/src/types.js ADDED
@@ -0,0 +1,130 @@
1
+ /**
2
+ * Shared JSDoc types of `@link-foundation/ui-animation` (the same types are
3
+ * declared for TypeScript in index.d.ts).
4
+ */
5
+
6
+ /**
7
+ * @typedef {import('@link-foundation/ui-core').Diagnostic} Diagnostic
8
+ */
9
+
10
+ /**
11
+ * A time: milliseconds, or a `(token PATH)` resolved by `resolveToken`.
12
+ * @typedef {number | { type: 'token', path: string }} Time
13
+ */
14
+
15
+ /**
16
+ * @typedef {{ type: 'linear' }
17
+ * | { type: 'named', name: string }
18
+ * | { type: 'cubic-bezier', points: number[] }
19
+ * | { type: 'steps', count: number, position: 'start'|'end'|'both'|'none' }
20
+ * | { type: 'spring', stiffness: number, damping: number, mass: number }} Easing
21
+ */
22
+
23
+ /**
24
+ * A key value as written: a number, a colour, a text of quantities
25
+ * (`'0 8px'`) or a token reference.
26
+ * @typedef {{ type: 'number', value: number }
27
+ * | { type: 'color', color: object }
28
+ * | { type: 'text', parts: (string|{ value: number, unit: string })[] }
29
+ * | { type: 'token', path: string }} AnimValue
30
+ */
31
+
32
+ /**
33
+ * @typedef {object} Key
34
+ * @property {number} offset 0..1
35
+ * @property {AnimValue} value
36
+ * @property {Easing|null} easing of the segment that starts at this key; null inherits animation easing
37
+ */
38
+
39
+ /**
40
+ * @typedef {object} Track
41
+ * @property {string} property a CSS property, or `text`, `label`, ...
42
+ * @property {Key[]} keys
43
+ */
44
+
45
+ /**
46
+ * @typedef {object} Animation
47
+ * @property {string} id
48
+ * @property {'animation'} kind
49
+ * @property {string|null} target
50
+ * @property {Time|null} duration
51
+ * @property {Time} delay
52
+ * @property {number} iterations `Infinity` for `infinite`
53
+ * @property {'normal'|'reverse'|'alternate'|'alternate-reverse'} direction
54
+ * @property {'none'|'forwards'|'backwards'|'both'|'auto'} fill
55
+ * @property {'replace'|'add'|'accumulate'} composite
56
+ * @property {Easing|null} easing
57
+ * @property {Track[]} tracks
58
+ * @property {{ name: string, params: Record<string, unknown> }|null} effect
59
+ * @property {boolean} persist
60
+ * @property {'bell'|'sustain'|null} envelope
61
+ * @property {string[]} triggers the states of `(on STATE)`
62
+ * @property {Partial<Animation>|null} reducedMotion
63
+ */
64
+
65
+ /**
66
+ * @typedef {object} AnimationModel
67
+ * @property {Map<string, Animation>} animations
68
+ * @property {Map<string, { id: string, kind: 'timeline', items: object[] }>} timelines
69
+ * @property {{ state: string, element: string, animation: string, target: string|null }[]} triggers
70
+ * @property {Diagnostic[]} diagnostics
71
+ */
72
+
73
+ /**
74
+ * @typedef {object} SampleOptions
75
+ * @property {(path: string) => unknown} [resolveToken]
76
+ * @property {number|string} [seed] the seed of effects without `(seed ...)`
77
+ * @property {string} [input] the text an effect works on
78
+ */
79
+
80
+ /**
81
+ * @typedef {object} Layer
82
+ * @property {Animation} animation
83
+ * @property {number} [start]
84
+ * @property {number|string} [seed]
85
+ * @property {string} [input]
86
+ */
87
+
88
+ /**
89
+ * @typedef {object} ValidateOptions
90
+ * @property {(path: string) => unknown} [resolveToken]
91
+ * @property {Partial<typeof import('./validate.js').FLASH_LIMITS>} [flash]
92
+ */
93
+
94
+ /**
95
+ * @typedef {object} PlayOptions
96
+ * @property {string} [target]
97
+ * @property {number|string} [seed]
98
+ * @property {string} [input]
99
+ */
100
+
101
+ /**
102
+ * Where the player finds elements: a ui-dom render handle (`nodeFor`), a
103
+ * function of an ID, or nothing (`document.getElementById`).
104
+ * @typedef {{ nodeFor: (id: string) => Element|null }
105
+ * | ((id: string) => Element|null) | null | undefined} ElementSource
106
+ */
107
+
108
+ /**
109
+ * @typedef {object} PlayerOptions
110
+ * @property {string|AnimationModel} [animations]
111
+ * @property {object} [clock] `{ now, requestFrame, cancelFrame }`
112
+ * @property {'full'|'reduced'|((element: Element|null) => 'full'|'reduced')} [motion]
113
+ * @property {(element: Element, keyframes: object[], options: object) => Animation} [animate]
114
+ * @property {(path: string) => unknown} [resolveToken]
115
+ * @property {number|string} [seed]
116
+ * @property {(property: string) => boolean} [isCssProperty]
117
+ * @property {(element: Element, property: string, value: unknown) => void} [apply]
118
+ */
119
+
120
+ /**
121
+ * @typedef {object} Player
122
+ * @property {(listener: (event: object) => void) => () => void} subscribe
123
+ * @property {AnimationModel} model
124
+ * @property {(source: string|AnimationModel) => AnimationModel} load
125
+ * @property {(id: string, options?: PlayOptions) => object} play
126
+ * @property {(store: object) => () => void} bindTriggers
127
+ * @property {(id: string) => 'full'|'reduced'} motion
128
+ */
129
+
130
+ export {};
@@ -0,0 +1,218 @@
1
+ /**
2
+ * `validateAnimation(animation)`: the safety rules of an animation.
3
+ *
4
+ * - `persistent-fill` (error): `(fill both)` or `(fill forwards)` on a
5
+ * clip-path, transform, translate, scale or rotate track keeps the final
6
+ * value on the element after the animation ends (immortality issue-7,
7
+ * R19), unless the animation says `(persist true)`.
8
+ * - `flash` (error): WCAG 2.3.1 Three Flashes or Below Threshold. The
9
+ * opacity, background-color and color tracks are sampled at 60 Hz; a flash
10
+ * is a pair of opposing changes of relative luminance of 0.1 or more where
11
+ * the darker side is below 0.8; more than 3 flashes in any one-second
12
+ * window is an error (immortality issue-7, R20).
13
+ * - `missing-reduced-motion` (warning): a movement track that runs for more
14
+ * than 0 ms without a `(reduced-motion ...)` block.
15
+ */
16
+
17
+ import { animationDiagnostic } from './diagnostics.js';
18
+ import { sampleTyped } from './sample.js';
19
+ import { endTime, isMovement, resolveTiming } from './timing.js';
20
+ import { relativeLuminance } from './values.js';
21
+
22
+ /** Tracks whose final value must not persist without `(persist true)`. */
23
+ export const PERSIST_PROPERTIES = Object.freeze([
24
+ 'clip-path',
25
+ 'transform',
26
+ 'translate',
27
+ 'scale',
28
+ 'rotate',
29
+ ]);
30
+
31
+ /** Tracks whose luminance changes are checked for flashes. */
32
+ export const FLASH_PROPERTIES = Object.freeze([
33
+ 'opacity',
34
+ 'background-color',
35
+ 'color',
36
+ ]);
37
+
38
+ /** WCAG 2.3.1 thresholds. */
39
+ export const FLASH_LIMITS = Object.freeze({
40
+ maxFlashes: 3,
41
+ minChange: 0.1,
42
+ darkerBelow: 0.8,
43
+ sampleRate: 60,
44
+ windowMs: 1000,
45
+ });
46
+
47
+ /** How long an infinite animation is sampled for flashes (ms). */
48
+ const INFINITE_SPAN = 3000;
49
+ /** The longest finite span that is sampled (ms), to bound the work. */
50
+ const MAX_SPAN = 60000;
51
+
52
+ function checkFill(animation) {
53
+ if (animation.persist || !['both', 'forwards'].includes(animation.fill)) {
54
+ return [];
55
+ }
56
+ return animation.tracks
57
+ .filter((track) => PERSIST_PROPERTIES.includes(track.property))
58
+ .map((track) =>
59
+ animationDiagnostic('persistent-fill', 'error', {
60
+ element: animation.id,
61
+ track: track.property,
62
+ fill: animation.fill,
63
+ })
64
+ );
65
+ }
66
+
67
+ /** The luminance (0..1) of a sampled flash-track value, or `null`. */
68
+ function luminanceOf(property, value) {
69
+ if (value === undefined) {
70
+ return null;
71
+ }
72
+ if (property === 'opacity') {
73
+ // Opacity is the worst case: a white layer over black.
74
+ return value.type === 'number'
75
+ ? Math.min(1, Math.max(0, value.value))
76
+ : null;
77
+ }
78
+ return value.type === 'color' ? relativeLuminance(value.color) : null;
79
+ }
80
+
81
+ /**
82
+ * The times (ms) of the luminance changes of a series: a change is a swing
83
+ * of at least `minChange` from the last extreme, and counts only when its
84
+ * darker side is below `darkerBelow`.
85
+ * @param {{ t: number, l: number }[]} series
86
+ */
87
+ export function luminanceChanges(series, limits = FLASH_LIMITS) {
88
+ const changes = [];
89
+ if (series.length === 0) {
90
+ return changes;
91
+ }
92
+ let direction = 0;
93
+ let low = series[0].l;
94
+ let high = series[0].l;
95
+ for (const { t, l } of series) {
96
+ if (direction >= 0 && l > high) {
97
+ high = l;
98
+ }
99
+ if (direction <= 0 && l < low) {
100
+ low = l;
101
+ }
102
+ const rose = l - low >= limits.minChange && direction <= 0;
103
+ const fell = high - l >= limits.minChange && direction >= 0;
104
+ if (rose || fell) {
105
+ const darker = rose ? low : l;
106
+ if (darker < limits.darkerBelow) {
107
+ changes.push(t);
108
+ }
109
+ direction = rose ? 1 : -1;
110
+ low = l;
111
+ high = l;
112
+ }
113
+ }
114
+ return changes;
115
+ }
116
+
117
+ /** The most changes in any window of `windowMs`. */
118
+ function maxInWindow(times, windowMs) {
119
+ let most = 0;
120
+ let start = 0;
121
+ for (let end = 0; end < times.length; end++) {
122
+ while (times[end] - times[start] >= windowMs) {
123
+ start++;
124
+ }
125
+ most = Math.max(most, end - start + 1);
126
+ }
127
+ return most;
128
+ }
129
+
130
+ function checkFlashes(animation, options) {
131
+ const limits = { ...FLASH_LIMITS, ...options.flash };
132
+ const tracks = animation.tracks.filter((t) =>
133
+ FLASH_PROPERTIES.includes(t.property)
134
+ );
135
+ if (tracks.length === 0) {
136
+ return [];
137
+ }
138
+ const timing = resolveTiming(animation, options.resolveToken);
139
+ if (!(timing.duration > 0)) {
140
+ return [];
141
+ }
142
+ const end = endTime(animation, options.resolveToken);
143
+ const span = Math.min(
144
+ Number.isFinite(end) ? end : timing.delay + INFINITE_SPAN,
145
+ MAX_SPAN
146
+ );
147
+ const step = 1000 / limits.sampleRate;
148
+ const series = new Map(tracks.map((t) => [t.property, []]));
149
+ for (let i = 0; i * step <= span; i++) {
150
+ const t = i * step;
151
+ const { values } = sampleTyped(animation, t, options);
152
+ for (const [property, points] of series) {
153
+ const l = luminanceOf(property, values.get(property));
154
+ if (l !== null) {
155
+ points.push({ t, l });
156
+ }
157
+ }
158
+ }
159
+ const diagnostics = [];
160
+ for (const [property, points] of series) {
161
+ const changes = luminanceChanges(points, limits);
162
+ const flashes = Math.floor(maxInWindow(changes, limits.windowMs) / 2);
163
+ if (flashes > limits.maxFlashes) {
164
+ diagnostics.push(
165
+ animationDiagnostic('flash', 'error', {
166
+ element: animation.id,
167
+ track: property,
168
+ flashes,
169
+ limit: limits.maxFlashes,
170
+ })
171
+ );
172
+ }
173
+ }
174
+ return diagnostics;
175
+ }
176
+
177
+ function checkReducedMotion(animation, options) {
178
+ if (animation.reducedMotion) {
179
+ return [];
180
+ }
181
+ const moving = animation.tracks.find((t) => isMovement(t.property));
182
+ const { duration } = resolveTiming(animation, options.resolveToken);
183
+ if (!moving || !(duration > 0)) {
184
+ return [];
185
+ }
186
+ return [
187
+ animationDiagnostic('missing-reduced-motion', 'warning', {
188
+ element: animation.id,
189
+ track: moving.property,
190
+ duration,
191
+ }),
192
+ ];
193
+ }
194
+
195
+ /**
196
+ * The safety diagnostics of one animation.
197
+ * @param {import('./types.js').Animation} animation
198
+ * @param {import('./types.js').ValidateOptions} [options]
199
+ * @returns {import('./types.js').Diagnostic[]}
200
+ */
201
+ export function validateAnimation(animation, options = {}) {
202
+ return [
203
+ ...checkFill(animation),
204
+ ...checkFlashes(animation, options),
205
+ ...checkReducedMotion(animation, options),
206
+ ];
207
+ }
208
+
209
+ /**
210
+ * The safety diagnostics of every animation of a model.
211
+ * @param {import('./types.js').AnimationModel} model
212
+ * @param {import('./types.js').ValidateOptions} [options]
213
+ */
214
+ export function validateAnimations(model, options = {}) {
215
+ return [...model.animations.values()].flatMap((a) =>
216
+ validateAnimation(a, options)
217
+ );
218
+ }