Gesture relations (#3693)

> [!IMPORTANT]
> Supersede #3664.
>
> I've decided to create a separate PR since it was easier to start working on it directly than waiting for #3682 to be merged.

## Description

This PR introduces hooks to set relations between handlers. 

## API

New API replaces the old one as follows:

- `Gesture.Race(g1, g2)` $\rightarrow$ `useRace(g1, g2)`
- `Gesture.Exclusive(g1, g2)` $\rightarrow$ `useExclusive(g1, g2)`
- `Gesture.Simultaneous(g1, g2)` $\rightarrow$ `useSimultaneous(g1, g2)`

## Algorithm for populating relations

### Handling external relations
In order to properly handle gesture relations, we need to pass 3 arrays to the native side:

- `waitFor` - responsible for handling `Exclusive` and `requireExternalGestureToFail` relations
- `simultaneousHandlers` - responsible for `Simultaneous` and `simultaneousWithExternalGesture` relations
- `blocksHandlers` - responsible for `blocksExternalGesture` relation

At first, these arrays are filled with external relations in `useGesture` hook. Then we use `DFS` algorithm to add remaining relations, added with relation hooks. Since `Race` doesn't really change anything when it comes to gesture interactions, we can ignore it in our algorithm. 

### DFS overview

We use `DFS` because gesture relations form tree structure. 

<details>
<summary>The algorithm works as follows:</summary>

- Initialize two arrays: `waitFor` and `simultaneousHandlers`. If root node is `SimultaneousGesture`, we also add its handler tags into `simultaneousHandlers` array. This ensures that the algorithm works even if we have only `Simultaneous` as the root node (e.g. `useSimultaneous(g1, g1)`)
- Traverse the gesture tree:
  - If we are not in the `ComposedGesture`, it means that we reached leaf node. In that case we populate `waitFor` and `simultanoursHandlers` arrays into `node` arrays and then update relations on the native side
  - If we are in the `ComposedGesture`, then for each child:
    - If the child is not `ComposedGesture`:
      - We call `traverseGestureRelations` to reach stop condition and configure relations on the native side
      - If current node is `Exclusive`, then we add child `tag` to `waitFor` array
    - If the child is `ComposedGesture`:
      - On the way down:
        - Going from `non-simultaneous` gesture to `simultaneous` gesture we add all **child** tags into global `simulatneousHandlers` array
        - If we go from `simultaneous` to `non-simultaneous` gesture, we remove **child** tags instead of adding. 
      - We store length of `waitFor` to reset it later. 
      - We call `traverseGestureRelations`
      - On the way back:
        - if we go from `simultaneous` (child) to `non-simultaneous` (node) gesture, we remove **node** tags from `simultaneousHandlers`
        - Going from `non-simultaneous` (child) to `simultaneous` (node) gesture we add **node** tags instead of removing
        - Returning to `Exclusive` gesture means that we want to add all children tags into `waitFor`
        - If we return from `Exclusive` child to `non-exclusive` node, we want to reset `waitFor` to previous state, using `length` variable.

</details>

### Example 

Below you can see example of the algorithm. 

<details>
<summary>We use the following notation:</summary>

- Handlers and composition:
  - `E` - `Exclusive`
  - `S` - `Simultaneous`
  - `P` - `Pan`
  - `T` - `Tap`
- Relation arrays:
  - `SH` - `simultaneousHandlers`
  - `WF` - `waitFor`
- Operators:
  - `+=` -  adding tags
  - `-=` -  removing tags

</details>

_**Note:**_ vertex label in relation arrays expands to all tags in the composed gesture.

```mermaid
graph TB
    E1["E₁"] --> |SH += S₁| S1
    E1["E₁"] --> |SH += S₂| S2

    S1["S₁"] --> |SH -= S₁ <br/> WF += S₁| E1
    S1 --> |SH -= E₂| E2
    S1 --> P3
    E2["E₂"] --> |SH += E₂ <br/> WF -= E₂| S1
    P3["P₃ <br/> SH: {T₁, T₂, P₃}<br/>WF: #91;#93;"] --> S1

    E2 --> T1
    E2 --> T2
    T1["T₁ <br/> SH: {P₃}<br/>WF: #91;#93;"] --> |WF += T₁| E2
    T2["T₂ <br/> SH: {P₃}<br/>WF: #91;T₁#93;"] --> |WF += T₂| E2

    S2["S₂"] -->|SH -= S₂| E1
    S2 --> P4
    S2 --> P5
    P4["P₄ <br/> SH: {P₄, P₅}<br/>WF: #91;T₁, T₂, P₃#93;"] --> S2
    P5["P₅ <br/> SH: {P₄, P₅}<br/>WF: #91;T₁, T₂, P₃#93;"] --> S2

    style DFS fill-opacity:0,stroke-opacity:0,stroke-width:0px
```

## Limitations

Currently the following setup doesn't work on `android`:
```js
const composedGesture = useExclusive(tap1, useRace(pan1, pan2));
```

I've managed to find out what is the difference between this and using only `useRace`.

>[!WARNING]
> This problem seems to be present also on `main`, so I think it will be better to solve it in the follow-up PR.

For now, external relation props do not support composed gestures. Let me know if this should be done in this PR, or in a follow-up.

## Test plan

### Same detector interactions

Verified that the following relations work:

<details>
<summary>Android</summary>

- [x] `Simultaneous`
  - [x] Only JS
  - [x] Only Reanimated
  - [x] JS + Reanimated 
  - [x] JS + Animated
- [x] `Exclusive` 
  - [x] Only JS
  - [x] Only Reanimated
  - [x] JS + Reanimated
  - [x] JS + Animated
- [x] `Race` 
  - [x] Only JS
  - [x] Only Reanimated
  - [x] JS + Reanimated
  - [x] JS + Animated
- [x] Simple composition
  - [x] `Exclusive` + `Simultaneous` 

</details>

<details>
<summary>iOS</summary>

- [x] `Simultaneous`
  - [x] Only JS
  - [x] Only Reanimated
  - [x] JS + Reanimated 
  - [x] JS + Animated
- [x] `Exclusive` 
  - [x] Only JS
  - [x] Only Reanimated
  - [x] JS + Reanimated
  - [x] JS + Animated
- [x] `Race` 
  - [x] Only JS
  - [x] Only Reanimated
  - [x] JS + Reanimated
  - [x] JS + Animated
- [x] Simple composition
  - [x] `Exclusive` + `Simultaneous` 

</details>

<details>
<summary>Base code used for testing:</summary>

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

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

  const value = useAnimatedValue(0);
  const event = Animated.event(
    [{ nativeEvent: { handlerData: { translationX: value } } }],
    {
      useNativeDriver: true,
    }
  );

  const tap1 = useGesture('TapGestureHandler', {
    onEnd: () => {
      // 'worklet';
      console.log('Tap 1');
    },
    numberOfTaps: 1,
    disableReanimated: true,
  });

  const tap2 = useGesture('TapGestureHandler', {
    onEnd: () => {
      // 'worklet';
      console.log('Tap 2');
    },
    numberOfTaps: 2,
    disableReanimated: true,
  });

  const pan1 = useGesture('PanGestureHandler', {
    // onUpdate: event,
    onUpdate: (e) => {
      // 'worklet';
      console.log('Pan 1');
    },
    disableReanimated: true,
  });

  const pan2 = useGesture('PanGestureHandler', {
    onUpdate: (e) => {
      // 'worklet';
      console.log('Pan 2');
    },
    disableReanimated: true,
  });

  const composedGesture = useSimultaneous(pan1, pan2);

  // const composedGesture = useExclusive(tap2, tap1);
  // const composedGesture = useExclusive(pan2, pan1); // For Animtaed.Event
  // const composedGesture = useExclusive(pan1, pan2); // For Animtaed.Event

  // const composedGesture = useRace(pan1, pan2);
  // const composedGesture = useRace(pan2, pan1);

  // const composedGesture = useExclusive(tap1, useSimultaneous(pan1, pan2));

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

      {visible && (
        <NativeDetector gesture={composedGesture}>
          <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>

### Cross detector interactions

Verified that the following relations work:

<details>
<summary>Android</summary>

- [x] `simultaneousWithExternalGesture`
  - [x] Only JS
  - [x] Only Reanimated
  - [x] JS + Reanimated 
  - [x] JS + Animated
- [x] `requireExternalGestureToFail` 
  - [x] Only JS
  - [x] Only Reanimated
  - [x] JS + Reanimated
  - [x] JS + Animated
- [x] `blocksExternalGesture` 
  - [x] Only JS
  - [x] Only Reanimated
  - [x] JS + Reanimated
  - [x] JS + Animated

</details>

<details>
<summary>iOS</summary>

- [x] `simultaneousWithExternalGesture`
  - [x] Only JS
  - [x] Only Reanimated
  - [x] JS + Reanimated 
  - [x] JS + Animated
- [x] `requireExternalGestureToFail` 
  - [x] Only JS
  - [x] Only Reanimated
  - [x] JS + Reanimated
  - [x] JS + Animated
- [x] `blocksExternalGesture` 
  - [x] Only JS
  - [x] Only Reanimated
  - [x] JS + Reanimated
  - [x] JS + Animated

</details>

<details>
<summary>Base code used for testing:</summary>

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

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

  const value = useAnimatedValue(0);
  const event = Animated.event(
    [{ nativeEvent: { handlerData: { translationX: value } } }],
    {
      useNativeDriver: true,
    }
  );

  const tap1 = useGesture('TapGestureHandler', {
    onEnd: () => {
      // 'worklet';
      console.log('Tap 1');
    },
    numberOfTaps: 1,
    disableReanimated: true,
  });

  const tap2 = useGesture('TapGestureHandler', {
    onEnd: () => {
      // 'worklet';
      console.log('Tap 2');
    },
    numberOfTaps: 2,
    disableReanimated: true,
    blocksExternalGesture: tap1,
  });

  // const tap1 = useGesture('TapGestureHandler', {
  //   onEnd: () => {
  //     'worklet';
  //     console.log('Tap 1');
  //   },
  //   numberOfTaps: 1,
  //   // disableReanimated: true,
  //   requireExternalGestureToFail: tap2,
  // });

  const pan1 = useGesture('PanGestureHandler', {
    // onUpdate: event,
    onUpdate: (e) => {
      'worklet';
      console.log('Pan 1');
    },
    // disableReanimated: true,
  });

  const pan2 = useGesture('PanGestureHandler', {
    onUpdate: (e) => {
      'worklet';
      console.log('Pan 2');
    },
    simultaneousWithExternalGesture: pan1,
    // requireExternalGestureToFail: pan1,
    // blocksExternalGesture: pan1,
    // disableReanimated: true,
  });

  // const composedGesture = useSimultaneous(pan1, pan2);

  // const composedGesture = useExclusive(tap2, tap1);
  // const composedGesture = useExclusive(pan2, pan1); // For Animated.Event
  // const composedGesture = useExclusive(pan1, pan2); // For Animated.Event

  // const composedGesture = useRace(pan1, pan2);
  // const composedGesture = useRace(pan2, pan1);

  // const composedGesture = useExclusive(tap1, useSimultaneous(pan1, pan2));

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

      {visible && (
        <NativeDetector gesture={pan1}>
          <Animated.View
            style={[
              {
                width: 150,
                height: 150,
                backgroundColor: 'blue',
                opacity: 0.5,
                borderWidth: 10,
                borderColor: 'green',
                marginTop: 20,
                marginLeft: 40,
                display: 'flex',
                alignItems: 'center',
                justifyContent: 'space-around',
              },
              { transform: [{ translateX: value }] },
            ]}>
            <NativeDetector gesture={pan2}>
              <Animated.View
                style={{ width: 100, height: 100, backgroundColor: 'green' }}
              />
            </NativeDetector>
          </Animated.View>
        </NativeDetector>
      )}
    </GestureHandlerRootView>
  );
}
```

</details>

Author: m-bert

apps/basic-example/src/NativeDetector.tsx

@@ -3,6 +3,7 @@ import { Animated, Button, useAnimatedValue } from 'react-native';
 import {
   GestureHandlerRootView,
   NativeDetector,
+  SingleGestureName,
   useGesture,
 } from 'react-native-gesture-handler';
 
@@ -17,7 +18,7 @@ export default function App() {
     }
   );
 
-  const gesture = useGesture('PanGestureHandler', {
+  const gesture = useGesture(SingleGestureName.Pan, {
     onUpdate: event,
   });
 

packages/react-native-gesture-handler/android/src/main/java/com/swmansion/gesturehandler/react/RNGestureHandlerModule.kt

@@ -97,8 +97,6 @@ class RNGestureHandlerModule(reactContext: ReactApplicationContext?) :
     val handler = registry.getHandler(handlerTag) ?: return
     val factory = RNGestureHandlerFactoryUtil.findFactoryForHandler<GestureHandler>(handler) ?: return
 
-    interactionManager.dropRelationsForHandlerWithTag(handlerTag)
-    interactionManager.configureInteractions(handler, config)
     factory.setConfig(handler, config)
   }
 
@@ -111,6 +109,15 @@ class RNGestureHandlerModule(reactContext: ReactApplicationContext?) :
     factory.updateConfig(handler, config)
   }
 
+  @ReactMethod
+  override fun configureRelations(handlerTagDouble: Double, relations: ReadableMap) {
+    val handlerTag = handlerTagDouble.toInt()
+    val handler = registry.getHandler(handlerTag) ?: return
+
+    interactionManager.dropRelationsForHandlerWithTag(handlerTag)
+    interactionManager.configureInteractions(handler, relations)
+  }
+
   @ReactMethod
   override fun dropGestureHandler(handlerTagDouble: Double) {
     val handlerTag = handlerTagDouble.toInt()

packages/react-native-gesture-handler/android/src/main/java/com/swmansion/gesturehandler/react/events/RNGestureHandlerEvent.kt

@@ -59,7 +59,8 @@ class RNGestureHandlerEvent private constructor() : Event<RNGestureHandlerEvent>
     EVENT_NAME
   }
 
-  override fun canCoalesce() = true
+  // Unfortunately getCoalescingKey is not considered when sending event to C++, therefore we have to disable coalescing in v3
+  override fun canCoalesce() = actionType != GestureHandler.ACTION_TYPE_NATIVE_DETECTOR
 
   override fun getCoalescingKey() = coalescingKey
 

packages/react-native-gesture-handler/apple/RNGestureHandler.h

@@ -89,6 +89,7 @@
 - (void)resetConfig NS_REQUIRES_SUPER;
 - (void)setConfig:(nullable NSDictionary *)config NS_REQUIRES_SUPER;
 - (void)updateConfig:(nullable NSDictionary *)config NS_REQUIRES_SUPER;
+- (void)updateRelations:(nonnull NSDictionary *)relations;
 - (void)handleGesture:(nonnull id)recognizer;
 - (void)handleGesture:(nonnull id)recognizer inState:(RNGestureHandlerState)state;
 - (BOOL)containsPointInView;

packages/react-native-gesture-handler/apple/RNGestureHandler.mm

@@ -103,9 +103,6 @@ - (void)resetConfig
   self.enabled = YES;
   self.manualActivation = NO;
   _shouldCancelWhenOutside = NO;
-  _handlersToWaitFor = nil;
-  _simultaneousHandlers = nil;
-  _handlersThatShouldWait = nil;
   _hitSlop = RNGHHitSlopEmpty;
   _needsPointerData = NO;
   _dispatchesAnimatedEvents = NO;
@@ -123,10 +120,6 @@ - (void)setConfig:(NSDictionary *)config
 
 - (void)updateConfig:(NSDictionary *)config
 {
-  _handlersToWaitFor = [RCTConvert NSNumberArray:config[@"waitFor"]];
-  _simultaneousHandlers = [RCTConvert NSNumberArray:config[@"simultaneousHandlers"]];
-  _handlersThatShouldWait = [RCTConvert NSNumberArray:config[@"blocksHandlers"]];
-
   id prop = config[@"enabled"];
   if (prop != nil) {
     self.enabled = [RCTConvert BOOL:prop];
@@ -191,6 +184,13 @@ - (void)updateConfig:(NSDictionary *)config
   }
 }
 
+- (void)updateRelations:(NSDictionary *)relations
+{
+  _handlersToWaitFor = [RCTConvert NSNumberArray:relations[@"waitFor"]];
+  _simultaneousHandlers = [RCTConvert NSNumberArray:relations[@"simultaneousHandlers"]];
+  _handlersThatShouldWait = [RCTConvert NSNumberArray:relations[@"blocksHandlers"]];
+}
+
 - (void)setEnabled:(BOOL)enabled
 {
   _enabled = enabled;

packages/react-native-gesture-handler/apple/RNGestureHandlerManager.h

@@ -28,6 +28,8 @@
 
 - (void)updateGestureHandlerConfig:(nonnull NSNumber *)handlerTag config:(nonnull NSDictionary *)config;
 
+- (void)updateGestureHandlerRelations:(nonnull NSNumber *)handlerTag relations:(nonnull NSDictionary *)relations;
+
 - (void)dropGestureHandler:(nonnull NSNumber *)handlerTag;
 
 - (void)dropAllGestureHandlers;

packages/react-native-gesture-handler/apple/RNGestureHandlerManager.mm

@@ -191,6 +191,12 @@ - (void)updateGestureHandlerConfig:(NSNumber *)handlerTag config:(NSDictionary *
   [handler updateConfig:config];
 }
 
+- (void)updateGestureHandlerRelations:(NSNumber *)handlerTag relations:(NSDictionary *)relations
+{
+  RNGestureHandler *handler = [_registry handlerWithTag:handlerTag];
+  [handler updateRelations:relations];
+}
+
 - (void)dropGestureHandler:(NSNumber *)handlerTag
 {
   [_registry dropHandlerWithTag:handlerTag];

packages/react-native-gesture-handler/apple/RNGestureHandlerModule.mm

@@ -159,6 +159,12 @@ - (void)updateGestureHandlerConfig:(double)handlerTag newConfig:(NSDictionary *)
   }];
 }
 
+- (void)configureRelations:(double)handlerTag relations:(NSDictionary *)relations
+{
+  RNGestureHandlerManager *manager = [RNGestureHandlerModule handlerManagerForModuleId:_moduleId];
+  [manager updateGestureHandlerRelations:[NSNumber numberWithDouble:handlerTag] relations:relations];
+}
+
 - (void)dropGestureHandler:(double)handlerTag
 {
   [self addOperationBlock:^(RNGestureHandlerManager *manager) {

packages/react-native-gesture-handler/src/handlers/gestures/reanimatedWrapper.ts

@@ -59,6 +59,9 @@ let Reanimated:
       >(
         value: unknown
       ): value is WorkletFunction<Args, ReturnValue>;
+      useComposedEventHandler<T>(
+        handlers: (((event: T) => void) | null)[]
+      ): (event: T) => void;
       runOnUI<A extends any[], R>(
         fn: (...args: A) => R
       ): (...args: Parameters<typeof fn>) => void;

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

@@ -162,9 +162,12 @@ export type {
 } from './components/DrawerLayout';
 export { default as DrawerLayout } from './components/DrawerLayout';
 
-export type { NativeDetectorProps } from './v3/NativeDetector';
-export { NativeDetector } from './v3/NativeDetector';
+export type { NativeDetectorProps } from './v3/NativeDetector/NativeDetector';
+export { NativeDetector } from './v3/NativeDetector/NativeDetector';
 
 export * from './v3/hooks/useGesture';
+export * from './v3/hooks/relations';
+
+export { SingleGestureName } from './v3/types';
 
 initialize();