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

package/components/input/demo/accessibility.md

@@ -4,7 +4,7 @@
 <div class="scrollWrapper">
 The `auro-input` component renders a native HTML <code>&lt;input&gt;</code> element inside its shadow DOM and augments it with custom label, help text, and validation UI. This page documents the ARIA semantics, screen reader announcements, and other accessibility behaviors built into the component.
 
-For keyboard interaction details, see the <auro-hyperlink href="./keyboard-behavior.html">Keyboard Behavior</auro-hyperlink> 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="inputElement">Input Element</auro-header>

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

@@ -12267,7 +12267,7 @@ class AuroHelpText extends i$3 {
   }
 }
 
-var formkitVersion = '202607072023';
+var formkitVersion = '202607102214';
 
 /**
  * @license

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

@@ -12267,7 +12267,7 @@ class AuroHelpText extends i$3 {
   }
 }
 
-var formkitVersion = '202607072023';
+var formkitVersion = '202607102214';
 
 /**
  * @license

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

@@ -12267,7 +12267,7 @@ class AuroHelpText extends i$3 {
   }
 }
 
-var formkitVersion = '202607072023';
+var formkitVersion = '202607102214';
 
 /**
  * @license

package/components/input/dist/index.js

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

package/components/input/dist/registered.js

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

package/components/menu/demo/accessibility.md

@@ -19,11 +19,16 @@
 <auro-header level="2" id="keyboardInteraction">Keyboard Interaction</auro-header>
 <p>The menu supports full keyboard navigation:</p>
 <ul>
-<li><strong>Arrow Down / Arrow Up:</strong> Moves focus between options.</li>
-<li><strong>Enter / Space:</strong> Selects the currently focused option.</li>
-<li><strong>Home / End:</strong> Moves focus to the first or last option.</li>
+<li><strong>Arrow Down / Arrow Up:</strong> Moves the active option.</li>
+<li><strong>Enter:</strong> Selects the currently active option.</li>
+<li><strong>Tab:</strong> Selects the currently active option and moves focus out of the menu.</li>
 </ul>
-<p>See the <auro-hyperlink href="keyboardBehavior">Keyboard Behavior</auro-hyperlink> page for full details.</p>
+<p>See the <auro-hyperlink href="keyboard-behavior">Keyboard Behavior</auro-hyperlink> page for full details.</p>
+</section>
+<section>
+<auro-header level="2" id="modifierKeys">Modifier Keys</auro-header>
+<p>The <strong>Meta</strong> key (Command on macOS, Windows/Super elsewhere) is intentionally not used as a modifier for menu keyboard shortcuts. On Windows, Linux, and ChromeOS, the operating system intercepts <code>Meta</code> + Arrow combinations for window management (e.g. window snapping) before the browser receives the event, so any shortcut bound to <code>Meta</code> + Arrow would work only on macOS and silently fail on other platforms.</p>
+<p>To jump to the first or last option in a way that works uniformly across platforms, use <strong>Home</strong> and <strong>End</strong>, which follow the <a href="https://www.w3.org/WAI/ARIA/apg/patterns/listbox/" target="_blank">WAI-ARIA Listbox pattern</a>.</p>
 </section>
 <section>
 <auro-header level="2" id="multiselect">Multi-Select</auro-header>

package/components/menu/demo/api.md

@@ -7,23 +7,23 @@ The `auro-menu` element provides users a way to select from a list of options.
 
 ## Properties
 
-| Property                | Attribute        | Modifiers | Type                  | Default     | Description                                      |
-|-------------------------|------------------|-----------|-----------------------|-------------|--------------------------------------------------|
-| `currentLabel`          |                  | readonly  | `string`              |             |                                                  |
-| `disabled`              | `disabled`       |           | `boolean`             |             | When true, the entire menu and all options are disabled. |
-| `hasLoadingPlaceholder` |                  | readonly  | `boolean`             |             | Getter for loading placeholder state.            |
-| `index`                 |                  |           | `number`              |             |                                                  |
-| `layout`                |                  |           | `string`              |             |                                                  |
-| `loading`               | `loading`        |           | `boolean`             | false       | When true, displays a loading state using the loadingIcon and loadingText slots if provided. |
-| `matchWord`             | `matchword`      |           | `string`              | "undefined" | Specifies a string used to highlight matched string parts in options. |
-| `multiSelect`           | `multiselect`    |           | `boolean`             | false       | When true, the selected option can be multiple options. |
-| `noCheckmark`           | `nocheckmark`    |           | `boolean`             | false       | When true, selected option will not show the checkmark. |
-| `optionActive`          | `optionactive`   |           | `object`              | "undefined" | Specifies the current active menuOption.         |
-| `optionSelected`        | `optionSelected` |           | `object`              | "undefined" | An array of currently selected menu options, type `HTMLElement` by default. In multi-select mode, `optionSelected` is an array of HTML elements. |
-| `options`               |                  | readonly  | `HTMLElement[]`       |             |                                                  |
-| `selectedOption`        |                  | readonly  | `HTMLElement \| null` |             | Gets the first selected option, or null if none. |
-| `selectedOptions`       |                  | readonly  | `HTMLElement[]`       |             | Gets the currently selected options as an array. |
-| `value`                 | `value`          |           | `string`              | "undefined" | The value of the selected option. In multi-select mode, this is a JSON stringified array of selected option values. |
+| Property                | Attribute     | Modifiers | Type                  | Default     | Description                                      |
+|-------------------------|---------------|-----------|-----------------------|-------------|--------------------------------------------------|
+| `currentLabel`          |               | readonly  | `string`              |             |                                                  |
+| `disabled`              | `disabled`    |           | `boolean`             |             | When true, the entire menu and all options are disabled. |
+| `hasLoadingPlaceholder` |               | readonly  | `boolean`             |             | Getter for loading placeholder state.            |
+| `index`                 |               |           | `number`              |             |                                                  |
+| `layout`                |               |           | `string`              |             |                                                  |
+| `loading`               | `loading`     |           | `boolean`             | false       | When true, displays a loading state using the loadingIcon and loadingText slots if provided. |
+| `matchWord`             | `matchword`   |           | `string`              | "undefined" | Specifies a string used to highlight matched string parts in options. |
+| `multiSelect`           | `multiselect` |           | `boolean`             | false       | When true, the selected option can be multiple options. |
+| `noCheckmark`           | `nocheckmark` |           | `boolean`             | false       | When true, selected option will not show the checkmark. |
+| `optionActive`          |               |           | `object`              | "undefined" | Specifies the current active menuOption.         |
+| `optionSelected`        |               |           | `object`              | "undefined" | 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. |
+| `options`               |               | readonly  | `HTMLElement[]`       |             |                                                  |
+| `selectedOption`        |               | readonly  | `HTMLElement \| null` |             | Gets the first selected option, or null if none. |
+| `selectedOptions`       |               | readonly  | `HTMLElement[]`       |             | Gets the currently selected options as an array. |
+| `value`                 | `value`       |           | `string`              | "undefined" | The value of the selected option. In multi-select mode, this is a JSON stringified array of selected option values.<br />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. |
 
 ## Methods
 
@@ -31,7 +31,7 @@ The `auro-menu` element provides users a way to select from a list of options.
 |----------------------|--------------------------------------------------|--------------------------------------------------|
 | `navigateOptions`    | `(direction: string): void`                      | Navigates through options using keyboard.<br /><br />**direction**: 'up' or 'down'. |
 | `reset`              | `(): void`                                       | Resets the menu to its initial state.<br />This is the only way to return value to undefined. |
-| `selectByValue`      | `(value: string \| string[] \| null \| undefined): void` | Selects options by value.<br /><br />**value**: The value(s) to select. |
+| `selectByValue`      | `(value: string \| string[] \| null \| undefined): void` | 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.<br /><br />**value**: The value(s) to select. |
 | `updateActiveOption` | `(indexOrOption: number \| HTMLElement): void`   | Updates the active option state and dispatches events.<br />Accepts either a numeric index or an HTMLElement option.<br /><br />**indexOrOption**: Index of the option or the option element to make active. |
 
 ## Events
@@ -58,6 +58,12 @@ The `auro-menu` element provides users a way to select from a list of options.
 
 The `auro-menuoption` element provides users a way to define a menu option.
 
+## Attributes
+
+| Attribute | Type      | Description                                      |
+|-----------|-----------|--------------------------------------------------|
+| `static`  | `Boolean` | 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. |
+
 ## Properties
 
 | Property      | Attribute     | Modifiers | Type      | Default | Description                                      |
@@ -68,7 +74,8 @@ The `auro-menuoption` element provides users a way to define a menu option.
 | `layout`      |               |           | `string`  |         |                                                  |
 | `noCheckmark` | `noCheckmark` |           | `boolean` | false   |                                                  |
 | `noMatch`     | `nomatch`     |           | `boolean` | false   | When true, marks this option as the "no matching results" placeholder shown by combobox<br />when the user's input does not match any available options. |
-| `selected`    | `selected`    |           | `boolean` | false   |                                                  |
+| `persistent`  | `persistent`  |           | `boolean` | false   | 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. |
+| `selected`    | `selected`    |           | `boolean` | false   | **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. |
 | `value`       | `value`       |           | `string`  |         |                                                  |
 
 ## Methods

package/components/menu/demo/css-only.md

@@ -54,26 +54,28 @@
 &lt;/ul&gt;</code></pre>
 <auro-header level="2">What you lose without auro-menu</auro-header>
 <p>While the CSS above replicates the <strong>visual styling</strong> of <code>auro-menu</code>, the following functionality built into the <code>auro-menu</code> and <code>auro-menuoption</code> web components is <strong>not available</strong> when using plain HTML:</p>
-<auro-header level="3">Roving tabindex</auro-header>
-<p><code>auro-menu</code> manages a roving <code>tabindex</code> so that only the currently active option is in the tab order, and focus moves between options without leaving the menu. With plain HTML, you must implement the roving-tabindex pattern yourself by maintaining the <code>tabindex="0"</code>/<code>tabindex="-1"</code> state across all options on every focus and key event.</p>
+<auro-header level="3">Active-option tracking</auro-header>
+<p><code>auro-menu</code> tracks the active option internally (via an <code>active</code> CSS class on the current <code>auro-menuoption</code>) rather than moving DOM focus between options. In typical integrations (<code>&lt;auro-select&gt;</code>, <code>&lt;auro-combobox&gt;</code>), focus remains on the parent trigger/input and <code>aria-activedescendant</code> points at the active option; if you make <code>&lt;auro-menu&gt;</code> focusable (e.g., <code>tabindex="0"</code>), the same active-option model applies while focus is on the menu host. With plain HTML, you must pick one focus model — either roving <code>tabindex="0"</code>/<code>tabindex="-1"</code>, or <code>aria-activedescendant</code> on the container — and wire up the DOM writes yourself on every key event.</p>
 <auro-header level="3">Arrow-key navigation</auro-header>
-<p><code>auro-menu</code> handles <code>ArrowUp</code>, <code>ArrowDown</code>, <code>Home</code>, <code>End</code>, <code>Enter</code>, and <code>Space</code> to move the highlight and commit selections. Native <code>&lt;ul&gt;</code> elements have no built-in keyboard model — you must wire up <code>keydown</code> listeners, track the highlighted index, and prevent default browser scrolling on the arrow keys yourself.</p>
-<auro-header level="3">Type-ahead search</auro-header>
-<p><code>auro-menu</code> supports a <code>matchword</code> attribute that highlights matched substrings within option labels, and the listbox supports type-ahead focus jumping. Plain HTML provides neither — both behaviors must be implemented manually with string matching and DOM manipulation.</p>
+<p><code>auro-menu</code> handles <code>ArrowUp</code>, <code>ArrowDown</code>, <code>Enter</code>, and <code>Tab</code> to move the highlight and commit selections. Native <code>&lt;ul&gt;</code> elements have no built-in keyboard model — you must wire up <code>keydown</code> listeners, track the highlighted index, and prevent default browser scrolling on the arrow keys yourself.</p>
+<auro-header level="3">matchWord highlighting</auro-header>
+<p><code>auro-menu</code> supports a <code>matchWord</code> attribute that highlights matched substrings within option labels — used by <code>auro-combobox</code> to visually mark the user's typed input inside each filtered option. Plain HTML provides no equivalent; you must walk each option and wrap matched substrings yourself.</p>
+<auro-header level="3">Type-ahead navigation</auro-header>
+<p>Type-ahead — jumping the active option to whichever entry starts with the letters the user typed — is <strong>not</strong> handled by <code>auro-menu</code> itself. It is provided by the parent selection component (<code>auro-select</code>, <code>auro-combobox</code>) which captures printable characters on its trigger and calls back into the menu. A plain-HTML listbox has no such wiring and would need a bespoke keydown handler that tracks a rolling character buffer and resolves it against the option list.</p>
 <auro-header level="3">Nested submenu support</auro-header>
-<p><code>auro-menu</code> detects nested <code>auro-menu</code> elements, applies the correct <code>role="group"</code>, computes indentation per level, and propagates the shared menu service down the tree. With plain HTML, you must apply nested ARIA roles and indentation manually, and there is no built-in coordination of focus or selection between parent and child lists.</p>
+<p><code>auro-menu</code> detects nested <code>auro-menu</code> elements, applies the correct <code>role="group"</code>, and computes indentation per level. The root menu treats all descendant options as a single flat list, so selecting an option inside a nested menu updates the root menu's <code>value</code> and <code>optionSelected</code> — the root always owns the selection state. With plain HTML, you must apply nested ARIA roles and indentation manually.</p>
 <auro-header level="3">Selection state coordination</auro-header>
-<p><code>auro-menu</code> coordinates the selected option(s) through an internal <code>MenuService</code> that keeps <code>optionSelected</code>, <code>value</code>, and each option's <code>aria-selected</code> state in sync. With native HTML, you must update <code>aria-selected</code> on every option yourself on each change and manage your own source of truth for the selected value.</p>
+<p><code>auro-menu</code> keeps <code>optionSelected</code>, <code>value</code>, and each option's <code>aria-selected</code> state in sync internally. With native HTML, you must update <code>aria-selected</code> on every option yourself on each change and manage your own source of truth for the selected value.</p>
 <auro-header level="3">ARIA roles and live announcements</auro-header>
 <p><code>auro-menu</code> automatically applies <code>role="listbox"</code>, <code>aria-multiselectable</code>, <code>aria-busy</code> during loading, and per-option <code>role="option"</code> with <code>aria-selected</code> and <code>aria-disabled</code>. Plain HTML requires you to author every one of these attributes by hand and keep them in sync with state — and to add any additional live-region announcements yourself.</p>
 <auro-header level="3">Value emission and events</auro-header>
-<p><code>auro-menu</code> dispatches a structured set of events — <code>auroMenu-selectedOption</code>, <code>auroMenu-activatedOption</code>, <code>auroMenu-optionsChange</code>, <code>auroMenu-selectValueReset</code>, <code>auroMenu-selectValueFailure</code>, <code>auroMenu-deselectPrevented</code>, and <code>auroMenu-loadingChange</code> — so parent components can react to highlight, selection, and lifecycle changes. Native listboxes emit no equivalent events; you must dispatch your own.</p>
+<p><code>auro-menu</code> dispatches a structured set of events — <code>auroMenu-selectedOption</code>, <code>auroMenu-activatedOption</code>, <code>auroMenu-optionsChange</code>, <code>auroMenu-selectValueReset</code>, <code>auroMenu-selectValueFailure</code>, and <code>auroMenu-loadingChange</code> — so parent components can react to highlight, selection, and lifecycle changes. Native listboxes emit no equivalent events; you must dispatch your own.</p>
 <auro-header level="3">Multi-select with array value</auro-header>
 <p><code>auro-menu</code> supports <code>multiselect</code>, exposing the selection as a JSON-stringified array via <code>value</code> and as an array of elements via <code>optionSelected</code>. With plain HTML, you must track multiple selections yourself, manage the <code>aria-multiselectable</code> attribute, and serialize the result manually.</p>
-<auro-header level="3">Allow-deselect behavior</auro-header>
-<p><code>auro-menu</code> supports an <code>allowDeselect</code> attribute that lets a user click an already-selected option to clear it in single-select mode, with a <code>auroMenu-deselectPrevented</code> event when the operation is blocked. Native listboxes do not have a deselect concept; you must implement and gate the behavior yourself.</p>
+<auro-header level="3">Multi-select deselect</auro-header>
+<p>In multi-select mode, clicking an already-selected option toggles it off. Native listboxes have no built-in deselect concept for individual options; you must implement the toggle behavior and update <code>aria-selected</code> yourself.</p>
 <auro-header level="3">Select-by-value and reset</auro-header>
-<p><code>auro-menu</code> exposes a <code>value</code> attribute that drives selection programmatically (including the <code>selectAllMatchingOptions</code> option for multi-select) and a single <code>reset()</code> method that clears all selection and validation state. With plain HTML, you must walk the list to find a matching option, set its state, and write your own reset routine.</p>
+<p><code>auro-menu</code> exposes a <code>value</code> attribute that drives selection programmatically (accepting a JSON-stringified array in multi-select mode) and a single <code>reset()</code> method that clears all selection and validation state. With plain HTML, you must walk the list to find a matching option, set its state, and write your own reset routine.</p>
 <auro-header level="3">Loading state</auro-header>
 <p><code>auro-menu</code> renders a built-in loading placeholder via <code>loadingIcon</code> and <code>loadingText</code> slots, sets <code>aria-busy</code>, and emits <code>auroMenu-loadingChange</code> when the loading attribute toggles. With plain HTML, you must render a placeholder, manage <code>aria-busy</code>, and signal loading transitions yourself.</p>
 <auro-header level="3">Shape and size variants</auro-header>
@@ -96,9 +98,9 @@
 <td>Built-in</td>
 </tr>
 <tr>
-<td>Roving tabindex</td>
-<td>Manual</td>
-<td>Built-in</td>
+<td>Active-option tracking</td>
+<td>Manual (roving tabindex or <code>aria-activedescendant</code>)</td>
+<td>Built-in (<code>active</code> class on the current option)</td>
 </tr>
 <tr>
 <td>Arrow-key navigation</td>
@@ -106,9 +108,14 @@
 <td>Built-in</td>
 </tr>
 <tr>
-<td>Type-ahead and <code>matchword</code> highlighting</td>
+<td><code>matchWord</code> highlighting</td>
+<td>Not supported</td>
+<td>Built-in via <code>matchWord</code></td>
+</tr>
+<tr>
+<td>Type-ahead navigation</td>
 <td>Not supported</td>
-<td>Built-in via <code>matchword</code></td>
+<td>Provided by parent <code>auro-select</code> / <code>auro-combobox</code></td>
 </tr>
 <tr>
 <td>Nested submenus</td>
@@ -118,7 +125,7 @@
 <tr>
 <td>Selection state coordination</td>
 <td>Manual <code>aria-selected</code> sync</td>
-<td>Centralized via menu service</td>
+<td>Coordinated internally</td>
 </tr>
 <tr>
 <td>ARIA roles and <code>aria-busy</code></td>
@@ -136,9 +143,9 @@
 <td><code>multiselect</code> + <code>value</code></td>
 </tr>
 <tr>
-<td>Allow-deselect behavior</td>
+<td>Multi-select deselect</td>
 <td>Manual</td>
-<td><code>allowDeselect</code> attribute</td>
+<td>Click-to-toggle built in</td>
 </tr>
 <tr>
 <td>Select-by-value and reset</td>