@lumx/react 4.8.1 → 4.9.0-next.0

package/index.js

@@ -10659,6 +10659,12 @@ Progress.displayName = COMPONENT_NAME$v;
 Progress.className = CLASSNAME$w;
 Progress.defaultProps = DEFAULT_PROPS$A;
 
+/**
+ * SSR-safe version of `useLayoutEffect`.
+ * Uses `useLayoutEffect` on the client and `useEffect` on the server to avoid React SSR warnings.
+ */
+const useIsomorphicLayoutEffect = typeof window !== 'undefined' ? useLayoutEffect : useEffect;
+
 const INIT_STATE = {
   isLazy: true,
   shouldActivateOnFocus: false,
@@ -10738,7 +10744,7 @@ const useTabProviderContext = (type, originalId) => {
   // Current tab or tab panel id.
   const generatedId = useId();
   const id = originalId || generatedId;
-  useEffect(() => {
+  useIsomorphicLayoutEffect(() => {
     // On mount: register tab or tab panel id.
     dispatch({
       type: 'register',
@@ -10838,77 +10844,341 @@ const ProgressTrackerProvider = props => {
 };
 ProgressTrackerProvider.defaultProps = DEFAULT_PROPS$z;
 
-const useRovingTabIndex = ({
-  parentRef,
-  elementSelector,
-  keepTabIndex,
-  onElementFocus,
-  extraDependencies = []
-}) => {
-  useEffect(() => {
-    const parent = parentRef?.current;
-    if (!parent) {
-      return undefined;
+/**
+ * Internal state for tracking the active (focused) item.
+ * Shared by both list and grid navigation implementations.
+ */
+
+/**
+ * Create shared active item state with cleanup on abort.
+ *
+ * Callback invocation:
+ * - `setActive(item)`: calls `onDeactivate(previous)` then `onActivate(item)`.
+ * - `clear()`: calls `onDeactivate(current)` then `onClear()`.
+ * - On `signal.abort()`: same as `clear()`.
+ *
+ * @param callbacks Focus state change callbacks.
+ * @param signal AbortSignal for cleanup.
+ * @param initialItem Optional item to silently pre-select on creation (no callbacks fired).
+ */
+function createActiveItemState(callbacks, signal, initialItem) {
+  let activeItem = initialItem ?? null;
+  function clear() {
+    if (activeItem) {
+      callbacks.onDeactivate(activeItem);
+      activeItem = null;
     }
-    const elements = parent.querySelectorAll(elementSelector);
-    const initialFocusableElement = parent?.querySelector(`${elementSelector}[tabindex="0"]`);
-    const handleKeyDown = index => evt => {
-      let newTabFocus = index;
-      if (!(evt.key === 'ArrowRight' || evt.key === 'ArrowLeft')) {
-        return;
+    callbacks.onClear?.();
+  }
+  signal.addEventListener('abort', clear);
+  return {
+    get active() {
+      return activeItem;
+    },
+    setActive(item) {
+      if (activeItem === item) return;
+      if (activeItem) {
+        callbacks.onDeactivate(activeItem);
       }
-      if (evt.key === 'ArrowRight') {
-        // Move right
-        newTabFocus += 1;
-        // If we're at the end, go to the start
-        if (newTabFocus >= elements.length) {
-          newTabFocus = 0;
-        }
-      } else if (evt.key === 'ArrowLeft') {
-        // Move left
-        newTabFocus -= 1;
-        if (newTabFocus < 0) {
-          // If we're at the start, move to the end
-          newTabFocus = elements.length - 1;
-        }
+      activeItem = item;
+      if (item) {
+        callbacks.onActivate(item);
+      }
+    },
+    clear
+  };
+}
+
+/**
+ * Create a focus navigation controller for a 1D list.
+ *
+ * @param options List navigation options (container, itemSelector, direction, wrap).
+ * @param callbacks Callbacks for focus state changes.
+ * @param signal AbortSignal for cleanup.
+ * @returns FocusNavigationController instance.
+ */
+function createListFocusNavigation(options, callbacks, signal) {
+  const {
+    container,
+    itemSelector,
+    direction = 'vertical',
+    wrap = false,
+    itemDisabledSelector,
+    itemActiveSelector
+  } = options;
+  const initialItem = itemActiveSelector ? container.querySelector(itemActiveSelector) ?? null : null;
+  const state = createActiveItemState(callbacks, signal, initialItem);
+
+  /** Combined CSS selector matching enabled (non-disabled) items. */
+  const enabledItemSelector = itemDisabledSelector ? `${itemSelector}:not(${itemDisabledSelector})` : itemSelector;
+
+  /**
+   * Create a TreeWalker over items in the container.
+   * @param enabledOnly When true (default), disabled items are skipped.
+   */
+  function createItemWalker(enabledOnly = true) {
+    const selector = enabledOnly ? enabledItemSelector : itemSelector;
+    return document.createTreeWalker(container, NodeFilter.SHOW_ELEMENT, {
+      acceptNode(node) {
+        return node.matches(selector) ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP;
       }
-      const newElement = elements[newTabFocus];
-      newElement?.focus();
+    });
+  }
+
+  /** Find the first enabled item in the container. */
+  function findFirstEnabled() {
+    return container.querySelector(enabledItemSelector);
+  }
+
+  /** Find the last enabled item in the container. */
+  function findLastEnabled() {
+    const items = container.querySelectorAll(enabledItemSelector);
+    return items.length > 0 ? items[items.length - 1] : null;
+  }
+
+  /** Navigate to the first enabled item and set it as active. */
+  function goToFirst() {
+    const first = findFirstEnabled();
+    if (!first) return false;
+    state.setActive(first);
+    return true;
+  }
 
-      // When an element is focused using roving tab index, trigger the onElementFocus callback
-      if (newElement && onElementFocus) {
-        onElementFocus(newElement);
+  /** Navigate to the last enabled item and set it as active. */
+  function goToLast() {
+    const last = findLastEnabled();
+    if (!last) return false;
+    state.setActive(last);
+    return true;
+  }
+  function navigateByOffset(offset) {
+    if (offset === 0) return state.active !== null;
+    const forward = offset > 0;
+    const stepsNeeded = Math.abs(offset);
+
+    // No active item — try to recover from DOM state, then fall back to first/last.
+    if (!state.active) {
+      const activeFromDom = itemActiveSelector && container.querySelector(itemActiveSelector);
+      if (activeFromDom && activeFromDom.matches(enabledItemSelector)) {
+        state.setActive(activeFromDom);
+      } else {
+        const started = forward ? goToFirst() : goToLast();
+        if (!started) return false;
       }
-      if (keepTabIndex) {
-        evt.currentTarget.setAttribute('tabindex', '-1');
-        newElement?.setAttribute('tabindex', '0');
+      if (stepsNeeded === 1) return true;
+      return navigateByOffset(forward ? offset - 1 : offset + 1);
+    }
+
+    // Walk from the active item using a TreeWalker.
+    const walker = createItemWalker();
+    walker.currentNode = state.active;
+    const step = forward ? () => walker.nextNode() : () => walker.previousNode();
+    let stepsCompleted = 0;
+    let lastFound = null;
+    for (let i = 0; i < stepsNeeded; i++) {
+      const next = step();
+      if (next) {
+        lastFound = next;
+        stepsCompleted += 1;
+      } else if (wrap) {
+        // Hit boundary — wrap around to the opposite end.
+        const wrapped = forward ? findFirstEnabled() : findLastEnabled();
+        if (!wrapped || wrapped === state.active) break;
+        lastFound = wrapped;
+        stepsCompleted += 1;
+        walker.currentNode = wrapped;
+      } else {
+        break;
       }
-    };
-    if (elements?.length > 0) {
-      elements.forEach((el, key) => {
-        // if no element has tabindex set to 0, set the first element as focusable
-        if (!initialFocusableElement && key === 0) {
-          el.setAttribute('tabindex', '0');
-          // set all other to -1
-        } else if (initialFocusableElement !== el) {
-          el.setAttribute('tabindex', '-1');
+    }
+    if (stepsCompleted === 0) return false;
+    state.setActive(lastFound);
+    return true;
+  }
+  const navigateForward = () => navigateByOffset(1);
+  const navigateBackward = () => navigateByOffset(-1);
+  return {
+    type: 'list',
+    get activeItem() {
+      return state.active;
+    },
+    get hasActiveItem() {
+      return state.active !== null;
+    },
+    get hasNavigableItems() {
+      return container.querySelector(enabledItemSelector) !== null;
+    },
+    goToFirst,
+    goToLast,
+    goToItem(item) {
+      if (!item.matches(itemSelector)) return false;
+      if (!container.contains(item)) return false;
+      state.setActive(item);
+      return true;
+    },
+    goToOffset(offset) {
+      return navigateByOffset(offset);
+    },
+    goToItemMatching(predicate) {
+      const walker = createItemWalker(false);
+      let node = walker.nextNode();
+      while (node) {
+        if (predicate(node)) {
+          state.setActive(node);
+          return true;
         }
-        // add event listener
-        el.addEventListener('keydown', handleKeyDown(key));
-      });
+        node = walker.nextNode();
+      }
+      return false;
+    },
+    clear: state.clear,
+    goUp() {
+      return direction === 'vertical' ? navigateBackward() : false;
+    },
+    goDown() {
+      return direction === 'vertical' ? navigateForward() : false;
+    },
+    goLeft() {
+      return direction === 'horizontal' ? navigateBackward() : false;
+    },
+    goRight() {
+      return direction === 'horizontal' ? navigateForward() : false;
     }
+  };
+}
 
-    // Cleanup listeners
-    return () => {
-      if (elements?.length > 0) {
-        elements.forEach((el, key) => {
-          el.removeEventListener('keydown', handleKeyDown(key));
-        });
+/**
+ * Options for the roving tabindex setup.
+ */
+
+/**
+ * Set up the roving tabindex pattern on a container element.
+ *
+ * Handles:
+ * - Keyboard navigation (Arrow keys, Home, End) via a keydown listener on the container
+ * - tabindex management on focus changes (`0` on active, `-1` on inactive)
+ * - Calling `.focus()` on the newly active item
+ *
+ * The consumer is responsible for setting the initial tabindex values on items
+ * (`tabindex="0"` on the active item, `tabindex="-1"` on the rest). On setup, the item
+ * with `tabindex="0"` is silently adopted as the initial active item.
+ *
+ * The setup is torn down when the provided `signal` is aborted.
+ *
+ * @param options  Roving tabindex configuration.
+ * @param signal   AbortSignal for teardown.
+ * @returns The underlying {@link FocusNavigationController} for programmatic access.
+ */
+function setupRovingTabIndex(options, signal) {
+  const {
+    container,
+    itemSelector,
+    direction = 'horizontal',
+    itemDisabledSelector,
+    onItemFocused
+  } = options;
+  const nav = createListFocusNavigation({
+    container,
+    itemSelector,
+    direction,
+    wrap: true,
+    itemDisabledSelector,
+    itemActiveSelector: `${itemSelector}[tabindex="0"]`
+  }, {
+    onActivate(item) {
+      item.setAttribute('tabindex', '0');
+      item.focus();
+      onItemFocused?.(item);
+    },
+    onDeactivate(item) {
+      item.setAttribute('tabindex', '-1');
+    }
+  }, signal);
+  container.addEventListener('keydown', evt => {
+    // Clear stale reference if the active item was removed from the DOM.
+    if (nav.hasActiveItem && !nav.activeItem?.isConnected) {
+      nav.clear();
+    }
+
+    // Sync: if nothing is active yet, pick up focus from the event target.
+    if (!nav.hasActiveItem) {
+      const target = evt.target;
+      if (target.matches(itemSelector) && container.contains(target)) {
+        nav.goToItem(target);
       }
-    };
-  },
+    }
+    let handled = false;
+    switch (evt.key) {
+      case 'ArrowRight':
+        handled = nav.goRight();
+        break;
+      case 'ArrowLeft':
+        handled = nav.goLeft();
+        break;
+      case 'ArrowDown':
+        handled = nav.goDown();
+        break;
+      case 'ArrowUp':
+        handled = nav.goUp();
+        break;
+      case 'Home':
+        handled = nav.goToFirst();
+        break;
+      case 'End':
+        handled = nav.goToLast();
+        break;
+    }
+    if (handled) {
+      evt.preventDefault();
+      evt.stopPropagation();
+    }
+  }, {
+    signal
+  });
+  return nav;
+}
+
+/**
+ * Returns a stable callback that always calls the latest version of `fn`.
+ * Useful to avoid re-running effects when a callback prop changes reference.
+ *
+ * https://github.com/facebook/react/issues/14099#issuecomment-440013892
+ *
+ * @param fn A function to stabilize.
+ * @return A stable function with the same signature.
+ */
+function useEventCallback(fn) {
+  const ref = React__default.useRef(fn);
+  useIsomorphicLayoutEffect(() => {
+    ref.current = fn;
+  });
   // eslint-disable-next-line react-hooks/exhaustive-deps
-  [parentRef, ...extraDependencies]);
+  return React__default.useCallback((...args) => ref.current?.(...args), []);
+}
+
+const useRovingTabIndexContainer = ({
+  containerRef,
+  itemSelector,
+  onItemFocused: unstableOnItemFocused,
+  direction,
+  itemDisabledSelector
+}) => {
+  const onItemFocused = useEventCallback(unstableOnItemFocused);
+  useIsomorphicLayoutEffect(() => {
+    const container = containerRef?.current;
+    if (!container) {
+      return undefined;
+    }
+    const abortController = new AbortController();
+    setupRovingTabIndex({
+      container,
+      itemSelector,
+      direction,
+      itemDisabledSelector,
+      onItemFocused
+    }, abortController.signal);
+    return () => abortController.abort();
+  }, [containerRef, itemSelector, direction, itemDisabledSelector, onItemFocused]);
 };
 
 /**
@@ -10947,11 +11217,9 @@ const ProgressTracker = forwardRef((props, ref) => {
     ...forwardedProps
   } = props;
   const stepListRef = React__default.useRef(null);
-  useRovingTabIndex({
-    parentRef: stepListRef,
-    elementSelector: '[role="tab"]',
-    keepTabIndex: false,
-    extraDependencies: [children]
+  useRovingTabIndexContainer({
+    containerRef: stepListRef,
+    itemSelector: '[role="tab"]'
   });
   const state = useTabProviderContextState();
   const numberOfSteps = state?.ids?.tab?.length || 0;
@@ -12251,22 +12519,6 @@ SkeletonTypography.displayName = COMPONENT_NAME$j;
 SkeletonTypography.defaultProps = DEFAULT_PROPS$n;
 SkeletonTypography.className = CLASSNAME$j;
 
-const useEnhancedEffect = typeof window !== 'undefined' ? React__default.useLayoutEffect : React__default.useEffect;
-
-/**
- * https://github.com/facebook/react/issues/14099#issuecomment-440013892
- *
- * @param fn A function to run
- * @return A React callback
- */
-function useEventCallback(fn) {
-  const ref = React__default.useRef(fn);
-  useEnhancedEffect(() => {
-    ref.current = fn;
-  });
-  return React__default.useCallback(event => ref.current(event), []);
-}
-
 /**
  * Clamp value in range.
  *
@@ -13212,11 +13464,10 @@ const InternalSlideshowControls = forwardRef((props, ref) => {
   /**
    * Add roving tab index pattern to pagination items and activate slide on focus.
    */
-  useRovingTabIndex({
-    parentRef: paginationRef,
-    elementSelector: 'button',
-    keepTabIndex: true,
-    onElementFocus: el => {
+  useRovingTabIndexContainer({
+    containerRef: paginationRef,
+    itemSelector: 'button',
+    onItemFocused: el => {
       el.click();
     }
   });
@@ -14145,7 +14396,11 @@ const TabProvider = props => {
     onChange,
     ...propState
   } = props;
-  const [state, dispatch] = useReducer(reducer, INIT_STATE);
+  const [state, dispatch] = useReducer(reducer, {
+    ...INIT_STATE,
+    ...DEFAULT_PROPS$c,
+    ...propState
+  });
 
   // On prop state change => dispatch update.
   useEffect(() => {
@@ -14236,11 +14491,9 @@ const TabList = forwardRef((props, ref) => {
     ...forwardedProps
   } = props;
   const tabListRef = React__default.useRef(null);
-  useRovingTabIndex({
-    parentRef: tabListRef,
-    elementSelector: '[role="tab"]',
-    keepTabIndex: false,
-    extraDependencies: [children]
+  useRovingTabIndexContainer({
+    containerRef: tabListRef,
+    itemSelector: '[role="tab"]'
   });
   return /*#__PURE__*/jsx("div", {
     ref: mergeRefs(ref, tabListRef),