Combobox RFC

[najikahalsema]

Hello! Below you will find the RFC for the combobox component which is very similar to how its documentation will look. :) Please leave your comments and suggestions below for this work if you have any.

You can track our current progress on the features outlined via this project board.

Link to working branch | Link to draft PR

Combobox

A combobox combines a textfield with a picker, allowing users to filter longer lists to only the selections matching a query. It's composed of a textfield, a picker button, and child menu items.

Spectrum CSS documentation

Usage

yarn add @spectrum-web-components/combobox

Import the side effectful registration of <sp-combobox>:

import '@spectrum-web-components/combobox/sp-combobox.js'

When looking to leverage the Combobox base class as a type and/or for extension purposes, do so via:

import { Combobox } from '@spectrum-web-components/combobox';

Examples

The combobox accepts an array of options in the form of the type ComboboxOptions.

type ComboboxOption = {
    id: string;
    value: string;
};

Using an object

  <sp-field-label for="combobox">
    Options
  </sp-field-label>
  <sp-combobox autocomplete="list" label="Options" id="combobox" .options=${optionList}>
  </sp-combobox>

Using a map

  <sp-field-label for="combobox">
    Options
  </sp-field-label>
  <sp-combobox autocomplete="none" label="Options" id="combobox">
     ${optionList.map(
     (option) => html`
       <sp-menu-item id=${option.id} value=${option.value}>
         ${option.value}
       </sp-menu-item>
     `
  </sp-combobox>

Manually adding items

  <sp-field-label for="combobox">
    Options
  </sp-field-label>
  <sp-combobox autocomplete="none" label="Options" id="combobox">
     <sp-menu-item id="option1" value="Option 1">
       "Option 1"
     </sp-menu-item>
     <sp-menu-item id="option2" value="Option 2">
       "Option 2"
     </sp-menu-item>
  </sp-combobox>

Properties and attributes

• autocomplete: Corresponds to aria-autocomplete. Has a value of "none" (the default), "list", or "both" and set the ARIA value accordingly.
• disabled: Whether the combobox is disabled.
• invalid: Declares the textfield's input is invalid, similar to <sp-textfield>. Part of the Spectrum CSS spec, but marked as a contribution.
• label: The label describing what the combobox is for.
• open: whether the overlay of menu items in the combobox is open.
• options?: An array of combobox's menu item children.
• quiet: Whether the visual delivery of the combobox is quiet.
• selected: The current selected value of the combobox. (This also may be overkill when factoring in the fact that value exists??)
• selects?: Visual (ie has a checkmark to denote the selected item) or no?
• valid: Indicates the textfield input is valid, similar to <sp-textfield>.
• value: The selected value of the combobox. This matches either the text input or the selected menu item's value.

Slots

• help-text: Optional help text that renders below the combobox.
• options: Slotted <sp-menu-item>s that make up the overlay of combobox options.
• tooltip: Slot for an <sp-tooltip> for the combobox.

Events

• @change: Announces the value of the combobox has changed.
• @input: Announces the streaming value of the combobox.
• @sp-opened: Announces that the overlay has opened
• @sp-closed: Announces that the overlay has closed

Behaviour

Forms of combobox autocomplete

The combobox has four types of usages as specified by WAI:

1. Editable without autocomplete (p0)

The combobox is editable (ie supports text input), but the suggested values its menu item children contain are the same, regardless of what is typed into the textfield. autocomplete="none"

2. Editable with list autocomplete (p1)

The combobox is editable, and when its menu is opened, it presents suggested values that either correspond to or complete the characters typed into the combobox's textfield. If the entered text matches the value of one of the items, it becomes the value of the combobox. autocomplete="list"

3. Editable with inline and list autocomplete (not scoped)

This version operates the same as #2, but the portion of the string that has not been typed by the user appears inline after the cursor in the combobox textfield. autocomplete="both"

4. Selection only (p2)

A combobox that has no text input and is functionally similar to a picker.

Focus

The dropdown list of menu items opens on clicking or focusing the textfield or picker button. It supports keyboard navigation.

When the combobox is focused, the ArrowDown moves focus into the first focusable menu item in the overlay. ArrowUp and ArrowDown moves between the menu items.

Escape dismisses the overlay of menu items if it is open. If the overlay is closed, Escape clears the combobox's textfield.

Enter sets the value of <sp-combobox>. If the combobox's overlay of menu items is open, value is set to the value of the selected menu item and closes the overlay of menu items, returning focus back to the combobox's textfield.

Mobile

Currently, behaviour for mobile is not prioritised, as Spectrum has not specified the design for mobile surfaces.

[Westbrook]

If you happen to have been following along, we are currently on schedule for the initial editable combobox without autocomplete release within the next week. Keep am eye on #3894 to more closely track timing.