Skip to content

Commit 13b5214

Browse files
authored
[material_ui] Improve Autocomplete, DrawerHeader, and Tooltip accessibility (flutter#12918)
Adds three targeted accessibility improvements to `packages/material_ui`: 1. **`Autocomplete` option selection state (`lib/src/autocomplete.dart`)**: - Passes `selected: highlight` to the `Semantics` wrapper around each option in `_AutocompleteOptions` so screen readers announce which autocomplete option is currently highlighted/selected (`aria-selected` / `aria-current`). 2. **`DrawerHeader` header semantics (`lib/src/drawer_header.dart`)**: - Wraps `DrawerHeader` in `Semantics(header: true)` so drawer titles expose semantic heading/header structure (`<h2>` via `effectiveHeadingLevel = 2` on Web when `hasLabel && !hasChildren`, and `<header>` when wrapping composite children like `UserAccountsDrawerHeader`). 3. **`TooltipThemeData.ignorePointer` (`lib/src/tooltip_theme.dart`, `lib/src/tooltip.dart`)**: - Adds `ignorePointer` to `TooltipThemeData` and wires `Tooltip` to consult `_tooltipTheme.ignorePointer` before falling back to `widget.message != null`, allowing apps to configure hoverable plain-text tooltips globally via `ThemeData(tooltipTheme: const TooltipThemeData(ignorePointer: false))` (satisfying WCAG 1.4.13 Hoverable without breaking `flutter#182527` default pass-through hit-testing). Related Flutter Web VPAT issues: - Autocomplete options (`#/auto-complete`, WCAG 4.1.2): [http://b/464138739](http://b/464138739), [http://b/460080184](http://b/460080184) - Drawer & NavigationDrawer (`#/drawer`, `#/navigation-drawer`, WCAG 1.3.1): [http://b/462581277](http://b/462581277), [http://b/462597561](http://b/462597561) - Tooltip Hoverable (`WCAG 1.4.13`): [http://b/463913706](http://b/463913706), [http://b/463912499](http://b/463912499), [http://b/463910116](http://b/463910116), [http://b/463900105](http://b/463900105), [http://b/462283112](http://b/462283112), [http://b/462276641](http://b/462276641) ## Pre-Adoption Checklist
1 parent 72a0a40 commit 13b5214

9 files changed

Lines changed: 133 additions & 19 deletions

‎packages/material_ui/lib/src/autocomplete.dart‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -318,16 +318,17 @@ class _AutocompleteOptionsListState<T extends Object> extends State<_Autocomplet
318318
itemCount: widget.options.length,
319319
itemBuilder: (BuildContext context, int index) {
320320
final T option = widget.options.elementAt(index);
321+
final highlight = highlightedIndex == index;
321322
return Semantics(
322323
button: true,
324+
selected: highlight,
323325
child: InkWell(
324326
key: GlobalObjectKey(option),
325327
onTap: () {
326328
widget.onSelected(option);
327329
},
328330
child: Builder(
329331
builder: (BuildContext context) {
330-
final highlight = highlightedIndex == index;
331332
return Container(
332333
color: highlight ? Theme.of(context).focusColor : null,
333334
padding: const EdgeInsets.all(16.0),

‎packages/material_ui/lib/src/drawer_header.dart‎

Lines changed: 18 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -82,21 +82,24 @@ class DrawerHeader extends StatelessWidget {
8282
assert(debugCheckHasMediaQuery(context));
8383
final ThemeData theme = Theme.of(context);
8484
final double statusBarHeight = MediaQuery.paddingOf(context).top;
85-
return Container(
86-
height: statusBarHeight + _kDrawerHeaderHeight,
87-
margin: margin,
88-
decoration: BoxDecoration(border: Border(bottom: Divider.createBorderSide(context))),
89-
child: AnimatedContainer(
90-
padding: padding.add(EdgeInsets.only(top: statusBarHeight)),
91-
decoration: decoration,
92-
duration: duration,
93-
curve: curve,
94-
child: child == null
95-
? null
96-
: DefaultTextStyle(
97-
style: theme.textTheme.bodyLarge!,
98-
child: MediaQuery.removePadding(context: context, removeTop: true, child: child!),
99-
),
85+
return Semantics(
86+
header: true,
87+
child: Container(
88+
height: statusBarHeight + _kDrawerHeaderHeight,
89+
margin: margin,
90+
decoration: BoxDecoration(border: Border(bottom: Divider.createBorderSide(context))),
91+
child: AnimatedContainer(
92+
padding: padding.add(EdgeInsets.only(top: statusBarHeight)),
93+
decoration: decoration,
94+
duration: duration,
95+
curve: curve,
96+
child: child == null
97+
? null
98+
: DefaultTextStyle(
99+
style: theme.textTheme.bodyLarge!,
100+
child: MediaQuery.removePadding(context: context, removeTop: true, child: child!),
101+
),
102+
),
100103
),
101104
);
102105
}

‎packages/material_ui/lib/src/tooltip.dart‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -575,7 +575,8 @@ class TooltipState extends State<Tooltip> with SingleTickerProviderStateMixin {
575575
onTriggered: widget.onTriggered,
576576
dismissDelay: widget.exitDuration ?? _tooltipTheme.exitDuration ?? _defaultExitDuration,
577577
positionDelegate: _getDefaultPositionDelegate,
578-
ignorePointer: widget.ignorePointer ?? widget.message != null,
578+
ignorePointer:
579+
widget.ignorePointer ?? _tooltipTheme.ignorePointer ?? widget.message != null,
579580
child: effectiveChild,
580581
);
581582
}

‎packages/material_ui/lib/src/tooltip_theme.dart‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,7 @@ class TooltipThemeData with Diagnosticable {
5454
this.exitDuration,
5555
this.triggerMode,
5656
this.enableFeedback,
57+
this.ignorePointer,
5758
}) : assert(
5859
height == null || constraints == null,
5960
'Only one of `height` and `constraints` may be specified.',
@@ -137,6 +138,14 @@ class TooltipThemeData with Diagnosticable {
137138
/// * [Feedback], for providing platform-specific feedback to certain actions.
138139
final bool? enableFeedback;
139140

141+
/// Whether the tooltip overlay should be invisible to hit testing.
142+
///
143+
/// If `false`, moving the mouse pointer onto the tooltip overlay keeps the
144+
/// tooltip visible (satisfying WCAG 1.4.13 Hoverable).
145+
///
146+
/// This value is used if [Tooltip.ignorePointer] is null.
147+
final bool? ignorePointer;
148+
140149
/// Creates a copy of this object but with the given fields replaced with the
141150
/// new values.
142151
TooltipThemeData copyWith({
@@ -159,6 +168,7 @@ class TooltipThemeData with Diagnosticable {
159168
Duration? exitDuration,
160169
TooltipTriggerMode? triggerMode,
161170
bool? enableFeedback,
171+
bool? ignorePointer,
162172
}) {
163173
return TooltipThemeData(
164174
height: height ?? this.height,
@@ -173,8 +183,10 @@ class TooltipThemeData with Diagnosticable {
173183
textAlign: textAlign ?? this.textAlign,
174184
waitDuration: waitDuration ?? this.waitDuration,
175185
showDuration: showDuration ?? this.showDuration,
186+
exitDuration: exitDuration ?? this.exitDuration,
176187
triggerMode: triggerMode ?? this.triggerMode,
177188
enableFeedback: enableFeedback ?? this.enableFeedback,
189+
ignorePointer: ignorePointer ?? this.ignorePointer,
178190
);
179191
}
180192

@@ -198,6 +210,12 @@ class TooltipThemeData with Diagnosticable {
198210
decoration: Decoration.lerp(a?.decoration, b?.decoration, t),
199211
textStyle: TextStyle.lerp(a?.textStyle, b?.textStyle, t),
200212
textAlign: t < 0.5 ? a?.textAlign : b?.textAlign,
213+
waitDuration: t < 0.5 ? a?.waitDuration : b?.waitDuration,
214+
showDuration: t < 0.5 ? a?.showDuration : b?.showDuration,
215+
exitDuration: t < 0.5 ? a?.exitDuration : b?.exitDuration,
216+
triggerMode: t < 0.5 ? a?.triggerMode : b?.triggerMode,
217+
enableFeedback: t < 0.5 ? a?.enableFeedback : b?.enableFeedback,
218+
ignorePointer: t < 0.5 ? a?.ignorePointer : b?.ignorePointer,
201219
);
202220
}
203221

@@ -218,6 +236,7 @@ class TooltipThemeData with Diagnosticable {
218236
exitDuration,
219237
triggerMode,
220238
enableFeedback,
239+
ignorePointer,
221240
);
222241

223242
@override
@@ -243,7 +262,8 @@ class TooltipThemeData with Diagnosticable {
243262
other.showDuration == showDuration &&
244263
other.exitDuration == exitDuration &&
245264
other.triggerMode == triggerMode &&
246-
other.enableFeedback == enableFeedback;
265+
other.enableFeedback == enableFeedback &&
266+
other.ignorePointer == ignorePointer;
247267
}
248268

249269
@override
@@ -286,6 +306,7 @@ class TooltipThemeData with Diagnosticable {
286306
properties.add(
287307
FlagProperty('enableFeedback', value: enableFeedback, ifTrue: 'true', showName: true),
288308
);
309+
properties.add(DiagnosticsProperty<bool>('ignorePointer', ignorePointer, defaultValue: null));
289310
}
290311
}
291312

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
changelog: |
2+
- Exposes `selected` state on `Autocomplete` option semantics.
3+
- Wraps `DrawerHeader` in `Semantics(header: true)`.
4+
- Adds `ignorePointer` to `TooltipThemeData` for WCAG 1.4.13 Hoverable support.
5+
version: minor

‎packages/material_ui/test/autocomplete_test.dart‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -893,18 +893,31 @@ void main() {
893893
);
894894
await tester.tap(find.byType(TextField));
895895
await tester.pump();
896-
await tester.enterText(find.byType(TextField), 'aa');
896+
await tester.enterText(find.byType(TextField), 'a');
897897
await tester.pump();
898898
expect(
899899
tester.getSemantics(find.text('aardvark')),
900900
matchesSemantics(
901901
isButton: true,
902902
isFocusable: true,
903+
hasSelectedState: true,
904+
isSelected: true,
903905
hasTapAction: true,
904906
hasFocusAction: true,
905907
label: 'aardvark',
906908
),
907909
);
910+
expect(
911+
tester.getSemantics(find.text('bobcat')),
912+
matchesSemantics(
913+
isButton: true,
914+
isFocusable: true,
915+
hasSelectedState: true,
916+
hasTapAction: true,
917+
hasFocusAction: true,
918+
label: 'bobcat',
919+
),
920+
);
908921
});
909922

910923
testWidgets('Same option in Autocomplete should be selectable again after text is cleared', (

‎packages/material_ui/test/drawer_test.dart‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1516,6 +1516,21 @@ void main() {
15161516
expect(tester.getSize(find.byType(DrawerHeader)), Size.zero);
15171517
});
15181518

1519+
testWidgets('DrawerHeader provides header semantics', (WidgetTester tester) async {
1520+
final SemanticsHandle handle = tester.ensureSemantics();
1521+
await tester.pumpWidget(
1522+
const MaterialApp(
1523+
home: Scaffold(body: DrawerHeader(child: Text('Drawer Title'))),
1524+
),
1525+
);
1526+
1527+
expect(
1528+
tester.getSemantics(find.byType(DrawerHeader)),
1529+
matchesSemantics(isHeader: true, label: 'Drawer Title', textDirection: TextDirection.ltr),
1530+
);
1531+
handle.dispose();
1532+
});
1533+
15191534
testWidgets('Drawer double tap to close does not leak LocalHistoryEntry', (
15201535
WidgetTester tester,
15211536
) async {

‎packages/material_ui/test/tooltip_theme_test.dart‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,38 @@ void main() {
2323
expect(TooltipThemeData.lerp(null, null, 0), null);
2424
const data = TooltipThemeData();
2525
expect(identical(TooltipThemeData.lerp(data, data, 0.5), data), true);
26+
27+
const a = TooltipThemeData(
28+
waitDuration: Duration(milliseconds: 100),
29+
showDuration: Duration(milliseconds: 200),
30+
exitDuration: Duration(milliseconds: 300),
31+
triggerMode: TooltipTriggerMode.tap,
32+
enableFeedback: true,
33+
ignorePointer: true,
34+
);
35+
const b = TooltipThemeData(
36+
waitDuration: Duration(milliseconds: 400),
37+
showDuration: Duration(milliseconds: 500),
38+
exitDuration: Duration(milliseconds: 600),
39+
triggerMode: TooltipTriggerMode.longPress,
40+
enableFeedback: false,
41+
ignorePointer: false,
42+
);
43+
final TooltipThemeData lerpedEarly = TooltipThemeData.lerp(a, b, 0.25)!;
44+
expect(lerpedEarly.waitDuration, a.waitDuration);
45+
expect(lerpedEarly.showDuration, a.showDuration);
46+
expect(lerpedEarly.exitDuration, a.exitDuration);
47+
expect(lerpedEarly.triggerMode, a.triggerMode);
48+
expect(lerpedEarly.enableFeedback, a.enableFeedback);
49+
expect(lerpedEarly.ignorePointer, a.ignorePointer);
50+
51+
final TooltipThemeData lerpedLate = TooltipThemeData.lerp(a, b, 0.75)!;
52+
expect(lerpedLate.waitDuration, b.waitDuration);
53+
expect(lerpedLate.showDuration, b.showDuration);
54+
expect(lerpedLate.exitDuration, b.exitDuration);
55+
expect(lerpedLate.triggerMode, b.triggerMode);
56+
expect(lerpedLate.enableFeedback, b.enableFeedback);
57+
expect(lerpedLate.ignorePointer, b.ignorePointer);
2658
});
2759

2860
test('TooltipThemeData defaults', () {
@@ -41,6 +73,7 @@ void main() {
4173
expect(theme.exitDuration, null);
4274
expect(theme.triggerMode, null);
4375
expect(theme.enableFeedback, null);
76+
expect(theme.ignorePointer, null);
4477
});
4578

4679
testWidgets('Default TooltipThemeData debugFillProperties', (WidgetTester tester) async {
@@ -62,6 +95,7 @@ void main() {
6295
const exit = Duration(milliseconds: 100);
6396
const TooltipTriggerMode triggerMode = TooltipTriggerMode.longPress;
6497
const enableFeedback = true;
98+
const ignorePointer = false;
6599
const TooltipThemeData(
66100
height: 15.0,
67101
padding: EdgeInsets.all(20.0),
@@ -76,6 +110,7 @@ void main() {
76110
exitDuration: exit,
77111
triggerMode: triggerMode,
78112
enableFeedback: enableFeedback,
113+
ignorePointer: ignorePointer,
79114
).debugFillProperties(builder);
80115

81116
final List<String> description = builder.properties
@@ -97,6 +132,7 @@ void main() {
97132
'exit duration: $exit',
98133
'triggerMode: $triggerMode',
99134
'enableFeedback: true',
135+
'ignorePointer: false',
100136
]);
101137
});
102138

@@ -1540,6 +1576,23 @@ void main() {
15401576
);
15411577
expect(tester.element(textAncestors.first).size, equals(themeConstraints.biggest));
15421578
});
1579+
1580+
testWidgets('Tooltip respects ignorePointer from the ambient theme', (WidgetTester tester) async {
1581+
final tooltipKey = GlobalKey<TooltipState>();
1582+
await tester.pumpWidget(
1583+
MaterialApp(
1584+
theme: ThemeData(tooltipTheme: const TooltipThemeData(ignorePointer: false)),
1585+
home: Tooltip(
1586+
key: tooltipKey,
1587+
message: tooltipText,
1588+
child: const SizedBox(width: 100, height: 100),
1589+
),
1590+
),
1591+
);
1592+
1593+
final RawTooltip rawTooltip = tester.widget<RawTooltip>(find.byType(RawTooltip));
1594+
expect(rawTooltip.ignorePointer, isFalse);
1595+
});
15431596
}
15441597

15451598
SemanticsNode findDebugSemantics(RenderObject object) {

‎packages/material_ui/test/user_accounts_drawer_header_test.dart‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -494,6 +494,7 @@ void main() {
494494
expect(
495495
tester.semantics.find(find.byType(UserAccountsDrawerHeader)),
496496
matchesSemantics(
497+
isHeader: true,
497498
isFocusable: true,
498499
hasFocusAction: true,
499500
label: 'Signed in\nname\nemail',
@@ -559,6 +560,7 @@ void main() {
559560
expect(
560561
tester.semantics.find(find.byType(UserAccountsDrawerHeader)),
561562
matchesSemantics(
563+
isHeader: true,
562564
label: 'Signed in',
563565
textDirection: TextDirection.ltr,
564566
children: <Matcher>[

0 commit comments

Comments
 (0)