Skip to content

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

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

/**
 * @file pressGesture.test.ts
 * @input pressGesture.ts
 * @output Unit tests for the press state machine, one case per requirement
 *   of the touch press model, in the model's order
 * @position Testing; validates pressGesture.ts without a browser
 *
 * Every number these assert against was measured on an iPhone simulator
 * driving the real Settings and Contacts apps with real HID touches at
 * 60 fps. The test names say the behaviour, not the mechanism, so a rewrite
 * of the machine still has to keep them.
 */

import {describe, expect, it} from 'vitest';
import {UIKIT_GESTURES} from '../motion/uikit/gestures';
import type {PressEvent, PressGesture, PressPaint} from './pressGesture';
import {
  idlePressGesture,
  PRESS_FADE_MS,
  PRESS_FLASH_MS,
  PRESS_ONSET_MS,
  PRESS_SLOP_PX,
  pressGestureStep,
} from './pressGesture';

/** Drive a gesture and collect what was painted after each event. */
function run(events: PressEvent[]): {
  paints: PressPaint[];
  gesture: PressGesture;
} {
  let gesture = idlePressGesture();
  const paints: PressPaint[] = [];
  for (const event of events) {
    const step = pressGestureStep(gesture, event);
    gesture = step.gesture;
    paints.push(step.paint);
  }
  return {gesture, paints};
}

const down = (x = 100, y = 100): PressEvent => ({kind: 'down', x, y});
const move = (x: number, y: number): PressEvent => ({kind: 'move', x, y});

describe('the clocks are the native ones', () => {
  it("waits the scroll view's content-touch delay before believing a press", () => {
    // `UIScrollView.delaysContentTouches` holds a content touch 0.15 s.
    // Measured: a 1.5 s hold painted the native highlight for 1.34 s.
    expect(PRESS_ONSET_MS).toBe(150);
  });

  it("uses the scroller's own slop and a flash for a quick tap, and without a theme the exit token's fade", () => {
    expect(PRESS_SLOP_PX).toBe(10);
    // `--duration-exit` is `var(--duration-fast)`, 175 ms by default.
    expect(PRESS_FADE_MS).toBe(175);
    expect(PRESS_FLASH_MS).toBe(100);
  });

  it("are the UIKit table's measured values, one definition each", () => {
    // The machine keeps its own constants, so a pressable page loads no
    // motion table; the table's entries stay the one definition.
    expect(PRESS_ONSET_MS).toBe(UIKIT_GESTURES.press.contentTouchDelay.value);
    expect(PRESS_FLASH_MS).toBe(UIKIT_GESTURES.press.quickTapFlash.value);
    expect(PRESS_SLOP_PX).toBe(UIKIT_GESTURES.press.slop.value);
  });
});

describe('nothing paints until the press is believed', () => {
  it('paints nothing on the touch itself', () => {
    const {paints, gesture} = run([down()]);
    expect(paints).toEqual(['none']);
    expect(gesture.phase).toBe('armed');
  });

  it('asks for the onset timer, and only then', () => {
    expect(pressGestureStep(idlePressGesture(), down()).timer).toBe('onset');
  });

  it('never paints for a fling: the scroller claims it inside the delay', () => {
    // Measured: `pointercancel` at +31 ms on a fling, 119 ms before the onset
    // timer would have fired.
    const {paints} = run([down(), move(100, 90), {kind: 'cancel'}]);
    expect(paints).toEqual(['none', 'none', 'none']);
  });
});

describe('a held press paints instantly and completely', () => {
  it('paints on the onset, with no transition state in between', () => {
    const {paints, gesture} = run([down(), {kind: 'onset'}]);
    expect(paints).toEqual(['none', 'on']);
    expect(gesture.phase).toBe('pressed');
  });
});

describe('travel cancels, and a shaky hand does not', () => {
  it('keeps the press while the finger stays inside the slop', () => {
    // Measured: a 4 pt drag over 2 s kept the native highlight for the whole
    // gesture.
    const inside = PRESS_SLOP_PX - 1;
    const {paints, gesture} = run([
      down(),
      {kind: 'onset'},
      move(100, 100 + inside),
    ]);
    expect(paints).toEqual(['none', 'on', 'on']);
    expect(gesture.phase).toBe('pressed');
  });

  it('cancels the moment the finger passes the slop, painted or not', () => {
    const beyond = PRESS_SLOP_PX + 1;
    const painted = run([down(), {kind: 'onset'}, move(100, 100 + beyond)]);
    expect(painted.paints.at(-1)).toBe('none');
    expect(painted.gesture.phase).toBe('dead');

    const unpainted = run([down(), move(100, 100 + beyond)]);
    expect(unpainted.paints).toEqual(['none', 'none']);
    expect(unpainted.gesture.phase).toBe('dead');
  });

  it('measures travel from where the finger landed, not from the last move', () => {
    // Otherwise a slow drag never trips the slop: each step is small, and the
    // press would ride a scroll all the way down the list.
    const creep: PressEvent[] = [];
    for (let y = 101; y <= 100 + PRESS_SLOP_PX + 2; y += 1) {
      creep.push(move(100, y));
    }
    const {gesture} = run([down(), {kind: 'onset'}, ...creep]);
    expect(gesture.phase).toBe('dead');
  });
});

describe("the scroller's claim cancels", () => {
  it('drops the paint with no fade', () => {
    // Measured: the native highlight goes from full to bare in ONE frame, and
    // 45 ms BEFORE the list's content first moves.
    const {paints, gesture} = run([down(), {kind: 'onset'}, {kind: 'cancel'}]);
    expect(paints).toEqual(['none', 'on', 'none']);
    expect(gesture.phase).toBe('dead');
  });

  it('asks for no timer on the way out, so nothing can fire later', () => {
    const armed = pressGestureStep(idlePressGesture(), down()).gesture;
    const pressed = pressGestureStep(armed, {kind: 'onset'}).gesture;
    expect(pressGestureStep(pressed, {kind: 'cancel'}).timer).toBeNull();
  });
});

describe('a cancelled gesture is dead', () => {
  it('does not come back when the finger stops moving', () => {
    const {paints, gesture} = run([
      down(),
      {kind: 'onset'},
      move(100, 200),
      move(100, 200),
      move(100, 201),
    ]);
    expect(paints.slice(2)).toEqual(['none', 'none', 'none']);
    expect(gesture.phase).toBe('dead');
  });

  it('does not come back when the finger returns to where it started', () => {
    const {paints} = run([
      down(),
      {kind: 'onset'},
      move(100, 200),
      move(100, 100),
    ]);
    expect(paints.at(-1)).toBe('none');
  });

  it('does not paint on the release either', () => {
    const {paints} = run([
      down(),
      {kind: 'onset'},
      {kind: 'cancel'},
      {kind: 'up'},
    ]);
    expect(paints.at(-1)).toBe('none');
  });

  it('does not paint if the onset timer fires late, after the scroll took the gesture', () => {
    // iOS throttles frame callbacks during a scroll and a queued timer can
    // land after the cancel; the phase, not the timer, decides.
    const {paints} = run([down(), {kind: 'cancel'}, {kind: 'onset'}]);
    expect(paints).toEqual(['none', 'none', 'none']);
  });

  it('only a new touch revives it', () => {
    const {paints, gesture} = run([
      down(),
      {kind: 'cancel'},
      down(120, 300),
      {kind: 'onset'},
    ]);
    expect(paints.at(-1)).toBe('on');
    expect(gesture.phase).toBe('pressed');
  });

  it('ends when the finger lifts, so the NEXT press is heard', () => {
    // The gesture holds the controller's one tracking slot until it resolves.
    // A `dead` gesture that never resolved is how every press after the first
    // scroll would answer with nothing.
    const {gesture} = run([
      down(),
      {kind: 'onset'},
      move(100, 300),
      {kind: 'up'},
    ]);
    expect(gesture.phase).toBe('idle');
  });
});

describe('a press after a scroll', () => {
  it('paints, the way the first one did', () => {
    const {paints, gesture} = run([
      down(),
      {kind: 'onset'},
      move(100, 400),
      {kind: 'up'},
      down(100, 420),
      {kind: 'onset'},
    ]);
    expect(paints.at(-1)).toBe('on');
    expect(gesture.phase).toBe('pressed');
  });
});

describe('the paint does not survive its gesture', () => {
  it('leaves nothing painted once a cancelled gesture is over', () => {
    const {paints, gesture} = run([
      down(),
      {kind: 'onset'},
      {kind: 'cancel'},
      {kind: 'up'},
    ]);
    expect(paints.at(-1)).toBe('none');
    expect(gesture.phase).toBe('idle');
  });
});

describe('a tap too quick for the delay still answers', () => {
  it('paints at the release and holds it at full strength', () => {
    const {paints, gesture} = run([down(), {kind: 'up'}]);
    expect(paints).toEqual(['none', 'on']);
    expect(gesture.phase).toBe('flash');
  });

  it('arms the flash hold, then hands over to the same fade a long press gets', () => {
    const armed = pressGestureStep(idlePressGesture(), down()).gesture;
    const flash = pressGestureStep(armed, {kind: 'up'});
    expect(flash.timer).toBe('flash');
    const fading = pressGestureStep(flash.gesture, {kind: 'flashEnd'});
    expect(fading.paint).toBe('fading');
    expect(fading.timer).toBe('fade');
  });

  it('is not clipped by the cancel iOS sends after the tap', () => {
    // iOS Safari delivers `touchcancel` at `scrollend`, up to seconds after a
    // tap. It must not cut the answer the tap earned.
    const {paints} = run([down(), {kind: 'up'}, {kind: 'cancel'}]);
    expect(paints.at(-1)).toBe('on');
  });
});

describe('the release fades', () => {
  it('fades from a held press and ends idle', () => {
    const {paints, gesture} = run([
      down(),
      {kind: 'onset'},
      {kind: 'up'},
      {kind: 'fadeEnd'},
    ]);
    expect(paints).toEqual(['none', 'on', 'fading', 'none']);
    expect(gesture.phase).toBe('idle');
  });

  it('asks for the fade timer so the state cannot be left behind', () => {
    const armed = pressGestureStep(idlePressGesture(), down()).gesture;
    const pressed = pressGestureStep(armed, {kind: 'onset'}).gesture;
    expect(pressGestureStep(pressed, {kind: 'up'}).timer).toBe('fade');
  });
});

describe('on a touch-first device, a mouse button or the Space key presses at once', () => {
  // The stylesheet drops `:active` by the PRIMARY pointer, so on a phone or
  // a tablet a trackpad click or a Space press has nothing else to paint it.
  // Nothing can turn either into a scroll, so nothing waits.
  const buttonDown: PressEvent = {kind: 'buttonDown'};

  it('paints on the press itself and arms no timer', () => {
    const step = pressGestureStep(idlePressGesture(), buttonDown);
    expect(step.paint).toBe('on');
    expect(step.timer).toBeNull();
    expect(step.gesture.phase).toBe('buttonHeld');
  });

  it('keeps the paint through any travel, as a held mouse keeps `:active`', () => {
    const {paints, gesture} = run([
      buttonDown,
      move(100 + PRESS_SLOP_PX * 10, 100),
      move(-500, -500),
      {kind: 'onset'},
    ]);
    expect(paints).toEqual(['on', 'on', 'on', 'on']);
    expect(gesture.phase).toBe('buttonHeld');
  });

  it("fades at the release with a finger's fade, and ends idle", () => {
    const held = pressGestureStep(idlePressGesture(), buttonDown).gesture;
    const release = pressGestureStep(held, {kind: 'up'});
    expect(release.paint).toBe('fading');
    expect(release.timer).toBe('fade');
    const {paints, gesture} = run([
      buttonDown,
      {kind: 'up'},
      {kind: 'fadeEnd'},
    ]);
    expect(paints).toEqual(['on', 'fading', 'none']);
    expect(gesture.phase).toBe('idle');
  });

  it('drops the paint at once when the platform takes the press away', () => {
    const {paints, gesture} = run([buttonDown, {kind: 'cancel'}]);
    expect(paints).toEqual(['on', 'none']);
    expect(gesture.phase).toBe('dead');
  });

  it('takes over a surface whose last press is still fading', () => {
    const {paints} = run([buttonDown, {kind: 'up'}, buttonDown]);
    expect(paints).toEqual(['on', 'fading', 'on']);
  });
});

describe('a control with no scroller above it does not wait', () => {
  const now = (x = 100, y = 100): PressEvent => ({
    kind: 'down',
    x,
    y,
    delayed: false,
  });

  it('paints in the frame the finger lands, with no timer', () => {
    const step = pressGestureStep(idlePressGesture(), now());
    expect(step.paint).toBe('on');
    expect(step.gesture.phase).toBe('pressed');
    expect(step.timer).toBeNull();
  });

  it('is still cancelled by travel past the slop, with no fade', () => {
    expect(run([now(), move(100, 100 + PRESS_SLOP_PX + 1)]).paints).toEqual([
      'on',
      'none',
    ]);
  });

  it('is still cancelled by the scroll that takes the touch', () => {
    expect(run([now(), {kind: 'cancel'}]).paints).toEqual(['on', 'none']);
  });

  it('fades at the lift', () => {
    const {paints, gesture} = run([now(), {kind: 'up'}]);
    expect(paints).toEqual(['on', 'fading']);
    expect(gesture.phase).toBe('fading');
  });

  it('a delayed touch still waits, which is the default', () => {
    expect(
      pressGestureStep(idlePressGesture(), {
        kind: 'down',
        x: 100,
        y: 100,
        delayed: true,
      }).paint,
    ).toBe('none');
    expect(pressGestureStep(idlePressGesture(), down()).paint).toBe('none');
  });
});