fix: compose existing child refs in CSSMotion

src/CSSMotion.tsx

@@ -1,6 +1,10 @@
 /* eslint-disable react/default-props-match-prop-types, react/no-multi-comp, react/prop-types */
 import { getDOM } from '@rc-component/util/lib/Dom/findDOMNode';
-import { getNodeRef, supportRef } from '@rc-component/util/lib/ref';
+import {
+  getNodeRef,
+  supportRef,
+  useComposeRef,
+} from '@rc-component/util/lib/ref';
 import { clsx } from 'clsx';
 import * as React from 'react';
 import { useRef } from 'react';
@@ -189,7 +193,7 @@ export function genCSSMotion(config: CSSMotionConfig) {
       }
 
       // We should render children when motionStyle is sync with stepStatus
-      return React.useMemo(() => {
+      const motionChildren = React.useMemo(() => {
         if (styleReady === 'NONE') {
           return null;
         }
@@ -246,25 +250,27 @@ export function genCSSMotion(config: CSSMotionConfig) {
           );
         }
 
-        // Auto inject ref if child node not have `ref` props
-        if (
-          React.isValidElement(motionChildren) &&
-          supportRef(motionChildren)
-        ) {
-          const originNodeRef = getNodeRef(motionChildren);
-
-          if (!originNodeRef) {
-            motionChildren = React.cloneElement(
-              motionChildren as React.ReactElement,
-              {
-                ref: nodeRef,
-              },
-            );
-          }
-        }
-
         return motionChildren;
       }, [idRef.current]) as React.ReactElement;
+
+      const canHoldRef =
+        React.isValidElement(motionChildren) && supportRef(motionChildren);
+      const originNodeRef = canHoldRef ? getNodeRef(motionChildren) : null;
+      const shouldInjectRef = canHoldRef && originNodeRef !== nodeRef;
+      const mergedNodeRef = useComposeRef(
+        shouldInjectRef ? originNodeRef : null,
+        nodeRef,
+      );
+
+      // Preserve original behavior when child already uses motion's ref directly.
+      // Only compose refs when child owns another ref or misses the motion ref.
+      if (shouldInjectRef) {
+        return React.cloneElement(motionChildren, {
+          ref: mergedNodeRef,
+        });
+      }
+
+      return motionChildren;
     },
   );
 

tests/CSSMotion.spec.tsx

@@ -942,6 +942,51 @@ describe('CSSMotion', () => {
 
       expect(ReactDOM.findDOMNode).not.toHaveBeenCalled();
     });
+
+    it('supports existing child refs for motion end', () => {
+      const motionRef = React.createRef<CSSMotionRef>();
+      const childRef = React.createRef<HTMLDivElement>();
+
+      const Demo = ({ visible }: { visible: boolean }) => (
+        <CSSMotion
+          motionName="transition"
+          motionAppear={false}
+          visible={visible}
+          ref={motionRef}
+        >
+          {({ style, className }) => (
+            <div
+              ref={childRef}
+              style={style}
+              className={clsx('motion-box', className)}
+            />
+          )}
+        </CSSMotion>
+      );
+
+      const { container, rerender } = render(<Demo visible />);
+
+      act(() => {
+        jest.runAllTimers();
+      });
+
+      expect(motionRef.current.nativeElement).toBe(childRef.current);
+
+      rerender(<Demo visible={false} />);
+
+      act(() => {
+        jest.runAllTimers();
+      });
+
+      fireEvent.transitionEnd(childRef.current!);
+
+      act(() => {
+        jest.runAllTimers();
+      });
+
+      expect(container.querySelector('.motion-box')).toBeFalsy();
+      expect(ReactDOM.findDOMNode).not.toHaveBeenCalled();
+    });
   });
 
   describe('onVisibleChanged', () => {