Introduce SemanticsFlag.hasSelectedState to the engine API (#55780)

Introduce `SemanticsFlag.hasSelectedState` to the engine API. At this point the flag is not backed by any engine functionality. See also: #66673 (comment)

| ⚠️ WARNING           |
|:----------------------------|
| Submit _AFTER_ #157017 and #157061 land in the framework     |

A step towards #66673

Author: yjbanov

lib/ui/semantics.dart

@@ -342,15 +342,27 @@ class SemanticsFlag {
   static const int _kIsCheckStateMixedIndex = 1 << 25;
   static const int _kHasExpandedStateIndex = 1 << 26;
   static const int _kIsExpandedIndex = 1 << 27;
-  // READ THIS: if you add a flag here, you MUST update the numSemanticsFlags
-  // value in testing/dart/semantics_test.dart and
-  // lib/web_ui/test/engine/semantics/semantics_api_test.dart, or tests will
-  // fail. Also, please update the Flag enum in
-  // flutter/shell/platform/android/io/flutter/view/AccessibilityBridge.java,
-  // and the SemanticsFlag class in lib/web_ui/lib/semantics.dart. If the new flag
-  // affects the visibility of a [SemanticsNode] to accessibility services,
-  // `flutter_test/controller.dart#SemanticsController._importantFlags`
-  // must be updated as well.
+  static const int _kHasSelectedStateIndex = 1 << 28;
+  // READ THIS: if you add a flag here, you MUST update the following:
+  //
+  // - Add an appropriately named and documented `static const SemanticsFlag`
+  //   field to this class.
+  // - Add the new flag to `_kFlagById` in this file.
+  // - Make changes in lib/web_ui/lib/semantics.dart in the web engine that mirror
+  //   the changes in this file (i.e. `_k*Index`, `static const SemanticsFlag`,
+  //   `_kFlagById`).
+  // - Increment the `numSemanticsFlags` value in testing/dart/semantics_test.dart
+  //   and in lib/web_ui/test/engine/semantics/semantics_api_test.dart.
+  // - Add the new flag to platform-specific enums:
+  //   - The `Flag` enum in flutter/shell/platform/android/io/flutter/view/AccessibilityBridge.java.
+  //   - The `SemanticsFlags` enum in lib/ui/semantics/semantics_node.h.
+  //   - The `FlutterSemanticsFlag` enum in shell/platform/embedder/embedder.h.
+  // - If the new flag affects the visibility of a [SemanticsNode] to accessibility services,
+  //   update `flutter_test/controller.dart#SemanticsController._importantFlags`
+  //   accordingly.
+  // - If the new flag affects focusability of a semantics node, also update the
+  //   value of `AccessibilityBridge.FOCUSABLE_FLAGS` in
+  //   flutter/shell/platform/android/io/flutter/view/AccessibilityBridge.java.
 
   /// The semantics node has the quality of either being "checked" or "unchecked".
   ///
@@ -386,9 +398,20 @@ class SemanticsFlag {
   /// Must be false when the checkbox is either checked or unchecked.
   static const SemanticsFlag isCheckStateMixed = SemanticsFlag._(_kIsCheckStateMixedIndex, 'isCheckStateMixed');
 
+  /// The semantics node has the quality of either being "selected" or "unselected".
+  ///
+  /// Whether the widget corresponding to this node is currently selected or not
+  /// is determined by the [isSelected] flag.
+  ///
+  /// When this flag is not set, the corresponding widget cannot be selected by
+  /// the user, and the presence or the lack of [isSelected] does not carry any
+  /// meaning.
+  static const SemanticsFlag hasSelectedState = SemanticsFlag._(_kHasSelectedStateIndex, 'hasSelectedState');
 
   /// Whether a semantics node is selected.
   ///
+  /// This flag only has meaning in nodes that have [hasSelectedState] flag set.
+  ///
   /// If true, the semantics node is "selected". If false, the semantics node is
   /// "unselected".
   ///
@@ -614,6 +637,7 @@ class SemanticsFlag {
   static const Map<int, SemanticsFlag> _kFlagById = <int, SemanticsFlag>{
     _kHasCheckedStateIndex: hasCheckedState,
     _kIsCheckedIndex: isChecked,
+    _kHasSelectedStateIndex: hasSelectedState,
     _kIsSelectedIndex: isSelected,
     _kIsButtonIndex: isButton,
     _kIsTextFieldIndex: isTextField,

lib/ui/semantics/semantics_node.h

@@ -91,6 +91,7 @@ enum class SemanticsFlags : int32_t {
   kIsCheckStateMixed = 1 << 25,
   kHasExpandedState = 1 << 26,
   kIsExpanded = 1 << 27,
+  kHasSelectedState = 1 << 28,
 };
 
 const int kScrollableSemanticsFlags =

lib/web_ui/lib/semantics.dart

@@ -126,9 +126,11 @@ class SemanticsFlag {
   static const int _kIsCheckStateMixedIndex = 1 << 25;
   static const int _kHasExpandedStateIndex = 1 << 26;
   static const int _kIsExpandedIndex = 1 << 27;
+  static const int _kHasSelectedStateIndex = 1 << 28;
 
   static const SemanticsFlag hasCheckedState = SemanticsFlag._(_kHasCheckedStateIndex, 'hasCheckedState');
   static const SemanticsFlag isChecked = SemanticsFlag._(_kIsCheckedIndex, 'isChecked');
+  static const SemanticsFlag hasSelectedState = SemanticsFlag._(_kHasSelectedStateIndex, 'hasSelectedState');
   static const SemanticsFlag isSelected = SemanticsFlag._(_kIsSelectedIndex, 'isSelected');
   static const SemanticsFlag isButton = SemanticsFlag._(_kIsButtonIndex, 'isButton');
   static const SemanticsFlag isTextField = SemanticsFlag._(_kIsTextFieldIndex, 'isTextField');
@@ -159,6 +161,7 @@ class SemanticsFlag {
   static const Map<int, SemanticsFlag> _kFlagById = <int, SemanticsFlag>{
     _kHasCheckedStateIndex: hasCheckedState,
     _kIsCheckedIndex: isChecked,
+    _kHasSelectedStateIndex: hasSelectedState,
     _kIsSelectedIndex: isSelected,
     _kIsButtonIndex: isButton,
     _kIsTextFieldIndex: isTextField,

lib/web_ui/test/engine/semantics/semantics_api_test.dart

@@ -18,7 +18,7 @@ void main() {
 
 void testMain() {
   // This must match the number of flags in lib/ui/semantics.dart
-  const int numSemanticsFlags = 28;
+  const int numSemanticsFlags = 29;
   test('SemanticsFlag.values refers to all flags.', () async {
     expect(SemanticsFlag.values.length, equals(numSemanticsFlags));
     for (int index = 0; index < numSemanticsFlags; ++index) {

shell/platform/android/io/flutter/view/AccessibilityBridge.java

@@ -2158,7 +2158,8 @@ public enum Action {
     IS_KEYBOARD_KEY(1 << 24),
     IS_CHECK_STATE_MIXED(1 << 25),
     HAS_EXPANDED_STATE(1 << 26),
-    IS_EXPANDED(1 << 27);
+    IS_EXPANDED(1 << 27),
+    HAS_SELECTED_STATE(1 << 28);
 
     final int value;
 

shell/platform/embedder/embedder.h

@@ -243,6 +243,9 @@ typedef enum {
   kFlutterSemanticsFlagHasExpandedState = 1 << 26,
   /// Whether a semantic node that hasExpandedState is currently expanded.
   kFlutterSemanticsFlagIsExpanded = 1 << 27,
+  /// The semantics node has the quality of either being "selected" or
+  /// "not selected".
+  kFlutterSemanticsFlagHasSelectedState = 1 << 28,
 } FlutterSemanticsFlag;
 
 typedef enum {

testing/dart/semantics_test.dart

@@ -11,7 +11,7 @@ import 'package:test/test.dart';
 
 void main() {
   // This must match the number of flags in lib/ui/semantics.dart
-  const int numSemanticsFlags = 28;
+  const int numSemanticsFlags = 29;
   test('SemanticsFlag.values refers to all flags.', () async {
     expect(SemanticsFlag.values.length, equals(numSemanticsFlags));
     for (int index = 0; index < numSemanticsFlags; ++index) {