[docs] Gesture detectors

packages/docs-gesture-handler/docs/fundamentals/animated-interactions.mdx

@@ -0,0 +1,151 @@
+---
+id: animated-interactions
+title: Integration with Animated
+sidebar_label: Integration with Animated
+sidebar_position: 5
+---
+
+import CollapsibleCode from '@site/src/components/CollapsibleCode';
+
+Using hook API allows for smooth integration with the [Animated API](https://reactnative.dev/docs/animated) by allowing for passing an `Animated.event` as the argument to the `onUpdate` callback. The event mapping of `Animated.event` depends on the `useNativeDriver` property.
+
+:::danger Mixing Reanimated and Animated
+It is not possible to mix `Reanimated` and `Animated` within any of the [gesture detectors](/docs/fundamentals/gesture-detectors).
+:::
+
+<CollapsibleCode 
+label="Show full example"
+expandedLabel="Hide full example"
+lineBounds={[8, 31]}
+src={`
+import * as React from 'react';
+import { Animated, StyleSheet, useAnimatedValue } from 'react-native';
+import {
+  GestureHandlerRootView,
+  GestureDetector,
+  usePanGesture,
+} from 'react-native-gesture-handler';
+
+export default function App() {
+  const value = useAnimatedValue(0);
+
+  const event = Animated.event(
+    [{ nativeEvent: { handlerData: { translationX: value } } }],
+    {
+      useNativeDriver: true,
+    }
+  );
+
+  const gesture = usePanGesture({
+    // highlight-next-line
+    onUpdate: event,
+  });
+
+  return (
+    <GestureHandlerRootView>
+      <GestureDetector gesture={gesture}>
+        <Animated.View
+          style={[styles.box, { transform: [{ translateX: value }] }]}
+        />
+      </GestureDetector>
+    </GestureHandlerRootView>
+  );
+}
+
+const styles = StyleSheet.create({
+  box: {
+    width: 150,
+    height: 150,
+    backgroundColor: '#b58df1',
+  },
+});
+`}/>
+
+## useNativeDriver
+
+When using `Animated.event` with `useNativeDriver` set to `false`, it is required to set [`disableReanimated`](/docs/fundamentals/reanimated-interactions#disablereanimated) to `true` in the gesture configuration. 
+
+Mapping of `Animated.event` depends on the value of `useNativeDriver` property. When set to `true`, event data can be accessed through `nativeEvent.handlerData` property:
+
+```jsx
+  const value = useAnimatedValue(0);
+
+  const event = Animated.event(
+    [{ nativeEvent: { handlerData: { /* translationX: value, ... */ } } }],
+    { useNativeDriver: true }
+  );
+```
+
+In case of `useNativeDriver` set to `false`, event data is accessed directly:
+
+```jsx
+  const value = useAnimatedValue(0);
+
+  const event = Animated.event(
+    [ { /* translationX: value, ... */ } ],
+    { useNativeDriver: false }
+  );
+```
+
+## Usage with VirtualGestureDetector
+
+Using `Animated.event` with [`VirtualGestureDetector`](/docs/fundamentals/gesture-detectors#virtualgesturedetector) is possible only when `useNativeDriver` is set to `false`.
+
+<CollapsibleCode 
+label="Show full example"
+expandedLabel="Hide full example"
+lineBounds={[8, 33]}
+src={`
+import React from 'react';
+import { View, StyleSheet, Animated, useAnimatedValue } from 'react-native';
+import {
+  GestureHandlerRootView,
+  InterceptingGestureDetector,
+  usePanGesture,
+  VirtualGestureDetector,
+} from 'react-native-gesture-handler';
+
+export default function App() {
+  const value = useAnimatedValue(0);
+  const event = Animated.event([{ translationX: value }], {
+    useNativeDriver: false,
+  });
+
+  const panGesture = usePanGesture({
+    onUpdate: event,
+    disableReanimated: true,
+  });
+
+  return (
+    <GestureHandlerRootView style={styles.container}>
+      <InterceptingGestureDetector>
+        <View style={styles.outerBox}>
+          <VirtualGestureDetector gesture={panGesture}>
+            <Animated.View
+              style={[styles.innerBox, { transform: [{ translateX: value }] }]}
+            />
+          </VirtualGestureDetector>
+        </View>
+      </InterceptingGestureDetector>
+    </GestureHandlerRootView>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  outerBox: {
+    backgroundColor: '#b58df1',
+    width: 150,
+    height: 150,
+  },
+  innerBox: {
+    width: 100,
+    height: 100,
+    backgroundColor: 'blue',
+  },
+});
+`}/>

packages/docs-gesture-handler/docs/fundamentals/gesture-composition.md

@@ -2,7 +2,7 @@
 id: gesture-composition
 title: Gesture composition & interactions
 sidebar_label: Gesture composition & interactions
-sidebar_position: 10
+sidebar_position: 6
 ---
 
 RNGH3 simplifies gesture interaction through dedicated composition hooks and configuration properties. To choose the right approach, simply ask: Are all the gestures attached to the same component?

packages/docs-gesture-handler/docs/fundamentals/gesture-detector.mdx

@@ -0,0 +1,224 @@
+---
+id: gesture-detectors
+title: Gesture Detectors
+sidebar_label: Gesture detectors
+sidebar_position: 3
+---
+
+import CollapsibleCode from '@site/src/components/CollapsibleCode';
+
+
+## Gesture Detector
+
+The `GestureDetector` is a key component of `react-native-gesture-handler`. It supports gestures created either using the hooks API or the builder pattern. Additionally, it allows for the recognition of multiple gestures through [gesture composition](/docs/fundamentals/gesture-composition). `GestureDetector` interacts closely with [`Reanimated`](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/). For more details, refer to the [Integration with Reanimated](/docs/fundamentals/reanimated-interactions) section.
+
+When using hook API, you can also integrate it directly with the [Animated API](https://reactnative.dev/docs/animated). More on that can be found in [Integreation with Animated](/docs/fundamentals/animated-interactions) section.
+
+:::danger
+
+####  Nesting Gesture Detectors
+
+Because `GestureDetector` supports both the hook API and the builder pattern, it is important to avoid nesting detectors that use different APIs, as this can result in undefined behavior.
+
+#### Reusing Gestures
+Using the same instance of a gesture across multiple Gesture Detectors may result in undefined behavior.
+:::
+
+```js
+import { GestureDetector, useTapGesture } from 'react-native-gesture-handler';
+
+export default function App() {
+  const tap = useTapGesture({
+    onDeactivate: () => {
+      console.log('Tap!');
+    },
+  });
+
+  return (
+    <GestureHandlerRootView>
+      // highlight-next-line
+      <GestureDetector gesture={tap}>
+        <Animated.View />
+        // highlight-next-line
+      </GestureDetector>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+## Virtual Detectors
+
+Since RNGH3, `GestureDetector` is a standalone host component. Depending on the view hierarchy, this can occasionally disrupt interactions between specific components. To resolve this, use `InterceptingGestureDetector` in combination with `VirtualNativeDetector`.
+
+### InterceptingGestureDetector
+
+`InterceptingGestureDetector` functions similarly to a `GestureDetector`, but it can also act as a proxy for `VirtualGestureDetector` within its component subtree. Because it can be used solely to establish the context for virtual detectors, the [`gesture`](#gesture) property is optional.
+
+### VirtualGestureDetector
+
+`VirtualGestureDetector` is similar to the `GestureDetector` from RNGH2. Because it is not a host component, it does not interfere with the host view hierarchy. This allows you to attach gestures without disrupting functionality that depends on it.
+
+### Known use cases
+
+Here are some of the most common use cases for virtual gesture detectors.
+
+#### SVG
+
+You can combine `VirtualGestureDetector` with `react-native-svg` to add gesture handling to individual SVG elements.
+
+<CollapsibleCode 
+label="Show full example"
+expandedLabel="Hide full example"
+lineBounds={[10, 45]}
+src={`
+import React from 'react';
+import { View, StyleSheet } from 'react-native';
+import {
+  GestureHandlerRootView,
+  InterceptingGestureDetector,
+  useTapGesture,
+  VirtualGestureDetector,
+} from 'react-native-gesture-handler';
+import Svg, { Circle } from 'react-native-svg';
+
+export default function App() {
+  const outerTap = useTapGesture({
+    onDeactivate: () => {
+      console.log('Box tapped!');
+    },
+  });
+  const innerTap = useTapGesture({
+    onDeactivate: () => {
+      console.log('Circle tapped!');
+    },
+  });
+
+  return (
+    <GestureHandlerRootView style={styles.container}>
+      // highlight-next-line
+      <InterceptingGestureDetector gesture={outerTap}>
+        <View style={styles.box}>
+          <Svg height="250" width="250">
+            // highlight-next-line
+            <VirtualGestureDetector gesture={innerTap}>
+              <Circle
+                cx="125"
+                cy="125"
+                r="125"
+                fill="#001A72"
+                onPress={() => {}}
+              />
+              // highlight-next-line
+            </VirtualGestureDetector>
+          </Svg>
+        </View>
+        // highlight-next-line
+      </InterceptingGestureDetector>
+    </GestureHandlerRootView>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  box: {
+    backgroundColor: '#b58df1',
+  },
+});
+`}/>
+
+
+#### Text
+
+You can use `VirtualGestureDetector` to add gesture handling to specific parts of a `Text` component.
+
+<CollapsibleCode 
+label="Show full example"
+expandedLabel="Hide full example"
+lineBounds={[8, 37]}
+src={`
+import * as React from 'react';
+import { StyleSheet, Text } from 'react-native';
+import {
+  GestureHandlerRootView,
+  InterceptingGestureDetector,
+  VirtualGestureDetector,
+  useTapGesture,
+} from 'react-native-gesture-handler';
+
+export default function App() {
+  const outerTap = useTapGesture({
+    onDeactivate: () => {
+      console.log('Tapped on text!');
+    },
+  });
+
+  const nestedTap = useTapGesture({
+    onDeactivate: () => {
+      console.log('Tapped on nested part!');
+    },
+  });
+
+  return (
+    <GestureHandlerRootView style={styles.container}>
+      <InterceptingGestureDetector gesture={outerTap}>
+        <Text style={{ fontSize: 18, textAlign: 'center' }}>
+          Nested text
+          <VirtualGestureDetector gesture={nestedTap}>
+            <Text style={{ fontSize: 24, color: '#001A72' }}>
+              try tapping on this part.
+            </Text>
+          </VirtualGestureDetector>
+          This part is not special :c
+        </Text>
+      </InterceptingGestureDetector>
+    </GestureHandlerRootView>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'space-around',
+  },
+});
+`}/>
+
+
+## Properties
+
+### gesture
+
+```ts
+gesture: SingleGesture | ComposedGesture;
+```
+
+A gesture object containing the configuration and callbacks. Can be any of the base gestures or any [`ComposedGesture`](/docs/fundamentals/gesture-composition).
+
+### userSelect (Web only)
+
+```ts
+userSelect: 'none' | 'auto' | 'text';
+```
+
+This parameter allows to specify which `userSelect` property should be applied to underlying view. Default value is set to `"none"`.
+
+### touchAction (Web only)
+
+```ts
+userSelect: TouchAction;
+```
+
+This parameter allows to specify which `touchAction` property should be applied to underlying view. Supports all CSS [touch-action](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/touch-action) values. Default value is set to `"none"`.
+
+### enableContextMenu (Web only)
+
+```ts
+enableContextMenu: boolean;
+```
+
+Specifies whether context menu should be enabled after clicking on underlying view with right mouse button. Default value is set to `false`.