@astryxdesign/core 0.7.5 → 0.7.6-canary.0d71e8d

package/src/gestures/haptics.ts

@@ -0,0 +1,203 @@
+// 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),
+ *   and its own events never reach the page.
+ * - `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';
+
+/** Marks the hidden switch, so click handlers can recognize and ignore it. */
+export const HAPTIC_SWITCH_ATTRIBUTE = 'data-astryx-haptic-switch';
+
+/** 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;
+
+/** A native disabled control, or one marked `aria-disabled`. */
+function isDisabledControl(control: HTMLElement): boolean {
+  return (
+    control.matches(':disabled') ||
+    control.getAttribute('aria-disabled') === 'true'
+  );
+}
+
+/** 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 (
+    (existing instanceof HTMLInputElement && isSwitch(existing)) ||
+    (existing != null && label.htmlFor !== '')
+  ) {
+    return () => {};
+  }
+  const doc = label.ownerDocument;
+  const input = doc.createElement('input');
+  input.type = 'checkbox';
+  input.setAttribute('switch', '');
+  input.setAttribute(HAPTIC_SWITCH_ATTRIBUTE, '');
+  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 (
+      existing instanceof HTMLElement &&
+      existing.tabIndex >= 0 &&
+      !isDisabledControl(existing)
+    ) {
+      existing.focus({preventScroll: true});
+    }
+    if (doc.activeElement !== input) {
+      return;
+    }
+    if (previous instanceof HTMLElement && 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 (
+      existing instanceof HTMLElement &&
+      !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();
+  };
+}

package/src/gestures/index.ts

@@ -0,0 +1,79 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input The modules of packages/core/src/gestures
+ * @output Re-exports the gesture system for core's own components
+ * @position Core's own barrel. Not exported from the package.
+ */
+
+export {GestureArena, browserClock} from './GestureArena';
+export type {
+  ArenaBeganInput,
+  ClickDisposition,
+  GestureArenaOptions,
+  GestureClock,
+} from './GestureArena';
+export {GestureHost, getGestureHost} from './GestureHost';
+export type {AttachOptions, GestureHostOptions} from './GestureHost';
+export {
+  GestureRecognizer,
+  isActive,
+  isTerminal,
+  isTransitionAllowed,
+} from './GestureRecognizer';
+export type {
+  GestureListener,
+  GestureRecognizerOptions,
+  GestureTransitionListener,
+  NativeTouchBehavior,
+} from './GestureRecognizer';
+export {
+  attachTapHaptic,
+  canVibrate,
+  playHaptic,
+  supportsSwitchControl,
+} from './haptics';
+export {LongPressGestureRecognizer} from './LongPressGestureRecognizer';
+export type {LongPressGestureRecognizerOptions} from './LongPressGestureRecognizer';
+export {createNativeScrollProbe, parseTouchAction} from './nativeScroll';
+export {PanGestureRecognizer} from './PanGestureRecognizer';
+export type {
+  PanDirection,
+  PanGestureRecognizerOptions,
+} from './PanGestureRecognizer';
+export {PinchGestureRecognizer} from './PinchGestureRecognizer';
+export type {PinchGestureRecognizerOptions} from './PinchGestureRecognizer';
+export {PRESS_PROFILES, createPressTracker} from './PressTracker';
+export type {
+  ControlEvent,
+  PressBounds,
+  PressHighlightDelay,
+  PressProfile,
+  PressProfileName,
+  PressTracker,
+  PressTrackerOptions,
+} from './PressTracker';
+export {ScreenEdgePanGestureRecognizer} from './ScreenEdgePanGestureRecognizer';
+export type {
+  ScreenEdge,
+  ScreenEdgePanGestureRecognizerOptions,
+} from './ScreenEdgePanGestureRecognizer';
+export {SwipeGestureRecognizer} from './SwipeGestureRecognizer';
+export type {
+  SwipeDirection,
+  SwipeGestureRecognizerOptions,
+} from './SwipeGestureRecognizer';
+export {TapGestureRecognizer} from './TapGestureRecognizer';
+export type {TapGestureRecognizerOptions} from './TapGestureRecognizer';
+export {deriveTouchAction, gestureHostStyle} from './touchAction';
+export type {GestureHostStyle} from './touchAction';
+export type * from './types';
+export {DEFAULT_ENVIRONMENT} from './types';
+export {useGestureRecognizer, usePressTracker} from './useGestureRecognizer';
+export type {
+  UseGestureRecognizerOptions,
+  UsePressTrackerOptions,
+} from './useGestureRecognizer';
+export {VelocityTracker} from './VelocityTracker';
+export type {VelocityTrackerOptions} from './VelocityTracker';

package/src/gestures/nativeScroll.ts

@@ -0,0 +1,277 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file nativeScroll.ts
+ * @input An element a touch landed on
+ * @output Exports createNativeScrollProbe (the NativeScrollProbe a host gives
+ *   each touch) and parseTouchAction
+ * @position DOM half of the scroll coordination in packages/core/src/gestures
+ *
+ * Answers one question for a recognizer without letting it touch the DOM:
+ * would the browser scroll something if this finger moved that way?
+ *
+ * The browser scrolls the innermost scroller that has room, then chains
+ * outward, so the answer is "yes" while ANY scroller under the touch can
+ * still move in that direction, with three narrowings that match the
+ * browser's own:
+ *
+ * - `touch-action` between the touch target and a scroller must allow the
+ *   axis, or the browser will not pan that scroller with a finger;
+ * - an `overscroll-behavior` other than `auto` on the axis stops the chain at
+ *   that scroller (a sheet body with `contain` never scrolls the page);
+ * - a finger moving down scrolls content toward its START (scrollTop
+ *   decreasing), and horizontally the range follows the writing direction
+ *   (RTL `scrollLeft` runs from minus the overflow to zero).
+ *
+ * Styles are read once per touch, on the first question; scroll offsets are
+ * read fresh on every question, since a native scroll moves them.
+ */
+
+import type {NativeScrollProbe} from './types';
+
+export interface AllowedPans {
+  readonly x: boolean;
+  readonly y: boolean;
+}
+
+/** Which pans a `touch-action` value lets the browser perform. */
+export function parseTouchAction(value: string): AllowedPans {
+  const tokens = value.trim().split(/\s+/);
+  if (tokens.includes('auto') || tokens.includes('manipulation')) {
+    return {x: true, y: true};
+  }
+  if (tokens.includes('none')) {
+    return {x: false, y: false};
+  }
+  return {
+    x: tokens.some(
+      token =>
+        token === 'pan-x' || token === 'pan-left' || token === 'pan-right',
+    ),
+    y: tokens.some(
+      token => token === 'pan-y' || token === 'pan-up' || token === 'pan-down',
+    ),
+  };
+}
+
+interface ChainEntry {
+  readonly element: Element;
+  readonly x: boolean;
+  readonly y: boolean;
+  readonly isRtl: boolean;
+  readonly stopsX: boolean;
+  readonly stopsY: boolean;
+  /**
+   * The scroller sits beyond a `position: fixed` ancestor of the touch: it
+   * still scrolls under the finger, but it does not carry the touched
+   * element, so the element is not inside a scroll view (spec:AST-094 FR11).
+   */
+  readonly isBeyondFixed: boolean;
+}
+
+const SCROLLABLE = new Set(['auto', 'scroll', 'overlay']);
+const EDGE_TOLERANCE = 1;
+
+/**
+ * The node's parent in the flat tree: a slotted node's slot, then out of
+ * shadow roots to their hosts, so a scroller inside a shadow tree around the
+ * slot is found.
+ */
+export function parentAcrossShadow(node: Node): Node | null {
+  const slot =
+    node instanceof Element || node instanceof Text ? node.assignedSlot : null;
+  if (slot != null) {
+    return slot;
+  }
+  if (node.parentNode != null) {
+    return node.parentNode instanceof ShadowRoot
+      ? node.parentNode.host
+      : node.parentNode;
+  }
+  return null;
+}
+
+interface Chain {
+  readonly entries: ChainEntry[];
+  /** touch-action allows some pan all the way up. */
+  readonly allowsPan: boolean;
+}
+
+function buildChain(target: Element): Chain {
+  const doc = target.ownerDocument;
+  const view = doc.defaultView;
+  if (view == null) {
+    return {entries: [], allowsPan: false};
+  }
+  const root = doc.scrollingElement ?? doc.documentElement;
+  const chain: ChainEntry[] = [];
+  let allowX = true;
+  let allowY = true;
+  let reachedRoot = false;
+  let isBeyondFixed = false;
+  for (
+    let node: Node | null = target;
+    node != null;
+    node = parentAcrossShadow(node)
+  ) {
+    if (!(node instanceof Element)) {
+      continue;
+    }
+    const style = view.getComputedStyle(node);
+    const pans = parseTouchAction(style.touchAction || 'auto');
+    allowX &&= pans.x;
+    allowY &&= pans.y;
+    const isRoot = node === root || node === doc.documentElement;
+    if (isRoot) {
+      reachedRoot = true;
+    }
+    const overflowX = isRoot ? rootOverflow(doc, 'x') : style.overflowX;
+    const overflowY = isRoot ? rootOverflow(doc, 'y') : style.overflowY;
+    const scrollsX = SCROLLABLE.has(overflowX);
+    const scrollsY = SCROLLABLE.has(overflowY);
+    if (scrollsX || scrollsY) {
+      const element = isRoot ? root : node;
+      const [behaviorX, behaviorY] = overscrollBehavior(style);
+      chain.push({
+        element,
+        x: scrollsX && allowX,
+        y: scrollsY && allowY,
+        isRtl: style.direction === 'rtl',
+        stopsX: behaviorX !== 'auto',
+        stopsY: behaviorY !== 'auto',
+        isBeyondFixed,
+      });
+    }
+    if (isRoot) {
+      break;
+    }
+    if (style.position === 'fixed') {
+      isBeyondFixed = true;
+    }
+  }
+  if (!reachedRoot && root instanceof Element) {
+    chain.push({
+      element: root,
+      x: allowX && SCROLLABLE.has(rootOverflow(doc, 'x')),
+      y: allowY && SCROLLABLE.has(rootOverflow(doc, 'y')),
+      isRtl: false,
+      stopsX: false,
+      stopsY: false,
+      isBeyondFixed,
+    });
+  }
+  return {entries: chain, allowsPan: allowX || allowY};
+}
+
+/** `overscroll-behavior` per axis, from the longhands or the shorthand. */
+function overscrollBehavior(style: CSSStyleDeclaration): [string, string] {
+  const x = style.overscrollBehaviorX;
+  const y = style.overscrollBehaviorY;
+  if (x !== '' && y !== '' && x != null && y != null) {
+    return [x, y];
+  }
+  const [first = 'auto', second = first] = (
+    style.getPropertyValue('overscroll-behavior') || 'auto'
+  )
+    .trim()
+    .split(/\s+/);
+  return [x || first, y || second];
+}
+
+/**
+ * The viewport scrolls unless the root or the body clips it (a scroll lock
+ * sets `overflow: hidden` on one of them).
+ */
+function rootOverflow(doc: Document, axis: 'x' | 'y'): string {
+  const view = doc.defaultView;
+  if (view == null) {
+    return 'hidden';
+  }
+  for (const element of [doc.documentElement, doc.body]) {
+    if (element == null) {
+      continue;
+    }
+    const style = view.getComputedStyle(element);
+    const value = axis === 'x' ? style.overflowX : style.overflowY;
+    if (value === 'hidden' || value === 'clip') {
+      return 'hidden';
+    }
+  }
+  return 'auto';
+}
+
+function canMoveY(element: Element, dy: number): boolean {
+  if (element.scrollHeight - element.clientHeight <= EDGE_TOLERANCE) {
+    return false;
+  }
+  return dy > 0
+    ? element.scrollTop > EDGE_TOLERANCE - 0.5
+    : element.scrollTop <
+        element.scrollHeight - element.clientHeight - EDGE_TOLERANCE + 0.5;
+}
+
+function canMoveX(entry: ChainEntry, dx: number): boolean {
+  const {element} = entry;
+  const overflow = element.scrollWidth - element.clientWidth;
+  if (overflow <= EDGE_TOLERANCE) {
+    return false;
+  }
+  const min = entry.isRtl ? -overflow : 0;
+  const max = entry.isRtl ? 0 : overflow;
+  // A finger moving right drags the content right: scrollLeft decreases.
+  return dx > 0
+    ? element.scrollLeft > min + EDGE_TOLERANCE - 0.5
+    : element.scrollLeft < max - EDGE_TOLERANCE + 0.5;
+}
+
+/** A probe of the native scrollers under `target`. */
+export function createNativeScrollProbe(target: unknown): NativeScrollProbe {
+  let chain: Chain | null = null;
+  const getChain = (): ChainEntry[] => {
+    chain ??=
+      target instanceof Element
+        ? buildChain(target)
+        : {entries: [], allowsPan: false};
+    return chain.entries;
+  };
+  return {
+    canScroll(dx: number, dy: number): boolean {
+      const ax = Math.abs(dx);
+      const ay = Math.abs(dy);
+      // The minor axis of a mostly-straight drag is the hand's wobble, not
+      // a direction: the browser locks to the major one.
+      const considerX = ax > 0 && ax >= ay / 2;
+      const considerY = ay > 0 && ay >= ax / 2;
+      for (const entry of getChain()) {
+        if (considerY && entry.y && canMoveY(entry.element, dy)) {
+          return true;
+        }
+        if (considerX && entry.x && canMoveX(entry, dx)) {
+          return true;
+        }
+        const stops =
+          (!considerX || entry.stopsX) && (!considerY || entry.stopsY);
+        if (stops && (entry.stopsX || entry.stopsY)) {
+          return false;
+        }
+      }
+      return false;
+    },
+    get allowsNativePan(): boolean {
+      getChain();
+      return chain?.allowsPan === true;
+    },
+    get isInsideScroller(): boolean {
+      return getChain().some(
+        entry =>
+          !entry.isBeyondFixed &&
+          ((entry.y &&
+            entry.element.scrollHeight - entry.element.clientHeight >
+              EDGE_TOLERANCE) ||
+            (entry.x &&
+              entry.element.scrollWidth - entry.element.clientWidth >
+                EDGE_TOLERANCE)),
+      );
+    },
+  };
+}