Skip to content

Commit afe281a

Browse files
authored
[material_ui] Add tabBar/tab roles and expanded state semantics (flutter#13176)
Exposes `SemanticsRole.tabBar` and `SemanticsRole.tab` on `NavigationRail` destinations (omitting the redundant `"Tab i of n"` `indexLabel` on web where `role="tablist"` natively computes set size, matching `TabBar` and `Tab`) and sets `Semantics(expanded: ...)` on `DrawerButtonIcon`, `EndDrawerButtonIcon`, and `CalendarDatePicker`'s year/day mode toggle button so assistive technologies announce tab selection and expand/collapse states (WCAG 4.1.2). Fixes flutter#173052 Fixes flutter#194904 ## Pre-Review Checklist **Note**: The Flutter team is currently trialing the use of [Gemini Code Assist for GitHub](https://developers.google.com/gemini-code-assist/docs/review-github-code). Comments from the `gemini-code-assist` bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed. [^1]: Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling.
1 parent aa134bb commit afe281a

9 files changed

Lines changed: 411 additions & 99 deletions

‎packages/material_ui/lib/material_ui.dart‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -156,7 +156,7 @@ export 'src/range_slider.dart';
156156
export 'src/range_slider_parts.dart';
157157
export 'src/refresh_indicator.dart';
158158
export 'src/reorderable_list.dart';
159-
export 'src/scaffold.dart';
159+
export 'src/scaffold.dart' hide scaffoldDrawerExpandedOf, scaffoldEndDrawerExpandedOf;
160160
export 'src/scrollbar.dart';
161161
export 'src/scrollbar_theme.dart';
162162
export 'src/search.dart';

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

Lines changed: 22 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -292,14 +292,17 @@ class DrawerButtonIcon extends StatelessWidget {
292292

293293
@override
294294
Widget build(BuildContext context) {
295-
return _ActionIcon(
296-
iconBuilderCallback: (ActionIconThemeData? actionIconTheme) {
297-
return actionIconTheme?.drawerButtonIconBuilder;
298-
},
299-
getIcon: (BuildContext context) => Icons.menu,
300-
getAndroidSemanticsLabel: (MaterialLocalizations materialLocalization) {
301-
return materialLocalization.openAppDrawerTooltip;
302-
},
295+
return Semantics(
296+
expanded: scaffoldDrawerExpandedOf(context),
297+
child: _ActionIcon(
298+
iconBuilderCallback: (ActionIconThemeData? actionIconTheme) {
299+
return actionIconTheme?.drawerButtonIconBuilder;
300+
},
301+
getIcon: (BuildContext context) => Icons.menu,
302+
getAndroidSemanticsLabel: (MaterialLocalizations materialLocalization) {
303+
return materialLocalization.openAppDrawerTooltip;
304+
},
305+
),
303306
);
304307
}
305308
}
@@ -354,14 +357,17 @@ class EndDrawerButtonIcon extends StatelessWidget {
354357

355358
@override
356359
Widget build(BuildContext context) {
357-
return _ActionIcon(
358-
iconBuilderCallback: (ActionIconThemeData? actionIconTheme) {
359-
return actionIconTheme?.endDrawerButtonIconBuilder;
360-
},
361-
getIcon: (BuildContext context) => Icons.menu,
362-
getAndroidSemanticsLabel: (MaterialLocalizations materialLocalization) {
363-
return materialLocalization.openAppDrawerTooltip;
364-
},
360+
return Semantics(
361+
expanded: scaffoldEndDrawerExpandedOf(context),
362+
child: _ActionIcon(
363+
iconBuilderCallback: (ActionIconThemeData? actionIconTheme) {
364+
return actionIconTheme?.endDrawerButtonIconBuilder;
365+
},
366+
getIcon: (BuildContext context) => Icons.menu,
367+
getAndroidSemanticsLabel: (MaterialLocalizations materialLocalization) {
368+
return materialLocalization.openAppDrawerTooltip;
369+
},
370+
),
365371
);
366372
}
367373
}

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -587,6 +587,7 @@ class _DatePickerModeToggleButtonState extends State<_DatePickerModeToggleButton
587587
Flexible(
588588
child: Semantics(
589589
label: MaterialLocalizations.of(context).selectYearSemanticsLabel,
590+
expanded: widget.mode == DatePickerMode.year,
590591
button: true,
591592
container: true,
592593
child: SizedBox(

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

Lines changed: 67 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ library;
1010

1111
import 'dart:ui';
1212

13+
import 'package:flutter/foundation.dart' show kIsWeb;
1314
import 'package:flutter/widgets.dart';
1415

1516
import 'color_scheme.dart';
@@ -519,37 +520,49 @@ class _NavigationRailState extends State<NavigationRail> with TickerProviderStat
519520
widget.leading!,
520521
_verticalSpacer,
521522
],
522-
for (int i = 0; i < widget.destinations.length; i += 1)
523-
_RailDestination(
524-
minWidth: minWidth,
525-
minExtendedWidth: minExtendedWidth,
526-
extendedTransitionAnimation: _extendedAnimation,
527-
selected: widget.selectedIndex == i,
528-
icon: widget.selectedIndex == i
529-
? widget.destinations[i].selectedIcon
530-
: widget.destinations[i].icon,
531-
label: widget.destinations[i].label,
532-
destinationAnimation: _destinationAnimations[i],
533-
labelType: labelType,
534-
iconTheme: widget.selectedIndex == i ? selectedIconTheme : effectiveUnselectedIconTheme,
535-
labelTextStyle: widget.selectedIndex == i
536-
? selectedLabelTextStyle
537-
: unselectedLabelTextStyle,
538-
padding: widget.destinations[i].padding,
539-
useIndicator: useIndicator,
540-
indicatorColor: useIndicator ? indicatorColor : null,
541-
indicatorShape: useIndicator ? indicatorShape : null,
542-
onTap: () {
543-
if (widget.onDestinationSelected != null) {
544-
widget.onDestinationSelected!(i);
545-
}
546-
},
547-
indexLabel: localizations.tabLabel(
548-
tabIndex: i + 1,
549-
tabCount: widget.destinations.length,
550-
),
551-
disabled: widget.destinations[i].disabled,
523+
Semantics(
524+
role: SemanticsRole.tabBar,
525+
explicitChildNodes: true,
526+
container: true,
527+
child: Column(
528+
mainAxisSize: MainAxisSize.min,
529+
children: <Widget>[
530+
for (int i = 0; i < widget.destinations.length; i += 1)
531+
_RailDestination(
532+
minWidth: minWidth,
533+
minExtendedWidth: minExtendedWidth,
534+
extendedTransitionAnimation: _extendedAnimation,
535+
selected: widget.selectedIndex == i,
536+
icon: widget.selectedIndex == i
537+
? widget.destinations[i].selectedIcon
538+
: widget.destinations[i].icon,
539+
label: widget.destinations[i].label,
540+
destinationAnimation: _destinationAnimations[i],
541+
labelType: labelType,
542+
iconTheme: widget.selectedIndex == i
543+
? selectedIconTheme
544+
: effectiveUnselectedIconTheme,
545+
labelTextStyle: widget.selectedIndex == i
546+
? selectedLabelTextStyle
547+
: unselectedLabelTextStyle,
548+
padding: widget.destinations[i].padding,
549+
useIndicator: useIndicator,
550+
indicatorColor: useIndicator ? indicatorColor : null,
551+
indicatorShape: useIndicator ? indicatorShape : null,
552+
onTap: () {
553+
if (widget.onDestinationSelected != null) {
554+
widget.onDestinationSelected!(i);
555+
}
556+
},
557+
indexLabel: localizations.tabLabel(
558+
tabIndex: i + 1,
559+
tabCount: widget.destinations.length,
560+
),
561+
disabled: widget.destinations[i].disabled,
562+
),
563+
],
552564
),
565+
),
553566
if (!widget.trailingAtBottom && widget.trailing != null) widget.trailing!,
554567
],
555568
);
@@ -960,28 +973,31 @@ class _RailDestinationState extends State<_RailDestination> {
960973
final Color effectiveHoverColor = primaryColorAlphaModified
961974
? colors.primary
962975
: colors.primary.withOpacity(0.04);
963-
return Semantics(
964-
container: true,
965-
selected: widget.selected,
966-
child: Stack(
967-
children: <Widget>[
968-
Material(
969-
type: MaterialType.transparency,
970-
child: _IndicatorInkWell(
971-
onTap: widget.disabled ? null : widget.onTap,
972-
borderRadius: BorderRadius.all(Radius.circular(widget.minWidth / 2.0)),
973-
customBorder: widget.indicatorShape,
974-
splashColor: effectiveSplashColor,
975-
hoverColor: effectiveHoverColor,
976-
useMaterial3: material3,
977-
indicatorOffset: indicatorOffset,
978-
applyXOffset: applyXOffset,
979-
textDirection: textDirection,
980-
child: content,
976+
return MergeSemantics(
977+
child: Semantics(
978+
role: SemanticsRole.tab,
979+
selected: widget.selected,
980+
enabled: widget.disabled ? false : null,
981+
child: Stack(
982+
children: <Widget>[
983+
Material(
984+
type: MaterialType.transparency,
985+
child: _IndicatorInkWell(
986+
onTap: widget.disabled ? null : widget.onTap,
987+
borderRadius: BorderRadius.all(Radius.circular(widget.minWidth / 2.0)),
988+
customBorder: widget.indicatorShape,
989+
splashColor: effectiveSplashColor,
990+
hoverColor: effectiveHoverColor,
991+
useMaterial3: material3,
992+
indicatorOffset: indicatorOffset,
993+
applyXOffset: applyXOffset,
994+
textDirection: textDirection,
995+
child: content,
996+
),
981997
),
982-
),
983-
Semantics(label: widget.indexLabel),
984-
],
998+
if (!kIsWeb) Semantics(label: widget.indexLabel),
999+
],
1000+
),
9851001
),
9861002
);
9871003
}

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

Lines changed: 61 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2257,8 +2257,10 @@ class Scaffold extends StatefulWidget {
22572257
/// the listener, and register a listener to the new [ScaffoldGeometry]
22582258
/// listenable.
22592259
static ValueListenable<ScaffoldGeometry> geometryOf(BuildContext context) {
2260-
final _ScaffoldScope? scaffoldScope = context
2261-
.dependOnInheritedWidgetOfExactType<_ScaffoldScope>();
2260+
final _ScaffoldScope? scaffoldScope = InheritedModel.inheritFrom<_ScaffoldScope>(
2261+
context,
2262+
aspect: _ScaffoldAspect.geometry,
2263+
);
22622264
if (scaffoldScope == null) {
22632265
throw FlutterError.fromParts(<DiagnosticsNode>[
22642266
ErrorSummary(
@@ -2303,7 +2305,10 @@ class Scaffold extends StatefulWidget {
23032305
/// whole, from which you can show bottom sheets, and so forth.
23042306
static bool hasDrawer(BuildContext context, {bool registerForUpdates = true}) {
23052307
if (registerForUpdates) {
2306-
final _ScaffoldScope? scaffold = context.dependOnInheritedWidgetOfExactType<_ScaffoldScope>();
2308+
final _ScaffoldScope? scaffold = InheritedModel.inheritFrom<_ScaffoldScope>(
2309+
context,
2310+
aspect: _ScaffoldAspect.hasDrawer,
2311+
);
23072312
return scaffold?.hasDrawer ?? false;
23082313
} else {
23092314
final ScaffoldState? scaffold = context.findAncestorStateOfType<ScaffoldState>();
@@ -3402,6 +3407,9 @@ class ScaffoldState extends State<Scaffold>
34023407

34033408
return _ScaffoldScope(
34043409
hasDrawer: hasDrawer,
3410+
hasEndDrawer: hasEndDrawer,
3411+
isDrawerOpen: isDrawerOpen,
3412+
isEndDrawerOpen: isEndDrawerOpen,
34053413
geometryNotifier: _geometryNotifier,
34063414
child: ScrollNotificationObserver(
34073415
child: Material(
@@ -3653,19 +3661,67 @@ class PersistentBottomSheetController
36533661
final bool _isLocalHistoryEntry;
36543662
}
36553663

3656-
class _ScaffoldScope extends InheritedWidget {
3664+
enum _ScaffoldAspect { geometry, hasDrawer, drawerExpanded, endDrawerExpanded }
3665+
3666+
/// Returns whether the enclosing [Scaffold]'s start drawer is open, or `null`
3667+
/// if there is no enclosing [Scaffold] or it has no [Scaffold.drawer], and
3668+
/// registers [context] to rebuild when that value changes.
3669+
@internal
3670+
bool? scaffoldDrawerExpandedOf(BuildContext context) {
3671+
return InheritedModel.inheritFrom<_ScaffoldScope>(
3672+
context,
3673+
aspect: _ScaffoldAspect.drawerExpanded,
3674+
)?.drawerExpanded;
3675+
}
3676+
3677+
/// Returns whether the enclosing [Scaffold]'s end drawer is open, or `null` if
3678+
/// there is no enclosing [Scaffold] or it has no [Scaffold.endDrawer], and
3679+
/// registers [context] to rebuild when that value changes.
3680+
@internal
3681+
bool? scaffoldEndDrawerExpandedOf(BuildContext context) {
3682+
return InheritedModel.inheritFrom<_ScaffoldScope>(
3683+
context,
3684+
aspect: _ScaffoldAspect.endDrawerExpanded,
3685+
)?.endDrawerExpanded;
3686+
}
3687+
3688+
class _ScaffoldScope extends InheritedModel<_ScaffoldAspect> {
36573689
const _ScaffoldScope({
36583690
required this.hasDrawer,
3691+
required this.hasEndDrawer,
3692+
required this.isDrawerOpen,
3693+
required this.isEndDrawerOpen,
36593694
required this.geometryNotifier,
36603695
required super.child,
36613696
});
36623697

36633698
final bool hasDrawer;
3699+
final bool hasEndDrawer;
3700+
final bool isDrawerOpen;
3701+
final bool isEndDrawerOpen;
36643702
final _ScaffoldGeometryNotifier geometryNotifier;
36653703

3704+
bool? get drawerExpanded => hasDrawer ? isDrawerOpen : null;
3705+
bool? get endDrawerExpanded => hasEndDrawer ? isEndDrawerOpen : null;
3706+
36663707
@override
36673708
bool updateShouldNotify(_ScaffoldScope oldWidget) {
3668-
return hasDrawer != oldWidget.hasDrawer;
3709+
return geometryNotifier != oldWidget.geometryNotifier ||
3710+
hasDrawer != oldWidget.hasDrawer ||
3711+
hasEndDrawer != oldWidget.hasEndDrawer ||
3712+
isDrawerOpen != oldWidget.isDrawerOpen ||
3713+
isEndDrawerOpen != oldWidget.isEndDrawerOpen;
3714+
}
3715+
3716+
@override
3717+
bool updateShouldNotifyDependent(_ScaffoldScope oldWidget, Set<_ScaffoldAspect> dependencies) {
3718+
return (dependencies.contains(_ScaffoldAspect.geometry) &&
3719+
geometryNotifier != oldWidget.geometryNotifier) ||
3720+
(dependencies.contains(_ScaffoldAspect.hasDrawer) && hasDrawer != oldWidget.hasDrawer) ||
3721+
(dependencies.contains(_ScaffoldAspect.drawerExpanded) &&
3722+
drawerExpanded != oldWidget.drawerExpanded) ||
3723+
(dependencies.contains(_ScaffoldAspect.endDrawerExpanded) &&
3724+
endDrawerExpanded != oldWidget.endDrawerExpanded);
36693725
}
36703726
}
36713727

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
changelog: |
2+
- Adds `SemanticsRole.tabBar` and `SemanticsRole.tab` semantics to `NavigationRail` and its destinations.
3+
- Exposes `expanded` state semantics on `DrawerButton`, `EndDrawerButton`, and the `CalendarDatePicker` year-mode toggle button.
4+
version: minor

‎packages/material_ui/test/calendar_date_picker_test.dart‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1231,6 +1231,7 @@ void main() {
12311231
matchesSemantics(
12321232
label: 'Select year\nJanuary 2016',
12331233
isButton: true,
1234+
hasExpandedState: true,
12341235
hasTapAction: true,
12351236
hasFocusAction: true,
12361237
isFocusable: true,
@@ -1722,6 +1723,8 @@ void main() {
17221723
matchesSemantics(
17231724
label: 'Select year\nJanuary 2016',
17241725
isButton: true,
1726+
hasExpandedState: true,
1727+
isExpanded: true,
17251728
hasTapAction: true,
17261729
hasFocusAction: true,
17271730
isFocusable: true,

0 commit comments

Comments
 (0)