Skip to content

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

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

/**
 * @file navigationTransition.test.ts
 * @input Uses vitest and navigationTransition.ts
 * @output Unit coverage of NavigationStack's transition math: the layers at
 *   a progress, their velocities, and the release rule against UIKit's
 *   measured releases. It also covers progress from a finger's travel and the
 *   progress a caught screen resumes from.
 * @position Testing; guards the numbers the component hands the animator
 */

import {rubberBand} from '@astryxdesign/core/internal/touch';
import {describe, expect, it} from 'vitest';
import {navigation} from './navigationMotion';
import {
  layersAt,
  layerVelocities,
  popVelocity,
  programmaticVelocity,
  progressFromScreen,
  progressFromTravel,
  shouldFinishPop,
} from './navigationTransition';

const W = 402;

describe('layersAt', () => {
  it('covers the screen with the top card at p = 0 (a push has landed)', () => {
    expect(layersAt(0, W)).toEqual({
      topX: 0,
      underX: navigation.parallax * W,
      dim: 1,
    });
  });

  it('has the card under it back at p = 1 (a pop has landed)', () => {
    const at = layersAt(1, W);
    expect(at.topX).toBe(W);
    expect(at.underX).toBeCloseTo(0, 10);
    expect(at.dim).toBe(0);
  });

  it('moves the card underneath at 0.3 of the top card’s speed (parallax)', () => {
    const a = layersAt(0.2, W);
    const b = layersAt(0.6, W);
    expect((b.underX - a.underX) / (b.topX - a.topX)).toBeCloseTo(0.3, 10);
  });

  it('mirrors every x under RTL', () => {
    const ltr = layersAt(0.4, W);
    const rtl = layersAt(0.4, W, 'rtl');
    expect(rtl.topX).toBe(-ltr.topX);
    expect(rtl.underX).toBe(-ltr.underX);
    expect(rtl.dim).toBe(ltr.dim);
  });
});

describe('layerVelocities', () => {
  it('is the derivative of layersAt, so one spring keeps the layers together', () => {
    const dp = 3.2;
    const h = 1e-6;
    const a = layersAt(0.5, W);
    const b = layersAt(0.5 + dp * h, W);
    const v = layerVelocities(dp, W);
    expect(v.topX).toBeCloseTo((b.topX - a.topX) / h, 3);
    expect(v.underX).toBeCloseTo((b.underX - a.underX) / h, 3);
    expect(v.dim).toBeCloseTo((b.dim - a.dim) / h, 3);
  });
});

describe('programmaticVelocity', () => {
  it('starts the push and the pop at 8.773 widths per second, not from rest', () => {
    expect(programmaticVelocity('push')).toBe(-navigation.pushVelocity);
    expect(programmaticVelocity('pop')).toBe(navigation.pushVelocity);
    // 3527 pt/s on the 402 pt card UIKit was measured on.
    expect(navigation.pushVelocity * W).toBeCloseTo(3527, -1);
  });
});

describe('shouldFinishPop', () => {
  it.each([
    // UIKit's own boundary cases (iOS 26.2 decision hook, 61 releases).
    [0.475, 0, false], // a still finger short of half cancels
    [0.05, 2.0, true], // a flick of ~2 widths/s from the edge finishes
    [0.05, 1.28, false], // ~490 pt/s from the edge cancels
    [0.6, 0, true],
    [0.6, -0.5, false], // dragged back toward the edge
    [0.9, -0.5, false], // moving back cancels, however far it went
    [0.3, 0.6, true],
  ])('p %f, v %f widths/s → finish %s', (p, v, finish) => {
    expect(shouldFinishPop(p, v)).toBe(finish);
  });
});

describe('progressFromTravel', () => {
  it('tracks the finger 1:1 as a share of the width', () => {
    expect(progressFromTravel(0, W / 4, W)).toBeCloseTo(0.25, 10);
  });

  it('continues from the progress a grabbed transition had', () => {
    expect(progressFromTravel(0.4, W / 10, W)).toBeCloseTo(0.5, 10);
  });

  it('never passes the far edge', () => {
    expect(progressFromTravel(0.9, W, W)).toBe(1);
  });

  it('back past the start, resists with UIKit’s rubber band', () => {
    const c = navigation.interactivePopRubberBand;
    expect(progressFromTravel(0, -50, W)).toBeCloseTo(
      rubberBand(-50, W, c) / W,
      10,
    );
    expect(progressFromTravel(0.05, -W * 0.1, W)).toBeCloseTo(
      rubberBand(-W * 0.05, W, c) / W,
      10,
    );
    // At the start it follows at the coefficient's share of the finger.
    expect(progressFromTravel(0, -0.01, W) * W).toBeCloseTo(-0.01 * c, 5);
  });

  it('reads leftward travel as a pop under RTL', () => {
    expect(progressFromTravel(0, -W / 2, W, 'rtl')).toBeCloseTo(0.5, 10);
  });
});

describe('progressFromScreen', () => {
  it.each([
    [80, 'ltr'],
    [-12, 'ltr'],
    [-80, 'rtl'],
    [12, 'rtl'],
  ] as const)(
    'a screen caught at x %f (%s) resumes where it shows',
    (x, direction) => {
      const p = progressFromScreen(x, W, direction);
      const sign = direction === 'rtl' ? -1 : 1;
      expect(progressFromTravel(p, 0, W, direction) * W * sign).toBeCloseTo(
        x,
        8,
      );
    },
  );

  it('keeps the side of the start: caught past it, it stays past it', () => {
    expect(progressFromScreen(-12, W)).toBeLessThan(0);
    expect(progressFromScreen(12, W, 'rtl')).toBeLessThan(0);
  });
});

describe('popVelocity', () => {
  it('converts px/s to widths per second toward the pop', () => {
    expect(popVelocity(804, W)).toBeCloseTo(2, 10);
    expect(popVelocity(-804, W, 'rtl')).toBeCloseTo(2, 10);
    expect(popVelocity(100, 0)).toBe(0);
  });
});