add semantics role and tab (#161260)

fixes flutter/flutter#157134

## Pre-launch Checklist

- [ ] I read the [Contributor Guide] and followed the process outlined
there for submitting PRs.
- [ ] I read the [Tree Hygiene] wiki page, which explains my
responsibilities.
- [ ] I read and followed the [Flutter Style Guide], including [Features
we expect every widget to implement].
- [ ] I signed the [CLA].
- [ ] I listed at least one issue that this PR fixes in the description
above.
- [ ] I updated/added relevant documentation (doc comments with `///`).
- [ ] I added new tests to check the change I am making, or this PR is
[test-exempt].
- [ ] I followed the [breaking change policy] and added [Data Driven
Fixes] where supported.
- [ ] All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel
on [Discord].

<!-- Links -->
[Contributor Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview
[Tree Hygiene]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md
[test-exempt]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests
[Flutter Style Guide]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md
[Features we expect every widget to implement]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement
[CLA]: https://cla.developers.google.com/
[flutter/tests]: https://github.com/flutter/tests
[breaking change policy]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes
[Discord]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md
[Data Driven Fixes]:
https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md

Author: chunhtai

engine/src/flutter/ci/licenses_golden/licenses_flutter

@@ -43284,6 +43284,7 @@ ORIGIN: ../../../flutter/lib/web_ui/lib/src/engine/semantics/route.dart + ../../
 ORIGIN: ../../../flutter/lib/web_ui/lib/src/engine/semantics/scrollable.dart + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/lib/web_ui/lib/src/engine/semantics/semantics.dart + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/lib/web_ui/lib/src/engine/semantics/semantics_helper.dart + ../../../flutter/LICENSE
+ORIGIN: ../../../flutter/lib/web_ui/lib/src/engine/semantics/tabs.dart + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/lib/web_ui/lib/src/engine/semantics/tappable.dart + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/lib/web_ui/lib/src/engine/semantics/text_field.dart + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/lib/web_ui/lib/src/engine/services.dart + ../../../flutter/LICENSE
@@ -46226,6 +46227,7 @@ FILE: ../../../flutter/lib/web_ui/lib/src/engine/semantics/route.dart
 FILE: ../../../flutter/lib/web_ui/lib/src/engine/semantics/scrollable.dart
 FILE: ../../../flutter/lib/web_ui/lib/src/engine/semantics/semantics.dart
 FILE: ../../../flutter/lib/web_ui/lib/src/engine/semantics/semantics_helper.dart
+FILE: ../../../flutter/lib/web_ui/lib/src/engine/semantics/tabs.dart
 FILE: ../../../flutter/lib/web_ui/lib/src/engine/semantics/tappable.dart
 FILE: ../../../flutter/lib/web_ui/lib/src/engine/semantics/text_field.dart
 FILE: ../../../flutter/lib/web_ui/lib/src/engine/services.dart

engine/src/flutter/lib/ui/fixtures/ui_test.dart

@@ -238,6 +238,59 @@ void sendSemanticsUpdate() {
   _semanticsUpdate(builder.build());
 }
 
+@pragma('vm:entry-point')
+void sendSemanticsUpdateWithRole() {
+  final SemanticsUpdateBuilder builder = SemanticsUpdateBuilder();
+
+  final Float64List transform = Float64List(16);
+  final Int32List childrenInTraversalOrder = Int32List(0);
+  final Int32List childrenInHitTestOrder = Int32List(0);
+  final Int32List additionalActions = Int32List(0);
+  // Identity matrix 4x4.
+  transform[0] = 1;
+  transform[5] = 1;
+  transform[10] = 1;
+  builder.updateNode(
+    id: 0,
+    flags: 0,
+    actions: 0,
+    maxValueLength: 0,
+    currentValueLength: 0,
+    textSelectionBase: -1,
+    textSelectionExtent: -1,
+    platformViewId: -1,
+    scrollChildren: 0,
+    scrollIndex: 0,
+    scrollPosition: 0,
+    scrollExtentMax: 0,
+    scrollExtentMin: 0,
+    rect: Rect.fromLTRB(0, 0, 10, 10),
+    elevation: 0,
+    thickness: 0,
+    identifier: "identifier",
+    label: "label",
+    labelAttributes: const <StringAttribute>[],
+    value: "value",
+    valueAttributes: const <StringAttribute>[],
+    increasedValue: "increasedValue",
+    increasedValueAttributes: const <StringAttribute>[],
+    decreasedValue: "decreasedValue",
+    decreasedValueAttributes: const <StringAttribute>[],
+    hint: "hint",
+    hintAttributes: const <StringAttribute>[],
+    tooltip: "tooltip",
+    textDirection: TextDirection.ltr,
+    transform: transform,
+    childrenInTraversalOrder: childrenInTraversalOrder,
+    childrenInHitTestOrder: childrenInHitTestOrder,
+    additionalActions: additionalActions,
+    headingLevel: 0,
+    linkUrl: '',
+    role: SemanticsRole.tab,
+  );
+  _semanticsUpdate(builder.build());
+}
+
 @pragma('vm:external-name', 'SemanticsUpdate')
 external void _semanticsUpdate(SemanticsUpdate update);
 

engine/src/flutter/lib/ui/semantics.dart

@@ -339,6 +339,31 @@ class SemanticsAction {
   String toString() => 'SemanticsAction.$name';
 }
 
+/// An enum to describe the role for a semantics node.
+///
+/// The roles are translated into native accessibility roles in each platform.
+enum SemanticsRole {
+  /// Does not represent any role.
+  none,
+
+  /// A tab button.
+  ///
+  /// see also:
+  ///
+  ///  * [tabBar], which is the role for containers of tab buttons.
+  tab,
+
+  /// Contains tab buttons.
+  ///
+  /// see also:
+  ///
+  ///  * [tab], which is the role for tab buttons.
+  tabBar,
+
+  /// The main display for a tab.
+  tabPanel,
+}
+
 /// A Boolean value that can be associated with a semantics node.
 //
 // When changes are made to this class, the equivalent APIs in
@@ -960,6 +985,9 @@ abstract class SemanticsUpdateBuilder {
   /// The `linkUrl` describes the URI that this node links to. If the node is
   /// not a link, this should be an empty string.
   ///
+  /// The `role` describes the role of this node. Defaults to
+  /// [SemanticsRole.none] if not set.
+  ///
   /// See also:
   ///
   ///  * https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/heading_role
@@ -1000,6 +1028,7 @@ abstract class SemanticsUpdateBuilder {
     required Int32List additionalActions,
     int headingLevel = 0,
     String linkUrl = '',
+    SemanticsRole role = SemanticsRole.none,
   });
 
   /// Update the custom semantics action associated with the given `id`.
@@ -1075,6 +1104,7 @@ base class _NativeSemanticsUpdateBuilder extends NativeFieldWrapperClass1
     required Int32List additionalActions,
     int headingLevel = 0,
     String linkUrl = '',
+    SemanticsRole role = SemanticsRole.none,
   }) {
     assert(_matrix4IsValid(transform));
     assert(
@@ -1120,6 +1150,7 @@ base class _NativeSemanticsUpdateBuilder extends NativeFieldWrapperClass1
       additionalActions,
       headingLevel,
       linkUrl,
+      role.index,
     );
   }
 
@@ -1164,6 +1195,7 @@ base class _NativeSemanticsUpdateBuilder extends NativeFieldWrapperClass1
       Handle,
       Int32,
       Handle,
+      Int32,
     )
   >(symbol: 'SemanticsUpdateBuilder::updateNode')
   external void _updateNode(
@@ -1205,6 +1237,7 @@ base class _NativeSemanticsUpdateBuilder extends NativeFieldWrapperClass1
     Int32List additionalActions,
     int headingLevel,
     String linkUrl,
+    int role,
   );
 
   @override

engine/src/flutter/lib/ui/semantics/semantics_node.h

@@ -57,6 +57,19 @@ const int kHorizontalScrollSemanticsActions =
 const int kScrollableSemanticsActions =
     kVerticalScrollSemanticsActions | kHorizontalScrollSemanticsActions;
 
+/// C/C++ representation of `SemanticsRole` defined in
+/// `lib/ui/semantics.dart`.
+///\warning This must match the `SemanticsRole` enum in
+///         `lib/ui/semantics.dart`.
+/// See also:
+///   - file://./../../../lib/ui/semantics.dart
+enum class SemanticsRole : int32_t {
+  kNone = 0,
+  kTab = 1,
+  kTabBar = 2,
+  kTabPanel = 3,
+};
+
 /// C/C++ representation of `SemanticsFlags` defined in
 /// `lib/ui/semantics.dart`.
 ///\warning This must match the `SemanticsFlags` enum in
@@ -148,6 +161,7 @@ struct SemanticsNode {
   int32_t headingLevel = 0;
 
   std::string linkUrl;
+  SemanticsRole role;
 };
 
 // Contains semantic nodes that need to be updated.

engine/src/flutter/lib/ui/semantics/semantics_update_builder.cc

@@ -68,7 +68,8 @@ void SemanticsUpdateBuilder::updateNode(
     const tonic::Int32List& childrenInHitTestOrder,
     const tonic::Int32List& localContextActions,
     int headingLevel,
-    std::string linkUrl) {
+    std::string linkUrl,
+    int role) {
   FML_CHECK(scrollChildren == 0 ||
             (scrollChildren > 0 && childrenInHitTestOrder.data()))
       << "Semantics update contained scrollChildren but did not have "
@@ -119,10 +120,11 @@ void SemanticsUpdateBuilder::updateNode(
   node.customAccessibilityActions = std::vector<int32_t>(
       localContextActions.data(),
       localContextActions.data() + localContextActions.num_elements());
-  nodes_[id] = node;
-
   node.headingLevel = headingLevel;
   node.linkUrl = std::move(linkUrl);
+  node.role = static_cast<SemanticsRole>(role);
+
+  nodes_[id] = node;
 }
 
 void SemanticsUpdateBuilder::updateCustomAction(int id,

engine/src/flutter/lib/ui/semantics/semantics_update_builder.h

@@ -67,7 +67,8 @@ class SemanticsUpdateBuilder
       const tonic::Int32List& childrenInHitTestOrder,
       const tonic::Int32List& customAccessibilityActions,
       int headingLevel,
-      std::string linkUrl);
+      std::string linkUrl,
+      int role);
 
   void updateCustomAction(int id,
                           std::string label,

engine/src/flutter/lib/ui/semantics/semantics_update_builder_unittests.cc

@@ -88,5 +88,48 @@ TEST_F(SemanticsUpdateBuilderTest, CanHandleAttributedStrings) {
   DestroyShell(std::move(shell), task_runners);
 }
 
+TEST_F(SemanticsUpdateBuilderTest, CanHandleSemanticsRole) {
+  auto message_latch = std::make_shared<fml::AutoResetWaitableEvent>();
+
+  auto nativeSemanticsUpdate = [message_latch](Dart_NativeArguments args) {
+    auto handle = Dart_GetNativeArgument(args, 0);
+    intptr_t peer = 0;
+    Dart_Handle result = Dart_GetNativeInstanceField(
+        handle, tonic::DartWrappable::kPeerIndex, &peer);
+    ASSERT_FALSE(Dart_IsError(result));
+    SemanticsUpdate* update = reinterpret_cast<SemanticsUpdate*>(peer);
+    SemanticsNodeUpdates nodes = update->takeNodes();
+    ASSERT_EQ(nodes.size(), (size_t)1);
+    auto node = nodes.find(0)->second;
+    // Should match the updateNode in ui_test.dart.
+    ASSERT_EQ(node.role, SemanticsRole::kTab);
+    message_latch->Signal();
+  };
+
+  Settings settings = CreateSettingsForFixture();
+  TaskRunners task_runners("test",                  // label
+                           GetCurrentTaskRunner(),  // platform
+                           CreateNewThread(),       // raster
+                           CreateNewThread(),       // ui
+                           CreateNewThread()        // io
+  );
+
+  AddNativeCallback("SemanticsUpdate",
+                    CREATE_NATIVE_ENTRY(nativeSemanticsUpdate));
+
+  std::unique_ptr<Shell> shell = CreateShell(settings, task_runners);
+
+  ASSERT_TRUE(shell->IsSetup());
+  auto configuration = RunConfiguration::InferFromSettings(settings);
+  configuration.SetEntrypoint("sendSemanticsUpdateWithRole");
+
+  shell->RunEngine(std::move(configuration), [](auto result) {
+    ASSERT_EQ(result, Engine::RunStatus::Success);
+  });
+
+  message_latch->Wait();
+  DestroyShell(std::move(shell), task_runners);
+}
+
 }  // namespace testing
 }  // namespace flutter

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

@@ -255,6 +255,9 @@ class SemanticsFlag {
   String toString() => 'SemanticsFlag.$name';
 }
 
+// Mirrors engine/src/flutter/lib/ui/semantics.dart
+enum SemanticsRole { none, tab, tabBar, tabPanel }
+
 // When adding a new StringAttributeType, the classes in these file must be
 // updated as well.
 //  * engine/src/flutter/lib/ui/semantics.dart
@@ -341,6 +344,7 @@ class SemanticsUpdateBuilder {
     required Int32List additionalActions,
     int headingLevel = 0,
     String? linkUrl,
+    SemanticsRole role = SemanticsRole.none,
   }) {
     if (transform.length != 16) {
       throw ArgumentError('transform argument must have 16 entries.');
@@ -382,6 +386,7 @@ class SemanticsUpdateBuilder {
         platformViewId: platformViewId,
         headingLevel: headingLevel,
         linkUrl: linkUrl,
+        role: role,
       ),
     );
   }

engine/src/flutter/lib/web_ui/lib/src/engine.dart

@@ -159,6 +159,7 @@ export 'engine/semantics/route.dart';
 export 'engine/semantics/scrollable.dart';
 export 'engine/semantics/semantics.dart';
 export 'engine/semantics/semantics_helper.dart';
+export 'engine/semantics/tabs.dart';
 export 'engine/semantics/tappable.dart';
 export 'engine/semantics/text_field.dart';
 export 'engine/services/buffers.dart';

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

@@ -16,5 +16,6 @@ export 'semantics/platform_view.dart';
 export 'semantics/scrollable.dart';
 export 'semantics/semantics.dart';
 export 'semantics/semantics_helper.dart';
+export 'semantics/tabs.dart';
 export 'semantics/tappable.dart';
 export 'semantics/text_field.dart';