Interaction with Reanimated

Author: m-bert

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: 4
+sidebar_position: 5
 ---
 
 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.md

@@ -7,7 +7,7 @@ sidebar_position: 3
 
 ## Gesture Detector
 
-The `GestureDetector` is a key component of RNGH3. 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).
+The `GestureDetector` is a key component of RNGH3. 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).
 
@@ -160,10 +160,6 @@ const styles = StyleSheet.create({
 });
 ```
 
-## Interaction with Reanimated
-
-`GestureDetector` will decide whether to use [Reanimated](https://docs.swmansion.com/react-native-reanimated/) to process provided gestures based on their configuration. If any of the callbacks is a worklet and Reanimated is not explicitly turned off, tools provided by the Reanimated will be utilized bringing ability to handle gestures synchronously.
-
 ## Properties
 
 ### gesture

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

@@ -0,0 +1,118 @@
+---
+id: reanimated-interactions
+title: Integration with Reanimated
+sidebar_label: Integration with Reanimated
+sidebar_position: 4
+---
+
+import CollapsibleCode from '@site/src/components/CollapsibleCode';
+
+`GestureDetector` will decide whether to use [Reanimated](https://docs.swmansion.com/react-native-reanimated/) to process provided gestures based on their configuration. If any of the callbacks is a [worklet](<(https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary/#worklet)>) and Reanimated is not explicitly turned off, tools provided by the Reanimated will be utilized bringing ability to handle gestures synchronously.
+
+## Automatic [workletization](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary/#to-workletize) of gesture callbacks
+
+[Worklets' Babel plugin](https://docs.swmansion.com/react-native-worklets/docs/worklets-babel-plugin/about) is setup in a way that automatically marks callbacks passed to gestures in the configuration chain as worklets. This means that you don't need to add a `'worklet';` directive at the beginning of the functions. Here is an example that will be automatically workletized:
+
+```jsx
+const gesture = useTapGesture({
+  onBegin: () => {
+    console.log(_WORKLET);
+  },
+});
+```
+
+And here is one that won't:
+
+```jsx
+const callback = () => {
+  console.log(_WORKLET);
+};
+
+const gesture = useTapGesture({
+  onBegin: callback,
+});
+```
+
+It also won't work when wrapped with hooks like `useCallback` or `useMemo`, e.g:
+
+```jsx
+const callback = useCallback(() => {
+  console.log(_WORKLET);
+}, []);
+
+const gesture = useTapGesture({
+  onBegin: callback,
+});
+```
+
+In the above cases, you should add a `"worklet";` directive at the beginning of the callbacks, like so:
+
+```jsx
+const callback = () => {
+  // highlight-next-line
+  'worklet';
+  console.log(_WORKLET);
+};
+
+const gesture = useTapGesture({
+  onBegin: callback,
+});
+```
+
+```jsx
+const callback = useCallback(() => {
+  // highlight-next-line
+  'worklet;';
+  console.log(_WORKLET);
+}, []);
+
+const gesture = useTapGesture({
+  onBegin: callback,
+});
+```
+
+## Using SharedValue in gesture config
+
+RNGH3 allows to pass [`SharedValue`](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#shared-value) to gestures' configurations. This allows to react to configuration changes without unnecessary rerenders.
+
+<CollapsibleCode 
+label="Show full example"
+expandedLabel="Hide full example"
+lineBounds={[10, 19]}
+src={`
+import * as React from 'react';
+import { Animated } from 'react-native';
+import {
+  GestureHandlerRootView,
+  GestureDetector,
+  useTapGesture,
+} from 'react-native-gesture-handler';
+import { useSharedValue } from 'react-native-reanimated';
+
+export default function App() {
+  // highlight-next-line
+  const taps = useSharedValue(2);
+
+  const gesture = useTapGesture({
+    // highlight-next-line
+    numberOfTaps: taps,
+    onDeactivate: () => {
+      taps.value += 1;
+    },
+  });
+
+  return (
+    <GestureHandlerRootView>
+      <GestureDetector gesture={gesture}>
+        <Animated.View
+          style={{
+            width: 150,
+            height: 150,
+            backgroundColor: 'blue',
+          }}
+        />
+      </GestureDetector>
+    </GestureHandlerRootView>
+  );
+}
+`}/>

packages/docs-gesture-handler/docs/fundamentals/states-events.mdx

@@ -2,7 +2,7 @@
 id: states-events
 title: Gesture states & events
 sidebar_label: Gesture states & events
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 Every gesture can be treated as ["state machine"](https://en.wikipedia.org/wiki/Finite-state_machine).