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

package/src/gestures/SwipeGestureRecognizer.ts

@@ -0,0 +1,197 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SwipeGestureRecognizer.ts
+ * @input Touches from a GestureArena
+ * @output Exports SwipeGestureRecognizer (UISwipeGestureRecognizer), its
+ *   options and direction type
+ * @position Discrete recognizer of packages/core/src/gestures
+ *
+ * Recognized WHILE the fingers move, as UIKit's is: as soon as the centroid
+ * has travelled `minimumDistance` along an allowed direction, within
+ * `maximumDuration` of touch-down, with off-axis travel no more than
+ * `maximumSecondaryMovement` px across it. Off-axis travel past that
+ * allowance, or the distance travelled the wrong way, rules a direction out;
+ * the swipe fails once every allowed direction is ruled out, as it does for
+ * too many fingers, the duration running out, and a lift before it was
+ * recognized.
+ */
+
+import {UIKIT_SWIPE} from '../motion/uikit/gestures';
+import {centroid} from './geometry';
+import {
+  GestureRecognizer,
+  type GestureRecognizerOptions,
+  type NativeTouchBehavior,
+} from './GestureRecognizer';
+import type {GestureEventContext, GestureTouch, Point} from './types';
+
+export type SwipeDirection = 'left' | 'right' | 'up' | 'down';
+
+export interface SwipeGestureRecognizerOptions extends GestureRecognizerOptions<SwipeGestureRecognizer> {
+  /** @default ['right'] */
+  direction?: SwipeDirection | ReadonlyArray<SwipeDirection>;
+  /** @default 1 */
+  numberOfTouchesRequired?: number;
+  minimumDistance?: number;
+  maximumDuration?: number;
+  maximumSecondaryMovement?: number;
+}
+
+const SWIPE = UIKIT_SWIPE;
+
+export class SwipeGestureRecognizer extends GestureRecognizer {
+  override get kind(): GestureRecognizer['kind'] {
+    return 'swipe';
+  }
+
+  directions: ReadonlyArray<SwipeDirection>;
+  numberOfTouchesRequired: number;
+  minimumDistance: number;
+  maximumDuration: number;
+  maximumSecondaryMovement: number;
+  /** The direction of the recognized swipe. */
+  recognizedDirection: SwipeDirection | null = null;
+
+  private origin: Point = {x: 0, y: 0};
+  /** Directions this touch's path has ruled out. */
+  private readonly ruledOut = new Set<SwipeDirection>();
+  /** The centroid at the previous move. */
+  private last: Point | null = null;
+
+  constructor(options: SwipeGestureRecognizerOptions = {}) {
+    super(options);
+    const direction = options.direction ?? ['right'];
+    this.directions = typeof direction === 'string' ? [direction] : direction;
+    this.numberOfTouchesRequired = options.numberOfTouchesRequired ?? 1;
+    this.minimumDistance =
+      options.minimumDistance ?? SWIPE.minimumDistance.value;
+    this.maximumDuration =
+      options.maximumDuration ?? SWIPE.maximumDuration.value;
+    this.maximumSecondaryMovement =
+      options.maximumSecondaryMovement ?? SWIPE.maximumSecondaryMovement.value;
+  }
+
+  override get isDiscrete(): boolean {
+    return true;
+  }
+
+  override get nativeTouchBehavior(): NativeTouchBehavior {
+    const horizontal = this.directions.some(
+      direction => direction === 'left' || direction === 'right',
+    );
+    const vertical = this.directions.some(
+      direction => direction === 'up' || direction === 'down',
+    );
+    return {
+      panX: !horizontal,
+      panY: !vertical,
+      pinchZoom: true,
+      doubleTapZoom: false,
+    };
+  }
+
+  protected override touchesBegan(
+    touches: ReadonlyArray<GestureTouch>,
+    event: GestureEventContext,
+  ): void {
+    if (this.numberOfTouches > this.numberOfTouchesRequired) {
+      this.setState('failed');
+      return;
+    }
+    if (this.numberOfTouches === touches.length) {
+      this.setTimer(event.time + this.maximumDuration, () => {
+        // A swipe already recognized, waiting on a recognizer it requires to
+        // fail, holds its recognition (spec:AST-094 FR15).
+        if (this.pending == null) {
+          this.setState('failed');
+        }
+      });
+    }
+    // Measure from where every required finger is down.
+    this.origin = centroid(this.touches.values());
+    this.last = null;
+  }
+
+  protected override touchesMoved(): void {
+    if (
+      this.pending != null ||
+      this.numberOfTouches !== this.numberOfTouchesRequired
+    ) {
+      return;
+    }
+    const current = centroid(this.touches.values());
+    const from = this.last ?? this.origin;
+    this.last = current;
+    for (const direction of this.directions) {
+      if (this.ruledOut.has(direction)) {
+        continue;
+      }
+      // Along and across this direction at the start and the end of the
+      // move. The path between two events is read as a straight segment, so
+      // the verdict does not depend on how far apart the events were.
+      const [along0, across0] = this.project(direction, from);
+      const [along1, across1] = this.project(direction, current);
+      const reaches = segmentCrossing(along0, along1, this.minimumDistance);
+      const strays = Math.max(
+        segmentCrossing(across0, across1, this.maximumSecondaryMovement),
+        segmentCrossing(-across0, -across1, this.maximumSecondaryMovement),
+      );
+      const strayAt = strays < 0 ? Infinity : strays;
+      if (reaches >= 0 && reaches <= strayAt) {
+        this.recognizedDirection = direction;
+        this.setState('ended');
+        return;
+      }
+      // Off-axis travel past the allowance, or the distance the wrong way,
+      // rules a direction out for good.
+      if (strays >= 0 || along1 <= -this.minimumDistance) {
+        this.ruledOut.add(direction);
+      }
+    }
+    if (this.directions.every(direction => this.ruledOut.has(direction))) {
+      this.setState('failed');
+    }
+  }
+
+  /** Travel along and across `direction` from the origin to `point`. */
+  private project(direction: SwipeDirection, point: Point): [number, number] {
+    const dx = point.x - this.origin.x;
+    const dy = point.y - this.origin.y;
+    return direction === 'left'
+      ? [-dx, dy]
+      : direction === 'right'
+        ? [dx, dy]
+        : direction === 'up'
+          ? [-dy, dx]
+          : [dy, dx];
+  }
+
+  protected override touchesEnded(): void {
+    // Recognized and waiting, it holds past the lift (FR15).
+    if (this.pending == null) {
+      this.setState('failed');
+    }
+  }
+
+  protected override reset(): void {
+    this.recognizedDirection = null;
+    this.ruledOut.clear();
+    this.last = null;
+    this.origin = {x: 0, y: 0};
+  }
+}
+
+/**
+ * Where on the segment from `start` to `end` (0 to 1) the value first
+ * reaches `limit`; 0 when it starts there, -1 when it never does.
+ */
+function segmentCrossing(start: number, end: number, limit: number): number {
+  if (start >= limit) {
+    return 0;
+  }
+  if (end < limit) {
+    return -1;
+  }
+  return (limit - start) / (end - start);
+}

package/src/gestures/TapGestureRecognizer.ts

@@ -43,6 +43,10 @@ export interface TapGestureRecognizerOptions extends GestureRecognizerOptions<Ta
 const TAP = UIKIT_TAP;
 
 export class TapGestureRecognizer extends GestureRecognizer {
+  override get kind(): GestureRecognizer['kind'] {
+    return 'tap';
+  }
+
   numberOfTapsRequired: number;
   numberOfTouchesRequired: number;
   allowableMovement: number;

package/src/gestures/VelocityTracker.ts

@@ -88,15 +88,22 @@ export class VelocityTracker {
    * Record a position. Timestamps must not go backwards (an older sample is
    * ignored), and a moved sample at the newest moved sample's timestamp
    * replaces it. A sample at the newest position is not motion: it changes
-   * no velocity.
+   * no velocity, unless `isMotion` says the contact moved anyway (a pinch's
+   * value holding while both fingers move, which reads as zero velocity for
+   * that interval).
    */
-  add(x: number, y: number, time: number): void {
+  add(
+    x: number,
+    y: number,
+    time: number,
+    {isMotion = false}: {isMotion?: boolean} = {},
+  ): void {
     if (this.newest != null && time < this.newest.time) {
       return;
     }
     this.newest = {x, y, time};
     const last = this.moved[this.moved.length - 1];
-    if (last != null && x === last.x && y === last.y) {
+    if (last != null && x === last.x && y === last.y && !isMotion) {
       return;
     }
     if (last != null && time === last.time) {

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';