Skip to content

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

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

/**
 * @file haptics.ts
 * @input A feedback kind, or a label element a real finger will tap
 * @output Exports playHaptic (vibration where the platform has it),
 *   attachTapHaptic (iOS Safari's tap-moment light impact) and the support
 *   probes
 * @position Haptics of packages/core/src/gestures; the kinds and the
 *   vibration patterns live in the constants table (motion/uikit/gestures.ts)
 *
 * The web has one haptics API, `navigator.vibrate`, and iOS Safari does not
 * implement it. iOS Safari does play a haptic in exactly one place: when a
 * REAL tap toggles an `<input type="checkbox" switch>`, by landing on the
 * switch or on a `<label>` tied to it (and during a native drag-flip of the
 * switch). That haptic is UIImpactFeedbackGenerator(.light). WebKit requires
 * a user gesture AND a trusted event for it: a `label.click()` from script
 * does not play it (WebKit bug 309082, May 2026), so nothing can fire a
 * haptic later from JavaScript, and mid-drag haptics (detent snaps, picker
 * ticks) cannot exist in iOS Safari.
 *
 * So there are two tools:
 *
 * - `attachTapHaptic(label)` puts a visually hidden switch inside a label the
 *   control renders as its tap target: every real tap on the label plays the
 *   light impact at the moment of the tap. The switch itself never takes the
 *   touch (`pointer-events: none`; WebKit marks a switch's `touchstart`
 *   handled, which would stop a pan starting on it from scrolling the page),
 *   its own events never bubble to the page (capture-phase listeners still
 *   see its click; the gesture host's click swallower skips it by
 *   attribute), and focus the label's activation gives it goes straight
 *   back, so a later Space never toggles it. A label tied to its control
 *   by `for`, or whose control is itself a switch, gets no switch; a label
 *   wrapping its own control gets one, which hands each tap on to it.
 * - `playHaptic(kind)` vibrates where `navigator.vibrate` exists (Android
 *   browsers) with the kind's pattern, and does nothing elsewhere.
 *
 * UIKit's haptics follow the system setting, not Reduce Motion, so neither
 * tool consults `prefers-reduced-motion`.
 */

import {
  HAPTIC_VIBRATION_PATTERNS,
  type HapticFeedbackKind,
} from '../motion/uikit/gestures';
import {isDisabledControl} from '../utils/pressDisabled';
import {markHapticSwitch} from '../privateAttributes/hapticSwitch.stylex';
import {isHTMLElement} from '../utils/nodeType';

/** Whether this browser vibrates at all. */
export function canVibrate(): boolean {
  return (
    typeof navigator !== 'undefined' && typeof navigator.vibrate === 'function'
  );
}

/** Whether this browser knows the switch control (Safari 17.4 and later). */
export function supportsSwitchControl(doc?: Document): boolean {
  const target = doc ?? (typeof document === 'undefined' ? null : document);
  if (target == null) {
    return false;
  }
  const input = target.createElement('input');
  input.type = 'checkbox';
  return 'switch' in input;
}

/**
 * Vibrate for a feedback kind where `navigator.vibrate` exists. Returns
 * whether anything was played. Never plays on iOS, which has no vibration
 * API; use `attachTapHaptic` for the tap moment there.
 */
export function playHaptic(kind: HapticFeedbackKind): boolean {
  if (!canVibrate()) {
    return false;
  }
  return navigator.vibrate([...HAPTIC_VIBRATION_PATTERNS[kind].value]);
}

const VISUALLY_HIDDEN =
  'position:absolute;width:1px;height:1px;margin:-1px;padding:0;border:0;' +
  'overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);white-space:nowrap;' +
  'opacity:0;pointer-events:none;';

let nextLabelId = 0;

/** Whether `input` is a switch checkbox, which plays the tap haptic itself. */
function isSwitch(input: HTMLInputElement): boolean {
  return input.type === 'checkbox' && input.hasAttribute('switch');
}

function swallow(event: Event): void {
  event.stopPropagation();
}

/**
 * Make every real tap on `label` play iOS Safari's light impact, by giving it
 * a hidden switch to toggle. Returns a function that removes the switch.
 * Harmless where switches have no haptics.
 *
 * - The switch never keeps the focus: where a label's activation focuses
 *   its control (Chromium), the focus goes on to the label's own control,
 *   or back where it was, so it never lands on an `aria-hidden` element.
 * - A label that already has a control keeps it: the switch takes the
 *   label's activation (it goes first) and hands the click on to that
 *   control, so the tap plays and the control still toggles. The control
 *   keeps its name too: while the switch is attached it is labelled by the
 *   label through `aria-labelledby`, unless it already names itself. A control
 *   that is itself a switch plays on its own, and a label tied to its
 *   control by `for` cannot be given a second one: both are left as they
 *   are.
 */
export function attachTapHaptic(label: HTMLLabelElement): () => void {
  const existing = label.control;
  if (
    (isHTMLElement(existing) &&
      existing.localName === 'input' &&
      isSwitch(existing as HTMLInputElement)) ||
    (existing != null && label.htmlFor !== '')
  ) {
    return () => {};
  }
  const doc = label.ownerDocument;
  const input = doc.createElement('input');
  input.type = 'checkbox';
  input.setAttribute('switch', '');
  markHapticSwitch(input);
  input.setAttribute('aria-hidden', 'true');
  input.tabIndex = -1;
  input.style.cssText = VISUALLY_HIDDEN;
  // The label's activation clicks the switch, and that click would bubble
  // through the control as a second click: keep it, and the switch's
  // change events, inside. A label with a control of its own gets that
  // click handed on, so the control still toggles.
  // A disabled control gives no feedback (spec:AST-094 FR23): its label's
  // activation neither toggles the switch, so nothing plays, nor reaches
  // the control.
  const onClick = (event: Event) => {
    event.stopPropagation();
    if (existing != null && isDisabledControl(existing)) {
      event.preventDefault();
      return;
    }
    existing?.click();
  };
  const onFocus = (event: FocusEvent) => {
    const previous = event.relatedTarget;
    if (
      isHTMLElement(existing) &&
      existing.tabIndex >= 0 &&
      !isDisabledControl(existing)
    ) {
      existing.focus({preventScroll: true});
    }
    if (doc.activeElement !== input) {
      return;
    }
    if (isHTMLElement(previous) && previous.isConnected) {
      previous.focus({preventScroll: true});
    }
    if (doc.activeElement === input) {
      input.blur();
    }
  };
  input.addEventListener('click', onClick);
  input.addEventListener('change', swallow);
  input.addEventListener('input', swallow);
  input.addEventListener('focus', onFocus);
  // The switch becomes the label's control, so the control the label named
  // is named through `aria-labelledby` instead (the switch is aria-hidden,
  // so the label's text is the name).
  let labelledControl: HTMLElement | null = null;
  let addedLabelId = false;
  if (existing != null) {
    label.prepend(input);
    if (
      isHTMLElement(existing) &&
      !existing.hasAttribute('aria-labelledby') &&
      !existing.hasAttribute('aria-label')
    ) {
      if (label.id === '') {
        label.id = `astryx-haptic-label-${(nextLabelId += 1)}`;
        addedLabelId = true;
      }
      existing.setAttribute('aria-labelledby', label.id);
      labelledControl = existing;
    }
  } else {
    label.appendChild(input);
  }
  return () => {
    labelledControl?.removeAttribute('aria-labelledby');
    if (addedLabelId) {
      label.removeAttribute('id');
    }
    input.removeEventListener('click', onClick);
    input.removeEventListener('change', swallow);
    input.removeEventListener('input', swallow);
    input.removeEventListener('focus', onFocus);
    input.remove();
  };
}