fix(react-motion): improve element validation to work with React 19 (#34164)

Author: layershifter

change/@fluentui-react-motion-2fb518da-d51e-44ae-be2e-ad538c2ef007.json

@@ -0,0 +1,7 @@
+{
+  "type": "patch",
+  "comment": "fix: improve element validation to work with React 19",
+  "packageName": "@fluentui/react-motion",
+  "email": "olfedias@microsoft.com",
+  "dependentChangeType": "patch"
+}

packages/react-components/react-motion/library/package.json

@@ -27,8 +27,7 @@
   "dependencies": {
     "@fluentui/react-shared-contexts": "^9.23.1",
     "@fluentui/react-utilities": "^9.18.23",
-    "@swc/helpers": "^0.5.1",
-    "react-is": "^17.0.2"
+    "@swc/helpers": "^0.5.1"
   },
   "peerDependencies": {
     "@types/react": ">=16.8.0 <19.0.0",

packages/react-components/react-motion/library/src/factories/createMotionComponent.ts

@@ -1,10 +1,10 @@
-import { useEventCallback, useIsomorphicLayoutEffect, useMergedRefs } from '@fluentui/react-utilities';
+import { useEventCallback, useIsomorphicLayoutEffect } from '@fluentui/react-utilities';
 import * as React from 'react';
 
 import { useAnimateAtoms } from '../hooks/useAnimateAtoms';
 import { useMotionImperativeRef } from '../hooks/useMotionImperativeRef';
 import { useIsReducedMotion } from '../hooks/useIsReducedMotion';
-import { getChildElement } from '../utils/getChildElement';
+import { useChildElement } from '../utils/useChildElement';
 import type { AtomMotion, AtomMotionFn, MotionParam, MotionImperativeRef } from '../types';
 import { useMotionBehaviourContext } from '../contexts/MotionBehaviourContext';
 
@@ -63,10 +63,9 @@ export function createMotionComponent<MotionParams extends Record<string, Motion
       ..._rest
     } = props;
     const params = _rest as Exclude<typeof props, MotionComponentProps>;
-    const child = getChildElement(children);
+    const [child, childRef] = useChildElement(children);
 
     const handleRef = useMotionImperativeRef(imperativeRef);
-    const elementRef = React.useRef<HTMLElement>();
     const skipMotions = useMotionBehaviourContext() === 'skip';
     const optionsRef = React.useRef<{ skipMotions: boolean; params: MotionParams }>({
       skipMotions,
@@ -95,7 +94,7 @@ export function createMotionComponent<MotionParams extends Record<string, Motion
     });
 
     useIsomorphicLayoutEffect(() => {
-      const element = elementRef.current;
+      const element = childRef.current;
 
       if (element) {
         const atoms = typeof value === 'function' ? value({ element, ...optionsRef.current.params }) : value;
@@ -113,9 +112,9 @@ export function createMotionComponent<MotionParams extends Record<string, Motion
           handle.cancel();
         };
       }
-    }, [animateAtoms, handleRef, isReducedMotion, onMotionFinish, onMotionStart, onMotionCancel]);
+    }, [animateAtoms, childRef, handleRef, isReducedMotion, onMotionFinish, onMotionStart, onMotionCancel]);
 
-    return React.cloneElement(children, { ref: useMergedRefs(elementRef, child.ref) });
+    return child;
   };
 
   return Atom;

packages/react-components/react-motion/library/src/factories/createPresenceComponent.ts

@@ -1,12 +1,12 @@
-import { useEventCallback, useFirstMount, useIsomorphicLayoutEffect, useMergedRefs } from '@fluentui/react-utilities';
+import { useEventCallback, useFirstMount, useIsomorphicLayoutEffect } from '@fluentui/react-utilities';
 import * as React from 'react';
 
 import { PresenceGroupChildContext } from '../contexts/PresenceGroupChildContext';
 import { useAnimateAtoms } from '../hooks/useAnimateAtoms';
 import { useMotionImperativeRef } from '../hooks/useMotionImperativeRef';
 import { useMountedState } from '../hooks/useMountedState';
 import { useIsReducedMotion } from '../hooks/useIsReducedMotion';
-import { getChildElement } from '../utils/getChildElement';
+import { useChildElement } from '../utils/useChildElement';
 import type {
   MotionParam,
   PresenceMotion,
@@ -107,11 +107,9 @@ export function createPresenceComponent<MotionParams extends Record<string, Moti
       const params = _rest as Exclude<typeof merged, PresenceComponentProps | typeof itemContext>;
 
       const [mounted, setMounted] = useMountedState(visible, unmountOnExit);
-      const child = getChildElement(children);
+      const [child, childRef] = useChildElement(children, mounted);
 
       const handleRef = useMotionImperativeRef(imperativeRef);
-      const elementRef = React.useRef<HTMLElement>();
-      const ref = useMergedRefs(elementRef, child.ref);
       const optionsRef = React.useRef<{ appear?: boolean; params: MotionParams; skipMotions: boolean }>({
         appear,
         params,
@@ -146,7 +144,7 @@ export function createPresenceComponent<MotionParams extends Record<string, Moti
 
       useIsomorphicLayoutEffect(
         () => {
-          const element = elementRef.current;
+          const element = childRef.current;
 
           if (!element) {
             return;
@@ -223,11 +221,20 @@ export function createPresenceComponent<MotionParams extends Record<string, Moti
         },
         // Excluding `isFirstMount` from deps to prevent re-triggering the animation on subsequent renders
         // eslint-disable-next-line react-hooks/exhaustive-deps
-        [animateAtoms, handleRef, isReducedMotion, handleMotionFinish, handleMotionStart, handleMotionCancel, visible],
+        [
+          animateAtoms,
+          childRef,
+          handleRef,
+          isReducedMotion,
+          handleMotionFinish,
+          handleMotionStart,
+          handleMotionCancel,
+          visible,
+        ],
       );
 
       if (mounted) {
-        return React.cloneElement(child, { ref });
+        return child;
       }
 
       return null;

packages/react-components/react-motion/library/src/utils/getChildElement.test.tsx

@@ -0,0 +1,83 @@
+import { render } from '@testing-library/react';
+import { renderHook } from '@testing-library/react-hooks';
+import * as React from 'react';
+
+import { useChildElement } from './useChildElement';
+
+const TestComponent: React.FC<{ children: React.ReactElement }> = ({ children }) => {
+  const [child] = useChildElement(children);
+
+  return child;
+};
+
+describe('useChildElement', () => {
+  let consoleErrorSpy: jest.SpyInstance;
+
+  beforeAll(() => {
+    // Silence React errors, we capture errors in the tests
+    consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {
+      /* empty */
+    });
+  });
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it('should return the child element and a ref to it', () => {
+    const { result } = renderHook(() => useChildElement(<div />));
+
+    expect(result.current[0].type).toBe('div');
+    expect(result.current[1]).toMatchObject({ current: null });
+  });
+
+  it('should not log errors if a ref was assigned to the child', () => {
+    const ComponentWithRef = React.forwardRef<HTMLDivElement>((props, ref) => <div ref={ref} {...props} />);
+
+    render(
+      <TestComponent>
+        <ComponentWithRef />
+      </TestComponent>,
+    );
+
+    expect(consoleErrorSpy).not.toHaveBeenCalled();
+  });
+
+  it('should throw an error if no child is passed', () => {
+    expect(() => render(<TestComponent children={undefined as unknown as React.ReactElement} />))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "@fluentui/react-motion: Invalid child element.
+      Motion factories require a single child element to be passed. That element element should support ref forwarding i.e. it should be either an intrinsic element (e.g. div) or a component that uses React.forwardRef()."
+    `);
+    expect(() => render(<TestComponent children={null as unknown as React.ReactElement} />))
+      .toThrowErrorMatchingInlineSnapshot(`
+      "@fluentui/react-motion: Invalid child element.
+      Motion factories require a single child element to be passed. That element element should support ref forwarding i.e. it should be either an intrinsic element (e.g. div) or a component that uses React.forwardRef()."
+    `);
+  });
+
+  it('should throw an error if multiple children are passed', () => {
+    expect(() =>
+      render(<TestComponent children={[<div key="1" />, <div key="2" />] as unknown as React.ReactElement} />),
+    ).toThrowErrorMatchingInlineSnapshot(`
+      "@fluentui/react-motion: Invalid child element.
+      Motion factories require a single child element to be passed. That element element should support ref forwarding i.e. it should be either an intrinsic element (e.g. div) or a component that uses React.forwardRef()."
+    `);
+  });
+
+  it('should log an error if the child does not support ref forwarding', () => {
+    const NonForwardingRefComponent: React.FC = () => {
+      return null;
+    };
+
+    render(
+      <TestComponent>
+        <NonForwardingRefComponent />
+      </TestComponent>,
+    );
+
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.stringContaining('@fluentui/react-motion: Invalid child element.'),
+    );
+  });
+});

packages/react-components/react-motion/library/src/utils/getChildElement.ts

@@ -0,0 +1,60 @@
+import * as React from 'react';
+import { useMergedRefs } from '@fluentui/react-utilities';
+
+const IS_REACT_19 = React.version.startsWith('19.');
+const CHILD_ERROR_MESSAGE = [
+  '@fluentui/react-motion: Invalid child element.',
+  '\n',
+  'Motion factories require a single child element to be passed. ',
+  'That element element should support ref forwarding i.e. it should be either an intrinsic element (e.g. div) or a component that uses React.forwardRef().',
+].join('');
+
+/**
+ * A backwards-compatible way to get the ref from a React element without console errors.
+ */
+function getRefFromReactElement<T>(element: React.ReactElement): React.Ref<T> | undefined {
+  if (IS_REACT_19) {
+    return element.props.ref;
+  }
+
+  return (element as React.ReactElement & { ref: React.Ref<T> | undefined }).ref;
+}
+
+/**
+ * Validates the child and returns a cloned child element with a ref.
+ *
+ * Throws an error if the child is not a valid React element, similar to "React.Children.only".
+ * Logs a warning in development mode if the ref is not set as the component remains functional.
+ */
+export function useChildElement(
+  children: React.ReactElement,
+  mounted: boolean = true,
+): [React.ReactElement, React.RefObject<HTMLElement>] {
+  const childRef = React.useRef<HTMLElement>(null);
+
+  React.useEffect(() => {
+    if (process.env.NODE_ENV !== 'production') {
+      if (mounted && !childRef.current) {
+        // eslint-disable-next-line no-console
+        console.error(CHILD_ERROR_MESSAGE);
+      }
+    }
+  }, [mounted]);
+
+  try {
+    const child = React.Children.only(children) as Parameters<typeof React.isValidElement>[0];
+
+    if (React.isValidElement(child)) {
+      return [
+        React.cloneElement(child as React.ReactElement<{ ref: React.Ref<HTMLElement> }>, {
+          ref: useMergedRefs(childRef, getRefFromReactElement(child)),
+        }),
+        childRef,
+      ];
+    }
+  } catch {
+    /* empty */
+  }
+
+  throw new Error(CHILD_ERROR_MESSAGE);
+}