react-native-gesture-handler 2.16.2 → 2.17.1

package/src/handlers/gestures/GestureDetector/Wrap.tsx

@@ -0,0 +1,35 @@
+import React from 'react';
+import { Reanimated } from '../reanimatedWrapper';
+import { tagMessage } from '../../../utils';
+
+export class Wrap extends React.Component<{
+  onGestureHandlerEvent?: unknown;
+  // implicit `children` prop has been removed in @types/react^18.0.0
+  children?: React.ReactNode;
+}> {
+  render() {
+    try {
+      // I don't think that fighting with types over such a simple function is worth it
+      // The only thing it does is add 'collapsable: false' to the child component
+      // to make sure it is in the native view hierarchy so the detector can find
+      // correct viewTag to attach to.
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const child: any = React.Children.only(this.props.children);
+      return React.cloneElement(
+        child,
+        { collapsable: false },
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+        child.props.children
+      );
+    } catch (e) {
+      throw new Error(
+        tagMessage(
+          `GestureDetector got more than one view as a child. If you want the gesture to work on multiple views, wrap them with a common parent and attach the gesture to that view.`
+        )
+      );
+    }
+  }
+}
+
+export const AnimatedWrap =
+  Reanimated?.default?.createAnimatedComponent(Wrap) ?? Wrap;

package/src/handlers/gestures/GestureDetector/attachHandlers.ts

@@ -0,0 +1,112 @@
+import React from 'react';
+import { GestureType, HandlerCallbacks } from '../gesture';
+import { registerHandler } from '../../handlersRegistry';
+import RNGestureHandlerModule from '../../../RNGestureHandlerModule';
+import {
+  filterConfig,
+  scheduleFlushOperations,
+} from '../../gestureHandlerCommon';
+import { ComposedGesture } from '../gestureComposition';
+import { ActionType } from '../../../ActionType';
+import { Platform } from 'react-native';
+import type RNGestureHandlerModuleWeb from '../../../RNGestureHandlerModule.web';
+import { ghQueueMicrotask } from '../../../ghQueueMicrotask';
+import { AttachedGestureState, WebEventHandler } from './types';
+import {
+  extractGestureRelations,
+  checkGestureCallbacksForWorklets,
+  ALLOWED_PROPS,
+} from './utils';
+
+interface AttachHandlersConfig {
+  preparedGesture: AttachedGestureState;
+  gestureConfig: ComposedGesture | GestureType;
+  gesturesToAttach: GestureType[];
+  viewTag: number;
+  webEventHandlersRef: React.RefObject<WebEventHandler>;
+}
+
+export function attachHandlers({
+  preparedGesture,
+  gestureConfig,
+  gesturesToAttach,
+  viewTag,
+  webEventHandlersRef,
+}: AttachHandlersConfig) {
+  gestureConfig.initialize();
+
+  // use queueMicrotask to extract handlerTags, because all refs should be initialized
+  // when it's ran
+  ghQueueMicrotask(() => {
+    if (!preparedGesture.isMounted) {
+      return;
+    }
+    gestureConfig.prepare();
+  });
+
+  for (const handler of gesturesToAttach) {
+    checkGestureCallbacksForWorklets(handler);
+    RNGestureHandlerModule.createGestureHandler(
+      handler.handlerName,
+      handler.handlerTag,
+      filterConfig(handler.config, ALLOWED_PROPS)
+    );
+
+    registerHandler(handler.handlerTag, handler, handler.config.testId);
+  }
+
+  // use queueMicrotask to extract handlerTags, because all refs should be initialized
+  // when it's ran
+  ghQueueMicrotask(() => {
+    if (!preparedGesture.isMounted) {
+      return;
+    }
+    for (const handler of gesturesToAttach) {
+      RNGestureHandlerModule.updateGestureHandler(
+        handler.handlerTag,
+        filterConfig(
+          handler.config,
+          ALLOWED_PROPS,
+          extractGestureRelations(handler)
+        )
+      );
+    }
+
+    scheduleFlushOperations();
+  });
+
+  for (const gesture of gesturesToAttach) {
+    const actionType = gesture.shouldUseReanimated
+      ? ActionType.REANIMATED_WORKLET
+      : ActionType.JS_FUNCTION_NEW_API;
+
+    if (Platform.OS === 'web') {
+      (
+        RNGestureHandlerModule.attachGestureHandler as typeof RNGestureHandlerModuleWeb.attachGestureHandler
+      )(
+        gesture.handlerTag,
+        viewTag,
+        ActionType.JS_FUNCTION_OLD_API, // ignored on web
+        webEventHandlersRef
+      );
+    } else {
+      RNGestureHandlerModule.attachGestureHandler(
+        gesture.handlerTag,
+        viewTag,
+        actionType
+      );
+    }
+  }
+
+  preparedGesture.attachedGestures = gesturesToAttach;
+
+  if (preparedGesture.animatedHandlers) {
+    const isAnimatedGesture = (g: GestureType) => g.shouldUseReanimated;
+
+    preparedGesture.animatedHandlers.value = gesturesToAttach
+      .filter(isAnimatedGesture)
+      .map((g) => g.handlers) as unknown as HandlerCallbacks<
+      Record<string, unknown>
+    >[];
+  }
+}

package/src/handlers/gestures/GestureDetector/dropHandlers.ts

@@ -0,0 +1,14 @@
+import { unregisterHandler } from '../../handlersRegistry';
+import RNGestureHandlerModule from '../../../RNGestureHandlerModule';
+import { scheduleFlushOperations } from '../../gestureHandlerCommon';
+import { AttachedGestureState } from './types';
+
+export function dropHandlers(preparedGesture: AttachedGestureState) {
+  for (const handler of preparedGesture.attachedGestures) {
+    RNGestureHandlerModule.dropGestureHandler(handler.handlerTag);
+
+    unregisterHandler(handler.handlerTag, handler.config.testId);
+  }
+
+  scheduleFlushOperations();
+}

package/src/handlers/gestures/GestureDetector/index.tsx

@@ -0,0 +1,187 @@
+/* eslint-disable react/no-unused-prop-types */
+import React, {
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+} from 'react';
+import { Platform, findNodeHandle } from 'react-native';
+import { GestureType } from '../gesture';
+import { UserSelect, TouchAction } from '../../gestureHandlerCommon';
+import { ComposedGesture } from '../gestureComposition';
+import { isJestEnv } from '../../../utils';
+
+import GestureHandlerRootViewContext from '../../../GestureHandlerRootViewContext';
+import { AttachedGestureState, GestureDetectorState } from './types';
+import { useAnimatedGesture } from './useAnimatedGesture';
+import { attachHandlers } from './attachHandlers';
+import { needsToReattach } from './needsToReattach';
+import { dropHandlers } from './dropHandlers';
+import { useWebEventHandlers } from './utils';
+import { Wrap, AnimatedWrap } from './Wrap';
+import { useDetectorUpdater } from './useDetectorUpdater';
+import { useViewRefHandler } from './useViewRefHandler';
+
+function propagateDetectorConfig(
+  props: GestureDetectorProps,
+  gesture: ComposedGesture | GestureType
+) {
+  const keysToPropagate: (keyof GestureDetectorProps)[] = [
+    'userSelect',
+    'enableContextMenu',
+    'touchAction',
+  ];
+
+  for (const key of keysToPropagate) {
+    const value = props[key];
+    if (value === undefined) {
+      continue;
+    }
+
+    for (const g of gesture.toGestureArray()) {
+      const config = g.config as { [key: string]: unknown };
+      config[key] = value;
+    }
+  }
+}
+
+interface GestureDetectorProps {
+  children?: React.ReactNode;
+  /**
+   * A gesture object containing the configuration and callbacks.
+   * Can be any of:
+   * - base gestures (`Tap`, `Pan`, ...)
+   * - `ComposedGesture` (`Race`, `Simultaneous`, `Exclusive`)
+   */
+  gesture: ComposedGesture | GestureType;
+  /**
+   * #### Web only
+   * This parameter allows to specify which `userSelect` property should be applied to underlying view.
+   * Possible values are `"none" | "auto" | "text"`. Default value is set to `"none"`.
+   */
+  userSelect?: UserSelect;
+  /**
+   * #### Web only
+   * Specifies whether context menu should be enabled after clicking on underlying view with right mouse button.
+   * Default value is set to `false`.
+   */
+  enableContextMenu?: boolean;
+  /**
+   * #### Web only
+   * This parameter allows to specify which `touchAction` property should be applied to underlying view.
+   * Supports all CSS touch-action values (e.g. `"none"`, `"pan-y"`). Default value is set to `"none"`.
+   */
+  touchAction?: TouchAction;
+}
+
+/**
+ * `GestureDetector` is responsible for creating and updating native gesture handlers based on the config of provided gesture.
+ *
+ * ### Props
+ * - `gesture`
+ * - `userSelect` (**Web only**)
+ * - `enableContextMenu` (**Web only**)
+ * - `touchAction` (**Web only**)
+ *
+ * ### Remarks
+ * - Gesture Detector will use first native view in its subtree to recognize gestures, however if this view is used only to group its children it may get automatically collapsed.
+ * - Using the same instance of a gesture across multiple Gesture Detectors is not possible.
+ *
+ * @see https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/gesture-detector
+ */
+export const GestureDetector = (props: GestureDetectorProps) => {
+  const rootViewContext = useContext(GestureHandlerRootViewContext);
+  if (__DEV__ && !rootViewContext && !isJestEnv() && Platform.OS !== 'web') {
+    throw new Error(
+      'GestureDetector must be used as a descendant of GestureHandlerRootView. Otherwise the gestures will not be recognized. See https://docs.swmansion.com/react-native-gesture-handler/docs/installation for more details.'
+    );
+  }
+
+  // Gesture config should be wrapped with useMemo to prevent unnecessary re-renders
+  const gestureConfig = props.gesture;
+  propagateDetectorConfig(props, gestureConfig);
+
+  const gesturesToAttach = useMemo(
+    () => gestureConfig.toGestureArray(),
+    [gestureConfig]
+  );
+  const shouldUseReanimated = gesturesToAttach.some(
+    (g) => g.shouldUseReanimated
+  );
+
+  const webEventHandlersRef = useWebEventHandlers();
+  // store state in ref to prevent unnecessary renders
+  const state = useRef<GestureDetectorState>({
+    firstRender: true,
+    viewRef: null,
+    previousViewTag: -1,
+    forceRebuildReanimatedEvent: false,
+  }).current;
+
+  const preparedGesture = React.useRef<AttachedGestureState>({
+    attachedGestures: [],
+    animatedEventHandler: null,
+    animatedHandlers: null,
+    shouldUseReanimated: shouldUseReanimated,
+    isMounted: false,
+  }).current;
+
+  const updateAttachedGestures = useDetectorUpdater(
+    state,
+    preparedGesture,
+    gesturesToAttach,
+    gestureConfig,
+    webEventHandlersRef
+  );
+
+  const refHandler = useViewRefHandler(state, updateAttachedGestures);
+
+  // Reanimated event should be rebuilt only when gestures are reattached, otherwise
+  // config update will be enough as all necessary items are stored in shared values anyway
+  const needsToRebuildReanimatedEvent =
+    state.firstRender ||
+    state.forceRebuildReanimatedEvent ||
+    needsToReattach(preparedGesture, gesturesToAttach);
+  state.forceRebuildReanimatedEvent = false;
+
+  useAnimatedGesture(preparedGesture, needsToRebuildReanimatedEvent);
+
+  useLayoutEffect(() => {
+    const viewTag = findNodeHandle(state.viewRef) as number;
+    preparedGesture.isMounted = true;
+
+    attachHandlers({
+      preparedGesture,
+      gestureConfig,
+      gesturesToAttach,
+      webEventHandlersRef,
+      viewTag,
+    });
+
+    return () => {
+      preparedGesture.isMounted = false;
+      dropHandlers(preparedGesture);
+    };
+  }, []);
+
+  useEffect(() => {
+    if (state.firstRender) {
+      state.firstRender = false;
+    } else {
+      updateAttachedGestures();
+    }
+  }, [props]);
+
+  if (shouldUseReanimated) {
+    return (
+      <AnimatedWrap
+        ref={refHandler}
+        onGestureHandlerEvent={preparedGesture.animatedEventHandler}>
+        {props.children}
+      </AnimatedWrap>
+    );
+  } else {
+    return <Wrap ref={refHandler}>{props.children}</Wrap>;
+  }
+};

package/src/handlers/gestures/GestureDetector/needsToReattach.ts

@@ -0,0 +1,27 @@
+import { GestureType } from '../gesture';
+import { AttachedGestureState } from './types';
+
+// Checks whether the gesture should be reattached to the view, this will happen when:
+// - The number of gestures in the preparedGesture is different than the number of gestures in the gesture
+// - The handlerName is different in any of the gestures
+// - At least one of the gestures changed the thread it runs on
+export function needsToReattach(
+  preparedGesture: AttachedGestureState,
+  newGestures: GestureType[]
+) {
+  if (newGestures.length !== preparedGesture.attachedGestures.length) {
+    return true;
+  }
+  for (let i = 0; i < newGestures.length; i++) {
+    if (
+      newGestures[i].handlerName !==
+        preparedGesture.attachedGestures[i].handlerName ||
+      newGestures[i].shouldUseReanimated !==
+        preparedGesture.attachedGestures[i].shouldUseReanimated
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/handlers/gestures/GestureDetector/types.ts

@@ -0,0 +1,32 @@
+import { GestureType, HandlerCallbacks } from '../gesture';
+import { SharedValue } from '../reanimatedWrapper';
+import { HandlerStateChangeEvent } from '../../gestureHandlerCommon';
+
+export interface AttachedGestureState {
+  // Array of gestures that should be attached to the view under that gesture detector
+  attachedGestures: GestureType[];
+  // Event handler for the gesture, returned by `useEvent` from Reanimated
+  animatedEventHandler: unknown;
+  // Shared value that's responsible for transferring the callbacks to the UI thread handler
+  animatedHandlers: SharedValue<
+    HandlerCallbacks<Record<string, unknown>>[] | null
+  > | null;
+  // Whether `useAnimatedGesture` should be called inside detector
+  shouldUseReanimated: boolean;
+  // Whether the GestureDetector is mounted
+  isMounted: boolean;
+}
+
+export interface GestureDetectorState {
+  firstRender: boolean;
+  viewRef: React.Component | null;
+  previousViewTag: number;
+  forceRebuildReanimatedEvent: boolean;
+}
+
+export interface WebEventHandler {
+  onGestureHandlerEvent: (event: HandlerStateChangeEvent<unknown>) => void;
+  onGestureHandlerStateChange?: (
+    event: HandlerStateChangeEvent<unknown>
+  ) => void;
+}

package/src/handlers/gestures/GestureDetector/updateHandlers.ts

@@ -0,0 +1,94 @@
+import { GestureType, HandlerCallbacks } from '../gesture';
+import { registerHandler } from '../../handlersRegistry';
+import RNGestureHandlerModule from '../../../RNGestureHandlerModule';
+import {
+  filterConfig,
+  scheduleFlushOperations,
+} from '../../gestureHandlerCommon';
+import { ComposedGesture } from '../gestureComposition';
+import { ghQueueMicrotask } from '../../../ghQueueMicrotask';
+import { AttachedGestureState } from './types';
+import {
+  extractGestureRelations,
+  checkGestureCallbacksForWorklets,
+  ALLOWED_PROPS,
+} from './utils';
+
+export function updateHandlers(
+  preparedGesture: AttachedGestureState,
+  gestureConfig: ComposedGesture | GestureType,
+  newGestures: GestureType[]
+) {
+  gestureConfig.prepare();
+
+  for (let i = 0; i < newGestures.length; i++) {
+    const handler = preparedGesture.attachedGestures[i];
+    checkGestureCallbacksForWorklets(handler);
+
+    // only update handlerTag when it's actually different, it may be the same
+    // if gesture config object is wrapped with useMemo
+    if (newGestures[i].handlerTag !== handler.handlerTag) {
+      newGestures[i].handlerTag = handler.handlerTag;
+      newGestures[i].handlers.handlerTag = handler.handlerTag;
+    }
+  }
+
+  // use queueMicrotask to extract handlerTags, because when it's ran, all refs should be updated
+  // and handlerTags in BaseGesture references should be updated in the loop above (we need to wait
+  // in case of external relations)
+  ghQueueMicrotask(() => {
+    if (!preparedGesture.isMounted) {
+      return;
+    }
+    for (let i = 0; i < newGestures.length; i++) {
+      const handler = preparedGesture.attachedGestures[i];
+
+      handler.config = newGestures[i].config;
+      handler.handlers = newGestures[i].handlers;
+
+      RNGestureHandlerModule.updateGestureHandler(
+        handler.handlerTag,
+        filterConfig(
+          handler.config,
+          ALLOWED_PROPS,
+          extractGestureRelations(handler)
+        )
+      );
+
+      registerHandler(handler.handlerTag, handler, handler.config.testId);
+    }
+
+    if (preparedGesture.animatedHandlers) {
+      const previousHandlersValue =
+        preparedGesture.animatedHandlers.value ?? [];
+      const newHandlersValue = preparedGesture.attachedGestures
+        .filter((g) => g.shouldUseReanimated) // ignore gestures that shouldn't run on UI
+        .map((g) => g.handlers) as unknown as HandlerCallbacks<
+        Record<string, unknown>
+      >[];
+
+      // if amount of gesture configs changes, we need to update the callbacks in shared value
+      let shouldUpdateSharedValue =
+        previousHandlersValue.length !== newHandlersValue.length;
+
+      if (!shouldUpdateSharedValue) {
+        // if the amount is the same, we need to check if any of the configs inside has changed
+        for (let i = 0; i < newHandlersValue.length; i++) {
+          if (
+            // we can use the `gestureId` prop as it's unique for every config instance
+            newHandlersValue[i].gestureId !== previousHandlersValue[i].gestureId
+          ) {
+            shouldUpdateSharedValue = true;
+            break;
+          }
+        }
+      }
+
+      if (shouldUpdateSharedValue) {
+        preparedGesture.animatedHandlers.value = newHandlersValue;
+      }
+    }
+
+    scheduleFlushOperations();
+  });
+}