@lumx/react 4.16.0-next.0 → 4.16.1-alpha.0

package/index.js

@@ -5325,15 +5325,25 @@ Tooltip.displayName = COMPONENT_NAME$1i;
 Tooltip.className = CLASSNAME$1h;
 Tooltip.defaultProps = DEFAULT_PROPS$12;
 
-/**
- * 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 pending navigation store; discards intent on abort. */
+function createPendingNavigation(signal) {
+  let pending = null;
+  const clear = () => {
+    pending = null;
+  };
+  signal.addEventListener('abort', clear);
+  return {
+    get hasPending() {
+      return pending !== null;
+    },
+    defer(navigate) {
+      pending = navigate;
+    },
+    flush() {
+      if (pending?.()) pending = null;
+    },
+    clear
+  };
 }
 
 /**
@@ -5362,10 +5372,7 @@ function createListFocusNavigation(options, callbacks, signal) {
   /** 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.
-   */
+  /** Create a TreeWalker over items in the container. */
   function createItemWalker(enabledOnly = true) {
     const selector = enabledOnly ? enabledItemSelector : itemSelector;
     return createSelectorTreeWalker(container, selector);
@@ -5382,110 +5389,76 @@ function createListFocusNavigation(options, callbacks, signal) {
     return items.length > 0 ? items[items.length - 1] : null;
   }
 
-  /** Navigate to the first enabled item and activate it. */
-  function goToFirst() {
-    const first = findFirstEnabled();
-    if (!first) return false;
-    transition(getActiveItem, callbacks, first);
-    return true;
-  }
+  // Deferred navigation intent (replayed once items are committed to the DOM)
+  const pending = createPendingNavigation(signal);
 
-  /** Navigate to the last enabled item and activate it. */
-  function goToLast() {
-    const last = findLastEnabled();
-    if (!last) return false;
-    transition(getActiveItem, callbacks, last);
-    return true;
-  }
-  function navigateByOffset(offset) {
-    const active = getActiveItem();
-    if (offset === 0) return active !== null;
+  /** Find item at offset (lazily walk nodes) */
+  function findAtOffset(offset) {
     const forward = offset > 0;
     const stepsNeeded = Math.abs(offset);
-
-    // 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 active = getActiveItem();
     const walker = createItemWalker();
-    walker.currentNode = active;
     const step = forward ? () => walker.nextNode() : () => walker.previousNode();
-    let stepsCompleted = 0;
-    let lastFound = null;
-    for (let i = 0; i < stepsNeeded; i++) {
+    let target = null;
+    let remaining = stepsNeeded;
+    if (active) {
+      // Walk from the active item.
+      walker.currentNode = active;
+    } else if (!forward) {
+      // Walking backward with no active item: position at the last enabled item
+      target = walker.lastChild();
+      if (!target) return null;
+      remaining -= 1;
+    }
+    for (let i = 0; i < remaining; i++) {
       const next = step();
       if (next) {
-        lastFound = next;
-        stepsCompleted += 1;
-      } else if (wrap) {
-        // Hit boundary — wrap around to the opposite end.
+        target = next;
+      } else if (active && wrap) {
+        // Hit boundary with an active item — wrap around to the opposite end.
         const wrapped = forward ? findFirstEnabled() : findLastEnabled();
         if (!wrapped || wrapped === active) break;
-        lastFound = wrapped;
-        stepsCompleted += 1;
+        target = wrapped;
         walker.currentNode = wrapped;
       } else {
         break;
       }
     }
-    if (stepsCompleted === 0) return false;
-    transition(getActiveItem, callbacks, lastFound);
-    return true;
+    return target;
+  }
+  function findMatching(predicate) {
+    const walker = createItemWalker(false);
+    let node = walker.nextNode();
+    while (node) {
+      if (predicate(node)) return node;
+      node = walker.nextNode();
+    }
+    return null;
   }
-  const navigateForward = () => navigateByOffset(1);
-  const navigateBackward = () => navigateByOffset(-1);
 
-  /** Clear the active item. */
+  /** Clear the active item and discard any pending navigation intent. */
   function clear() {
     const current = getActiveItem();
     if (current) {
       callbacks.onDeactivate(current);
     }
+    pending.clear();
     callbacks.onClear?.();
   }
 
   // Cleanup on abort.
   signal.addEventListener('abort', clear);
-  return {
-    type: 'list',
+  const selectors = {
     enabledItemSelector,
     get activeItem() {
       return getActiveItem();
     },
-    get hasActiveItem() {
-      return getActiveItem() !== null;
-    },
     get hasNavigableItems() {
       return container.querySelector(enabledItemSelector) !== null;
     },
-    goToFirst,
-    goToLast,
-    goToItem(item) {
-      if (!item.matches(itemSelector)) return false;
-      if (!container.contains(item)) return false;
-      transition(getActiveItem, callbacks, item);
-      return true;
-    },
-    goToOffset(offset) {
-      return navigateByOffset(offset);
-    },
-    goToItemMatching(predicate) {
-      const walker = createItemWalker(false);
-      let node = walker.nextNode();
-      while (node) {
-        if (predicate(node)) {
-          transition(getActiveItem, callbacks, node);
-          return true;
-        }
-        node = walker.nextNode();
-      }
-      return false;
-    },
+    getFirst: findFirstEnabled,
+    getLast: findLastEnabled,
+    getMatching: findMatching,
     findNearestEnabled(anchor) {
       if (!container.contains(anchor)) return findFirstEnabled();
 
@@ -5503,19 +5476,57 @@ function createListFocusNavigation(options, callbacks, signal) {
       // No enabled item after anchor — walk backward (reuse same walker).
       walker.currentNode = anchor;
       return walker.previousNode();
-    },
+    }
+  };
+
+  /**
+   * Navigate via a resolver. The resolver receives the selectors to find the target.
+   * If the target is valid, focus is committed (deactivate current, activate target).
+   * If the target is not resolvable yet, the intent is deferred for later replay.
+   */
+  function goTo(resolve) {
+    const target = resolve(selectors);
+    if (target && target.matches(itemSelector) && container.contains(target)) {
+      const current = getActiveItem();
+      if (current !== target) {
+        if (current) callbacks.onDeactivate(current);
+        callbacks.onActivate(target);
+      }
+      pending.clear();
+      return true;
+    }
+    // Target not resolvable yet (e.g. items not committed to the DOM) — defer
+    pending.defer(() => goTo(resolve));
+    return false;
+  }
+
+  /** Go to the item at the given offset from the active item. */
+  function goToOffset(offset) {
+    if (offset === 0) return getActiveItem() !== null;
+    const target = findAtOffset(offset);
+    if (!target) return false;
+    return goTo(() => target);
+  }
+  return {
+    type: 'list',
+    selectors,
+    goToOffset,
     clear,
+    goTo,
+    flushPendingNavigation() {
+      pending.flush();
+    },
     goUp() {
-      return direction === 'vertical' ? navigateBackward() : false;
+      return direction === 'vertical' ? goToOffset(-1) : false;
     },
     goDown() {
-      return direction === 'vertical' ? navigateForward() : false;
+      return direction === 'vertical' ? goToOffset(1) : false;
     },
     goLeft() {
-      return direction === 'horizontal' ? navigateBackward() : false;
+      return direction === 'horizontal' ? goToOffset(-1) : false;
     },
     goRight() {
-      return direction === 'horizontal' ? navigateForward() : false;
+      return direction === 'horizontal' ? goToOffset(1) : false;
     }
   };
 }
@@ -5565,13 +5576,32 @@ function createActiveItemState(callbacks, signal, initialItem) {
   };
 }
 
+/** Deepest last-child descendant of `el` (or `el` itself if it has no children). */
+function lastDescendant(element) {
+  let node = element;
+  while (node.lastElementChild) node = node.lastElementChild;
+  return node;
+}
+
+/** Return the first item of an iterable, or `null` if it is empty. */
+function first(iterable) {
+  const {
+    value,
+    done
+  } = iterable[Symbol.iterator]().next();
+  return done ? null : value;
+}
+
 /**
  * Create a focus navigation controller for a 2D grid.
  *
+ * Resolves rows and cells by querying the DOM and commits focus by updating the
+ * active-item state (which fires {@link FocusNavigationCallbacks}).
+ *
  * Supports Up/Down between rows (with column memory) and Left/Right between cells
  * (with wrapping across rows).
  *
- * @param options Grid navigation options (container, rowSelector, cellSelector, isRowVisible, wrap).
+ * @param options Grid navigation options (container, rowSelector, cellSelector, wrap).
  * @param callbacks Callbacks for focus state changes.
  * @param signal AbortSignal for cleanup.
  * @returns FocusNavigationController instance.
@@ -5581,89 +5611,46 @@ function createGridFocusNavigation(options, callbacks, signal) {
     container,
     rowSelector,
     cellSelector,
-    isRowVisible,
     wrap = false
   } = options;
   const state = createActiveItemState(callbacks, signal);
-  /** Remembered column index for Up/Down navigation (column memory). */
-  let rememberedCol = 0;
-
-  /** Check if a row element is visible (passes the isRowVisible filter). */
-  function isVisible(row) {
-    return !isRowVisible || isRowVisible(row);
-  }
-
-  /** Check if a row is navigable (visible with at least one cell). */
-  function isNavigableRow(row) {
-    return isVisible(row) && row.querySelector(cellSelector) !== null;
-  }
-
-  /** Create a TreeWalker scoped to row elements within the container. */
-  function createRowWalker() {
-    return createSelectorTreeWalker(container, rowSelector);
-  }
-
-  /**
-   * Iterate navigable rows from the container using a TreeWalker.
-   * - `'first'`: returns the first navigable row (or null).
-   * - `'last'`: returns the last navigable row (or null).
-   * - `'all'`: returns all navigable rows as an array.
-   */
-
-  function findVisibleRows(mode) {
-    const walker = createRowWalker();
-    if (mode === 'all') {
-      const result = [];
-      let node = walker.nextNode();
-      while (node) {
-        if (isNavigableRow(node)) result.push(node);
-        node = walker.nextNode();
-      }
-      return result;
-    }
-    let found = null;
-    let node = walker.nextNode();
-    while (node) {
-      if (isNavigableRow(node)) {
-        if (mode === 'first') return node;
-        found = node;
+  const isNavigableRow = row => row.querySelector(cellSelector) !== null;
+  const getFirstCell = row => row.querySelector(cellSelector);
+  const getRowCells = row => Array.from(row.querySelectorAll(cellSelector));
+
+  /** Lazily walk navigable rows from `start` in a `direction`, projecting each row through `dive`. */
+  function* findRows(start = 'first', direction = 'next', dive) {
+    // Tree walker
+    const walker = createSelectorTreeWalker(container, rowSelector);
+
+    // Start at a specific row
+    if (start instanceof HTMLElement) walker.currentNode = start;
+    // Start from the last
+    else if (start === 'last') walker.currentNode = lastDescendant(container);
+
+    // Walk nodes
+    let node;
+    do {
+      node = direction === 'next' ? walker.nextNode() : walker.previousNode();
+      if (node && isNavigableRow(node)) {
+        const result = dive ? dive(node) : node;
+        if (result) yield result;
       }
-      node = walker.nextNode();
-    }
-    return found;
-  }
-
-  /** Get the cells within a single row element. */
-  function getRowCells(row) {
-    return Array.from(row.querySelectorAll(cellSelector));
+    } while (node);
   }
-
-  /** Find the row element containing a cell, using closest(). */
+  const findFirstVisibleRow = () => first(findRows());
+  const findLastVisibleRow = () => first(findRows('last', 'prev'));
   function findParentRow(cell) {
     const row = cell.closest(rowSelector);
     return row && container.contains(row) ? row : null;
   }
 
-  /**
-   * Walk to the next or previous visible row (with cells) from a given row
-   * using a TreeWalker. Avoids building the full visible rows array.
-   */
-  function findAdjacentVisibleRow(fromRow, direction) {
-    const walker = createRowWalker();
-    walker.currentNode = fromRow;
-    const advance = direction === 'next' ? () => walker.nextNode() : () => walker.previousNode();
-    let node = advance();
-    while (node) {
-      if (isNavigableRow(node)) return node;
-      node = advance();
-    }
-    return null;
-  }
+  /** Deferred navigation intent (replayed once cells are committed to the DOM). */
+  const pending = createPendingNavigation(signal);
+  /** Remembered column index for Up/Down navigation (column memory). */
+  let rememberedCol = 0;
 
-  /**
-   * Activate the cell at the given column in a row element.
-   * Clamps col to the row's available cells.
-   */
+  /** Activate the cell at the given column in a row element. */
   function focusCellInRow(row, col) {
     const cells = getRowCells(row);
     if (cells.length === 0) return false;
@@ -5671,14 +5658,30 @@ function createGridFocusNavigation(options, callbacks, signal) {
     state.setActive(cells[clampedCol]);
     return true;
   }
+
+  /** Activate the given cell (validates it is in the grid, updates column memory). */
+  function activateCell(item) {
+    const row = findParentRow(item);
+    if (!row) return false;
+    const cells = getRowCells(row);
+    const col = cells.indexOf(item);
+    if (col === -1) return false;
+    rememberedCol = col;
+    state.setActive(item);
+    return true;
+  }
+
+  /** Got to first cell in first row */
   function goToFirst() {
-    const row = findVisibleRows('first');
+    const row = findFirstVisibleRow();
     if (!row) return false;
     rememberedCol = 0;
     return focusCellInRow(row, 0);
   }
+
+  /** Got to first cell in last row */
   function goToLast() {
-    const row = findVisibleRows('last');
+    const row = findLastVisibleRow();
     if (!row) return false;
     rememberedCol = 0;
     return focusCellInRow(row, 0);
@@ -5702,8 +5705,8 @@ function createGridFocusNavigation(options, callbacks, signal) {
 
     // Wrap to the adjacent row (or opposite boundary row), activating the first or last cell.
     const rowDirection = step > 0 ? 'next' : 'prev';
-    const adjacentRow = findAdjacentVisibleRow(currentRow, rowDirection);
-    const targetRow = adjacentRow ?? (step > 0 ? findVisibleRows('first') : findVisibleRows('last'));
+    const adjacentRow = first(findRows(currentRow, rowDirection));
+    const targetRow = adjacentRow ?? (step > 0 ? findFirstVisibleRow() : findLastVisibleRow());
     if (!targetRow) return false;
     const targetCells = getRowCells(targetRow);
     if (targetCells.length === 0) return false;
@@ -5721,31 +5724,35 @@ function createGridFocusNavigation(options, callbacks, signal) {
     }
     const currentRow = findParentRow(state.active);
     if (!currentRow) return false;
-    const adjacentRow = findAdjacentVisibleRow(currentRow, direction);
+    const adjacentRow = first(findRows(currentRow, direction));
     if (adjacentRow) return focusCellInRow(adjacentRow, rememberedCol);
     if (wrap) {
       // Wrap to the opposite boundary row.
-      const wrapRow = direction === 'next' ? findVisibleRows('first') : findVisibleRows('last');
+      const wrapRow = direction === 'next' ? findFirstVisibleRow() : findLastVisibleRow();
       if (wrapRow) return focusCellInRow(wrapRow, rememberedCol);
     }
     return false;
   }
-  return {
-    type: 'grid',
+  const selectors = {
     get activeItem() {
       return state.active;
     },
-    get hasActiveItem() {
-      return state.active !== null;
-    },
     get hasNavigableItems() {
-      return findVisibleRows('first') !== null;
+      return first(findRows()) !== null;
     },
-    goToFirst,
-    goToLast,
+    // First cell in first row
+    getFirst: () => first(findRows('first', 'next', getFirstCell)),
+    // First cell in last row
+    getLast: () => first(findRows('last', 'prev', getFirstCell)),
+    // First cell matching predicate
+    getMatching: predicate => first(findRows('first', 'next', row => getRowCells(row).find(predicate)))
+  };
+  return {
+    type: 'grid',
+    selectors,
     goToOffset(offset) {
       if (offset === 0) return state.active !== null;
-      const visibleRows = findVisibleRows('all');
+      const visibleRows = Array.from(findRows());
       if (visibleRows.length === 0) return false;
       if (!state.active) {
         // No active item: jump to first or last row, then apply remaining offset.
@@ -5764,38 +5771,22 @@ function createGridFocusNavigation(options, callbacks, signal) {
       if (targetIdx === rowIdx) return false;
       return focusCellInRow(visibleRows[targetIdx], rememberedCol);
     },
-    goToItemMatching(predicate) {
-      // Iterate visible rows lazily — short-circuit on first match.
-      const walker = createRowWalker();
-      let row = walker.nextNode();
-      while (row) {
-        if (isNavigableRow(row)) {
-          const cells = getRowCells(row);
-          for (let c = 0; c < cells.length; c++) {
-            if (predicate(cells[c])) {
-              rememberedCol = c;
-              state.setActive(cells[c]);
-              return true;
-            }
-          }
-        }
-        row = walker.nextNode();
+    clear() {
+      state.clear();
+      pending.clear();
+    },
+    goTo(resolve) {
+      const target = resolve(selectors);
+      if (target && activateCell(target)) {
+        pending.clear();
+        return true;
       }
+      // Target not resolvable yet (e.g. cells not committed to the DOM) — defer
+      pending.defer(() => this.goTo(resolve));
       return false;
     },
-    goToItem(item) {
-      // Use closest() to find the parent row, then find col within that row only.
-      const row = findParentRow(item);
-      if (!row || !isVisible(row)) return false;
-      const cells = getRowCells(row);
-      const col = cells.indexOf(item);
-      if (col === -1) return false;
-      rememberedCol = col;
-      state.setActive(item);
-      return true;
-    },
-    clear() {
-      state.clear();
+    flushPendingNavigation() {
+      pending.flush();
     },
     goUp() {
       return goVertical('prev');
@@ -5931,7 +5922,7 @@ function setupRovingTabIndex(options, signal) {
       }
     }
     if (!hasTabStop) {
-      const fallback = container.querySelector(nav.enabledItemSelector);
+      const fallback = container.querySelector(nav.selectors.enabledItemSelector);
       if (fallback) setTabIndex(fallback, '0');
     }
   }
@@ -5941,7 +5932,7 @@ function setupRovingTabIndex(options, signal) {
     const items = Array.from(container.querySelectorAll(itemSelector));
     const {
       activeItem
-    } = nav;
+    } = nav.selectors;
 
     // Prefer either the current active item (from DOM) or the current selected item
     let preferredTabStopIndex = activeItem && items.indexOf(activeItem);
@@ -5958,10 +5949,10 @@ function setupRovingTabIndex(options, signal) {
   /** 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);
+    const fallback = (anchor && nav.selectors.findNearestEnabled(anchor)) ?? container.querySelector(nav.selectors.enabledItemSelector);
     if (!fallback) return;
     if (shouldFocus) {
-      nav.goToItem(fallback);
+      nav.goTo(() => fallback);
     } else {
       setTabIndex(fallback, '0');
     }
@@ -6031,7 +6022,7 @@ function setupRovingTabIndex(options, signal) {
 
     // Handle disabled
     if (disabledTargets.length > 0) {
-      const currentActive = nav.activeItem;
+      const currentActive = nav.selectors.activeItem;
       for (const target of disabledTargets) {
         setTabIndex(target, '-1');
       }
@@ -6063,10 +6054,10 @@ function setupRovingTabIndex(options, signal) {
 
   container.addEventListener('keydown', evt => {
     // Adopt focus target if nothing is active yet.
-    if (!nav.activeItem) {
+    if (!nav.selectors.activeItem) {
       const target = evt.target;
       if (target.matches(itemSelector) && container.contains(target)) {
-        nav.goToItem(target);
+        nav.goTo(() => target);
       }
     }
     let handled = false;
@@ -6084,10 +6075,10 @@ function setupRovingTabIndex(options, signal) {
         handled = nav.goUp();
         break;
       case 'Home':
-        handled = nav.goToFirst();
+        handled = nav.goTo(s => s.getFirst());
         break;
       case 'End':
-        handled = nav.goToLast();
+        handled = nav.goTo(s => s.getLast());
         break;
     }
     if (handled) {
@@ -6248,12 +6239,24 @@ SelectionChipGroup.className = CLASSNAME$1j;
 /**
  * Get the value for a combobox option element.
  * Uses `data-value` when set; falls back to the element's trimmed `textContent`.
+ *
+ * This is the *selection* value , which may differ from the visible label
  */
 function getOptionValue(option) {
   if (option.dataset.value !== undefined) return option.dataset.value;
   return option.textContent?.trim() ?? '';
 }
 
+/**
+ * Get the visible label for a combobox option element (its trimmed `textContent`).
+ *
+ * Used for typeahead matching: the user types the characters they see, which is the
+ * option's label — not its `data-value` (which can be an unrelated id).
+ */
+function getOptionLabel(option) {
+  return option.textContent?.trim() ?? '';
+}
+
 /** Returns true when an option carries aria-disabled="true". */
 function isOptionDisabled(option) {
   return option.getAttribute('aria-disabled') === 'true';
@@ -6265,20 +6268,8 @@ function isActionCell(cell) {
   if (!row) return false;
   return row.querySelector('[role="gridcell"]') !== cell;
 }
-
-/** Predicate matching an option element that carries `aria-selected="true"`. */
 const isSelected = el => el.getAttribute('aria-selected') === 'true';
 
-/** Navigate to the selected option, or to the first option if none is selected. */
-function goToSelectedOrFirst(nav) {
-  if (!nav.goToItemMatching(isSelected)) nav.goToFirst();
-}
-
-/** Navigate to the selected option, or to the last option if none is selected. */
-function goToSelectedOrLast(nav) {
-  if (!nav.goToItemMatching(isSelected)) nav.goToLast();
-}
-
 /**
  * Compute the current state of a section and notify when it changed.
  *
@@ -6330,7 +6321,7 @@ function notifySection(sectionElement, sectionRegistrations, optionRegistrations
  * @param notify Notify subscribers of combobox events.
  * @returns The created focus navigation controller.
  */
-function setupListbox(handle, signal, notify) {
+function setupListbox(handle, signal, notify, options) {
   const trigger = handle.trigger;
   const listbox = handle.listbox;
   const isGrid = listbox.getAttribute('role') === 'grid';
@@ -6383,6 +6374,7 @@ function setupListbox(handle, signal, notify) {
     focusNav = createListFocusNavigation({
       container: listbox,
       itemSelector,
+      wrap: options?.wrapNavigation,
       getActiveItem: () => {
         const id = trigger.getAttribute('aria-activedescendant');
         return id ? document.getElementById(id) : null;
@@ -6591,12 +6583,12 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
       const nav = handle.focusNav;
       switch (event.key) {
         case 'Enter':
-          if (handle.isOpen && nav?.hasActiveItem && nav.activeItem) {
+          if (handle.isOpen && nav?.selectors.activeItem) {
             // Capture activeItem before click — the click handler may close
             // the popover and clear the focus navigation state.
             const {
               activeItem
-            } = nav;
+            } = nav.selectors;
             // "Click" on active option
             if (!isOptionDisabled(activeItem)) {
               activeItem.click();
@@ -6614,40 +6606,38 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
           // Otherwise (closed popup, or multi-select with no active item),
           // let Enter pass through so it can submit a surrounding form
           break;
+
+        // Open if closed, else move focus within listbox (wrap if enabled).
         case 'ArrowDown':
-          if (nav?.hasNavigableItems) {
-            if (handle.isOpen && !altKey) {
-              if (nav.hasActiveItem) {
-                if (nav.type === 'grid') {
-                  nav.goDown();
-                } else if (!nav.goToOffset(1) && wrapNavigation) {
-                  nav.goToFirst();
-                }
-              } else {
-                goToSelectedOrFirst(nav);
-              }
+          if (!handle.isOpen) {
+            handle.setIsOpen(true);
+            // Focus first or selected item on open.
+            if (!altKey) nav?.goTo(s => s.getMatching(isSelected) ?? s.getFirst());
+          } else if (nav?.selectors.hasNavigableItems && !altKey) {
+            if (nav.selectors.activeItem) {
+              // Go down
+              nav.goDown();
             } else {
-              // Open the listbox and focus selected option, fall back to first.
-              handle.setIsOpen(true);
-              if (!altKey) goToSelectedOrFirst(nav);
+              // Focus first or selected item when no active item.
+              nav.goTo(s => s.getMatching(isSelected) ?? s.getFirst());
             }
           }
           flag = true;
           break;
+
+        // Open if closed, else move focus within listbox (wrap if enabled).
         case 'ArrowUp':
-          if (nav?.hasNavigableItems) {
-            if (!handle.isOpen && !altKey) {
-              // Open the listbox and focus selected option, fall back to last.
-              handle.setIsOpen(true);
-              goToSelectedOrLast(nav);
-            } else if (handle.isOpen && nav.hasActiveItem) {
-              if (nav.type === 'grid') {
-                nav.goUp();
-              } else if (!nav.goToOffset(-1) && wrapNavigation) {
-                nav.goToLast();
-              }
-            } else if (handle.isOpen && !nav.hasActiveItem && !altKey) {
-              goToSelectedOrLast(nav);
+          if (!handle.isOpen && !altKey) {
+            handle.setIsOpen(true);
+            // Focus last or selected item on open.
+            nav?.goTo(s => s.getMatching(isSelected) ?? s.getLast());
+          } else if (handle.isOpen && nav?.selectors.hasNavigableItems) {
+            if (nav.selectors.activeItem) {
+              // Go up
+              nav.goUp();
+            } else if (!altKey) {
+              // Focus last or selected item when no active item.
+              nav.goTo(s => s.getMatching(isSelected) ?? s.getLast());
             }
           }
           flag = true;
@@ -6662,13 +6652,13 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
           flag = true;
           break;
         case 'PageUp':
-          if (handle.isOpen && nav?.hasActiveItem) {
+          if (handle.isOpen && nav?.selectors.activeItem) {
             nav.goToOffset(-10);
           }
           flag = true;
           break;
         case 'PageDown':
-          if (handle.isOpen && nav?.hasActiveItem) {
+          if (handle.isOpen && nav?.selectors.activeItem) {
             nav.goToOffset(10);
           }
           flag = true;
@@ -6713,7 +6703,9 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
       });
     }
     if (listbox && !focusNav) {
-      focusNav = setupListbox(handle, abortController.signal, notify);
+      focusNav = setupListbox(handle, abortController.signal, notify, {
+        wrapNavigation
+      });
     }
   }
   handle = {
@@ -6754,25 +6746,16 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
       // Update aria-expanded on trigger
       trigger?.setAttribute('aria-expanded', String(isOpen));
       notify('open', isOpen);
-
-      // When opening, always notify the current options state so that
-      // subscribers (ComboboxState) get the correct initial value.
-      // Without this, a list that starts empty never fires `optionsChange`
-      // because `lastOptionsLength` is initialized to `0` and `notifyVisibilityChange`
-      // only fires on *changes*.
-      if (isOpen) {
-        const inputValue = trigger?.value ?? '';
-        notify('optionsChange', {
-          optionsLength: lastOptionsLength,
-          inputValue
-        });
-      }
     },
     select(option) {
       callbacks.onSelect?.({
         value: option ? getOptionValue(option) : ''
       });
     },
+    flushPendingNavigation() {
+      // Do navigations actions we could not do because the combobox items were not mounted yet
+      focusNav?.flushPendingNavigation();
+    },
     registerOption(element, callback) {
       const filterLower = filterValue.toLowerCase();
       const text = getOptionValue(element).toLowerCase();
@@ -6867,7 +6850,9 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
       if (trigger && abortController) {
         if (!hadListbox) {
           // First listbox — set up focus nav and listbox listeners
-          focusNav = setupListbox(handle, abortController.signal, notify);
+          focusNav = setupListbox(handle, abortController.signal, notify, {
+            wrapNavigation
+          });
         } else {
           // Replacing listbox — full re-attach
           detach();
@@ -6945,18 +6930,9 @@ function createTypeahead(getWalker, getItemValue, signal) {
   }
   signal.addEventListener('abort', reset);
 
-  // Handle typeahead keys
-  function handle(key, currentItem) {
-    // Clear any pending reset timeout.
-    if (searchTimeout !== undefined) {
-      clearTimeout(searchTimeout);
-    }
-
-    // Accumulate the character.
-    searchString += key.toLowerCase();
-
-    // Schedule clearing the search string after inactivity.
-    searchTimeout = setTimeout(reset, SEARCH_TIMEOUT);
+  // Match the current accumulated search string against the live DOM.
+  function match(currentItem) {
+    if (!searchString) return null;
     const walker = getWalker();
     if (!walker) return null;
 
@@ -7017,8 +6993,29 @@ function createTypeahead(getWalker, getItemValue, signal) {
       }
     }
   }
+
+  // Handle typeahead keys
+  function handle(key, currentItem) {
+    // Clear any pending reset timeout.
+    if (searchTimeout !== undefined) {
+      clearTimeout(searchTimeout);
+    }
+
+    // Accumulate the character.
+    searchString += key.toLowerCase();
+
+    // Schedule clearing the search string after inactivity.
+    searchTimeout = setTimeout(reset, SEARCH_TIMEOUT);
+    return match(currentItem);
+  }
+
+  // Re-run the match for the current buffer without mutating it.
+  function rematch(currentItem) {
+    return match(currentItem);
+  }
   return {
     handle,
+    rematch,
     reset
   };
 }
@@ -7055,7 +7052,7 @@ function setupComboboxButton(button, callbacks) {
       // In list mode, walk option elements.
       const selector = combobox.focusNav?.type === 'grid' ? '[role="gridcell"]' : '[role="option"]';
       return createSelectorTreeWalker(combobox.listbox, selector);
-    }, getOptionValue, signal);
+    }, getOptionLabel, signal);
 
     // Click toggles the listbox.
     button.addEventListener('click', () => combobox.setIsOpen(!combobox.isOpen), {
@@ -7066,47 +7063,49 @@ function setupComboboxButton(button, callbacks) {
       switch (event.key) {
         case 'Tab':
           // Selects the focused option
-          if (combobox.isOpen && nav?.hasActiveItem && nav.activeItem) {
-            combobox.select(nav.activeItem);
+          if (combobox.isOpen && nav?.selectors.activeItem) {
+            combobox.select(nav.selectors.activeItem);
           }
           // Return false to continue normal 'Tab' behavior (focus next).
           return false;
         case ' ':
           // Space acts like Enter in button mode.
-          if (combobox.isOpen && nav?.hasActiveItem && nav.activeItem) {
+          if (combobox.isOpen && nav?.selectors.activeItem) {
             // Click the active item — delegated handler handles select + close.
-            nav.activeItem.click();
+            nav.selectors.activeItem.click();
           } else {
             combobox.setIsOpen(true);
           }
           return true;
         case 'ArrowUp':
           // Alt+ArrowUp: select the focused option and close.
-          if (event.altKey && combobox.isOpen && nav?.hasActiveItem && nav.activeItem) {
-            combobox.select(nav.activeItem);
+          if (event.altKey && combobox.isOpen && nav?.selectors.activeItem) {
+            combobox.select(nav.selectors.activeItem);
             combobox.setIsOpen(false);
             return true;
           }
           // All other ArrowUp cases handled by base handler.
           return false;
         case 'Home':
+          // `goTo` focuses the first option immediately when open, or defers
+          // until the options commit when opening from closed.
           combobox.setIsOpen(true);
-          nav?.goToFirst();
+          nav?.goTo(n => n.getFirst());
           return true;
         case 'End':
           combobox.setIsOpen(true);
-          nav?.goToLast();
+          nav?.goTo(n => n.getLast());
           return true;
         case 'ArrowLeft':
           // Grid mode: navigate to previous cell.
-          if (nav?.type === 'grid' && combobox.isOpen && nav.hasActiveItem) {
+          if (nav?.type === 'grid' && combobox.isOpen && nav.selectors.activeItem) {
             nav.goLeft();
             return true;
           }
           return false;
         case 'ArrowRight':
           // Grid mode: navigate to next cell.
-          if (nav?.type === 'grid' && combobox.isOpen && nav.hasActiveItem) {
+          if (nav?.type === 'grid' && combobox.isOpen && nav.selectors.activeItem) {
             nav.goRight();
             return true;
           }
@@ -7121,10 +7120,8 @@ function setupComboboxButton(button, callbacks) {
           // Printable characters → typeahead.
           if (isPrintableKey(event)) {
             combobox.setIsOpen(true);
-            const match = typeahead.handle(event.key, nav?.activeItem ?? null);
-            if (match && nav) {
-              nav.goToItem(match);
-            }
+            typeahead.handle(event.key, nav?.selectors.activeItem ?? null);
+            nav?.goTo(n => typeahead.rematch(n.activeItem));
             return true;
           }
           return false;
@@ -7448,7 +7445,7 @@ function setupComboboxInput(input, options) {
         case 'ArrowLeft':
         case 'ArrowRight':
           // Grid mode: navigate cells when active item exists.
-          if (nav?.type === 'grid' && nav.hasActiveItem) {
+          if (nav?.type === 'grid' && nav.selectors.activeItem) {
             if (event.key === 'ArrowLeft') nav.goLeft();else nav.goRight();
             return true;
           }
@@ -8307,25 +8304,30 @@ const ComboboxList = forwardRef((props, ref) => {
   const listContextValue = useMemo(() => ({
     type
   }), [type]);
+  const [isOpen] = useComboboxOpen();
+  const options = useComboboxEvent('optionsChange', undefined);
+  const visibleCount = options?.optionsLength ?? 0;
 
-  // Register the list as the listbox when the handle becomes available
+  // Register list as listbox when handle is available.
   useEffect(() => {
     const list = internalRef.current;
     if (!list) return undefined;
     return handle?.registerListbox(list);
   }, [handle]);
 
-  // Track loading state for aria-busy (auto-derived from skeleton registrations).
-  // Uses both the handle's synchronous getter (for initial state) and the loadingChange event
-  // (for subsequent updates), because child useEffects (skeleton registration) run before
-  // parent subscriptions — relying on events alone would miss the initial notification.
+  // Track loading state for aria-busy
   const [isLoading, setIsLoading] = useState(false);
   useEffect(() => {
     if (!handle) return undefined;
-    // Read current state synchronously (catches registrations that happened before subscription)
+    // Read current state synchronously (catches registrations before subscription).
     setIsLoading(handle.isLoading);
     return handle.subscribe('loadingChange', setIsLoading);
   }, [handle]);
+
+  // Flush pending keyboard navigation after options commit on open.
+  useEffect(() => {
+    if (isOpen) handle?.flushPendingNavigation();
+  }, [isOpen, visibleCount, handle]);
   return /*#__PURE__*/jsx(ComboboxListContext.Provider, {
     value: listContextValue,
     children: ComboboxList$1({
@@ -8336,7 +8338,7 @@ const ComboboxList = forwardRef((props, ref) => {
       ref: mergedRef,
       id: listboxId,
       type,
-      children
+      children: isOpen ? children : null
     })
   });
 });
@@ -9163,6 +9165,7 @@ const Popover$1 = (props, {
         [`position-${position}`]: Boolean(position),
         'is-hidden': Boolean(isHidden)
       })),
+      hidden: isHidden || undefined,
       style: isHidden ? undefined : popoverStyle,
       "data-popper-placement": position,
       children: [unmountSentinel, /*#__PURE__*/jsxs(ClickAwayProvider, {