Skip to content

Conversation

vineethkuttan
Copy link
Contributor

@vineethkuttan vineethkuttan commented Oct 6, 2025

Description

Add UIA HeadingLevel behaviour for Fabric architecture which is particularly useful for identifying and interacting with elements that represent headings in a structured document or application interface.

Type of Change

  • New feature (non-breaking change which adds functionality)

Why

For identifying and interacting with elements that represent headings in a structured document or application interface.

Resolves [ microsoft/react-native-gallery/issues/699 ]

What

i)When role is set to heading the aria-level property will be considered as heading level
ii)Sent it to the UIA Clients , when it is requested
iii)Added tests to capture it in our test snapshot.

Testing

Added test cases in e2e tests.

Changelog

Should this change be included in the release notes: yes

Add a brief summary of the change to use in the release notes for the next release.
Implement accessibilityHeadingLevel for Fabric architecture

Microsoft Reviewers: Open in CodeFlow

@vineethkuttan vineethkuttan marked this pull request as ready for review October 6, 2025 13:16
@vineethkuttan vineethkuttan requested a review from a team as a code owner October 6, 2025 13:16
@acoates-ms
Copy link
Contributor

acoates-ms commented Oct 6, 2025

We should align the property with aria-level.
So the property should be called accessibilityLevel, and be a number not a string. We should also implement it as 'aria-level' -- That way we align with other accessibility properties.

In fact the property is already there in the JS.

Edit: Actually looks like the level property is already implemented end to end.

Copy link
Contributor

@acoates-ms acoates-ms left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This feature already exists as accessiblityLevel

@microsoft-github-policy-service microsoft-github-policy-service bot added Needs: Author Feedback The issue/PR needs activity from its author (label drives bot activity) and removed Needs: Author Feedback The issue/PR needs activity from its author (label drives bot activity) labels Oct 6, 2025
@vineethkuttan
Copy link
Contributor Author

vineethkuttan commented Oct 6, 2025

This feature already exists as accessiblityLevel

@acoates-ms

#14593 is a PR for accessibilityLevel/aria-level, which uses UIA_LevelPropertyId for UIA clients.

However, the grading team specifically raised concerns regarding the Heading Level, for which we should be using UIA_HeadingLevelPropertyId.

https://learn.microsoft.com/en-us/windows/win32/winauto/uiauto-automation-element-propids

To avoid confusion, I believe it would be better to have separate props for level and heading level.

While we could consider making it a single property that supports multiple usages, my preference is to keep them distinct to ensure clarity and proper usage.

@acoates-ms
Copy link
Contributor

@ksiler - Is headingLevel something we have done for win32? -- Is there a matching aria property we should be looking at hooking up?

If it is a new property, we should probably make it a number to align with how aria-level works, rather than a string.

@vineethkuttan
Copy link
Contributor Author

vineethkuttan commented Oct 7, 2025

We can use accessibilityLevel value for heading level , if accessibilityRole is set to heading.

Your suggestion on this @acoates-ms ?

https://learn.microsoft.com/en-us/windows/win32/winauto/uiauto-ariaspecification

@ksiler
Copy link
Contributor

ksiler commented Oct 7, 2025

@vineethkuttan @acoates-ms the ability to set the UIA heading level works today by setting the role (or accessibilityRole) to "header" or "heading" and the aria-level (or accessibilityLevel) to the desired heading level. Both properties must be set in order for it to work.

@vineethkuttan vineethkuttan changed the title Implement accessibilityHeadingLevel for Fabric architecture Add UIA HeadingLevel behaviour for Fabric architecture Oct 8, 2025
Copy link
Contributor

@acoates-ms acoates-ms left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ksiler - you mind taking a look at this?

@acoates-ms acoates-ms requested review from acoates-ms and removed request for acoates-ms October 8, 2025 16:51
@acoates-ms acoates-ms requested a review from ksiler October 8, 2025 16:52
Copy link
Contributor

@protikbiswas100 protikbiswas100 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@Nitin-100 Nitin-100 merged commit 8826a55 into microsoft:main Oct 9, 2025
58 checks passed
@vineethkuttan vineethkuttan deleted the impHeadingLevel branch October 9, 2025 04:50
Copilot AI pushed a commit that referenced this pull request Oct 9, 2025
* Add HeadingLevel Behaviour for Fabric Arch

* format fix

* function definition fix

* Update Snapshot
github-actions bot pushed a commit to vineethkuttan/react-native-windows that referenced this pull request Oct 9, 2025
* Add HeadingLevel Behaviour for Fabric Arch

* format fix

* function definition fix

* Update Snapshot
vineethkuttan added a commit that referenced this pull request Oct 10, 2025
…architecture (#15221)

* Initial plan

* Add UIA HeadingLevel behaviour for Fabric architecture (#15207)

* Add HeadingLevel Behaviour for Fabric Arch

* format fix

* function definition fix

* Update Snapshot

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Vineeth <66076509+vineethkuttan@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants