Merge branch 'main' into @mbert/fix-sticky-scroll

Author: m-bert

AGENTS.md

@@ -21,6 +21,11 @@
 - This project contains 3 versions of API. The newest is located in `packages/react-native-gesture-handler/src/v3` directory. Most of the logic is shared, but make sure that your changes do not break older APIs.
 - When writing code, you can use `usesNativeOrVirtualDetector` function to either include only, or exclude new API v3. It is available on all platforms.
 
+## API versions — defaults for new code
+
+- **Always use the v3 API by default** for any new code, examples, reproductions, or test screens. `Gesture.*` builders (v2) and `*GestureHandler` components (v1) are legacy. Even when a bug is reported against a legacy API, build the reproduction with v3 first to check whether it affects v3 too — switch to the legacy API only if the issue does not reproduce on v3, or the user explicitly asks for a legacy reproduction.
+- v3 usage: hook-based gestures (`usePanGesture`, `useTapGesture`, `useLongPressGesture`, …) attached via `GestureDetector`, all imported from `react-native-gesture-handler` (the main entry re-exports `src/v3`).
+
 ## Build checks
 
 - To check Android build go to `apps/basic-example` and run `yarn android` command.

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

@@ -215,30 +215,30 @@ childrenContainerStyle?: StyleProp<ViewStyle>;
 
 Style object for the children container ([`Animated.View`](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary/#animated-component)).
 
-### simultaneousWithExternalGesture
+### simultaneousWith
 
 ```ts
-simultaneousWithExternalGesture?: AnyGesture | AnyGesture[];
+simultaneousWith?: AnyGesture | AnyGesture[];
 ```
 
-Gestures to be recognized simultaneously with the `Swipeable` (see [gesture composition section](/docs/fundamentals/gesture-composition#simultaneouswith)).
+Gestures to be recognized simultaneously with the `Swipeable` (see [`simultaneousWith`](/docs/composition/simultaneous-with)).
 
-### requireExternalGestureToFail
+### requireToFail
 
 ```ts
-requireExternalGestureToFail?: AnyGesture | AnyGesture[];
+requireToFail?: AnyGesture | AnyGesture[];
 ```
 
-Gestures that `Swipeable` has to wait for before activating (see [gesture composition section](/docs/fundamentals/gesture-composition#simultaneouswith)).
+Gestures that `Swipeable` has to wait for before activating (see [`requireToFail`](/docs/composition/require-to-fail)).
 
 
-### blocksExternalGesture
+### block
 
 ```ts
-blocksExternalGesture?: AnyGesture | AnyGesture[];
+block?: AnyGesture | AnyGesture[];
 ```
 
-Gestures that `Swipeable` will prevent from activating (see [gesture composition section](/docs/fundamentals/gesture-composition#simultaneouswith)).
+Gestures that `Swipeable` will prevent from activating (see [`block`](/docs/composition/block)).
 
 <Badges platforms={['ios', 'web']}>
 ### enableTrackpadTwoFingerGesture

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

@@ -87,4 +87,4 @@ Those components also receive an additional prop named `onGestureUpdate_CAN_CAUS
 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.
+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/composition/overview) 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/docs-gesture-handler/docs/composition/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Gesture composition & interactions",
+  "position": 3,
+  "link": {
+    "type": "generated-index"
+  }
+}