[iOS] Fixed Flyout icon not updating when root page changes using InsertPageBefore

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

Issue Detail

When using the InsertPageBefore method to change the root page in a NavigationPage, the back button is not visible, but the flyout icon remains visible.
 

Root Cause

The flyout icon was not updated when changing the root page using InsertPageBefore.
 

Description of Change

The updated logic checks whether the inserted page becomes the new root, updates the flyout icon. Previously, the flyout icon was updated based on NavPageController.Pages. However, this collection was not updated with the actual native navigation stack. Since pages are inserted directly into ViewControllers in InsertPageBefore, the fix updates the flyout icon based on the ViewControllers stack instead.

Tested the behavior in the following platforms

• Android
• Windows
• iOS
• Mac

Issues Fixed

Fixes #29921

Screenshots

Before Issue Fix	After Issue Fix
iOSBeforeFixInsertpage.mov	iOSAfterFixInsertPage.mov

[jsuarezruiz]

/azp run MAUI-UITests-public

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[jsuarezruiz]

Pending snapshot on Mac and Windows.

Could you commit the images?

[Vignesh-SF3580]

@jsuarezruiz I have updated the pending snapshots for Mac and Windows.

[jsuarezruiz]

/azp run MAUI-UITests-public

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[Copilot]

Pull request overview

This PR fixes an iOS-specific issue where the flyout icon was not updated when the root page of a NavigationPage was changed using the InsertPageBefore method. The fix updates the logic to reference the actual native ViewControllers stack instead of the managed Pages collection, which was not kept in sync during InsertPageBefore operations.

Key Changes

• Updated flyout icon update logic to use ViewControllers stack for determining the first page
• Added automatic flyout icon update when inserting a page at index 0 (making it the new root)
• Added comprehensive UI test coverage with snapshots for all platforms

Reviewed changes

Copilot reviewed 3 out of 7 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/Controls/src/Core/Compatibility/Handlers/NavigationPage/iOS/NavigationRenderer.cs	Core fix: Updates InsertPageBefore to trigger flyout icon update when inserting at root position, and changes UpdateLeftBarButtonItem to use ViewControllers instead of Pages collection
src/Controls/tests/TestCases.HostApp/Issues/Issue29921.cs	Test implementation: Creates FlyoutPage with NavigationPage that demonstrates the InsertPageBefore root change scenario
src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue29921.cs	NUnit test: Automates the test by clicking button and verifying screenshot shows correct state after root page change
src/Controls/tests/TestCases.iOS.Tests/snapshots/ios/FlyoutIconUpdatedAfterInsertPageBefore.png	Expected visual output for iOS platform
src/Controls/tests/TestCases.Android.Tests/snapshots/android/FlyoutIconUpdatedAfterInsertPageBefore.png	Expected visual output for Android platform
src/Controls/tests/TestCases.WinUI.Tests/snapshots/windows/FlyoutIconUpdatedAfterInsertPageBefore.png	Expected visual output for Windows platform
src/Controls/tests/TestCases.Mac.Tests/snapshots/mac/FlyoutIconUpdatedAfterInsertPageBefore.png	Expected visual output for MacCatalyst platform

The changes are well-structured, follow established patterns in the codebase, and include appropriate test coverage. The fix correctly addresses the root cause by using the native ViewControllers collection which is properly maintained during InsertPageBefore operations.

[rmarinho]

🤖 AI Summary

📊 Expand Full Review

---

🔍 Pre-Flight — Context & Validation

---

📝 Review Session — Update FlyoutIconUpdatedAfterInsertPageBefore.png · 25655ad

---

Issue: #29921 - [iOS] Flyout icon not replaced by back button when root page is changed using InsertPageBefore
PR: #29924 - [iOS] Fixed Flyout icon not updating when root page changes using InsertPageBefore
Platforms Affected: iOS (primary, label: platform/ios; also tested on Android, Windows, Mac)
Files Changed: 1 implementation file, 2 test files, 4 snapshot images
Author: Vignesh-SF3580 (community contribution, Syncfusion partner)

Issue Summary

When using InsertPageBefore to change the root page in a NavigationPage that is inside a FlyoutPage, the flyout icon (hamburger menu) remains visible in the navigation bar instead of being replaced by a back button. This is an iOS-specific bug.

Reproduction Steps:

1. Start with a FlyoutPage containing a NavigationPage
2. Call Navigation.InsertPageBefore(newPage, navPage.RootPage) to insert before the root page
3. Observe that the flyout (hamburger) icon is still shown — expected: back button

Root Cause (from PR description)

The UpdateLeftBarButtonItem method was checking NavPageController.Pages (the managed collection) to determine the first page. However, during InsertPageBefore, pages are inserted directly into ViewControllers (the native collection), so NavPageController.Pages was not updated. Using the native ViewControllers collection fixes the sync issue.

PR's Fix Approach

Changes in NavigationRenderer.cs:

1. InsertPageBefore method (line ~663):

   • Captures the insertion index
   • After inserting into ViewControllers, checks if (index == 0) (new root)
   • Calls (target as ParentingViewController)?.UpdateLeftBarButtonItem() to refresh

2. UpdateLeftBarButtonItem method (line ~1659):

   • Changed from n.NavPageController.Pages.FirstOrDefault()
   • To (n.ViewControllers.FirstOrDefault() as ParentingViewController)?.Child
   • Uses native stack instead of managed collection

Test Coverage

HostApp Test: Issue29921.cs

• FlyoutPage (root) → NavigationPage containing Issue29921Page1
• Issue29921Page1 has a button calling InsertPageBefore to insert Issue29921Page2 as new root

NUnit Test: Issue29921.cs (TestCases.Shared.Tests)

• Category: FlyoutPage
• App.WaitForElement("InsertPageButton") → App.Tap("InsertPageButton") → VerifyScreenshot()
• Snapshot-based verification for all 4 platforms

PR Discussion Summary

Reviewer	Feedback	Status
jsuarezruiz	Missing snapshots for Mac and Windows	✅ Resolved
kubaflo	iOS snapshot needed update	✅ Resolved (commit 25655ad)
jsuarezruiz	Initially CHANGES_REQUESTED (snapshots); subsequently approved	✅ Resolved
copilot-pull-request-reviewer	General review, no blocking comments	✅

Prior Agent Review

A complete agent review was posted by user 'rmarinho':

• ✅ Pre-Flight: Complete
• ❌ Gate: Failed (environment blocker — snapshot dimension mismatch: 1124×2286 vs 1206×2472)
• ⏭️ Fix: Skipped (environment blocker)
• ✅ Report: APPROVE recommended

Gate failure was due to iPhone 14 simulator vs iPhone Xs baseline mismatch — not a code bug.

Files Classification

Fix files:

• src/Controls/src/Core/Compatibility/Handlers/NavigationPage/iOS/NavigationRenderer.cs (+9/-3)

Test files:

• src/Controls/tests/TestCases.HostApp/Issues/Issue29921.cs (new, +63)
• src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue29921.cs (new, +22)
• 4 snapshot images (iOS, Android, Windows, Mac)

Test Type: UI Tests (Appium/VerifyScreenshot)

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
PR	PR #29924	Update InsertPageBefore to call UpdateLeftBarButtonItem when index==0; change UpdateLeftBarButtonItem to use ViewControllers stack	⏳ PENDING (Gate)	NavigationRenderer.cs (+9/-3)	Original PR — uses native ViewControllers for accurate first-page detection

---

🚦 Gate — Test Verification

---

📝 Review Session — Update FlyoutIconUpdatedAfterInsertPageBefore.png · 25655ad

---

Result: ✅ PASSED
Platform: ios
Mode: Full Verification (RequireFullVerification: true)

Check	Expected	Actual	Status
Tests WITHOUT fix	FAIL	FAIL	✅
Tests WITH fix	PASS	PASS	✅

• Tests FAIL without fix ✅ (bug is present, test detects it)
• Tests PASS with fix ✅ (fix resolves the issue)

Conclusion: Tests correctly validate the fix and catch the bug.

---

🔧 Fix — Analysis & Comparison

---

📝 Review Session — Update FlyoutIconUpdatedAfterInsertPageBefore.png · 25655ad

---

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
1	try-fix	In InsertPageBefore when index==0, call UpdateLeftBarButtonItem via BeginInvokeOnMainThread (deferred, no change to UpdateLeftBarButtonItem logic)	✅ PASS	1 file	Different from PR: deferred instead of synchronous, keeps NavPageController.Pages in UpdateLeftBarButtonItem
2	try-fix	Override ViewControllers property setter to detect root changes, call UpdateLeftBarButtonItem via BeginInvokeOnMainThread. No InsertPageBefore change	✅ PASS	3 files (+PublicAPI)	Intercepts any root change from any code path, not just InsertPageBefore
3	try-fix	In InsertPageBefore, clear NavigationItem.LeftBarButtonItem directly on old root VC when index==0 and FlyoutPage present	✅ PASS	1 file	Minimal: directly clears stale button state without going through UpdateLeftBarButtonItem
4	try-fix	Use NavPage.Navigation.NavigationStack.FirstOrDefault() in UpdateLeftBarButtonItem + call from ViewWillAppear	❌ FAIL	1 file	1.89% visual diff — NavigationStack doesn't sync correctly
5	try-fix	Modify SetFlyoutLeftBarButton as gatekeeper: check native position; update all VCs in InsertPageBefore	✅ PASS	1 file	Defense-in-depth: prevents flyout icon from being set on non-root VCs
6	try-fix	Hook UINavigationControllerDelegate.DidShowViewController to loop UpdateLeftBarButtonItem	❌ FAIL	1 file	1.89% diff — UpdateLeftBarButtonItem still reads stale Pages without companion fix
7	try-fix	KVO observer on viewControllers key path	❌ FAIL	3 files	UIKit's setViewControllers:animated: bypasses KVO — fundamentally incompatible
PR	PR #29924	Change UpdateLeftBarButtonItem to use ViewControllers instead of Pages; call it synchronously from InsertPageBefore when index==0	✅ PASS (Gate)	NavigationRenderer.cs (+9/-3)	Original PR — minimal, cohesive two-part fix addressing both the trigger and the data source bug

Cross-Pollination: 3 rounds completed. All 5 models confirmed NO NEW IDEAS in round 3.

Exhausted: Yes

Fix Selection Analysis

Passing candidates:

• Attempt 1 (BeginInvokeOnMainThread): Similar scope to PR but defers the call and doesn't fix the data source bug in UpdateLeftBarButtonItem. The deferred call works due to timing, but leaves Pages vs ViewControllers inconsistency unaddressed.
• Attempt 2 (Override ViewControllers setter): Broader fix — catches root changes from any source. However, it touches more code (setter override + PublicAPI entries), and the deferred call adds complexity.
• Attempt 3 (Clear LeftBarButtonItem directly): Minimal. Works but bypasses the proper UpdateLeftBarButtonItem flow; less aligned with codebase patterns.
• Attempt 5 (SetFlyoutLeftBarButton gatekeeper): Defensive approach but modifies more code paths (every call to SetFlyoutLeftBarButton), increasing risk.
• PR's fix: Two-part, cohesive fix — (1) correct the data source bug (Pages → ViewControllers in UpdateLeftBarButtonItem), (2) add the explicit trigger when needed (InsertPageBefore index==0). Minimal, focused, and addresses both the symptom and root cause.

Selected Fix: PR's fix — it is the simplest, most cohesive solution that addresses both the root cause (stale Pages collection in UpdateLeftBarButtonItem) and the missing trigger. All try-fix alternatives either leave a secondary bug unaddressed or require more code changes. The PR's fix is optimal.

---

📋 Report — Final Recommendation

---

📝 Review Session — Update FlyoutIconUpdatedAfterInsertPageBefore.png · 25655ad

---

✅ Final Recommendation: APPROVE

Summary

PR #29924 fixes a bug where calling InsertPageBefore to change the root page in a NavigationPage (inside a FlyoutPage) on iOS would leave the flyout (hamburger) icon visible instead of showing a back button. The fix is minimal, correct, and well-tested.

Root Cause

UpdateLeftBarButtonItem was reading NavPageController.Pages.FirstOrDefault() to determine if the current page was the root. However, InsertPageBefore inserts pages directly into the native ViewControllers array without updating NavPageController.Pages, causing a stale read. Additionally, InsertPageBefore never called UpdateLeftBarButtonItem at all, so the bar button never had a chance to refresh.

Fix Quality

Two-part cohesive fix (+9/-3 lines):

1. Data source fix (UpdateLeftBarButtonItem): Change from NavPageController.Pages.FirstOrDefault() to (n.ViewControllers.FirstOrDefault() as ParentingViewController)?.Child — always reads the accurate native stack
2. Trigger fix (InsertPageBefore): When index == 0 (new root), call UpdateLeftBarButtonItem() on the displaced root VC to refresh its bar button item

Alternative Exploration Results

7 independent fix attempts were explored across 5 AI models:

• 4 PASS (attempts 1, 2, 3, 5): All alternatives found working solutions
• 3 FAIL (attempts 4, 6, 7): NavigationStack, DidShowViewController, and KVO approaches failed due to sync/timing issues
• All PASS candidates were more complex or less cohesive than the PR's fix
• The PR's fix was independently validated as the simplest and most complete solution

Code Quality Assessment

• ✅ Minimal change (9 additions, 3 deletions in one implementation file)
• ✅ Proper null-safety (?.UpdateLeftBarButtonItem(), ?.Child)
• ✅ Correct guard condition (index == 0 precisely identifies new-root case)
• ✅ Comprehensive UI tests with snapshots for all 4 platforms
• 🟡 Minor: Test label text slightly misleading ("Flyout icon is visible")
• 🟡 Minor: Missing trailing newline in one test file
• 🟡 Title should use "Fix" not "Fixed"

Platforms Tested (by author)

• iOS (primary affected platform)
• Android
• Windows
• Mac

Agent Test Results

• Gate: ✅ PASSED on iOS — tests FAIL without fix, PASS with fix
• Try-fix: Exhausted — PR's fix is the best available candidate

Recommendation: APPROVE — PR's fix is correct, minimal, and optimal.

---

📋 Expand PR Finalization Review

---

Title: ✅ Good

Current: [iOS] Fixed Flyout icon not updating when root page changes using InsertPageBefore

Description: ✅ Good

Description needs updates. See details below.

✨ Suggested PR Description

[!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 Detail

When using InsertPageBefore to insert a page before the current root in a NavigationPage inside a FlyoutPage, the flyout icon was not updated correctly: the old root page continued to show the flyout icon even though it was no longer the root.

Root Cause

The flyout icon visibility is determined in UpdateLeftBarButtonItem by comparing the current page against the first page in the navigation stack. Previously, this used NavPageController.Pages.FirstOrDefault(), which reflects the MAUI page collection. However, when InsertPageBefore inserts pages, it does so directly into the native ViewControllers array without updating NavPageController.Pages. This caused the root page detection to use stale data.

Description of Change

**1. trigger flyout icon update on root change:** InsertPageBefore
When the inserted page becomes the new root (index == 0), UpdateLeftBarButtonItem() is now called on the old root's ParentingViewController to clear its flyout icon.

**2. use native ViewControllers as source of truth:** UpdateLeftBarButtonItem
Changed firstPage detection from NavPageController.Pages.FirstOrDefault() to (n.ViewControllers.FirstOrDefault() as ParentingViewController)?.Child. Since InsertPageBefore inserts directly into ViewControllers, the native stack is always accurate. This also makes UpdateLeftBarButtonItem more robust for all callers.

Issues Fixed

Fixes #29921

Tested the behavior in the following platforms

• Android
• Windows
• iOS
• Mac

Screenshots

Before Issue Fix	After Issue Fix
iOSBeforeFixInsertpage.mov	iOSAfterFixInsertPage.mov

Code Review: ✅ Passed

Code Review: PR #29924

Changes Reviewed

NavigationRenderer. Two changes:cs

1. InsertPageBefore: Capture index, then call UpdateLeftBarButtonItem() on the old root when a new root is inserted (index == 0)
2. UpdateLeftBarButtonItem: Changed firstPage source from NavPageController.Pages.FirstOrDefault() to (n.ViewControllers.FirstOrDefault() as ParentingViewController)?.Child

---

1. UpdateLeftBarButtonItem is called on old root, but new root may also need it

File: NavigationRenderer.cs:668
Code:

if (index == 0)
{
    (target as ParentingViewController)?.UpdateLeftBarButtonItem();
}

target is the old root (now at index 1 after insertion). Calling UpdateLeftBarButtonItem() on it correctly clears the flyout icon from the old root. However, the new root (pageContainer) also needs the flyout icon set. The screenshots confirm it works, so there must be another code path that sets it (possibly during the view controller's ViewDidAppear/ViewWillAppear lifecycle). This is acceptable, but worth a comment explaining that pageContainer gets its flyout icon via the normal view lifecycle.

Optional improvement:

if (index == 0)
{
    // Clear flyout icon from old root (it's no longer the root).
    // New root (pageContainer) gets its flyout icon via ViewWillAppear lifecycle.
    (target as ParentingViewController)?.UpdateLeftBarButtonItem();
}

---

2. firstPage change in UpdateLeftBarButtonItem is broader than InsertPageBefore

File: NavigationRenderer.cs:1659
Change:

// Before:
var firstPage = n.NavPageController.Pages.FirstOrDefault();

// After:
var firstPage = (n.ViewControllers.FirstOrDefault() as ParentingViewController)?.Child;

This change affects all callers of UpdateLeftBarButtonItem, not just the InsertPageBefore path. The fix is logically correct (native ViewControllers is the source of truth), but it's a broader behavioral change than the PR description implies. The PR description says this is intentional (the Pages collection wasn't kept in sync), which is accurate. Worth noting in case this changes behavior in other navigation scenarios.

3. Non-nested helper classes in HostApp test file

File: TestCases.HostApp/Issues/Issue29921.cs
Issue29921Page1 and Issue29921Page2 are declared as public top-level classes in the namespace. This is the common pattern used elsewhere in this project, so it's acceptable. However, having them public means they could theoretically conflict with other issue pages if names ever collide.

---

Looks Good

• Null safety: (target as ParentingViewController)?.UpdateLeftBarButtonItem() safely handles the case where target is not a ParentingViewController.
• Null safety: (n.ViewControllers.FirstOrDefault() as ParentingViewController)?.Child safely handles empty ViewControllers collection.
• Test coverage: UI test added with VerifyScreenshot() and snapshots for all 4 platforms.
• Test structure: Follows established _IssuesUITest pattern with correct [Category(UITestCategories.FlyoutPage)].
• Minimal fix: The change is only the necessary lines are modified.surgical
• Root cause fix: The UpdateLeftBarButtonItem change addresses the underlying issue (stale Pages collection) rather than just working around it.

---

[kubaflo]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 3 pipeline(s).

[kubaflo]

@Vignesh-SF3580 can you update the iOS snapshot please?

[Vignesh-SF3580]

@Vignesh-SF3580 can you update the iOS snapshot please?

@kubaflo This PR includes the iOS snapshot, and there are no major concerns from the agent review.

[kubaflo]

@Vignesh-SF3580 cool! Thanks!