@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/values.js ADDED
@@ -0,0 +1,331 @@
1
+ /**
2
+ * Animated values: reading the value of a key, resolving token references,
3
+ * interpolating two values and writing a value as CSS text.
4
+ *
5
+ * - numbers (`0.96`) interpolate linearly and are output as numbers;
6
+ * - colours (`'#FF0000'`, `(oklch ...)`, `(rgb ...)`) interpolate in OKLCH
7
+ * along the shorter hue arc and are output as CSS text;
8
+ * - any other text (`'0 8px'`, `'inset(0 0 100% 0)'`) is scanned into a
9
+ * skeleton of text and quantities; two texts with the same skeleton
10
+ * interpolate quantity by quantity (a bare `0` takes the unit of the other
11
+ * side), any other pair switches discretely at progress 0.5, as CSS does.
12
+ *
13
+ * Text is scanned character by character; no regular expressions.
14
+ */
15
+
16
+ import { values as coreValues } from '@link-foundation/ui-core';
17
+ import { cssNumber } from './easing.js';
18
+ import { unwrapToken } from './tokens.js';
19
+
20
+ const { parseColor, parseNumber, colorCss, oklchToSrgb, srgbToOklch } =
21
+ coreValues;
22
+
23
+ /**
24
+ * @typedef {{ type: 'number', value: number }
25
+ * | { type: 'color', color: import('@link-foundation/ui-core').values.Color }
26
+ * | { type: 'text', parts: (string | { value: number, unit: string })[] }
27
+ * | { type: 'token', path: string }} AnimValue
28
+ */
29
+
30
+ const isDigit = (c) => c >= '0' && c <= '9';
31
+ const isLetter = (c) =>
32
+ (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z') || c === '_';
33
+ const isUnitChar = (c) => isLetter(c) || c === '%';
34
+
35
+ /** Whether a number starts at `i` of `text`. */
36
+ function numberStarts(text, i) {
37
+ const previous = text[i - 1];
38
+ if (previous !== undefined && (isLetter(previous) || isDigit(previous))) {
39
+ return false;
40
+ }
41
+ let j = i;
42
+ if (text[j] === '-' || text[j] === '+') {
43
+ j++;
44
+ }
45
+ if (text[j] === '.') {
46
+ j++;
47
+ }
48
+ return isDigit(text[j] ?? '');
49
+ }
50
+
51
+ /** The end index of the number that starts at `i`. */
52
+ function numberEnd(text, i) {
53
+ let j = i;
54
+ if (text[j] === '-' || text[j] === '+') {
55
+ j++;
56
+ }
57
+ while (isDigit(text[j] ?? '')) {
58
+ j++;
59
+ }
60
+ if (text[j] === '.') {
61
+ j++;
62
+ while (isDigit(text[j] ?? '')) {
63
+ j++;
64
+ }
65
+ }
66
+ return j;
67
+ }
68
+
69
+ /**
70
+ * Scan CSS-like text into text parts and quantities:
71
+ * `'inset(0 0 100% 0)'` -> `['inset(', {0,''}, ' ', ..., {100,'%'}, ...]`.
72
+ * @param {string} text
73
+ */
74
+ export function scanText(text) {
75
+ const parts = [];
76
+ let literal = '';
77
+ let i = 0;
78
+ while (i < text.length) {
79
+ if (!numberStarts(text, i)) {
80
+ literal += text[i];
81
+ i++;
82
+ continue;
83
+ }
84
+ const end = numberEnd(text, i);
85
+ let unitEnd = end;
86
+ while (unitEnd < text.length && isUnitChar(text[unitEnd])) {
87
+ unitEnd++;
88
+ }
89
+ parts.push(literal);
90
+ literal = '';
91
+ parts.push({
92
+ value: Number(text.slice(i, end)),
93
+ unit: text.slice(end, unitEnd),
94
+ });
95
+ i = unitEnd;
96
+ }
97
+ parts.push(literal);
98
+ return parts;
99
+ }
100
+
101
+ /**
102
+ * Read the raw value of a key (as the ui-core projection gives it).
103
+ * @param {import('@link-foundation/ui-core').RawValue} raw
104
+ * @returns {AnimValue|null} `null` when it is not a value
105
+ */
106
+ export function readValue(raw) {
107
+ if (typeof raw === 'string') {
108
+ const n = parseNumber(raw);
109
+ if (n !== null) {
110
+ return { type: 'number', value: n };
111
+ }
112
+ const color = parseColor(raw);
113
+ return color
114
+ ? { type: 'color', color }
115
+ : { type: 'text', parts: scanText(raw) };
116
+ }
117
+ if (Array.isArray(raw)) {
118
+ if (raw[0] === 'token' && raw.length === 2 && typeof raw[1] === 'string') {
119
+ return { type: 'token', path: raw[1] };
120
+ }
121
+ const color = parseColor(raw);
122
+ return color ? { type: 'color', color } : null;
123
+ }
124
+ return null;
125
+ }
126
+
127
+ /** The CSS variable of a token path: `color.primary` -> `--color-primary`. */
128
+ const tokenVariable = (path) => `var(--${path.split('.').join('-')})`;
129
+
130
+ /**
131
+ * A resolved token (a ui-tokens typed value) as an animated value.
132
+ * @returns {AnimValue|null}
133
+ */
134
+ function fromToken(resolved) {
135
+ const token = unwrapToken(resolved);
136
+ if (token === undefined || token === null) {
137
+ return null;
138
+ }
139
+ if (typeof token === 'number') {
140
+ return { type: 'number', value: token };
141
+ }
142
+ if (typeof token === 'string') {
143
+ return readValue(token);
144
+ }
145
+ switch (token.type) {
146
+ case 'color':
147
+ return { type: 'color', color: token };
148
+ case 'number':
149
+ return { type: 'number', value: token.value };
150
+ case 'dimension':
151
+ case 'duration':
152
+ return {
153
+ type: 'text',
154
+ parts: ['', { value: token.value, unit: token.unit }, ''],
155
+ };
156
+ default:
157
+ return typeof token.value === 'string' ? readValue(token.value) : null;
158
+ }
159
+ }
160
+
161
+ /**
162
+ * Resolve a token reference with `resolveToken`; other values are returned
163
+ * as they are, and an unknown token stays a reference (CSS `var(--...)`).
164
+ * @param {AnimValue} value
165
+ * @param {(path: string) => unknown} [resolveToken]
166
+ * @returns {AnimValue}
167
+ */
168
+ export function resolveValue(value, resolveToken) {
169
+ if (value.type !== 'token') {
170
+ return value;
171
+ }
172
+ return fromToken(resolveToken?.(value.path)) ?? value;
173
+ }
174
+
175
+ const lerp = (a, b, p) => a + (b - a) * p;
176
+
177
+ /** The shortest signed hue difference from `a` to `b`, in degrees. */
178
+ function hueDelta(a, b) {
179
+ const d = (((b - a) % 360) + 540) % 360;
180
+ return d - 180;
181
+ }
182
+
183
+ function asOklch(color) {
184
+ return color.space === 'oklch' ? color : srgbToOklch(color);
185
+ }
186
+
187
+ function mixColors(from, to, p) {
188
+ const a = asOklch(from);
189
+ const b = asOklch(to);
190
+ // A grey has no hue: it takes the hue of the other colour.
191
+ const ha = a.c < 1e-4 ? b.h : a.h;
192
+ const hb = b.c < 1e-4 ? ha : b.h;
193
+ const h = (((ha + hueDelta(ha, hb) * p) % 360) + 360) % 360;
194
+ return {
195
+ type: 'color',
196
+ space: 'oklch',
197
+ l: lerp(a.l, b.l, p),
198
+ c: lerp(a.c, b.c, p),
199
+ h,
200
+ a: lerp(a.a, b.a, p),
201
+ };
202
+ }
203
+
204
+ const quantity = (part) => typeof part === 'object';
205
+
206
+ /** Whether two scanned texts can interpolate quantity by quantity. */
207
+ function sameSkeleton(a, b) {
208
+ if (a.length !== b.length) {
209
+ return false;
210
+ }
211
+ return a.every((part, i) => {
212
+ const other = b[i];
213
+ if (!quantity(part) || !quantity(other)) {
214
+ return part === other;
215
+ }
216
+ return (
217
+ part.unit === other.unit ||
218
+ (part.unit === '' && part.value === 0) ||
219
+ (other.unit === '' && other.value === 0)
220
+ );
221
+ });
222
+ }
223
+
224
+ function mixTexts(a, b, p) {
225
+ return a.map((part, i) => {
226
+ if (!quantity(part)) {
227
+ return part;
228
+ }
229
+ const other = b[i];
230
+ return {
231
+ value: lerp(part.value, other.value, p),
232
+ unit: part.unit || other.unit,
233
+ };
234
+ });
235
+ }
236
+
237
+ /**
238
+ * Interpolate two resolved values at progress `p` (eased, may overshoot).
239
+ * @param {AnimValue} from
240
+ * @param {AnimValue} to
241
+ * @param {number} p
242
+ * @returns {AnimValue}
243
+ */
244
+ export function interpolate(from, to, p) {
245
+ if (from.type === 'number' && to.type === 'number') {
246
+ return { type: 'number', value: lerp(from.value, to.value, p) };
247
+ }
248
+ if (from.type === 'color' && to.type === 'color') {
249
+ return { type: 'color', color: mixColors(from.color, to.color, p) };
250
+ }
251
+ if (from.type === 'number' && to.type === 'text') {
252
+ return interpolate(numberText(from), to, p);
253
+ }
254
+ if (from.type === 'text' && to.type === 'number') {
255
+ return interpolate(from, numberText(to), p);
256
+ }
257
+ if (
258
+ from.type === 'text' &&
259
+ to.type === 'text' &&
260
+ sameSkeleton(from.parts, to.parts)
261
+ ) {
262
+ return { type: 'text', parts: mixTexts(from.parts, to.parts, p) };
263
+ }
264
+ return p < 0.5 ? from : to;
265
+ }
266
+
267
+ const numberText = (n) => ({
268
+ type: 'text',
269
+ parts: ['', { value: n.value, unit: '' }, ''],
270
+ });
271
+
272
+ /**
273
+ * A resolved value as CSS text (`'0.96'`, `'0 8px'`, `'#FF0000'`).
274
+ * @param {AnimValue} value
275
+ * @returns {string}
276
+ */
277
+ export function valueCss(value) {
278
+ switch (value.type) {
279
+ case 'number':
280
+ return cssNumber(value.value);
281
+ case 'color':
282
+ return colorCss(roundColor(value.color));
283
+ case 'token':
284
+ return tokenVariable(value.path);
285
+ default:
286
+ return value.parts
287
+ .map((part) =>
288
+ quantity(part) ? `${cssNumber(part.value)}${part.unit}` : part
289
+ )
290
+ .join('');
291
+ }
292
+ }
293
+
294
+ function roundColor(color) {
295
+ const round = (x) => Math.round(x * 10000) / 10000;
296
+ if (color.space === 'oklch') {
297
+ return {
298
+ ...color,
299
+ l: round(color.l),
300
+ c: round(color.c),
301
+ h: round(color.h),
302
+ a: round(color.a),
303
+ };
304
+ }
305
+ return color;
306
+ }
307
+
308
+ /**
309
+ * A resolved value as the output of `sample`: a number stays a number, any
310
+ * other value is CSS text.
311
+ * @param {AnimValue} value
312
+ * @returns {number|string}
313
+ */
314
+ export function outputValue(value) {
315
+ return value.type === 'number' ? value.value : valueCss(value);
316
+ }
317
+
318
+ /**
319
+ * The WCAG 2 relative luminance of a colour (0 black .. 1 white), with its
320
+ * alpha over black.
321
+ * @param {import('@link-foundation/ui-core').values.Color} color
322
+ */
323
+ export function relativeLuminance(color) {
324
+ const { r, g, b, a } = color.space === 'oklch' ? oklchToSrgb(color) : color;
325
+ const linear = (x) => {
326
+ const c = Math.min(1, Math.max(0, x));
327
+ return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
328
+ };
329
+ const y = 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
330
+ return y * Math.min(1, Math.max(0, a));
331
+ }