@amazon-devices/react-native-gesture-handler 2.0.1759135970 → 4.0.0

package/src/handlers/gestures/gestureStateManager.ts

@@ -7,56 +7,70 @@ export interface GestureStateManagerType {
   activate: () => void;
   fail: () => void;
   end: () => void;
+  /** @internal */
+  handlerTag: number;
 }
 
 const warningMessage = tagMessage(
   'react-native-reanimated is required in order to use synchronous state management'
 );
 
-// check if reanimated module is available, but look for useSharedValue as conditional
+// Check if reanimated module is available, but look for useSharedValue as conditional
 // require of reanimated can sometimes return content of `utils.ts` file (?)
 const REANIMATED_AVAILABLE = Reanimated?.useSharedValue !== undefined;
 const setGestureState = Reanimated?.setGestureState;
 
+function create(handlerTag: number): GestureStateManagerType {
+  'worklet';
+  return {
+    handlerTag,
+
+    begin: () => {
+      'worklet';
+      if (REANIMATED_AVAILABLE) {
+        // When Reanimated is available, setGestureState should be defined
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        setGestureState!(handlerTag, State.BEGAN);
+      } else {
+        console.warn(warningMessage);
+      }
+    },
+
+    activate: () => {
+      'worklet';
+      if (REANIMATED_AVAILABLE) {
+        // When Reanimated is available, setGestureState should be defined
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        setGestureState!(handlerTag, State.ACTIVE);
+      } else {
+        console.warn(warningMessage);
+      }
+    },
+
+    fail: () => {
+      'worklet';
+      if (REANIMATED_AVAILABLE) {
+        // When Reanimated is available, setGestureState should be defined
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        setGestureState!(handlerTag, State.FAILED);
+      } else {
+        console.warn(warningMessage);
+      }
+    },
+
+    end: () => {
+      'worklet';
+      if (REANIMATED_AVAILABLE) {
+        // When Reanimated is available, setGestureState should be defined
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        setGestureState!(handlerTag, State.END);
+      } else {
+        console.warn(warningMessage);
+      }
+    },
+  };
+}
+
 export const GestureStateManager = {
-  create(handlerTag: number): GestureStateManagerType {
-    'worklet';
-    return {
-      begin: () => {
-        'worklet';
-        if (REANIMATED_AVAILABLE) {
-          setGestureState(handlerTag, State.BEGAN);
-        } else {
-          console.warn(warningMessage);
-        }
-      },
-
-      activate: () => {
-        'worklet';
-        if (REANIMATED_AVAILABLE) {
-          setGestureState(handlerTag, State.ACTIVE);
-        } else {
-          console.warn(warningMessage);
-        }
-      },
-
-      fail: () => {
-        'worklet';
-        if (REANIMATED_AVAILABLE) {
-          setGestureState(handlerTag, State.FAILED);
-        } else {
-          console.warn(warningMessage);
-        }
-      },
-
-      end: () => {
-        'worklet';
-        if (REANIMATED_AVAILABLE) {
-          setGestureState(handlerTag, State.END);
-        } else {
-          console.warn(warningMessage);
-        }
-      },
-    };
-  },
+  create,
 };

package/src/handlers/gestures/gestureStateManager.web.ts

@@ -4,12 +4,14 @@ import { GestureStateManagerType } from './gestureStateManager';
 export const GestureStateManager = {
   create(handlerTag: number): GestureStateManagerType {
     return {
+      handlerTag,
+
       begin: () => {
         NodeManager.getHandler(handlerTag).begin();
       },
 
       activate: () => {
-        NodeManager.getHandler(handlerTag).activate();
+        NodeManager.getHandler(handlerTag).activate(true);
       },
 
       fail: () => {

package/src/handlers/gestures/hoverGesture.ts

@@ -1,12 +1,6 @@
 import { BaseGestureConfig, ContinousBaseGesture } from './gesture';
 import { GestureUpdateEvent } from '../gestureHandlerCommon';
-
-export type HoverGestureHandlerEventPayload = {
-  x: number;
-  y: number;
-  absoluteX: number;
-  absoluteY: number;
-};
+import type { HoverGestureHandlerEventPayload } from '../GestureHandlerEventPayload';
 
 export type HoverGestureChangeEventPayload = {
   changeX: number;
@@ -59,8 +53,8 @@ export class HoverGesture extends ContinousBaseGesture<
   }
 
   /**
+   * #### iOS only
    * Sets the visual hover effect.
-   * iOS only
    */
   effect(effect: HoverEffect) {
     this.config.hoverEffect = effect;

package/src/handlers/gestures/longPressGesture.ts

@@ -1,8 +1,6 @@
 import { BaseGesture, BaseGestureConfig } from './gesture';
-import {
-  LongPressGestureConfig,
-  LongPressGestureHandlerEventPayload,
-} from '../LongPressGestureHandler';
+import { LongPressGestureConfig } from '../LongPressGestureHandler';
+import type { LongPressGestureHandlerEventPayload } from '../GestureHandlerEventPayload';
 
 export class LongPressGesture extends BaseGesture<LongPressGestureHandlerEventPayload> {
   public config: BaseGestureConfig & LongPressGestureConfig = {};
@@ -14,15 +12,34 @@ export class LongPressGesture extends BaseGesture<LongPressGestureHandlerEventPa
     this.shouldCancelWhenOutside(true);
   }
 
+  /**
+   * Minimum time, expressed in milliseconds, that a finger must remain pressed on the corresponding view.
+   * The default value is 500.
+   * @param duration
+   */
   minDuration(duration: number) {
     this.config.minDurationMs = duration;
     return this;
   }
 
+  /**
+   * Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a long press gesture.
+   * @param distance
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/long-press-gesture#maxdistancevalue-number
+   */
   maxDistance(distance: number) {
     this.config.maxDist = distance;
     return this;
   }
+
+  /**
+   * Determine exact number of points required to handle the long press gesture.
+   * @param pointers
+   */
+  numberOfPointers(pointers: number) {
+    this.config.numberOfPointers = pointers;
+    return this;
+  }
 }
 
 export type LongPressGestureType = InstanceType<typeof LongPressGesture>;

package/src/handlers/gestures/nativeGesture.ts

@@ -1,8 +1,6 @@
 import { BaseGestureConfig, BaseGesture } from './gesture';
-import {
-  NativeViewGestureConfig,
-  NativeViewGestureHandlerPayload,
-} from '../NativeViewGestureHandler';
+import { NativeViewGestureConfig } from '../NativeViewGestureHandler';
+import type { NativeViewGestureHandlerPayload } from '../GestureHandlerEventPayload';
 
 export class NativeGesture extends BaseGesture<NativeViewGestureHandlerPayload> {
   public config: BaseGestureConfig & NativeViewGestureConfig = {};
@@ -13,11 +11,19 @@ export class NativeGesture extends BaseGesture<NativeViewGestureHandlerPayload>
     this.handlerName = 'NativeViewGestureHandler';
   }
 
+  /**
+   * When true, underlying handler will activate unconditionally when in `BEGAN` or `UNDETERMINED` state.
+   * @param value
+   */
   shouldActivateOnStart(value: boolean) {
     this.config.shouldActivateOnStart = value;
     return this;
   }
 
+  /**
+   * When true, cancels all other gesture handlers when this `NativeViewGestureHandler` receives an `ACTIVE` state event.
+   * @param value
+   */
   disallowInterruption(value: boolean) {
     this.config.disallowInterruption = value;
     return this;

package/src/handlers/gestures/panGesture.ts

@@ -1,9 +1,7 @@
 import { BaseGestureConfig, ContinousBaseGesture } from './gesture';
 import { GestureUpdateEvent } from '../gestureHandlerCommon';
-import {
-  PanGestureConfig,
-  PanGestureHandlerEventPayload,
-} from '../PanGestureHandler';
+import { PanGestureConfig } from '../PanGestureHandler';
+import type { PanGestureHandlerEventPayload } from '../GestureHandlerEventPayload';
 
 export type PanGestureChangeEventPayload = {
   changeX: number;
@@ -43,7 +41,14 @@ export class PanGesture extends ContinousBaseGesture<
     this.handlerName = 'PanGestureHandler';
   }
 
-  activeOffsetY(offset: number | number[]) {
+  /**
+   * Range along Y axis (in points) where fingers travels without activation of gesture.
+   * @param offset
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/pan-gesture#activeoffsetyvalue-number--number
+   */
+  activeOffsetY(
+    offset: number | [activeOffsetYStart: number, activeOffsetYEnd: number]
+  ) {
     if (Array.isArray(offset)) {
       this.config.activeOffsetYStart = offset[0];
       this.config.activeOffsetYEnd = offset[1];
@@ -55,7 +60,14 @@ export class PanGesture extends ContinousBaseGesture<
     return this;
   }
 
-  activeOffsetX(offset: number | number[]) {
+  /**
+   * Range along X axis (in points) where fingers travels without activation of gesture.
+   * @param offset
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/pan-gesture#activeoffsetxvalue-number--number
+   */
+  activeOffsetX(
+    offset: number | [activeOffsetXStart: number, activeOffsetXEnd: number]
+  ) {
     if (Array.isArray(offset)) {
       this.config.activeOffsetXStart = offset[0];
       this.config.activeOffsetXEnd = offset[1];
@@ -67,7 +79,14 @@ export class PanGesture extends ContinousBaseGesture<
     return this;
   }
 
-  failOffsetY(offset: number | number[]) {
+  /**
+   * When the finger moves outside this range (in points) along Y axis and gesture hasn't yet activated it will fail recognizing the gesture.
+   * @param offset
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/pan-gesture#failoffsetyvalue-number--number
+   */
+  failOffsetY(
+    offset: number | [failOffsetYStart: number, failOffsetYEnd: number]
+  ) {
     if (Array.isArray(offset)) {
       this.config.failOffsetYStart = offset[0];
       this.config.failOffsetYEnd = offset[1];
@@ -79,7 +98,14 @@ export class PanGesture extends ContinousBaseGesture<
     return this;
   }
 
-  failOffsetX(offset: number | number[]) {
+  /**
+   * When the finger moves outside this range (in points) along X axis and gesture hasn't yet activated it will fail recognizing the gesture.
+   * @param offset
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/pan-gesture#failoffsetxvalue-number--number
+   */
+  failOffsetX(
+    offset: number | [failOffsetXStart: number, failOffsetXEnd: number]
+  ) {
     if (Array.isArray(offset)) {
       this.config.failOffsetXStart = offset[0];
       this.config.failOffsetXEnd = offset[1];
@@ -91,46 +117,89 @@ export class PanGesture extends ContinousBaseGesture<
     return this;
   }
 
+  /**
+   * A number of fingers that is required to be placed before gesture can activate. Should be a higher or equal to 0 integer.
+   * @param minPointers
+   */
   minPointers(minPointers: number) {
     this.config.minPointers = minPointers;
     return this;
   }
 
+  /**
+   * When the given number of fingers is placed on the screen and gesture hasn't yet activated it will fail recognizing the gesture.
+   * Should be a higher or equal to 0 integer.
+   * @param maxPointers
+   */
   maxPointers(maxPointers: number) {
     this.config.maxPointers = maxPointers;
     return this;
   }
 
+  /**
+   * Minimum distance the finger (or multiple finger) need to travel before the gesture activates.
+   * Expressed in points.
+   * @param distance
+   */
   minDistance(distance: number) {
     this.config.minDist = distance;
     return this;
   }
 
+  /**
+   * Minimum velocity the finger has to reach in order to activate handler.
+   * @param velocity
+   */
   minVelocity(velocity: number) {
     this.config.minVelocity = velocity;
     return this;
   }
 
+  /**
+   * Minimum velocity along X axis the finger has to reach in order to activate handler.
+   * @param velocity
+   */
   minVelocityX(velocity: number) {
     this.config.minVelocityX = velocity;
     return this;
   }
 
+  /**
+   * Minimum velocity along Y axis the finger has to reach in order to activate handler.
+   * @param velocity
+   */
   minVelocityY(velocity: number) {
     this.config.minVelocityY = velocity;
     return this;
   }
 
+  /**
+   * #### Android only
+   * Android, by default, will calculate translation values based on the position of the leading pointer (the first one that was placed on the screen).
+   * This modifier allows that behavior to be changed to the one that is default on iOS - the averaged position of all active pointers will be used to calculate the translation values.
+   * @param value
+   */
   averageTouches(value: boolean) {
     this.config.avgTouches = value;
     return this;
   }
 
+  /**
+   * #### iOS only
+   * Enables two-finger gestures on supported devices, for example iPads with trackpads.
+   * @param value
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/pan-gesture/#enabletrackpadtwofingergesturevalue-boolean-ios-only
+   */
   enableTrackpadTwoFingerGesture(value: boolean) {
     this.config.enableTrackpadTwoFingerGesture = value;
     return this;
   }
 
+  /**
+   * Duration in milliseconds of the LongPress gesture before Pan is allowed to activate.
+   * @param duration
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/pan-gesture/#activateafterlongpressduration-number
+   */
   activateAfterLongPress(duration: number) {
     this.config.activateAfterLongPress = duration;
     return this;

package/src/handlers/gestures/pinchGesture.ts

@@ -1,5 +1,5 @@
 import { ContinousBaseGesture } from './gesture';
-import { PinchGestureHandlerEventPayload } from '../PinchGestureHandler';
+import type { PinchGestureHandlerEventPayload } from '../GestureHandlerEventPayload';
 import { GestureUpdateEvent } from '../gestureHandlerCommon';
 
 export type PinchGestureChangeEventPayload = {

package/src/handlers/gestures/reanimatedWrapper.ts

@@ -9,23 +9,24 @@ export interface SharedValue<T> {
   value: T;
 }
 
-let Reanimated: {
-  default: {
-    // Slightly modified definition copied from 'react-native-reanimated'
-    // eslint-disable-next-line @typescript-eslint/ban-types
-    createAnimatedComponent<P extends object>(
-      component: ComponentClass<P>,
-      options?: unknown
-    ): ComponentClass<P>;
-  };
-  useEvent: (
-    callback: (event: GestureUpdateEvent | GestureStateChangeEvent) => void,
-    events: string[],
-    rebuild: boolean
-  ) => unknown;
-  useSharedValue: <T>(value: T) => SharedValue<T>;
-  setGestureState: (handlerTag: number, newState: number) => void;
-};
+let Reanimated:
+  | {
+      default: {
+        // Slightly modified definition copied from 'react-native-reanimated'
+        createAnimatedComponent<P extends object>(
+          component: ComponentClass<P>,
+          options?: unknown
+        ): ComponentClass<P>;
+      };
+      useEvent: (
+        callback: (event: GestureUpdateEvent | GestureStateChangeEvent) => void,
+        events: string[],
+        rebuild: boolean
+      ) => unknown;
+      useSharedValue: <T>(value: T) => SharedValue<T>;
+      setGestureState: (handlerTag: number, newState: number) => void;
+    }
+  | undefined;
 
 try {
   Reanimated = require('@amazon-devices/react-native-reanimated');

package/src/handlers/gestures/rotationGesture.ts

@@ -1,5 +1,5 @@
 import { ContinousBaseGesture } from './gesture';
-import { RotationGestureHandlerEventPayload } from '../RotationGestureHandler';
+import type { RotationGestureHandlerEventPayload } from '../GestureHandlerEventPayload';
 import { GestureUpdateEvent } from '../gestureHandlerCommon';
 
 type RotationGestureChangeEventPayload = {

package/src/handlers/gestures/tapGesture.ts

@@ -1,8 +1,6 @@
 import { BaseGestureConfig, BaseGesture } from './gesture';
-import {
-  TapGestureConfig,
-  TapGestureHandlerEventPayload,
-} from '../TapGestureHandler';
+import { TapGestureConfig } from '../TapGestureHandler';
+import type { TapGestureHandlerEventPayload } from '../GestureHandlerEventPayload';
 
 export class TapGesture extends BaseGesture<TapGestureHandlerEventPayload> {
   public config: BaseGestureConfig & TapGestureConfig = {};
@@ -14,36 +12,71 @@ export class TapGesture extends BaseGesture<TapGestureHandlerEventPayload> {
     this.shouldCancelWhenOutside(true);
   }
 
+  /**
+   * Minimum number of pointers (fingers) required to be placed before the gesture activates.
+   * Should be a positive integer. The default value is 1.
+   * @param minPointers
+   */
   minPointers(minPointers: number) {
     this.config.minPointers = minPointers;
     return this;
   }
 
+  /**
+   * Number of tap gestures required to activate the gesture.
+   * The default value is 1.
+   * @param count
+   */
   numberOfTaps(count: number) {
     this.config.numberOfTaps = count;
     return this;
   }
 
+  /**
+   * Maximum distance, expressed in points, that defines how far the finger is allowed to travel during a tap gesture.
+   * @param maxDist
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/tap-gesture#maxdistancevalue-number
+   */
   maxDistance(maxDist: number) {
     this.config.maxDist = maxDist;
     return this;
   }
 
+  /**
+   * Maximum time, expressed in milliseconds, that defines how fast a finger must be released after a touch.
+   * The default value is 500.
+   * @param duration
+   */
   maxDuration(duration: number) {
     this.config.maxDurationMs = duration;
     return this;
   }
 
+  /**
+   * Maximum time, expressed in milliseconds, that can pass before the next tap — if many taps are required.
+   * The default value is 500.
+   * @param delay
+   */
   maxDelay(delay: number) {
     this.config.maxDelayMs = delay;
     return this;
   }
 
+  /**
+   * Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the X axis during a tap gesture.
+   * @param delta
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/tap-gesture#maxdeltaxvalue-number
+   */
   maxDeltaX(delta: number) {
     this.config.maxDeltaX = delta;
     return this;
   }
 
+  /**
+   * Maximum distance, expressed in points, that defines how far the finger is allowed to travel along the Y axis during a tap gesture.
+   * @param delta
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/tap-gesture#maxdeltayvalue-number
+   */
   maxDeltaY(delta: number) {
     this.config.maxDeltaY = delta;
     return this;

package/src/handlers/getNextHandlerTag.ts

@@ -0,0 +1,5 @@
+let handlerTag = 1;
+
+export function getNextHandlerTag(): number {
+  return handlerTag++;
+}

package/src/handlers/handlersRegistry.ts

@@ -1,4 +1,4 @@
-import { isJestEnv } from '../utils';
+import { isTestEnv } from '../utils';
 import { GestureType } from './gestures/gesture';
 import { GestureEvent, HandlerStateChangeEvent } from './gestureHandlerCommon';
 
@@ -7,19 +7,13 @@ const gestures = new Map<number, GestureType>();
 const oldHandlers = new Map<number, GestureHandlerCallbacks>();
 const testIDs = new Map<string, number>();
 
-let handlerTag = 1;
-
-export function getNextHandlerTag(): number {
-  return handlerTag++;
-}
-
 export function registerHandler(
   handlerTag: number,
   handler: GestureType,
   testID?: string
 ) {
   gestures.set(handlerTag, handler);
-  if (isJestEnv() && testID) {
+  if (isTestEnv() && testID) {
     testIDs.set(testID, handlerTag);
   }
 }
@@ -31,9 +25,13 @@ export function registerOldGestureHandler(
   oldHandlers.set(handlerTag, handler);
 }
 
+export function unregisterOldGestureHandler(handlerTag: number) {
+  oldHandlers.delete(handlerTag);
+}
+
 export function unregisterHandler(handlerTag: number, testID?: string) {
   gestures.delete(handlerTag);
-  if (isJestEnv() && testID) {
+  if (isTestEnv() && testID) {
     testIDs.delete(testID);
   }
 }

package/src/handlers/utils.ts

@@ -0,0 +1,76 @@
+import * as React from 'react';
+import { Platform, findNodeHandle as findNodeHandleRN } from 'react-native';
+import { handlerIDToTag } from './handlersRegistry';
+import { toArray } from '../utils';
+import RNGestureHandlerModule from '../RNGestureHandlerModule';
+import { ghQueueMicrotask } from '../ghQueueMicrotask';
+
+function isConfigParam(param: unknown, name: string) {
+  // param !== Object(param) returns false if `param` is a function
+  // or an object and returns true if `param` is null
+  return (
+    param !== undefined &&
+    (param !== Object(param) ||
+      !('__isNative' in (param as Record<string, unknown>))) &&
+    name !== 'onHandlerStateChange' &&
+    name !== 'onGestureEvent'
+  );
+}
+
+export function filterConfig(
+  props: Record<string, unknown>,
+  validProps: string[],
+  defaults: Record<string, unknown> = {}
+) {
+  const filteredConfig = { ...defaults };
+  for (const key of validProps) {
+    let value = props[key];
+    if (isConfigParam(value, key)) {
+      if (key === 'simultaneousHandlers' || key === 'waitFor') {
+        value = transformIntoHandlerTags(props[key]);
+      } else if (key === 'hitSlop' && typeof value !== 'object') {
+        value = { top: value, left: value, bottom: value, right: value };
+      }
+      filteredConfig[key] = value;
+    }
+  }
+  return filteredConfig;
+}
+
+export function transformIntoHandlerTags(handlerIDs: any) {
+  handlerIDs = toArray(handlerIDs);
+
+  if (Platform.OS === 'web') {
+    return handlerIDs
+      .map(({ current }: { current: any }) => current)
+      .filter((handle: any) => handle);
+  }
+  // converts handler string IDs into their numeric tags
+  return handlerIDs
+    .map(
+      (handlerID: any) =>
+        handlerIDToTag[handlerID] || handlerID.current?.handlerTag || -1
+    )
+    .filter((handlerTag: number) => handlerTag > 0);
+}
+
+export function findNodeHandle(
+  node: null | number | React.Component<any, any> | React.ComponentClass<any>
+): null | number | React.Component<any, any> | React.ComponentClass<any> {
+  if (Platform.OS === 'web') {
+    return node;
+  }
+  return findNodeHandleRN(node) ?? null;
+}
+let flushOperationsScheduled = false;
+
+export function scheduleFlushOperations() {
+  if (!flushOperationsScheduled) {
+    flushOperationsScheduled = true;
+    ghQueueMicrotask(() => {
+      RNGestureHandlerModule.flushOperations();
+
+      flushOperationsScheduled = false;
+    });
+  }
+}