@aurodesignsystem/auro-formkit 4.0.1 → 5.0.0-rc-1002.1.1

package/components/select/demo/api.md

@@ -20,9 +20,12 @@ The auro-select element is a wrapper for auro-dropdown and auro-menu to create a
 | [autocomplete](#autocomplete)                  | `autocomplete`                  | `string`                          |                | If declared, sets the autocomplete attribute for the select element. |
 | [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. |
+| [fluid](#fluid)                         | `fluid`                         | `boolean`                         |                | When attribute is present, element will be 100% width of container element. |
+| [forceDisplayValue](#forceDisplayValue)             | `forceDisplayValue`             | `boolean`                         | false          | If declared, the label and value will be visually hidden and the displayValue will render 100% of the time. |
 | [fullscreenBreakpoint](#fullscreenBreakpoint)          | `fullscreenBreakpoint`          | `string`                          | "sm"           | Defines the screen size breakpoint (`xs`, `sm`, `md`, `lg`, `xl`, `disabled`)<br />at which the dropdown switches to fullscreen mode on mobile. `disabled` indicates a dropdown should _never_ enter fullscreen.<br /><br />When expanded, the dropdown will automatically display in fullscreen mode<br />if the screen size is equal to or smaller than the selected breakpoint. |
 | [largeFullscreenHeadline](#largeFullscreenHeadline)       | `largeFullscreenHeadline`       | `boolean`                         |                | If declared, make bib.fullscreen.headline in HeadingDisplay.<br />Otherwise, Heading 600. |
+| [layout](#layout)                        |                                 | `string`                          |                |                                                  |
+| [matchWidth](#matchWidth)                    | `matchWidth`                    | `boolean`                         | false          | If declared, the popover and trigger will be set to the same width. |
 | [multiSelect](#multiSelect)                   | `multiselect`                   | `boolean`                         |                | Sets multi-select mode, allowing multiple options to be selected at once. |
 | [name](#name)                          | `name`                          | `string`                          |                | The name for the select element.                 |
 | [noCheckmark](#noCheckmark)                   | `noCheckmark`                   | `boolean`                         |                | When true, checkmark on selected option will no longer be present. |
@@ -31,19 +34,22 @@ The auro-select element is a wrapper for auro-dropdown and auro-menu to create a
 | [offset](#offset)                        | `offset`                        | `number`                          | "0"            | Gap between the trigger element and bib.         |
 | [onDark](#onDark)                        | `onDark`                        | `boolean`                         |                | If declared, onDark styles will be applied to the trigger. |
 | [optionSelected](#optionSelected)                | `optionSelected`                | `HTMLElement\|Array<HTMLElement>` |                | Specifies the current selected menuOption. Default type is `HTMLElement`, changing to `Array<HTMLElement>` when `multiSelect` is true. |
-| [placement](#placement)                     | `placement`                     | `string`                          | "bottom-start" | Position where the bib should appear relative to the trigger.<br />Accepted values:<br />"top" \| "right" \| "bottom" \| "left" \|<br />"bottom-start" \| "top-start" \| "top-end" \|<br />"right-start" \| "right-end" \| "bottom-end" \|<br />"left-start" \| "left-end" |
+| [placeholder](#placeholder)                   | `placeholder`                   | `string`                          |                | Define custom placeholder text.                  |
+| [placement](#placement)                     | `placement`                     | `string`                          | "bottom-start" | Position where the bib should appear relative to the trigger.<br />Accepted values:<br />"top" \| "right" \| "bottom" \| "left" \|<br />"bottom-start" \| "top-start" \| "top-end" \|<br />"right-start" \| "right-end" \| "bottom-end" \|<br />"left-start" \| "left-end". |
 | [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`                          |                | Specifies the `validityState` this element is in. |
-| [value](#value)                         | `value`                         | `String\|Array<String>`           |                | Value selected for the component. Default type is `String`, changing to `Array<String>` when `multiSelect` is true. |
+| [value](#value)                         | `value`                         | `string`                          |                | Value selected for the component.                |
 
 ## Methods
 
 | Method     | Type                                   | Description                                      |
 |------------|----------------------------------------|--------------------------------------------------|
+| [hideBib](#hideBib)  | `(): void`                             | Hides the dropdown bib if its open.              |
 | [reset](#reset)    | `(): void`                             | Resets component to initial state.               |
+| [showBib](#showBib)  | `(): void`                             | Shows the dropdown bib if there are options to show. |
 | [validate](#validate) | `(force?: boolean \| undefined): void` | Validates value.<br /><br />**force**: Whether to force validation. |
 
 ## Events
@@ -52,24 +58,29 @@ The auro-select element is a wrapper for auro-dropdown and auro-menu to create a
 |-----------------------------|--------------------------------------------------|--------------------------------------------------|
 | `auroFormElement-validated` |                                                  | Notifies that the `validity` and `errorMessage` values have changed. |
 | `auroSelect-valueSet`       | `CustomEvent<any>`                               | Notifies that the component has a new value set. |
-| [input](#input)                     | `CustomEvent<{ optionSelected: any; value: any; }>` | Notifies every time the value prop of the element is changed. The updated `value` and `optionSelected` will be delivered in `detail` object. |
+| [input](#input)                     | `CustomEvent<{ optionSelected: any; value: string \| string[]; }>` | Notifies every time the value prop of the element is changed. The updated `value` and `optionSelected` will be delivered in `detail` object. |
 
 ## Slots
 
 | Name                      | Description                                      |
 |---------------------------|--------------------------------------------------|
 |                           | Default slot for the menu content.               |
+| `ariaLabel.bib.close`     | Sets aria-label on close button in fullscreen bib |
 | `bib.fullscreen.headline` | Defines the headline to display above menu-options |
+| [displayValue](#displayValue)            | Allows custom HTML content to display the selected value when select is not focused. |
 | [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 |
+| [optionalLabel](#optionalLabel)           | Allows overriding the optional display text "(optional)", which appears next to the label. |
 | [valueText](#valueText)               | Dropdown value text display.                     |
 
 ## CSS Shadow Parts
 
-| Part       | Description                 |
-|------------|-----------------------------|
-| [helpText](#helpText) | Apply CSS to the help text. |
+| Part              | Description                                      |
+|-------------------|--------------------------------------------------|
+| [dropdownChevron](#dropdownChevron) | Apply CSS to the collapsed/expanded state icon container. |
+| [dropdownSize](#dropdownSize)    | Apply size styles to the dropdown bib. (height, width, maxHeight, maxWidth only) |
+| [dropdownTrigger](#dropdownTrigger) | Apply CSS to the trigger content container.      |
+| [helpText](#helpText)        | Apply CSS to the help text.                      |
 <!-- AURO-GENERATED-CONTENT:END -->
 
 ## API Examples
@@ -82,6 +93,7 @@ A baseline `auro-select` using `auro-menu` and `auro-menuoption` elements.
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/basic.html) -->
   <!-- The below content is automatically added from ./../apiExamples/basic.html -->
   <auro-select>
+    <span slot="ariaLabel.bib.close">Close Popup</span>
     <span slot="bib.fullscreen.headline">Bib Headline</span>
     <span slot="label">Select Example</span>
     <auro-menu>
@@ -119,6 +131,7 @@ A baseline `auro-select` using `auro-menu` and `auro-menuoption` elements.
 
 ```html
 <auro-select>
+  <span slot="ariaLabel.bib.close">Close Popup</span>
   <span slot="bib.fullscreen.headline">Bib Headline</span>
   <span slot="label">Select Example</span>
   <auro-menu>
@@ -402,10 +415,9 @@ When the validity check fails the validityState, equals `valueMissing`. The erro
 <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.">
+  <auro-select required setCustomValidityValueMissing="Custom required validation error message." placeholder="Placeholder Text">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <span slot="label">required field</span>
-    <label slot="placeholder">Placeholder Text</label>
+    <span slot="label">Label</span>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -423,10 +435,53 @@ When the validity check fails the validityState, equals `valueMissing`. The erro
 <!-- The below code snippet is automatically added from ./../apiExamples/required.html -->
 
 ```html
-<auro-select required setCustomValidityValueMissing="Custom required validation error message.">
+<auro-select required setCustomValidityValueMissing="Custom required validation error message." placeholder="Placeholder Text">
   <span slot="bib.fullscreen.headline">Bib Headline</span>
-  <span slot="label">required field</span>
-  <label slot="placeholder">Placeholder Text</label>
+  <span slot="label">Label</span>
+  <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>
+
+### Custom optional label <a name="optionalLabel"></a>
+The `<auro-select>` supports an `optionalLabel` slot, where users can can override the default `(optional)` notification text.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/optionalLabel.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/optionalLabel.html -->
+  <auro-select>
+    <span slot="bib.fullscreen.headline">Bib Headline</span>
+    <span slot="label">Please select a preference</span>
+    <span slot="optionalLabel" style="color: grey; font-size: small"> - optional</span>
+    <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/optionalLabel.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/optionalLabel.html -->
+
+```html
+<auro-select>
+  <span slot="bib.fullscreen.headline">Bib Headline</span>
+  <span slot="label">Please select a preference</span>
+  <span slot="optionalLabel" style="color: grey; font-size: small"> - optional</span>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
@@ -446,10 +501,9 @@ Use the `error` boolean attribute to toggle the error UI.
 <div class="exampleWrapper">
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/error.html) -->
   <!-- The below content is automatically added from ./../apiExamples/error.html -->
-  <auro-select error="Custom error message">
-    <span slot="label">error select example</span>
+  <auro-select error="Custom error message" placeholder="Placeholder Text">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <label slot="placeholder">Placeholder Text</label>
+    <span slot="label">Label</span>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -464,10 +518,9 @@ Use the `error` boolean attribute to toggle the error UI.
 <div class="exampleWrapper--ondark" aria-hidden>
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/onDarkError.html) -->
   <!-- The below content is automatically added from ./../apiExamples/onDarkError.html -->
-  <auro-select onDark error="Custom error message">
-    <span slot="label">error select example</span>
+  <auro-select onDark error="Custom error message" placeholder="Placeholder Text">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <label slot="placeholder">Placeholder Text</label>
+    <span slot="label">Label</span>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -485,10 +538,9 @@ Use the `error` boolean attribute to toggle the error UI.
 <!-- The below code snippet is automatically added from ./../apiExamples/error.html -->
 
 ```html
-<auro-select error="Custom error message">
-  <span slot="label">error select example</span>
+<auro-select error="Custom error message" placeholder="Placeholder Text">
   <span slot="bib.fullscreen.headline">Bib Headline</span>
-  <label slot="placeholder">Placeholder Text</label>
+  <span slot="label">Label</span>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
@@ -502,10 +554,9 @@ Use the `error` boolean attribute to toggle the error UI.
 <!-- AURO-GENERATED-CONTENT:END -->
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/onDarkError.html) -->
 <!-- The below content is automatically added from ./../apiExamples/onDarkError.html -->
-<auro-select onDark error="Custom error message">
-  <span slot="label">error select example</span>
+<auro-select onDark error="Custom error message" placeholder="Placeholder Text">
   <span slot="bib.fullscreen.headline">Bib Headline</span>
-  <label slot="placeholder">Placeholder Text</label>
+  <span slot="label">Label</span>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
@@ -524,10 +575,9 @@ Use the `disabled` boolean attribute to toggle the disabled UI.
 <div class="exampleWrapper">
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/disabled.html) -->
   <!-- The below content is automatically added from ./../apiExamples/disabled.html -->
-  <auro-select disabled>
+  <auro-select disabled placeholder="Placeholder Text">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <label slot="placeholder">Placeholder Text</label>
-    <span slot="label">disabled select example</span>
+    <span slot="label">Label</span>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -542,10 +592,9 @@ Use the `disabled` boolean attribute to toggle the disabled UI.
 <div class="exampleWrapper--ondark" aria-hidden>
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/onDarkDisabled.html) -->
   <!-- The below content is automatically added from ./../apiExamples/onDarkDisabled.html -->
-  <auro-select onDark disabled>
+  <auro-select onDark disabled placeholder="Placeholder Text">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <label slot="placeholder">Placeholder Text</label>
-    <span slot="label">disabled select example</span>
+    <span slot="label">Label</span>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -563,10 +612,9 @@ Use the `disabled` boolean attribute to toggle the disabled UI.
 <!-- The below code snippet is automatically added from ./../apiExamples/disabled.html -->
 
 ```html
-<auro-select disabled>
+<auro-select disabled placeholder="Placeholder Text">
   <span slot="bib.fullscreen.headline">Bib Headline</span>
-  <label slot="placeholder">Placeholder Text</label>
-  <span slot="label">disabled select example</span>
+  <span slot="label">Label</span>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
@@ -580,10 +628,9 @@ Use the `disabled` boolean attribute to toggle the disabled UI.
 <!-- AURO-GENERATED-CONTENT:END -->
 <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/onDarkDisabled.html) -->
 <!-- The below content is automatically added from ./../apiExamples/onDarkDisabled.html -->
-<auro-select onDark disabled>
+<auro-select onDark disabled placeholder="Placeholder Text">
   <span slot="bib.fullscreen.headline">Bib Headline</span>
-  <label slot="placeholder">Placeholder Text</label>
-  <span slot="label">disabled select example</span>
+  <span slot="label">Label</span>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
@@ -640,10 +687,9 @@ Use the `flexMenuWidth` boolean attribute to toggle the width of the `<auro-sele
 <div class="exampleWrapper">
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=../apiExamples/flexMenuWidth.html) -->
   <!-- The below content is automatically added from ../apiExamples/flexMenuWidth.html -->
-  <auro-select flexMenuWidth id="flexMenuWidthExample">
-    <span slot="label">flexMenuWidth select example</span>
+  <auro-select flexMenuWidth id="flexMenuWidthExample" placeholder="Placeholder Text">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <label slot="placeholder">Placeholder Text</label>
+    <span slot="label">Label</span>
     <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>
@@ -665,10 +711,9 @@ Use the `flexMenuWidth` boolean attribute to toggle the width of the `<auro-sele
 <!-- The below code snippet is automatically added from ../apiExamples/flexMenuWidth.html -->
 
 ```html
-<auro-select flexMenuWidth id="flexMenuWidthExample">
-  <span slot="label">flexMenuWidth select example</span>
+<auro-select flexMenuWidth id="flexMenuWidthExample" placeholder="Placeholder Text">
   <span slot="bib.fullscreen.headline">Bib Headline</span>
-  <label slot="placeholder">Placeholder Text</label>
+  <span slot="label">Label</span>
   <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>
@@ -731,16 +776,15 @@ Use the `label` slot to give your users contextual information about their selec
 </auro-accordion>
 
 #### helpText <a name="helpText"></a>
-Use the `helptext` slot to provide additional information back to your user about their selection option(s).
+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/helpText.html) -->
   <!-- The below content is automatically added from ./../apiExamples/helpText.html -->
-  <auro-select>
+  <auro-select placeholder="Placeholder Text">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <label slot="placeholder">Placeholder Text</label>
+    <span slot="label">Label</span>
     <span slot="helpText">Custom help text message.</span>
-    <span slot="label">helpText select example</span>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -758,11 +802,10 @@ Use the `helptext` slot to provide additional information back to your user abou
 <!-- The below code snippet is automatically added from ./../apiExamples/helpText.html -->
 
 ```html
-<auro-select>
+<auro-select placeholder="Placeholder Text">
   <span slot="bib.fullscreen.headline">Bib Headline</span>
-  <label slot="placeholder">Placeholder Text</label>
+  <span slot="label">Label</span>
   <span slot="helpText">Custom help text message.</span>
-  <span slot="label">helpText select example</span>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
@@ -787,9 +830,9 @@ Use the `reset()` method to reset the `<auro-select>`'s `value` and `validity` s
   <!-- The below content is automatically added from ./../apiExamples/resetState.html -->
   <auro-button id="resetStateBtn">Reset</auro-button>
   <br/><br/>
-  <auro-select id="resetStateExample" value="price">
+  <auro-select id="resetStateExample" value="price" placeholder="Placeholder Text">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <label slot="placeholder">Placeholder Text</label>
+    <span slot="label">Label</span>
     <span slot="label">Name</span>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
@@ -810,9 +853,9 @@ Use the `reset()` method to reset the `<auro-select>`'s `value` and `validity` s
 ```html
 <auro-button id="resetStateBtn">Reset</auro-button>
 <br/><br/>
-<auro-select id="resetStateExample" value="price">
+<auro-select id="resetStateExample" value="price" placeholder="Placeholder Text">
   <span slot="bib.fullscreen.headline">Bib Headline</span>
-  <label slot="placeholder">Placeholder Text</label>
+  <span slot="label">Label</span>
   <span slot="label">Name</span>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
@@ -847,10 +890,9 @@ The following example illustrates how a user may query the `element.value` or `e
 <div class="exampleWrapper">
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/valueExtraction.html) -->
   <!-- The below content is automatically added from ./../apiExamples/valueExtraction.html -->
-  <auro-select id="valueExtraction">
+  <auro-select id="valueExtraction" placeholder="Placeholder Text">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <label slot="placeholder">Placeholder Text</label>
-    <span slot="label">Select Example</span>
+    <span slot="label">Label</span>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -869,10 +911,9 @@ The following example illustrates how a user may query the `element.value` or `e
 <!-- The below code snippet is automatically added from ./../apiExamples/valueExtraction.html -->
 
 ```html
-<auro-select id="valueExtraction">
+<auro-select id="valueExtraction" placeholder="Placeholder Text">
   <span slot="bib.fullscreen.headline">Bib Headline</span>
-  <label slot="placeholder">Placeholder Text</label>
-  <span slot="label">Select Example</span>
+  <span slot="label">Label</span>
   <auro-menu>
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>
@@ -911,10 +952,9 @@ This example programmatically adds the `error` state when a user selects an opti
 <div class="exampleWrapper">
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/customErrorValidity.html) -->
   <!-- The below content is automatically added from ./../apiExamples/customErrorValidity.html -->
-  <auro-select id="primaryError">
+  <auro-select id="primaryError" placeholder="Placeholder Text">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <label slot="placeholder">Placeholder Text</label>
-    <span slot="label">Select Example</span>
+    <span slot="label">Label</span>
     <auro-menu>
       <auro-menuoption value="1">1</auro-menuoption>
       <auro-menuoption value="2">2</auro-menuoption>
@@ -932,10 +972,9 @@ This example programmatically adds the `error` state when a user selects an opti
 <!-- The below code snippet is automatically added from ./../apiExamples/customErrorValidity.html -->
 
 ```html
-<auro-select id="primaryError">
+<auro-select id="primaryError" placeholder="Placeholder Text">
   <span slot="bib.fullscreen.headline">Bib Headline</span>
-  <label slot="placeholder">Placeholder Text</label>
-  <span slot="label">Select Example</span>
+  <span slot="label">Label</span>
   <auro-menu>
     <auro-menuoption value="1">1</auro-menuoption>
     <auro-menuoption value="2">2</auro-menuoption>
@@ -1034,57 +1073,56 @@ export function auroMenuLoadingExample() {
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
-### valueText <a name="valueText"></a>
-The label for selected option can be customized using `valueText` slot.
-This slot can be manipulated on the `input` event which delivers the new value and selected `auro-menuoption` element in the `detail` object.
+### displayValue <a name="displayValue"></a>
+The label for selected option can be customized using `displayValue` slot under `<menuoption>.
 
 <div class="exampleWrapper">
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/valueText.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/valueText.html -->
-  <auro-select id="valueTextExample" autocomplete="address-level1">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/displayValue.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/displayValue.html -->
+  <auro-select id="displayValueExample" autocomplete="address-level1">
     <span slot="bib.fullscreen.headline">Select Your Gender</span>
     <span slot="label">Gender</span>
-    <span slot="valueText"></span>
+    <span slot="displayValue"></span>
       <auro-menu>
-        <auro-menuoption value="m" data-display="Male">M - Male</auro-menuoption>
-        <auro-menuoption value="f" data-display="Female">F - Female</auro-menuoption>
-        <auro-menuoption value="x" data-display="Unspecified">X - Unspecified</auro-menuoption>
-        <auro-menuoption value="u" data-display="Undisclosed">U - Undisclosed</auro-menuoption>
+        <auro-menuoption value="m" data-display="Male">M - Male
+          <span slot="displayValue">Male</span>
+        </auro-menuoption>
+        <auro-menuoption value="f" data-display="Female">F - Female
+          <span slot="displayValue">Female</span>
+        </auro-menuoption>
+        <auro-menuoption value="x" data-display="Unspecified">X - Unspecified
+          <span slot="displayValue">Unspecified</span>
+        </auro-menuoption>
+        <auro-menuoption value="u" data-display="Undisclosed">U - Undisclosed
+          <span slot="displayValue">Undisclosed</span>
+        </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/valueText.js) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/valueText.js -->
-
-```js
-export function valueTextExample() {
-  const onValueTextSelectInput = (e) => {
-    const valueText = e.target.querySelector("[slot=valueText]");
-
-    valueText.textContent = e.detail.optionSelected.dataset.display;
-  };
-
-  const select = document.querySelector("#valueTextExample");
-  select.addEventListener('input', onValueTextSelectInput);
-}
-```
-<!-- AURO-GENERATED-CONTENT:END -->
-<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/valueText.html) -->
-<!-- The below code snippet is automatically added from ./../apiExamples/valueText.html -->
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/displayValue.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/displayValue.html -->
 
 ```html
-<auro-select id="valueTextExample" autocomplete="address-level1">
+<auro-select id="displayValueExample" autocomplete="address-level1">
   <span slot="bib.fullscreen.headline">Select Your Gender</span>
   <span slot="label">Gender</span>
-  <span slot="valueText"></span>
+  <span slot="displayValue"></span>
     <auro-menu>
-      <auro-menuoption value="m" data-display="Male">M - Male</auro-menuoption>
-      <auro-menuoption value="f" data-display="Female">F - Female</auro-menuoption>
-      <auro-menuoption value="x" data-display="Unspecified">X - Unspecified</auro-menuoption>
-      <auro-menuoption value="u" data-display="Undisclosed">U - Undisclosed</auro-menuoption>
+      <auro-menuoption value="m" data-display="Male">M - Male
+        <span slot="displayValue">Male</span>
+      </auro-menuoption>
+      <auro-menuoption value="f" data-display="Female">F - Female
+        <span slot="displayValue">Female</span>
+      </auro-menuoption>
+      <auro-menuoption value="x" data-display="Unspecified">X - Unspecified
+        <span slot="displayValue">Unspecified</span>
+      </auro-menuoption>
+      <auro-menuoption value="u" data-display="Undisclosed">U - Undisclosed
+        <span slot="displayValue">Undisclosed</span>
+      </auro-menuoption>
   </auro-menu>
 </auro-select>
 ```
@@ -1105,7 +1143,8 @@ The bib position can be customized with `placement`, `offset`, `flip`, `autoPlac
   <div style="width: 350px">
     <auro-select offset="20" noFlip placement="bottom-end">
       <span slot="bib.fullscreen.headline">Bib Headline</span>
-      <span slot="label">bottom-end bib with 20px offset and noFlip</span>
+      <span slot="label">Label</span>
+      <span slot="helpText">bottom-end bib with 20px offset and noFlip</span>
       <auro-menu>
         <auro-menuoption value="stops">Stops</auro-menuoption>
         <auro-menuoption value="price">Price</auro-menuoption>
@@ -1117,7 +1156,8 @@ The bib position can be customized with `placement`, `offset`, `flip`, `autoPlac
     </auro-select>
     <auro-select offset="20" placement="bottom-end">
       <span slot="bib.fullscreen.headline">Bib Headline</span>
-      <span slot="label">bottom-end bib with 20px offset and flip</span>
+      <span slot="label">Label</span>
+      <span slot="helpText">bottom-end bib with 20px offset and flip</span>
       <auro-menu>
         <auro-menuoption value="stops">Stops</auro-menuoption>
         <auro-menuoption value="price">Price</auro-menuoption>
@@ -1129,7 +1169,8 @@ The bib position can be customized with `placement`, `offset`, `flip`, `autoPlac
     </auro-select>
     <auro-select offset="20" noFlip placement="right" autoPlacement noFlip >
       <span slot="bib.fullscreen.headline">Bib Headline</span>
-      <span slot="label">right bib with 20px offset, noFlip and autoPlacement</span>
+      <span slot="label">Label</span>
+      <span slot="helpText">right bib with 20px offset, noFlip and autoPlacement</span>
       <auro-menu>
         <auro-menuoption value="stops">Stops</auro-menuoption>
         <auro-menuoption value="price">Price</auro-menuoption>
@@ -1151,7 +1192,8 @@ The bib position can be customized with `placement`, `offset`, `flip`, `autoPlac
 <div style="width: 350px">
   <auro-select offset="20" noFlip placement="bottom-end">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <span slot="label">bottom-end bib with 20px offset and noFlip</span>
+    <span slot="label">Label</span>
+    <span slot="helpText">bottom-end bib with 20px offset and noFlip</span>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -1163,7 +1205,8 @@ The bib position can be customized with `placement`, `offset`, `flip`, `autoPlac
   </auro-select>
   <auro-select offset="20" placement="bottom-end">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <span slot="label">bottom-end bib with 20px offset and flip</span>
+    <span slot="label">Label</span>
+    <span slot="helpText">bottom-end bib with 20px offset and flip</span>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -1175,7 +1218,8 @@ The bib position can be customized with `placement`, `offset`, `flip`, `autoPlac
   </auro-select>
   <auro-select offset="20" noFlip placement="right" autoPlacement noFlip >
     <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <span slot="label">right bib with 20px offset, noFlip and autoPlacement</span>
+    <span slot="label">Label</span>
+    <span slot="helpText">right bib with 20px offset, noFlip and autoPlacement</span>
     <auro-menu>
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -1317,10 +1361,9 @@ The following example listens for the `auroMenu-selectedOption` event. Once trig
 <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">
-    <span slot="label">Select Example</span>
+  <auro-select id="valueAlert" placeholder="Placeholder Text">
     <span slot="bib.fullscreen.headline">Bib Headline</span>
-    <label slot="placeholder">Placeholder Text</label>
+    <span slot="label">Label</span>
     <auro-menu id="valueAlertMenu">
       <auro-menuoption value="stops">Stops</auro-menuoption>
       <auro-menuoption value="price">Price</auro-menuoption>
@@ -1338,10 +1381,9 @@ The following example listens for the `auroMenu-selectedOption` event. Once trig
 <!-- The below code snippet is automatically added from ./../apiExamples/valueAlert.html -->
 
 ```html
-<auro-select id="valueAlert">
-  <span slot="label">Select Example</span>
+<auro-select id="valueAlert" placeholder="Placeholder Text">
   <span slot="bib.fullscreen.headline">Bib Headline</span>
-  <label slot="placeholder">Placeholder Text</label>
+  <span slot="label">Label</span>
   <auro-menu id="valueAlertMenu">
     <auro-menuoption value="stops">Stops</auro-menuoption>
     <auro-menuoption value="price">Price</auro-menuoption>