Skip to content

feat(GlListbox): create listbox component

Olena Horal-Koretska requested to merge 348738-create-listbox-component-without-bootstrap-vue into main

What does this MR do?

References gitlab#348738 (closed)

In the scope of this MR we pull in popper.js as a direct dependency and implement Listbox component without bootsrap-vue.

Single-select Multi-select
2022-02-14_20.27.11 2022-02-14_21.42.36

We support multi and single-selection. v-model can be set to track selection in the listbox.

header && footer slots are available but without any styling - it is the responsibility of the component consumer to style content in these slots.

Item will be rendered based on the text prop if provided or the user can provide a custom template for rendering the Listbox item.

Keyboard navigation support

I've used this example as a reference.

Key Behaviour single-select Behavior multi-select
Esc Close dropdown/focus toggle button Close dropdown/focus toggle button
Enter If the focus is on the toggle, expands the Listbox and places focus on the selected option in the list or on the first option if there is no selection. If the focus is on the toggle, expands the Listbox and places focus on the first selected option in the list or on the first option if there is no selection.
Enter If focus is in the listbox, selects the item. If it was selected, does not change selection, collapses the listbox and keeps the currently selected option as the button label (default behavior) but the user can customize the toggle label If focus is in the Listbox, selects the item. If it was selected - deselects it.
Space Same as Enter Same as Enter
Down/ Up arrow If focus is on the list item, will focus the next item up/down the list. If the end of the list is reached, won't move the focus Same as for the single-select
Home/End Focuses the first/last item in the list Same as for the single-select

ARIA attributes

Attribute Value Element
aria-labelledby labelId string provided by compoennt consumer Toggle button && items container - ul
aria-haspopup listbox Toggle button
aria-expanded true when listbox expanded Toggle button
role listbox Items container - ul element
tabindex -1 Items container - ul element - to avoid tabbing to container instead of the list item
aria-activedescendant Id of the active option Items container - ul element - Not implemented,
role option List item - li element
aria-selected true List item - li element

Does this MR meet the acceptance criteria?

Conformity

  • Code review guidelines.
  • GitLab UI's contributing guidlines.
  • If it changes a Pajamas-compliant component's look & feel, the MR has been reviewed by a UX designer.
  • If it changes GitLab UI's documentation guidelines, the MR has been reviewed by a Technical Writer.
  • If the MR changes a component's API, integration MR(s) have been opened in the following projects to ensure that the @gitlab/ui package can be upgraded quickly after the changes are released:
  • Added the ~"component:*" label(s) if applicable.

Security

If this MR contains changes to processing or storing of credentials or tokens, authorization and authentication methods and other items described in the security review guidelines:

  • Label as security and @ mention @gitlab-com/gl-security/appsec
  • Security reports checked/validated by a reviewer from the AppSec team

Accessibility

If this MR adds or modifies a component, take a few moments to review the following:

  • All actions and functionality can be done with a keyboard.
  • Links, buttons, and controls have a visible focus state.
  • All content is presented in text or with a text equivalent. For example, alt text for SVG, or aria-label for icons that have meaning or perform actions.
  • Changes in a component’s state are announced by a screen reader. For example, changing aria-expanded="false" to aria-expanded="true" when an accordion is expanded.
  • Color combinations have sufficient contrast.
Edited by Jeremy Elder

Merge request reports