Handle Animated.Event in onUpdate callback (#3630)

## Description

This PR automatically assigns `onUpdate` callback to `onGestureHandlerAnimatedEvent` when `Animated.Event` is passed. It also checks whether `change*` fields were used in `Animated.Event` - if so, we throw an error.

## Test plan

Since basic example is already "under construction", I'll copy whole code. Forgive me for I have sinned 🙏 

Basically it covers the case where we switch between `Animated.Event` and standard callback, along with using `change*` in `Animated.Event`.


<details>
<summary> Test code </summary>

```tsx
import * as React from 'react';
import { Animated, Button, useAnimatedValue } from 'react-native';
import {
  GestureHandlerRootView,
  NativeDetector,
  useGesture,
} from 'react-native-gesture-handler';

export default function App() {
  const [visible, setVisible] = React.useState(true);
  const [shouldUseAnimated, setShouldUseAnimated] = React.useState(true);

  const value = useAnimatedValue(0);
  const animatedEvent = Animated.event(
    [
      { nativeEvent: { handlerData: { translationX: value } } },
      // { nativeEvent: { handlerData: { changeX: 10 } } },
    ],
    {
      useNativeDriver: true,
    }
  );
  const jsCallback = (e: any) => console.log(e.nativeEvent);

  // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
  const gesture = useGesture('PanGestureHandler', {
    // onGestureHandlerAnimatedEvent: event,
    // onGestureHandlerEvent: (e: any) =>
    //   console.log('onGestureHandlerEvent', e.nativeEvent),
    onUpdate: shouldUseAnimated ? animatedEvent : jsCallback,
    onEnd: (_e: any) => {
      setShouldUseAnimated((prev) => !prev);
    },

    changeEventCalculator: (event: any, _lastUpdateEvent: any) => {
      return { ...event.nativeEvent, changeX: 10 };
    },
  });

  return (
    <GestureHandlerRootView
      style={{ flex: 1, backgroundColor: 'white', paddingTop: 8 }}>
      <Button
        title="Toggle visibility"
        onPress={() => {
          setVisible(!visible);
        }}
      />

      {visible && (
        <NativeDetector gesture={gesture}>
          <Animated.View
            style={[
              {
                width: 150,
                height: 150,
                backgroundColor: 'blue',
                opacity: 0.5,
                borderWidth: 10,
                borderColor: 'green',
                marginTop: 20,
                marginLeft: 40,
              },
              { transform: [{ translateX: value }] },
            ]}
          />
        </NativeDetector>
      )}
    </GestureHandlerRootView>
  );
}

```

</details>

Author: m-bert

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

@@ -1,5 +1,9 @@
 import { CALLBACK_TYPE } from '../../../handlers/gestures/gesture';
-import { isEventForHandlerWithTag, runWorkletCallback } from '../utils';
+import {
+  isAnimatedEvent,
+  isEventForHandlerWithTag,
+  runWorkletCallback,
+} from '../utils';
 import {
   Reanimated,
   ReanimatedContext,
@@ -49,8 +53,10 @@ export function useGestureHandlerEvent(
   };
 
   if (config.disableReanimated) {
-    return (event: UpdateEvent<Record<string, unknown>>) =>
-      onGestureHandlerEvent(event, jsContext);
+    return isAnimatedEvent(config.onUpdate)
+      ? undefined
+      : (event: UpdateEvent<Record<string, unknown>>) =>
+          onGestureHandlerEvent(event, jsContext);
   }
 
   // eslint-disable-next-line react-hooks/rules-of-hooks
@@ -65,8 +71,10 @@ export function useGestureHandlerEvent(
     !!reanimatedHandler?.doDependenciesDiffer
   );
 
-  return shouldUseReanimated
-    ? reanimatedEvent
-    : (event: UpdateEvent<Record<string, unknown>>) =>
-        onGestureHandlerEvent(event, jsContext);
+  return isAnimatedEvent(config.onUpdate)
+    ? undefined
+    : shouldUseReanimated
+      ? reanimatedEvent
+      : (event: UpdateEvent<Record<string, unknown>>) =>
+          onGestureHandlerEvent(event, jsContext);
 }

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

@@ -4,6 +4,7 @@ import RNGestureHandlerModule from '../../RNGestureHandlerModule';
 import { useGestureEvent } from './useGestureEvent';
 import { Reanimated } from '../../handlers/gestures/reanimatedWrapper';
 import { tagMessage } from '../../utils';
+import { AnimatedEvent } from '../types';
 
 type GestureType =
   | 'TapGestureHandler'
@@ -18,9 +19,9 @@ type GestureType =
 
 type GestureEvents = {
   onGestureHandlerStateChange: (event: any) => void;
-  onGestureHandlerEvent: (event: any) => void;
+  onGestureHandlerEvent: undefined | ((event: any) => void);
   onGestureHandlerTouchEvent: (event: any) => void;
-  onGestureHandlerAnimatedEvent: (event: any) => void;
+  onGestureHandlerAnimatedEvent: undefined | AnimatedEvent;
 };
 
 export interface NativeGesture {
@@ -77,7 +78,8 @@ export function useGesture(
   // we have to mark these as possibly undefined to make TypeScript happy.
   if (
     !onGestureHandlerStateChange ||
-    !onGestureHandlerEvent ||
+    // If onUpdate is an AnimatedEvent, `onGestureHandlerEvent` will be undefined and vice versa.
+    (!onGestureHandlerEvent && !onGestureHandlerAnimatedEvent) ||
     !onGestureHandlerTouchEvent
   ) {
     throw new Error(tagMessage('Failed to create event handlers.'));
@@ -98,10 +100,10 @@ export function useGesture(
   useEffect(() => {
     // TODO: filter changes - passing functions (and possibly other types)
     // causes a native crash
-    const animatedEvent = config.onGestureHandlerAnimatedEvent;
-    config.onGestureHandlerAnimatedEvent = null;
+    const animatedEvent = config.onUpdate;
+    config.onUpdate = null;
     RNGestureHandlerModule.updateGestureHandler(tag, config);
-    config.onGestureHandlerAnimatedEvent = animatedEvent;
+    config.onUpdate = animatedEvent;
 
     RNGestureHandlerModule.flushOperations();
   }, [config, tag]);
@@ -118,7 +120,7 @@ export function useGesture(
     },
     shouldUseReanimated,
     dispatchesAnimatedEvents:
-      onGestureHandlerAnimatedEvent &&
+      !!onGestureHandlerAnimatedEvent &&
       '__isNative' in onGestureHandlerAnimatedEvent,
   };
 }

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

@@ -1,6 +1,8 @@
 import { useGestureStateChangeEvent } from './events/useGestureStateChangeEvent';
 import { useGestureHandlerEvent } from './events/useGestureHandlerEvent';
 import { useTouchEvent } from './events/useTouchEvent';
+import { AnimatedEvent } from '../types';
+import { checkMappingForChangeProperties, isAnimatedEvent } from './utils';
 
 export function useGestureEvent(
   handlerTag: number,
@@ -24,10 +26,16 @@ export function useGestureEvent(
     shouldUseReanimated
   );
 
-  // TODO: Assign `onGestureHandlerAnimatedEvent` automatically when user passes `onUpdate` callback as Animated.Event
-  // Also throw error when someone uses `change*` properties with Animated Event in `onUpdate`
-  const onGestureHandlerAnimatedEvent =
-    config.onGestureHandlerAnimatedEvent as (...args: any[]) => void;
+  let onGestureHandlerAnimatedEvent: AnimatedEvent | undefined;
+
+  if (isAnimatedEvent(config.onUpdate)) {
+    for (const mapping of config.onUpdate._argMapping) {
+      checkMappingForChangeProperties(mapping);
+    }
+
+    // TODO: Remove cast when config is properly typed.
+    onGestureHandlerAnimatedEvent = config.onUpdate as AnimatedEvent;
+  }
 
   return {
     onGestureHandlerStateChange,

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

@@ -1,13 +1,15 @@
-import { NativeSyntheticEvent } from 'react-native';
+import { Animated, NativeSyntheticEvent } from 'react-native';
 import { CALLBACK_TYPE } from '../../handlers/gestures/gesture';
 import { TouchEventType } from '../../TouchEventType';
 import {
+  AnimatedEvent,
   CallbackHandlers,
   GestureHandlerEvent,
   GestureStateChangeEventWithData,
   GestureUpdateEventWithData,
 } from '../types';
 import { GestureTouchEvent } from '../../handlers/gestureHandlerCommon';
+import { tagMessage } from '../../utils';
 
 export function getHandler(type: CALLBACK_TYPE, config: CallbackHandlers) {
   'worklet';
@@ -85,3 +87,25 @@ export function isEventForHandlerWithTag(
     ? event.nativeEvent.handlerTag === handlerTag
     : event.handlerTag === handlerTag;
 }
+
+export function isAnimatedEvent(
+  callback: ((event: any) => void) | AnimatedEvent
+): callback is AnimatedEvent {
+  'worklet';
+
+  return '_argMapping' in callback;
+}
+
+export function checkMappingForChangeProperties(obj: Animated.Mapping) {
+  if (!('nativeEvent' in obj) || !('handlerData' in obj.nativeEvent)) {
+    return;
+  }
+
+  for (const key in obj.nativeEvent.handlerData) {
+    if (key.startsWith('change')) {
+      throw new Error(
+        tagMessage(`${key} is not available when using Animated.Event.`)
+      );
+    }
+  }
+}

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

@@ -41,3 +41,10 @@ export type CallbackHandlers = Omit<
   | 'changeEventCalculator'
   | 'onChange'
 >;
+
+// This is almost how Animated.event is typed in React Native. We add _argMapping in order to:
+// 1. Distinguish it from a regular function,
+// 2. Have access to the _argMapping property to check for usage of `change*` callbacks.
+export type AnimatedEvent = ((...args: any[]) => void) & {
+  _argMapping?: unknown;
+};