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

package/components/select/demo/customize.min.js

@@ -926,7 +926,7 @@ const selectKeyboardStrategy = {
   ArrowDown(component, evt, ctx) {
     evt.preventDefault();
     if (ctx.isExpanded) {
-      if (evt.altKey || evt.ctrlKey || evt.metaKey) {
+      if (evt.altKey || evt.ctrlKey) {
         // navigate to last enabled option
         selectKeyboardStrategy.End(component, evt, ctx);
       } else {
@@ -940,7 +940,7 @@ const selectKeyboardStrategy = {
   ArrowUp(component, evt, ctx) {
     evt.preventDefault();
     if (ctx.isExpanded) {
-      if (evt.altKey || evt.ctrlKey || evt.metaKey) {
+      if (evt.altKey || evt.ctrlKey) {
         // navigate to first enabled option
         selectKeyboardStrategy.Home(component, evt, ctx);
       } else {
@@ -3379,12 +3379,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() {
@@ -4054,199 +4082,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.
 
@@ -4744,7 +4579,7 @@ class AuroDropdownBib extends i$2 {
     classes[`shape-${this.shape}`] = true;
 
     return u$4`
-      <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$4`<span id="dialogLabel" class="util_displayHiddenVisually">${this.dialogLabel}</span>` : ''}
         <slot></slot>
         <span id="srAnnouncement" class="util_displayHiddenVisually" aria-live="polite" role="status"></span>
@@ -4995,7 +4830,7 @@ let AuroHelpText$1 = class AuroHelpText extends i$2 {
   }
 };
 
-var formkitVersion$1 = '202607072023';
+var formkitVersion$1 = '202607102214';
 
 class AuroElement extends i$2 {
   static get properties() {
@@ -5749,7 +5584,10 @@ class AuroDropdown extends AuroElement {
     }
 
 
-    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).
@@ -5979,15 +5817,16 @@ class AuroDropdown extends AuroElement {
             }
           });
         } 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();
             }
           });
         }
@@ -7034,7 +6873,7 @@ class AuroHelpText extends i$2 {
   }
 }
 
-var formkitVersion = '202607072023';
+var formkitVersion = '202607102214';
 
 var styleCss$2 = i$5`.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}.body-default{font-size:var(--wcss-body-default-font-size, 1rem);font-weight:var(--wcss-body-default-weight, );line-height:var(--wcss-body-default-line-height, 1.5rem)}.body-default,.body-default-emphasized{font-family:var(--wcss-body-family, "AS Circular"),system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;letter-spacing:var(--wcss-body-letter-spacing, 0)}.body-default-emphasized{font-size:var(--wcss-body-default-emphasized-font-size, 1rem);font-weight:var(--wcss-body-default-emphasized-weight, );line-height:var(--wcss-body-default-emphasized-line-height, 1.5rem)}.body-lg{font-size:var(--wcss-body-lg-font-size, 1.125rem);font-weight:var(--wcss-body-lg-weight, );line-height:var(--wcss-body-lg-line-height, 1.625rem)}.body-lg,.body-lg-emphasized{font-family:var(--wcss-body-family, "AS Circular"),system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;letter-spacing:var(--wcss-body-letter-spacing, 0)}.body-lg-emphasized{font-size:var(--wcss-body-lg-emphasized-font-size, 1.125rem);font-weight:var(--wcss-body-lg-emphasized-weight, );line-height:var(--wcss-body-lg-emphasized-line-height, 1.625rem)}.body-sm{font-size:var(--wcss-body-sm-font-size, 0.875rem);font-weight:var(--wcss-body-sm-weight, );line-height:var(--wcss-body-sm-line-height, 1.25rem)}.body-sm,.body-sm-emphasized{font-family:var(--wcss-body-family, "AS Circular"),system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;letter-spacing:var(--wcss-body-letter-spacing, 0)}.body-sm-emphasized{font-size:var(--wcss-body-sm-emphasized-font-size, 0.875rem);font-weight:var(--wcss-body-sm-emphasized-weight, );line-height:var(--wcss-body-sm-emphasized-line-height, 1.25rem)}.body-xs{font-size:var(--wcss-body-xs-font-size, 0.75rem);font-weight:var(--wcss-body-xs-weight, );line-height:var(--wcss-body-xs-line-height, 1rem)}.body-xs,.body-xs-emphasized{font-family:var(--wcss-body-family, "AS Circular"),system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;letter-spacing:var(--wcss-body-letter-spacing, 0)}.body-xs-emphasized{font-size:var(--wcss-body-xs-emphasized-font-size, 0.75rem);font-weight:var(--wcss-body-xs-emphasized-weight, );line-height:var(--wcss-body-xs-emphasized-line-height, 1rem)}.body-2xs{font-size:var(--wcss-body-2xs-font-size, 0.625rem);font-weight:var(--wcss-body-2xs-weight, );line-height:var(--wcss-body-2xs-line-height, 0.875rem)}.body-2xs,.body-2xs-emphasized{font-family:var(--wcss-body-family, "AS Circular"),system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif;letter-spacing:var(--wcss-body-letter-spacing, 0)}.body-2xs-emphasized{font-size:var(--wcss-body-2xs-emphasized-font-size, 0.625rem);font-weight:var(--wcss-body-2xs-emphasized-weight, );line-height:var(--wcss-body-2xs-emphasized-line-height, 0.875rem)}.display-2xl{font-family:var(--wcss-display-2xl-family, "AS Circular"),var(--wcss-display-2xl-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-display-2xl-font-size, clamp(3.5rem, 6vw, 5.375rem));font-weight:var(--wcss-display-2xl-weight, 300);letter-spacing:var(--wcss-display-2xl-letter-spacing, 0);line-height:var(--wcss-display-2xl-line-height, 1.3)}.display-xl{font-family:var(--wcss-display-xl-family, "AS Circular"),var(--wcss-display-xl-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-display-xl-font-size, clamp(3rem, 5.3333333333vw, 4.5rem));font-weight:var(--wcss-display-xl-weight, 300);letter-spacing:var(--wcss-display-xl-letter-spacing, 0);line-height:var(--wcss-display-xl-line-height, 1.3)}.display-lg{font-family:var(--wcss-display-lg-family, "AS Circular"),var(--wcss-display-lg-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-display-lg-font-size, clamp(2.75rem, 4.6666666667vw, 4rem));font-weight:var(--wcss-display-lg-weight, 300);letter-spacing:var(--wcss-display-lg-letter-spacing, 0);line-height:var(--wcss-display-lg-line-height, 1.3)}.display-md{font-family:var(--wcss-display-md-family, "AS Circular"),var(--wcss-display-md-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-display-md-font-size, clamp(2.5rem, 4vw, 3.5rem));font-weight:var(--wcss-display-md-weight, 300);letter-spacing:var(--wcss-display-md-letter-spacing, 0);line-height:var(--wcss-display-md-line-height, 1.3)}.display-sm{font-family:var(--wcss-display-sm-family, "AS Circular"),var(--wcss-display-sm-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-display-sm-font-size, clamp(2rem, 3.6666666667vw, 3rem));font-weight:var(--wcss-display-sm-weight, 300);letter-spacing:var(--wcss-display-sm-letter-spacing, 0);line-height:var(--wcss-display-sm-line-height, 1.3)}.display-xs{font-family:var(--wcss-display-xs-family, "AS Circular"),var(--wcss-display-xs-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-display-xs-font-size, clamp(1.75rem, 3vw, 2.375rem));font-weight:var(--wcss-display-xs-weight, 300);letter-spacing:var(--wcss-display-xs-letter-spacing, 0);line-height:var(--wcss-display-xs-line-height, 1.3)}.heading-xl{font-family:var(--wcss-heading-xl-family, "AS Circular"),var(--wcss-heading-xl-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-heading-xl-font-size, clamp(2rem, 3vw, 2.5rem));font-weight:var(--wcss-heading-xl-weight, 300);letter-spacing:var(--wcss-heading-xl-letter-spacing, 0);line-height:var(--wcss-heading-xl-line-height, 1.3)}.heading-lg{font-family:var(--wcss-heading-lg-family, "AS Circular"),var(--wcss-heading-lg-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-heading-lg-font-size, clamp(1.75rem, 2.6666666667vw, 2.25rem));font-weight:var(--wcss-heading-lg-weight, 300);letter-spacing:var(--wcss-heading-lg-letter-spacing, 0);line-height:var(--wcss-heading-lg-line-height, 1.3)}.heading-md{font-family:var(--wcss-heading-md-family, "AS Circular"),var(--wcss-heading-md-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-heading-md-font-size, clamp(1.625rem, 2.3333333333vw, 1.75rem));font-weight:var(--wcss-heading-md-weight, 300);letter-spacing:var(--wcss-heading-md-letter-spacing, 0);line-height:var(--wcss-heading-md-line-height, 1.3)}.heading-sm{font-family:var(--wcss-heading-sm-family, "AS Circular"),var(--wcss-heading-sm-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-heading-sm-font-size, clamp(1.375rem, 2vw, 1.5rem));font-weight:var(--wcss-heading-sm-weight, 300);letter-spacing:var(--wcss-heading-sm-letter-spacing, 0);line-height:var(--wcss-heading-sm-line-height, 1.3)}.heading-xs{font-family:var(--wcss-heading-xs-family, "AS Circular"),var(--wcss-heading-xs-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-heading-xs-font-size, clamp(1.25rem, 1.6666666667vw, 1.25rem));font-weight:var(--wcss-heading-xs-weight, 300);letter-spacing:var(--wcss-heading-xs-letter-spacing, 0);line-height:var(--wcss-heading-xs-line-height, 1.3)}.heading-2xs{font-family:var(--wcss-heading-2xs-family, "AS Circular"),var(--wcss-heading-2xs-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-heading-2xs-font-size, clamp(1.125rem, 1.5vw, 1.125rem));font-weight:var(--wcss-heading-2xs-weight, 300);letter-spacing:var(--wcss-heading-2xs-letter-spacing, 0);line-height:var(--wcss-heading-2xs-line-height, 1.3)}.accent-2xl{font-family:var(--wcss-accent-2xl-family, "Good OT"),var(--wcss-accent-2xl-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-accent-2xl-font-size, clamp(2rem, 3.1666666667vw, 2.375rem));font-weight:var(--wcss-accent-2xl-weight, 450);letter-spacing:var(--wcss-accent-2xl-letter-spacing, 0.05em);line-height:var(--wcss-accent-2xl-line-height, 1)}.accent-2xl,.accent-xl{text-transform:uppercase}.accent-xl{font-family:var(--wcss-accent-xl-family, "Good OT"),var(--wcss-accent-xl-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-accent-xl-font-size, clamp(1.625rem, 2.3333333333vw, 2rem));font-weight:var(--wcss-accent-xl-weight, 450);letter-spacing:var(--wcss-accent-xl-letter-spacing, 0.05em);line-height:var(--wcss-accent-xl-line-height, 1.3)}.accent-lg{font-family:var(--wcss-accent-lg-family, "Good OT"),var(--wcss-accent-lg-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-accent-lg-font-size, clamp(1.5rem, 2.1666666667vw, 1.75rem));font-weight:var(--wcss-accent-lg-weight, 450);letter-spacing:var(--wcss-accent-lg-letter-spacing, 0.05em);line-height:var(--wcss-accent-lg-line-height, 1.3)}.accent-lg,.accent-md{text-transform:uppercase}.accent-md{font-family:var(--wcss-accent-md-family, "Good OT"),var(--wcss-accent-md-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-accent-md-font-size, clamp(1.375rem, 1.8333333333vw, 1.5rem));font-weight:var(--wcss-accent-md-weight, 500);letter-spacing:var(--wcss-accent-md-letter-spacing, 0.05em);line-height:var(--wcss-accent-md-line-height, 1.3)}.accent-sm{font-family:var(--wcss-accent-sm-family, "Good OT"),var(--wcss-accent-sm-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-accent-sm-font-size, clamp(1.125rem, 1.5vw, 1.25rem));font-weight:var(--wcss-accent-sm-weight, 500);letter-spacing:var(--wcss-accent-sm-letter-spacing, 0.05em);line-height:var(--wcss-accent-sm-line-height, 1.3)}.accent-sm,.accent-xs{text-transform:uppercase}.accent-xs{font-family:var(--wcss-accent-xs-family, "Good OT"),var(--wcss-accent-xs-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-accent-xs-font-size, clamp(1rem, 1.3333333333vw, 1rem));font-weight:var(--wcss-accent-xs-weight, 500);letter-spacing:var(--wcss-accent-xs-letter-spacing, 0.1em);line-height:var(--wcss-accent-xs-line-height, 1.3)}.accent-2xs{font-family:var(--wcss-accent-2xs-family, "Good OT"),var(--wcss-accent-2xs-family-fallback, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif);font-size:var(--wcss-accent-2xs-font-size, clamp(0.875rem, 1.1666666667vw, 0.875rem));font-weight:var(--wcss-accent-2xs-weight, 450);letter-spacing:var(--wcss-accent-2xs-letter-spacing, 0.1em);line-height:var(--wcss-accent-2xs-line-height, 1.3);text-transform:uppercase}[auro-dropdown]{--ds-auro-dropdown-trigger-border-color: var(--ds-auro-select-border-color);--ds-auro-dropdown-trigger-background-color: var(--ds-auro-select-background-color);--ds-auro-dropdown-trigger-container-color: var(--ds-auro-select-background-color);--ds-auro-dropdown-trigger-outline-color: var(--ds-auro-select-outline-color)}:host{display:inline-block;text-align:left;vertical-align:top}:host([layout*=emphasized]) [auro-dropdown],:host([layout*=snowflake]) [auro-dropdown]{--ds-auro-select-border-color: transparent}:host([layout*=emphasized]) .mainContent,:host([layout*=snowflake]) .mainContent{text-align:center}.mainContent{position:relative;display:flex;overflow:hidden;flex:1;flex-direction:column;align-items:center;justify-content:center}.valueContainer [slot=displayValue]{display:none}.accents{display:flex;flex-direction:row;align-items:center;justify-content:center}::slotted([slot=typeIcon]){margin-right:var(--ds-size-100, 0.5rem)}.displayValue{display:block}.displayValue:not(.force){display:none}.displayValue:not(.force).hasContent:is(.withValue):not(.hasFocus){display:block}.triggerContent{display:flex;width:100%;align-items:center;justify-content:center}:host([layout*=emphasized]) .triggerContent{padding:0 var(--ds-size-100, 0.5rem) 0 var(--ds-size-300, 1.5rem)}:host([layout*=snowflake]) .triggerContent{padding:0 var(--ds-size-100, 0.5rem) 0 var(--ds-size-200, 1rem)}:host([layout*=snowflake]) label{padding-block:var(--ds-size-25, 0.125rem)}:host([layout*=classic]) .triggerContent{padding:0 var(--ds-size-100, 0.5rem)}:host([layout*=classic]) .mainContent{align-items:start}:host([layout*=classic]) label{overflow:hidden;cursor:text;text-overflow:ellipsis;white-space:nowrap}:host([layout*=classic]) .value{height:auto}label{color:var(--ds-auro-select-label-text-color)}:host(:is([validity]:not([validity=valid]))) [auro-dropdown]{--ds-auro-select-border-color: var(--ds-basic-color-status-error, #e31f26);--ds-auro-select-outline-color: var(--ds-basic-color-status-error, #e31f26);--ds-auro-dropdown-helptext-text-color: var(--ds-basic-color-texticon-default, #2a2a2a)}:host([ondark]:is([validity]:not([validity=valid]))) [auro-dropdown],:host([appearance=inverse]:is([validity]:not([validity=valid]))) [auro-dropdown]{--ds-auro-select-border-color: var(--ds-advanced-color-state-error-inverse, #f9a4a8);--ds-auro-select-outline-color: var(--ds-advanced-color-state-error-inverse, #f9a4a8);--ds-auro-dropdown-helptext-text-color: var(--ds-basic-color-texticon-inverse, #ffffff)}#slotHolder{display:none}:host([fluid]){width:100%}:host([disabled]){pointer-events:none;user-select:none}:host([disabled]:not([ondark])) [auro-dropdown],:host([disabled]:not([appearance=inverse])) [auro-dropdown]{--ds-auro-select-border-color: var(--ds-basic-color-border-subtle, #dddddd)}:host(:not([layout*=classic])[disabled][ondark]) [auro-dropdown],:host(:not([layout*=classic])[disabled][appearance=inverse]) [auro-dropdown]{--ds-auro-select-border-color: transparent}`;
 
@@ -7476,7 +7315,7 @@ class AuroSelect extends AuroElement$1 {
       },
 
       /**
-       * Value selected for the component.
+       * Value selected for the component. 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` is cleared to `undefined` while `optionSelected` is cleared to `undefined` in single-select or `[]` in multiSelect. `hidden` options remain selectable by value.
        */
       value: {
         type: String,
@@ -8296,6 +8135,10 @@ class AuroSelect extends AuroElement$1 {
     this._observeLabelChanges();
   }
 
+  /**
+   * Sets the selected value by matching it against the menu options. Options marked `disabled` or `static` are not selectable: if the value matches one, the selection is rejected and `value` is cleared to `undefined` while `optionSelected` is cleared to `undefined` in single-select or `[]` in multiSelect. `hidden` options remain selectable.
+   * @param {string} value - The value to match against the menu options.
+   */
   setMenuValue(value) {
     if (!this.menu) return;
     this.menu.selectByValue(value);
@@ -8823,6 +8666,18 @@ var tokensCss = i$5`: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
@@ -8835,6 +8690,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.
@@ -9004,22 +8873,26 @@ class AuroMenu extends AuroElement$1 {
 
       /**
        * 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,
@@ -9143,7 +9016,7 @@ class AuroMenu extends AuroElement$1 {
   }
 
   /**
-   * 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
    */
@@ -9228,6 +9101,11 @@ class AuroMenu extends AuroElement$1 {
         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() === '')) {
@@ -9240,11 +9118,31 @@ class AuroMenu extends AuroElement$1 {
           // 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;
@@ -9286,8 +9184,9 @@ class AuroMenu extends AuroElement$1 {
         ]
       ]));
 
-      // 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')) {
@@ -9500,7 +9399,7 @@ class AuroMenu extends AuroElement$1 {
       const currentSelected = this.optionSelected || [];
 
       if (!currentValue.includes(option.value)) {
-        this.value = JSON.stringify([
+        this.value = serializeMultiSelectValue([
           ...currentValue,
           option.value
         ]);
@@ -9526,15 +9425,9 @@ class AuroMenu extends AuroElement$1 {
    */
   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) {
@@ -9581,6 +9474,11 @@ class AuroMenu extends AuroElement$1 {
     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([
       [
@@ -9990,6 +9888,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.
@@ -10019,6 +9918,7 @@ class AuroMenuOption extends AuroElement$1 {
     this.noCheckmark = false;
     this.disabled = false;
     this.noMatch = false;
+    this.persistent = false;
 
     /**
      * @private
@@ -10040,6 +9940,12 @@ class AuroMenuOption extends AuroElement$1 {
         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
@@ -10074,6 +9980,12 @@ class AuroMenuOption extends AuroElement$1 {
         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
+      },
     };
   }
 

package/components/select/demo/design.md

@@ -340,19 +340,19 @@
 <span slot="helpText">Help Text</span>
 <auro-menu nocheckmark>
 <auro-menuoption value="flights">
-<auro-icon category="terminal" name="plane-diag-stroke" customColor></auro-icon> Flights
+<auro-icon category="terminal" name="plane-diag-stroke" customcolor></auro-icon> Flights
 </auro-menuoption>
 <auro-menuoption value="cars">
-<auro-icon category="destination" name="car-rental-stroke" customColor></auro-icon> Cars
+<auro-icon category="destination" name="car-rental-stroke" customcolor></auro-icon> Cars
 </auro-menuoption>
 <auro-menuoption value="hotels">
-<auro-icon category="destination" name="hotel-stroke" customColor></auro-icon> Hotels
+<auro-icon category="destination" name="hotel-stroke" customcolor></auro-icon> Hotels
 </auro-menuoption>
 <auro-menuoption value="packages">
-<auro-icon category="shop" name="gift-stroke" customColor></auro-icon> Packages
+<auro-icon category="shop" name="gift-stroke" customcolor></auro-icon> Packages
 </auro-menuoption>
 <auro-menuoption value="cruises">
-<auro-icon category="in-flight" name="boarding" customColor></auro-icon> Cruises
+<auro-icon category="in-flight" name="boarding" customcolor></auro-icon> Cruises
 </auro-menuoption>
 </auro-menu>
 </auro-select>
@@ -368,19 +368,19 @@
   &lt;span slot="helpText"&gt;Help Text&lt;/span&gt;
   &lt;auro-menu nocheckmark&gt;
     &lt;auro-menuoption value="flights"&gt;
-      &lt;auro-icon category="terminal" name="plane-diag-stroke" customColor&gt;&lt;/auro-icon&gt; Flights
+      &lt;auro-icon category="terminal" name="plane-diag-stroke" customcolor&gt;&lt;/auro-icon&gt; Flights
     &lt;/auro-menuoption&gt;
     &lt;auro-menuoption value="cars"&gt;
-      &lt;auro-icon category="destination" name="car-rental-stroke" customColor&gt;&lt;/auro-icon&gt; Cars
+      &lt;auro-icon category="destination" name="car-rental-stroke" customcolor&gt;&lt;/auro-icon&gt; Cars
     &lt;/auro-menuoption&gt;
     &lt;auro-menuoption value="hotels"&gt;
-      &lt;auro-icon category="destination" name="hotel-stroke" customColor&gt;&lt;/auro-icon&gt; Hotels
+      &lt;auro-icon category="destination" name="hotel-stroke" customcolor&gt;&lt;/auro-icon&gt; Hotels
     &lt;/auro-menuoption&gt;
     &lt;auro-menuoption value="packages"&gt;
-      &lt;auro-icon category="shop" name="gift-stroke" customColor&gt;&lt;/auro-icon&gt; Packages
+      &lt;auro-icon category="shop" name="gift-stroke" customcolor&gt;&lt;/auro-icon&gt; Packages
     &lt;/auro-menuoption&gt;
     &lt;auro-menuoption value="cruises"&gt;
-      &lt;auro-icon category="in-flight" name="boarding" customColor&gt;&lt;/auro-icon&gt; Cruises
+      &lt;auro-icon category="in-flight" name="boarding" customcolor&gt;&lt;/auro-icon&gt; Cruises
     &lt;/auro-menuoption&gt;
   &lt;/auro-menu&gt;
 &lt;/auro-select&gt;</code></pre>

package/components/select/demo/getting-started.md

@@ -390,7 +390,7 @@ Ensure your `tsconfig.json` uses `"moduleResolution": "bundler"` so TypeScript c
 <auro-header level="3" id="validity">validity</auro-header>
 <p>Returns the current <code>validityState</code> of the component as a string. Possible values include <code>"valid"</code>, <code>"valueMissing"</code>, and <code>"customError"</code>.</p>
 <auro-header level="3" id="value">value</auro-header>
-<p>Gets or sets the selected value of the select. When set programmatically, the component will attempt to match and select the corresponding menu option.</p>
+<p>Gets or sets the selected value of the select. When set programmatically, the component will attempt to match and select the corresponding menu option. If the value matches an option marked <code>disabled</code> or <code>static</code>, the selection is rejected and <code>value</code> is cleared to <code>undefined</code>. <code>hidden</code> options remain selectable by value.</p>
 </section>
 <section>
 <auro-header level="2" id="publicFunctions">Functions</auro-header>