[web] autofocus in new routes (#47727)

Fixes flutter/flutter#138371

When a new route pops up the expectation is that the screen reader focuses on something in the new route. Since routes typically result in DOM nodes being replaced, the current effect is that the screen reader simply unfocuses from the page, causing the user to have to refocus on back on the page and look for elements to interact with, which is a poor user experience. The current workaround is to use `autofocus`, but that doesn't scale as it's easy to forget, and if the route in question is maintained by a different person you may not even have enough control over it to set `autofocus` on anything. For example, this is the case with Flutter's default date picker. All you have is `showDatePicker` and there's no way to control the focus.

With this change the route (managed by the `Dialog` primary role) will check if a widget requested explicit focus (perhaps using `autofocus`), and if not, looks for the first descendant that a screen reader can focus on, and requests focus on it. The auto-focused element does not have to be literally focusable. For example, plain `Text` nodes do not have input focus (i.e. they are not `isFocusable`) but screen readers can still focus on them. If such an element is found, the web engine requests that the browser move focus to it programmatically (`element.focus()`), which causes the screen reader to move the a11y focus to it as well, but it sets `tabindex=-1` so the element is not focusable via keyboard or mouse.

Author: yjbanov

lib/web_ui/lib/src/engine/semantics/checkable.dart

@@ -102,4 +102,7 @@ class Checkable extends PrimaryRoleManager {
     removeAttribute('aria-disabled');
     removeAttribute('disabled');
   }
+
+  @override
+  bool focusAsRouteDefault() => focusable?.focusAsRouteDefault() ?? false;
 }

lib/web_ui/lib/src/engine/semantics/dialog.dart

@@ -16,6 +16,39 @@ class Dialog extends PrimaryRoleManager {
     // names its own route an `aria-label` is used instead of `aria-describedby`.
     addFocusManagement();
     addLiveRegion();
+
+    // When a route/dialog shows up it is expected that the screen reader will
+    // focus on something inside it. There could be two possibilities:
+    //
+    // 1. The framework explicitly marked a node inside the dialog as focused
+    //    via the `isFocusable` and `isFocused` flags. In this case, the node
+    //    will request focus directly and there's nothing to do on top of that.
+    // 2. No node inside the route takes focus explicitly. In this case, the
+    //    expectation is to look through all nodes in traversal order and focus
+    //    on the first one.
+    semanticsObject.owner.addOneTimePostUpdateCallback(() {
+      if (semanticsObject.owner.hasNodeRequestingFocus) {
+        // Case 1: a node requested explicit focus. Nothing extra to do.
+        return;
+      }
+
+      // Case 2: nothing requested explicit focus. Focus on the first descendant.
+      _setDefaultFocus();
+    });
+  }
+
+  void _setDefaultFocus() {
+    semanticsObject.visitDepthFirstInTraversalOrder((SemanticsObject node) {
+      final PrimaryRoleManager? roleManager = node.primaryRole;
+      if (roleManager == null) {
+        return true;
+      }
+
+      // If the node does not take focus (e.g. focusing on it does not make
+      // sense at all). Despair not. Keep looking.
+      final bool didTakeFocus = roleManager.focusAsRouteDefault();
+      return !didTakeFocus;
+    });
   }
 
   @override
@@ -57,6 +90,13 @@ class Dialog extends PrimaryRoleManager {
       routeName.semanticsObject.element.id,
     );
   }
+
+  @override
+  bool focusAsRouteDefault() {
+    // Dialogs are the ones that look inside themselves to find elements to
+    // focus on. It doesn't make sense to focus on the dialog itself.
+    return false;
+  }
 }
 
 /// Supplies a description for the nearest ancestor [Dialog].

lib/web_ui/lib/src/engine/semantics/focusable.dart

@@ -34,6 +34,24 @@ class Focusable extends RoleManager {
 
   final AccessibilityFocusManager _focusManager;
 
+  /// Requests focus as a result of a route (e.g. dialog) deciding that the node
+  /// managed by this class should be focused by default when nothing requests
+  /// focus explicitly.
+  ///
+  /// This method of taking focus is different from the regular method of using
+  /// the [SemanticsObject.hasFocus] flag, as in this case the framework did not
+  /// explicitly request focus. Instead, the DOM element is being focus directly
+  /// programmatically, simulating the screen reader choosing a default element
+  /// to focus on.
+  ///
+  /// Returns `true` if the role manager took the focus. Returns `false` if
+  /// this role manager did not take the focus. The return value can be used to
+  /// decide whether to stop searching for a node that should take focus.
+  bool focusAsRouteDefault() {
+    owner.element.focus();
+    return true;
+  }
+
   @override
   void update() {
     if (semanticsObject.isFocusable) {
@@ -84,6 +102,14 @@ class AccessibilityFocusManager {
 
   _FocusTarget? _target;
 
+  // The last focus value set by this focus manager, used to prevent requesting
+  // focus on the same element repeatedly. Requesting focus on DOM elements is
+  // not an idempotent operation. If the element is already focused and focus is
+  // requested the browser will scroll to that element. However, scrolling is
+  // not this class' concern and so this class should avoid doing anything that
+  // would affect scrolling.
+  bool? _lastSetValue;
+
   /// Whether this focus manager is managing a focusable target.
   bool get isManaging => _target != null;
 
@@ -136,6 +162,7 @@ class AccessibilityFocusManager {
   void stopManaging() {
     final _FocusTarget? target = _target;
     _target = null;
+    _lastSetValue = null;
 
     if (target == null) {
       /// Nothing is being managed. Just return.
@@ -144,11 +171,6 @@ class AccessibilityFocusManager {
 
     target.element.removeEventListener('focus', target.domFocusListener);
     target.element.removeEventListener('blur', target.domBlurListener);
-
-    // Blur the element after removing listeners. If this method is being called
-    // it indicates that the framework already knows that this node should not
-    // have focus, and there's no need to notify it.
-    target.element.blur();
   }
 
   void _setFocusFromDom(bool acquireFocus) {
@@ -174,6 +196,10 @@ class AccessibilityFocusManager {
     final _FocusTarget? target = _target;
 
     if (target == null) {
+      // If this branch is being executed, there's a bug somewhere already, but
+      // it doesn't hurt to clean up old values anyway.
+      _lastSetValue = null;
+
       // Nothing is being managed right now.
       assert(() {
         printWarning(
@@ -185,6 +211,32 @@ class AccessibilityFocusManager {
       return;
     }
 
+    if (value == _lastSetValue) {
+      // The focus is being changed to a value that's already been requested in
+      // the past. Do nothing.
+      return;
+    }
+    _lastSetValue = value;
+
+    if (value) {
+      _owner.willRequestFocus();
+    } else {
+      // Do not blur elements. Instead let the element be blurred by requesting
+      // focus elsewhere. Blurring elements is a very error-prone thing to do,
+      // as it is subject to non-local effects. Let's say the framework decides
+      // that a semantics node is currently not focused. That would lead to
+      // changeFocus(false) to be called. However, what if this node is inside
+      // a dialog, and nothing else in the dialog is focused. The Flutter
+      // framework expects that the screen reader will focus on the first (in
+      // traversal order) focusable element inside the dialog and send a
+      // didGainAccessibilityFocus action. Screen readers on the web do not do
+      // that, and so the web engine has to implement this behavior directly. So
+      // the dialog will look for a focusable element and request focus on it,
+      // but now there may be a race between this method unsetting the focus and
+      // the dialog requesting focus on the same element.
+      return;
+    }
+
     // Delay the focus request until the final DOM structure is established
     // because the element may not yet be attached to the DOM, or it may be
     // reparented and lose focus again.
@@ -197,11 +249,7 @@ class AccessibilityFocusManager {
         return;
       }
 
-      if (value) {
-        target.element.focus();
-      } else {
-        target.element.blur();
-      }
+      target.element.focus();
     });
   }
 }

lib/web_ui/lib/src/engine/semantics/image.dart

@@ -23,6 +23,9 @@ class ImageRoleManager extends PrimaryRoleManager {
     addTappable();
   }
 
+  @override
+  bool focusAsRouteDefault() => focusable?.focusAsRouteDefault() ?? false;
+
   /// The element with role="img" and aria-label could block access to all
   /// children elements, therefore create an auxiliary element and  describe the
   /// image in that if the semantic object have child nodes.

lib/web_ui/lib/src/engine/semantics/incrementable.dart

@@ -59,6 +59,12 @@ class Incrementable extends PrimaryRoleManager {
     _focusManager.manage(semanticsObject.id, _element);
   }
 
+  @override
+  bool focusAsRouteDefault() {
+    _element.focus();
+    return true;
+  }
+
   /// The HTML element used to render semantics to the browser.
   final DomHTMLInputElement _element = createDomHTMLInputElement();
 

lib/web_ui/lib/src/engine/semantics/link.dart

@@ -18,4 +18,7 @@ class Link extends PrimaryRoleManager {
     element.style.display = 'block';
     return element;
   }
+
+  @override
+  bool focusAsRouteDefault() => focusable?.focusAsRouteDefault() ?? false;
 }

lib/web_ui/lib/src/engine/semantics/platform_view.dart

@@ -38,4 +38,13 @@ class PlatformViewRoleManager extends PrimaryRoleManager {
       removeAttribute('aria-owns');
     }
   }
+
+  @override
+  bool focusAsRouteDefault() {
+    // It's unclear how it's possible to auto-focus on something inside a
+    // platform view without knowing what's in it. If the framework adds API for
+    // focusing on platform view internals, this method will be able to do more,
+    // but for now there's nothing to focus on.
+    return false;
+  }
 }

lib/web_ui/lib/src/engine/semantics/scrollable.dart

@@ -239,4 +239,7 @@ class Scrollable extends PrimaryRoleManager {
       _gestureModeListener = null;
     }
   }
+
+  @override
+  bool focusAsRouteDefault() => focusable?.focusAsRouteDefault() ?? false;
 }