@aurodesignsystem-dev/auro-formkit 0.0.0-pr1540.0 → 0.0.0-pr1540.2

package/components/combobox/demo/getting-started.min.js

@@ -825,6 +825,188 @@ function navigateArrow(component, direction, options = {}) {
   }
 }
 
+// Selectors for focusable elements
+const FOCUSABLE_SELECTORS$1 = [
+  "a[href]",
+  "button:not([disabled])",
+  "textarea:not([disabled])",
+  "input:not([disabled])",
+  "select:not([disabled])",
+  '[role="tab"]:not([disabled])',
+  '[role="link"]:not([disabled])',
+  '[role="button"]:not([disabled])',
+  '[tabindex]:not([tabindex="-1"])',
+  '[contenteditable]:not([contenteditable="false"])',
+];
+
+// List of custom components that are known to be focusable
+const FOCUSABLE_COMPONENTS$1 = [
+  "auro-checkbox",
+  "auro-radio",
+  "auro-dropdown",
+  "auro-button",
+  "auro-combobox",
+  "auro-input",
+  "auro-counter",
+  // 'auro-menu', // Auro menu is not focusable by default, it uses a different interaction model
+  "auro-select",
+  "auro-datepicker",
+  "auro-hyperlink",
+  "auro-accordion",
+];
+
+/**
+ * Determines if a given element is a custom focusable component.
+ * Returns true if the element matches a known focusable component and is not disabled.
+ *
+ * @param {HTMLElement} element The element to check for focusability.
+ * @returns {boolean} True if the element is a focusable custom component, false otherwise.
+ */
+function isFocusableComponent$1(element) {
+  const componentName = element.tagName.toLowerCase();
+
+  // Guard Clause: Element is a focusable component
+  if (
+    !FOCUSABLE_COMPONENTS$1.some(
+      (name) => element.hasAttribute(name) || componentName === name,
+    )
+  )
+    return false;
+
+  // Guard Clause: Element is not disabled
+  if (element.hasAttribute("disabled")) return false;
+
+  // Guard Clause: The element is a hyperlink and has no href attribute
+  if (componentName.match("hyperlink") && !element.hasAttribute("href"))
+    return false;
+
+  // If all guard clauses pass, the element is a focusable component
+  return true;
+}
+
+/**
+ * Safely get a numeric tabindex for an element.
+ * Returns a number if the tabindex is a valid integer, otherwise null.
+ *
+ * @param {HTMLElement} element The element whose tabindex to read.
+ * @returns {?number} The numeric tabindex or null if missing/invalid.
+ */
+function getNumericTabIndex$1(element) {
+  const raw = element.getAttribute("tabindex");
+  if (raw == null) return null;
+
+  const value = Number.parseInt(raw, 10);
+  return Number.isNaN(value) ? null : value;
+}
+
+/**
+ * Retrieves all focusable elements within the container in DOM order, including those in shadow DOM and slots.
+ * Returns a unique, ordered array of elements that can receive focus.
+ * Also sorts elements with tabindex first, preserving their order.
+ *
+ * @param {HTMLElement} container The container to search within
+ * @returns {Array<HTMLElement>} An array of focusable elements within the container.
+ */
+function getFocusableElements$1(container) {
+  // Get elements in DOM order by walking the tree
+  const orderedFocusableElements = [];
+
+  // Define a recursive function to collect focusable elements in DOM order
+  const collectFocusableElements = (root) => {
+    // Check if current element is focusable
+    if (root.nodeType === Node.ELEMENT_NODE) {
+      // Check if this is a custom component that is focusable
+      const isComponentFocusable = isFocusableComponent$1(root);
+
+      if (isComponentFocusable) {
+        // Add the component itself as a focusable element and don't traverse its shadow DOM
+        orderedFocusableElements.push(root);
+        return; // Skip traversing inside this component
+      }
+
+      // Check if the element itself matches any selector
+      for (const selector of FOCUSABLE_SELECTORS$1) {
+        if (root.matches?.(selector)) {
+          orderedFocusableElements.push(root);
+          break; // Once we know it's focusable, no need to check other selectors
+        }
+      }
+
+      // Process shadow DOM only for non-Auro components
+      if (root.shadowRoot) {
+        // Process shadow DOM children in order
+        if (root.shadowRoot.children) {
+          Array.from(root.shadowRoot.children).forEach((child) => {
+            collectFocusableElements(child);
+          });
+        }
+      }
+
+      // Process slots and their assigned nodes in order
+      if (root.tagName === "SLOT") {
+        const assignedNodes = root.assignedNodes({ flatten: true });
+        for (const node of assignedNodes) {
+          collectFocusableElements(node);
+        }
+      } else {
+        // Process light DOM children in order
+        if (root.children) {
+          Array.from(root.children).forEach((child) => {
+            collectFocusableElements(child);
+          });
+        }
+      }
+    }
+  };
+
+  // Start the traversal from the container
+  collectFocusableElements(container);
+
+  // Remove duplicates that might have been collected through different paths
+  // while preserving order
+  const uniqueElements = [];
+  const seen = new Set();
+
+  for (const element of orderedFocusableElements) {
+    if (!seen.has(element)) {
+      seen.add(element);
+      uniqueElements.push(element);
+    }
+  }
+
+  // Move tab-indexed elements to the front while preserving their order
+  // This ensures that elements with tabindex are prioritized in the focus order
+
+  // First extract elements with valid positive tabindex
+  const elementsWithTabindex = uniqueElements.filter((el) => {
+    const tabindex = getNumericTabIndex$1(el);
+    return tabindex !== null && tabindex > 0;
+  });
+
+  // Sort these elements by their tabindex value
+  elementsWithTabindex.sort((a, b) => {
+    const aIndex = getNumericTabIndex$1(a) ?? 0;
+    const bIndex = getNumericTabIndex$1(b) ?? 0;
+    return aIndex - bIndex;
+  });
+
+  // Elements without tabindex (preserving their original order)
+  const elementsWithoutTabindex = uniqueElements.filter((el) => {
+    const tabindex = getNumericTabIndex$1(el);
+
+    // Elements without tabindex or with tabindex of 0 stay in DOM order
+    return tabindex === null || tabindex === 0;
+  });
+
+  // Combine both arrays with tabindex elements first
+  const tabIndexedUniqueElements = [
+    ...elementsWithTabindex,
+    ...elementsWithoutTabindex,
+  ];
+
+  return tabIndexedUniqueElements;
+}
+
 /* eslint-disable no-underscore-dangle */
 
 /**
@@ -870,6 +1052,82 @@ function reconcileMenuIndex(menu) {
   }
 }
 
+/**
+ * Commit the highlighted option and close the bib.
+ * @param {Element} component - The auro-combobox host element.
+ */
+function selectAndClose(component) {
+  reconcileMenuIndex(component.menu);
+  component.menu.makeSelection();
+  component.hideBib();
+}
+
+/**
+ * Whether `el` is currently visible enough to receive focus. Prefers the
+ * browser's `checkVisibility()` (Chrome/Safari; Firefox behind a flag until
+ * recently); otherwise combines a display/visibility check with an
+ * ancestor-hidden probe that keeps position:fixed elements visible.
+ * @param {Element} el - The element to test.
+ * @returns {boolean}
+ */
+function isVisibleForFocus(el) {
+  if (typeof el.checkVisibility === 'function') {
+    return el.checkVisibility();
+  }
+  const style = el.ownerDocument.defaultView.getComputedStyle(el);
+  if (style.display === 'none' || style.visibility === 'hidden') {
+    return false;
+  }
+  return el.offsetParent !== null || style.position === 'fixed';
+}
+
+/**
+ * Return the tab stop that comes before `component` in page tab order,
+ * skipping any hidden entries the walker doesn't filter itself.
+ * @param {Element} component - The auro-combobox host element.
+ * @returns {Element|null}
+ */
+function getPreviousTabStop(component) {
+  const tabStops = getFocusableElements$1(component.ownerDocument.body);
+  const componentIndex = tabStops.indexOf(component);
+  for (let index = componentIndex - 1; index >= 0; index -= 1) {
+    if (isVisibleForFocus(tabStops[index])) {
+      return tabStops[index];
+    }
+  }
+  return null;
+}
+
+/**
+ * Commit the highlighted option, close the bib, and move focus to the tab
+ * stop before the combobox — the Shift+Tab exit path (AB#1592239).
+ * Returns true when this function moved focus and the caller should
+ * preventDefault; false when no previous tab stop was found and the browser's
+ * native traversal should run.
+ * @param {Element} component - The auro-combobox host element.
+ * @returns {boolean}
+ */
+function selectAndExitBackward(component) {
+  const previousTabStop = getPreviousTabStop(component);
+
+  // Opts this selection out of setClearBtnFocus so the focus move below
+  // isn't clobbered. Consumed by auro-combobox's selection listener; also
+  // cleared via microtask in case makeSelection is a no-op and the listener
+  // never fires (microtasks run before the next user event, so this can't
+  // leak into an unrelated selection).
+  component._suppressClearBtnFocusOnSelection = true;
+  selectAndClose(component);
+  queueMicrotask(() => {
+    component._suppressClearBtnFocusOnSelection = false;
+  });
+
+  if (!previousTabStop) {
+    return false;
+  }
+  doubleRaf(() => previousTabStop.focus());
+  return true;
+}
+
 const comboboxKeyboardStrategy = {
   ArrowDown(component, evt, ctx) {
     // If the clear button has focus, let the browser handle ArrowDown normally.
@@ -969,18 +1227,17 @@ const comboboxKeyboardStrategy = {
 
   Tab(component, evt, ctx) {
     if (ctx.isExpanded && !isClearBtnFocused(ctx)) {
-      // When the clear button is focused, Tab events do not bubble out of
-      // its shadow DOM, so this handler only fires when the clear button
-      // is NOT focused. In that case, select the active option and close.
-      reconcileMenuIndex(component.menu);
-      component.menu.makeSelection();
-      component.hideBib();
+      if (evt.shiftKey) {
+        if (selectAndExitBackward(component)) {
+          evt.preventDefault();
+        }
+        return;
+      }
+
+      selectAndClose(component);
 
-      // In fullscreen modal mode, closing the dialog does not
-      // automatically restores focus to the input. In the tab case,
-      // Explicitly move focus to the trigger's clear button so the
-      // user can continues tabbing through the page normally.
-      if (ctx.isModal && !evt.shiftKey) {
+      if (ctx.isModal) {
+        // Fullscreen close does not automatically restore focus to the input.
         component.setClearBtnFocus();
       }
     }
@@ -3263,12 +3520,40 @@ class AuroFloatingUI {
       return;
     }
 
+    // Chrome-specific: during popover top-layer promotion after a click on a
+    // slotted focusable, :focus-within can briefly evaluate false while the
+    // active element is still structurally inside the trigger/bib. Fall back
+    // to a shadow-piercing ancestry walk from the deep active element before
+    // treating this as a real focus loss.
+    try {
+      let active = document.activeElement;
+      while (active && active.shadowRoot && active.shadowRoot.activeElement) {
+        active = active.shadowRoot.activeElement;
+      }
+      const targets = [element, element.trigger, element.bib].filter(Boolean);
+      let node = active;
+      while (node) {
+        if (targets.includes(node)) {
+          return;
+        }
+        node =
+          node.parentElement ||
+          (node.getRootNode && node.getRootNode().host) ||
+          null;
+      }
+    } catch (e) {
+      // Defensive: fall through to the existing close path if traversal fails.
+    }
+
     // if fullscreen bib is in fullscreen mode, do not close
     if (element.bib.hasAttribute("isfullscreen")) {
       return;
     }
 
-    this.hideBib("keydown");
+    // eventType "focusloss" distinguishes a Tab/click-driven close from an
+    // Escape keydown close. Consumers use this to decide whether to restore
+    // focus to the trigger (Escape) or let it advance naturally (Tab).
+    this.hideBib("focusloss");
   }
 
   setupHideHandlers() {
@@ -3938,199 +4223,6 @@ function getFocusableElements(container) {
   return tabIndexedUniqueElements;
 }
 
-/**
- * FocusTrap manages keyboard focus within a specified container element, ensuring that focus does not leave the container when tabbing.
- * It is commonly used for modal dialogs or overlays to improve accessibility by trapping focus within interactive UI components.
- */
-class FocusTrap {
-  /**
-   * Creates a new FocusTrap instance for the given container element.
-   * Initializes event listeners and prepares the container for focus management.
-   *
-   * @param {HTMLElement} container The DOM element to trap focus within.
-   * @param {boolean} [controlTabOrder=false] If true enables manual control of the tab order by the FocusTrap.
-   * @throws {Error} If the provided container is not a valid HTMLElement.
-   */
-  constructor(container, controlTabOrder = false) {
-    if (!container || !(container instanceof HTMLElement)) {
-      throw new Error("FocusTrap requires a valid HTMLElement.");
-    }
-
-    this.container = container;
-    this.tabDirection = "forward"; // or 'backward';
-    this.controlTabOrder = controlTabOrder;
-
-    this._init();
-  }
-
-  /**
-   * Initializes the focus trap by setting up event listeners and attributes on the container.
-   * Prepares the container for focus management, including support for shadow DOM and inert attributes.
-   *
-   * @private
-   */
-  _init() {
-    // Add inert attribute to prevent focusing programmatically as well (if supported)
-    if ("inert" in HTMLElement.prototype) {
-      this.container.inert = false; // Ensure the container isn't inert
-      this.container.setAttribute("data-focus-trap-container", true); // Mark for identification
-    }
-
-    // Track tab direction
-    this.container.addEventListener("keydown", this._onKeydown);
-  }
-
-  /**
-   * Gets an array of currently active (focused) elements in the document and shadow DOM.
-   * @returns {Array<HTMLElement>} An array of focusable elements within the container.
-   * @private
-   */
-  _getActiveElements() {
-    // Get the active element(s) in the document and shadow root
-    // This will include the active element in the shadow DOM if it exists
-    // Active element may be inside the shadow DOM depending on delegatesFocus, so we need to check both
-    let { activeElement } = document;
-    const actives = [activeElement];
-    while (activeElement?.shadowRoot?.activeElement) {
-      actives.push(activeElement.shadowRoot.activeElement);
-      activeElement = activeElement.shadowRoot.activeElement;
-    }
-    return actives;
-  }
-
-  /**
-   * Gets the next focus index based on the current index and focusable elements.
-   * @param {number} currentIndex The current index of the focused element.
-   * @param {Array<HTMLElement>} focusables The array of focusable elements.
-   * @returns {number|null} The next focus index or null if not determined.
-   */
-  _getNextFocusIndex(currentIndex, focusables, actives) {
-    if (this.controlTabOrder) {
-      // Calculate the new index based on the current index and tab direction
-      let newFocusIndex =
-        currentIndex + (this.tabDirection === "forward" ? 1 : -1);
-
-      // Wrap-around logic
-      if (newFocusIndex < 0) newFocusIndex = focusables.length - 1;
-      if (newFocusIndex >= focusables.length) newFocusIndex = 0;
-
-      // Early return with the new index
-      return newFocusIndex;
-    }
-
-    // Determine if we need to wrap
-    const atFirst =
-      actives.includes(focusables[0]) || actives.includes(this.container);
-    const atLast = actives.includes(focusables[focusables.length - 1]);
-
-    // Only wrap if at the ends
-    if (this.tabDirection === "backward" && atFirst) {
-      return focusables.length - 1;
-    }
-
-    if (this.tabDirection === "forward" && atLast) {
-      return 0;
-    }
-
-    // No wrap, so don't change focus, return early
-    return null;
-  }
-
-  /**
-   * Handles the Tab key press event to manage focus within the container.
-   * @param {KeyboardEvent} e The keyboard event triggered by the user.
-   * @returns {void}
-   */
-  _handleTabKey(e) {
-    // Update the focusable elements
-    const focusables = this._getFocusableElements();
-
-    // If there are no focusable elements, exit
-    if (!focusables.length) return;
-
-    // Set the tab direction based on the key pressed
-    this.tabDirection = e.shiftKey ? "backward" : "forward";
-
-    // Get the active elements that are currently focused
-    const actives = this._getActiveElements();
-
-    // If we're at either end of the focusable elements, wrap around to the other end
-    let focusIndex = focusables.findIndex((el) => actives.includes(el));
-
-    // Fallback if we have no focused element
-    if (focusIndex === -1) focusIndex = 0;
-
-    // Get the next focus index based on the current focus index, tab direction, and controlTabOrder setting
-    // Is null if no new focus index is determined
-    const newFocusIndex = this._getNextFocusIndex(
-      focusIndex,
-      focusables,
-      actives,
-    );
-
-    // If we have a new focus index, set focus to that element
-    if (newFocusIndex !== null) {
-      e.preventDefault();
-      focusables[newFocusIndex].focus();
-    }
-  }
-
-  /**
-   * Catches the keydown event
-   * @param {KeyboardEvent} e The keyboard event triggered by user interaction.
-   * @private
-   */
-  _onKeydown = (e) => {
-    // Handle tab
-    if (e.key === "Tab") this._handleTabKey(e);
-  };
-
-  /**
-   * Retrieves all focusable elements within the container in DOM order, including those in shadow DOM and slots.
-   * Returns a unique, ordered array of elements that can receive focus.
-   *
-   * @returns {Array<HTMLElement>} An array of focusable elements within the container.
-   * @private
-   */
-  _getFocusableElements() {
-    // Use the imported utility function to get focusable elements
-    const elements = getFocusableElements(this.container);
-
-    // Return the elements found
-    return elements;
-  }
-
-  /**
-   * Moves focus to the first focusable element within the container.
-   * Useful for setting initial focus when activating the focus trap.
-   */
-  focusFirstElement() {
-    const focusables = this._getFocusableElements();
-    if (focusables.length) focusables[0].focus();
-  }
-
-  /**
-   * Moves focus to the last focusable element within the container.
-   * Useful for setting focus when deactivating or cycling focus in reverse.
-   */
-  focusLastElement() {
-    const focusables = this._getFocusableElements();
-    if (focusables.length) focusables[focusables.length - 1].focus();
-  }
-
-  /**
-   * Removes event listeners and attributes added by the focus trap.
-   * Call this method to clean up when the focus trap is no longer needed.
-   */
-  disconnect() {
-    if (this.container.hasAttribute("data-focus-trap-container")) {
-      this.container.removeAttribute("data-focus-trap-container");
-    }
-
-    this.container.removeEventListener("keydown", this._onKeydown);
-  }
-}
-
 // Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.
 
@@ -4628,7 +4720,7 @@ class AuroDropdownBib extends i$3 {
     classes[`shape-${this.shape}`] = true;
 
     return u$7`
-      <dialog class="${e$2(classes)}" part="bibContainer" role="${o(this.dialogRole)}" aria-labelledby="${o(this.dialogLabel ? 'dialogLabel' : undefined)}">
+      <dialog tabindex="-1" class="${e$2(classes)}" part="bibContainer" role="${o(this.dialogRole)}" aria-labelledby="${o(this.dialogLabel ? 'dialogLabel' : undefined)}">
         ${this.dialogLabel ? u$7`<span id="dialogLabel" class="util_displayHiddenVisually">${this.dialogLabel}</span>` : ''}
         <slot></slot>
         <span id="srAnnouncement" class="util_displayHiddenVisually" aria-live="polite" role="status"></span>
@@ -4879,7 +4971,7 @@ let AuroHelpText$2 = class AuroHelpText extends i$3 {
   }
 };
 
-var formkitVersion$2 = '202607072023';
+var formkitVersion$2 = '202607102214';
 
 let AuroElement$2 = class AuroElement extends i$3 {
   static get properties() {
@@ -5633,7 +5725,10 @@ class AuroDropdown extends AuroElement$2 {
     }
 
 
-    if (!this.isPopoverVisible) {
+    // On Tab-driven close (eventType "focusloss"), let focus advance naturally
+    // — restoring to the trigger would trap the user on this dropdown, forcing
+    // an extra Tab to move on. Escape and outside-click still restore.
+    if (!this.isPopoverVisible && eventType !== "focusloss") {
       // wait til the bib gets fully closed and rendered
       setTimeout(() => {
         // Skip if the bib re-opened, or if focus moved intentionally outside the dropdown (not to body).
@@ -5863,15 +5958,16 @@ class AuroDropdown extends AuroElement$2 {
             }
           });
         } else {
-          // Normal desktop: use FocusTrap on the bib element.
-          // Defer focusFirstElement to the next frame because the popover
-          // is positioned asynchronously by Floating UI — calling focus()
-          // synchronously here would target elements with zero dimensions
-          // and the focus call would be silently ignored.
-          this.focusTrap = new FocusTrap(this.bibContent);
+          // Normal desktop (non-modal): move initial focus into the bib but
+          // don't trap Tab. Tab should exit the bib and let the floater's
+          // handleFocusLoss close it, matching native <select>/<details>
+          // behavior. Deferred one frame because Floating UI positions the
+          // popover asynchronously — a synchronous focus() would target
+          // zero-dimension elements and be silently ignored.
           requestAnimationFrame(() => {
-            if (this.focusTrap) {
-              this.focusTrap.focusFirstElement();
+            const focusables = getFocusableElements(this.bibContent);
+            if (focusables.length) {
+              focusables[0].focus();
             }
           });
         }
@@ -18504,7 +18600,7 @@ let AuroHelpText$1 = class AuroHelpText extends i$3 {
   }
 };
 
-var formkitVersion$1 = '202607072023';
+var formkitVersion$1 = '202607102214';
 
 // Copyright (c) 2025 Alaska Airlines. All right reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.
@@ -19625,7 +19721,7 @@ class AuroBibtemplate extends i$3 {
   }
 }
 
-var formkitVersion = '202607072023';
+var formkitVersion = '202607102214';
 
 var styleCss$3 = i$6`.util_displayInline{display:inline}.util_displayInlineBlock{display:inline-block}.util_displayBlock{display:block}.util_displayFlex{display:flex}.util_displayHidden{display:none}.util_displayHiddenVisually{position:absolute;overflow:hidden;clip:rect(1px, 1px, 1px, 1px);width:1px;height:1px;padding:0;border:0}:host{display:block;text-align:left}:host [auro-dropdown]{--ds-auro-dropdown-trigger-background-color: transparent}:host #inputInBib::part(wrapper){box-shadow:none}:host #inputInBib::part(accent-left){display:none}:host([layout*=classic]) [auro-input]{width:100%}:host([layout*=classic]) [auro-input]::part(helpText){display:none}:host([layout*=classic]) #slotHolder{display:none}`;
 
@@ -20408,6 +20504,8 @@ class AuroCombobox extends AuroElement {
 
       /**
        * If set, the `icon` attribute will be applied to the trigger `auro-input` element.
+       * Icon rendering is currently limited to `type="credit-card"`. Setting `triggerIcon`
+       * without a supported `type` propagates the attribute but does not render a visible icon.
        */
       triggerIcon: {
         type: Boolean,
@@ -20439,7 +20537,7 @@ class AuroCombobox extends AuroElement {
       },
 
       /**
-       * Value selected for the dropdown menu.
+       * Value selected for the dropdown menu. When set programmatically or as a preset attribute, the value must match a selectable option. If it matches an option marked `disabled` or `static`, the selection is rejected: `value` and `optionSelected` are cleared to `undefined`. `hidden` options (including those filtered out by type-ahead) remain selectable by value.
        */
       value: {
         type: String
@@ -20935,7 +21033,12 @@ class AuroCombobox extends AuroElement {
       this.dropdown.bibDialogLabel = labelElement.textContent.trim() || undefined;
     }
 
-    // Exposes the CSS parts from the bibtemplate for styling
+    if (this.customBibWidth) {
+      this.dropdown.dropdownWidth = this.customBibWidth;
+    }
+
+    // Exposes the CSS parts from the dropdown and bibtemplate for styling
+    this.dropdown.exposeCssParts();
     this.bibtemplate.exposeCssParts();
 
     this.hideBib = this.hideBib.bind(this);
@@ -21155,8 +21258,11 @@ class AuroCombobox extends AuroElement {
         // do not close while typing in suggestion mode with no value selected, to allow freeform input
         this.hideBib();
 
-        // Move focus to the clear button when the user makes a selection.
-        if (!isEcho && this.menu.value !== undefined) {
+        // Move focus to the clear button when the user makes a selection,
+        // unless the Shift+Tab handler opted this selection out.
+        if (this._suppressClearBtnFocusOnSelection) {
+          this._suppressClearBtnFocusOnSelection = false;
+        } else if (!isEcho && this.menu.value !== undefined) {
           this.setClearBtnFocus();
         }
 
@@ -21562,6 +21668,12 @@ class AuroCombobox extends AuroElement {
     this.value = undefined;
     this.typedValue = undefined;
     this.input.value = undefined;
+    // Fullscreen bib mounts a second auro-input that holds the user-facing
+    // native <input> on mobile; clearing only the trigger leaves stale text
+    // there when the bib is reopened after reset.
+    if (this.inputInBib) {
+      this.inputInBib.value = undefined;
+    }
     this.menu.value = undefined;
     this.validation.reset(this);
     this.touched = false;
@@ -21957,6 +22069,18 @@ var tokensCss = i$6`:host{--ds-auro-menu-divider-color: var(--ds-basic-color-bor
 // See LICENSE in the project root for license information.
 
 
+/**
+ * Serializes a multi-select value array back into the String `value` property.
+ * An empty (or missing) array collapses to `undefined` so an emptied selection
+ * clears `value` rather than reflecting a `"[]"` attribute.
+ * @private
+ * @param {Array<string>|undefined} values - The selected values.
+ * @returns {string|undefined} JSON string of the values, or undefined when empty.
+ */
+function serializeMultiSelectValue(values) {
+  return values && values.length > 0 ? JSON.stringify(values) : undefined;
+}
+
 /**
  * Validates if an option can be interacted with.
  * @private
@@ -21969,6 +22093,20 @@ function isOptionInteractive(option) {
          !option.hasAttribute('static');
 }
 
+/**
+ * Validates if an option may be selected by matching a programmatic value.
+ * Unlike `isOptionInteractive`, `hidden` is allowed: the combobox toggles
+ * `hidden` as its type-ahead filter, so a filtered-out option is still a
+ * valid programmatic selection. Only disabled and static options — which are
+ * never selectable — are rejected.
+ * @param {HTMLElement} option - The option to check.
+ * @returns {boolean} True if option can be selected by value.
+ */
+function isSelectableByValue(option) {
+  return !option.hasAttribute('disabled') &&
+         !option.hasAttribute('static');
+}
+
 /**
  * Helper method to dispatch custom events.
  * @param {HTMLElement} element - Element to dispatch event from.
@@ -22138,22 +22276,26 @@ class AuroMenu extends AuroElement {
 
       /**
        * Specifies the current active menuOption.
+       * @readonly
        */
       optionActive: {
         type: Object,
-        attribute: 'optionactive'
+        attribute: false
       },
 
       /**
-       * An array of currently selected menu options, type `HTMLElement` by default. In multi-select mode, `optionSelected` is an array of HTML elements.
+       * The currently selected menu option(s). In single-select mode this is a single `HTMLElement` (or `undefined` when nothing is selected). In multi-select mode this is an array of `HTMLElement`s.
+       * @readonly
        */
       optionSelected: {
         // Allow HTMLElement, HTMLElement[] arrays and undefined
-        type: Object
+        type: Object,
+        attribute: false
       },
 
       /**
        * The value of the selected option. In multi-select mode, this is a JSON stringified array of selected option values.
+       * Options marked `disabled` or `static` are not selectable by value; `hidden` options remain selectable. In single-select mode, if the value matches a non-selectable option the selection is cleared (`optionSelected` becomes `undefined`) and `auroMenu-selectValueFailure` is dispatched. In multi-select mode, non-selectable entries are dropped from the value and the remaining selectable entries are selected; `auroMenu-selectValueFailure` is dispatched only when none of the entries match a selectable option.
        */
       value: {
         type: String,
@@ -22277,7 +22419,7 @@ class AuroMenu extends AuroElement {
   }
 
   /**
-   * Selects options by value.
+   * Selects options by value. Options marked `disabled` or `static` are not selectable; `hidden` options remain selectable. In single-select mode, if the value matches a non-selectable option the selection is cleared and `auroMenu-selectValueFailure` is dispatched. In multi-select mode, non-selectable entries are dropped and the remaining selectable entries are selected; `auroMenu-selectValueFailure` is dispatched only when none of the entries match a selectable option. Passing `undefined`, `null`, an empty string, or an empty array clears the selection without dispatching a failure.
    * @param {string|string[]|undefined|null} value - The value(s) to select.
    * @public
    */
@@ -22362,6 +22504,11 @@ class AuroMenu extends AuroElement {
         this.initItems();
       }
 
+      // Set when reconciliation reassigns `value` below. That reassignment schedules a
+      // second updated() cycle, so the `event`-attribute dispatch is deferred to that
+      // cycle to avoid firing option custom events twice on the same selection.
+      let valueReconciled = false;
+
       // Handle null/undefined/empty case — empty/whitespace strings clear selection
       // consistently with selectByValue(''), and avoid downstream `.includes('')` matches.
       if (this.value === undefined || this.value === null || (typeof this.value === 'string' && this.value.trim() === '')) {
@@ -22374,11 +22521,31 @@ class AuroMenu extends AuroElement {
           // Defensive default: `formattedValue` can be undefined for unexpected value types,
           // and calling `.includes` on undefined would throw during reconciliation.
           const valueArray = this.formattedValue || [];
-          const matchingOptions = this.items ? this.items.filter((item) => valueArray.includes(item.value)) : [];
+          const matchingOptions = this.items ? this.items.filter((item) => isSelectableByValue(item) && valueArray.includes(item.value)) : [];
           newSelected = matchingOptions.length > 0 ? matchingOptions : undefined;
+
+          // Reconcile `value` with the selectable set. Drop only entries whose option is
+          // loaded but non-selectable (disabled/static) — leaving them would desync `value`
+          // from `optionSelected`, and the toggle handlers rebuild `value` from `formattedValue`,
+          // so the rejected entry would resurface on the next select/deselect. Entries with no
+          // matching item yet are preserved so async preselection still works once options render.
+          const rejectedValues = this.items
+            ? this.items.filter((item) => !isSelectableByValue(item) && valueArray.includes(item.value)).map((item) => item.value)
+            : [];
+          if (rejectedValues.length > 0) {
+            const reconciled = valueArray.filter((val) => !rejectedValues.includes(val));
+            this.value = serializeMultiSelectValue(reconciled);
+            valueReconciled = true;
+          }
         } else {
-          // In single-select mode, this.value should be a string
-          const matchingOption = this.items ? this.items.find((item) => item.value === this.value) : undefined;
+          // In single-select mode, this.value should be a string. Reject
+          // disabled/static options so a programmatic value pointing at a
+          // non-selectable option falls through to the no-match path below
+          // (dispatching auroMenu-selectValueFailure) instead of pinning it.
+          // `hidden` is intentionally NOT excluded: the combobox toggles
+          // `hidden` as its type-ahead filter, so a filtered-out option is
+          // still a valid programmatic selection.
+          const matchingOption = this.items ? this.items.find((item) => isSelectableByValue(item) && item.value === this.value) : undefined;
 
           if (matchingOption) {
             newSelected = matchingOption;
@@ -22420,8 +22587,9 @@ class AuroMenu extends AuroElement {
         ]
       ]));
 
-      // Notify of changes
-      if (this.optionSelected !== undefined) {
+      // Notify of changes. Skip when reconciliation just reassigned `value`: the
+      // follow-on update cycle re-runs this branch and fires the events exactly once.
+      if (this.optionSelected !== undefined && !valueReconciled) {
         const selected = Array.isArray(this.optionSelected) ? this.optionSelected : [this.optionSelected];
         selected.forEach((opt) => {
           if (opt.hasAttribute('event')) {
@@ -22634,7 +22802,7 @@ class AuroMenu extends AuroElement {
       const currentSelected = this.optionSelected || [];
 
       if (!currentValue.includes(option.value)) {
-        this.value = JSON.stringify([
+        this.value = serializeMultiSelectValue([
           ...currentValue,
           option.value
         ]);
@@ -22660,15 +22828,9 @@ class AuroMenu extends AuroElement {
    */
   handleDeselectState(option) {
     if (this.multiSelect) {
-      // Remove this option from array
+      // Remove this option from array; an empty result collapses `value` to undefined.
       const newFormattedValue = (this.formattedValue || []).filter((val) => val !== option.value);
-
-      // If array is empty after removal, set back to undefined
-      if (newFormattedValue && newFormattedValue.length === 0) {
-        this.value = undefined;
-      } else {
-        this.value = JSON.stringify(newFormattedValue);
-      }
+      this.value = serializeMultiSelectValue(newFormattedValue);
 
       this.optionSelected = this.optionSelected.filter((val) => val !== option);
       if (this.optionSelected.length === 0) {
@@ -22715,6 +22877,11 @@ class AuroMenu extends AuroElement {
     this.optionSelected = undefined;
     this._index = -1;
 
+    // Clear active option state so a follow-up open/navigation starts fresh
+    // rather than reusing a stale reference from before the reset.
+    this.items?.forEach((item) => item.classList.remove('active'));
+    this.optionActive = undefined;
+
     // Reset UI state
     this.updateItemsState(new Map([
       [
@@ -23124,6 +23291,7 @@ let menuOptionIdCounter = 0;
  * The `auro-menuoption` element provides users a way to define a menu option.
  * @customElement auro-menuoption
  *
+ * @attr {Boolean} static - When present, marks the option as non-interactive — it renders but is skipped during keyboard navigation and cannot be selected. Useful for section headers, informational rows inside a menu, or attaching event listeners.
  * @slot default - The default slot for the menu option text.
  *
  * @event auroMenuOption-mouseover - Notifies that this option has been hovered over.
@@ -23153,6 +23321,7 @@ class AuroMenuOption extends AuroElement {
     this.noCheckmark = false;
     this.disabled = false;
     this.noMatch = false;
+    this.persistent = false;
 
     /**
      * @private
@@ -23174,6 +23343,12 @@ class AuroMenuOption extends AuroElement {
         type: Boolean,
         reflect: true
       },
+
+      /**
+       * **Deprecated.** Use the `value` attribute on `auro-menu` to set the selected option when the menu renders (or call `menu.selectByValue(value)` programmatically). Support for the child-level `selected` attribute will be removed in a future major release.
+       *
+       * @deprecated Use the `value` attribute on `auro-menu` instead.
+       */
       selected: {
         type: Boolean,
         reflect: true
@@ -23208,6 +23383,12 @@ class AuroMenuOption extends AuroElement {
         reflect: true,
         attribute: 'nomatch'
       },
+
+      /** When true, this option is excluded from `matchWord` DOM rewriting — useful for utility rows (e.g., "Add new…") that must render identically regardless of the current filter. */
+      persistent: {
+        type: Boolean,
+        reflect: true
+      },
     };
   }