One detector to rule them all (#3732)

## Description

To simplify migration the `GestureDetector` will check the type of the
gesture it receives and render the detector accordingly it:
* Checks if the gesture it received is V2 or V2:
* If it's V2, it renders the old `GestureDetector` component
* If it's V3, it checks for the `InterceptingGestureDetector` context:
* If context is there, it's inside boundary and renders `LogicDetector`
* If the context is not there, it renders `NativeDetector`

### Why separate `NativeDetector` and `InterceptingGestureDetector`?

We did some [performance
tests](#3689 (comment))
on the `NativeDetector` after adding changes that handle attaching
`LogicDetector`, which revealed that the new logic adds quite a bit of
overhead, but only on the JS side. New logic on the native side does not
seem to have a significant effect.
We concluded that the best solution is to create a separate component
that will have all functionalities of `NativeDetector` and also allow
`LogicDetector` attachment, while NativeDetector will be reverted to how
it had been before implementing `LogicDetector`.

## Test plan

Rendering `LogicDetector`:
<details>

```tsx
import React from 'react';
import { Text, View, StyleSheet } from 'react-native';
import { GestureDetectorBoundary, GestureDetector, useTap, GestureHandlerRootView } from 'react-native-gesture-handler';

import Svg, { Circle, Rect } from 'react-native-svg';

export default function SvgExample() {
  const circleElementTap = useTap({
    onStart: () => {
      'worklet';
      console.log('RNGH: clicked circle')
    },
  });
  const rectElementTap = useTap({
    onStart: () => {
      'worklet';
      console.log('RNGH: clicked parallelogram')
    },
  });

  return (
    <GestureHandlerRootView>
      <View style={styles.container}>
        <Text style={styles.header}>
          Overlapping SVGs with gesture detectors
        </Text>
        <View style={{ backgroundColor: 'tomato' }}>
          <GestureDetectorBoundary>
            <Svg
              height="250"
              width="250"
              onPress={() => console.log('SVG: clicked container')}>
              <GestureDetector gesture={circleElementTap}>
                <Circle
                  cx="125"
                  cy="125"
                  r="125"
                  fill="green"
                  onPress={() => console.log('SVG: clicked circle')}
                />
              </GestureDetector>
              <GestureDetector gesture={rectElementTap}>
                <Rect
                  skewX="45"
                  width="125"
                  height="250"
                  fill="yellow"
                  onPress={() => console.log('SVG: clicked parallelogram')}
                />
              </GestureDetector>
            </Svg>
          </GestureDetectorBoundary>
        </View>
        <Text>
          Tapping each color should read to a different console.log output
        </Text>
      </View>
    </GestureHandlerRootView>
  );
}

const styles = StyleSheet.create({
  container: {
    alignItems: 'center',
    justifyContent: 'center',
    marginBottom: 48,
  },
  header: {
    fontSize: 18,
    fontWeight: 'bold',
    margin: 10,
  },
});
```

</details

Rendering `NativeDetector`:
<details>

```tsx
import React from 'react';
import { StyleSheet, View } from 'react-native';
import {
  GestureDetector,
  useTap,
} from 'react-native-gesture-handler';
import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withTiming,
  Easing,
  interpolateColor,
} from 'react-native-reanimated';

export default function SimpleTap() {
  const colorValue = useSharedValue(0);

  const tapGesture = useTap({
    onStart: () => {
      'worklet';
      colorValue.value = withTiming(colorValue.value === 0 ? 1 : 0, {
        duration: 400,
        easing: Easing.inOut(Easing.ease),
      });
    },
  });

  const animatedStyle = useAnimatedStyle(() => {
    const backgroundColor = interpolateColor(
      colorValue.value,
      [0, 1],
      ['#b58df1', '#ff7f50'] // purple → coral
    );

    return {
      backgroundColor,
    };
  });

  return (
    <View style={styles.centerView}>
      <GestureDetector gesture={tapGesture}>
        <Animated.View style={[styles.box, animatedStyle]} />
      </GestureDetector>
    </View>
  );
}

const styles = StyleSheet.create({
  centerView: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
  box: {
    height: 120,
    width: 120,
    backgroundColor: '#b58df1',
    marginBottom: 30,
    borderRadius: 12,
  },
});
```

</details

Rendering old v2 `GestureDetector`:
<details>

```tsx
import React from 'react';
import { StyleSheet, View } from 'react-native';
import {
  Gesture,
  GestureDetector,
} from 'react-native-gesture-handler';
import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withTiming,
  Easing,
  interpolateColor,
} from 'react-native-reanimated';

export default function SimpleTap() {
  const colorValue = useSharedValue(0);

  const tapGesture = Gesture.Tap()
    .onStart(() => {
      'worklet';
      colorValue.value = withTiming(colorValue.value === 0 ? 1 : 0, {
        duration: 400,
        easing: Easing.inOut(Easing.ease),
      });
    });

  const animatedStyle = useAnimatedStyle(() => {
    const backgroundColor = interpolateColor(
      colorValue.value,
      [0, 1],
      ['#b58df1', '#ff7f50'] // purple → coral
    );

    return {
      backgroundColor,
    };
  });

  return (
    <View style={styles.centerView}>
      <GestureDetector gesture={tapGesture}>
        <Animated.View style={[styles.box, animatedStyle]} />
      </GestureDetector>
    </View>
  );
}

const styles = StyleSheet.create({
  centerView: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
  },
  box: {
    height: 120,
    width: 120,
    backgroundColor: '#b58df1',
    marginBottom: 30,
    borderRadius: 12,
  },
});

```

</details

Author: akwasniewski

apps/basic-example/src/NativeDetector.tsx

@@ -2,7 +2,7 @@ import * as React from 'react';
 import { Animated, Button, useAnimatedValue } from 'react-native';
 import {
   GestureHandlerRootView,
-  NativeDetector,
+  GestureDetector,
   usePan,
 } from 'react-native-gesture-handler';
 
@@ -32,7 +32,7 @@ export default function App() {
       />
 
       {visible && (
-        <NativeDetector gesture={gesture}>
+        <GestureDetector gesture={gesture}>
           <Animated.View
             style={[
               {
@@ -48,7 +48,7 @@ export default function App() {
               { transform: [{ translateX: value }] },
             ]}
           />
-        </NativeDetector>
+        </GestureDetector>
       )}
     </GestureHandlerRootView>
   );

apps/basic-example/src/Text.tsx

@@ -3,8 +3,7 @@ import { StyleSheet, Text, View } from 'react-native';
 import {
   Gesture,
   GestureDetector,
-  LogicDetector,
-  NativeDetector,
+  InterceptingGestureDetector,
   useTap,
 } from 'react-native-gesture-handler';
 
@@ -37,24 +36,24 @@ function NativeDetectorExample() {
       <Text style={styles.header}>
         Native Detector example - this one should work
       </Text>
-      <NativeDetector gesture={tapAll}>
+      <InterceptingGestureDetector gesture={tapAll}>
         <Text style={{ fontSize: 18, textAlign: 'center' }}>
           Some text example running with RNGH
-          <LogicDetector gesture={tapFirstPart}>
+          <GestureDetector gesture={tapFirstPart}>
             <Text style={{ fontSize: 24, color: COLORS.NAVY }}>
               {' '}
               try tapping on this part
             </Text>
-          </LogicDetector>
-          <LogicDetector gesture={tapSecondPart}>
+          </GestureDetector>
+          <GestureDetector gesture={tapSecondPart}>
             <Text style={{ fontSize: 28, color: COLORS.KINDA_BLUE }}>
               {' '}
               or on this part
             </Text>
-          </LogicDetector>
+          </GestureDetector>
           this part is not special :(
         </Text>
-      </NativeDetector>
+      </InterceptingGestureDetector>
     </View>
   );
 }

packages/react-native-gesture-handler/src/__tests__/RelationsTraversal.test.tsx

@@ -1,7 +1,7 @@
 import { tagMessage } from '../utils';
 import { useExclusive, useRace, useSimultaneous } from '../v3/hooks/relations';
 import { useGesture } from '../v3/hooks/useGesture';
-import { configureRelations } from '../v3/NativeDetector/utils';
+import { configureRelations } from '../v3/detectors/utils';
 import { SingleGesture, SingleGestureName } from '../v3/types';
 import { renderHook } from '@testing-library/react-native';
 

packages/react-native-gesture-handler/src/handlers/gestures/GestureDetector/index.tsx

@@ -42,7 +42,7 @@ function propagateDetectorConfig(
   }
 }
 
-interface GestureDetectorProps {
+export interface GestureDetectorProps {
   children?: React.ReactNode;
   /**
    * A gesture object containing the configuration and callbacks.

packages/react-native-gesture-handler/src/index.ts

@@ -51,7 +51,7 @@ export { RotationGestureHandler } from './handlers/RotationGestureHandler';
 export { FlingGestureHandler } from './handlers/FlingGestureHandler';
 export { default as createNativeWrapper } from './handlers/createNativeWrapper';
 export type { NativeViewGestureHandlerProps } from './handlers/NativeViewGestureHandler';
-export { GestureDetector } from './handlers/gestures/GestureDetector';
+export { GestureDetector as LegacyGestureDetector } from './handlers/gestures/GestureDetector';
 export { GestureObjects as Gesture } from './handlers/gestures/gestureObjects';
 export type { TapGestureType as LegacyTapGesture } from './handlers/gestures/tapGesture';
 export type { PanGestureType as LegacyPanGesture } from './handlers/gestures/panGesture';
@@ -149,10 +149,12 @@ export type {
 } from './components/Pressable';
 export { default as Pressable } from './components/Pressable';
 
-export type { NativeDetectorProps } from './v3/NativeDetector/NativeDetector';
-export { NativeDetector } from './v3/NativeDetector/NativeDetector';
+export {
+  GestureDetector,
+  InterceptingGestureDetector,
+  GestureDetectorProps,
+} from './v3/detectors';
 
-export { LogicDetector } from './v3/LogicDetector';
 export * from './v3/hooks/useGesture';
 export * from './v3/hooks/relations';
 

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

@@ -0,0 +1,31 @@
+import { NativeDetectorProps } from './common';
+import { BaseGesture } from '../../handlers/gestures/gesture';
+import { NativeDetector } from './NativeDetector';
+import { ComposedGesture } from '../../handlers/gestures/gestureComposition';
+import {
+  GestureDetectorProps as LegacyGestureDetectorProps,
+  GestureDetector as LegacyGestureDetector,
+} from '../../handlers/gestures/GestureDetector';
+import { DetectorContext } from './LogicDetector/useDetectorContext';
+import { LogicDetector } from './LogicDetector/LogicDetector';
+import { use } from 'react';
+
+export function GestureDetector<THandlerData, TConfig>(
+  props: NativeDetectorProps<THandlerData, TConfig> | LegacyGestureDetectorProps
+) {
+  if (
+    props.gesture instanceof ComposedGesture ||
+    props.gesture instanceof BaseGesture
+  ) {
+    return <LegacyGestureDetector {...(props as LegacyGestureDetectorProps)} />;
+  }
+
+  const context = use(DetectorContext);
+  return context ? (
+    <LogicDetector {...(props as NativeDetectorProps<THandlerData, TConfig>)} />
+  ) : (
+    <NativeDetector
+      {...(props as NativeDetectorProps<THandlerData, TConfig>)}
+    />
+  );
+}

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

@@ -110,6 +110,11 @@ const HostGestureDetector = (props: GestureHandlerDetectorProps) => {
     );
 
     props.logicChildren?.forEach((child) => {
+      if (child.viewRef.current == null) {
+        // We must check whether viewRef is  not null as otherwise we get an error when intercepting gesture detector
+        // switches its component based on whether animated/reanimated events should run.
+        return;
+      }
       if (!attachedLogicHandlers.current.has(child.viewTag)) {
         attachedLogicHandlers.current.set(child.viewTag, new Set());
       }

packages/react-native-gesture-handler/src/v3/NativeDetector/HostGestureDetector.web.tsx renamed to packages/react-native-gesture-handler/src/v3/detectors/HostGestureDetector.web.tsx

@@ -1,46 +1,55 @@
 import React, { RefObject, useCallback, useRef, useState } from 'react';
-import { Animated, StyleSheet } from 'react-native';
-import HostGestureDetector from './HostGestureDetector';
-import { tagMessage } from '../../utils';
+import HostGestureDetector from '../HostGestureDetector';
 import {
   LogicChildren,
-  Gesture,
-  DetectorCallbacks,
   GestureHandlerEvent,
-} from '../types';
+  DetectorCallbacks,
+} from '../../types';
 import { DetectorContext } from './useDetectorContext';
-import { Reanimated } from '../../handlers/gestures/reanimatedWrapper';
-import { configureRelations } from './utils';
-import { isComposedGesture } from '../hooks/utils/relationUtils';
-
-export interface NativeDetectorProps<THandlerData, TConfig> {
-  children?: React.ReactNode;
-  gesture: Gesture<THandlerData, TConfig>;
-}
-
-const AnimatedNativeDetector =
-  Animated.createAnimatedComponent(HostGestureDetector);
-
-const ReanimatedNativeDetector =
-  Reanimated?.default.createAnimatedComponent(HostGestureDetector);
-
-export function NativeDetector<THandlerData, TConfig>({
+import { Reanimated } from '../../../handlers/gestures/reanimatedWrapper';
+import { configureRelations, ensureNativeDetectorComponent } from '../utils';
+import { isComposedGesture } from '../../hooks/utils/relationUtils';
+import {
+  AnimatedNativeDetector,
+  InterceptingGestureDetectorProps,
+  nativeDetectorStyles,
+  ReanimatedNativeDetector,
+} from '../common';
+import { tagMessage } from '../../../utils';
+
+export function InterceptingGestureDetector<THandlerData, TConfig>({
   gesture,
   children,
-}: NativeDetectorProps<THandlerData, TConfig>) {
+}: InterceptingGestureDetectorProps<THandlerData, TConfig>) {
   const [logicChildren, setLogicChildren] = useState<LogicChildren[]>([]);
+
   const logicMethods = useRef<
     Map<number, RefObject<DetectorCallbacks<unknown>>>
   >(new Map());
 
-  const NativeDetectorComponent = gesture.config.dispatchesAnimatedEvents
+  const [shouldUseReanimated, setShouldUseReanimated] = useState(
+    gesture ? gesture.config.shouldUseReanimatedDetector : false
+  );
+  const [dispatchesAnimatedEvents, setDispatchesAnimatedEvents] = useState(
+    gesture ? gesture.config.dispatchesAnimatedEvents : false
+  );
+
+  const NativeDetectorComponent = dispatchesAnimatedEvents
     ? AnimatedNativeDetector
-    : gesture.config.shouldUseReanimatedDetector
+    : shouldUseReanimated
       ? ReanimatedNativeDetector
       : HostGestureDetector;
 
   const register = useCallback(
-    (child: LogicChildren, methods: RefObject<DetectorCallbacks<unknown>>) => {
+    (
+      child: LogicChildren,
+      methods: RefObject<DetectorCallbacks<unknown>>,
+      forReanimated: boolean | undefined,
+      forAnimated: boolean | undefined
+    ) => {
+      setShouldUseReanimated(!!forReanimated);
+      setDispatchesAnimatedEvents(!!forAnimated);
+
       setLogicChildren((prev) => {
         const index = prev.findIndex((c) => c.viewTag === child.viewTag);
         if (index !== -1) {
@@ -76,11 +85,9 @@ export function NativeDetector<THandlerData, TConfig>({
     );
   }
 
-  configureRelations(gesture);
-
   const handleGestureEvent = (key: keyof DetectorCallbacks<THandlerData>) => {
     return (e: GestureHandlerEvent<THandlerData>) => {
-      if (gesture.detectorCallbacks[key]) {
+      if (gesture?.detectorCallbacks[key]) {
         gesture.detectorCallbacks[key](e);
       }
 
@@ -97,7 +104,7 @@ export function NativeDetector<THandlerData, TConfig>({
     (key: keyof DetectorCallbacks<unknown>) => {
       const handlers: ((e: GestureHandlerEvent<THandlerData>) => void)[] = [];
 
-      if (gesture.detectorCallbacks[key]) {
+      if (gesture?.detectorCallbacks[key]) {
         handlers.push(
           gesture.detectorCallbacks[key] as (
             e: GestureHandlerEvent<unknown>
@@ -116,21 +123,27 @@ export function NativeDetector<THandlerData, TConfig>({
 
       return handlers;
     },
-    [logicChildren, gesture.detectorCallbacks]
+    [logicChildren, gesture?.detectorCallbacks]
   );
 
   const reanimatedEventHandler = Reanimated?.useComposedEventHandler(
     getHandlers('onReanimatedUpdateEvent')
   );
-  const reanimedStateChangeHandler = Reanimated?.useComposedEventHandler(
+  const reanimatedStateChangeHandler = Reanimated?.useComposedEventHandler(
     getHandlers('onReanimatedStateChange')
   );
   const reanimatedTouchEventHandler = Reanimated?.useComposedEventHandler(
     getHandlers('onReanimatedTouchEvent')
   );
 
+  ensureNativeDetectorComponent(NativeDetectorComponent);
+
+  if (gesture) {
+    configureRelations(gesture);
+  }
+
   return (
-    <DetectorContext.Provider value={{ register, unregister }}>
+    <DetectorContext value={{ register, unregister }}>
       <NativeDetectorComponent
         // @ts-ignore This is a type mismatch between RNGH types and RN Codegen types
         onGestureHandlerStateChange={handleGestureEvent(
@@ -140,32 +153,36 @@ export function NativeDetector<THandlerData, TConfig>({
         onGestureHandlerEvent={handleGestureEvent('onGestureHandlerEvent')}
         // @ts-ignore This is a type mismatch between RNGH types and RN Codegen types
         onGestureHandlerAnimatedEvent={
-          gesture.detectorCallbacks.onGestureHandlerAnimatedEvent
+          gesture?.detectorCallbacks.onGestureHandlerAnimatedEvent
         }
         // @ts-ignore This is a type mismatch between RNGH types and RN Codegen types
         onGestureHandlerTouchEvent={handleGestureEvent(
           'onGestureHandlerTouchEvent'
         )}
         // @ts-ignore This is a type mismatch between RNGH types and RN Codegen types
-        onGestureHandlerReanimatedStateChange={reanimatedEventHandler}
+        onGestureHandlerReanimatedStateChange={
+          shouldUseReanimated ? reanimatedStateChangeHandler : undefined
+        }
         // @ts-ignore This is a type mismatch between RNGH types and RN Codegen types
-        onGestureHandlerReanimatedEvent={reanimedStateChangeHandler}
+        onGestureHandlerReanimatedEvent={
+          shouldUseReanimated ? reanimatedEventHandler : undefined
+        }
         // @ts-ignore This is a type mismatch between RNGH types and RN Codegen types
-        onGestureHandlerReanimatedTouchEvent={reanimatedTouchEventHandler}
+        onGestureHandlerReanimatedTouchEvent={
+          shouldUseReanimated ? reanimatedTouchEventHandler : undefined
+        }
         moduleId={globalThis._RNGH_MODULE_ID}
-        handlerTags={isComposedGesture(gesture) ? gesture.tags : [gesture.tag]}
-        style={styles.detector}
+        handlerTags={
+          gesture
+            ? isComposedGesture(gesture)
+              ? gesture.tags
+              : [gesture.tag]
+            : []
+        }
+        style={nativeDetectorStyles.detector}
         logicChildren={logicChildren}>
         {children}
       </NativeDetectorComponent>
-    </DetectorContext.Provider>
+    </DetectorContext>
   );
 }
-
-const styles = StyleSheet.create({
-  detector: {
-    display: 'contents',
-    // TODO: remove, debug info only
-    backgroundColor: 'red',
-  },
-});

packages/react-native-gesture-handler/src/v3/NativeDetector/NativeDetector.tsx renamed to packages/react-native-gesture-handler/src/v3/detectors/LogicDetector/InterceptingGestureDetector.tsx

@@ -1,19 +1,29 @@
 import { RefObject, useCallback, useEffect, useRef, useState } from 'react';
-import { Wrap } from '../handlers/gestures/GestureDetector/Wrap';
+import { Wrap } from '../../../handlers/gestures/GestureDetector/Wrap';
 import { findNodeHandle, Platform } from 'react-native';
-import { useDetectorContext } from './NativeDetector/useDetectorContext';
-import { NativeDetectorProps } from './NativeDetector/NativeDetector';
-import { isComposedGesture } from './hooks/utils/relationUtils';
-import { DetectorCallbacks } from './types';
+import { useDetectorContext } from './useDetectorContext';
+import { isComposedGesture } from '../../hooks/utils/relationUtils';
+import { NativeDetectorProps } from '../common';
+import { configureRelations } from '../utils';
+import { tagMessage } from '../../../utils';
+import { DetectorCallbacks } from '../../types';
 
 export function LogicDetector<THandlerData, TConfig>(
   props: NativeDetectorProps<THandlerData, TConfig>
 ) {
-  const { register, unregister } = useDetectorContext();
+  const context = useDetectorContext();
+  if (!context) {
+    throw new Error(
+      tagMessage(
+        'Logic detector must be a descendant of an InterceptingGestureDecector'
+      )
+    );
+  }
+  const { register, unregister } = context;
+
   const viewRef = useRef(null);
   const [viewTag, setViewTag] = useState<number>(-1);
   const logicMethods = useRef(props.gesture.detectorCallbacks);
-
   const handleRef = useCallback((node: any) => {
     viewRef.current = node;
     if (!node) {
@@ -52,12 +62,19 @@ export function LogicDetector<THandlerData, TConfig>(
       Object.assign(logicProps, { viewRef });
     }
 
-    register(logicProps, logicMethods as RefObject<DetectorCallbacks<unknown>>);
+    register(
+      logicProps,
+      logicMethods as RefObject<DetectorCallbacks<unknown>>,
+      props.gesture.config.shouldUseReanimatedDetector,
+      props.gesture.config.dispatchesAnimatedEvents
+    );
 
     return () => {
       unregister(viewTag, handlerTags);
     };
   }, [viewTag, props.gesture, register, unregister]);
 
+  configureRelations(props.gesture);
+
   return <Wrap ref={handleRef}>{props.children}</Wrap>;
 }