Combobox Component (Single Select)

[scurker]

Follow general ARIA practices guidelines: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/

This implementation addresses only single select comboboxes.

• for multiselect see Combobox Component (Multiselect) #1103.
• for custom form values see Combobox Hidden Form Values #1184

List items can be provided via a child component, ComboboxOption:

<Combobox label="Combobox">
  <ComboboxOption value="...">
    Item
    Longer Description
  </ComboboxOption>
</Combobox>

...or via a list with item definition:

<Combobox label="Combobox" options={[{ label: 'Foo', value: 'foo' }]} />

The label provided for Combobox should be of type ContentNode to allow for additional values beyond strings:

<Combobox label={`<Icon type="apple"/> Fruit`}>
  ...
</Combobox>

To allow for grouping of items, an additional ComboboxGroup component can be used to wrap combobox items:

<Combobox label="Combobox">
  <ComboboxGroup label="Group A">
   <ComboboxItem>1</ComboboxItem>
   <ComboboxItem>2</ComboboxItem>
   <ComboboxItem>3</ComboboxItem>
  </ComboboxGroup>
  <ComboboxGroup label="Group B">
   <ComboboxItem>4</ComboboxItem>
   <ComboboxItem>5</ComboboxItem>
   <ComboboxItem>6</ComboboxItem>
  </ComboboxGroup>
</Combobox>

For the list of items and ComboboxOption, providing the value property is optional and will reflect the value of the label associated with that item. Additionally, a selected prop can be provided to both to indicate that item is currently selected.

Under the hood:

• The input component should behave similarly to <TextField /> (some different accommodations may need to be made to help support Combobox Component (Multiselect) #1103)
  • Include inner right padding to prevent text overflowing the down arrow
  • General input props should be supported such as disabled, required, etc.
• Use the same styles as <OptionsMenuList> to display the list of items
• Allow custom filtering function to display matching items on input via prop
  • Defaults to a text matching based on the the value or label of the item
• Support both auto selection and manual selection during autocomplete (see #2 and #3 list items in the autocomplete section of the aria authoring practices)
• When selected, an item should show it's selected state in the popup
  • This checkbox can reuse the existing check icon with a css ring to match the design
  • Changing the selected item(s) will call any onChange handlers

Other Notes:

Opening/closing the listbox has the following behaviors:

• When Open
  • Has Selected Value (Autocomplete Manual)
    • The input value will be set to an empty string to allow users to see all options and filter options based on the combobox input
  • No Selected Value (Autocomplete Manual)
    • The input value will retain its initial value and will not clear, allowing the user to update the combobox input to change the filtered options
• When Closed
  • Has Selected Value (Autocomplete Manual)
    • If the selected value did not change, the combobox input will revert back to the selected value
  • No Selected Value (Autocomplete Manual)
    • The combobox input will retain the currently typed characters

Examples:

• Overall UX design
• Additional Combobox Examples

[thuey]

To allow for grouping of items, an additional ComboboxGroup component can be used to wrap combobox items:

Is there a similar way to accomplish this using the item definition list approach?

As an aside, what is the value in supporting two ways to define the list?

[scurker]

As an aside, what is the value in supporting two ways to define the list?

It's similar to how we support options and HTMLOptions for selects and there's some value in keeping the props similar to make it easy to convert between the two:

cauldron/packages/react/src/components/Select/index.tsx

Lines 19 to 20 in b60588f

	options?: SelectOption[];
	children?: React.ReactElement<HTMLOptionElement | HTMLOptGroupElement>[];

The general idea is if an author needs a simple list of label/value items they can use the list array. More advanced configurations could use the component to display more complex items.

As an example, React Spectrum (Adobe) Combobox does something very similar.

Is there a similar way to accomplish this using the item definition list approach?

Not unless we really think it's needed. I'm double checking with @dequelabs/cauldron-design on this, but my understanding is most cases will not need to be grouped so the list format will be the easiest to implement.

[schne324]

<ComboboxGroup label="Group A">

This may already be planned (perhaps some prop types defined in the ticket would've cleared this up a bit) but I think the label prop for ComboboxGroup should support any react nodes so we can do stuffs like

<ComboboxGroup label={<Icon type="bananas" /> Fruits}>
   <ComboboxItem>Bananas</ComboboxItem>
   <ComboboxItem>Mangos</ComboboxItem>
   <ComboboxItem>Cucumbers (yes a cucumber is in fact a fruit)</ComboboxItem>
</ComboboxGroup>

---

Due to the complicated nature of comboboxes (and historical UA/AT bugs surrounding comboboxes), it may be useful to clearly document which screen readers we will support for this (in both the ticket and demo/docs page for it). I would suggest latest VO, NVDA, and JAWS versions as our target support here but maybe that is something to consider more "globally" (on the cauldron readme/landing page of docs list what AT we support)

[scurker]

<ComboboxGroup label="Group A">

This may already be planned (perhaps some prop types defined in the ticket would've cleared this up a bit) but I think the label prop for ComboboxGroup should support any react nodes so we can do stuffs like

Good callout, I can update the description.

<ComboboxGroup label={<Icon type="bananas" /> Fruits}>
   <ComboboxItem>Bananas</ComboboxItem>
   <ComboboxItem>Mangos</ComboboxItem>
   <ComboboxItem>Cucumbers (yes a cucumber is in fact a fruit)</ComboboxItem>
</ComboboxGroup>

Due to the complicated nature of comboboxes (and historical UA/AT bugs surrounding comboboxes), it may be useful to clearly document which screen readers we will support for this (in both the ticket and demo/docs page for it). I would suggest latest VO, NVDA, and JAWS versions as our target support here but maybe that is something to consider more "globally" (on the cauldron readme/landing page of docs list what AT we support)

There's already general guidelines here: https://cauldron.dequelabs.com/component-guidelines#accessibility

[Amandeque]

Estimates:
SIZE: Large

[Keerthi-Penukonda]

Question

@scurker error message is being displayed even when selected an option from "Does this combobox have an error?" dropdown. Is this expected? or do we need to remove the error once the option is selected?

Testing

Verified UI and performed basic accessibility testing. Did not find any issues. Moving this to a11y column for accessibility testing.

[scurker]

@Keerthi-Penukonda Yes, that's expected. Combobox/text fields are dependent on the author clearing the error once there's a valid selection made.

[VaniChinnam]

Verified on the latest build. Raised 1 violation and 3 best practices.

Violation - 1505025
Best Practices - 1495130, 1505019, 1505022

[scurker]

Thanks @VaniChinnam, I've raised issues for the following:

• 1505025: Combobox Not Announcing "No Results" status (NVDA) #1201
• 1495130: Combobox Not Announcing Selected State (NVDA) #1202
• 1505019: Documentation Table of Contents not visible during tab focus #1203

For 1505022, it was an intentional design decision to allow for a user to easily filter down the list of options again if the user expanded the list again without being limited to options that were currently there. If the user types/remove characters the value does persist (or gets restored to its original value if no selections were made). I can ask @dequelabs/cauldron-design to see if we can get some usability testing here to see if this is something we want to tweak.

[Keerthi-Penukonda]

Closing this ticket as we have separate tickets to track accessibility issues.