[web] better class names for semantics (flutter#54070)

A few non-functional clean-ups in semantics:

* Rename `RoleManager` to `SemanticBehavior`.
* Rename `PrimaryRoleManager` to `SemanticRole`.
* Remove the `Role` enum. Move the enum docs into the respective classes.

## Why?

Previous naming was confusing. It's not clear what the difference is between a "role manager" and a "primary role manager". The word "manager" is a meaningless addition; the `Semantic*` prefix is much more meaningful. The `Role` enum was only used for tests, but tests can just use `SemanticRole.runtimeType`.

## New state of the world

After this PR the semantics system has "objects" (class `SemanticsObject`), "roles" (class `SemanticRole`), and "behaviors" (class `SemanticBehavior`).

- A semantic _object_ is an object attached to the framework-side `SemanticNode`. It lives as long as the semantic node does, and provides basic functionality that's common across all nodes.
- A semantic object has exactly one semantic _role_. This role is determined from the flags set on the semantic node. Flags can change, causing a semantic object to change its role, which is why these are two separate classes. If an object had just one permanent role, we could combine these classes into one (maybe one day we'll do it, as changing roles dynamically is weird, but that needs major changes in the framework).
- A semantic role may have zero or more semantic _behaviors_. A behavior supplies a piece of functionality, such as focusability, clickability/tappability, live regions, etc. A behavior can be shared by multiple roles. For example, both `Button` and `Checkable` roles use the `Tappable` behavior. This is why there's a many-to-many relationship between roles and behaviors.

Or in entity relationship terms:

```mermaid
---
title: Semantic object relationships
---
erDiagram
    SemanticsNode ||--|| SemanticsObject : managed-by
    SemanticsObject ||--o{ SemanticRole : has-a
    SemanticRole }o--o{ SemanticBehavior : has
```

Author: yjbanov

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

@@ -49,11 +49,11 @@ _CheckableKind _checkableKindFromSemanticsFlag(
 /// See also [ui.SemanticsFlag.hasCheckedState], [ui.SemanticsFlag.isChecked],
 /// [ui.SemanticsFlag.isInMutuallyExclusiveGroup], [ui.SemanticsFlag.isToggled],
 /// [ui.SemanticsFlag.hasToggledState]
-class Checkable extends PrimaryRoleManager {
-  Checkable(SemanticsObject semanticsObject)
+class SemanticCheckable extends SemanticRole {
+  SemanticCheckable(SemanticsObject semanticsObject)
       : _kind = _checkableKindFromSemanticsFlag(semanticsObject),
         super.withBasics(
-          PrimaryRole.checkable,
+          SemanticRoleKind.checkable,
           semanticsObject,
           preferredLabelRepresentation: LabelRepresentation.ariaLabel,
         ) {

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

@@ -6,12 +6,10 @@ import '../dom.dart';
 import '../semantics.dart';
 import '../util.dart';
 
-/// Provides accessibility for dialogs.
-///
-/// See also [Role.dialog].
-class Dialog extends PrimaryRoleManager {
-  Dialog(SemanticsObject semanticsObject) : super.blank(PrimaryRole.dialog, semanticsObject) {
-    // The following secondary roles can coexist with dialog. Generic `RouteName`
+/// Provides accessibility for routes, including dialogs and pop-up menus.
+class SemanticDialog extends SemanticRole {
+  SemanticDialog(SemanticsObject semanticsObject) : super.blank(SemanticRoleKind.dialog, semanticsObject) {
+    // The following behaviors can coexist with dialog. Generic `RouteName`
     // and `LabelAndValue` are not used by this role because when the dialog
     // names its own route an `aria-label` is used instead of `aria-describedby`.
     addFocusManagement();
@@ -39,14 +37,14 @@ class Dialog extends PrimaryRoleManager {
 
   void _setDefaultFocus() {
     semanticsObject.visitDepthFirstInTraversalOrder((SemanticsObject node) {
-      final PrimaryRoleManager? roleManager = node.primaryRole;
-      if (roleManager == null) {
+      final SemanticRole? role = node.semanticRole;
+      if (role == 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();
+      final bool didTakeFocus = role.focusAsRouteDefault();
       return !didTakeFocus;
     });
   }
@@ -99,14 +97,18 @@ class Dialog extends PrimaryRoleManager {
   }
 }
 
-/// Supplies a description for the nearest ancestor [Dialog].
-class RouteName extends RoleManager {
-  RouteName(
-    SemanticsObject semanticsObject,
-    PrimaryRoleManager owner,
-  ) : super(Role.routeName, semanticsObject, owner);
+/// Supplies a description for the nearest ancestor [SemanticDialog].
+///
+/// This role is assigned to nodes that have `namesRoute` set but not
+/// `scopesRoute`. When both flags are set the node only gets the [SemanticDialog] role.
+///
+/// If the ancestor dialog is missing, this role has no effect. It is up to the
+/// framework, widget, and app authors to make sure a route name is scoped under
+/// a route.
+class RouteName extends SemanticBehavior {
+  RouteName(super.semanticsObject, super.owner);
 
-  Dialog? _dialog;
+  SemanticDialog? _dialog;
 
   @override
   void update() {
@@ -124,7 +126,7 @@ class RouteName extends RoleManager {
     }
 
     if (semanticsObject.isLabelDirty) {
-      final Dialog? dialog = _dialog;
+      final SemanticDialog? dialog = _dialog;
       if (dialog != null) {
         // Already attached to a dialog, just update the description.
         dialog.describeBy(this);
@@ -143,11 +145,11 @@ class RouteName extends RoleManager {
 
   void _lookUpNearestAncestorDialog() {
     SemanticsObject? parent = semanticsObject.parent;
-    while (parent != null && parent.primaryRole?.role != PrimaryRole.dialog) {
+    while (parent != null && parent.semanticRole?.kind != SemanticRoleKind.dialog) {
       parent = parent.parent;
     }
-    if (parent != null && parent.primaryRole?.role == PrimaryRole.dialog) {
-      _dialog = parent.primaryRole! as Dialog;
+    if (parent != null && parent.semanticRole?.kind == SemanticRoleKind.dialog) {
+      _dialog = parent.semanticRole! as SemanticDialog;
     }
   }
 }

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

@@ -12,9 +12,9 @@ import 'semantics.dart';
 /// Supplies generic accessibility focus features to semantics nodes that have
 /// [ui.SemanticsFlag.isFocusable] set.
 ///
-/// Assumes that the element being focused on is [SemanticsObject.element]. Role
-/// managers with special needs can implement custom focus management and
-/// exclude this role manager.
+/// Assumes that the element being focused on is [SemanticsObject.element].
+/// Semantic roles with special needs can implement custom focus management and
+/// exclude this behavior.
 ///
 /// `"tab-index=0"` is used because `<flt-semantics>` is not intrinsically
 /// focusable. Examples of intrinsically focusable elements include:
@@ -27,10 +27,9 @@ import 'semantics.dart';
 /// See also:
 ///
 ///   * https://developer.mozilla.org/en-US/docs/Web/Accessibility/Keyboard-navigable_JavaScript_widgets
-class Focusable extends RoleManager {
-  Focusable(SemanticsObject semanticsObject, PrimaryRoleManager owner)
-      : _focusManager = AccessibilityFocusManager(semanticsObject.owner),
-        super(Role.focusable, semanticsObject, owner);
+class Focusable extends SemanticBehavior {
+  Focusable(super.semanticsObject, super.owner)
+      : _focusManager = AccessibilityFocusManager(semanticsObject.owner);
 
   final AccessibilityFocusManager _focusManager;
 
@@ -44,9 +43,9 @@ class Focusable extends RoleManager {
   /// 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.
+  /// Returns `true` if the node took the focus. Returns `false` if the node 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() {
     _focusManager._lastEvent = AccessibilityFocusManagerEvent.requestedFocus;
     owner.element.focusWithoutScroll();
@@ -106,10 +105,10 @@ enum AccessibilityFocusManagerEvent {
 ///
 /// Unlike [Focusable], which implements focus features on [SemanticsObject]s
 /// whose [SemanticsObject.element] is directly focusable, this class can help
-/// implementing focus features on custom elements. For example, [Incrementable]
-/// uses a custom `<input>` tag internally while its root-level element is not
-/// focusable. However, it can still use this class to manage the focus of the
-/// internal element.
+/// implementing focus features on custom elements. For example,
+/// [SemanticIncrementable] uses a custom `<input>` tag internally while its
+/// root-level element is not focusable. However, it can still use this class to
+/// manage the focus of the internal element.
 class AccessibilityFocusManager {
   /// Creates a focus manager tied to a specific [EngineSemanticsOwner].
   AccessibilityFocusManager(this._owner);

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

@@ -8,9 +8,9 @@ import 'semantics.dart';
 
 /// Renders semantics objects as headings with the corresponding
 /// level (h1 ... h6).
-class Heading extends PrimaryRoleManager {
-  Heading(SemanticsObject semanticsObject)
-      : super.blank(PrimaryRole.heading, semanticsObject) {
+class SemanticHeading extends SemanticRole {
+  SemanticHeading(SemanticsObject semanticsObject)
+      : super.blank(SemanticRoleKind.heading, semanticsObject) {
     addFocusManagement();
     addLiveRegion();
     addRouteName();

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

@@ -10,11 +10,11 @@ import 'semantics.dart';
 /// Uses aria img role to convey this semantic information to the element.
 ///
 /// Screen-readers takes advantage of "aria-label" to describe the visual.
-class ImageRoleManager extends PrimaryRoleManager {
-  ImageRoleManager(SemanticsObject semanticsObject)
-      : super.blank(PrimaryRole.image, semanticsObject) {
-    // The following secondary roles can coexist with images. `LabelAndValue` is
-    // not used because this role manager uses special auxiliary elements to
+class SemanticImage extends SemanticRole {
+  SemanticImage(SemanticsObject semanticsObject)
+      : super.blank(SemanticRoleKind.image, semanticsObject) {
+    // The following behaviors can coexist with images. `LabelAndValue` is
+    // not used because this behavior uses special auxiliary elements to
     // supply ARIA labels.
     // TODO(yjbanov): reevaluate usage of aux elements, https://github.com/flutter/flutter/issues/129317
     addFocusManagement();

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

@@ -19,10 +19,10 @@ import 'semantics.dart';
 /// The input element is disabled whenever the gesture mode switches to pointer
 /// events. This is to prevent the browser from taking over drag gestures. Drag
 /// gestures must be interpreted by the Flutter framework.
-class Incrementable extends PrimaryRoleManager {
-  Incrementable(SemanticsObject semanticsObject)
+class SemanticIncrementable extends SemanticRole {
+  SemanticIncrementable(SemanticsObject semanticsObject)
       : _focusManager = AccessibilityFocusManager(semanticsObject.owner),
-        super.blank(PrimaryRole.incrementable, semanticsObject) {
+        super.blank(SemanticRoleKind.incrementable, semanticsObject) {
     // The following generic roles can coexist with incrementables. Generic focus
     // management is not used by this role because the root DOM element is not
     // the one being focused on, but the internal `<input>` element.

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

@@ -48,7 +48,7 @@ enum LabelRepresentation {
   sizedSpan;
 
   /// Creates the behavior for this label representation.
-  LabelRepresentationBehavior createBehavior(PrimaryRoleManager owner) {
+  LabelRepresentationBehavior createBehavior(SemanticRole owner) {
     return switch (this) {
       ariaLabel => AriaLabelRepresentation._(owner),
       domText => DomTextRepresentation._(owner),
@@ -63,8 +63,8 @@ abstract final class LabelRepresentationBehavior {
 
   final LabelRepresentation kind;
 
-  /// The role manager that this label representation is attached to.
-  final PrimaryRoleManager owner;
+  /// The role that this label representation is attached to.
+  final SemanticRole owner;
 
   /// Convenience getter for the corresponding semantics object.
   SemanticsObject get semanticsObject => owner.semanticsObject;
@@ -109,7 +109,7 @@ abstract final class LabelRepresentationBehavior {
 ///
 ///     <flt-semantics aria-label="Hello, World!"></flt-semantics>
 final class AriaLabelRepresentation extends LabelRepresentationBehavior {
-  AriaLabelRepresentation._(PrimaryRoleManager owner) : super(LabelRepresentation.ariaLabel, owner);
+  AriaLabelRepresentation._(SemanticRole owner) : super(LabelRepresentation.ariaLabel, owner);
 
   String? _previousLabel;
 
@@ -143,7 +143,7 @@ final class AriaLabelRepresentation extends LabelRepresentationBehavior {
 /// no ARIA role set, or the role does not size the element, then the
 /// [SizedSpanRepresentation] representation can be used.
 final class DomTextRepresentation extends LabelRepresentationBehavior {
-  DomTextRepresentation._(PrimaryRoleManager owner) : super(LabelRepresentation.domText, owner);
+  DomTextRepresentation._(SemanticRole owner) : super(LabelRepresentation.domText, owner);
 
   DomText? _domText;
   String? _previousLabel;
@@ -233,7 +233,7 @@ typedef _Measurement = ({
 /// * Use an existing non-text role, e.g. "heading". Sizes correctly, but breaks
 ///   the message (reads "heading").
 final class SizedSpanRepresentation extends LabelRepresentationBehavior {
-  SizedSpanRepresentation._(PrimaryRoleManager owner) : super(LabelRepresentation.sizedSpan, owner) {
+  SizedSpanRepresentation._(SemanticRole owner) : super(LabelRepresentation.sizedSpan, owner) {
     _domText.style
       // `inline-block` is needed for two reasons:
       // - It supports measuring the true size of the text. Pure `block` would
@@ -433,14 +433,13 @@ final class SizedSpanRepresentation extends LabelRepresentationBehavior {
   DomElement get focusTarget => _domText;
 }
 
-/// Renders [SemanticsObject.label] and/or [SemanticsObject.value] to the semantics DOM.
+/// Renders the label for a [SemanticsObject] that can be scanned by screen
+/// readers, web crawlers, and other automated agents.
 ///
-/// The value is not always rendered. Some semantics nodes correspond to
-/// interactive controls. In such case the value is reported via that element's
-/// `value` attribute rather than rendering it separately.
-class LabelAndValue extends RoleManager {
-  LabelAndValue(SemanticsObject semanticsObject, PrimaryRoleManager owner, { required this.preferredRepresentation })
-      : super(Role.labelAndValue, semanticsObject, owner);
+/// See [computeDomSemanticsLabel] for the exact logic that constructs the label
+/// of a semantic node.
+class LabelAndValue extends SemanticBehavior {
+  LabelAndValue(super.semanticsObject, super.owner, { required this.preferredRepresentation });
 
   /// The preferred representation of the label in the DOM.
   ///
@@ -471,7 +470,7 @@ class LabelAndValue extends RoleManager {
   /// If the node has children always use an `aria-label`. Using extra child
   /// nodes to represent the label will cause layout shifts and confuse the
   /// screen reader. If the are no children, use the representation preferred
-  /// by the primary role manager.
+  /// by the role.
   LabelRepresentationBehavior _getEffectiveRepresentation() {
     final LabelRepresentation effectiveRepresentation = semanticsObject.hasChildren
       ? LabelRepresentation.ariaLabel
@@ -491,7 +490,7 @@ class LabelAndValue extends RoleManager {
   /// combination is present.
   String? _computeLabel() {
     // If the node is incrementable the value is reported to the browser via
-    // the respective role manager. We do not need to also render it again here.
+    // the respective role. We do not need to also render it again here.
     final bool shouldDisplayValue = !semanticsObject.isIncrementable && semanticsObject.hasValue;
 
     return computeDomSemanticsLabel(

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

@@ -6,9 +6,9 @@ import '../dom.dart';
 import '../semantics.dart';
 
 /// Provides accessibility for links.
-class Link extends PrimaryRoleManager {
-  Link(SemanticsObject semanticsObject) : super.withBasics(
-    PrimaryRole.link,
+class SemanticLink extends SemanticRole {
+  SemanticLink(SemanticsObject semanticsObject) : super.withBasics(
+    SemanticRoleKind.link,
     semanticsObject,
     preferredLabelRepresentation: LabelRepresentation.domText,
   ) {

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

@@ -10,15 +10,21 @@ import 'semantics.dart';
 
 /// Manages semantics configurations that represent live regions.
 ///
-/// Assistive technologies treat "aria-live" attribute differently. To keep
-/// the behavior consistent, [AccessibilityAnnouncements.announce] is used.
+/// A live region is a region whose changes will be announced by the screen
+/// reader without the user moving focus onto the node.
+///
+/// Examples of live regions include snackbars and text field errors. Once
+/// identified with this role, they will be able to get the assistive
+/// technology's attention right away.
+///
+/// Different assistive technologies treat "aria-live" attribute differently. To
+/// keep the behavior consistent, [AccessibilityAnnouncements.announce] is used.
 ///
 /// When there is an update to [LiveRegion], assistive technologies read the
 /// label of the element. See [LabelAndValue]. If there is no label provided
 /// no content will be read.
-class LiveRegion extends RoleManager {
-  LiveRegion(SemanticsObject semanticsObject, PrimaryRoleManager owner)
-      : super(Role.liveRegion, semanticsObject, owner);
+class LiveRegion extends SemanticBehavior {
+  LiveRegion(super.semanticsObject, super.owner);
 
   String? _lastAnnouncement;
 

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

@@ -20,10 +20,10 @@ import 'semantics.dart';
 /// See also:
 ///   * https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-owns
 ///   * https://bugs.webkit.org/show_bug.cgi?id=223798
-class PlatformViewRoleManager extends PrimaryRoleManager {
-  PlatformViewRoleManager(SemanticsObject semanticsObject)
+class SemanticPlatformView extends SemanticRole {
+  SemanticPlatformView(SemanticsObject semanticsObject)
       : super.withBasics(
-          PrimaryRole.platformView,
+          SemanticRoleKind.platformView,
           semanticsObject,
           preferredLabelRepresentation: LabelRepresentation.ariaLabel,
         );