Skip to content

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

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

/**
 * @file clickGuard.test.ts
 * @input Uses vitest and jsdom
 * @output An armed guard swallows the browser's next click before any page
 *   listener and is spent; a click whose detail is 0, one dispatched inside
 *   withoutClickGuard and the haptic switch's click pass; the next
 *   pointerdown and the window disarm it; it hears pointerdown only while
 *   armed; the menu press model's click listener stays, one per document,
 *   ahead of later ones, while the gesture host's lasts only while armed;
 *   the menu press model and the gesture host arm this one guard; an arm at
 *   a claimed touch's lift also takes that touch's late mousedown and mouseup
 * @position Unit tests of packages/core/src/utils/clickGuard.ts
 */

import {afterEach, describe, expect, it, vi} from 'vitest';

import {GestureHost} from '../gestures/GestureHost';
import {coarsePrimaryPointer} from '../gestures/__tests__/pointerQuery';
import {markHapticSwitch} from '../privateAttributes/hapticSwitch.stylex';
import {TapGestureRecognizer} from '../gestures/TapGestureRecognizer';
import {MENU_PRESS_STRAY_CLICK_MS} from '../hooks/useMenuPress';
import {
  __resetClickGuardForTest,
  armClickGuard,
  CLICK_GUARD_WINDOW_MS,
  disarmClickGuard,
  isClickGuardArmed,
  withoutClickGuard,
} from './clickGuard';

afterEach(() => {
  __resetClickGuardForTest();
  vi.useRealTimers();
  vi.restoreAllMocks();
  document.body.innerHTML = '';
});

function click(target: EventTarget, detail = 1): MouseEvent {
  const event = new MouseEvent('click', {
    bubbles: true,
    cancelable: true,
    detail,
  });
  target.dispatchEvent(event);
  return event;
}

function mouse(
  type: 'mousedown' | 'mouseup',
  target: EventTarget,
  detail = 1,
): MouseEvent {
  const event = new MouseEvent(type, {bubbles: true, cancelable: true, detail});
  target.dispatchEvent(event);
  return event;
}

/** A tap that a recognizer on `target` claims, by touch events. */
function claimedTap(target: HTMLElement) {
  const contact = {identifier: 1, clientX: 5, clientY: 5, target};
  for (const type of ['touchstart', 'touchend'] as const) {
    const event = new Event(type, {bubbles: true, cancelable: true});
    Object.defineProperty(event, 'changedTouches', {value: [contact]});
    Object.defineProperty(event, 'touches', {
      value: type === 'touchend' ? [] : [contact],
    });
    target.dispatchEvent(event);
  }
}

/** A `touchend` at `target`, as a browser fires it after the touch's `pointerup`. */
function touchEnd(target: EventTarget, cancelable = true): Event {
  const event = new Event('touchend', {bubbles: true, cancelable});
  target.dispatchEvent(event);
  return event;
}

function button(): HTMLButtonElement {
  const element = document.createElement('button');
  document.body.append(element);
  return element;
}

describe('clickGuard', () => {
  it("swallows the browser's next click before any page listener, once", () => {
    const target = button();
    const heard = vi.fn();
    document.addEventListener('click', heard, {capture: true});
    armClickGuard(document);
    expect(click(target).defaultPrevented).toBe(true);
    expect(heard).not.toHaveBeenCalled();
    expect(isClickGuardArmed(document)).toBe(false);
    expect(click(target).defaultPrevented).toBe(false);
    expect(heard).toHaveBeenCalledTimes(1);
    document.removeEventListener('click', heard, {capture: true});
  });

  it("keeps its place ahead of a window listener the page adds after the menu press model's first gesture: installed once per document (module:DropdownMenu/useMenuPress PR2)", () => {
    const target = button();
    armClickGuard(document, {staysInstalled: true});
    disarmClickGuard(document);
    const heard = vi.fn();
    window.addEventListener('click', heard, {capture: true});
    try {
      // A later arm, the gesture host's included, uses the staying listener.
      armClickGuard(document);
      expect(click(target).defaultPrevented).toBe(true);
      expect(heard).not.toHaveBeenCalled();
      // Disarmed, every click passes, the page's listener included.
      expect(click(target).defaultPrevented).toBe(false);
      expect(heard).toHaveBeenCalledTimes(1);
    } finally {
      window.removeEventListener('click', heard, {capture: true});
    }
  });

  it('armed by the gesture host, keeps its click listener only while armed: it goes at the click, at the next pointerdown and after its window (spec:AST-094 FR24)', () => {
    vi.useFakeTimers();
    const target = button();
    const add = vi.spyOn(window, 'addEventListener');
    const remove = vi.spyOn(window, 'removeEventListener');
    const clicks = (spy: typeof add) =>
      spy.mock.calls.filter(call => call[0] === 'click').length;
    armClickGuard(document);
    expect(clicks(add)).toBe(1);
    expect(click(target).defaultPrevented).toBe(true);
    expect(clicks(remove)).toBe(1);
    armClickGuard(document);
    target.dispatchEvent(new Event('pointerdown', {bubbles: true}));
    expect(clicks(remove)).toBe(2);
    armClickGuard(document);
    vi.advanceTimersByTime(CLICK_GUARD_WINDOW_MS);
    expect(clicks(remove)).toBe(3);
    expect(clicks(add)).toBe(3);
  });

  it("armed at a claimed touch's lift, also takes that touch's late mousedown and mouseup, until its click (spec:AST-094 FR21)", () => {
    const target = button();
    const heard = vi.fn();
    const types = ['mousedown', 'mouseup', 'click'] as const;
    for (const type of types) {
      document.addEventListener(type, heard, {capture: true});
    }
    try {
      armClickGuard(document, {takesLateMouse: true});
      expect(mouse('mousedown', target).defaultPrevented).toBe(true);
      expect(mouse('mouseup', target).defaultPrevented).toBe(true);
      expect(click(target).defaultPrevented).toBe(true);
      expect(heard).not.toHaveBeenCalled();
      // Spent at the click: the next press is the page's.
      expect(mouse('mousedown', target).defaultPrevented).toBe(false);
      expect(heard).toHaveBeenCalledTimes(1);
    } finally {
      for (const type of types) {
        document.removeEventListener(type, heard, {capture: true});
      }
    }
  });

  it("leaves mousedown and mouseup to the page on any other arm, and always lets a keyboard's or the caller's through", () => {
    const target = button();
    armClickGuard(document);
    expect(mouse('mousedown', target).defaultPrevented).toBe(false);
    expect(mouse('mouseup', target).defaultPrevented).toBe(false);
    armClickGuard(document, {takesLateMouse: true});
    expect(mouse('mousedown', target, 0).defaultPrevented).toBe(false);
    expect(
      withoutClickGuard(() => mouse('mouseup', target)).defaultPrevented,
    ).toBe(false);
    expect(isClickGuardArmed(document)).toBe(true);
  });

  it('hears mousedown and mouseup only while armed at a claimed touch, and drops them when it disarms (spec:AST-094 FR24)', () => {
    vi.useFakeTimers();
    const target = button();
    const add = vi.spyOn(window, 'addEventListener');
    const remove = vi.spyOn(window, 'removeEventListener');
    const late = (spy: typeof add) =>
      spy.mock.calls
        .map(call => call[0])
        .filter(type => type === 'mousedown' || type === 'mouseup');
    armClickGuard(document);
    expect(late(add)).toEqual([]);
    armClickGuard(document, {takesLateMouse: true});
    expect(late(add)).toEqual(['mousedown', 'mouseup']);
    target.dispatchEvent(new Event('pointerdown', {bubbles: true}));
    expect(late(remove)).toEqual(['mousedown', 'mouseup']);
    armClickGuard(document, {takesLateMouse: true});
    vi.advanceTimersByTime(CLICK_GUARD_WINDOW_MS);
    expect(late(remove)).toEqual([
      'mousedown',
      'mouseup',
      'mousedown',
      'mouseup',
    ]);
  });

  it("lets through a keyboard's or a screen reader's click, a click the caller dispatches, and the haptic switch's", () => {
    const target = button();
    armClickGuard(document);
    expect(click(target, 0).defaultPrevented).toBe(false);
    expect(withoutClickGuard(() => click(target)).defaultPrevented).toBe(false);
    const haptic = document.createElement('input');
    markHapticSwitch(haptic);
    document.body.append(haptic);
    expect(click(haptic).defaultPrevented).toBe(false);
    // Still armed for the browser's own click.
    expect(isClickGuardArmed(document)).toBe(true);
    expect(click(target).defaultPrevented).toBe(true);
  });

  it('disarms at the next pointerdown, and after its window', () => {
    vi.useFakeTimers();
    const target = button();
    armClickGuard(document);
    target.dispatchEvent(new Event('pointerdown', {bubbles: true}));
    expect(isClickGuardArmed(document)).toBe(false);
    expect(click(target).defaultPrevented).toBe(false);

    armClickGuard(document);
    vi.advanceTimersByTime(CLICK_GUARD_WINDOW_MS - 1);
    expect(isClickGuardArmed(document)).toBe(true);
    vi.advanceTimersByTime(1);
    expect(isClickGuardArmed(document)).toBe(false);
    expect(click(target).defaultPrevented).toBe(false);
  });

  it("hears pointerdown only while armed, and keeps the menu press model's one click listener", () => {
    armClickGuard(document, {staysInstalled: true});
    disarmClickGuard(document);
    const add = vi.spyOn(window, 'addEventListener');
    const remove = vi.spyOn(window, 'removeEventListener');
    armClickGuard(document);
    expect(add.mock.calls.map(call => call[0])).toEqual(['pointerdown']);
    disarmClickGuard(document);
    expect(remove.mock.calls.map(call => call[0])).toEqual(['pointerdown']);
  });

  it('is the one guard the menu press model and the gesture host arm', () => {
    // A phone: the host attaches only where the primary pointer is coarse.
    const restorePointer = coarsePrimaryPointer();
    try {
      expect(MENU_PRESS_STRAY_CLICK_MS).toBe(CLICK_GUARD_WINDOW_MS);
      // A tap the host's recognizer claims arms the shared guard for the
      // browser's click.
      const host = new GestureHost(document);
      const target = button();
      const tap = new TapGestureRecognizer({name: 'tap'});
      const detach = host.attach(target, tap);
      claimedTap(target);
      expect(isClickGuardArmed(document)).toBe(true);
      expect(click(target).defaultPrevented).toBe(true);
      detach();
    } finally {
      restorePointer();
    }
  });

  it("takes a claimed tap's late mousedown and mouseup with its click: WebKit sends them after the cancelled touchend of a held tap (spec:AST-094 FR21)", () => {
    const restorePointer = coarsePrimaryPointer();
    try {
      const host = new GestureHost(document);
      const target = button();
      const tap = new TapGestureRecognizer({name: 'tap'});
      const detach = host.attach(target, tap);
      claimedTap(target);
      expect(mouse('mousedown', target).defaultPrevented).toBe(true);
      expect(mouse('mouseup', target).defaultPrevented).toBe(true);
      expect(click(target).defaultPrevented).toBe(true);
      // The next press is the page's.
      expect(mouse('mousedown', target).defaultPrevented).toBe(false);
      detach();
    } finally {
      restorePointer();
    }
  });

  it("armed at a finger's release, cancels that touch's touchend and disarms: no click follows it", () => {
    const target = button();
    armClickGuard(document, {staysInstalled: true, cancelsTouchEnd: true});
    expect(touchEnd(target).defaultPrevented).toBe(true);
    expect(isClickGuardArmed(document)).toBe(false);
    // The next touch's touchend, and a click with no press behind it, are the page's.
    expect(touchEnd(target).defaultPrevented).toBe(false);
    expect(click(target).defaultPrevented).toBe(false);
  });

  it('leaves an uncancelable touchend alone, and stays armed for a click that may follow it', () => {
    const target = button();
    armClickGuard(document, {cancelsTouchEnd: true});
    expect(touchEnd(target, false).defaultPrevented).toBe(false);
    expect(isClickGuardArmed(document)).toBe(true);
    // Only that touch's touchend is its: a later one is the page's.
    expect(touchEnd(target).defaultPrevented).toBe(false);
    expect(click(target).defaultPrevented).toBe(true);
  });

  it('cancels no touchend on any other arm', () => {
    const target = button();
    armClickGuard(document, {staysInstalled: true});
    expect(touchEnd(target).defaultPrevented).toBe(false);
    armClickGuard(document, {takesLateMouse: true});
    expect(touchEnd(target).defaultPrevented).toBe(false);
    expect(isClickGuardArmed(document)).toBe(true);
  });

  it('hears touchend only while armed with it, and drops it at the next pointerdown and after its window', () => {
    vi.useFakeTimers();
    const target = button();
    const add = vi.spyOn(window, 'addEventListener');
    const remove = vi.spyOn(window, 'removeEventListener');
    const touchEnds = (spy: typeof add) =>
      spy.mock.calls.map(call => call[0]).filter(type => type === 'touchend');
    armClickGuard(document);
    expect(touchEnds(add)).toEqual([]);
    armClickGuard(document, {cancelsTouchEnd: true});
    expect(touchEnds(add)).toEqual(['touchend']);
    target.dispatchEvent(new Event('pointerdown', {bubbles: true}));
    expect(touchEnds(remove)).toEqual(['touchend']);
    expect(touchEnd(target).defaultPrevented).toBe(false);
    armClickGuard(document, {cancelsTouchEnd: true});
    vi.advanceTimersByTime(CLICK_GUARD_WINDOW_MS);
    expect(isClickGuardArmed(document)).toBe(false);
    expect(touchEnds(remove)).toEqual(['touchend', 'touchend']);
  });
});