[docs] State management

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

@@ -0,0 +1,217 @@
+---
+id: callbacks-events
+title: Gesture callbacks & events
+sidebar_label: Gesture callbacks & events
+sidebar_position: 5
+---
+
+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).
+
+## 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. 
+
+## 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,
+})
+```
+
+In the above case, you should add a [`"worklet";`](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary/#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,
+})
+```

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

@@ -0,0 +1,79 @@
+---
+id: state-manager
+title: State manager
+sidebar_label: State manager
+sidebar_position: 6
+---
+
+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.
+
+```tsx {3}
+const longPress = useLongPressGesture({
+  onTouchesDown: (e) => {
+    GestureStateManager.activate(e.handlerTag);
+  },
+  onActivate: () => {
+    console.log('LongPress activated!');
+  },
+});
+```
+
+### Outside gesture definition
+
+If you want to control gesture lifecycle outside of it, you can use `handlerTag` from created gesture object.
+
+```tsx {9}
+const longPress = useLongPressGesture({
+  onActivate: () => {
+    console.log('LongPress activated!');
+  },
+});
+
+const pan = usePanGesture({
+  onBegin: () => {
+    GestureStateManager.activate(longPress.handlerTag);
+  },
+});
+```
+
+## 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;
+```
+
+Triggers first [`onDeactivate`](/docs/fundamentals/callbacks-events#ondeactivate), then [`onFinalize`](/docs/fundamentals/callbacks-events#onfinalize) callbacks on gesture with 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.

packages/docs-gesture-handler/docs/guides/manual-gestures/_steps/step1.md → packages/docs-gesture-handler/docs/gestures/_manual_gesture_steps/step1.md

@@ -1,7 +1,7 @@
-```jsx
-interface Pointer {
-  visible: boolean;
+```tsx
+type Pointer = {
   x: number;
   y: number;
-}
+  visible: boolean;
+};
 ```