react-native-gesture-handler 3.0.0-beta.4 → 3.0.0-beta.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-gesture-handler",
-  "version": "3.0.0-beta.4",
+  "version": "3.0.0-beta.5",
   "description": "Declarative API exposing native platform touch and gesture system to React Native",
   "scripts": {
     "test": "jest",
@@ -77,7 +77,7 @@
     "@react-native/jest-preset": "0.85.0",
     "@testing-library/react-native": "^12.5.1",
     "@types/invariant": "^2.2.37",
-    "@types/jest": "^27.0.3",
+    "@types/jest": "^29.5.12",
     "@types/react": "^19.2.0",
     "@typescript-eslint/eslint-plugin": "^6.9.0",
     "@typescript-eslint/parser": "^6.9.0",
@@ -90,7 +90,7 @@
     "eslint-plugin-prettier": "^5.0.1",
     "eslint-plugin-react": "^7.37.5",
     "husky": "^8.0.1",
-    "jest": "^28.1.0",
+    "jest": "^29.7.0",
     "lint-staged": "^12.3.2",
     "madge": "^6.1.0",
     "prettier": "3.3.3",

package/src/RNGestureHandlerModule.web.ts

@@ -82,6 +82,9 @@ export default {
     NodeManager.dropGestureHandler(handlerTag);
   },
   configureRelations(handlerTag: number, relations: GestureRelations) {
+    if (!NodeManager.hasHandler(handlerTag)) {
+      return;
+    }
     InteractionManager.instance.configureInteractions(
       NodeManager.getHandler(handlerTag),
       relations
@@ -89,7 +92,8 @@ export default {
   },
   // eslint-disable-next-line @typescript-eslint/no-empty-function
   flushOperations() {},
-  setReanimatedAvailable(_isAvailable: boolean) {
+  installUIRuntimeBindings() {
     // No-op on web
+    return true;
   },
 };

package/src/components/GestureButtons.tsx

@@ -18,19 +18,30 @@ import type {
   LegacyRectButtonProps,
   RectButtonWithRefProps,
 } from './GestureButtonsProps';
-import GestureHandlerButton from './GestureHandlerButton';
+import GestureHandlerButton, { type ButtonProps } from './GestureHandlerButton';
 
-/**
- * @deprecated use `RawButton` instead
- */
-export const LegacyRawButton = createNativeWrapper<LegacyRawButtonProps>(
-  GestureHandlerButton as unknown as HostComponent<LegacyRawButtonProps>,
+type LegacyRawButtonInnerProps = LegacyRawButtonProps & {
+  needsOffscreenAlphaCompositing?: boolean;
+};
+
+const LegacyRawButtonInner = createNativeWrapper<LegacyRawButtonInnerProps>(
+  GestureHandlerButton as unknown as HostComponent<LegacyRawButtonInnerProps>,
   {
     shouldCancelWhenOutside: false,
     shouldActivateOnStart: Platform.OS === 'web',
   }
 );
 
+/**
+ * @deprecated use `RawButton` instead
+ */
+export const LegacyRawButton = (
+  props: Omit<
+    React.ComponentProps<typeof LegacyRawButtonInner>,
+    'needsOffscreenAlphaCompositing'
+  >
+) => <LegacyRawButtonInner {...props} needsOffscreenAlphaCompositing />;
+
 class InnerBaseButton extends React.Component<BaseButtonWithRefProps> {
   static defaultProps = {
     delayLongPress: 600,
@@ -280,4 +291,9 @@ export const LegacyBorderlessButton = ({
   ref?: React.Ref<React.ComponentType<any>> | undefined;
 }) => <InnerBorderlessButton innerRef={ref} {...props} />;
 
-export { default as LegacyPureNativeButton } from './GestureHandlerButton';
+/**
+ * @deprecated use `PureNativeButton` instead
+ */
+export const LegacyPureNativeButton = (
+  props: Omit<ButtonProps, 'needsOffscreenAlphaCompositing'>
+) => <GestureHandlerButton {...props} needsOffscreenAlphaCompositing />;

package/src/components/GestureHandlerButton.tsx

@@ -60,18 +60,31 @@ export interface ButtonProps extends ViewProps, AccessibilityProps {
   touchSoundDisabled?: boolean | undefined;
 
   /**
-   * Duration of the press-in animation when the button is held down, in
-   * milliseconds. Defaults to `tapAnimationDuration` when not set (or set
-   * to any negative value).
+   * Minimum duration (in milliseconds) of the press-in animation on a
+   * quick tap. Defaults to 50ms.
    */
-  pressAndHoldAnimationDuration?: number | undefined;
+  tapAnimationInDuration?: number | undefined;
 
   /**
-   * Minimum duration (in milliseconds) that the press animation must run
-   * before the press-out animation is allowed to start. Ensures the pressed
-   * state is visible on quick taps. Defaults to 100ms.
+   * Minimum duration (in milliseconds) of the press-out animation on a
+   * quick tap. Defaults to 100ms.
    */
-  tapAnimationDuration?: number | undefined;
+  tapAnimationOutDuration?: number | undefined;
+
+  /**
+   * Threshold (in milliseconds) at which the press-out animation
+   * switches from the tap-out timing to `longPressAnimationOutDuration`.
+   * Set to any negative value to disable the switch.
+   */
+  longPressDuration?: number | undefined;
+
+  /**
+   * Duration of the press-out animation, in milliseconds, when the
+   * button is released after being held past `longPressDuration`.
+   * Defaults to `tapAnimationOutDuration` when not set (or set to any
+   * negative value).
+   */
+  longPressAnimationOutDuration?: number | undefined;
 
   /**
    * Opacity applied to the button when it is pressed.
@@ -88,6 +101,44 @@ export interface ButtonProps extends ViewProps, AccessibilityProps {
    */
   activeUnderlayOpacity?: number | undefined;
 
+  /**
+   * Web only.
+   *
+   * Opacity applied to the button when it is hovered. Defaults to
+   * `defaultOpacity` when not set.
+   */
+  hoverOpacity?: number | undefined;
+
+  /**
+   * Web only.
+   *
+   * Scale applied to the button when it is hovered. Defaults to
+   * `defaultScale` when not set.
+   */
+  hoverScale?: number | undefined;
+
+  /**
+   * Web only.
+   *
+   * Opacity applied to the underlay when the button is hovered. Defaults
+   * to `defaultUnderlayOpacity` when not set.
+   */
+  hoverUnderlayOpacity?: number | undefined;
+
+  /**
+   * Web only.
+   *
+   * Duration of the hover-in animation, in milliseconds. Defaults to 50ms.
+   */
+  hoverAnimationInDuration?: number | undefined;
+
+  /**
+   * Web only.
+   *
+   * Duration of the hover-out animation, in milliseconds. Defaults to 100ms.
+   */
+  hoverAnimationOutDuration?: number | undefined;
+
   /**
    * Opacity applied to the button when it is not pressed.
    */
@@ -108,6 +159,17 @@ export interface ButtonProps extends ViewProps, AccessibilityProps {
    */
   underlayColor?: ColorValue | undefined;
 
+  /**
+   * Android only.
+   *
+   * Whether the view should render with an offscreen alpha-compositing buffer
+   * when its `opacity` is less than 1. Defaults to `false` — without the
+   * offscreen buffer, children that draw past the view's bounds (e.g. anti-
+   * aliased border edges) are not clipped by the layer when `opacity < 1`.
+   * Set to `true` to opt back into the standard Android behavior.
+   */
+  needsOffscreenAlphaCompositing?: boolean | undefined;
+
   /**
    * Style object, use it to set additional styles.
    */

package/src/components/GestureHandlerButton.web.tsx

@@ -8,11 +8,18 @@ import { GestureLifecycleEvent } from '../web/tools/GestureLifecycleEvents';
 type ButtonProps = ViewProps & {
   ref?: React.Ref<React.ComponentRef<typeof View>>;
   enabled?: boolean;
-  pressAndHoldAnimationDuration?: number;
-  tapAnimationDuration?: number;
+  tapAnimationInDuration?: number;
+  tapAnimationOutDuration?: number;
+  longPressDuration?: number;
+  longPressAnimationOutDuration?: number;
+  hoverAnimationInDuration?: number;
+  hoverAnimationOutDuration?: number;
   activeOpacity?: number;
   activeScale?: number;
   activeUnderlayOpacity?: number;
+  hoverOpacity?: number;
+  hoverScale?: number;
+  hoverUnderlayOpacity?: number;
   defaultOpacity?: number;
   defaultScale?: number;
   defaultUnderlayOpacity?: number;
@@ -22,11 +29,18 @@ type ButtonProps = ViewProps & {
 export const ButtonComponent = ({
   ref: externalRef,
   enabled = true,
-  pressAndHoldAnimationDuration: pressAndHoldAnimationDurationProp = -1,
-  tapAnimationDuration: tapAnimationDurationProp = 100,
+  tapAnimationInDuration = 50,
+  tapAnimationOutDuration = 100,
+  longPressDuration = -1,
+  longPressAnimationOutDuration = 100,
+  hoverAnimationInDuration = 50,
+  hoverAnimationOutDuration = 100,
   activeOpacity = 1,
   activeScale = 1,
   activeUnderlayOpacity = 0,
+  hoverOpacity: hoverOpacityProp,
+  hoverScale: hoverScaleProp,
+  hoverUnderlayOpacity: hoverUnderlayOpacityProp,
   defaultOpacity = 1,
   defaultScale = 1,
   defaultUnderlayOpacity = 0,
@@ -35,16 +49,15 @@ export const ButtonComponent = ({
   children,
   ...rest
 }: ButtonProps) => {
-  const tapAnimationDuration =
-    tapAnimationDurationProp < 0 ? 0 : tapAnimationDurationProp;
-  const pressAndHoldAnimationDuration =
-    pressAndHoldAnimationDurationProp < 0
-      ? tapAnimationDuration
-      : pressAndHoldAnimationDurationProp;
+  const hoverOpacity = hoverOpacityProp ?? defaultOpacity;
+  const hoverScale = hoverScaleProp ?? defaultScale;
+  const hoverUnderlayOpacity =
+    hoverUnderlayOpacityProp ?? defaultUnderlayOpacity;
 
   const [pressed, setPressed] = React.useState(false);
+  const [hovered, setHovered] = React.useState(false);
   const [currentDuration, setCurrentDuration] = React.useState(
-    pressAndHoldAnimationDuration
+    tapAnimationInDuration
   );
   const pressInTimestamp = React.useRef(0);
   const pressOutTimer = React.useRef<ReturnType<typeof setTimeout> | null>(
@@ -114,10 +127,10 @@ export const ButtonComponent = ({
         pressOutTimer.current = null;
       }
       pressInTimestamp.current = performance.now();
-      setCurrentDuration(pressAndHoldAnimationDuration);
+      setCurrentDuration(tapAnimationInDuration);
       setPressed(true);
     },
-    [enabled, pressAndHoldAnimationDuration]
+    [enabled, tapAnimationInDuration]
   );
 
   const pressOut = React.useCallback(
@@ -137,34 +150,88 @@ export const ButtonComponent = ({
       const elapsed = performance.now() - pressInTimestamp.current;
       pressInTimestamp.current = 0;
 
-      if (elapsed >= pressAndHoldAnimationDuration) {
-        setCurrentDuration(pressAndHoldAnimationDuration);
+      if (longPressDuration >= 0 && elapsed >= longPressDuration) {
+        // Long-press release — use the configured long-press out duration.
+        setCurrentDuration(longPressAnimationOutDuration);
         setPressed(false);
-        // elapsed * 2 to ensure there is at least half of the tapAnimationDuration left for the animation to play
-      } else if (elapsed * 2 >= tapAnimationDuration) {
+      } else if (elapsed >= tapAnimationInDuration) {
+        // Press-in animation fully finished - release with the configured out duration.
+        setCurrentDuration(tapAnimationOutDuration);
+        setPressed(false);
+        // elapsed * 2 to ensure there is at least half of the tapAnimationOutDuration left for the animation to play
+      } else if (elapsed * 2 >= tapAnimationOutDuration) {
         setCurrentDuration(elapsed);
         setPressed(false);
       } else {
-        // Let the in-progress CSS press-in transition continue; schedule press-out after remaining time
-        const remaining = tapAnimationDuration - elapsed;
+        // Let the in-progress CSS press-in transition continue; schedule press-out after remaining time.
+        const remaining = tapAnimationInDuration - elapsed;
         pressOutTimer.current = setTimeout(() => {
           pressOutTimer.current = null;
-          setCurrentDuration(tapAnimationDuration);
+          setCurrentDuration(tapAnimationOutDuration);
           setPressed(false);
         }, remaining);
       }
     },
-    [pressAndHoldAnimationDuration, tapAnimationDuration]
+    [
+      longPressDuration,
+      longPressAnimationOutDuration,
+      tapAnimationInDuration,
+      tapAnimationOutDuration,
+    ]
+  );
+
+  const handlePointerEnter = React.useCallback(
+    (event: NativeSyntheticEvent<{ pointerType?: string }>) => {
+      if (!enabled || event.nativeEvent.pointerType === 'touch') {
+        return;
+      }
+      // Skip duration update while pressed so the press transition owns it.
+      if (!pressed) {
+        setCurrentDuration(hoverAnimationInDuration);
+      }
+      setHovered(true);
+    },
+    [enabled, pressed, hoverAnimationInDuration]
   );
 
+  const handlePointerLeave = React.useCallback(
+    (event: NativeSyntheticEvent<{ pointerType?: string }>) => {
+      pressOut(event);
+      if (event.nativeEvent.pointerType === 'touch') {
+        return;
+      }
+      if (!pressed) {
+        setCurrentDuration(hoverAnimationOutDuration);
+      }
+      setHovered(false);
+    },
+    [pressOut, pressed, hoverAnimationOutDuration]
+  );
+
+  // Mask hover at render rather than clearing the state. Avoids a state
+  // write inside an effect, and lets hover resume naturally when `enabled`
+  // flips back to true while the pointer is still inside.
+  const effectiveHovered = hovered && enabled;
+
   const currentUnderlayOpacity = pressed
     ? activeUnderlayOpacity
-    : defaultUnderlayOpacity;
-  const hasUnderlay = underlayColor != null;
-  const hasOpacity = activeOpacity !== 1 || defaultOpacity !== 1;
-  const currentOpacity = pressed ? activeOpacity : defaultOpacity;
-  const hasScale = activeScale !== 1 || defaultScale !== 1;
-  const currentScale = pressed ? activeScale : defaultScale;
+    : effectiveHovered
+      ? hoverUnderlayOpacity
+      : defaultUnderlayOpacity;
+  const hasUnderlay = underlayColor != null && underlayColor !== 'transparent';
+  const hasOpacity =
+    activeOpacity !== 1 || hoverOpacity !== 1 || defaultOpacity !== 1;
+  const currentOpacity = pressed
+    ? activeOpacity
+    : effectiveHovered
+      ? hoverOpacity
+      : defaultOpacity;
+  const hasScale = activeScale !== 1 || hoverScale !== 1 || defaultScale !== 1;
+  const currentScale = pressed
+    ? activeScale
+    : effectiveHovered
+      ? hoverScale
+      : defaultScale;
 
   const easing = 'cubic-bezier(0.5, 1, 0.89, 1)';
   const transitionProps: string[] = [];
@@ -178,6 +245,7 @@ export const ButtonComponent = ({
 
   return (
     <View
+      {...rest}
       ref={setRef}
       accessibilityRole="button"
       style={[
@@ -191,11 +259,11 @@ export const ButtonComponent = ({
           ...(hasUnderlay && { overflow: 'hidden' }),
         },
       ]}
+      onPointerEnter={handlePointerEnter}
       onPointerDown={pressIn}
       onPointerUp={pressOut}
       onPointerCancel={pressOut}
-      onPointerLeave={pressOut}
-      {...rest}>
+      onPointerLeave={handlePointerLeave}>
       {hasUnderlay && (
         <View
           style={{

package/src/components/Pressable/Pressable.tsx

@@ -377,6 +377,7 @@ const LegacyPressable = (props: LegacyPressableProps) => {
     <GestureDetector gesture={gesture}>
       <NativeButton
         {...remainingProps}
+        needsOffscreenAlphaCompositing
         onLayout={setDimensions}
         accessible={accessible !== false}
         hitSlop={appliedHitSlop}

package/src/components/Pressable/PressableProps.tsx

@@ -32,7 +32,8 @@ export type InnerPressableEvent = {
 
 export type PressableEvent = { nativeEvent: InnerPressableEvent };
 
-export interface LegacyPressableProps extends CommonPressableProps {
+export interface LegacyPressableProps
+  extends Omit<CommonPressableProps, 'needsOffscreenAlphaCompositing'> {
   /**
    * A gesture object or an array of gesture objects containing the configuration and callbacks to be
    * used with the Pressable's gesture handlers.

package/src/components/ReanimatedDrawerLayout.tsx

@@ -44,6 +44,7 @@ import { MouseButton } from '../handlers/gestureHandlerCommon';
 import { GestureDetector } from '../v3/detectors';
 import type { PanGestureActiveEvent } from '../v3/hooks/gestures';
 import { usePanGesture, useTapGesture } from '../v3/hooks/gestures';
+import type { WithSharedValue } from '../v3/types';
 
 const DRAG_TOSS = 0.05;
 
@@ -75,7 +76,7 @@ export enum DrawerKeyboardDismissMode {
   ON_DRAG,
 }
 
-export interface DrawerLayoutProps {
+export type DrawerLayoutProps = {
   /**
    * This attribute is present in the native android implementation already and is one
    * of the required params. The gesture handler version of DrawerLayout makes it
@@ -193,14 +194,6 @@ export interface DrawerLayoutProps {
    */
   drawerContainerStyle?: StyleProp<ViewStyle>;
 
-  /**
-   * Enables two-finger gestures on supported devices, for example iPads with
-   * trackpads. If not enabled the gesture will require click + drag, with
-   * `enableTrackpadTwoFingerGesture` swiping with two fingers will also trigger
-   * the gesture.
-   */
-  enableTrackpadTwoFingerGesture?: boolean;
-
   onDrawerSlide?: (position: number) => void;
 
   // Implicit `children` prop has been removed in @types/react^18.0.
@@ -216,25 +209,36 @@ export interface DrawerLayoutProps {
    */
   userSelect?: UserSelect;
 
-  /**
-   * @default 'auto'
-   * Sets the displayed cursor pictogram when the drawer is being dragged.
-   * Values: see CSS cursor values
-   */
-  activeCursor?: ActiveCursor;
-
-  /**
-   * @default 'MouseButton.LEFT'
-   * Allows to choose which mouse button should underlying pan handler react to.
-   */
-  mouseButton?: MouseButton;
-
   /**
    * @default 'false if MouseButton.RIGHT is specified'
    * Allows to enable/disable context menu.
    */
   enableContextMenu?: boolean;
-}
+} & WithSharedValue<
+  {
+    /**
+     * Enables two-finger gestures on supported devices, for example iPads with
+     * trackpads. If not enabled the gesture will require click + drag, with
+     * `enableTrackpadTwoFingerGesture` swiping with two fingers will also trigger
+     * the gesture.
+     */
+    enableTrackpadTwoFingerGesture?: boolean;
+
+    /**
+     * @default 'auto'
+     * Sets the displayed cursor pictogram when the drawer is being dragged.
+     * Values: see CSS cursor values
+     */
+    activeCursor?: ActiveCursor;
+
+    /**
+     * @default 'MouseButton.LEFT'
+     * Allows to choose which mouse button should underlying pan handler react to.
+     */
+    mouseButton?: MouseButton;
+  },
+  ActiveCursor | MouseButton
+>;
 
 export type DrawerMovementOption = {
   initialVelocity?: number;

package/src/components/ReanimatedSwipeable/ReanimatedSwipeable.tsx

@@ -1,5 +1,10 @@
 import type { ForwardedRef } from 'react';
-import { useCallback, useImperativeHandle, useMemo } from 'react';
+import React, {
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+} from 'react';
 import type { LayoutChangeEvent } from 'react-native';
 import { I18nManager, StyleSheet, View } from 'react-native';
 import Animated, {
@@ -14,9 +19,16 @@ import Animated, {
   withSpring,
 } from 'react-native-reanimated';
 
+import { Reanimated } from '../../handlers/gestures/reanimatedWrapper';
+import { tagMessage } from '../../utils';
 import { GestureDetector } from '../../v3/detectors';
 import type { PanGestureActiveEvent } from '../../v3/hooks/gestures';
 import { usePanGesture, useTapGesture } from '../../v3/hooks/gestures';
+import {
+  maybeUnpackValue,
+  SHARED_VALUE_OFFSET,
+} from '../../v3/hooks/utils/reanimatedUtils';
+import type { SharedValueOrT } from '../../v3/types';
 import type {
   SwipeableMethods,
   SwipeableProps,
@@ -44,8 +56,8 @@ const Swipeable = (props: SwipeableProps) => {
     testID,
     children,
     enableTrackpadTwoFingerGesture = DEFAULT_ENABLE_TRACKING_TWO_FINGER_GESTURE,
-    dragOffsetFromLeftEdge = DEFAULT_DRAG_OFFSET,
-    dragOffsetFromRightEdge = DEFAULT_DRAG_OFFSET,
+    dragOffsetFromLeft = DEFAULT_DRAG_OFFSET,
+    dragOffsetFromRight = -DEFAULT_DRAG_OFFSET,
     friction = DEFAULT_FRICTION,
     overshootFriction = DEFAULT_OVERSHOOT_FRICTION,
     onSwipeableOpenStartDrag,
@@ -63,6 +75,40 @@ const Swipeable = (props: SwipeableProps) => {
     ...remainingProps
   } = props;
 
+  if (__DEV__) {
+    const checkValue = (value: SharedValueOrT<number>) => {
+      'worklet';
+      if (maybeUnpackValue<number>(value) > 0) {
+        throw new Error(
+          tagMessage('dragOffsetFromRight should be non-positive.')
+        );
+      }
+    };
+
+    checkValue(dragOffsetFromRight);
+
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    useEffect(() => {
+      if (!Reanimated?.isSharedValue<number>(dragOffsetFromRight)) {
+        return;
+      }
+
+      const listenerId = Math.random() + SHARED_VALUE_OFFSET;
+
+      Reanimated?.runOnUI(() => {
+        'worklet';
+        dragOffsetFromRight.addListener(listenerId, checkValue);
+      })();
+
+      return () => {
+        Reanimated?.runOnUI(() => {
+          'worklet';
+          dragOffsetFromRight.removeListener(listenerId);
+        })();
+      };
+    }, [dragOffsetFromRight, checkValue]);
+  }
+
   const shouldEnableTap = useSharedValue<boolean>(false);
   const rowState = useSharedValue<number>(0);
 
@@ -468,9 +514,9 @@ const Swipeable = (props: SwipeableProps) => {
   });
 
   const panGesture = usePanGesture({
-    enabled: enabled !== false,
+    enabled: enabled ?? true,
     enableTrackpadTwoFingerGesture: enableTrackpadTwoFingerGesture,
-    activeOffsetX: [-dragOffsetFromRightEdge, dragOffsetFromLeftEdge],
+    activeOffsetX: [dragOffsetFromRight, dragOffsetFromLeft],
     simultaneousWith,
     requireToFail,
     block,