Merge branch 'main' into @jpiasecki/yields-to-continous-gestures

Author: j-piasecki

.eslintrc.json

@@ -45,6 +45,7 @@
     "@typescript-eslint/ban-types": "warn",
     "@typescript-eslint/consistent-type-imports": "error",
     "@typescript-eslint/consistent-type-exports": "error",
+    "@typescript-eslint/no-unsafe-enum-comparison": "off",
 
     // common
     "@typescript-eslint/explicit-module-boundary-types": "off",

packages/docs-gesture-handler/docs/components/wrapped-components.mdx

@@ -0,0 +1,90 @@
+---
+id: wrapped-components
+title: Wrapped Components
+sidebar_label: Wrapped Components
+---
+
+Some components come with a [`Native`](/docs/gestures/use-native-gesture) gesture pre-applied. This allows them to participate in the gesture recognition process. Have a look at the example below.
+
+```tsx
+import { useState } from 'react';
+import { Switch } from 'react-native';
+import {
+  GestureDetector,
+  GestureHandlerRootView,
+  useTapGesture,
+  Switch as RNGHSwitch,
+} from 'react-native-gesture-handler';
+
+export default function App() {
+  const [isEnabled, setIsEnabled] = useState(false);
+
+  const tap1 = useTapGesture({
+    onDeactivate: () => {
+      console.log('Tapped!');
+    },
+  });
+
+  const tap2 = useTapGesture({
+    onDeactivate: () => {
+      console.log('Tapped!');
+    },
+  });
+
+  return (
+    <GestureHandlerRootView style={{ flex: 1, paddingTop: 100 }}>
+      <GestureDetector gesture={tap1}>
+        <Switch value={isEnabled} onValueChange={setIsEnabled} />
+      </GestureDetector>
+      <GestureDetector gesture={tap2}>
+        <RNGHSwitch value={isEnabled} onValueChange={setIsEnabled} />
+      </GestureDetector>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+On Android, in this scenario, the `Switch` from React Native cannot be toggled on because the `tap1` gesture intercepts it. However, using `RNGHSwitch` makes it capable of participating in the gesture recognition process. This setup allows the switch to be toggled on while still enabling `tap2` to recognize taps on it.
+
+## List of wrapped components
+
+Components listed below come with a pre-applied `Native` gesture.
+
+- `FlatList`
+- `ScrollView`
+- `RefreshControl`
+- `TextInput`
+- `Switch`
+
+## onGestureUpdate_CAN_CAUSE_INFINITE_RERENDER
+
+:::danger
+This callback may lead to infinite re-renders if not used carefully.
+
+```tsx
+export default function App() {
+  const [gesture, setGesture] = useState<NativeGesture | null>(null);
+
+  const updateGesture = (g: NativeGesture) => {
+    // ❌ Wrong usage: calling setState here triggers a re-render,
+    // which re-creates the ScrollView's Native gesture, which fires
+    // this callback again → infinite re-render loop.
+    setGesture(g);
+  };
+
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <ScrollView onGestureUpdate_CAN_CAUSE_INFINITE_RERENDER={updateGesture} />
+    </GestureHandlerRootView>
+  );
+}
+```
+:::
+
+Those components also receive an additional prop named `onGestureUpdate_CAN_CAUSE_INFINITE_RERENDER`.
+
+```ts
+onGestureUpdate_CAN_CAUSE_INFINITE_RERENDER?: (gesture: NativeGesture) => void;
+```
+
+This callback is invoked when the wrapped component's underlying `Native` gesture instance or configuration changes, providing access to the underlying gesture. This can be helpful when setting up [relations](/docs/fundamentals/gesture-composition) with other gestures. You can check example usage in our [`ScrollView`](https://github.com/software-mansion/react-native-gesture-handler/blob/main/packages/react-native-gesture-handler/src/v3/components/GestureComponents.tsx#L78) component.

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

@@ -70,9 +70,17 @@ class PinchGestureHandler : GestureHandler() {
     }
 
     if (state == STATE_UNDETERMINED) {
-      initialize(event, sourceEvent)
-      begin()
+      when (sourceEvent.actionMasked) {
+        MotionEvent.ACTION_DOWN -> {
+          initialize(event, sourceEvent)
+        }
+
+        MotionEvent.ACTION_POINTER_DOWN -> {
+          begin()
+        }
+      }
     }
+
     scaleGestureDetector?.onTouchEvent(sourceEvent)
     scaleGestureDetector?.let {
       val point = transformPoint(PointF(it.focusX, it.focusY))
@@ -81,10 +89,10 @@ class PinchGestureHandler : GestureHandler() {
     }
 
     if (sourceEvent.actionMasked == MotionEvent.ACTION_UP) {
-      if (state == STATE_ACTIVE) {
-        end()
-      } else {
-        fail()
+      when (state) {
+        STATE_UNDETERMINED -> cancel()
+        STATE_ACTIVE -> end()
+        else -> fail()
       }
     }
   }

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

@@ -61,9 +61,17 @@ class RotationGestureHandler : GestureHandler() {
     }
 
     if (state == STATE_UNDETERMINED) {
-      initialize(event, sourceEvent)
-      begin()
+      when (sourceEvent.actionMasked) {
+        MotionEvent.ACTION_DOWN -> {
+          initialize(event, sourceEvent)
+        }
+
+        MotionEvent.ACTION_POINTER_DOWN -> {
+          begin()
+        }
+      }
     }
+
     rotationGestureDetector?.onTouchEvent(sourceEvent)
     rotationGestureDetector?.let {
       val point = transformPoint(PointF(it.anchorX, it.anchorY))
@@ -73,8 +81,11 @@ class RotationGestureHandler : GestureHandler() {
 
     // ACTION_UP is already handled in rotationGestureDetector.onTouchEvent (and effectively in onRotationEnd)
     // if more than one pointer was used
-    if (sourceEvent.actionMasked == MotionEvent.ACTION_UP && state == STATE_BEGAN) {
-      fail()
+    if (sourceEvent.actionMasked == MotionEvent.ACTION_UP) {
+      when (state) {
+        STATE_UNDETERMINED -> cancel()
+        STATE_BEGAN -> fail()
+      }
     }
   }
 

packages/react-native-gesture-handler/src/components/GestureHandlerButton.web.tsx

@@ -2,6 +2,7 @@ import * as React from 'react';
 import type { ColorValue, NativeSyntheticEvent, ViewProps } from 'react-native';
 import { View } from 'react-native';
 
+import { NativeGestureRole } from '../web/interfaces';
 import { GestureLifecycleEvent } from '../web/tools/GestureLifecycleEvents';
 
 type ButtonProps = ViewProps & {
@@ -216,4 +217,6 @@ export const ButtonComponent = ({
   );
 };
 
+ButtonComponent.displayName = NativeGestureRole.Button;
+
 export default ButtonComponent;

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

@@ -9,7 +9,8 @@ import type {
 } from '../../handlers/gestureHandlerCommon';
 import RNGestureHandlerModule from '../../RNGestureHandlerModule.web';
 import { tagMessage } from '../../utils';
-import type { PropsRef } from '../../web/interfaces';
+import { type PropsRef } from '../../web/interfaces';
+import { useNativeGestureRole } from './useNativeGestureRole';
 
 export interface GestureHandlerDetectorProps extends PropsRef {
   handlerTags: number[];
@@ -103,6 +104,8 @@ const HostGestureDetector = (props: GestureHandlerDetectorProps) => {
     });
   };
 
+  useNativeGestureRole(viewRef, children);
+
   useEffect(() => {
     const shouldUpdateDOMProps =
       propsRef.current.userSelect !== props.userSelect ||

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

@@ -6,6 +6,7 @@ import { tagMessage } from '../../../utils';
 import { isComposedGesture } from '../../hooks/utils/relationUtils';
 import type { DetectorCallbacks, VirtualChild } from '../../types';
 import type { VirtualDetectorProps } from '../common';
+import { useNativeGestureRole } from '../useNativeGestureRole';
 import { configureRelations } from '../utils';
 import {
   InterceptingDetectorMode,
@@ -54,6 +55,8 @@ export function VirtualDetector<
     [props.children]
   );
 
+  useNativeGestureRole(viewRef, props.children);
+
   useEffect(() => {
     if (viewTag === -1) {
       return;

packages/react-native-gesture-handler/src/v3/detectors/useNativeGestureRole.ts

@@ -0,0 +1,8 @@
+import type { ReactNode, RefObject } from 'react';
+
+export function useNativeGestureRole(
+  _viewRef: RefObject<unknown>,
+  _children: ReactNode
+): void {
+  // No-op on native; the web implementation lives in `useNativeGestureRole.web.ts`.
+}

packages/react-native-gesture-handler/src/v3/detectors/useNativeGestureRole.web.ts

@@ -0,0 +1,42 @@
+import type { ReactNode, RefObject } from 'react';
+import { useEffect } from 'react';
+
+import { NATIVE_GESTURE_ROLE_ATTRIBUTE } from '../../web/constants';
+import { NativeGestureRole } from '../../web/interfaces';
+
+export function useNativeGestureRole(
+  viewRef: RefObject<Element | null>,
+  children: ReactNode
+): void {
+  useEffect(() => {
+    const child = viewRef.current?.firstChild as HTMLElement | undefined;
+
+    if (!child) {
+      return;
+    }
+
+    // @ts-ignore This exists on React.ReactNode
+    const displayName = children?.type?.displayName as string;
+
+    if (displayName === NativeGestureRole.ScrollView) {
+      child.setAttribute(
+        NATIVE_GESTURE_ROLE_ATTRIBUTE,
+        NativeGestureRole.ScrollView
+      );
+    } else if (displayName === NativeGestureRole.Switch) {
+      child.setAttribute(
+        NATIVE_GESTURE_ROLE_ATTRIBUTE,
+        NativeGestureRole.Switch
+      );
+    } else if (displayName === NativeGestureRole.Button) {
+      child.setAttribute(
+        NATIVE_GESTURE_ROLE_ATTRIBUTE,
+        NativeGestureRole.Button
+      );
+    }
+
+    return () => {
+      child.removeAttribute(NATIVE_GESTURE_ROLE_ATTRIBUTE);
+    };
+  }, [children, viewRef]);
+}

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

@@ -1,2 +1,3 @@
 export const DEFAULT_TOUCH_SLOP = 15;
 export const MINIMAL_RECOGNIZABLE_MAGNITUDE = 0.1;
+export const NATIVE_GESTURE_ROLE_ATTRIBUTE = 'rngh-role';