@aurodesignsystem-dev/auro-formkit 0.0.0-pr1540.1 → 0.0.0-pr1541.1

package/components/menu/demo/getting-started.md

@@ -22,10 +22,13 @@
 <auro-anchorlink fluid href="#options" class="level2 body-xs">options</auro-anchorlink>
 <auro-anchorlink fluid href="#index" class="level2 body-xs">index</auro-anchorlink>
 <auro-anchorlink fluid href="#functions">Functions</auro-anchorlink>
-<auro-anchorlink fluid href="#makeSelection" class="level2 body-xs">makeSelection()</auro-anchorlink>
 <auro-anchorlink fluid href="#reset" class="level2 body-xs">reset()</auro-anchorlink>
+<auro-anchorlink fluid href="#selectByValue" class="level2 body-xs">selectByValue()</auro-anchorlink>
 <auro-anchorlink fluid href="#updateActiveOption" class="level2 body-xs">updateActiveOption()</auro-anchorlink>
 <auro-anchorlink fluid href="#navigateOptions" class="level2 body-xs">navigateOptions()</auro-anchorlink>
+<auro-anchorlink fluid href="#events">Events</auro-anchorlink>
+<auro-anchorlink fluid href="#eventList" class="level2 body-xs">Event List</auro-anchorlink>
+<auro-anchorlink fluid href="#eventAttribute" class="level2 body-xs">Option event attribute</auro-anchorlink>
 </auro-nav>
 </nav>
 <div class="mainContent">
@@ -308,14 +311,148 @@ Ensure your `tsconfig.json` uses `"moduleResolution": "bundler"` so TypeScript c
 <section>
 <auro-header level="2" id="functions">Functions</auro-header>
 <p>The following public methods are available on the <code>&lt;auro-menu&gt;</code> element.</p>
-<auro-header level="3" id="makeSelection">makeSelection()</auro-header>
-<p>Selects the currently active menu option. This is the programmatic equivalent of clicking on an option or pressing Enter while an option is focused.</p>
 <auro-header level="3" id="reset">reset()</auro-header>
 <p>Resets the menu to its initial state, clearing all selected options and restoring the value to <code>undefined</code>.</p>
-<auro-header level="3" id="updateActiveOption">updateActiveOption(option)</auro-header>
-<p>Sets the specified <code>&lt;auro-menuoption&gt;</code> element as the currently active (highlighted) option.</p>
+<div class="exampleWrapper">
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/reset.html) -->
+<!-- The below content is automatically added from ./../apiExamples/reset.html -->
+<auro-menu id="resetExample" value="duration">
+<auro-menuoption value="stops">Stops</auro-menuoption>
+<auro-menuoption value="price">Price</auro-menuoption>
+<auro-menuoption value="duration">Duration</auro-menuoption>
+<auro-menuoption value="departure">Departure</auro-menuoption>
+<auro-menuoption value="arrival">Arrival</auro-menuoption>
+</auro-menu>
+<br/><br/>
+<auro-button id="resetExampleBtn">RESET</auro-button>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+<span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/reset.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/reset.html -->
+<pre class="language-html"><code class="language-html">&lt;auro-menu id="resetExample" value="duration"&gt;
+  &lt;auro-menuoption value="stops"&gt;Stops&lt;/auro-menuoption&gt;
+  &lt;auro-menuoption value="price"&gt;Price&lt;/auro-menuoption&gt;
+  &lt;auro-menuoption value="duration"&gt;Duration&lt;/auro-menuoption&gt;
+  &lt;auro-menuoption value="departure"&gt;Departure&lt;/auro-menuoption&gt;
+  &lt;auro-menuoption value="arrival"&gt;Arrival&lt;/auro-menuoption&gt;
+&lt;/auro-menu&gt;
+&lt;br/&gt;&lt;br/&gt;
+&lt;auro-button id="resetExampleBtn"&gt;RESET&lt;/auro-button&gt;</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+<auro-header level="3" id="selectByValue">selectByValue(value)</auro-header>
+<p>Selects the option(s) whose <code>value</code> matches the argument. Accepts a string in single-select mode or an array of strings in multi-select mode; passing <code>undefined</code>, <code>null</code>, an empty string, or an empty array clears the selection.</p>
+<div class="exampleWrapper">
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/select-by-value.html) -->
+<!-- The below content is automatically added from ./../apiExamples/select-by-value.html -->
+<auro-menu id="selectByValueMenu">
+<auro-menuoption value="stops">Stops</auro-menuoption>
+<auro-menuoption value="price">Price</auro-menuoption>
+<auro-menuoption value="duration">Duration</auro-menuoption>
+<auro-menuoption value="departure">Departure</auro-menuoption>
+<auro-menuoption value="arrival">Arrival</auro-menuoption>
+</auro-menu>
+<br />
+<auro-button id="selectByValueStops">Select "Stops"</auro-button>
+<auro-button id="selectByValueDuration">Select "Duration"</auro-button>
+<auro-button id="selectByValueClear">Clear selection</auro-button>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+<span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/select-by-value.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/select-by-value.html -->
+<pre class="language-html"><code class="language-html">&lt;auro-menu id="selectByValueMenu"&gt;
+  &lt;auro-menuoption value="stops"&gt;Stops&lt;/auro-menuoption&gt;
+  &lt;auro-menuoption value="price"&gt;Price&lt;/auro-menuoption&gt;
+  &lt;auro-menuoption value="duration"&gt;Duration&lt;/auro-menuoption&gt;
+  &lt;auro-menuoption value="departure"&gt;Departure&lt;/auro-menuoption&gt;
+  &lt;auro-menuoption value="arrival"&gt;Arrival&lt;/auro-menuoption&gt;
+&lt;/auro-menu&gt;
+&lt;br /&gt;
+&lt;auro-button id="selectByValueStops"&gt;Select "Stops"&lt;/auro-button&gt;
+&lt;auro-button id="selectByValueDuration"&gt;Select "Duration"&lt;/auro-button&gt;
+&lt;auro-button id="selectByValueClear"&gt;Clear selection&lt;/auro-button&gt;</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+<auro-header level="3" id="updateActiveOption">updateActiveOption(indexOrOption)</auro-header>
+<p>Sets the specified option as the currently active (highlighted) option. Accepts either a numeric index into <code>options</code> or an <code>&lt;auro-menuoption&gt;</code> element reference.</p>
 <auro-header level="3" id="navigateOptions">navigateOptions(direction)</auro-header>
-<p>Moves the highlight to the next or previous option. Accepts <code>'up'</code> or <code>'down'</code> as the direction parameter.</p>
+<p>Moves the active option to the next or previous option. Accepts <code>'up'</code> or <code>'down'</code> as the direction parameter.</p>
+</section>
+<section>
+<auro-header level="2" id="events">Events</auro-header>
+<p>The <code>&lt;auro-menu&gt;</code> element dispatches custom events that consumers can subscribe to via <code>addEventListener</code>. The example below wires listeners for the full event set and logs each firing.</p>
+<auro-header level="3" id="eventList">Event List</auro-header>
+<ul>
+<li><code>auroMenu-selectedOption</code> — a new selection has been made.</li>
+<li><code>auroMenu-activatedOption</code> — the active (highlighted) option changed via keyboard or hover.</li>
+<li><code>auroMenu-optionsChange</code> — the set of available options was updated (e.g., after a slot change).</li>
+<li><code>auroMenu-selectValueReset</code> — the menu's <code>value</code> was reset via <code>reset()</code>.</li>
+<li><code>auroMenu-selectValueFailure</code> — a call to <code>selectByValue()</code> found no matching option.</li>
+</ul>
+<div class="exampleWrapper">
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/events.html) -->
+<!-- The below content is automatically added from ./../apiExamples/events.html -->
+<auro-menu id="eventsExampleMenu">
+<auro-menuoption value="stops">Stops</auro-menuoption>
+<auro-menuoption value="price">Price</auro-menuoption>
+<auro-menuoption value="duration">Duration</auro-menuoption>
+<auro-menuoption value="departure">Departure</auro-menuoption>
+<auro-menuoption value="arrival">Arrival</auro-menuoption>
+</auro-menu>
+<br />
+<auro-button id="eventsExampleReset">reset()</auro-button>
+<auro-button id="eventsExampleBadValue">selectByValue("nonexistent")</auro-button>
+<auro-button id="eventsExampleClearLog">Clear log</auro-button>
+        <pre id="eventsExampleLog" style="max-height: 200px; overflow: auto; padding: var(--ds-size-100, 8px); background: var(--ds-color-container-secondary, #f5f5f5); border-radius: 4px;">(interact with the menu above)</pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+<span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/events.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/events.html -->
+<pre class="language-html"><code class="language-html">&lt;auro-menu id="eventsExampleMenu"&gt;
+  &lt;auro-menuoption value="stops"&gt;Stops&lt;/auro-menuoption&gt;
+  &lt;auro-menuoption value="price"&gt;Price&lt;/auro-menuoption&gt;
+  &lt;auro-menuoption value="duration"&gt;Duration&lt;/auro-menuoption&gt;
+  &lt;auro-menuoption value="departure"&gt;Departure&lt;/auro-menuoption&gt;
+  &lt;auro-menuoption value="arrival"&gt;Arrival&lt;/auro-menuoption&gt;
+&lt;/auro-menu&gt;
+&lt;br /&gt;
+&lt;auro-button id="eventsExampleReset"&gt;reset()&lt;/auro-button&gt;
+&lt;auro-button id="eventsExampleBadValue"&gt;selectByValue("nonexistent")&lt;/auro-button&gt;
+&lt;auro-button id="eventsExampleClearLog"&gt;Clear log&lt;/auro-button&gt;
+&lt;pre id="eventsExampleLog" style="max-height: 200px; overflow: auto; padding: var(--ds-size-100, 8px); background: var(--ds-color-container-secondary, #f5f5f5); border-radius: 4px;"&gt;(interact with the menu above)&lt;/pre&gt;</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+<auro-header level="3" id="eventAttribute">Option event attribute</auro-header>
+<p>Attach an <code>event</code> attribute to any <code>auro-menuoption</code> to dispatch a named custom event from the menu when that option is selected. The generic <code>auroMenu-customEventFired</code> event is also dispatched on every firing — its <code>detail.option</code> references the option that triggered it, so a single listener can route on the <code>event</code> attribute value.</p>
+<div class="exampleWrapper">
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/event-attribute.html) -->
+<!-- The below content is automatically added from ./../apiExamples/event-attribute.html -->
+<auro-menu id="eventAttrExample">
+<auro-menuoption value="search" event="custom-flight-search">Search flights</auro-menuoption>
+<auro-menuoption value="clear" event="custom-clear-filters">Clear filters</auro-menuoption>
+<auro-menuoption value="save" event="custom-save-preferences">Save preferences</auro-menuoption>
+</auro-menu>
+<p>Last custom event: <output id="eventAttrOutput">(none)</output></p>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+<span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/event-attribute.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/event-attribute.html -->
+<pre class="language-html"><code class="language-html">&lt;auro-menu id="eventAttrExample"&gt;
+  &lt;auro-menuoption value="search" event="custom-flight-search"&gt;Search flights&lt;/auro-menuoption&gt;
+  &lt;auro-menuoption value="clear" event="custom-clear-filters"&gt;Clear filters&lt;/auro-menuoption&gt;
+  &lt;auro-menuoption value="save" event="custom-save-preferences"&gt;Save preferences&lt;/auro-menuoption&gt;
+&lt;/auro-menu&gt;
+&lt;p&gt;Last custom event: &lt;output id="eventAttrOutput"&gt;(none)&lt;/output&gt;&lt;/p&gt;</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
 </section>
 </div>
 </div>

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

@@ -422,7 +422,7 @@ class AuroMenu extends AuroElement {
       },
 
       /**
-       * 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.
        */
       optionSelected: {
         // Allow HTMLElement, HTMLElement[] arrays and undefined
@@ -992,6 +992,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([
       [
@@ -1483,6 +1488,7 @@ class AuroMenuOption extends AuroElement {
     this.noCheckmark = false;
     this.disabled = false;
     this.noMatch = false;
+    this.persistent = false;
 
     /**
      * @private
@@ -1504,6 +1510,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
@@ -1538,6 +1550,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
+      },
     };
   }
 
@@ -1712,6 +1730,103 @@ class AuroMenuOption extends AuroElement {
   }
 }
 
+function auroMenuLoadingExample() {
+  document.querySelector("#loadingExampleToggleButton").addEventListener("click", () => {
+    document.querySelectorAll("#loadingExampleTable auro-menu").forEach(menu => menu.toggleAttribute("loading"));
+  });
+}
+
+function updateMatch() {
+  let matchWordMenu = document.querySelector('#matchWordMenu');
+
+  matchWordMenu.matchWord = matchWordInput.value;
+}
+
+function auroMenuMatchWordExample() {
+  let matchWordInput = document.querySelector('#matchWordInput');
+
+  matchWordInput.addEventListener('keyup', updateMatch);
+}
+
+function auroMenuResetExample() {
+  const resetExampleBtnElem = document.querySelector('#resetExampleBtn');
+  const resetExampleElem = document.querySelector('#resetExample');
+  
+  if (resetExampleElem && resetExampleBtnElem) {
+    resetExampleBtnElem.addEventListener('click', () => {
+      resetExampleElem.reset();
+    });
+  }
+}
+
+function auroMenuEventAttributeExample() {
+  const menu = document.querySelector('#eventAttrExample');
+  const output = document.querySelector('#eventAttrOutput');
+
+  menu.addEventListener('auroMenu-customEventFired', (evt) => {
+    const eventName = evt.detail.option.getAttribute('event');
+    output.textContent = `${eventName} (from "${evt.detail.option.textContent}")`;
+  });
+}
+
+function auroMenuEventsExample() {
+  const menu = document.querySelector('#eventsExampleMenu');
+  const log = document.querySelector('#eventsExampleLog');
+  const resetBtn = document.querySelector('#eventsExampleReset');
+  const badValueBtn = document.querySelector('#eventsExampleBadValue');
+  const clearBtn = document.querySelector('#eventsExampleClearLog');
+
+  let entries = [];
+  const write = (name, detail) => {
+    const label = detail && detail.tagName ? detail.tagName.toLowerCase() : JSON.stringify(detail);
+    entries.unshift(`${name}: ${label}`);
+    log.textContent = entries.slice(0, 10).join('\n');
+  };
+
+  menu.addEventListener('auroMenu-selectedOption', () => {
+    write('auroMenu-selectedOption', menu.optionSelected);
+  });
+  menu.addEventListener('auroMenu-activatedOption', (evt) => {
+    write('auroMenu-activatedOption', evt.detail);
+  });
+  menu.addEventListener('auroMenu-optionsChange', (evt) => {
+    write('auroMenu-optionsChange', { count: (evt.detail.options || []).length });
+  });
+  menu.addEventListener('auroMenu-selectValueReset', () => {
+    write('auroMenu-selectValueReset', { value: menu.value });
+  });
+  menu.addEventListener('auroMenu-selectValueFailure', (evt) => {
+    write('auroMenu-selectValueFailure', evt.detail);
+  });
+
+  resetBtn.addEventListener('click', () => menu.reset());
+  badValueBtn.addEventListener('click', () => menu.selectByValue('nonexistent'));
+  clearBtn.addEventListener('click', () => {
+    entries = [];
+    log.textContent = '(interact with the menu above)';
+  });
+}
+
+function auroMenuPersistentExample() {
+  const input = document.querySelector('#persistentExampleInput');
+  const menu = document.querySelector('#persistentExampleMenu');
+
+  input.addEventListener('keyup', () => {
+    menu.matchWord = input.value;
+  });
+}
+
+function auroMenuSelectByValueExample() {
+  const menu = document.querySelector('#selectByValueMenu');
+  const stopsBtn = document.querySelector('#selectByValueStops');
+  const durationBtn = document.querySelector('#selectByValueDuration');
+  const clearBtn = document.querySelector('#selectByValueClear');
+
+  stopsBtn.addEventListener('click', () => menu.selectByValue('stops'));
+  durationBtn.addEventListener('click', () => menu.selectByValue('duration'));
+  clearBtn.addEventListener('click', () => menu.selectByValue(undefined));
+}
+
 /* eslint-disable jsdoc/require-jsdoc, no-magic-numbers, no-param-reassign */
 
 
@@ -1720,7 +1835,36 @@ AuroMenuOption.register();
 AuroMenu.register('custom-menu');
 AuroMenuOption.register('custom-menuoption');
 
-function initExamples(initCount) {
+const examples = [
+  auroMenuLoadingExample,
+  auroMenuMatchWordExample,
+  auroMenuResetExample,
+  auroMenuEventAttributeExample,
+  auroMenuEventsExample,
+  auroMenuPersistentExample,
+  auroMenuSelectByValueExample
+];
+
+function initExamples(pending, initCount) {
+  pending = pending || examples.slice();
+  initCount = initCount || 0;
+  const stillPending = [];
+
+  for (const fn of pending) {
+    try {
+      fn();
+    } catch (err) {
+      stillPending.push(fn);
+    }
+  }
+
+  if (stillPending.length && initCount <= 20) {
+    setTimeout(() => {
+      initExamples(stillPending, initCount + 1);
+    }, 100);
+  }
 }
 
+initExamples();
+
 export { initExamples };

package/components/menu/demo/keyboard-behavior.md

@@ -7,11 +7,90 @@
 <auro-header level="2" id="keyEvents">Key Events</auro-header>
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../docs/partials/keyEvents.md) -->
 <!-- The below content is automatically added from ./../docs/partials/keyEvents.md -->
-<!-- auro-menu does not implement direct keyboard event handling. -->
-<!-- Keyboard navigation is delegated to parent components (auro-select, auro-combobox) via their keyboard strategy files. -->
 <div class="note">
-<p><strong>Note:</strong> The <code>&lt;auro-menu&gt;</code> component does not handle keyboard events directly. Keyboard navigation is managed by the parent component (e.g., <code>&lt;auro-select&gt;</code>, <code>&lt;auro-combobox&gt;</code>) through their keyboard strategy classes, which call menu methods such as <code>navigateOptions()</code>, <code>makeSelection()</code>, and <code>updateActiveOption()</code>.</p>
-</div>
+<p><strong>Note:</strong> <code>&lt;auro-menu&gt;</code> registers a <code>keydown</code> listener on its host. By default the menu is not focusable — no <code>tabindex</code> on the host, and menuoptions are <code>tabindex="-1"</code> — so the listener does not fire on its own. It fires whenever a <code>keydown</code> reaches the host, which happens in any of the following ways:</p>
+<ul>
+<li>A wrapping component focuses something inside the menu subtree and the event bubbles up to the host. In the standard integrations (<code>&lt;auro-select&gt;</code>, <code>&lt;auro-combobox&gt;</code>), keyboard behavior is primarily parent-managed rather than bubble-driven: focus stays on the parent's trigger/input, and the parent captures keys there and invokes <code>navigateOptions()</code> / <code>makeSelection()</code> on the menu directly.</li>
+<li>A wrapping component dispatches or reroutes a <code>KeyboardEvent</code> at the menu programmatically (for example, <code>menu.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }))</code>).</li>
+<li>The author makes the host focusable (for example, by adding <code>tabindex="0"</code> to the <code>&lt;auro-menu&gt;</code> element) and focuses it. The host already has <code>role="listbox"</code>, so this yields a bare, focusable listbox that responds to the keys in the table below. For full combobox semantics use <code>&lt;auro-select&gt;</code> or <code>&lt;auro-combobox&gt;</code>, or replicate their <code>aria-activedescendant</code> wiring from a separate trigger.</li>
+</ul>
+<p>Keys not listed below (<code>Home</code>, <code>End</code>, <code>Escape</code>, type-ahead) are handled by the parent — see the <code>&lt;auro-select&gt;</code> and <code>&lt;auro-combobox&gt;</code> keyboard behavior docs. An "interactive option" is one that is not <code>disabled</code>, <code>hidden</code>, or <code>static</code> — these are always skipped during navigation and selection, along with <code>&lt;hr&gt;</code> dividers.</p>
+</div>
+<table>
+<thead>
+<tr>
+<th>Key</th>
+<th>Current State</th>
+<th>Behavior</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td rowspan="5">ArrowDown</td>
+<td>No option is active</td>
+<td>The first interactive option becomes active.</td>
+</tr>
+<tr>
+<td>An option is active, followed by interactive options</td>
+<td>Advances the active option to the next interactive option.</td>
+</tr>
+<tr>
+<td>The last interactive option is active</td>
+<td>Wraps to the first interactive option.</td>
+</tr>
+<tr>
+<td>Menu has no options or all options are non-interactive</td>
+<td>No option becomes active; no <code>auroMenu-activatedOption</code> event fires.</td>
+</tr>
+<tr>
+<td>Menu is in <code>loading</code> state</td>
+<td>The rendered loading placeholder is inert (marked <code>disabled</code>) and is not part of <code>items</code>, so it cannot become active.</td>
+</tr>
+<tr>
+<td rowspan="4">ArrowUp</td>
+<td>No option is active</td>
+<td>The last interactive option becomes active.</td>
+</tr>
+<tr>
+<td>An option is active, preceded by interactive options</td>
+<td>Advances the active option to the previous interactive option.</td>
+</tr>
+<tr>
+<td>The first interactive option is active</td>
+<td>Wraps to the last interactive option.</td>
+</tr>
+<tr>
+<td>Menu has no options or all options are non-interactive</td>
+<td>No option becomes active.</td>
+</tr>
+<tr>
+<td rowspan="4">Enter</td>
+<td>Single-select, active option is not currently selected</td>
+<td>The active option is selected. Any previous selection is cleared. <code>auroMenu-selectedOption</code> fires.</td>
+</tr>
+<tr>
+<td>Single-select, active option is already selected</td>
+<td>No selection change, but <code>auroMenu-selectedOption</code> still fires so the parent can react (for example, close the dropdown).</td>
+</tr>
+<tr>
+<td>Multi-select</td>
+<td>The active option toggles selected. Other selections are preserved.</td>
+</tr>
+<tr>
+<td>Active option is disabled, hidden, or static</td>
+<td>Selection is a no-op.</td>
+</tr>
+<tr>
+<td rowspan="2">Tab</td>
+<td>An option is active</td>
+<td>The active option is selected (same behavior as <code>Enter</code>).<div class="note"><strong>Note:</strong> <code>Tab</code> does not <code>preventDefault</code>, so focus continues to the next element in the tabindex sequence after selection.</div></td>
+</tr>
+<tr>
+<td>No option is active</td>
+<td>Focus moves to the next tabbable element; no selection change.</td>
+</tr>
+</tbody>
+</table>
 <!-- AURO-GENERATED-CONTENT:END -->
 </div>
 </div>

package/components/menu/demo/voiceover.md

@@ -4,20 +4,23 @@
 <auro-header level="3" id="voiceOverMenuContainer">Menu Container</auro-header>
 <p>When focus enters the menu, VoiceOver announces:</p>
 <ol>
-<li><strong>Role:</strong> <em>"list box"</em></li>
+<li><strong>Role:</strong> <em>"list box"</em> — set on the root <code>&lt;auro-menu&gt;</code>; nested menus use <code>role="group"</code> with <code>aria-label="submenu"</code>.</li>
 <li><strong>Item count:</strong> The number of visible options (e.g., <em>"5 items"</em>)</li>
+<li><strong>Multi-select:</strong> When <code>multiSelect</code> is set on the root menu, <code>aria-multiselectable="true"</code> is exposed so VoiceOver announces the listbox as multi-selectable.</li>
+<li><strong>Loading:</strong> While <code>loading</code> is set, <code>aria-busy="true"</code> is exposed so VoiceOver signals that the option set is not yet stable.</li>
 </ol>
 <auro-header level="3" id="voiceOverMenuOptions">Menu Options</auro-header>
-<p>Each <code>auro-menuoption</code> announces the following when focused:</p>
+<p>Each <code>auro-menuoption</code> announces the following when the parent field points at it (via <code>aria-activedescendant</code>) or when the user reads through the listbox:</p>
 <ol>
 <li><strong>Label:</strong> The option's text content</li>
 <li><strong>Role:</strong> <em>"option"</em></li>
-<li><strong>Position:</strong> Position in the list (e.g., <em>"3 of 5"</em>)</li>
-<li><strong>Selected state:</strong> <em>"selected"</em> if the option is currently selected</li>
-<li><strong>Disabled state:</strong> <em>"dimmed"</em> if the option is disabled</li>
-</ol>
+<li><strong>Position:</strong> Position in the list (e.g., <em>"3 of 5"</em>) — when the menu is used inside <code>&lt;auro-select&gt;</code> (or another host that stamps them), each option receives <code>aria-setsize</code> and <code>aria-posinset</code>. Standalone <code>&lt;auro-menu&gt;</code> does not set these attributes itself; positional announcements outside a select/combobox host rely on VoiceOver's own listbox item count.</li>
+<li><strong>Selected state:</strong> <em>"selected"</em> if <code>aria-selected="true"</code> is set on the option</li>
+<li><strong>Disabled state:</strong> <em>"dimmed"</em> if <code>aria-disabled="true"</code> is set on the option</li>
+</ol>
+<div class="note"><strong>Note:</strong> <code>&lt;auro-menuoption&gt;</code> is not directly focusable — <code>tabindex="-1"</code> keeps it out of the tab order. In a select or combobox context, focus stays on the parent trigger and the active option is pointed at via <code>aria-activedescendant</code> (using <code>ariaActiveDescendantElement</code> to cross the shadow-root boundary).</div>
 <auro-header level="3" id="voiceOverSelection">Selection</auro-header>
-<p>When an option is selected via Enter or Space:</p>
+<p>When an option is selected via Enter (or Tab, which selects and moves focus out of the menu):</p>
 <ul>
 <li>VoiceOver announces the option label followed by <em>"selected"</em></li>
 <li>In multi-select mode, previously selected options remain selected and their state is preserved</li>
@@ -26,8 +29,8 @@
 <ol>
 <li><strong>Enter the menu:</strong> Focus moves into the listbox; VoiceOver announces role and item count</li>
 <li><strong>Navigate options:</strong> Use Arrow Down/Up keys; VoiceOver announces each option's label, role, and position</li>
-<li><strong>Select an option:</strong> Press Enter or Space; VoiceOver confirms the selection</li>
-<li><strong>Exit:</strong> Tab out of the menu or press Escape (when used within a dropdown context)</li>
+<li><strong>Select an option:</strong> Press Enter; VoiceOver confirms the selection</li>
+<li><strong>Exit:</strong> Tab out of the menu (Tab also selects the active option). When the menu is used inside a dropdown context, the parent handles Escape.</li>
 </ol>
 <auro-header level="2" id="voiceOverNestedMenus">Nested Menus</auro-header>
 <p>When a nested <code>auro-menu</code> is encountered, VoiceOver announces a new listbox context. Each nested menu maintains its own option count and position tracking.</p>

package/components/menu/demo/why-menu.md

@@ -4,7 +4,7 @@
 <p>Custom list implementations often fail to provide correct ARIA semantics, keyboard navigation, or screen reader announcements.</p>
 <p><code>auro-menu</code> provides:</p>
 <ul>
-<li><strong>Keyboard navigation</strong> — Arrow keys move between options, Enter selects, Escape cancels, Home/End jump to the first and last options.</li>
+<li><strong>Keyboard navigation</strong> — Arrow Up/Down move the active option; Enter selects it; Tab selects and moves focus out of the menu.</li>
 <li><strong>Active option tracking</strong> — The currently highlighted option is tracked programmatically, enabling <code>aria-activedescendant</code> patterns in parent components like <code>auro-select</code> and <code>auro-combobox</code>.</li>
 <li><strong>Multi-select semantics</strong> — When <code>multiSelect</code> is enabled, <code>aria-multiselectable</code> is set on the menu.</li>
 <li><strong>Loading state</strong> — <code>aria-busy</code> is set during loading, with customizable loading icon and text slots.</li>
@@ -24,15 +24,14 @@
 <ul>
 <li>Checkmark indicators for each selected option</li>
 <li>A <code>value</code> that returns a JSON-stringified array of selections</li>
-<li><code>allowDeselect</code> to toggle selections off</li>
-<li><code>selectAllMatchingOptions</code> for bulk selection operations</li>
-<li><code>clearSelection()</code> and <code>reset()</code> methods for programmatic control</li>
+<li>Click-to-toggle behavior that deselects an already-selected option</li>
+<li><code>reset()</code> method for programmatic control</li>
 </ul>
 <auro-header level="2" id="searchAndFiltering">Search and filtering</auro-header>
 <p>Native menus have no concept of filtering or highlighting matched text.</p>
 <p><code>auro-menu</code> supports:</p>
 <ul>
-<li><code>matchWord</code> to highlight matching portions of option text as the user types (used by <code>auro-combobox</code> for real-time filtering)</li>
+<li><auro-hyperlink href="customize#matchWord"><code>matchWord</code></auro-hyperlink> to highlight matching portions of option text as the user types (used by <code>auro-combobox</code> for real-time filtering)</li>
 <li>Programmatic <code>navigateOptions(direction)</code> for keyboard-driven traversal</li>
 </ul>
 <auro-header level="2" id="loadingState">Loading state</auro-header>
@@ -88,7 +87,7 @@
 <tr>
 <td>Keyboard navigation</td>
 <td>Browser-dependent</td>
-<td>Full arrow/Enter/Escape/Home/End</td>
+<td>Arrow Up/Down, Enter, Tab</td>
 </tr>
 <tr>
 <td>Composable primitive</td>
@@ -96,9 +95,9 @@
 <td>Foundation for select and combobox</td>
 </tr>
 <tr>
-<td>Deselect support</td>
-<td>No</td>
-<td><code>allowDeselect</code> attribute</td>
+<td>Multi-select deselect</td>
+<td>Ctrl+click list box</td>
+<td>Click-to-toggle in multi-select</td>
 </tr>
 </tbody>
 </table>

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

@@ -68,7 +68,7 @@ export class AuroMenu extends AuroElement {
             attribute: string;
         };
         /**
-         * 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.
          */
         optionSelected: {
             type: ObjectConstructor;

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

@@ -13,6 +13,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 +50,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 +84,7 @@ export class AuroMenuOption extends AuroElement {
     noCheckmark: boolean;
     disabled: boolean;
     noMatch: boolean;
+    persistent: boolean;
     /**
      * @private
      */