Skip to content

Commit 6dfa8bf

Browse files
kevmooDanTup
authored andcommitted
[web] Omit group role on menu scrollables and assign region role to named routes (flutter#192965)
## Description Fixes two web accessibility ARIA role issues in `lib/web_ui`: 1. **VoiceOver item count off-by-one in `PopupMenuButton`, `MenuAnchor`, and `DropdownButton` (`flutter#190661`)**: When a menu renders on the web, its items are wrapped in an intermediate `SingleChildScrollView` (`SemanticScrollable`, which sets `role="group"` in its constructor) while `SemanticMenu` / `SemanticMenuBar` sets `aria-owns` directly to the descendant `menuItem` nodes. Leaving `role="group"` on the unlabeled intermediate scrollable causes WebKit/VoiceOver to count the scrollable container as child `1` alongside the `N` `aria-owns` `menuitem`s (`"menu, N+1 items"`, announcing item 1 as `"2 of N+1"`). Setting `role="none"` on unlabeled intermediate `SemanticScrollable` containers inside `SemanticMenu` and `SemanticMenuBar` eliminates the off-by-one item count while preserving DOM scroll behavior. 2. **Valid ARIA role for self-labeled `SemanticRoute` (`aria-prohibited-attr`, http://b/462008723, http://b/461982793, http://b/460641753)**: When `SemanticRoute` has `namesRoute: true` (setting `aria-label` on `<flt-semantics>`), it previously omitted the `role` attribute (`role="generic"`), violating WAI-ARIA 1.2 `aria-prohibited-attr` (`aria-label` is prohibited on generic elements). `SemanticRoute.update()` now sets `role="region"` when `semanticsObject.namesRoute` is true. Fixes flutter#190661 Fixes http://b/462008723 Fixes http://b/461982793 Fixes http://b/460641753 ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing.
1 parent 0bd6071 commit 6dfa8bf

5 files changed

Lines changed: 113 additions & 81 deletions

File tree

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

Lines changed: 26 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -7,29 +7,18 @@ import 'package:ui/ui.dart' as ui;
77
import 'label_and_value.dart';
88
import 'semantics.dart';
99

10-
/// Indicates a menu element.
11-
///
12-
/// Uses aria menu role to convey this semantic information to the element.
13-
///
14-
/// Screen-readers takes advantage of "aria-label" to describe the visual.
15-
class SemanticMenu extends SemanticRole {
16-
SemanticMenu(SemanticsObject semanticsObject)
17-
: super.withBasics(
18-
EngineSemanticsRole.menu,
19-
semanticsObject,
20-
preferredLabelRepresentation: LabelRepresentation.ariaLabel,
21-
) {
22-
setAriaRole('menu');
10+
abstract class _SemanticMenuContainerBase extends SemanticRole {
11+
_SemanticMenuContainerBase(super.kind, super.semanticsObject, String ariaRole)
12+
: super.withBasics(preferredLabelRepresentation: LabelRepresentation.ariaLabel) {
13+
setAriaRole(ariaRole);
2314
}
2415

2516
@override
2617
void update() {
2718
super.update();
28-
// Menu items in DropdownButton, PopupMenuButton and MenuAnchor are not the
29-
// immediate children of the menu, so we need to set `aria-owns` on menu.
30-
// When the menu is open, the tree is still the old one without the menu
31-
// item information, so `addOneTimePostUpdateCallback` is called here to get
32-
// the latest tree info.
19+
// Menu items in DropdownButton, PopupMenuButton, MenuAnchor, and MenuBar are
20+
// not immediate children of the menu container, so set `aria-owns` after the
21+
// semantics tree is finalized via `addOneTimePostUpdateCallback`.
3322
semanticsObject.owner.addOneTimePostUpdateCallback(_updateMenuItemId);
3423
}
3524

@@ -39,9 +28,8 @@ class SemanticMenu extends SemanticRole {
3928
semanticsObject.role == ui.SemanticsRole.menuItemRadio;
4029
}
4130

42-
// Starting from the current semantics node, this method traverses the
43-
// semantics tree and collects the menu items by checking whether the role of
44-
// the node is [menuItem], then set `aria-owns` attribute to them.
31+
// Starting from the current semantics node, traverses the semantics tree,
32+
// collects descendant menu items, and sets `aria-owns`.
4533
void _updateMenuItemId() {
4634
final Map<int, SemanticsObject> tree = semanticsObject.owner.semanticsTree;
4735
final List<int> ids = [];
@@ -52,11 +40,12 @@ class SemanticMenu extends SemanticRole {
5240
}
5341
while (queue.isNotEmpty) {
5442
final int child = queue.removeAt(0);
55-
if (tree[child] != null && _isMenuItem(tree[child]!)) {
43+
final SemanticsObject? node = tree[child];
44+
if (node != null && _isMenuItem(node)) {
5645
ids.add(child);
57-
} else {
58-
if (tree[child]?.childrenInTraversalOrder != null) {
59-
queue.addAll(tree[child]!.childrenInTraversalOrder!);
46+
} else if (node != null) {
47+
if (node.childrenInTraversalOrder != null) {
48+
queue.addAll(node.childrenInTraversalOrder!);
6049
}
6150
}
6251
}
@@ -69,65 +58,24 @@ class SemanticMenu extends SemanticRole {
6958
bool focusAsRouteDefault() => focusable?.focusAsRouteDefault() ?? false;
7059
}
7160

61+
/// Indicates a menu element.
62+
///
63+
/// Uses aria menu role to convey this semantic information to the element.
64+
///
65+
/// Screen-readers takes advantage of "aria-label" to describe the visual.
66+
class SemanticMenu extends _SemanticMenuContainerBase {
67+
SemanticMenu(SemanticsObject semanticsObject)
68+
: super(EngineSemanticsRole.menu, semanticsObject, 'menu');
69+
}
70+
7271
/// Indicates a menu bar element.
7372
///
7473
/// Uses aria menubar role to convey this semantic information to the element.
7574
///
7675
/// Screen-readers takes advantage of "aria-label" to describe the visual.
77-
class SemanticMenuBar extends SemanticRole {
76+
class SemanticMenuBar extends _SemanticMenuContainerBase {
7877
SemanticMenuBar(SemanticsObject semanticsObject)
79-
: super.withBasics(
80-
EngineSemanticsRole.menuBar,
81-
semanticsObject,
82-
preferredLabelRepresentation: LabelRepresentation.ariaLabel,
83-
) {
84-
setAriaRole('menubar');
85-
}
86-
87-
@override
88-
void update() {
89-
super.update();
90-
// Menu items in Menu bar are not the immediate children of the menu, so we
91-
// need to set `aria-owns` on menu bar. When the menu is open, the tree is
92-
// still the old one without the menu item information, so
93-
// `addOneTimePostUpdateCallback` is called to get the latest tree info.
94-
semanticsObject.owner.addOneTimePostUpdateCallback(_updateMenuItemId);
95-
}
96-
97-
bool _isMenuItem(SemanticsObject semanticsObject) {
98-
return semanticsObject.role == ui.SemanticsRole.menuItem ||
99-
semanticsObject.role == ui.SemanticsRole.menuItemCheckbox ||
100-
semanticsObject.role == ui.SemanticsRole.menuItemRadio;
101-
}
102-
103-
// Starting from the current semantics node, this method traverses the
104-
// semantics tree and collects the menu items by checking whether the role of
105-
// the node is [menuItem], then set `aria-owns` attribute to them.
106-
void _updateMenuItemId() {
107-
final Map<int, SemanticsObject> tree = semanticsObject.owner.semanticsTree;
108-
final List<int> ids = [];
109-
final int root = semanticsObject.id;
110-
final List<int> queue = [];
111-
if (tree[root]?.childrenInTraversalOrder != null) {
112-
queue.addAll(tree[root]!.childrenInTraversalOrder!);
113-
}
114-
while (queue.isNotEmpty) {
115-
final int child = queue.removeAt(0);
116-
if (tree[child] != null && _isMenuItem(tree[child]!)) {
117-
ids.add(child);
118-
} else {
119-
if (tree[child]?.childrenInTraversalOrder != null) {
120-
queue.addAll(tree[child]!.childrenInTraversalOrder!);
121-
}
122-
}
123-
}
124-
125-
final String attributeValue = ids.map((id) => '$kFlutterSemanticNodePrefix$id').join(' ');
126-
setAttribute('aria-owns', attributeValue);
127-
}
128-
129-
@override
130-
bool focusAsRouteDefault() => focusable?.focusAsRouteDefault() ?? false;
78+
: super(EngineSemanticsRole.menuBar, semanticsObject, 'menubar');
13179
}
13280

13381
/// Indicates a menu item element.

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,8 @@ class SemanticRouteBase extends SemanticRole {
7070
}());
7171

7272
setAttribute('aria-label', label ?? '');
73+
} else {
74+
removeAttribute('aria-label');
7375
}
7476
}
7577

@@ -100,6 +102,17 @@ class SemanticRouteBase extends SemanticRole {
100102
/// of an explicit route label set on the route itself.
101103
class SemanticRoute extends SemanticRouteBase {
102104
SemanticRoute(SemanticsObject object) : super(EngineSemanticsRole.route, object);
105+
106+
@override
107+
void update() {
108+
super.update();
109+
final String? label = semanticsObject.label;
110+
if (semanticsObject.namesRoute && label != null && label.trim().isNotEmpty) {
111+
setAriaRole('region');
112+
} else {
113+
removeAttribute('role');
114+
}
115+
}
103116
}
104117

105118
/// Indicates the container as a pop dialog.

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

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,13 @@ class SemanticScrollable extends SemanticRole {
114114
@override
115115
void update() {
116116
super.update();
117+
semanticsObject.owner.addOneTimePostUpdateCallback(() {
118+
if (!semanticsObject.hasLabel && hasMenuAncestor) {
119+
setAriaRole('none');
120+
} else {
121+
setAriaRole('group');
122+
}
123+
});
117124
if (!_canScroll) {
118125
_cleanUp();
119126
return;

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

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1022,6 +1022,20 @@ abstract class SemanticRole {
10221022
bool get isDisposed => _isDisposed;
10231023
bool _isDisposed = false;
10241024

1025+
/// Whether any ancestor of [semanticsObject] has the [EngineSemanticsRole.menu]
1026+
/// or [EngineSemanticsRole.menuBar] role.
1027+
bool get hasMenuAncestor {
1028+
SemanticsObject? current = semanticsObject.parent;
1029+
while (current != null) {
1030+
final EngineSemanticsRole? kind = current.semanticRole?.kind;
1031+
if (kind == EngineSemanticsRole.menu || kind == EngineSemanticsRole.menuBar) {
1032+
return true;
1033+
}
1034+
current = current.parent;
1035+
}
1036+
return false;
1037+
}
1038+
10251039
/// Called when [semanticsObject] is removed, or when it changes its role such
10261040
/// that this role is no longer relevant.
10271041
///
@@ -1077,9 +1091,19 @@ final class GenericRole extends SemanticRole {
10771091
if (!semanticsObject.hasLabel) {
10781092
// The node didn't get a more specific role, and it has no label. It is
10791093
// likely that this node is simply there for positioning its children and
1080-
// has no other role for the screen reader to be aware of. In this case,
1081-
// the element does not need a `role` attribute at all.
1094+
// has no other role for the screen reader to be aware of. Normally the
1095+
// element does not need a `role` attribute at all, except when nested
1096+
// inside a menu/menubar (such as the outer ListView semantics node in
1097+
// DropdownButton), where omitting `role="none"` causes the browser to
1098+
// expose the element as an extra generic child of `role="menu"`.
10821099
super.update();
1100+
semanticsObject.owner.addOneTimePostUpdateCallback(() {
1101+
if (!semanticsObject.hasLabel && !semanticsObject.isTappable && hasMenuAncestor) {
1102+
setAriaRole('none');
1103+
} else {
1104+
removeAttribute('role');
1105+
}
1106+
});
10831107
return;
10841108
}
10851109

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

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4316,7 +4316,7 @@ void _testRoute() {
43164316

43174317
owner().updateSemantics(builder.build());
43184318
expectSemanticsTree(owner(), '''
4319-
<sem aria-label="this is a route label"><sem></sem></sem>
4319+
<sem role="region" aria-label="this is a route label"><sem></sem></sem>
43204320
''');
43214321

43224322
expect(owner().debugSemanticsTree![0]!.semanticRole?.kind, EngineSemanticsRole.route);
@@ -5307,6 +5307,46 @@ void _testMenus() {
53075307
);
53085308
});
53095309

5310+
test('menu sets role="none" on unlabeled intermediate generic and scrollable containers', () {
5311+
semantics()
5312+
..debugOverrideTimestampFunction(() => _testTime)
5313+
..semanticsEnabled = true;
5314+
5315+
final tester = SemanticsTester(owner());
5316+
tester.updateNode(
5317+
id: 0,
5318+
role: ui.SemanticsRole.menu,
5319+
rect: const ui.Rect.fromLTRB(0, 0, 100, 50),
5320+
children: <SemanticsNodeUpdate>[
5321+
tester.updateNode(
5322+
id: 1,
5323+
rect: const ui.Rect.fromLTRB(0, 0, 100, 50),
5324+
children: <SemanticsNodeUpdate>[
5325+
tester.updateNode(
5326+
id: 2,
5327+
flags: const ui.SemanticsFlags(hasImplicitScrolling: true),
5328+
actions: ui.SemanticsAction.scrollUp.index | ui.SemanticsAction.scrollDown.index,
5329+
rect: const ui.Rect.fromLTRB(0, 0, 100, 50),
5330+
children: <SemanticsNodeUpdate>[
5331+
tester.updateNode(id: 3, role: ui.SemanticsRole.menuItem),
5332+
tester.updateNode(id: 4, role: ui.SemanticsRole.menuItem),
5333+
],
5334+
),
5335+
],
5336+
),
5337+
],
5338+
);
5339+
tester.apply();
5340+
5341+
final SemanticsObject menuObject = tester.getSemanticsObject(0);
5342+
final SemanticsObject outerGenericObject = tester.getSemanticsObject(1);
5343+
final SemanticsObject scrollableObject = tester.getSemanticsObject(2);
5344+
expect(menuObject.element.getAttribute('aria-owns'), 'flt-semantic-node-3 flt-semantic-node-4');
5345+
expect(outerGenericObject.element.getAttribute('role'), 'none');
5346+
expect(scrollableObject.element.getAttribute('role'), 'none');
5347+
semantics().semanticsEnabled = false;
5348+
});
5349+
53105350
test('nested menus have correct menu item nodes', () {
53115351
semantics()
53125352
..debugOverrideTimestampFunction(() => _testTime)

0 commit comments

Comments
 (0)