Skip to content

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

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

/**
 * @file paging.test.ts
 * @input vitest, the paging math, and UIKit reference curves recorded on the
 *   iOS 26.2 simulator (a 402 pt paging UIScrollView, contentOffset per 60 Hz
 *   frame)
 * @output Holds solvePaging and solveAnimatedPageScroll to the recorded
 *   motion
 * @position Testing; validates paging.ts without a browser
 */

import {describe, expect, it} from 'vitest';
import {
  pagingSettleVelocity,
  solveAnimatedPageScroll,
  solvePaging,
} from './paging';
import {paging} from './uikit/paging';

/**
 * contentOffset per frame after a release at rest, from the frame the settle
 * starts (ms, px). UIKit lab, iOS 26.2 simulator, 402 pt pages.
 */
const SETTLES: Record<
  string,
  {from: number; velocity?: number; to: number; frames: number[][]}
> = {
  // 60 % of the way from page 1 to page 2, released at rest: page 2.
  forwardFrom60: {
    from: 633.33,
    to: 804,
    frames: [
      [0.7, 633.33],
      [17.4, 639],
      [34.0, 652],
      [50.7, 668.67],
      [67.4, 686.67],
      [84.0, 704.67],
      [100.7, 721.33],
      [117.4, 736.33],
      [134.0, 749.67],
      [150.7, 761],
      [167.4, 770.67],
      [184.0, 778.33],
      [200.7, 784.67],
      [217.4, 789.67],
      [234.0, 793.67],
      [250.7, 796.67],
      [267.4, 799],
      [284.0, 800.67],
      [300.7, 802],
      [317.4, 803],
      [334.0, 803.67],
      [350.7, 804],
    ],
  },
  // 46 % (content) of the way to page 2, released at rest: back to page 1.
  backFrom46: {
    from: 589,
    to: 402,
    frames: [
      [0.6, 589],
      [17.3, 583],
      [33.9, 569],
      [50.6, 550.67],
      [67.3, 531],
      [83.9, 511.33],
      [100.6, 493],
      [117.3, 476.33],
      [133.9, 461.67],
      [150.6, 449.33],
      [167.3, 439],
      [183.9, 430.33],
      [200.6, 423.33],
      [217.3, 417.67],
      [233.9, 413.33],
      [250.6, 410],
      [267.3, 407.33],
      [283.9, 405.33],
      [300.6, 404],
      [317.3, 403],
      [333.9, 402.33],
      [350.6, 402],
    ],
  },
  // Dragged back 23 % toward page 0, released at rest: page 1.
  forwardFromMinus23: {
    from: 311.33,
    to: 402,
    frames: [
      [0.6, 311.33],
      [17.2, 314.33],
      [33.9, 321],
      [50.6, 330],
      [67.2, 339.67],
      [83.9, 349.33],
      [100.6, 358.33],
      [117.2, 366.33],
      [133.9, 373.33],
      [150.6, 379.33],
      [167.2, 384.33],
      [183.9, 388.33],
      [200.6, 391.67],
      [217.2, 394.33],
      [233.9, 396.33],
      [250.6, 398],
      [267.2, 399.33],
      [283.9, 400.33],
      [300.6, 401],
      [317.2, 401.33],
      [333.9, 401.67],
      [350.6, 402],
    ],
  },
  // Released moving forward at 25 % with a settle velocity of 0.314 pt/ms
  // (steady 320 pt/s drag): the next page.
  flick314From24: {
    from: 499.67,
    velocity: 314,
    to: 804,
    frames: [
      [15.0, 499.67],
      [31.7, 513.33],
      [48.4, 538.33],
      [65.0, 569],
      [81.7, 601.67],
      [98.4, 633.33],
      [115.0, 662.67],
      [131.7, 689],
      [148.4, 712],
      [165.0, 731.67],
      [181.7, 748],
      [198.4, 761.33],
      [215.0, 772],
      [231.7, 780.33],
      [248.4, 787],
      [265.0, 792],
      [281.7, 796],
      [298.4, 799],
      [315.0, 801],
      [331.7, 802.33],
      [348.4, 803.33],
      [365.0, 804],
    ],
  },
  // 600 pt/s drag released with no hold: settle velocity 0.565 pt/ms.
  flick565From24: {
    from: 497.33,
    velocity: 565,
    to: 804,
    frames: [
      [-3.2, 497.33],
      [13.5, 514.33],
      [30.2, 541.33],
      [46.8, 573],
      [63.5, 606],
      [80.2, 637.67],
      [96.8, 667],
      [113.5, 693],
      [130.2, 715.33],
      [146.8, 734.33],
      [163.5, 750],
      [180.2, 763],
      [196.8, 773.33],
      [213.5, 781.67],
      [230.2, 788],
      [246.8, 793],
      [263.5, 796.67],
      [280.2, 799.33],
      [296.8, 801.33],
      [313.5, 802.67],
      [330.2, 803.67],
      [346.8, 804],
    ],
  },
  // 290 pt of pan past page 0 (114.33 pt shown), released at rest.
  overscrollReturn: {
    from: -114.33,
    to: 0,
    frames: [
      [0, -114.33],
      [10.6, -113],
      [27.3, -105.67],
      [43.9, -95.33],
      [60.6, -83.33],
      [77.3, -71],
      [93.9, -59.33],
      [110.6, -48.67],
      [127.3, -39.33],
      [143.9, -31.33],
      [160.6, -24.67],
      [177.3, -19],
      [193.9, -14.33],
      [210.6, -10.67],
      [227.3, -7.67],
      [243.9, -5.33],
      [260.6, -3.67],
      [277.3, -2.33],
      [293.9, -1.33],
      [310.6, -0.67],
      [327.3, -0.33],
      [343.9, 0],
    ],
  },
};

/** `setContentOffset(_:animated:)` per frame from its first frame (ms, px). */
const ANIMATED: Record<string, {from: number; to: number; frames: number[][]}> =
  {
    twoPages: {
      from: 402,
      to: 1206,
      frames: [
        [0, 402],
        [16.7, 408],
        [33.3, 426.33],
        [50, 456],
        [66.7, 496],
        [83.3, 545.67],
        [100, 603],
        [116.7, 666.67],
        [133.3, 734.33],
        [150, 804],
        [166.7, 873.67],
        [183.3, 941.33],
        [200, 1005],
        [216.7, 1062.33],
        [233.3, 1112],
        [250, 1152],
        [266.7, 1181.67],
        [283.3, 1200],
        [300, 1206],
      ],
    },
    fivePages: {
      from: 0,
      to: 2010,
      frames: [
        [0, 0],
        [16.7, 15.33],
        [33.3, 60.67],
        [50, 134.67],
        [66.7, 235],
        [83.3, 359],
        [100, 502.67],
        [116.7, 661.33],
        [133.3, 830.33],
        [150, 1005],
        [166.7, 1179.67],
        [183.3, 1348.67],
        [200, 1507.67],
        [216.7, 1651],
        [233.3, 1775],
        [250, 1875.33],
        [266.7, 1949.33],
        [283.3, 1994.67],
        [300, 2010],
      ],
    },
  };

/**
 * Residuals of a curve against recorded frames. The paging integrator runs
 * floor(elapsed ms) steps on each frame. So a frame shows the curve after the
 * floored steps since the start (`steps`). A timed curve, such as the animated
 * scroll, is read at the frame times (`time`).
 */
function errors(
  curve: {at(t: number): number},
  frames: number[][],
  clock: 'steps' | 'time',
): {rms: number; max: number} {
  let steps = 0;
  const residuals = frames.map(([ms, x], i) => {
    if (clock === 'steps' && i > 0) {
      steps += Math.floor(ms - frames[i - 1][0] + 1e-6);
    }
    const t =
      clock === 'steps' ? steps / paging.integrator.stepsPerSecond : ms / 1000;
    return curve.at(t) - x;
  });
  const rms = Math.sqrt(
    residuals.reduce((sum, r) => sum + r * r, 0) / residuals.length,
  );
  return {rms, max: Math.max(...residuals.map(Math.abs))};
}

describe('pagingSettleVelocity: the floor on the one release velocity (spec:AST-100 FR3)', () => {
  it('zeroes a release velocity below the floor, either way', () => {
    expect(pagingSettleVelocity(200)).toBe(0);
    expect(pagingSettleVelocity(-200)).toBe(0);
  });

  it('keeps a velocity at or above the floor: UIKit keeps a steady 249 pt/s release (0.249 pt/ms)', () => {
    expect(pagingSettleVelocity(249)).toBe(249);
    expect(pagingSettleVelocity(-260)).toBe(-260);
  });
});

describe("solvePaging: UIKit's paging settle, frame by frame", () => {
  it.each(Object.entries(SETTLES))(
    'reproduces the recorded %s within a pixel',
    (_, {from, velocity = 0, to, frames}) => {
      const curve = solvePaging({from, velocity, to});
      const {rms, max} = errors(curve, frames, 'steps');
      expect(rms).toBeLessThan(0.35);
      expect(max).toBeLessThan(0.8);
    },
  );

  it('ends exactly on the page about 0.33 s after a release at rest', () => {
    const curve = solvePaging({from: 633.33, velocity: 0, to: 804});
    expect(curve.at(curve.duration)).toBe(804);
    expect(curve.velocity(curve.duration)).toBe(0);
    expect(curve.duration).toBeGreaterThan(0.3);
    expect(curve.duration).toBeLessThan(0.36);
  });

  it("starts at the release position with UIKit's step velocity", () => {
    const curve = solvePaging({from: 500, velocity: 1000, to: 804});
    expect(curve.at(0)).toBe(500);
    // 1000 px/s enters as 1 px per step; 960 steps a second.
    expect(curve.velocity(0)).toBeCloseTo(960, 6);
  });

  it('is continuous and monotonic for a release at rest', () => {
    const curve = solvePaging({from: 589, velocity: 0, to: 402});
    let previous = curve.at(0);
    for (let t = 0.001; t <= curve.duration; t += 0.001) {
      const value = curve.at(t);
      expect(value).toBeLessThanOrEqual(previous + 1e-9);
      expect(Math.abs(value - previous)).toBeLessThan(3);
      previous = value;
    }
  });

  it('carries a forward flick on with a small overshoot-free approach', () => {
    const curve = solvePaging({from: 450, velocity: 600, to: 804});
    // The pull is underdamped (ζ ≈ 0.88): it may pass the page by a hair.
    let maxValue = -Infinity;
    for (let t = 0; t <= curve.duration; t += 0.004) {
      maxValue = Math.max(maxValue, curve.at(t));
    }
    expect(maxValue).toBeLessThan(804 + 2);
    expect(curve.at(curve.duration)).toBe(804);
  });

  it('settles at once when already on the page and at rest', () => {
    const curve = solvePaging({from: 804, velocity: 0, to: 804});
    expect(curve.steps).toBe(0);
    expect(curve.duration).toBe(0);
    expect(curve.at(0.1)).toBe(804);
  });

  it.each([0.75, 1.5, 3])(
    'at tempo %s, a settle from rest keeps its shape and takes tempo times as long',
    tempo => {
      const measured = solvePaging({from: 633.33, velocity: 0, to: 804});
      const paced = solvePaging({from: 633.33, velocity: 0, to: 804, tempo});
      expect(paced.steps).toBe(measured.steps);
      expect(paced.duration).toBeCloseTo(measured.duration * tempo, 9);
      for (let t = 0; t <= measured.duration; t += 0.01) {
        expect(paced.at(t * tempo)).toBeCloseTo(measured.at(t), 6);
      }
      expect(paced.at(paced.duration)).toBe(804);
    },
  );

  it("at any tempo, a release starts at UIKit's step velocity", () => {
    for (const tempo of [0.75, 1.5, 3]) {
      const curve = solvePaging({from: 500, velocity: 1000, to: 804, tempo});
      expect(curve.velocity(0)).toBeCloseTo(960, 6);
      expect(curve.at(curve.duration)).toBe(804);
    }
  });

  it('at tempo 1, the settle is the measured one', () => {
    const measured = solvePaging({from: 450, velocity: 600, to: 804});
    const atOne = solvePaging({from: 450, velocity: 600, to: 804, tempo: 1});
    expect(atOne.steps).toBe(measured.steps);
    expect(atOne.duration).toBe(measured.duration);
    for (let t = 0; t <= measured.duration; t += 0.004) {
      expect(atOne.at(t)).toBe(measured.at(t));
    }
  });

  it('runs the documented integrator', () => {
    const {springPull, friction} = paging.integrator;
    const curve = solvePaging({from: 0, velocity: 0, to: 100});
    // One step from rest: v = (0 + 100·pull)·friction.
    const oneStep = 100 * springPull * friction;
    expect(curve.at(1 / paging.integrator.stepsPerSecond)).toBeCloseTo(
      oneStep,
      9,
    );
  });
});

describe('solveAnimatedPageScroll: setContentOffset(_:animated:)', () => {
  it.each(Object.entries(ANIMATED))(
    'reproduces the recorded %s',
    (_, {from, to, frames}) => {
      const curve = solveAnimatedPageScroll({from, to});
      const {rms, max} = errors(curve, frames, 'time');
      expect(rms).toBeLessThan(0.5);
      expect(max).toBeLessThan(1.2);
    },
  );

  it('lasts 0.3 s whatever the distance and ends at rest', () => {
    for (const distance of [402, 804, 2010]) {
      const curve = solveAnimatedPageScroll({from: 0, to: distance});
      expect(curve.duration).toBe(0.3);
      expect(curve.at(0.3)).toBe(distance);
      expect(curve.velocity(0.3)).toBe(0);
      expect(curve.velocity(0)).toBe(0);
    }
  });

  // spec:AST-094 FR6: a new target keeps the current velocity (UIKit's
  // setContentOffset drops it).
  it('a retarget starts at the velocity it was handed and still ends on the target, at rest, on time', () => {
    for (const velocity of [900, -900, 0]) {
      const curve = solveAnimatedPageScroll({from: 100, to: 804, velocity});
      expect(curve.at(0)).toBe(100);
      expect(curve.velocity(0)).toBe(velocity);
      expect(curve.velocity(1e-4)).toBeCloseTo(velocity, -1);
      expect(curve.at(0.3)).toBe(804);
      expect(curve.velocity(0.3)).toBe(0);
      expect(curve.velocity(0.2999)).toBeCloseTo(0, -1);
    }
  });

  it('peaks at π/2 times the average speed halfway (the sinusoid, to 0.2 %)', () => {
    const curve = solveAnimatedPageScroll({from: 0, to: 402});
    expect(curve.velocity(0.15) / ((Math.PI / 2) * (402 / 0.3))).toBeCloseTo(
      1,
      2,
    );
  });

  it('follows the sinusoid to 0.02 % of the distance', () => {
    const curve = solveAnimatedPageScroll({from: 0, to: 402});
    for (let t = 0; t <= 0.3; t += 0.01) {
      const sine = (402 * (1 - Math.cos((Math.PI * t) / 0.3))) / 2;
      expect(Math.abs(curve.at(t) - sine)).toBeLessThan(0.1);
    }
  });

  it("takes a theme's duration and curve", () => {
    const curve = solveAnimatedPageScroll({
      from: 0,
      to: 100,
      durationMs: 500,
      curve: [0, 0, 1, 1],
    });
    expect(curve.duration).toBe(0.5);
    expect(curve.at(0.25)).toBeCloseTo(50, 1);
  });
});