Skip to content

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

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

'use client';

/**
 * @file touchHitArea.ts
 * @input Whether an element takes taps, how it grows, the shared touch hit
 *   area (utils/hitArea.ts) and the Web Animations around the element
 * @output `useTouchHitArea`, a callback ref that keeps an element's hit insets
 *   live for its invisible layer (`touchHitAreaStyles.layer`)
 * @position Core-internal hook for the coarse-only 44 px target. List rows,
 *   InfoTip, CheckboxInput, RadioListItem, SegmentedControl segments and the
 *   press-tracking groups use it, and so can any control whose target outgrows
 *   its box under a finger.
 *
 * SYNC: When modified, update internal/touchHitArea.stylex.ts and
 * touchHitArea.test.tsx.
 */

import {useCallback, type RefCallback} from 'react';
import {
  MIN_TOUCH_TARGET,
  NO_HIT_INSETS,
  watchHitArea,
  writeHitInsets,
  type HitInsets,
  type HitRect,
} from './hitArea';

/** How an owner's element grows, for an owner with its own rule. */
export interface TouchHitAreaOptions {
  /**
   * How far the element grows on each side before any neighbour stops it,
   * read as `watchHitArea`'s `growth`. It also gets the element. A group
   * passes `groupGrowth` of its members.
   * @default toward 44 px on each axis, centered
   */
  readonly growth?: (
    target: HitRect,
    toLayout: (rect: HitRect) => HitRect,
    element: HTMLElement,
  ) => HitInsets;
  /**
   * Whether a finger's press on the element re-measures it against every
   * interactive element on the page. An owner that reads its own targets
   * when a press begins turns it off.
   * @default true
   */
  readonly checkAtPress?: boolean;
  /**
   * Whether a finger's press that lands on a descendant is the element's,
   * however near a neighbour is, read as `watchHitArea`'s
   * `ownsDescendantTouches`. An owner that draws the band on a descendant,
   * and whose content never paints past its box, turns it off, so a band
   * press nearer a neighbour is not the element's.
   * @default true
   */
  readonly ownsDescendantTouches?: boolean;
}

const NO_OPTIONS: TouchHitAreaOptions = {};

/**
 * The finite animations running or held in the element's parent, the element
 * included: a row's own motion and its neighbors'. An endless one (a spinner)
 * moves nothing that comes to rest, so it holds nothing.
 */
function settlingAnimations(element: HTMLElement): Animation[] {
  const scope = element.parentElement ?? element;
  if (typeof scope.getAnimations !== 'function') {
    return [];
  }
  return scope.getAnimations({subtree: true}).filter(animation => {
    if (animation.playState !== 'running' && animation.playState !== 'paused') {
      return false;
    }
    const end = animation.effect?.getComputedTiming().endTime;
    return typeof end === 'number' && Number.isFinite(end);
  });
}

/**
 * Watches `element` and takes its insets only at rest. Returns the stop.
 *
 * Under a coarse primary pointer, the shared utility measures how far the
 * element's hit target may grow without reaching a neighbor's half of the
 * gap. This writes those insets on the element, where its layer reads them.
 * Under a fine pointer the shared utility starts no observer.
 *
 * Elements move by transform: a list row in an update's slide, a swipe, or
 * neighbors that slide past. The shared measurement reads them as they stand
 * in one frame. So a measurement that arrives while the parent has a finite
 * animation running or held is dropped. When those animations end, the
 * element is watched again. The insets are then taken at rest, and no frame
 * of a compositor-only motion lays out or paints for them.
 */
function watchAtRest(
  element: HTMLElement,
  minSize: number,
  {growth, checkAtPress, ownsDescendantTouches = true}: TouchHitAreaOptions,
): () => void {
  let stopWatch = (): void => {};
  let isStopped = false;
  let isWaiting = false;
  let hasWritten = false;
  // A stopped watch clears the insets it wrote. A fresh watch skips a
  // measurement equal to its start, zero, so old insets would otherwise stay.
  // A watch that wrote nothing, as under a mouse, writes nothing.
  const stop = (): void => {
    stopWatch();
    if (hasWritten) {
      hasWritten = false;
      writeHitInsets(element, NO_HIT_INSETS);
    }
  };
  const watch = (): void => {
    stopWatch = watchHitArea(
      element,
      insets => {
        const moving = settlingAnimations(element);
        if (moving.length === 0) {
          hasWritten = true;
          writeHitInsets(element, insets);
          return;
        }
        if (isWaiting) {
          return;
        }
        isWaiting = true;
        void Promise.allSettled(
          moving.map(async animation => animation.finished),
        ).then(() => {
          isWaiting = false;
          if (!isStopped) {
            stop();
            watch();
          }
        });
      },
      // By default the layer is the host's own `::after`, so a touch on the
      // host's content is the host's, even where that content paints past
      // its box.
      {
        minSize,
        ownsDescendantTouches,
        growth:
          growth == null
            ? undefined
            : (target, toLayout) => growth(target, toLayout, element),
        checkAtPress,
      },
    );
  };
  watch();
  return () => {
    isStopped = true;
    stop();
  };
}

/** The watch on an element, and how many attached refs hold it. */
interface HeldWatch {
  readonly stop: () => void;
  holders: number;
}

const heldWatches = new WeakMap<HTMLElement, HeldWatch>();

/**
 * Holds the element's watch, and starts it on the first hold. Returns the
 * release. A ref that changes, such as a merge with a caller's inline ref,
 * detaches and attaches again in one commit. So the last release waits a
 * microtask, and an attach in between keeps the watch and its insets.
 */
function holdWatch(
  element: HTMLElement,
  options: TouchHitAreaOptions,
): () => void {
  let held = heldWatches.get(element);
  if (held == null) {
    held = {
      stop: watchAtRest(element, MIN_TOUCH_TARGET, options),
      holders: 0,
    };
    heldWatches.set(element, held);
  }
  held.holders += 1;
  const entry = held;
  let isReleased = false;
  return () => {
    if (isReleased) {
      return;
    }
    isReleased = true;
    entry.holders -= 1;
    queueMicrotask(() => {
      if (entry.holders === 0 && heldWatches.get(element) === entry) {
        heldWatches.delete(element);
        entry.stop();
      }
    });
  };
}

/**
 * A callback ref that keeps its element's hit insets live while `enabled`:
 * the element takes taps, so it is interactive and not disabled or read-only.
 * Merge it into the element's ref, and pair it with `touchHitAreaStyles.layer`
 * on the same element, or on a descendant with `ownsDescendantTouches` off.
 * The watch lasts while the element is attached, so a replaced element starts
 * its own. A re-render that hands the same element a
 * new merged ref keeps its watch. `options` set how the element grows. Keep
 * them stable, as a module constant. An element's first holder sets them.
 *
 * @example
 * ```
 * const hitAreaRef = useTouchHitArea(isInteractive && !isDisabled);
 * <li ref={hitAreaRef} {...stylex.props(isInteractive && touchHitAreaStyles.layer)} />
 * ```
 */
export function useTouchHitArea(
  enabled: boolean,
  options: TouchHitAreaOptions = NO_OPTIONS,
): RefCallback<HTMLElement> {
  // Syncs with an external system: the shared touch hit area
  // (utils/hitArea.ts) measures the element against its neighbors and writes
  // its insets on it. The ref's cleanup stops the watch.
  return useCallback(
    (element: HTMLElement | null) => {
      if (!enabled || element == null) {
        return undefined;
      }
      return holdWatch(element, options);
    },
    [enabled, options],
  );
}