@lumx/react 4.11.0-next.0 → 4.11.0-next.2

package/index.js

@@ -2554,51 +2554,6 @@ function notifySection(sectionElement, sectionRegistrations, optionRegistrations
   }
 }
 
-/**
- * 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;
-    }
-    callbacks.onClear?.();
-  }
-  signal.addEventListener('abort', clear);
-  return {
-    get active() {
-      return activeItem;
-    },
-    setActive(item) {
-      if (activeItem === item) return;
-      if (activeItem) {
-        callbacks.onDeactivate(activeItem);
-      }
-      activeItem = item;
-      if (item) {
-        callbacks.onActivate(item);
-      }
-    },
-    clear
-  };
-}
-
 /**
  * Create a TreeWalker that iterates over elements matching a CSS selector
  * within a container.
@@ -2619,13 +2574,29 @@ function createSelectorTreeWalker(container, selector) {
   });
 }
 
+/**
+ * Transition the active item: deactivate the current one (if any) and activate the new one.
+ * Reads the current active item via `getActiveItem` so there is no internal state to desync.
+ */
+function transition(getActiveItem, callbacks, newItem) {
+  const current = getActiveItem();
+  if (current === newItem) return;
+  if (current) callbacks.onDeactivate(current);
+  callbacks.onActivate(newItem);
+}
+
 /**
  * Create a focus navigation controller for a 1D list.
  *
- * @param options List navigation options (container, itemSelector, direction, wrap).
+ * This controller is **stateless** — it does not maintain an internal reference to
+ * the active item. Instead it reads the active item from the DOM each time via the
+ * `getActiveItem` callback provided in the options. This avoids any desync between
+ * the controller's internal state and the actual DOM.
+ *
+ * @param options List navigation options (container, itemSelector, direction, wrap, getActiveItem).
  * @param callbacks Callbacks for focus state changes.
  * @param signal AbortSignal for cleanup.
- * @returns FocusNavigationController instance.
+ * @returns ListFocusNavigationController instance.
  */
 function createListFocusNavigation(options, callbacks, signal) {
   const {
@@ -2634,10 +2605,8 @@ function createListFocusNavigation(options, callbacks, signal) {
     direction = 'vertical',
     wrap = false,
     itemDisabledSelector,
-    itemActiveSelector
+    getActiveItem = () => null
   } = 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;
@@ -2662,42 +2631,38 @@ function createListFocusNavigation(options, callbacks, signal) {
     return items.length > 0 ? items[items.length - 1] : null;
   }
 
-  /** Navigate to the first enabled item and set it as active. */
+  /** Navigate to the first enabled item and activate it. */
   function goToFirst() {
     const first = findFirstEnabled();
     if (!first) return false;
-    state.setActive(first);
+    transition(getActiveItem, callbacks, first);
     return true;
   }
 
-  /** Navigate to the last enabled item and set it as active. */
+  /** Navigate to the last enabled item and activate it. */
   function goToLast() {
     const last = findLastEnabled();
     if (!last) return false;
-    state.setActive(last);
+    transition(getActiveItem, callbacks, last);
     return true;
   }
   function navigateByOffset(offset) {
-    if (offset === 0) return state.active !== null;
+    const active = getActiveItem();
+    if (offset === 0) return 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;
-      }
+    // No active item — fall back to first/last.
+    if (!active) {
+      const started = forward ? goToFirst() : goToLast();
+      if (!started) return false;
       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;
+    walker.currentNode = active;
     const step = forward ? () => walker.nextNode() : () => walker.previousNode();
     let stepsCompleted = 0;
     let lastFound = null;
@@ -2709,7 +2674,7 @@ function createListFocusNavigation(options, callbacks, signal) {
       } else if (wrap) {
         // Hit boundary — wrap around to the opposite end.
         const wrapped = forward ? findFirstEnabled() : findLastEnabled();
-        if (!wrapped || wrapped === state.active) break;
+        if (!wrapped || wrapped === active) break;
         lastFound = wrapped;
         stepsCompleted += 1;
         walker.currentNode = wrapped;
@@ -2718,18 +2683,31 @@ function createListFocusNavigation(options, callbacks, signal) {
       }
     }
     if (stepsCompleted === 0) return false;
-    state.setActive(lastFound);
+    transition(getActiveItem, callbacks, lastFound);
     return true;
   }
   const navigateForward = () => navigateByOffset(1);
   const navigateBackward = () => navigateByOffset(-1);
+
+  /** Clear the active item. */
+  function clear() {
+    const current = getActiveItem();
+    if (current) {
+      callbacks.onDeactivate(current);
+    }
+    callbacks.onClear?.();
+  }
+
+  // Cleanup on abort.
+  signal.addEventListener('abort', clear);
   return {
     type: 'list',
+    enabledItemSelector,
     get activeItem() {
-      return state.active;
+      return getActiveItem();
     },
     get hasActiveItem() {
-      return state.active !== null;
+      return getActiveItem() !== null;
     },
     get hasNavigableItems() {
       return container.querySelector(enabledItemSelector) !== null;
@@ -2739,7 +2717,7 @@ function createListFocusNavigation(options, callbacks, signal) {
     goToItem(item) {
       if (!item.matches(itemSelector)) return false;
       if (!container.contains(item)) return false;
-      state.setActive(item);
+      transition(getActiveItem, callbacks, item);
       return true;
     },
     goToOffset(offset) {
@@ -2750,14 +2728,32 @@ function createListFocusNavigation(options, callbacks, signal) {
       let node = walker.nextNode();
       while (node) {
         if (predicate(node)) {
-          state.setActive(node);
+          transition(getActiveItem, callbacks, node);
           return true;
         }
         node = walker.nextNode();
       }
       return false;
     },
-    clear: state.clear,
+    findNearestEnabled(anchor) {
+      if (!container.contains(anchor)) return findFirstEnabled();
+
+      // If the anchor itself is an enabled item, return it directly.
+      if (anchor instanceof HTMLElement && anchor.matches(enabledItemSelector)) {
+        return anchor;
+      }
+
+      // Walk forward from the anchor for the nearest enabled item.
+      const walker = createItemWalker();
+      walker.currentNode = anchor;
+      const next = walker.nextNode();
+      if (next instanceof HTMLElement) return next;
+
+      // No enabled item after anchor — walk backward (reuse same walker).
+      walker.currentNode = anchor;
+      return walker.previousNode();
+    },
+    clear,
     goUp() {
       return direction === 'vertical' ? navigateBackward() : false;
     },
@@ -2773,6 +2769,51 @@ function createListFocusNavigation(options, callbacks, signal) {
   };
 }
 
+/**
+ * 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;
+    }
+    callbacks.onClear?.();
+  }
+  signal.addEventListener('abort', clear);
+  return {
+    get active() {
+      return activeItem;
+    },
+    setActive(item) {
+      if (activeItem === item) return;
+      if (activeItem) {
+        callbacks.onDeactivate(activeItem);
+      }
+      activeItem = item;
+      if (item) {
+        callbacks.onActivate(item);
+      }
+    },
+    clear
+  };
+}
+
 /**
  * Create a focus navigation controller for a 2D grid.
  *
@@ -3021,26 +3062,65 @@ function createGridFocusNavigation(options, callbacks, signal) {
 }
 
 /**
- * Options for the roving tabindex setup.
+ * Like `querySelectorAll`, but also tests the root node itself.
+ *
+ * Yields the root element first (if it matches), then all matching descendants
+ * in document order. Being a generator, callers that only need the first match
+ * can break early without collecting the full list.
+ *
+ * @param node  The starting DOM node.
+ * @param selector  CSS selector to match against.
  */
+function* querySelectorInclusive(node, selector) {
+  if (!(node instanceof HTMLElement)) return;
+  if (node.matches(selector)) yield node;
+  yield* node.querySelectorAll(selector);
+}
 
 /**
- * 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
+ * Track whether the container currently has focus.
  *
- * 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.
+ * We can't rely on `document.activeElement` inside MutationObserver callbacks because
+ * the browser moves focus to `<body>` before they fire. focusout with `relatedTarget === null`
+ * (element removed from DOM) keeps the flag true so the observer can move focus to a fallback.
+ */
+function trackContainerFocus(container, signal) {
+  let hasFocus = container.contains(document.activeElement);
+  container.addEventListener('focusin', () => {
+    hasFocus = true;
+  }, {
+    signal
+  });
+  container.addEventListener('focusout', evt => {
+    const newTarget = evt.relatedTarget;
+    if (newTarget && !container.contains(newTarget)) {
+      hasFocus = false;
+    }
+  }, {
+    signal
+  });
+  return {
+    get hasFocus() {
+      return hasFocus;
+    },
+    reset() {
+      hasFocus = false;
+    }
+  };
+}
+
+/** Options for {@link setupRovingTabIndex}. */
+
+/**
+ * Set up the roving tabindex pattern on a container element.
  *
- * The setup is torn down when the provided `signal` is aborted.
+ * - Keyboard navigation (Arrow keys, Home, End)
+ * - tabindex management (`0` on active, `-1` on others)
+ * - Mount normalization (single-tabstop invariant)
+ * - DOM mutation handling via MutationObserver:
+ *   removal recovery, insertion normalization, disabled-state changes
  *
- * @param options  Roving tabindex configuration.
- * @param signal   AbortSignal for teardown.
- * @returns The underlying {@link FocusNavigationController} for programmatic access.
+ * Torn down when `signal` is aborted.
  */
 function setupRovingTabIndex(options, signal) {
   const {
@@ -3048,15 +3128,24 @@ function setupRovingTabIndex(options, signal) {
     itemSelector,
     direction = 'horizontal',
     itemDisabledSelector,
+    itemSelectedAttr = 'aria-selected',
     onItemFocused
   } = options;
+  const itemActiveSelector = `${itemSelector}[tabindex="0"]`;
+
+  // Item selected selector
+  let itemSelectedSelector = `${itemSelector}[${itemSelectedAttr}=true]`;
+  if (itemDisabledSelector) itemSelectedSelector += `:not(${itemDisabledSelector})`;
+
+  // Track focus inside container
+  const containerFocus = trackContainerFocus(container, signal);
   const nav = createListFocusNavigation({
     container,
     itemSelector,
     direction,
     wrap: true,
     itemDisabledSelector,
-    itemActiveSelector: `${itemSelector}[tabindex="0"]`
+    getActiveItem: () => container.querySelector(itemActiveSelector)
   }, {
     onActivate(item) {
       item.setAttribute('tabindex', '0');
@@ -3067,14 +3156,163 @@ function setupRovingTabIndex(options, signal) {
       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();
+
+  // ─── tabindex normalization ────────────────────────────────────
+
+  /** Set tabindex only when the value actually changes to avoid unnecessary DOM mutations. */
+  function setTabIndex(item, value) {
+    if (item.getAttribute('tabindex') !== value) {
+      item.setAttribute('tabindex', value);
+    }
+  }
+
+  /** Assign tabindex across `items`, ensuring at most one `tabindex="0"` */
+  function normalizeItems(items, hasExistingTabStop) {
+    let hasTabStop = hasExistingTabStop;
+    for (const item of items) {
+      if (!container.contains(item)) continue;
+      const isDisabled = itemDisabledSelector ? item.matches(itemDisabledSelector) : false;
+      if (!isDisabled && !hasTabStop) {
+        setTabIndex(item, '0');
+        hasTabStop = true;
+      } else {
+        setTabIndex(item, '-1');
+      }
+    }
+    if (!hasTabStop) {
+      const fallback = container.querySelector(nav.enabledItemSelector);
+      if (fallback) setTabIndex(fallback, '0');
+    }
+  }
+
+  /** Enforce the single-tabstop invariant across all items. */
+  function normalizeAllItems() {
+    const items = Array.from(container.querySelectorAll(itemSelector));
+    const {
+      activeItem
+    } = nav;
+
+    // Prefer either the current active item (from DOM) or the current selected item
+    let preferredTabStopIndex = activeItem && items.indexOf(activeItem);
+    if (!preferredTabStopIndex || preferredTabStopIndex === -1) {
+      preferredTabStopIndex = items.findIndex(item => item.matches(itemSelectedSelector));
+    }
+    if (preferredTabStopIndex && preferredTabStopIndex > 0) {
+      const [preferredItem] = items.splice(preferredTabStopIndex, 1);
+      items.unshift(preferredItem);
+    }
+    normalizeItems(items, false);
+  }
+
+  /** Ensure a tab stop exists; find a fallback near `anchor` and optionally move focus to it. */
+  function ensureTabStop(shouldFocus, anchor) {
+    if (container.querySelector(itemActiveSelector)) return;
+    const fallback = (anchor && nav.findNearestEnabled(anchor)) ?? container.querySelector(nav.enabledItemSelector);
+    if (!fallback) return;
+    if (shouldFocus) {
+      nav.goToItem(fallback);
+    } else {
+      setTabIndex(fallback, '0');
+    }
+  }
+  normalizeAllItems();
+
+  // ─── MutationObserver ──────────────────────────────────────────
+
+  const observer = new MutationObserver(mutations => {
+    // Track removed
+    let removedActiveItem = null;
+    let removalAnchor = null;
+    // Track selected
+    let newSelectedItem = null;
+    // Track disabled
+    const disabledTargets = [];
+    // Track added
+    const insertedItems = [];
+    for (const mutation of mutations) {
+      if (mutation.type === 'childList') {
+        // Track removed — scan removed nodes for the active item (tabindex="0").
+        // We cannot gate this on a live DOM query because the item is already removed.
+        if (!removedActiveItem) {
+          for (const removedNode of mutation.removedNodes) {
+            const {
+              value: firstMatch
+            } = querySelectorInclusive(removedNode, itemActiveSelector).next();
+            if (firstMatch) {
+              removedActiveItem = firstMatch;
+              removalAnchor = mutation.nextSibling ?? mutation.previousSibling ?? null;
+              break;
+            }
+          }
+        }
+
+        // Track added
+        for (const addedNode of mutation.addedNodes) {
+          for (const item of querySelectorInclusive(addedNode, itemSelector)) {
+            insertedItems.push(item);
+          }
+        }
+      }
+      const target = mutation.target;
+      if (mutation.type === 'attributes' && target.matches(itemSelector)) {
+        if (mutation.attributeName === itemSelectedAttr && target.getAttribute(itemSelectedAttr) === 'true') {
+          // Track selected item
+          newSelectedItem = target;
+        } else if (itemDisabledSelector && target.matches(itemDisabledSelector)) {
+          // Track disabled items
+          disabledTargets.push(target);
+        }
+      }
+    }
+
+    // Handle removed item
+    if (removedActiveItem) {
+      const shouldMoveFocus = containerFocus.hasFocus;
+      containerFocus.reset();
+      ensureTabStop(shouldMoveFocus, removalAnchor);
+    }
+
+    // Handle inserted items
+    if (insertedItems.length > 0) {
+      const hasTabStop = container.querySelector(itemActiveSelector) !== null;
+      normalizeItems(insertedItems, hasTabStop);
     }
 
-    // Sync: if nothing is active yet, pick up focus from the event target.
-    if (!nav.hasActiveItem) {
+    // Handle disabled
+    if (disabledTargets.length > 0) {
+      const currentActive = nav.activeItem;
+      for (const target of disabledTargets) {
+        setTabIndex(target, '-1');
+      }
+      const activeItemDisabled = currentActive && disabledTargets.includes(currentActive);
+      const shouldFocus = !!(activeItemDisabled && containerFocus.hasFocus);
+      ensureTabStop(shouldFocus);
+    }
+
+    // Handle selected
+    if (newSelectedItem) {
+      // Demote previous item
+      const currentTabStop = container.querySelector(itemActiveSelector);
+      if (currentTabStop && currentTabStop !== newSelectedItem) {
+        setTabIndex(currentTabStop, '-1');
+      }
+      // Selected item is the new default focuable item
+      setTabIndex(newSelectedItem, '0');
+    }
+  });
+  observer.observe(container, {
+    childList: true,
+    subtree: true,
+    attributes: true,
+    attributeFilter: ['aria-disabled', 'disabled', itemSelectedAttr]
+  });
+  signal.addEventListener('abort', () => observer.disconnect());
+
+  // ─── Keyboard navigation ───────────────────────────────────────
+
+  container.addEventListener('keydown', evt => {
+    // Adopt focus target if nothing is active yet.
+    if (!nav.activeItem) {
       const target = evt.target;
       if (target.matches(itemSelector) && container.contains(target)) {
         nav.goToItem(target);
@@ -3170,7 +3408,11 @@ function setupListbox(handle, signal, notify) {
       container: listbox,
       // Filtered options don't render [role="option"] at all (they render only a
       // hidden placeholder), so no :not([data-filtered]) filter is needed here.
-      itemSelector: '[role="option"]'
+      itemSelector: '[role="option"]',
+      getActiveItem: () => {
+        const id = trigger.getAttribute('aria-activedescendant');
+        return id ? document.getElementById(id) : null;
+      }
     }, focusCallbacks, signal);
   }
 
@@ -15142,7 +15384,8 @@ const useRovingTabIndexContainer = ({
   itemSelector,
   onItemFocused: unstableOnItemFocused,
   direction,
-  itemDisabledSelector
+  itemDisabledSelector,
+  itemSelectedAttr
 }) => {
   const onItemFocused = useEventCallback(unstableOnItemFocused);
   useIsomorphicLayoutEffect(() => {
@@ -15156,10 +15399,11 @@ const useRovingTabIndexContainer = ({
       itemSelector,
       direction,
       itemDisabledSelector,
+      itemSelectedAttr,
       onItemFocused
     }, abortController.signal);
     return () => abortController.abort();
-  }, [containerRef, itemSelector, direction, itemDisabledSelector, onItemFocused]);
+  }, [containerRef, itemSelector, direction, itemDisabledSelector, itemSelectedAttr, onItemFocused]);
 };
 
 /**