Merge pull request #3775 from department-of-veterans-affairs/3567-Add-Combo-box-documentation

Added combo box guidance

Author: babsdenney

src/_components/form/combo-box.md

@@ -0,0 +1,85 @@
+---
+layout: component
+permalink: /components/form/combo-box
+has-parent: /components/form/
+title: Combo box
+intro-text: "A combo box helps users select an item from a large list of options."
+research-title: Form controls
+status: use-with-caution-candidate
+figma-link: https://www.figma.com/design/afurtw4iqQe6y4gXfNfkkk/VADS-Component-Library?node-id=19200-2377
+uswds-v3: default
+web-component: va-combo-box
+anchors:
+  - anchor: Examples
+  - anchor: Usage
+  - anchor: Code usage
+  - anchor: Accessibility considerations
+  - anchor: Related
+  - anchor: Component checklist
+---
+
+## Examples
+
+### Default
+
+{% include storybook-preview.html story="uswds-va-combo-box--default" link_text="va-combo-box default" height="300px" %}
+
+### With Default Value
+
+{% include storybook-preview.html story="uswds-va-combo-box--with-default-value" link_text="va-combo-box with default value" height="300px" %}
+
+### With Error
+
+{% include storybook-preview.html story="uswds-va-combo-box--with-error" link_text="va-combo-box with error" height="300px" %}
+
+### Required
+
+{% include storybook-preview.html story="uswds-va-combo-box--required" link_text="va-combo-box required" height="300px" %}
+
+### With Placeholder Text
+
+{% include storybook-preview.html story="uswds-va-combo-box--with-placeholder-text" link_text="va-combo-box with placeholder text" height="300px" %}
+
+### With Hint Text
+
+{% include storybook-preview.html story="uswds-va-combo-box--with-hint-text" link_text="va-combo-box with hint text" height="300px" %}
+
+### With Message Aria Described By
+
+{% include storybook-preview.html story="uswds-va-combo-box--with-message-aria-described-by" link_text="uswds-va-combo-box with message aria described by" height="300px" %}
+
+## Usage
+
+<a class="vads-c-action-link--blue" href="https://designsystem.digital.gov/components/combo-box/">Refer to the U.S. Web Design System for usage guidance</a>
+
+{% include content/select-options.md %}
+
+### Errors
+
+* Refer to the specific [error example](#with-error) above.
+
+<a class="vads-c-action-link--blue" href="{{ site.baseurl }}/components/form/#error-handling">
+  View form error handling for additional guidance
+</a>
+
+### Hint text
+
+* Refer to the [hint text example](#with-hint-text) above.
+
+<a class="vads-c-action-link--blue" href="{{ site.baseurl }}/components/form/label#hint-text">
+  View label hint text for additional guidance
+</a>
+
+{% include component-docs.html component_name=page.web-component %}
+
+## Accessibility considerations
+
+<a class="vads-c-action-link--blue" href="https://designsystem.digital.gov/components/combo-box/#accessibility-guidance">Refer to the U.S. Web Design System for accessibility guidance</a>
+
+## Related
+
+* [Select]({{ site.baseurl }}/components/form/select)
+* [Radio button]({{ site.baseurl }}/components/form/radio-button)
+* [Search input]({{ site.baseurl }}/components/search-input)
+
+{% include _component-checklist.html component_name=page.web-component %}

src/_components/form/index.md

@@ -8,6 +8,7 @@ status: use-deployed
 sub-pages:
   - sub-page: Autosave
   - sub-page: Checkbox
+  - sub-page: Combo box
   - sub-page: Date input
   - sub-page: Memorable date
   - sub-page: File input

src/_components/form/radio-button.md

@@ -63,6 +63,8 @@ anchors:
 
 <a class="vads-c-action-link--blue" href="https://designsystem.digital.gov/components/radio-buttons/">Refer to the U.S. Web Design System for usage guidance</a>
 
+{% include content/select-options.md %}
+
 ### Choosing between variations
 
 * Use the [Hint text](#hint-text) variation to provide additional information that pertains to the question being asked or all of the options presented.

src/_components/form/select.md

@@ -27,7 +27,7 @@ anchors:
 
 {% include storybook-preview.html story="uswds-va-select--required" link_text="va-select required" %}
 
-### With hint text
+### Hint text
 
 {% include storybook-preview.html story="uswds-va-select--with-hint-text" link_text="va-select with hint text" %}
 
@@ -57,9 +57,7 @@ anchors:
 
 ### Additional guidance for VA
 
-#### Additional reasons to consider something else
-
-**More than 15 options.** If the list of options is very long, we do not yet have the combo box component in our system thus an alternative is to use functionality that allows users to type the same information into a text input that suggests possible options instead as seen in our [search input]({{ site.baseurl }}/components/search-input) component.
+{% include content/select-options.md %}
 
 ### Errors
 

src/_components/search-input.md

@@ -52,6 +52,8 @@ web-component: va-search-input
 
 * When free text input is allowed, do not use type-ahead in form fields where the user might assume they are limited to selecting a suggested term. Alternatively, provide a clear way for the user to add an entry if you do use type-ahead in a form field.
 
+{% include content/select-options.md %}
+
 ### Placement
 
 * The search input component should only appear in the global header, on search results pages, and in search-related tools such as Resources and Support and Find a VA Form.

src/_includes/content/select-options.md

@@ -0,0 +1,15 @@
+### Choosing the right component for the task
+Consider how many options the user will have when choosing the right component. The number of options will determine what component is right for the task. 
+
+* **2 - 5: Radio Buttons.** Use [radio buttons]({{ site.baseurl }}/components/form/radio-button) when there are only a few options that can all be exposed at once.
+* **6 - 15: Select.** Use a [select]({{ site.baseurl }}/components/form/select) for a limited number of options.
+* **16 - 100: Combo Box.** For over 15 items, use a [combo box]({{ site.baseurl }}/components/form/combo-box) that combines a select with typeahead.
+* **101 - ∞: Search Input typeahead.** Over 100 items, use the [search input]({{ site.baseurl }}/components/search-input) component with typeahead.
+
+### Some exceptions when choosing the right component
+Some exceptions can be considered when choosing the right component. 
+
+* **When the options are known and memorable.** Use the combo box when the user will know what to expect as options in the dropdown. Some examples of this would be a list of countries or states. See the [USWDS address pattern](https://designsystem.digital.gov/patterns/create-a-user-profile/address/#guidance-2) for an example.
+* **When the radio button labels are long or radio tiles contain descriptive text.** Using long labels within a dropdown might create an issue where the information needed to make a selection is lost. There's also descriptive text added within radio tiles that can't be used in a dropdown. In those use cases a radio button might be required instead of a dropdown opton. 
+
+These are some things to consider when choosing between different components. Contact the Design System team for help if you have other use cases that are considered exceptions.