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

package/src/handlers/gestures/forceTouchGesture.ts

@@ -1,10 +1,11 @@
 import { BaseGestureConfig, ContinousBaseGesture } from './gesture';
-import {
-  ForceTouchGestureConfig,
-  ForceTouchGestureHandlerEventPayload,
-} from '../ForceTouchGestureHandler';
+import { ForceTouchGestureConfig } from '../ForceTouchGestureHandler';
+import type { ForceTouchGestureHandlerEventPayload } from '../GestureHandlerEventPayload';
 import { GestureUpdateEvent } from '../gestureHandlerCommon';
 
+/**
+ * @deprecated ForceTouch gesture is deprecated and will be removed in the future.
+ */
 export type ForceTouchGestureChangeEventPayload = {
   forceChange: number;
 };
@@ -28,6 +29,9 @@ function changeEventCalculator(
   return { ...current, ...changePayload };
 }
 
+/**
+ * @deprecated ForceTouch gesture is deprecated and will be removed in the future.
+ */
 export class ForceTouchGesture extends ContinousBaseGesture<
   ForceTouchGestureHandlerEventPayload,
   ForceTouchGestureChangeEventPayload
@@ -40,16 +44,30 @@ export class ForceTouchGesture extends ContinousBaseGesture<
     this.handlerName = 'ForceTouchGestureHandler';
   }
 
+  /**
+   * A minimal pressure that is required before gesture can activate.
+   * Should be a value from range [0.0, 1.0]. Default is 0.2.
+   * @param force
+   */
   minForce(force: number) {
     this.config.minForce = force;
     return this;
   }
 
+  /**
+   * A maximal pressure that could be applied for gesture.
+   * If the pressure is greater, gesture fails. Should be a value from range [0.0, 1.0].
+   * @param force
+   */
   maxForce(force: number) {
     this.config.maxForce = force;
     return this;
   }
 
+  /**
+   * Value defining if haptic feedback has to be performed on activation.
+   * @param value
+   */
   feedbackOnActivation(value: boolean) {
     this.config.feedbackOnActivation = value;
     return this;
@@ -71,4 +89,7 @@ export class ForceTouchGesture extends ContinousBaseGesture<
   }
 }
 
+/**
+ * @deprecated ForceTouch gesture is deprecated and will be removed in the future.
+ */
 export type ForceTouchGestureType = InstanceType<typeof ForceTouchGesture>;

package/src/handlers/gestures/gesture.ts

@@ -1,5 +1,3 @@
-import { FlingGestureHandlerEventPayload } from '../FlingGestureHandler';
-import { ForceTouchGestureHandlerEventPayload } from '../ForceTouchGestureHandler';
 import {
   HitSlop,
   CommonGestureConfig,
@@ -7,15 +5,21 @@ import {
   GestureStateChangeEvent,
   GestureUpdateEvent,
   ActiveCursor,
+  MouseButton,
 } from '../gestureHandlerCommon';
-import { getNextHandlerTag } from '../handlersRegistry';
+import { getNextHandlerTag } from '../getNextHandlerTag';
 import { GestureStateManagerType } from './gestureStateManager';
-import { LongPressGestureHandlerEventPayload } from '../LongPressGestureHandler';
-import { PanGestureHandlerEventPayload } from '../PanGestureHandler';
-import { PinchGestureHandlerEventPayload } from '../PinchGestureHandler';
-import { RotationGestureHandlerEventPayload } from '../RotationGestureHandler';
-import { TapGestureHandlerEventPayload } from '../TapGestureHandler';
-import { NativeViewGestureHandlerPayload } from '../NativeViewGestureHandler';
+import type {
+  FlingGestureHandlerEventPayload,
+  ForceTouchGestureHandlerEventPayload,
+  LongPressGestureHandlerEventPayload,
+  PanGestureHandlerEventPayload,
+  PinchGestureHandlerEventPayload,
+  RotationGestureHandlerEventPayload,
+  TapGestureHandlerEventPayload,
+  NativeViewGestureHandlerPayload,
+  HoverGestureHandlerEventPayload,
+} from '../GestureHandlerEventPayload';
 import { isRemoteDebuggingEnabled } from '../../utils';
 
 export type GestureType =
@@ -28,19 +32,21 @@ export type GestureType =
   | BaseGesture<PinchGestureHandlerEventPayload>
   | BaseGesture<FlingGestureHandlerEventPayload>
   | BaseGesture<ForceTouchGestureHandlerEventPayload>
-  | BaseGesture<NativeViewGestureHandlerPayload>;
+  | BaseGesture<NativeViewGestureHandlerPayload>
+  | BaseGesture<HoverGestureHandlerEventPayload>;
 
 export type GestureRef =
   | number
   | GestureType
   | React.RefObject<GestureType | undefined>
-  | React.RefObject<React.ComponentType | undefined>; // allow adding a ref to a gesture handler
+  | React.RefObject<React.ComponentType | undefined>; // Allow adding a ref to a gesture handler
 export interface BaseGestureConfig
   extends CommonGestureConfig,
     Record<string, unknown> {
   ref?: React.MutableRefObject<GestureType | undefined>;
   requireToFail?: GestureRef[];
   simultaneousWith?: GestureRef[];
+  blocksHandlers?: GestureRef[];
   needsPointerData?: boolean;
   manualActivation?: boolean;
   runOnJS?: boolean;
@@ -95,7 +101,7 @@ export const CALLBACK_TYPE = {
 
 // Allow using CALLBACK_TYPE as object and type
 // eslint-disable-next-line @typescript-eslint/no-redeclare
-export type CALLBACK_TYPE = typeof CALLBACK_TYPE[keyof typeof CALLBACK_TYPE];
+export type CALLBACK_TYPE = (typeof CALLBACK_TYPE)[keyof typeof CALLBACK_TYPE];
 
 export abstract class Gesture {
   /**
@@ -119,7 +125,7 @@ export abstract class Gesture {
 
 let nextGestureId = 0;
 export abstract class BaseGesture<
-  EventPayloadT extends Record<string, unknown>
+  EventPayloadT extends Record<string, unknown>,
 > extends Gesture {
   private gestureId = -1;
   public handlerTag = -1;
@@ -144,7 +150,7 @@ export abstract class BaseGesture<
   }
 
   private addDependency(
-    key: 'simultaneousWith' | 'requireToFail',
+    key: 'simultaneousWith' | 'requireToFail' | 'blocksHandlers',
     gesture: Exclude<GestureRef, number>
   ) {
     const value = this.config[key];
@@ -153,6 +159,10 @@ export abstract class BaseGesture<
       : [gesture];
   }
 
+  /**
+   * Sets a `ref` to the gesture object, allowing for interoperability with the old API.
+   * @param ref
+   */
   withRef(ref: React.MutableRefObject<GestureType | undefined>) {
     this.config.ref = ref;
     return this;
@@ -160,22 +170,36 @@ export abstract class BaseGesture<
 
   // eslint-disable-next-line @typescript-eslint/ban-types
   protected isWorklet(callback: Function) {
-    //@ts-ignore if callback is a worklet, the property will be available, if not then the check will return false
+    // @ts-ignore if callback is a worklet, the property will be available, if not then the check will return false
     return callback.__workletHash !== undefined;
   }
 
+  /**
+   * Set the callback that is being called when given gesture handler starts receiving touches.
+   * At the moment of this callback the handler is in `BEGAN` state and we don't know yet if it will recognize the gesture at all.
+   * @param callback
+   */
   onBegin(callback: (event: GestureStateChangeEvent<EventPayloadT>) => void) {
     this.handlers.onBegin = callback;
     this.handlers.isWorklet[CALLBACK_TYPE.BEGAN] = this.isWorklet(callback);
     return this;
   }
 
+  /**
+   * Set the callback that is being called when the gesture is recognized by the handler and it transitions to the `ACTIVE` state.
+   * @param callback
+   */
   onStart(callback: (event: GestureStateChangeEvent<EventPayloadT>) => void) {
     this.handlers.onStart = callback;
     this.handlers.isWorklet[CALLBACK_TYPE.START] = this.isWorklet(callback);
     return this;
   }
 
+  /**
+   * Set the callback that is being called when the gesture that was recognized by the handler finishes and handler reaches `END` state.
+   * It will be called only if the handler was previously in the `ACTIVE` state.
+   * @param callback
+   */
   onEnd(
     callback: (
       event: GestureStateChangeEvent<EventPayloadT>,
@@ -183,11 +207,15 @@ export abstract class BaseGesture<
     ) => void
   ) {
     this.handlers.onEnd = callback;
-    //@ts-ignore if callback is a worklet, the property will be available, if not then the check will return false
+    // @ts-ignore if callback is a worklet, the property will be available, if not then the check will return false
     this.handlers.isWorklet[CALLBACK_TYPE.END] = this.isWorklet(callback);
     return this;
   }
 
+  /**
+   * Set the callback that is being called when the handler finalizes handling gesture - the gesture was recognized and has finished or it failed to recognize.
+   * @param callback
+   */
   onFinalize(
     callback: (
       event: GestureStateChangeEvent<EventPayloadT>,
@@ -195,11 +223,15 @@ export abstract class BaseGesture<
     ) => void
   ) {
     this.handlers.onFinalize = callback;
-    //@ts-ignore if callback is a worklet, the property will be available, if not then the check will return false
+    // @ts-ignore if callback is a worklet, the property will be available, if not then the check will return false
     this.handlers.isWorklet[CALLBACK_TYPE.FINALIZE] = this.isWorklet(callback);
     return this;
   }
 
+  /**
+   * Set the `onTouchesDown` callback which is called every time a pointer is placed on the screen.
+   * @param callback
+   */
   onTouchesDown(callback: TouchEventHandlerType) {
     this.config.needsPointerData = true;
     this.handlers.onTouchesDown = callback;
@@ -209,6 +241,10 @@ export abstract class BaseGesture<
     return this;
   }
 
+  /**
+   * Set the `onTouchesMove` callback which is called every time a pointer is moved on the screen.
+   * @param callback
+   */
   onTouchesMove(callback: TouchEventHandlerType) {
     this.config.needsPointerData = true;
     this.handlers.onTouchesMove = callback;
@@ -218,6 +254,10 @@ export abstract class BaseGesture<
     return this;
   }
 
+  /**
+   * Set the `onTouchesUp` callback which is called every time a pointer is lifted from the screen.
+   * @param callback
+   */
   onTouchesUp(callback: TouchEventHandlerType) {
     this.config.needsPointerData = true;
     this.handlers.onTouchesUp = callback;
@@ -227,6 +267,10 @@ export abstract class BaseGesture<
     return this;
   }
 
+  /**
+   * Set the `onTouchesCancelled` callback which is called every time a pointer stops being tracked, for example when the gesture finishes.
+   * @param callback
+   */
   onTouchesCancelled(callback: TouchEventHandlerType) {
     this.config.needsPointerData = true;
     this.handlers.onTouchesCancelled = callback;
@@ -236,31 +280,77 @@ export abstract class BaseGesture<
     return this;
   }
 
+  /**
+   * Indicates whether the given handler should be analyzing stream of touch events or not.
+   * @param enabled
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/pan-gesture#enabledvalue-boolean
+   */
   enabled(enabled: boolean) {
     this.config.enabled = enabled;
     return this;
   }
 
+  /**
+   * When true the handler will cancel or fail recognition (depending on its current state) whenever the finger leaves the area of the connected view.
+   * @param value
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/pan-gesture#shouldcancelwhenoutsidevalue-boolean
+   */
   shouldCancelWhenOutside(value: boolean) {
     this.config.shouldCancelWhenOutside = value;
     return this;
   }
 
+  /**
+   * This parameter enables control over what part of the connected view area can be used to begin recognizing the gesture.
+   * When a negative number is provided the bounds of the view will reduce the area by the given number of points in each of the sides evenly.
+   * @param hitSlop
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/pan-gesture#hitslopsettings
+   */
   hitSlop(hitSlop: HitSlop) {
     this.config.hitSlop = hitSlop;
     return this;
   }
 
+  /**
+   * #### Web only
+   * This parameter allows to specify which `cursor` should be used when gesture activates.
+   * Supports all CSS cursor values (e.g. `"grab"`, `"zoom-in"`). Default value is set to `"auto"`.
+   * @param activeCursor
+   */
   activeCursor(activeCursor: ActiveCursor) {
     this.config.activeCursor = activeCursor;
     return this;
   }
 
+  /**
+   * #### Web & Android only
+   * Allows users to choose which mouse button should handler respond to.
+   * Arguments can be combined using `|` operator, e.g. `mouseButton(MouseButton.LEFT | MouseButton.RIGHT)`.
+   * Default value is set to `MouseButton.LEFT`.
+   * @param mouseButton
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/pan-gesture#mousebuttonvalue-mousebutton-web--android-only
+   */
+  mouseButton(mouseButton: MouseButton) {
+    this.config.mouseButton = mouseButton;
+    return this;
+  }
+
+  /**
+   * When `react-native-reanimated` is installed, the callbacks passed to the gestures are automatically workletized and run on the UI thread when called.
+   * This option allows for changing this behavior: when `true`, all the callbacks will be run on the JS thread instead of the UI thread, regardless of whether they are worklets or not.
+   * Defaults to `false`.
+   * @param runOnJS
+   */
   runOnJS(runOnJS: boolean) {
     this.config.runOnJS = runOnJS;
     return this;
   }
 
+  /**
+   * Allows gestures across different components to be recognized simultaneously.
+   * @param gestures
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/gesture-composition/#simultaneouswithexternalgesture
+   */
   simultaneousWithExternalGesture(...gestures: Exclude<GestureRef, number>[]) {
     for (const gesture of gestures) {
       this.addDependency('simultaneousWith', gesture);
@@ -268,6 +358,11 @@ export abstract class BaseGesture<
     return this;
   }
 
+  /**
+   * Allows to delay activation of the handler until all handlers passed as arguments to this method fail (or don't begin at all).
+   * @param gestures
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/gesture-composition/#requireexternalgesturetofail
+   */
   requireExternalGestureToFail(...gestures: Exclude<GestureRef, number>[]) {
     for (const gesture of gestures) {
       this.addDependency('requireToFail', gesture);
@@ -275,11 +370,33 @@ export abstract class BaseGesture<
     return this;
   }
 
+  /**
+   * Works similarily to `requireExternalGestureToFail` but the direction of the relation is reversed - instead of being one-to-many relation, it's many-to-one.
+   * @param gestures
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/gesture-composition/#blocksexternalgesture
+   */
+  blocksExternalGesture(...gestures: Exclude<GestureRef, number>[]) {
+    for (const gesture of gestures) {
+      this.addDependency('blocksHandlers', gesture);
+    }
+    return this;
+  }
+
+  /**
+   * Sets a `testID` property for gesture object, allowing for querying for it in tests.
+   * @param id
+   */
   withTestId(id: string) {
     this.config.testId = id;
     return this;
   }
 
+  /**
+   * #### iOS only
+   * When `true`, the handler will cancel touches for native UI components (`UIButton`, `UISwitch`, etc) it's attached to when it becomes `ACTIVE`.
+   * Default value is `true`.
+   * @param value
+   */
   cancelsTouchesInView(value: boolean) {
     this.config.cancelsTouchesInView = value;
     return this;
@@ -303,8 +420,8 @@ export abstract class BaseGesture<
   prepare() {}
 
   get shouldUseReanimated(): boolean {
-    // use Reanimated when runOnJS isn't set explicitly,
-    // and all defined callbacks are worklets,
+    // Use Reanimated when runOnJS isn't set explicitly,
+    // all defined callbacks are worklets
     // and remote debugging is disabled
     return (
       this.config.runOnJS !== true &&
@@ -316,14 +433,23 @@ export abstract class BaseGesture<
 
 export abstract class ContinousBaseGesture<
   EventPayloadT extends Record<string, unknown>,
-  EventChangePayloadT extends Record<string, unknown>
+  EventChangePayloadT extends Record<string, unknown>,
 > extends BaseGesture<EventPayloadT> {
+  /**
+   * Set the callback that is being called every time the gesture receives an update while it's active.
+   * @param callback
+   */
   onUpdate(callback: (event: GestureUpdateEvent<EventPayloadT>) => void) {
     this.handlers.onUpdate = callback;
     this.handlers.isWorklet[CALLBACK_TYPE.UPDATE] = this.isWorklet(callback);
     return this;
   }
 
+  /**
+   * Set the callback that is being called every time the gesture receives an update while it's active.
+   * This callback will receive information about change in value in relation to the last received event.
+   * @param callback
+   */
   onChange(
     callback: (
       event: GestureUpdateEvent<EventPayloadT & EventChangePayloadT>
@@ -334,6 +460,11 @@ export abstract class ContinousBaseGesture<
     return this;
   }
 
+  /**
+   * When `true` the handler will not activate by itself even if its activation criteria are met.
+   * Instead you can manipulate its state using state manager.
+   * @param manualActivation
+   */
   manualActivation(manualActivation: boolean) {
     this.config.manualActivation = manualActivation;
     return this;

package/src/handlers/gestures/gestureComposition.ts

@@ -29,6 +29,8 @@ export class ComposedGesture extends Gesture {
     if (gesture instanceof BaseGesture) {
       const newConfig = { ...gesture.config };
 
+      // No need to extend `blocksHandlers` here, because it's not changed in composition.
+      // The same effect is achieved by reversing the order of 2 gestures in `Exclusive`
       newConfig.simultaneousWith = extendRelation(
         newConfig.simultaneousWith,
         simultaneousGestures
@@ -69,7 +71,7 @@ export class ComposedGesture extends Gesture {
 
 export class SimultaneousGesture extends ComposedGesture {
   prepare() {
-    // this piece of magic works something like this:
+    // This piece of magic works something like this:
     // for every gesture in the array
     const simultaneousArrays = this.gestures.map((gesture) =>
       // we take the array it's in
@@ -95,7 +97,7 @@ export class SimultaneousGesture extends ComposedGesture {
 
 export class ExclusiveGesture extends ComposedGesture {
   prepare() {
-    // transforms the array of gestures into array of grouped raw (not composed) gestures
+    // Transforms the array of gestures into array of grouped raw (not composed) gestures
     // i.e. [gesture1, gesture2, ComposedGesture(gesture3, gesture4)] -> [[gesture1], [gesture2], [gesture3, gesture4]]
     const gestureArrays = this.gestures.map((gesture) =>
       gesture.toGestureArray()
@@ -110,7 +112,7 @@ export class ExclusiveGesture extends ComposedGesture {
         this.requireGesturesToFail.concat(requireToFail)
       );
 
-      // every group gets to wait for all groups before it
+      // Every group gets to wait for all groups before it
       requireToFail = requireToFail.concat(gestureArrays[i]);
     }
   }

package/src/handlers/gestures/gestureObjects.ts

@@ -15,43 +15,99 @@ import { NativeGesture } from './nativeGesture';
 import { ManualGesture } from './manualGesture';
 import { HoverGesture } from './hoverGesture';
 
+/**
+ * `Gesture` is the object that allows you to create and compose gestures.
+ *
+ * ### Remarks
+ * - Consider wrapping your gesture configurations with `useMemo`, as it will reduce the amount of work Gesture Handler has to do under the hood when updating gestures.
+ *
+ * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/gesture
+ */
 export const GestureObjects = {
+  /**
+   * A discrete gesture that recognizes one or many taps.
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/tap-gesture
+   */
   Tap: () => {
     return new TapGesture();
   },
 
+  /**
+   * A continuous gesture that can recognize a panning (dragging) gesture and track its movement.
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/pan-gesture
+   */
   Pan: () => {
     return new PanGesture();
   },
 
+  /**
+   * A continuous gesture that recognizes pinch gesture. It allows for tracking the distance between two fingers and use that information to scale or zoom your content.
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/pinch-gesture
+   */
   Pinch: () => {
     return new PinchGesture();
   },
 
+  /**
+   * A continuous gesture that can recognize rotation and track its movement.
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/rotation-gesture
+   */
   Rotation: () => {
     return new RotationGesture();
   },
 
+  /**
+   * A discrete gesture that activates when the movement is sufficiently fast.
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/fling-gesture
+   */
   Fling: () => {
     return new FlingGesture();
   },
 
+  /**
+   * A discrete gesture that activates when the corresponding view is pressed for a sufficiently long time.
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/long-press-gesture
+   */
   LongPress: () => {
     return new LongPressGesture();
   },
 
+  /**
+   * @deprecated ForceTouch gesture is deprecated and will be removed in the future.
+   *
+   *  #### iOS only
+   * A continuous gesture that recognizes force of a touch. It allows for tracking pressure of touch on some iOS devices.
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/force-touch-gesture
+   */
   ForceTouch: () => {
     return new ForceTouchGesture();
   },
 
+  /**
+   * A gesture that allows other touch handling components to participate in RNGH's gesture system.
+   * When used, the other component should be the direct child of a `GestureDetector`.
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/native-gesture
+   */
   Native: () => {
     return new NativeGesture();
   },
 
+  /**
+   * A plain gesture that has no specific activation criteria nor event data set.
+   * Its state has to be controlled manually using a state manager.
+   * It will not fail when all the pointers are lifted from the screen.
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/manual-gesture
+   */
   Manual: () => {
     return new ManualGesture();
   },
 
+  /**
+   * A continuous gesture that can recognize hovering above the view it's attached to.
+   * The hover effect may be activated by moving a mouse or a stylus over the view.
+   *
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/hover-gesture
+   */
   Hover: () => {
     return new HoverGesture();
   },
@@ -59,6 +115,7 @@ export const GestureObjects = {
   /**
    * Builds a composed gesture consisting of gestures provided as parameters.
    * The first one that becomes active cancels the rest of gestures.
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/gesture-composition/#race
    */
   Race: (...gestures: Gesture[]) => {
     return new ComposedGesture(...gestures);
@@ -66,6 +123,7 @@ export const GestureObjects = {
 
   /**
    * Builds a composed gesture that allows all base gestures to run simultaneously.
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/gesture-composition/#simultaneous
    */
   Simultaneous(...gestures: Gesture[]) {
     return new SimultaneousGesture(...gestures);
@@ -77,6 +135,7 @@ export const GestureObjects = {
    * than the second one, second one has higher priority than the third one, and so on.
    * For example, to make a gesture that recognizes both single and double tap you need
    * to call Exclusive(doubleTap, singleTap).
+   * @see https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/gesture-composition/#exclusive
    */
   Exclusive(...gestures: Gesture[]) {
     return new ExclusiveGesture(...gestures);