home: Adjust semantics of bottom nav bar

Fixes #1857.
Fixes #1960.
Some of this has an effect I observes in my testing on iOS with
VoiceOver:

- MergeSemantics on each tab causes the tab to be represented by a
  single node instead of multiple, so it isn't double-visited when
  swiping right to traverse the tree.

The rest is just a best effort at following the docs, which doesn't
make the experience obviously worse, but I didn't notice an effect
in my testing.

Author: chrisbobbe

lib/widgets/home.dart

@@ -1,7 +1,7 @@
 import 'dart:async';
-import 'dart:ui';
 
 import 'package:flutter/material.dart';
+import 'package:flutter/rendering.dart';
 
 import '../generated/l10n/zulip_localizations.dart';
 import '../model/narrow.dart';
@@ -48,6 +48,9 @@ class HomePage extends StatefulWidget {
       HomePage.buildRoute(accountId: accountId)));
   }
 
+  static String contentSemanticsIdentifier = 'home-page-content';
+  static String titleSemanticsIdentifier = 'home-page-title';
+
   @override
   State<HomePage> createState() => _HomePageState();
 }
@@ -96,15 +99,20 @@ class _HomePageState extends State<HomePage> {
 
     return Scaffold(
       appBar: ZulipAppBar(titleSpacing: 16,
-        title: Text(_currentTabTitle)),
-      body: Stack(
-        children: [
-          for (final (tab, body) in pageBodies)
-            // TODO(#535): Decide if we find it helpful to use something like
-            //   [SemanticsProperties.namesRoute] to structure this UI better
-            //   for screen-reader software.
-            Offstage(offstage: tab != _tab.value, child: body),
-        ]),
+        title: Semantics(
+          identifier: HomePage.titleSemanticsIdentifier,
+          namesRoute: true,
+          child: Text(_currentTabTitle))),
+      body: Semantics(
+        role: SemanticsRole.tabPanel,
+        identifier: HomePage.contentSemanticsIdentifier,
+        container: true,
+        explicitChildNodes: true,
+        child: Stack(
+          children: [
+            for (final (tab, body) in pageBodies)
+              Offstage(offstage: tab != _tab.value, child: body),
+          ])),
       bottomNavigationBar: _BottomNavBar(tabNotifier: _tab));
   }
 }
@@ -114,13 +122,17 @@ class _BottomNavBar extends StatelessWidget {
 
   final ValueNotifier<_HomePageTab> tabNotifier;
 
-  _NavigationBarButton _button(_HomePageTab tab, IconData icon, String label) {
+  _NavigationBarButton _button({
+    required _HomePageTab tab,
+    required IconData icon,
+    required String label
+  }) {
     return _NavigationBarButton(icon: icon,
+      label: label,
       selected: tabNotifier.value == tab,
       onPressed: () {
         tabNotifier.value = tab;
-      },
-      label: label);
+      });
   }
 
   @override
@@ -130,39 +142,54 @@ class _BottomNavBar extends StatelessWidget {
 
     // TODO(a11y): add tooltips for these buttons
     final navigationBarButtons = [
-      _button(_HomePageTab.inbox,          ZulipIcons.inbox,
-        zulipLocalizations.inboxPageTitle),
-      _NavigationBarButton(         icon: ZulipIcons.message_feed,
+      _button(tab: _HomePageTab.inbox,
+        icon: ZulipIcons.inbox,
+        label: zulipLocalizations.inboxPageTitle),
+      _NavigationBarButton(
+        icon: ZulipIcons.message_feed,
+        label: zulipLocalizations.combinedFeedPageTitle,
         selected: false,
         onPressed: () => Navigator.push(context,
           MessageListPage.buildRoute(context: context,
-            narrow: const CombinedFeedNarrow())),
-        label: zulipLocalizations.combinedFeedPageTitle),
-      _button(_HomePageTab.channels,       ZulipIcons.hash_italic,
-        zulipLocalizations.channelsPageTitle),
+            narrow: const CombinedFeedNarrow()))),
+      _button(tab: _HomePageTab.channels,
+        icon: ZulipIcons.hash_italic,
+        label: zulipLocalizations.channelsPageTitle),
       // TODO(#1094): Users
-      _button(_HomePageTab.directMessages, ZulipIcons.two_person,
-        zulipLocalizations.recentDmConversationsPageTitle),
-      _NavigationBarButton(         icon: ZulipIcons.menu,
+      _button(tab: _HomePageTab.directMessages,
+        icon: ZulipIcons.two_person,
+        label: zulipLocalizations.recentDmConversationsPageTitle),
+      _NavigationBarButton(
+        icon: ZulipIcons.menu,
+        label: zulipLocalizations.navBarMenuLabel,
         selected: false,
-        onPressed: () => _showMainMenu(context, tabNotifier: tabNotifier),
-        label: zulipLocalizations.navBarMenuLabel),
+        onPressed: () => _showMainMenu(context, tabNotifier: tabNotifier)),
     ];
 
-    return DecoratedBox(
+    Widget result = DecoratedBox(
       decoration: BoxDecoration(
         border: Border(top: BorderSide(color: designVariables.borderBar)),
         color: designVariables.bgBotBar),
-      child: SafeArea(
-        child: ConstrainedBox(
-          // TODO(design): determine a suitable max width for bottom nav bar
-          constraints: const BoxConstraints(maxWidth: 600, minHeight: 48),
-          child: Row(
-            crossAxisAlignment: CrossAxisAlignment.start,
-            children: [
-              for (final navigationBarButton in navigationBarButtons)
-                Expanded(child: navigationBarButton),
-            ]))));
+      child: IntrinsicHeight(
+        child: SafeArea(
+          child: Center(
+            child: ConstrainedBox(
+              // TODO(design): determine a suitable max width for bottom nav bar
+              constraints: const BoxConstraints(maxWidth: 600, minHeight: 48),
+              child: Row(
+                crossAxisAlignment: CrossAxisAlignment.start,
+                children: [
+                  for (final navigationBarButton in navigationBarButtons)
+                    Expanded(child: navigationBarButton),
+                ]))))));
+
+    result = Semantics(
+      container: true,
+      explicitChildNodes: true,
+      role: SemanticsRole.tabBar,
+      child: result);
+
+    return result;
   }
 }
 
@@ -262,7 +289,7 @@ class _NavigationBarButton extends StatelessWidget {
     final designVariables = DesignVariables.of(context);
     final color = selected ? designVariables.iconSelected : designVariables.icon;
 
-    return AnimatedScaleOnTap(
+    Widget result = AnimatedScaleOnTap(
       scaleEnd: 0.875,
       duration: const Duration(milliseconds: 100),
       child: Material(
@@ -278,21 +305,31 @@ class _NavigationBarButton extends StatelessWidget {
             // text wrap before getting too close to the button's edge, which is
             // visible on tap-down.)
             padding: const EdgeInsets.fromLTRB(3, 6, 3, 3),
-            child: Semantics(
-              role: SemanticsRole.tab,
-              selected: selected,
-              child: Column(
-                spacing: 3,
-                mainAxisSize: MainAxisSize.min,
-                children: [
-                  Icon(icon, size: 24, color: color),
-                  Flexible(
-                    child: Text(
-                      label,
-                      style: TextStyle(fontSize: 12, color: color, height: 12 / 12),
-                      textAlign: TextAlign.center,
-                      textScaler: MediaQuery.textScalerOf(context).clamp(maxScaleFactor: 1.5))),
-                ]))))));
+            child: Column(
+              spacing: 3,
+              mainAxisSize: MainAxisSize.min,
+              children: [
+                Icon(icon, size: 24, color: color),
+                Flexible(
+                  child: Text(
+                    label,
+                    style: TextStyle(fontSize: 12, color: color, height: 12 / 12),
+                    textAlign: TextAlign.center,
+                    textScaler: MediaQuery.textScalerOf(context).clamp(maxScaleFactor: 1.5))),
+              ])))));
+
+    result = MergeSemantics(
+      child: Semantics(
+        role: SemanticsRole.tab,
+        controlsNodes: {
+          HomePage.contentSemanticsIdentifier,
+          HomePage.titleSemanticsIdentifier,
+        },
+        selected: selected,
+        onTap: onPressed,
+        child: result));
+
+    return result;
   }
 }
 

test/widgets/home_test.dart

@@ -1,3 +1,5 @@
+import 'dart:ui';
+
 import 'package:checks/checks.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_checks/flutter_checks.dart';
@@ -82,19 +84,14 @@ void main () {
   }
 
   group('bottom nav navigation', () {
-    final findBottomNavDecoratedBox = find.byWidgetPredicate((widget) {
-      if (widget is! DecoratedBox) return false;
-
-      final decoration = widget.decoration;
-      if (decoration is! BoxDecoration) return false;
-
-      final expectedBorderTop = BorderSide(color: Colors.black.withValues(alpha: 0.2));
-      return decoration.border == Border(top: expectedBorderTop);
+    final findBottomNavSemantics = find.byWidgetPredicate((widget) {
+      if (widget is! Semantics) return false;
+      return widget.properties.role == SemanticsRole.tabBar;
     });
 
-    // Finds a widget within the bottom navbar's decorated box subtree.
+    // Finds a widget within the bottom navbar's semantics subtree.
     Finder findInBottomNav(Finder finder) =>
-      find.descendant(of: findBottomNavDecoratedBox, matching: finder);
+      find.descendant(of: findBottomNavSemantics, matching: finder);
 
     testWidgets('preserve states when switching between views', (tester) async {
       await prepare(tester);