Remove begin from StateManager (#4024)

## Description

We realised that there is no real use case for allowing to state manage
gestures which did not receive touches. Thus we decided to remove the
function `GestureStateManager.begin()` altogether, as if gesture had
received touches it's state is set to begun. Additonally StateManager
will no longer force going through begin state in activate, thus if we
attempt to use state manager to activate a non begun gesture it won't
activate.

## Test plan

Tested on the following example

<details>

```tsx

import { COLORS, commonStyles } from '../common-app/src/common';
import React from 'react';
import { View } from 'react-native';
import {
  GestureHandlerRootView,
  GestureDetector,
  useLongPressGesture,
  GestureStateManager,
  useSimultaneousGestures,
  usePanGesture,
  useManualGesture,
} from 'react-native-gesture-handler';
import Animated, {
  useAnimatedStyle,
  useSharedValue,
  withTiming,
} from 'react-native-reanimated';

export default function TwoPressables() {
  const isActivated = [useSharedValue(0), useSharedValue(0)];

  const lp1 = useLongPressGesture({
    onBegin: () => {
      'worklet';
      console.log("other begin");
    },
    onActivate: () => {
      'worklet';
      isActivated[0].value = 1;
      console.log(`Box 1: long pressed`);
    },
    onFinalize: () => {
      'worklet';
      console.log("other finalized")
      isActivated[0].value = 0;
    },
    disableReanimated: true,
    minDuration: 1000000
  })

  const lp2 = useManualGesture({
    onTouchesDown: () => {
      console.log("touches down")
    },
    onTouchesUp: (e) => {
      console.log("touches up")
      GestureStateManager.deactivate(e.handlerTag)
    },
    onActivate: () => {
      'worklet';
      isActivated[1].value = 1;
      GestureStateManager.activate(lp1.handlerTag);
      console.log(`Box 2: long pressed`);
    },
    onFinalize: () => {
      'worklet';
      console.log("fhduifhuifhuiwefhuf")
      isActivated[1].value = 0;
    },
    disableReanimated: true,
  })

  const pan = usePanGesture({
    onActivate: () => {
      'worklet';
      GestureStateManager.activate(lp2.handlerTag);
    }
  })

  const g2 = useSimultaneousGestures(lp2, pan);

  const gestures = []

  gestures[0] = lp1;
  gestures[1] = g2;


  const colors = [COLORS.PURPLE, COLORS.NAVY, COLORS.GREEN, COLORS.RED];

  function Box({ index }: { index: number }) {
    const animatedStyle = useAnimatedStyle(() => ({
      opacity: isActivated[index].value === 1 ? 0.5 : 1,
      transform: [
        { scale: withTiming(isActivated[index].value === 1 ? 0.95 : 1) },
      ],
    }));

    return (
      <GestureDetector gesture={gestures[index]}>
        <Animated.View
          style={[
            commonStyles.box,
            { backgroundColor: colors[index] },
            animatedStyle,
          ]}
        />
      </GestureDetector>
    );
  }
  return (
    <GestureHandlerRootView>
      <View style={commonStyles.centerView}>
        <Box index={0} />
        <Box index={1} />
      </View>
    </GestureHandlerRootView>
  );
}

```

</details>

---------

Co-authored-by: Michał Bert <63123542+m-bert@users.noreply.github.com>

Author: akwasniewski

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

@@ -70,6 +70,10 @@ const styles = StyleSheet.create({
 
 If you want to control gesture lifecycle outside of it, you can use `handlerTag` from created gesture object.
 
+:::note 
+The gestures can only be activated after it has begun, that is, after it has received received touch events.
+:::
+
 <CollapsibleCode
 label="Show full example"
 expandedLabel="Hide full example"
@@ -179,14 +183,6 @@ const styles = {
 
 `GestureStateManager` provides methods to manipulate gesture's state imperatively.
 
-### begin
-
-```tsx
-begin: (handlerTag: number) => void;
-```
-
-Triggers [`onBegin`](/docs/fundamentals/callbacks-events#onbegin) callback on gesture with specified `handlerTag`.
-
 ### activate
 
 ```tsx

packages/react-native-gesture-handler/android/src/main/java/com/swmansion/gesturehandler/react/RNGestureHandlerModule.kt

@@ -145,17 +145,11 @@ class RNGestureHandlerModule(reactContext: ReactApplicationContext?) :
     UiThreadUtil.assertOnUiThread()
 
     registry.getHandler(handlerTag)?.let { handler ->
-      if (handler.state == GestureHandler.STATE_UNDETERMINED) {
-        handler.forceReinitializeDuringOnHandle = true
-
-        // When going from UNDETERMINED to ACTIVE, force going through BEGAN to preserve
-        // the correct state flow
-        if (newState == GestureHandler.STATE_ACTIVE) {
-          handler.begin()
+      if (newState == GestureHandler.STATE_ACTIVE) {
+        if (handler.state != GestureHandler.STATE_BEGAN) {
+          // We don't allow activation of gestures which haven't received any touches
+          return
         }
-      }
-
-      if (newState == GestureHandler.STATE_ACTIVE || newState == GestureHandler.STATE_BEGAN) {
         handler.recordHandlerIfNotPresent()
       }
 

packages/react-native-gesture-handler/apple/RNGestureHandler.h

@@ -86,6 +86,7 @@
 @property (nonatomic, weak, nullable) RNGHUIView *hostDetectorView;
 @property (nonatomic, nullable, assign) NSNumber *virtualViewTag;
 @property (nonatomic, copy, nullable) NSNumber *viewTag;
+@property (nonatomic, readonly) RNGestureHandlerState lastState;
 
 - (BOOL)isViewParagraphComponent:(nullable RNGHUIView *)view;
 - (nonnull RNGHUIView *)chooseViewForInteraction:(nonnull UIGestureRecognizer *)recognizer;

packages/react-native-gesture-handler/apple/RNGestureHandlerModule.mm

@@ -225,9 +225,9 @@ - (void)setGestureStateSync:(int)state forHandler:(int)handlerTag
     } else if (state == 3) { // CANCELLED
       handler.recognizer.state = RNGHGestureRecognizerStateCancelled;
     } else if (state == 4) { // ACTIVE
-      if (handler.recognizer.state == UIGestureRecognizerStatePossible) {
-        // Force going from UNDETERMINED to ACTIVE through BEGAN to preserve the correct state transition flow.
-        [handler handleGesture:handler.recognizer fromReset:NO fromManualStateChange:YES];
+      // We don't allow activation of gestures which haven't received any touches
+      if (handler.lastState == RNGestureHandlerStateUndetermined) {
+        return;
       }
       [handler stopActivationBlocker];
       handler.recognizer.state = RNGHGestureRecognizerStateBegan;

packages/react-native-gesture-handler/src/v3/gestureStateManager.ts

@@ -2,7 +2,6 @@ import { State } from '../State';
 import { tagMessage } from '../utils';
 
 export type GestureStateManagerType = {
-  begin(handlerTag: number): void;
   activate(handlerTag: number): void;
   fail(handlerTag: number): void;
   deactivate(handlerTag: number): void;
@@ -21,11 +20,6 @@ const setGestureState = (handlerTag: number, state: State) => {
 };
 
 export const GestureStateManager: GestureStateManagerType = {
-  begin(handlerTag: number) {
-    'worklet';
-    setGestureState(handlerTag, State.BEGAN);
-  },
-
   activate(handlerTag: number) {
     'worklet';
     setGestureState(handlerTag, State.ACTIVE);

packages/react-native-gesture-handler/src/v3/gestureStateManager.web.ts

@@ -1,4 +1,3 @@
-import { State } from '../State';
 import { tagMessage } from '../utils';
 import IGestureHandler from '../web/handlers/IGestureHandler';
 import GestureHandlerOrchestrator from '../web/tools/GestureHandlerOrchestrator';
@@ -16,24 +15,10 @@ function ensureHandlerAttached(handler: IGestureHandler) {
 }
 
 export const GestureStateManager: GestureStateManagerType = {
-  begin(handlerTag: number): void {
-    'worklet';
-    const handler = NodeManager.getHandler(handlerTag);
-    ensureHandlerAttached(handler);
-
-    GestureHandlerOrchestrator.instance.recordHandlerIfNotPresent(handler);
-    handler.begin();
-  },
-
   activate(handlerTag: number): void {
     'worklet';
     const handler = NodeManager.getHandler(handlerTag);
     ensureHandlerAttached(handler);
-    // Force going from UNDETERMINED to ACTIVE through BEGAN to preserve
-    // the correct state transition flow.
-    if (handler.state === State.UNDETERMINED) {
-      handler.begin();
-    }
 
     GestureHandlerOrchestrator.instance.recordHandlerIfNotPresent(handler);
     handler.activate(true);

packages/react-native-gesture-handler/src/web/handlers/GestureHandler.ts

@@ -228,7 +228,7 @@ export default abstract class GestureHandler implements IGestureHandler {
   public activate(force = false) {
     if (
       (this.manualActivation !== true || force) &&
-      (this.state === State.UNDETERMINED || this.state === State.BEGAN)
+      this.state === State.BEGAN
     ) {
       this.delegate.onActivate();
       this.moveToState(State.ACTIVE);

skills/gesture-handler-3-migration/SKILL.md

@@ -69,7 +69,6 @@ In Gesture Handler 3, `stateManager` is no longer passed to `TouchEvent` callbac
 
 `GestureStateManager` provides methods for imperative state management:
 
-- .begin(handlerTag: number)
 - .activate(handlerTag: number)
 - .deactivate(handlerTag: number) (.end() in the old API)
 - .fail(handlerTag: number)
@@ -81,6 +80,8 @@ In Gesture Handler 3, `stateManager` is no longer passed to `TouchEvent` callbac
 
 Callback definitions CANNOT reference the gesture that's being defined. In this scenario use events to get access to the handler tag.
 
+Remove GestureStateManager.begin() as gestures must now automatically enter the BEGAN state via touch events before they can be activated through the GestureStateManager.
+
 ### Migrating relations
 
 #### Composed gestures