Skip to content

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

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

/**
 * @file menuPressGesture.test.ts
 * @input vitest, the pure menuPressStep machine
 * @output One test per transition of the press-model state diagram
 * @position Testing; validates menuPressGesture.ts without a browser
 */

import {describe, it, expect} from 'vitest';
import {
  IDLE_MENU_PRESS,
  MENU_PRESS_HANDOFF_PX,
  MENU_PRESS_SETTLE_MS,
  menuPressStep,
  menuPressTransition,
  type MenuPressInput,
  type MenuPressState,
  type MenuPressEvent,
} from './menuPressGesture';

type Row = 'A' | 'B';

function run(events: MenuPressInput<Row>[]) {
  let gesture: MenuPressState<Row> = IDLE_MENU_PRESS;
  const effects = [];
  for (const event of events) {
    const step = menuPressTransition(gesture, event);
    gesture = step.gesture;
    effects.push(step.effect);
  }
  return {gesture, effects, last: effects[effects.length - 1]};
}

const downInMenu = (
  row: Row | null,
  pointerType: 'mouse' | 'touch' = 'touch',
) => ({type: 'down', target: 'menu', pointerType, row, time: 0}) as const;
const downOnTrigger = (pointerType: 'mouse' | 'touch' | 'pen', time = 0) =>
  ({type: 'down', target: 'trigger', pointerType, row: null, time}) as const;
const move = (row: Row | null, isInMenu = true, time = 10) =>
  ({type: 'move', row, isInMenu, time}) as const;
const up = (
  row: Row | null,
  {
    isInMenu = row != null,
    isOnTrigger = false,
    time = 20,
  }: {isInMenu?: boolean; isOnTrigger?: boolean; time?: number} = {},
) => ({type: 'up', row, isInMenu, isOnTrigger, time}) as const;

describe('menuPressStep — inside the menu', () => {
  it('Idle → Tracking: a pointer down inside the menu highlights the row under it', () => {
    const {gesture, last} = run([downInMenu('A')]);
    expect(gesture.phase).toBe('tracking');
    expect(last).toEqual({type: 'highlight', row: 'A'});
  });

  it('Idle → Tracking: a pointer down over a divider highlights nothing', () => {
    const {gesture, last} = run([downInMenu(null)]);
    expect(gesture.phase).toBe('tracking');
    expect(last).toEqual({type: 'clear'});
  });

  it('Tracking → Tracking: a move onto another row moves the highlight', () => {
    const {last} = run([downInMenu('A'), move('B')]);
    expect(last).toEqual({type: 'highlight', row: 'B'});
  });

  it('Tracking → Tracking: a move over a disabled row or a heading clears the highlight', () => {
    const {last} = run([downInMenu('A'), move(null)]);
    expect(last).toEqual({type: 'clear'});
  });

  it('Tracking → Tracking: a move within the same row changes nothing', () => {
    const {last} = run([downInMenu('A'), move('A')]);
    expect(last).toEqual({type: 'none'});
  });

  it('Tracking → Acted: a release over an enabled row acts on THAT row, not the one pressed', () => {
    const {gesture, last} = run([downInMenu('A'), move('B'), up('B')]);
    expect(last).toEqual({type: 'act', row: 'B'});
    expect(gesture.phase).toBe('idle');
  });

  it('a tap that never left its row acts on that row and swallows nothing else', () => {
    const {last} = run([downInMenu('A'), up('A')]);
    expect(last).toEqual({type: 'act', row: 'A'});
  });

  it('Tracking → Idle: a release over a divider, heading or disabled row acts on nothing and keeps the menu', () => {
    const {last} = run([
      downInMenu('A'),
      move(null),
      up(null, {isInMenu: true}),
    ]);
    expect(last).toEqual({type: 'settle', stray: true, dismiss: false});
  });

  it('Tracking → Released → Idle: a MOUSE released outside acts on nothing and dismisses', () => {
    const {last} = run([
      downInMenu('A', 'mouse'),
      move(null, false),
      up(null, {isInMenu: false}),
    ]);
    expect(last).toEqual({type: 'settle', stray: true, dismiss: true});
  });

  it('Tracking → Released → Idle: a FINGER released outside acts on nothing and leaves the menu open', () => {
    const {last} = run([
      downInMenu('A', 'touch'),
      move(null, false),
      up(null, {isInMenu: false}),
    ]);
    expect(last).toEqual({type: 'settle', stray: true, dismiss: false});
  });

  it('Tracking → Idle: a cancel (scroll, second pointer, browser) acts on nothing', () => {
    const {gesture, last} = run([downInMenu('A'), move('B'), {type: 'cancel'}]);
    expect(gesture.phase).toBe('idle');
    expect(last).toEqual({type: 'settle', stray: false, dismiss: false});
  });

  it('ignores a move or a release with no gesture live', () => {
    expect(menuPressTransition(IDLE_MENU_PRESS, move('A')).effect).toEqual({
      type: 'none',
    });
    expect(menuPressTransition(IDLE_MENU_PRESS, up('A')).effect).toEqual({
      type: 'none',
    });
  });
});

describe('menuPressStep — the trigger', () => {
  it('Idle → Open: a mouse press on the trigger opens the menu at once', () => {
    const {gesture, last} = run([downOnTrigger('mouse')]);
    expect(gesture.phase).toBe('open');
    expect(last).toEqual({type: 'open'});
  });

  it('Idle → TriggerPress: a finger on the trigger opens nothing yet', () => {
    const {gesture, last} = run([downOnTrigger('touch')]);
    expect(gesture.phase).toBe('triggerPress');
    expect(last).toEqual({type: 'none'});
  });

  it('TriggerPress → Idle: a finger that lifts before the delay is a tap; the browser click opens the menu', () => {
    const {gesture, last} = run([
      downOnTrigger('touch'),
      up(null, {isInMenu: false, isOnTrigger: true}),
    ]);
    expect(gesture.phase).toBe('idle');
    expect(last).toEqual({type: 'settle', stray: false, dismiss: false});
  });

  it('TriggerPress → Open: the menu opens under a finger held for the delay', () => {
    const {gesture, last} = run([
      downOnTrigger('touch'),
      {type: 'opened', time: 500},
    ]);
    expect(gesture.phase).toBe('open');
    expect(last).toEqual({type: 'none'});
  });

  it('TriggerPress → Idle: a cancel before the delay ends the gesture', () => {
    // The effect has to be a settle, not nothing: a held finger installs a
    // document touchmove preventer for the gesture, and only the end of a
    // gesture takes it back off. Returning `none` here left the page unable
    // to scroll after an interrupted press.
    const {gesture, last} = run([downOnTrigger('touch'), {type: 'cancel'}]);
    expect(gesture.phase).toBe('idle');
    expect(last).toEqual({type: 'settle', stray: false, dismiss: false});
  });

  it('Open → Tracking: the pointer moving onto the menu starts tracking from the trigger', () => {
    const {gesture, last} = run([downOnTrigger('mouse'), move('A', true)]);
    expect(gesture).toMatchObject({
      phase: 'tracking',
      origin: 'trigger',
      row: 'A',
    });
    expect(last).toEqual({type: 'highlight', row: 'A'});
  });

  it('Open → Open: a move that stays outside the menu changes nothing', () => {
    const {gesture, last} = run([downOnTrigger('mouse'), move(null, false)]);
    expect(gesture.phase).toBe('open');
    expect(last).toEqual({type: 'none'});
  });

  it('Open → Idle: the opening release before the settle time, without entering, acts on nothing and the menu stays', () => {
    const {gesture, last} = run([
      downOnTrigger('mouse', 0),
      up(null, {
        isInMenu: false,
        isOnTrigger: true,
        time: MENU_PRESS_SETTLE_MS - 1,
      }),
    ]);
    expect(gesture.phase).toBe('idle');
    expect(last).toEqual({type: 'settle', stray: true, dismiss: false});
  });

  it('Open → Acted: a drag from the trigger into the menu that releases over a row acts on it', () => {
    const {last} = run([
      downOnTrigger('mouse', 0),
      move('B', true, 50),
      up('B', {time: 60}),
    ]);
    expect(last).toEqual({type: 'act', row: 'B'});
  });

  it('Open → Acted: after the settle time the opening release acts on the row under it', () => {
    const {last} = run([
      downOnTrigger('mouse', 0),
      up('A', {time: MENU_PRESS_SETTLE_MS}),
    ]);
    expect(last).toEqual({type: 'act', row: 'A'});
  });

  it('Open → Idle: releasing on the trigger after the settle time leaves the menu open', () => {
    const {last} = run([
      downOnTrigger('mouse', 0),
      up(null, {
        isInMenu: false,
        isOnTrigger: true,
        time: MENU_PRESS_SETTLE_MS,
      }),
    ]);
    expect(last).toEqual({type: 'settle', stray: true, dismiss: false});
  });

  it('Open → Released → Idle: a settled mouse release outside dismisses; a finger leaves the menu open', () => {
    expect(
      run([
        downOnTrigger('mouse', 0),
        up(null, {isInMenu: false, time: MENU_PRESS_SETTLE_MS}),
      ]).last,
    ).toEqual({type: 'settle', stray: true, dismiss: true});
    expect(
      run([
        downOnTrigger('touch', 0),
        {type: 'opened', time: 500},
        up(null, {isInMenu: false, time: 500 + MENU_PRESS_SETTLE_MS}),
      ]).last,
    ).toEqual({type: 'settle', stray: true, dismiss: false});
  });

  it('Open → Idle: a cancel while open ends the gesture and keeps the menu', () => {
    // As above: the gesture's document listeners come off, and the menu is
    // left open because a cancelled pointer never asked to close it.
    const {gesture, last} = run([downOnTrigger('mouse'), {type: 'cancel'}]);
    expect(gesture.phase).toBe('idle');
    expect(last).toEqual({type: 'settle', stray: false, dismiss: false});
  });
});

describe('menuPressStep — a finger that opened the menu hands off after travelling (UIMenu)', () => {
  // UIKit on iOS 26.2: the menu opens under a held finger. The finger picks
  // only once it has moved the handoff distance from the first sample the
  // menu saw. Positions are viewport px.
  const held = (pointerType: 'touch' | 'pen' = 'touch') =>
    [
      downOnTrigger(pointerType, 0),
      {type: 'opened', time: 150},
    ] as MenuPressInput<Row>[];
  const moveTo = (x: number, y: number, row: Row | null = 'A', time = 400) =>
    ({type: 'move', row, isInMenu: row != null, time, x, y}) as const;
  const upAt = (
    x: number,
    y: number,
    row: Row | null = 'A',
    {isInMenu = row != null, isOnTrigger = false, time = 600} = {},
  ) => ({type: 'up', row, isInMenu, isOnTrigger, time, x, y}) as const;

  it('the handoff distance is the one in the UIKit constants table', () => {
    expect(MENU_PRESS_HANDOFF_PX).toBe(10);
  });

  it('Open → Idle: the opening finger lifted without moving picks nothing, however long it rested', () => {
    for (const time of [200, 600, 5000]) {
      const {gesture, last} = run([...held(), upAt(200, 182, 'A', {time})]);
      expect(gesture.phase).toBe('idle');
      expect(last).toEqual({type: 'settle', stray: true, dismiss: false});
    }
  });

  it('Open → Open: the first sample after the open is where the distance counts from', () => {
    const {gesture, last} = run([...held(), moveTo(200, 189)]);
    expect(gesture).toMatchObject({
      phase: 'open',
      handoffFrom: {x: 200, y: 189},
    });
    expect(last).toEqual({type: 'none'});
  });

  it('Open → Open: under the handoff distance nothing is highlighted', () => {
    const {gesture, last} = run([
      ...held(),
      moveTo(200, 189),
      moveTo(200, 189 + MENU_PRESS_HANDOFF_PX - 1),
    ]);
    expect(gesture.phase).toBe('open');
    expect(last).toEqual({type: 'none'});
  });

  it('Open → Tracking: at the handoff distance the highlight follows the finger', () => {
    const {gesture, last} = run([
      ...held(),
      moveTo(200, 189),
      moveTo(200, 189 + MENU_PRESS_HANDOFF_PX, 'B'),
    ]);
    expect(gesture).toMatchObject({
      phase: 'tracking',
      origin: 'trigger',
      row: 'B',
    });
    expect(last).toEqual({type: 'highlight', row: 'B'});
  });

  it('counts from the first sample, not from where the finger was when the menu opened (b4 capture: 7.3 pt, then 11 pt)', () => {
    // The finger rested at y 182 when the menu opened. Samples then came at
    // 189.33, 196.67 and 200.33, where UIKit began. The second sample is 14.7
    // from the open point and 7.3 from the first sample. The third is 11 from
    // the first sample.
    const samples = [189.33, 196.67, 200.33];
    const phases = samples.map(
      (_, i) =>
        run([...held(), ...samples.slice(0, i + 1).map(y => moveTo(200, y))])
          .gesture.phase,
    );
    expect(phases).toEqual(['open', 'open', 'tracking']);
  });

  it('measures a straight-line distance, as UIMenu does (iOS 26.2: after a 1 pt first step)', () => {
    // UIKit lab: (0, 9) and (7, 7) [9.9] pick nothing; (0, 10), (10, 0) and
    // (9, 9) [12.7] pick.
    const phaseAfter = (dx: number, dy: number) =>
      run([...held(), moveTo(100, 100), moveTo(100 + dx, 100 + dy)]).gesture
        .phase;
    expect(phaseAfter(0, 9)).toBe('open');
    expect(phaseAfter(7, 7)).toBe('open');
    expect(phaseAfter(0, 10)).toBe('tracking');
    expect(phaseAfter(10, 0)).toBe('tracking');
    expect(phaseAfter(9, 9)).toBe('tracking');
    expect(phaseAfter(0, -10)).toBe('tracking');
  });

  it('counts from the first sample, not from where the finger was at the open (iOS 26.2: a 9 pt step, then 3 more, picks nothing)', () => {
    const {gesture, last} = run([
      ...held(),
      moveTo(200, 191),
      moveTo(200, 194),
      upAt(200, 194, 'A'),
    ]);
    expect(gesture.phase).toBe('idle');
    expect(last).toEqual({type: 'settle', stray: true, dismiss: false});
  });

  it('Open → Tracking → Acted: after the handoff, the lift acts on the row under it', () => {
    const {last} = run([
      ...held(),
      moveTo(200, 189),
      moveTo(200, 230, 'A'),
      moveTo(200, 280, 'B'),
      upAt(200, 292, 'B'),
    ]);
    expect(last).toEqual({type: 'act', row: 'B'});
  });

  it('Open → Idle: a finger that moved under the distance and lifted over a row picks nothing', () => {
    const {last} = run([
      ...held(),
      moveTo(200, 189),
      moveTo(200, 195),
      upAt(200, 195, 'A'),
    ]);
    expect(last).toEqual({type: 'settle', stray: true, dismiss: false});
  });

  it('a pen follows the finger rules', () => {
    expect(run([...held('pen'), upAt(200, 182, 'A')]).last).toEqual({
      type: 'settle',
      stray: true,
      dismiss: false,
    });
  });

  it('a mouse keeps the settle rule: entering the menu tracks at once', () => {
    const {gesture, last} = run([
      downOnTrigger('mouse', 0),
      moveTo(200, 189, 'A', 40),
    ]);
    expect(gesture).toMatchObject({phase: 'tracking', row: 'A'});
    expect(last).toEqual({type: 'highlight', row: 'A'});
    expect(
      run([
        downOnTrigger('mouse', 0),
        upAt(200, 182, 'A', {time: MENU_PRESS_SETTLE_MS}),
      ]).last,
    ).toEqual({type: 'act', row: 'A'});
  });
});

describe('menuPressStep, the released public machine', () => {
  it('keeps the settle rule when a caller\u2019s events carry positions: the opening finger picks the row it lifts on', () => {
    type Positioned = MenuPressEvent<Row> & {x: number; y: number};
    let gesture = menuPressStep<Row>(IDLE_MENU_PRESS, {
      type: 'down',
      target: 'trigger',
      pointerType: 'touch',
      row: null,
      time: 0,
    }).gesture;
    gesture = menuPressStep(gesture, {type: 'opened', time: 500}).gesture;
    const move: Positioned = {
      type: 'move',
      row: 'B' as Row,
      isInMenu: true,
      time: 1000,
      x: 0,
      y: 60,
    };
    gesture = menuPressStep(gesture, move).gesture;
    const up: Positioned = {
      type: 'up',
      row: 'B' as Row,
      isInMenu: true,
      isOnTrigger: false,
      time: 1100,
      x: 0,
      y: 60,
    };
    expect(menuPressStep(gesture, up).effect).toEqual({type: 'act', row: 'B'});
  });

  it('keeps the released shapes: no handoff state', () => {
    let gesture = menuPressStep(IDLE_MENU_PRESS, {
      type: 'down',
      target: 'menu',
      pointerType: 'touch',
      row: 'A' as Row,
      time: 0,
    }).gesture;
    gesture = menuPressStep(gesture, {
      type: 'move',
      row: 'B' as Row,
      isInMenu: true,
      time: 10,
    }).gesture;
    const {effect} = menuPressStep(gesture, {type: 'cancel'});
    expect(effect).toEqual({type: 'settle', stray: false, dismiss: false});
    const opened = menuPressStep(
      menuPressStep(IDLE_MENU_PRESS, {
        type: 'down',
        target: 'trigger',
        pointerType: 'touch',
        row: null,
        time: 0,
      }).gesture,
      {type: 'opened', time: 500},
    ).gesture;
    expect(Object.keys(opened).sort()).toEqual(
      ['openedAt', 'phase', 'pointerType'].sort(),
    );
  });
});