Skip to content

[iOS][MacCatalyst] Fix accessibility hierarchy for non-UIElement semantic containers - #36702

Open
SuthiYuvaraj wants to merge 16 commits into
dotnet:net11from
SuthiYuvaraj:fix-accessibility-approach
Open

SuthiYuvaraj wants to merge 16 commits into
dotnet:net11from
SuthiYuvaraj:fix-accessibility-approach

Conversation

@SuthiYuvaraj

Copy link
Copy Markdown
Contributor

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Issue Description

When a non-UIControl container (in this case ContentView) had semantic text assigned, the container was automatically marked as an accessibility element.

As a result:

  • VoiceOver treated the entire container as a single accessibility element.
  • Child elements were no longer exposed individually.
  • Users could not navigate or interact with child content independently.

RootCause

IsAccessibilityElement was being set to true for non-interactive containers whenever semantic text was present, without considering accessible child elements.
This caused VoiceOver to stop traversing the container's descendants and instead expose only the container itself.

Description of Change

SemanticsExtensions:Updated the semantics handling to preserve child accessibility elements when semantic properties are applied to a non-UIElement container.
MauiView: Modified the accessibility container behavior so the parent semantics do not prevent VoiceOver from exposing and reading the child accessible elements.

Issues Fixed

Fixes #33612

Tested the behaviour in the following platforms

  • Android
  • Windows
  • iOS
  • Mac

Output Screenshot

Before Issue Fix After Issue Fix
ContentViewBefore.mov
ContentViewAfter.mov

@github-actions

Copy link
Copy Markdown
Contributor

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.sh | bash -s -- 36702

Or

  • Run remotely in PowerShell:
iex "& { $(irm https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.ps1) } 36702"

@azure-pipelines

This comment has been minimized.

@dotnet-policy-service dotnet-policy-service Bot added the partner/syncfusion Issues / PR's with Syncfusion collaboration label Jul 21, 2026
@kubaflo

This comment has been minimized.

@github-actions github-actions Bot added the s/agent-review-in-progress AI review is currently running for this PR label Jul 23, 2026
@MauiBot MauiBot added s/agent-changes-requested AI agent recommends changes - found a better alternative or issues s/agent-gate-failed AI could not verify tests catch the bug s/agent-fix-pr-picked AI could not beat the PR fix - PR is the best among all candidates s/agent-reviewed PR was reviewed by AI agent workflow (full 4-phase review) labels Jul 24, 2026
MauiBot

This comment was marked as outdated.

@MauiBot MauiBot left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Expert Review — 2 findings

See inline comments for details.

Comment thread src/Core/src/Platform/iOS/MauiView.cs Resolved
@MauiBot MauiBot removed the s/agent-review-in-progress AI review is currently running for this PR label Jul 24, 2026
@SuthiYuvaraj SuthiYuvaraj changed the title [WIP] [iOS][MacCatalyst] Fix accessibility hierarchy for non-UIElement semantic containers [iOS][MacCatalyst] Fix accessibility hierarchy for non-UIElement semantic containers Jul 27, 2026
@kubaflo

This comment has been minimized.

@github-actions github-actions Bot added the s/agent-review-in-progress AI review is currently running for this PR label Jul 27, 2026
@MauiBot MauiBot added s/agent-fix-win AI found a better alternative fix than the PR and removed s/agent-fix-pr-picked AI could not beat the PR fix - PR is the best among all candidates labels Jul 27, 2026
@azure-pipelines

This comment has been minimized.

@SuthiYuvaraj
SuthiYuvaraj changed the base branch from main to net11 November 12, 2026 14:11
@sheiksyedm
sheiksyedm marked this pull request as ready for review November 13, 2026 13:53
@azure-pipelines

This comment has been minimized.

@kubaflo

This comment has been minimized.

@github-actions github-actions Bot added the s/agent-review-in-progress AI review is currently running for this PR label Nov 13, 2026
@MauiBot

MauiBot commented Nov 13, 2026

Copy link
Copy Markdown
Collaborator

PR Test Gate

@SuthiYuvaraj — existing-test verification; Setup did not capture a tested commit.

Result INCONCLUSIVE Platform Android


🧪 Gate analysis — click to expand

⚠ Inconclusive. Setup, build, or execution did not produce a conclusive result. This does not prove the fix is incorrect.

No interpretable test-group summary was produced. No additional test execution is inferred.

Setup did not capture a verified PR head; no commit is claimed as tested.

No immutable without-fix baseline was prepared.

@MauiBot MauiBot removed the s/agent-review-in-progress AI review is currently running for this PR label Nov 13, 2026

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Expert Review — 5 findings

Reviewed commit 64f2e91.

See inline comments for details.

[Category(UITestCategories.Accessibility)]
public void ContainerDescriptionDoesNotHideIndividuallyAccessibleItems()
{
App.WaitForElement("SuggestionsContainer");

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[moderate] Regression Prevention and Test Coverage - Neither test checks preservation of the parent's semantic text. Removing the new AccessibilityLabel assignment while keeping the parent non-leaf leaves SuggestionsContainer and Item1..3 identifiers and the gesture result unchanged, so both tests still accept losing the "Suggestions" description. The distinct item identifiers correctly distinguish Borders from inner Labels, but do not protect the parent's label or hint. Add focused iOS/MacCatalyst coverage for the native parent label/hint alongside child reachability, rather than only looking up its AutomationId.

@kubaflo kubaflo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Could you check the ai's suggestions?

@kubaflo

This comment has been minimized.

@github-actions github-actions Bot added the s/agent-review-in-progress AI review is currently running for this PR label Nov 17, 2026
@kubaflo

kubaflo commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

/rebase

@github-actions

Copy link
Copy Markdown
Contributor

Unable to rebase this branch automatically. It may have conflicts with its base branch, or the PR author has not allowed maintainer edits. Please rebase manually.

@MauiBot

MauiBot commented Nov 17, 2026

Copy link
Copy Markdown
Collaborator

PR Test Gate

@SuthiYuvaraj — existing-test verification; Setup did not capture a tested commit.

Result INCONCLUSIVE Platform Android


🧪 Gate analysis — click to expand

⚠ Inconclusive. Setup, build, or execution did not produce a conclusive result. This does not prove the fix is incorrect.

No interpretable test-group summary was produced. No additional test execution is inferred.

Setup did not capture a verified PR head; no commit is claimed as tested.

No immutable without-fix baseline was prepared.

@MauiBot MauiBot removed the s/agent-review-in-progress AI review is currently running for this PR label Nov 17, 2026

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Expert Review — 7 findings

Reviewed commit 7ab5c37.

See inline comments for details.

if (semantics is null)
{
if (view is ILayout && platformView is not UIControl && platformView.IsAccessibilityElement)
if ((view is ILayout || view is IContentView) && platformView is not UIControl && platformView.IsAccessibilityElement)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[major] Logic and Correctness Verification - This resets handler-established accessibility defaults, not just previous semantic promotions. RadioButtonHandler creates SemanticSwitchContentView with IsAccessibilityElement=true; it derives from ContentView, not UIControl. With Content=null and no SemanticProperties, including a ControlTemplate that supplies its own visible label, RadioButton.UpdateSemantics returns null and initial mapping now clears that flag. Gesture setup does not restore it for non-layout views, so the focusable switch element carrying the checked AccessibilityValue is lost. A RadioButton with string Content synthesizes semantics and does not exercise this case. Preserve the native default unless this semantics path owns the promotion; the existing ValidateIsImportantForAccessibility source expects RadioButton to remain accessible.

if (view is IContentView contentView
&& view is not ILayout
&& contentView.PresentedContent is not null
&& platformView.GestureRecognizers is not { Length: > 0 })

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[major] Logic and Correctness Verification - Native recognizer count is neither activation-specific nor refreshed when gestures change. Connect a populated, described Border without gestures, then add a single-tap TapGestureRecognizer: it remains IsAccessibilityElement=false because GestureRecognizersOnCollectionChanged/LoadRecognizers adds the recognizer and Button trait but neither remaps Semantics nor promotes non-layout views. VoiceOver cannot focus the newly actionable Border, although coordinate taps work. Conversely, updating semantics on a structural ContentView with a pan recognizer takes the generic leaf path and hides its children despite having no accessible tap action. Classify accessible activation specifically and refresh the role on gesture changes; cover these post-connection sequences.

{
platformView.AccessibilityLabel = semantics.Description;
platformView.AccessibilityHint = semantics.Hint;
platformView.IsAccessibilityElement = false;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[major] Logic and Correctness Verification - PresentedContent being non-null does not mean there are accessible descendants to replace this focus stop. A ContentView containing only a decorative BoxView, with Description describing that visual and no gestures, now becomes IsAccessibilityElement=false. BoxView is not accessible by default, and ShouldGroupAccessibilityChildren only groups descendants; it does not create an accessible element for the parent's label/hint. The previously announced description therefore has no focusable owner. Preserve the semantic leaf when the content supplies no independently accessible element, and cover this negative case.

// should remain containers so their independently accessible children stay reachable.
if (view is IContentView contentView
&& view is not ILayout
&& contentView.PresentedContent is not null

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[moderate] Logic and Correctness Verification - Content changes do not refresh this new classification input. Connect a fixed-size Border with a Description and Label content, then set Content=null without changing semantics. It remains IsAccessibilityElement=false with grouped children even though no descendants remain, making its retained description unreachable instead of taking the empty-content leaf fallback. Border.ContentChanged updates logical children/layout and BorderHandler.MapContent replaces subviews; neither remaps Semantics. Adding accessible content to an initially empty described Border likewise leaves the new descendants hidden behind its existing leaf role. Re-evaluate the role on content changes and cover both transitions.

{
platformView.AccessibilityLabel = semantics.Description;
platformView.AccessibilityHint = semantics.Hint;
platformView.IsAccessibilityElement = false;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[moderate] Accessibility - Updating Description or Hint overrides an explicit AutomationProperties.IsInAccessibleTree=true. After connecting a populated ContentView or Border without gestures, set IsInAccessibleTree=true, then change either semantic property. Element.MapAutomationPropertiesIsInAccessibleTree sets the native flag to true, but VisualElement.UpdateSemanticsFromMapper subsequently remaps only IView.Semantics and this assignment resets it to false. The explicitly requested parent focus stop disappears despite the attached property remaining true; the previous generic semantics path preserved it. Honor the explicit accessibility-tree choice and cover this post-connection update sequence.

[Category(UITestCategories.Accessibility)]
public void ContainerDescriptionDoesNotHideIndividuallyAccessibleItems()
{
App.WaitForElement("SuggestionsContainer");

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[moderate] Regression Prevention and Test Coverage - Neither test protects the parent's semantic text. Removing the new parent AccessibilityLabel assignment while keeping the parent non-leaf leaves SuggestionsContainer, Item1..3, and the gesture result unchanged, so both tests still accept losing "Suggestions". The distinct item identifiers correctly distinguish Borders from inner Labels, but the parent never has a Hint and no assertion inspects its label/hint. Add focused iOS/MacCatalyst native parent-label/hint assertions alongside child reachability, including a Hint-only parent and a clear/reapply sequence that verifies the new cleanup.

platformView.AccessibilityHint = semantics.Hint;
platformView.IsAccessibilityElement = false;
platformView.ShouldGroupAccessibilityChildren = true;
UpdateSemanticsHeading(platformView, semantics);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

[moderate] Accessibility - Heading semantics are applied to a view this branch has just removed as an accessibility element. A Border containing a Label, with Description="Suggestions" and HeadingLevel=Level1 but no gestures, previously exposed a focusable Header element. It now has IsAccessibilityElement=false; UpdateSemanticsHeading sets Header only on that non-focusable Border, and neither the child Label nor another accessible element receives it. Grouping children does not create a heading element, so the heading is lost from VoiceOver heading navigation. Preserve an accessible heading representation while exposing the children and cover this scenario.

@kubaflo kubaflo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Could you please check the latest suggestions?

This branch had an error being deployed

1 failed (outdated) deployment
copilot-pat-pool — 9a88799e Deployed Jul 21, 2026 by SuthiYuvaraj via pre_activation #879
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

community ✨ Community Contribution partner/syncfusion Issues / PR's with Syncfusion collaboration s/agent-changes-requested AI agent recommends changes - found a better alternative or issues s/agent-reviewed PR was reviewed by AI agent workflow (full 4-phase review)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Inconsistent Accessibility Behavior Across Platforms in MAUI

5 participants