@aurodesignsystem/auro-formkit 5.1.2 → 5.1.4

package/components/combobox/demo/api.md

@@ -5,54 +5,64 @@
 
 ## Properties
 
-| Property                        | Attribute                       | Type          | Default        | Description                                      |
-|---------------------------------|---------------------------------|---------------|----------------|--------------------------------------------------|
-| [autoPlacement](#autoPlacement)                 | `autoPlacement`                 | `boolean`     |                | If declared, bib's position will be automatically calculated where to appear. |
-| [autocomplete](#autocomplete)                  | `autocomplete`                  | `string`      | "false"        | An enumerated attribute that defines what the user agent can suggest for autofill. At this time, only `autocomplete="off"` is supported. |
-| [checkmark](#checkmark)                     | `checkmark`                     | `boolean`     |                | When attribute is present auro-menu will apply checkmarks to selected options. |
-| [disabled](#disabled)                      | `disabled`                      | `boolean`     |                | If set, disables the combobox.                   |
-| [error](#error)                         | `error`                         | `string`      |                | When defined, sets persistent validity to `customError` and sets the validation message to the attribute value. |
-| [format](#format)                        | `format`                        | `string`      |                | Specifies the input mask format.                 |
-| [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. |
-| [inputmode](#inputmode)                     | `inputmode`                     | `string`      |                | Exposes inputmode attribute for input.           |
-| [largeFullscreenHeadline](#largeFullscreenHeadline)       | `largeFullscreenHeadline`       | `boolean`     |                | If declared, make bib.fullscreen.headline in HeadingDisplay.<br />Otherwise, Heading 600 |
-| [layout](#layout)                        |                                 | `string`      |                |                                                  |
-| [matchWidth](#matchWidth)                    | `matchWidth`                    | `boolean`     | true           | If declared, the popover and trigger will be set to the same width. |
-| [noFilter](#noFilter)                      | `noFilter`                      | `boolean`     |                | If set, combobox will not filter menuoptions based in input. |
-| [noFlip](#noFlip)                        | `noFlip`                        | `boolean`     | "false"        | If declared, the bib will NOT flip to an alternate position<br />when there isn't enough space in the specified `placement`. |
-| [noValidate](#noValidate)                    | `noValidate`                    | `boolean`     |                | If set, disables auto-validation on blur.        |
-| [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` |                | Specifies the current selected option.           |
-| [placeholder](#placeholder)                   | `placeholder`                   | `string`      |                | Define custom placeholder text, only supported by date input formats. |
-| [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 input. 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`. |
-| [triggerIcon](#triggerIcon)                   | `triggerIcon`                   | `boolean`     |                | If set, the `icon` attribute will be applied to the trigger `auro-input` element. |
-| [type](#type)                          | `type`                          | `string`      |                | Applies the defined value as the type attribute on auro-input. |
-| [validity](#validity)                      | `validity`                      | `string`      |                | Specifies the `validityState` this element is in. |
-| [value](#value)                         | `value`                         | `string`      |                | Value selected for the dropdown menu.            |
+| Property                        | Attribute                       | Modifiers | Type                  | Default                    | Description                                      |
+|---------------------------------|---------------------------------|-----------|-----------------------|----------------------------|--------------------------------------------------|
+| [autoPlacement](#autoPlacement)                 | `autoPlacement`                 |           | `boolean`             | false                      | If declared, bib's position will be automatically calculated where to appear. |
+| [autocomplete](#autocomplete)                  | `autocomplete`                  |           | `string`              | "false"                    | An enumerated attribute that defines what the user agent can suggest for autofill. At this time, only `autocomplete="off"` is supported. |
+| [checkmark](#checkmark)                     | `checkmark`                     |           | `boolean`             | false                      | When attribute is present auro-menu will apply check marks to selected options. |
+| [disabled](#disabled)                      | `disabled`                      |           | `boolean`             | false                      | If set, disables the combobox.                   |
+| [dvInputOnly](#dvInputOnly)                   | `dvInputOnly`                   |           | `boolean`             | false                      | If defined, the display value slot content will only mask the HTML5 input element. The inputs label will not be masked. |
+| [error](#error)                         | `error`                         |           | `string`              |                            | When defined, sets persistent validity to `customError` and sets the validation message to the attribute value. |
+| [format](#format)                        | `format`                        |           | `string`              |                            | Specifies the input mask format.                 |
+| [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. |
+| [inputValue](#inputValue)                    |                                 | readonly  | `string \| undefined` |                            | Returns the current value of the input element within the combobox. |
+| [inputmode](#inputmode)                     | `inputmode`                     |           | `string`              |                            | Exposes inputmode attribute for input.           |
+| [largeFullscreenHeadline](#largeFullscreenHeadline)       | `largeFullscreenHeadline`       |           | `boolean`             |                            | If declared, make bib.fullscreen.headline in HeadingDisplay.<br />Otherwise, Heading 600 |
+| [layout](#layout)                        |                                 |           | `string`              | "classic"                  |                                                  |
+| [matchWidth](#matchWidth)                    | `matchWidth`                    |           | `boolean`             | true                       | If declared, the popover and trigger will be set to the same width. |
+| [msgSelectionMissing](#msgSelectionMissing)           |                                 |           | `string`              | "Please select an option." |                                                  |
+| [noFilter](#noFilter)                      | `noFilter`                      |           | `boolean`             | false                      | If set, combobox will not filter menuoptions based in input. |
+| [noFlip](#noFlip)                        | `noFlip`                        |           | `boolean`             | "false"                    | If declared, the bib will NOT flip to an alternate position<br />when there isn't enough space in the specified `placement`. |
+| [noValidate](#noValidate)                    | `noValidate`                    |           | `boolean`             | false                      | If set, disables auto-validation on blur.        |
+| [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`         |                            | Specifies the current selected option.           |
+| [persistInput](#persistInput)                  | `persistInput`                  |           | `Boolean`             | false                      | If declared, selecting a menu option will not change the input value. By doing so,<br />the current menu filter will be preserved and the user can continue from their last<br />filter state. It is recommended to use this in combination with the `displayValue` slot. |
+| [placeholder](#placeholder)                   | `placeholder`                   |           | `string`              |                            | Define custom placeholder text, only supported by date input formats. |
+| [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`             | false                      | Populates the `required` attribute on the input. 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`              | "classic"                  |                                                  |
+| [size](#size)                          |                                 |           | `string`              | "xl"                       |                                                  |
+| [triggerIcon](#triggerIcon)                   | `triggerIcon`                   |           | `boolean`             | false                      | If set, the `icon` attribute will be applied to the trigger `auro-input` element. |
+| [type](#type)                          | `type`                          |           | `string`              |                            | Applies the defined value as the type attribute on auro-input. |
+| [typedValue](#typedValue)                    | `typedValue`                    |           | `string`              | "undefined"                | Specifies the value of the input element within the combobox. |
+| [validity](#validity)                      | `validity`                      |           | `string`              |                            | Specifies the `validityState` this element is in. |
+| [value](#value)                         | `value`                         |           | `string`              | "undefined"                | Value selected for the dropdown menu.            |
 
 ## Methods
 
-| Method     | Type                                   | Description                                      |
-|------------|----------------------------------------|--------------------------------------------------|
-| [clear](#clear)    | `(): void`                             | Clears the current value of the combobox.        |
-| [focus](#focus)    | `(): void`                             | Focuses the combobox trigger input.              |
-| [hideBib](#hideBib)  | `(): void`                             | Hides the dropdown bib if its open.              |
-| [isValid](#isValid)  | `(): boolean`                          | Checks if the element is valid.                  |
-| [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. |
+| Method               | Type                                   | Description                                      |
+|----------------------|----------------------------------------|--------------------------------------------------|
+| [clear](#clear)              | `(): void`                             | Clears the current value of the combobox.        |
+| [focus](#focus)              | `(): void`                             | Focuses the combobox trigger input.              |
+| [hideBib](#hideBib)            | `(): void`                             | Hides the dropdown bib if its open.              |
+| [isValid](#isValid)            | `(): boolean`                          | Checks if the element is valid.                  |
+| [reset](#reset)              | `(): void`                             | Resets component to initial state.               |
+| [showBib](#showBib)            | `(): void`                             | Shows the dropdown bib if there are options to show. |
+| [updateActiveOption](#updateActiveOption) | `(index: number): void`                | Updates the active option in the menu.<br /><br />**index**: Index of the option to make active. |
+| [validate](#validate)           | `(force?: boolean \| undefined): void` | Validates value.<br /><br />**force**: Whether to force validation. |
 
 ## Events
 
-| Event                       | Type               | Description                                      |
-|-----------------------------|--------------------|--------------------------------------------------|
-| `auroCombobox-valueSet`     | `CustomEvent<any>` | Notifies that the component has a new value set. |
-| `auroFormElement-validated` |                    | Notifies that the component value(s) have been validated. |
+| Event                       | Type                                           | Description                                      |
+|-----------------------------|------------------------------------------------|--------------------------------------------------|
+| `auroCombobox-valueSet`     | `CustomEvent<any>`                             | (Deprecated) Notifies that the component has a new value set. |
+| `auroFormElement-validated` |                                                | Notifies that the component value(s) have been validated. |
+| [input](#input)                     | `CustomEvent<any>`                             | Notifies that the component has a new value set. |
+| [inputValue](#inputValue)                | `CustomEvent<{ value: string \| undefined; }>` | Notifies that the components internal HTML5 input value has changed. |
 
 ## Slots
 
@@ -153,20 +163,52 @@ This example demonstrates a data driven combobox. The data is used to populate t
 
 The menu in this example was populated from data from a country/city API. To keep the data set small, the data in the menu is based off an API call that returns all countries and cities that contain the substring "**germ**" (non case-sensitive) in their name.
 
-<div class="exampleWrapper">
+<div class="exampleWrapper--ondark">
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/dynamicMenu.html) -->
   <!-- The below content is automatically added from ./../apiExamples/dynamicMenu.html -->
   <!-- HTML example file -->
   <!-- ----------------- -->
-  <auro-combobox id="dynamicMenuExample" noFilter>
+  <auro-combobox
+    id="dynamicMenuExample"
+    value="TAN"
+    layout="snowflake"
+    shape="snowflake"
+    size="lg"
+    ondark
+    noFilter
+    persistInput
+    dvInputOnly
+    required>
     <span slot="bib.fullscreen.headline">Dynamic Combobox Header</span>
-    <span slot="label">Name</span>
+    <span slot="label">First</span>
     <!--
       The auro-combobox element requires an empty auro-menu element
       due to the requirements of auro-dropdown and auro-input
     -->
     <auro-menu id="initMenu"></auro-menu>
-  </auro-combobox>
+  </auro-combobox>
+  <auro-combobox
+    id="dynamicMenuExampleTwo"
+    value="GER"
+    layout="snowflake"
+    shape="snowflake"
+    size="lg"
+    ondark
+    noFilter
+    persistInput
+    dvInputOnly
+    required>
+    <span slot="bib.fullscreen.headline">Dynamic Combobox Header</span>
+    <span slot="label">Second</span>
+    <!--
+      The auro-combobox element requires an empty auro-menu element
+      due to the requirements of auro-dropdown and auro-input
+    -->
+    <auro-menu id="initMenuTwo"></auro-menu>
+  </auro-combobox>
+  <auro-button id="dynamicMenuSwapButton">
+    Swap Values
+  </auro-button>
   <!-- AURO-GENERATED-CONTENT:END -->
 </div>
 <auro-accordion alignRight>
@@ -177,15 +219,47 @@ The menu in this example was populated from data from a country/city API. To kee
 ```html
 <!-- HTML example file -->
 <!-- ----------------- -->
-<auro-combobox id="dynamicMenuExample" noFilter>
+<auro-combobox
+  id="dynamicMenuExample"
+  value="TAN"
+  layout="snowflake"
+  shape="snowflake"
+  size="lg"
+  ondark
+  noFilter
+  persistInput
+  dvInputOnly
+  required>
   <span slot="bib.fullscreen.headline">Dynamic Combobox Header</span>
-  <span slot="label">Name</span>
+  <span slot="label">First</span>
   <!--
     The auro-combobox element requires an empty auro-menu element
     due to the requirements of auro-dropdown and auro-input
   -->
   <auro-menu id="initMenu"></auro-menu>
 </auro-combobox>
+<auro-combobox
+  id="dynamicMenuExampleTwo"
+  value="GER"
+  layout="snowflake"
+  shape="snowflake"
+  size="lg"
+  ondark
+  noFilter
+  persistInput
+  dvInputOnly
+  required>
+  <span slot="bib.fullscreen.headline">Dynamic Combobox Header</span>
+  <span slot="label">Second</span>
+  <!--
+    The auro-combobox element requires an empty auro-menu element
+    due to the requirements of auro-dropdown and auro-input
+  -->
+  <auro-menu id="initMenuTwo"></auro-menu>
+</auro-combobox>
+<auro-button id="dynamicMenuSwapButton">
+  Swap Values
+</auro-button>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
 <!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/dynamicMenu.js) -->
@@ -196,7 +270,7 @@ The menu in this example was populated from data from a country/city API. To kee
 // -----------------------
 import { DynamicData } from './dynamicMenuDataApi';
 
-export function dynamicMenuExample() {
+export async function dynamicMenuExample() {
   // Resets the root menu
   function resetMenu(root) {
     while (root.firstChild) {
@@ -204,22 +278,48 @@ export function dynamicMenuExample() {
     }
   }
 
+  function swapValues() {
+    const elOne = document.querySelector('#dynamicMenuExample');
+    const elTwo = document.querySelector('#dynamicMenuExampleTwo');
+
+    const elOneValue = elOne.value;
+    const elTwoValue = elTwo.value;
+
+    const elOneInputValue = elOne.input.value;
+    const elTwoInputValue = elTwo.input.value;
+
+    elOne.reset();
+    elTwo.reset();
+
+    elOne.value = elTwoValue;
+    elTwo.value = elOneValue;
+
+    setTimeout(() => {
+      elOne.typedValue = elTwoInputValue;
+      elTwo.typedValue = elOneInputValue;
+    }, 0);
+  }
+
+  document.querySelector('#dynamicMenuSwapButton').addEventListener('click', () => {
+    swapValues();
+  });
+
   // Generates HTML for menu and submenus using country & city data from an external API
-  function generateHtml(data) {
-    const initialMenu = document.querySelector('#initMenu');
+  function generateHtml(data, selector) {
+    const initialMenu = document.querySelector(selector);
 
     resetMenu(initialMenu);
 
     for (let index = 0; index < data.length; index++) {
-      let country = data[index]['country'];
-      let cities = data[index]['cities'];
+      const country = data[index]['country'];
+      const cities = data[index]['cities'];
 
-      generateMenuOptionHtml(initialMenu, country, country);
+      generateMenuOptionHtml(initialMenu, country, country.substring(0, 3).toUpperCase());
 
       for (let indexB = 0; indexB < cities.length; indexB++) {
-        let subMenu = document.createElement('auro-menu');
+        const subMenu = document.createElement('auro-menu');
 
-        generateMenuOptionHtml(subMenu, cities[indexB], cities[indexB]);
+        generateMenuOptionHtml(subMenu, cities[indexB], cities[indexB].substring(0, 3).toUpperCase());
 
         initialMenu.appendChild(subMenu);
       }
@@ -228,26 +328,54 @@ export function dynamicMenuExample() {
 
   // Helper function that generates HTML for menuoptions
   function generateMenuOptionHtml(menu, label, value) {
-    let option = document.createElement('auro-menuoption');
+    const option = document.createElement('auro-menuoption');
+    const displayValue = document.createElement('div');
+    displayValue.setAttribute("slot", "displayValue");
+    displayValue.innerHTML = value;
 
     option.value = value;
     option.innerHTML = label;
-
     menu.appendChild(option);
+    option.appendChild(displayValue);
   }
 
   // Main javascript that runs all JS to create example
   const dynamicData = new DynamicData();
-  const dynamicMenuExample = document.querySelector('#dynamicMenuExample');
-  const dropdownEl = dynamicMenuExample.shadowRoot.querySelector(dynamicMenuExample.dropdownTag._$litStatic$);
-  const inputEl = dropdownEl.querySelector(dynamicMenuExample.inputTag._$litStatic$);
+  const dynamicMenuExampleEl = document.querySelector('#dynamicMenuExample');
+  const dropdownEl = dynamicMenuExampleEl.shadowRoot.querySelector(dynamicMenuExampleEl.dropdownTag._$litStatic$);
+  const inputEl = dropdownEl.querySelector(dynamicMenuExampleEl.inputTag._$litStatic$);
 
   inputEl.addEventListener('input', () => {
     let data = dynamicData.getData();
     data = dynamicData.filterData(data, inputEl.value);
 
-    generateHtml(data);
+    generateHtml(data, '#initMenu');
+  });
+
+  if (dynamicMenuExampleEl.value && dynamicMenuExampleEl.value.length > 0 && dynamicMenuExampleEl.input.value && (!dynamicMenuExampleEl.menu.availableOptions || dynamicMenuExampleEl.menu.availableOptions.length === 0)) {
+    let data = dynamicData.getData();
+    data = dynamicData.filterData(data, inputEl.value);
+    generateHtml(data, '#initMenu');
+  }
+
+  // TODO: Need to refactor this to to not console a console error
+  const dynamicDataTwo = new DynamicData();
+  const dynamicMenuExampleElTwo = document.querySelector('#dynamicMenuExample');
+  const dropdownElTwo = dynamicMenuExampleElTwo.shadowRoot.querySelector(dynamicMenuExampleElTwo.dropdownTag._$litStatic$);
+  const inputElTwo = dropdownElTwo.querySelector(dynamicMenuExampleElTwo.inputTag._$litStatic$);
+
+  inputElTwo.addEventListener('input', () => {
+    let data = dynamicDataTwo.getData();
+    data = dynamicDataTwo.filterData(data, inputEl.value);
+
+    generateHtml(data, '#initMenuTwo');
   });
+
+  if (dynamicMenuExampleElTwo.value && dynamicMenuExampleElTwo.value.length > 0 && dynamicMenuExampleElTwo.input.value && (!dynamicMenuExampleElTwo.menu.availableOptions || dynamicMenuExampleElTwo.menu.availableOptions.length === 0)) {
+    let data = dynamicDataTwo.getData();
+    data = dynamicDataTwo.filterData(data, inputElTwo.value);
+    generateHtml(data, '#initMenuTwo');
+  }
 }
 ```
 <!-- AURO-GENERATED-CONTENT:END -->