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

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

@@ -54,28 +54,26 @@
 &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">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">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">Arrow-key navigation</auro-header>
-<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>
+<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>
 <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>, 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>
+<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>
 <auro-header level="3">Selection state coordination</auro-header>
-<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>
+<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>
 <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>, 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>, <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>
 <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">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">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">Select-by-value and reset</auro-header>
-<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>
+<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>
 <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>
@@ -98,9 +96,9 @@
 <td>Built-in</td>
 </tr>
 <tr>
-<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>
+<td>Roving tabindex</td>
+<td>Manual</td>
+<td>Built-in</td>
 </tr>
 <tr>
 <td>Arrow-key navigation</td>
@@ -108,14 +106,9 @@
 <td>Built-in</td>
 </tr>
 <tr>
-<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>Type-ahead and <code>matchword</code> highlighting</td>
 <td>Not supported</td>
-<td>Provided by parent <code>auro-select</code> / <code>auro-combobox</code></td>
+<td>Built-in via <code>matchword</code></td>
 </tr>
 <tr>
 <td>Nested submenus</td>
@@ -125,7 +118,7 @@
 <tr>
 <td>Selection state coordination</td>
 <td>Manual <code>aria-selected</code> sync</td>
-<td>Coordinated internally</td>
+<td>Centralized via menu service</td>
 </tr>
 <tr>
 <td>ARIA roles and <code>aria-busy</code></td>
@@ -143,9 +136,9 @@
 <td><code>multiselect</code> + <code>value</code></td>
 </tr>
 <tr>
-<td>Multi-select deselect</td>
+<td>Allow-deselect behavior</td>
 <td>Manual</td>
-<td>Click-to-toggle built in</td>
+<td><code>allowDeselect</code> attribute</td>
 </tr>
 <tr>
 <td>Select-by-value and reset</td>

package/components/menu/demo/customize.md

@@ -9,20 +9,15 @@
 <auro-anchorlink fluid href="#restrictedWidth" class="level2 body-xs">Restricted Width</auro-anchorlink>
 <auro-anchorlink fluid href="#scroll" class="level2 body-xs">Scroll</auro-anchorlink>
 <auro-anchorlink fluid href="#nocheckmark" class="level2 body-xs">No Checkmark</auro-anchorlink>
-<auro-anchorlink fluid href="#dividers" class="level2 body-xs">Dividers</auro-anchorlink>
 <auro-anchorlink fluid href="#nestedMenu" class="level2 body-xs">Nested Menu</auro-anchorlink>
 <auro-anchorlink fluid href="#customBehavior">Behavior</auro-anchorlink>
-<auro-anchorlink fluid href="#static" class="level2 body-xs">Static Options</auro-anchorlink>
-<auro-anchorlink fluid href="#matchWord" class="level2 body-xs">Match Word</auro-anchorlink>
-<auro-anchorlink fluid href="#persistent" class="level2 body-xs">Persistent Option</auro-anchorlink>
-<auro-anchorlink fluid href="#nomatch" class="level2 body-xs">No Match Placeholder</auro-anchorlink>
 <auro-anchorlink fluid href="#disabled" class="level2 body-xs">Disabled Options</auro-anchorlink>
 <auro-anchorlink fluid href="#disabledMenu" class="level2 body-xs">Disabled Menu</auro-anchorlink>
-<auro-anchorlink fluid href="#loading" class="level2 body-xs">Loading</auro-anchorlink>
 <auro-anchorlink fluid href="#hidden" class="level2 body-xs">Hidden Options</auro-anchorlink>
 <auro-anchorlink fluid href="#multiselect" class="level2 body-xs">Multi-Select</auro-anchorlink>
 <auro-anchorlink fluid href="#presetValue" class="level2 body-xs">Preset Value</auro-anchorlink>
 <auro-anchorlink fluid href="#presetValueMultiselect" class="level2 body-xs">Preset Value (Multi)</auro-anchorlink>
+<auro-anchorlink fluid href="#preselect" class="level2 body-xs">Pre-Selected</auro-anchorlink>
 </auro-nav>
 </nav>
 <div class="mainContent">
@@ -57,9 +52,9 @@
             --ds-auro-menuoption-text-color: #5b1a6e;
           }
 </style>
-<auro-menu id="customTokensMenu" value="price">
+<auro-menu id="customTokensMenu">
 <auro-menuoption value="stops">Stops</auro-menuoption>
-<auro-menuoption value="price">Price</auro-menuoption>
+<auro-menuoption value="price" selected>Price</auro-menuoption>
 <auro-menuoption value="duration">Duration</auro-menuoption>
 <hr>
 <auro-menuoption value="departure">Departure</auro-menuoption>
@@ -80,9 +75,9 @@
     --ds-auro-menuoption-text-color: #5b1a6e;
   }
 &lt;/style&gt;
-&lt;auro-menu id="customTokensMenu" value="price"&gt;
+&lt;auro-menu id="customTokensMenu"&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="price" selected&gt;Price&lt;/auro-menuoption&gt;
   &lt;auro-menuoption value="duration"&gt;Duration&lt;/auro-menuoption&gt;
   &lt;hr&gt;
   &lt;auro-menuoption value="departure"&gt;Departure&lt;/auro-menuoption&gt;
@@ -283,47 +278,6 @@
 &lt;/auro-menu&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
-<auro-header level="3" id="dividers">Dividers</auro-header>
-<p>Insert standard <code>&lt;hr&gt;</code> elements between <code>auro-menuoption</code> elements to create visual group separators. Dividers are non-interactive and are skipped during keyboard navigation.</p>
-<div class="exampleWrapper">
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/hr.html) -->
-<!-- The below content is automatically added from ./../apiExamples/hr.html -->
-<auro-menu>
-<auro-menuoption value="new tab">New tab</auro-menuoption>
-<auro-menuoption value="new window">New window</auro-menuoption>
-<auro-menuoption value="open file">Open file</auro-menuoption>
-<auro-menuoption value="open location">Open location</auro-menuoption>
-<hr>
-<auro-menuoption value="close window">Close window</auro-menuoption>
-<auro-menuoption value="close tab">Close tab</auro-menuoption>
-<auro-menuoption value="save page as...">Save page as...</auro-menuoption>
-<hr>
-<auro-menuoption value="share">Share</auro-menuoption>
-<hr>
-<auro-menuoption value="print">Print</auro-menuoption>
-</auro-menu>
-<!-- AURO-GENERATED-CONTENT:END -->
-</div>
-<auro-accordion alignRight>
-<span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/hr.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/hr.html -->
-<pre class="language-html"><code class="language-html">&lt;auro-menu&gt;
-  &lt;auro-menuoption value="new tab"&gt;New tab&lt;/auro-menuoption&gt;
-  &lt;auro-menuoption value="new window"&gt;New window&lt;/auro-menuoption&gt;
-  &lt;auro-menuoption value="open file"&gt;Open file&lt;/auro-menuoption&gt;
-  &lt;auro-menuoption value="open location"&gt;Open location&lt;/auro-menuoption&gt;
-  &lt;hr&gt;
-  &lt;auro-menuoption value="close window"&gt;Close window&lt;/auro-menuoption&gt;
-  &lt;auro-menuoption value="close tab"&gt;Close tab&lt;/auro-menuoption&gt;
-  &lt;auro-menuoption value="save page as..."&gt;Save page as...&lt;/auro-menuoption&gt;
-  &lt;hr&gt;
-  &lt;auro-menuoption value="share"&gt;Share&lt;/auro-menuoption&gt;
-  &lt;hr&gt;
-  &lt;auro-menuoption value="print"&gt;Print&lt;/auro-menuoption&gt;
-&lt;/auro-menu&gt;</code></pre>
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
 <auro-header level="3" id="nestedMenu">Nested Menu</auro-header>
 <p>Nest additional <code>auro-menu</code> elements inside the default slot to create sub-menus. Each nested menu maintains its own selection state.</p>
 <div class="exampleWrapper">
@@ -404,144 +358,6 @@
 </section>
 <section>
 <auro-header level="2" id="customBehavior">Behavior</auro-header>
-<auro-header level="3" id="static">Static Options</auro-header>
-<p>Add the <code>static</code> attribute to an <code>auro-menuoption</code> to make it non-interactive — the option renders but is skipped during keyboard navigation and cannot be selected. Useful for section headers or informational rows inside a menu.</p>
-<div class="exampleWrapper">
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/static.html) -->
-<!-- The below content is automatically added from ./../apiExamples/static.html -->
-<auro-menu>
-<auro-menuoption static>Popular Destinations</auro-menuoption>
-<auro-menuoption value="sea">Seattle (SEA)</auro-menuoption>
-<auro-menuoption value="pdx">Portland (PDX)</auro-menuoption>
-<auro-menuoption value="sfo">San Francisco (SFO)</auro-menuoption>
-<auro-menuoption static>International</auro-menuoption>
-<auro-menuoption value="lhr">London (LHR)</auro-menuoption>
-<auro-menuoption value="nrt">Tokyo (NRT)</auro-menuoption>
-</auro-menu>
-<!-- AURO-GENERATED-CONTENT:END -->
-</div>
-<auro-accordion alignRight>
-<span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/static.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/static.html -->
-<pre class="language-html"><code class="language-html">&lt;auro-menu&gt;
-  &lt;auro-menuoption static&gt;Popular Destinations&lt;/auro-menuoption&gt;
-  &lt;auro-menuoption value="sea"&gt;Seattle (SEA)&lt;/auro-menuoption&gt;
-  &lt;auro-menuoption value="pdx"&gt;Portland (PDX)&lt;/auro-menuoption&gt;
-  &lt;auro-menuoption value="sfo"&gt;San Francisco (SFO)&lt;/auro-menuoption&gt;
-  &lt;auro-menuoption static&gt;International&lt;/auro-menuoption&gt;
-  &lt;auro-menuoption value="lhr"&gt;London (LHR)&lt;/auro-menuoption&gt;
-  &lt;auro-menuoption value="nrt"&gt;Tokyo (NRT)&lt;/auro-menuoption&gt;
-&lt;/auro-menu&gt;</code></pre>
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
-<auro-header level="3" id="matchWord">Match Word</auro-header>
-<p>Set the <code>matchWord</code> property to a string, and any option whose text contains that substring will render the matching portion visually highlighted. Typically driven by an input's <code>keyup</code> handler to power real-time filtering — this is the mechanism <code>&lt;auro-combobox&gt;</code> uses to highlight matches as the user types.</p>
-<div class="exampleWrapper">
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/match-word.html) -->
-<!-- The below content is automatically added from ./../apiExamples/match-word.html -->
-<auro-input id="matchWordInput" required>
-<span slot="label">Enter a value to match in the menu</span>
-</auro-input>
-<br />
-<auro-menu id="matchWordMenu">
-<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-menu>
-<auro-menuoption value="apples">Apples</auro-menuoption>
-<auro-menuoption value="oranges">Oranges</auro-menuoption>
-<auro-menuoption value="peaches">Peaches</auro-menuoption>
-</auro-menu>
-<auro-menuoption value="arrival">Arrival</auro-menuoption>
-</auro-menu>
-<!-- AURO-GENERATED-CONTENT:END -->
-</div>
-<auro-accordion alignRight>
-<span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/match-word.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/match-word.html -->
-<pre class="language-html"><code class="language-html">&lt;auro-input id="matchWordInput" required&gt;
-  &lt;span slot="label"&gt;Enter a value to match in the menu&lt;/span&gt;
-&lt;/auro-input&gt;
-&lt;br /&gt;
-&lt;auro-menu id="matchWordMenu"&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-menu&gt;
-    &lt;auro-menuoption value="apples"&gt;Apples&lt;/auro-menuoption&gt;
-    &lt;auro-menuoption value="oranges"&gt;Oranges&lt;/auro-menuoption&gt;
-    &lt;auro-menuoption value="peaches"&gt;Peaches&lt;/auro-menuoption&gt;
-  &lt;/auro-menu&gt;
-  &lt;auro-menuoption value="arrival"&gt;Arrival&lt;/auro-menuoption&gt;
-&lt;/auro-menu&gt;</code></pre>
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
-<auro-header level="3" id="persistent">Persistent Option</auro-header>
-<p>Add the <code>persistent</code> attribute to an <code>auro-menuoption</code> to opt it out of <code>matchWord</code> highlighting. The option remains fully interactive but its label is never rewritten — useful for utility rows like "Add new…" that should render identically regardless of the current filter string.</p>
-<div class="exampleWrapper">
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/persistent.html) -->
-<!-- The below content is automatically added from ./../apiExamples/persistent.html -->
-<auro-input id="persistentExampleInput">
-<span slot="label">Type to highlight matches</span>
-</auro-input>
-<br />
-<auro-menu id="persistentExampleMenu">
-<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-menuoption value="add" persistent>+ Add a new sort option</auro-menuoption>
-</auro-menu>
-<!-- AURO-GENERATED-CONTENT:END -->
-</div>
-<auro-accordion alignRight>
-<span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/persistent.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/persistent.html -->
-<pre class="language-html"><code class="language-html">&lt;auro-input id="persistentExampleInput"&gt;
-  &lt;span slot="label"&gt;Type to highlight matches&lt;/span&gt;
-&lt;/auro-input&gt;
-&lt;br /&gt;
-&lt;auro-menu id="persistentExampleMenu"&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-menuoption value="add" persistent&gt;+ Add a new sort option&lt;/auro-menuoption&gt;
-&lt;/auro-menu&gt;</code></pre>
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
-<auro-header level="3" id="nomatch">No Match Placeholder</auro-header>
-<p>Mark an option with the <code>nomatch</code> attribute to designate it as the placeholder shown when no other options match the user's input. When paired with <code>&lt;auro-combobox&gt;</code>, the combobox toggles the <code>hidden</code> attribute on this option automatically based on filter results.</p>
-<div class="exampleWrapper">
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/nomatch.html) -->
-<!-- The below content is automatically added from ./../apiExamples/nomatch.html -->
-<auro-menu>
-<auro-menuoption value="stops">Stops</auro-menuoption>
-<auro-menuoption value="price">Price</auro-menuoption>
-<auro-menuoption value="duration">Duration</auro-menuoption>
-<auro-menuoption nomatch>No matching results</auro-menuoption>
-</auro-menu>
-<!-- AURO-GENERATED-CONTENT:END -->
-</div>
-<auro-accordion alignRight>
-<span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/nomatch.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/nomatch.html -->
-<pre class="language-html"><code class="language-html">&lt;auro-menu&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 nomatch&gt;No matching results&lt;/auro-menuoption&gt;
-&lt;/auro-menu&gt;</code></pre>
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
 <auro-header level="3" id="disabled">Disabled Options</auro-header>
 <p>Use the <code>disabled</code> attribute on <code>auro-menuoption</code> to prevent interaction with specific options.</p>
 <div class="exampleWrapper">
@@ -624,123 +440,6 @@
 &lt;/auro-menu&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
-<auro-header level="3" id="loading">Loading</auro-header>
-<p>Use the <code>loading</code> attribute on <code>auro-menu</code> to indicate that options are being fetched asynchronously. Optional <code>loadingIcon</code> and <code>loadingText</code> slots let you customize the placeholder — a spinner, message, both, or neither.</p>
-<div class="exampleWrapper">
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/loading.html) -->
-<!-- The below content is automatically added from ./../apiExamples/loading.html -->
-<auro-button id="loadingExampleToggleButton">Toggle Loading</auro-button>
-<table id="loadingExampleTable">
-<thead>
-<tr>
-<td width="25%">Spinner + Text</td>
-<td width="25%">Text Only</td>
-<td width="25%">Spinner Only</td>
-<td width="25%">None</td>
-</tr>
-</thead>
-<tr>
-<td>
-<auro-menu>
-<auro-loader slot="loadingIcon" orbit xs></auro-loader><span slot="loadingText">Loading...</span>
-<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>
-</td>
-<td>
-<auro-menu>
-<span slot="loadingText">Loading...</span>
-<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>
-</td>
-<td>
-<auro-menu>
-<auro-loader slot="loadingIcon" orbit xs></auro-loader>
-<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>
-</td>
-<td>
-<auro-menu>
-<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>
-</td>
-</tr>
-</table>
-<!-- AURO-GENERATED-CONTENT:END -->
-</div>
-<auro-accordion alignRight>
-<span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/loading.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/loading.html -->
-<pre class="language-html"><code class="language-html">&lt;auro-button id="loadingExampleToggleButton"&gt;Toggle Loading&lt;/auro-button&gt;
-&lt;table id="loadingExampleTable"&gt;
-  &lt;thead&gt;
-    &lt;tr&gt;
-      &lt;td width="25%"&gt;Spinner + Text&lt;/td&gt;
-      &lt;td width="25%"&gt;Text Only&lt;/td&gt;
-      &lt;td width="25%"&gt;Spinner Only&lt;/td&gt;
-      &lt;td width="25%"&gt;None&lt;/td&gt;
-    &lt;/tr&gt;
-  &lt;/thead&gt;
-  &lt;tr&gt;
-    &lt;td&gt;
-      &lt;auro-menu&gt;
-        &lt;auro-loader slot="loadingIcon" orbit xs&gt;&lt;/auro-loader&gt;&lt;span slot="loadingText"&gt;Loading...&lt;/span&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;/td&gt;
-    &lt;td&gt;
-      &lt;auro-menu&gt;
-        &lt;span slot="loadingText"&gt;Loading...&lt;/span&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;/td&gt;
-    &lt;td&gt;
-      &lt;auro-menu&gt;
-        &lt;auro-loader slot="loadingIcon" orbit xs&gt;&lt;/auro-loader&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;/td&gt;
-    &lt;td&gt;
-      &lt;auro-menu&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;/td&gt;
-&lt;/tr&gt;
-&lt;/table&gt;</code></pre>
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
 <auro-header level="3" id="hidden">Hidden Options</auro-header>
 <p>Use the <code>hidden</code> attribute on <code>auro-menuoption</code> to visually hide an option while keeping it in the DOM.</p>
 <div class="exampleWrapper">
@@ -810,7 +509,7 @@
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 <auro-header level="3" id="presetValue">Preset Value</auro-header>
-<p>Use the <code>value</code> attribute on <code>auro-menu</code> to set the selected option when the menu renders. The value must match a selectable option; if it matches an option marked <code>disabled</code> or <code>static</code>, no option is selected and <code>auroMenu-selectValueFailure</code> is dispatched.</p>
+<p>Use the <code>value</code> attribute on <code>auro-menu</code> to set the selected option when the menu renders.</p>
 <div class="exampleWrapper">
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/preset-value.html) -->
 <!-- The below content is automatically added from ./../apiExamples/preset-value.html -->
@@ -863,6 +562,47 @@
 &lt;/auro-menu&gt;</code></pre>
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
+<auro-header level="3" id="preselect">Pre-Selected</auro-header>
+<p>Use the <code>selected</code> attribute on <code>auro-menuoption</code> to pre-select an option when the menu renders.</p>
+<div class="exampleWrapper">
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/preselect.html) -->
+<!-- The below content is automatically added from ./../apiExamples/preselect.html -->
+<auro-menu>
+<auro-menuoption value="new tab">New tab</auro-menuoption>
+<auro-menuoption value="new window" selected>New window</auro-menuoption>
+<auro-menuoption value="open file">Open file</auro-menuoption>
+<auro-menuoption value="open location">Open location</auro-menuoption>
+<hr>
+<auro-menuoption value="close window">Close window</auro-menuoption>
+<auro-menuoption value="close tab" disabled>Close tab</auro-menuoption>
+<auro-menuoption value="save page as...">Save page as...</auro-menuoption>
+<hr>
+<auro-menuoption value="share" disabled>Share</auro-menuoption>
+<hr>
+<auro-menuoption value="print">Print</auro-menuoption>
+</auro-menu>
+<!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+<span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/preselect.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/preselect.html -->
+<pre class="language-html"><code class="language-html">&lt;auro-menu&gt;
+  &lt;auro-menuoption value="new tab"&gt;New tab&lt;/auro-menuoption&gt;
+  &lt;auro-menuoption value="new window" selected&gt;New window&lt;/auro-menuoption&gt;
+  &lt;auro-menuoption value="open file"&gt;Open file&lt;/auro-menuoption&gt;
+  &lt;auro-menuoption value="open location"&gt;Open location&lt;/auro-menuoption&gt;
+  &lt;hr&gt;
+  &lt;auro-menuoption value="close window"&gt;Close window&lt;/auro-menuoption&gt;
+  &lt;auro-menuoption value="close tab" disabled&gt;Close tab&lt;/auro-menuoption&gt;
+  &lt;auro-menuoption value="save page as..."&gt;Save page as...&lt;/auro-menuoption&gt;
+  &lt;hr&gt;
+  &lt;auro-menuoption value="share" disabled&gt;Share&lt;/auro-menuoption&gt;
+  &lt;hr&gt;
+  &lt;auro-menuoption value="print"&gt;Print&lt;/auro-menuoption&gt;
+&lt;/auro-menu&gt;</code></pre>
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
 </section>
 </div>
 </div>

package/components/menu/demo/design.md

@@ -22,7 +22,7 @@
 <auro-header level="2" id="shapeSizeLayout">Shape | Size | Layout Support</auro-header>
 <p>The <code>auro-menu</code> component supports the <code>shape</code> and <code>size</code> feature set. The component defaults to <code>shape="box"</code> and <code>size="sm"</code>. The <code>layout</code> attribute is not supported by this component.</p>
 <auro-header level="3" id="size">Size</auro-header>
-<p>Use the <code>size</code> attribute to change the size of menu options. Supported values are <code>xs</code>, <code>sm</code> (default), <code>md</code>, <code>lg</code>, and <code>xl</code>.</p>
+<p>Use the <code>size</code> attribute to change the size of menu options. Supported values are <code>sm</code> (default) and <code>md</code>.</p>
 <div class="exampleWrapper">
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/size.html) -->
 <!-- The below content is automatically added from ./../apiExamples/size.html -->