[a11y] Suggestion details are not available to screen readers

[jjaeggli]

Does this issue occur when all extensions are disabled?: Yes

• VS Code Version: Monaco 0.34.1
• OS Version: Mac OS 12.6.1, Windows 10 20H2 Build 19042.2251

Steps to Reproduce:

1. Enable screen reader (JAWS 2020, Voiceover)
2. Open Monaco https://microsoft.github.io/monaco-editor/index.html
3. On a new line, type a code snippet to autocomplete, ie "window.a". The autosuggest overlay will appear.
   • screen reader reads name and type declaration of first selected item.
4. Toggle auto suggest details (click right chevron on highlighted item, or press ctrl+i / cmd+i)
   • Screen reader will not read information in the suggestion overlay
   • User is not notified that there is additional content on the screen
   • User is not provided information about viewing additional content
   • User cannot use arrow keys / change screen reader navigation modes to navigate to the content as these are handled by the editor and close the overlay

Expected Behavior

1. When the suggestion overlay appears, it is indicated to the user that there is a subtree item which they are able to view
2. When using a keyboard modality to navigate the suggestions list, a command is made available to users to interact with the details item
3. Screen reader users are able to perceive documentation for suggestions which is provided to sighted users
4. A proper tree-treeitem relationship is used to define the association between the autosuggest and details overlays. See: https://www.w3.org/WAI/ARIA/apg/patterns/treeview/

In its current state, this has the fundamental issue in that it provides information to sighted users that it does not make available to screen reader users. More specifically, WCAG 2.1 1.3.1 Level A states:

The intent of this Success Criterion is to ensure that information and relationships that are implied by visual or auditory formatting are preserved when the presentation format changes. For example, the presentation format changes when the content is read by a screen reader or when a user style sheet is substituted for the style sheet provided by the author.

The structure of the information provided, according to this criteria, is also relevant and should be conveyed to users.

[vscodenpa]

Thanks for creating this issue! It looks like you may be using an old version of VS Code, the latest stable release is 1.73.1. Please try upgrading to the latest version and checking whether this issue remains.

Happy Coding!

[jjaeggli]

Hi Johannees, I wanted to know if there had been any discussion of this issue, and if there was a proposed solution in mind. The complicating factor is that keyboard controls required to navigate the tree (left-right) are also required to navigate within the editor. As the suggest popup can occur automatically, using navigation keys would interfere with the user's workflow.

One possibility is that the tree content is automatically announced using an aria-live region after a timeout. The documentation would not be navigable but the same content would be presented to the user.

Another possibility is that when using a specific key to invoke the suggestion popup, ie. ctrl-space, the list popup becomes effectively a modal dialog, and must be dismissed via escape. This would allow navigation within the list via keyboard, but would be potentially disruptive to existing users. Additionally, the popup would now have two modes, "passive" and "interactive" which could also be confusing.

Currently, vscode users understand the nature of the popup intuitively - if they need to navigate and the suggestion is open, they instinctively hit escape to dismiss the box. Any change which traps navigation within the dialog may not actually significantly impact users if they reflexively hit escape to navigate already.

[jjaeggli]

Another issue I've identified relating to the suggest tree structure is that the ">" (tooltip: "Read more") and overlay "X" close behave as toggles but are not identified as such. Currently they provide mouse only behavior because the overlay itself is mouse only, and as we've discussed is not accessible. An example of the overlay is here:

">" toggles sets the state of "show more always on" and "x" toggles the state of show more as always off.

The issues here are:

1. These buttons don't accurately represent the function of being a toggle for this overlay.
2. These buttons are non-focusable and pointer-accessible only - tab serves a different purpose within the editor
3. Visual-keyboard-only users don't have an easy way of activating these
4. Even for visual users without assistive technology, knowing that there is more documentation for a suggestion requires moving hands from keyboard to pointing device to hover the ">" read more arrow or "x" to dismiss. Documentation is not always present, and depends on what is provided by language support.

Suggestions on how to handle this:

1. Include a persistent ">" for the suggested item if there is more text available, indicating that the tree can be expanded further.
2. Use the keyboard combination "shift+arrow" to expand or collapse the documentation or tree node.
3. When "shift+arrow right" is used, focus is moved to the expanded node for screen reader users. "shift+arrow left" will collapse the node
4. When up or down arrow is used within the expanded documentation node, the focus will move to the next or previous suggestion item (branch) within the tree, but leave the documentation open or "toggled on".
5. "use shift+-> to expand" is shown at the bottom of the suggest when documentation is available for items within the suggest. This label will be specified with "aria-describedby" for the tree.

This solves the needs of making the tree screen reader and visual keyboard-only user friendly.

Questions:

1. When escape is used within a focused leaf node, should only the leaf and not the entire tree be closed?
2. Should a literal toggle button be present to toggle the expanded document view? What other UI patterns exist within VSCode to support this, and how should this be placed? Ideally a toggle button would toggle would expand / collapse the node using the same button. The ">" could become the toggle. Ie. switching between ">/<". This would also reduce mouse navigation.

[jjaeggli]

After working with this further I determined a better minimal approach to resolving this issue.

1. Use the same existing keyboard controls (ctrl+space, ctrl+i to toggle documentation overlay).
2. Mouse controls "Read more" and "Close" should receive button roles and be visible to screen readers, even though they are not tab focusable. Screen reader assisted pointer users and voice control users may still use these controls.
3. Change the documentation output to be the aria description using aria-describedby. Therefore screen readers will read this after the suggestion label and will be clearer. Example:

Current:

DisplayPositionclass DisplayPosition, Selected (1 of 1)

With aria-ariadescribedby:

DisplayPosition, Selected (1 of 1), class DisplayPosition

The description is always announced as either with the expanded documentation overlay or the inline description the content is always visible (although often truncated when displayed inline).

This still disadvantages screen reader users to some degree as there is no ideal way to perform line by line navigation in the documentation box. Reaching this is still nearly impossible when using content navigation controls.

[jjaeggli]

I found what I believe is another potential approach. It looks like there is a partially implemented feature from ~6 yrs ago to focus the suggest details as can be seen here:

https://github.com/microsoft/vscode/blob/a650b6b3bd7e0037c2fc956376896942c60e6067/src/vs/editor/contrib/suggest/browser/suggestWidget.ts#L679

The toggleDetailsFocus method is currently bound to the ctrl + alt + space key combination. Therefore the current behavior is:

1. ctrl + space : suggest opens suggest from the editor
2. ctrl + space : opens suggest details for the selected listitem
3. ctrl + alt + space : applies the focused state to the suggest details

The implementation is currently incomplete. All that happens currently when suggest details receives the focus state is that the style is changed. The overlay does not receive focus, and screen readers are not able to interact with the dialog. However if this._details.widget.domNode.focus(); is added when entering the Details state, the screen reader is then able to use content navigation keys to interact with the content, which is actually what is needed here.

State management needs to be properly handled for exiting the details state.

• If ctrl + alt + space is pressed again while in the details state, focus should return to the list item.
  • this is slightly problematic if focus moves elsewhere in the document through some other means.
• If the current selection is changed, the "focused" state is removed from the details widget
• if the suggest widget is exited, the focused state is removed.
• if ctrl + alt + space is pressed while details is not visible, it should probably also open and focus the widget.

[meganrogge]

@jjaeggli Thanks for looking into this important issue.

Since we often present sighted users with the details without requiring a user gesture, I'm wondering if we should make it configurable as to whether they're automatically read for screen reader users. While the details can be verbose, some screen reader users I've worked with have said that just pressing escape will silence the info, so they don't mind it.

[jjaeggli]

Sorry for the delay. The conclusion I came to on this was that when in a code window, the suggestions can contain rendered markdown text. Markdown has semantics which can be rendered as accessible HTML. In the suggestion documentation overlay, a visual user sees fully rendered markdown, however the details are only provided to the screenreader as a rendered text string without any of the associated semantics. Therefore it is possible to provide the same information to a screen reader if the documentation is focusable, reachable, and the user knows about it, however this is not currently the case. Just as examples, the rich suggestion could contain bulleted lists, code blocks, or links to other code, depending on what is provided by language support. Not providing proper semantics and not being reachable are problems for products based on vs web or monaco.

[jrieken]

This was actually fixed in September 2024 with https://github.com/microsoft/vscode/pull/190096.

With ctrl+alt+space you can now toggle focus between the editor and suggest details. When focus in the details part, screen readers will pick it up. To change the keybinding, the underlying command is toggleSuggestionFocus