refactor: decouple overflow logic to create independent overflow utility

packages/ibm-products/src/components/TagOverflow/TagOverflow.stories.jsx

@@ -75,6 +75,7 @@ export const TagsWithOverflowCount = Template.bind({});
 TagsWithOverflowCount.args = {
   containerWidth: 250,
   items: fiveTags,
+  onOverflowTagChange: (items) => console.log(items),
 };
 
 export const TagsWithTruncation = Template.bind({});

packages/ibm-products/src/components/TagOverflow/TagOverflow.tsx

@@ -7,12 +7,10 @@
 
 import React, {
   ReactNode,
-  Ref,
   RefObject,
   createElement,
   forwardRef,
   useCallback,
-  useEffect,
   useRef,
   useState,
 } from 'react';
@@ -26,7 +24,7 @@
 import { getDevtoolsProps } from '../../global/js/utils/devtools';
 import { isRequiredIf } from '../../global/js/utils/props-helper';
 import { pkg } from '../../settings';
-import { useResizeObserver } from '../../global/js/hooks/useResizeObserver';
+import { useOverflowItems } from '../../global/js/hooks/useOverflowItems';
 export interface TagOverflowItem {
   className?: string;
   /**
@@ -61,10 +59,19 @@
   allTagsModalTitle?: string;
   autoAlign?: boolean;
   className?: string;
-  containingElementRef?: RefObject<HTMLElement>;
+  /**
+   * @deprecated The `containingElementRef` prop is no longer going to be used in favor of the forwarded ref.
+   */
+  containingElementRef?: RefObject<HTMLDivElement>;
   items: TagOverflowItem[];
   maxVisible?: number;
+  /**
+   * @deprecated The `measurementOffset` prop is no longer going to be used. This value will now be calculated automatically.
+   */
   measurementOffset?: number;
+  /**
+   * @deprecated The `multiline` prop is no longer going to be used. This component should only be used when you need to hide overflowing items.
+   */
   multiline?: boolean;
   overflowAlign?:
     | 'top'
@@ -90,8 +97,8 @@
 const componentName = 'TagOverflow';
 const allTagsModalSearchThreshold = 10;
 
-export let TagOverflow = forwardRef(
-  (props: TagOverflowProps, ref: Ref<HTMLDivElement>) => {
+export let TagOverflow = forwardRef<HTMLDivElement, TagOverflowProps>(
+  (props, ref) => {
     const {
       align = 'start',
       allTagsModalAriaLabel,
@@ -101,11 +108,8 @@
       allTagsModalTitle,
       autoAlign,
       className,
-      containingElementRef,
       items,
       maxVisible,
-      measurementOffset = 0,
-      multiline,
       overflowAlign = 'bottom',
       overflowClassName,
       overflowType = 'default',
@@ -115,25 +119,16 @@
       ...rest
     } = props;
 
-    const localContainerRef = useRef<HTMLDivElement>(null);
-    const containerRef = ref || localContainerRef;
-    const itemRefs = useRef<Map<string, string> | null>(null);
     const overflowRef = useRef<HTMLDivElement>(null);
-    // itemOffset is the value of margin applied on each items
-    // This value is required for calculating how many items will fit within the container
-    const itemOffset = 4;
-    const overflowIndicatorWidth = 40;
-
-    const [containerWidth, setContainerWidth] = useState<number>(0);
-    const [visibleItems, setVisibleItems] = useState<TagOverflowItem[]>([]);
-    const [overflowItems, setOverflowItems] = useState<TagOverflowItem[]>([]);
     const [showAllModalOpen, setShowAllModalOpen] = useState<boolean>(false);
     const [popoverOpen, setPopoverOpen] = useState<boolean>(false);
 
-    const resizeElm =
-      containingElementRef && containingElementRef.current
-        ? containingElementRef
-        : containerRef;
+    const {
+      visibleItems,
+      hiddenItems: overflowItems,
+      containerRef,
+      itemRefHandler,
+    } = useOverflowItems(items, ref, maxVisible, onOverflowTagChange);
 
     const handleShowAllClick = () => {
       setShowAllModalOpen(true);
@@ -143,80 +138,6 @@
       setShowAllModalOpen(false);
     };
 
-    const handleResize = () => {
-      if (typeof resizeElm !== 'function' && resizeElm.current) {
-        setContainerWidth(resizeElm.current.offsetWidth);
-      }
-    };
-
-    useResizeObserver(resizeElm, handleResize);
-
-    const getMap = () => {
-      if (!itemRefs.current) {
-        itemRefs.current = new Map();
-      }
-      return itemRefs.current;
-    };
-
-    const itemRefHandler = (id, node) => {
-      const map = getMap();
-      if (id && node && map.get(id) !== node.offsetWidth) {
-        map.set(id, node.offsetWidth);
-      }
-    };
-
-    const getVisibleItems = useCallback(() => {
-      if (!itemRefs.current) {
-        return items;
-      }
-
-      if (multiline) {
-        const visibleItems = maxVisible ? items?.slice(0, maxVisible) : items;
-        return visibleItems;
-      }
-
-      const map = getMap();
-      const optionalContainingElement = containingElementRef?.current;
-      const measurementOffsetValue =
-        typeof measurementOffset === 'number' ? measurementOffset : 0;
-      const spaceAvailable = optionalContainingElement
-        ? optionalContainingElement.offsetWidth - measurementOffsetValue
-        : containerWidth;
-
-      const overflowContainerWidth =
-        overflowRef &&
-        overflowRef.current &&
-        overflowRef.current.offsetWidth > overflowIndicatorWidth
-          ? overflowRef.current.offsetWidth
-          : overflowIndicatorWidth;
-      const maxWidth = spaceAvailable - overflowContainerWidth;
-
-      let childrenWidth = 0;
-      let maxReached = false;
-
-      return items.reduce((prev: TagOverflowItem[], cur: TagOverflowItem) => {
-        if (!maxReached) {
-          const itemWidth = (map ? Number(map.get(cur.id)) : 0) + itemOffset;
-          const fits = itemWidth + childrenWidth < maxWidth;
-
-          if (fits) {
-            childrenWidth += itemWidth;
-            prev.push(cur);
-          } else {
-            maxReached = true;
-          }
-        }
-        return prev;
-      }, []);
-    }, [
-      containerWidth,
-      containingElementRef,
-      items,
-      maxVisible,
-      measurementOffset,
-      multiline,
-    ]);
-
     const getCustomComponent = (
       item: TagOverflowItem,
       tagComponent: string
@@ -226,27 +147,10 @@
         ...other,
         key: id,
         className: cx(`${blockClass}__item`, className),
-        ref: (node) => itemRefHandler(id, node),
+        ref: (node) => itemRefHandler(id, node as HTMLDivElement),
       });
     };
 
-    useEffect(() => {
-      let visibleItemsArr = getVisibleItems();
-
-      if (maxVisible && maxVisible < visibleItemsArr.length) {
-        visibleItemsArr = visibleItemsArr?.slice(0, maxVisible);
-      }
-
-      const hiddenItems = items?.slice(visibleItemsArr.length);
-      const overflowItemsArr = hiddenItems?.map(({ tagType, ...other }) => {
-        return { type: tagType, ...other };
-      });
-
-      setVisibleItems(visibleItemsArr);
-      setOverflowItems(overflowItemsArr);
-      onOverflowTagChange?.(overflowItemsArr);
-    }, [getVisibleItems, items, maxVisible, onOverflowTagChange]);
-
     const handleTagOnClose = useCallback(
       (onClose, index) => {
         onClose?.();
@@ -259,24 +163,17 @@
 
     return (
       <div
-        {
-          // Pass through any other property values as HTML attributes.
-          ...rest
-        }
-        className={cx(blockClass, className, `${blockClass}--align-${align}`, {
-          [`${blockClass}--multiline`]: multiline,
-        })}
+        {...rest}
+        className={cx(blockClass, className, `${blockClass}--align-${align}`)}
         ref={containerRef}
         {...getDevtoolsProps(componentName)}
       >
         {visibleItems?.length > 0 &&
           visibleItems.map((item, index) => {
-            // Render custom components
             if (tagComponent) {
               return getCustomComponent(item, tagComponent);
             } else {
               const { id, label, tagType, onClose, filter, ...other } = item;
-              // If there is no template prop, then render items as Tags
               return (
                 <div ref={(node) => itemRefHandler(id, node)} key={id}>
                   {typeof onClose === 'function' || filter ? (

packages/ibm-products/src/global/js/hooks/useOverflowItems.ts

@@ -0,0 +1,100 @@
+/**
+ * Copyright IBM Corp. 2024, 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 { useState, useRef, ForwardedRef } from 'react';
+import { useResizeObserver } from './useResizeObserver';
+
+type Item = {
+  id: string;
+};
+
+export function useOverflowItems<T extends Item>(
+  items: T[] = [],
+  ref?: ForwardedRef<HTMLDivElement>,
+  maxVisible?: number,
+  onChange?: (hiddenItems: T[]) => void
+) {
+  const localRef = useRef<HTMLDivElement>(null);
+  const itemRefs = useRef<Map<number, number> | null>(null);
+  const [containerWidth, setContainerWidth] = useState<number>(0);
+  const containerRef = ref || localRef;
+  const visibleItemCount = useRef<number>(0);
+
+  const handleResize = () => {
+    if (typeof containerRef !== 'function' && containerRef.current) {
+      setContainerWidth(containerRef.current.offsetWidth);
+    }
+  };
+
+  const getMap = (): Map<string | number, number> => {
+    if (!itemRefs.current) {
+      itemRefs.current = new Map();
+    }
+    return itemRefs.current;
+  };
+
+  const itemRefHandler = (
+    id: string | number,
+    node: HTMLElement | null
+  ): void => {
+    const map = getMap();
+    if (node && !map.get(id)) {
+      const style = getComputedStyle?.(node);
+      const totalWidth = style
+        ? parseInt(style.marginLeft) +
+          parseInt(style.marginRight) +
+          node.offsetWidth
+        : node.offsetWidth;
+      map.set(id, totalWidth);
+    }
+  };
+
+  const getItems = (): T[] => {
+    const map = getMap();
+    if (!map) {
+      return items;
+    }
+    const maxWidth = containerWidth;
+    let maxReached = false;
+    let totalWidth = 0;
+
+    return items.reduce((prev, cur) => {
+      if (maxVisible && prev.length >= maxVisible) {
+        maxReached = true;
+      }
+      if (!maxReached) {
+        const itemWidth = map.get(cur.id) || 0;
+        const willFit = itemWidth + totalWidth <= maxWidth;
+        if (willFit) {
+          totalWidth += itemWidth;
+          prev.push(cur);
+        } else {
+          maxReached = true;
+        }
+      }
+      return prev;
+    }, [] as T[]);
+  };
+
+  useResizeObserver(containerRef, handleResize);
+
+  const visibleItems = getItems();
+  const visibleItemsNum = visibleItems.length;
+  const hiddenItems = items.slice(visibleItemsNum);
+  // only call the change handler when the number of visible items has changed
+  if (visibleItemsNum !== visibleItemCount.current) {
+    visibleItemCount.current = visibleItemsNum;
+    onChange?.(hiddenItems);
+  }
+
+  return {
+    visibleItems,
+    hiddenItems,
+    containerRef,
+    itemRefHandler,
+  };
+}