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

Desktop: Accessibility: Improve note list keyboard and screen reader accessibility #10940

Conversation

personalizedrefrigerator
Copy link
Collaborator

@personalizedrefrigerator personalizedrefrigerator commented Aug 29, 2024

Summary

This pull request improves the note list's screen reader and keyboard accessibility.

In particular, it,

  • Allows selecting multiple notes from just the keyboard (Shift+arrow keys).
    • Related: WCAG 2.2: SC 2.1.1.
    • Note: This does not fully satisfy WCAG 2.2 § 2.1.1. It's possible to select non-adjacent items with a mouse, but still not possible with a keyboard.
  • Adds label information about whether an item is a to-do (and whether it's completed).
  • Adds role information to the note list.
    • Previously on Linux with the Orca screen reader, the up/down arrow keys did not change the focused note. Adding role information fixes this issue and makes the screen reader output more informative.
    • Related: WCAG 2.2: Failure condition 59.

This is related to #10795.

Remaining work

  • Currently, the note list overrides Tab behavior. This breaks (causes Tab to do nothing) when the note editor isn't visible (e.g. when multiple note items are selected). This prevents certain UI components (e.g. the multiple selection menu) from being reached while navigating with the keyboard.
  • Make selection different from focus. See the keyboard interaction section of the listbox ARIA Practicing Guides page and their section on focus vs selection.
  • Document keyboard shortcuts for toggling to-dos?
  • Improve accessibility of non-default note lists:
    • The example note list that includes a text input, for example, does not allow editing note titles when navigating with just a keyboard.
  • It's currently difficult to determine the number of selected items with just a screen reader.
  • With the Orca screen reader, clicking on an item in the note list reads "not selected" after changing the focus. This does not happen when changing the focus with a keyboard.

Notes

  • This pull request adds the listbox role to the note list (see the WAI ARIA Authoring Guide's Listbox Pattern).
  • Prior to this commit, this pull request used the grid role for the note list. This change was reverted because it seemed to prevent Windows Narrator from reading the content of the note list. The note list was read correctly with Orca on Linux.
    • It's possible that the grid role was incorrectly implemented.
    • For more-complex note lists, role=grid may be a better fit than role=listboxgrid should support multiple columns and possibly support focusing elements within a note list item.
    • role=listbox seems to fit the default note list renderer.

Testing plan

Existing issues: I've observed at least one issue that seems to have also been present before this pull request:

  • While creating a large number of notes in the current folder, it doesn't seem possible to change the focused note by clicking (just with the arrow keys).
  • Pressing tab after selecting multiple items does not move to the selection menu. Instead, it seems to do nothing.

Linux (with the Orca screen reader running):

  1. Create several thousand notes.
    • I ran a script similar to the following 2 times total in Joplin's dev tools:
    for (let i = 0; i < 1000; i++) {
        await Note.save({
            parent_id: '[[notebook ID here]]',
            title: `Test: ${i}`,
            body: `This is a random number: ${Math.floor(Math.random() * 10000)}`
        });
        if (i % 100 === 0) { console.log(i); }
     }
  2. Click on the title input for the current note.
  3. Press shift-tab.
  4. Verify that the note list is focused.
  5. Scroll the focused note out of view.
  6. Click on the title input.
  7. Press shift-tab.
  8. Verify that the focused note list item has been scrolled into view.
  9. Verify that the name of the note is read by the screen reader.
    • For me, the screen reader read Notes: Multi-select list with 2156 items: Test: 997, where Test: 997 is the name of the note.
  10. Press the Down arrow key. Verify that the name of the newly-selected note is read by the screen reader.
    • For me, the screen reader read Test: 996. Pressing Down again reads Test: 995.
  11. Verify that the focused item is highlighted in blue (in the light theme):
    • screenshot: Item test 995 is highlighted in blue
    • This color is the "focus-visible" color.
  12. Press Tab.
  13. Verify that the note title input is focused.
  14. Verify that the selected note is highlighted in gray.
  15. Click on an item in the note list and move the cursor away from the list.
  16. Verify that the item is highlighted in gray:
    screenshot: Selected item is highlighted in gray, others have a lighter gray background
  17. Press the Down arrow key.
  18. Verify that the active item is now highlighted in blue (assumes default light theme).
  19. Press shift-down.
  20. Verify that two notes are selected.
  21. Press shift-up.
  22. Verify that just one note is selected.
  23. Press shift-up.
  24. Verify that two notes are selected.
  25. Press delete
  26. Verify that the two notes have been deleted.
  27. Press ctrl-a.
  28. Verify that all notes are selected.
  29. Press shift-up.
  30. Verify that one fewer item is selected.
    • Note: Currently, this removes items from the selection near the point where ctrl-a was pressed:
      screenshot: Item 990 is the only unselected item, has selected items above and below
  31. Create a new to-do by clicking "new to-do".
  32. Give it a title ("test to-do").
  33. Press shift-tab.
  34. Verify that the note list is selected and that the screen reader reads Incomplete to-do, test to-do, incomplete to-do checkbox not checked (after reading information about the note list).
    • On Windows (with Windows Narrator), this message is more verbose (does not repeat "incomplete to-do checkbox not checked").
  35. Press space.
  36. Verify that the screen reader reads Complete to-do, test to-do, complete to-do checkbox checked. Complete.
    • Note: The trailing Complete is to support Windows, where "Complete to-do, test to-do, complete to-do checkbox checked" is not read in at least some cases.
  37. Press space again and verify that the to-do is marked as incomplete.
  38. Select two to-dos and press space. Verify that both are marked as complete.
  39. Select more notes than are on the screen using shift-click.
  40. Navigate to the trash, select them, right-click, and select "restore".
  41. Verify that the notes are restored.
  42. Scroll the focused note offscreen.
  43. Press ctrl-shift-l.
  44. Verify that the focused note is scrolled into view.
  45. Switch to the detailed note list view.
  46. Click on an item in the list.
  47. Verify that the item is marked as selected.
  48. Click on a different item.
  49. Press shift-up 4-6 times.
  50. Verify that multiple items are marked as focused:
    screenshot: Multiple items marked as focused in detailed/multi-column note list

Note: This is being edited — ctrl-enter (which opens a pull request) was pressed accidentally.

data-id="todo-checkbox"
type="checkbox"
aria-label="{{note.todoStatusText}}"
tabindex="-1"
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Without tabindex="-1", it's possible to focus just the checkbox in some cases. (For example, when navigating from the note title input with shift-tab).

Comment on lines -60 to +61
&:hover, :focus-visible > & > .content {
&:hover, &.-focus-visible > .content {
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Focus is no longer directly on each list item. Instead, the note list itself has focus and communicates the selected item using aria-selected and aria-activedescendant. MDN includes an example that takes a similar approach.

To style the sidebar differently when it has keyboard focus, the -focus-visible class is added (related to WCAG 2.2, SC 2.4.7).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
accessibility Related to accessibility desktop All desktop platforms
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants