react-native-gesture-handler 2.17.1 → 2.18.0

package/src/components/Pressable/Pressable.tsx

@@ -0,0 +1,398 @@
+import React, { useCallback, useMemo, useRef, useState } from 'react';
+import { GestureObjects as Gesture } from '../../handlers/gestures/gestureObjects';
+import { GestureDetector } from '../../handlers/gestures/GestureDetector';
+import { PressableEvent, PressableProps } from './PressableProps';
+import {
+  Insets,
+  Platform,
+  StyleProp,
+  View,
+  ViewStyle,
+  processColor,
+  StyleSheet,
+} from 'react-native';
+import NativeButton from '../GestureHandlerButton';
+import {
+  numberAsInset,
+  gestureToPressableEvent,
+  isTouchWithinInset,
+  gestureTouchToPressableEvent,
+  addInsets,
+  splitStyles,
+} from './utils';
+import { PressabilityDebugView } from '../../handlers/PressabilityDebugView';
+import { GestureTouchEvent } from '../../handlers/gestureHandlerCommon';
+
+const DEFAULT_LONG_PRESS_DURATION = 500;
+
+export default function Pressable(props: PressableProps) {
+  const [pressedState, setPressedState] = useState(
+    props.testOnly_pressed ?? false
+  );
+
+  const pressableRef = useRef<View>(null);
+
+  // Disabled when onLongPress has been called
+  const isPressCallbackEnabled = useRef<boolean>(true);
+  const hasPassedBoundsChecks = useRef<boolean>(false);
+  const shouldPreventNativeEffects = useRef<boolean>(false);
+
+  const normalizedHitSlop: Insets = useMemo(
+    () =>
+      typeof props.hitSlop === 'number'
+        ? numberAsInset(props.hitSlop)
+        : props.hitSlop ?? {},
+    [props.hitSlop]
+  );
+
+  const normalizedPressRetentionOffset: Insets = useMemo(
+    () =>
+      typeof props.pressRetentionOffset === 'number'
+        ? numberAsInset(props.pressRetentionOffset)
+        : props.pressRetentionOffset ?? {},
+    [props.pressRetentionOffset]
+  );
+
+  const hoverInTimeout = useRef<number | null>(null);
+  const hoverOutTimeout = useRef<number | null>(null);
+
+  const hoverGesture = useMemo(
+    () =>
+      Gesture.Hover()
+        .manualActivation(true) // Stops Hover from blocking Native gesture activation on web
+        .cancelsTouchesInView(false)
+        .onBegin((event) => {
+          if (hoverOutTimeout.current) {
+            clearTimeout(hoverOutTimeout.current);
+          }
+          if (props.delayHoverIn) {
+            hoverInTimeout.current = setTimeout(
+              () => props.onHoverIn?.(gestureToPressableEvent(event)),
+              props.delayHoverIn
+            );
+            return;
+          }
+          props.onHoverIn?.(gestureToPressableEvent(event));
+        })
+        .onFinalize((event) => {
+          if (hoverInTimeout.current) {
+            clearTimeout(hoverInTimeout.current);
+          }
+          if (props.delayHoverOut) {
+            hoverOutTimeout.current = setTimeout(
+              () => props.onHoverOut?.(gestureToPressableEvent(event)),
+              props.delayHoverOut
+            );
+            return;
+          }
+          props.onHoverOut?.(gestureToPressableEvent(event));
+        }),
+    [props]
+  );
+
+  const pressDelayTimeoutRef = useRef<number | null>(null);
+  const isTouchPropagationAllowed = useRef<boolean>(false);
+
+  // iOS only: due to varying flow of gestures, events sometimes have to be saved for later use
+  const deferredEventPayload = useRef<PressableEvent | null>(null);
+
+  const pressInHandler = useCallback(
+    (event: PressableEvent) => {
+      if (handlingOnTouchesDown.current) {
+        deferredEventPayload.current = event;
+      }
+
+      if (!isTouchPropagationAllowed.current) {
+        return;
+      }
+
+      deferredEventPayload.current = null;
+
+      props.onPressIn?.(event);
+      isPressCallbackEnabled.current = true;
+      pressDelayTimeoutRef.current = null;
+      setPressedState(true);
+    },
+    [props]
+  );
+
+  const pressOutHandler = useCallback(
+    (event: PressableEvent) => {
+      if (
+        !hasPassedBoundsChecks.current ||
+        event.nativeEvent.touches.length >
+          event.nativeEvent.changedTouches.length
+      ) {
+        return;
+      }
+
+      if (props.unstable_pressDelay && pressDelayTimeoutRef.current !== null) {
+        // When delay is preemptively finished by lifting touches,
+        // we want to immediately activate it's effects - pressInHandler,
+        // even though we are located at the pressOutHandler
+        clearTimeout(pressDelayTimeoutRef.current);
+        pressInHandler(event);
+      }
+
+      if (deferredEventPayload.current) {
+        props.onPressIn?.(deferredEventPayload.current);
+        deferredEventPayload.current = null;
+      }
+
+      props.onPressOut?.(event);
+
+      if (isPressCallbackEnabled.current) {
+        props.onPress?.(event);
+      }
+
+      if (longPressTimeoutRef.current) {
+        clearTimeout(longPressTimeoutRef.current);
+        longPressTimeoutRef.current = null;
+      }
+
+      isTouchPropagationAllowed.current = false;
+      hasPassedBoundsChecks.current = false;
+      isPressCallbackEnabled.current = true;
+      setPressedState(false);
+    },
+    [pressInHandler, props]
+  );
+
+  const handlingOnTouchesDown = useRef<boolean>(false);
+  const onEndHandlingTouchesDown = useRef<(() => void) | null>(null);
+  const cancelledMidPress = useRef<boolean>(false);
+
+  const activateLongPress = useCallback(
+    (event: GestureTouchEvent) => {
+      if (!isTouchPropagationAllowed.current) {
+        return;
+      }
+
+      if (hasPassedBoundsChecks.current) {
+        props.onLongPress?.(gestureTouchToPressableEvent(event));
+        isPressCallbackEnabled.current = false;
+      }
+
+      if (longPressTimeoutRef.current) {
+        clearTimeout(longPressTimeoutRef.current);
+        longPressTimeoutRef.current = null;
+      }
+    },
+    [props]
+  );
+
+  const longPressTimeoutRef = useRef<number | null>(null);
+  const longPressMinDuration =
+    (props.delayLongPress ?? DEFAULT_LONG_PRESS_DURATION) +
+    (props.unstable_pressDelay ?? 0);
+
+  const pressAndTouchGesture = useMemo(
+    () =>
+      Gesture.LongPress()
+        .minDuration(Number.MAX_SAFE_INTEGER) // Stops long press from blocking native gesture
+        .maxDistance(Number.MAX_SAFE_INTEGER) // Stops long press from cancelling after set distance
+        .cancelsTouchesInView(false)
+        .onTouchesDown((event) => {
+          handlingOnTouchesDown.current = true;
+          pressableRef.current?.measure((_x, _y, width, height) => {
+            if (
+              !isTouchWithinInset(
+                {
+                  width,
+                  height,
+                },
+                normalizedHitSlop,
+                event.changedTouches.at(-1)
+              ) ||
+              hasPassedBoundsChecks.current ||
+              cancelledMidPress.current
+            ) {
+              cancelledMidPress.current = false;
+              onEndHandlingTouchesDown.current = null;
+              handlingOnTouchesDown.current = false;
+              return;
+            }
+
+            hasPassedBoundsChecks.current = true;
+
+            // In case of multiple touches, the first one starts long press gesture
+            if (longPressTimeoutRef.current === null) {
+              // Start long press gesture timer
+              longPressTimeoutRef.current = setTimeout(
+                () => activateLongPress(event),
+                longPressMinDuration
+              );
+            }
+
+            if (props.unstable_pressDelay) {
+              pressDelayTimeoutRef.current = setTimeout(() => {
+                pressInHandler(gestureTouchToPressableEvent(event));
+              }, props.unstable_pressDelay);
+            } else {
+              pressInHandler(gestureTouchToPressableEvent(event));
+            }
+
+            onEndHandlingTouchesDown.current?.();
+            onEndHandlingTouchesDown.current = null;
+            handlingOnTouchesDown.current = false;
+          });
+        })
+        .onTouchesUp((event) => {
+          if (handlingOnTouchesDown.current) {
+            onEndHandlingTouchesDown.current = () =>
+              pressOutHandler(gestureTouchToPressableEvent(event));
+            return;
+          }
+          // On iOS, short taps will make LongPress gesture call onTouchesUp before Native gesture calls onStart
+          // This variable ensures that onStart isn't detected as the first gesture since Pressable is pressed.
+          if (deferredEventPayload.current !== null) {
+            shouldPreventNativeEffects.current = true;
+          }
+          pressOutHandler(gestureTouchToPressableEvent(event));
+        })
+        .onTouchesCancelled((event) => {
+          isPressCallbackEnabled.current = false;
+
+          if (handlingOnTouchesDown.current) {
+            cancelledMidPress.current = true;
+            onEndHandlingTouchesDown.current = () =>
+              pressOutHandler(gestureTouchToPressableEvent(event));
+            return;
+          }
+
+          if (
+            !hasPassedBoundsChecks.current ||
+            event.allTouches.length > event.changedTouches.length
+          ) {
+            return;
+          }
+
+          pressOutHandler(gestureTouchToPressableEvent(event));
+        }),
+    [
+      activateLongPress,
+      longPressMinDuration,
+      normalizedHitSlop,
+      pressInHandler,
+      pressOutHandler,
+      props.unstable_pressDelay,
+    ]
+  );
+
+  // RNButton is placed inside ButtonGesture to enable Android's ripple and to capture non-propagating events
+  const buttonGesture = useMemo(
+    () =>
+      Gesture.Native()
+        .onBegin(() => {
+          // Android sets BEGAN state on press down
+          if (Platform.OS === 'android') {
+            isTouchPropagationAllowed.current = true;
+          }
+        })
+        .onStart(() => {
+          if (Platform.OS === 'web') {
+            isTouchPropagationAllowed.current = true;
+          }
+
+          // iOS sets ACTIVE state on press down
+          if (Platform.OS !== 'ios') {
+            return;
+          }
+
+          if (deferredEventPayload.current) {
+            isTouchPropagationAllowed.current = true;
+
+            if (hasPassedBoundsChecks.current) {
+              pressInHandler(deferredEventPayload.current);
+              deferredEventPayload.current = null;
+            } else {
+              pressOutHandler(deferredEventPayload.current);
+              isTouchPropagationAllowed.current = false;
+            }
+
+            return;
+          }
+
+          if (hasPassedBoundsChecks.current) {
+            isTouchPropagationAllowed.current = true;
+            return;
+          }
+
+          if (shouldPreventNativeEffects.current) {
+            shouldPreventNativeEffects.current = false;
+            return;
+          }
+
+          isTouchPropagationAllowed.current = true;
+        }),
+    [pressInHandler, pressOutHandler]
+  );
+
+  const appliedHitSlop = addInsets(
+    normalizedHitSlop,
+    normalizedPressRetentionOffset
+  );
+
+  const isPressableEnabled = props.disabled !== true;
+
+  const gestures = [pressAndTouchGesture, hoverGesture, buttonGesture];
+
+  for (const gesture of gestures) {
+    gesture.enabled(isPressableEnabled);
+    gesture.runOnJS(true);
+    gesture.hitSlop(appliedHitSlop);
+    gesture.shouldCancelWhenOutside(false);
+
+    if (Platform.OS !== 'web') {
+      gesture.shouldCancelWhenOutside(true);
+    }
+  }
+
+  // Uses different hitSlop, to activate on hitSlop area instead of pressRetentionOffset area
+  buttonGesture.hitSlop(normalizedHitSlop);
+
+  const gesture = Gesture.Simultaneous(...gestures);
+
+  const defaultRippleColor = props.android_ripple ? undefined : 'transparent';
+
+  // `cursor: 'pointer'` on `RNButton` crashes iOS
+  const pointerStyle: StyleProp<ViewStyle> =
+    Platform.OS === 'web' ? { cursor: 'pointer' } : {};
+
+  const styleProp =
+    typeof props.style === 'function'
+      ? props.style({ pressed: pressedState })
+      : props.style;
+
+  const childrenProp =
+    typeof props.children === 'function'
+      ? props.children({ pressed: pressedState })
+      : props.children;
+
+  const flattenedStyles = StyleSheet.flatten(styleProp ?? {});
+
+  const [innerStyles, outerStyles] = splitStyles(flattenedStyles);
+
+  return (
+    <View style={outerStyles}>
+      <GestureDetector gesture={gesture}>
+        <NativeButton
+          ref={pressableRef}
+          testID={props.testID}
+          hitSlop={appliedHitSlop}
+          enabled={isPressableEnabled}
+          touchSoundDisabled={props.android_disableSound ?? undefined}
+          rippleColor={processColor(
+            props.android_ripple?.color ?? defaultRippleColor
+          )}
+          rippleRadius={props.android_ripple?.radius ?? undefined}
+          style={[StyleSheet.absoluteFill, pointerStyle, innerStyles]}>
+          {childrenProp}
+          {__DEV__ ? (
+            <PressabilityDebugView color="red" hitSlop={normalizedHitSlop} />
+          ) : null}
+        </NativeButton>
+      </GestureDetector>
+    </View>
+  );
+}

package/src/components/Pressable/PressableProps.tsx

@@ -0,0 +1,149 @@
+import {
+  ColorValue,
+  AccessibilityProps,
+  ViewProps,
+  Insets,
+  StyleProp,
+  ViewStyle,
+} from 'react-native';
+
+export interface PressableStateCallbackType {
+  readonly pressed: boolean;
+}
+
+export interface PressableAndroidRippleConfig {
+  color?: null | ColorValue | undefined;
+  borderless?: null | boolean | undefined;
+  radius?: null | number | undefined;
+  foreground?: null | boolean | undefined;
+}
+
+export type InnerPressableEvent = {
+  changedTouches: InnerPressableEvent[];
+  identifier: number;
+  locationX: number;
+  locationY: number;
+  pageX: number;
+  pageY: number;
+  target: number;
+  timestamp: number;
+  touches: InnerPressableEvent[];
+  force?: number;
+};
+
+export type PressableEvent = { nativeEvent: InnerPressableEvent };
+
+export interface PressableProps
+  extends AccessibilityProps,
+    Omit<ViewProps, 'children' | 'style' | 'hitSlop'> {
+  /**
+   * Called when the hover is activated to provide visual feedback.
+   */
+  onHoverIn?: null | ((event: PressableEvent) => void);
+
+  /**
+   * Called when the hover is deactivated to undo visual feedback.
+   */
+  onHoverOut?: null | ((event: PressableEvent) => void);
+
+  /**
+   * Called when a single tap gesture is detected.
+   */
+  onPress?: null | ((event: PressableEvent) => void);
+
+  /**
+   * Called when a touch is engaged before `onPress`.
+   */
+  onPressIn?: null | ((event: PressableEvent) => void);
+
+  /**
+   * Called when a touch is released before `onPress`.
+   */
+  onPressOut?: null | ((event: PressableEvent) => void);
+
+  /**
+   * Called when a long-tap gesture is detected.
+   */
+  onLongPress?: null | ((event: PressableEvent) => void);
+
+  /**
+   * Either children or a render prop that receives a boolean reflecting whether
+   * the component is currently pressed.
+   */
+  children?:
+    | React.ReactNode
+    | ((state: PressableStateCallbackType) => React.ReactNode);
+
+  /**
+   * Whether a press gesture can be interrupted by a parent gesture such as a
+   * scroll event. Defaults to true.
+   */
+  cancelable?: null | boolean;
+
+  /**
+   * Duration to wait after hover in before calling `onHoverIn`.
+   * @platform web macos
+   *
+   * NOTE: not present in RN docs
+   */
+  delayHoverIn?: number | null;
+
+  /**
+   * Duration to wait after hover out before calling `onHoverOut`.
+   * @platform web macos
+   *
+   * NOTE: not present in RN docs
+   */
+  delayHoverOut?: number | null;
+
+  /**
+   * Duration (in milliseconds) from `onPressIn` before `onLongPress` is called.
+   */
+  delayLongPress?: null | number;
+
+  /**
+   * Whether the press behavior is disabled.
+   */
+  disabled?: null | boolean;
+
+  /**
+   * Additional distance outside of this view in which a press is detected.
+   */
+  hitSlop?: null | Insets | number;
+
+  /**
+   * Additional distance outside of this view in which a touch is considered a
+   * press before `onPressOut` is triggered.
+   */
+  pressRetentionOffset?: null | Insets | number;
+
+  /**
+   * If true, doesn't play system sound on touch.
+   * @platform android
+   */
+  android_disableSound?: null | boolean;
+
+  /**
+   * Enables the Android ripple effect and configures its color.
+   * @platform android
+   */
+  android_ripple?: null | PressableAndroidRippleConfig;
+
+  /**
+   * Used only for documentation or testing (e.g. snapshot testing).
+   */
+  testOnly_pressed?: null | boolean;
+
+  /**
+   * Either view styles or a function that receives a boolean reflecting whether
+   * the component is currently pressed and returns view styles.
+   */
+  style?:
+    | StyleProp<ViewStyle>
+    | ((state: PressableStateCallbackType) => StyleProp<ViewStyle>);
+
+  /**
+   * Duration (in milliseconds) to wait after press down before calling onPressIn.
+   */
+  unstable_pressDelay?: number;
+}

package/src/components/Pressable/index.ts

@@ -0,0 +1,2 @@
+export { PressableProps } from './PressableProps';
+export { default } from './Pressable';