Skip to content

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

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

'use client';

/**
 * @file gestureCounter.ts
 * @input Pointer and context-menu events through the shared input stream;
 *   keydown and click on the document
 * @output Exports the gesture identity, whether its click has run, whether a
 *   press is down, and the press claims (claimPress, claimContextMenuPress)
 * @position Internal to the package, not exported. useLayer reads it to tell
 *   a click that belongs to a dismissing press from a fresh one.
 *   useTouchTrigger, useMenuPress, ContextMenu and DropdownMenu read the
 *   gesture too. A layer or a menu that opens on a press claims that press
 *   here
 *
 * A browser light-dismiss and the trigger's own click come from ONE press, and
 * which of them React sees first is a race. Comparing timestamps against a
 * window guesses; counting gestures does not. The counter advances on every
 * new press or keystroke, so "the click from the gesture that dismissed the
 * layer" is exactly "the click while the counter still reads what it read at
 * the dismissal", no matter how long the main thread was blocked in between.
 */

import {subscribeInput} from '../utils/inputStream';

let gesture = 0;
let clickedGesture: number | null = null;
let contextMenuGesture: number | null = null;
let pressPointerId: number | null = null;
let claimedPress: {
  layer: HTMLElement;
  pointerId: number;
  gesture: number;
} | null = null;
let isListening = false;

function advance() {
  gesture += 1;
}

let unsubscribePress: (() => void) | null = null;

// The page listens for a press's end and its context menu only while a press
// is down, so at rest it keeps no pointerup listener of its own.
function startPress(event: PointerEvent) {
  advance();
  pressPointerId = event.pointerId;
  const view = event.view ?? document.defaultView;
  if (unsubscribePress != null || view == null) {
    return;
  }
  const unsubscribes = [
    subscribeInput(view, 'pointerup', endPress, {first: true}),
    subscribeInput(view, 'pointercancel', endPress, {first: true}),
    subscribeInput(view, 'contextmenu', markContextMenu, {first: true}),
  ];
  unsubscribePress = () => {
    for (const unsubscribe of unsubscribes) {
      unsubscribe();
    }
  };
}

function endPress() {
  pressPointerId = null;
  unsubscribePress?.();
  unsubscribePress = null;
}

function markContextMenu() {
  contextMenuGesture = gesture;
}

function markClicked() {
  clickedGesture = gesture;
}

function listen() {
  if (isListening || typeof document === 'undefined') {
    return;
  }
  isListening = true;
  // Capture phase: the count must advance before any handler reads it.
  const view = document.defaultView;
  if (view != null) {
    subscribeInput(view, 'pointerdown', startPress, {first: true});
  }
  document.addEventListener('keydown', advance, true);
  // Capture phase observes the click even when a consumer stops propagation.
  document.addEventListener('click', markClicked, true);
}

/**
 * Identifies the user gesture in flight. Two reads returning the same value
 * happened within one press (or one keystroke).
 */
export function currentGesture(): number {
  listen();
  return gesture;
}

/** Whether the click belonging to the current gesture already bubbled. */
export function currentGestureHasClicked(): boolean {
  listen();
  return clickedGesture === gesture;
}

/** Whether a press is down, its release not yet seen by the page. */
export function isPressInFlight(): boolean {
  listen();
  return pressPointerId !== null;
}

/**
 * Keeps the release of the press in flight from dismissing `layer`. The
 * browser's light dismiss reads a release outside every open popover as a
 * dismissal, also the release of the press that opened the popover. While the
 * pointer is outside the layer, the layer captures it, so a release there
 * lands on the layer. Over the layer the capture lets go, so hover works and a
 * release there is inside anyway. The claim ends at that press's release, or
 * when the layer closes; a later press dismisses as usual. A second claim of
 * the same press for the same layer does nothing.
 *
 * `releaseTarget` is the control the press began on, which the caller keeps
 * as the popover's invoker. It holds the pointer while the pointer is over
 * it, so its own pointerup and click still reach it. It still gets them when
 * it moves away under a pointer that stays still.
 */
export function claimPress(
  layer: HTMLElement,
  {releaseTarget = null}: {releaseTarget?: HTMLElement | null} = {},
): void {
  listen();
  const pointerId = pressPointerId;
  const view = layer.ownerDocument.defaultView;
  if (pointerId === null || view == null) {
    return;
  }
  if (
    claimedPress !== null &&
    claimedPress.layer === layer &&
    claimedPress.pointerId === pointerId &&
    claimedPress.gesture === gesture
  ) {
    return;
  }
  const claim = {layer, pointerId, gesture};
  claimedPress = claim;
  // Gives the pointer to `holder`, or lets it go when `holder` is null.
  const holdCapture = (holder: HTMLElement | null) => {
    try {
      if (holder !== null) {
        holder.setPointerCapture(pointerId);
        return;
      }
      for (const element of [layer, releaseTarget]) {
        if (element?.hasPointerCapture(pointerId) === true) {
          element.releasePointerCapture(pointerId);
        }
      }
    } catch {
      // The pointer is no longer active (its release did not reach the
      // page), so no release can dismiss the layer.
    }
  };
  // The press began on the release target, so the pointer is over it now.
  holdCapture(releaseTarget ?? layer);
  // A move of the pointer reads no layout. The claim reads the layer's box,
  // and the box of each popover open in it (a sub-menu), once. It reads them
  // again only after a scroll, a resize or a toggle in the layer.
  let boxes: DOMRect[] | null = null;
  const readBoxes = (): DOMRect[] => {
    let nested: HTMLElement[] = [];
    try {
      nested = [...layer.querySelectorAll<HTMLElement>(':popover-open')];
    } catch {
      // An engine without `:popover-open` has no nested popover to read.
    }
    return [layer, ...nested].map(el => el.getBoundingClientRect());
  };
  const isOverLayer = (x: number, y: number): boolean => {
    boxes ??= readBoxes();
    return boxes.some(
      box => x >= box.left && x < box.right && y >= box.top && y < box.bottom,
    );
  };
  let targetBox: DOMRect | null = null;
  const isOverTarget = (x: number, y: number): boolean => {
    targetBox ??= releaseTarget?.getBoundingClientRect() ?? null;
    if (targetBox === null) {
      return false;
    }
    return (
      x >= targetBox.left &&
      x < targetBox.right &&
      y >= targetBox.top &&
      y < targetBox.bottom
    );
  };
  const invalidate = () => {
    boxes = null;
    targetBox = null;
  };
  const followPointer = (event: PointerEvent) => {
    if (event.pointerId === pointerId) {
      const {clientX: x, clientY: y} = event;
      if (isOverLayer(x, y)) {
        holdCapture(null);
      } else if (releaseTarget !== null && isOverTarget(x, y)) {
        holdCapture(releaseTarget);
      } else {
        holdCapture(layer);
      }
    }
  };
  const unsubscribes: (() => void)[] = [];
  const stop = () => {
    for (const unsubscribe of unsubscribes) {
      unsubscribe();
    }
    unsubscribes.length = 0;
    if (claimedPress === claim) {
      claimedPress = null;
    }
  };
  const endClaim = (event: PointerEvent) => {
    if (event.pointerId === pointerId) {
      stop();
    }
  };
  // A layer that closes while the button is still down lets the pointer go,
  // so the page under it hovers again.
  const onToggle = (event: Event) => {
    if (
      event.target === layer &&
      (event as Event & {newState?: string}).newState === 'closed'
    ) {
      holdCapture(null);
      stop();
      return;
    }
    invalidate();
  };
  layer.addEventListener('toggle', onToggle, true);
  unsubscribes.push(
    subscribeInput(view, 'pointermove', followPointer),
    subscribeInput(view, 'pointerup', endClaim),
    subscribeInput(view, 'pointercancel', endClaim),
    subscribeInput(view, 'scroll', invalidate),
    subscribeInput(view, 'resize', invalidate),
    () => layer.removeEventListener('toggle', onToggle, true),
  );
}

/**
 * Claims the press in flight for `layer` (`claimPress`) when that press opened
 * a context menu (a right click).
 */
export function claimContextMenuPress(layer: HTMLElement): void {
  listen();
  if (contextMenuGesture === gesture) {
    claimPress(layer);
  }
}