@aurodesignsystem/auro-formkit 5.6.0 → 5.8.0

package/components/combobox/demo/api.md

@@ -5,43 +5,46 @@
 
 ## Properties
 
-| 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"                  |                                                  |
-| [shift](#shift)                         | `shift`                         |           | `boolean`             | "false"                    | If declared, the dropdown will shift its position to avoid being cut off by the viewport. |
-| [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.            |
+| Property                              | Attribute                             | Modifiers | Type                  | Default                    | Description                                      |
+|---------------------------------------|---------------------------------------|-----------|-----------------------|----------------------------|--------------------------------------------------|
+| [appearance](#appearance)                          | `appearance`                          |           | `string`              | "'default'"                | Defines whether the component will be on lighter or darker backgrounds. |
+| [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. |
+| [behavior](#behavior)                            | `behavior`                            |           | `string`              | "suggestion"               | Sets the behavior of the combobox, "filter" or "suggestion".<br />"filter" requires the user to select an option from the menu.<br />"suggestion" allows the user to enter a value not present in the menu options. |
+| [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 on 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`             |                            | DEPRECATED - use `appearance` instead.           |
+| [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`. |
+| [setCustomValidityValueMissingFilter](#setCustomValidityValueMissingFilter) | `setCustomValidityValueMissingFilter` |           | `string`              |                            | Custom help text message to display when validity = `valueMissing` due to the user not choosing a menu option when behavior = "filter". |
+| [shape](#shape)                               |                                       |           | `string`              | "classic"                  |                                                  |
+| [shift](#shift)                               | `shift`                               |           | `boolean`             | "false"                    | If declared, the dropdown will shift its position to avoid being cut off by the viewport. |
+| [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
 
@@ -103,9 +106,9 @@
   <!-- AURO-GENERATED-CONTENT:END -->
 </div>
 <div class="exampleWrapper--ondark" aria-hidden>
-  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/onDark.html) -->
-  <!-- The below content is automatically added from ./../apiExamples/onDark.html -->
-  <auro-combobox onDark>
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/inverseAppearance.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/inverseAppearance.html -->
+  <auro-combobox appearance="inverse">
     <span slot="bib.fullscreen.headline">Bib Header</span>
     <span slot="label">Name</span>
     <auro-menu>
@@ -141,9 +144,9 @@
 </auro-combobox>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/onDark.html) -->
-<!-- The below content is automatically added from ./../apiExamples/onDark.html -->
-<auro-combobox onDark>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/inverseAppearance.html) -->
+<!-- The below content is automatically added from ./../apiExamples/inverseAppearance.html -->
+<auro-combobox appearance="inverse">
   <span slot="bib.fullscreen.headline">Bib Header</span>
   <span slot="label">Name</span>
   <auro-menu>
@@ -158,6 +161,107 @@
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
+### Behavior
+
+There are two behaviors available for the combo box: suggestion and filter.
+The default behavior is "suggestion".
+
+#### Suggestion
+
+With the suggestion behavior, the menu options are displayed to the user as suggestions, but the user may enter whatever value they like into the input
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/suggestion.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/suggestion.html -->
+  <auro-combobox behavior="suggestion">
+    <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>
+      <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/suggestion.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/suggestion.html -->
+
+```html
+<auro-combobox behavior="suggestion">
+  <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>
+    <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>
+
+#### Filter
+
+With the filter behavior, the menu options are displayed to the user, and the user is required to choose one of the menu options in order for the input to be considered valid.
+
+The `setCustomValidityValueMissingFilter` attribute is also available to display a custom message to the user when this validation check fails.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/filter.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/filter.html -->
+  <auro-combobox behavior="filter" setCustomValidityValueMissingFilter="Please select an option from the list">
+    <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>
+      <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/filter.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/filter.html -->
+
+```html
+<auro-combobox behavior="filter" setCustomValidityValueMissingFilter="Please select an option from the list">
+  <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>
+    <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>
+
 ### Dynamic Menu
 
 This example demonstrates a data driven combobox. The data is used to populate the `auro-menu`. In this example, each time the input's value changes, the data is updated and the menu is recreated.
@@ -175,10 +279,11 @@ The menu in this example was populated from data from a country/city API. To kee
     layout="snowflake"
     shape="snowflake"
     size="lg"
-    ondark
+    appearance="inverse"
     noFilter
     persistInput
     dvInputOnly
+    setCustomValidityValueMissing="Please select an option from the list."
     required>
     <span slot="bib.fullscreen.headline">Dynamic Combobox Header</span>
     <span slot="label">First</span>
@@ -195,10 +300,11 @@ The menu in this example was populated from data from a country/city API. To kee
     layout="snowflake"
     shape="snowflake"
     size="lg"
-    ondark
+    appearance="inverse"
     noFilter
     persistInput
     dvInputOnly
+    setCustomValidityValueMissing="Please select an option from the list."
     required>
     <span slot="bib.fullscreen.headline">Dynamic Combobox Header</span>
     <span slot="label">Second</span>
@@ -231,10 +337,11 @@ The menu in this example was populated from data from a country/city API. To kee
   layout="snowflake"
   shape="snowflake"
   size="lg"
-  ondark
+  appearance="inverse"
   noFilter
   persistInput
   dvInputOnly
+  setCustomValidityValueMissing="Please select an option from the list."
   required>
   <span slot="bib.fullscreen.headline">Dynamic Combobox Header</span>
   <span slot="label">First</span>
@@ -251,10 +358,11 @@ The menu in this example was populated from data from a country/city API. To kee
   layout="snowflake"
   shape="snowflake"
   size="lg"
-  ondark
+  appearance="inverse"
   noFilter
   persistInput
   dvInputOnly
+  setCustomValidityValueMissing="Please select an option from the list."
   required>
   <span slot="bib.fullscreen.headline">Dynamic Combobox Header</span>
   <span slot="label">Second</span>
@@ -400,6 +508,91 @@ export async function dynamicMenuExample() {
 <!-- AURO-GENERATED-CONTENT:END -->
 </auro-accordion>
 
+### Persistent Input
+
+The `persistInput` attribute allows you to set the combo box to persist the value of the input regardless of the current value set for the combo box.
+
+A persistent input is typically used in conjunction with display values to show the actual value of the selected option to the user when the input is not focused.
+
+This is helpful for things like dynamic menus where you want the user to be able to continue their search where they left off but display a full selected value when the input is not focused.
+
+_*Note:*_ When using `persistInput` with the `required` attribute, you must also pass an error message for when there isn't a valid value but the user has typed something in the input to the `setCustomValidityValueMissing` attribute.
+
+<div class="exampleWrapper">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/persistInput.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/persistInput.html -->
+  <auro-combobox
+    required
+    persistInput
+    setCustomValidityValueMissing="Please select an option from the list."
+    >
+    <span slot="bib.fullscreen.headline">Persistant Input</span>
+    <span slot="label">Persistant Input</span>
+    <auro-menu>
+      <auro-menuoption value="Apples" id="option-0">
+        Apples
+        <div slot="displayValue">Apples</div>
+      </auro-menuoption>
+      <auro-menuoption value="Oranges" id="option-1">
+        Oranges
+        <div slot="displayValue">Oranges</div>
+      </auro-menuoption>
+      <auro-menuoption value="Peaches" id="option-2">
+        Peaches
+        <div slot="displayValue">Peaches</div>
+      </auro-menuoption>
+      <auro-menuoption value="Grapes" id="option-3">
+        Grapes
+        <div slot="displayValue">Grapes</div>
+      </auro-menuoption>
+      <auro-menuoption value="Cherries" id="option-4">
+        Cherries
+        <div slot="displayValue">Cherries</div>
+      </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/persistInput.html) -->
+<!-- The below code snippet is automatically added from ./../apiExamples/persistInput.html -->
+
+```html
+<auro-combobox
+  required
+  persistInput
+  setCustomValidityValueMissing="Please select an option from the list."
+  >
+  <span slot="bib.fullscreen.headline">Persistant Input</span>
+  <span slot="label">Persistant Input</span>
+  <auro-menu>
+    <auro-menuoption value="Apples" id="option-0">
+      Apples
+      <div slot="displayValue">Apples</div>
+    </auro-menuoption>
+    <auro-menuoption value="Oranges" id="option-1">
+      Oranges
+      <div slot="displayValue">Oranges</div>
+    </auro-menuoption>
+    <auro-menuoption value="Peaches" id="option-2">
+      Peaches
+      <div slot="displayValue">Peaches</div>
+    </auro-menuoption>
+    <auro-menuoption value="Grapes" id="option-3">
+      Grapes
+      <div slot="displayValue">Grapes</div>
+    </auro-menuoption>
+    <auro-menuoption value="Cherries" id="option-4">
+      Cherries
+      <div slot="displayValue">Cherries</div>
+    </auro-menuoption>
+  </auro-menu>
+</auro-combobox>
+```
+<!-- AURO-GENERATED-CONTENT:END -->
+</auro-accordion>
+
 ### Updating Externally
 
 This example demonstrates using the <code>updateActiveOption</code> method to set a specific menu option as "active."
@@ -412,7 +605,7 @@ This is useful for situations like matching IATA codes (sea -> SeaTac airport)
   <p style="color: white;">
       Type 'a' in the combobox for best testing results :)
   </p>
-  <auro-combobox ondark id="externalSelectionExample" layout="classic" shape="classic" size="lg" placeholder="Placeholder content" required style="width: 249px;">
+  <auro-combobox appearance="inverse" id="externalSelectionExample" layout="classic" shape="classic" size="lg" placeholder="Placeholder content" required style="width: 249px;">
     <span slot="ariaLabel.bib.close">Close combobox</span>
     <span slot="ariaLabel.input.clear">Clear All</span>
     <span slot="bib.fullscreen.headline">Bib Header</span>
@@ -440,7 +633,7 @@ This is useful for situations like matching IATA codes (sea -> SeaTac airport)
 <p style="color: white;">
     Type 'a' in the combobox for best testing results :)
 </p>
-<auro-combobox ondark id="externalSelectionExample" layout="classic" shape="classic" size="lg" placeholder="Placeholder content" required style="width: 249px;">
+<auro-combobox appearance="inverse" id="externalSelectionExample" layout="classic" shape="classic" size="lg" placeholder="Placeholder content" required style="width: 249px;">
   <span slot="ariaLabel.bib.close">Close combobox</span>
   <span slot="ariaLabel.input.clear">Clear All</span>
   <span slot="bib.fullscreen.headline">Bib Header</span>
@@ -511,9 +704,9 @@ If set, disables the combobox.
   <!-- AURO-GENERATED-CONTENT:END -->
 </div>
 <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-combobox onDark disabled>
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/inverseAppearanceDisabled.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/inverseAppearanceDisabled.html -->
+  <auro-combobox appearance="inverse" disabled>
     <span slot="bib.fullscreen.headline">Bib Header</span>
     <span slot="label">Name</span>
     <auro-menu>
@@ -549,9 +742,9 @@ If set, disables the combobox.
 </auro-combobox>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/onDarkDisabled.html) -->
-<!-- The below content is automatically added from ./../apiExamples/onDarkDisabled.html -->
-<auro-combobox onDark disabled>
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/inverseAppearanceDisabled.html) -->
+<!-- The below content is automatically added from ./../apiExamples/inverseAppearanceDisabled.html -->
+<auro-combobox appearance="inverse" disabled>
   <span slot="bib.fullscreen.headline">Bib Header</span>
   <span slot="label">Name</span>
   <auro-menu>
@@ -676,9 +869,9 @@ Sets a persistent error state (e.g. an error state returned from the server).
   <!-- AURO-GENERATED-CONTENT:END -->
 </div>
 <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-combobox onDark error="Custom error message">
+  <!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/inverseAppearanceError.html) -->
+  <!-- The below content is automatically added from ./../apiExamples/inverseAppearanceError.html -->
+  <auro-combobox appearance="inverse" error="Custom error message">
     <span slot="bib.fullscreen.headline">Bib Header</span>
     <span slot="label">Name</span>
     <auro-menu>
@@ -714,9 +907,9 @@ Sets a persistent error state (e.g. an error state returned from the server).
 </auro-combobox>
 ```
 <!-- AURO-GENERATED-CONTENT:END -->
-<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/onDarkError.html) -->
-<!-- The below content is automatically added from ./../apiExamples/onDarkError.html -->
-<auro-combobox onDark error="Custom error message">
+<!-- AURO-GENERATED-CONTENT:START (FILE:src=./../apiExamples/inverseAppearanceError.html) -->
+<!-- The below content is automatically added from ./../apiExamples/inverseAppearanceError.html -->
+<auro-combobox appearance="inverse" error="Custom error message">
   <span slot="bib.fullscreen.headline">Bib Header</span>
   <span slot="label">Name</span>
   <auro-menu>
@@ -1541,7 +1734,7 @@ You can fully customize how selected values appear by using the `displayValue` s
 <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">
+  <auro-combobox layout="snowflake" shape="snowflake" size="xl" appearance="inverse" value="Apples">
     <span slot="bib.fullscreen.headline">Bib Header</span>
     <span slot="label">Name</span>
     <auro-menu>
@@ -1565,7 +1758,7 @@ You can fully customize how selected values appear by using the `displayValue` s
 <!-- The below code snippet is automatically added from ./../apiExamples/displayValueSlot.html -->
 
 ```html
-<auro-combobox layout="snowflake" shape="snowflake" size="xl" ondark value="Apples">
+<auro-combobox layout="snowflake" shape="snowflake" size="xl" appearance="inverse" value="Apples">
   <span slot="bib.fullscreen.headline">Bib Header</span>
   <span slot="label">Name</span>
   <auro-menu>