feat: Make `Flyout` an ARIA `list` (experimental) #9528

BenHenning · 2025-12-11T22:26:57Z

The basics

I validated my changes

The details

Resolves

Fixes #9495

Proposed Changes

Changes a bunch of ARIA role & label management to ensure that Flyout acts like a list rather than a tree.

Reason for Changes

Flyouts are always hierarchically flat so it doesn't make sense to model them as a tree. Instead, a menu is likely a better fit per https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menu_role:

A menu generally represents a grouping of common actions or functions that the user can invoke. The menu role is appropriate when a list of menu items is presented in a manner similar to a menu on a desktop application. Submenus, also known as pop-up menus, also have the role menu.

However, there are important caveats that need to be considered and addressed:

As discussed below, menus introduce some unexpected compatibility issues with VoiceOver so this PR presently uses list and listitems as a slightly more generic enumerating alternative for menus.
Menus (and to some extent lists) are stricter* than trees in that they seem to impose a requirement that menuitems cannot contain interactive elements (they are expected to be interactive themselves). This has led to a few specific changes:
- Block children are now hidden when in the flyout (since they aren't navigable anyway).
- Flyout buttons are themselves now the menuitem rather than their container parent, and they no longer use the role button.
Menus aren't really expected to contain labels but it isn't inherently disallowed. This is less of an issue with lists.
Because everything must be a listitem (or a few more specific alternatives) both blocks and buttons lack some context. Since not all Flyout items can be expected to be interactive, buttons and blocks have both had their labels updated to include an explicit indicator that they are buttons and blocks, respectively. Note that this does possibly go against convention for buttons in particular but it seems fine since this is an unusual (but seemingly correct) utilization of a list element.
To further provide context on blocks, the generated label for blocks in the Flyout is now its verbose label rather than the more compact form.

* This is largely a consequence of a few specific attributes of menuitem and menus as a whole and very likely also applies to trees and treeitems (and lists and listitemss). However, now seemed like a good time to fix this especially in case some screen readers get confused rather than ignore nested interactive controls/follow semantic cloaking per the spec.

Demo of it working on VoiceOver (per @gonfunko -- note this was the menu variant rather than the list variant of the PR):

Test Coverage

This has been manually tested with ChromeVox. No automated tests are needed as part of this experimental change.

Documentation

No new documentation changes are needed for this experimental change.

Additional Information

None.

…ode-hierarchy

Addresses some observed gaps in behaviors with connections. This is unfortunately mainly a patch without fully understanding the deep issue being avoided but it seems reasonable for the experimental branch.

…ode-hierarchy

…ode-hierarchy Conflicts: core/block_svg.ts

…ode-hierarchy

It seems that the extra safety checks weren't actually needed.

More investigation and fixes are likely still needed.

…ode-hierarchy

…ode-hierarchy Conflicts: core/block_svg.ts

Conflicts: core/block_svg.ts

BenHenning · 2025-12-11T23:00:10Z

@microbit-robert does this work for micro:bit? Will get this into review if you don't see any issues (and after #9449 goes in). It seems to be working well for me in ChromeVox and @gonfunko tested it on VoiceOver and didn't spot any issues so I'm hoping this addresses the root problem.

Only one behavioral change was needed.

Fixes ARIA ownership for these connection types.

BenHenning · 2025-12-12T02:45:55Z

PTAL @gonfunko. Apologies that this includes the changes in #9449. I will be merging this after that PR for sure, and if you don't review this before it's merged I'll make sure to update the conversation thread here with a note once the PR diff is clean.

microbit-robert · 2025-12-12T10:13:54Z

I have the following issue on Chrome, Firefox and Safari:

When navigating up from a statement block inside an if block, the VoiceOver cursor doesn't follow the focused element and the if block label is not read out. Update: the addition of this line appears to be the cause of the VO cursor becoming decoupled from the focused element during workspace navigation. Removing it addresses this problem.

In Safari and Firefox, the changes work well and the flyout navigation seems good.

I get some very odd VoiceOver issues when testing these changes on Chrome only.

When pressing 'T' to move into the toolbox, the toolbox categories are not read out, even when switching between them with up/down (this is what I experienced when I quickly attempted this change). Update: so, remove this line and everything works fine (but this is obviously incorrect). You can also change the role to generic or listbox or presumably almost anything else and it will work. I'm baffled.
- Chrome (and other Chromium-based browsers) are important to us and we recommend Chrome for MakeCode (and for user testing) because it supports WebUSB which makes downloading a MakeCode program to a micro:bit easy. Safari does not support WebUSB.

I reset my VoiceOver settings to the defaults. I'll be even more confused if these issues can't be reproduced by anyone else - specifically the Chrome only issue. An alternative approach that does seem to work in Chrome, Firefox and Safari is to replace menu and menuitem with listbox and listitem.

Screen recording using VoiceOver and Chrome:
https://github.com/user-attachments/assets/14638a8c-7e03-42cb-ae4a-846fe928f3b3

I'll try and track down what changes specifically affect things in VoiceOver - comment has been updated.

gonfunko · 2025-12-12T16:52:55Z

@microbit-robert I can repro the Safari issue, but the Chrome/VoiceOver one works fine for me even with the same block layout and key sequence as shown in your demo video oddly enough.

gonfunko · 2025-12-12T16:59:13Z

core/flyout_base.ts

+    // TODO: Optimize this.
+    return this.normalizeSeparators(contents).map((item) => {
+      // aria.setRole(item.getElement().getFocusableElement(), aria.Role.MENUITEM);
+      return item;
+    });


This appears to be a no-op at present, remove or uncomment the role setting?

Uh, this was a placeholder for testing and I did forget to remove it. Thanks for calling it out!

gonfunko · 2025-12-12T17:06:00Z

core/block_svg.ts

+      if (
+        nextConnection &&
+        nextConnection.canBeFocused() &&
+        nextConnection.type === ConnectionType.NEXT_STATEMENT


I think the check for type === ConnectionType.NEXT_STATEMENT is redundant given that we got the connection from the nextConnection field?

Good point--will remove this.

Also, moving comment to #9449 where it's actually needed.

Addressed in #9449.

BenHenning · 2025-12-12T21:19:56Z

Thanks @microbit-robert! That is very puzzling. I'm not opposed to switching to listitem and I was considering that originally. I think to some extent a list is even more generic than a menu, and the specification isn't super clear on when to pick one versus the other so I don't think it's strictly wrong to use list here, instead (that is, I'm not sure the extra semantic benefits of menu are worth risking bugs).

BenHenning · 2025-12-12T21:22:04Z

When navigating up from a statement block inside an if block, the VoiceOver cursor doesn't follow the focused element and the if block label is not read out. Update: the addition of this line appears to be the cause of the VO cursor becoming decoupled from the focused element during workspace navigation. Removing it addresses this problem.

This is an issue with #9449 and is actually rather concerning. I wasn't expecting the aria-owns declarations to actually impact behaviors, they were meant to just fix up the hierarchy. It's rather annoying that the VO cursor isn't following the focus given that's basically its job--I will need to try and figure out which specific association is breaking it since the hierarchy is more, not less, correct than before.

BenHenning · 2025-12-12T21:23:37Z

I was semi expecting the hierarchy changes from #9449 to cause more stability in the flyout for this PR but that may not actually be the case. I will try to decouple those changes so that this can go in independently as this is a much more pressing problem for the user test than #9449 (which is really just a stabilizing PR despite the regression).

BenHenning

Quick self-review after detaching #9449.

Technically the branch name is now a lie.

BenHenning

Self-reviewed commit that changes this to a list (and makes the branch name a liar :) ).

BenHenning · 2025-12-12T21:46:44Z

@gonfunko could you perhaps take one more quick pass on the PR now that #9449 is detached and there are some other changes here?

@microbit-robert is this working well enough to merge or are more changes needed? I can do those on Monday if so.

microbit-robert · 2025-12-15T09:49:42Z

@BenHenning This now works well for me, thanks! There is some interesting numbering going on in VoiceOver with the list items in the flyout for full block fields that exist on their own (i.e., the first block in the Math flyout), but I think this is something that could be looked at separately. I would be happy if this got merged as is.

BenHenning · 2025-12-15T18:12:19Z

@BenHenning This now works well for me, thanks! There is some interesting numbering going on in VoiceOver with the list items in the flyout for full block fields that exist on their own (i.e., the first block in the Math flyout), but I think this is something that could be looked at separately. I would be happy if this got merged as is.

Could you file an issue for that separately @microbit-robert? Would be helpful to look at with a bit more context.

BenHenning added 10 commits October 30, 2025 00:37

feat: Clean up a11y node hierarchy.

b1d3d6d

Merge branch 'add-screen-reader-support-experimental' into clean-up-n…

a7f7810

…ode-hierarchy

fix: Fix CI failures.

f81e2b2

Addresses some observed gaps in behaviors with connections. This is unfortunately mainly a patch without fully understanding the deep issue being avoided but it seems reasonable for the experimental branch.

Merge branch 'add-screen-reader-support-experimental' into clean-up-n…

cc5d002

…ode-hierarchy

Merge branch 'add-screen-reader-support-experimental' into clean-up-n…

7e1b4d5

…ode-hierarchy Conflicts: core/block_svg.ts

Merge branch 'add-screen-reader-support-experimental' into clean-up-n…

18200c9

…ode-hierarchy

chore: Simplify connectiong gating logic.

eeaff73

It seems that the extra safety checks weren't actually needed.

chore: Reduce complexity.

5e28067

More investigation and fixes are likely still needed.

Merge branch 'add-screen-reader-support-experimental' into clean-up-n…

4a6f102

…ode-hierarchy

feat: Make Flyout a menu.

c7e074f

github-actions bot added the PR: feature Adds a feature label Dec 11, 2025

BenHenning added 2 commits December 11, 2025 22:30

Merge branch 'add-screen-reader-support-experimental' into clean-up-n…

14cd72c

…ode-hierarchy Conflicts: core/block_svg.ts

Merge branch 'clean-up-node-hierarchy' into make-flyout-a-menu

45206fa

Conflicts: core/block_svg.ts

github-actions bot added PR: feature Adds a feature and removed PR: feature Adds a feature labels Dec 11, 2025

BenHenning added 4 commits December 12, 2025 01:52

fix: Broken tests due to connection change.

8dacb41

Only one behavioral change was needed.

chore: Lint fixes.

c19eaa5

fix: Fix output connections in C-shaped blocks.

71a9678

Fixes ARIA ownership for these connection types.

Merge branch 'clean-up-node-hierarchy' into make-flyout-a-menu

6660963

BenHenning marked this pull request as ready for review December 12, 2025 02:45

BenHenning requested a review from a team as a code owner December 12, 2025 02:45

BenHenning requested review from gonfunko and removed request for a team December 12, 2025 02:45

github-actions bot assigned gonfunko Dec 12, 2025

gonfunko approved these changes Dec 12, 2025

View reviewed changes

BenHenning mentioned this pull request Dec 12, 2025

fix: Clean up accessibility node hierarchy (experimental) #9449

Merged

1 task

BenHenning added 2 commits December 12, 2025 21:30

chore: Undo changes from RaspberryPiFoundation#9449.

84f78e2

chore: Re-add BlockSvg changes.

fa925e8

BenHenning changed the title ~~feat: Make Flyout an ARIA menu (experimental) [Blocked: #9449]~~ feat: Make Flyout an ARIA menu (experimental) Dec 12, 2025

github-actions bot added PR: feature Adds a feature and removed PR: feature Adds a feature labels Dec 12, 2025

chore: Remove unnecessary testing code.

a6c2744

BenHenning commented Dec 12, 2025

View reviewed changes

fix: Attempt to use list instead of menu.

dc750a1

Technically the branch name is now a lie.

BenHenning changed the title ~~feat: Make Flyout an ARIA menu (experimental)~~ feat: Make Flyout an ARIA list (experimental) Dec 12, 2025

github-actions bot added PR: feature Adds a feature and removed PR: feature Adds a feature labels Dec 12, 2025

BenHenning commented Dec 12, 2025

View reviewed changes

gonfunko approved these changes Dec 12, 2025

View reviewed changes

BenHenning merged commit bb342f9 into RaspberryPiFoundation:add-screen-reader-support-experimental Dec 15, 2025
13 of 14 checks passed

BenHenning deleted the make-flyout-a-menu branch December 15, 2025 18:13

feat: Make Flyout an ARIA list (experimental) #9528

feat: Make Flyout an ARIA list (experimental) #9528

Uh oh!

Conversation

BenHenning commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

The basics

The details

Resolves

Proposed Changes

Reason for Changes

Test Coverage

Documentation

Additional Information

Uh oh!

BenHenning commented Dec 11, 2025

Uh oh!

BenHenning commented Dec 12, 2025

Uh oh!

microbit-robert commented Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gonfunko commented Dec 12, 2025

Uh oh!

gonfunko Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

BenHenning Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

gonfunko Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

BenHenning Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

BenHenning Dec 12, 2025

Choose a reason for hiding this comment

Uh oh!

BenHenning Dec 16, 2025

Choose a reason for hiding this comment

Uh oh!

BenHenning commented Dec 12, 2025

Uh oh!

BenHenning commented Dec 12, 2025

Uh oh!

BenHenning commented Dec 12, 2025

Uh oh!

BenHenning left a comment

Choose a reason for hiding this comment

Uh oh!

BenHenning left a comment

Choose a reason for hiding this comment

Uh oh!

BenHenning commented Dec 12, 2025

Uh oh!

microbit-robert commented Dec 15, 2025

Uh oh!

BenHenning commented Dec 15, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat: Make `Flyout` an ARIA `list` (experimental) #9528

feat: Make `Flyout` an ARIA `list` (experimental) #9528

BenHenning commented Dec 11, 2025 •

edited

Loading

microbit-robert commented Dec 12, 2025 •

edited

Loading