Skip to content

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

TypeScript
12.0 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file wheelPhysics.test.ts
 * @input wheelPhysics.ts and per-frame offsets recorded from a UIPickerView,
 *   with the release velocity UIKit handed its delegate
 * @output Proves the Wheel's curves reproduce UIKit's measured picker. They
 *   cover the projected target, the coast onto the row, the coast into an
 *   end and the snap. They also cover the rubber band, a turn from rest and
 *   the ticks
 * @position Unit coverage for DateInput/wheelPhysics.ts
 *
 * The recordings are of a 216 pt UIPickerView column of 60 rows, 32 pt each.
 * Real HID touches drove it on the iOS 26.2 simulator (iPhone 17 Pro), Oct 23
 * 2026. Offsets are converted to this file's convention (row k centred at k ×
 * 32): UIKit's contentOffset + 129.67. Frames are [ms after the lift, offset].
 */

import {describe, expect, it} from 'vitest';
import {springs} from '../motion/uikit/springs';
import {
  MAX_PLAN_SECONDS,
  bounceCurve,
  coastCurve,
  dragOffset,
  planRelease,
  projectRelease,
  reachesRow,
  snapCurve,
  tickTimes,
  type WheelLayout,
} from './wheelPhysics';

const MINUTES: WheelLayout = {rowHeight: 32, rowCount: 60};

interface Recording {
  /** Offset at the lift. */
  readonly offset: number;
  /** The velocity UIKit handed scrollViewWillEndDragging, px/s. */
  readonly velocity: number;
  /** Its projected target, and the row it snapped that to. */
  readonly targetIn: number;
  readonly targetOut: number;
  /** ms after the lift. */
  readonly didSelect: number;
  readonly frames: ReadonlyArray<readonly [number, number]>;
}

const SWIPE_200_IN_50MS: Recording = {
  offset: 1093.33,
  velocity: 933.4,
  targetIn: 1554.67,
  targetOut: 1568,
  didSelect: 2314,
  frames: [],
};

const SWIPE_200_IN_100MS: Recording = {
  offset: 1143.33,
  velocity: 2114,
  targetIn: 1888,
  targetOut: 1888,
  didSelect: 1220,
  frames: [],
};

const SWIPE_200_IN_200MS: Recording = {
  offset: 1110,
  velocity: 1016.2,
  targetIn: 1612.67,
  targetOut: 1600,
  didSelect: 2316,
  frames: [
    [15, 1126.67],
    [81.4, 1187.67],
    [149.2, 1241],
    [215.6, 1287.67],
    [282.2, 1328],
    [351.3, 1363.33],
    [415, 1394.33],
    [481.6, 1421],
    [550.8, 1444.67],
    [617.3, 1465],
    [681.5, 1482.67],
    [749, 1498.33],
    [815.9, 1512],
    [882.6, 1523.67],
    [949.1, 1534],
    [1015.5, 1543],
    [1084, 1551],
    [1149.7, 1557.67],
    [1214.9, 1563.67],
    [1282.1, 1569],
    [1351.5, 1573.33],
    [1415.2, 1577.33],
    [1481.7, 1581],
    [1549, 1584],
    [1614.7, 1586.33],
    [1684.1, 1588.67],
    [1748.1, 1590.67],
    [1815.2, 1592.33],
    [1883.9, 1594],
    [1948.2, 1595.33],
    [2014.9, 1596.33],
    [2081.6, 1597.33],
    [2149.5, 1598.33],
    [2216.3, 1599],
    [2282.4, 1599.67],
    [2315.2, 1600],
  ],
};

const FLICK_90: Recording = {
  offset: 1014,
  velocity: 543.6,
  targetIn: 1280.67,
  targetOut: 1280,
  didSelect: 2032,
  frames: [
    [19.4, 1023],
    [81.4, 1055.67],
    [151.9, 1084.33],
    [215.5, 1109.33],
    [281.4, 1131.33],
    [352.9, 1150.67],
    [415.1, 1167.33],
    [482, 1182],
    [548.2, 1195],
    [615.9, 1206],
    [682.6, 1216],
    [748.2, 1224.67],
    [816.8, 1232],
    [883.1, 1238.67],
    [949.1, 1244.33],
    [1016, 1249.33],
    [1081.5, 1254],
    [1149.7, 1257.67],
    [1214.8, 1261],
    [1281.9, 1264],
    [1350.8, 1266.67],
    [1415.7, 1269],
    [1483.9, 1271],
    [1548.4, 1272.67],
    [1616.4, 1274],
    [1682.3, 1275.33],
    [1750.6, 1276.67],
    [1815, 1277.67],
    [1882.9, 1278.67],
    [1949.6, 1279.33],
    [2015.2, 1280],
    [2031.5, 1280],
  ],
};

/** A slow drag up, held still 300 ms: no velocity, 6 px past row 31. */
const STILL_6PX_PAST: Recording = {
  offset: 998,
  velocity: 0,
  targetIn: 998,
  targetOut: 992,
  didSelect: 300,
  frames: [
    [16.1, 997],
    [34.2, 996],
    [50.7, 995.33],
    [66.2, 994.67],
    [82.9, 994.33],
    [102.3, 994],
    [116.3, 993.67],
    [133.2, 993.33],
    [152.4, 993.33],
    [166.2, 993],
    [184.1, 993],
    [199.5, 992.67],
    [216.1, 992.67],
    [232.8, 992.67],
    [249.5, 992.33],
    [267.3, 992.33],
    [283, 992],
    [299.7, 992],
  ],
};

/** RMS distance between a curve and recorded frames, in px. */
function rms(
  value: (t: number) => number,
  frames: Recording['frames'],
): number {
  let sum = 0;
  for (const [ms, offset] of frames) {
    sum += (value(ms / 1000) - offset) ** 2;
  }
  return Math.sqrt(sum / frames.length);
}

describe('the projected target', () => {
  it.each([
    ['200 pt in 50 ms', SWIPE_200_IN_50MS],
    ['200 pt in 200 ms', SWIPE_200_IN_200MS],
    ['a 90 pt flick', FLICK_90],
  ])('matches UIKit’s targetContentOffset for %s', (_name, recording) => {
    expect(
      Math.abs(
        projectRelease(recording.offset, recording.velocity) -
          recording.targetIn,
      ),
    ).toBeLessThan(0.3);
  });

  it('snaps to the row UIKit snapped to', () => {
    for (const recording of [SWIPE_200_IN_50MS, SWIPE_200_IN_200MS, FLICK_90]) {
      const plan = planRelease(recording.offset, recording.velocity, MINUTES);
      expect(plan.kind).toBe('coast');
      expect(plan.index * 32).toBe(recording.targetOut);
    }
  });
});

describe('the coast onto a row', () => {
  it.each([
    ['200 pt in 200 ms', SWIPE_200_IN_200MS, 0.8],
    ['a 90 pt flick', FLICK_90, 0.8],
  ])(
    'follows UIKit’s frames for %s and stops on the row',
    (_name, recording, tolerance) => {
      const {curve} = planRelease(
        recording.offset,
        recording.velocity,
        MINUTES,
      );
      expect(rms(curve.value, recording.frames)).toBeLessThan(tolerance);
      expect(curve.value(curve.duration)).toBe(recording.targetOut);
      // didSelect lands in the frame of the last offset change.
      expect(
        Math.abs(curve.duration * 1000 - recording.didSelect),
      ).toBeLessThan(50);
    },
  );

  it('keeps the release velocity at the lift and ends at the stop speed', () => {
    const curve = coastCurve(1110, 1016.2, 1600);
    expect(curve.velocity(0)).toBeCloseTo(1016.2, 6);
    expect(curve.velocity(curve.duration - 1e-9)).toBeCloseTo(8.9, 3);
    expect(curve.velocity(curve.duration)).toBe(0);
  });

  it('is never re-solved backwards: a target behind the velocity snaps', () => {
    const curve = coastCurve(1010, 500, 992);
    expect(curve.value(curve.duration)).toBe(992);
    expect(curve.velocity(0)).toBeLessThan(0);
  });
});

describe('a coast into an end', () => {
  it('decays at the normal rate into the last row, then bounces back to it', () => {
    const plan = planRelease(
      SWIPE_200_IN_100MS.offset,
      SWIPE_200_IN_100MS.velocity,
      MINUTES,
    );
    expect(plan.kind).toBe('edge');
    expect(plan.index).toBe(59);
    const end = 59 * 32;
    // UIKit's frames pass the end about 600 ms after the lift. They overshoot
    // by 20.7 pt around 700 ms and are back on the row by about 1.2 s.
    let hit = 0;
    let peak = end;
    for (let t = 0; t < plan.curve.duration; t += 1 / 240) {
      const value = plan.curve.value(t);
      if (hit === 0 && value >= end) {
        hit = t;
      }
      peak = Math.max(peak, value);
    }
    expect(hit).toBeGreaterThan(0.55);
    expect(hit).toBeLessThan(0.65);
    expect(peak - end).toBeGreaterThan(10);
    expect(peak - end).toBeLessThan(30);
    expect(plan.curve.value(plan.curve.duration)).toBe(end);
  });
});

describe('a release without velocity', () => {
  it('eases onto the nearest row as UIKit does', () => {
    const plan = planRelease(STILL_6PX_PAST.offset, 0, MINUTES);
    expect(plan.kind).toBe('snap');
    expect(plan.index).toBe(31);
    expect(rms(plan.curve.value, STILL_6PX_PAST.frames)).toBeLessThan(0.4);
    expect(
      Math.abs(plan.curve.duration * 1000 - STILL_6PX_PAST.didSelect),
    ).toBeLessThan(60);
  });

  it('treats a release below the velocity floor as no velocity', () => {
    // 244.7 pt/s was zeroed by UIKit; 257.7 was handed on.
    expect(planRelease(1000, 240, MINUTES).kind).toBe('snap');
    expect(planRelease(1000, -240, MINUTES).kind).toBe('snap');
    expect(planRelease(1000, 260, MINUTES).kind).toBe('coast');
  });

  it('is already at rest on a row', () => {
    const curve = snapCurve(992, 992);
    expect(curve.duration).toBe(0);
    expect(curve.value(0)).toBe(992);
  });
});

describe('past an end', () => {
  it('rubber-bands a drag past the last row as UIPickerView does', () => {
    const end = 59 * 32;
    // 10, 50 and 110 px of finger travel past the end; UIKit showed 5.3, 25
    // and 50.
    expect(dragOffset(end + 10, MINUTES) - end).toBeCloseTo(5.4, 1);
    expect(dragOffset(end + 50, MINUTES) - end).toBeCloseTo(25.1, 1);
    expect(dragOffset(end + 110, MINUTES) - end).toBeCloseTo(50.1, 1);
    expect(dragOffset(-50, MINUTES)).toBeCloseTo(-25.1, 1);
    expect(dragOffset(500, MINUTES)).toBe(500);
  });

  it('returns to the end it was released past, keeping any velocity', () => {
    const plan = planRelease(-37.33, -147.8, MINUTES);
    expect(plan.kind).toBe('return');
    expect(plan.index).toBe(0);
    expect(plan.curve.velocity(0)).toBeCloseTo(-147.8, 6);
    expect(plan.curve.value(plan.curve.duration)).toBe(0);
  });
});

describe('a turn from rest', () => {
  it('springs onto the row on the settle spring, from rest, without overshoot', () => {
    // A tap, a key or the program turns the wheel on `springs.settle`, from
    // rest.
    const curve = bounceCurve(0, 0, 64, 1, springs.settle);
    expect(curve.velocity(0)).toBe(0);
    expect(curve.value(curve.duration)).toBe(64);
    let last = 0;
    for (let t = 0; t <= curve.duration; t += 1 / 120) {
      const value = curve.value(t);
      expect(value).toBeGreaterThanOrEqual(last - 1e-9);
      expect(value).toBeLessThanOrEqual(64 + 1e-9);
      last = value;
    }
  });
});

describe('the selection tick', () => {
  it('fires when a row’s centre reaches the band, not when it leaves it', () => {
    expect(reachesRow(31.9 * 32, 32 * 32, 32)).toBe(true);
    expect(reachesRow(32 * 32, 32.4 * 32, 32)).toBe(false);
    expect(reachesRow(32.1 * 32, 32 * 32, 32)).toBe(true);
    expect(reachesRow(32 * 32, 31.6 * 32, 32)).toBe(false);
  });

  it('ticks once per row on a coast, at most every 40 ms', () => {
    const {curve} = planRelease(1110, 1016.2, MINUTES);
    const ticks = tickTimes(curve, 32);
    // From row 34.7 to row 50: rows 35 to 50.
    expect(ticks.length).toBeLessThanOrEqual(16);
    expect(ticks.length).toBeGreaterThan(12);
    for (let i = 1; i < ticks.length; i++) {
      expect(ticks[i] - ticks[i - 1]).toBeGreaterThanOrEqual(0.04 - 1e-9);
    }
  });
});

describe('the bounce spring it is handed', () => {
  it('returns from past an end on the spring it is handed', () => {
    const layout: WheelLayout = {rowHeight: 32, rowCount: 60};
    const table = planRelease(-60, 0, layout);
    const stiff = planRelease(-60, 0, layout, {duration: 0.2, bounce: 0});
    expect(table.kind).toBe('return');
    expect(stiff.kind).toBe('return');
    expect(stiff.curve.to).toBe(0);
    expect(stiff.curve.duration).toBeLessThan(table.curve.duration);
  });

  // An undamped bounce spring (bounce 1, or a physical spring with no
  // damping) never settles, and a plan that never ends cannot be baked. It snaps onto its end at the animator's limit, as the
  // animator's own motion does.
  it('ends a plan whose bounce never settles at the animator limit', () => {
    const springs = [
      {duration: 0.5, bounce: 1},
      {stiffness: 300, damping: 0},
      {duration: 0.5, bounce: 0.999},
    ];
    for (const bounce of springs) {
      const back = planRelease(-60, 0, MINUTES, bounce);
      const into = planRelease(
        SWIPE_200_IN_100MS.offset,
        SWIPE_200_IN_100MS.velocity,
        MINUTES,
        bounce,
      );
      expect([back.kind, into.kind]).toEqual(['return', 'edge']);
      for (const {curve} of [back, into]) {
        expect(curve.duration, JSON.stringify(bounce)).toBeLessThanOrEqual(
          MAX_PLAN_SECONDS,
        );
        expect(curve.value(curve.duration)).toBe(curve.to);
        expect(curve.velocity(curve.duration)).toBe(0);
      }
    }
  });
});