Skip to content

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

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

/**
 * @file menuPressGesture.ts
 * @input A menu press gesture and one pointer event, both as plain data
 * @output The pure `menuPressStep` state machine, its state, event and effect
 *   types, the settle constant, and the finger's handoff distance
 * @position Pure module under `useMenuPress`. It has no DOM and no React, so
 *   a unit test can check each transition without a browser.
 *
 * SYNC: When modified, update:
 * - /packages/core/src/hooks/menuPressGesture.test.ts
 * - /packages/core/src/hooks/useMenuPress.ts
 */

import {MENU_PRESS_HANDOFF_PX as UIKIT_MENU_PRESS_HANDOFF_PX} from './menuPressValues';

/**
 * How long the opening press must last before its release may act, unless a
 * finger's handoff applies.
 */
export const MENU_PRESS_SETTLE_MS = 300;

/**
 * How far a finger that opened the menu travels, from the first sample the
 * menu sees, before it starts picking (UIMenu's scrub handoff).
 */
export const MENU_PRESS_HANDOFF_PX: number = UIKIT_MENU_PRESS_HANDOFF_PX;

export type MenuPressPointerType = 'mouse' | 'touch' | 'pen';

/** @internal The machine's own shape, with the finger's handoff; not public contract. */
export type MenuPressState<T> =
  | {phase: 'idle'}
  | {
      phase: 'triggerPress';
      pointerType: MenuPressPointerType;
      startedAt: number;
    }
  | {
      phase: 'open';
      pointerType: MenuPressPointerType;
      openedAt: number;
      /**
       * A finger's handoff: the first position the menu saw after it opened,
       * which the scrub distance is counted from. Unset until that sample.
       * @internal Not public contract.
       */
      handoffFrom?: {x: number; y: number};
    }
  | {
      phase: 'tracking';
      pointerType: MenuPressPointerType;
      /** Where the press began. */
      origin: 'trigger' | 'menu';
      /** The enabled row currently under the pointer, if any. */
      row: T | null;
    };

/** @internal The machine's own shape, with the finger's handoff; not public contract. */
export type MenuPressInput<T> =
  | {
      type: 'down';
      target: 'trigger' | 'menu';
      pointerType: MenuPressPointerType;
      /** The enabled row under the press when it lands inside the menu. */
      row: T | null;
      time: number;
    }
  /** The menu opened while the trigger press is still held. */
  | {type: 'opened'; time: number}
  | {
      type: 'move';
      row: T | null;
      isInMenu: boolean;
      time: number;
      /**
       * Viewport position, for a finger's handoff distance.
       * @internal Not public contract.
       */
      x?: number;
      /** @internal See `x`. */
      y?: number;
    }
  | {
      type: 'up';
      row: T | null;
      isInMenu: boolean;
      isOnTrigger: boolean;
      time: number;
      /**
       * Viewport position, for a finger's handoff distance.
       * @internal Not public contract.
       */
      x?: number;
      /** @internal See `x`. */
      y?: number;
    }
  /** The browser took the gesture: pointercancel, a second pointer, a scroll. */
  | {type: 'cancel'};

/** @internal The machine's own shape, with the finger's handoff; not public contract. */
export type MenuPressOutcome<T> =
  | {type: 'none'}
  /** A mouse pressed the trigger: open the menu now, under the held pointer. */
  | {type: 'open'}
  | {type: 'highlight'; row: T}
  | {type: 'clear'}
  | {type: 'act'; row: T}
  /**
   * The gesture ended without a row acting. `stray` says whether the browser
   * will still report a `click` for this gesture that must not act; `dismiss`
   * says the menu should close: a mouse released outside it.
   */
  | {type: 'settle'; stray: boolean; dismiss: boolean};

/** @internal The machine's own shape, with the finger's handoff; not public contract. */
export interface MenuPressTransition<T> {
  gesture: MenuPressState<T>;
  effect: MenuPressOutcome<T>;
}

export const IDLE_MENU_PRESS: MenuPressState<never> = {phase: 'idle'};

const NONE: MenuPressOutcome<never> = {type: 'none'};

function idle<T>(effect: MenuPressOutcome<T>): MenuPressTransition<T> {
  return {gesture: {phase: 'idle'}, effect};
}

function highlightEffect<T>(row: T | null): MenuPressOutcome<T> {
  return row == null ? {type: 'clear'} : {type: 'highlight', row};
}

/** A finger or a pen: UIKit's touch rules apply. */
function isFinger(pointerType: MenuPressPointerType): boolean {
  return pointerType !== 'mouse';
}

function hasPosition(event: {
  x?: number;
  y?: number;
}): event is {x: number; y: number} {
  return event.x != null && event.y != null;
}

/**
 * Whether a finger has travelled the handoff distance from `from`. The
 * distance is a straight line, as UIMenu measures it: a diagonal 7 pt each
 * way does not hand off, 9 pt each way does.
 */
function hasPassedHandoff(
  from: {x: number; y: number},
  to: {x: number; y: number},
): boolean {
  return Math.hypot(to.x - from.x, to.y - from.y) >= MENU_PRESS_HANDOFF_PX;
}

/**
 * Resolve a release while the highlight is tracking the pointer: over an
 * enabled row it acts, over the menu's chrome it acts on nothing, outside the
 * menu it acts on nothing and — under a mouse — dismisses the menu (a
 * finger leaves it open). A release back on the trigger never dismisses.
 */
function release<T>(
  pointerType: MenuPressPointerType,
  event: Extract<MenuPressInput<T>, {type: 'up'}>,
): MenuPressTransition<T> {
  if (event.row != null) {
    return idle({type: 'act', row: event.row});
  }
  if (event.isInMenu || event.isOnTrigger) {
    return idle({type: 'settle', stray: true, dismiss: false});
  }
  return idle({type: 'settle', stray: true, dismiss: pointerType === 'mouse'});
}

/**
 * Advance the gesture by one event. Pure: same inputs, same output.
 *
 * The row under the pointer at the release acts, and the highlight follows
 * the held pointer, as in macOS and iOS menus. The states:
 * - `idle`: no gesture is live.
 * - `triggerPress`: a finger rests on the trigger, and the menu is not open
 *   yet. A mouse press on the trigger skips this state and opens at once.
 * - `open`: the menu opened under a held pointer, and the pointer does not
 *   pick yet.
 * - `tracking`: the pointer is held, and the highlight follows it.
 *
 * A finger or a pen that opened the menu picks only after it travels
 * `MENU_PRESS_HANDOFF_PX` from the first position the menu sees. UIMenu
 * hands off the same way. Until then nothing lights, and its lift acts on
 * nothing. A host that reports no positions keeps the settle rule.
 *
 * The settle rule: the release of the opening gesture acts only after the
 * pointer entered the menu or the press lasted `MENU_PRESS_SETTLE_MS`. Else a
 * menu that opens under the pointer would pick a row that nobody chose.
 *
 * Rows are opaque (`T`). The hook feeds in the enabled row under the
 * pointer, or `null` over a divider, a heading, a disabled row, or outside
 * the menu.
 *
 * @internal The machine's own shape, with the finger's handoff; not public
 * contract.
 */
export function menuPressTransition<T>(
  gesture: MenuPressState<T>,
  event: MenuPressInput<T>,
): MenuPressTransition<T> {
  switch (gesture.phase) {
    case 'idle':
      return stepIdle(gesture, event);
    case 'triggerPress':
      return stepTriggerPress(gesture, event);
    case 'open':
      return stepOpen(gesture, event);
    case 'tracking':
      return stepTracking(gesture, event);
  }
}

function stepIdle<T>(
  gesture: Extract<MenuPressState<T>, {phase: 'idle'}>,
  event: MenuPressInput<T>,
): MenuPressTransition<T> {
  if (event.type !== 'down') {
    return {gesture, effect: NONE};
  }
  if (event.target === 'menu') {
    return {
      gesture: {
        phase: 'tracking',
        pointerType: event.pointerType,
        origin: 'menu',
        row: event.row,
      },
      effect: highlightEffect(event.row),
    };
  }
  if (event.pointerType === 'mouse') {
    return {
      gesture: {
        phase: 'open',
        pointerType: 'mouse',
        openedAt: event.time,
      },
      effect: {type: 'open'},
    };
  }
  return {
    gesture: {
      phase: 'triggerPress',
      pointerType: event.pointerType,
      startedAt: event.time,
    },
    effect: NONE,
  };
}

function stepTriggerPress<T>(
  gesture: Extract<MenuPressState<T>, {phase: 'triggerPress'}>,
  event: MenuPressInput<T>,
): MenuPressTransition<T> {
  switch (event.type) {
    case 'opened':
      return {
        gesture: {
          phase: 'open',
          pointerType: gesture.pointerType,
          openedAt: event.time,
        },
        effect: NONE,
      };
    case 'up':
      // A tap. The browser's click on the trigger is what opens the menu, so
      // it must pass, and no gesture is live afterwards.
      return idle({type: 'settle', stray: false, dismiss: false});
    case 'cancel':
      // The browser took the gesture, for example for a system gesture.
      // Settle and do not go idle: a held finger installed the document's
      // touchmove preventer, and only the end of a gesture removes it. No
      // click follows a cancelled pointer.
      return idle({type: 'settle', stray: false, dismiss: false});
    case 'down':
    case 'move':
      return {gesture, effect: NONE};
  }
}

function stepOpen<T>(
  gesture: Extract<MenuPressState<T>, {phase: 'open'}>,
  event: MenuPressInput<T>,
): MenuPressTransition<T> {
  switch (event.type) {
    case 'move': {
      if (isFinger(gesture.pointerType) && hasPosition(event)) {
        // UIMenu counts from the first sample after the open, not from the
        // open point.
        const from = gesture.handoffFrom;
        if (from == null) {
          return {
            gesture: {...gesture, handoffFrom: {x: event.x, y: event.y}},
            effect: NONE,
          };
        }
        if (!hasPassedHandoff(from, event)) {
          return {gesture, effect: NONE};
        }
        return {
          gesture: {
            phase: 'tracking',
            pointerType: gesture.pointerType,
            origin: 'trigger',
            row: event.row,
          },
          effect: highlightEffect(event.row),
        };
      }
      if (!event.isInMenu) {
        return {gesture, effect: NONE};
      }
      return {
        gesture: {
          phase: 'tracking',
          pointerType: gesture.pointerType,
          origin: 'trigger',
          row: event.row,
        },
        effect: highlightEffect(event.row),
      };
    }
    case 'up': {
      if (isFinger(gesture.pointerType) && hasPosition(event)) {
        // The finger never travelled the handoff distance, so the row under it
        // appeared under a press nobody moved. Nothing acts, the menu stays,
        // and the trigger's click for this press is spent.
        return idle({type: 'settle', stray: true, dismiss: false});
      }
      const hasSettled = event.time - gesture.openedAt >= MENU_PRESS_SETTLE_MS;
      if (!hasSettled) {
        // The pointer never entered the menu and the press was short: the
        // menu stays open and nothing acts. The trigger's own click for this
        // gesture must not toggle it shut either.
        return idle({type: 'settle', stray: true, dismiss: false});
      }
      return release(gesture.pointerType, event);
    }
    case 'cancel':
      // As above: the gesture ends, so its document listeners come off. The
      // menu stays open: a cancelled pointer did not ask to close it.
      return idle({type: 'settle', stray: false, dismiss: false});
    case 'down':
    case 'opened':
      return {gesture, effect: NONE};
  }
}

function stepTracking<T>(
  gesture: Extract<MenuPressState<T>, {phase: 'tracking'}>,
  event: MenuPressInput<T>,
): MenuPressTransition<T> {
  switch (event.type) {
    case 'move':
      if (event.row === gesture.row) {
        return {gesture, effect: NONE};
      }
      return {
        gesture: {...gesture, row: event.row},
        effect: highlightEffect(event.row),
      };
    case 'up':
      return release(gesture.pointerType, event);
    case 'cancel':
      // The browser took the gesture (a scroll, a second finger): nothing
      // acts, the menu stays, and no click follows a cancelled pointer.
      return idle({type: 'settle', stray: false, dismiss: false});
    case 'down':
    case 'opened':
      return {gesture, effect: NONE};
  }
}

// ---------------------------------------------------------------------------
// The released public shape (`@astryxdesign/core/hooks`). The handoff
// positions and `handoffFrom` stay internal: a caller of
// `menuPressStep` keeps the settle rule, as released.
// ---------------------------------------------------------------------------

export type MenuPressGesture<T> =
  | {phase: 'idle'}
  | {
      phase: 'triggerPress';
      pointerType: MenuPressPointerType;
      startedAt: number;
    }
  | {
      phase: 'open';
      pointerType: MenuPressPointerType;
      openedAt: number;
    }
  | {
      phase: 'tracking';
      pointerType: MenuPressPointerType;
      /** Where the press began. */
      origin: 'trigger' | 'menu';
      /** The enabled row currently under the pointer, if any. */
      row: T | null;
    };

export type MenuPressEvent<T> =
  | {
      type: 'down';
      target: 'trigger' | 'menu';
      pointerType: MenuPressPointerType;
      /** The enabled row under the press when it lands inside the menu. */
      row: T | null;
      time: number;
    }
  /** The menu opened while the trigger press is still held. */
  | {type: 'opened'; time: number}
  | {type: 'move'; row: T | null; isInMenu: boolean; time: number}
  | {
      type: 'up';
      row: T | null;
      isInMenu: boolean;
      isOnTrigger: boolean;
      time: number;
    }
  /** The browser took the gesture: pointercancel, a second pointer, a scroll. */
  | {type: 'cancel'};

export type MenuPressEffect<T> =
  | {type: 'none'}
  /** A mouse pressed the trigger: open the menu now, under the held pointer. */
  | {type: 'open'}
  | {type: 'highlight'; row: T}
  | {type: 'clear'}
  | {type: 'act'; row: T}
  /**
   * The gesture ends without a row acting. Its `stray` flag is true when the
   * browser still sends a `click` for this gesture. That click must not act.
   * Its `dismiss` flag is true when the menu must close (a mouse released
   * outside it).
   */
  | {type: 'settle'; stray: boolean; dismiss: boolean};

export interface MenuPressStep<T> {
  gesture: MenuPressGesture<T>;
  effect: MenuPressEffect<T>;
}

/**
 * The menu press machine, as released: one step from a gesture and an event
 * to the next gesture and the effect to apply. Pure.
 */
export function menuPressStep<T>(
  gesture: MenuPressGesture<T>,
  event: MenuPressEvent<T>,
): MenuPressStep<T> {
  // The released machine keeps the settle rule. Positions start the handoff,
  // so a caller's event reaches the transition without them.
  const {
    x: _x,
    y: _y,
    ...released
  } = event as MenuPressEvent<T> & {x?: number; y?: number};
  const {gesture: next, effect} = menuPressTransition(
    gesture,
    released as MenuPressEvent<T>,
  );
  return {
    gesture: publicGesture(next),
    effect,
  };
}

function publicGesture<T>(gesture: MenuPressState<T>): MenuPressGesture<T> {
  if (gesture.phase !== 'open') {
    return gesture;
  }
  return {
    phase: 'open',
    pointerType: gesture.pointerType,
    openedAt: gesture.openedAt,
  };
}