@aurodesignsystem-dev/auro-formkit 0.0.0-pr1541.2 → 0.0.0-pr1541.4

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

@@ -221,6 +221,18 @@ class AuroLibraryRuntimeUtils {
 // 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
@@ -233,6 +245,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.
@@ -415,6 +441,7 @@ class AuroMenu extends AuroElement {
 
       /**
        * Specifies the current active menuOption.
+       * @readonly
        */
       optionActive: {
         type: Object,
@@ -423,14 +450,17 @@ class AuroMenu extends AuroElement {
 
       /**
        * 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,
@@ -554,7 +584,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
    */
@@ -639,6 +669,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() === '')) {
@@ -651,11 +686,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;
@@ -697,8 +752,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')) {
@@ -911,7 +967,7 @@ class AuroMenu extends AuroElement {
       const currentSelected = this.optionSelected || [];
 
       if (!currentValue.includes(option.value)) {
-        this.value = JSON.stringify([
+        this.value = serializeMultiSelectValue([
           ...currentValue,
           option.value
         ]);
@@ -937,15 +993,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) {
@@ -1459,6 +1509,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.
@@ -1853,7 +1904,7 @@ function initExamples(pending, initCount) {
   for (const fn of pending) {
     try {
       fn();
-    } catch (err) {
+    } catch {
       stillPending.push(fn);
     }
   }

package/components/menu/dist/auro-menu-utils.d.ts

@@ -10,6 +10,15 @@
  * or if the value cannot be parsed into an array from a JSON string.
  */
 export function arrayConverter(value: any): any[] | undefined;
+/**
+ * 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.
+ */
+export function serializeMultiSelectValue(values: Array<string> | undefined): string | undefined;
 /**
  * Compare two arrays for equality.
  * @private
@@ -25,6 +34,16 @@ export function arraysAreEqual(arr1: any[], arr2: any[]): boolean;
  * @returns {boolean} True if option is interactive.
  */
 export function isOptionInteractive(option: HTMLElement): boolean;
+/**
+ * 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.
+ */
+export function isSelectableByValue(option: HTMLElement): boolean;
 /**
  * Helper method to dispatch custom events.
  * @param {HTMLElement} element - Element to dispatch event from.

package/components/menu/dist/auro-menu.d.ts

@@ -60,21 +60,17 @@ export class AuroMenu extends AuroElement {
             reflect: boolean;
             attribute: string;
         };
-        /**
-         * Specifies the current active menuOption.
-         */
         optionActive: {
             type: ObjectConstructor;
             attribute: string;
         };
-        /**
-         * 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.
-         */
         optionSelected: {
             type: ObjectConstructor;
+            attribute: boolean;
         };
         /**
          * 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: StringConstructor;
@@ -171,7 +167,7 @@ export class AuroMenu extends AuroElement {
      */
     private get formattedValue();
     /**
-     * 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
      */

package/components/menu/dist/auro-menuoption.d.ts

@@ -2,6 +2,7 @@
  * 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.

package/components/menu/dist/index.js

@@ -241,6 +241,18 @@ function arrayConverter(value) {
   throw new Error('Invalid value: Input must be an array or undefined');
 }
 
+/**
+ * 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
@@ -253,6 +265,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.
@@ -422,6 +448,7 @@ class AuroMenu extends AuroElement {
 
       /**
        * Specifies the current active menuOption.
+       * @readonly
        */
       optionActive: {
         type: Object,
@@ -430,14 +457,17 @@ class AuroMenu extends AuroElement {
 
       /**
        * 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,
@@ -561,7 +591,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
    */
@@ -646,6 +676,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() === '')) {
@@ -658,11 +693,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;
@@ -704,8 +759,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')) {
@@ -918,7 +974,7 @@ class AuroMenu extends AuroElement {
       const currentSelected = this.optionSelected || [];
 
       if (!currentValue.includes(option.value)) {
-        this.value = JSON.stringify([
+        this.value = serializeMultiSelectValue([
           ...currentValue,
           option.value
         ]);
@@ -944,15 +1000,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) {
@@ -1453,6 +1503,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.

package/components/menu/dist/registered.js

@@ -200,6 +200,18 @@ class AuroLibraryRuntimeUtils {
 // 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
@@ -212,6 +224,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.
@@ -381,6 +407,7 @@ class AuroMenu extends AuroElement {
 
       /**
        * Specifies the current active menuOption.
+       * @readonly
        */
       optionActive: {
         type: Object,
@@ -389,14 +416,17 @@ class AuroMenu extends AuroElement {
 
       /**
        * 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,
@@ -520,7 +550,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
    */
@@ -605,6 +635,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() === '')) {
@@ -617,11 +652,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;
@@ -663,8 +718,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')) {
@@ -877,7 +933,7 @@ class AuroMenu extends AuroElement {
       const currentSelected = this.optionSelected || [];
 
       if (!currentValue.includes(option.value)) {
-        this.value = JSON.stringify([
+        this.value = serializeMultiSelectValue([
           ...currentValue,
           option.value
         ]);
@@ -903,15 +959,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) {
@@ -1412,6 +1462,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.

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

@@ -1227,7 +1227,7 @@ class AuroHelpText extends i$2 {
   }
 }
 
-var formkitVersion = '202607072330';
+var formkitVersion = '202607082038';
 
 // Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.

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

@@ -1227,7 +1227,7 @@ class AuroHelpText extends i$2 {
   }
 }
 
-var formkitVersion = '202607072330';
+var formkitVersion = '202607082038';
 
 // Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.

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

@@ -1227,7 +1227,7 @@ class AuroHelpText extends i$2 {
   }
 }
 
-var formkitVersion = '202607072330';
+var formkitVersion = '202607082038';
 
 // Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.

package/components/radio/dist/index.js

@@ -1166,7 +1166,7 @@ class AuroHelpText extends LitElement {
   }
 }
 
-var formkitVersion = '202607072330';
+var formkitVersion = '202607082038';
 
 // Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.

package/components/radio/dist/registered.js

@@ -1166,7 +1166,7 @@ class AuroHelpText extends LitElement {
   }
 }
 
-var formkitVersion = '202607072330';
+var formkitVersion = '202607082038';
 
 // Copyright (c) Alaska Air. All right reserved. Licensed under the Apache-2.0 license
 // See LICENSE in the project root for license information.