feat: Introduce initial screen reader support (experimental) by BenHenning · Pull Request #684 · RaspberryPiFoundation/blockly-keyboard-experimentation

added 2 commits

July 29, 2025 21:00

This was referenced

Jul 29, 2025

The branch is no longer dependent on Core changes.

Also, expose state that may be needed for experimentation in mover.

This is in the form of a bunch of monkey patches that carefully replace
essentially all ARIA initialization happening within core Blockly.

This is largely done in a way that won't be well compatible with certain
uses of Blockly itself, and is only mean to act as a baseline for
testing.

This also removes some unnecessary code and one TODO.

This property isn't needed right now.

This adds the missing div needed for ARIA 'announcements'.

This removes unstubbing since it can't really work well, anyway, which
fixes the Mocha tests that validate initialization and disposal for the
KeyboardNavigation class.

This addresses all lint warnings.

This updates stubbing to use direct function references rather than name
strings since the code references will be correctly updated during
minification.

This also makes it a bit more explicit when non-public functions are
being stubbed, and it slightly simplifies stubbing logic.

The decision has been made to set up ARIA directly in core Blockly on a
specific long-lived experimental branch.

BenHenning changed the title ~~feat: Introduce initial screen reader support~~ feat: Introduce initial screen reader support (experimental)

Aug 6, 2025

BenHenning changed the base branch from add-screen-reader-support to add-screen-reader-support-experimental

August 6, 2025 20:28

BenHenning added a commit to RaspberryPiFoundation/blockly that referenced this pull request

Aug 6, 2025

## The basics

- [x] I [validated my changes](https://developers.google.com/blockly/guides/contribute/core#making_and_verifying_a_change)

## The details
### Resolves

Fixes part of #8207
Fixes part of #3370

### Proposed Changes

This introduces initial broad ARIA integration in order to enable at least basic screen reader support when using keyboard navigation.

Largely this involves introducing ARIA roles and labels in a bunch of places, sometimes done in a way to override normal built-in behaviors of the accessibility node tree in order to get a richer first-class output for Blockly (such as for blocks and workspaces).

### Reason for Changes

ARIA is the fundamental basis for configuring how focusable nodes in Blockly are represented to the user when using a screen reader. As such, all focusable nodes requires labels and roles in order to correctly communicate their contexts.

The specific approach taken in this PR is to simply add labels and roles to all nodes where obvious with some extra work done for `WorkspaceSvg` and `BlockSvg` in order to represent blocks as a tree (since that seems to be the best fitting ARIA role per those available: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles). The custom work specifically for blocks includes:
- Overriding the role description to be 'block' rather than 'tree item' (which is the default).
- Overriding the position, level, and number of sibling counts since those are normally determined based on the DOM tree and blocks are not laid out in the tree the same way they are visually or logically (so these computations were incorrect). This is also the reason for a bunch of extra computation logic being introduced.

One note on some of the labels being nonsensical (e.g. 'DoNotOverride?'): this was done intentionally to try and ensure _all_ focusable nodes (that can be focused) have labels, even when the specifics of what that label should be aren't yet clear. More components had these temporary labels until testing revealed how exactly they would behave from a screen reader perspective (at which point their roles and labels were updated as needed). The temporary labels act as an indicator when navigating through the UI, and some of the nodes can't easily be reached (for reasons) and thus may never actually need a label. More work is needed in understanding both what components need labels and what those labels should be, but that will be done beyond this PR.

### Test Coverage

No tests are added to this as it's experimental and not a final implementation.

The keyboard navigation tests are failing due to a visibility expansion of `connectionCandidate` in `BlockDragStrategy`. There's no way to avoid this breakage, unfortunately. Instead, this PR will be merged and then RaspberryPiFoundation/blockly-keyboard-experimentation#684 will be finalized and merged to fix it. There's some additional work that will happen both in that branch and in a later PR in core Blockly to integrate the two experimentation branches as part of #9283 so that CI passes correctly for both branches.

### Documentation

No documentation is needed at this time.

### Additional Information

This work is experimental and is meant to serve two purposes:
- Provide a foundation for testing and iterating the core screen reader experience in Blockly.
- Provide a reference point for designing a long-term solution that accounts for all requirements collected during user testing.

This code should never be merged into `develop` as it stands. Instead, it will be redesigned with maintainability, testing, and correctness in mind at a future date (see RaspberryPiFoundation/blockly-keyboard-experimentation#673).

This was referenced

Aug 6, 2025