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.mdindex 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 touchdiff --git a/internal/interaction-harness/package.json b/internal/interaction-harness/package.jsonindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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;+}