Components: Add a WAI-ARIA compliant custom select. #17926

epiqueras · 2019-10-13T19:54:04Z

Description

This PR implements a fully accessible and customizable select component with individually style-able items, in the @wordpress/components package.

It uses Downshift, a library that will be very useful for any of our other complex a11y input needs.

It has some modifications hooked on top of it to make it fully compliant with the spec. These modifications might soon make it into a future Downshift release and at that point we should remove them from our implementations.

The story for the component is:

https://deploy-preview-17926--gutenberg-playground.netlify.com/design-system/components/?path=/story/customselect--default

How has this been tested?

It was verified that the component works as expected.

Although the libraries used are heavily tested, unit testing this implementation once the approach is approved wouldn't be a bad idea to make sure we never regress to configuring something incorrectly.

Screenshots

Types of Changes

New Feature: @wordpress/components now has a fully WAI-ARIA compliant custom select.

Checklist:

My code is tested.
My code follows the WordPress code style.
My code follows the accessibility standards.
My code has proper inline documentation.
I've included developer documentation if appropriate.

packages/components/src/custom-select/index.js

youknowriad · 2019-10-14T09:28:49Z

Design-wise the options should be shown in a Popover I think.

epiqueras · 2019-10-14T18:38:37Z

Design-wise the options should be shown in a Popover I think.

I want to tick all the a11y boxes first, and then see what we can do with styling without regressing.

tellthemachines

Good work on this! Checked with VO/Safari and NVDA/Firefox and it's behaving pretty well on both, apart from the repetition of "Font size" label I commented on below.

One thing I noticed on NVDA but was unable to reproduce consistently is that sometimes the font size button is announced as "expanded" when focused, and with the dropdown closed. I realise this may not be very helpful, will try and debug further 😄

Another potential issue is that focus is not being limited to the component when it is open, so if we open the dropdown and then press tab we move out of it but the dropdown stays open. Shift-tabbing until the font size button is focused again allows us to continue interacting with the dropdown, but after that pressing esc will not close it.

Also, minor styling issue on Firefox and IE:

Removing display: inline-flex and adding text-align: left to components-button will fix it for both browsers 🙂

tellthemachines · 2019-10-18T00:07:49Z

packages/components/src/custom-select/index.js

+import { Button, Dashicon } from '../';
+
+const itemToString = ( item ) => item.name;
+// This is needed so that in Windows, where


Just checked this on Windows and the behaviour is identical to Mac: on arrow down/up the menu opens. I don't see that as a major issue though. If we did want the arrow keys to work with the menu closed we'd probably have to make sure the options always render, and hide them with CSS, but then it's not clear that we could limit that behaviour to Windows 🤷‍♀

the issue here is the returned changes. @epiqueras just return the selectedItem because if you also return the rest of the changes then one of them is isOpen that comes as true :D

tellthemachines · 2019-10-18T00:18:46Z

packages/components/src/custom-select/index.js

+				{ ...getLabelProps( { className: 'components-custom-select__label' } ) }
+			>
+				{ label }
+			</span>


Any reason not to make this an actual <label> instead of using aria-labelledby? Then we might not need the aria-label. Having both, VoiceOver and NVDA are announcing the button as "Font size font size". Would be good to avoid the repetition.

The way I wrote useSelect was with having a physical label that also labels the button and the menu. As I understood there was an issue with Dragon Speech because of this.

Having said that, anyone tried Dragonn Speech to select an item then check what the console.log prints?

Any reason not to make this an actual instead of using aria-labelledby? Then we might not need the aria-label. Having both, VoiceOver and NVDA are announcing the button as "Font size font size". Would be good to avoid the repetition.

Dragon Speech still needs the explicit aria label on the toggle to be able to click on it.

Having said that, anyone tried Dragonn Speech to select an item then check what the console.log prints?

It registers a click on the toggle button I think:

In that test^^ "Small" was already the selected item.

Hmm can we use the semantic <label> and add aria-label too? @enriquesanchez 's testing on #17418 showed that approach works with Dragon, and aria-label seems to supersede <label> so the screen readers don't read out both.

With the current font size controls we're already having an issue where VoiceOver reads out the fieldset legend twice (that's a VO bug, but still annoying), so it would be good to avoid unnecessary repetition wherever we can.

epiqueras · 2019-10-18T21:11:24Z

@tellthemachines Thanks for the help!

Removing display: inline-flex and adding text-align: left to components-button will fix it for both browsers 🙂

Done 😄

tellthemachines

We're getting there!

One remaining issue, apart from the comments I left: pressing Tab when the dropdown is open still causes focus to be moved to the button control. Subsequently pressing Esc will not close the dropdown, but pressing any arrow key will close it.

Also, would be good to test replacing the current font size picker with this component, to check focus management when entering/exiting it.

tellthemachines · 2019-10-22T00:54:28Z

packages/components/src/custom-select/index.js

+				{ ...getLabelProps( { className: 'components-custom-select__label' } ) }
+			>
+				{ label }
+			</span>


Hmm can we use the semantic <label> and add aria-label too? @enriquesanchez 's testing on #17418 showed that approach works with Dragon, and aria-label seems to supersede <label> so the screen readers don't read out both.

With the current font size controls we're already having an issue where VoiceOver reads out the fieldset legend twice (that's a VO bug, but still annoying), so it would be good to avoid unnecessary repetition wherever we can.

tellthemachines · 2019-10-22T00:56:47Z

packages/components/src/custom-select/style.scss

+	border: 1px solid $dark-gray-200;
+	border-radius: 4px;
+	color: $dark-gray-500;
+	display: initial;


I'm afraid IE doesn't support initial 🙀
Can we replace this with inline, which is iirc the default value for <button>?

enriquesanchez · 2019-10-22T22:31:44Z

I ran some tests of the component in https://deploy-preview-17926--gutenberg-playground.netlify.com/design-system/components/?path=/story/customselect--default with Dragon, NVDA and Voice Over.

Here are the videos of the test:

With Dragon: https://cldup.com/cihauaUTN4.m4v
So far with Dragon I haven't able to select an option from the list by saying "Click Large", but I'm able to do so if I use the "move up/down" commands to switch focus to an option and then say "press enter". I'm a fairly new user of speech recognition software, so I'm not sure how common or uncommon this flow is. That being said, I was able to interact with the component and select an option.

With NVDA: https://cldup.com/7n79VbZMo3.m4v (sorry for the shaky camera)
Besides "Font Size" being announced repetitively, the only thing that I felt was missing was that on Windows I can't change the selection by using the up/down keys, like on Mac.

With Voice Over: https://cldup.com/A12FmcNrSn.m4v
Same as with NVDA, "Font Size" is announced repetitively. Other than that, interaction was as expected.

tellthemachines · 2019-10-22T22:42:08Z

Besides "Font Size" being announced repetitively, the only thing that I felt was missing was that on Windows I can't change the selection by using the up/down keys, like on Mac.

@enriquesanchez this happens because NVDA is not switching into forms mode when entering this component. If you manually switch by pressing Insert+Space then you'll be able to use up/down keys. It would be worth investigating if it's possible to make NVDA switch automatically as that would be closer in behaviour to a native control.

aduth · 2019-12-03T23:20:58Z

It still needs to be included in the published package.json for Webpack to consider it for tree shaking:

The new webpack 4 release expands on this capability with a way to provide hints to the compiler via the "sideEffects" package.json property to denote which files in your project are "pure" and therefore safe to prune if unused.

https://webpack.js.org/guides/tree-shaking/#mark-the-file-as-side-effect-free

epiqueras · 2019-12-03T23:41:47Z

It looks like it will still try to tree-shake most things, but will trip up with things like HOCs without directives:

https://webpack.js.org/guides/tree-shaking/#clarifying-tree-shaking-and-sideeffects

@silviuavram can we add the sideEffects hint to make this more efficient?

silviuaavram · 2019-12-04T08:13:01Z

I am really interested to try this out, I will make changes on Downshift side if needed. Let me know on the progress please!

epiqueras · 2019-12-04T17:19:37Z

@silviuavram it's Downshift that is missing the sideEffects property, we need to add it there.

silviuaavram · 2019-12-04T17:23:27Z

Can you create a PR and I will look over it tomorrow? Thank you! Do we need to publish an alpha version to test if it works?

…

On Wed, 4 Dec 2019 at 18:19, Enrique Piqueras ***@***.***> wrote: @silviuavram <https://github.com/silviuavram> it's Downshift that is missing the sideEffects property, we need to add it there. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#17926?email_source=notifications&email_token=ACWAZAEBES6R3WBPJB3BDA3QW7RCXA5CNFSM4JAIMOL2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEF5YV4I#issuecomment-561744625>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACWAZAEFWUKASHJVNY2NJW3QW7RCXANCNFSM4JAIMOLQ> .

epiqueras · 2019-12-04T17:35:37Z

@silviuavram downshift-js/downshift#843

Do we need
to publish an alpha version to test if it works?

Yeah, that would be helpful. It should work, unless Downshift has side effects, but better to be safe.

silviuaavram · 2019-12-04T19:42:41Z

Thanks very much! I will publish an alpha tomorrow from that branch and test it out.

…

On Wed, 4 Dec 2019 at 18:35, Enrique Piqueras ***@***.***> wrote: @silviuavram <https://github.com/silviuavram> downshift-js/downshift#843 <downshift-js/downshift#843> Do we need to publish an alpha version to test if it works? Yeah, that would be helpful. It should work, unless Downshift has side effects, but better to be safe. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#17926?email_source=notifications&email_token=ACWAZACDGJCFX4WO4ZEKWXDQW7S6XA5CNFSM4JAIMOL2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEF533UQ#issuecomment-561757650>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACWAZADXQ3NX46KJ3SOKF23QW7S6XANCNFSM4JAIMOLQ> .

silviuaavram · 2019-12-05T20:15:11Z

I published downshift@3.5.0-alpha.0 and could not manage to properly test it. Maybe my testing project is not configured as it should. If you have any tips that will help me looking into it tomorrow that will be super helpful.

epiqueras · 2019-12-05T20:55:56Z

What was the issue?

…

On Thu, Dec 5, 2019 at 12:15 PM Silviu Alexandru Avram < ***@***.***> wrote: I published ***@***.*** and could not manage to properly test it. Maybe my testing project is not configured as it should. If you have any tips that will help me looking into it tomorrow that will be super helpful. — You are receiving this because you modified the open/close state. Reply to this email directly, view it on GitHub <#17926?email_source=notifications&email_token=AESFA2GOTNEADODBACKASW3QXFONDA5CNFSM4JAIMOL2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEGB76SQ#issuecomment-562298698>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AESFA2EGR6DXCORG43C43ETQXFONDANCNFSM4JAIMOLQ> .

silviuaavram · 2019-12-05T21:08:32Z

I probably did not know what to look for in the minified file. In the main.map.js I could still find all the exports (useSelect, Downshift, useCombobox) even though I only imported: import {useCombobox} from ‘downshift’. I probably did not configure the webpack in my test project correctly. Or it’s something wrong in Downshift’s rollup config or index.js. Or maybe it works and I could not figure tjat out from the minified file. I don’t know yet. On Thu, 5 Dec 2019 at 21:55, Enrique Piqueras <notifications@github.com> wrote:

…

What was the issue? On Thu, Dec 5, 2019 at 12:15 PM Silviu Alexandru Avram < ***@***.***> wrote: > I published ***@***.*** and could not manage to properly test > it. Maybe my testing project is not configured as it should. If you have > any tips that will help me looking into it tomorrow that will be super > helpful. > > — > You are receiving this because you modified the open/close state. > Reply to this email directly, view it on GitHub > < #17926?email_source=notifications&email_token=AESFA2GOTNEADODBACKASW3QXFONDA5CNFSM4JAIMOL2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEGB76SQ#issuecomment-562298698 >, > or unsubscribe > < https://github.com/notifications/unsubscribe-auth/AESFA2EGR6DXCORG43C43ETQXFONDANCNFSM4JAIMOLQ > > . > — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#17926?email_source=notifications&email_token=ACWAZABWTCLZN6KD6HMHY63QXFTF5A5CNFSM4JAIMOL2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEGCDWII#issuecomment-562314017>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACWAZAGQVQCTX7ZLIGTEZ5TQXFTF5ANCNFSM4JAIMOLQ> .

epiqueras · 2019-12-05T22:35:23Z

Can you push your test somewhere?

silviuaavram · 2019-12-06T08:35:24Z

https://github.com/silviuavram/check-downshift-shake tried it here. But I probably did not configure webpack or babel. The alpha version contains useCombobx along with the sideEffects in package.json.

silviuaavram · 2019-12-06T14:11:29Z

I updated the repo with some things I tried on babel. Still it imports the whole things in the ES bundle.

epiqueras · 2019-12-06T17:40:10Z

Yeah, you're building in development mode:

https://github.com/silviuavram/check-downshift-shake/blob/27a5fcb763ce2b837017a948a6c859ccfa0a0148/package.json#L11-L12

See, https://webpack.js.org/guides/tree-shaking/.

silviuaavram · 2019-12-06T17:42:53Z

I tried to build with —production as well. The es has the same size as the cjs.

…

On Fri, 6 Dec 2019 at 18:40, Enrique Piqueras ***@***.***> wrote: Yeah, you're building in development mode: https://github.com/silviuavram/check-downshift-shake/blob/27a5fcb763ce2b837017a948a6c859ccfa0a0148/package.json#L11-L12 See, https://webpack.js.org/guides/tree-shaking/. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#17926?email_source=notifications&email_token=ACWAZAGDSWVR44R3RIMB25TQXKE7ZA5CNFSM4JAIMOL2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEGE2LHQ#issuecomment-562668958>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACWAZAEL6VZESKP6KJFGAKTQXKE7ZANCNFSM4JAIMOLQ> .

epiqueras · 2019-12-06T18:24:34Z

I just debugged this and it's probably because of how Downshift bundles its esm module.

There are a lot of static property assignments in there like Downshift.stateChangeTypes = stateChangeTypes; and useCombobox.stateChangeTypes = stateChangeTypes$2;.

Some prior discussion:

downshift-js/downshift#380

silviuaavram · 2019-12-07T15:17:55Z

Looks good, I was also suspicious about those state change things while going through the bundled code. Thanks so much for looking into this!

The bad part is the fact that we need to deliver a breaking change to make the bundle tree-shakeable again: exporting those stateChangeTypes separately and removing the static allocation. Will check if indeed, with these changes, the problem will be fixed.

epiqueras · 2019-12-07T17:47:21Z

There are other workarounds:

You could break down the output into multiple files with their ESM imports intact and that would allow the sideEffects flag to work. Currently, Webpack evaluates the single output file, because there are used exports there, and it can't prune the unused ones because they are mutated. If they were imported and mutated from a different file, Webpack could use the sideEffects hint and avoid evaluating those files.
Another, perhaps easier change, would be to use the /*#__PURE__*/ annotations. They're like the sideEffects hint, but for statements instead of modules.

Related discussion: styled-components/babel-plugin-styled-components#245.

silviuaavram · 2019-12-07T18:53:12Z

Found a few problems with today's investigation:

The hooks were not tree-shaken because of

const validatePropTypes = getPropTypesValidator(useSelect, propTypes)

Downshift component not tree-shaken because of the static props stateChangeTypes and defaultProps!!!. The propTypes static one was correctly removed by a babel transpiler (I think) at bundle time, like:

process.env.NODE_ENV !== "production" ? Downshift.propTypes = {
  children: PropTypes.func,
  ...

Probably I could add this same check manually to the hooks, because I don't need that prop types check function to run in production. On the Downshift static fields stateChangeTypes and defaultProps maybe there is a solution with one of your suggestions?

epiqueras · 2019-12-07T19:13:36Z

Yeah, both should work, albeit the first one is a better long-term solution that will work for future code as well.

youknowriad · 2019-12-09T10:12:21Z

Any plans to add a README for this component.

epiqueras · 2019-12-09T22:07:53Z

#19026

adamsilverstein · 2019-12-10T23:22:48Z

With Downshift merged, we should reconsider using it elsewhere (eg for Author selection, page parent selection, etc... eg #7478).

@afercia I missed most of the work/conversation here - does the progress on Downshift address the feedback from the original ticket? shall I work on a new PR for you to review?

epiqueras · 2019-12-10T23:36:02Z

Yes, that is a good next step with it.

epiqueras added [Focus] Accessibility (a11y) Changes that impact accessibility and need corresponding review (e.g. markup changes). Needs Accessibility Feedback Need input from accessibility [a11y] Epic labels Oct 13, 2019

epiqueras added this to the Future milestone Oct 13, 2019

epiqueras requested review from ajitbohra, chrisvanpatten, gziolo, jorgefilipecosta, talldan and youknowriad as code owners October 13, 2019 19:54

epiqueras self-assigned this Oct 13, 2019

silviuaavram reviewed Oct 14, 2019

View reviewed changes

packages/components/src/custom-select/index.js Outdated Show resolved Hide resolved

silviuaavram reviewed Oct 14, 2019

View reviewed changes

packages/components/src/custom-select/index.js Show resolved Hide resolved

gziolo added this to In progress in WordPress 5.3 Must Have via automation Oct 14, 2019

gziolo mentioned this pull request Oct 14, 2019

Try adding a keyboard-navigable font size selector with visual feedback #17418

Closed

gziolo added the [Package] Components /packages/components label Oct 14, 2019

spacedmonkey mentioned this pull request Oct 14, 2019

Allow Users to Preview Fonts within the Font Dropdown ampproject/amp-wp#3317

Closed

youknowriad removed this from In progress in WordPress 5.3 Must Have Oct 14, 2019

epiqueras force-pushed the add/a11y-custom-select branch 2 times, most recently from 70ae1d5 to 421f9fb Compare October 17, 2019 18:18

tellthemachines reviewed Oct 18, 2019

View reviewed changes

karmatosed added this to Inbox in Tightening Up Oct 21, 2019

karmatosed moved this from Inbox to Ready to create in Tightening Up Oct 21, 2019

karmatosed moved this from Ready to create to In Progress in Tightening Up Oct 21, 2019

tellthemachines requested changes Oct 22, 2019

View reviewed changes

youknowriad modified the milestones: Future, Gutenberg 7.1 Dec 9, 2019

adamsilverstein mentioned this pull request Dec 23, 2019

Post author dropdown: add accessible-autocomplete #7385

Closed

4 tasks

diegohaz mentioned this pull request Apr 30, 2020

CustomSelectControl: read currently selected value on focus #21461

Closed

2 tasks

adamsilverstein mentioned this pull request Sep 16, 2020

Page parent selector with ComboboxControl. #25267

Merged

6 tasks

priethor removed the [a11y] Epic label Jul 24, 2023

Components: Add a WAI-ARIA compliant custom select. #17926

Components: Add a WAI-ARIA compliant custom select. #17926

Conversation

epiqueras commented Oct 13, 2019 • edited

Description

How has this been tested?

Screenshots

Types of Changes

Checklist:

youknowriad commented Oct 14, 2019

epiqueras commented Oct 14, 2019

tellthemachines left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

epiqueras commented Oct 18, 2019

tellthemachines left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

enriquesanchez commented Oct 22, 2019 • edited

tellthemachines commented Oct 22, 2019

aduth commented Dec 3, 2019

epiqueras commented Dec 3, 2019

silviuaavram commented Dec 4, 2019

epiqueras commented Dec 4, 2019

silviuaavram commented Dec 4, 2019 via email

epiqueras commented Dec 4, 2019

silviuaavram commented Dec 4, 2019 via email

silviuaavram commented Dec 5, 2019

epiqueras commented Dec 5, 2019 via email

silviuaavram commented Dec 5, 2019 via email

epiqueras commented Dec 5, 2019

silviuaavram commented Dec 6, 2019 • edited

silviuaavram commented Dec 6, 2019

epiqueras commented Dec 6, 2019

silviuaavram commented Dec 6, 2019 via email

epiqueras commented Dec 6, 2019

silviuaavram commented Dec 7, 2019

epiqueras commented Dec 7, 2019

silviuaavram commented Dec 7, 2019 • edited

epiqueras commented Dec 7, 2019

youknowriad commented Dec 9, 2019

epiqueras commented Dec 9, 2019

adamsilverstein commented Dec 10, 2019

epiqueras commented Dec 10, 2019

epiqueras commented Oct 13, 2019 •

edited

enriquesanchez commented Oct 22, 2019 •

edited

silviuaavram commented Dec 6, 2019 •

edited

silviuaavram commented Dec 7, 2019 •

edited