Add aria menu roles to menu-related widgets #164741

QuncCccccc · 2025-03-06T21:26:08Z

Related to #157177

This PR is to add the following changes:

Implement SemanticsRole.menu, SemanticsRole.menuItem, SemanticsRole.menuBar, SemanticsRole.menuItemCheckbox, and SemanticsRole.menuItemRadio.
Add SemanticsRole.menu role in ~~MenuAnchor~~, DropdownButton, and PopupMenuButton
* Add SemanticsRole.menuBar role to MenuBar
Add SemanticsRole.menuItem to ~~MenuItemButton~~, DropdownMenuItem and PopupMenuItem
* Add SemanticsRole.menuItemCheckbox to CheckboxMenuButton
* Add SemanticsRole.menuItemRadio to RadioMenuButton

Pre-launch Checklist

I read the Contributor Guide and followed the process outlined there for submitting PRs.
I read the Tree Hygiene wiki page, which explains my responsibilities.
I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
I signed the CLA.
I listed at least one issue that this PR fixes in the description above.
I updated/added relevant documentation (doc comments with ///).
I added new tests to check the change I am making, or this PR is test-exempt.
I followed the breaking change policy and added Data Driven Fixes where supported.
All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

engine/src/flutter/lib/ui/semantics.dart

chunhtai · 2025-03-11T17:21:35Z

engine/src/flutter/lib/ui/semantics.dart

  menuItem,

+  /// A item with a checkbox in a dropdown created by [menu] or [menuBar].
+  menuItemCheckbox,


The order here need to be the same as semantics_node.h , so we have to either add this to the end or the enum in semantics_node.h has to be moved to the middle and shift all number after them by 2.

For now adding enum in the middle is fine since this hasn't yet expose to embedder.h. Once we expose them in embedder.h, moving enum around will be a breaking change.

I see! Thanks for reminding! I also noticed the dialog, alertDialog and table roles have reversed order. Just matched all of them.

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/menus.dart

chunhtai · 2025-03-12T20:47:47Z

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/menus.dart

+
+    if (semanticsObject.isFlagsDirty) {
+      String checkedValue;
+      if (semanticsObject.isCheckable && semanticsObject.hasFlag(ui.SemanticsFlag.isChecked)) {


can this reuse SemanticCheckable behavior?

Seems SemanticCheckable doesn't have mixed state and only contain on and off status.

SemanticCheckable is a SemanticsRole. Just added a Checkable behavior.

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/menus.dart

chunhtai · 2025-03-12T20:50:23Z

packages/flutter/lib/src/semantics/semantics.dart

+  static FlutterError? _semanticsMenuBar(SemanticsNode node) {
+    if (node.childrenCount < 1) {
+      return FlutterError('a menu bar cannot be empty');
+    }


also check if all children are menu?

Based on the description on the mdn website, a menubar's children can be menuItem, menuItemCheckbox, menuItemRadio, group, and separator. It looks pretty flexible, so I didn't add more checks for menu and menuBar, is this okay?

EDIT:
Additionally, in DropdownButton, PopupMenuButton, MenuAnchor, and MenuBar, the menu items are not menu's immediate children, so I added aria-owns on menu and menuBar.

packages/flutter/lib/src/semantics/semantics.dart

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/menus.dart

QuncCccccc · 2025-03-13T16:10:43Z

The PR is ready for another round of review:-)

chunhtai · 2025-03-13T17:51:10Z

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/menus.dart

+  }
+
+  bool _isMenuItem(SemanticsObject semanticsObject) {
+    if (semanticsObject.role == ui.SemanticsRole.menuItem ||


just return the condition directly

also since this if for menubar, should this only owns the Menu?

MenuBar in framework side also have a SingleChildScrollView to wrap the children. This _MenuPanel contains a scrollable and it is used by menu bar:)

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/menus.dart

engine/src/flutter/lib/web_ui/test/engine/semantics/semantics_test.dart

packages/flutter/lib/src/semantics/semantics.dart

chunhtai · 2025-03-17T22:35:10Z

packages/flutter/test/widgets/semantics_role_checks_test.dart

@@ -300,6 +300,80 @@ void main() {
    });
  });

+  group('menu', () {


Can you also add failure case for menuitem?

chunhtai · 2025-03-17T22:36:26Z

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/semantics.dart

+  /// A visible list of items or a widget that can be made to open and close.
+  menu,
+
+  /// A presentation of [menu] that usually remains visible and is usually


Suggested change

/// A presentation of [menu] that usually remains visible and is usually

/// A presentation of [menu]s that usually remains visible and is usually

Updated the doc.

chunhtai · 2025-03-17T22:39:46Z

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/checkable.dart

+/// (i.e. [SemanticsObject.isChecked] and [SemanticsObject.isMixed] are
+/// false). If the node is not checkable (i.e. [SemanticsObject.isCheckable]
+/// is false), then `aria-checked` is unset.
+class Checkable extends SemanticBehavior {


can some of the SemanticCheckable's logic to be replaced by this?

I don't see a very straightforward refactor on SemanticCheckable as it involves all checkbox, radio and switch. Checkable behavior is more relevant to checkbox. I just added more doc for it. Maybe a separate PR for refactoring SemanticCheckable would be better?

chunhtai · 2025-03-17T22:42:36Z

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/menus.dart

+    }
+
+    String attributeValue = '';
+    for (final int id in ids) {


this can be simplified as

ids.map((id) => 'flt-semantic-node-$id').join(' ')

Done. Thanks for helping simplify this.

chunhtai · 2025-03-17T22:43:00Z

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/menus.dart

+
+    String attributeValue = '';
+    for (final int id in ids) {
+      attributeValue = '$attributeValue flt-semantic-node-$id';


same as below

chunhtai · 2025-03-17T22:52:36Z

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/menus.dart

+    for (final int id in ids) {
+      attributeValue = '$attributeValue flt-semantic-node-$id';
+    }
+    setAttribute('aria-owns', attributeValue.trim());


no need to trim if using join

chunhtai · 2025-03-17T23:01:19Z

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/menus.dart

+/// Uses aria menubar role to convey this semantic information to the element.
+///
+/// Screen-readers takes advantage of "aria-label" to describe the visual.
+class SemanticMenuBar extends SemanticRole {


I have been reading the doc in mdn aria role menubar

Menubar interactions should be similar to the typical menu bar interaction in a desktop graphical user interface. In Google Docs, each of those menu items is a menuitem with a popup submenu, so each has an aria-haspopup attribute set to true. The menubar element does not.

This seems to me suggesting the menu in menubar should have role menuItem, but I am not sure if this is what it means. I am curious what your interpretation is on the doc.

My understanding is menuBar is just a horizontal menu, so they are not a parent-child relationship. And menubar should contain a list of submenu(menuItem with aria-haspopup attribute setting to true).

accidentally approved

chunhtai · 2025-03-19T15:51:50Z

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/tappable.dart

@@ -29,6 +29,13 @@ class SemanticButton extends SemanticRole {
    } else {
      removeAttribute('aria-disabled');
    }
+
+    // This is especially useful when the button is used to open a menu.
+    if (semanticsObject.hasExpandedState) {


expansion tile can be a button, too.
Also this role already has Expandable behavior which will assign aria-expanded.

Make sense! Reverted!

Created an issue for the popup flag: #165505 :)

chunhtai · 2025-03-19T15:57:38Z

packages/flutter/lib/src/material/popup_menu.dart

-      onPressed: widget.enabled ? showButtonMenu : null,
-      enableFeedback: enableFeedback,
-      style: widget.style,
+    return MergeSemantics(


If you wrap the icon with semantics(expanded) instead of wraping the entire iconButton, you don't need the mergesemantics I think

chunhtai

LGTM

QuncCccccc force-pushed the wire_up_menu_role branch from a026241 to 261a16f Compare March 11, 2025 01:16

github-actions bot removed d: api docs Issues with https://api.flutter.dev/ d: examples Sample code and demos a: desktop Running on desktop labels Mar 11, 2025

QuncCccccc requested a review from chunhtai March 11, 2025 16:55

QuncCccccc marked this pull request as ready for review March 11, 2025 16:59

chunhtai reviewed Mar 12, 2025

View reviewed changes

chunhtai requested a review from yjbanov March 12, 2025 20:51

yjbanov reviewed Mar 12, 2025

View reviewed changes

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/menus.dart Outdated Show resolved Hide resolved

engine/src/flutter/lib/web_ui/lib/src/engine/semantics/menus.dart Outdated Show resolved Hide resolved

QuncCccccc force-pushed the wire_up_menu_role branch from 3c7a476 to 301f656 Compare March 13, 2025 03:29

QuncCccccc requested review from yjbanov and chunhtai March 13, 2025 16:10

chunhtai reviewed Mar 13, 2025

View reviewed changes

QuncCccccc force-pushed the wire_up_menu_role branch 2 times, most recently from f95b557 to 4e50291 Compare March 13, 2025 22:43

QuncCccccc requested a review from chunhtai March 13, 2025 22:47

QuncCccccc added 5 commits March 17, 2025 11:21

Add menu, menuItem and menuBar

5cfcb3a

Update

3297c3c

Add menu and meunItem role to DropdownButton

2df250b

Adjust semantics tree shape

2d9c054

Add menu, menuBar, menuItem roles for menu and menu buttons

a9b0d9f

QuncCccccc added 8 commits March 17, 2025 11:21

Update code comments

25dc867

Fix linux_unopt warnings

b80376d

Update _isMenuItem

fe9d6e7

Update _isMenuItem in menuBar

90d8976

Add tests for aria-haspopup and aria-owns

b386436

Reformat

f0f1b81

Update test for _DebugSemanticsRoleChecks

28ddeb6

Fix test failures

2760e69

QuncCccccc force-pushed the wire_up_menu_role branch from 50c6960 to 2760e69 Compare March 17, 2025 18:21

chunhtai previously approved these changes Mar 17, 2025

View reviewed changes

chunhtai self-requested a review March 17, 2025 23:02

QuncCccccc added 7 commits March 17, 2025 19:23

Address PR comments

8dff291

Remove accidentally copied test configuration

e9a172c

Fix grammar

ace9e1d

Update doc

807f29f

Fix Linux linux_unopt

e3cc70c

Check expandable flag for SemanticButton

f85c1eb

PopupMenuButton and DropdownButton should have expanded flag

a81b93d

chunhtai reviewed Mar 19, 2025

View reviewed changes

QuncCccccc added 2 commits March 19, 2025 10:09

Address PR comments

14ce9ad

Address PR comment

2d002c4

chunhtai approved these changes Mar 19, 2025

View reviewed changes

QuncCccccc added the autosubmit Merge PR when tree becomes green via auto submit App label Mar 19, 2025

auto-submit bot added this pull request to the merge queue Mar 19, 2025

Merged via the queue into flutter:master with commit 32b34ff Mar 19, 2025
171 checks passed

flutter-dashboard bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Mar 19, 2025

QuncCccccc mentioned this pull request Mar 21, 2025

DropdownButton, DropdownMenuItem, PopupMenuButton, and PopupMenuItem widgets requires roles, ARIA properties, and keyboard support (Accessibility) #157177

Closed

Piinks mentioned this pull request Mar 21, 2025

Flutter Notable Commits - 2025 #161460

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add aria menu roles to menu-related widgets #164741

Add aria menu roles to menu-related widgets #164741

QuncCccccc commented Mar 6, 2025 •

edited

Loading

chunhtai Mar 11, 2025

QuncCccccc Mar 12, 2025

chunhtai Mar 12, 2025

QuncCccccc Mar 12, 2025

QuncCccccc Mar 12, 2025

chunhtai Mar 12, 2025

QuncCccccc Mar 12, 2025 •

edited

Loading

QuncCccccc commented Mar 13, 2025

chunhtai Mar 13, 2025

chunhtai Mar 13, 2025

QuncCccccc Mar 13, 2025

chunhtai Mar 17, 2025

QuncCccccc Mar 18, 2025

chunhtai Mar 17, 2025

QuncCccccc Mar 18, 2025

chunhtai Mar 17, 2025

QuncCccccc Mar 18, 2025

chunhtai Mar 17, 2025

QuncCccccc Mar 18, 2025

chunhtai Mar 17, 2025

chunhtai Mar 17, 2025

QuncCccccc Mar 18, 2025

chunhtai Mar 17, 2025

QuncCccccc Mar 18, 2025

chunhtai Mar 19, 2025

QuncCccccc Mar 19, 2025

QuncCccccc Mar 19, 2025

chunhtai Mar 19, 2025

QuncCccccc Mar 19, 2025

chunhtai left a comment

	/// A presentation of [menu] that usually remains visible and is usually
	/// A presentation of [menu]s that usually remains visible and is usually

Add aria menu roles to menu-related widgets #164741

Add aria menu roles to menu-related widgets #164741

Conversation

QuncCccccc commented Mar 6, 2025 • edited Loading

Pre-launch Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

QuncCccccc Mar 12, 2025 • edited Loading

Choose a reason for hiding this comment

QuncCccccc commented Mar 13, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chunhtai left a comment

Choose a reason for hiding this comment

QuncCccccc commented Mar 6, 2025 •

edited

Loading

QuncCccccc Mar 12, 2025 •

edited

Loading