[iOS] Fix gap at top of view after rotating device while Entry keyboard is visible

[praveenkumarkarunanithi]

Root Cause

When the keyboard appears on iOS, MAUI’s keyboard auto-scroll manager records the container view’s position (the “starting origin”) so that it can restore the view to the same position when the keyboard is dismissed. This works correctly during normal keyboard interactions.
However, if the device is rotated while the keyboard is visible, iOS transforms the container view into landscape coordinates before the keyboardWillHide notification is fired. By the time MAUI’s restore logic runs, the container view has already been laid out using landscape dimensions, while the saved origin still corresponds to the portrait orientation. As a result, MAUI animates the view back to this stale portrait Y-coordinate, which is incorrect for the current layout and creates a visible gap between the navigation bar and the page content.

Description of Change

The fix records the container view’s size at the time the keyboard appears, in addition to the existing origin value. When the keyboard is about to be dismissed, the restore logic compares the current container size with the recorded size.
If the sizes differ, it indicates that the device orientation changed while the keyboard was visible. In this case, the restore animation is skipped entirely, allowing iOS to maintain the correct layout for the new orientation.
If the sizes match, the restore animation proceeds as before, ensuring that the existing behavior remains unchanged for normal keyboard interactions.

Issues Fixed

Fixes #33407

Tested the behaviour in the following platforms

• Android
• Windows
• iOS
• Mac

Output Video

Before Issue Fix	After Issue Fix
Beforefix1.mov	Afterfix.24.mov

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

Or

• Run remotely in PowerShell:

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

[Copilot]

Pull request overview

Fixes an iOS keyboard auto-scroll restoration regression where rotating the device while the keyboard is visible can restore the container view to a stale (pre-rotation) origin, leaving a visible gap at the top of the page.

Changes:

• Record the container view size when the keyboard first appears and skip restore animation when the container size changes before keyboard dismissal (rotation detected).
• Add a new HostApp issue page (Issue33407) to reproduce the scenario via UI navigation and focused Entry.
• Add a new Appium-based UI test plus iOS/Android snapshot baselines to validate the layout after rotation + keyboard dismissal.

Reviewed changes

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

Show a summary per file

File	Description
src/Core/src/Platform/iOS/KeyboardAutoManagerScroll.cs	Tracks container size at keyboard-show time and conditionally skips restore animation when size changes (rotation).
src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue33407.cs	New UI test that navigates, focuses Entry, rotates, dismisses keyboard, and verifies screenshot.
src/Controls/tests/TestCases.HostApp/Issues/Issue33407.cs	New HostApp repro Shell + pages for Issue33407 navigation and Entry focus scenario.
src/Controls/tests/TestCases.iOS.Tests/snapshots/ios/EntryFocusedShouldNotCauseGapAfterRotation.png	Adds iOS baseline screenshot for the new UI test.
src/Controls/tests/TestCases.Android.Tests/snapshots/android/EntryFocusedShouldNotCauseGapAfterRotation.png	Adds Android baseline screenshot for the new UI test.

[Copilot]

Thread.Sleep(2000) introduces an arbitrary delay and will also fail to compile unless System.Threading is imported (implicit global usings don’t include Thread). Prefer using the screenshot retry mechanisms (e.g., VerifyScreenshot with a retry timeout) and/or an awaited delay with an async test if you truly need to wait for rotation/keyboard animations to settle.

[Copilot]

The page content/instructions appear to be copied from the Entry “IsPassword” manual test and don’t describe (or visually emphasize) the rotation-gap scenario this issue/test is meant to validate. Consider updating the labels/instructions to reflect the gap-at-top repro/expected behavior so the HostApp page is self-explanatory and the screenshot assertion is easier to interpret during future regressions.

Suggested change

	Text = "1. In the Entry control below, input some text. The test passes if the text is not obscured."
	},
	new UITestEntry
	{
	IsPassword = false,
	IsCursorVisible = false,
	Placeholder = "IsPassword=False",
	AutomationId = "Entry1"
	},
	new Label
	{
	Text = "2. In the Entry control below, input some text. The test passes if the text is obscured."
	},
	new UITestEntry
	{
	IsPassword = true,
	IsCursorVisible = false,
	Placeholder = "IsPassword=True",
	Text = "1. Rotate the device between portrait and landscape with the keyboard hidden. The test passes if no extra gap appears at the top of the page above the entries."
	},
	new UITestEntry
	{
	IsPassword = false,
	IsCursorVisible = false,
	Placeholder = "Top gap check (normal entry)",
	AutomationId = "Entry1"
	},
	new Label
	{
	Text = "2. Tap into each Entry, then rotate the device again. The test passes if no additional top gap appears and both entries remain aligned directly under this text."
	},
	new UITestEntry
	{
	IsPassword = true,
	IsCursorVisible = false,
	Placeholder = "Top gap check (password entry)",

[Copilot]

This test dismisses the keyboard right before taking the screenshot, but the regression is about incorrect restoration during keyboardWillHide after an orientation change. To ensure the test is actually exercising the buggy path, consider explicitly waiting for the keyboard-dismiss/restore animation to complete (instead of relying on timing) before asserting the screenshot, otherwise the screenshot could be taken mid-transition and become flaky.

[kubaflo]

🤖 AI Summary

📊 Expand Full Review

---

🔍 Pre-Flight — Context & Validation

---

📝 Review Session — Address review feedback: fix test flakiness and update HostApp instructions · 8d17a6d

---

Issue: #33407 - Focusing and entering texts on entry control causes a gap at the top after rotating simulator.
PR: #34328 - [iOS] Fix gap at top of view after rotating device while Entry keyboard is visible
Platforms Affected: iOS only (regression since 9.0.120, not reproducible on 9.0.111)
Labels: platform/ios, area-keyboard, partner/syncfusion, i/regression, s/agent-reviewed, s/agent-suggestions-implemented
Author: praveenkumarkarunanithi

Issue Summary

When a user focuses an Entry control on iOS and then rotates the device while the keyboard is visible, a visible gap appears between the navigation bar and the page content. This is an iOS-only regression introduced in v9.0.120.

Root Cause (per PR description): KeyboardAutoManagerScroll records the container view's origin (TopViewBeginOrigin) when the keyboard appears. When the device rotates while the keyboard is visible, iOS transforms the container view into landscape coordinates before keyboardWillHide fires. RestorePosition() then animates the view back to the stale portrait Y-coordinate, creating a visible gap.

Prior Review Context

This PR had a prior agent review at commit 17f3a22. The previous recommendation was REQUEST CHANGES due to:

1. Thread.Sleep(2000) in test (prohibited by project conventions)
2. HostApp page had wrong instructions (copy-pasted from IsPassword test)
3. Missing mandatory NOTE block in PR description

The label s/agent-suggestions-implemented indicates the author addressed review feedback. Current commit 8d17a6d5 addresses items 1 and 2 but the NOTE block status needs verification.

Files Changed

Fix Files:

• src/Core/src/Platform/iOS/KeyboardAutoManagerScroll.cs (+21, -4) - Core platform fix (UNCHANGED since previous Gate pass)

Test Files:

• src/Controls/tests/TestCases.HostApp/Issues/Issue33407.cs (+151) - HostApp repro page (updated instructions)
• src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue33407.cs (+44) - UI test (Thread.Sleep → retryTimeout)
• src/Controls/tests/TestCases.iOS.Tests/snapshots/ios/EntryFocusedShouldNotCauseGapAfterRotation.png - Baseline
• src/Controls/tests/TestCases.iOS.Tests/snapshots/ios-26/EntryFocusedShouldNotCauseGapAfterRotation.png - Baseline
• src/Controls/tests/TestCases.Android.Tests/snapshots/android/EntryFocusedShouldNotCauseGapAfterRotation.png - Android baseline

Test Type: UI Tests (Appium/NUnit) - #if IOS || ANDROID guard

Changes Since Previous Gate Pass

Only test/HostApp files changed since Gate passed at 17f3a22:

• HostApp updated instructions (cosmetic)
• Test replaced Thread.Sleep(2000) with VerifyScreenshot(retryTimeout: TimeSpan.FromSeconds(2)) ✅

The fix file KeyboardAutoManagerScroll.cs was NOT modified.

Reviewer Comments

From Copilot automated review (all now addressed or outdated):

Comment	Status
Thread.Sleep(2000) should use retryTimeout	✅ ADDRESSED - now uses VerifyScreenshot(retryTimeout: TimeSpan.FromSeconds(2))
HostApp instructions copied from IsPassword test	✅ ADDRESSED - updated descriptions
Screenshot timing concern after keyboard dismiss	✅ ADDRESSED - retryTimeout handles this

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
PR	PR #34328	Record TopViewBeginContainerSize at keyboard-show; in RestorePosition() skip restore animation if container size changed by >1pt (orientation detection)	✅ PASS (Gate - iOS, prev review)	KeyboardAutoManagerScroll.cs (+21/-4)	Original PR fix; validated in prior review

---

🚦 Gate — Test Verification

---

📝 Review Session — Address review feedback: fix test flakiness and update HostApp instructions · 8d17a6d

---

Result: ⚠️ INCONCLUSIVE (Android) / ✅ PASSED (iOS, prior review)
Platform: android (attempted), ios (prior review at unchanged commit)
Mode: Full Verification (RequireFullVerification: true)

Android Gate: ⚠️ BLOCKED (Environment Issue)

Android test run failed due to Android emulator ANR ("System UI isn't responding" dialog), which is a CI infrastructure issue unrelated to the PR code. The emulator's System UI crashed, preventing the gallery from loading, causing a navigation timeout.

• Tests FAIL without fix on Android: ✅ (but due to emulator ANR, not the fix)
• Tests FAIL with fix on Android: ✅ (same emulator ANR)
• Root cause: System UI isn't responding ANR dialog blocking gallery navigation

This is NOT a code issue - it's a known Android CI emulator environment instability.

iOS Gate: ✅ PASSED (Prior Review, Commit Unchanged)

The fix file src/Core/src/Platform/iOS/KeyboardAutoManagerScroll.cs is unchanged since the prior iOS Gate verification at commit 17f3a22:

• Tests FAIL without fix ✅
• Tests PASS with fix ✅
• Validated with: RequireFullVerification: true

Since the fix code is unchanged and only test files were modified since the iOS Gate, the iOS Gate validation remains valid.

Test Filter: Issue33407
Base Branch: main
Fix Files Validated (iOS):

• src/Core/src/Platform/iOS/KeyboardAutoManagerScroll.cs

---

🔧 Fix — Analysis & Comparison

---

📝 Review Session — Address review feedback: fix test flakiness and update HostApp instructions · 8d17a6d

---

Fix Exploration: SKIPPED (Environment Blocked)

Reason for skip: Try-fix requires running tests to validate alternatives. Both available paths are blocked:

1. Android: Emulator ANR ("System UI isn't responding") prevents app navigation
2. iOS: Not available on current Linux host

Prior Review Fix Candidates (10 attempts from commit 17f3a22)

The prior review at the unchanged fix commit explored 10 independent alternatives:

#	Source	Approach	Test Result	Files Changed	Notes
1	try-fix	Subscribe to UIDeviceOrientationDidChangeNotification; reset TopViewBeginOrigin = InvalidPoint when orientation changes	✅ PASS	KeyboardAutoManagerScroll.cs (+17)	Adds new observer lifecycle
2	try-fix	Save UIInterfaceOrientation at keyboard-show; compare in WillHideKeyboard, invalidate origin if changed	✅ PASS	KeyboardAutoManagerScroll.cs (+18)	Uses WindowScene.InterfaceOrientation (iOS 13+)
3	try-fix	Clamp restored Y to superview bounds origin	❌ FAIL	KeyboardAutoManagerScroll.cs	Visual diff 5-7%; animation conflicts with UIKit rotation
4	try-fix	Refresh TopViewBeginOrigin on second WillKeyboardShow during rotation	❌ FAIL	KeyboardAutoManagerScroll.cs	Timing issue — rotation fires before new layout settles
5	try-fix	Track Window.Bounds.Size at keyboard-show; skip restore if window size changed	✅ PASS	KeyboardAutoManagerScroll.cs (+9/-4)	Similar pattern to PR but uses window size
6	try-fix	Track applied delta (Y shift from keyboard); undo that delta from current Y instead of absolute portrait restore	✅ PASS	KeyboardAutoManagerScroll.cs (+15/-8)	Rotation-agnostic
7	try-fix	Record ContainerView.SafeAreaInsets at keyboard-show; skip restore if insets changed	✅ PASS	KeyboardAutoManagerScroll.cs (+6)	⚠️ Early return skips ScrolledView cleanup — latent bug
8	try-fix	Use CGAffineTransform translation deltas; reset to identity on hide	✅ PASS	KeyboardAutoManagerScroll.cs (+9/-19)	Restructures AnimateRootView; more invasive
9	try-fix	Compare live container frame size vs superview bounds size in RestorePosition — no saved state needed	✅ PASS	KeyboardAutoManagerScroll.cs (+12/-4)	Relies on timing assumption about iOS internals
10	try-fix	Check ContainerView.Layer.AnimationKeys in RestorePosition; cancel + skip if animations in flight	✅ PASS	KeyboardAutoManagerScroll.cs (+13/-3)	Relies on Core Animation timing — potentially fragile
PR	PR #34328	Record TopViewBeginContainerSize at keyboard-show; in RestorePosition skip if size differs by >1pt	✅ PASS (Gate)	KeyboardAutoManagerScroll.cs (+21/-4)	Clear, explicit, well-documented, minimal deps

Exhausted: Yes (via prior review)
Selected Fix: PR's fix — simplest, most explicit, no timing dependencies, no latent bugs, proper cleanup

---

📋 Report — Final Recommendation

---

📝 Review Session — Address review feedback: fix test flakiness and update HostApp instructions · 8d17a6d

---

⚠️ Final Recommendation: REQUEST CHANGES

Summary

PR #34328 fixes a real iOS regression (#33407) where rotating the device while the keyboard is visible causes a gap at the top of the page. The core fix in KeyboardAutoManagerScroll.cs is correct, Gate-validated on iOS, and confirmed by 10 independent fix explorations from the prior review. The author has addressed prior review feedback (Thread.Sleep → retryTimeout, HostApp instructions updated). One required item remains: the mandatory NOTE block is still missing from the PR description.

---

Root Cause

KeyboardAutoManagerScroll saves TopViewBeginOrigin (the container view's CGPoint) when the keyboard appears. When the device rotates while the keyboard is visible, iOS updates the container view layout to landscape coordinates before UIKeyboardWillHideNotification fires. By the time RestorePosition() runs, the stale portrait Y-origin no longer corresponds to a valid position in the new orientation, causing the view to animate to an incorrect Y and leaving a visible gap above the page content.

---

Fix Quality: ✅ Correct and Well-Chosen

The PR's approach — recording TopViewBeginContainerSize at keyboard-show and skipping the restore animation when the container size changes — is the simplest, most explicit, and most defensive of all alternatives explored.

8 of 10 independent try-fix alternatives (from prior review) also passed, validating the fix direction. The PR's approach was selected because:

• No timing dependencies on UIKit internals
• No invasive signature changes
• No latent bugs (unlike alternative [Spec] TabView #7 which has an early return that skips ScrolledView cleanup)
• Minimal footprint with proper cleanup (= CGSize.Empty at end of RestorePosition)

---

Title & Description Review

Title: [iOS] Fix gap at top of view after rotating device while Entry keyboard is visible — ✅ Accurate, descriptive

Description:

• ✅ Root Cause section: clear and accurate
• ✅ Description of Change: accurately describes the size-comparison approach
• ✅ Issues Fixed: Fixes #33407 ✅
• ✅ Platform checkboxes present
• ❌ Missing mandatory NOTE block — must be prepended per repo conventions

---

Code Review Findings

🔴 Required Change: Missing NOTE Block

File: PR Description

The mandatory NOTE block is missing from the top of the PR description. This is required for all PRs per repository conventions:

<!-- Please let the below note in for people that find this PR -->
> [!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](https://github.com/dotnet/maui/wiki/Testing-PR-Builds) from this PR and let us know in a comment if this change resolves your issue. Thank you!

✅ Implementation Looks Good

• TopViewBeginContainerSize field added alongside TopViewBeginOrigin — consistent pattern
• CGSize.Empty used for initialization and cleanup — correct sentinel value
• 1pt tolerance guard for sub-pixel float drift — well-reasoned and documented
• Comment clearly explains the rotation detection logic
• Cleanup at end of RestorePosition() is correct (resets to CGSize.Empty)

✅ Tests Improved

• Thread.Sleep(2000) replaced with VerifyScreenshot(retryTimeout: TimeSpan.FromSeconds(2)) ✅
• HostApp instructions updated to describe the gap-at-top scenario ✅
• DismissKeyboard() before screenshot avoids cursor flakiness ✅

---

Required Changes

1. Add NOTE block to the top of the PR description (before the existing "### Root Cause" section)

That's the only remaining required change. Once added, the PR is ready to approve.

---

📋 Expand PR Finalization Review

---

Title: ✅ Good

Current: [iOS] Fix gap at top of view after rotating device while Entry keyboard is visible

Description: ✅ Excellent

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!

Root Cause

When the keyboard appears on iOS, MAUI's keyboard auto-scroll manager records the container view's position (the "starting origin") so that it can restore the view to the same position when the keyboard is dismissed. This works correctly during normal keyboard interactions.
However, if the device is rotated while the keyboard is visible, iOS transforms the container view into landscape coordinates before the keyboardWillHide notification is fired. By the time MAUI's restore logic runs, the container view has already been laid out using landscape dimensions, while the saved origin still corresponds to the portrait orientation. As a result, MAUI animates the view back to this stale portrait Y-coordinate, which is incorrect for the current layout and creates a visible gap between the navigation bar and the page content.

Description of Change

The fix records the container view's size at the time the keyboard appears, in addition to the existing origin value. When the keyboard is about to be dismissed, the restore logic compares the current container size with the recorded size.
If the sizes differ, it indicates that the device orientation changed while the keyboard was visible. In this case, the restore animation is skipped entirely, allowing iOS to maintain the correct layout for the new orientation.
If the sizes match, the restore animation proceeds as before, ensuring that the existing behavior remains unchanged for normal keyboard interactions.

Issues Fixed

Fixes #33407

Tested the behaviour in the following platforms

• Android
• Windows
• iOS
• Mac

Output Video

Before Issue Fix	After Issue Fix

Code Review: ⚠️ Issues Found

Code Review — PR #34328

✅ Looks Good

• Core fix is correct and minimal. KeyboardAutoManagerScroll.cs adds a single CGSize sentinel field that is recorded when the keyboard appears and compared on dismiss. The change is surgical and does not alter any existing code paths when no orientation change occurs.
• Normal-case preservation. The if (!sizeChanged) guard ensures the existing restore animation is executed unchanged when orientation has not changed, avoiding any regression risk for the common path.
• Proper reset/cleanup. TopViewBeginContainerSize is reset to CGSize.Empty in RestorePosition()'s cleanup block alongside the other static state fields, preventing stale state across keyboard appearances.
• Clear comments. Inline comments in RestorePosition() explain the rationale (stale portrait origin in landscape space) and the reasoning behind the 1pt tolerance, making future maintenance straightforward.
• Test follows best practices. Uses UITestEntry (cursor-visible = false) to prevent flaky screenshot comparisons due to cursor blink. Uses VerifyScreenshot(retryTimeout: TimeSpan.FromSeconds(2)) instead of Task.Delay(). Has TearDown to reset orientation.
• Snapshot baselines included. Both ios and ios-26 environment snapshots are committed.

---

🟡 Suggestions (Low Priority)

1. SizeChangeTolerance should use nfloat or double instead of float

File: src/Core/src/Platform/iOS/KeyboardAutoManagerScroll.cs

const float SizeChangeTolerance = 1.0f;
var sizeChanged = TopViewBeginContainerSize != CGSize.Empty
    && (Math.Abs(currentSize.Width - TopViewBeginContainerSize.Width) > SizeChangeTolerance
        || Math.Abs(currentSize.Height - TopViewBeginContainerSize.Height) > SizeChangeTolerance);

CGSize properties (Width, Height) are nfloat (which is double on 64-bit). The subtraction produces a nfloat, and comparing it against float SizeChangeTolerance involves an implicit widening conversion. This is not a bug — the value 1.0f round-trips to 1.0 as double exactly — but using nfloat or double would be more consistent with the surrounding CoreGraphics API surface and avoids an implicit cast:

const double SizeChangeTolerance = 1.0;

Impact: None (no behavioral difference). Pure style/consistency.

---

2. HostApp test page navigation is deeper than necessary

File: src/Controls/tests/TestCases.HostApp/Issues/Issue33407.cs

The automated test navigates through three levels of pages (Issue33407 Shell → Issue33407CategoriesPage → Issue33407EntryListPage → Issue33407E1Page) before reaching the entries being tested. The intermediate category/list pages exist to support potential expansion, but currently there is only one test item (E1).

This makes the test more fragile (more taps required, more navigation state to manage) and the HostApp page more complex than required for the single scenario.

A simpler structure — a flat Shell with a single ContentPage containing the two UITestEntry controls — would be equally effective for the automated test. The more complex structure does have value for manual testing because it better mimics real-world navigation depth (where this bug would be encountered), so it's a trade-off.

Impact: Test reliability (minor). The current structure works and is already committed with snapshot baselines; not a blocking concern.

---

3. [Issue] attribute specifies PlatformAffected.iOS but test compiles for Android

File: src/Controls/tests/TestCases.HostApp/Issues/Issue33407.cs (line 19) and src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue33407.cs (line 1 #if IOS || ANDROID)

[Issue(IssueTracker.Github, 33407, "...", PlatformAffected.iOS)]
public class Issue33407 : Shell

The [Issue] attribute declares the platform as iOS-only, but the UI test compiles for Android too (via #if IOS || ANDROID). The Android snapshot (EntryFocusedShouldNotCauseGapAfterRotation.png) is committed, confirming Android runs the test. Including Android is fine — it validates that Android doesn't regress — but the PlatformAffected.iOS attribute creates a slight inconsistency.

PlatformAffected.iOS | PlatformAffected.Android would be more accurate, or leave it as PlatformAffected.iOS (the bug only affects iOS) and add a brief comment explaining why the test also runs on Android.

Impact: None (purely informational metadata). Not a blocking concern.

---

🔴 Critical Issues

None.

---