Skip to content

Commit 87910ce

Browse files
authored
[material_ui] Port flutter/flutter flutter#185475 "Accessibility: Add semanticLabel to MenuAnchor" (flutter#12806)
Ports flutter#185475 to `material_ui`, following the instructions in flutter#188444. The commits were cherry-picked from the original PR, with only file paths adjusted for this repo. `MenuAnchor` had no way to label the expanded menu overlay, so screen readers announced nothing useful when a menu opened. This adds a `semanticLabel` property, applied to a `Semantics` node wrapping the submenu in `_buildOverlay`, and only when a label is provided. The original PR also announced the label with `SemanticsService.announce` when the menu opened. Following @chunhtai's review feedback on flutter#185475, that part is dropped here: a semantics label should not double as announcement text, and anyone who wants an announcement can call `SemanticsService.announce` from `onOpen`. The last commit on this branch removes it. ## Tests New test `MenuAnchor applies semanticLabel to the expanded menu overlay` in `packages/material_ui/test/menu_anchor_test.dart`, checking that the label is absent before the menu opens and present once it expands. The `menu_anchor.0` API example now sets a `semanticLabel`, and its example test still passes. Fixes flutter#184876 Supersedes flutter#185475, which will be closed with a pointer to this PR. ## 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 9caa77c commit 87910ce

4 files changed

Lines changed: 67 additions & 18 deletions

File tree

‎packages/material_ui/example/lib/menu_anchor/menu_anchor.0.dart‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,6 +112,7 @@ class _MyCascadingMenuState extends State<MyCascadingMenu> {
112112
children: <Widget>[
113113
MenuAnchor(
114114
animated: true,
115+
semanticLabel: 'Cascading application menu',
115116
onAnimationStatusChanged: (AnimationStatus status) {
116117
// Store the animation status so that it can be used to determine
117118
// whether the menu is opening or closing when the button is

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

Lines changed: 33 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -282,6 +282,7 @@ class MenuAnchor extends StatefulWidget {
282282
this.onAnimationStatusChanged,
283283
required this.menuChildren,
284284
this.builder,
285+
this.semanticLabel,
285286
this.child,
286287
});
287288

@@ -475,6 +476,11 @@ class MenuAnchor extends StatefulWidget {
475476
/// closed.
476477
final MenuAnchorChildBuilder? builder;
477478

479+
/// The semantic label of the menu.
480+
///
481+
/// Defaults to null.
482+
final String? semanticLabel;
483+
478484
/// The optional child to be passed to the [builder].
479485
///
480486
/// Supply this child if there is a portion of the widget tree built in
@@ -714,6 +720,32 @@ class _MenuAnchorState extends State<MenuAnchor> with SingleTickerProviderStateM
714720
}
715721

716722
Widget _buildOverlay(BuildContext context, RawMenuOverlayInfo position) {
723+
Widget submenu = _Submenu(
724+
fadeAnimation: opacityAnimation,
725+
heightAnimation: heightAnimation,
726+
layerLink: widget.layerLink,
727+
consumeOutsideTaps: widget.consumeOutsideTap,
728+
menuScopeNode: _menuScopeNode,
729+
menuStyle: widget.style,
730+
clipBehavior: widget.clipBehavior,
731+
menuChildren: _menuChildren,
732+
crossAxisUnconstrained: widget.crossAxisUnconstrained,
733+
menuPosition: position,
734+
anchor: this,
735+
alignmentOffset: widget.alignmentOffset ?? Offset.zero,
736+
reservedPadding: widget.reservedPadding ?? const EdgeInsets.all(_kMenuViewPadding),
737+
);
738+
739+
// Only inject the semantics node if a label is provided
740+
if (widget.semanticLabel != null) {
741+
submenu = Semantics(
742+
container: true,
743+
explicitChildNodes: true,
744+
label: widget.semanticLabel,
745+
child: submenu,
746+
);
747+
}
748+
717749
// ExcludeSemantics, ExcludeFocus, and IgnorePointer are used to effectively
718750
// disable all interactions with the menu while it is closing.
719751
//
@@ -724,24 +756,7 @@ class _MenuAnchorState extends State<MenuAnchor> with SingleTickerProviderStateM
724756
excluding: isClosingOrClosed,
725757
child: IgnorePointer(
726758
ignoring: isClosingOrClosed,
727-
child: ExcludeFocus(
728-
excluding: isClosingOrClosed,
729-
child: _Submenu(
730-
fadeAnimation: opacityAnimation,
731-
heightAnimation: heightAnimation,
732-
layerLink: widget.layerLink,
733-
consumeOutsideTaps: widget.consumeOutsideTap,
734-
menuScopeNode: _menuScopeNode,
735-
menuStyle: widget.style,
736-
clipBehavior: widget.clipBehavior,
737-
menuChildren: _menuChildren,
738-
crossAxisUnconstrained: widget.crossAxisUnconstrained,
739-
menuPosition: position,
740-
anchor: this,
741-
alignmentOffset: widget.alignmentOffset ?? Offset.zero,
742-
reservedPadding: widget.reservedPadding ?? const EdgeInsets.all(_kMenuViewPadding),
743-
),
744-
),
759+
child: ExcludeFocus(excluding: isClosingOrClosed, child: submenu),
745760
),
746761
);
747762
}
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
changelog: |
2+
- Adds a semanticLabel to MenuAnchor for the expanded menu overlay.
3+
version: minor

‎packages/material_ui/test/menu_anchor_test.dart‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7004,6 +7004,36 @@ void main() {
70047004
await tester.pump();
70057005
expect(find.text('X'), findsOne);
70067006
});
7007+
7008+
testWidgets('MenuAnchor applies semanticLabel to the expanded menu overlay', (
7009+
WidgetTester tester,
7010+
) async {
7011+
final SemanticsHandle handle = tester.ensureSemantics();
7012+
final controller = MenuController();
7013+
7014+
await tester.pumpWidget(
7015+
MaterialApp(
7016+
home: Material(
7017+
child: Center(
7018+
child: MenuAnchor(
7019+
controller: controller,
7020+
semanticLabel: 'Custom Menu Label',
7021+
menuChildren: const <Widget>[Text('Menu Item')],
7022+
),
7023+
),
7024+
),
7025+
),
7026+
);
7027+
7028+
expect(find.bySemanticsLabel('Custom Menu Label'), findsNothing);
7029+
7030+
controller.open();
7031+
await tester.pumpAndSettle();
7032+
7033+
expect(find.bySemanticsLabel('Custom Menu Label'), findsOneWidget);
7034+
7035+
handle.dispose();
7036+
});
70077037
}
70087038

70097039
List<Widget> createTestMenus({

0 commit comments

Comments
 (0)