Skip to content

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

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

/**
 * @file touchAction.ts
 * @input The recognizers attached to one element
 * @output Exports deriveTouchAction (the element's `touch-action`),
 *   gestureHostStyle (the inline style a host sets for its recognizers) and
 *   intersectTouchAction (what both a derived and a caller's value allow).
 *   The selection and callout lock for one held press is the recognizer's
 *   own `selectionLock` (gestures/selectionLock.ts), which the host calls
 * @position Browser negotiation of packages/core/src/gestures, pure so a
 *   server render can emit the same style the client would set
 *
 * `touch-action` is decided when the finger lands and cannot change during
 * the gesture, so it must say up front what the browser may still do: the
 * intersection of what every recognizer on the element leaves it.
 *
 * - A tap or long press only removes double-tap zoom (`manipulation`): no
 *   300 ms click delay, scrolling and pinch-zoom untouched.
 * - A one-axis pan or swipe gives the browser the other axis.
 * - A pan that coordinates with native scrolling (`scrollEdge`) keeps both
 *   axes: who gets the drag is decided once, when it begins, and a drag the
 *   browser began scrolling stays the browser's to the lift (`spec:AST-094`
 *   FR14).
 * - `pinch-zoom` stays in every value unless a pinch recognizer is attached,
 *   so the page stays zoomable (WCAG 1.4.4).
 *
 * WebKit pans a drag with any vertical component even under `pan-y`, so the
 * value alone does not protect a horizontal pan there: the host also cancels
 * `touchmove` while a recognizer owns the touch (see GestureHost.ts).
 */

import type {GestureRecognizer, NativeTouchBehavior} from './GestureRecognizer';
import {internals} from './recognizerInternals';

/**
 * The intersection of what each touch recognizer leaves the browser. A
 * watcher (`claimsTouches: false`) never takes a touch, so it leaves the
 * browser everything: its direction restricts no scroll (`spec:AST-094`
 * FR20, DEC-7).
 */
export function combinedNativeBehavior(
  recognizers: ReadonlyArray<GestureRecognizer>,
): NativeTouchBehavior {
  let panX = true;
  let panY = true;
  let pinchZoom = true;
  let doubleTapZoom = true;
  for (const recognizer of recognizers) {
    if (!internals(recognizer).acceptsTouchInput || !recognizer.claimsTouches) {
      continue;
    }
    const behavior = recognizer.nativeTouchBehavior;
    panX &&= behavior.panX;
    panY &&= behavior.panY;
    pinchZoom &&= behavior.pinchZoom;
    doubleTapZoom &&= behavior.doubleTapZoom;
  }
  return {panX, panY, pinchZoom, doubleTapZoom};
}

/** The `touch-action` value for a set of recognizers, or null for none needed. */
export function deriveTouchAction(
  recognizers: ReadonlyArray<GestureRecognizer>,
): string | null {
  const behavior = combinedNativeBehavior(recognizers);
  if (
    behavior.panX &&
    behavior.panY &&
    behavior.pinchZoom &&
    behavior.doubleTapZoom
  ) {
    return null;
  }
  if (behavior.panX && behavior.panY && behavior.pinchZoom) {
    return 'manipulation';
  }
  const tokens: string[] = [];
  if (behavior.panX) {
    tokens.push('pan-x');
  }
  if (behavior.panY) {
    tokens.push('pan-y');
  }
  if (behavior.pinchZoom) {
    tokens.push('pinch-zoom');
  }
  return tokens.length === 0 ? 'none' : tokens.join(' ');
}

export interface GestureHostStyle {
  touchAction?: string;
  WebkitTouchCallout?: string;
  WebkitUserSelect?: string;
  userSelect?: string;
}

/**
 * The style a host sets for these recognizers while they are attached: the
 * `touch-action`. Text selection is not locked here: a mouse, a keyboard and
 * assistive technology keep selecting as they do today (spec:AST-017 FR59,
 * spec:AST-094 FR41).
 */
export function gestureHostStyle(
  recognizers: ReadonlyArray<GestureRecognizer>,
): GestureHostStyle {
  const style: GestureHostStyle = {};
  const touchAction = deriveTouchAction(recognizers);
  if (touchAction != null) {
    style.touchAction = touchAction;
  }
  return style;
}

/** What a `touch-action` value lets the browser do, as tokens. */
const ALL_PANS = [
  'pan-left',
  'pan-right',
  'pan-up',
  'pan-down',
  'pinch-zoom',
] as const;

function touchActionTokens(value: string): Set<string> {
  const parts = value
    .trim()
    .split(/\s+/)
    .filter(part => part !== '');
  const tokens = new Set<string>();
  if (parts.length === 0) {
    parts.push('auto');
  }
  for (const part of parts) {
    if (part === 'auto') {
      ALL_PANS.forEach(token => tokens.add(token));
      tokens.add('double-tap-zoom');
    } else if (part === 'manipulation') {
      ALL_PANS.forEach(token => tokens.add(token));
    } else if (part === 'pan-x') {
      tokens.add('pan-left').add('pan-right');
    } else if (part === 'pan-y') {
      tokens.add('pan-up').add('pan-down');
    } else if ((ALL_PANS as ReadonlyArray<string>).includes(part)) {
      tokens.add(part);
    }
  }
  return tokens;
}

/**
 * The `touch-action` that allows only what both values allow: the host's
 * derived value never overrides a caller's narrower one.
 */
export function intersectTouchAction(derived: string, caller: string): string {
  const own = touchActionTokens(caller);
  const both = new Set(
    [...touchActionTokens(derived)].filter(token => own.has(token)),
  );
  if (ALL_PANS.every(token => both.has(token))) {
    return both.has('double-tap-zoom') ? 'auto' : 'manipulation';
  }
  const parts: string[] = [];
  for (const [axis, start, end] of [
    ['pan-x', 'pan-left', 'pan-right'],
    ['pan-y', 'pan-up', 'pan-down'],
  ] as const) {
    if (both.has(start) && both.has(end)) {
      parts.push(axis);
    } else if (both.has(start)) {
      parts.push(start);
    } else if (both.has(end)) {
      parts.push(end);
    }
  }
  if (both.has('pinch-zoom')) {
    parts.push('pinch-zoom');
  }
  return parts.length === 0 ? 'none' : parts.join(' ');
}