Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

test(interaction): curve oracles for animation proofs (#8462)

Cindy Zhang99ad3f6d906e
diff --git a/internal/interaction-harness/README.md b/internal/interaction-harness/README.md
index 0edec528d0..08a393f9e1 100644
--- a/internal/interaction-harness/README.md
+++ b/internal/interaction-harness/README.md
@@ -27,6 +27,7 @@ pnpm test:interaction <spec file> # one spec, both engines
| `scripts.ts` | Touch scripts as data: `tap`, `drag` (hold, rest), `flick` (exact final-move speed, velocity profiles), `holdThenDrag`, `pinch`, `rotate`, `path`, `merge` (a second finger mid-gesture), `releaseVelocity`, `toTouchEvents`. |
| `touch.ts` | `touchDriver(page).play(script)`: the script as real engine input. `installInputLog` / `readInputLog`: what the page received. |
| `story.ts` | `phone`, `withStorybook`, `openStory`, `frames`. |
+| `math.ts` | Oracles independent of the code under test: `cubicBezier`, `timingFunction`, `springStep` (SwiftUI response / dampingFraction, initial velocity), `projectDecay`, `rubberBand`, `parseTransform`, `compareCurve`, `timeline`. |
## Real touch
diff --git a/internal/interaction-harness/package.json b/internal/interaction-harness/package.json
index 08b1d02f61..81fc8e0ead 100644
--- a/internal/interaction-harness/package.json
+++ b/internal/interaction-harness/package.json
@@ -7,6 +7,7 @@
"main": "./src/index.ts",
"exports": {
".": "./src/index.ts",
+ "./math": "./src/math.ts",
"./scripts": "./src/scripts.ts"
},
"scripts": {
diff --git a/internal/interaction-harness/src/index.ts b/internal/interaction-harness/src/index.ts
index 587b9f82d2..6fc3b85340 100644
--- a/internal/interaction-harness/src/index.ts
+++ b/internal/interaction-harness/src/index.ts
@@ -4,14 +4,15 @@
* @file index.ts
* @input Re-exports the harness modules
* @output The `@astryxdesign/interaction-harness` entry point for Playwright
- * specs. The pure touch scripts are also reachable without Playwright
- * through `@astryxdesign/interaction-harness/scripts` (unit tests).
+ * specs. Pure helpers are also reachable without Playwright through
+ * `@astryxdesign/interaction-harness/math` and `/scripts` (unit tests).
* @position Imported only from `*.interaction.browser.spec.ts` files (run by
* playwright.interaction.config.ts) and from this package's own tests.
*
* SYNC: When a module is added, export it here and describe it in README.md.
*/
+export * from './math';
export * from './scripts';
export * from './story';
export * from './touch';
diff --git a/internal/interaction-harness/src/math.test.ts b/internal/interaction-harness/src/math.test.ts
new file mode 100644
index 0000000000..8a1e204a56
--- /dev/null
+++ b/internal/interaction-harness/src/math.test.ts
@@ -0,0 +1,176 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {
+ compareCurve,
+ cubicBezier,
+ parseTransform,
+ projectDecay,
+ rubberBand,
+ springStep,
+ timeline,
+ timingFunction,
+ velocityAt,
+} from './math';
+
+describe('cubicBezier', () => {
+ it('matches the CSS keyword curves at known points', () => {
+ const linear = cubicBezier(0, 0, 1, 1);
+ expect(linear(0.3)).toBeCloseTo(0.3, 6);
+ // ease (0.25, 0.1, 0.25, 1) at x = 0.5 is 0.8024 (CSS reference value).
+ expect(cubicBezier(0.25, 0.1, 0.25, 1)(0.5)).toBeCloseTo(0.8024, 3);
+ expect(cubicBezier(0.24, 1, 0.4, 1)(0)).toBe(0);
+ expect(cubicBezier(0.24, 1, 0.4, 1)(1)).toBe(1);
+ });
+ it('parses timing functions', () => {
+ expect(timingFunction('cubic-bezier(0, 0, 1, 1)')(0.25)).toBeCloseTo(
+ 0.25,
+ 6,
+ );
+ expect(timingFunction('ease-out')(0.5)).toBeCloseTo(
+ cubicBezier(0, 0, 0.58, 1)(0.5),
+ 9,
+ );
+ expect(() => timingFunction('steps(4)')).toThrow();
+ });
+});
+
+describe('springStep (SwiftUI response / dampingFraction)', () => {
+ const critical = {response: 0.5, dampingFraction: 1};
+ it('starts at 0 with the given velocity and ends at 1', () => {
+ expect(springStep(critical, 0)).toBe(0);
+ expect(springStep(critical, 3000)).toBeCloseTo(1, 6);
+ const v = 4; // progress units per second
+ const slope = springStep({...critical, initialVelocity: v}, 0.01) / 0.00001;
+ expect(slope).toBeCloseTo(v, 1);
+ });
+ it('matches the closed forms in each regime', () => {
+ const w0 = (2 * Math.PI) / 0.5;
+ const t = 0.12;
+ expect(springStep(critical, t * 1000)).toBeCloseTo(
+ 1 - Math.exp(-w0 * t) * (1 + w0 * t),
+ 9,
+ );
+ const z = 0.5;
+ const wd = w0 * Math.sqrt(1 - z * z);
+ const under =
+ 1 -
+ Math.exp(-z * w0 * t) *
+ (Math.cos(wd * t) + ((z * w0) / wd) * Math.sin(wd * t));
+ expect(
+ springStep({response: 0.5, dampingFraction: z}, t * 1000),
+ ).toBeCloseTo(under, 9);
+ // Over-damped and critical agree as damping approaches 1 from above.
+ expect(
+ springStep({response: 0.5, dampingFraction: 1.000001}, 120),
+ ).toBeCloseTo(springStep(critical, 120), 4);
+ });
+ it('overshoots only when under-damped', () => {
+ const peak = (dampingFraction: number) =>
+ Math.max(
+ ...timeline(2000, 4).map(ms =>
+ springStep({response: 0.4, dampingFraction}, ms),
+ ),
+ );
+ expect(peak(0.6)).toBeGreaterThan(1.05);
+ expect(peak(1)).toBeLessThanOrEqual(1);
+ expect(peak(1.5)).toBeLessThanOrEqual(1);
+ });
+});
+
+describe('UIKit scroll physics', () => {
+ it('projects a release with UIScrollView deceleration', () => {
+ // 1000 pt/s at 0.998/ms coasts 499 pt; at 0.99/ms (fast) 99 pt.
+ expect(projectDecay(1000)).toBeCloseTo(499, 6);
+ expect(projectDecay(1000, 0.99)).toBeCloseTo(99, 6);
+ expect(projectDecay(-500)).toBeCloseTo(-249.5, 6);
+ });
+ it('rubber-bands with c = 0.55', () => {
+ expect(rubberBand(0, 800)).toBeCloseTo(0, 9);
+ expect(rubberBand(100, 800)).toBeCloseTo(
+ (1 - 1 / ((100 * 0.55) / 800 + 1)) * 800,
+ 9,
+ );
+ expect(rubberBand(-100, 800)).toBeCloseTo(-rubberBand(100, 800), 9);
+ expect(rubberBand(1e9, 800)).toBeLessThan(800);
+ });
+});
+
+describe('parseTransform', () => {
+ it('decomposes computed transforms', () => {
+ expect(parseTransform('none')).toEqual({
+ translateX: 0,
+ translateY: 0,
+ scaleX: 1,
+ scaleY: 1,
+ rotate: 0,
+ });
+ expect(parseTransform('matrix(1, 0, 0, 1, 12.5, -40)')).toMatchObject({
+ translateX: 12.5,
+ translateY: -40,
+ scaleX: 1,
+ });
+ const rotated = parseTransform(
+ `matrix(${Math.cos(0.5)}, ${Math.sin(0.5)}, ${-Math.sin(0.5)}, ${Math.cos(0.5)}, 0, 0)`,
+ );
+ expect(rotated.rotate).toBeCloseTo((0.5 * 180) / Math.PI, 6);
+ expect(
+ parseTransform(
+ 'matrix3d(2, 0, 0, 0, 0, 2, 0, 0, 0, 0, 1, 0, 5, 6, 0, 1)',
+ ),
+ ).toMatchObject({translateX: 5, translateY: 6, scaleX: 2, scaleY: 2});
+ expect(() => parseTransform('translateX(4px)')).toThrow();
+ });
+});
+
+describe('velocityAt', () => {
+ it('fits the last window and reports zero for a rest', () => {
+ const samples = timeline(200, 10).map(t => ({t, value: t * 0.5}));
+ expect(velocityAt(samples, 200)).toBeCloseTo(500, 6);
+ expect(velocityAt(samples, 400)).toBe(0);
+ });
+});
+
+describe('compareCurve', () => {
+ it('reports the worst point', () => {
+ const result = compareCurve(
+ [
+ {t: 0, value: 0},
+ {t: 10, value: 1.2},
+ ],
+ t => t / 10,
+ 0.1,
+ );
+ expect(result.pass).toBe(false);
+ expect(result.worst.t).toBe(10);
+ expect(result.maxError).toBeCloseTo(0.2, 9);
+ });
+});
+
+describe('compareCurve with points it cannot compare', () => {
+ it('fails a sample the reference has no value for', () => {
+ const reference = new Map([[0, 0]]);
+ const result = compareCurve(
+ [
+ {t: 0, value: 0},
+ {t: 10, value: 1},
+ ],
+ t => reference.get(t) ?? Number.NaN,
+ 0.1,
+ );
+ expect(result.pass).toBe(false);
+ expect(result.worst.t).toBe(10);
+ expect(result.maxError).toBe(Number.POSITIVE_INFINITY);
+ });
+
+ it('fails a non-finite sampled value', () => {
+ const result = compareCurve([{t: 0, value: Number.NaN}], () => 0, 0.1);
+ expect(result.pass).toBe(false);
+ });
+});
+
+describe('timeline', () => {
+ it('includes both ends', () => {
+ expect(timeline(50, 1000 / 60)).toEqual([0, 16.667, 33.333, 50]);
+ });
+});
diff --git a/internal/interaction-harness/src/math.ts b/internal/interaction-harness/src/math.ts
new file mode 100644
index 0000000000..b86b07a888
--- /dev/null
+++ b/internal/interaction-harness/src/math.ts
@@ -0,0 +1,297 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file math.ts
+ * @input Nothing: pure functions
+ * @output Test oracles for motion: `cubicBezier`, `springStep` (SwiftUI
+ * response / dampingFraction semantics, with initial velocity),
+ * `projectDecay` (UIScrollView deceleration), `rubberBand` (UIKit's
+ * formula), `parseTransform`, `velocityAt`, and curve comparison helpers.
+ * @position Imported by the browser helpers and by the specs that compare a
+ * sampled curve against an expected one. Deliberately independent of the
+ * motion code under test in packages/core: an oracle that shares code with
+ * the implementation cannot catch the implementation's mistakes.
+ *
+ * Units: time in milliseconds, distance in CSS px (= points), velocity in
+ * px/s unless a name says otherwise. Spring progress is unitless (0 -> 1).
+ *
+ * SYNC: Keep ./math.test.ts covering every export.
+ */
+
+/** A CSS `cubic-bezier(x1, y1, x2, y2)` timing function: progress in, eased progress out. */
+export function cubicBezier(
+ x1: number,
+ y1: number,
+ x2: number,
+ y2: number,
+): (progress: number) => number {
+ const cx = 3 * x1;
+ const bx = 3 * (x2 - x1) - cx;
+ const ax = 1 - cx - bx;
+ const cy = 3 * y1;
+ const by = 3 * (y2 - y1) - cy;
+ const ay = 1 - cy - by;
+ const sampleX = (s: number) => ((ax * s + bx) * s + cx) * s;
+ const sampleY = (s: number) => ((ay * s + by) * s + cy) * s;
+ const slopeX = (s: number) => (3 * ax * s + 2 * bx) * s + cx;
+ return progress => {
+ if (progress <= 0) {
+ return 0;
+ }
+ if (progress >= 1) {
+ return 1;
+ }
+ // Newton first (fast, converges for well-behaved curves), bisection as the fallback.
+ let s = progress;
+ for (let i = 0; i < 8; i += 1) {
+ const error = sampleX(s) - progress;
+ if (Math.abs(error) < 1e-7) {
+ return sampleY(s);
+ }
+ const slope = slopeX(s);
+ if (Math.abs(slope) < 1e-6) {
+ break;
+ }
+ s -= error / slope;
+ }
+ let lo = 0;
+ let hi = 1;
+ s = progress;
+ for (let i = 0; i < 64; i += 1) {
+ const x = sampleX(s);
+ if (Math.abs(x - progress) < 1e-7) {
+ break;
+ }
+ if (x < progress) {
+ lo = s;
+ } else {
+ hi = s;
+ }
+ s = (lo + hi) / 2;
+ }
+ return sampleY(s);
+ };
+}
+
+/** Parses `cubic-bezier(a, b, c, d)` or one of the CSS keywords into a timing function. */
+export function timingFunction(css: string): (progress: number) => number {
+ const named: Record<string, [number, number, number, number]> = {
+ ease: [0.25, 0.1, 0.25, 1],
+ 'ease-in': [0.42, 0, 1, 1],
+ 'ease-out': [0, 0, 0.58, 1],
+ 'ease-in-out': [0.42, 0, 0.58, 1],
+ };
+ const value = css.trim();
+ if (value === 'linear') {
+ return progress => Math.min(1, Math.max(0, progress));
+ }
+ const match = /^cubic-bezier\(([^)]+)\)$/.exec(value);
+ const parts = match
+ ? match[1].split(',').map(Number)
+ : (named[value] as number[] | undefined);
+ if (parts == null || parts.length !== 4 || parts.some(Number.isNaN)) {
+ throw new Error(`unsupported timing function: ${css}`);
+ }
+ return cubicBezier(parts[0], parts[1], parts[2], parts[3]);
+}
+
+export interface SpringParameters {
+ /** SwiftUI `response`: the period of the undamped spring, in seconds. */
+ readonly response: number;
+ /** SwiftUI `dampingFraction` (UIKit `dampingRatio`): 1 = critical, < 1 bounces. */
+ readonly dampingFraction: number;
+ /**
+ * Initial velocity in progress units per second, UIKit's `initialVelocity`
+ * convention: release velocity (px/s) divided by the distance to travel (px).
+ */
+ readonly initialVelocity?: number;
+}
+
+/**
+ * Progress (0 -> 1, may overshoot) of a spring released from rest-or-moving at
+ * progress 0 towards 1, after `timeMs`. Mass 1, stiffness (2π/response)²,
+ * damping 4π·dampingFraction/response: SwiftUI's mapping.
+ */
+export function springStep(
+ {response, dampingFraction, initialVelocity = 0}: SpringParameters,
+ timeMs: number,
+): number {
+ if (timeMs <= 0) {
+ return 0;
+ }
+ const t = timeMs / 1000;
+ const w0 = (2 * Math.PI) / response;
+ const z = dampingFraction;
+ // y = x - 1: displacement from the target, y(0) = -1, y'(0) = v0.
+ const v0 = initialVelocity;
+ let y: number;
+ if (Math.abs(z - 1) < 1e-9) {
+ y = Math.exp(-w0 * t) * (-1 + (v0 - w0) * t);
+ } else if (z < 1) {
+ const wd = w0 * Math.sqrt(1 - z * z);
+ const b = (v0 - z * w0) / wd;
+ y = Math.exp(-z * w0 * t) * (-Math.cos(wd * t) + b * Math.sin(wd * t));
+ } else {
+ const root = Math.sqrt(z * z - 1);
+ const r1 = -w0 * (z - root);
+ const r2 = -w0 * (z + root);
+ const c1 = (v0 + r2) / (r1 - r2);
+ const c2 = -1 - c1;
+ y = c1 * Math.exp(r1 * t) + c2 * Math.exp(r2 * t);
+ }
+ return 1 + y;
+}
+
+/**
+ * Where a surface released at `velocity` px/s comes to rest, relative to the
+ * release point, under UIScrollView deceleration (`rate` per millisecond:
+ * 0.998 normal, 0.99 fast). UIKit's own projection formula.
+ */
+export function projectDecay(velocity: number, rate = 0.998): number {
+ return ((velocity / 1000) * rate) / (1 - rate);
+}
+
+/** UIKit's rubber band: `(1 - 1 / (x * c / d + 1)) * d`, c = 0.55. */
+export function rubberBand(
+ offset: number,
+ dimension: number,
+ constant = 0.55,
+): number {
+ const sign = Math.sign(offset);
+ const x = Math.abs(offset);
+ return sign * (1 - 1 / ((x * constant) / dimension + 1)) * dimension;
+}
+
+export interface Transform2D {
+ readonly translateX: number;
+ readonly translateY: number;
+ readonly scaleX: number;
+ readonly scaleY: number;
+ /** Rotation in degrees. */
+ readonly rotate: number;
+}
+
+const IDENTITY: Transform2D = {
+ translateX: 0,
+ translateY: 0,
+ scaleX: 1,
+ scaleY: 1,
+ rotate: 0,
+};
+
+/** Decomposes a computed `transform` (`none`, `matrix(...)`, `matrix3d(...)`) into 2D parts. */
+export function parseTransform(css: string): Transform2D {
+ const value = css.trim();
+ if (value === '' || value === 'none') {
+ return IDENTITY;
+ }
+ const match = /^matrix(3d)?\(([^)]+)\)$/.exec(value);
+ if (match == null) {
+ throw new Error(`not a computed transform: ${css}`);
+ }
+ const n = match[2].split(',').map(Number);
+ const [a, b, c, d, e, f] = match[1]
+ ? [n[0], n[1], n[4], n[5], n[12], n[13]]
+ : n;
+ const scaleX = Math.hypot(a, b);
+ const rotate = (Math.atan2(b, a) * 180) / Math.PI;
+ const scaleY = (a * d - b * c) / (scaleX || 1);
+ return {translateX: e, translateY: f, scaleX, scaleY, rotate};
+}
+
+export interface TimedValue {
+ /** Milliseconds. */
+ readonly t: number;
+ readonly value: number;
+}
+
+/**
+ * Velocity (units/s) at the end of `samples`, by least squares over the last
+ * `windowMs`, the way a release velocity is judged: one slow sample before the
+ * lift must not cancel a throw, and a finger that rested has no velocity.
+ */
+export function velocityAt(
+ samples: readonly TimedValue[],
+ endMs: number,
+ windowMs = 100,
+): number {
+ const recent = samples.filter(s => s.t <= endMs && s.t >= endMs - windowMs);
+ if (recent.length < 2) {
+ return 0;
+ }
+ const meanT = recent.reduce((sum, s) => sum + s.t, 0) / recent.length;
+ const meanV = recent.reduce((sum, s) => sum + s.value, 0) / recent.length;
+ let num = 0;
+ let den = 0;
+ for (const s of recent) {
+ num += (s.t - meanT) * (s.value - meanV);
+ den += (s.t - meanT) ** 2;
+ }
+ return den === 0 ? 0 : (num / den) * 1000;
+}
+
+export interface CurveComparison {
+ readonly pass: boolean;
+ readonly tolerance: number;
+ readonly maxError: number;
+ readonly rmsError: number;
+ readonly worst: {
+ readonly t: number;
+ readonly actual: number;
+ readonly expected: number;
+ };
+ readonly points: readonly {
+ readonly t: number;
+ readonly actual: number;
+ readonly expected: number;
+ }[];
+}
+
+/** Compares sampled values with an expected curve, point by point. */
+export function compareCurve(
+ samples: readonly TimedValue[],
+ expected: (timeMs: number) => number,
+ tolerance: number,
+): CurveComparison {
+ if (samples.length === 0) {
+ throw new Error('compareCurve: no samples');
+ }
+ const points = samples.map(s => ({
+ t: s.t,
+ actual: s.value,
+ expected: expected(s.t),
+ }));
+ // A point that cannot be compared (a missing reference value, an oracle
+ // with a NaN parameter) is a failure, never a pass.
+ const errorOf = (p: (typeof points)[number]) =>
+ Number.isFinite(p.actual) && Number.isFinite(p.expected)
+ ? Math.abs(p.actual - p.expected)
+ : Number.POSITIVE_INFINITY;
+ let worst = points[0];
+ let sumSq = 0;
+ for (const p of points) {
+ const error = errorOf(p);
+ sumSq += error * error;
+ if (error > errorOf(worst)) {
+ worst = p;
+ }
+ }
+ const maxError = errorOf(worst);
+ return {
+ pass: maxError <= tolerance,
+ tolerance,
+ maxError,
+ rmsError: Math.sqrt(sumSq / points.length),
+ worst,
+ points,
+ };
+}
+
+/** `from`, `from + step`, … up to and including `to` (within float error). */
+export function timeline(to: number, step = 1000 / 60, from = 0): number[] {
+ const out: number[] = [];
+ for (let i = 0; from + i * step <= to + 1e-6; i += 1) {
+ out.push(+(from + i * step).toFixed(3));
+ }
+ return out;
+}