Discussion: making the hover accessible

[aiday-mar]

We are currently working on the accessible hover, and would like to ask feedback from @jooyoungseo and @rperez030 concerning the issue below.

Last iteration, we started working on making the hover accessible to screen reader users. To this effect, we have started working on the accessible hover view and the accessible hover help which you can toggle with the option+f1 and option+f2 keys on MacOS. So far, the view and the help have been developed so as to display markdown hover content only. Currently they do not display other content like diagnostics, information relative to the color picker or the go-to-definition previews. After discussing this with team members, we are no longer sure if we should go forwards with the accessible hover view/help implementation and instead let users navigate normally with the screen reader. The reasons for this are as follows:

• Navigation in the editor hover is richer than navigation in the accessible hover view/help. Using a screen reader you can navigate to the links/tables/images in a hover. The accessible hover view/help renders only string content so to navigate to links and to table cells in plain-text we would have to develop some special commands/navigation methods.
• Since the accessible hover view/help renders string content it will have to represent textually certain non-textual HTML elements. The textual representation may therefore be inaccurate, leading to confusion among screen reader users.
• Screen reader users are a priori already accustomed to using screen readers on the web, so we suppose they should not find it difficult to navigate in the editor hover.
• We are unfortunately limited on time and would like to explore potential simpler solutions to improve the accessibility of the hover.

To better understand the hover accessibility issue, I have used VoiceOver on MacOS to try to navigate within the hover and read text within it word by word and letter by letter. I have found one can use the following steps to navigate in the hover word by word:

1. Turn on a screen reader, toggle the screen reader mode.
2. Place the cursor in the editor, show and focus the hover by pressing Cmd+K, Cmd+I in the screen reader mode
3. Focus on a specific hover part using Tab
4. Use VO-RightArrow and VO-LeftArrow in order to navigate to a specific paragraph
5. Enter into the paragraph using VO-Shift-DownArrow
6. Once inside the paragraph use the VO-LeftArrow and VO-RightArrow in order to navigate word by word. Press VO-W in order to read the word letter by letter.
7. Come out of the paragraph using VO-Shift-UpArrow
8. Continue navigation this way

We could let the screen reader users navigate the hover with the steps above. We would still like to improve the accessibility of the hover however, so our proposal is as follows:

• Make all the hover parts focusable. Indeed, currently not all sub-hover parts are focusable (like for example the hover part containing the color-picker that appears when you hover over a color decorator).
• Explore better aria-roles for the hover and the sub-hover parts. The hover has aria-role tooltip which is perhaps not appropriate for the editor hover since it contains a lot of elements other than text like images, links and buttons. We should tweak as well the aria labels to signal better to screen reader users what context they are in.
• Keep the accessible hover help and show there the commands relative to the hover. Ie: instead of showing the hover content we would show the actions that can be taken relative to the hover and their corresponding keybindings. The accessible hover view would be removed.

We would like to ask you @jooyoungseo and @rperez030 what you think of the proposal above, and also generally share with us your thoughts about the current state of the hover accessibility. Do you find it easy to navigate in the hover with a screen reader? What do you think could be improved? You may use the following TypeScript code example to make a hover appear that contains an image, a link and a table for testing:

/**
 * [![VS Code screenshot](https://user-images.githubusercontent.com/35271042/118224532-3842c400-b438-11eb-923d-a5f66fa6785a.png)](https://code.visualstudio.com)
 *
 * | Month    | Savings |
 * | -------- | ------- |
 * | January  | $250    |
 * | February | $80     |
 * | March    | $420    |
 *
 * ### Examples
 * See [title](https://www.example.com/) for examples
 */
export interface SomeInterface {
    someString: string;
}

cc @meganrogge @isidorn @hediet @alexdima

[rperez030]

hi @aiday-mar. I'm happy to help with this, but the hover is currently used in a multitude of places, likely with very different requirements. in fact, I'm personally not very familiar with this particular use case. Please feel free to schedule a meeting, and maybe we can go into more details.

[jooyoungseo]

@aiday-mar -- I have been using the Accessible Hover View a lot on a daily basis. Since whether to use Alt+F2 View or to navigate the rich content via screen reader virtual cursor is a user-gesture action, I personally don't understand why we had to take out the Accessible View option here. Once Ctrl+K, Ctrl+I is pressed, users can choose between two different navigation strategies. Alt+F2 view is not automatically populated. What's confusing here?

[jooyoungseo]

@aiday-mar In terms of the aria role, I think document role is more appropriate here because, in theory, it forces screen readers to activate their virtual cursor which is necessary in order to navigate rich content elements.

[aiday-mar]

Note: posting the same comment again because when I originally posted it, it appeared twice and on deletion, it removed both. The following is the same comment.

Hi @jooyoungseo thank you for the response and the valuable feedback. I believe the main driving force of the proposal is that we are on limited time and would like to find a simpler solution to implement the accessible hover. I will discuss your feedback with colleagues. I'll look at the document aria role thank you.

Hi @rperez030 thank you for the response. I have suggested a meeting in our internal group conversation.

[rperez030]

@jooyoungseo my concern with the document role is that it may not be appropriate for other use cases where the tooltip is used. if I'm debugging, for example, pressing the CTRL +K followed by CTRL +I key-binding with focus on an array, or the instance of a class, focus moves to a UI where I can inspect the content of that variable, and the virtual cursor wouldn't be my preferred mode of interaction in that situation. In the case of tooltips that require a significant amount of interaction with the keyboard, which I probably wouldn't call tooltips in the first place, the dialog role seems like a more appropriate one.

[jooyoungseo]

@rperez030 -- Could you please teach me the difference between document and dialog role in this context? Isn't dialog role using document property under the hood anyhow?

[rperez030]

Of course! @jooyoungseo the document role is an indication, particularly to Windows screen readers, that the content is supposed to be read with the virtual cursor, especially in the context of a web app that uses application role to restrict navigation focus / pc cursor. Additionally, NVDA and now a days also JAWS will trap the virtual cursor when focus enters a container with role document so that we can use CTRL +home or CTRL +End, for example, to move between the beginning and the end of the document without moving to the underlying application. VSCode currently uses that to display the release notes, or the rendered version of a markdown file. There is an issue with JAWS that currently disables the virtual PC cursor entirely in VSCode which prevents the document role from working as expected, and I'm working with them to address that, hopefully soon.

The dialog role in the other hand doesn't instruct the screen reader to change the active navigation mode when it receives focus, but communicates the idea that focus is entering on a child window. it also accepts attributes such as aria-labelledby to indicate the title of that window, aria-describedby or aria-description to associate descriptive text to it, or aria-modal to indicate whether virtual navigation must be restricted or not to the dialog

To summarize, the dialog role is in a way similar to the document role, but it doesn't initiate virtual navigation necessarily, and provides the added flexibility to tell whether it should be treated as modal or not. The dialog role is also honored by voiceover, whereas document role is only applicable to windows screen readers that have the virtual buffer.

Does it make sense?

[jooyoungseo]

@rperez030 -- Thanks for your kind explanation! :)

As far as I know, document role is also valid for Linux screen readers, such as Orca. I think VoiceOver is an exceptional case.

For JAWS not activating virtual cursor in VSCode, I personally configured to make it work. In VSCode, you can press JAWS+6 and type "virtual" and ArrowDown until "Use Virtual PC Cursor" and turn it on. However, I agree that this should be enabled by default.

[rperez030]

@jooyoungseo you are quite right about orca. In the case of voiceover, Chromebox and the mobile screen readers, they all simply follow a different paradigm where the document role is not applicable.