@aurodesignsystem-dev/auro-formkit 0.0.0-pr1541.3 → 0.0.0-pr1541.5

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,22 +448,26 @@ class AuroMenu extends AuroElement {
 
       /**
        * Specifies the current active menuOption.
+       * @readonly
        */
       optionActive: {
         type: Object,
-        attribute: 'optionactive'
+        attribute: false
       },
 
       /**
        * 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,22 +407,26 @@ class AuroMenu extends AuroElement {
 
       /**
        * Specifies the current active menuOption.
+       * @readonly
        */
       optionActive: {
         type: Object,
-        attribute: 'optionactive'
+        attribute: false
       },
 
       /**
        * 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 = '202607080002';
+var formkitVersion = '202607082148';
 
 // 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 = '202607080002';
+var formkitVersion = '202607082148';
 
 // 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 = '202607080002';
+var formkitVersion = '202607082148';
 
 // 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 = '202607080002';
+var formkitVersion = '202607082148';
 
 // 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 = '202607080002';
+var formkitVersion = '202607082148';
 
 // 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/select/demo/api.md

@@ -40,7 +40,7 @@ The `auro-select` element is a wrapper for auro-dropdown and auro-menu to create
 | `size`                          | `size`                          | `'lg' \| 'xl'`                                   |                  | Determines the size of the dropdown bib. Only the `emphasized` layout supports size=`xl`, while all other layouts support size=`lg`. |
 | `typeaheadTimeoutMs`            | `typeaheadTimeoutMs`            | `number`                                         | "500"            | Milliseconds of keyboard inactivity before the type-ahead buffer resets.<br />Increase for users who type slowly. |
 | `validity`                      | `validity`                      | `string`                                         |                  | Specifies the `validityState` this element is in. |
-| `value`                         | `value`                         | `string`                                         |                  | Value selected for the component.                |
+| `value`                         | `value`                         | `string`                                         |                  | 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. |
 
 ## Methods
 
@@ -48,7 +48,7 @@ The `auro-select` element is a wrapper for auro-dropdown and auro-menu to create
 |----------------------|----------------------------------------|--------------------------------------------------|
 | `hideBib`            | `(): void`                             | Hides the dropdown bib if its open.              |
 | `reset`              | `(): void`                             | Resets component to initial state.               |
-| `setMenuValue`       | `(value: any): void`                   |                                                  |
+| `setMenuValue`       | `(value: string): void`                | 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.<br /><br />**value**: The value to match against the menu options. |
 | `showBib`            | `(): void`                             | Shows the dropdown bib if there are options to show. |
 | `updateActiveOption` | `(index: number): void`                | Updates the active option in the menu.<br /><br />**index**: Index of the option to make active. |
 | `validate`           | `(force?: boolean \| undefined): void` | Validates value.<br /><br />**force**: Whether to force validation. |

package/components/select/demo/customize.md

@@ -907,6 +907,9 @@
 <p>The component may be rendered with one or more <code>disabled</code> options. When navigating the list of options with the keyboard or assistive technology to mark the next or previous option as active, disabled options will be skipped, jumping to the next enabled option.</p>
 <p>While using the pointer to mark options as active, hovering over disabled options will be ignored and the previous active option will remain active.</p>
 <p class="note">
+<strong>Note:</strong> Setting the component <code>value</code> to one that matches a <code>disabled</code> or <code>static</code> option — whether via the <code>value</code> attribute or programmatic assignment (e.g. <code>el.value = 'x'</code>) — is rejected: <code>value</code> and <code>optionSelected</code> are cleared to <code>undefined</code>. A value matching a <code>hidden</code> option is still applied.
+</p>
+<p class="note">
 <strong>Note:</strong> If the currently <code>selected</code> option is marked as <code>disabled</code>, the component value is reset to <code>undefined</code> and the component validation workflow is performed (e.g., if the component instance is <code>required</code> it will set <code>validity="valueMissing".</code>).
 </p>
 <p class="note">