refactor: rewrite mergeRefs in typescript (#20404)

adamalston · web-flow · commit 149f0f23fe82 · 2025-09-15T21:16:29.000Z
diff --git a/packages/react/src/components/ComboBox/ComboBox.tsx b/packages/react/src/components/ComboBox/ComboBox.tsx
@@ -40,7 +40,7 @@ import ListBox, { ListBoxSizePropType, type ListBoxSize } from '../ListBox';
 import { ListBoxTrigger, ListBoxSelection } from '../ListBox/next';
 import { match, keys } from '../../internal/keyboard';
 import { useId } from '../../internal/useId';
-import mergeRefs from '../../tools/mergeRefs';
+import { mergeRefs } from '../../tools/mergeRefs';
 import { deprecate } from '../../prop-types/deprecate';
 import { usePrefix } from '../../internal/usePrefix';
 import { FormContext } from '../FluidForm';
diff --git a/packages/react/src/components/ComboButton/index.tsx b/packages/react/src/components/ComboButton/index.tsx
@@ -23,7 +23,7 @@ import {
   autoUpdate,
 } from '@floating-ui/react';
 import { useFeatureFlag } from '../FeatureFlags';
-import mergeRefs from '../../tools/mergeRefs';
+import { mergeRefs } from '../../tools/mergeRefs';
 import { MenuAlignment } from '../MenuButton';
 import { TranslateWithId } from '../../types/common';
 import { deprecateValuesWithin } from '../../prop-types/deprecateValuesWithin';
diff --git a/packages/react/src/components/ComposedModal/ComposedModal.tsx b/packages/react/src/components/ComposedModal/ComposedModal.tsx
@@ -26,7 +26,7 @@ import { ModalHeader, type ModalHeaderProps } from './ModalHeader';
 import { ModalFooter, type ModalFooterProps } from './ModalFooter';
 import { debounce } from 'es-toolkit/compat';
 import useIsomorphicEffect from '../../internal/useIsomorphicEffect';
-import mergeRefs from '../../tools/mergeRefs';
+import { mergeRefs } from '../../tools/mergeRefs';
 import cx from 'classnames';
 import { toggleClass } from '../../tools/toggleClass';
 import { requiredIfGivenPropIsTruthy } from '../../prop-types/requiredIfGivenPropIsTruthy';
diff --git a/packages/react/src/components/Dropdown/Dropdown.tsx b/packages/react/src/components/Dropdown/Dropdown.tsx
@@ -12,6 +12,7 @@ import React, {
   useContext,
   useEffect,
   useMemo,
+  useRef,
   useState,
   type FocusEvent,
   type ForwardedRef,
@@ -42,7 +43,7 @@ import ListBox, {
   type ListBoxSize,
   type ListBoxType,
 } from '../ListBox';
-import mergeRefs from '../../tools/mergeRefs';
+import { mergeRefs } from '../../tools/mergeRefs';
 import { deprecate } from '../../prop-types/deprecate';
 import { usePrefix } from '../../internal/usePrefix';
 import { FormContext } from '../FluidForm';
@@ -510,7 +511,12 @@ const Dropdown = React.forwardRef(
       setIsFocused(evt.type === 'focus' && !selectedItem ? true : false);
     };
 
-    const mergedRef = mergeRefs(toggleButtonProps.ref, ref);
+    const buttonRef = useRef<HTMLButtonElement>(null);
+    const mergedRef = mergeRefs<HTMLButtonElement>(
+      toggleButtonProps.ref,
+      ref,
+      buttonRef
+    );
 
     const [currTimer, setCurrTimer] = useState<NodeJS.Timeout>();
 
@@ -563,7 +569,7 @@ const Dropdown = React.forwardRef(
             // NOTE: does not prevent click
             evt.preventDefault();
             // focus on the element as per readonly input behavior
-            mergedRef?.current?.focus();
+            buttonRef.current?.focus();
           },
           onKeyDown: (evt: React.KeyboardEvent<HTMLButtonElement>) => {
             const selectAccessKeys = ['ArrowDown', 'ArrowUp', ' ', 'Enter'];
@@ -578,7 +584,6 @@ const Dropdown = React.forwardRef(
           onKeyDown: onKeyDownHandler,
         };
       }
-      // eslint-disable-next-line  react-hooks/exhaustive-deps -- https://github.com/carbon-design-system/carbon/issues/20071
     }, [readOnly, onKeyDownHandler]);
 
     const menuProps = useMemo(
diff --git a/packages/react/src/components/ExpandableSearch/ExpandableSearch.tsx b/packages/react/src/components/ExpandableSearch/ExpandableSearch.tsx
@@ -1,5 +1,5 @@
 /**
- * Copyright IBM Corp. 2021
+ * Copyright IBM Corp. 2021, 2025
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
@@ -11,7 +11,7 @@ import Search, { type SearchProps } from '../Search';
 import { usePrefix } from '../../internal/usePrefix';
 import { composeEventHandlers } from '../../tools/events';
 import { match, keys } from '../../internal/keyboard';
-import mergeRefs from '../../tools/mergeRefs';
+import { mergeRefs } from '../../tools/mergeRefs';
 
 const ExpandableSearch = React.forwardRef(function ExpandableSearch(
   {
diff --git a/packages/react/src/components/MenuButton/index.tsx b/packages/react/src/components/MenuButton/index.tsx
@@ -1,5 +1,5 @@
 /**
- * Copyright IBM Corp. 2023
+ * Copyright IBM Corp. 2023, 2025
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
@@ -29,7 +29,7 @@ import {
   autoUpdate,
 } from '@floating-ui/react';
 import { useFeatureFlag } from '../FeatureFlags';
-import mergeRefs from '../../tools/mergeRefs';
+import { mergeRefs } from '../../tools/mergeRefs';
 
 const validButtonKinds = ['primary', 'tertiary', 'ghost'];
 const defaultButtonKind = 'primary';
diff --git a/packages/react/src/components/MultiSelect/FilterableMultiSelect.tsx b/packages/react/src/components/MultiSelect/FilterableMultiSelect.tsx
@@ -50,7 +50,7 @@ import ListBox, {
 import Checkbox from '../Checkbox';
 import { ListBoxTrigger, ListBoxSelection } from '../ListBox/next';
 import { match, keys } from '../../internal/keyboard';
-import mergeRefs from '../../tools/mergeRefs';
+import { mergeRefs } from '../../tools/mergeRefs';
 import { deprecate } from '../../prop-types/deprecate';
 import { useId } from '../../internal/useId';
 import { defaultSortItems, defaultCompareItems } from './tools/sorting';
@@ -977,8 +977,8 @@ export const FilterableMultiSelect = forwardRef(function FilterableMultiSelect<
           // NOTE: does not prevent click
           evt.preventDefault();
           // focus on the element as per readonly input behavior
-          if (mergedRef.current !== undefined) {
-            mergedRef.current.focus();
+          if (textInput.current) {
+            textInput.current.focus();
           }
         },
         onKeyDown: (evt: React.KeyboardEvent<HTMLInputElement>) => {
diff --git a/packages/react/src/components/MultiSelect/MultiSelect.tsx b/packages/react/src/components/MultiSelect/MultiSelect.tsx
@@ -22,6 +22,7 @@ import React, {
   useContext,
   useLayoutEffect,
   useMemo,
+  useRef,
   useState,
   type ForwardedRef,
   type ReactNode,
@@ -40,7 +41,7 @@ import {
 import { defaultSortItems, defaultCompareItems } from './tools/sorting';
 import { useSelection } from '../../internal/Selection';
 import { useId } from '../../internal/useId';
-import mergeRefs from '../../tools/mergeRefs';
+import { mergeRefs } from '../../tools/mergeRefs';
 import { deprecate } from '../../prop-types/deprecate';
 import { keys, match } from '../../internal/keyboard';
 import { usePrefix } from '../../internal/usePrefix';
@@ -504,7 +505,12 @@ export const MultiSelect = React.forwardRef(
       },
     });
 
-    const mergedRef = mergeRefs(toggleButtonProps.ref, ref);
+    const toggleButtonRef = useRef<HTMLButtonElement>(null);
+    const mergedRef = mergeRefs<HTMLButtonElement>(
+      toggleButtonProps.ref,
+      ref,
+      toggleButtonRef
+    );
 
     const selectedItems = selectedItem as ItemType[];
 
@@ -670,8 +676,8 @@ export const MultiSelect = React.forwardRef(
             // NOTE: does not prevent click
             evt.preventDefault();
             // focus on the element as per readonly input behavior
-            if (mergedRef.current !== undefined) {
-              mergedRef.current.focus();
+            if (toggleButtonRef.current) {
+              toggleButtonRef.current.focus();
             }
           },
           onKeyDown: (evt: React.KeyboardEvent<HTMLButtonElement>) => {
diff --git a/packages/react/src/components/OverflowMenu/OverflowMenu.tsx b/packages/react/src/components/OverflowMenu/OverflowMenu.tsx
@@ -38,7 +38,7 @@ import { matches as keyCodeMatches, keys } from '../../internal/keyboard';
 import { noopFn } from '../../internal/noopFn';
 import { PrefixContext } from '../../internal/usePrefix';
 import { deprecate } from '../../prop-types/deprecate';
-import mergeRefs from '../../tools/mergeRefs';
+import { mergeRefs } from '../../tools/mergeRefs';
 import { setupGetInstanceId } from '../../tools/setupGetInstanceId';
 import { IconButton, IconButtonProps } from '../IconButton';
 import { OverflowMenuItemProps } from '../OverflowMenuItem/OverflowMenuItem';
diff --git a/packages/react/src/components/OverflowMenu/next/index.tsx b/packages/react/src/components/OverflowMenu/next/index.tsx
@@ -15,7 +15,7 @@ import { useFeatureFlag } from '../../FeatureFlags';
 import { IconButton } from '../../IconButton';
 import { Menu } from '../../Menu';
 import type { PopoverAlignment } from '../../Popover';
-import mergeRefs from '../../../tools/mergeRefs';
+import { mergeRefs } from '../../../tools/mergeRefs';
 
 import { useId } from '../../../internal/useId';
 import { usePrefix } from '../../../internal/usePrefix';
diff --git a/packages/react/src/components/RadioButton/RadioButton.tsx b/packages/react/src/components/RadioButton/RadioButton.tsx
@@ -12,7 +12,7 @@ import { Text } from '../Text';
 import { deprecate } from '../../prop-types/deprecate';
 import { usePrefix } from '../../internal/usePrefix';
 import { useId } from '../../internal/useId';
-import mergeRefs from '../../tools/mergeRefs';
+import { mergeRefs } from '../../tools/mergeRefs';
 import { AILabel } from '../AILabel';
 import { isComponentElement } from '../../internal';
 
diff --git a/packages/react/src/components/RadioButtonGroup/RadioButtonGroup.tsx b/packages/react/src/components/RadioButtonGroup/RadioButtonGroup.tsx
@@ -20,7 +20,7 @@ import { Legend } from '../Text/createTextComponent';
 import { usePrefix } from '../../internal/usePrefix';
 import { WarningFilled, WarningAltFilled } from '@carbon/icons-react';
 import { deprecate } from '../../prop-types/deprecate';
-import mergeRefs from '../../tools/mergeRefs';
+import { mergeRefs } from '../../tools/mergeRefs';
 import { useId } from '../../internal/useId';
 import { AILabel } from '../AILabel';
 import { isComponentElement } from '../../internal';
diff --git a/packages/react/src/components/Tag/DismissibleTag.tsx b/packages/react/src/components/Tag/DismissibleTag.tsx
@@ -25,7 +25,7 @@ import { Close } from '@carbon/icons-react';
 import { Tooltip } from '../Tooltip';
 import { Text } from '../Text';
 import { isEllipsisActive } from './isEllipsisActive';
-import mergeRefs from '../../tools/mergeRefs';
+import { mergeRefs } from '../../tools/mergeRefs';
 import { AILabel } from '../AILabel';
 import { isComponentElement } from '../../internal';
 import { PopoverAlignment } from '../Popover';
diff --git a/packages/react/src/components/Tag/OperationalTag.tsx b/packages/react/src/components/Tag/OperationalTag.tsx
@@ -22,7 +22,7 @@ import Tag, { SIZES } from './Tag';
 import { Tooltip } from '../Tooltip';
 import { Text } from '../Text';
 import { isEllipsisActive } from './isEllipsisActive';
-import mergeRefs from '../../tools/mergeRefs';
+import { mergeRefs } from '../../tools/mergeRefs';
 
 const TYPES = {
   red: 'Red',
diff --git a/packages/react/src/components/Tag/SelectableTag.tsx b/packages/react/src/components/Tag/SelectableTag.tsx
@@ -22,7 +22,7 @@ import Tag, { SIZES } from './Tag';
 import { Tooltip } from '../Tooltip';
 import { Text } from '../Text';
 import { isEllipsisActive } from './isEllipsisActive';
-import mergeRefs from '../../tools/mergeRefs';
+import { mergeRefs } from '../../tools/mergeRefs';
 import { useControllableState } from '../../internal/useControllableState';
 export interface SelectableTagBaseProps {
   /**
diff --git a/packages/react/src/tools/__tests__/mergeRefs-test.js b/packages/react/src/tools/__tests__/mergeRefs-test.js
@@ -1,15 +1,15 @@
 /**
- * Copyright IBM Corp. 2016, 2023
+ * Copyright IBM Corp. 2016, 2025
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
  */
 
 import React from 'react';
-import mergeRefs from '../mergeRefs';
+import { mergeRefs } from '../mergeRefs';
 
 describe('mergeRefs', () => {
-  it('supports forwardRef as well as ref callback', () => {
+  it('should support object refs and ref callbacks', () => {
     const elem = document.createElement('div');
     const ref = React.createRef();
     let functionRefResult;
@@ -20,9 +20,67 @@ describe('mergeRefs', () => {
     expect(functionRefResult).toBe(elem);
   });
 
-  it('skips empty ref', () => {
+  it('should skip empty refs', () => {
     expect(() => {
       mergeRefs(undefined)(document.createElement('div'));
-    }).not.toThrow(Error);
+    }).not.toThrow();
+    expect(() => {
+      mergeRefs(null)(document.createElement('div'));
+    }).not.toThrow();
+  });
+
+  it('should merge multiple refs and update them all', () => {
+    const element = document.createElement('div');
+    const ref1 = React.createRef();
+    const ref2 = React.createRef();
+    let callback1, callback2;
+    const merged = mergeRefs(
+      ref1,
+      ref2,
+      (el) => (callback1 = el),
+      (el) => (callback2 = el)
+    );
+
+    merged(element);
+
+    expect(ref1.current).toBe(element);
+    expect(ref2.current).toBe(element);
+    expect(callback1).toBe(element);
+    expect(callback2).toBe(element);
+  });
+
+  it('should allow clearing', () => {
+    const ref = React.createRef();
+    let callbackValue;
+    const merged = mergeRefs(ref, (el) => {
+      callbackValue = el;
+    });
+    const element = document.createElement('div');
+
+    merged(element);
+
+    expect(ref.current).toBe(element);
+    expect(callbackValue).toBe(element);
+
+    // Setting the value to `null` should update the object and callback refs.
+    merged(null);
+
+    expect(ref.current).toBeNull();
+    expect(callbackValue).toBeNull();
+  });
+
+  it('should not mutate non-ref plain objects', () => {
+    const element = document.createElement('div');
+    const randomObject = {};
+
+    mergeRefs(randomObject)(element);
+
+    expect('current' in randomObject).toBe(false);
+  });
+
+  it('should ignore primitive values passed accidentally as refs', () => {
+    const element = document.createElement('div');
+
+    expect(() => mergeRefs(42, 'hello')(element)).not.toThrow();
   });
 });
diff --git a/packages/react/src/tools/mergeRefs.js b/packages/react/src/tools/mergeRefs.js
diff --git a/packages/react/src/tools/mergeRefs.ts b/packages/react/src/tools/mergeRefs.ts
@@ -0,0 +1,29 @@
+/**
+ * Copyright IBM Corp. 2016, 2025
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type { Ref, RefCallback } from 'react';
+
+/**
+ * @param refs Refs to merge.
+ * @returns Merged ref.
+ */
+export const mergeRefs = <T>(
+  ...refs: (Ref<T> | null | undefined)[]
+): RefCallback<T> => {
+  return (value: T | null) => {
+    refs.forEach((ref) => {
+      if (!ref) return;
+
+      // https://github.com/facebook/react/issues/13029#issuecomment-410002316
+      if (typeof ref === 'function') {
+        ref(value);
+      } else if (typeof ref === 'object' && 'current' in ref) {
+        ref.current = value;
+      }
+    });
+  };
+};

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`/**`
`2`		`- * Copyright IBM Corp. 2021`
	`2`	`+ * Copyright IBM Corp. 2021, 2025`
`3`	`3`	`*`
`4`	`4`	`* This source code is licensed under the Apache-2.0 license found in the`
`5`	`5`	`* LICENSE file in the root directory of this source tree.`
`@@ -11,7 +11,7 @@ import Search, { type SearchProps } from '../Search';`
`11`	`11`	`import { usePrefix } from '../../internal/usePrefix';`
`12`	`12`	`import { composeEventHandlers } from '../../tools/events';`
`13`	`13`	`import { match, keys } from '../../internal/keyboard';`
`14`		`-import mergeRefs from '../../tools/mergeRefs';`
	`14`	`+import { mergeRefs } from '../../tools/mergeRefs';`
`15`	`15`
`16`	`16`	`const ExpandableSearch = React.forwardRef(function ExpandableSearch(`
`17`	`17`	`{`