[release/10.0.1xx-sr10] Preserve custom iOS button styling

[kubaflo]

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!

Summary

Manual backport of #36769 to release/10.0.1xx-sr10 for .NET MAUI 10.0.101.

• Addresses [iOS] ButtonHandler now clears platform-view styling set by custom handlers when Button.Background/TextColor are null (regression in 10.0.80) #36749.
• Applies the exact net patch from immutable source head 348f69b8e04a72d83b563064404a7c4fd79aef75.
• Preserves the iOS UI regression coverage from the source PR.
• The source PR merged to inflight/current and has not flowed to main; this manual port intentionally excludes unrelated inflight branch history.

Validation

• Source and SR10 patches have matching stable patch ID f5eb0ffddfe5e87e84c64060fcb73927191d00e1.
• Core.csproj builds successfully for net10.0-ios26.0 in Release configuration with zero warnings and zero errors.

Review gate

This agent-authored release PR must remain unmerged until two distinct non-bot MAUI maintainers with write access, other than the PR author, approve the current head SHA.

[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 -- 37726

Or

• Run remotely in PowerShell:

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

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
There may be pipelines that require an authorized user to comment /azp run to run.

[kubaflo]

/azp run

[azure-pipelines]

Azure Pipelines:
Successfully started running 3 pipeline(s).

[Copilot]

Pull request overview

Backports the iOS ButtonHandler regression fix to release/10.0.1xx-sr10 by updating the iOS UIButton background-mapping behavior to preserve native styling when Background is unset during initial handler connection, and adds a UI regression test covering the scenario.

Changes:

• iOS: Guard UIButton.BackgroundColor = UIColor.Clear behind a Window != null check when paint is null/empty, preserving constructor-set native styling on initial render.
• Tests: Add HostApp repro page + custom handler and a corresponding Appium UI test for issue #36749.
• Register the custom test handler in the HostApp’s MauiProgram.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
src/Core/src/Platform/iOS/ButtonExtensions.cs	Updates iOS button background mapping to avoid clearing native styling during initial render when Window is null.
src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue36749.cs	Adds an Appium UI test asserting the regression is fixed on iOS/MacCatalyst.
src/Controls/tests/TestCases.HostApp/MauiProgram.cs	Registers the issue-specific custom button handler for the HostApp test page.
src/Controls/tests/TestCases.HostApp/Issues/Issue36749.cs	Adds the HostApp issue page and custom ButtonHandler/UIButton subclass used to reproduce and validate the fix.

[PureWeen]

Adversarial review

💡 Regression — src/Core/src/Platform/iOS/ButtonExtensions.cs:74: Window == null identifies both the initial map and a previously shown button that is temporarily detached. If a button with a MAUI solid background is detached (for example, during navigation or cell reuse) and its Background becomes null, the mapper removes its gradient layer but skips BackgroundColor = UIColor.Clear. Reattaching the existing native button can therefore show the stale solid background instead of restoring the null-background state.

Use a one-time initial-map/handler-lifecycle signal rather than current window attachment, so only the true first map preserves native styling while later null-background updates always clear prior MAUI state.

Flagged by: 3/3 reviewers, including independent reviewer validation.

The added UI test covers initial native styling preservation, but not the detached-view reset path above.

Methodology: 3 independent reviewers with adversarial consensus.

[kubaflo]

@copilot addressed the latest feedback by making a missing native background color a deterministic UI-test failure. The iOS-simulator HostApp build succeeds cleanly. This is ready for re-review — thanks!

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue36749.cs:26

• The test reads the result label immediately after WaitForElement(...), but the label is created with initial text "Checking..." and is only updated in OnAppearing() in the HostApp page. Since _IssuesUITest navigation doesn’t wait for OnAppearing, this can flake by asserting against "Checking...". Prefer waiting for the label text to become "PASS" (or timing out) using WaitForTextToBePresentInElement.

        App.WaitForElement("Issue36749Result");

        var resultText = App.FindElement("Issue36749Result").GetText();

        Assert.That(resultText, Is.EqualTo("PASS"),

[kubaflo]

@PureWeen fixed in 6c898fa. ButtonExtensions now tracks the first background mapping per native UIButton with weak lifecycle state instead of inferring it from Window, so only the true initial null map preserves constructor/appearance styling and later null maps clear stale MAUI state even while detached. The Issue36749 regression now explicitly applies a red MAUI background, detaches the native view, clears the background, and requires transparent output. Core iOS Button device tests passed (97 passed, 1 skipped), and the iOS HostApp plus Appium test assembly build cleanly. Ready for re-review — thanks!

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue36749.cs:1

• Minor: the preprocessor line comment is missing a space after // and uses "Mac Catalyst" inconsistently with the rest of the repo's "MacCatalyst" naming.

#if IOS || MACCATALYST      //This is an iOS-specific issue and can be reproduced by extending UIButton. Therefore, the test was added only for iOS and Mac Catalyst.

src/Controls/tests/TestCases.HostApp/Issues/Issue36749.cs:70

• This comment explains the detached-null scenario in terms of a Window-based guard, but the production fix is now initial-update state tracking. Rewording to a conditional rationale avoids implying the current code uses Window checks.

		// A later null mapping must clear MAUI-applied state even while the native view is
		// detached. Window-based initial-map detection incorrectly leaves this color red.

[PureWeen]

Adversarial review

⚠️ Regression — src/Core/src/Platform/iOS/ButtonExtensions.cs:63 records whether a UIButton has ever received a background mapping, rather than whether the current virtual button has applied a MAUI background. ElementHandler.SetVirtualView deliberately retains an existing platform view when it reconnects that handler to a different virtual view, then reruns all property mappers. A recycled custom button whose new virtual view still has the default null Background therefore takes the later-null path and sets UIColor.Clear, wiping the native constructor styling this change is intended to preserve.

Track the initialization state per virtual-view assignment, or clear only after MAUI has applied a non-null background, and add a reconnect/reuse regression case.

Flagged by 2/3 reviewers after adversarial consensus and independent reviewer source validation.

Automated assessment complete: verified current head 6c898fa576dbeda5dd933b8421ea4e068fb7e859; sender session 20939cfd-13dd-40eb-83ee-cdb524c95e95.

[PureWeen]

Adversarial review

💡 Logic — src/Core/src/Platform/iOS/ButtonExtensions.cs:83 records HasMauiBackground for every non-empty paint even though ViewExtensions.UpdateBackground applies only SolidPaint and GradientPaint. A custom UIButton with native styling can receive a valid ImagePaint or PatternPaint (neither changes BackgroundColor), then receive Background = null; the recorded state makes the null path clear the native color even though MAUI never applied a background. Mark state only for paint types that the delegated updater applies, and add this transition to the regression coverage.

Flagged by: 3/3 reviewers after adversarial consensus, including independent reviewer validation.

The current tests cover initial native styling, a detached solid-background clear, and handler reuse, but not the image/pattern-paint transition above.

Methodology: 3 independent reviewers with adversarial consensus.

[kubaflo]

@PureWeen addressed in 8ef8ece: weak state is now recorded only for SolidPaint/GradientPaint, the paint kinds the delegated iOS updater actually applies. Added direct PatternPaint -> null coverage proving unsupported paints preserve native UIButton styling. The iOS Core Button category passed 99/100 with the existing single skip. Ready for re-review.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue36749.cs:21

• The test can race by reading the result label immediately after it appears; the label exists with initial text (e.g., "Checking...") before OnAppearing updates it to PASS/FAIL. This can make the test flaky.

        App.WaitForElement("Issue36749Result");

        var resultText = App.FindElement("Issue36749Result").GetText();

src/Core/src/Platform/iOS/ButtonExtensions.cs:67

• UpdateBackground calls RemoveBackgroundLayer() and then delegates to ViewExtensions.UpdateBackground(...), which calls RemoveBackgroundLayer() again for non-null paints. This duplicates work on every non-null background update and makes the cleanup logic harder to follow.

			// Remove previous background gradient layer if any.
			// Safe to call when MAUI has not applied a gradient because this is a no-op.
			// Running it before the paint guard ensures any previously-applied gradient is cleaned
			// up regardless of the new paint value.
			platformButton.RemoveBackgroundLayer();

[PureWeen]

Adversarial review

⚠️ Logic — ButtonExtensions.UpdateBackground records HasMauiBackground for every GradientPaint, but the delegated iOS updater creates a layer only for LinearGradientPaint and RadialGradientPaint. A custom non-empty GradientPaint subclass therefore leaves constructor/native styling intact while arming the state; clearing Background afterward resets that native color to UIColor.Clear even though MAUI never applied a background.

Track the state only for SolidPaint, LinearGradientPaint, and RadialGradientPaint, or set it only when the delegated updater actually applies a layer. Add the analogous custom-gradient-to-null regression case.

Flagged by: 3/3 reviewers after adversarial consensus, including independent reviewer validation.

Methodology: 3 independent reviewers with adversarial consensus + repo domain specialist.

[kubaflo]

@PureWeen addressed the custom-gradient background ownership finding in c28674d9e9 and added the analogous native-style regression test. The iOS Button device category passed 100 tests (1 skipped). This is ready for re-review — thanks!

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue36749.cs:1

• The #if line comment uses inconsistent spacing and platform naming ("Mac Catalyst") compared to other issue tests (e.g., Issue35490.cs:1 uses "MacCatalyst"). Normalizing this makes the comment easier to scan and keeps terminology consistent.

#if IOS || MACCATALYST      //This is an iOS-specific issue and can be reproduced by extending UIButton. Therefore, the test was added only for iOS and Mac Catalyst.

[PureWeen]

Adversarial review

An independent reviewer completed an exact-head review of c28674d9e9d2ffb9980cef0ff54b5c6da0869445.

No actionable findings. The iOS background ownership tracking and its UI/device regression coverage are internally consistent.

Methodology: 3 independent reviewers with adversarial consensus.

Test coverage: The PR adds targeted HostApp, Appium, and iOS device coverage; this was a review-only pass.

[kubaflo]

SR10.1 merge assessment

Recommendation: merge. Current head c28674d9e9 is mergeable, and its completed current-head check set is 36 passed, 0 failed, 0 canceled, 1 skipped. No unresolved current review threads were found.

The remaining BLOCKED state is the required independent review. Because @kubaflo authored this PR, GitHub requires approval from a different maintainer; the authenticated account cannot self-approve it.