@aurodesignsystem-dev/auro-formkit 0.0.0-pr624.3 → 0.0.0-pr624.31

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

@@ -214,8 +214,8 @@ class AuroRadio extends i$2 {
       },
 
       /**
+       * ID for input node.
        * @private
-       * id for input node
        */
       inputId: {
         type: String,
@@ -472,9 +472,10 @@ class DateFormatter {
     /**
      * Convert a date object to string format.
      * @param {Object} date - Date to convert to string.
-     * @returns {Object} Returns the date as a string.
+     * @param {String} locale - Optional locale to use for the date string. Defaults to user's locale.
+     * @returns {String} Returns the date as a string.
      */
-    this.getDateAsString = (date) => date.toLocaleDateString(undefined, {
+    this.getDateAsString = (date, locale = undefined) => date.toLocaleDateString(locale, {
       year: "numeric",
       month: "2-digit",
       day: "2-digit",
@@ -666,7 +667,7 @@ class AuroDateUtilities extends AuroDateUtilitiesBase {
       const dateObj = new Date(this.getFourDigitYear(dateParts.year), dateParts.month - 1, dateParts.day || 1);
 
       // Get the date string of the date object we created from the string date
-      const actualDateStr = dateFormatter.getDateAsString(dateObj);
+      const actualDateStr = dateFormatter.getDateAsString(dateObj, "en-US");
 
       // Guard Clause: Generated date matches date string input
       if (expectedDateStr !== actualDateStr) {
@@ -1110,7 +1111,9 @@ class AuroFormValidation {
       elem.validity = this.auroInputElements[0].validity;
       elem.errorMessage = this.auroInputElements[0].errorMessage;
 
-      if (elem.validity === 'valid' && this.auroInputElements.length > 1) {
+      // combobox has 2 inputs but no need to check validity on the 2nd one which is in fullscreen bib. 
+      // combobox's 2nd input will have noValidate set true.
+      if (elem.validity === 'valid' && this.auroInputElements.length > 1 && !this.auroInputElements[1].noValidate) {
         elem.validity = this.auroInputElements[1].validity;
         elem.errorMessage = this.auroInputElements[1].errorMessage;
       }
@@ -1230,9 +1233,9 @@ class AuroDependencyVersioning {
   }
 }
 
-var colorCss = i$5`:host([error]){--ds-auro-helptext-color: var(--ds-basic-color-status-error, #e31f26)}:host([onDark]){--ds-auro-helptext-color: var(--ds-basic-color-texticon-inverse-muted, #ccd2db)}:host([onDark][error]){--ds-auro-helptext-color: var(--ds-advanced-color-state-error-inverse, #f9a4a8)}.helptext-wrapper{color:var(--ds-auro-helptext-color)}`;
+var colorCss = i$5`:host([error]){--ds-auro-helptext-color: var(--ds-basic-color-status-error, #e31f26)}:host([onDark]){--ds-auro-helptext-color: var(--ds-basic-color-texticon-inverse-muted, #ccd2db)}:host([onDark][error]){--ds-auro-helptext-color: var(--ds-basic-color-status-error-subtle, #fbc6c6)}.helptext-wrapper{color:var(--ds-auro-helptext-color)}`;
 
-var styleCss = i$5`.helptext-wrapper{display:none;font-size:var(--ds-basic-text-body-xs-font-size, 12px);font-weight:var(--ds-basic-text-body-xs-font-weight, 450);letter-spacing:var(--ds-basic-text-body-xs-letter-spacing, 0);line-height:var(--ds-basic-text-body-xs-line-height, 16px)}:host([large]) .helptext-wrapper{font-size:var(--ds-basic-text-body-default-font-size, 16px);font-weight:var(--ds-basic-text-body-default-font-weight, 450);letter-spacing:var(--ds-basic-text-body-default-letter-spacing, 0);line-height:var(--ds-basic-text-body-default-line-height, 24px)}.helptext-wrapper[visible]{display:block}::slotted(*:not(:empty)){margin-top:var(--ds-size-50, 0.25rem);margin-bottom:0}::slotted(p){margin-block:0}`;
+var styleCss = i$5`.helptext-wrapper{display:none;font-size:12px;font-weight:450;letter-spacing:0;line-height:16px}:host([large]) .helptext-wrapper{font-size:16px;font-weight:450;letter-spacing:0;line-height:24px}.helptext-wrapper[visible]{display:block}::slotted(*:not(:empty)){margin-top:var(--ds-size-50, 0.25rem);margin-bottom:0}::slotted(p){margin-block:0}`;
 
 var tokensCss = i$5`:host{--ds-auro-helptext-color: var(--ds-basic-color-texticon-muted, #676767)}`;
 
@@ -1458,7 +1461,7 @@ var helpTextVersion = '1.0.0';
  * @attr {Object} optionSelected - Specifies the current selected radio button.
  * @csspart radio-group - Apply css to the fieldset element in the shadow DOM
  * @slot {HTMLSlotElement} legend - Allows for the legend to be overridden.
- * @slot {HTMLSlotElement} optionalLabel - Allows for the optional label to be overridden.
+ * @slot {HTMLSlotElement} optionalLabel - Allows overriding the optional display text "(optional)", which appears next to the label.
  * @slot {HTMLSlotElement} helpText - Allows for the helper text to be overridden.
  * @event auroFormElement-validated - Notifies that the element has been validated.
  * @event input - Notifies every time the value prop of the element is changed.
@@ -1614,7 +1617,7 @@ class AuroRadioGroup extends i$2 {
 
     this.optionSelected = event.target;
 
-    this.validation.validate(this);
+    this.validation.validate(this, this.optionSelected !== undefined);
   }
 
   /**
@@ -1881,10 +1884,10 @@ class AuroRadioGroup extends i$2 {
 
     return u`
       <fieldset class="${e(groupClasses)}" part="radio-group">
-        ${this.required
-        ? u`<legend><slot name="legend"></slot></legend>`
-        : u`<legend><slot name="legend"></slot> <slot name="optionalLabel">(optional)</slot></legend>`
-      }
+        <legend>
+          <slot name="legend"></slot>
+          ${this.required ? undefined : u`<slot name="optionalLabel"> (optional)</slot>`}
+        </legend>
         <slot @slotchange=${this.handleSlotChange}></slot>
       </fieldset>
 

package/components/radio/dist/auro-radio-group.d.ts

@@ -10,7 +10,7 @@
  * @attr {Object} optionSelected - Specifies the current selected radio button.
  * @csspart radio-group - Apply css to the fieldset element in the shadow DOM
  * @slot {HTMLSlotElement} legend - Allows for the legend to be overridden.
- * @slot {HTMLSlotElement} optionalLabel - Allows for the optional label to be overridden.
+ * @slot {HTMLSlotElement} optionalLabel - Allows overriding the optional display text "(optional)", which appears next to the label.
  * @slot {HTMLSlotElement} helpText - Allows for the helper text to be overridden.
  * @event auroFormElement-validated - Notifies that the element has been validated.
  * @event input - Notifies every time the value prop of the element is changed.

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

@@ -64,8 +64,8 @@ export class AuroRadio extends LitElement {
             attribute: boolean;
         };
         /**
+         * ID for input node.
          * @private
-         * id for input node
          */
         inputId: {
             type: StringConstructor;

package/components/radio/dist/index.js

@@ -174,8 +174,8 @@ class AuroRadio extends LitElement {
       },
 
       /**
+       * ID for input node.
        * @private
-       * id for input node
        */
       inputId: {
         type: String,
@@ -425,9 +425,10 @@ class DateFormatter {
     /**
      * Convert a date object to string format.
      * @param {Object} date - Date to convert to string.
-     * @returns {Object} Returns the date as a string.
+     * @param {String} locale - Optional locale to use for the date string. Defaults to user's locale.
+     * @returns {String} Returns the date as a string.
      */
-    this.getDateAsString = (date) => date.toLocaleDateString(undefined, {
+    this.getDateAsString = (date, locale = undefined) => date.toLocaleDateString(locale, {
       year: "numeric",
       month: "2-digit",
       day: "2-digit",
@@ -619,7 +620,7 @@ class AuroDateUtilities extends AuroDateUtilitiesBase {
       const dateObj = new Date(this.getFourDigitYear(dateParts.year), dateParts.month - 1, dateParts.day || 1);
 
       // Get the date string of the date object we created from the string date
-      const actualDateStr = dateFormatter.getDateAsString(dateObj);
+      const actualDateStr = dateFormatter.getDateAsString(dateObj, "en-US");
 
       // Guard Clause: Generated date matches date string input
       if (expectedDateStr !== actualDateStr) {
@@ -1063,7 +1064,9 @@ class AuroFormValidation {
       elem.validity = this.auroInputElements[0].validity;
       elem.errorMessage = this.auroInputElements[0].errorMessage;
 
-      if (elem.validity === 'valid' && this.auroInputElements.length > 1) {
+      // combobox has 2 inputs but no need to check validity on the 2nd one which is in fullscreen bib. 
+      // combobox's 2nd input will have noValidate set true.
+      if (elem.validity === 'valid' && this.auroInputElements.length > 1 && !this.auroInputElements[1].noValidate) {
         elem.validity = this.auroInputElements[1].validity;
         elem.errorMessage = this.auroInputElements[1].errorMessage;
       }
@@ -1183,9 +1186,9 @@ class AuroDependencyVersioning {
   }
 }
 
-var colorCss = css`:host([error]){--ds-auro-helptext-color: var(--ds-basic-color-status-error, #e31f26)}:host([onDark]){--ds-auro-helptext-color: var(--ds-basic-color-texticon-inverse-muted, #ccd2db)}:host([onDark][error]){--ds-auro-helptext-color: var(--ds-advanced-color-state-error-inverse, #f9a4a8)}.helptext-wrapper{color:var(--ds-auro-helptext-color)}`;
+var colorCss = css`:host([error]){--ds-auro-helptext-color: var(--ds-basic-color-status-error, #e31f26)}:host([onDark]){--ds-auro-helptext-color: var(--ds-basic-color-texticon-inverse-muted, #ccd2db)}:host([onDark][error]){--ds-auro-helptext-color: var(--ds-basic-color-status-error-subtle, #fbc6c6)}.helptext-wrapper{color:var(--ds-auro-helptext-color)}`;
 
-var styleCss = css`.helptext-wrapper{display:none;font-size:var(--ds-basic-text-body-xs-font-size, 12px);font-weight:var(--ds-basic-text-body-xs-font-weight, 450);letter-spacing:var(--ds-basic-text-body-xs-letter-spacing, 0);line-height:var(--ds-basic-text-body-xs-line-height, 16px)}:host([large]) .helptext-wrapper{font-size:var(--ds-basic-text-body-default-font-size, 16px);font-weight:var(--ds-basic-text-body-default-font-weight, 450);letter-spacing:var(--ds-basic-text-body-default-letter-spacing, 0);line-height:var(--ds-basic-text-body-default-line-height, 24px)}.helptext-wrapper[visible]{display:block}::slotted(*:not(:empty)){margin-top:var(--ds-size-50, 0.25rem);margin-bottom:0}::slotted(p){margin-block:0}`;
+var styleCss = css`.helptext-wrapper{display:none;font-size:12px;font-weight:450;letter-spacing:0;line-height:16px}:host([large]) .helptext-wrapper{font-size:16px;font-weight:450;letter-spacing:0;line-height:24px}.helptext-wrapper[visible]{display:block}::slotted(*:not(:empty)){margin-top:var(--ds-size-50, 0.25rem);margin-bottom:0}::slotted(p){margin-block:0}`;
 
 var tokensCss = css`:host{--ds-auro-helptext-color: var(--ds-basic-color-texticon-muted, #676767)}`;
 
@@ -1411,7 +1414,7 @@ var helpTextVersion = '1.0.0';
  * @attr {Object} optionSelected - Specifies the current selected radio button.
  * @csspart radio-group - Apply css to the fieldset element in the shadow DOM
  * @slot {HTMLSlotElement} legend - Allows for the legend to be overridden.
- * @slot {HTMLSlotElement} optionalLabel - Allows for the optional label to be overridden.
+ * @slot {HTMLSlotElement} optionalLabel - Allows overriding the optional display text "(optional)", which appears next to the label.
  * @slot {HTMLSlotElement} helpText - Allows for the helper text to be overridden.
  * @event auroFormElement-validated - Notifies that the element has been validated.
  * @event input - Notifies every time the value prop of the element is changed.
@@ -1567,7 +1570,7 @@ class AuroRadioGroup extends LitElement {
 
     this.optionSelected = event.target;
 
-    this.validation.validate(this);
+    this.validation.validate(this, this.optionSelected !== undefined);
   }
 
   /**
@@ -1834,10 +1837,10 @@ class AuroRadioGroup extends LitElement {
 
     return html$1`
       <fieldset class="${classMap(groupClasses)}" part="radio-group">
-        ${this.required
-        ? html$1`<legend><slot name="legend"></slot></legend>`
-        : html$1`<legend><slot name="legend"></slot> <slot name="optionalLabel">(optional)</slot></legend>`
-      }
+        <legend>
+          <slot name="legend"></slot>
+          ${this.required ? undefined : html$1`<slot name="optionalLabel"> (optional)</slot>`}
+        </legend>
         <slot @slotchange=${this.handleSlotChange}></slot>
       </fieldset>
 

package/components/radio/dist/registered.js

@@ -174,8 +174,8 @@ class AuroRadio extends LitElement {
       },
 
       /**
+       * ID for input node.
        * @private
-       * id for input node
        */
       inputId: {
         type: String,
@@ -425,9 +425,10 @@ class DateFormatter {
     /**
      * Convert a date object to string format.
      * @param {Object} date - Date to convert to string.
-     * @returns {Object} Returns the date as a string.
+     * @param {String} locale - Optional locale to use for the date string. Defaults to user's locale.
+     * @returns {String} Returns the date as a string.
      */
-    this.getDateAsString = (date) => date.toLocaleDateString(undefined, {
+    this.getDateAsString = (date, locale = undefined) => date.toLocaleDateString(locale, {
       year: "numeric",
       month: "2-digit",
       day: "2-digit",
@@ -619,7 +620,7 @@ class AuroDateUtilities extends AuroDateUtilitiesBase {
       const dateObj = new Date(this.getFourDigitYear(dateParts.year), dateParts.month - 1, dateParts.day || 1);
 
       // Get the date string of the date object we created from the string date
-      const actualDateStr = dateFormatter.getDateAsString(dateObj);
+      const actualDateStr = dateFormatter.getDateAsString(dateObj, "en-US");
 
       // Guard Clause: Generated date matches date string input
       if (expectedDateStr !== actualDateStr) {
@@ -1063,7 +1064,9 @@ class AuroFormValidation {
       elem.validity = this.auroInputElements[0].validity;
       elem.errorMessage = this.auroInputElements[0].errorMessage;
 
-      if (elem.validity === 'valid' && this.auroInputElements.length > 1) {
+      // combobox has 2 inputs but no need to check validity on the 2nd one which is in fullscreen bib. 
+      // combobox's 2nd input will have noValidate set true.
+      if (elem.validity === 'valid' && this.auroInputElements.length > 1 && !this.auroInputElements[1].noValidate) {
         elem.validity = this.auroInputElements[1].validity;
         elem.errorMessage = this.auroInputElements[1].errorMessage;
       }
@@ -1183,9 +1186,9 @@ class AuroDependencyVersioning {
   }
 }
 
-var colorCss = css`:host([error]){--ds-auro-helptext-color: var(--ds-basic-color-status-error, #e31f26)}:host([onDark]){--ds-auro-helptext-color: var(--ds-basic-color-texticon-inverse-muted, #ccd2db)}:host([onDark][error]){--ds-auro-helptext-color: var(--ds-advanced-color-state-error-inverse, #f9a4a8)}.helptext-wrapper{color:var(--ds-auro-helptext-color)}`;
+var colorCss = css`:host([error]){--ds-auro-helptext-color: var(--ds-basic-color-status-error, #e31f26)}:host([onDark]){--ds-auro-helptext-color: var(--ds-basic-color-texticon-inverse-muted, #ccd2db)}:host([onDark][error]){--ds-auro-helptext-color: var(--ds-basic-color-status-error-subtle, #fbc6c6)}.helptext-wrapper{color:var(--ds-auro-helptext-color)}`;
 
-var styleCss = css`.helptext-wrapper{display:none;font-size:var(--ds-basic-text-body-xs-font-size, 12px);font-weight:var(--ds-basic-text-body-xs-font-weight, 450);letter-spacing:var(--ds-basic-text-body-xs-letter-spacing, 0);line-height:var(--ds-basic-text-body-xs-line-height, 16px)}:host([large]) .helptext-wrapper{font-size:var(--ds-basic-text-body-default-font-size, 16px);font-weight:var(--ds-basic-text-body-default-font-weight, 450);letter-spacing:var(--ds-basic-text-body-default-letter-spacing, 0);line-height:var(--ds-basic-text-body-default-line-height, 24px)}.helptext-wrapper[visible]{display:block}::slotted(*:not(:empty)){margin-top:var(--ds-size-50, 0.25rem);margin-bottom:0}::slotted(p){margin-block:0}`;
+var styleCss = css`.helptext-wrapper{display:none;font-size:12px;font-weight:450;letter-spacing:0;line-height:16px}:host([large]) .helptext-wrapper{font-size:16px;font-weight:450;letter-spacing:0;line-height:24px}.helptext-wrapper[visible]{display:block}::slotted(*:not(:empty)){margin-top:var(--ds-size-50, 0.25rem);margin-bottom:0}::slotted(p){margin-block:0}`;
 
 var tokensCss = css`:host{--ds-auro-helptext-color: var(--ds-basic-color-texticon-muted, #676767)}`;
 
@@ -1411,7 +1414,7 @@ var helpTextVersion = '1.0.0';
  * @attr {Object} optionSelected - Specifies the current selected radio button.
  * @csspart radio-group - Apply css to the fieldset element in the shadow DOM
  * @slot {HTMLSlotElement} legend - Allows for the legend to be overridden.
- * @slot {HTMLSlotElement} optionalLabel - Allows for the optional label to be overridden.
+ * @slot {HTMLSlotElement} optionalLabel - Allows overriding the optional display text "(optional)", which appears next to the label.
  * @slot {HTMLSlotElement} helpText - Allows for the helper text to be overridden.
  * @event auroFormElement-validated - Notifies that the element has been validated.
  * @event input - Notifies every time the value prop of the element is changed.
@@ -1567,7 +1570,7 @@ class AuroRadioGroup extends LitElement {
 
     this.optionSelected = event.target;
 
-    this.validation.validate(this);
+    this.validation.validate(this, this.optionSelected !== undefined);
   }
 
   /**
@@ -1834,10 +1837,10 @@ class AuroRadioGroup extends LitElement {
 
     return html$1`
       <fieldset class="${classMap(groupClasses)}" part="radio-group">
-        ${this.required
-        ? html$1`<legend><slot name="legend"></slot></legend>`
-        : html$1`<legend><slot name="legend"></slot> <slot name="optionalLabel">(optional)</slot></legend>`
-      }
+        <legend>
+          <slot name="legend"></slot>
+          ${this.required ? undefined : html$1`<slot name="optionalLabel"> (optional)</slot>`}
+        </legend>
         <slot @slotchange=${this.handleSlotChange}></slot>
       </fieldset>
 

package/components/select/demo/api.js

@@ -5,6 +5,7 @@ import { valueAlertExample } from "../apiExamples/valueAlert.js";
 import { inDialogExample } from '../apiExamples/inDialog';
 import { resetStateExample } from "../apiExamples/resetState";
 import { auroMenuLoadingExample } from "../apiExamples/loading";
+import { valueTextExample } from '../apiExamples/valueText.js';
 
 /* eslint-disable jsdoc/require-jsdoc, no-magic-numbers, no-param-reassign */
 import { AuroSelect } from '../src/auro-select.js';
@@ -24,6 +25,7 @@ export function initExamples(initCount) {
     inDialogExample();
     resetStateExample();
     auroMenuLoadingExample();
+    valueTextExample();
   } catch (err) {
     if (initCount <= 20) {
       // setTimeout handles issue where content is sometimes loaded after the functions get called

package/components/select/demo/api.md

@@ -20,9 +20,11 @@ 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. |
+| [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`                          | "snowflake"    |                                                  |
+| [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,28 +33,33 @@ 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" |
+| [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`. |
+| [shape](#shape)                         |                                 | `string`                          | "snowflake"    |                                                  |
+| [size](#size)                          |                                 | `string`                          | "xl"           |                                                  |
 | [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. |
 
 ## Methods
 
-| Method     | Type                                   | Description                                      |
-|------------|----------------------------------------|--------------------------------------------------|
-| [reset](#reset)    | `(): void`                             | Resets component to initial state.               |
-| [validate](#validate) | `(force?: boolean \| undefined): void` | Validates value.<br /><br />**force**: Whether to force validation. |
+| Method               | Type                                   | Description                                      |
+|----------------------|----------------------------------------|--------------------------------------------------|
+| [renderAriaHtml](#renderAriaHtml)     | `(): TemplateResult`                   |                                                  |
+| [renderBACKUP](#renderBACKUP)       | `(): TemplateResult`                   |                                                  |
+| [renderNativeSelect](#renderNativeSelect) | `(): TemplateResult`                   |                                                  |
+| [reset](#reset)              | `(): void`                             | Resets component to initial state.               |
+| [validate](#validate)           | `(force?: boolean \| undefined): void` | Validates value.<br /><br />**force**: Whether to force validation. |
 
 ## Events
 
-| Event                       | Type               | Description                                      |
-|-----------------------------|--------------------|--------------------------------------------------|
-| `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<any>` | Notifies every time the value prop of the element is changed. |
+| Event                       | Type                                             | Description                                      |
+|-----------------------------|--------------------------------------------------|--------------------------------------------------|
+| `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. |
 
 ## Slots
 
@@ -60,9 +67,12 @@ The auro-select element is a wrapper for auro-dropdown and auro-menu to create a
 |---------------------------|--------------------------------------------------|
 |                           | Default slot for the menu content.               |
 | `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. |
+| [placeholder](#placeholder)             | Defines the content of the placeholder to be shown when there is no value |
+| [valueText](#valueText)               | Dropdown value text display.                     |
 
 ## CSS Shadow Parts
 
@@ -439,6 +449,50 @@ When the validity check fails the validityState, equals `valueMissing`. The erro
 <!-- 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>
+    <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>
+
 #### error <a name="error"></a>
 Use the `error` boolean attribute to toggle the error UI.
 
@@ -730,7 +784,7 @@ 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) -->
@@ -1033,6 +1087,63 @@ 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.
+
+<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">
+    <span slot="bib.fullscreen.headline">Select Your Gender</span>
+    <span slot="label">Gender</span>
+    <span slot="valueText"></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-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 -->
+
+```html
+<auro-select id="valueTextExample" autocomplete="address-level1">
+  <span slot="bib.fullscreen.headline">Select Your Gender</span>
+  <span slot="label">Gender</span>
+  <span slot="valueText"></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-menu>
+</auro-select>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
 ### Customized bib position
 The bib position can be customized with `placement`, `offset`, `flip`, `autoPlacement` attributes.