[docs] State management #3905

m-bert · 2026-01-08T13:54:09Z

Description

This PR handles state management in our docs:

Moves information about states to "under the hood" section
Rewrites entire states & events page to focus more on callbacks
Updates GestureStateManager entry and moves it to fundamentals
Merges manual gesture guide with manual gesture docs

Test plan

Read docs 🤓

j-piasecki · 2026-01-26T10:54:05Z

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

+onUpdate: (event: GestureEvent<HandlerData>) => void
+```
+
+Called every time a gesture is updated after it has started.


What does it mean that "gesture is updated"?

Okay, I agree that it might not make much sense. However, I'm not sure how to rephrase it. Maybe something like

"Called every time a gesture receives a GestureEvent, provided it has previously activated."

What do you think?

j-piasecki · 2026-01-26T10:56:40Z

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

+const longPress = useLongPressGesture({
+  onActivate: () => {
+    console.log('LongPress activated!');
+  },
+});
+
+const pan = usePanGesture({
+  onBegin: () => {
+    GestureStateManager.activate(longPress.handlerTag);
+  },
+});


This example doesn't make sense, why not in reverse? (long press activating pan)

j-piasecki · 2026-01-26T10:58:02Z

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

+Triggers first [`onDeactivate`](/docs/fundamentals/callbacks-events#ondeactivate), then [`onFinalize`](/docs/fundamentals/callbacks-events#onfinalize) callbacks on gesture with specified `handlerTag`.
+


What if I call it before the gesture activates?

j-piasecki · 2026-01-26T10:59:02Z

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

+### begin
+
+```tsx
+begin: (handlerTag: number) => void;
+```
+
+Triggers [`onBegin`](/docs/fundamentals/callbacks-events#onbegin) callback on gesture with specified `handlerTag`.


Do we actually need the explicit "begin" method here? Won't all gestures automatically begin when detecting the first touch?

Is it always the case? What about pinch and rotation? At first glance (at least on web), they won't begin unless interacting with at least 2 pointers.

j-piasecki · 2026-01-26T11:03:34Z

packages/docs-gesture-handler/docs/gestures/use-long-press-gesture.mdx

 import SharedValueInfo from './\_shared/shared-value-info.md';

 A discrete gesture that activates when the corresponding view is pressed for a sufficiently long time.
-This gesture's state will turn into [END](/docs/fundamentals/states-events#end) immediately after the finger is released.


Do we want to get rid of all the state links? We could be linking to specific callbacks instead.

j-piasecki · 2026-01-26T11:06:01Z

packages/docs-gesture-handler/docs/gestures/use-manual-gesture.mdx

+
+## Modifying existing gestures
+
+While manual gestures open great possibilities we are aware that reimplementing pinch or rotation from scratch just because you need to activate in specific circumstances or require position of the fingers, would be a waste of time as those gestures are already available. Therefore, you can use touch events with every gesture to extract more detailed information about the gesture than what the basic events alone provide. We also added a `manualActivation` modifier on all continuous gestures, which prevents the gesture it is applied to from activating automatically, giving you full control over its behavior.


I'm not sure whether this is the right place for this information.

tl;dr

I think we can remove it. If we really want to keep this, then I believe it should be rephrased - in that case we have to decide what we actually want to say here.

Whole answer

Probably not. However, I have mixed feelings about this message. It looks like it gathers information from few sections and tries to merge them into one, but I'm not sure if it works.

It mentions TouchEvent, but only to say that "you don't have to use manual, you have more info on other gestures already"

It introduces concept of continuous gestures, which is not explained in the docs

It also describes manualActivation, which is already described when looking at specific handlers' configs.

I'm also not sure where do we want to put this if we were to move it. Overall it just sounds like "hey, we have manual handlers, but probably you could use the ones that are already configured" and that doesn't make much sense, especially after whole "tutorial" of how you use them.

j-piasecki · 2026-01-26T11:10:42Z

packages/docs-gesture-handler/docs/gestures/use-native-gesture.mdx

 ### shouldActivateOnStart (**Android only**)

 ```ts
 shouldActivateOnStart: boolean | SharedValue<boolean>;


Unrelated, but this name doesn't make sense with the current api.

shouldActivateOnActivate 😄

packages/docs-gesture-handler/docs/gestures/use-pinch-gesture.mdx

packages/docs-gesture-handler/docs/gestures/use-rotation-gesture.mdx

j-piasecki · 2026-01-26T11:17:21Z

packages/docs-gesture-handler/docs/under-the-hood/state.md

+| **`FAILED`**       | The handler failed to recognize the gesture.                                             | [`onFinalize`](/docs/fundamentals/callbacks-events#onfinalize)                                                              |
+| **`CANCELLED`**    | The system interrupted the gesture.                                                      | [`onFinalize`](/docs/fundamentals/callbacks-events#onfinalize)                                                              |


Failed and Cancelled will also trigger onDeactivate if the gesture was active.

…re.mdx Co-authored-by: Jakub Piasecki <jakub.piasecki@swmansion.com>

Co-authored-by: Jakub Piasecki <jakub.piasecki@swmansion.com>

m-bert added 6 commits January 8, 2026 10:56

Initial events page

c7de4c6

Switch to vis.js

285fc72

Adjust resize

c867d7c

Add theme-common to package.json

ea4b04f

Rename section

0f7586f

Bring back prism

1b25b59

m-bert changed the title ~~@mbert/docs state manager~~ [docs] Rewrite "States & Events" page Jan 8, 2026

m-bert marked this pull request as draft January 8, 2026 14:06

m-bert added 5 commits January 8, 2026 15:49

Add states table

eb83d43

Add CodeWithDetails

33a85a3

Do not mention states outside dedicated page

35d2da7

Add note about complementary callbacks

e06ad48

Add StateManager page

5f998f4

m-bert changed the title ~~[docs] Rewrite "States & Events" page~~ [docs] State management Jan 9, 2026

m-bert added the Documentation Documentation change/enhancement label Jan 9, 2026

m-bert added 13 commits January 9, 2026 16:09

Merge branch '@mbert/docs-detector' into @mbert/docs-state-manager

1c20ea0

Update manual quick guide

764b1d8

Change number of array elements in example

f6145db

Split states

b920df7

Update margin in flow chart

1c5ae3d

Improve CollapsibleCode component

aa13ec4

Use CollapsibleCode

e250c68

Update variable

1c4e142

Remove old state manager guide

2afec03

Fix details component

b54932a

Remove manual guide

66ddc2b

Fix broken link

404e465

Remove CodeWithTypes

fc3fcd2

m-bert marked this pull request as ready for review January 12, 2026 13:27

Move autoworkletization

cc3f815

m-bert added 2 commits January 12, 2026 15:47

Update autoworkletization

fbfb9fc

Remove bold

cc46156

j-piasecki reviewed Jan 26, 2026

View reviewed changes

m-bert and others added 2 commits January 26, 2026 17:05

Update packages/docs-gesture-handler/docs/gestures/use-rotation-gestu…

d671e4f

…re.mdx Co-authored-by: Jakub Piasecki <jakub.piasecki@swmansion.com>

Update packages/docs-gesture-handler/docs/gestures/use-pinch-gesture.mdx

481e165

Co-authored-by: Jakub Piasecki <jakub.piasecki@swmansion.com>

		Triggers first [`onDeactivate`](/docs/fundamentals/callbacks-events#ondeactivate), then [`onFinalize`](/docs/fundamentals/callbacks-events#onfinalize) callbacks on gesture with specified `handlerTag`.


		## Modifying existing gestures

		While manual gestures open great possibilities we are aware that reimplementing pinch or rotation from scratch just because you need to activate in specific circumstances or require position of the fingers, would be a waste of time as those gestures are already available. Therefore, you can use touch events with every gesture to extract more detailed information about the gesture than what the basic events alone provide. We also added a `manualActivation` modifier on all continuous gestures, which prevents the gesture it is applied to from activating automatically, giving you full control over its behavior.

		\| `FAILED` \| The handler failed to recognize the gesture. \| [`onFinalize`](/docs/fundamentals/callbacks-events#onfinalize) \|
		\| `CANCELLED` \| The system interrupted the gesture. \| [`onFinalize`](/docs/fundamentals/callbacks-events#onfinalize) \|

Uh oh!

[docs] State management #3905

Are you sure you want to change the base?

[docs] State management #3905

Conversation

m-bert commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Test plan

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

tl;dr

Whole answer

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

m-bert commented Jan 8, 2026 •

edited

Loading