@lumx/react 4.16.0-alpha.3 → 4.16.0-alpha.5

package/index.js

@@ -1687,7 +1687,7 @@ const IconButton$1 = props => {
     size = DEFAULT_PROPS$1a.size,
     ...forwardedProps
   } = props;
-  const iconNode = image ? /*#__PURE__*/jsx("img", {
+  const defaultChildren = image ? /*#__PURE__*/jsx("img", {
     // no need to set alt as an aria-label is already set on the button
     alt: "",
     src: image
@@ -1700,12 +1700,7 @@ const IconButton$1 = props => {
     ...forwardedProps,
     'aria-label': label,
     variant: 'icon',
-    children: /*#__PURE__*/jsxs(Fragment, {
-      children: [iconNode, /*#__PURE__*/jsx("span", {
-        className: visuallyHidden(),
-        children: label
-      })]
-    })
+    children: defaultChildren
   });
 };
 IconButton$1.displayName = COMPONENT_NAME$1r;
@@ -5330,6 +5325,111 @@ Tooltip.displayName = COMPONENT_NAME$1i;
 Tooltip.className = CLASSNAME$1h;
 Tooltip.defaultProps = DEFAULT_PROPS$12;
 
+/** 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
+  };
+}
+
+/**
+ * Create the pure selection layer for a 1D list.
+ *
+ * Everything here is side-effect-free: it only *queries* the DOM to resolve and report
+ * items. No focus is moved and no {@link FocusNavigationCallbacks} are invoked — that is
+ * the job of the mover layer built on top of this (`createListFocusNavigation`).
+ *
+ * @param options List navigation options (container, itemSelector, itemDisabledSelector, getActiveItem).
+ * @returns The public {@link ListFocusNavigationSelectors} plus the internal
+ *   {@link ListSelectorHelpers} the mover layer consumes.
+ */
+function createListSelectors(options) {
+  const {
+    container,
+    itemSelector,
+    itemDisabledSelector,
+    getActiveItem = () => null
+  } = options;
+
+  /** Combined CSS selector matching enabled (non-disabled) items. */
+  const enabledItemSelector = itemDisabledSelector ? `${itemSelector}:not(${itemDisabledSelector})` : itemSelector;
+  function createItemWalker(enabledOnly = true) {
+    const selector = enabledOnly ? enabledItemSelector : itemSelector;
+    return createSelectorTreeWalker(container, selector);
+  }
+  function findFirstEnabled() {
+    return container.querySelector(enabledItemSelector);
+  }
+  function findLastEnabled() {
+    const items = container.querySelectorAll(enabledItemSelector);
+    return items.length > 0 ? items[items.length - 1] : null;
+  }
+  function findMatching(predicate) {
+    const walker = createItemWalker(false);
+    let node = walker.nextNode();
+    while (node) {
+      if (predicate(node)) return node;
+      node = walker.nextNode();
+    }
+    return null;
+  }
+  function 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();
+  }
+  const selectors = {
+    enabledItemSelector,
+    get activeItem() {
+      return getActiveItem();
+    },
+    get hasNavigableItems() {
+      return container.querySelector(enabledItemSelector) !== null;
+    },
+    getFirst: findFirstEnabled,
+    getLast: findLastEnabled,
+    getMatching: findMatching,
+    findNearestEnabled
+  };
+  const helpers = {
+    createItemWalker,
+    findFirstEnabled,
+    findLastEnabled,
+    getActiveItem
+  };
+  return {
+    selectors,
+    helpers
+  };
+}
+
 /**
  * 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.
@@ -5344,6 +5444,12 @@ function transition(getActiveItem, callbacks, newItem) {
 /**
  * Create a focus navigation controller for a 1D list.
  *
+ * The controller is composed of two layers:
+ * - a pure, side-effect-free **selection** layer ({@link createListSelectors}) that only
+ *   resolves/reports items by querying the DOM, and
+ * - a **mover** layer (this function) that commits focus by calling
+ *   {@link FocusNavigationCallbacks} on top of the selectors.
+ *
  * 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
@@ -5356,36 +5462,24 @@ function transition(getActiveItem, callbacks, newItem) {
  */
 function createListFocusNavigation(options, callbacks, signal) {
   const {
-    container,
     itemSelector,
+    container,
     direction = 'vertical',
-    wrap = false,
-    itemDisabledSelector,
-    getActiveItem = () => null
+    wrap = false
   } = options;
+  const {
+    selectors,
+    helpers
+  } = createListSelectors(options);
+  const {
+    getActiveItem,
+    createItemWalker,
+    findFirstEnabled,
+    findLastEnabled
+  } = helpers;
 
-  /** 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 createSelectorTreeWalker(container, selector);
-  }
-
-  /** 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;
-  }
+  // Deferred navigation intent (replayed once items are committed to the DOM)
+  const pending = createPendingNavigation(signal);
 
   /** Navigate to the first enabled item and activate it. */
   function goToFirst() {
@@ -5402,7 +5496,9 @@ function createListFocusNavigation(options, callbacks, signal) {
     transition(getActiveItem, callbacks, last);
     return true;
   }
-  function navigateByOffset(offset) {
+
+  /** Go to item at an offset */
+  function goToOffset(offset) {
     const active = getActiveItem();
     if (offset === 0) return active !== null;
     const forward = offset > 0;
@@ -5413,7 +5509,7 @@ function createListFocusNavigation(options, callbacks, signal) {
       const started = forward ? goToFirst() : goToLast();
       if (!started) return false;
       if (stepsNeeded === 1) return true;
-      return navigateByOffset(forward ? offset - 1 : offset + 1);
+      return goToOffset(forward ? offset - 1 : offset + 1);
     }
 
     // Walk from the active item using a TreeWalker.
@@ -5442,15 +5538,14 @@ function createListFocusNavigation(options, callbacks, signal) {
     transition(getActiveItem, callbacks, lastFound);
     return true;
   }
-  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?.();
   }
 
@@ -5458,69 +5553,40 @@ function createListFocusNavigation(options, callbacks, signal) {
   signal.addEventListener('abort', clear);
   return {
     type: 'list',
-    enabledItemSelector,
-    get activeItem() {
-      return getActiveItem();
-    },
-    get hasActiveItem() {
-      return getActiveItem() !== null;
-    },
-    get hasNavigableItems() {
-      return container.querySelector(enabledItemSelector) !== null;
-    },
-    goToFirst,
-    goToLast,
+    selectors,
     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();
+    goToOffset,
+    clear,
+    goTo(resolve) {
+      const target = resolve(selectors);
+      if (target && target.matches(itemSelector) && container.contains(target)) {
+        transition(getActiveItem, callbacks, target);
+        pending.clear();
+        return true;
       }
+      // Target not resolvable yet (e.g. items not committed to the DOM) — defer
+      pending.defer(() => this.goTo(resolve));
       return false;
     },
-    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();
+    flushPendingNavigation() {
+      pending.flush();
     },
-    clear,
     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;
     }
   };
 }
@@ -5543,7 +5609,7 @@ function createListFocusNavigation(options, callbacks, signal) {
  * @param initialItem Optional item to silently pre-select on creation (no callbacks fired).
  */
 function createActiveItemState(callbacks, signal, initialItem) {
-  let activeItem = initialItem ?? null;
+  let activeItem = null;
   function clear() {
     if (activeItem) {
       callbacks.onDeactivate(activeItem);
@@ -5570,105 +5636,165 @@ 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.
+ * Create the pure selection layer for a 2D grid.
  *
- * Supports Up/Down between rows (with column memory) and Left/Right between cells
- * (with wrapping across rows).
+ * Everything here is side-effect-free: it only *queries* the DOM to resolve and report
+ * rows/cells. No focus is moved and no {@link FocusNavigationCallbacks} are invoked — that
+ * is the job of the mover layer built on top of this.
  *
- * @param options Grid navigation options (container, rowSelector, cellSelector, isRowVisible, wrap).
- * @param callbacks Callbacks for focus state changes.
- * @param signal AbortSignal for cleanup.
- * @returns FocusNavigationController instance.
+ * @param options Grid navigation options (container, rowSelector, cellSelector).
+ * @param getActive Reader for the currently active cell (owned by the mover's active-item state).
+ * @param isVisible Predicate deciding whether a row is visible (derived from `isRowVisible`).
+ * @returns The public {@link FocusNavigationSelectors} plus the internal
+ *   {@link GridSelectorHelpers} the mover layer consumes.
  */
-function createGridFocusNavigation(options, callbacks, signal) {
+function createGridSelectors(options, getActive, isVisible) {
   const {
     container,
     rowSelector,
-    cellSelector,
-    isRowVisible,
-    wrap = false
+    cellSelector
   } = 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.
+   * Lazily walk navigable rows (visible, with cells) starting from `startNode` in
+   * `direction`, projecting each row through `dive`.
    */
-
-  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();
+  function* findRow(direction, startNode = null, dive) {
+    const walker = createSelectorTreeWalker(container, rowSelector);
+    if (startNode) walker.currentNode = startNode;
+    const advance = direction === 'next' ? () => walker.nextNode() : () => walker.previousNode();
+    let node = advance();
     while (node) {
       if (isNavigableRow(node)) {
-        if (mode === 'first') return node;
-        found = node;
+        const result = dive ? dive(node) : node;
+        if (result) yield result;
       }
-      node = walker.nextNode();
+      node = advance();
     }
-    return found;
   }
 
-  /** Get the cells within a single row element. */
+  /** Find the first or last navigable row (visible, with cells), or null. */
+  function findVisibleRow(mode) {
+    return mode === 'first' ? first(findRow('next')) : first(findRow('prev', lastDescendant(container)));
+  }
+
+  /** Collect all navigable rows (visible, with cells) in DOM order. */
+  function findAllVisibleRows() {
+    return Array.from(findRow('next'));
+  }
   function getRowCells(row) {
     return Array.from(row.querySelectorAll(cellSelector));
   }
-
-  /** Find the row element containing a cell, using closest(). */
   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;
+    return first(findRow(direction, fromRow));
   }
 
-  /**
-   * Activate the cell at the given column in a row element.
-   * Clamps col to the row's available cells.
-   */
+  /** Resolve the first cell of the boundary row (without moving focus). */
+  function getBoundaryCell(mode) {
+    const row = findVisibleRow(mode);
+    if (!row) return null;
+    const cells = getRowCells(row);
+    return cells.length > 0 ? cells[0] : null;
+  }
+
+  /** Resolve the first cell matching a predicate (without moving focus). */
+  function getMatching(predicate) {
+    return first(findRow('next', null, row => getRowCells(row).find(predicate) ?? null));
+  }
+  const selectors = {
+    get activeItem() {
+      return getActive();
+    },
+    get hasNavigableItems() {
+      return first(findRow('next')) !== null;
+    },
+    getFirst: () => getBoundaryCell('first'),
+    getLast: () => getBoundaryCell('last'),
+    getMatching
+  };
+  const helpers = {
+    findFirstVisibleRow: () => findVisibleRow('first'),
+    findLastVisibleRow: () => findVisibleRow('last'),
+    findAllVisibleRows,
+    getRowCells,
+    findParentRow,
+    findAdjacentVisibleRow
+  };
+  return {
+    selectors,
+    helpers
+  };
+}
+
+/**
+ * Create a focus navigation controller for a 2D grid.
+ *
+ * The controller is composed of two layers:
+ * - a pure, side-effect-free **selection** layer ({@link createGridSelectors}) that only
+ *   resolves/reports rows and cells by querying the DOM, and
+ * - a **mover** layer (this function) that commits focus by updating the active-item state
+ *   (which fires {@link FocusNavigationCallbacks}) on top of the selectors.
+ *
+ * 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 callbacks Callbacks for focus state changes.
+ * @param signal AbortSignal for cleanup.
+ * @returns FocusNavigationController instance.
+ */
+function createGridFocusNavigation(options, callbacks, signal) {
+  const {
+    isRowVisible,
+    wrap = false
+  } = options;
+  const state = createActiveItemState(callbacks, signal);
+
+  /** Whether a row is visible (passes the optional `isRowVisible` filter). */
+  const isVisible = row => !isRowVisible || isRowVisible(row);
+  const {
+    selectors,
+    helpers
+  } = createGridSelectors(options, () => state.active, isVisible);
+  const {
+    findFirstVisibleRow,
+    findLastVisibleRow,
+    findAllVisibleRows,
+    getRowCells,
+    findParentRow,
+    findAdjacentVisibleRow
+  } = helpers;
+
+  /** 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. */
   function focusCellInRow(row, col) {
     const cells = getRowCells(row);
     if (cells.length === 0) return false;
@@ -5676,14 +5802,18 @@ function createGridFocusNavigation(options, callbacks, signal) {
     state.setActive(cells[clampedCol]);
     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);
@@ -5708,7 +5838,7 @@ 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 targetRow = adjacentRow ?? (step > 0 ? findFirstVisibleRow() : findLastVisibleRow());
     if (!targetRow) return false;
     const targetCells = getRowCells(targetRow);
     if (targetCells.length === 0) return false;
@@ -5730,27 +5860,17 @@ function createGridFocusNavigation(options, callbacks, signal) {
     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',
-    get activeItem() {
-      return state.active;
-    },
-    get hasActiveItem() {
-      return state.active !== null;
-    },
-    get hasNavigableItems() {
-      return findVisibleRows('first') !== null;
-    },
-    goToFirst,
-    goToLast,
+    selectors,
     goToOffset(offset) {
       if (offset === 0) return state.active !== null;
-      const visibleRows = findVisibleRows('all');
+      const visibleRows = findAllVisibleRows();
       if (visibleRows.length === 0) return false;
       if (!state.active) {
         // No active item: jump to first or last row, then apply remaining offset.
@@ -5769,25 +5889,6 @@ 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();
-      }
-      return false;
-    },
     goToItem(item) {
       // Use closest() to find the parent row, then find col within that row only.
       const row = findParentRow(item);
@@ -5801,6 +5902,20 @@ function createGridFocusNavigation(options, callbacks, signal) {
     },
     clear() {
       state.clear();
+      pending.clear();
+    },
+    goTo(resolve) {
+      const target = resolve(selectors);
+      if (target && this.goToItem(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;
+    },
+    flushPendingNavigation() {
+      pending.flush();
     },
     goUp() {
       return goVertical('prev');
@@ -5936,7 +6051,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');
     }
   }
@@ -5946,7 +6061,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);
@@ -5963,7 +6078,7 @@ 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);
@@ -6036,7 +6151,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');
       }
@@ -6068,7 +6183,7 @@ 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);
@@ -6089,10 +6204,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) {
@@ -6253,12 +6368,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';
@@ -6270,20 +6397,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.
  *
@@ -6596,12 +6711,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();
@@ -6620,39 +6735,35 @@ function setupCombobox(callbacks, options, onTriggerAttach) {
           // let Enter pass through so it can submit a surrounding form
           break;
         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);
+            if (!altKey) nav?.goTo(s => s.getMatching(isSelected) ?? s.getFirst());
+          } else if (nav?.selectors.hasNavigableItems && !altKey) {
+            if (nav.selectors.activeItem) {
+              if (nav.type === 'grid') {
+                nav.goDown();
+              } else if (!nav.goToOffset(1) && wrapNavigation) {
+                nav.goTo(s => s.getFirst());
               }
             } else {
-              // Open the listbox and focus selected option, fall back to first.
-              handle.setIsOpen(true);
-              if (!altKey) goToSelectedOrFirst(nav);
+              nav.goTo(s => s.getMatching(isSelected) ?? s.getFirst());
             }
           }
           flag = true;
           break;
         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 (!handle.isOpen && !altKey) {
+            handle.setIsOpen(true);
+            nav?.goTo(s => s.getMatching(isSelected) ?? s.getLast());
+          } else if (handle.isOpen && nav?.selectors.hasNavigableItems) {
+            if (nav.selectors.activeItem) {
               if (nav.type === 'grid') {
                 nav.goUp();
               } else if (!nav.goToOffset(-1) && wrapNavigation) {
-                nav.goToLast();
+                nav.goTo(s => s.getLast());
               }
-            } else if (handle.isOpen && !nav.hasActiveItem && !altKey) {
-              goToSelectedOrLast(nav);
+            } else if (!altKey) {
+              nav.goTo(s => s.getMatching(isSelected) ?? s.getLast());
             }
           }
           flag = true;
@@ -6667,13 +6778,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;
@@ -6759,25 +6870,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();
@@ -6950,18 +7052,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;
 
@@ -7022,8 +7115,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
   };
 }
@@ -7060,7 +7174,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), {
@@ -7071,59 +7185,65 @@ 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;
           }
           return false;
+        case 'Escape':
+          // Close if open; never clear selection (button-mode has no text input).
+          if (combobox.isOpen) {
+            combobox.setIsOpen(false);
+          }
+          return true;
         default:
           // 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;
@@ -7286,9 +7406,10 @@ const ComboboxButton = Object.assign(forwardRefPolymorphic((props, ref) => {
 
   // If `as` is provided, use it directly; otherwise use the LumX Button (full theme/disabled behavior).
   const ButtonComp = as ?? Button;
-  const internalRef = useRef(null);
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const mergedRef = useMergeRefs(ref, internalRef, anchorRef);
+
+  // Track the button DOM element via state (instead of useRef) so it re-triggers the useEffect
+  const [buttonElement, setButtonElement] = useState(null);
+  const mergedRef = useMergeRefs(ref, setButtonElement, anchorRef);
 
   // Keep onSelect in a ref to avoid re-creating the handle on every render
   const onSelectRef = useRef(onSelect);
@@ -7296,9 +7417,8 @@ const ComboboxButton = Object.assign(forwardRefPolymorphic((props, ref) => {
 
   // Create the combobox handle with button-mode controller on mount
   useEffect(() => {
-    const button = internalRef.current;
-    if (!button) return undefined;
-    const handle = setupComboboxButton(button, {
+    if (!buttonElement) return undefined;
+    const handle = setupComboboxButton(buttonElement, {
       onSelect(option) {
         onSelectRef.current?.(option);
       }
@@ -7308,7 +7428,7 @@ const ComboboxButton = Object.assign(forwardRefPolymorphic((props, ref) => {
       handle.destroy();
       setHandle(null);
     };
-  }, [setHandle]);
+  }, [buttonElement, setHandle]);
   return ComboboxButton$1({
     ...buttonProps,
     label,
@@ -7447,7 +7567,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;
           }
@@ -8306,25 +8426,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.
+  useLayoutEffect(() => {
+    if (isOpen) handle?.flushPendingNavigation();
+  }, [isOpen, visibleCount, handle]);
   return /*#__PURE__*/jsx(ComboboxListContext.Provider, {
     value: listContextValue,
     children: ComboboxList$1({
@@ -8335,7 +8460,7 @@ const ComboboxList = forwardRef((props, ref) => {
       ref: mergedRef,
       id: listboxId,
       type,
-      children
+      children: isOpen ? children : null
     })
   });
 });
@@ -16825,6 +16950,24 @@ function toggleSelection(options, getOptionId, currentValue, selectedOptionId, i
   return updated;
 }
 
+/**
+ * Get the display name for a single option value.
+ *
+ * Resolves the option's display name by trying `getOptionName` first,
+ * then falling back to `getOptionId`, returning `''` for nullish values.
+ */
+function getOptionDisplayName(value, getOptionName, getOptionId) {
+  if (value === undefined || value === null) return '';
+  if (getOptionName) {
+    const name = getWithSelector(getOptionName, value);
+    if (name != null) return String(name);
+  }
+  if (getOptionId) {
+    return String(getWithSelector(getOptionId, value));
+  }
+  return '';
+}
+
 /**
  * Render options as ComboboxOption elements.
  * Framework-specific components are passed as a second argument.
@@ -16949,7 +17092,7 @@ const SelectButton$2 = (props, {
    * each option to its name and join with `, `. Falsy entries (undefined, empty names)
    * are filtered out so partial state still renders cleanly.
    */
-  const displayValue = value != null ? castArray(value).map(v => v != null && getWithSelector(getOptionName, v)).filter(Boolean).join(', ') : '';
+  const displayValue = value != null ? castArray(value).map(v => getOptionDisplayName(v, getOptionName, getOptionId)).filter(Boolean).join(', ') : '';
   return /*#__PURE__*/jsxs(Combobox.Provider, {
     onOpen: onOpen,
     children: [/*#__PURE__*/jsx(Combobox.Button, {
@@ -17078,8 +17221,8 @@ const DefaultButton = forwardRef((props, ref) => /*#__PURE__*/jsx(Button, {
  * fully replaced and only props valid for that component apply.
  *
  * Discriminated on `selectionType`:
- * - default / `'single'` → `value?: O`, `onChange?: (newValue?: O) => void`.
- * - `'multiple'`         → `value?: O[]`, `onChange?: (newValue?: O[]) => void`.
+ * - default / `'single'` → `value?: O`, `onChange?: (newValue: O) => void`.
+ * - `'multiple'`         → `value?: O[]`, `onChange?: (newValue: O[]) => void`.
  *
  * `as` and `selectionType` are top-level on this type (rather than buried in
  * an intersection or union member) so that TS can infer `E` from `as` and
@@ -17092,10 +17235,11 @@ const DefaultButton = forwardRef((props, ref) => /*#__PURE__*/jsx(Button, {
 
 /**
  * Single-selection props (`selectionType` defaults to `'single'`).
- * Backwards-compatible alias — existing consumers do not need to set `selectionType`.
  */
 
-/** Multi-selection props (`selectionType: 'multiple'` is required to opt in). */
+/**
+ * Multi-selection props (`selectionType: 'multiple'` is required to opt in).
+ */
 
 /**
  * `React.forwardRef` re-typed to preserve our polymorphic generics
@@ -17139,6 +17283,9 @@ const SelectButton$1 = React__default.forwardRef((props, ref) => {
     const next = toggleSelection(options, getOptionId, value, selectedOption?.value, isMultiple);
     onChange?.(next);
   }, [getOptionId, isMultiple, onChange, options, value]);
+
+  // If as is defined and not the Button, render as, else render DefaultButton (with mdiMenuDown right icon)
+  const buttonAs = as && as !== Button ? as : DefaultButton;
   return SelectButton$2({
     options,
     getOptionId,
@@ -17151,10 +17298,9 @@ const SelectButton$1 = React__default.forwardRef((props, ref) => {
     isMultiselectable: isMultiple,
     label,
     labelDisplayMode,
-    // With no `as`, the default trigger adds the chevron.
     buttonProps: {
       ...buttonProps,
-      as: as ?? DefaultButton,
+      as: buttonAs,
       ref
     },
     popoverProps,
@@ -17185,24 +17331,6 @@ const SelectButton = Object.assign(SelectButton$1, {
   Option: ComboboxOption
 });
 
-/**
- * Get the display name for a single option value.
- *
- * Resolves the option's display name by trying `getOptionName` first,
- * then falling back to `getOptionId`, returning `''` for nullish values.
- */
-function getOptionDisplayName(value, getOptionName, getOptionId) {
-  if (value === undefined || value === null) return '';
-  if (getOptionName) {
-    const name = getWithSelector(getOptionName, value);
-    if (name != null) return String(name);
-  }
-  if (getOptionId) {
-    return String(getWithSelector(getOptionId, value));
-  }
-  return '';
-}
-
 /**
  * Component display name.
  */