fix: Ensure ref callback cleanup executes on MuxPlayer unmount (#1132)

Fixes #1112 

## Changes
- Modified useCombinedRefs hook to collect cleanup functions returned by
the function refs and ensure they are called.
- Updated the toNativeProps utility to explicitly exclude the ref prop,
ensuring that React handles the ref mechanism directly.

Author: Pintorado

packages/mux-player-react/src/common/utils.ts

@@ -51,8 +51,9 @@ export const toNativeAttrValue = (propValue: any, _propName: string) => {
   return propValue;
 };
 
-export const toNativeProps = (props = {}) => {
-  return Object.entries(props).reduce<{ [k: string]: string }>((transformedProps, [propName, propValue]) => {
+export const toNativeProps = (props: { ref?: any; [key: string]: any } = {}) => {
+  const { ref, ...restProps } = props;
+  return Object.entries(restProps).reduce<{ [k: string]: string }>((transformedProps, [propName, propValue]) => {
     const attrName = toNativeAttrName(propName, propValue);
 
     // prop was stripped. Don't add.

packages/mux-player-react/src/index.tsx

@@ -15,7 +15,7 @@ import type MuxPlayerElement from '@mux/mux-player';
 import type { Tokens, MuxPlayerElementEventMap } from '@mux/mux-player';
 import { toNativeProps } from './common/utils';
 import { useRef } from 'react';
-import { useCombinedRefs } from './useCombinedRefs';
+import { useComposedRefs } from './useComposedRefs';
 import useObjectPropEffect, { defaultHasChanged } from './useObjectPropEffect';
 import { getPlayerVersion } from './env';
 
@@ -141,7 +141,8 @@ const MuxPlayerInternal = React.forwardRef<MuxPlayerRefAttributes, MuxPlayerProp
     'mux-player',
     {
       suppressHydrationWarning: true, // prevent issues with SSR / player-init-time
-      ...toNativeProps({ ...props, ref }),
+      ...toNativeProps(props),
+      ref,
     },
     children
   );
@@ -275,14 +276,14 @@ const MuxPlayer = React.forwardRef<
   Omit<MuxPlayerProps, 'playerSoftwareVersion' | 'playerSoftwareName'>
 >((props, ref) => {
   const innerPlayerRef = useRef<MuxPlayerElement>(null);
-  const playerRef = useCombinedRefs(innerPlayerRef, ref);
+  const playerRef = useComposedRefs(innerPlayerRef, ref);
   const [remainingProps] = usePlayer(innerPlayerRef, props);
   const [playerInitTime] = useState(props.playerInitTime ?? generatePlayerInitTime());
 
   return (
     <MuxPlayerInternal
       /** @TODO Fix types relationships (CJP) */
-      ref={playerRef as typeof innerPlayerRef}
+      ref={playerRef as React.Ref<MuxPlayerElement>}
       defaultHiddenCaptions={props.defaultHiddenCaptions}
       playerSoftwareName={playerSoftwareName}
       playerSoftwareVersion={playerSoftwareVersion}

packages/mux-player-react/src/useCombinedRefs.ts

@@ -0,0 +1,60 @@
+import * as React from 'react';
+
+type PossibleRef<T> = React.Ref<T> | undefined;
+
+/**
+ * Set a given ref to a given value
+ * This utility takes care of different types of refs: callback refs and RefObject(s)
+ */
+function setRef<T>(ref: PossibleRef<T>, value: T): (() => void) | void | undefined {
+  if (typeof ref === 'function') {
+    return ref(value);
+  } else if (ref !== null && ref !== undefined) {
+    (ref as React.MutableRefObject<T>).current = value;
+  }
+}
+
+/**
+ * A utility to compose multiple refs together
+ * Accepts callback refs and RefObject(s)
+ */
+function composeRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T> {
+  return (node) => {
+    let hasCleanup = false;
+    const cleanups = refs.map((ref) => {
+      const cleanup = setRef(ref, node);
+      if (!hasCleanup && typeof cleanup == 'function') {
+        hasCleanup = true;
+      }
+      return cleanup;
+    });
+
+    // React <19 will log an error to the console if a callback ref returns a
+    // value. We don't use ref cleanups internally so this will only happen if a
+    // user's ref callback returns a value, which we only expect if they are
+    // using the cleanup functionality added in React 19.
+    if (hasCleanup) {
+      return () => {
+        for (let i = 0; i < cleanups.length; i++) {
+          const cleanup = cleanups[i];
+          if (typeof cleanup == 'function') {
+            cleanup();
+          } else {
+            setRef(refs[i], null);
+          }
+        }
+      };
+    }
+  };
+}
+
+/**
+ * A custom hook that composes multiple refs
+ * Accepts callback refs and RefObject(s)
+ */
+function useComposedRefs<T>(...refs: PossibleRef<T>[]): React.RefCallback<T> {
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  return React.useCallback(composeRefs(...refs), refs);
+}
+
+export { composeRefs, useComposedRefs };