[docs] State management

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

@@ -0,0 +1,181 @@
+---
+id: callbacks-events
+title: Gesture callbacks & events
+sidebar_label: Gesture callbacks & events
+sidebar_position: 7
+---
+
+import {GestureEventFlowChart, TouchEventFlowChart} from '@site/src/examples/CallbacksFlowCharts'
+import CollapsibleCode from '@site/src/components/CollapsibleCode';
+
+At any given time, each handler instance has an assigned [state](/docs/under-the-hood/state) that can change when new touch events occur or can be forced to change by the touch system in certain circumstances. You can hook into state transitions using specific [gesture callbacks](#callbacks).
+
+When `Reanimated` is installed, all callbacks are automatically workletized. For more details, refer to the [Integration with Reanimated](/docs/fundamentals/reanimated-interactions#automatic-workletization-of-gesture-callbacks) section.
+
+## Callbacks flow
+
+### GestureEvent callbacks
+
+<GestureEventFlowChart />
+
+Note that some of these callbacks are complementary:
+
+- if `onBegin` was called, it is guaranteed that `onFinalize` will be called later.
+- if `onActivate` was called, it is guaranteed that `onDeactivate` will be called later.
+
+### TouchEvent callbacks
+
+<TouchEventFlowChart />
+
+## Callbacks
+
+### onBegin
+
+```ts
+onBegin: (event: GestureEvent<HandlerData>) => void
+```
+
+Called when a handler begins to recognize gestures. If `onBegin` was called, it is guaranteed that `onFinalize` will be called later.
+
+### onActivate
+
+```ts
+onActivate: (event: GestureEvent<HandlerData>) => void
+```
+
+Called when activation criteria for handler are met. If `onActivate` was called, it is guaranteed that `onDeactivate` will be called later.
+
+### onUpdate
+
+```ts
+onUpdate: (event: GestureEvent<HandlerData>) => void
+```
+
+Called every time a gesture is updated after it has started.
+
+### onDeactivate
+
+```ts
+onDeactivate: (event: GestureEvent<HandlerData>, didSucceed: boolean) => void
+```
+
+Called after when handler stops recognizing gestures, but only if handler activated. It is called before `onFinalize`. If the handler was interrupted, the `didSucceed` argument is set to `false`. Otherwise it is set to `true`.
+
+### onFinalize
+
+```ts
+onFinalize: (event: GestureEvent<HandlerData>, didSucceed: boolean) => void
+```
+
+Called when handler stops recognizing gestures. If handler managed to activate, the `didSucceed` argument is set to `true` and `onFinalize` will be called right after `onDeactivate`. Otherwise it is set to `false`.
+
+### onTouchesDown
+
+```ts
+onTouchesDown: (event: GestureTouchEvent) => void
+```
+
+Called when new pointers are placed on the screen. It may carry information about more than one pointer because the events are batched.
+
+### onTouchesMove
+
+```ts
+onTouchesMove: (event: GestureTouchEvent) => void
+```
+
+Called when pointers are moved on the screen. It may carry information about more than one pointer because the events are batched.
+
+### onTouchesUp
+
+```ts
+onTouchesUp: (event: GestureTouchEvent) => void
+```
+
+Called when pointers are lifted from the screen. It may carry information about more than one pointer because the events are batched.
+
+### onTouchesCancelled
+
+```ts
+onTouchesCancelled: (event: GestureTouchEvent) => void
+```
+
+Called when there will be no more information about this pointer. It may be called because the gesture has ended or was interrupted. It may carry information about more than one pointer because the events are batched.
+
+## Events
+
+### GestureEvent
+
+<CollapsibleCode 
+label="Show composed types definitions"
+expandedLabel="Hide composed types definitions"
+lineBounds={[0, 4]}
+src={`
+export type GestureEvent<HandlerData> = {
+  handlerTag: number;
+  numberOfPointers: number;
+  pointerType: PointerType;
+} & HandlerData;
+
+export enum PointerType {
+  TOUCH,
+  STYLUS,
+  MOUSE,
+  KEY,
+  OTHER,
+}
+`}/>
+
+`GestureEvent` contains properties common to all gestures (`handlerTag`, `numberOfPointers`, `pointerType`) along with gesture-specific data defined in each gesture's documentation.
+
+### TouchEvent
+
+<CollapsibleCode 
+label="Show composed types definitions"
+expandedLabel="Hide composed types definitions"
+lineBounds={[0, 8]}
+src={`
+export type GestureTouchEvent = {
+  handlerTag: number;
+  numberOfTouches: number;
+  state: State;
+  eventType: TouchEventType;
+  allTouches: TouchData[];
+  changedTouches: TouchData[];
+  pointerType: PointerType;
+};
+
+export const State = {
+  UNDETERMINED: 0,
+  FAILED: 1,
+  BEGAN: 2,
+  CANCELLED: 3,
+  ACTIVE: 4,
+  END: 5,
+} as const;
+
+export const TouchEventType = {
+  UNDETERMINED: 0,
+  TOUCHES_DOWN: 1,
+  TOUCHES_MOVE: 2,
+  TOUCHES_UP: 3,
+  TOUCHES_CANCEL: 4,
+} as const;
+
+export const TouchEventType = {
+  UNDETERMINED: 0,
+  TOUCHES_DOWN: 1,
+  TOUCHES_MOVE: 2,
+  TOUCHES_UP: 3,
+  TOUCHES_CANCEL: 4,
+} as const;
+
+export enum PointerType {
+  TOUCH,
+  STYLUS,
+  MOUSE,
+  KEY,
+  OTHER,
+}
+`}/>
+
+`TouchEvent` carries information about raw touch events, like touching the screen or moving the finger. 

packages/docs-gesture-handler/docs/fundamentals/state-manager.mdx

@@ -0,0 +1,160 @@
+---
+id: state-manager
+title: State manager
+sidebar_label: State manager
+sidebar_position: 6
+---
+
+import CollapsibleCode from '@site/src/components/CollapsibleCode';
+
+RNGH3 allows to manually control gestures lifecycle by using `GestureStateManager`.
+
+## State management
+
+Manual state management is based on `handlerTag`. There are two ways of manual state control.
+
+### Inside gesture definition
+
+If you want to manipulate gesture's state in its callbacks, you can get `handlerTag` from event parameter.
+
+<CollapsibleCode 
+label="Show full example"
+expandedLabel="Hide full example"
+lineBounds={[9, 17]}
+src={`
+import { StyleSheet, View } from 'react-native';
+import {
+  GestureDetector,
+  GestureHandlerRootView,
+  GestureStateManager,
+  useLongPressGesture,
+} from 'react-native-gesture-handler';
+
+export default function App() {
+  const longPress = useLongPressGesture({
+    onTouchesDown: (e) => {
+      // highlight-next-line
+      GestureStateManager.activate(e.handlerTag);
+    },
+    onActivate: () => {
+      console.log('LongPress activated!');
+    },
+  });
+
+  return (
+    <GestureHandlerRootView style={styles.container}>
+      <GestureDetector gesture={longPress}>
+        <View style={styles.box} />
+      </GestureDetector>
+    </GestureHandlerRootView>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'space-around',
+  },
+
+  box: {
+    width: 150,
+    height: 150,
+    backgroundColor: 'blue',
+  },
+});
+`}/>
+
+
+### Outside gesture definition
+
+If you want to control gesture lifecycle outside of it, you can use `handlerTag` from created gesture object.
+
+<CollapsibleCode 
+label="Show full example"
+expandedLabel="Hide full example"
+lineBounds={[10, 21]}
+src={`
+import { StyleSheet, View } from 'react-native';
+import {
+  GestureDetector,
+  GestureHandlerRootView,
+  GestureStateManager,
+  useLongPressGesture,
+  usePanGesture,
+} from 'react-native-gesture-handler';
+
+export default function App() {
+  const pan = usePanGesture({
+    onActivate: () => {
+      console.log('Pan activated!');
+    },
+  });
+
+  const longPress = useLongPressGesture({
+    onActivate: () => {
+      // highlight-next-line
+      GestureStateManager.activate(pan.handlerTag);
+    },
+  });
+
+  return (
+    <GestureHandlerRootView style={styles.container}>
+      <GestureDetector gesture={longPress}>
+        <View style={styles.box} />
+      </GestureDetector>
+      <GestureDetector gesture={pan}>
+        <View style={styles.box} />
+      </GestureDetector>
+    </GestureHandlerRootView>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'space-around',
+  },
+
+  box: {
+    width: 150,
+    height: 150,
+    backgroundColor: 'blue',
+  },
+});
+`}/>
+
+## Methods
+
+### begin
+
+```tsx
+begin: (handlerTag: number) => void;
+```
+
+Triggers [`onBegin`](/docs/fundamentals/callbacks-events#onbegin) callback on gesture with specified `handlerTag`.
+
+### activate
+
+```tsx
+activate: (handlerTag: number) => void;
+```
+
+Triggers [`onActivate`](/docs/fundamentals/callbacks-events#onactivate) callback on gesture with specified `handlerTag`.
+
+### deactivate
+
+```tsx
+deactivate: (handlerTag: number) => void;
+```
+
+If the gesture had activated, it triggers the [`onDeactivate`](/docs/fundamentals/callbacks-events#ondeactivate) callback. It also triggers the [`onFinalize`](/docs/fundamentals/callbacks-events#onfinalize) callback on gesture with the specified `handlerTag`.
+
+### fail
+
+```tsx
+fail: (handlerTag: number) => void;
+```
+
+Triggers [`onFinalize`](/docs/fundamentals/callbacks-events#onfinalize) callback on gesture with specified `handlerTag`. If gesture had activated, it will also trigger [`onDeactivate`](/docs/fundamentals/callbacks-events#ondeactivate) callback.