Expose animatable refs for v3 touchables

Author: sorinc03

packages/react-native-gesture-handler/src/__tests__/api_v3.test.tsx

@@ -1,13 +1,18 @@
 import { render, renderHook } from '@testing-library/react-native';
-import { act } from 'react';
+import { act, createRef } from 'react';
+import type { View } from 'react-native';
 
 import GestureHandlerRootView from '../components/GestureHandlerRootView';
 import { fireGestureHandler, getByGestureTestId } from '../jestUtils';
 import { State } from '../State';
-import { RectButton, Touchable } from '../v3/components';
+import { Pressable, RectButton, Touchable } from '../v3/components';
 import { usePanGesture } from '../v3/hooks/gestures';
 import type { SingleGesture } from '../v3/types';
 
+type AnimatableViewRef = View & {
+  getAnimatableRef?: () => View | null;
+};
+
 describe('[API v3] Hooks', () => {
   test('Pan gesture', () => {
     const onBegin = jest.fn();
@@ -34,6 +39,51 @@ describe('[API v3] Hooks', () => {
 });
 
 describe('[API v3] Components', () => {
+  test('Pressable exposes the native button as an animatable ref', () => {
+    const ref = createRef<AnimatableViewRef>();
+
+    render(
+      <GestureHandlerRootView>
+        <Pressable ref={ref} />
+      </GestureHandlerRootView>
+    );
+
+    expect(ref.current?.getAnimatableRef?.()).toBe(ref.current);
+  });
+
+  test('Pressable forwards function refs on mount and unmount', () => {
+    const ref = jest.fn();
+
+    const { unmount } = render(
+      <GestureHandlerRootView>
+        <Pressable ref={ref} />
+      </GestureHandlerRootView>
+    );
+
+    expect(ref).toHaveBeenCalledWith(expect.anything());
+
+    unmount();
+
+    expect(ref).toHaveBeenLastCalledWith(null);
+  });
+
+  test('Pressable animatable refs stay bound to their host instance', () => {
+    const ref = createRef<AnimatableViewRef>();
+    const renderPressable = (key: string) => (
+      <GestureHandlerRootView>
+        <Pressable key={key} ref={ref} />
+      </GestureHandlerRootView>
+    );
+    const { rerender } = render(renderPressable('first'));
+    const firstRef = ref.current;
+
+    rerender(renderPressable('second'));
+    const secondRef = ref.current;
+
+    expect(firstRef?.getAnimatableRef?.()).toBe(firstRef);
+    expect(secondRef?.getAnimatableRef?.()).toBe(secondRef);
+  });
+
   test('Rect Button', () => {
     const pressFn = jest.fn();
 
@@ -61,6 +111,18 @@ describe('[API v3] Components', () => {
   });
 
   describe('Touchable', () => {
+    test('exposes the native button as an animatable ref', () => {
+      const ref = createRef<AnimatableViewRef>();
+
+      render(
+        <GestureHandlerRootView>
+          <Touchable ref={ref} />
+        </GestureHandlerRootView>
+      );
+
+      expect(ref.current?.getAnimatableRef?.()).toBe(ref.current);
+    });
+
     test('calls onPress on successful press', () => {
       const pressFn = jest.fn();
 

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

@@ -42,6 +42,7 @@ import {
   useNativeGesture,
   useSimultaneousGestures,
 } from '../hooks';
+import { setAndForwardAnimatableRef } from './animatableRef';
 import { PureNativeButton } from './GestureButtons';
 
 const DEFAULT_LONG_PRESS_DURATION = 500;
@@ -72,6 +73,7 @@ const Pressable = (props: PressableProps) => {
     simultaneousWith,
     requireToFail,
     block,
+    ref,
     ...remainingProps
   } = props;
 
@@ -81,10 +83,19 @@ const Pressable = (props: PressableProps) => {
   const pressDelayTimeoutRef = useRef<number | null>(null);
   const isOnPressAllowed = useRef<boolean>(true);
   const isCurrentlyPressed = useRef<boolean>(false);
+  const buttonRef = useRef<React.ComponentRef<typeof PureNativeButton> | null>(
+    null
+  );
   const dimensions = useRef<PressableDimensions>({
     width: 0,
     height: 0,
   });
+  const setButtonRef = useCallback(
+    (button: React.ComponentRef<typeof PureNativeButton> | null) => {
+      setAndForwardAnimatableRef(buttonRef, ref, button);
+    },
+    [ref]
+  );
 
   const normalizedHitSlop: Insets = useMemo(
     () =>
@@ -399,6 +410,7 @@ const Pressable = (props: PressableProps) => {
       <PureNativeButton
         {...remainingProps}
         {...tvProps}
+        ref={setButtonRef}
         onLayout={setDimensions}
         accessible={accessible !== false}
         hitSlop={appliedHitSlop}

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

@@ -5,6 +5,7 @@ import GestureHandlerButton from '../../../components/GestureHandlerButton';
 import { getTVProps } from '../../../components/utils';
 import { NativeDetector } from '../../detectors/NativeDetector';
 import { useNativeGesture } from '../../hooks';
+import { setAndForwardAnimatableRef } from '../animatableRef';
 import type {
   AnimationDuration,
   CallbackEventType,
@@ -100,6 +101,15 @@ export const Touchable = (props: TouchableProps) => {
   const longPressTimeout = useRef<ReturnType<typeof setTimeout> | undefined>(
     undefined
   );
+  const buttonRef = useRef<React.ComponentRef<
+    typeof GestureHandlerButton
+  > | null>(null);
+  const setButtonRef = useCallback(
+    (button: React.ComponentRef<typeof GestureHandlerButton> | null) => {
+      setAndForwardAnimatableRef(buttonRef, ref, button);
+    },
+    [ref]
+  );
 
   const wrappedLongPress = useCallback(() => {
     longPressDetected.current = true;
@@ -218,7 +228,7 @@ export const Touchable = (props: TouchableProps) => {
         {...tvProps}
         {...rippleProps}
         {...resolvedDurations}
-        ref={ref ?? null}
+        ref={setButtonRef}
         enabled={!disabled}
         defaultOpacity={defaultOpacity}
         defaultUnderlayOpacity={defaultUnderlayOpacity}

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

@@ -0,0 +1,24 @@
+import type React from 'react';
+
+type AnimatableRef<T> = T & {
+  getAnimatableRef?: () => T | null;
+};
+
+export function setAndForwardAnimatableRef<T extends object>(
+  localRef: React.MutableRefObject<T | null>,
+  forwardedRef: React.Ref<T> | undefined,
+  ref: T | null
+) {
+  localRef.current = ref;
+
+  const animatableRef = ref as AnimatableRef<T> | null;
+  if (animatableRef && !animatableRef.getAnimatableRef) {
+    animatableRef.getAnimatableRef = () => ref;
+  }
+
+  if (typeof forwardedRef === 'function') {
+    forwardedRef(ref);
+  } else if (forwardedRef) {
+    (forwardedRef as React.MutableRefObject<T | null>).current = ref;
+  }
+}