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

package/components/combobox/demo/api.md

@@ -12,15 +12,19 @@
 | [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. |
@@ -35,8 +39,12 @@
 
 | 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. |
 
 ## Events
@@ -51,9 +59,13 @@
 | Name                      | Description                                      |
 |---------------------------|--------------------------------------------------|
 |                           | Default slot for the menu content.               |
+| `ariaLabel.bib.close`     | Sets aria-label on close button in fullscreen bib |
+| `ariaLabel.input.clear`   | Sets aria-label on clear button                  |
 | `bib.fullscreen.headline` | Defines the headline to display above menu-options |
+| [displayValue](#displayValue)            | Allows custom HTML content to display the selected value when the combobox is not focused. Only works with `snowflake` and `emphasized` layouts. |
 | [helpText](#helpText)                | Defines the content of the helpText.             |
-| [label](#label)                   | Defines the content of the label.                |
+| [label](#label)                   | Defines the content of the label.                |
+| [optionalLabel](#optionalLabel)           | Allows overriding the optional display text "(optional)", which appears next to the label. |
 <!-- AURO-GENERATED-CONTENT:END -->
 
 ## API Examples
@@ -64,6 +76,8 @@
   <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/basic.html) -->
   <!-- The below content is automatically added from ./../apiExamples/basic.html -->
   <auro-combobox>
+    <span slot="ariaLabel.bib.close">Close combobox</span>
+    <span slot="ariaLabel.input.clear">Clear All</span>
     <span slot="bib.fullscreen.headline">Bib Header</span>
     <span slot="label">Name</span>
     <auro-menu>
@@ -101,6 +115,8 @@
 
 ```html
 <auro-combobox>
+  <span slot="ariaLabel.bib.close">Close combobox</span>
+  <span slot="ariaLabel.input.clear">Clear All</span>
   <span slot="bib.fullscreen.headline">Bib Header</span>
   <span slot="label">Name</span>
   <auro-menu>
@@ -573,6 +589,50 @@ Populates the `required` attribute on the input. Used for client-side validation
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
+### Custom optional label <a name="optionalLabel"></a>
+The `<auro-combobox>` 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-combobox>
+    <span slot="bib.fullscreen.headline">Bib Header</span>
+    <span slot="label">Name</span>
+    <span slot="optionalLabel" style="font-size: small; color: grey"> - optional</span>
+    <auro-menu>
+      <auro-menuoption value="Apples" id="option-0">Apples</auro-menuoption>
+      <auro-menuoption value="Oranges" id="option-1">Oranges</auro-menuoption>
+      <auro-menuoption value="Peaches" id="option-2">Peaches</auro-menuoption>
+      <auro-menuoption value="Grapes" id="option-3">Grapes</auro-menuoption>
+      <auro-menuoption value="Cherries" id="option-4">Cherries</auro-menuoption>
+      <auro-menuoption static nomatch>No matching option</auro-menuoption>
+    </auro-menu>
+  </auro-combobox>
+  <!-- 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-combobox>
+  <span slot="bib.fullscreen.headline">Bib Header</span>
+  <span slot="label">Name</span>
+  <span slot="optionalLabel" style="font-size: small; color: grey"> - optional</span>
+  <auro-menu>
+    <auro-menuoption value="Apples" id="option-0">Apples</auro-menuoption>
+    <auro-menuoption value="Oranges" id="option-1">Oranges</auro-menuoption>
+    <auro-menuoption value="Peaches" id="option-2">Peaches</auro-menuoption>
+    <auro-menuoption value="Grapes" id="option-3">Grapes</auro-menuoption>
+    <auro-menuoption value="Cherries" id="option-4">Cherries</auro-menuoption>
+    <auro-menuoption static nomatch>No matching option</auro-menuoption>
+  </auro-menu>
+</auro-combobox>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
 #### value
 
 Use the `value` attribute to programmatically set the value of the combobox.
@@ -1003,7 +1063,8 @@ The bib position can be customized with `placement`, `offset`, `flip`, `autoPlac
   <div style="width: 350px">
     <auro-combobox offset="20" noFlip placement="bottom-end">
       <span slot="bib.fullscreen.headline">Bib Header</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="Apples" id="option-0">Apples</auro-menuoption>
         <auro-menuoption value="Oranges" id="option-1">Oranges</auro-menuoption>
@@ -1015,7 +1076,8 @@ The bib position can be customized with `placement`, `offset`, `flip`, `autoPlac
     </auro-combobox>
     <auro-combobox offset="20" placement="bottom-end">
       <span slot="bib.fullscreen.headline">Bib Header</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="Apples" id="option-0">Apples</auro-menuoption>
         <auro-menuoption value="Oranges" id="option-1">Oranges</auro-menuoption>
@@ -1027,7 +1089,8 @@ The bib position can be customized with `placement`, `offset`, `flip`, `autoPlac
     </auro-combobox>
     <auro-combobox offset="20" noFlip placement="right" autoPlacement>
       <span slot="bib.fullscreen.headline">Bib Header</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="Apples" id="option-0">Apples</auro-menuoption>
         <auro-menuoption value="Oranges" id="option-1">Oranges</auro-menuoption>
@@ -1049,7 +1112,8 @@ The bib position can be customized with `placement`, `offset`, `flip`, `autoPlac
 <div style="width: 350px">
   <auro-combobox offset="20" noFlip placement="bottom-end">
     <span slot="bib.fullscreen.headline">Bib Header</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="Apples" id="option-0">Apples</auro-menuoption>
       <auro-menuoption value="Oranges" id="option-1">Oranges</auro-menuoption>
@@ -1061,7 +1125,8 @@ The bib position can be customized with `placement`, `offset`, `flip`, `autoPlac
   </auro-combobox>
   <auro-combobox offset="20" placement="bottom-end">
     <span slot="bib.fullscreen.headline">Bib Header</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="Apples" id="option-0">Apples</auro-menuoption>
       <auro-menuoption value="Oranges" id="option-1">Oranges</auro-menuoption>
@@ -1073,7 +1138,8 @@ The bib position can be customized with `placement`, `offset`, `flip`, `autoPlac
   </auro-combobox>
   <auro-combobox offset="20" noFlip placement="right" autoPlacement>
     <span slot="bib.fullscreen.headline">Bib Header</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="Apples" id="option-0">Apples</auro-menuoption>
       <auro-menuoption value="Oranges" id="option-1">Oranges</auro-menuoption>
@@ -1206,4 +1272,55 @@ export function inDialogExample() {
 };
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
+#### Custom display value
+
+You can fully customize how selected values appear by using the `displayValue` slot. This slot allows you to pass in any HTML content. Only the `snowflake` and `emphasized` layouts are supported.
+
+<div class="exampleWrapper--ondark">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/displayValueSlot.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/displayValueSlot.html -->
+  <auro-combobox layout="snowflake" shape="snowflake" size="xl" ondark value="Apples">
+    <span slot="bib.fullscreen.headline">Bib Header</span>
+    <span slot="label">Name</span>
+    <auro-menu>
+      <auro-menuoption value="Apples" id="option-0">Apples</auro-menuoption>
+      <auro-menuoption value="Oranges" id="option-1">Oranges</auro-menuoption>
+      <auro-menuoption value="Peaches" id="option-2">Peaches</auro-menuoption>
+      <auro-menuoption value="Grapes" id="option-3">Grapes</auro-menuoption>
+      <auro-menuoption value="Cherries" id="option-4">Cherries</auro-menuoption>
+      <auro-menuoption static nomatch>No matching option</auro-menuoption>
+    </auro-menu>
+    <div slot="displayValue">
+        <div class="mainText">Custom display value</div>
+        <div class="subText">Any html can be used</div>
+    </div>
+  </auro-combobox>
+  <!-- AURO-GENERATED-CONTENT:END -->
+</div>
+<auro-accordion alignRight>
+  <span slot="trigger">See code</span>
+<!-- AURO-GENERATED-CONTENT:START (CODE:src=./../apiExamples/displayValueSlot.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/displayValueSlot.html -->
+
+```html
+<auro-combobox layout="snowflake" shape="snowflake" size="xl" ondark value="Apples">
+  <span slot="bib.fullscreen.headline">Bib Header</span>
+  <span slot="label">Name</span>
+  <auro-menu>
+    <auro-menuoption value="Apples" id="option-0">Apples</auro-menuoption>
+    <auro-menuoption value="Oranges" id="option-1">Oranges</auro-menuoption>
+    <auro-menuoption value="Peaches" id="option-2">Peaches</auro-menuoption>
+    <auro-menuoption value="Grapes" id="option-3">Grapes</auro-menuoption>
+    <auro-menuoption value="Cherries" id="option-4">Cherries</auro-menuoption>
+    <auro-menuoption static nomatch>No matching option</auro-menuoption>
+  </auro-menu>
+  <div slot="displayValue">
+      <div class="mainText">Custom display value</div>
+      <div class="subText">Any html can be used</div>
+  </div>
+</auro-combobox>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>