@mui/utils 9.0.0-alpha.4 → 9.0.0-beta.1

package/useRovingTabIndex/useRovingTabIndex.mjs

@@ -1,59 +1,99 @@
 'use client';
 
 import * as React from 'react';
-import ownerDocument from "../ownerDocument/index.mjs";
+import fastObjectShallowCompare from "../fastObjectShallowCompare/index.mjs";
 import getActiveElement from "../getActiveElement/index.mjs";
+import ownerDocument from "../ownerDocument/index.mjs";
+import setRef from "../setRef/index.mjs";
+import useEnhancedEffect from "../useEnhancedEffect/index.mjs";
+import useEventCallback from "../useEventCallback/index.mjs";
+import useForkRef from "../useForkRef/index.mjs";
+import { useRovingTabIndexContext } from "./RovingTabIndexContext.mjs";
 const SUPPORTED_KEYS = ['ArrowRight', 'ArrowLeft', 'ArrowUp', 'ArrowDown', 'Home', 'End'];
 
 /**
- * Provides roving tab index behavior for a container and its focusable children.
+ * Provides roving tab index behavior for a composite container and its focusable children.
  * This is useful for implementing keyboard navigation in components like menus, tabs, and lists.
  * The hook manages the focus state of child elements and provides props to be spread on both the container and the items.
  * The container will handle keyboard events to move focus between items based on the specified orientation and wrapping behavior.
- *
- * @param options - Configuration options for the roving tab index behavior, including orientation, initial focusable index, RTL support, and custom focus logic.
- * @returns An object containing `getItemProps` and `getContainerProps` functions to be spread on the respective elements, and a `focusNext` function to programmatically move focus to the next item.
  */
-export default function useRovingTabIndex(options) {
+export function useRovingTabIndexRoot(params) {
   const {
+    activeItemId: activeItemIdProp,
+    getDefaultActiveItemId,
     orientation,
-    focusableIndex: focusableIndexProp,
     isRtl = false,
-    shouldFocus = internalShouldFocus,
-    shouldWrap = true
-  } = options;
-  const initialFocusableIndex = focusableIndexProp ?? 0;
-  const [focusableIndex, setFocusableIndex] = React.useState(initialFocusableIndex);
-  const elementsRef = React.useRef([]);
-  const containerRef = React.useRef(null);
-  const previousFocusableIndexPropRef = React.useRef(initialFocusableIndex);
-  if (focusableIndexProp !== undefined && focusableIndexProp !== previousFocusableIndexPropRef.current) {
-    previousFocusableIndexPropRef.current = focusableIndexProp;
-    if (focusableIndexProp !== focusableIndex) {
-      setFocusableIndex(focusableIndexProp);
+    isItemFocusable: itemFilter = isItemFocusable,
+    wrap = true
+  } = params;
+  const [activeItemIdState, setActiveItemIdState] = React.useState(activeItemIdProp);
+  const previousActiveItemIdPropRef = React.useRef(activeItemIdProp);
+  let activeItemIdCandidate = activeItemIdState;
+  if (activeItemIdProp !== previousActiveItemIdPropRef.current) {
+    previousActiveItemIdPropRef.current = activeItemIdProp;
+    if (activeItemIdProp !== undefined && activeItemIdProp !== activeItemIdState) {
+      activeItemIdCandidate = activeItemIdProp;
+      setActiveItemIdState(activeItemIdProp);
     }
   }
-  React.useEffect(() => {
-    if (elementsRef.current.length === 0 || focusableIndex === -1 || focusableIndex >= elementsRef.current.length) {
+  const containerRef = React.useRef(null);
+
+  // based on https://github.com/mui/base-ui/blob/7392a928fca91fcc68b9fad3439ac61e10f3f7ba/packages/react/src/composite/list/CompositeList.tsx#L25-L35
+  const itemMapRef = React.useRef(new Map());
+  const [mapTick, setMapTick] = React.useState(0);
+  const orderedItems = React.useMemo(() => {
+    void mapTick;
+    return getOrderedItems(itemMapRef.current);
+  }, [mapTick]);
+  const resolvedActiveItemId = resolveActiveItemId(activeItemIdCandidate, orderedItems, itemFilter, getDefaultActiveItemId);
+  const activeItemIdRef = React.useRef(resolvedActiveItemId);
+  activeItemIdRef.current = resolvedActiveItemId;
+  const getActiveItem = React.useCallback(() => {
+    const snapshot = getOrderedItems(itemMapRef.current);
+    const resolvedItemId = resolveActiveItemId(activeItemIdRef.current, snapshot, itemFilter, getDefaultActiveItemId);
+    return getItemById(snapshot, resolvedItemId);
+  }, [getDefaultActiveItemId, itemFilter]);
+  const getItemMap = React.useCallback(() => {
+    return itemMapRef.current;
+  }, []);
+  const registerItem = useEventCallback(item => {
+    const previousItem = itemMapRef.current.get(item.id);
+    if (fastObjectShallowCompare(previousItem ?? null, item)) {
       return;
     }
-    if (!shouldFocus(elementsRef.current[focusableIndex])) {
-      const nextIndex = focusNext(elementsRef, focusableIndex, 'next', false, shouldFocus);
-      setFocusableIndex(nextIndex);
+    itemMapRef.current.set(item.id, item);
+    setMapTick(value => value + 1);
+  });
+  const unregisterItem = useEventCallback(itemId => {
+    if (itemMapRef.current.delete(itemId)) {
+      setMapTick(value => value + 1);
+    }
+  });
+  const setActiveItemId = useEventCallback(itemId => {
+    setActiveItemIdState(itemId);
+  });
+  const isItemActive = React.useCallback(itemId => {
+    return activeItemIdRef.current === itemId;
+  }, []);
+
+  // Moves focus relative to a starting index. This is the directional helper used by
+  // keyboard navigation and `focusNext()`.
+  const focusItem = React.useCallback((currentIndex, direction, wrap, isItemFocusableOverride) => {
+    const snapshot = getNavigableItemsSnapshot(itemMapRef.current);
+    const nextItem = getNextActiveItem(snapshot, currentIndex, direction, wrap, isItemFocusableOverride ?? itemFilter);
+    if (!nextItem) {
+      return null;
     }
-  }, [focusableIndex, shouldFocus]);
-  const getItemProps = React.useCallback((index, ref) => ({
-    ref: handleRefs(ref, elementNode => {
-      elementsRef.current[index] = elementNode;
-    }),
-    tabIndex: index === focusableIndex ? 0 : -1
-  }), [focusableIndex]);
+    nextItem.element?.focus();
+    setActiveItemIdState(nextItem.id);
+    return nextItem;
+  }, [itemFilter]);
   const getContainerProps = React.useCallback(ref => {
     const onFocus = event => {
-      const focusedElement = event.target;
-      const focusedIndex = elementsRef.current.findIndex(element => element === focusedElement);
+      const snapshot = getNavigableItemsSnapshot(itemMapRef.current);
+      const focusedIndex = findItemIndexByElement(snapshot, event.target);
       if (focusedIndex !== -1) {
-        setFocusableIndex(focusedIndex);
+        setActiveItemIdState(snapshot[focusedIndex].id);
       }
     };
     const onKeyDown = event => {
@@ -66,45 +106,42 @@ export default function useRovingTabIndex(options) {
       let previousItemKey = orientation === 'horizontal' ? 'ArrowLeft' : 'ArrowUp';
       let nextItemKey = orientation === 'horizontal' ? 'ArrowRight' : 'ArrowDown';
       if (orientation === 'horizontal' && isRtl) {
-        // swap previousItemKey with nextItemKey
         previousItemKey = 'ArrowRight';
         nextItemKey = 'ArrowLeft';
       }
+      const snapshot = getNavigableItemsSnapshot(itemMapRef.current);
       const currentFocus = getActiveElement(ownerDocument(containerRef.current));
       const isFocusOnContainer = currentFocus === containerRef.current;
+      let currentIndex = getCurrentActiveItemIndex(snapshot, currentFocus, activeItemIdRef.current);
       let direction = 'next';
-      let currentIndex = focusableIndex;
       switch (event.key) {
         case previousItemKey:
           direction = 'previous';
           event.preventDefault();
           if (isFocusOnContainer) {
             // Set to length, so that the previous focused element will be the last one.
-            currentIndex = elementsRef.current.length;
+            currentIndex = snapshot.length;
           }
           break;
         case nextItemKey:
           event.preventDefault();
           if (isFocusOnContainer) {
-            // Set to -1, so that the next focused element will be the first one.
             currentIndex = -1;
           }
           break;
         case 'Home':
           event.preventDefault();
-          // Set to -1, so that the next focused element will be the first one.
           currentIndex = -1;
           break;
         case 'End':
           event.preventDefault();
           direction = 'previous';
-          // Set to length, so that the previous focused element will be the last one.
-          currentIndex = elementsRef.current.length;
+          currentIndex = snapshot.length;
           break;
         default:
           return;
       }
-      focusNext(elementsRef, currentIndex, direction, shouldWrap, shouldFocus);
+      focusItem(currentIndex, direction, wrap);
     };
     return {
       onFocus,
@@ -113,51 +150,269 @@ export default function useRovingTabIndex(options) {
         containerRef.current = elementNode;
       })
     };
-  }, [focusableIndex, isRtl, orientation, shouldWrap, shouldFocus]);
-  const focusNextExport = React.useCallback(shouldFocusOverride => {
+  }, [focusItem, isRtl, orientation, wrap]);
+  const focusNext = React.useCallback(isItemFocusableOverride => {
+    const snapshot = getNavigableItemsSnapshot(itemMapRef.current);
     const currentFocus = getActiveElement(ownerDocument(containerRef.current));
     const isFocusOnContainer = currentFocus === containerRef.current;
-    let currentIndex = focusableIndex;
-    if (isFocusOnContainer) {
-      currentIndex = -1;
+    const currentIndex = isFocusOnContainer ? -1 : getCurrentActiveItemIndex(snapshot, currentFocus, activeItemIdRef.current);
+    return focusItem(currentIndex, 'next', true, isItemFocusableOverride)?.id ?? null;
+  }, [focusItem]);
+  return React.useMemo(() => ({
+    activeItemId: resolvedActiveItemId,
+    focusNext,
+    getActiveItem,
+    getContainerProps,
+    getItemMap,
+    isItemActive,
+    registerItem,
+    setActiveItemId,
+    unregisterItem
+  }), [resolvedActiveItemId, focusNext, getActiveItem, getContainerProps, getItemMap, isItemActive, registerItem, setActiveItemId, unregisterItem]);
+}
+export function useRovingTabIndexItem(params) {
+  const rootContext = useRovingTabIndexContext();
+  const {
+    activeItemId,
+    registerItem,
+    unregisterItem
+  } = rootContext;
+  const elementRef = React.useRef(null);
+  const item = React.useMemo(() => ({
+    disabled: params.disabled ?? false,
+    element: null,
+    focusableWhenDisabled: params.focusableWhenDisabled ?? false,
+    id: params.id,
+    selected: params.selected ?? false,
+    textValue: params.textValue
+  }), [params.disabled, params.focusableWhenDisabled, params.id, params.selected, params.textValue]);
+  const latestItemRef = React.useRef(item);
+  // Keep the ref callback stable across item prop changes. The callback reads the latest
+  // item metadata from this ref so React does not have to detach and re-attach the ref
+  // every time `disabled`, `selected`, or similar item state changes.
+  latestItemRef.current = item;
+  const handleElementRef = React.useCallback(element => {
+    elementRef.current = element;
+    if (element == null) {
+      // Ref detachment runs during React's commit phase. Calling `unregisterItem()`
+      // synchronously here can trigger a nested state update while React is still
+      // finishing that commit. Unregister in a microtask so it runs after the
+      // commit completes.
+      queueMicrotask(() => {
+        // null check prevents stale unregisters for a remove-then-re-add edge case
+        if (elementRef.current == null) {
+          unregisterItem(params.id);
+        }
+      });
+      return;
     }
-    const nextIndex = focusNext(elementsRef, currentIndex, 'next', true, shouldFocusOverride ?? shouldFocus);
-    if (nextIndex !== -1) {
-      setFocusableIndex(nextIndex);
+    registerItem({
+      ...latestItemRef.current,
+      element
+    });
+  }, [params.id, registerItem, unregisterItem]);
+
+  // `UseRovingTabIndexItemReturnValue.ref` must always be a callback ref. `useForkRef()`
+  // is typed to return `null` when every input ref is nullish, but this call always includes
+  // `handleElementRef`, so the merged ref cannot be `null` here.
+  const mergedRef = useForkRef(params.ref, handleElementRef);
+  useEnhancedEffect(() => {
+    if (!elementRef.current) {
+      return;
     }
-    return nextIndex;
-  }, [focusableIndex, shouldFocus]);
+    registerItem({
+      ...item,
+      element: elementRef.current
+    });
+  }, [item, registerItem]);
+  useEnhancedEffect(() => {
+    const itemId = params.id;
+
+    // Keep unmount cleanup separate from the effect above. The effect above re-runs when
+    // item metadata changes, but we only want to unregister on unmount or when the item id changes.
+    return () => {
+      unregisterItem(itemId);
+    };
+  }, [params.id, unregisterItem]);
   return {
-    getItemProps,
-    getContainerProps,
-    focusNext: focusNextExport
+    ref: mergedRef,
+    tabIndex: activeItemId === params.id ? 0 : -1
   };
 }
-function focusNext(elementsRef, currentIndex, direction, wrap, shouldFocus) {
-  const lastIndex = elementsRef.current.length - 1;
+
+/**
+ * Resolves which item id should own the roving tab stop for the current render.
+ *
+ * This is the top-level decision point for "who gets `tabIndex=0` right now?".
+ * For example:
+ * - `Tabs` sometimes passes `selectedValue` as `activeItemId` so the selected tab becomes
+ *   the tab stop when focus enters the list from outside.
+ * - `MenuList` leaves `activeItemId` undefined and relies on the default-item logic below
+ *   so that menu-specific rules decide which menu item should initially own the tab stop.
+ *
+ * @param activeItemId The item id supplied through the root hook's `activeItemId` option.
+ *   `undefined` means "the caller did not ask for a specific item, use the default-item
+ *   logic instead". `null` means "there is intentionally no preferred item, so also fall
+ *   back to the default-item logic".
+ * @param items The ordered registered items currently in the roving set.
+ * @param isFocusable A predicate that decides whether an item may receive roving focus.
+ * @param getDefaultActiveItemId Optional caller-provided function that picks the preferred
+ *   default item when `activeItemId` is not driving the tab stop directly.
+ * @returns The id of the item that should own `tabIndex=0`, or `null` if no item is focusable.
+ */
+function resolveActiveItemId(activeItemId, items, isFocusable, getDefaultActiveItemId) {
+  if (activeItemId != null) {
+    return resolveRequestedItemId(activeItemId, items, isFocusable);
+  }
+  return resolveDefaultItemId(items, isFocusable, getDefaultActiveItemId);
+}
+
+/**
+ * Resolves the item id supplied through the root hook's `activeItemId` option.
+ *
+ * This path is used when a component such as `Tabs` or `MenuList` wants roving focus to
+ * follow a specific logical item. For example, `Tabs` can pass the selected tab's value as
+ * `activeItemId` so that the selected tab owns `tabIndex=0` when focus enters the list.
+ *
+ * @param requestedItemId The item id passed to the root hook's `activeItemId` option.
+ * @param items The ordered registered items currently in the roving set.
+ * @param isFocusable A predicate that decides whether an item may receive roving focus.
+ * @returns The same id when it still points to a focusable item. If that id no longer exists,
+ *   returns the first focusable item. If the id still exists but the item is not focusable,
+ *   returns the next focusable item after it without wrapping.
+ */
+function resolveRequestedItemId(requestedItemId, items, isFocusable) {
+  const requestedItemIndex = findItemIndexById(items, requestedItemId);
+  if (requestedItemIndex === -1) {
+    return getFirstFocusableItemId(items, isFocusable);
+  }
+  if (isFocusable(items[requestedItemIndex])) {
+    return items[requestedItemIndex].id;
+  }
+  return getNextActiveItem(items, requestedItemIndex, 'next', false, isFocusable)?.id ?? null;
+}
+
+/**
+ * Resolves the default active item when the caller is not driving roving focus with
+ * `activeItemId`.
+ *
+ * This path is used on the initial render and whenever the caller leaves the choice of tab
+ * stop to the hook. `getDefaultActiveItemId` lets a component prefer a specific logical item
+ * before falling back to the first focusable item.
+ *
+ * For example:
+ * - `MenuList` uses this path all the time. When `variant="selectedMenu"`, it prefers the
+ *   selected menu item; otherwise it prefers the first focusable menu item.
+ * - `Tabs` uses this path while focus is already inside the tab list, because at that point
+ *   the current roving position should be driven by actual focus movement rather than by the
+ *   selected tab value.
+ *
+ * @param items The ordered registered items currently in the roving set.
+ * @param isFocusable A predicate that decides whether an item may receive roving focus.
+ * @param getDefaultActiveItemId Optional caller-provided function that chooses which item
+ *   should own the tab stop before the generic "first focusable item" fallback runs.
+ * @returns The default item id when it points to a focusable item, otherwise the first
+ *   focusable item in the snapshot, or `null` when none are focusable.
+ */
+function resolveDefaultItemId(items, isFocusable, getDefaultActiveItemId) {
+  const defaultItemId = getDefaultActiveItemId?.(items);
+  if (defaultItemId != null) {
+    const defaultItem = getItemById(items, defaultItemId);
+    if (defaultItem && isFocusable(defaultItem)) {
+      return defaultItem.id;
+    }
+  }
+  return getFirstFocusableItemId(items, isFocusable);
+}
+
+/**
+ * Finds the best starting index for keyboard navigation.
+ *
+ * This is used immediately before keyboard navigation and `focusNext()` navigation. It prefers
+ * the item that currently holds DOM focus, but if focus is on the container or outside the item
+ * set it falls back to the last known active item id.
+ *
+ * @param items The navigable item snapshot used for the current keyboard interaction.
+ * @param currentFocus The element that currently has DOM focus, if any.
+ * @param fallbackActiveItemId The last known active item id when focus is not on an item.
+ * @returns The focused item's index when focus is currently on an item. Otherwise, the index
+ *   of the fallback active item id, or `-1` when no matching item exists.
+ */
+function getCurrentActiveItemIndex(items, currentFocus, fallbackActiveItemId) {
+  if (currentFocus) {
+    const focusedIndex = findItemIndexByElement(items, currentFocus);
+    if (focusedIndex !== -1) {
+      return focusedIndex;
+    }
+  }
+  return findItemIndexById(items, fallbackActiveItemId);
+}
+
+/**
+ * Walks the item snapshot to find the next focusable item in the requested direction.
+ *
+ * This is the shared navigation primitive used by keyboard handling and imperative helpers
+ * such as `focusNext()`. It starts from the supplied index, advances through the snapshot in
+ * the requested direction, and skips over items that fail the `isFocusable` predicate.
+ *
+ * @param items The ordered navigable item snapshot.
+ * @param currentIndex The index to start from. Use `-1` to start before the first item or
+ *   `items.length` to start after the last item.
+ * @param direction The direction to move through the snapshot.
+ * @param wrap Whether navigation should wrap around at the ends of the list.
+ * @param isFocusable A predicate that decides whether an item may receive roving focus.
+ * @returns The next focusable item record, or `null` when no focusable item can be reached.
+ */
+function getNextActiveItem(items, currentIndex, direction, wrap, isFocusable) {
+  const lastIndex = items.length - 1;
+  if (lastIndex === -1) {
+    return null;
+  }
   let wrappedOnce = false;
   let nextIndex = getNextIndex(currentIndex, lastIndex, direction, wrap);
   const startIndex = nextIndex;
   while (nextIndex !== -1) {
-    // Prevent infinite loop.
     if (nextIndex === startIndex) {
       if (wrappedOnce) {
-        return -1;
+        return null;
       }
       wrappedOnce = true;
     }
-    const nextElement = elementsRef.current[nextIndex];
-
-    // Same logic as useAutocomplete.js
-    if (!shouldFocus(nextElement)) {
-      // Move to the next element.
+    const nextItem = items[nextIndex];
+    if (!nextItem || !isFocusable(nextItem)) {
       nextIndex = getNextIndex(nextIndex, lastIndex, direction, wrap);
     } else {
-      nextElement?.focus();
-      return nextIndex;
+      return nextItem;
     }
   }
-  return -1;
+  return null;
+}
+function getFirstFocusableItemId(items, isFocusable) {
+  return items.find(item => isFocusable(item))?.id ?? null;
+}
+function getItemById(items, itemId) {
+  return itemId == null ? null : items.find(item => item.id === itemId) ?? null;
+}
+function findItemIndexById(items, itemId) {
+  return itemId == null ? -1 : items.findIndex(item => item.id === itemId);
+}
+function findItemIndexByElement(items, element) {
+  if (!element) {
+    return -1;
+  }
+  return items.findIndex(item => item.element === element || item.element?.contains(element));
+}
+function getOrderedItems(itemMap) {
+  const items = Array.from(itemMap.values());
+  if (items.every(item => item.element == null)) {
+    return items;
+  }
+  const connectedItems = items.filter(isConnectedItem).sort((itemA, itemB) => sortByDocumentPosition(itemA.element, itemB.element));
+  const disconnectedItems = items.filter(item => !isConnectedItem(item));
+  return [...connectedItems, ...disconnectedItems];
+}
+function getNavigableItemsSnapshot(itemMap) {
+  return getOrderedItems(itemMap).filter(isConnectedItem);
 }
 function getNextIndex(currentIndex, lastIndex, direction, wrap = true) {
   if (direction === 'next') {
@@ -171,20 +426,39 @@ function getNextIndex(currentIndex, lastIndex, direction, wrap = true) {
   }
   return currentIndex - 1;
 }
-function internalShouldFocus(element) {
-  if (!element) {
+export function isItemFocusable(item) {
+  if (!item.element) {
     return false;
   }
-  return !element.hasAttribute('disabled') && element.getAttribute('aria-disabled') !== 'true' && element.hasAttribute('tabindex');
+  if (item.focusableWhenDisabled) {
+    return true;
+  }
+  return !item.disabled && !item.element.hasAttribute('disabled') && item.element.getAttribute('aria-disabled') !== 'true' && item.element.hasAttribute('tabindex');
+}
+function isConnectedItem(item) {
+  return item.element != null && item.element.isConnected;
 }
+
+/* eslint-disable no-bitwise */
+function sortByDocumentPosition(a, b) {
+  if (a === b) {
+    return 0;
+  }
+  const position = a.compareDocumentPosition(b);
+  if (position & Node.DOCUMENT_POSITION_FOLLOWING || position & Node.DOCUMENT_POSITION_CONTAINED_BY) {
+    return -1;
+  }
+  if (position & Node.DOCUMENT_POSITION_PRECEDING || position & Node.DOCUMENT_POSITION_CONTAINS) {
+    return 1;
+  }
+  return 0;
+}
+/* eslint-enable no-bitwise */
+
 function handleRefs(...refs) {
   return node => {
     refs.forEach(ref => {
-      if (typeof ref === 'function') {
-        ref(node);
-      } else if (ref) {
-        ref.current = node;
-      }
+      setRef(ref ?? null, node);
     });
   };
 }