@aurodesignsystem/auro-formkit 1.6.0-beta.9 → 2.0.0-beta.10

package/components/select/demo/api.md

@@ -14,21 +14,26 @@ The auro-select element is a wrapper for auro-dropdown and auro-menu to create a
 
 ## Properties
 
-| Property                        | Attribute                       | Type      | Default                | Description                                      |
-|---------------------------------|---------------------------------|-----------|------------------------|--------------------------------------------------|
-| [disabled](#disabled)                      | `disabled`                      | `Boolean` |                        | When attribute is present element shows disabled state. |
-| [error](#error)                         | `error`                         | `String`  |                        | When defined, sets persistent validity to `customError` and sets `setCustomValidity` = attribute value. |
-| [flexMenuWidth](#flexMenuWidth)                 | `flexMenuWidth`                 | `Boolean` |                        | If set, makes dropdown bib width match the size of the content, rather than the width of the trigger. |
-| [noCheckmark](#noCheckmark)                   | `noCheckmark`                   | `Boolean` |                        | When true, checkmark on selected option will no longer be present. |
-| [noValidate](#noValidate)                    | `noValidate`                    | `Boolean` |                        | If set, disables auto-validation on blur.        |
-| [optionSelected](#optionSelected)                | `optionSelected`                | `Object`  | "undefined"            | Specifies the current selected menuOption.       |
-| [placeholder](#placeholder)                   | `placeholder`                   | `String`  | "Please select option" | Define placeholder text to display before a value is manually selected. |
-| [required](#required)                      | `required`                      | `Boolean` |                        | Populates the `required` attribute on the element. Used for client-side validation. |
-| [setCustomValidity](#setCustomValidity)             | `setCustomValidity`             | `String`  |                        | Sets a custom help text message to display for all validityStates. |
-| [setCustomValidityCustomError](#setCustomValidityCustomError)  | `setCustomValidityCustomError`  | `String`  |                        | Custom help text message to display when validity = `customError`. |
-| [setCustomValidityValueMissing](#setCustomValidityValueMissing) | `setCustomValidityValueMissing` | `String`  |                        | Custom help text message to display when validity = `valueMissing`. |
-| [validity](#validity)                      | `validity`                      | `String`  | "undefined"            | Specifies the `validityState` this element is in. |
-| [value](#value)                         | `value`                         | `String`  |                        | Value selected for the component.                |
+| Property                        | Attribute                       | Type      | Default     | Description                                      |
+|---------------------------------|---------------------------------|-----------|-------------|--------------------------------------------------|
+| [disabled](#disabled)                      | `disabled`                      | `boolean` |             | When attribute is present, element shows disabled state. |
+| [error](#error)                         | `error`                         | `string`  |             | When defined, sets persistent validity to `customError` and sets `setCustomValidity` = attribute value. |
+| [flexMenuWidth](#flexMenuWidth)                 | `flexMenuWidth`                 | `boolean` |             | If set, makes dropdown width match the size of the content, rather than the width of the trigger. |
+| [noCheckmark](#noCheckmark)                   | `noCheckmark`                   | `boolean` |             | When true, checkmark on selected option will no longer be present. |
+| [noValidate](#noValidate)                    | `noValidate`                    | `boolean` |             | If set, disables auto-validation on blur.        |
+| [optionSelected](#optionSelected)                | `optionSelected`                | `object`  | "undefined" | Specifies the current selected menuOption.       |
+| [required](#required)                      | `required`                      | `boolean` |             | Populates the `required` attribute on the element. Used for client-side validation. |
+| [setCustomValidity](#setCustomValidity)             | `setCustomValidity`             | `string`  |             | Sets a custom help text message to display for all validityStates. |
+| [setCustomValidityCustomError](#setCustomValidityCustomError)  | `setCustomValidityCustomError`  | `string`  |             | Custom help text message to display when validity = `customError`. |
+| [setCustomValidityValueMissing](#setCustomValidityValueMissing) | `setCustomValidityValueMissing` | `string`  |             | Custom help text message to display when validity = `valueMissing`. |
+| [validity](#validity)                      | `validity`                      | `string`  | "undefined" | Specifies the `validityState` this element is in. |
+| [value](#value)                         | `value`                         | `string`  |             | Value selected for the component.                |
+
+## Methods
+
+| Method  | Type       | Description                        |
+|---------|------------|------------------------------------|
+| [reset](#reset) | `(): void` | Resets component to initial state. |
 
 ## Events
 
@@ -39,11 +44,12 @@ The auro-select element is a wrapper for auro-dropdown and auro-menu to create a
 
 ## Slots
 
-| Name       | Description                          |
-|------------|--------------------------------------|
-|            | Default slot for the menu content.   |
-| [helpText](#helpText) | Defines the content of the helpText. |
-| [label](#label)    | Defines the content of the label.    |
+| Name          | Description                                      |
+|---------------|--------------------------------------------------|
+|               | Default slot for the menu content.               |
+| [helpText](#helpText)    | Defines the content of the helpText.             |
+| [label](#label)       | Defines the content of the label.                |
+| [placeholder](#placeholder) | Defines the content of the placeholder to be shown when there is no value |
 
 ## CSS Shadow Parts
 
@@ -56,7 +62,7 @@ The auro-select element is a wrapper for auro-dropdown and auro-menu to create a
 
 ### Default example
 
-A baseline `auro-select` using `auro-menu` and `auro-menuoption` elements. Notice a default `Please select option` placeholder in the trigger.
+A baseline `auro-select` using `auro-menu` and `auro-menuoption` elements.
 
 <div class="exampleWrapper">
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/basic.html) -->
@@ -105,7 +111,6 @@ To pre-set the value of auro-select on load, use the `value` property. The `sele
   <!-- The below content is automatically added from ./../apiExamples/value.html -->
   <auro-button id="validValueExampleBtn">Set Value to Valid Option</auro-button>
   <auro-button id="invalidValueExampleBtn">Set Value to Invalid Option</auro-button>
-  <auro-button id="undefinedValueExampleBtn">Set Value to Undefined</auro-button>
   <br/><br/>
   <auro-select id="valueExample" value="price">
     <span slot="label">Name</span>
@@ -128,7 +133,6 @@ To pre-set the value of auro-select on load, use the `value` property. The `sele
 ```html
 <auro-button id="validValueExampleBtn">Set Value to Valid Option</auro-button>
 <auro-button id="invalidValueExampleBtn">Set Value to Invalid Option</auro-button>
-<auro-button id="undefinedValueExampleBtn">Set Value to Undefined</auro-button>
 <br/><br/>
 <auro-select id="valueExample" value="price">
   <span slot="label">Name</span>
@@ -152,67 +156,26 @@ export function valueExample() {
 
   document.querySelector('#validValueExampleBtn').addEventListener('click', () => {
     valueExample.value = 'arrival';
-  })
+  });
 
   document.querySelector('#invalidValueExampleBtn').addEventListener('click', () => {
     valueExample.value = 'flight course';
-  })
-
-  document.querySelector('#undefinedValueExampleBtn').addEventListener('click', () => {
-    valueExample.value = undefined;
-  })
+  });
 }
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-#### placeholder <a name="placeholder"></a>
-Use the `placeholder` string attribute to inject a custom placeholder option with the select element.
-
-<div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/customPlaceholder.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/customPlaceholder.html -->
-  <auro-select placeholder="Please select your preferred option">
-    <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-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
-    </auro-menu>
-  </auro-select>
-  <!-- AURO-GENERATED-CONTENT:END -->
-</div>
-<auro-accordion alignRight>
-  <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/customPlaceholder.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/customPlaceholder.html -->
-
-```html
-<auro-select placeholder="Please select your preferred option">
-  <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-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
-  </auro-menu>
-</auro-select>
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
-
 #### required <a name="required"></a>
 When present, the `required` attribute specifies that a select field must be filled out before submitting the form.
 
-When the validity check fails the validityState equals `valueMissing`. The error message for the `valueMissing` validityState can be set to a custom string using the `setCustomValidityValueMissing`. There is no default error message defined.
+When the validity check fails the validityState, equals `valueMissing`. The error message for the `valueMissing` validityState can be set to a custom string using the `setCustomValidityValueMissing`. There is no default error message defined.
 
 <div class="exampleWrapper">
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/required.html) -->
   <!-- The below content is automatically added from ./../apiExamples/required.html -->
   <auro-select required setCustomValidityValueMissing="Custom required validation error message.">
+    <label slot="placeholder">Placeholder Text</label>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -231,6 +194,7 @@ When the validity check fails the validityState equals `valueMissing`. The error
 
 ```html
 <auro-select required setCustomValidityValueMissing="Custom required validation error message.">
+  <label slot="placeholder">Placeholder Text</label>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
@@ -245,7 +209,9 @@ When the validity check fails the validityState equals `valueMissing`. The error
 </auro-accordion>
 
 #### error <a name="error"></a>
-Use the `error` boolean attribute to toggle the error UI.
+Use the `error` attribute to apply a persistent custom error that supersedes the HTML5 validation logic.
+
+A custom error message can be set using the `error` attribute, or it can be used in conjuction with the `setCustomValidityCustomError` attribute.
 
 <div class="exampleWrapper">
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/errorApi.html) -->
@@ -254,6 +220,7 @@ Use the `error` boolean attribute to toggle the error UI.
   <auro-button id="undefinedValueExampleBtnRemoveError">Remove Error</auro-button>
   <br /><br />
   <auro-select id="errorExample" error="Custom error message">
+    <label slot="placeholder">Placeholder Text</label>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -275,6 +242,7 @@ Use the `error` boolean attribute to toggle the error UI.
 <auro-button id="undefinedValueExampleBtnRemoveError">Remove Error</auro-button>
 <br /><br />
 <auro-select id="errorExample" error="Custom error message">
+  <label slot="placeholder">Placeholder Text</label>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
@@ -295,6 +263,7 @@ Use the `disabled` boolean attribute to toggle the disabled UI.
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/disabled.html) -->
   <!-- The below content is automatically added from ./../apiExamples/disabled.html -->
   <auro-select disabled>
+    <label slot="placeholder">Placeholder Text</label>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -313,6 +282,7 @@ Use the `disabled` boolean attribute to toggle the disabled UI.
 
 ```html
 <auro-select disabled>
+  <label slot="placeholder">Placeholder Text</label>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
@@ -333,6 +303,7 @@ Use the `flexMenuWidth` boolean attribute to toggle the width of the `<auro-sele
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/flexMenuWidth.html) -->
   <!-- The below content is automatically added from ../apiExamples/flexMenuWidth.html -->
   <auro-select flexMenuWidth id="flexMenuWidthExample">
+    <label slot="placeholder">Placeholder Text</label>
     <auro-menu>
       <auro-menuoption value="united states">United States has a country code of (+1)</auro-menuoption>
       <auro-menuoption value="costa rica">Costa Rica has a country code of (+506)</auro-menuoption>
@@ -355,6 +326,7 @@ Use the `flexMenuWidth` boolean attribute to toggle the width of the `<auro-sele
 
 ```html
 <auro-select flexMenuWidth id="flexMenuWidthExample">
+  <label slot="placeholder">Placeholder Text</label>
   <auro-menu>
     <auro-menuoption value="united states">United States has a country code of (+1)</auro-menuoption>
     <auro-menuoption value="costa rica">Costa Rica has a country code of (+506)</auro-menuoption>
@@ -414,15 +386,15 @@ Use the `label` slot to give your users contextual information about their selec
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-#### label with placeholder
-
-The `label` slot and `placeholder` attribute may be used together.
+#### helpText <a name="helpText"></a>
+Use the `helptext` slot to provide additional information back to your user about their selection option(s).
 
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/labelWithPlaceholder.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/labelWithPlaceholder.html -->
-  <auro-select placeholder="Placeholder Text">
-    <span slot="label">Label Text</span>
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/helpText.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/helpText.html -->
+  <auro-select>
+    <label slot="placeholder">Placeholder Text</label>
+    <span slot="helpText">Custom help text message.</span>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -436,12 +408,13 @@ The `label` slot and `placeholder` attribute may be used together.
 </div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/labelWithPlaceholder.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/labelWithPlaceholder.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/helpText.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/helpText.html -->
 
 ```html
-<auro-select placeholder="Placeholder Text">
-  <span slot="label">Label Text</span>
+<auro-select>
+  <label slot="placeholder">Placeholder Text</label>
+  <span slot="helpText">Custom help text message.</span>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
@@ -455,14 +428,20 @@ The `label` slot and `placeholder` attribute may be used together.
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-#### helpText <a name="helpText"></a>
-Use the `helptext` slot to provide additional information back to your user about their selection option(s).
+## Functional Examples
+
+### Reset State
+
+Use the `reset()` method to reset the `<auro-select>`'s `value` and `validity` state. Doing so will preserve all other attributes and properties.
 
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/helpText.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/helpText.html -->
-  <auro-select>
-    <span slot="helpText">Custom help text message.</span>
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/resetState.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/resetState.html -->
+  <auro-button id="resetStateBtn">Reset</auro-button>
+  <br/><br/>
+  <auro-select id="resetStateExample" required value="price">
+    <label slot="placeholder">Placeholder Text</label>
+    <span slot="label">Name</span>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -473,15 +452,18 @@ Use the `helptext` slot to provide additional information back to your user abou
     </auro-menu>
   </auro-select>
   <!-- AURO-GENERATED-CONTENT:END -->
-</div>
+</div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/helpText.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/helpText.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/resetState.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/resetState.html -->
 
 ```html
-<auro-select>
-  <span slot="helpText">Custom help text message.</span>
+<auro-button id="resetStateBtn">Reset</auro-button>
+<br/><br/>
+<auro-select id="resetStateExample" required value="price">
+  <label slot="placeholder">Placeholder Text</label>
+  <span slot="label">Name</span>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
@@ -493,9 +475,20 @@ Use the `helptext` slot to provide additional information back to your user abou
 </auro-select>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/resetState.js) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/resetState.js -->
 
-## Functional Examples
+```js
+export function resetStateExample() {
+  const elem = document.querySelector('#resetStateExample');
+
+  document.querySelector('#resetStateBtn').addEventListener('click', () => {
+    elem.reset();
+  });
+}
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
 
 ### Extract value
 
@@ -505,6 +498,7 @@ The following example illustrates how a user may query the `element.value` or `e
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/valueExtraction.html) -->
   <!-- The below content is automatically added from ./../apiExamples/valueExtraction.html -->
   <auro-select id="valueExtraction">
+    <label slot="placeholder">Placeholder Text</label>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -519,28 +513,12 @@ The following example illustrates how a user may query the `element.value` or `e
 </div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/valueExtraction.js) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/valueExtraction.js -->
-
-```js
-export function valueExtractionExample() {
-  const valueExtractionExample = document.querySelector('#valueExtraction');
-  const valueExtractionBtn = document.querySelector('#valueExtractionBtn');
-
-  valueExtractionBtn.addEventListener('click', () => {
-    console.warn('Value selected:', valueExtractionExample.value);
-    console.warn('Option selected:', valueExtractionExample.optionSelected);
-
-    alert(`Value selected: ${valueExtractionExample.value}`);
-  })
-}
-```
-<!-- AURO-GENERATED-CONTENT:END -->
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/valueExtraction.html) -->
 <!-- The below code snippet is automatically added from ./../apiExamples/valueExtraction.html -->
 
 ```html
 <auro-select id="valueExtraction">
+  <label slot="placeholder">Placeholder Text</label>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
@@ -553,6 +531,23 @@ export function valueExtractionExample() {
 <auro-button id="valueExtractionBtn">Get current value</auro-button>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/valueExtraction.js) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/valueExtraction.js -->
+
+```js
+export function valueExtractionExample() {
+  const valueExtractionExample = document.querySelector('#valueExtraction');
+  const valueExtractionBtn = document.querySelector('#valueExtractionBtn');
+
+  valueExtractionBtn.addEventListener('click', () => {
+    console.warn('Value selected:', valueExtractionExample.value);
+    console.warn('Option selected:', valueExtractionExample.optionSelected);
+
+    alert(`Value selected: ${valueExtractionExample.value}`);
+  })
+}
+```
+<!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
 ### Custom Validity with Error State
@@ -563,6 +558,7 @@ This example programmatically adds the `error` state when a user selects an opti
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/customErrorValidity.html) -->
   <!-- The below content is automatically added from ./../apiExamples/customErrorValidity.html -->
   <auro-select id="primaryError">
+    <label slot="placeholder">Placeholder Text</label>
     <auro-menu>
       <auro-menuoption value="1">1</auro-menuoption>
       <auro-menuoption value="2">2</auro-menuoption>
@@ -581,6 +577,7 @@ This example programmatically adds the `error` state when a user selects an opti
 
 ```html
 <auro-select id="primaryError">
+  <label slot="placeholder">Placeholder Text</label>
   <auro-menu>
     <auro-menuoption value="1">1</auro-menuoption>
     <auro-menuoption value="2">2</auro-menuoption>
@@ -611,58 +608,7 @@ export function customErrorValidityExample(elem) {
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-### Watch for value changes
-
-The following example listens for the `selectedOption` event. Once triggered, `element.value` or `element.optionSelected` may be queried for the new value or complete option object.
-
-<div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/valueAlert.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/valueAlert.html -->
-  <auro-select id="valueAlert">
-    <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-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
-    </auro-menu>
-  </auro-select>
-  <!-- AURO-GENERATED-CONTENT:END -->
-</div>
-<auro-accordion alignRight>
-  <span slot="trigger">See code</span>
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./alertValue.js) -->
-<!-- The below code snippet is automatically added from ./alertValue.js -->
-
-```js
-export function valueAlert(elem) {
-  elem.addEventListener('selectedOption', () => {
-    console.warn('Select value changed to:', elem.value);
-    console.warn('Select optionSelected changed to:', elem.optionSelected);
-  })
-}
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/valueAlert.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/valueAlert.html -->
-
-```html
-<auro-select id="valueAlert">
-  <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-menuoption value="prefer alaska">Prefer Alaska</auro-menuoption>
-  </auro-menu>
-</auro-select>
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-</auro-accordion>
-
-#### Loading<a name="loading"></a>
+### Loading<a name="loading"></a>
 While content is loading, the menu can either remain empty or display a loading placeholder
 
 <div class="exampleWrapper">
@@ -755,7 +701,7 @@ The component can be in a dialog.
     </auro-dialog>
   </div>
   <!-- AURO-GENERATED-CONTENT:END -->
-</div>
+</div>
 <auro-accordion alignRight>
   <span slot="trigger">See code</span>
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/inDialog.html) -->
@@ -797,6 +743,62 @@ export function inDialogExample() {
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
+#### Watch for value changes
+
+The following example listens for the `auroMenu-selectedOption` event. Once triggered, element.value or element.optionSelected may be queried for the new value or complete option object.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/valueAlert.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/valueAlert.html -->
+  <auro-select id="valueAlert">
+    <label slot="placeholder">Placeholder Text</label>
+    <auro-menu id="valueAlertMenu">
+      <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="prefer alaska">Prefer Alaska</auro-menuoption>
+    </auro-menu>
+  </auro-select>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/valueAlert.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/valueAlert.html -->
+
+```html
+<auro-select id="valueAlert">
+  <label slot="placeholder">Placeholder Text</label>
+  <auro-menu id="valueAlertMenu">
+    <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="prefer alaska">Prefer Alaska</auro-menuoption>
+  </auro-menu>
+</auro-select>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/valueAlert.js) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/valueAlert.js -->
+
+```js
+export function valueAlertExample() {
+  const select = document.querySelector('#valueAlert');
+  const menu = document.querySelector('#valueAlertMenu');
+
+  menu.addEventListener('auroMenu-selectedOption', () => {
+    console.warn('Select value changed to:', select.value);
+    console.warn('Select optionSelected changed to:', select.optionSelected);
+  });
+}
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
 ### Theme Support
 
 The component may be restyled using the following code sample and changing the values of the following token(s).