[Label] Expose SectionHeader labels as semantic headings (#887)

Author: haavamoa

CHANGELOG.md

@@ -1,3 +1,6 @@
+## [60.2.6]
+- [Label] `SectionHeader` labels are now exposed as level 2 semantic headings by default, improving VoiceOver and TalkBack navigation for section headers.
+
 ## [60.2.5]
 - [Pickers][Android] Added error haptic feedback when TimePicker or DateAndTimePicker selections are clamped by minimum or maximum constraints.
 

src/library/DIPS.Mobile.UI/Resources/Styles/Label/LabelStyleResources.cs

@@ -23,6 +23,22 @@ internal class LabelStyleResources
         [LabelStyle.Header700] = s_sharedStyles[TextStyle.Header700],
         [LabelStyle.Header600] = s_sharedStyles[TextStyle.Header600],
         [LabelStyle.Header500] = s_sharedStyles[TextStyle.Header500],
-        [LabelStyle.SectionHeader] = s_sharedStyles[TextStyle.SectionHeader]
+        [LabelStyle.SectionHeader] = CreateSectionHeaderStyle()
     };
+
+    private static Style CreateSectionHeaderStyle()
+    {
+        return new Style(typeof(Components.Labels.Label))
+        {
+            BasedOn = s_sharedStyles[TextStyle.SectionHeader],
+            Setters =
+            {
+                new Setter
+                {
+                    Property = SemanticProperties.HeadingLevelProperty,
+                    Value = SemanticHeadingLevel.Level2
+                }
+            }
+        };
+    }
 }

src/tests/unittests/Resources/Styles/SectionHeaderStyleTests.cs

@@ -0,0 +1,43 @@
+using System.Linq;
+using DIPS.Mobile.UI.Resources.Styles;
+using DIPS.Mobile.UI.Resources.Styles.Label;
+using DIPS.Mobile.UI.Resources.Styles.Span;
+using Microsoft.Maui;
+using Microsoft.Maui.Controls;
+using DuiStyles = DIPS.Mobile.UI.Resources.Styles.Styles;
+
+namespace DIPS.Mobile.UI.UnitTests.Resources.Styles;
+
+public class SectionHeaderStyleTests
+{
+    [Fact]
+    public void LabelSectionHeaderStyle_ShouldSetHeadingLevel2()
+    {
+        var style = DuiStyles.GetLabelStyle(LabelStyle.SectionHeader);
+
+        var headingLevelSetter = GetSetters(style).Single(setter => setter.Property == SemanticProperties.HeadingLevelProperty);
+
+        headingLevelSetter.Value.Should().Be(SemanticHeadingLevel.Level2);
+    }
+
+    [Fact]
+    public void SpanSectionHeaderStyle_ShouldNotSetHeadingLevel()
+    {
+        var style = DuiStyles.GetSpanStyle(SpanStyle.SectionHeader);
+
+        GetSetters(style).Should().NotContain(setter => setter.Property == SemanticProperties.HeadingLevelProperty);
+    }
+
+    private static IEnumerable<Setter> GetSetters(Style? style)
+    {
+        while (style is not null)
+        {
+            foreach (var setter in style.Setters.OfType<Setter>())
+            {
+                yield return setter;
+            }
+
+            style = style.BasedOn;
+        }
+    }
+}

wiki/Components/Labels.md

@@ -15,6 +15,19 @@ Each of these style categories has a different weight, such as: `UI400`, to cont
 
 Inspect [LabelStyle.cs](https://github.com/DIPSAS/DIPS.Mobile.UI/blob/main/src/library/DIPS.Mobile.UI/Resources/Styles/Label/LabelStyle.cs) to see all of the different styles.
 
+## SectionHeader and accessibility
+
+Use `LabelStyle.SectionHeader` for labels that visually introduce a section, group, or list of content. A `dui:Label` with this style is exposed as a semantic heading with `SemanticProperties.HeadingLevel=Level2` by default, so screen reader users can navigate to it as a heading.
+
+```xml
+<dui:Label Text="Recent patients"
+           Style="{dui:Styles Label=SectionHeader}" />
+```
+
+Override `SemanticProperties.HeadingLevel` on the label when the information hierarchy needs a different level, for example `Level3` for a subsection or `None` when the label is not actually a heading.
+
+For formatted text headings, apply `LabelStyle.SectionHeader` to the parent `dui:Label`. `SpanStyle.SectionHeader` is visual text styling only and does not make the label a semantic heading by itself.
+
 # Usage
 Here we place a `Label` with a style of `Body` with a weight of `400`.
 

wiki/Interaction & Accessibility/Accessibility.md

@@ -166,6 +166,19 @@ Available heading levels: `None`, `Level1`, `Level2`, `Level3`, `Level4`, `Level
 
 **Note:** Not all platforms support all heading levels. Check the specific platform documentation for details.
 
+#### Section headers
+
+Use `dui:Label` with `LabelStyle.SectionHeader` for text that visually introduces a section, group, or list. This style sets `SemanticProperties.HeadingLevel=Level2` by default on labels, giving the visual section header matching screen reader heading semantics.
+
+```xml
+<dui:Label Text="Recent patients"
+           Style="{dui:Styles Label=SectionHeader}" />
+```
+
+Set `SemanticProperties.HeadingLevel` explicitly when a different level is needed, such as `Level3` for a subsection, or `None` when the label uses the visual style without representing a real heading.
+
+When using `FormattedString`, put the `SectionHeader` label style and heading level on the parent `dui:Label`. Span styles are visual only and do not expose heading semantics by themselves.
+
 ---
 
 ## MAUI AutomationProperties