@link-foundation/ui-animation 0.0.0-stage → 0.0.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/easing.js ADDED
@@ -0,0 +1,327 @@
1
+ /**
2
+ * Easing functions: `cubicBezier`, `steps`, a closed-form `spring` and
3
+ * `toCssLinear`, plus the named easings and the conversion of a model easing
4
+ * (`{ type: 'cubic-bezier', points }`, ...) into a function or CSS text.
5
+ *
6
+ * An easing function maps progress 0..1 to eased progress; it is pure.
7
+ */
8
+
9
+ import { unwrapToken } from './tokens.js';
10
+
11
+ /** Cubic-bezier points of the named easings (ui-core / Material 3 names). */
12
+ export const NAMED_EASINGS = Object.freeze({
13
+ linear: [0, 0, 1, 1],
14
+ ease: [0.25, 0.1, 0.25, 1],
15
+ 'ease-in': [0.42, 0, 1, 1],
16
+ 'ease-out': [0, 0, 0.58, 1],
17
+ 'ease-in-out': [0.42, 0, 0.58, 1],
18
+ standard: [0.2, 0, 0, 1],
19
+ emphasized: [0.2, 0, 0, 1],
20
+ decelerate: [0, 0, 0, 1],
21
+ accelerate: [0.3, 0, 1, 1],
22
+ });
23
+
24
+ /** Named step easings (CSS `step-start`, `step-end`, and `hold`). */
25
+ const NAMED_STEPS = Object.freeze({
26
+ 'step-start': { count: 1, position: 'start' },
27
+ 'step-end': { count: 1, position: 'end' },
28
+ hold: { count: 1, position: 'end' },
29
+ });
30
+
31
+ /** Whether `name` is a built-in easing name. */
32
+ export const isEasingName = (name) =>
33
+ Object.hasOwn(NAMED_EASINGS, name) || Object.hasOwn(NAMED_STEPS, name);
34
+
35
+ export const linear = (t) => t;
36
+
37
+ /**
38
+ * The CSS `cubic-bezier(x1, y1, x2, y2)` timing function. `x1` and `x2` must
39
+ * be in 0..1 (as in CSS); `y` may overshoot.
40
+ * @returns {(t: number) => number}
41
+ */
42
+ export function cubicBezier(x1, y1, x2, y2) {
43
+ for (const x of [x1, x2]) {
44
+ if (!(x >= 0 && x <= 1)) {
45
+ throw new RangeError('cubic-bezier x1 and x2 must be in 0..1');
46
+ }
47
+ }
48
+ if (x1 === y1 && x2 === y2) {
49
+ return linear;
50
+ }
51
+ const cx = 3 * x1;
52
+ const bx = 3 * (x2 - x1) - cx;
53
+ const ax = 1 - cx - bx;
54
+ const cy = 3 * y1;
55
+ const by = 3 * (y2 - y1) - cy;
56
+ const ay = 1 - cy - by;
57
+ const curveX = (s) => ((ax * s + bx) * s + cx) * s;
58
+ const curveY = (s) => ((ay * s + by) * s + cy) * s;
59
+ const slopeX = (s) => (3 * ax * s + 2 * bx) * s + cx;
60
+
61
+ /** The curve parameter `s` whose x is `x` (Newton, then bisection). */
62
+ function solve(x) {
63
+ let s = x;
64
+ for (let i = 0; i < 8; i++) {
65
+ const error = curveX(s) - x;
66
+ if (Math.abs(error) < 1e-7) {
67
+ return s;
68
+ }
69
+ const slope = slopeX(s);
70
+ if (Math.abs(slope) < 1e-6) {
71
+ break;
72
+ }
73
+ s -= error / slope;
74
+ }
75
+ let low = 0;
76
+ let high = 1;
77
+ s = x;
78
+ for (let i = 0; i < 64 && high - low > 1e-9; i++) {
79
+ if (curveX(s) < x) {
80
+ low = s;
81
+ } else {
82
+ high = s;
83
+ }
84
+ s = (low + high) / 2;
85
+ }
86
+ return s;
87
+ }
88
+
89
+ return (t) => {
90
+ if (t <= 0) {
91
+ return t < 0 && x1 > 0 ? (y1 / x1) * t : 0;
92
+ }
93
+ if (t >= 1) {
94
+ return 1;
95
+ }
96
+ return curveY(solve(t));
97
+ };
98
+ }
99
+
100
+ /**
101
+ * The CSS `steps(n, position)` timing function.
102
+ * @param {number} n the number of steps, a positive integer
103
+ * @param {'start'|'end'|'both'|'none'} [position] `jump-start`, `jump-end`
104
+ * (the default), `jump-both` or `jump-none`
105
+ * @returns {(t: number) => number}
106
+ */
107
+ export function steps(n, position = 'end') {
108
+ if (!Number.isInteger(n) || n < 1 || (position === 'none' && n < 2)) {
109
+ throw new RangeError('steps needs a positive integer count');
110
+ }
111
+ const jumps = { start: n, end: n, both: n + 1, none: n - 1 }[position];
112
+ if (jumps === undefined) {
113
+ throw new RangeError(`unknown steps position "${position}"`);
114
+ }
115
+ const startsHigh = position === 'start' || position === 'both';
116
+ return (t) => {
117
+ if (t >= 1) {
118
+ return 1;
119
+ }
120
+ if (t < 0) {
121
+ return 0;
122
+ }
123
+ const step = Math.floor(t * n) + (startsHigh ? 1 : 0);
124
+ return Math.min(step, jumps) / jumps;
125
+ };
126
+ }
127
+
128
+ /** A spring is settled when it stays within this distance of its target. */
129
+ export const SPRING_TOLERANCE = 0.0005;
130
+
131
+ /**
132
+ * A damped spring from 0 to 1, solved in closed form (no simulation): the
133
+ * displacement of a mass on a spring released at rest.
134
+ *
135
+ * Time is in milliseconds; the physics uses seconds (stiffness in N/m,
136
+ * damping in N·s/m, mass in kg).
137
+ * - underdamped (ζ < 1): `1 - e^(-ζωt) (cos ω_d t + ζω/ω_d sin ω_d t)`
138
+ * - critically damped (ζ = 1): `1 - e^(-ωt) (1 + ωt)`
139
+ * - overdamped (ζ > 1): `1 - (r2 e^(r1 t) - r1 e^(r2 t)) / (r2 - r1)`
140
+ *
141
+ * `settleTime` is the first time (ms, rounded up) after which the spring
142
+ * stays within {@link SPRING_TOLERANCE} (0.05%) of 1; it is `Infinity`
143
+ * without damping.
144
+ * @param {{ stiffness?: number, damping?: number, mass?: number }} [options]
145
+ * @returns {{ at: (tMs: number) => number, settleTime: number }}
146
+ */
147
+ export function spring({ stiffness = 100, damping = 10, mass = 1 } = {}) {
148
+ if (!(stiffness > 0) || !(mass > 0) || !(damping >= 0)) {
149
+ throw new RangeError(
150
+ 'spring needs stiffness > 0, mass > 0 and damping >= 0'
151
+ );
152
+ }
153
+ const omega = Math.sqrt(stiffness / mass);
154
+ const zeta = damping / (2 * Math.sqrt(stiffness * mass));
155
+ const displacement = springDisplacement(omega, zeta);
156
+ const at = (tMs) => (tMs <= 0 ? 0 : displacement(tMs / 1000));
157
+ return { at, settleTime: springSettleTime(omega, zeta, displacement) };
158
+ }
159
+
160
+ function springDisplacement(omega, zeta) {
161
+ if (zeta < 1) {
162
+ const decay = zeta * omega;
163
+ const omegaD = omega * Math.sqrt(1 - zeta * zeta);
164
+ return (t) =>
165
+ 1 -
166
+ Math.exp(-decay * t) *
167
+ (Math.cos(omegaD * t) + (decay / omegaD) * Math.sin(omegaD * t));
168
+ }
169
+ if (zeta === 1) {
170
+ return (t) => 1 - Math.exp(-omega * t) * (1 + omega * t);
171
+ }
172
+ const root = Math.sqrt(zeta * zeta - 1);
173
+ const r1 = -omega * (zeta - root);
174
+ const r2 = -omega * (zeta + root);
175
+ return (t) => 1 - (r2 * Math.exp(r1 * t) - r1 * Math.exp(r2 * t)) / (r2 - r1);
176
+ }
177
+
178
+ function springSettleTime(omega, zeta, displacement) {
179
+ if (zeta === 0) {
180
+ return Infinity;
181
+ }
182
+ if (zeta < 1) {
183
+ // |1 - x(t)| <= e^(-ζωt) / sqrt(1 - ζ²): the envelope bounds the error.
184
+ const amplitude = 1 / Math.sqrt(1 - zeta * zeta);
185
+ const seconds = Math.log(amplitude / SPRING_TOLERANCE) / (zeta * omega);
186
+ return Math.ceil(Math.max(0, seconds) * 1000);
187
+ }
188
+ // Critically damped and overdamped springs approach 1 monotonically.
189
+ const settled = (seconds) => 1 - displacement(seconds) <= SPRING_TOLERANCE;
190
+ let high = 1 / omega;
191
+ while (!settled(high)) {
192
+ high *= 2;
193
+ }
194
+ let low = 0;
195
+ for (let i = 0; i < 60; i++) {
196
+ const middle = (low + high) / 2;
197
+ if (settled(middle)) {
198
+ high = middle;
199
+ } else {
200
+ low = middle;
201
+ }
202
+ }
203
+ return Math.ceil(high * 1000);
204
+ }
205
+
206
+ /**
207
+ * A spring as an easing over its settle time: progress `x` is the time
208
+ * `x * settleTime`, and the end (x >= 1) is exactly 1.
209
+ * @param {{ at: (tMs: number) => number, settleTime: number }} s
210
+ * @returns {(x: number) => number}
211
+ */
212
+ export function springEasing(s) {
213
+ const span = Number.isFinite(s.settleTime) ? s.settleTime : 1000;
214
+ return (x) => (x >= 1 ? 1 : s.at(x * span));
215
+ }
216
+
217
+ /** A number as short CSS text (at most 4 decimals, no trailing zeros). */
218
+ export function cssNumber(n) {
219
+ const rounded = Math.round(n * 10000) / 10000;
220
+ return String(Object.is(rounded, -0) ? 0 : rounded);
221
+ }
222
+
223
+ /**
224
+ * The CSS `linear()` easing that follows `fn`: `samples + 1` evenly spaced
225
+ * points from progress 0 to 1, `linear(0, 0.0123, ..., 1)`.
226
+ * @param {(t: number) => number} fn
227
+ * @param {number} [samples]
228
+ * @returns {string}
229
+ */
230
+ export function toCssLinear(fn, samples = 40) {
231
+ if (!Number.isInteger(samples) || samples < 1) {
232
+ throw new RangeError('toCssLinear needs a positive integer sample count');
233
+ }
234
+ const points = [];
235
+ for (let i = 0; i <= samples; i++) {
236
+ points.push(cssNumber(fn(i / samples)));
237
+ }
238
+ return `linear(${points.join(', ')})`;
239
+ }
240
+
241
+ /**
242
+ * The easing of a named token: `resolveToken('motion.easing.NAME')` when it
243
+ * gives a cubic-bezier, else the built-in table.
244
+ * @returns {import('./types.js').Easing|null}
245
+ */
246
+ export function resolveNamedEasing(name, resolveToken) {
247
+ const token = resolveToken?.(`motion.easing.${name}`);
248
+ const points = tokenBezier(token);
249
+ if (points) {
250
+ return { type: 'cubic-bezier', points };
251
+ }
252
+ if (Object.hasOwn(NAMED_EASINGS, name)) {
253
+ return { type: 'cubic-bezier', points: [...NAMED_EASINGS[name]] };
254
+ }
255
+ if (Object.hasOwn(NAMED_STEPS, name)) {
256
+ return { type: 'steps', ...NAMED_STEPS[name] };
257
+ }
258
+ return null;
259
+ }
260
+
261
+ /** The points of a cubic-bezier token (typed or raw), or `null`. */
262
+ function tokenBezier(token) {
263
+ const typed = unwrapToken(token);
264
+ const value = typed?.type === 'cubicBezier' ? typed.value : typed;
265
+ return Array.isArray(value) &&
266
+ value.length === 4 &&
267
+ value.every((n) => typeof n === 'number')
268
+ ? value
269
+ : null;
270
+ }
271
+
272
+ /**
273
+ * A model easing as a function of progress 0..1.
274
+ * @param {import('./types.js').Easing|null|undefined} easing
275
+ * @param {(path: string) => unknown} [resolveToken]
276
+ * @returns {(t: number) => number}
277
+ */
278
+ export function easingFunction(easing, resolveToken) {
279
+ switch (easing?.type) {
280
+ case undefined:
281
+ case 'linear':
282
+ return linear;
283
+ case 'named': {
284
+ const named = resolveNamedEasing(easing.name, resolveToken);
285
+ return named ? easingFunction(named) : linear;
286
+ }
287
+ case 'cubic-bezier':
288
+ return cubicBezier(...easing.points);
289
+ case 'steps':
290
+ return steps(easing.count, easing.position);
291
+ case 'spring':
292
+ return springEasing(spring(easing));
293
+ default:
294
+ return linear;
295
+ }
296
+ }
297
+
298
+ /**
299
+ * A model easing as CSS text for WAAPI: `linear`, `cubic-bezier(a, b, c, d)`,
300
+ * `steps(n, jump-end)` or (springs) `linear(...)`.
301
+ * @param {import('./types.js').Easing|null|undefined} easing
302
+ * @param {(path: string) => unknown} [resolveToken]
303
+ * @returns {string}
304
+ */
305
+ export function easingCss(easing, resolveToken) {
306
+ switch (easing?.type) {
307
+ case undefined:
308
+ case 'linear':
309
+ return 'linear';
310
+ case 'named': {
311
+ const named = resolveNamedEasing(easing.name, resolveToken);
312
+ return named ? easingCss(named) : 'linear';
313
+ }
314
+ case 'cubic-bezier': {
315
+ const [a, b, c, d] = easing.points;
316
+ return a === b && c === d
317
+ ? 'linear'
318
+ : `cubic-bezier(${easing.points.join(', ')})`;
319
+ }
320
+ case 'steps':
321
+ return `steps(${easing.count}, jump-${easing.position ?? 'end'})`;
322
+ case 'spring':
323
+ return toCssLinear(springEasing(spring(easing)));
324
+ default:
325
+ return 'linear';
326
+ }
327
+ }
@@ -0,0 +1,83 @@
1
+ /**
2
+ * The built-in `decipher` text effect: every non-space character starts as a
3
+ * random glyph and is revealed, in a random order, as progress goes 0 -> 1.
4
+ *
5
+ * Ported from immortality `app/src/textEffects.ts` (Unlicense):
6
+ * https://github.com/konard/immortality/blob/main/app/src/textEffects.ts
7
+ * whose algorithm follows Arwes `animateTextDecipher` (MIT). The port
8
+ * replaces the platform random generator with {@link seededRandom}: the
9
+ * reveal order depends only on the seed, and the glyphs of a frame only on
10
+ * the seed and the progress, so the same sample is always the same text.
11
+ */
12
+
13
+ import { mix, seedNumber, seededRandom } from '../random.js';
14
+
15
+ export const DECIPHER_CHARACTERS =
16
+ ' ----____abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
17
+
18
+ /** Whitespace is kept as it is (no regular expression needed). */
19
+ const isWhitespace = (c) => c.trim() === '';
20
+
21
+ /**
22
+ * The order in which character positions are revealed (a Fisher–Yates
23
+ * shuffle of the non-whitespace positions).
24
+ * @param {string} text
25
+ * @param {() => number} random
26
+ * @returns {number[]}
27
+ */
28
+ export function revealOrder(text, random) {
29
+ const indexes = [];
30
+ for (let i = 0; i < text.length; i++) {
31
+ if (!isWhitespace(text[i])) {
32
+ indexes.push(i);
33
+ }
34
+ }
35
+ for (let i = indexes.length - 1; i > 0; i--) {
36
+ const j = Math.floor(random() * (i + 1));
37
+ [indexes[i], indexes[j]] = [indexes[j], indexes[i]];
38
+ }
39
+ return indexes;
40
+ }
41
+
42
+ /**
43
+ * The text at `progress` (0..1): revealed positions show the real
44
+ * character, the others a random glyph; whitespace is kept.
45
+ * @param {string} text
46
+ * @param {number} progress
47
+ * @param {readonly number[]} order
48
+ * @param {() => number} random
49
+ * @returns {string}
50
+ */
51
+ export function decipherFrame(text, progress, order, random) {
52
+ if (progress >= 1) {
53
+ return text;
54
+ }
55
+ const count = Math.floor(Math.max(0, progress) * order.length);
56
+ const revealed = new Set(order.slice(0, count));
57
+ let out = '';
58
+ for (let i = 0; i < text.length; i++) {
59
+ const c = text[i];
60
+ out +=
61
+ isWhitespace(c) || revealed.has(i)
62
+ ? c
63
+ : DECIPHER_CHARACTERS[
64
+ Math.floor(random() * DECIPHER_CHARACTERS.length)
65
+ ];
66
+ }
67
+ return out;
68
+ }
69
+
70
+ /**
71
+ * The `decipher` effect: `(effect decipher (seed 42))`.
72
+ * @param {string} input the final text
73
+ * @param {number} progress 0..1
74
+ * @param {number|string} seed
75
+ * @returns {string}
76
+ */
77
+ export function decipher(input, progress, seed) {
78
+ const text = String(input ?? '');
79
+ const base = seedNumber(seed);
80
+ const order = revealOrder(text, seededRandom(base));
81
+ const frame = Math.round(Math.min(1, Math.max(0, progress)) * 1e6);
82
+ return decipherFrame(text, progress, order, seededRandom(mix(base, frame)));
83
+ }
package/src/effects.js ADDED
@@ -0,0 +1,44 @@
1
+ /**
2
+ * The effect registry: effects compute a non-CSS value (such as the text of
3
+ * an element) from progress 0..1, a seed and the effect parameters. The
4
+ * player runs them in its clock-driven frame loop; `sample` runs them too.
5
+ *
6
+ * An effect must be pure: the same input, progress, seed and parameters give
7
+ * the same output. Use `seededRandom(seed)` for randomness.
8
+ */
9
+
10
+ import { decipher } from './effects/decipher.js';
11
+
12
+ /**
13
+ * @typedef {(input: unknown, progress: number, seed: number|string,
14
+ * params: Record<string, number|string>) => unknown} EffectFn
15
+ * @typedef {{ name: string, fn: EffectFn, property: string }} EffectEntry
16
+ */
17
+
18
+ /** @type {Map<string, EffectEntry>} */
19
+ const registry = new Map();
20
+
21
+ /**
22
+ * Register (or replace) an effect.
23
+ * @param {string} name
24
+ * @param {EffectFn} fn
25
+ * @param {{ property?: string }} [options] the element property it drives
26
+ * (default `text`)
27
+ */
28
+ export function registerEffect(name, fn, { property = 'text' } = {}) {
29
+ if (typeof name !== 'string' || name === '' || typeof fn !== 'function') {
30
+ throw new TypeError('registerEffect(name, fn) needs a name and a function');
31
+ }
32
+ registry.set(name, { name, fn, property });
33
+ }
34
+
35
+ /**
36
+ * @param {string} name
37
+ * @returns {EffectEntry|undefined}
38
+ */
39
+ export const getEffect = (name) => registry.get(name);
40
+
41
+ /** The names of the registered effects. */
42
+ export const effectNames = () => [...registry.keys()];
43
+
44
+ registerEffect('decipher', decipher);