[Mac] Fix Prevent CollectionView scroll position reset on Mac Catalyst after Picker interaction

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

Root Cause

On Mac Catalyst, certain window state changes (opening/dismissing a Picker, minimizing/restoring, or resizing the window) cause UIKit to silently adjust the UICollectionView contentOffset when the view is programmatically scrolled near or to the last item.

During these transitions, UIKit recalculates scroll bounds using estimated item sizes (NSCollectionLayoutDimension.CreateEstimated(30f)). Because the estimated contentSize is smaller than the actual contentSize, UIKit calculates a lower maximum valid contentOffset and silently clamps the current offset down to that value. The scroll position does not always jump to the very top — it shifts to whatever UIKit calculates as the maximum valid offset: max(0, estimatedContentSize - frameHeight). No delegate, layout, or view controller callbacks fire — the change happens entirely inside UIKit's property mutation machinery.

Why items near the bottom are affected: Items near the bottom require a larger offset than UIKit's estimated bounds permit. Intermediate items sit within the estimated range and are unaffected.

Why only Mac Catalyst: The same window transitions on iOS do not trigger this recalculation behavior.

Why conventional fixes fail: Standard callbacks (LayoutSubviews, ViewDidLayoutSubviews, Scrolled) are not triggered because this is not a layout pass or a user scroll. KVO on contentOffset is the only mechanism that fires synchronously at the moment UIKit mutates the property.

Description of Change

KVO-Based Scroll Restore

The fix uses NSObject.AddObserver("contentOffset", ...) (Key-Value Observing) to detect the silent reset and restore the scroll position.

Flow:

1. After a non-animated ScrollTo, SetPendingScrollRestore(section, item, position) is called, storing the target index path as plain int fields and enabling tracking.
2. KVO OnContentOffsetChanged monitors every contentOffset change:
   • While the new Y is within 10px of the last known Y: treat as normal movement, update reference.
   • If Y drops more than 10px below the last known Y: silent reset detected → async-dispatches ScrollToItem to restore position.
3. DraggingStarted clears the restore target when the user manually scrolls (respects user intent).
4. KVO lifecycle is managed in MovedToWindow — started when view attaches, stopped when it detaches.

Why relative threshold (not Y < 1.0): UIKit does not always reset to Y=0. It clamps to max(0, estimatedContentSize - frameHeight), which can be a non-zero value. A fixed Y < 1.0 check would miss non-zero resets entirely. Comparing against the last known Y detects any sudden downward shift regardless of the absolute value.

Why plain int storage (not NSIndexPath): NSIndexPath is created inside a using block in ScrollToRequested and is disposed before the KVO callback fires. Storing section and item as int fields avoids this lifetime issue.

Why ScrollToItem instead of SetContentOffset: ScrollToItem recalculates the pixel offset using UIKit's current layout (including actual item heights), yielding the exact visual position. SetContentOffset uses a raw pixel value that becomes stale after layout changes.

Issues Fixed

Fixes #34271

Files Changed

File	Change
src/Controls/src/Core/Handlers/Items/iOS/MauiCollectionView.cs	KVO observer infrastructure, scroll restore state, SetPendingScrollRestore, ClearPendingScrollRestore, MovedToWindow lifecycle
src/Controls/src/Core/Handlers/Items2/ItemsViewHandler2.iOS.cs	Call SetPendingScrollRestore after non-animated ScrollToItem; capture section/item as ints inside using block
src/Controls/src/Core/Handlers/Items2/iOS/ItemsViewDelegator2.cs	DraggingStarted override to clear restore target on user drag
src/Controls/src/Core/PublicAPI/net-maccatalyst/PublicAPI.Unshipped.txt	New public override: ItemsViewDelegator2.DraggingStarted

Total: fix spans 4 production files

Screenshots

Before Issue Fix	After Issue Fix
34271BeforeFix.mov	34271AfterFix.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 -- 34356

Or

• Run remotely in PowerShell:

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

[Copilot]

Pull request overview

Fixes a Mac Catalyst-specific CollectionView scroll position jump that can occur after programmatic scrolling near the end of the list and then interacting with window/UI state (e.g., dismissing a Picker). The change introduces a KVO-based mechanism on contentOffset to detect UIKit’s silent clamp/reset and restore the intended scroll position.

Changes:

• Add a Mac Catalyst-only KVO observer in MauiCollectionView to detect silent contentOffset drops and re-ScrollToItem the pending target.
• Arm/clear the pending “restore target” from ItemsViewHandler2 (after non-animated ScrollTo) and ItemsViewDelegator2 (on user drag).
• Add a HostApp repro page and an Appium UITest for issue #34271, plus a PublicAPI entry for the new Mac Catalyst override.

Reviewed changes

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

Show a summary per file

File	Description
src/Controls/src/Core/Handlers/Items/iOS/MauiCollectionView.cs	Adds Mac Catalyst-only KVO observer + pending scroll restore state and lifecycle wiring in MovedToWindow.
src/Controls/src/Core/Handlers/Items2/ItemsViewHandler2.iOS.cs	Captures index path parts and arms pending restore after non-animated ScrollToItem (Mac Catalyst-only).
src/Controls/src/Core/Handlers/Items2/iOS/ItemsViewDelegator2.cs	Clears pending restore on DraggingStarted (Mac Catalyst-only).
src/Controls/src/Core/PublicAPI/net-maccatalyst/PublicAPI.Unshipped.txt	Declares the new Mac Catalyst public override API surface.
src/Controls/tests/TestCases.HostApp/Issues/Issue34271.cs	Adds a repro page with a CollectionView + Picker interaction flow.
src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue34271.cs	Adds an Appium UI test verifying scroll position remains stable after picker dismiss.

[kubaflo]

Could you please review the ai's summary?

[Vignesh-SF3580]

Could you please review the ai's summary?

@kubaflo Based on the AI summary, I have addressed the valid concerns.

• Added a note clarifying that scroll restore tracking applies only to vertical offset changes, and horizontal CollectionView layouts are not covered.
• Added a guard at the start of the async closure to ensure the native view is still valid and attached to a window before performing scroll restoration, preventing potential crashes on detached or disposed views.
• Added a helper method to validate that the pending section and item indices are within the current data source bounds before restoring scroll position, preventing native inconsistencies if the data source changes after scheduling.

[kubaflo]

Could you please review the ai's summary?

[Vignesh-SF3580]

Could you please review the ai's summary?

@kubaflo The AI summary suggested an alternative fix. I tried implementing it, but it did not resolve the reported issue. Therefore, no changes were made to the existing PR.

[kubaflo]

🔍 AI-generated — automated conflict resolution & adversarial review by GitHub Copilot CLI, on behalf of @kubaflo. Please verify before merging.

Conflicts resolved & rebased onto current inflight/current

This branch had diverged badly from inflight/current (a ~1074-file diff caused by inflight/current's frequent rebases dragging in unrelated WebView/Shell/Carousel history). I merged the current tip and collapsed it back down to the real fix — 7 files:

• MauiCollectionView.cs, ItemsViewHandler2.iOS.cs, CarouselViewDelegator2.cs, ItemsViewDelegator2.cs
• PublicAPI.Unshipped.txt (net‑maccatalyst), Issue34271 HostApp + shared tests

Noise conflicts (WebView Android, Shell, Directory.Build.targets, eng/Versions.props, net‑android/net‑windows PublicAPI) were taken from inflight/current.

● Fixed a merge‑breaking issue

• MauiScrollView.OnOrientationChanged() was duplicated after the merge (inflight/current already defines it; the branch re‑added an identical copy) → CS0111 duplicate‑member compile error. Removed the redundant copy (the method is unchanged and unused by this PR).

ℹ Adversarial review notes (for the author — not blocking the merge mechanics)

• PublicAPI parity verified correct: MauiCollectionView.Dispose(bool) and ItemsViewDelegator2.DraggingStarted are inside #if MACCATALYST, so they belong only in net‑maccatalyst (not net‑ios). ✓
• Animated scroll path: the restore appears armed only for !args.IsAnimated (ItemsViewHandler2.iOS.cs). The picker/window‑clamp reset isn't animation‑specific — please confirm ScrollTo(..., animate: true) is also covered.
• Test coverage: Issue34271 opens/closes the Picker but doesn't hover/change the ScrollToPosition selection the way the original repro does; consider strengthening it. It also pulls images over the network — a fixed HeightRequest would make it hermetic.

Lifecycle cleanup (observer stopped on detach/dispose, base.Dispose called) looks correct, and the core behavior is correctly Mac Catalyst‑gated with no iOS regression.

[kubaflo]

Could you please create a new PR with the necessary files?

[Vignesh-SF3580]

Could you please create a new PR with the necessary files?

@kubaflo Created a new PR with the necessary files.#36431