Expose animatable refs for v3 touchables

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

@@ -1,13 +1,19 @@
 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 { setAndForwardAnimatableRef } from '../v3/components/animatableRef';
 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();
@@ -16,8 +22,8 @@
     const panGesture = renderHook(() =>
       usePanGesture({
         disableReanimated: true,
         onBegin: (e) => onBegin(e),
         onActivate: (e) => onStart(e),
       })
     ).result.current;
 
@@ -34,6 +40,66 @@
 });
 
 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('setAndForwardAnimatableRef preserves an existing animatable ref', () => {
+    const localRef = createRef<AnimatableViewRef>();
+    const forwardedRef = createRef<AnimatableViewRef>();
+    const existingAnimatableRef = jest.fn();
+    const hostRef = {
+      getAnimatableRef: existingAnimatableRef,
+    } as unknown as AnimatableViewRef;
+
+    setAndForwardAnimatableRef(localRef, forwardedRef, hostRef);
+
+    expect(localRef.current).toBe(hostRef);
+    expect(forwardedRef.current).toBe(hostRef);
+    expect(hostRef.getAnimatableRef).toBe(existingAnimatableRef);
+  });
+
   test('Rect Button', () => {
     const pressFn = jest.fn();
 
@@ -61,6 +127,51 @@
   });
 
   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('forwards function refs on mount and unmount', () => {
+      const ref = jest.fn();
+
+      const { unmount } = render(
+        <GestureHandlerRootView>
+          <Touchable ref={ref} />
+        </GestureHandlerRootView>
+      );
+
+      expect(ref).toHaveBeenCalledWith(expect.anything());
+
+      unmount();
+
+      expect(ref).toHaveBeenLastCalledWith(null);
+    });
+
+    test('animatable refs stay bound to their host instance', () => {
+      const ref = createRef<AnimatableViewRef>();
+      const renderTouchable = (key: string) => (
+        <GestureHandlerRootView>
+          <Touchable key={key} ref={ref} />
+        </GestureHandlerRootView>
+      );
+      const { rerender } = render(renderTouchable('first'));
+      const firstRef = ref.current;
+
+      rerender(renderTouchable('second'));
+      const secondRef = ref.current;
+
+      expect(firstRef?.getAnimatableRef?.()).toBe(firstRef);
+      expect(secondRef?.getAnimatableRef?.()).toBe(secondRef);
+    });
+
     test('calls onPress on successful press', () => {
       const pressFn = jest.fn();
 
@@ -128,9 +239,9 @@
       render(<Example />);
 
       const gesture = getByGestureTestId('touchable') as SingleGesture<
         any,
         any,
         any
       >;
       const { jsEventHandler } = gesture.detectorCallbacks;
 

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;
+  }
+}