Reland: Add OrderedFocusTraversalPolicy and FocusTraversalGrou… (#50672)

This re-lands #49235 with the addition of includeSemantics flag on the Focus widget so that the FocusTraversalGroup can create a Focus widget without affecting the semantics tree.

The FocusTraversalGroup uses the Focus widget to create a grouping of descendants for traversal, but doesn't actually participate in focus (canRequestFocus is always false), so we don't want it to add a Semantics widget in that case, since that can cause semantics changes. The canRequestFocus attribute can also be used when a widget is disabled, so we do sometimes want to include Semantics even if that is false, but not in the case where it is always false, as for FocusTraversalGroup.

- Added a test to make sure that FocusTraversalGroup doesn't add any semantics information.

dev/manual_tests/lib/actions.dart

@@ -435,7 +435,7 @@ class _FocusDemoState extends State<FocusDemo> {
         kUndoActionKey: () => kUndoAction,
         kRedoActionKey: () => kRedoAction,
       },
-      child: DefaultFocusTraversal(
+      child: FocusTraversalGroup(
         policy: ReadingOrderTraversalPolicy(),
         child: Shortcuts(
           shortcuts: <LogicalKeySet, Intent>{

dev/manual_tests/lib/focus.dart

@@ -142,7 +142,7 @@ class _FocusDemoState extends State<FocusDemo> {
   Widget build(BuildContext context) {
     final TextTheme textTheme = Theme.of(context).textTheme;
 
-    return DefaultFocusTraversal(
+    return FocusTraversalGroup(
       policy: ReadingOrderTraversalPolicy(),
       child: FocusScope(
         debugLabel: 'Scope',

packages/flutter/lib/src/widgets/app.dart

@@ -1395,7 +1395,7 @@ class _WidgetsAppState extends State<WidgetsApp> with WidgetsBindingObserver {
       debugLabel: '<Default WidgetsApp Shortcuts>',
       child: Actions(
         actions: widget.actions ?? WidgetsApp.defaultActions,
-        child: DefaultFocusTraversal(
+        child: FocusTraversalGroup(
           policy: ReadingOrderTraversalPolicy(),
           child: _MediaQueryFromWindow(
             child: Localizations(

packages/flutter/lib/src/widgets/focus_manager.dart

@@ -232,12 +232,12 @@ class FocusAttachment {
 /// particular direction, is determined by the [FocusTraversalPolicy] in force.
 ///
 /// The ambient policy is determined by looking up the widget hierarchy for a
-/// [DefaultFocusTraversal] widget, and obtaining the focus traversal policy
+/// [FocusTraversalGroup] widget, and obtaining the focus traversal policy
 /// from it. Different focus nodes can inherit difference policies, so part of
 /// the app can go in widget order, and part can go in reading order, depending
 /// upon the use case.
 ///
-/// Predefined policies include [WidgetOrderFocusTraversalPolicy],
+/// Predefined policies include [WidgetOrderTraversalPolicy],
 /// [ReadingOrderTraversalPolicy], and [DirectionalFocusTraversalPolicyMixin],
 /// but custom policies can be built based upon these policies.
 ///
@@ -363,8 +363,8 @@ class FocusAttachment {
 ///    events to focused nodes.
 ///  * [FocusTraversalPolicy], a class used to determine how to move the focus
 ///    to other nodes.
-///  * [DefaultFocusTraversal], a widget used to configure the default focus
-///    traversal policy for a widget subtree.
+///  * [FocusTraversalGroup], a widget used to group together and configure the
+///    focus traversal policy for a widget subtree.
 class FocusNode with DiagnosticableTreeMixin, ChangeNotifier {
   /// Creates a focus node.
   ///
@@ -427,8 +427,8 @@ class FocusNode with DiagnosticableTreeMixin, ChangeNotifier {
   ///
   /// See also:
   ///
-  ///  * [DefaultFocusTraversal], a widget that sets the traversal policy for
-  ///    its descendants.
+  ///  * [FocusTraversalGroup], a widget used to group together and configure the
+  ///    focus traversal policy for a widget subtree.
   ///  * [FocusTraversalPolicy], a class that can be extended to describe a
   ///    traversal policy.
   bool get canRequestFocus {
@@ -518,7 +518,8 @@ class FocusNode with DiagnosticableTreeMixin, ChangeNotifier {
     return _descendants;
   }
 
-  /// Returns all descendants which do not have the [skipTraversal] flag set.
+  /// Returns all descendants which do not have the [skipTraversal] and do have
+  /// the [canRequestFocus] flag set.
   Iterable<FocusNode> get traversalDescendants => descendants.where((FocusNode node) => !node.skipTraversal && node.canRequestFocus);
 
   /// An [Iterable] over the ancestors of this node.
@@ -779,7 +780,7 @@ class FocusNode with DiagnosticableTreeMixin, ChangeNotifier {
       _manager?.primaryFocus?._setAsFocusedChildForScope();
     }
     if (oldScope != null && child.context != null && child.enclosingScope != oldScope) {
-      DefaultFocusTraversal.of(child.context, nullOk: true)?.changedScope(node: child, oldScope: oldScope);
+      FocusTraversalGroup.of(child.context, nullOk: true)?.changedScope(node: child, oldScope: oldScope);
     }
     if (child._requestFocusWhenReparented) {
       child._doRequestFocus();
@@ -918,19 +919,19 @@ class FocusNode with DiagnosticableTreeMixin, ChangeNotifier {
   /// [FocusTraversalPolicy.next] method.
   ///
   /// Returns true if it successfully found a node and requested focus.
-  bool nextFocus() => DefaultFocusTraversal.of(context).next(this);
+  bool nextFocus() => FocusTraversalGroup.of(context).next(this);
 
   /// Request to move the focus to the previous focus node, by calling the
   /// [FocusTraversalPolicy.previous] method.
   ///
   /// Returns true if it successfully found a node and requested focus.
-  bool previousFocus() => DefaultFocusTraversal.of(context).previous(this);
+  bool previousFocus() => FocusTraversalGroup.of(context).previous(this);
 
   /// Request to move the focus to the nearest focus node in the given
   /// direction, by calling the [FocusTraversalPolicy.inDirection] method.
   ///
   /// Returns true if it successfully found a node and requested focus.
-  bool focusInDirection(TraversalDirection direction) => DefaultFocusTraversal.of(context).inDirection(this, direction);
+  bool focusInDirection(TraversalDirection direction) => FocusTraversalGroup.of(context).inDirection(this, direction);
 
   @override
   void debugFillProperties(DiagnosticPropertiesBuilder properties) {

packages/flutter/lib/src/widgets/focus_scope.dart

@@ -149,8 +149,10 @@ class Focus extends StatefulWidget {
     this.debugLabel,
     this.canRequestFocus,
     this.skipTraversal,
+    this.includeSemantics = true,
   })  : assert(child != null),
         assert(autofocus != null),
+        assert(includeSemantics != null),
         super(key: key);
 
   /// A debug label for this widget.
@@ -231,6 +233,17 @@ class Focus extends StatefulWidget {
   /// still be focused explicitly.
   final bool skipTraversal;
 
+  /// Include semantics information in this [Focus] widget.
+  ///
+  /// If true, this [Focus] widget will include a [Semantics] node that
+  /// indicates the [Semantics.focusable] and [Semantics.focused] properties.
+  ///
+  /// Is is not typical to set this to false, as that can affect the semantics
+  /// information available to accessibility systems.
+  ///
+  /// Must not be null, defaults to true.
+  final bool includeSemantics;
+
   /// {@template flutter.widgets.Focus.canRequestFocus}
   /// If true, this widget may request the primary focus.
   ///
@@ -459,13 +472,17 @@ class _FocusState extends State<Focus> {
   @override
   Widget build(BuildContext context) {
     _focusAttachment.reparent();
-    return _FocusMarker(
-      node: focusNode,
-      child: Semantics(
+    Widget child = widget.child;
+    if (widget.includeSemantics) {
+      child = Semantics(
         focusable: _canRequestFocus,
         focused: _hasPrimaryFocus,
         child: widget.child,
-      ),
+      );
+    }
+    return _FocusMarker(
+      node: focusNode,
+      child: child,
     );
   }
 }

packages/flutter/lib/src/widgets/framework.dart

@@ -2191,6 +2191,8 @@ abstract class BuildContext {
   /// Obtains the element corresponding to the nearest widget of the given type [T],
   /// which must be the type of a concrete [InheritedWidget] subclass.
   ///
+  /// Returns null if no such element is found.
+  ///
   /// Calling this method is O(1) with a small constant factor.
   ///
   /// This method does not establish a relationship with the target in the way

packages/flutter/test/material/checkbox_test.dart

@@ -68,7 +68,7 @@ void main() {
       ),
     ));
 
-    expect(tester.getSemantics(find.byType(Focus).last), matchesSemantics(
+    expect(tester.getSemantics(find.byType(Focus)), matchesSemantics(
       hasCheckedState: true,
       hasEnabledState: true,
       isEnabled: true,
@@ -83,7 +83,7 @@ void main() {
       ),
     ));
 
-    expect(tester.getSemantics(find.byType(Focus).last), matchesSemantics(
+    expect(tester.getSemantics(find.byType(Focus)), matchesSemantics(
       hasCheckedState: true,
       hasEnabledState: true,
       isChecked: true,
@@ -99,7 +99,7 @@ void main() {
       ),
     ));
 
-    expect(tester.getSemantics(find.byType(Focus).last), matchesSemantics(
+    expect(tester.getSemantics(find.byWidgetPredicate((Widget widget) => widget.runtimeType.toString() == '_CheckboxRenderObjectWidget')), matchesSemantics(
       hasCheckedState: true,
       hasEnabledState: true,
     ));
@@ -111,7 +111,7 @@ void main() {
       ),
     ));
 
-    expect(tester.getSemantics(find.byType(Focus).last), matchesSemantics(
+    expect(tester.getSemantics(find.byWidgetPredicate((Widget widget) => widget.runtimeType.toString() == '_CheckboxRenderObjectWidget')), matchesSemantics(
       hasCheckedState: true,
       hasEnabledState: true,
       isChecked: true,

packages/flutter/test/material/debug_test.dart

@@ -116,7 +116,7 @@ void main() {
       '   The ancestors of this widget were:\n'
       '     Semantics\n'
       '     Builder\n'
-      '     RepaintBoundary-[GlobalKey#2d465]\n'
+      '     RepaintBoundary-[GlobalKey#00000]\n'
       '     IgnorePointer\n'
       '     AnimatedBuilder\n'
       '     FadeTransition\n'
@@ -131,19 +131,19 @@ void main() {
       '     PageStorage\n'
       '     Offstage\n'
       '     _ModalScopeStatus\n'
-      '     _ModalScope<dynamic>-[LabeledGlobalKey<_ModalScopeState<dynamic>>#969b7]\n'
+      '     _ModalScope<dynamic>-[LabeledGlobalKey<_ModalScopeState<dynamic>>#00000]\n'
       '     _EffectiveTickerMode\n'
       '     TickerMode\n'
-      '     _OverlayEntryWidget-[LabeledGlobalKey<_OverlayEntryWidgetState>#545d0]\n'
+      '     _OverlayEntryWidget-[LabeledGlobalKey<_OverlayEntryWidgetState>#00000]\n'
       '     _Theatre\n'
-      '     Overlay-[LabeledGlobalKey<OverlayState>#31a52]\n'
+      '     Overlay-[LabeledGlobalKey<OverlayState>#00000]\n'
       '     _FocusMarker\n'
       '     Semantics\n'
       '     FocusScope\n'
       '     AbsorbPointer\n'
       '     _PointerListener\n'
       '     Listener\n'
-      '     Navigator-[GlobalObjectKey<NavigatorState> _WidgetsAppState#10579]\n'
+      '     Navigator-[GlobalObjectKey<NavigatorState> _WidgetsAppState#00000]\n'
       '     IconTheme\n'
       '     IconTheme\n'
       '     _InheritedCupertinoTheme\n'
@@ -158,19 +158,22 @@ void main() {
       '     CheckedModeBanner\n'
       '     Title\n'
       '     Directionality\n'
-      '     _LocalizationsScope-[GlobalKey#a51e3]\n'
+      '     _LocalizationsScope-[GlobalKey#00000]\n'
       '     Semantics\n'
       '     Localizations\n'
       '     MediaQuery\n'
       '     _MediaQueryFromWindow\n'
-      '     DefaultFocusTraversal\n'
+      '     _FocusMarker\n'
+      '     Focus\n'
+      '     _FocusTraversalGroupMarker\n'
+      '     FocusTraversalGroup\n'
       '     Actions\n'
       '     _ShortcutsMarker\n'
       '     Semantics\n'
       '     _FocusMarker\n'
       '     Focus\n'
       '     Shortcuts\n'
-      '     WidgetsApp-[GlobalObjectKey _MaterialAppState#38e79]\n'
+      '     WidgetsApp-[GlobalObjectKey _MaterialAppState#00000]\n'
       '     ScrollConfiguration\n'
       '     MaterialApp\n'
       '     [root]\n'

packages/flutter/test/material/icon_button_test.dart

@@ -570,7 +570,7 @@ void main() {
 }
 
 Widget wrap({ Widget child }) {
-  return DefaultFocusTraversal(
+  return FocusTraversalGroup(
     policy: ReadingOrderTraversalPolicy(),
     child: Directionality(
       textDirection: TextDirection.ltr,

packages/flutter/test/widgets/focus_scope_test.dart

@@ -598,7 +598,7 @@ void main() {
       // This checks both FocusScopes that have their own nodes, as well as those
       // that use external nodes.
       await tester.pumpWidget(
-        DefaultFocusTraversal(
+        FocusTraversalGroup(
           child: Column(
             children: <Widget>[
               FocusScope(
@@ -661,7 +661,7 @@ void main() {
       final FocusScopeNode parentFocusScope2 = FocusScopeNode(debugLabel: 'Parent Scope 2');
 
       await tester.pumpWidget(
-        DefaultFocusTraversal(
+        FocusTraversalGroup(
           child: Column(
             children: <Widget>[
               FocusScope(
@@ -711,7 +711,7 @@ void main() {
       expect(find.text('b'), findsOneWidget);
 
       await tester.pumpWidget(
-        DefaultFocusTraversal(
+        FocusTraversalGroup(
           child: Column(
             children: <Widget>[
               FocusScope(
@@ -746,7 +746,7 @@ void main() {
       final FocusScopeNode parentFocusScope2 = FocusScopeNode(debugLabel: 'Parent Scope 2');
 
       await tester.pumpWidget(
-        DefaultFocusTraversal(
+        FocusTraversalGroup(
           child: Column(
             children: <Widget>[
               FocusScope(
@@ -794,7 +794,7 @@ void main() {
       expect(find.text('b'), findsOneWidget);
 
       await tester.pumpWidget(
-        DefaultFocusTraversal(
+        FocusTraversalGroup(
           child: Column(
             children: <Widget>[
               FocusScope(