@aurodesignsystem/auro-formkit 5.9.0 → 5.9.2

package/components/menu/demo/api.md

@@ -3,29 +3,29 @@
 
 # auro-menu
 
-The auro-menu element provides users a way to select from a list of options.
+The `auro-menu` element provides users a way to select from a list of options.
 
 ## Properties
 
-| Property                   | Attribute                  | Modifiers | Type                              | Default     | Description                                      |
-|----------------------------|----------------------------|-----------|-----------------------------------|-------------|--------------------------------------------------|
-| [allowDeselect](#allowDeselect)            | `allowDeselect`            |           | `boolean`                         | false       | Allows deselecting an already selected option when clicked again in single-select mode. |
-| [disabled](#disabled)                 | `disabled`                 |           | `boolean`                         |             | When true, the entire menu and all options are disabled; |
-| [hasLoadingPlaceholder](#hasLoadingPlaceholder)    |                            |           | `boolean`                         |             | Indicates whether the menu has a loadingIcon or loadingText to render when in a loading state. |
-| [index](#index)                    |                            |           | `number`                          |             |                                                  |
-| [items](#items)                    |                            | readonly  | `HTMLElement[]`                   |             |                                                  |
-| [layout](#layout)                   |                            |           | `string`                          |             |                                                  |
-| [loading](#loading)                  | `loading`                  |           | `boolean`                         | false       | When true, displays a loading state using the loadingIcon and loadingText slots if provided. |
-| [matchWord](#matchWord)                | `matchword`                |           | `string`                          | "undefined" | Specifies a string used to highlight matched string parts in options. |
-| [multiSelect](#multiSelect)              | `multiselect`              |           | `boolean`                         | false       | When true, the selected option can be multiple options. |
-| [noCheckmark](#noCheckmark)              | `nocheckmark`              |           | `boolean`                         | false       | When true, selected option will not show the checkmark. |
-| [optionActive](#optionActive)             | `optionactive`             |           | `object`                          | "undefined" | Specifies the current active menuOption.         |
-| [optionSelected](#optionSelected)           | `optionSelected`           |           | `HTMLElement\|Array<HTMLElement>` | "undefined" | An array of currently selected menu options, type `HTMLElement` by default. In multi-select mode, `optionSelected` is an array of HTML elements. |
-| [options](#options)                  |                            | readonly  | `array`                           |             | Available menu options                           |
-| [selectAllMatchingOptions](#selectAllMatchingOptions) | `selectAllMatchingOptions` |           | `boolean`                         | false       | When true, selects all options that match the provided value/key when setting value and multiselect is enabled. |
-| [selectedOption](#selectedOption)           |                            | readonly  | `HTMLElement \| null`             |             | Gets the first selected option, or null if none. |
-| [selectedOptions](#selectedOptions)          |                            | readonly  | `HTMLElement[]`                   |             | Gets the currently selected options.             |
-| [value](#value)                    | `value`                    |           | `string`                          | "undefined" | Value selected for the component.                |
+| Property                   | Attribute                  | Modifiers | Type                  | Default     | Description                                      |
+|----------------------------|----------------------------|-----------|-----------------------|-------------|--------------------------------------------------|
+| [allowDeselect](#allowDeselect)            | `allowDeselect`            |           | `boolean`             | false       | Allows deselecting an already selected option when clicked again in single-select mode. |
+| [currentLabel](#currentLabel)             |                            | readonly  | `string`              |             |                                                  |
+| [disabled](#disabled)                 | `disabled`                 |           | `boolean`             |             | When true, the entire menu and all options are disabled. |
+| [hasLoadingPlaceholder](#hasLoadingPlaceholder)    | `hasLoadingPlaceholder`    |           | `boolean`             |             | Indicates whether the menu has a loadingIcon or loadingText to render when in a loading state. |
+| [index](#index)                    |                            |           | `number`              |             |                                                  |
+| [items](#items)                    |                            | readonly  | `HTMLElement[]`       |             |                                                  |
+| [loading](#loading)                  | `loading`                  |           | `boolean`             | false       | When true, displays a loading state using the loadingIcon and loadingText slots if provided. |
+| [matchWord](#matchWord)                | `matchword`                |           | `string`              | "undefined" | Specifies a string used to highlight matched string parts in options. |
+| [multiSelect](#multiSelect)              | `multiselect`              |           | `boolean`             | false       | When true, the selected option can be multiple options. |
+| [noCheckmark](#noCheckmark)              | `nocheckmark`              |           | `boolean`             | false       | When true, selected option will not show the checkmark. |
+| [optionActive](#optionActive)             | `optionactive`             |           | `object`              | "undefined" | Specifies the current active menuOption.         |
+| [optionSelected](#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](#options)                  |                            | readonly  | `array`               |             | Available menu options                           |
+| [selectAllMatchingOptions](#selectAllMatchingOptions) | `selectAllMatchingOptions` |           | `boolean`             | false       | When true, selects all options that match the provided value/key when setting value and multiselect is enabled. |
+| [selectedOption](#selectedOption)           |                            | readonly  | `HTMLElement \| null` |             | Gets the first selected option, or null if none. |
+| [selectedOptions](#selectedOptions)          |                            | readonly  | `HTMLElement[]`       |             | Gets the currently selected options.             |
+| [value](#value)                    | `value`                    |           | `string`              | "undefined" | The value of the selected option. In multi-select mode, this is a JSON stringified array of selected option values. |
 
 ## Methods
 
@@ -56,31 +56,20 @@ The auro-menu element provides users a way to select from a list of options.
 
 # auro-menuoption
 
-The auro-menu element provides users a way to define a menu option.
+The `auro-menuoption` element provides users a way to define a menu option.
 
-## Attributes
-
-| Attribute     | Type     | Description                                      |
-|---------------|----------|--------------------------------------------------|
-| [noCheckmark](#noCheckmark) | `String` | When true, selected option will not show the checkmark. |
-
 ## Properties
 
-| Property      | Attribute     | Modifiers | Type      | Default | Description                                      |
-|---------------|---------------|-----------|-----------|---------|--------------------------------------------------|
-| [disabled](#disabled)    | `disabled`    |           | `Boolean` | false   | When true specifies that the menuoption is disabled. |
-| [event](#event)       | `event`       |           | `string`  |         |                                                  |
-| [iconTag](#iconTag)     |               |           | `string`  |         |                                                  |
-| [isActive](#isActive)    |               | readonly  | `boolean` |         | Returns whether the menu option is currently active and selectable.<br />An option is considered active if it is not hidden, not disabled, and not static. |
-| [key](#key)         | `key`         |           | `string`  |         |                                                  |
-| [layout](#layout)      |               |           | `string`  |         |                                                  |
-| [matchWord](#matchWord)   | `matchWord`   |           | `string`  |         |                                                  |
-| [menuService](#menuService) | `menuService` |           | `object`  | null    |                                                  |
-| [nocheckmark](#nocheckmark) | `nocheckmark` |           | `boolean` | false   |                                                  |
-| [selected](#selected)    | `selected`    |           | `Boolean` | false   | Specifies that an option is selected.            |
-| [tabIndex](#tabIndex)    | `tabIndex`    |           | `number`  |         |                                                  |
-| [unsubscribe](#unsubscribe) |               |           |           | null    |                                                  |
-| [value](#value)       | `value`       |           | `String`  |         | Specifies the value to be sent to a server.      |
+| Property      | Attribute  | Modifiers | Type      | Default | Description                                      |
+|---------------|------------|-----------|-----------|---------|--------------------------------------------------|
+| [disabled](#disabled)    | `disabled` |           | `boolean` | false   | When true, disables the menu option.             |
+| [iconTag](#iconTag)     |            |           | `string`  |         |                                                  |
+| [isActive](#isActive)    |            | readonly  | `boolean` |         | Returns whether the menu option is currently active and selectable.<br />An option is considered active if it is not hidden, not disabled, and not static. |
+| [key](#key)         | `key`      |           | `string`  |         | Allows users to set a unique key for the menu option for specified option selection. If no key is provided, the value property will be used. |
+| [selected](#selected)    | `selected` |           | `boolean` | false   | Specifies that an option is selected.            |
+| [tabIndex](#tabIndex)    | `tabIndex` |           | `number`  |         | Specifies the tab index of the menu option.      |
+| [unsubscribe](#unsubscribe) |            |           |           | null    |                                                  |
+| [value](#value)       | `value`    |           | `string`  |         | Specifies the value to be sent to a server.      |
 
 ## Methods
 
@@ -107,9 +96,7 @@ The auro-menu element provides users a way to define a menu option.
 |      | Specifies text for an option, but is not the value. |
 <!-- AURO-GENERATED-CONTENT:END -->
 
-## API Examples
-
-### Basic
+## Basic
 
 <div class="exampleWrapper">
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/basic.html) -->
@@ -140,7 +127,138 @@ The auro-menu element provides users a way to define a menu option.
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-### Using Keys
+## Property & Attribute Examples
+
+### Deselect Option
+
+When set, the `allowDeselect` attribute allows the user to click on a selected menu option again to deselect it when the menu is not in multi-select mode.
+
+When the menu is in multi-select mode, this attribute has no effect and the user will be able to deselect the last remaining selected option.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/allow-deselect.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/allow-deselect.html -->
+  <auro-menu allowDeselect>
+    <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>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/allow-deselect.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/allow-deselect.html -->
+
+```html
+<auro-menu allowDeselect>
+  <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>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+### Disabled
+
+The `auro-menu` element with `disabled` will mark all `auro-menuoption` elements as disabled.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/disabled-menu.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/disabled-menu.html -->
+  <auro-menu disabled>
+    <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/disabled-menu.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/disabled-menu.html -->
+
+```html
+<auro-menu disabled>
+  <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 -->
+</auro-accordion>
+
+#### Single Disabled Option
+
+The `auro-menuoption` element supports the placement of the `disabled` attribute per option. A fully disabled list would be managed in an outer wrapping drop down menu element.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/disabled.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/disabled.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" 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/disabled.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/disabled.html -->
+
+```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" 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 -->
+</auro-accordion>
+
+### Keys
 
 When setting the `value` property, matches are actually performed on the value of the `key` property of the `auro-menuoption` and not the `value` property. By default, the value of `key` is equal to the value of the `value` property. However, for advanced use cases, the `key` value can be overriden to allow for more specific matches.
 
@@ -150,25 +268,25 @@ In the below example, setting the value of the menu `'stops'` will select the bo
 
 Due to a limitation with Lit change detection to the `value` property, if multiple options with the same exist and one is selected, you must first clear the current value before attempting to select another option with the same value, even if the keys are unique. See code example below.
 
-_Note: Since the value passed to the `value` property when programmatically setting it is overwritten with the proper derived value once the menu has updated, note that it will take one lifecycle before the `value` property is updated to the value that represents the actual menu state._
-
+_Note: Since the value passed to the `value` property when programmatically setting it is overwritten with the proper derived value once the menu has updated, note that it will take one lifecycle before the `value` property is updated to the value that represents the actual menu state._
+
 <div class="exampleWrapper">
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/keys.html) -->
-<!-- The below content is automatically added from ./../apiExamples/keys.html -->
-<auro-button id="stopsTopButton">Call `menu.value = 'stops-top'`</auro-button>
-<auro-button id="stopsButton">Call `menu.value = 'stops'`</auro-button>
-<auro-menu id="keys-menu">
-  <auro-menuoption value="stops" key="stops-top">Stops</auro-menuoption>
-  <auro-menuoption value="price" key="price-top">Price</auro-menuoption>
-  <hr>
-  <auro-menuoption value="duration">Duration</auro-menuoption>
-  <auro-menuoption value="departure">Departure</auro-menuoption>
-  <auro-menuoption value="arrival">Arrival</auro-menuoption>
-  <auro-menuoption value="stops">Stops</auro-menuoption>
-  <auro-menuoption value="price">Price</auro-menuoption>
-</auro-menu>
-<p id="output" class="body-sm"></p>
-<!-- AURO-GENERATED-CONTENT:END -->
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/keys.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/keys.html -->
+  <auro-button id="stopsTopButton">Call `menu.value = 'stops-top'`</auro-button>
+  <auro-button id="stopsButton">Call `menu.value = 'stops'`</auro-button>
+  <auro-menu id="keys-menu">
+    <auro-menuoption value="stops" key="stops-top">Stops</auro-menuoption>
+    <auro-menuoption value="price" key="price-top">Price</auro-menuoption>
+    <hr>
+    <auro-menuoption value="duration">Duration</auro-menuoption>
+    <auro-menuoption value="departure">Departure</auro-menuoption>
+    <auro-menuoption value="arrival">Arrival</auro-menuoption>
+    <auro-menuoption value="stops">Stops</auro-menuoption>
+    <auro-menuoption value="price">Price</auro-menuoption>
+  </auro-menu>
+  <p id="output" class="body-sm"></p>
+  <!-- AURO-GENERATED-CONTENT:END -->
 </div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
@@ -212,41 +330,248 @@ export function initKeysExample() {
     output.innerHTML = '';
   };
 
-  const updateMenuValue = (value) => {
-    resetConsole();
-    createConsoleEntry(`Setting menu.value: <em>"${value}"</em>`);
-    menu.value = '';
-    menu.value = value;
-    createConsoleEntry(`menu.value before next lifecycle: <em>"${menu.value}"</em>`);
-    setTimeout(() => {
-      createConsoleEntry(`menu.value after lifecycle: <em>"${menu.value}"</em>`);
-    });
-  };
+  const updateMenuValue = (value) => {
+    resetConsole();
+    createConsoleEntry(`Setting menu.value: <em>"${value}"</em>`);
+    menu.value = '';
+    menu.value = value;
+    createConsoleEntry(`menu.value before next lifecycle: <em>"${menu.value}"</em>`);
+    setTimeout(() => {
+      createConsoleEntry(`menu.value after lifecycle: <em>"${menu.value}"</em>`);
+    });
+  };
+
+  stopsButton.addEventListener('click', () => {
+    updateMenuValue('stops');
+  });
+
+  stopsTopButton.addEventListener('click', () => {
+    updateMenuValue('stops-top');
+  });
+};
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+### Loading
+
+While content is loading, the menu can either remain empty or display a loading placeholder
+
+<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 -->
+
+```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 -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/loading.js) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/loading.js -->
+
+```js
+export function auroMenuLoadingExample() {
+  document.querySelector("#loadingExampleToggleButton").addEventListener("click", () => {
+    document.querySelectorAll("#loadingExampleTable auro-menu").forEach(menu => menu.toggleAttribute("loading"));
+  });
+}
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+### Match Word
+
+Use the `matchWord` attribute to highlight string parts of each menuoption that are equal to `matchWord`. The matching algorithm is case insensitive (e.g., `n` matches `N`).
+
+<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 -->
+
+```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 -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/match-word.js) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/match-word.js -->
+
+```js
+function updateMatch() {
+  let matchWordMenu = document.querySelector('#matchWordMenu');
+
+  matchWordMenu.matchWord = matchWordInput.value;
+}
 
-  stopsButton.addEventListener('click', () => {
-    updateMenuValue('stops');
-  });
+export function auroMenuMatchWordExample() {
+  let matchWordInput = document.querySelector('#matchWordInput');
 
-  stopsTopButton.addEventListener('click', () => {
-    updateMenuValue('stops-top');
-  });
-};
+  matchWordInput.addEventListener('keyup', updateMatch);
+}
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-### Attribute Examples
-
-#### allowDeselect
+### Multi-Select
 
-When set, the `allowDeselect` attribute allows the user to click on a selected menu option again to deselect it when the menu is not in multi-select mode.
+The `auro-menu` supports a multi-select option. To use, place the `multiselect` attribute on the `<auro-menu>` element tag or update the `multiselect` property programmatically.
 
-When the menu is in multi-select mode, this attribute has no effect and the user will be able to deselect the last remaining selected option.
+In multi-select mode, the `value` property will always return a valid JSON string that contains an array of selected values, e.g. `'["stops","duration","arrival"]'`, when accessed.
+
+The value of the menu may be set via multiple methods when in multi-select mode: 
+- Programmatically or via attribute by passing a valid JSON string that can be parsed using `JSON.parse`.
+- Programmatically or via attribute by passing a single matching value in a string, e.g. `"stops"`.
+- Programmatically by passing an array of string values, e.g. `["stops","duration","arrival"]`.
+
+_Note: Other methods of setting the value may work but are not officially supported and may stop working unexpectedly._
 
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/allowDeselect.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/allowDeselect.html -->
-  <auro-menu allowDeselect>
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/multi-select.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/multi-select.html -->
+  <auro-menu multiselect>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
     <auro-menuoption value="duration">Duration</auro-menuoption>
@@ -257,11 +582,11 @@ When the menu is in multi-select mode, this attribute has no effect and the user
 </div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/allowDeselect.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/allowDeselect.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/multi-select.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/multi-select.html -->
 
 ```html
-<auro-menu allowDeselect>
+<auro-menu multiselect>
   <auro-menuoption value="stops">Stops</auro-menuoption>
   <auro-menuoption value="price">Price</auro-menuoption>
   <auro-menuoption value="duration">Duration</auro-menuoption>
@@ -272,7 +597,8 @@ When the menu is in multi-select mode, this attribute has no effect and the user
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-#### noCheckmark<a name="noCheckmark"></a>
+### No Checkmark
+
 Applying the `noCheckmark` attribute will prevent the check icon from being shown on the selected option. The left padding to reserve space for the checkmark is also removed.
 
 <div class="exampleWrapper">
@@ -354,169 +680,15 @@ Applying the `noCheckmark` attribute will prevent the check icon from being show
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-#### disabled<a name="disabled"></a>
-The `auro-menu` element with `disabled` will mark all `auro-menuoption` elements as disabled.
-
-<div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/disabledMenu.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/disabledMenu.html -->
-  <auro-menu disabled>
-    <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/disabledMenu.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/disabledMenu.html -->
-
-```html
-<auro-menu disabled>
-  <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 -->
-</auro-accordion>
-
-#### matchWord<a name="matchWord"></a>
-The `auro-menu` component supports the use of the `matchWord` attribute to highlight string parts of each menuoption that are equal to `matchWord`. The matching algorithm is case insensitive (e.g., `n` matches `N`).
-
-<div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/matchWord.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/matchWord.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/matchWord.js) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/matchWord.js -->
-
-```js
-function updateMatch() {
-  let matchWordMenu = document.querySelector('#matchWordMenu');
-
-  matchWordMenu.matchWord = matchWordInput.value;
-}
-
-export function auroMenuMatchWordExample() {
-  let matchWordInput = document.querySelector('#matchWordInput');
-
-  matchWordInput.addEventListener('keyup', updateMatch);
-}
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/matchWord.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/matchWord.html -->
-
-```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 -->
-</auro-accordion>
-
-### Multi-Select<a name="multiSelect"></a>
-The `auro-menu` supports a multi-select option. To use, place the `multiselect` attribute on the `<auro-menu>` element tag or update the `multiselect` property programmatically.
-
-In multi-select mode, the `value` property will always return a valid JSON string that contains an array of selected values, e.g. `'["stops","duration","arrival"]'`, when accessed.
-
-The value of the menu may be set via multiple methods when in multi-select mode: 
-- Programmatically or via attribute by passing a valid JSON string that can be parsed using `JSON.parse`.
-- Programmatically or via attribute by passing a single matching value in a string, e.g. `"stops"`.
-- Programmatically by passing an array of string values, e.g. `["stops","duration","arrival"]`.
-
-_Note: Other methods of setting the value may work but are not officially supported and may stop working unexpectedly._
-
-<div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/multiSelect.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/multiSelect.html -->
-  <auro-menu multiselect>
-    <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>
-  <!-- AURO-GENERATED-CONTENT:END -->
-</div>
-<auro-accordion alignRight>
-  <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/multiSelect.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/multiSelect.html -->
-
-```html
-<auro-menu multiselect>
-  <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>
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
-
-#### Optional Flag - `selectAllMatchingOptions`
+### Select All Matching Options
 
-When this flag is set on the `auro-menu` tag, when the value is set, any option with a matching key will be selected, even when multiple options with that key exist.
+Use the `selectAllMatchingOptions` attribute to enable selecting all options with matching keys when `value` is set programmatically.
 
 If not set, only the first matching option will be selected.
 
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/selectAllMatchingOptions.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/selectAllMatchingOptions.html -->
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/select-all-matching-options.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/select-all-matching-options.html -->
   <p>With <code>selectAllMatchingOptions</code> enabled:</p>
   <auro-button id="selectAllBtn">Set <code>menu.value</code> to <code>'stops'</code></auro-button>
   <auro-button id="resetAllBtn">Reset Menu</auro-button>
@@ -550,8 +722,8 @@ If not set, only the first matching option will be selected.
 </div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/selectAllMatchingOptions.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/selectAllMatchingOptions.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/select-all-matching-options.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/select-all-matching-options.html -->
 
 ```html
 <p>With <code>selectAllMatchingOptions</code> enabled:</p>
@@ -585,148 +757,89 @@ If not set, only the first matching option will be selected.
 </auro-menu>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
-
-#### Loading<a name="loading"></a>
-While content is loading, the menu can either remain empty or display a loading placeholder
-
-<div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/loading.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/loading.html -->
-  <script>
-  </script>
-  <auro-button common 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.js) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/loading.js -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/select-all-matching-options.js) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/select-all-matching-options.js -->
 
 ```js
-export function auroMenuLoadingExample() {
-  document.querySelector("#loadingExampleToggleButton").addEventListener("click", () => {
-    document.querySelectorAll("#loadingExampleTable auro-menu").forEach(menu => menu.toggleAttribute("loading"));
+export const initSelectAllMatchingOptionsExample = () => {
+
+  const selectAllBtn = document.getElementById('selectAllBtn');
+  const selectAllMenu = document.getElementById('selectAllMenu');
+  const selectFirstBtn = document.getElementById('selectFirstBtn');
+  const selectFirstMenu = document.getElementById('selectFirstMenu');
+  const resetAllBtn = document.getElementById('resetAllBtn');
+  const resetFirstBtn = document.getElementById('resetFirstBtn');
+
+  selectAllBtn.addEventListener('click', () => {
+    selectAllMenu.value = 'stops';
   });
-}
+
+  resetAllBtn.addEventListener('click', () => {
+    selectAllMenu.reset();
+  });
+
+  selectFirstBtn.addEventListener('click', () => {
+    selectFirstMenu.value = 'stops';
+  });
+
+  resetFirstBtn.addEventListener('click', () => {
+    selectFirstMenu.reset();
+  });
+};
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/loading.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/loading.html -->
+</auro-accordion>
+
+### Preselect Option
+
+The `auro-menu` element supports a pre-selected option via the `selected` attribute on the `auro-menuoption` element.
+
+<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 -->
 
 ```html
-<script>
-</script>
-<auro-button common 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-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 -->
 </auro-accordion>
 
-### Common Use Cases
+## Common Usage Patterns & Functional Examples
 
-#### Scroll
+### Scroll
 
 When setting the `max-height` of `auro-menu`, all of the overflowing content can be accessed via a scrollbar.
 
@@ -809,7 +922,7 @@ When setting the `max-height` of `auro-menu`, all of the overflowing content can
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-#### Options with horizonal separator
+### Options with Horizontal Separator
 
 To create a natural separation between options, simply use a `<hr>` element.
 
@@ -856,13 +969,13 @@ To create a natural separation between options, simply use a `<hr>` element.
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-#### Nesting auro-menus to create sub-menus
+### Submenu / Nested Menu
 
 The `auro-menu` element supports the placement of an `auro-menu` inside of another `auro-menu`. There is no technical limit to the level of nesting.
 
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/nestedMenu.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/nestedMenu.html -->
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/nested-menu.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/nested-menu.html -->
   <auro-menu id="alpha">
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
@@ -899,8 +1012,8 @@ The `auro-menu` element supports the placement of an `auro-menu` inside of anoth
 </div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/nestedMenu.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/nestedMenu.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/nested-menu.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/nested-menu.html -->
 
 ```html
 <auro-menu id="alpha">
@@ -939,107 +1052,13 @@ The `auro-menu` element supports the placement of an `auro-menu` inside of anoth
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-#### An auro-menuoption element w/ disabled state
-
-The `auro-menuoption` element supports the placement of the `disabled` attribute per option. A fully disabled list would be managed in an outer wrapping drop down menu element.
-
-<div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/disabled.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/disabled.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" 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/disabled.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/disabled.html -->
-
-```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" 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 -->
-</auro-accordion>
-
-#### Menu with pre-selected menu option
-
-The `auro-menu` element supports a pre-selected option via the `selected` attribute on the `auro-menuoption` element.
-
-<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 -->
-
-```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 -->
-</auro-accordion>
-
-#### Menu with restricted width and long option
+### Restricted Width and Long Option
 
 The `auro-menu` element supports scenarios where the outer parent element of the menu constrains its width and there are options with text longer than the pull down menu will support. Truncated content will be illustrated with an ellipsis.
 
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/restrictedWidth.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/restrictedWidth.html -->
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/restricted-width.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/restricted-width.html -->
   <auro-menu style="width: 300px">
     <auro-menuoption value="new tab">New tab</auro-menuoption>
     <auro-menuoption value="new window">New window</auro-menuoption>
@@ -1058,8 +1077,8 @@ The `auro-menu` element supports scenarios where the outer parent element of the
 </div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/restrictedWidth.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/restrictedWidth.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/restricted-width.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/restricted-width.html -->
 
 ```html
 <auro-menu style="width: 300px">
@@ -1080,7 +1099,7 @@ The `auro-menu` element supports scenarios where the outer parent element of the
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-#### Menu with hidden options
+#### Hidden Options
 
 The `auro-menuoption` element supports scenarios where the menu option needs to be hidden. e.g. the only visible menu options contain the `matchWord`.
 
@@ -1127,7 +1146,7 @@ The `auro-menuoption` element supports scenarios where the menu option needs to
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-#### Reset menu selection state
+### Reset Menu Selection State
 
 The `auro-menu` may be reset to a state with no menuoption selected by setting the `value` to `undefined`.
 
@@ -1147,22 +1166,6 @@ The `auro-menu` may be reset to a state with no menuoption selected by setting t
 </div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/reset.js) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/reset.js -->
-
-```js
-export function auroMenuResetExample() {
-  const resetExampleBtnElem = document.querySelector('#resetExampleBtn');
-  const resetExampleElem = document.querySelector('#resetExample');
-
-  if (resetExampleElem && resetExampleBtnElem) {
-    resetExampleBtnElem.addEventListener('click', () => {
-      resetExampleElem.reset();
-    });
-  }
-}
-```
-<!-- AURO-GENERATED-CONTENT:END -->
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/reset.html) -->
 <!-- The below code snippet is automatically added from ./../apiExamples/reset.html -->
 
@@ -1178,80 +1181,20 @@ export function auroMenuResetExample() {
 <auro-button id="resetExampleBtn">RESET</auro-button>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/reset.js) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/reset.js -->
 
-### Theme Support
-
-The component may be restyled using the following code sample and changing the values of the following token(s).
-
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../src/styles/default/tokens.scss) -->
-<!-- The below code snippet is automatically added from ./../src/styles/default/tokens.scss -->
+```js
+export function auroMenuResetExample() {
+  const resetExampleBtnElem = document.querySelector('#resetExampleBtn');
+  const resetExampleElem = document.querySelector('#resetExample');
 
-```scss
-@use "@aurodesignsystem/design-tokens/dist/themes/alaska/SCSSVariables--alaska" as v;
-
-:host {
-  --ds-auro-menu-divider-color: var(--ds-basic-color-border-divider, #{v.$ds-basic-color-border-divider});
-  --ds-auro-menu-loader-color: var(--ds-basic-color-brand-primary, #{v.$ds-basic-color-brand-primary});
-  --ds-auro-menu-loader-text-color: var(--ds-basic-color-texticon-default, #{v.$ds-basic-color-texticon-default});
-  --ds-auro-menuoption-container-color: transparent;
-  --ds-auro-menuoption-container-border-color: var(--ds-auro-menuoption-container-color);
-  --ds-auro-menuoption-icon-color: transparent;
-  --ds-auro-menuoption-text-color: var(--ds-basic-color-texticon-default, #{v.$ds-basic-color-texticon-default});
+  if (resetExampleElem && resetExampleBtnElem) {
+    resetExampleBtnElem.addEventListener('click', () => {
+      resetExampleElem.reset();
+    });
+  }
 }
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
-<div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/customColor.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/customColor.html -->
-  <style>
-    #customColorMenu auro-menuoption[selected] {
-      --ds-auro-menuoption-container-color: var(--ds-basic-color-surface-accent1-subtle);
-      --ds-auro-menuoption-text-color: var(--ds-basic-color-texticon-default);
-    }
-    #customColorMenu auro-menuoption:hover {
-      --ds-auro-menuoption-container-color: var(--ds-basic-color-surface-accent1-muted);
-    }
-    #customColorMenu auro-menuoption:focus {
-      --ds-auro-menuoption-container-border-color: var(--ds-basic-color-border-brand);
-    }
-
-  </style>
-  <auro-menu id="customColorMenu">
-    <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>
-  <!-- AURO-GENERATED-CONTENT:END -->
-</div>
-<auro-accordion alignRight>
-  <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/customColor.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/customColor.html -->
-
-```html
-<style>
-  #customColorMenu auro-menuoption[selected] {
-    --ds-auro-menuoption-container-color: var(--ds-basic-color-surface-accent1-subtle);
-    --ds-auro-menuoption-text-color: var(--ds-basic-color-texticon-default);
-  }
-  #customColorMenu auro-menuoption:hover {
-    --ds-auro-menuoption-container-color: var(--ds-basic-color-surface-accent1-muted);
-  }
-  #customColorMenu auro-menuoption:focus {
-    --ds-auro-menuoption-container-border-color: var(--ds-basic-color-border-brand);
-  }
-
-</style>
-<auro-menu id="customColorMenu">
-  <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>
-```
-<!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>