[Windows] Border: Add AutomationPeer support

[Vignesh-SF3580]

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!

Description of Change

This PR is the first part of the split from #27713. It adds an AutomationPeer for the Windows Border (ContentPanel) so the control is properly exposed to UI Automation and accessibility tools while avoiding unnecessary noise in the screen-reader reading order.

• Added a new internal MauiBorderAutomationPeer derived from FrameworkElementAutomationPeer.
• Overrode ContentPanel.OnCreateAutomationPeer() to return MauiBorderAutomationPeer only when CrossPlatformLayout is IBorderView. Other ContentPanel usages continue using the default behavior.
• This peer is needed because Panel (the base class of ContentPanel) does not provide a default AutomationPeer, so Border was previously missing or not exposed correctly in the UIA tree.
• The peer follows an opt-in model for the screen-reader Control view, aligned with the layout AutomationPeer improvements from [Windows][net11] Make Layout AutomationPeer public + opt-in for screen reader tree #35597.

Added explicit opt-out handling so AutomationProperties.IsInAccessibleTree="False" always takes precedence over any opt-in signal, matching native WinUI Border behavior.

How It Works

On Windows, a MAUI Border is rendered using a native ContentPanel derived from Panel. UI Automation discovers elements by calling OnCreateAutomationPeer() on the native control and then querying the returned peer for details such as control type, class name, automation ID, accessible name, and Control / Content view membership.

• Peer entry point: ContentPanel.OnCreateAutomationPeer() now returns MauiBorderAutomationPeer only when CrossPlatformLayout is IBorderView. All other ContentPanel usages continue using the default behavior, so the change is scoped only to Border.
• What the peer provides: UI Automation queries methods like GetAutomationControlTypeCore, GetClassNameCore, IsControlElementCore, and IsContentElementCore. Existing MAUI mappings for AutomationId, SemanticProperties.Description, and Hint continue through the base peer implementation.
• Control View vs Content View: IsControlElementCore() is opt-in. It returns true only when the developer explicitly marks the Border as meaningful to accessibility tools using SemanticProperties.Description, SemanticProperties.Hint, or AutomationProperties.IsInAccessibleTree="True". This keeps decorative or structural Borders out of the screen-reader reading order. IsContentElementCore() requires explicit IsInAccessibleTree="True". AutomationId alone is treated as a UI-testing hook and does not move the Border into the accessibility views.
• Explicit opt-out: When AutomationProperties.IsInAccessibleTree="False" is set (AccessibilityView.Raw), both IsControlElementCore() and IsContentElementCore() immediately return false before evaluating any opt-in signals. This matches native WinUI Border behavior where an explicit opt-out always takes priority.
• Class name: GetClassNameCore() returns the cross-platform layout type name, such as "Border" or a derived type name like "MyBorder", instead of the generic native "Panel" name.

Overridden Core Methods and Purpose

1. GetAutomationControlTypeCore()
Returns AutomationControlType.Pane, which is the most suitable type for a layout container that is not an interactive control like a button or checkbox. This allows accessibility tools to treat the element as a structural container.
2. GetClassNameCore()
Returns the cross-platform control type name (for example, "Border") using panel.CrossPlatformLayout?.GetType().Name, with a fallback to nameof(Panel). This exposes the MAUI control name instead of the generic native Panel.
3. IsControlElementCore() (opt-in + opt-out)
Returns false immediately when AccessibilityView.Raw is set (IsInAccessibleTree="False"). Otherwise, it returns true when AccessibilityView is Control or Content (IsInAccessibleTree="True"), or when AutomationProperties.Name (SemanticProperties.Description) or AutomationProperties.HelpText (SemanticProperties.Hint) is set. If none of these conditions are met, it returns false, keeping structural or decorative Borders out of the Control view.
4. IsContentElementCore() (explicit opt-in only)
Returns false when AccessibilityView.Raw is set. Otherwise, it returns true only when AccessibilityView.Content is set (IsInAccessibleTree="True"). AutomationId alone does not move the Border into the Content view.

Issues Fixed

Fixes #27627

[github-actions]

🚀 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 -- 35577

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.ps1) } 35577"

[sheiksyedm]

/azp run maui-pr-uitests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[kubaflo]

/review -b feature/regression-check

[MauiBot]

Expert Review — 2 findings

See inline comments for details.

[kubaflo]

/review -b feature/refactor-copilot-yml

[MauiBot]

🤖 Automated review — alternative fix proposed

The expert-reviewer evaluation compared the PR fix against #1 automatically generated candidates and selected try-fix-1 as the strongest fix.

Why: try-fix-1 passed the Windows regression test and is more complete than the PR variants: it preserves Border AutomationId lookup, honors semantic descriptions, filters the decorative border Path from UIA children, and scopes peer creation to a Border-specific platform panel.

Please consider applying the candidate diff below (or use it as guidance). Once you push an update, this workflow will re-trigger and re-evaluate.

Candidate diff (`try-fix-1`)

diff --git a/src/Controls/tests/TestCases.HostApp/Issues/Issue27627.cs b/src/Controls/tests/TestCases.HostApp/Issues/Issue27627.cs
new file mode 100644
index 0000000000..2411f4027b
--- /dev/null
+++ b/src/Controls/tests/TestCases.HostApp/Issues/Issue27627.cs
@@ -0,0 +1,43 @@
+namespace Maui.Controls.Sample.Issues;
+
+[Issue(IssueTracker.Github, 27627, "[Windows] Border Automation Peer", PlatformAffected.UWP)]
+public partial class Issue27627 : ContentPage
+{
+	public Issue27627()
+	{
+		var grid = new Grid();
+
+		var border = new Border
+		{
+			AutomationId = "TestBorder",
+			VerticalOptions = LayoutOptions.Center,
+			HeightRequest = 100,
+			Padding = new Thickness(10),
+			Stroke = Colors.Red
+		};
+
+		var label = new Label
+		{
+			Text = "Welcome to Maui!",
+			AutomationId = "TestLabel",
+			HorizontalOptions = LayoutOptions.Center,
+			VerticalOptions = LayoutOptions.Center
+		};
+
+		var nestedBorder = new Border
+		{
+			Stroke = Colors.Blue,
+			AutomationId = "NestedBorder",
+			StrokeThickness = 2,
+			Padding = new Thickness(10),
+			HorizontalOptions = LayoutOptions.Center,
+			VerticalOptions = LayoutOptions.Center,
+		};
+
+		nestedBorder.Content = label;
+		border.Content = nestedBorder;
+
+		grid.Children.Add(border);
+		Content = grid;
+	}
+}
diff --git a/src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue27627.cs b/src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue27627.cs
new file mode 100644
index 0000000000..7a1b68c104
--- /dev/null
+++ b/src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue27627.cs
@@ -0,0 +1,29 @@
+using NUnit.Framework;
+using UITest.Appium;
+using UITest.Core;
+
+namespace Microsoft.Maui.TestCases.Tests.Issues
+{
+	public class Issue27627 : _IssuesUITest
+	{
+		public override string Issue => "[Windows] Border Automation Peer";
+
+		public Issue27627(TestDevice device)
+		: base(device)
+		{ }
+
+		[Test]
+		[Category(UITestCategories.Border)]
+		public void VerifyBorderAutomationPeer()
+		{
+			// Check whether the parent Border is found or not
+			App.WaitForElement("TestBorder");
+
+			// Check whether the nested Border is found or not
+			App.WaitForElement("NestedBorder");
+
+			// Check whether the Label inside the nested Border is found or not
+			App.WaitForElement("TestLabel");
+		}
+	}
+}
diff --git a/src/Core/src/Handlers/Border/BorderHandler.Windows.cs b/src/Core/src/Handlers/Border/BorderHandler.Windows.cs
index d9a32ce0ca..8ac5a49c99 100644
--- a/src/Core/src/Handlers/Border/BorderHandler.Windows.cs
+++ b/src/Core/src/Handlers/Border/BorderHandler.Windows.cs
@@ -1,4 +1,4 @@
-using System;
+using System;
 
 namespace Microsoft.Maui.Handlers
 {
@@ -39,7 +39,7 @@ namespace Microsoft.Maui.Handlers
 				throw new InvalidOperationException($"{nameof(VirtualView)} must be set to create a LayoutView");
 			}
 
-			var view = new ContentPanel
+			var view = new BorderContentPanel
 			{
 				CrossPlatformLayout = VirtualView
 			};
diff --git a/src/Core/src/Platform/Windows/MauiBorderAutomationPeer.cs b/src/Core/src/Platform/Windows/MauiBorderAutomationPeer.cs
new file mode 100644
index 0000000000..be443d4964
--- /dev/null
+++ b/src/Core/src/Platform/Windows/MauiBorderAutomationPeer.cs
@@ -0,0 +1,86 @@
+#nullable enable
+using System.Collections.Generic;
+using Microsoft.UI.Xaml.Automation;
+using Microsoft.UI.Xaml.Automation.Peers;
+using Microsoft.UI.Xaml.Controls;
+
+namespace Microsoft.Maui.Platform
+{
+// TODO: Make this class public in .NET11.0. Issue Link: https://github.com/dotnet/maui/issues/30205
+internal partial class MauiBorderAutomationPeer : FrameworkElementAutomationPeer
+{
+internal MauiBorderAutomationPeer(ContentPanel owner) : base(owner) { }
+
+protected override AutomationControlType GetAutomationControlTypeCore()
+{
+return AutomationControlType.Pane;
+}
+
+protected override string GetClassNameCore()
+{
+if (Owner is ContentPanel panel)
+{
+return panel.CrossPlatformLayout?.GetType().Name ?? nameof(Panel);
+}
+
+return nameof(Panel);
+}
+
+protected override IList<AutomationPeer>? GetChildrenCore()
+{
+var children = base.GetChildrenCore();
+
+if (children is null || Owner is not ContentPanel contentPanel)
+{
+return children;
+}
+
+List<AutomationPeer>? filteredChildren = null;
+
+for (var i = 0; i < children.Count; i++)
+{
+var child = children[i];
+
+if (child is FrameworkElementAutomationPeer peer && peer.Owner == contentPanel.BorderPath)
+{
+filteredChildren ??= new List<AutomationPeer>(children.Count - 1);
+
+for (var j = 0; j < i; j++)
+{
+filteredChildren.Add(children[j]);
+}
+
+continue;
+}
+
+filteredChildren?.Add(child);
+}
+
+return filteredChildren ?? children;
+}
+
+protected override bool IsControlElementCore() => true;
+
+protected override bool IsContentElementCore() => HasAutomationId() || HasSemanticDescription();
+
+bool HasAutomationId()
+{
+if (Owner is not ContentPanel contentPanel)
+{
+return false;
+}
+
+return !string.IsNullOrEmpty(AutomationProperties.GetAutomationId(contentPanel));
+}
+
+bool HasSemanticDescription()
+{
+if (Owner is not ContentPanel contentPanel)
+{
+return false;
+}
+
+return !string.IsNullOrEmpty(AutomationProperties.GetName(contentPanel));
+}
+}
+}
\ No newline at end of file

[kubaflo]

Could you please check the ai's suggestions?

[kubaflo]

/review -b feature/refactor-copilot-yml

[MauiBot]

Expert Review — 2 findings

See inline comments for details.

[kubaflo]

Can you please resolve conflicts?

[Vignesh-SF3580]

Can you please resolve conflicts?

@kubaflo I have resolved the conflicts.