Add support for setting the heading level for web semantics (#97894)

ci/licenses_golden/licenses_flutter

@@ -5932,6 +5932,7 @@ ORIGIN: ../../../flutter/lib/web_ui/lib/src/engine/semantics/accessibility.dart
 ORIGIN: ../../../flutter/lib/web_ui/lib/src/engine/semantics/checkable.dart + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/lib/web_ui/lib/src/engine/semantics/dialog.dart + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/lib/web_ui/lib/src/engine/semantics/focusable.dart + ../../../flutter/LICENSE
+ORIGIN: ../../../flutter/lib/web_ui/lib/src/engine/semantics/heading.dart + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/lib/web_ui/lib/src/engine/semantics/image.dart + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/lib/web_ui/lib/src/engine/semantics/incrementable.dart + ../../../flutter/LICENSE
 ORIGIN: ../../../flutter/lib/web_ui/lib/src/engine/semantics/label_and_value.dart + ../../../flutter/LICENSE
@@ -8734,6 +8735,7 @@ FILE: ../../../flutter/lib/web_ui/lib/src/engine/semantics/accessibility.dart
 FILE: ../../../flutter/lib/web_ui/lib/src/engine/semantics/checkable.dart
 FILE: ../../../flutter/lib/web_ui/lib/src/engine/semantics/dialog.dart
 FILE: ../../../flutter/lib/web_ui/lib/src/engine/semantics/focusable.dart
+FILE: ../../../flutter/lib/web_ui/lib/src/engine/semantics/heading.dart
 FILE: ../../../flutter/lib/web_ui/lib/src/engine/semantics/image.dart
 FILE: ../../../flutter/lib/web_ui/lib/src/engine/semantics/incrementable.dart
 FILE: ../../../flutter/lib/web_ui/lib/src/engine/semantics/label_and_value.dart

lib/ui/fixtures/ui_test.dart

@@ -226,7 +226,9 @@ void sendSemanticsUpdate() {
     transform: transform,
     childrenInTraversalOrder: childrenInTraversalOrder,
     childrenInHitTestOrder: childrenInHitTestOrder,
-    additionalActions: additionalActions);
+    additionalActions: additionalActions,
+    headingLevel: -1,
+  );
   _semanticsUpdate(builder.build());
 }
 

lib/ui/semantics.dart

@@ -790,6 +790,18 @@ abstract class SemanticsUpdateBuilder {
   /// z-direction starting at `elevation`. Basically, in the z-direction the
   /// node starts at `elevation` above the parent and ends at `elevation` +
   /// `thickness` above the parent.
+  ///
+  /// The `headingLevel` describes that this node is a heading and the hierarchy
+  /// level this node represents as a heading. A value of -1 indicates that this
+  /// node is not a heading. A value of 1 or greater indicates that this node is
+  /// a heading at the specified level. The valid value range is from 1 to 6,
+  /// inclusive. This attribute is only used for Web platform, and it will have
+  /// no effect on other platforms.
+  ///
+  /// See also:
+  ///
+  ///  * https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/heading_role
+  ///  * https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-level
   void updateNode({
     required int id,
     required int flags,
@@ -825,6 +837,7 @@ abstract class SemanticsUpdateBuilder {
     required Int32List childrenInTraversalOrder,
     required Int32List childrenInHitTestOrder,
     required Int32List additionalActions,
+    required int headingLevel,
   });
 
   /// Update the custom semantics action associated with the given `id`.
@@ -896,8 +909,13 @@ base class _NativeSemanticsUpdateBuilder extends NativeFieldWrapperClass1 implem
     required Int32List childrenInTraversalOrder,
     required Int32List childrenInHitTestOrder,
     required Int32List additionalActions,
+    required int headingLevel,
   }) {
     assert(_matrix4IsValid(transform));
+    assert (
+      headingLevel == -1 || (headingLevel >= 1 && headingLevel <= 6),
+      'Heading level must be between 1 and 6, or -1 to indicate that this node is not a heading.'
+    );
     _updateNode(
       id,
       flags,
@@ -936,6 +954,7 @@ base class _NativeSemanticsUpdateBuilder extends NativeFieldWrapperClass1 implem
       childrenInTraversalOrder,
       childrenInHitTestOrder,
       additionalActions,
+      headingLevel,
     );
   }
   @Native<
@@ -976,7 +995,8 @@ base class _NativeSemanticsUpdateBuilder extends NativeFieldWrapperClass1 implem
           Handle,
           Handle,
           Handle,
-          Handle)>(symbol: 'SemanticsUpdateBuilder::updateNode')
+          Handle,
+          Int32)>(symbol: 'SemanticsUpdateBuilder::updateNode')
   external void _updateNode(
       int id,
       int flags,
@@ -1349,7 +1369,8 @@ base class _NativeSemanticsUpdateBuilderNew extends NativeFieldWrapperClass1 imp
       Float64List transform,
       Int32List childrenInTraversalOrder,
       Int32List childrenInHitTestOrder,
-      Int32List additionalActions);
+      Int32List additionalAction,
+      int headingLevel);
 
   @override
   void updateCustomAction({required int id, String? label, String? hint, int overrideId = -1}) {

lib/ui/semantics/semantics_node.h

@@ -142,6 +142,7 @@ struct SemanticsNode {
   std::vector<int32_t> childrenInTraversalOrder;
   std::vector<int32_t> childrenInHitTestOrder;
   std::vector<int32_t> customAccessibilityActions;
+  int32_t headingLevel = -1;
 };
 
 // Contains semantic nodes that need to be updated.

lib/ui/semantics/semantics_update_builder.cc

@@ -66,7 +66,8 @@ void SemanticsUpdateBuilder::updateNode(
     const tonic::Float64List& transform,
     const tonic::Int32List& childrenInTraversalOrder,
     const tonic::Int32List& childrenInHitTestOrder,
-    const tonic::Int32List& localContextActions) {
+    const tonic::Int32List& localContextActions,
+    int headingLevel) {
   FML_CHECK(scrollChildren == 0 ||
             (scrollChildren > 0 && childrenInHitTestOrder.data()))
       << "Semantics update contained scrollChildren but did not have "
@@ -118,6 +119,8 @@ void SemanticsUpdateBuilder::updateNode(
       localContextActions.data(),
       localContextActions.data() + localContextActions.num_elements());
   nodes_[id] = node;
+
+  node.headingLevel = headingLevel;
 }
 
 void SemanticsUpdateBuilder::updateCustomAction(int id,

lib/ui/semantics/semantics_update_builder.h

@@ -65,7 +65,8 @@ class SemanticsUpdateBuilder
       const tonic::Float64List& transform,
       const tonic::Int32List& childrenInTraversalOrder,
       const tonic::Int32List& childrenInHitTestOrder,
-      const tonic::Int32List& customAccessibilityActions);
+      const tonic::Int32List& customAccessibilityActions,
+      int headingLevel);
 
   void updateCustomAction(int id,
                           std::string label,

lib/web_ui/lib/semantics.dart

@@ -283,6 +283,7 @@ class SemanticsUpdateBuilderNew {
     required Int32List childrenInTraversalOrder,
     required Int32List childrenInHitTestOrder,
     required Int32List additionalActions,
+    required int headingLevel,
   }) {
     if (transform.length != 16) {
       throw ArgumentError('transform argument must have 16 entries.');
@@ -417,6 +418,7 @@ class SemanticsUpdateBuilder {
       childrenInHitTestOrder: childrenInHitTestOrder,
       additionalActions: additionalActions,
       platformViewId: platformViewId,
+      headingLevel: headingLevel,
     ));
   }
 

lib/web_ui/lib/src/engine.dart

@@ -141,6 +141,7 @@ export 'engine/semantics/accessibility.dart';
 export 'engine/semantics/checkable.dart';
 export 'engine/semantics/dialog.dart';
 export 'engine/semantics/focusable.dart';
+export 'engine/semantics/heading.dart';
 export 'engine/semantics/image.dart';
 export 'engine/semantics/incrementable.dart';
 export 'engine/semantics/label_and_value.dart';

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

@@ -5,6 +5,7 @@
 export 'semantics/accessibility.dart';
 export 'semantics/checkable.dart';
 export 'semantics/focusable.dart';
+export 'semantics/heading.dart';
 export 'semantics/image.dart';
 export 'semantics/incrementable.dart';
 export 'semantics/label_and_value.dart';

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

@@ -0,0 +1,40 @@
+// Copyright 2013 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import '../dom.dart';
+import 'semantics.dart';
+
+/// Renders semantics objects as headings with the corresponding
+/// level (h1 ... h6).
+class Heading extends PrimaryRoleManager {
+  Heading(SemanticsObject semanticsObject)
+      : super.withBasics(PrimaryRole.heading, semanticsObject) {
+        addHeadingRole();
+      }
+
+  static const int defaultHeadingLevel = 1;
+
+  @override
+  void update() {
+    super.update();
+
+    if (!semanticsObject.isHeadingLevelDirty) {
+      return;
+    }
+
+    if (semanticsObject.headingLevel != -1) {
+      addHeadingLevel(semanticsObject.headingLevel);
+    } else {
+      addHeadingLevel(defaultHeadingLevel);
+    }
+  }
+
+  void addHeadingRole() {
+    setAriaRole('heading');
+  }
+
+  void addHeadingLevel(int headingLevel) {
+    semanticsObject.element.setAttribute('aria-level', headingLevel);
+  }
+}

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

@@ -21,6 +21,7 @@ import '../window.dart';
 import 'checkable.dart';
 import 'dialog.dart';
 import 'focusable.dart';
+import 'heading.dart';
 import 'image.dart';
 import 'incrementable.dart';
 import 'label_and_value.dart';
@@ -231,6 +232,7 @@ class SemanticsNodeUpdate {
     required this.childrenInTraversalOrder,
     required this.childrenInHitTestOrder,
     required this.additionalActions,
+    required this.headingLevel,
   });
 
   /// See [ui.SemanticsUpdateBuilder.updateNode].
@@ -331,6 +333,9 @@ class SemanticsNodeUpdate {
 
   /// See [ui.SemanticsUpdateBuilder.updateNode].
   final double thickness;
+
+  /// See [ui.SemanticsUpdateBuilder.updateNode].
+  final int headingLevel;
 }
 
 /// Identifies [PrimaryRoleManager] implementations.
@@ -353,6 +358,10 @@ enum PrimaryRole {
   /// A control that has a checked state, such as a check box or a radio button.
   checkable,
 
+  /// Adds the "heading" ARIA role to the node. The attribute "aria-level" is
+  /// also assigned.
+  heading,
+
   /// Visual only element.
   image,
 
@@ -1016,6 +1025,19 @@ class SemanticsObject {
     _dirtyFields |= _platformViewIdIndex;
   }
 
+  /// See [ui.SemanticsUpdateBuilder.updateNode].
+  int get headingLevel => _headingLevel;
+  int _headingLevel = -1;
+
+  static const int _headingLevelIndex = 1 << 24;
+
+  /// Whether the [headingLevel] field has been updated but has not been
+  /// applied to the DOM yet.
+  bool get isHeadingLevelDirty => _isDirty(_headingLevelIndex);
+  void _markHeadingLevelDirty() {
+    _dirtyFields |= _headingLevelIndex;
+  }
+
   /// A unique permanent identifier of the semantics node in the tree.
   final int id;
 
@@ -1120,6 +1142,9 @@ class SemanticsObject {
   /// Whether this object represents an editable text field.
   bool get isTextField => hasFlag(ui.SemanticsFlag.isTextField);
 
+  /// Whether this object represents a heading element.
+  bool get isHeading => headingLevel != -1;
+
     /// Whether this object represents an editable text field.
   bool get isLink => hasFlag(ui.SemanticsFlag.isLink);
 
@@ -1277,6 +1302,11 @@ class SemanticsObject {
       _markTooltipDirty();
     }
 
+    if (_headingLevel != update.headingLevel) {
+      _headingLevel = update.headingLevel;
+      _markHeadingLevelDirty();
+    }
+
     if (_textDirection != update.textDirection) {
       _textDirection = update.textDirection;
       _markTextDirectionDirty();
@@ -1510,6 +1540,8 @@ class SemanticsObject {
     // The most specific role should take precedence.
     if (isPlatformView) {
       return PrimaryRole.platformView;
+    } else if (isHeading) {
+      return PrimaryRole.heading;
     } else if (isTextField) {
       return PrimaryRole.textField;
     } else if (isIncrementable) {
@@ -1541,6 +1573,7 @@ class SemanticsObject {
       PrimaryRole.dialog => Dialog(this),
       PrimaryRole.image => ImageRoleManager(this),
       PrimaryRole.platformView => PlatformViewRoleManager(this),
+      PrimaryRole.heading => Heading(this),
       PrimaryRole.link => Link(this),
       PrimaryRole.generic => GenericRole(this),
     };

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

@@ -660,6 +660,28 @@ void _testHeader() {
     owner().updateSemantics(builder.build());
     expectSemanticsTree(owner(), '''
 <sem role="group" aria-label="Header of the page" style="$rootSemanticStyle"><sem-c><sem></sem></sem-c></sem>
+''');
+
+    semantics().semanticsEnabled = false;
+  });
+
+  test('renders aria-level tag for headings with heading level', () {
+    semantics()
+      ..debugOverrideTimestampFunction(() => _testTime)
+      ..semanticsEnabled = true;
+
+    final ui.SemanticsUpdateBuilder builder = ui.SemanticsUpdateBuilder();
+    updateNode(
+      builder,
+      headingLevel: 2,
+      label: 'Heading of the page',
+      transform: Matrix4.identity().toFloat64(),
+      rect: const ui.Rect.fromLTRB(0, 0, 100, 50),
+    );
+
+    semantics().updateSemantics(builder.build());
+    expectSemanticsTree('''
+<sem role="heading" aria-label="Heading of the page" aria-level="2" style="$rootSemanticStyle"></sem>
 ''');
 
     semantics().semanticsEnabled = false;
@@ -3070,6 +3092,7 @@ void updateNode(
   Int32List? childrenInTraversalOrder,
   Int32List? childrenInHitTestOrder,
   Int32List? additionalActions,
+  int headingLevel = -1,
 }) {
   transform ??= Float64List.fromList(Matrix4.identity().storage);
   childrenInTraversalOrder ??= Int32List(0);
@@ -3110,6 +3133,7 @@ void updateNode(
     childrenInTraversalOrder: childrenInTraversalOrder,
     childrenInHitTestOrder: childrenInHitTestOrder,
     additionalActions: additionalActions,
+    headingLevel: headingLevel,
   );
 }
 

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

@@ -116,6 +116,7 @@ class SemanticsTester {
     Float64List? transform,
     Int32List? additionalActions,
     List<SemanticsNodeUpdate>? children,
+    int? headingLevel,
   }) {
     // Flags
     if (hasCheckedState ?? false) {
@@ -316,6 +317,7 @@ class SemanticsTester {
       childrenInTraversalOrder: childIds,
       childrenInHitTestOrder: childIds,
       additionalActions: additionalActions ?? Int32List(0),
+      headingLevel: headingLevel ?? -1,
     );
     _nodeUpdates.add(update);
     return update;