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

lib/ui/fixtures/ui_test.dart

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

lib/ui/semantics.dart

@@ -798,6 +798,7 @@ class SemanticsUpdateBuilder extends NativeFieldWrapperClass1 {
     required Int32List childrenInTraversalOrder,
     required Int32List childrenInHitTestOrder,
     required Int32List additionalActions,
+    required int headingLevel,
   }) {
     assert(_matrix4IsValid(transform));
     _updateNode(
@@ -836,6 +837,7 @@ class SemanticsUpdateBuilder extends NativeFieldWrapperClass1 {
       childrenInTraversalOrder,
       childrenInHitTestOrder,
       additionalActions,
+      headingLevel,
     );
   }
   @Native<
@@ -875,7 +877,8 @@ class SemanticsUpdateBuilder extends NativeFieldWrapperClass1 {
           Handle,
           Handle,
           Handle,
-          Handle)>(symbol: 'SemanticsUpdateBuilder::updateNode')
+          Handle,
+          Int32)>(symbol: 'SemanticsUpdateBuilder::updateNode')
   external void _updateNode(
       int id,
       int flags,
@@ -911,7 +914,8 @@ class SemanticsUpdateBuilder extends NativeFieldWrapperClass1 {
       Float64List transform,
       Int32List childrenInTraversalOrder,
       Int32List childrenInHitTestOrder,
-      Int32List additionalActions);
+      Int32List additionalAction,
+      int headingLevel);
 
   /// Update the custom semantics action associated with the given `id`.
   ///

lib/ui/semantics/semantics_node.h

@@ -139,6 +139,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

@@ -65,7 +65,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 "
@@ -116,6 +117,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

@@ -64,7 +64,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

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

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

@@ -90,6 +90,9 @@ class LabelAndValue extends RoleManager {
       semanticsObject.setAriaRole('group', true);
     } else if (semanticsObject.hasFlag(ui.SemanticsFlag.isHeader)) {
       semanticsObject.setAriaRole('heading', true);
+      if (semanticsObject.headingLevel != -1) {
+        semanticsObject.setAriaLevel(semanticsObject.headingLevel);
+      }
     } else {
       semanticsObject.setAriaRole('text', true);
     }
@@ -98,6 +101,7 @@ class LabelAndValue extends RoleManager {
   void _cleanUpDom() {
     semanticsObject.element.removeAttribute('aria-label');
     semanticsObject.clearAriaRole();
+    semanticsObject.clearAriaLevel();
   }
 
   @override

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

@@ -224,6 +224,7 @@ class SemanticsNodeUpdate {
     required this.childrenInTraversalOrder,
     required this.childrenInHitTestOrder,
     required this.additionalActions,
+    required this.headingLevel,
   });
 
   /// See [ui.SemanticsUpdateBuilder.updateNode].
@@ -321,6 +322,9 @@ class SemanticsNodeUpdate {
 
   /// See [ui.SemanticsUpdateBuilder.updateNode].
   final double thickness;
+
+  /// See [ui.SemanticsUpdateBuilder.updateNode].
+  final int headingLevel;
 }
 
 /// Identifies one of the roles a [SemanticsObject] plays.
@@ -758,6 +762,15 @@ class SemanticsObject {
     _dirtyFields |= _platformViewIdIndex;
   }
 
+  /// See [ui.SemanticsUpdateBuilder.updateNode].
+  int get headingLevel => _headingLevel;
+  int _headingLevel = -1;
+
+  static const int _headingLevelIndex = 1 << 24;
+  void _markHeadingLevelDirty() {
+    _dirtyFields |= _headingLevelIndex;
+  }
+
   /// A unique permanent identifier of the semantics node in the tree.
   final int id;
 
@@ -978,6 +991,11 @@ class SemanticsObject {
       _markTooltipDirty();
     }
 
+    if (_headingLevel != update.headingLevel) {
+      _headingLevel = update.headingLevel;
+      _markHeadingLevelDirty();
+    }
+
     if (_textDirection != update.textDirection) {
       _textDirection = update.textDirection;
       _markTextDirectionDirty();
@@ -1224,6 +1242,15 @@ class SemanticsObject {
     element.removeAttribute('role');
   }
 
+  void setAriaLevel(int ariaLevel) {
+    element.setAttribute('aria-level', ariaLevel);
+  }
+
+  /// Removes the `aria-level` HTML attribue, if any.
+  void clearAriaLevel() {
+    element.removeAttribute('aria-level');
+  }
+
   /// Role managers.
   ///
   /// The [_roleManagers] map needs to have a stable order for easier debugging

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

@@ -518,6 +518,29 @@ void _testHeader() {
     semantics().updateSemantics(builder.build());
     expectSemanticsTree('''
 <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 headers with heading level', () {
+    semantics()
+      ..debugOverrideTimestampFunction(() => _testTime)
+      ..semanticsEnabled = true;
+
+    final ui.SemanticsUpdateBuilder builder = ui.SemanticsUpdateBuilder();
+    updateNode(
+      builder,
+      flags: 0 | ui.SemanticsFlag.isHeader.index,
+      headingLevel: 1,
+      label: 'Header 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="Header of the page" aria-level="1" style="$rootSemanticStyle"></sem>
 ''');
 
     semantics().semanticsEnabled = false;
@@ -2125,6 +2148,7 @@ void updateNode(
   Int32List? childrenInTraversalOrder,
   Int32List? childrenInHitTestOrder,
   Int32List? additionalActions,
+  int headingLevel = -1,
 }) {
   transform ??= Float64List.fromList(Matrix4.identity().storage);
   childrenInTraversalOrder ??= Int32List(0);
@@ -2163,6 +2187,7 @@ void updateNode(
     childrenInTraversalOrder: childrenInTraversalOrder,
     childrenInHitTestOrder: childrenInHitTestOrder,
     additionalActions: additionalActions,
+    headingLevel: headingLevel,
   );
 }
 

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

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

shell/platform/embedder/fixtures/main.dart

@@ -174,6 +174,7 @@ void a11y_main() async {
       decreasedValueAttributes: <StringAttribute>[],
       tooltip: 'tooltip',
       additionalActions: Int32List(0),
+      headingLevel: -1
     )
     ..updateNode(
       id: 84,
@@ -207,6 +208,7 @@ void a11y_main() async {
       additionalActions: Int32List(0),
       childrenInHitTestOrder: Int32List(0),
       childrenInTraversalOrder: Int32List(0),
+      headingLevel: -1
     )
     ..updateNode(
       id: 96,
@@ -240,6 +242,7 @@ void a11y_main() async {
       decreasedValueAttributes: <StringAttribute>[],
       tooltip: 'tooltip',
       additionalActions: Int32List(0),
+      headingLevel: -1
     )
     ..updateNode(
       id: 128,
@@ -273,6 +276,7 @@ void a11y_main() async {
       tooltip: 'tooltip',
       childrenInHitTestOrder: Int32List(0),
       childrenInTraversalOrder: Int32List(0),
+      headingLevel: -1
     )
     ..updateCustomAction(
       id: 21,