@aurodesignsystem-dev/auro-formkit 0.0.0-pr1533.13 → 0.0.0-pr1533.14

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

@@ -1275,7 +1275,7 @@ class AuroHelpText extends i$2 {
   }
 }
 
-var formkitVersion = '202607081857';
+var formkitVersion = '202607082225';
 
 // Copyright (c) 2026 Alaska Airlines. All rights reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.

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

@@ -1275,7 +1275,7 @@ class AuroHelpText extends i$2 {
   }
 }
 
-var formkitVersion = '202607081857';
+var formkitVersion = '202607082225';
 
 // Copyright (c) 2026 Alaska Airlines. All rights reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.

package/components/checkbox/demo/index.min.js

@@ -1275,7 +1275,7 @@ class AuroHelpText extends i$2 {
   }
 }
 
-var formkitVersion = '202607081857';
+var formkitVersion = '202607082225';
 
 // Copyright (c) 2026 Alaska Airlines. All rights reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.

package/components/checkbox/dist/index.js

@@ -1228,7 +1228,7 @@ class AuroHelpText extends LitElement {
   }
 }
 
-var formkitVersion = '202607081857';
+var formkitVersion = '202607082225';
 
 // Copyright (c) 2026 Alaska Airlines. All rights reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.

package/components/checkbox/dist/registered.js

@@ -1228,7 +1228,7 @@ class AuroHelpText extends LitElement {
   }
 }
 
-var formkitVersion = '202607081857';
+var formkitVersion = '202607082225';
 
 // Copyright (c) 2026 Alaska Airlines. All rights reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.

package/components/combobox/demo/api.md

@@ -38,11 +38,11 @@ The `auro-combobox` element provides users with a way to select an option from a
 | `setCustomValidityValueMissing`       | `setCustomValidityValueMissing`       |           | `string`                                         |                  | Custom help text message to display when validity = `valueMissing`. |
 | `setCustomValidityValueMissingFilter` | `setCustomValidityValueMissingFilter` |           | `string`                                         |                  | Custom help text message to display when validity = `valueMissing` due to the user not choosing a menu option when behavior = "filter". |
 | `shift`                               | `shift`                               |           | `boolean`                                        |                  | If declared, the dropdown will shift its position to avoid being cut off by the viewport. |
-| `triggerIcon`                         | `triggerIcon`                         |           | `boolean`                                        |                  | If set, the `icon` attribute will be applied to the trigger `auro-input` element. |
+| `triggerIcon`                         | `triggerIcon`                         |           | `boolean`                                        |                  | If set, the `icon` attribute will be applied to the trigger `auro-input` element.<br />Icon rendering is currently limited to `type="credit-card"`. Setting `triggerIcon`<br />without a supported `type` propagates the attribute but does not render a visible icon. |
 | `type`                                | `type`                                |           | `string`                                         |                  | Applies the defined value as the type attribute on `auro-input`. |
 | `typedValue`                          | `typedValue`                          |           | `string`                                         |                  | Specifies the value of the input element within the combobox. |
 | `validity`                            | `validity`                            |           | `string`                                         |                  | Specifies the `validityState` this element is in. |
-| `value`                               | `value`                               |           | `string`                                         |                  | Value selected for the dropdown menu.            |
+| `value`                               | `value`                               |           | `string`                                         |                  | 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. |
 
 ## Methods
 

package/components/combobox/demo/customize.md

@@ -669,7 +669,7 @@
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 <auro-header level="3" id="inputType">Input Type</auro-header>
-<p>When defined, the <code>auro-input</code> in the combobox trigger will use the defined <code>type</code>. Use the <code>triggerIcon</code> attribute to provide context to the user about the expected input type.</p>
+<p>When defined, the <code>auro-input</code> in the combobox trigger will use the defined <code>type</code>. Use the <code>triggerIcon</code> attribute to provide context to the user about the expected input type. Icon rendering is currently limited to <code>type="credit-card"</code>; <code>triggerIcon</code> without a supported type propagates the attribute but does not render a visible icon.</p>
 <div class="exampleWrapper">
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/type_credit-card.html) -->
 <!-- The below content is automatically added from ./../apiExamples/type_credit-card.html -->

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

@@ -968,6 +968,23 @@ const comboboxKeyboardStrategy = {
   },
 
   Tab(component, evt, ctx) {
+    // Runs for both Tab and Shift+Tab.
+    //
+    // Current behavior:
+    //   Tab       — select the active option, close the bib, and (in fullscreen
+    //               modal mode only) explicitly move focus to the trigger's
+    //               clear button. In desktop popover mode the browser's native
+    //               tab traversal takes focus forward from the input.
+    //   Shift+Tab — select the active option and close the bib. Focus then
+    //               lands on the trigger's clear button as a byproduct of the
+    //               shadow-DOM tab order, so keyboard users must press
+    //               Shift+Tab three times to exit the component (clear button
+    //               → input → previous element on the page).
+    //
+    // Intended behavior for Shift+Tab (per team decision, tracked in
+    // AB#1590650): a single Shift+Tab should select the active option, close
+    // the bib, and move focus directly to the previous focusable element on
+    // the page — symmetric with Tab.
     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
@@ -4879,7 +4896,7 @@ let AuroHelpText$2 = class AuroHelpText extends i$3 {
   }
 };
 
-var formkitVersion$2 = '202607081857';
+var formkitVersion$2 = '202607082225';
 
 let AuroElement$2 = class AuroElement extends i$3 {
   static get properties() {
@@ -18504,7 +18521,7 @@ let AuroHelpText$1 = class AuroHelpText extends i$3 {
   }
 };
 
-var formkitVersion$1 = '202607081857';
+var formkitVersion$1 = '202607082225';
 
 // 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 +19642,7 @@ class AuroBibtemplate extends i$3 {
   }
 }
 
-var formkitVersion = '202607081857';
+var formkitVersion = '202607082225';
 
 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 +20425,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 +20458,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
@@ -21957,6 +21976,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 +22000,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 +22183,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 +22326,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 +22411,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 +22428,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 +22494,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 +22709,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 +22735,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 +22784,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 +23198,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 +23228,7 @@ class AuroMenuOption extends AuroElement {
     this.noCheckmark = false;
     this.disabled = false;
     this.noMatch = false;
+    this.persistent = false;
 
     /**
      * @private
@@ -23174,6 +23250,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 +23290,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
+      },
     };
   }
 

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

@@ -968,6 +968,23 @@ const comboboxKeyboardStrategy = {
   },
 
   Tab(component, evt, ctx) {
+    // Runs for both Tab and Shift+Tab.
+    //
+    // Current behavior:
+    //   Tab       — select the active option, close the bib, and (in fullscreen
+    //               modal mode only) explicitly move focus to the trigger's
+    //               clear button. In desktop popover mode the browser's native
+    //               tab traversal takes focus forward from the input.
+    //   Shift+Tab — select the active option and close the bib. Focus then
+    //               lands on the trigger's clear button as a byproduct of the
+    //               shadow-DOM tab order, so keyboard users must press
+    //               Shift+Tab three times to exit the component (clear button
+    //               → input → previous element on the page).
+    //
+    // Intended behavior for Shift+Tab (per team decision, tracked in
+    // AB#1590650): a single Shift+Tab should select the active option, close
+    // the bib, and move focus directly to the previous focusable element on
+    // the page — symmetric with Tab.
     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
@@ -4879,7 +4896,7 @@ let AuroHelpText$2 = class AuroHelpText extends i$3 {
   }
 };
 
-var formkitVersion$2 = '202607081857';
+var formkitVersion$2 = '202607082225';
 
 let AuroElement$2 = class AuroElement extends i$3 {
   static get properties() {
@@ -18504,7 +18521,7 @@ let AuroHelpText$1 = class AuroHelpText extends i$3 {
   }
 };
 
-var formkitVersion$1 = '202607081857';
+var formkitVersion$1 = '202607082225';
 
 // 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 +19642,7 @@ class AuroBibtemplate extends i$3 {
   }
 }
 
-var formkitVersion = '202607081857';
+var formkitVersion = '202607082225';
 
 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 +20425,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 +20458,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
@@ -21957,6 +21976,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 +22000,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 +22183,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 +22326,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 +22411,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 +22428,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 +22494,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 +22709,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 +22735,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 +22784,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 +23198,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 +23228,7 @@ class AuroMenuOption extends AuroElement {
     this.noCheckmark = false;
     this.disabled = false;
     this.noMatch = false;
+    this.persistent = false;
 
     /**
      * @private
@@ -23174,6 +23250,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 +23290,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
+      },
     };
   }
 

package/components/combobox/demo/index.md

@@ -136,6 +136,7 @@
 <auro-header level="3" id="presetValue">Preset the value</auro-header>
 <p>In some cases it is necessary to preset the value of the component as part of the initial render.</p>
 <p>When a value is preset, the matching option in the menu will be marked as both <code>active</code> and <code>selected</code>, and the input will display the corresponding text.</p>
+<p>If a preset value matches an option marked <code>disabled</code> or <code>static</code>, the selection is rejected: <code>value</code> and <code>optionSelected</code> are cleared to <code>undefined</code>. A value that matches a <code>hidden</code> option is still applied.</p>
 <p>If a preset value does not match any option, the component value is preserved and displayed in the input, but no menu option will be marked as selected. In suggestion mode, this value is treated as valid freeform input. In filter mode, the value will fail validation if the component is <code>required</code>.</p>
 <auro-header level="3" id="autocomplete">Autocomplete</auro-header>
 <p>The component supports the use of <auro-hyperlink href="https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/autocomplete">autocomplete</auro-hyperlink> configuration through HTML attributes.</p>