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

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.
@@ -13,6 +14,11 @@ export class AuroMenuOption extends AuroElement {
             type: BooleanConstructor;
             reflect: boolean;
         };
+        /**
+         * **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: BooleanConstructor;
             reflect: boolean;
@@ -45,6 +51,11 @@ export class AuroMenuOption extends AuroElement {
             reflect: boolean;
             attribute: string;
         };
+        /** 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: BooleanConstructor;
+            reflect: boolean;
+        };
         layout: {
             type: StringConstructor;
             attribute: string;
@@ -74,6 +85,7 @@ export class AuroMenuOption extends AuroElement {
     noCheckmark: boolean;
     disabled: boolean;
     noMatch: boolean;
+    persistent: boolean;
     /**
      * @private
      */

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
       },
 
       /**
-       * 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,
@@ -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) {
@@ -999,6 +1049,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([
       [
@@ -1448,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.
@@ -1477,6 +1533,7 @@ class AuroMenuOption extends AuroElement {
     this.noCheckmark = false;
     this.disabled = false;
     this.noMatch = false;
+    this.persistent = false;
 
     /**
      * @private
@@ -1498,6 +1555,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
@@ -1532,6 +1595,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/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
       },
 
       /**
-       * 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,
@@ -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) {
@@ -958,6 +1008,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([
       [
@@ -1407,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.
@@ -1436,6 +1492,7 @@ class AuroMenuOption extends AuroElement {
     this.noCheckmark = false;
     this.disabled = false;
     this.noMatch = false;
+    this.persistent = false;
 
     /**
      * @private
@@ -1457,6 +1514,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
@@ -1491,6 +1554,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/radio/demo/accessibility.md

@@ -4,7 +4,7 @@
 <div class="scrollWrapper">
 The `auro-radio` component follows native HTML radio button semantics. This page documents the ARIA attributes, screen reader behavior, and other accessibility features built into the component.
 
-For keyboard interaction details, see the <a href="./keyboard-behavior.html">Keyboard Behavior</a> page.
+For keyboard interaction details, see the <auro-hyperlink href="keyboard-behavior">Keyboard Behavior</auro-hyperlink> page.
 
 <auro-header level="2" id="ariaRolesAndAttributes">ARIA Roles and Attributes</auro-header>
 <auro-header level="3" id="radioGroup">Radio Group</auro-header>

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

@@ -1227,7 +1227,7 @@ class AuroHelpText extends i$2 {
   }
 }
 
-var formkitVersion = '202607072023';
+var formkitVersion = '202607102214';
 
 // 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 = '202607072023';
+var formkitVersion = '202607102214';
 
 // 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 = '202607072023';
+var formkitVersion = '202607102214';
 
 // 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 = '202607072023';
+var formkitVersion = '202607102214';
 
 // 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 = '202607072023';
+var formkitVersion = '202607102214';
 
 // 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/accessibility.md

@@ -4,7 +4,7 @@
 <div class="scrollWrapper">
 The `auro-select` component follows the <a href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/" target="_blank">W3C APG Select-Only Combobox</a> pattern. This page documents the ARIA semantics, screen reader announcements, and other accessibility behaviors built into the component.
 
-For keyboard interaction details, see the <a href="./keyboard-behavior.html">Keyboard Behavior</a> page.
+For keyboard interaction details, see the <auro-hyperlink href="keyboard-behavior">Keyboard Behavior</auro-hyperlink> page.
 
 <auro-header level="2" id="ariaRolesAndAttributes">ARIA Roles and Attributes</auro-header>
 <auro-header level="3" id="trigger">Trigger</auro-header>
@@ -61,6 +61,11 @@ On smaller viewports, the bib opens as a fullscreen modal dialog:
 - A close button inside the dialog is focused when the modal opens, giving screen reader users an immediate action to dismiss it.
 - Touch scrolling on the page behind the dialog is blocked to prevent the background from scrolling into view.
 
+<auro-header level="2" id="modifierKeys">Modifier Keys</auro-header>
+The **Meta** key (Command on macOS, Windows/Super elsewhere) is intentionally not used as a modifier for select keyboard shortcuts. On Windows, Linux, and ChromeOS, the operating system intercepts `Meta` + Arrow combinations for window management (e.g. window snapping) before the browser receives the event, so any shortcut bound to `Meta` + Arrow would work only on macOS and silently fail on other platforms.
+
+To jump to the first or last option in a way that works uniformly across platforms, use **Home** and **End**, which follow the <a href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/" target="_blank">WAI-ARIA Select-Only Combobox pattern</a>.
+
 <auro-header level="2" id="reducedMotion">Reduced Motion</auro-header>
 The component respects the `prefers-reduced-motion` media query. When the user has requested reduced motion, scroll animations (e.g. scrolling the selected or active option into view) use instant scrolling instead of smooth scrolling.
 

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

@@ -40,7 +40,7 @@
 <auro-header level="2" id="appearance">Appearance</auro-header>
 <auro-header level="3" id="layout">Shape, Size & Layout</auro-header>
 <p>The <code>shape</code>, <code>size</code> and <code>layout</code> attributes work in collaboration to control the overall architecture of the component.</p>
-<p>See the <a href="./design.html">Design page</a> for a detailed breakdown.</p>
+<p>See the <auro-hyperlink href="design">Design page</auro-hyperlink> for a detailed breakdown.</p>
 <auro-header level="3" id="background">Light vs. Dark Background</auro-header>
 <p>The <code>appearance</code> attribute defines whether the component renders on lighter or darker backgrounds. Supported values are <code>default</code> and <code>inverse</code>. The default value is <code>default</code>.</p>
 <div class="exampleWrapper">
@@ -796,7 +796,7 @@
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/customize/typeahead.md) -->
 <!-- The below content is automatically added from ./../docs/partials/customize/typeahead.md -->
 <p>Type-ahead lets a guest jump to an option by typing. As keys are pressed, the active option advances to the first enabled option whose <strong>displayed text</strong> starts with the buffered keystrokes — following the <auro-hyperlink href="https://www.w3.org/WAI/ARIA/apg/patterns/listbox/">WAI-ARIA Listbox pattern</auro-hyperlink>, and mirroring native HTML <code>&lt;select&gt;</code> behavior. Matching uses the rendered text rather than the <code>value</code> attribute.</p>
-<p>The <code>typeaheadTimeoutMs</code> attribute (default <code>500</code>) controls how long the buffer persists between keystrokes. Repeating the same character cycles through every enabled option starting with it; disabled options are skipped.</p>
+<p>The <code>typeaheadTimeoutMs</code> attribute (default <code>500</code>) controls how long the buffer persists between keystrokes. Repeating the same character cycles through every enabled option starting with it; <code>disabled</code>, <code>hidden</code>, and <code>static</code> options are skipped.</p>
 <div class="note">
 <strong>Note:</strong> The <kbd>Space</kbd> key is context-sensitive. When the type-ahead buffer is empty it toggles the bib open or closed, matching the rest of <code>&lt;auro-select&gt;</code>. When the buffer is active it extends the buffer instead, so multi-word options such as "San Francisco" can be matched by typing <kbd>s</kbd>, <kbd>a</kbd>, <kbd>n</kbd>, <kbd>Space</kbd>, <kbd>f</kbd>.
 </div>
@@ -864,7 +864,7 @@
 </auro-accordion>
 <auro-header level="3" id="disableComponent">Disable Component</auro-header>
 <p>The entire component may be disabled. When disabled, the component will render to reflect the state, may not receive focus nor react to any key or pointer events.</p>
-<p>When the component is disabled and part of a form, the components value is still included in the form submission.</p>
+<p>When the component is disabled and part of a form, the component's value is not included in the form submission (matching native HTML behavior for disabled form controls).</p>
 <p class="note">
 <strong>Note:</strong> If the component is marked as both <strong>invalid</strong> and <code>disabled</code>, the <strong>invalid</strong> state UI/UX and functional behavior are ignored. The <code>disabled</code> UI/UX and functional behavior works normally.
 </p>
@@ -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">