@box/blueprint-web 12.135.1 → 12.136.1

package/dist/lib-esm/breadcrumb/useFolderTreeTruncation.js

@@ -1,10 +1,11 @@
 import noop from 'lodash/noop';
-import { useState, useRef, useCallback, useEffect } from 'react';
+import { useState, useRef, useCallback, useLayoutEffect } from 'react';
 
-const getInitialState = (crumbCount, isTruncationRequiredBasedOnCrumbCount) => ({
-  isTruncationRequired: isTruncationRequiredBasedOnCrumbCount,
-  visibleCrumbCount: isTruncationRequiredBasedOnCrumbCount ? 3 : crumbCount
-});
+const MAX_VISIBLE_CRUMBS = 3;
+/**
+ * Calculates how many crumbs (from the end) can fit within the available width.
+ * Returns at least 1 to ensure we always show the current page.
+ */
 const calculateVisibleCrumbCount = (crumbWidths, availableWidth, gap, maxVisible) => {
   let crumbWidthWithoutGaps = 0;
   let visibleCount = 0;
@@ -20,15 +21,21 @@ const calculateVisibleCrumbCount = (crumbWidths, availableWidth, gap, maxVisible
   }
   return Math.max(1, visibleCount);
 };
-const measureCrumbWidths = (children, totalCrumbCount) => {
-  // The first child is the icon button when we always truncate
-  const crumbs = children.slice(1);
-  const widths = [];
-  const startIndex = totalCrumbCount - crumbs.length;
-  crumbs.forEach((crumb, i) => {
-    widths[startIndex + i] = crumb.offsetWidth;
+/**
+ * Measures the width of each crumb element.
+ *
+ * For the last crumb (no separator), we measure just the text element.
+ * For other crumbs, we measure the full <li> to include the separator.
+ */
+const measureCrumbWidths = (crumbElements, isLastCrumbIncluded) => {
+  return crumbElements.map((element, index) => {
+    const isLastCrumb = isLastCrumbIncluded && index === crumbElements.length - 1;
+    if (isLastCrumb) {
+      const textElement = element.firstElementChild;
+      return textElement?.offsetWidth ?? element.offsetWidth;
+    }
+    return element.offsetWidth;
   });
-  return widths;
 };
 /**
  * Calculate total width of crumbs including gaps
@@ -39,97 +46,50 @@ const calculateTotalWidth = (widths, gap) => {
   return totalCrumbsWidth + totalGapWidth;
 };
 /**
- * Handle >3 crumbs case: Always truncate, show icon button + up to 3 crumbs
+ * Determines the best truncation state using a cascading fallback strategy.
+ *
+ * Priority order (from most preferred to last resort):
+ * 1. Show all crumbs without truncation or ellipsis
+ * 2. Show icon + fewer crumbs without ellipsis
+ * 3. Show icon + 1 crumb with ellipsis (last resort)
  */
-const handleAlwaysTruncate = (children, context) => {
-  const {
-    containerWidth,
-    gap,
-    iconButtonWidth,
-    crumbCount,
-    storedCrumbWidths
-  } = context;
-  // If we don't have stored crumb widths yet, measure them
-  const crumbWidths = storedCrumbWidths.length < crumbCount ? measureCrumbWidths(children, crumbCount) : storedCrumbWidths;
-  // Icon button not yet rendered - use conservative fallback
-  if (iconButtonWidth === 0) {
+const handleTruncationState = (crumbWidths, containerWidth, iconButtonWidth, gap) => {
+  const crumbCount = crumbWidths.length;
+  // Edge case: no crumbs
+  if (crumbCount === 0) {
     return {
-      state: {
-        isTruncationRequired: true,
-        visibleCrumbCount: 1
-      },
-      crumbWidths
+      isTruncationRequired: false,
+      ellipsizeLastCrumb: false,
+      visibleCrumbCount: 0
     };
   }
-  const availableWidth = containerWidth - iconButtonWidth - gap;
-  const visibleCount = calculateVisibleCrumbCount(crumbWidths, availableWidth, gap, 3);
-  return {
-    state: {
-      isTruncationRequired: true,
-      visibleCrumbCount: visibleCount
-    },
-    crumbWidths
-  };
-};
-/**
- * Get crumb widths for total width calculation
- * Factored out into its own function to reduce cognitive complexity
- */
-const getCrumbWidths = (children, storedWidths, crumbCount, isCurrentlyTruncated) => {
-  if (storedWidths.length === crumbCount) {
-    return storedWidths; // Already have all widths
-  }
-  // The first child could be the icon button, so we don't want to measure it as part of the crumbs
-  const crumbElements = isCurrentlyTruncated ? children.slice(1) : children;
-  return crumbElements.map(crumbElement => crumbElement.offsetWidth);
-};
-/**
- * Handle ≤3 crumbs case: Render all first, detect overflow, truncate if needed
- */
-const handleConditionalTruncate = (children, context, isCurrentlyTruncated) => {
-  const {
-    containerWidth,
-    gap,
-    iconButtonWidth,
-    crumbCount,
-    storedCrumbWidths
-  } = context;
-  // Get crumb widths when all crumbs are visible (not truncated)
-  const crumbWidths = !isCurrentlyTruncated && children.length === crumbCount ? children.map(crumbElement => crumbElement.offsetWidth) // fresh measurement
-  : storedCrumbWidths; // Reuse stored
-  // Calculate total width to check for overflow
-  const widthsForCalculation = getCrumbWidths(children, crumbWidths, crumbCount, isCurrentlyTruncated);
-  const totalWidth = calculateTotalWidth(widthsForCalculation, gap);
-  const areCrumbsOverflowingWithoutTruncation = totalWidth > containerWidth;
-  // No overflow - show all crumbs
-  if (!areCrumbsOverflowingWithoutTruncation) {
+  const totalWidthAllCrumbs = calculateTotalWidth(crumbWidths, gap);
+  const availableWidthWithIcon = Math.max(0, containerWidth - iconButtonWidth - gap);
+  // Check if all crumbs fit without truncation (up to MAX_VISIBLE_CRUMBS)
+  if (crumbCount <= MAX_VISIBLE_CRUMBS && totalWidthAllCrumbs <= containerWidth) {
     return {
-      state: {
-        isTruncationRequired: false,
-        visibleCrumbCount: crumbCount
-      },
-      crumbWidths
+      isTruncationRequired: false,
+      ellipsizeLastCrumb: false,
+      visibleCrumbCount: crumbCount
     };
   }
-  // If we are overflowing, now calculate how many crumbs fit with icon button
-  // Icon button not yet rendered - use conservative fallback
-  if (iconButtonWidth === 0) {
+  // Single crumb: never show icon, just ellipsize if needed
+  if (crumbCount === 1) {
     return {
-      state: {
-        isTruncationRequired: true,
-        visibleCrumbCount: 1
-      },
-      crumbWidths
+      isTruncationRequired: false,
+      visibleCrumbCount: 1,
+      ellipsizeLastCrumb: totalWidthAllCrumbs > containerWidth
     };
   }
-  const availableWidth = containerWidth - iconButtonWidth - gap;
-  const visibleCount = calculateVisibleCrumbCount(crumbWidths, availableWidth, gap, crumbCount);
+  // Calculate how many crumbs fit with the icon button
+  const visibleCrumbCount = calculateVisibleCrumbCount(crumbWidths, availableWidthWithIcon, gap, MAX_VISIBLE_CRUMBS);
+  // If only 1 crumb fits and it still doesn't fit fully, enable ellipsis
+  const lastCrumbWidth = crumbWidths[crumbWidths.length - 1];
+  const ellipsizeLastCrumb = visibleCrumbCount === 1 && lastCrumbWidth > availableWidthWithIcon;
   return {
-    state: {
-      isTruncationRequired: true,
-      visibleCrumbCount: visibleCount
-    },
-    crumbWidths
+    isTruncationRequired: true,
+    visibleCrumbCount,
+    ellipsizeLastCrumb
   };
 };
 /**
@@ -141,79 +101,84 @@ const performTruncationCalculation = ({
   measuredIconButtonWidth,
   storedCrumbWidths,
   crumbCount,
-  isTruncationRequiredBaseOnCrumbLength,
   isTruncationRequired,
   setState
 }) => {
   const containerWidth = container.clientWidth;
-  const children = Array.from(container.children);
   const computedStyle = getComputedStyle(container);
   const gap = parseFloat(computedStyle.gap) || 0;
+  const children = Array.from(container.children);
   if (iconButtonRef.current) {
     measuredIconButtonWidth.current = iconButtonRef.current.offsetWidth;
   }
-  const context = {
-    containerWidth,
-    gap,
-    iconButtonWidth: measuredIconButtonWidth.current,
-    crumbCount,
-    storedCrumbWidths: storedCrumbWidths.current
-  };
-  const result = isTruncationRequiredBaseOnCrumbLength ? handleAlwaysTruncate(children, context) : handleConditionalTruncate(children, context, isTruncationRequired);
-  storedCrumbWidths.current = result.crumbWidths;
-  setState(result.state);
+  // When truncated, first child is icon button, so skip it
+  const crumbElements = isTruncationRequired ? children.slice(1) : children;
+  if (storedCrumbWidths.current.length < crumbCount && crumbElements.length > 0) {
+    const startIndex = crumbCount - crumbElements.length;
+    const isLastCrumbIncluded = startIndex + crumbElements.length === crumbCount;
+    const measuredWidths = measureCrumbWidths(crumbElements, isLastCrumbIncluded);
+    measuredWidths.forEach((width, i) => {
+      storedCrumbWidths.current[startIndex + i] = width;
+    });
+  }
+  if (storedCrumbWidths.current.length < crumbCount) {
+    return;
+  }
+  setState(handleTruncationState(storedCrumbWidths.current, containerWidth, measuredIconButtonWidth.current, gap));
 };
 /**
- * Hook which calculates how many crumbs can be displayed when folder-tree truncation is enabled.
+ * Hook that calculates optimal breadcrumb truncation for folder-tree display.
  *
- * ## Truncation Rules
- * - **≤3 crumbs**: Render all crumbs first, detect overflow, truncate only if needed
- * - **>3 crumbs**: Render truncated state immediately, show icon button + up to 3 crumbs
+ * Uses a cascading fallback strategy to show as many crumbs as possible without
+ * text ellipsis, falling back to ellipsis only as a last resort.
  *
- * @param containerRef - Ref to the main ol element
- * @param crumbs - Array of breadcrumb items
- * @param isEnabled - Whether folder-tree truncation is enabled. Can be false when responsive behavior is triggered
- * @returns Object containing wouldCrumbsOverflow, visibleCrumbCount, and iconButtonRef
+ * @param containerRef - Ref to the breadcrumb list container (ol element)
+ * @param crumbs - Array of breadcrumb items to display
+ * @param isMobile - Whether the breadcrumb is on a mobile device
  */
-const useFolderTreeTruncation = (containerRef, crumbs, isEnabled) => {
-  const isTruncationRequiredBaseOnCrumbLength = crumbs.length > 3;
-  const [state, setState] = useState(() => getInitialState(crumbs.length, isTruncationRequiredBaseOnCrumbLength));
-  const animationFrameId = useRef(null);
+const useFolderTreeTruncation = (containerRef, crumbs, isMobile) => {
+  const crumbCount = crumbs.length;
+  // Initial state: for 4+ crumbs, start truncated; otherwise show all
+  const initialState = {
+    isTruncationRequired: crumbCount > MAX_VISIBLE_CRUMBS,
+    ellipsizeLastCrumb: false,
+    visibleCrumbCount: Math.min(crumbCount, MAX_VISIBLE_CRUMBS)
+  };
+  const [state, setState] = useState(initialState);
   const iconButtonRef = useRef(null);
-  // Refs are used here to persist values
-  const measuredIconButtonWidth = useRef(0);
+  // Cache for measured values to avoid re-measuring on every resize
   const storedCrumbWidths = useRef([]);
-  const prevCrumbsLength = useRef(crumbs.length);
-  // Clear stored widths when user navigates and the visible crumbs change
-  if (prevCrumbsLength.current !== crumbs.length) {
+  const measuredIconButtonWidth = useRef(0);
+  const prevCrumbCount = useRef(crumbCount);
+  // Reset cache when crumbs change (user navigated)
+  if (prevCrumbCount.current !== crumbCount) {
     storedCrumbWidths.current = [];
-    setState(getInitialState(crumbs.length, isTruncationRequiredBaseOnCrumbLength));
-    prevCrumbsLength.current = crumbs.length;
+    measuredIconButtonWidth.current = 0;
+    prevCrumbCount.current = crumbCount;
+    setState(initialState);
   }
   const calculateTruncation = useCallback(() => {
     const container = containerRef.current;
     if (!container) {
       return;
     }
-    animationFrameId.current = requestAnimationFrame(() => {
-      performTruncationCalculation({
-        container,
-        iconButtonRef,
-        measuredIconButtonWidth,
-        storedCrumbWidths,
-        crumbCount: crumbs.length,
-        isTruncationRequiredBaseOnCrumbLength,
-        isTruncationRequired: state.isTruncationRequired,
-        setState
-      });
+    performTruncationCalculation({
+      container,
+      iconButtonRef,
+      measuredIconButtonWidth,
+      storedCrumbWidths,
+      crumbCount,
+      isTruncationRequired: state.isTruncationRequired,
+      setState
     });
-  }, [containerRef, crumbs.length, state.isTruncationRequired, isTruncationRequiredBaseOnCrumbLength]);
-  useEffect(() => {
+  }, [containerRef, crumbCount, state.isTruncationRequired]);
+  useLayoutEffect(() => {
     // Reset state when truncation is disabled (e.g., responsive breakpoint triggers mobile view)
-    if (!isEnabled) {
+    if (isMobile) {
       setState({
         isTruncationRequired: false,
-        visibleCrumbCount: crumbs.length
+        ellipsizeLastCrumb: false,
+        visibleCrumbCount: crumbCount
       });
       measuredIconButtonWidth.current = 0;
       storedCrumbWidths.current = [];
@@ -230,11 +195,8 @@ const useFolderTreeTruncation = (containerRef, crumbs, isEnabled) => {
     calculateTruncation();
     return () => {
       observer.disconnect();
-      if (animationFrameId.current !== null) {
-        cancelAnimationFrame(animationFrameId.current);
-      }
     };
-  }, [containerRef, isEnabled, calculateTruncation, crumbs.length]);
+  }, [calculateTruncation, containerRef, crumbCount, isMobile]);
   return {
     ...state,
     iconButtonRef

package/dist/lib-esm/combobox/types.d.ts

@@ -204,6 +204,10 @@ export interface ComboboxBaseProps<Multiple extends boolean, FreeInput extends b
      * Callback used when combobox input/textarea loses focus
      */
     onBlur?: (event: React.FocusEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
+    /**
+     * Callback when text is pasted into the input
+     */
+    onPaste?: React.ClipboardEventHandler<HTMLInputElement>;
     /**
      * aria-label passed to the Combobox clear button. If not provided, the clear button is not shown.
      */