Fixing Intelisense verbosity with screen readers

[pawelurbanski]

#65499 65499
The following simple fixes improve usability and accessibility with screen readers. I am currently working on an NVDA screen reader add-on module to make more improvements.
I am not a TypeScript developer, and therefore someone more knowledgeable will need to clean my code. I am available to give feedback and do testing.

Fixed the alert implementation, which was reporting how many times a particular spoken item occured. It is too verbose, for example when editing code and navigating possible choices by typing and removing item names to quickly hear what is suggested.

Fixed the suggestion controller, which was inserting an alert reporting accepted item, and also reporting that it was inserted into the document. It made the experience almost unusable for this sentence was read out on every insert. Such information is easily reported by screen readers in much better way, for it is also integrated with braille display handling.

Fixes to the suggestion list pop-up and documentation.

Need review and further implementation:
When suggestion appeard it reported with an alert the type of suggestion regular / snippet, and if the item had details - namely type information, or more expanded documentation.
While sighted users are not much interrupted by such hints, for they can observe them in parallel, screen readers, report everything, and on every item change.
Providing the completion item label only is sufficient.

Further fixes to the documentation widget appearing with contents.

Case 1: The details are simple: just a type / a few words hint.
It can be reported via the alert, ofr it is very breaif, and does not interrupt the flow.
Case 2: If the documentation details are longer, and rendered from markdown, or inserted from HTML documentation, the widget may/should have the aria-role="dialogue" added during the element creation. The focus should be placed at the beginning of the dialogue.
Read more / ** Read less / Close link buttons should have tabindex properties manually set, starting from 0 as it is in the specification.
Pressing either escape or keyboard activation of one of close button should return the focus to the last possition in the editor.
Important: We need to figure out how to split automatic reporting of short strings, and creating a dialogue when activating the documentation with a shortcut: Ctrl+Space.
A temporary work-around is to disable automatic parameter hints, and use them on demand, which in many cases may be prefered by the screen reader users.

[Microsoft Contribution License Agreements (msftclas)]

All CLA requirements met.

[Johannes Rieken (jrieken)]

Isidor Nikolic (@isidorn) Can you advice? We usually add (verbose) messages as feedback from testing and that seems to collide with real-world users. It's a tricky spot to be in

pawelurbanski Your change doesn't build (https://dev.azure.com/vscode/VSCode/_build/results?buildId=13521) because there are some strict null checks that fail.

[pawelurbanski]

Unfortunately, I am not a TypeScript developer. It builds from my local checkout with a branch, and I’m using the dev build to work. That is why I mentioned that somebody would need to help out and do some fixing here and there. I will try t find someone to help me out, though. As for the feedback case: 1. Testing sessions, are quite specific for they last an hour or so, but when you code you code for hours on days. 2. . You get familiar with the tools, and the code you are working on, so you do not need such verbose messages. 1. The message emitted by the suggestController is unbareable. 2. Hearing Accepting <CompletionItemLabel> inserted the following text <CompletionItemLabel> every time yu do completion makes the editor unusable. We could try and think of introducing a kind of accessibility.verbosityLevel setting? From: Johannes Rieken<mailto:notifications@github.com> Sent: Monday, January 28, 2019 11:26 AM To: Microsoft/vscode<mailto:vscode@noreply.github.com> Cc: Pawel Urbanski<mailto:pawel@pawelurbanski.com>; Mention<mailto:mention@noreply.github.com> Subject: Re: [Microsoft/vscode] Fixing Intelisense verbosity with screen readers (#67155) @isidorn<https://github.com/isidorn> Can you advice? We usually add (verbose) messages as feedback from testing and that seems to collide with real-world users. It's a tricky spot to be in @pawelurbanski<https://github.com/pawelurbanski> Your change doesn't build (https://dev.azure.com/vscode/VSCode/_build/results?buildId=13521) because there are some strict null checks that fail. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub<#67155 (comment)>, or mute the thread<https://github.com/notifications/unsubscribe-auth/ACwCQDjjU9DrrFUcIAQVmDgMvLOijTFEks5vHtBigaJpZM4aUGpU>.

[Johannes Rieken (jrieken)]

Unfortunately, I am not a TypeScript developer. It builds from my local checkout with a branch, and I’m using the dev build to work.

Should be quite easy. Just run yarn run strict-null-check. It will produce another set of local errors.

Hearing Accepting inserted the following text every time yu do completion makes the editor unusable.

You don't wanna hear anything then, right? The challenge is that some completion items are more complex, e.g. they insert more than the label. Like an import a the top of the file. Adding a verbosity setting is an option but ideally we make it work best without config needs.

[Isidor Nikolic (isidorn)]

Johannes Rieken (@jrieken) I would suggest that we listen to our users and not testers. So we try to be less verbose.

For this particular sample in the default case when the compleition item is not complex we could be less verbose, and only mention if it is a case when more than the label is inserted.

Once we have some something we can ask feedback from our other users which use a screen reader.

[pawelurbanski]

I brought up this case, for screen readers are doing a good job of reading out anything from the textarea, where you are paging content. Providing those alerts is trying to do the job of a screen reader. I am done coding a basic / simple NVDA add-on module, which improves the following: 1. Keeps the focus in the editor – it used to get back to browse mode after pressing escape when the suggest widget was visible when triggered. 2. I intercept hitting the enter key when completing to process the current line, and read back only what was inserted, so you do not get read out the same line, again and again after every completion. I will try to fix the null string error now and push to the branch and update my pull request. I am working on those features, for I think, that Visual Studio Code, with its small footprint, language server protocol, can be a fantastic replacement for its big brother. Combining what the screen readers can do, with your alerts as a kind of multidimentional way of providing information, can be a killer combination.

…

________________________________ From: Isidor Nikolic <notifications@github.com> Sent: Monday, January 28, 2019 2:40:28 PM To: Microsoft/vscode Cc: Pawel Urbanski; Mention Subject: Re: [Microsoft/vscode] Fixing Intelisense verbosity with screen readers (#67155) @jrieken<https://github.com/jrieken> I would suggest that we listen to our users and not testers. So we try to be less verbose. For this particular sample in the default case when the compleition item is not complex we could be less verbose, and only mention if it is a case when more than the label is inserted. Once we have some something we can ask feedback from our other users which use a screen reader. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub<#67155 (comment)>, or mute the thread<https://github.com/notifications/unsubscribe-auth/ACwCQHRSjcjNxYEjAGpD5exKoaF-rqrOks5vHv3MgaJpZM4aUGpU>.