Skip to content

Conversation

@ndarilek
Copy link
Contributor

@ndarilek ndarilek commented Dec 29, 2025

Update Tree accessibility to follow the WAI-ARIA treegrid pattern:

Keyboard navigation changes:

  • Right arrow on cell 0: Expand collapsed row, or move to next cell
  • Left arrow on cell 0: Collapse expanded row, or stop if collapsed
  • Right/Left arrows: Navigate between cells and buttons within a row
  • Tab/Shift-Tab: Move between focusable elements (buttons, editable cells)
    in the current row, then exit tree when no more focusable elements
  • Up/Down arrows: Navigate between rows, maintaining column position
  • Arrow keys never exit the tree (always accepted)

Focus model:

  • Cell-focused navigation (no row-level focus) for screen reader compatibility

Accessibility improvements:

  • Use ROLE_TREE_GRID for multi-column trees
  • Use ROLE_ROW for tree items (instead of ROLE_TREE_ITEM)
  • Use ROLE_CELL for individual column cells
  • Use ROLE_COLUMN_HEADER for column titles
  • Hide column headers from accessibility tree when not visible
  • Parent buttons to row element (not cell) to prevent announcement clutter
  • Only set expanded/collapsed state on items with children
  • Set active_descendant on tree grid for screen reader focus tracking

Reference: https://www.w3.org/WAI/ARIA/apg/patterns/treegrid/

@ndarilek ndarilek requested a review from a team as a code owner December 29, 2025 21:05
@bruvzg bruvzg added this to the 4.6 milestone Dec 29, 2025
@bruvzg bruvzg self-requested a review December 29, 2025 21:11
@ndarilek ndarilek requested a review from a team as a code owner December 30, 2025 00:09
ROLE_COLUMN_HEADER,
ROLE_TREE,
ROLE_TREE_ITEM,
ROLE_TREE_GRID,
Copy link
Member

Choose a reason for hiding this comment

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

New values should be added to the end of the list to avoid compatibility breaking.

@ndarilek ndarilek force-pushed the treegrid branch 3 times, most recently from 3dab1f5 to 7ae3810 Compare January 2, 2026 02:09
@ndarilek ndarilek marked this pull request as draft January 2, 2026 02:15
@ndarilek ndarilek force-pushed the treegrid branch 10 times, most recently from 429a9bc to e7e3cee Compare January 6, 2026 13:33
Update Tree accessibility to follow the WAI-ARIA treegrid pattern:

Keyboard navigation changes:
- Right arrow on cell 0: Expand collapsed row, or move to next cell
- Left arrow on cell 0: Collapse expanded row, or stop if collapsed
- Right/Left arrows: Navigate between cells and buttons within a row
- Tab/Shift-Tab: Move between focusable elements (buttons, editable cells)
  in the current row, then exit tree when no more focusable elements
- Up/Down arrows: Navigate between rows, maintaining column position
- Arrow keys never exit the tree (always accepted)

Focus model:
- Cell-focused navigation (no row-level focus) for screen reader compatibility
- Orca expects cells to have focus, not rows - row focus only announces
  expanded/collapsed state without cell content

Accessibility improvements:
- Use ROLE_TREE_GRID for multi-column trees
- Use ROLE_ROW for tree items (instead of ROLE_TREE_ITEM)
- Use ROLE_CELL for individual column cells
- Use ROLE_COLUMN_HEADER for column titles
- Hide column headers from accessibility tree when not visible
- Parent buttons to row element (not cell) to prevent announcement clutter
- Only set expanded/collapsed state on items with children
- Set active_descendant on tree grid for screen reader focus tracking

Reference: https://www.w3.org/WAI/ARIA/apg/patterns/treegrid/
@ndarilek ndarilek marked this pull request as ready for review January 19, 2026 19:18
@ndarilek
Copy link
Contributor Author

This is ready for review. Open to feedback. I recognize it changes a lot regarding how trees are navigated via arrows/tab, but it seemed a bit messy and inconsistent before.

Originally I went with a more conservative interpretation of the treegrid pattern that just used arrows in the trees rather than tabbing between controls. I discovered, though, that this made discovery of associated buttons very difficult for me as a screen reader user. I'm used to tabbing through interfaces, and on numerous occasions completely missed that there were buttons to the right of tree items. Claude Code had to tell me where lots of functionality I needed was, at which point I realized we needed the stricter approach. I do, however, wonder if shift-tab should navigate backwards through the tree for consistency, which it currently doesn't as per strict adherence to the pattern.

@Repiteo Repiteo modified the milestones: 4.6, 4.x Jan 26, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants