[Native] Add cancelOnLeave prop to Touchable (#4105)

## Description

Adds `cancelOnLeave` prop to the `Touchable` component, set to `true` by
default. It doesn't take effect on the web for now.

It prevents `NativeViewGestureHandler` from canceling when the pointer
leaves the view bounds, and tracks `pointerInside` from update events to
call `onPressIn` and `onPressOut` callbacks. `onPress` is called only if
the pointer is released in the bounds of the button.

## Test plan

<details>
<summary>Expand</summary>

```jsx
import React, { useState } from 'react';
import { StyleSheet, Text, View } from 'react-native';
import { Touchable } from 'react-native-gesture-handler';

export default function EmptyExample() {
  const [isActive1, setIsActive1] = useState(false);
  const [isActive2, setIsActive2] = useState(false);

  return (
    <View style={styles.container}>
      <Touchable
        style={[styles.button, isActive1 && styles.buttonActive]}
        onPress={() => console.log('pressed')}
        onPressIn={() => {
          console.log('onPressIn');
          setIsActive1(true)
        }}
        onPressOut={() => {
          console.log('onPressOut');
          setIsActive1(false)
        }}
        activeScale={1.05}
        exclusive={false}
        cancelOnLeave={true}>
        <Text style={styles.label}>{isActive1 ? 'PRESS ME' : 'Press me'}</Text>
      </Touchable>
      <Touchable
        style={[styles.button, isActive2 && styles.buttonActive]}
        onPress={() => console.log('pressed')}
        onPressIn={() => {
          console.log('onPressIn');
          setIsActive2(true)
        }}
        onPressOut={() => {
          console.log('onPressOut');
          setIsActive2(false)
        }}
        activeScale={1.05}
        exclusive={false}
        cancelOnLeave={true}>
        <Text style={styles.label}>{isActive2 ? 'PRESS ME' : 'Press me'}</Text>
      </Touchable>
      <Text style={styles.hint}>
        Press the button, then slowly drag your pointer away from it.
      </Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: 'center',
    alignItems: 'center',
    padding: 24,
    gap: 24,
  },
  button: {
    backgroundColor: '#ddd',
    paddingHorizontal: 32,
    paddingVertical: 16,
    borderRadius: 8,
  },
  buttonActive: {
    backgroundColor: '#f97316',
  },
  label: {
    fontSize: 20,
    fontWeight: '600',
  },
  hint: {
    textAlign: 'center',
    opacity: 0.6,
    fontSize: 14,
  },
});
```

</details>

|-|cancelOnLeave=true|cancelOnLeave=false|
|-|-|-|
|Android|<video
src="https://github.com/user-attachments/assets/b2fb1d24-4dd1-4324-99ec-81c11a419af9"
/>|<video
src="https://github.com/user-attachments/assets/7080ef75-6a86-44c9-ad7a-2f49326c03ad"
/>|
|iOS|<video
src="https://github.com/user-attachments/assets/bcaa4f1d-8ce2-4265-a9ff-76a86479814f"
/>|<video
src="https://github.com/user-attachments/assets/e01b6a31-799b-45cb-ba5a-46854c29abf0"
/>|

Author: j-piasecki

packages/docs-gesture-handler/docs/components/touchable.mdx

@@ -270,9 +270,28 @@ Triggered when the button gets released or the pointer moves outside of the butt
 
 ### onPress
 
-```ts
-onPress?: (pointerInside: boolean) => void;
-```
+<CollapsibleCode 
+label="Show composed types definitions"
+expandedLabel="Hide composed types definitions"
+lineBounds={[0, 1]}
+src={`
+onPress?: (e: GestureEvent<NativeHandlerData>) => void;
+
+type GestureEvent<NativeHandlerData> = {
+    handlerTag: number;
+    numberOfPointers: number;
+    pointerType: PointerType;
+    pointerInside: boolean;
+}
+
+enum PointerType {
+    TOUCH,
+    STYLUS,
+    MOUSE,
+    KEY,
+    OTHER,
+}
+`}/>
 
 Triggered when the button gets pressed (analogous to `onPress` in `Pressable` from RN core).
 
@@ -314,3 +333,13 @@ type PressableAndroidRippleConfig = {
 `}/>
 
 Configuration for the ripple effect on Android. If not provided, the ripple effect will be disabled. If `{}` is provided, the ripple effect will be enabled with default configuration.
+
+<Badges platforms={['android', 'ios']}>
+### cancelOnLeave
+</Badges>
+
+```ts
+cancelOnLeave?: boolean;
+```
+
+Whether the touch should be canceled when the pointer leaves the component. By default set to `true`. On web this prop doesn't have any effect and behaves as if `true` was set.

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

@@ -379,6 +379,7 @@ class RNGestureHandlerButtonViewManager :
     private var underlayDrawable: PaintDrawable? = null
     private var pressInTimestamp = 0L
     private var pendingPressOut: Runnable? = null
+    private var isPointerInsideBounds = false
 
     // When non-null the ripple is drawn in dispatchDraw (above background, below children).
     // When null the ripple lives on the foreground drawable instead.
@@ -481,7 +482,30 @@ class RNGestureHandlerButtonViewManager :
       if (lastEventTime != eventTime || lastAction != action || action == MotionEvent.ACTION_CANCEL) {
         lastEventTime = eventTime
         lastAction = action
-        return super.onTouchEvent(event)
+        val handled = super.onTouchEvent(event)
+
+        // Replay press-in / press-out animations across drag transitions.
+        if (handled && canRespondToTouches()) {
+          when (event.actionMasked) {
+            MotionEvent.ACTION_DOWN, MotionEvent.ACTION_POINTER_DOWN -> isPointerInsideBounds = true
+            MotionEvent.ACTION_MOVE -> {
+              val inside = event.x >= 0 && event.y >= 0 && event.x < width && event.y < height
+              if (inside != isPointerInsideBounds) {
+                isPointerInsideBounds = inside
+                if (inside) {
+                  animatePressIn()
+                } else {
+                  animatePressOut()
+                }
+              }
+            }
+            MotionEvent.ACTION_UP, MotionEvent.ACTION_POINTER_UP, MotionEvent.ACTION_CANCEL ->
+              isPointerInsideBounds =
+                false
+          }
+        }
+
+        return handled
       }
       return false
     }
@@ -719,6 +743,12 @@ class RNGestureHandlerButtonViewManager :
       }
     }
 
+    private fun canRespondToTouches(): Boolean = if (exclusive) {
+      touchResponder === this
+    } else {
+      !(touchResponder?.exclusive ?: false)
+    }
+
     private fun tryGrabbingResponder(): Boolean {
       if (isChildTouched()) {
         return false
@@ -728,11 +758,8 @@ class RNGestureHandlerButtonViewManager :
         touchResponder = this
         return true
       }
-      return if (exclusive) {
-        touchResponder === this
-      } else {
-        !(touchResponder?.exclusive ?: false)
-      }
+
+      return canRespondToTouches()
     }
 
     private fun isChildTouched(children: Sequence<View> = this.children): Boolean {

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

@@ -80,7 +80,9 @@ - (void)commonInit
 
 #if !TARGET_OS_TV && !TARGET_OS_OSX
   [self setExclusiveTouch:YES];
-  [self addTarget:self action:@selector(handleAnimatePressIn) forControlEvents:UIControlEventTouchDown];
+  [self addTarget:self
+                action:@selector(handleAnimatePressIn)
+      forControlEvents:UIControlEventTouchDown | UIControlEventTouchDragEnter];
   [self addTarget:self
                 action:@selector(handleAnimatePressOut)
       forControlEvents:UIControlEventTouchUpInside | UIControlEventTouchUpOutside | UIControlEventTouchDragExit |
@@ -566,22 +568,29 @@ - (void)setUnderlayBorderInsetsWithTop:(CGFloat)top right:(CGFloat)right bottom:
 #if TARGET_OS_OSX
 - (void)mouseDown:(NSEvent *)event
 {
+  _isTouchInsideBounds = YES;
   [self handleAnimatePressIn];
   [super mouseDown:event];
 }
 
 - (void)mouseUp:(NSEvent *)event
 {
   [self handleAnimatePressOut];
+  _isTouchInsideBounds = NO;
   [super mouseUp:event];
 }
 
 - (void)mouseDragged:(NSEvent *)event
 {
   NSPoint locationInWindow = [event locationInWindow];
   NSPoint locationInView = [self convertPoint:locationInWindow fromView:nil];
+  BOOL currentlyInside = NSPointInRect(locationInView, self.bounds);
 
-  if (!NSPointInRect(locationInView, self.bounds)) {
+  if (currentlyInside && !_isTouchInsideBounds) {
+    _isTouchInsideBounds = YES;
+    [self handleAnimatePressIn];
+  } else if (!currentlyInside && _isTouchInsideBounds) {
+    _isTouchInsideBounds = NO;
     [self handleAnimatePressOut];
   }
 }

packages/react-native-gesture-handler/src/v3/components/Touchable/Touchable.tsx

@@ -22,6 +22,12 @@ const TouchableButton = createNativeWrapper<
 const isAndroid = Platform.OS === 'android';
 const TRANSPARENT_RIPPLE = { rippleColor: 'transparent' as const };
 
+enum PointerState {
+  UNKNOWN,
+  INSIDE,
+  OUTSIDE,
+}
+
 export const Touchable = (props: TouchableProps) => {
   const {
     underlayColor = 'black',
@@ -35,12 +41,14 @@ export const Touchable = (props: TouchableProps) => {
     onPressOut,
     children,
     disabled = false,
+    cancelOnLeave = true,
     ref,
     ...rest
   } = props;
 
   const shouldUseNativeRipple = isAndroid && androidRipple !== undefined;
 
+  const pointerState = useRef<PointerState>(PointerState.UNKNOWN);
   const longPressDetected = useRef(false);
   const longPressTimeout = useRef<ReturnType<typeof setTimeout> | undefined>(
     undefined
@@ -62,11 +70,14 @@ export const Touchable = (props: TouchableProps) => {
   const onBegin = useCallback(
     (e: CallbackEventType) => {
       if (!e.pointerInside) {
+        pointerState.current = PointerState.OUTSIDE;
         return;
       }
 
       onPressIn?.(e);
       startLongPressTimer();
+
+      pointerState.current = PointerState.INSIDE;
     },
     [startLongPressTimer, onPressIn]
   );
@@ -80,16 +91,20 @@ export const Touchable = (props: TouchableProps) => {
 
   const onDeactivate = useCallback(
     (e: EndCallbackEventType) => {
-      if (!e.canceled && !longPressDetected.current) {
-        onPress?.(e.pointerInside);
+      if (!e.canceled && !longPressDetected.current && e.pointerInside) {
+        onPress?.(e);
       }
     },
     [onPress]
   );
 
   const onFinalize = useCallback(
     (e: EndCallbackEventType) => {
-      onPressOut?.(e);
+      if (pointerState.current === PointerState.INSIDE) {
+        onPressOut?.(e);
+      }
+
+      pointerState.current = PointerState.UNKNOWN;
 
       if (longPressTimeout.current !== undefined) {
         clearTimeout(longPressTimeout.current);
@@ -99,6 +114,32 @@ export const Touchable = (props: TouchableProps) => {
     [onPressOut]
   );
 
+  const onUpdate = useCallback(
+    (e: CallbackEventType) => {
+      if (pointerState.current === PointerState.UNKNOWN) {
+        return;
+      }
+
+      if (e.pointerInside) {
+        if (pointerState.current === PointerState.OUTSIDE) {
+          onPressIn?.(e);
+        }
+        pointerState.current = PointerState.INSIDE;
+      } else {
+        if (pointerState.current === PointerState.INSIDE) {
+          onPressOut?.(e);
+
+          if (longPressTimeout.current !== undefined) {
+            clearTimeout(longPressTimeout.current);
+            longPressTimeout.current = undefined;
+          }
+        }
+        pointerState.current = PointerState.OUTSIDE;
+      }
+    },
+    [onPressIn, onPressOut]
+  );
+
   const rippleProps = shouldUseNativeRipple
     ? {
         rippleColor: androidRipple?.color,
@@ -118,9 +159,11 @@ export const Touchable = (props: TouchableProps) => {
       onActivate={onActivate}
       onDeactivate={onDeactivate}
       onFinalize={onFinalize}
+      onUpdate={onUpdate}
       defaultOpacity={defaultOpacity}
       defaultUnderlayOpacity={defaultUnderlayOpacity}
-      underlayColor={underlayColor}>
+      underlayColor={underlayColor}
+      shouldCancelWhenOutside={cancelOnLeave}>
       {children}
     </TouchableButton>
   );

packages/react-native-gesture-handler/src/v3/components/Touchable/TouchableProps.ts

@@ -18,12 +18,20 @@ type PressableAndroidRippleConfig = {
 type RippleProps = 'rippleColor' | 'rippleRadius' | 'borderless' | 'foreground';
 
 export type TouchableProps = Omit<ButtonProps, RippleProps | 'enabled'> &
-  Omit<BaseButtonProps, keyof RawButtonProps | 'onActiveStateChange'> & {
+  Omit<
+    BaseButtonProps,
+    keyof RawButtonProps | 'onActiveStateChange' | 'onPress'
+  > & {
     /**
      * Configuration for the ripple effect on Android.
      */
     androidRipple?: PressableAndroidRippleConfig | undefined;
 
+    /**
+     * Called when the component gets pressed.
+     */
+    onPress?: ((event: CallbackEventType) => void) | undefined;
+
     /**
      * Called when pointer touches the component.
      */
@@ -38,4 +46,10 @@ export type TouchableProps = Omit<ButtonProps, RippleProps | 'enabled'> &
      * Whether the component should ignore touches. By default set to false.
      */
     disabled?: boolean | undefined;
+
+    /**
+     * Whether the touch should be canceled when pointer leaves the component. By default set to true.
+     * On web this prop doesn't have any effect and behaves as if `true` was set.
+     */
+    cancelOnLeave?: boolean | undefined;
   };