[General] Add yieldsToNativeGestures property to native gesture (#4135)

## Description

Currently, `NativeViewGestureHandler` exposes `disallowInterruption`
property, which causes it to cancel all other gestures upon activation.
This is great for the `Touchable` component, since it shouldn't allow
other gesture handlers to activate when it's pressed. The issue with
that was the fact that `disallowInterruption` means that all native
gestures are cancelled as well, including `ScrollView` or any other
custom container, making `Touchable` not usable in real use-cases.

This PR adds `yieldsToNativeGestures` property, which works only when
`disallowInterruption` is `true`. It defaults to `false`, where it
behaves as `disallowInterruption` does currently. When set to `true`, it
allows the gesture to be canceled by other native gestures but not any
other type of gesture.

Touchable is now using this new config to make it work inside scrollable
containers.

## Test plan

Changed `RectButtons` with `Touchables` in the common app

|-|Before|After|
|-|-|-|
|Android|<video
src="https://github.com/user-attachments/assets/d5299802-e6f9-4987-aacb-ab41562fc660"
/>|<video
src="https://github.com/user-attachments/assets/5f012d5b-7da7-4d1a-8a32-d380eb09906d"
/>|
|iOS|<video
src="https://github.com/user-attachments/assets/3e0ef50b-c928-4187-99f8-b3e4ea57a8cd"
/>|<video
src="https://github.com/user-attachments/assets/13343460-93a7-47f6-9c90-8a547cb04c34"
/>|

Since scrolling on web dispatches `pointercancel` event, this prop is
effectively a no-op for `Touchable`.

Author: j-piasecki

packages/docs-gesture-handler/docs/gestures/use-native-gesture.mdx

@@ -115,6 +115,14 @@ disallowInterruption: boolean | SharedValue<boolean>;
 
 When `true`, this handler cancels all other gesture handlers when it activates.
 
+### yieldsToNativeGestures
+
+```ts
+yieldsToNativeGestures: boolean | SharedValue<boolean>;
+```
+
+Composes with [`disallowInterruption`](#disallowinterruption). When both are `true`, this handler still cancels other gestures (such as `Pan` or `Tap`) on activation but allows other native gestures — for example a wrapping `ScrollView` — to interrupt it. No-op when `disallowInterruption` is `false`. Defaults to `false`.
+
 <BaseGestureConfig />
 
 ## Callbacks

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

@@ -15,6 +15,7 @@ import com.facebook.react.views.text.ReactTextView
 import com.facebook.react.views.textinput.ReactEditText
 import com.facebook.react.views.view.ReactViewGroup
 import com.swmansion.gesturehandler.react.RNGestureHandlerButtonViewManager
+import com.swmansion.gesturehandler.react.RNGestureHandlerRootHelper
 import com.swmansion.gesturehandler.react.events.eventbuilders.NativeGestureHandlerEventDataBuilder
 import com.swmansion.gesturehandler.react.isScreenReaderOn
 
@@ -29,6 +30,14 @@ class NativeViewGestureHandler : GestureHandler() {
   var disallowInterruption = false
     private set
 
+  /**
+   * Composes with [disallowInterruption]. When both are `true`, the handler still resists
+   * generic gesture peers (Pan, Tap, etc.) but yields to other [NativeViewGestureHandler] peers
+   * such as a wrapping ScrollView. No-op when [disallowInterruption] is `false`.
+   */
+  var yieldsToNativeGestures = false
+    private set
+
   private var hook: NativeViewGestureHandlerHook = defaultHook
 
   private data class ActiveUpdateSnapshot(val pointerInside: Boolean, val numberOfPointers: Int, val pointerType: Int)
@@ -43,6 +52,7 @@ class NativeViewGestureHandler : GestureHandler() {
     super.resetConfig()
     shouldActivateOnStart = DEFAULT_SHOULD_ACTIVATE_ON_START
     disallowInterruption = DEFAULT_DISALLOW_INTERRUPTION
+    yieldsToNativeGestures = DEFAULT_YIELDS_TO_NATIVE_GESTURES
     shouldCancelWhenOutside = DEFAULT_SHOULD_CANCEL_WHEN_OUTSIDE
   }
 
@@ -61,12 +71,15 @@ class NativeViewGestureHandler : GestureHandler() {
       // For the `disallowInterruption` to work correctly we need to check the property when
       // accessed as a peer, because simultaneous recognizers can be set on either side of the
       // connection.
-      if (handler.state == STATE_ACTIVE && handler.disallowInterruption) {
+      if (handler.state == STATE_ACTIVE &&
+        handler.disallowInterruption &&
+        !handler.yieldsToNativeGestures
+      ) {
         // other handler is active and it disallows interruption, we don't want to get into its way
         return false
       }
     }
-    val canBeInterrupted = !disallowInterruption
+    val canBeInterrupted = canBeInterruptedBy(handler)
     val otherState = handler.state
     return if (state == STATE_ACTIVE && otherState == STATE_ACTIVE && canBeInterrupted) {
       // if both handlers are active and the current handler can be interrupted it we return `false`
@@ -81,7 +94,17 @@ class NativeViewGestureHandler : GestureHandler() {
     // otherwise we can only return `true` if already in an active state
   }
 
-  override fun shouldBeCancelledBy(handler: GestureHandler): Boolean = !disallowInterruption
+  override fun shouldBeCancelledBy(handler: GestureHandler): Boolean = canBeInterruptedBy(handler)
+
+  /**
+   * Whether this handler permits [other] to take over the touch stream, given its
+   * `disallowInterruption` and `yieldsToNativeGestures` configuration.
+   */
+  fun canBeInterruptedBy(other: GestureHandler): Boolean = !disallowInterruption ||
+    (
+      yieldsToNativeGestures &&
+        (other is NativeViewGestureHandler || other is RNGestureHandlerRootHelper.RootViewGestureHandler)
+      )
 
   override fun shouldBeginWithRecordedHandlers(recorded: List<GestureHandler>): Boolean =
     hook.shouldBeginWithRecordedHandlers(recorded, this)
@@ -203,20 +226,25 @@ class NativeViewGestureHandler : GestureHandler() {
       if (config.hasKey(KEY_DISALLOW_INTERRUPTION)) {
         handler.disallowInterruption = config.getBoolean(KEY_DISALLOW_INTERRUPTION)
       }
+      if (config.hasKey(KEY_YIELDS_TO_NATIVE_GESTURES)) {
+        handler.yieldsToNativeGestures = config.getBoolean(KEY_YIELDS_TO_NATIVE_GESTURES)
+      }
     }
 
     override fun createEventBuilder(handler: NativeViewGestureHandler) = NativeGestureHandlerEventDataBuilder(handler)
 
     companion object {
       private const val KEY_SHOULD_ACTIVATE_ON_START = "shouldActivateOnStart"
       private const val KEY_DISALLOW_INTERRUPTION = "disallowInterruption"
+      private const val KEY_YIELDS_TO_NATIVE_GESTURES = "yieldsToNativeGestures"
     }
   }
 
   companion object {
     private const val DEFAULT_SHOULD_CANCEL_WHEN_OUTSIDE = true
     private const val DEFAULT_SHOULD_ACTIVATE_ON_START = false
     private const val DEFAULT_DISALLOW_INTERRUPTION = false
+    private const val DEFAULT_YIELDS_TO_NATIVE_GESTURES = false
 
     private fun tryIntercept(view: View, event: MotionEvent) = view is ViewGroup && view.onInterceptTouchEvent(event)
 
@@ -317,11 +345,10 @@ class NativeViewGestureHandler : GestureHandler() {
       }
     }
 
-    // recognize alongside every handler besides RootViewGestureHandler, which is a private inner class
-    // of RNGestureHandlerRootHelper so no explicit type checks, but its tag is always negative
+    // recognize alongside every handler besides RootViewGestureHandler;
     // also if other handler is NativeViewGestureHandler then don't override the default implementation
     override fun shouldRecognizeSimultaneously(handler: GestureHandler) =
-      handler.tag > 0 && handler !is NativeViewGestureHandler
+      handler !is RNGestureHandlerRootHelper.RootViewGestureHandler && handler !is NativeViewGestureHandler
 
     override fun wantsToHandleEventBeforeActivation() = true
 

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

@@ -50,7 +50,7 @@ class RNGestureHandlerInteractionManager : GestureHandlerInteractionController {
 
   override fun shouldHandlerBeCancelledBy(handler: GestureHandler, otherHandler: GestureHandler): Boolean {
     if (otherHandler is NativeViewGestureHandler) {
-      return otherHandler.disallowInterruption
+      return !otherHandler.canBeInterruptedBy(handler)
     }
 
     if (otherHandler is RNGestureHandlerRootHelper.RootViewGestureHandler) {

packages/react-native-gesture-handler/apple/Handlers/RNNativeViewHandler.mm

@@ -113,6 +113,7 @@ - (void)updateStateIfScrollView
 @implementation RNNativeViewGestureHandler {
   BOOL _shouldActivateOnStart;
   BOOL _disallowInterruption;
+  BOOL _yieldsToNativeGestures;
   RNGestureHandlerEventExtraData *_lastActiveExtraData;
 }
 
@@ -129,6 +130,7 @@ - (void)updateConfig:(NSDictionary *)config
   [super updateConfig:config];
   _shouldActivateOnStart = [RCTConvert BOOL:config[@"shouldActivateOnStart"]];
   _disallowInterruption = [RCTConvert BOOL:config[@"disallowInterruption"]];
+  _yieldsToNativeGestures = [RCTConvert BOOL:config[@"yieldsToNativeGestures"]];
 }
 
 #if !TARGET_OS_OSX
@@ -239,11 +241,19 @@ - (void)handleTouchDown:(UIView *)sender forEvent:(UIEvent *)event
 
   if (_disallowInterruption) {
     // When `disallowInterruption` is set we cancel all gesture handlers when this UIControl
-    // gets DOWN event
+    // gets DOWN event. When `yieldsToNativeGestures` is also set we leave alone:
+    //   - non-RNGH recognizers (e.g. UIScrollView's pan), so native containers can take over
+    //   - peer NativeViewGestureHandler recognizers (RNDummyGestureRecognizer), so wrapping
+    //     RNGH-managed scrollables/native handlers can still take over
     for (RNGHUITouch *touch in [event allTouches]) {
-      for (UIGestureRecognizer *recogn in [touch gestureRecognizers]) {
-        recogn.enabled = NO;
-        recogn.enabled = YES;
+      for (UIGestureRecognizer *recognizer in [touch gestureRecognizers]) {
+        if (_yieldsToNativeGestures &&
+            (recognizer.gestureHandler == nil || [recognizer isKindOfClass:[RNDummyGestureRecognizer class]])) {
+          continue;
+        }
+
+        recognizer.enabled = NO;
+        recognizer.enabled = YES;
       }
     }
   }

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

@@ -152,3 +152,7 @@
 #endif
 
 @end
+
+@interface UIGestureRecognizer (GestureHandler)
+@property (nonatomic, readonly, nullable) RNGestureHandler *gestureHandler;
+@end

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

@@ -14,10 +14,6 @@
 #import <React/RCTParagraphComponentView.h>
 #import <React/RCTScrollViewComponentView.h>
 
-@interface UIGestureRecognizer (GestureHandler)
-@property (nonatomic, readonly) RNGestureHandler *gestureHandler;
-@end
-
 @implementation UIGestureRecognizer (GestureHandler)
 
 - (RNGestureHandler *)gestureHandler

packages/react-native-gesture-handler/src/v3/components/Touchable/Touchable.tsx

@@ -138,6 +138,7 @@ export const Touchable = (props: TouchableProps) => {
     disableReanimated: true,
     shouldActivateOnStart: false,
     disallowInterruption: true,
+    yieldsToNativeGestures: true,
   });
 
   const rippleProps = shouldUseNativeRipple

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

@@ -20,11 +20,19 @@ export type NativeGestureNativeProperties = {
    * `NativeViewGestureHandler` receives an `ACTIVE` state event.
    */
   disallowInterruption?: boolean;
+
+  /**
+   * Composes with `disallowInterruption`. When both are `true`, the handler still
+   * resists generic gesture peers (Pan, Tap, etc.) but yields to other
+   * `NativeViewGestureHandler` peers such as a wrapping ScrollView. No-op when
+   * `disallowInterruption` is `false`.
+   */
+  yieldsToNativeGestures?: boolean;
 };
 
 export const NativeHandlerNativeProperties = new Set<
   keyof NativeGestureNativeProperties
->(['shouldActivateOnStart', 'disallowInterruption']);
+>(['shouldActivateOnStart', 'disallowInterruption', 'yieldsToNativeGestures']);
 
 export type NativeHandlerData = {
   pointerInside: boolean;

packages/react-native-gesture-handler/src/web/handlers/NativeViewGestureHandler.ts

@@ -23,6 +23,7 @@ export default class NativeViewGestureHandler extends GestureHandler {
   // TODO: Implement logic for activation on start properly
   private shouldActivateOnStart = false;
   private disallowInterruption = false;
+  private yieldsToNativeGestures = false;
 
   private startX = 0;
   private startY = 0;
@@ -67,6 +68,9 @@ export default class NativeViewGestureHandler extends GestureHandler {
     if (config.disallowInterruption !== undefined) {
       this.disallowInterruption = config.disallowInterruption;
     }
+    if (config.yieldsToNativeGestures !== undefined) {
+      this.yieldsToNativeGestures = config.yieldsToNativeGestures;
+    }
 
     const view = this.delegate.view as HTMLElement;
     this.restoreViewStyles(view);
@@ -181,12 +185,16 @@ export default class NativeViewGestureHandler extends GestureHandler {
     if (
       handler instanceof NativeViewGestureHandler &&
       handler.state === State.ACTIVE &&
-      handler.disallowsInterruption()
+      handler.disallowsInterruption() &&
+      !handler.yieldsToOtherNativeGestures()
     ) {
       return false;
     }
 
-    const canBeInterrupted = !this.disallowInterruption;
+    const canBeInterrupted =
+      !this.disallowInterruption ||
+      (this.yieldsToNativeGestures &&
+        handler instanceof NativeViewGestureHandler);
 
     if (
       this.state === State.ACTIVE &&
@@ -201,8 +209,12 @@ export default class NativeViewGestureHandler extends GestureHandler {
     );
   }
 
-  public override shouldBeCancelledByOther(_handler: IGestureHandler): boolean {
-    return !this.disallowInterruption;
+  public override shouldBeCancelledByOther(handler: IGestureHandler): boolean {
+    return (
+      !this.disallowInterruption ||
+      (this.yieldsToNativeGestures &&
+        handler instanceof NativeViewGestureHandler)
+    );
   }
 
   public override shouldAttachGestureToChildView(): boolean {
@@ -213,6 +225,10 @@ export default class NativeViewGestureHandler extends GestureHandler {
     return this.disallowInterruption;
   }
 
+  public yieldsToOtherNativeGestures(): boolean {
+    return this.yieldsToNativeGestures;
+  }
+
   public isButton(): boolean {
     return this.buttonRole;
   }

packages/react-native-gesture-handler/src/web/interfaces.ts

@@ -88,6 +88,7 @@ export interface Config extends Record<string, ConfigArgs> {
   maxDeltaY?: number;
   shouldActivateOnStart?: boolean;
   disallowInterruption?: boolean;
+  yieldsToNativeGestures?: boolean;
   direction?: Directions;
   enableTrackpadTwoFingerGesture?: boolean;
 }