@amazon-devices/react-native-gesture-handler 2.0.9000000000 → 4.0.0-rn-83

package/src/components/Pressable/Pressable.tsx

@@ -0,0 +1,401 @@
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { GestureObjects as Gesture } from '../../handlers/gestures/gestureObjects';
+import { GestureDetector } from '../../handlers/gestures/GestureDetector';
+import {
+  PressableEvent,
+  PressableProps,
+  PressableDimensions,
+} from './PressableProps';
+import {
+  Insets,
+  LayoutChangeEvent,
+  Platform,
+  StyleProp,
+  ViewStyle,
+  processColor,
+} from 'react-native';
+import NativeButton from '../GestureHandlerButton';
+import {
+  gestureToPressableEvent,
+  addInsets,
+  numberAsInset,
+  gestureTouchToPressableEvent,
+  isTouchWithinInset,
+} from './utils';
+import { PressabilityDebugView } from '../../handlers/PressabilityDebugView';
+import { INT32_MAX, isFabric, isTestEnv } from '../../utils';
+import {
+  applyRelationProp,
+  RelationPropName,
+  RelationPropType,
+} from '../utils';
+import { getStatesConfig, StateMachineEvent } from './stateDefinitions';
+import { PressableStateMachine } from './StateMachine';
+
+const DEFAULT_LONG_PRESS_DURATION = 500;
+const IS_TEST_ENV = isTestEnv();
+
+let IS_FABRIC: null | boolean = null;
+
+const Pressable = (props: PressableProps) => {
+  const {
+    testOnly_pressed,
+    hitSlop,
+    pressRetentionOffset,
+    delayHoverIn,
+    delayHoverOut,
+    delayLongPress,
+    unstable_pressDelay,
+    onHoverIn,
+    onHoverOut,
+    onPress,
+    onPressIn,
+    onPressOut,
+    onLongPress,
+    onLayout,
+    style,
+    children,
+    android_disableSound,
+    android_ripple,
+    disabled,
+    accessible,
+    simultaneousWithExternalGesture,
+    requireExternalGestureToFail,
+    blocksExternalGesture,
+    ...remainingProps
+  } = props;
+
+  const relationProps = {
+    simultaneousWithExternalGesture,
+    requireExternalGestureToFail,
+    blocksExternalGesture,
+  };
+
+  const [pressedState, setPressedState] = useState(testOnly_pressed ?? false);
+
+  const longPressTimeoutRef = useRef<number | null>(null);
+  const pressDelayTimeoutRef = useRef<number | null>(null);
+  const isOnPressAllowed = useRef<boolean>(true);
+  const isCurrentlyPressed = useRef<boolean>(false);
+  const dimensions = useRef<PressableDimensions>({ width: 0, height: 0 });
+
+  const normalizedHitSlop: Insets = useMemo(
+    () =>
+      typeof hitSlop === 'number' ? numberAsInset(hitSlop) : (hitSlop ?? {}),
+    [hitSlop]
+  );
+
+  const normalizedPressRetentionOffset: Insets = useMemo(
+    () =>
+      typeof pressRetentionOffset === 'number'
+        ? numberAsInset(pressRetentionOffset)
+        : (pressRetentionOffset ?? {}),
+    [pressRetentionOffset]
+  );
+
+  const appliedHitSlop = addInsets(
+    normalizedHitSlop,
+    normalizedPressRetentionOffset
+  );
+
+  const cancelLongPress = useCallback(() => {
+    if (longPressTimeoutRef.current) {
+      clearTimeout(longPressTimeoutRef.current);
+      longPressTimeoutRef.current = null;
+      isOnPressAllowed.current = true;
+    }
+  }, []);
+
+  const cancelDelayedPress = useCallback(() => {
+    if (pressDelayTimeoutRef.current) {
+      clearTimeout(pressDelayTimeoutRef.current);
+      pressDelayTimeoutRef.current = null;
+    }
+  }, []);
+
+  const startLongPress = useCallback(
+    (event: PressableEvent) => {
+      if (onLongPress) {
+        cancelLongPress();
+        longPressTimeoutRef.current = setTimeout(() => {
+          isOnPressAllowed.current = false;
+          onLongPress(event);
+        }, delayLongPress ?? DEFAULT_LONG_PRESS_DURATION);
+      }
+    },
+    [onLongPress, cancelLongPress, delayLongPress]
+  );
+
+  const innerHandlePressIn = useCallback(
+    (event: PressableEvent) => {
+      onPressIn?.(event);
+      startLongPress(event);
+      setPressedState(true);
+      if (pressDelayTimeoutRef.current) {
+        clearTimeout(pressDelayTimeoutRef.current);
+        pressDelayTimeoutRef.current = null;
+      }
+    },
+    [onPressIn, startLongPress]
+  );
+
+  const handleFinalize = useCallback(() => {
+    isCurrentlyPressed.current = false;
+    cancelLongPress();
+    cancelDelayedPress();
+    setPressedState(false);
+  }, [cancelDelayedPress, cancelLongPress]);
+
+  const handlePressIn = useCallback(
+    (event: PressableEvent) => {
+      if (
+        !isTouchWithinInset(
+          dimensions.current,
+          normalizedHitSlop,
+          event.nativeEvent.changedTouches.at(-1)
+        )
+      ) {
+        // Ignoring pressIn within pressRetentionOffset
+        return;
+      }
+
+      isCurrentlyPressed.current = true;
+      if (unstable_pressDelay) {
+        pressDelayTimeoutRef.current = setTimeout(() => {
+          innerHandlePressIn(event);
+        }, unstable_pressDelay);
+      } else {
+        innerHandlePressIn(event);
+      }
+    },
+    [innerHandlePressIn, normalizedHitSlop, unstable_pressDelay]
+  );
+
+  const handlePressOut = useCallback(
+    (event: PressableEvent, success: boolean = true) => {
+      if (!isCurrentlyPressed.current) {
+        // Some prop configurations may lead to handlePressOut being called mutliple times.
+        return;
+      }
+
+      isCurrentlyPressed.current = false;
+
+      if (pressDelayTimeoutRef.current) {
+        innerHandlePressIn(event);
+      }
+
+      onPressOut?.(event);
+
+      if (isOnPressAllowed.current && success) {
+        onPress?.(event);
+      }
+
+      handleFinalize();
+    },
+    [handleFinalize, innerHandlePressIn, onPress, onPressOut]
+  );
+
+  const stateMachine = useMemo(() => new PressableStateMachine(), []);
+
+  useEffect(() => {
+    const configuration = getStatesConfig(handlePressIn, handlePressOut);
+    stateMachine.setStates(configuration);
+  }, [handlePressIn, handlePressOut, stateMachine]);
+
+  const hoverInTimeout = useRef<number | null>(null);
+  const hoverOutTimeout = useRef<number | null>(null);
+
+  const hoverGesture = useMemo(
+    () =>
+      Gesture.Hover()
+        .manualActivation(true) // Prevents Hover blocking Gesture.Native() on web
+        .cancelsTouchesInView(false)
+        .onBegin((event) => {
+          if (hoverOutTimeout.current) {
+            clearTimeout(hoverOutTimeout.current);
+          }
+          if (delayHoverIn) {
+            hoverInTimeout.current = setTimeout(
+              () => onHoverIn?.(gestureToPressableEvent(event)),
+              delayHoverIn
+            );
+            return;
+          }
+          onHoverIn?.(gestureToPressableEvent(event));
+        })
+        .onFinalize((event) => {
+          if (hoverInTimeout.current) {
+            clearTimeout(hoverInTimeout.current);
+          }
+          if (delayHoverOut) {
+            hoverOutTimeout.current = setTimeout(
+              () => onHoverOut?.(gestureToPressableEvent(event)),
+              delayHoverOut
+            );
+            return;
+          }
+          onHoverOut?.(gestureToPressableEvent(event));
+        }),
+    [delayHoverIn, delayHoverOut, onHoverIn, onHoverOut]
+  );
+
+  const pressAndTouchGesture = useMemo(
+    () =>
+      Gesture.LongPress()
+        .minDuration(INT32_MAX) // Stops long press from blocking Gesture.Native()
+        .maxDistance(INT32_MAX) // Stops long press from cancelling on touch move
+        .cancelsTouchesInView(false)
+        .onTouchesDown((event) => {
+          const pressableEvent = gestureTouchToPressableEvent(event);
+          stateMachine.handleEvent(
+            StateMachineEvent.LONG_PRESS_TOUCHES_DOWN,
+            pressableEvent
+          );
+        })
+        .onTouchesUp(() => {
+          if (Platform.OS === 'android') {
+            // Prevents potential soft-locks
+            stateMachine.reset();
+            handleFinalize();
+          }
+        })
+        .onTouchesCancelled((event) => {
+          const pressableEvent = gestureTouchToPressableEvent(event);
+          stateMachine.reset();
+          handlePressOut(pressableEvent, false);
+        })
+        .onFinalize((_event, success) => {
+          if (Platform.OS === 'web') {
+            if (success) {
+              stateMachine.handleEvent(StateMachineEvent.FINALIZE);
+            } else {
+              stateMachine.handleEvent(StateMachineEvent.CANCEL);
+            }
+            handleFinalize();
+          }
+        }),
+    [stateMachine, handleFinalize, handlePressOut]
+  );
+
+  // RNButton is placed inside ButtonGesture to enable Android's ripple and to capture non-propagating events
+  const buttonGesture = useMemo(
+    () =>
+      Gesture.Native()
+        .onTouchesCancelled((event) => {
+          if (Platform.OS !== 'macos' && Platform.OS !== 'web') {
+            // On MacOS cancel occurs in middle of gesture
+            // On Web cancel occurs on mouse move, which is unwanted
+            const pressableEvent = gestureTouchToPressableEvent(event);
+            stateMachine.reset();
+            handlePressOut(pressableEvent, false);
+          }
+        })
+        .onBegin(() => {
+          stateMachine.handleEvent(StateMachineEvent.NATIVE_BEGIN);
+        })
+        .onStart(() => {
+          if (Platform.OS !== 'android') {
+            // Gesture.Native().onStart() is broken with Android + hitSlop
+            stateMachine.handleEvent(StateMachineEvent.NATIVE_START);
+          }
+        })
+        .onFinalize((_event, success) => {
+          if (Platform.OS !== 'web') {
+            // On Web we use LongPress().onFinalize() instead of Native().onFinalize(),
+            // as Native cancels on mouse move, and LongPress does not.
+            if (success) {
+              stateMachine.handleEvent(StateMachineEvent.FINALIZE);
+            } else {
+              stateMachine.handleEvent(StateMachineEvent.CANCEL);
+            }
+            handleFinalize();
+          }
+        }),
+    [stateMachine, handlePressOut, handleFinalize]
+  );
+
+  const isPressableEnabled = disabled !== true;
+
+  const gestures = [buttonGesture, pressAndTouchGesture, hoverGesture];
+
+  for (const gesture of gestures) {
+    gesture.enabled(isPressableEnabled);
+    gesture.runOnJS(true);
+    gesture.hitSlop(appliedHitSlop);
+    gesture.shouldCancelWhenOutside(Platform.OS !== 'web');
+
+    Object.entries(relationProps).forEach(([relationName, relation]) => {
+      applyRelationProp(
+        gesture,
+        relationName as RelationPropName,
+        relation as RelationPropType
+      );
+    });
+  }
+
+  const gesture = Gesture.Simultaneous(...gestures);
+
+  // `cursor: 'pointer'` on `RNButton` crashes iOS
+  const pointerStyle: StyleProp<ViewStyle> =
+    Platform.OS === 'web' ? { cursor: 'pointer' } : {};
+
+  const styleProp =
+    typeof style === 'function' ? style({ pressed: pressedState }) : style;
+
+  const childrenProp =
+    typeof children === 'function'
+      ? children({ pressed: pressedState })
+      : children;
+
+  const rippleColor = useMemo(() => {
+    if (IS_FABRIC === null) {
+      IS_FABRIC = isFabric();
+    }
+
+    const defaultRippleColor = android_ripple ? undefined : 'transparent';
+    const unprocessedRippleColor = android_ripple?.color ?? defaultRippleColor;
+    return IS_FABRIC
+      ? unprocessedRippleColor
+      : processColor(unprocessedRippleColor);
+  }, [android_ripple]);
+
+  const setDimensions = useCallback(
+    (event: LayoutChangeEvent) => {
+      onLayout?.(event);
+      dimensions.current = event.nativeEvent.layout;
+    },
+    [onLayout]
+  );
+
+  return (
+    <GestureDetector gesture={gesture}>
+      <NativeButton
+        {...remainingProps}
+        onLayout={setDimensions}
+        accessible={accessible !== false}
+        hitSlop={appliedHitSlop}
+        enabled={isPressableEnabled}
+        touchSoundDisabled={android_disableSound ?? undefined}
+        rippleColor={rippleColor}
+        rippleRadius={android_ripple?.radius ?? undefined}
+        style={[pointerStyle, styleProp]}
+        testOnly_onPress={IS_TEST_ENV ? onPress : undefined}
+        testOnly_onPressIn={IS_TEST_ENV ? onPressIn : undefined}
+        testOnly_onPressOut={IS_TEST_ENV ? onPressOut : undefined}
+        testOnly_onLongPress={IS_TEST_ENV ? onLongPress : undefined}>
+        {childrenProp}
+        {__DEV__ ? (
+          <PressabilityDebugView color="red" hitSlop={normalizedHitSlop} />
+        ) : null}
+      </NativeButton>
+    </GestureDetector>
+  );
+};
+
+export default Pressable;

package/src/components/Pressable/PressableProps.tsx

@@ -0,0 +1,174 @@
+import {
+  AccessibilityProps,
+  ViewProps,
+  Insets,
+  StyleProp,
+  ViewStyle,
+  PressableStateCallbackType as RNPressableStateCallbackType,
+  PressableAndroidRippleConfig as RNPressableAndroidRippleConfig,
+  View,
+} from 'react-native';
+import { RelationPropType } from '../utils';
+
+export type PressableDimensions = { width: number; height: number };
+
+export type PressableStateCallbackType = RNPressableStateCallbackType;
+export type PressableAndroidRippleConfig = RNPressableAndroidRippleConfig;
+
+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);
+
+  /**
+   * A reference to the pressable element.
+   */
+  ref?: React.Ref<View>;
+
+  /**
+   * 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;
+
+  /**
+   * A gesture object or an array of gesture objects containing the configuration and callbacks to be
+   * used with the Pressable's gesture handlers.
+   */
+  simultaneousWithExternalGesture?: RelationPropType;
+
+  /**
+   * A gesture object or an array of gesture objects containing the configuration and callbacks to be
+   * used with the Pressable's gesture handlers.
+   */
+  requireExternalGestureToFail?: RelationPropType;
+
+  /**
+   * A gesture object or an array of gesture objects containing the configuration and callbacks to be
+   * used with the Pressable's gesture handlers.
+   */
+  blocksExternalGesture?: RelationPropType;
+
+  /**
+   * @deprecated This property is no longer used, and will be removed in the future.
+   */
+  dimensionsAfterResize?: PressableDimensions;
+}

package/src/components/Pressable/StateMachine.tsx

@@ -0,0 +1,57 @@
+import { PressableEvent } from './PressableProps';
+
+export interface StateDefinition {
+  eventName: string;
+  callback?: (event: PressableEvent) => void;
+}
+
+class PressableStateMachine {
+  private states: StateDefinition[] | null;
+  private currentStepIndex: number;
+  private eventPayload: PressableEvent | null;
+
+  constructor() {
+    this.states = null;
+    this.currentStepIndex = 0;
+    this.eventPayload = null;
+  }
+
+  public setStates(states: StateDefinition[]) {
+    this.states = states;
+  }
+
+  public reset() {
+    this.currentStepIndex = 0;
+    this.eventPayload = null;
+  }
+
+  public handleEvent(eventName: string, eventPayload?: PressableEvent) {
+    if (!this.states) {
+      return;
+    }
+
+    const step = this.states[this.currentStepIndex];
+    this.eventPayload = eventPayload || this.eventPayload;
+
+    if (step.eventName !== eventName) {
+      if (this.currentStepIndex > 0) {
+        // retry with position at index 0
+        this.reset();
+        this.handleEvent(eventName, eventPayload);
+      }
+      return;
+    }
+
+    if (this.eventPayload && step.callback) {
+      step.callback(this.eventPayload);
+    }
+
+    this.currentStepIndex++;
+
+    if (this.currentStepIndex === this.states.length) {
+      this.reset();
+    }
+  }
+}
+
+export { PressableStateMachine };

package/src/components/Pressable/index.ts

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