Skip to content

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

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

'use client';

/**
 * @file useGroupPressTracking.ts
 * @input A group's root ref and whether the group tracks presses: under the
 *   touch presentation only
 * @output useGroupPressTracking: the press tracking that ButtonGroup and
 *   ToggleButtonGroup share; GROUP_PRESS_POINTERS, the pointers it follows
 * @position Internal hook, not exported from the hooks entry. It drives
 *   useActionGroupTracking and the shared touch hit area (useTouchHitArea)
 *   for a group's members. Each group's root applies
 *   touchHitAreaStyles.layerBelowChildren. AlertDialog's tracking follows
 *   GROUP_PRESS_POINTERS too.
 *
 * SYNC: When modified, update ButtonGroupTracking.test.tsx and
 * ToggleButtonGroupTracking.test.tsx.
 */

import type {RefCallback, RefObject} from 'react';
import type {GestureTouch} from '../gestures/types';
import {isPressGroupItem} from '../privateAttributes/pressGroupItem.stylex';
import {groupGrowth} from '../utils/hitArea';
import {useTouchHitArea, type TouchHitAreaOptions} from '../utils/touchHitArea';
import {
  DISABLED_SELECTOR,
  measureActions,
  type ActionGroupTarget,
} from './actionGroupTracker';
import {
  measureNeighbours,
  resolveNearestAction,
  useActionGroupTracking,
} from './useActionGroupTracking';

/** What a member Button renders. The tracker keeps the marked ones. */
const MEMBER_ELEMENTS = 'button, a[href]';

/**
 * Whether `box` has an area. A hidden member's box is empty, at the
 * viewport's corner, so it neither tracks a press nor grows a target.
 */
function hasArea(box: Omit<ActionGroupTarget, 'element'>): boolean {
  return box.right > box.left && box.bottom > box.top;
}

/** Whether the group tracks `member`, read without its box. */
function isTrackedMember(member: Element): boolean {
  return isPressGroupItem(member) && !member.matches(DISABLED_SELECTOR);
}

/**
 * The tracked, enabled members with a box, each box read once. The tracker
 * measures its actions with the same function.
 */
function trackedTargets(group: HTMLElement): ActionGroupTarget[] {
  return measureActions([group], MEMBER_ELEMENTS, isTrackedMember).filter(
    hasArea,
  );
}

/**
 * The group's hit area. Each side grows as far as the members on that edge
 * would. The tracker reads the members when a press begins, so a press reads
 * nothing else on the page.
 */
const GROUP_HIT_AREA: TouchHitAreaOptions = {
  growth: (box, toLayout, group) =>
    groupGrowth(box, trackedTargets(group).map(toLayout)),
  checkAtPress: false,
};

/**
 * Whether the group takes `touch`'s press. It takes one on an enabled tracked
 * member. A press on a disabled member keeps its click, so its tooltip can
 * open. It takes a finger's press on its own box or hit layer only where a
 * member's grown target holds it. Any other press keeps its own click, so a
 * tap beside the members of a wide group reaches the page. A member the group
 * does not track, such as a menu trigger, keeps its own press. A group with
 * no box takes none.
 */
function takesPress(group: HTMLElement | null, touch: GestureTouch): boolean {
  const {target} = touch;
  // A node check, not `instanceof`: the group may render in another window.
  if (group == null || (target as Node | null)?.nodeType !== 1) {
    return false;
  }
  const box = group.getBoundingClientRect();
  if (box.width <= 0 || box.height <= 0) {
    return false;
  }
  if (target !== group) {
    const member = (target as Element).closest(MEMBER_ELEMENTS);
    return member != null && group.contains(member) && isTrackedMember(member);
  }
  return (
    touch.pointerType === 'touch' &&
    resolveNearestAction(
      touch.startX,
      touch.startY,
      trackedTargets(group),
      // The tracked members are read once above, so the neighbour test reads
      // only the others.
      measureNeighbours(group, {
        itemSelector: MEMBER_ELEMENTS,
        isItem: isTrackedMember,
      }),
    ) != null
  );
}

export interface GroupPressTracking {
  /**
   * Merge into the group's root: it keeps the hit layer's insets live. While
   * the group tracks presses, the root applies
   * `touchHitAreaStyles.layerBelowChildren` and is positioned, as the layer's
   * containing block.
   */
  readonly hitAreaRef: RefCallback<HTMLElement>;
}

/** The pointers a group's press slides for: a finger and a pen. */
export const GROUP_PRESS_POINTERS = ['touch', 'pen'] as const;

/**
 * Track a held finger or pen across the marked members of the group behind
 * `ref`, while `isEnabled`. The member under it highlights at once, and the
 * lift runs it through its own click. A finger picks the nearest member whose
 * grown target holds it.
 */
export function useGroupPressTracking(
  ref: RefObject<HTMLElement | null>,
  isEnabled: boolean,
): GroupPressTracking {
  useActionGroupTracking(ref, {
    itemSelector: MEMBER_ELEMENTS,
    // A disabled member is the tracker's neighbour. A hidden member has no box,
    // so it is no item.
    isItem: member =>
      isTrackedMember(member) && hasArea(member.getBoundingClientRect()),
    pointerTypes: GROUP_PRESS_POINTERS,
    highlightOnsetMs: 0,
    highlightExpansion: 0,
    resolveTarget: resolveNearestAction,
    shouldTrack: touch => takesPress(ref.current, touch),
    isEnabled,
  });
  // A finger's target grows toward 44 px through the hit layer, not the
  // members. A finger just past a small member lands on the layer, and the
  // tracker picks that member. The shared watch grows a target only under a
  // coarse primary pointer.
  const hitAreaRef = useTouchHitArea(isEnabled, GROUP_HIT_AREA);
  return {hitAreaRef};
}