@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/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 {};
|
package/src/validate.js
ADDED
|
@@ -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
|
+
}
|