Fix PR comments (41435)

lib/ui/semantics.dart

@@ -786,6 +786,11 @@ 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, additionally
+  /// indicates 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.
   void updateNode({
     required int id,
     required int flags,

lib/web_ui/lib/semantics.dart

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

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

@@ -9,15 +9,26 @@ import 'semantics.dart';
 /// level (h1 ... h6).
 class Heading extends PrimaryRoleManager {
   Heading(SemanticsObject semanticsObject)
-      : super.withBasics(PrimaryRole.heading, semanticsObject);
+      : super.withBasics(PrimaryRole.heading, semanticsObject) {
+        addHeadingRole();
+      }
 
   @override
   void update() {
     super.update();
 
-      if (semanticsObject.headingLevel != -1) {
-        semanticsObject.setAriaRole('heading');
-        semanticsObject.element.setAttribute('aria-level', semanticsObject.headingLevel);
-      }
+    if (semanticsObject.headingLevel != -1) {
+      addHeadingLevel(semanticsObject.headingLevel);
+    } else {
+      addHeadingLevel(1);
+    }
+  }
+
+  void addHeadingRole() {
+    semanticsObject.setAriaRole('heading');
+  }
+
+  void addHeadingLevel(int headingLevel) {
+    semanticsObject.element.setAttribute('aria-level', headingLevel);
   }
 }

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

@@ -230,7 +230,7 @@ class SemanticsNodeUpdate {
     required this.childrenInTraversalOrder,
     required this.childrenInHitTestOrder,
     required this.additionalActions,
-    required this.headingLevel,
+    this.headingLevel,
   });
 
   /// See [ui.SemanticsUpdateBuilder.updateNode].
@@ -330,7 +330,7 @@ class SemanticsNodeUpdate {
   final double thickness;
 
   /// See [ui.SemanticsUpdateBuilder.updateNode].
-  final int headingLevel;
+  final int? headingLevel;
 }
 
 /// Identifies [PrimaryRoleManager] implementations.
@@ -1097,7 +1097,7 @@ class SemanticsObject {
   /// Whether this object represents an editable text field.
   bool get isTextField => hasFlag(ui.SemanticsFlag.isTextField);
 
-  /// Whether this object represents a heading element
+  /// Whether this object represents a heading element.
   bool get isHeading => headingLevel != -1;
 
   /// Whether this object needs screen readers attention right away.
@@ -1528,8 +1528,8 @@ class SemanticsObject {
       PrimaryRole.dialog => Dialog(this),
       PrimaryRole.image => ImageRoleManager(this),
       PrimaryRole.platformView => PlatformViewRoleManager(this),
-      PrimaryRole.generic => GenericRole(this),
       PrimaryRole.heading => Heading(this),
+      PrimaryRole.generic => GenericRole(this),
     };
   }
 

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

@@ -670,25 +670,45 @@ void _testHeader() {
     semantics().semanticsEnabled = false;
   });
 
-  test('renders aria-level tag for headers with heading level', () {
+  test('renders aria-level tag for headings 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),
-    );
+    // State 1: render element with an initial headingLevel.
+    {
+      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="Header of the page" aria-level="1" style="$rootSemanticStyle"></sem>
-''');
+      semantics().updateSemantics(builder.build());
+      expectSemanticsTree('''
+  <sem role="heading" aria-label="Heading of the page" aria-level="2" style="$rootSemanticStyle"></sem>
+  ''');
+    }
+
+    // State 2: when the new state "clears" the headingLevel, a default value
+    // of 1 is assigned, as the aria-level is a required attribute for the
+    // heading role.
+    {
+      final ui.SemanticsUpdateBuilder builder = ui.SemanticsUpdateBuilder();
+      updateNode(
+        builder,
+        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="1" style="$rootSemanticStyle"></sem>
+  ''');
+    }
 
     semantics().semanticsEnabled = false;
   });