[General] Allow explicit opt-in for the Animated codepaths when not using native driver (#3824)

## Description

Currently, we're enabling the Animated codepath only when the handler
passed to `onUpdate` is an `Animated.Event` with `useNativeDriver`. When
`useNativeDriver` is not enabled, `Animated.event` returns a function,
and we have no way of differentiating between it and a function passed
by the user.

This is not ideal since the animated codepath receives events in a
different format (wrapped with `nativeEvent`). This meant that the code
would stop working when switching between using the native driver and
not. The same would happen when trying to use a native driver in code
supposed to also run on web, where it's not available - the gesture
would work on mobile, but crash on web.

To avoid this, this PR adds an option to explicitly opt-in to the
animated codepath by setting `useAnimated` in the gesture config. This
will automatically disable Reanimated and throw an error when user if
the user tries to reenable it.

## Test plan

Tested on the `Native Detector` example in the basic app, as well as on
the expo app on the same example for web.

Author: j-piasecki

packages/react-native-gesture-handler/src/v3/detectors/NativeDetector.tsx

@@ -51,6 +51,7 @@ export function NativeDetector<THandlerData, TConfig>({
       onGestureHandlerReanimatedTouchEvent={
         gesture.detectorCallbacks.onReanimatedTouchEvent
       }
+      // @ts-ignore This is a type mismatch between RNGH types and RN Codegen types
       onGestureHandlerAnimatedEvent={
         gesture.detectorCallbacks.onGestureHandlerAnimatedEvent
       }

packages/react-native-gesture-handler/src/v3/detectors/VirtualDetector/InterceptingGestureDetector.tsx

@@ -126,13 +126,15 @@ export function InterceptingGestureDetector<THandlerData, TConfig>({
   const createGestureEventHandler = useCallback(
     (key: keyof DetectorCallbacks<THandlerData>) => {
       return (e: GestureHandlerEvent<THandlerData>) => {
-        if (gesture?.detectorCallbacks[key]) {
+        if (typeof gesture?.detectorCallbacks[key] === 'function') {
+          // @ts-expect-error passing event to a union of functions where only one is typed as such
           gesture.detectorCallbacks[key](e);
         }
 
         virtualChildren.forEach((child) => {
           const method = child.methods[key];
-          if (method) {
+          if (typeof method === 'function') {
+            // @ts-expect-error passing event to a union of functions where only one is typed as such
             method(e);
           }
         });

packages/react-native-gesture-handler/src/v3/hooks/callbacks/js/useGestureUpdateEvent.ts

@@ -1,4 +1,4 @@
-import { prepareUpdateHandlers, isAnimatedEvent } from '../../utils';
+import { prepareUpdateHandlers } from '../../utils';
 import { ReanimatedContext } from '../../../../handlers/gestures/reanimatedWrapper';
 import { getUpdateHandler } from '../updateHandler';
 import { BaseGestureConfig } from '../../../types';
@@ -20,13 +20,18 @@ export function useGestureUpdateEvent<THandlerData, TConfig>(
       lastUpdateEvent: undefined,
     };
 
-    return isAnimatedEvent(config.onUpdate)
+    return config.dispatchesAnimatedEvents
       ? undefined
       : getUpdateHandler(
           handlerTag,
           handlers,
           jsContext,
           changeEventCalculator
         );
-  }, [handlerTag, config.onUpdate, config.changeEventCalculator]);
+  }, [
+    handlerTag,
+    config.onUpdate,
+    config.dispatchesAnimatedEvents,
+    config.changeEventCalculator,
+  ]);
 }

packages/react-native-gesture-handler/src/v3/hooks/useGesture.ts

@@ -30,14 +30,6 @@ export function useGesture<THandlerData, TConfig>(
   // This has to be done ASAP as other hooks depend `shouldUseReanimatedDetector`.
   prepareConfig(config);
 
-  if (config.dispatchesAnimatedEvents && config.shouldUseReanimatedDetector) {
-    throw new Error(
-      tagMessage(
-        `${type}: You cannot use Animated.Event together with callbacks running on the UI thread. Either remove Animated.Event from onUpdate, or set runOnJS property to true on the gesture.`
-      )
-    );
-  }
-
   // TODO: Call only necessary hooks depending on which callbacks are defined (?)
   const {
     onGestureHandlerStateChange,

packages/react-native-gesture-handler/src/v3/hooks/useGestureCallbacks.ts

@@ -1,11 +1,38 @@
 import { useGestureStateChangeEvent } from './callbacks/js/useGestureStateChangeEvent';
 import { useGestureUpdateEvent } from './callbacks/js/useGestureUpdateEvent';
 import { useGestureTouchEvent } from './callbacks/js/useGestureTouchEvent';
-import { AnimatedEvent, BaseGestureConfig } from '../types';
-import { checkMappingForChangeProperties, isAnimatedEvent } from './utils';
+import { AnimatedEvent, BaseGestureConfig, GestureUpdateEvent } from '../types';
+import {
+  checkMappingForChangeProperties,
+  isNativeAnimatedEvent,
+} from './utils';
 import { useReanimatedStateChangeEvent } from './callbacks/reanimated/useReanimatedStateChangeEvent';
 import { useReanimatedUpdateEvent } from './callbacks/reanimated/useReanimatedUpdateEvent';
 import { useReanimatedTouchEvent } from './callbacks/reanimated/useReanimatedTouchEvent';
+import { tagMessage } from '../../utils';
+
+function guardJSAnimatedEvent(handler: (...args: unknown[]) => void) {
+  return (...args: unknown[]) => {
+    try {
+      handler(...args);
+    } catch (e) {
+      if (
+        e instanceof Error &&
+        e.message.includes('Bad event of type undefined for key')
+      ) {
+        throw new Error(
+          tagMessage(
+            'The event mapping inside an Animated.event is invalid. ' +
+              'Please make sure you are using the correct structure for the gesture event:\n\n' +
+              '{ nativeEvent: { handlerData: { /* your mappings here */ } } }'
+          )
+        );
+      }
+
+      throw e;
+    }
+  };
+}
 
 export function useGestureCallbacks<THandlerData, TConfig>(
   handlerTag: number,
@@ -31,10 +58,21 @@ export function useGestureCallbacks<THandlerData, TConfig>(
     onReanimatedTouchEvent = useReanimatedTouchEvent(handlerTag, config);
   }
 
-  let onGestureHandlerAnimatedEvent: AnimatedEvent | undefined;
-  if (isAnimatedEvent(config.onUpdate)) {
-    checkMappingForChangeProperties(config.onUpdate);
-    onGestureHandlerAnimatedEvent = config.onUpdate;
+  let onGestureHandlerAnimatedEvent:
+    | ((event: GestureUpdateEvent<THandlerData>) => void)
+    | AnimatedEvent
+    | undefined;
+  if (config.dispatchesAnimatedEvents) {
+    if (__DEV__ && isNativeAnimatedEvent(config.onUpdate)) {
+      checkMappingForChangeProperties(config.onUpdate);
+    }
+
+    if (__DEV__ && !isNativeAnimatedEvent(config.onUpdate)) {
+      // @ts-expect-error At this point we know it's not a native animated event, so it's callable
+      onGestureHandlerAnimatedEvent = guardJSAnimatedEvent(config.onUpdate);
+    } else {
+      onGestureHandlerAnimatedEvent = config.onUpdate;
+    }
   }
 
   return {

packages/react-native-gesture-handler/src/v3/hooks/utils/configUtils.ts

@@ -6,7 +6,7 @@ import {
   SingleGestureName,
 } from '../../types';
 import { hasWorkletEventHandlers, maybeUnpackValue } from './reanimatedUtils';
-import { isAnimatedEvent, shouldHandleTouchEvents } from './eventUtils';
+import { isNativeAnimatedEvent, shouldHandleTouchEvents } from './eventUtils';
 import {
   allowedNativeProps,
   EMPTY_WHITE_LIST,
@@ -20,12 +20,46 @@ export function prepareConfig<THandlerData, TConfig extends object>(
 ) {
   const runOnJS = maybeUnpackValue(config.runOnJS);
 
+  if (
+    __DEV__ &&
+    isNativeAnimatedEvent(config.onUpdate) &&
+    !config.useAnimated
+  ) {
+    console.warn(
+      tagMessage(
+        'You are using Animated.event in onUpdate without setting useAnimated to true. ' +
+          'This may lead to unexpected behavior. If you intend to use Animated.event, ' +
+          'please set useAnimated to true in the gesture config.'
+      )
+    );
+  }
+
+  config.dispatchesAnimatedEvents =
+    config.useAnimated || isNativeAnimatedEvent(config.onUpdate);
+
+  // Validate that the user is not trying to mix Animated and Reanimated before updating the config.
+  if (
+    __DEV__ &&
+    config.dispatchesAnimatedEvents &&
+    (config.disableReanimated === false || config.runOnJS === false)
+  ) {
+    throw new Error(
+      tagMessage(
+        'Animated cannot be used together with Reanimated in the same gesture. Please choose either Animated or Reanimated for handling gesture events.'
+      )
+    );
+  }
+
+  if (config.dispatchesAnimatedEvents) {
+    config.disableReanimated = true;
+  }
+
   config.shouldUseReanimatedDetector =
     !config.disableReanimated &&
     Reanimated !== undefined &&
-    hasWorkletEventHandlers(config);
+    hasWorkletEventHandlers(config) &&
+    !config.dispatchesAnimatedEvents;
   config.needsPointerData = shouldHandleTouchEvents(config);
-  config.dispatchesAnimatedEvents = isAnimatedEvent(config.onUpdate);
   config.dispatchesReanimatedEvents =
     config.shouldUseReanimatedDetector && !runOnJS;
 }

packages/react-native-gesture-handler/src/v3/hooks/utils/eventUtils.ts

@@ -40,7 +40,7 @@ export function isEventForHandlerWithTag<THandlerData>(
   return event.handlerTag === handlerTag;
 }
 
-export function isAnimatedEvent<THandlerData>(
+export function isNativeAnimatedEvent<THandlerData>(
   callback:
     | ((event: GestureUpdateEvent<THandlerData>) => void)
     | AnimatedEvent

packages/react-native-gesture-handler/src/v3/hooks/utils/propsWhiteList.ts

@@ -53,6 +53,8 @@ export const PropsToFilter = new Set<BaseGestureConfig<unknown, unknown>>([
   'changeEventCalculator',
   'disableReanimated',
   'shouldUseReanimatedDetector',
+  'useAnimated',
+  'runOnJS',
 
   // Relations
   'simultaneousWithExternalGesture',

packages/react-native-gesture-handler/src/v3/types/ConfigTypes.ts

@@ -25,7 +25,9 @@ export type GestureCallbacks<THandlerData> = {
     event: GestureStateChangeEvent<THandlerData>,
     didSucceed: boolean
   ) => void;
-  onUpdate?: (event: GestureUpdateEvent<THandlerData>) => void | AnimatedEvent;
+  onUpdate?:
+    | ((event: GestureUpdateEvent<THandlerData>) => void)
+    | AnimatedEvent;
   onTouchesDown?: (event: GestureTouchEvent) => void;
   onTouchesMove?: (event: GestureTouchEvent) => void;
   onTouchesUp?: (event: GestureTouchEvent) => void;
@@ -48,6 +50,7 @@ export type InternalConfigProps<THandlerData> = {
 
 export type CommonGestureConfig = {
   disableReanimated?: boolean;
+  useAnimated?: boolean;
 } & WithSharedValue<
   {
     runOnJS?: boolean;

packages/react-native-gesture-handler/src/v3/types/DetectorTypes.ts

@@ -3,6 +3,7 @@ import {
   StateChangeEvent,
   UpdateEvent,
   TouchEvent,
+  GestureUpdateEvent,
 } from './EventTypes';
 
 export type DetectorCallbacks<THandlerData> = {
@@ -18,7 +19,10 @@ export type DetectorCallbacks<THandlerData> = {
     | undefined
     | ((event: UpdateEvent<THandlerData>) => void);
   onReanimatedTouchEvent: undefined | ((event: TouchEvent) => void);
-  onGestureHandlerAnimatedEvent: undefined | AnimatedEvent;
+  onGestureHandlerAnimatedEvent:
+    | undefined
+    | AnimatedEvent
+    | ((event: GestureUpdateEvent<THandlerData>) => void);
 };
 
 export type VirtualChild = {