fix: update ref handling in ListBoxMenuItem useIsTruncated hook (#18611)

* fix: update ref handling in ListBoxMenuItem useIsTruncated hook

* refactor: merge forwarded and local refs in useIsTruncated hook

* refactor: update useIsTruncated to use useMergedRefs

Author: adamalston

packages/react/src/components/ListBox/ListBoxMenuItem.tsx

@@ -1,5 +1,5 @@
 /**
- * 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.
@@ -8,26 +8,52 @@
 import cx from 'classnames';
 import React, {
   ForwardedRef,
+  forwardRef,
   ReactNode,
   useEffect,
   useRef,
   useState,
+  type MutableRefObject,
+  type Ref,
 } from 'react';
 import PropTypes from 'prop-types';
 import { usePrefix } from '../../internal/usePrefix';
 import { ForwardRefReturn, ReactAttr } from '../../types/common';
+import { useMergedRefs } from '../../internal/useMergedRefs';
 
-function useIsTruncated(ref) {
+/**
+ * Determines if the content of an element is truncated.
+ *
+ * Merges a forwarded ref with a local ref to check the element's dimensions.
+ *
+ * @template T
+ * @param forwardedRef - A ref passed from the parent component.
+ * @param deps - Dependencies to re-run the truncation check.
+ * @returns An object containing the truncation state and the merged ref.
+ */
+const useIsTruncated = <T extends HTMLElement>(
+  forwardedRef?: Ref<T>,
+  deps: any[] = []
+) => {
+  const localRef = useRef<T>(null);
+  const mergedRef = useMergedRefs([
+    ...(forwardedRef ? [forwardedRef] : []),
+    localRef,
+  ]);
   const [isTruncated, setIsTruncated] = useState(false);
 
   useEffect(() => {
-    const element = ref.current;
-    const { offsetWidth, scrollWidth } = element;
-    setIsTruncated(offsetWidth < scrollWidth);
-  }, [ref, setIsTruncated]);
+    const element = localRef.current;
 
-  return isTruncated;
-}
+    if (element) {
+      const { offsetWidth, scrollWidth } = element;
+
+      setIsTruncated(offsetWidth < scrollWidth);
+    }
+  }, [localRef, ...deps]);
+
+  return { isTruncated, ref: mergedRef };
+};
 
 export interface ListBoxMenuItemProps extends ReactAttr<HTMLLIElement> {
   /**
@@ -58,7 +84,7 @@ export interface ListBoxMenuItemProps extends ReactAttr<HTMLLIElement> {
 
 export type ListBoxMenuItemForwardedRef =
   | (ForwardedRef<HTMLLIElement> & {
-      menuItemOptionRef?: React.Ref<HTMLDivElement>;
+      menuItemOptionRef?: Ref<HTMLDivElement>;
     })
   | null;
 
@@ -72,20 +98,26 @@ export type ListBoxMenuItemComponent = ForwardRefReturn<
  * name, alongside any classes for any corresponding states, for a generic list
  * box menu item.
  */
-const ListBoxMenuItem = React.forwardRef<HTMLLIElement, ListBoxMenuItemProps>(
-  function ListBoxMenuItem(
-    {
-      children,
-      isActive = false,
-      isHighlighted = false,
-      title,
-      ...rest
-    }: ListBoxMenuItemProps,
-    forwardedRef: ListBoxMenuItemForwardedRef
-  ) {
+const ListBoxMenuItem = forwardRef<HTMLLIElement, ListBoxMenuItemProps>(
+  (
+    { children, isActive = false, isHighlighted = false, title, ...rest },
+    forwardedRef
+  ) => {
     const prefix = usePrefix();
-    const ref = useRef(null);
-    const isTruncated = useIsTruncated(forwardedRef?.menuItemOptionRef || ref);
+
+    const menuItemOptionRefProp =
+      forwardedRef && typeof forwardedRef !== 'function'
+        ? (
+            forwardedRef as MutableRefObject<HTMLLIElement | null> & {
+              menuItemOptionRef?: Ref<HTMLDivElement>;
+            }
+          ).menuItemOptionRef
+        : undefined;
+
+    const { isTruncated, ref: menuItemOptionRef } = useIsTruncated(
+      menuItemOptionRefProp,
+      [children]
+    );
     const className = cx(`${prefix}--list-box__menu-item`, {
       [`${prefix}--list-box__menu-item--active`]: isActive,
       [`${prefix}--list-box__menu-item--highlighted`]: isHighlighted,
@@ -98,7 +130,7 @@ const ListBoxMenuItem = React.forwardRef<HTMLLIElement, ListBoxMenuItemProps>(
         title={isTruncated ? title : undefined}>
         <div
           className={`${prefix}--list-box__menu-item__option`}
-          ref={forwardedRef?.menuItemOptionRef || ref}>
+          ref={menuItemOptionRef}>
           {children}
         </div>
       </li>

packages/react/src/components/ListBox/__tests__/ListBoxMenuItem-test.js

@@ -28,4 +28,18 @@ describe('ListBoxMenuItem', () => {
     const { container } = render(<ListBox.MenuItem data-testid="test" />);
     expect(container.firstChild).toHaveAttribute('data-testid', 'test');
   });
+
+  it('should forward `menuItemOptionRef` to the inner `div` element', () => {
+    let innerDivNode = null;
+    const menuItemOptionRefCallback = jest.fn((node) => {
+      innerDivNode = node;
+    });
+    const forwardedRef = { menuItemOptionRef: menuItemOptionRefCallback };
+    const { container } = render(<ListBox.MenuItem ref={forwardedRef} />);
+    const expectedDiv = container.querySelector(
+      '.cds--list-box__menu-item__option'
+    );
+
+    expect(innerDivNode).toBe(expectedDiv);
+  });
 });

packages/react/src/internal/useMergedRefs.ts

@@ -7,6 +7,9 @@
 
 import { useCallback, Ref, ForwardedRef } from 'react';
 
+// TODO: Investigate updating this hook based on the following code from
+// https://github.com/carbon-design-system/carbon/pull/18611:
+// https://github.com/adamalston/carbon/blob/dd403b6b10de3d8a6ccd8d2e21174c908c1e890a/packages/react/src/components/ListBox/ListBoxMenuItem.tsx#L23-L46
 /**
  * Combine multiple refs into a single ref. This use useful when you have two
  * refs from both `React.forwardRef` and `useRef` that you would like to add to