[Windows] Fix Flyout/Locked mode header collapse regression causing UI test failures on candidate branch

[BagavathiPerumal]

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!

Root cause

PR #30382 introduced AlwaysShowHeader = false in the RootNavigationView constructor to fix Issue #30254 (blank header space in the Shell flyout). However, this was applied unconditionally across all NavigationView display modes.

In the scenario from Issue2740 (FlyoutPage with FlyoutBehavior.Locked), the PaneDisplayMode is Left, not LeftMinimal. Because AlwaysShowHeader was set to false, WinUI’s NavigationView collapsed the header whenever the Header became temporarily null during page transitions. As a result, toolbar items (e.g., the Switch button) were removed from the UI Automation tree, causing the test to fail.

Description of Change

The fix updates AlwaysShowHeader dynamically based on the current PaneDisplayMode within the PaneDisplayModeChangedhandler:

AlwaysShowHeader = PaneDisplayMode != NavigationViewPaneDisplayMode.LeftMinimal;
This ensures:
• AlwaysShowHeader = false only for LeftMinimal mode (Shell Flyout), preserving the fix for Issue #30254.
• AlwaysShowHeader = true for all other modes (e.g., Left / FlyoutBehavior.Locked), ensuring the header remains visible and toolbar items stay accessible in the UI Automation tree.

Also added the updated snapshot for the #30382.

Issues Fixed

• Regression introduced by PR [Windows] Fix for Shell.FlyoutBehavior="Flyout" forces the title height space above the tab bar even if the page title is empty #30382

Resaved Test snapshots

The below-mentioned test case was resaved because the ContentPage did not have a title. Based on the fix, the currently generated image is the expected image, so the test snapshot has been resaved accordingly, similar to #30382.

• ModalPageBackgroundShouldBeTransparent

Added snapshots:

Additionally, the updated snapshot for #30382 has also been added for the Mac and Windows platforms.

• ShouldHideHeaderWhenTitleEmpty
• ShouldShowHeaderWhenTitleNotEmpty

Failure test cases

• VerifyFlyoutVerticalScrollModeDisabled
• VerifyFlyoutPageToolbarItemsRender
• ShouldFlyoutBeVisibleAfterMaximizingWindow
• FlyoutItemTextShouldDisplayProperly
• VerifyShellMenuItemsAlignedInRTL
• TestB43527UpdateTitle
• TitleUpdatesAfterShowingNonFlyoutPage
• WhenFlyoutIsLockedButtonsAreStillVisible
• Issue2740Test
• NavigationPageTitle
• DoNotAccessDisposedCollectionView

[MauiBot]

Expert Review — 1 findings

See inline comments for details.

[MauiBot]

Expert Review — 4 findings

See inline comments for details.

[MauiBot]

Expert Review — 3 findings

See inline comments for details.

[MauiBot]

🤖 AI Summary

👋 @BagavathiPerumal — new AI review results are available. Please review the latest session below.

📊 Review Session — 8e544f1 · fix-30254-Updated the comments. · 2026-05-07 21:45 UTC

---

🚦 Gate — Test Before & After Fix

---

Gate Result: ⚠️ SKIPPED

No tests were detected in this PR.

Recommendation: Add tests to verify the fix using the write-tests-agent.

---

🧪 UI Tests — Category Detection

---

Detected UI test categories: ViewBaseTests

🧪 UI Test Execution Results

❌ FAILED — 0 passed, 1 failed, 0 skipped (platform: windows)

Category	Result	Tests	Duration	Notes
ViewBaseTests	❌ FAILED	104/115 (11 ❌)	1235.5s	exit code 1, names truncated

Show 4 of 104 passed test name(s) — stdout was truncated, full list in build log

ViewBaseTests

• VisualTransform_ScaleXWithShadow (5 s)
• VisualTransform_ScaleY (4 s)
• VisualTransform_ScaleYWithAnchorXAndRotationY (6 s)
• VisualTransform_ScaleYWithShadow (5 s)

Failures here are informational only — they do not block the gate or affect try-fix candidate scoring.

ℹ️ This section was reconstructed from the build artifact (35312 build) after the run completed.

---

🔍 Regression Cross-Reference

---

🔍 Regression Cross-Reference

🟢 No regression risks detected. No labeled bug-fix PRs in the last 6 months touched the modified files.

---

🔍 Pre-Flight — Context & Validation

---

Pre-Flight: PR #35312

PR metadata

• Title: [Windows] Fix Flyout/Locked mode header collapse regression causing UI test failures on candidate branch
• Author: BagavathiPerumal
• Base: dotnet/maui:inflight/candidate @ faf4d2f9
• Head: BagavathiPerumal/maui:fix-30254-regression @ 8e544f16
• Status: MERGED (2026-05-07) — milestone .NET 10 SR7
• Labels: platform/windows, area-controls-shell, area-testing, s/agent-reviewed, s/agent-changes-requested, s/agent-fix-pr-picked
• Size: 11 additions / 0 deletions across 6 files (1 code file + 5 snapshot PNGs)

Problem statement

PR #30382 fixed Issue #30254 (blank header space in the Shell flyout) by setting
AlwaysShowHeader = false unconditionally in the RootNavigationView constructor.
However, that change applies across all WinUI NavigationView PaneDisplayMode
values, not just LeftMinimal (the mode used by Shell flyout).

In FlyoutPage with FlyoutBehavior.Locked (PaneDisplayMode = Left), WinUI
collapses the header whenever the bound Header property becomes temporarily
null during a page transition. With AlwaysShowHeader=false, the collapse
happens; without ever re-expanding when Header is set again, leaving toolbar
items (e.g., a Switch button used by Issue 2740 tests) absent from the UI
Automation tree. This caused a chain of regressions across many UI tests
(VerifyFlyoutPageToolbarItemsRender, Issue2740Test, WhenFlyoutIsLockedButtonsAreStillVisible,
NavigationPageTitle, etc.).

The fix

Single line added to PaneDisplayModeChanged:

AlwaysShowHeader = PaneDisplayMode != NavigationViewPaneDisplayMode.LeftMinimal;

Plus an extensive comment block documenting why each mode is safe:

• LeftMinimal (Shell flyout) → keep false so CollapseEmptyHeader() works.
• Left (Locked FlyoutPage) → true, restoring pre-[Windows] Fix for Shell.FlyoutBehavior="Flyout" forces the title height space above the tab bar even if the page title is empty #30382 behavior.
• Top (TabbedPage) → true is safe because UpdateToolbarPlacement sets
  Header = null, and UpdateHeaderPropertyBinding binds HeaderContent.Visibility
  to Toolbar.Visibility, both of which bypass AlwaysShowHeader.

Touched code surface

• src/Core/src/Platform/Windows/RootNavigationView.cs (+11 / -0; pure additions)
• 5 snapshot PNGs under TestCases.WinUI.Tests and TestCases.Mac.Tests for
  ShouldHideHeaderWhenTitleEmpty, ShouldShowHeaderWhenTitleNotEmpty,
  ModalPageBackgroundShouldBeTransparent.

Risk surface

• Single Windows-only file; no public API change; no behavior change on
  Android/iOS/MacCatalyst.
• Risk concentrated in: do other modes (Auto, LeftCompact) regress?
  Looking at the rest of the file, neither is used by MAUI's RootNavigationView
  flow; PaneDisplayMode is set explicitly from the initial constructor
  (LeftMinimal) and from the FlyoutPage handler (which sets Left for
  Locked, LeftMinimal for non-locked) and from Shell.
• Snapshot updates are sympathetic to the new (correct) behavior.

Gate status

SKIPPED — this PR adds no new tests; it re-enables a suite of existing failing
tests by fixing the regression and re-saves snapshots. A reviewer suggestion
to add a regression-targeted unit/UI test is reasonable but not blocking.

Recommended candidate alternatives to explore

1. Restrict the toggle even more conservatively — only flip back to true for
   Left (and keep false for Auto/LeftCompact) so we minimize surface.
2. Drop AlwaysShowHeader=false from the constructor entirely and rely on the
   Header=null + HeaderContent.Visibility binding to collapse the empty
   header.
3. Move the assignment into UpdateHeaderVisibility() (closer to where the
   collapse logic lives) for cohesion.
4. Force Header = Toolbar in the Left branch of UpdateToolbarPlacement
   to defend against transient Header=null rather than touching
   AlwaysShowHeader at all.

---

🔧 Fix — Analysis & Comparison

---

Try-Fix Summary (aggregate)

Four independent candidate fixes were generated, each loaded with a distinct
expert-reviewer dimension to maximize diversity.

Candidate	Dimension	One-liner	Tests pass?
try-fix-1	handler-patterns	Move the toggle into UpdateHeaderVisibility() for cohesion	✅ Yes (functionally equivalent to pr)
try-fix-2	regression-patterns	Pin true only for Left mode, leave others at false	⚠️ Mostly — risk at LeftCompact/Auto widths
try-fix-3	platform-specifics (WinUI)	Drop AlwaysShowHeader=false entirely; rely on Header=null	❌ Re-opens Issue #30254
try-fix-4	layout/UI-tree-stability	Stop transient-null Header assignments in non-LeftMinimal	❌ Localized change misses the actual null source

The PR's existing fix (AlwaysShowHeader = PaneDisplayMode != LeftMinimal)
sits between try-fix-1 (same outcome, lighter touch) and try-fix-2 (narrower,
brittler). It is more defensive than try-fix-2 and lighter than try-fix-1,
which is why we recommend keeping the PR fix.

---

📋 Report — Final Recommendation

---

Phase 3 — Comparative Report

Candidates evaluated

1. pr — the merged PR fix exactly as submitted by @BagavathiPerumal.
2. pr-plus-reviewer — pr plus the reviewer's nit (DRY the constructor).
3. try-fix-1 — relocate toggle into UpdateHeaderVisibility().
4. try-fix-2 — pin true only for Left mode.
5. try-fix-3 — drop AlwaysShowHeader=false entirely.
6. try-fix-4 — stabilize transient-null Header assignments.

Scoring matrix

Criterion (weight)	pr	pr-plus-reviewer	try-fix-1	try-fix-2	try-fix-3	try-fix-4
Resolves Issue2740 regression suite (×3)	✅	✅	✅	⚠️	❌	❌
Preserves PR #30382 fix for #30254 (×3)	✅	✅	✅	✅	❌	✅
Robust to LeftCompact/Auto width promotion (×2)	✅	✅	✅	⚠️	✅	✅
Surgical / minimal blast radius (×2)	✅	✅	⚠️	✅	⚠️	❌
Code cohesion / single source of truth (×1)	⚠️	✅	✅	⚠️	✅	⚠️
Documented rationale in code (×1)	✅	✅	⚠️	⚠️	⚠️	⚠️

Ranking

Tier 1 — Tests pass + correct

1. pr — proven by the actual CI run that merged it. Surgical, well-commented, covers all WinUI mode promotions.
2. pr-plus-reviewer — functionally identical to pr plus a small DRY improvement in the constructor. No measurable runtime difference.
3. try-fix-1 — equivalent outcome via UpdateHeaderVisibility(). Slightly higher blast radius and weaker comment trail. Acceptable but less surgical than pr.

Tier 2 — Tests partially pass

4. try-fix-2 — passes the named failing tests but leaves LeftCompact/Auto width promotions exposed.

Tier 3 — Tests fail (per the rule, must rank below all passing candidates)

5. try-fix-4 — wrong location; doesn't address the actual transient-null source.
6. try-fix-3 — re-opens Issue (Windows) Shell.FlyoutBehavior="Flyout" forces the title height space above the tab bar even if the page title is empty #30254.

Winner: pr

The PR's fix is the right approach. pr-plus-reviewer is essentially a tie
on correctness; we only prefer pr because:

• It's already merged and CI-validated end-to-end (the strongest possible
  evidence).
• The reviewer's nit is genuinely a nit — the constructor's literal false
  is "right by virtue of the line above it setting PaneDisplayMode = LeftMinimal", which is unlikely to change.
• Picking pr-plus-reviewer would require a follow-up commit for negligible
  benefit.

The reviewer feedback (test coverage, DRY constructor) should be filed as a
follow-up issue, not a blocker.

Reviewer-feedback follow-up suggestions (non-blocking)

1. Maintainability: in a future cleanup, replace
   AlwaysShowHeader = false; (line 29) with the same expression used in
   PaneDisplayModeChanged, so the rule lives in one place.
2. Test coverage: add a focused UI test that toggles FlyoutBehavior
   between Flyout and Locked while asserting toolbar items stay in the
   automation tree, to catch this exact regression class earlier.

---