feat: add refactored `Combobox` component #1559

jzempel · 2023-06-13T18:28:11Z

Description

Garden's current suite of combobox-like components – Autocomplete, Combobox, Multiselect and Select – is plagued with deep-seated accessibility issues, costly support maintenance, and APIs that challenging to navigate. This PR adds a new @zendeskgarden/dropdowns.next package with a fully refactored Combobox that is built to replace the existing component set with 100% WCAG 2.1 and WAI-ARIA 1.2 accessibility. The non-accessible component set will be removed in a future major release.

Detail

Key capabilities include:

Controllable: The Combobox functions in both uncontrolled and
controlled modes. Controlled mode enables aspects, such as input value, selection value(s),
listbox expansion, and current option active index, to share and adapt to the
surrounding UI.
Autocomplete-able: Denotes the Combobox with list
autocomplete. Filtering implementation is left to the API consumer.
Selectable: The Combobox API ensures the selection of one or more
listbox option values, while also supporting the W3C no autocomplete
example for use cases like search.
Multi-selectable: This feature enables the Combobox to provide WAI-ARIA
multi-select listbox functionality with option-as-tag value rendering.
Non-editable: The Combobox supports select-only mode, where the user cannot modify the <input>.
Filterable: The Combobox offers various filtering methods for listbox
options. Details of the filtering implementation are left to the API consumer.
Markup-able: The Combobox can convert input value text to rich HTML
markup on blur in single-selection mode.
Decorate-able: The Combobox allows adding start and end media (SVG icons).
Certain features will replace end media with Garden's standard dropdown chevron
treatment.
Group-able: The Combobox API utilizes fully accessible <OptGroup>
components for grouping, similar to the corresponding HTML element.
Compactible: Like other form elements, the Combobox supports compact
sizing.
Field-able: The Combobox builds on Garden’s Field API context to
establish accessible relationships with corresponding Label, Hint, and Message
components.
Validate-able: The Combobox provides validation styling and
accessibility comparable to other Garden form components.
RTL theme-able: Functionality displays and operates correctly for
left-to-right and right-to-left layouts.

Checklist

👌 design updates will be Garden Designer approved (add the designer as a reviewer)
🌐 demo is up-to-date (yarn start)
⬅️ renders as expected with reversed (RTL) direction
🤘 renders as expected with Bedrock CSS (?bedrock)
💂‍♂️ includes new unit tests. Maintain existing coverage (always >= 96%)
♿ tested for WCAG 2.1 AA accessibility compliance
📝 tested in Chrome, Firefox, Safari, and Edge

…ed ARIA

packages/dropdowns.next/README.md

Francois-Esquire

views often represent compositions of a user interface rather than a component (or its primitives). Views tend to be associated with application level thinking (like the MVC pattern) as well. What was the reason for src/views (instead of the conventional src/styled)?

packages/dropdowns.next/src/elements/combobox/Option.tsx

packages/dropdowns.next/src/elements/combobox/OptGroup.tsx

jzempel · 2023-06-20T18:02:01Z

What was the reason for src/views (instead of the conventional src/styled)?

@Francois-Esquire in light of future development plans, I want to establish a new/improved dev structure that more closely aligns with the documented API. In Garden, we historically refer to a "container-view-element" architecture. This structure reinforces that and takes weight off of the current choice of styled-components as a means for expressing view components.

geotrev

No strong thoughts so far. The code looks solid. I'll take a look at the tests & storybook next.

packages/dropdowns.next/src/elements/combobox/Combobox.tsx

packages/dropdowns.next/src/elements/combobox/Hint.tsx

packages/dropdowns.next/src/elements/combobox/Listbox.tsx

packages/dropdowns.next/src/elements/combobox/Message.tsx

packages/dropdowns.next/src/elements/combobox/OptGroup.tsx

packages/dropdowns.next/src/views/combobox/StyledListbox.ts

lucijanblagonic · 2023-06-21T13:35:12Z

Here are a couple of things I noticed:

The text jumps on focus. It should stay in the same line.

Focus styling on Tags not up-to-date with updated outlines.

Validation Warning outline color doesn't match to updated focus outlines.

In this case I see that the Input clears text on the second Escape press. Do you think we should follow that behavior here?

Is there an enhancement opportunity where the keyboard can move the focus between tags with the arrow keys? In situations where you have multi-select + editable, it could be appropriate. 🤔

Francois-Esquire

Solid work @jzempel 🙌 , left some feedback.

I noticed some visual tug-o-war between the scroll bar and the "Trigger" wrapping the input and tags. When multi-select is enabled with 2 or more tags and limited space, I'm seeing some overlap which may be undesirable:

Without focusInset:

With focusInset:

packages/dropdowns.next/demo/~patterns/stories/ListboxStory.tsx

Francois-Esquire · 2023-06-21T17:17:04Z

packages/dropdowns.next/src/elements/combobox/Combobox.tsx

+      const tagProps: Record<string, IOptionProps['tagProps']> = {};
+      const retVal = toOptions(children, tagProps);
+
+      setOptionTagProps(value => ({ ...value, ...tagProps }));


What was the reason for spreading the previous state?

A small concern I have about spreading the previous state is when it comes dynamic options, which is an edge case. It would result in persisting stale values and a possible memory leak.

Without this, tagProps get lost when options are filtered out – resulting in visual changes to currently selected tags. After careful consideration, I decided a "leak" wasn't a concern as the object will remain stable at N total options.

Well, what's the intended approach with virtual lists?

Virtualization (which isn't a recommended a11y approach here) doesn't change the situation. The state remains consistent at N total optionTagProps, where N = as many options that have tagProps as the user has experienced.

I'm thinking about putting a condition here to only set the state if the combobox isMultiselectable. Although, it would be silly for a consumer to add tagProps to a non-multiselectable combobox.

packages/dropdowns.next/src/elements/combobox/Tag.tsx

packages/dropdowns.next/src/index.ts

packages/dropdowns.next/src/views/combobox/StyledHint.ts

packages/dropdowns.next/src/views/combobox/StyledSeparator.ts

jzempel · 2023-06-21T17:57:26Z

@lucijanblagonic thanks for the review. Here are replies to your comments above.

The text jumps on focus. It should stay in the same line.

I'm digging into this and will re-request your review when I have a solution committed.

Focus styling on Tags not up-to-date with updated outlines.

I hadn't merged in the latest main with updated tag styling - done now.

Validation Warning outline color doesn't match to updated focus outlines

Fixed in latest deploy.

I see that the Input clears text on the second Escape press. Do you think we should follow that behavior here?

I actually have this commented as a TODO in the underlying container 😉. We can explore this option as a follow-on. But, since the keyboard interaction is optional, I think the default should match what we currently have in Garden.

Is there an enhancement opportunity where the keyboard can move the focus between tags with the arrow keys?

I don't think so. This results in an accessibility violation with the current <Multiselect>. I do think there is an opportunity for design research that opens up improved possibilities for multiselectable tag keyboarding while staying true to a11y specs.

jzempel · 2023-06-21T19:46:13Z

@Francois-Esquire re:

When multi-select is enabled with 2 or more tags and limited space, I'm seeing some overlap which may be undesirable

I'm not super concerned about this as the native scrollbar is better left alone – and isn't present by default (without enabling in system settings).

jzempel · 2023-06-21T22:49:38Z

@lucijanblagonic the latest commit addresses...

The text jumps on focus. It should stay in the same line.

PR is ready for your re-review

lucijanblagonic

Everything looks good! 🙌

jzempel added 30 commits March 28, 2023 13:51

Initial combobox.next scaffold

38f4e96

Initial combobox.next view stying

bef48fb

Continued combobox styling

8c00f65

Initial combobox.next Option view styling

81d782b

Continued combobox option styling

9f0fa30

Handle combobox option type styling

a223ca5

Initial combobox.next OptGroup view styling

4428e38

Add svg-icons dependency

f566fbe

Simplify OptGroup styling

67ea1aa

Fix cursor styling

7da1dfc

Fill out Listbox API

866baa7

Initial useCombobox plumbing

76cf176

API & styling tweaks

ae6737c

Merge branch 'main' into jzempel/combobox

6f0795e

Shuffle src files in prep for future Menu components

37a95c8

Add ComboboxStory and use children for initial Option extraction

1467131

Configure Option to allow for null value

bde3a40

Remove null Option value concept as isDisabled produces the desir…

939c181

…ed ARIA

Revert isAutocomplete to undefined default

a2ebda3

Spread OptGroup props

0429c36

Merge branch 'main' into jzempel/combobox

536ae4d

useWindow

dbf3318

Use window environment and add listboxAriaLabel prop

c2c1791

Simplify listbox props

3a1e382

Initial multiselectable tags implementation

19fadcf

Merge branch 'main' into jzempel/combobox

00ce2de

Implement maxTags with "show more" action

f769027

rearrange Combobox

f12503b

Merge branch 'main' into jzempel/combobox

8dbf7ed

Fix focus interaction

51dccc1

zendesk-garden deployed to staging June 15, 2023 14:49 View deployment

Francois-Esquire reviewed Jun 20, 2023

View reviewed changes

packages/dropdowns.next/README.md Outdated Show resolved Hide resolved

Francois-Esquire reviewed Jun 20, 2023

View reviewed changes

packages/dropdowns.next/src/elements/combobox/Option.tsx Show resolved Hide resolved

packages/dropdowns.next/src/elements/combobox/OptGroup.tsx Show resolved Hide resolved

Updates based on @Francois-Esquire review

2afa068

zendesk-garden deployed to staging June 20, 2023 18:22 View deployment

geotrev reviewed Jun 20, 2023

View reviewed changes

jzempel added 3 commits June 21, 2023 09:47

Merge branch 'main' into jzempel/combobox

4c82a41

Remove unused useEffect dependencies

9addb2e

Fix warning focus color

66dc587

zendesk-garden deployed to staging June 21, 2023 14:57 View deployment

Francois-Esquire reviewed Jun 21, 2023

View reviewed changes

jzempel added 2 commits June 21, 2023 15:38

Move styled component out of element component

9d80634

Use consistent COMPONENT_ID taxonomy

d09218c

jzempel requested review from Francois-Esquire and geotrev June 21, 2023 19:40

zendesk-garden deployed to staging June 21, 2023 19:59 View deployment

jzempel added 2 commits June 21, 2023 16:59

Fix combobox min-height

16d608b

Adjust input/value sizing

b54873a

zendesk-garden deployed to staging June 21, 2023 23:03 View deployment

lucijanblagonic approved these changes Jun 22, 2023

View reviewed changes

geotrev approved these changes Jun 22, 2023

View reviewed changes

jzempel merged commit 43d0410 into main Jun 22, 2023
1 check passed

jzempel deleted the jzempel/combobox branch June 22, 2023 18:38

jzempel mentioned this pull request Jul 24, 2023

chore(combobox): prevent optionTagProps state bloat #1584

Merged

7 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add refactored `Combobox` component #1559

feat: add refactored `Combobox` component #1559

jzempel commented Jun 13, 2023 •

edited

Loading

Francois-Esquire left a comment

jzempel commented Jun 20, 2023

geotrev left a comment

lucijanblagonic commented Jun 21, 2023

Francois-Esquire left a comment •

edited

Loading

Francois-Esquire Jun 21, 2023

jzempel Jun 21, 2023

Francois-Esquire Jun 22, 2023

jzempel Jun 22, 2023

jzempel commented Jun 21, 2023

jzempel commented Jun 21, 2023

jzempel commented Jun 21, 2023

lucijanblagonic left a comment

feat: add refactored Combobox component #1559

feat: add refactored Combobox component #1559

Conversation

jzempel commented Jun 13, 2023 • edited Loading

Description

Detail

Checklist

Francois-Esquire left a comment

Choose a reason for hiding this comment

jzempel commented Jun 20, 2023

geotrev left a comment

Choose a reason for hiding this comment

lucijanblagonic commented Jun 21, 2023

Francois-Esquire left a comment • edited Loading

Choose a reason for hiding this comment

Francois-Esquire Jun 21, 2023

Choose a reason for hiding this comment

jzempel Jun 21, 2023

Choose a reason for hiding this comment

Francois-Esquire Jun 22, 2023

Choose a reason for hiding this comment

jzempel Jun 22, 2023

Choose a reason for hiding this comment

jzempel commented Jun 21, 2023

jzempel commented Jun 21, 2023

jzempel commented Jun 21, 2023

lucijanblagonic left a comment

Choose a reason for hiding this comment

feat: add refactored `Combobox` component #1559

feat: add refactored `Combobox` component #1559

jzempel commented Jun 13, 2023 •

edited

Loading

Francois-Esquire left a comment •

edited

Loading