Skip to content

Commit b535b37

Browse files
authored
[web] Add SemanticsRole.listBox and SemanticsRole.option (#192971)
Adds `SemanticsRole.listBox` and `SemanticsRole.option` across `dart:ui`, the Web semantics engine (emitting `aria-selected` on selectable options), and `_DebugSemanticsRoleChecks` (widget wiring tracked in #194031). Verified: `felt test test/engine/semantics/semantics_test.dart` and `flutter test test/widgets/semantics_role_checks_test.dart`. - `engine/src/flutter/lib/ui/semantics.dart`, `engine/src/flutter/lib/ui/semantics/semantics_node.h`, `AccessibilityBridge.java`, `engine/src/flutter/lib/web_ui/lib/semantics.dart`: Adds `SemanticsRole.listBox` (`kListBox = 34`) and `SemanticsRole.option` (`kOption = 35`). - `engine/src/flutter/lib/web_ui/lib/src/engine/semantics/list.dart`, `checkable.dart`, `scrollable.dart`, `semantics.dart`: Implements `SemanticListBox` (`role="listbox"`) and `SemanticOption` (`role="option"` with `aria-selected="true"|"false"`), and omits intermediate `role="group"` on unlabeled scrollables inside a `listBox`. - `packages/flutter/lib/src/semantics/semantics.dart` & `packages/flutter/test/widgets/semantics_role_checks_test.dart`: Validates in `_DebugSemanticsRoleChecks` that `SemanticsRole.option` has an ancestor `SemanticsRole.listBox`. ## 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 2b089ff commit b535b37

11 files changed

Lines changed: 308 additions & 11 deletions

File tree

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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -559,6 +559,21 @@ enum SemanticsRole {
559559
/// For more information, see:
560560
/// https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/slider_role
561561
slider,
562+
563+
/// A widget that allows the user to select one or more items from a list of
564+
/// choices.
565+
///
566+
/// See also:
567+
///
568+
/// * [option], which is the role for selectable items inside a [listBox].
569+
listBox,
570+
571+
/// A selectable item in a [listBox].
572+
///
573+
/// See also:
574+
///
575+
/// * [listBox], which is the container role for [option] items.
576+
option,
562577
}
563578

564579
/// Describe the type of data for an input field.

‎engine/src/flutter/lib/ui/semantics/semantics_node.h‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,8 @@ enum class SemanticsRole : int32_t {
106106
kNavigation = 31,
107107
kRegion = 32,
108108
kSlider = 33,
109+
kListBox = 34,
110+
kOption = 35,
109111
};
110112

111113
/// C/C++ representation of `SemanticsValidationResult` defined in

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -653,6 +653,8 @@ enum SemanticsRole {
653653
navigation,
654654
region,
655655
slider,
656+
listBox,
657+
option,
656658
}
657659

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

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -150,7 +150,8 @@ class Selectable extends SemanticBehavior {
150150
// Roles confirmed to support aria-selected according to ARIA spec.
151151
// See: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected
152152
static const Set<ui.SemanticsRole> _rolesSupportingAriaSelected = {
153-
// Note: Flutter currently supports row and tab from the list (gridcell, option, row, tab).
153+
// Note: Flutter currently supports option, row, and tab from the list (gridcell, option, row, tab).
154+
ui.SemanticsRole.option,
154155
ui.SemanticsRole.row,
155156
ui.SemanticsRole.tab,
156157
};

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

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,3 +42,46 @@ class SemanticListItem extends SemanticRole {
4242
@override
4343
bool focusAsRouteDefault() => focusable?.focusAsRouteDefault() ?? false;
4444
}
45+
46+
/// Indicates a listbox container.
47+
///
48+
/// Uses aria listbox role to convey this semantic information to the element.
49+
class SemanticListBox extends SemanticRole {
50+
SemanticListBox(SemanticsObject semanticsObject)
51+
: super.withBasics(
52+
EngineSemanticsRole.listBox,
53+
semanticsObject,
54+
preferredLabelRepresentation: LabelRepresentation.ariaLabel,
55+
) {
56+
setAriaRole('listbox');
57+
}
58+
59+
@override
60+
void update() {
61+
super.update();
62+
if (!semanticsObject.hasLabel) {
63+
setAttribute('aria-label', 'Options');
64+
}
65+
}
66+
67+
@override
68+
bool focusAsRouteDefault() => focusable?.focusAsRouteDefault() ?? false;
69+
}
70+
71+
/// Indicates a selectable option inside a listbox.
72+
///
73+
/// Uses aria option role to convey this semantic information to the element.
74+
class SemanticOption extends SemanticRole {
75+
SemanticOption(SemanticsObject semanticsObject)
76+
: super.withBasics(
77+
EngineSemanticsRole.option,
78+
semanticsObject,
79+
preferredLabelRepresentation: LabelRepresentation.ariaLabel,
80+
) {
81+
setAriaRole('option');
82+
addTappable();
83+
}
84+
85+
@override
86+
bool focusAsRouteDefault() => focusable?.focusAsRouteDefault() ?? false;
87+
}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,7 @@ class SemanticScrollable extends SemanticRole {
115115
void update() {
116116
super.update();
117117
semanticsObject.owner.addOneTimePostUpdateCallback(() {
118-
if (!semanticsObject.hasLabel && hasMenuAncestor) {
118+
if (!semanticsObject.hasLabel && hasMenuOrListBoxAncestor) {
119119
setAriaRole('none');
120120
} else {
121121
setAriaRole('group');

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

Lines changed: 23 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -628,6 +628,12 @@ enum EngineSemanticsRole {
628628

629629
/// A graphic object that can be incremented or decremented as a slider.
630630
slider,
631+
632+
/// A widget that allows the user to select one or more items from a list of choices.
633+
listBox,
634+
635+
/// A selectable item in a [listBox].
636+
option,
631637
}
632638

633639
/// Responsible for setting the `role` ARIA attribute, for attaching
@@ -1031,13 +1037,15 @@ abstract class SemanticRole {
10311037
bool get isDisposed => _isDisposed;
10321038
bool _isDisposed = false;
10331039

1034-
/// Whether any ancestor of [semanticsObject] has the [EngineSemanticsRole.menu]
1035-
/// or [EngineSemanticsRole.menuBar] role.
1036-
bool get hasMenuAncestor {
1040+
/// Whether any ancestor of [semanticsObject] has the [EngineSemanticsRole.menu],
1041+
/// [EngineSemanticsRole.menuBar], or [EngineSemanticsRole.listBox] role.
1042+
bool get hasMenuOrListBoxAncestor {
10371043
SemanticsObject? current = semanticsObject.parent;
10381044
while (current != null) {
10391045
final EngineSemanticsRole? kind = current.semanticRole?.kind;
1040-
if (kind == EngineSemanticsRole.menu || kind == EngineSemanticsRole.menuBar) {
1046+
if (kind == EngineSemanticsRole.menu ||
1047+
kind == EngineSemanticsRole.menuBar ||
1048+
kind == EngineSemanticsRole.listBox) {
10411049
return true;
10421050
}
10431051
current = current.parent;
@@ -1112,12 +1120,13 @@ final class GenericRole extends SemanticRole {
11121120
// likely that this node is simply there for positioning its children and
11131121
// has no other role for the screen reader to be aware of. Normally the
11141122
// element does not need a `role` attribute at all, except when nested
1115-
// inside a menu/menubar (such as the outer ListView semantics node in
1116-
// DropdownButton), where omitting `role="none"` causes the browser to
1117-
// expose the element as an extra generic child of `role="menu"`.
1123+
// inside a menu, menubar, or listbox (such as the outer ListView
1124+
// semantics node in DropdownButton or an Autocomplete options list),
1125+
// where omitting `role="none"` causes the browser to expose the element
1126+
// as an extra generic child of the container.
11181127
super.update();
11191128
semanticsObject.owner.addOneTimePostUpdateCallback(() {
1120-
if (!semanticsObject.hasLabel && !semanticsObject.isTappable && hasMenuAncestor) {
1129+
if (!semanticsObject.hasLabel && !semanticsObject.isTappable && hasMenuOrListBoxAncestor) {
11211130
setAriaRole('none');
11221131
} else {
11231132
removeAttribute('role');
@@ -2298,6 +2307,10 @@ class SemanticsObject {
22982307
return EngineSemanticsRole.list;
22992308
case ui.SemanticsRole.listItem:
23002309
return EngineSemanticsRole.listItem;
2310+
case ui.SemanticsRole.listBox:
2311+
return EngineSemanticsRole.listBox;
2312+
case ui.SemanticsRole.option:
2313+
return EngineSemanticsRole.option;
23012314
case ui.SemanticsRole.complementary:
23022315
return EngineSemanticsRole.complementary;
23032316
case ui.SemanticsRole.contentInfo:
@@ -2371,6 +2384,8 @@ class SemanticsObject {
23712384
EngineSemanticsRole.link => SemanticLink(this),
23722385
EngineSemanticsRole.list => SemanticList(this),
23732386
EngineSemanticsRole.listItem => SemanticListItem(this),
2387+
EngineSemanticsRole.listBox => SemanticListBox(this),
2388+
EngineSemanticsRole.option => SemanticOption(this),
23742389
EngineSemanticsRole.heading => SemanticHeading(this),
23752390
EngineSemanticsRole.header => SemanticHeader(this),
23762391
EngineSemanticsRole.tab => SemanticTab(this),

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

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3456,6 +3456,70 @@ void _testSelectables() {
34563456
semantics().semanticsEnabled = false;
34573457
});
34583458

3459+
test('renders listBox and option with aria-selected and omits group on inner generic and scrollable wrappers', () async {
3460+
semantics()
3461+
..debugOverrideTimestampFunction(() => _testTime)
3462+
..semanticsEnabled = true;
3463+
3464+
final tester = SemanticsTester(owner());
3465+
tester.updateNode(
3466+
id: 0,
3467+
role: ui.SemanticsRole.listBox,
3468+
rect: const ui.Rect.fromLTRB(0, 0, 100, 60),
3469+
children: <SemanticsNodeUpdate>[
3470+
tester.updateNode(
3471+
id: 1,
3472+
rect: const ui.Rect.fromLTRB(0, 0, 100, 60),
3473+
children: <SemanticsNodeUpdate>[
3474+
tester.updateNode(
3475+
id: 2,
3476+
flags: const ui.SemanticsFlags(hasImplicitScrolling: true),
3477+
actions: ui.SemanticsAction.scrollUp.index | ui.SemanticsAction.scrollDown.index,
3478+
scrollExtentMax: 100.0,
3479+
scrollPosition: 0.0,
3480+
rect: const ui.Rect.fromLTRB(0, 0, 100, 60),
3481+
children: <SemanticsNodeUpdate>[
3482+
tester.updateNode(
3483+
id: 3,
3484+
role: ui.SemanticsRole.option,
3485+
label: 'apple',
3486+
hasTap: true,
3487+
// isButton mirrors material_ui's per-item Semantics(button: true,
3488+
// selected: ...); the explicit role must win over the button flag.
3489+
flags: const ui.SemanticsFlags(isButton: true, isSelected: ui.Tristate.isTrue),
3490+
rect: const ui.Rect.fromLTRB(0, 0, 100, 30),
3491+
),
3492+
tester.updateNode(
3493+
id: 4,
3494+
role: ui.SemanticsRole.option,
3495+
label: 'banana',
3496+
hasTap: true,
3497+
flags: const ui.SemanticsFlags(isSelected: ui.Tristate.isFalse),
3498+
rect: const ui.Rect.fromLTRB(0, 30, 100, 60),
3499+
),
3500+
],
3501+
),
3502+
],
3503+
),
3504+
],
3505+
);
3506+
tester.apply();
3507+
3508+
expectSemanticsTree(owner(), '''
3509+
<sem role="listbox">
3510+
<sem role="none">
3511+
<sem role="none" style="overflow-y: scroll">
3512+
<flt-semantics-scroll-overflow></flt-semantics-scroll-overflow>
3513+
<sem role="option" aria-label="apple" aria-selected="true"></sem>
3514+
<sem role="option" aria-label="banana" aria-selected="false"></sem>
3515+
</sem>
3516+
</sem>
3517+
</sem>
3518+
''');
3519+
3520+
semantics().semanticsEnabled = false;
3521+
});
3522+
34593523
test('Checkable takes precedence over selectable', () {
34603524
semantics()
34613525
..debugOverrideTimestampFunction(() => _testTime)

‎engine/src/flutter/shell/platform/android/io/flutter/view/AccessibilityBridge.java‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2071,7 +2071,9 @@ enum Role {
20712071
MAIN(30),
20722072
NAVIGATION(31),
20732073
REGION(32),
2074-
SLIDER(33);
2074+
SLIDER(33),
2075+
LIST_BOX(34),
2076+
OPTION(35);
20752077

20762078
final int value;
20772079

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

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -182,6 +182,8 @@ sealed class _DebugSemanticsRoleChecks {
182182
SemanticsRole.status => _noLiveRegion,
183183
SemanticsRole.list => _noCheckRequired,
184184
SemanticsRole.listItem => _semanticsListItem,
185+
SemanticsRole.listBox => _semanticsListBox,
186+
SemanticsRole.option => _semanticsOption,
185187
SemanticsRole.complementary => _semanticsComplementary,
186188
SemanticsRole.contentInfo => _semanticsContentInfo,
187189
SemanticsRole.main => _semanticsMain,
@@ -511,6 +513,39 @@ sealed class _DebugSemanticsRoleChecks {
511513
return null;
512514
}
513515

516+
static FlutterError? _semanticsListBox(SemanticsNode node) {
517+
if (node.childrenCount < 1) {
518+
return FlutterError('a listBox cannot be empty');
519+
}
520+
FlutterError? error;
521+
bool validateListBoxChildren(SemanticsNode child) {
522+
final SemanticsRole role = child.getSemanticsData().role;
523+
if (role == SemanticsRole.option) {
524+
return true;
525+
}
526+
if (role == SemanticsRole.none && child.childrenCount > 0) {
527+
child.visitChildren(validateListBoxChildren);
528+
return error == null;
529+
}
530+
error = FlutterError('Children of listBox must have the option role');
531+
return false;
532+
}
533+
534+
node.visitChildren(validateListBoxChildren);
535+
return error;
536+
}
537+
538+
static FlutterError? _semanticsOption(SemanticsNode node) {
539+
SemanticsNode? currentNode = node.parent;
540+
while (currentNode != null) {
541+
if (currentNode.role == SemanticsRole.listBox) {
542+
return null;
543+
}
544+
currentNode = currentNode.parent;
545+
}
546+
return FlutterError('An option must be a descendant of a listBox');
547+
}
548+
514549
static bool _isLandmarkRole(SemanticsData nodeData) =>
515550
nodeData.role == SemanticsRole.complementary ||
516551
nodeData.role == SemanticsRole.contentInfo ||

0 commit comments

Comments
 (0)