Combobox Accessibility Issues

[BryceStevenWilley]

Came across a use of a combo box in ILAO's Fee Waiver interview when doing an accessibility audit. There are a few accessibility issues I found when using it with a screen reader and keyboard:

• There is a button on the right side of the field that doesn't have any labels. Screen readers will announce it as just "Push button" or "button". I think the right way to describe it would be as a collapsible button, but...
• when you use keyboard controls to press the button, it quickly shows the available items, but then quickly selects the top option. What's actually happening is that on key down, the available items are shown, and then you can use the arrow keys to navigate and choose the right option, and on key up, that option is selected and entered into the combobox input field. This definitely isn't standard keyboard controls for a button like that (having to hold down one key while using others to choose something), and should be changed to be on 2 different key presses.
  • after writing this, I discovered that this only seems to happen on Firefox on Ubuntu, and not Firefox on windows, so I'm not sure how to start debugging OS differences here.
• the options available in the combobox aren't read out on the screen reader. With Orca (Ubuntu), nothing is read at all, and with NVDA (windows), it says "blank" each time you navigate to the next year selection.
• If you enter an invalid number and navigate to continue, the validation message pops up, but nothing is read out on with the reader (at all). If you navigate back to the combo box, it won't read out the issue either. If you just didn't enter anything it will read out "this field is required".

The combobox is a separate bootstrap plugin that we would have to patch separately from docassemble. There haven't been any substantive merged PRs since 2019, so our best bet is to patch it ourselves, see if the author has the time to review and merge, and if not, convince Jonathan to use our fork instead.

Here's an image of what the combobox looks like, and some example code to try it out.

question: |
  What year were you born?
fields:
  - Year of birth: birth_year
    input type: combobox
    datatype: integer
    maxlength: 4
    min: ${ today().year-120 }
    max: ${ today().year }
    code: |
      reversed(range(today().year-120, today().year+1))

[BryceStevenWilley]

Since this is (IMO) a pretty big accessibility issue, and there are a number of things to patch (that I would have to figure out, given I'm not a front-end expert yet), I might recommend that our interviews avoid combo box selections (at least the e-filing ones).

[BryceStevenWilley]

From our conversation at the coding deep-dive:

• the particular use case of combo boxes should be to always let a user add their own option, even if not present in the drop down.
  • the other alternate way of doing this in a docassemble interview is a dropdown with the "other" choice, and a show if that let's you add another
• it'll be a complicated change either way, so we will have to defer a sweeping audit / change of existing interviews that use this feature, likely until we add e-filing features to them.

Our priorities here should be to:

• [X] ~find a better plugin if possible, one that was built with accessibility in mind from the get go~ (none really)
• [ ] research the alternatives to using a combo box
• [ ] As a stopgap, in the existing interviews that do use combo boxes, we should note that they're deprecated and add a link to this interview and to the documentation page that describes why we're suggesting avoiding it for now.

[BryceStevenWilley]

Did a little more searching for other plugins, and unfortunately the only one I found was https://github.com/cchantep/bootstrap-combobox, which isn't really a combobox, it's just a dropdown. There are a lot of dropdown plugins, but not a lot of combo boxes.

It's not a plugin, but w3 does have a (not-production ready) version, which looks good, but likely won't be a drop-in-replacement when trying to get the styles we want.

[BryceStevenWilley]

Some quick updates here: I forgot that docassemble already it's own fork of most things, including the bootstrap-combobox plugin. So that makes it easier to merge into docassemble more quickly (might also merge upstream if I have the time).

Realizing this I was able to fairly quickly make the combobox much more accessible, with the right aria properties and roles. The code is fairly done, and in this commit. I have an fairly extensive testing plan though, because I want to do this right on mobile and different operating systems, and am kinda doing it on my free time to learn more about front-end stuff.

Keeping track of the testing plan here, cause I might as well.

OS/platforms

• [x] Windows
  • [x] Firefox
  • [x] Chrome
  • [x] Edge
• [ ] Mac
  • [ ] Safari: not working. Experience not degraded, but options still aren't read out.
  • [x] Chrome
• [ ] Android
  • [x] Chrome
  • [ ] Firefox: partial. Selecting options doesn't work like it does in chrome when using TalkBack, and Firefox doesn't have enough mobile debugging tools to help understand why
• [ ] iOS: still need to test
  • [ ] Safari
  • [ ] Chrome (though IIRC, all browsers on iOS are the same engine)
• [ ] ubuntu
  • [ ] Firefox: ubuntu screen reader (orca) refuses to work with Firefox. :(
  • [x] Chrome

Behaviors to test

Checked behaviors work on all tested browsers so far.

• [x] only keyboard controls
  • [x] can tab into the widget
  • [x] down and up to select existing options
  • [x] enter or tab to select it
  • [x] escape closes the dropbox
  • [ ] screen reader works on each action
• [x] only mouse
  • [ ] click to select (test box or button should expand)
  • [x] scroll / selection works
  • [x] toggle with just the button
  • [x] x button clears it
  • [ ] screen reader
• [x] typing
  • [x] can focus on the text input with a click / tap
  • [x] can type and filter data shows
  • [x] type partial and arrow keys down / tap to select
  • [ ] screen reader works and reads normally

[BryceStevenWilley]

https://github.com/jhpyle/docassemble/pull/581 was merged upstream and released as 1.4.13. However there are a few remaining things to address here:

• the known bugs:
  • [ ] Android + Firefox + Talkback doesn't handle focus well to chose from the filtered list
  • [ ] Mac + Safari + VoiceOver just doesn't work / read out the options. Need to learn more about talk back, and figure out what is supported and what's cause the specific issue.
• [ ] still needs testing on iPhone. Not optimistic with how VoiceOver behaved on Mac though
• [ ] The issue with validation messages not being read (copied below) hasn't been addressed. Even though I'd say the example given was a bit non-standard, validation code on comboboxes is still possible, so should be addressed at some point.

If you enter an invalid number and navigate to continue, the validation message pops up, but nothing is read out on with the reader (at all). If you navigate back to the combo box, it won't read out the issue either. If you just didn't enter anything it will read out "this field is required".

[nonprofittechy]

@BryceStevenWilley can we get an update on upstream status. I've seen at least one more changelog entry dealing with combobox. Is it still not fully accessible?

[BryceStevenWilley]

None of those changes have dealt with the known issues listed in https://github.com/SuffolkLITLab/docassemble-AssemblyLine/issues/548#issuecomment-1292238147. Mac / VoiceOver support is the biggest one remaining; I'd be willing to mark this as closed if we could get that working. I haven't had to time to dive into VoiceOver / Safari compatibility stuff though.