Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Descriptive aria-labels for Keyboard shortcuts which include punctuation previously ignored by screen readers #666

Open
wants to merge 16 commits into
base: main
Choose a base branch
from

Conversation

e218736
Copy link

@e218736 e218736 commented Dec 14, 2023

References

Issue 15497 - Screen reader doesn't read all keyboard shortcut punctuation
When using screen reader (Windows Narrator) and navigating through the top menubar/command palette some punctuation is not announced. Keyboard shortcuts being read out incorrectly may be confusing/misleading for users of assistive technologies. This PR ensures that aria labels include descriptive text for punctuation used within default keyboard shortcuts so that the screen reader will announce correctly.

Code changes

  • Function added to render aria labels for top menu item keyboard shortcuts which include full description rather than punctuation symbol.
  • Function added to render aria labels for top command palette keyboard shortcuts which include full description rather than punctuation symbol.
  • Tests added with key binding commands to include punctuation shortcut

User-facing changes

none visible.
For screen reader users, keyboard shortcuts that include punctuation will be announced by default when focused.

@e218736 e218736 changed the title Keyboard shortcut enhanced accessibility for screen readers Descriptive aria-labels for Keyboard shortcuts which include punctuation previously ignored by screen readers Dec 21, 2023
@e218736 e218736 marked this pull request as ready for review December 21, 2023 13:12
Copy link
Member

@krassowski krassowski left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for working on this!

Did you consider using aria-keyshortcuts instead?

Comment on lines 987 to 994
const keyToText: { [key: string]: string } = {
']': 'Closing bracket',
'[': 'Opening bracket',
',': 'Comma',
'.': 'Full stop',
"'": 'Single quote',
'-': 'Hyphen-minus'
};
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think that we would want to make it easy to override in subclasses of the renderer so that they could reuse the logic below, but change the values on the right-hand side. In particular, JupyterLab will want to substituted the values with translated versions.

One solution would be making keyToText an option that can be passed to the renderer constructor, something like:

constructor(options: IRenderer.IOptions = {}) {
  this._keyToText = options.keyToText ?? DEFAULT_KEY_TO_TEXT;
}

But please read the next comment which tackles the deeper question on where the logic should be placed before implementing the suggestion above.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@krassowski I had tried to use aria-keyshortcuts in place of aria-label however, my screen reader (Windows Narrator) still omits some punctuation. With aria-label it is read out as expected.

I have implemented your other suggestions which should now allow translations to be substituted in JupyterLab

packages/widgets/src/commandpalette.ts Outdated Show resolved Hide resolved
Comment on lines 1386 to 1414
const keyToText: { [key: string]: string } = {
']': 'Closing bracket',
'[': 'Opening bracket',
',': 'Comma',
'.': 'Full stop',
"'": 'Single quote',
'-': 'Hyphen-minus'
};

let kbText = data.item.keyBinding;
let result = kbText ? CommandRegistry.formatKeystroke(kbText.keys) : null;

let punctuationRegex = /\p{P}/u;
let punctuations = result?.match(punctuationRegex);
if (!punctuations) {
return [];
}
for (const punctuation of punctuations) {
if (result != null && Object.keys(keyToText).includes(punctuation)) {
const individualKeys = result.split('+');
let index = individualKeys.indexOf(punctuation);
if (index != -1) {
individualKeys[index] = keyToText[punctuation];
}
const textShortcut = individualKeys.join('+');
return textShortcut;
}
}
return kbText ? CommandRegistry.formatKeystroke(kbText.keys) : null;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All right, this makes it pretty clear that we need to have this implemented at CommandRegistry level (see earlier suggestion on creating CommandRegistry.formatKeystrokeAriaLabel)

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @krassowski,

All makes sense, thank you for your comments. I will revert back to draft for now whist I work on these and let you know once ready for review again.

@krassowski krassowski added enhancement New feature or request accessibility Addresses accessibility needs labels Dec 29, 2023
@e218736 e218736 marked this pull request as draft January 2, 2024 16:20
@e218736 e218736 marked this pull request as ready for review January 3, 2024 17:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
accessibility Addresses accessibility needs enhancement New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants