Fix inconsistent Grouped CollectionView (GridItemsLayout) rendering on Windows and iOS/macOS

[Shalini-Ashokan]

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 Details

Grouped  CollectionView  with  GridItemsLayout  (Span > 1,  VerticalItemSpacing  set) renders inconsistently across platforms. On Windows, the first item in the first group renders smaller than others. On iOS/macOS, no spacing appears between the group header and the first row of items.

Root Cause

Windows: The generated item container style didn't stretch content vertically, so the first grid cell (whose row height differs due to the header) collapsed to its content size instead of filling the row.

iOS/macOS: The grid layout path ( CreateGridLayout -equivalent) never set  InterSectionSpacing / ContentInsets  for the header-to-item gap — that logic only existed in the list layout path, not the grid layout path.

Description of Change

Windows: Added  VerticalContentAlignmentProperty = VerticalAlignment.Stretch  to the item container style in  StructuredItemsViewHandler.Windows.cs , ensuring all grid cells stretch uniformly to fill their row instead of the first item sizing to content.

iOS/macOS: Extracted the header/footer boundary-spacing logic into a shared  ApplyHeaderFooterBoundarySpacing  helper in  LayoutFactory2.cs , and invoked it from the grid layout as well (previously only the list layout applied it). Also set  layoutConfiguration.InterSectionSpacing  using the main-axis spacing so consistent gaps appear between the header and first row across grouped sections.

Validated the behavior in the following platforms

• Android
• Windows
• iOS
• Mac

Issues Fixed

Fixes #36545

Output ScreenShot

Windows

Before	After

iOS

Before	After

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

[dotnet-policy-service]

Hey there @@Shalini-Ashokan! Thank you so much for your PR! Someone from the team will get assigned to your PR shortly and we'll get it reviewed.

[vishnumenon2684]

/azp run maui-pr-uitests

[azure-pipelines]

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

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

Or

• Run remotely in PowerShell:

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

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

[Copilot]

Pull request overview

Fixes a grouped CollectionView + GridItemsLayout rendering inconsistency by aligning layout spacing/measurement behavior across Windows and iOS/macOS handlers.

Changes:

• Windows: Ensure GridViewItem content stretches vertically so the first item in a grouped grid row doesn’t collapse to content size.
• iOS/macOS: Apply header/footer boundary spacing logic to the grid compositional layout path (and set InterSectionSpacing) so grouped headers get the expected gap before the first row.

Reviewed changes

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

File	Description
src/Controls/src/Core/Handlers/Items2/iOS/LayoutFactory2.cs	Extracts and reuses header/footer boundary spacing logic; adds inter-section spacing for grouped grid layouts.
src/Controls/src/Core/Handlers/Items/StructuredItemsViewHandler.Windows.cs	Adds vertical content stretching to the grid item container style to keep item sizing consistent in grouped grids.

[MauiBot]

Expert Review — 1 findings

See inline comments for details.

[MauiBot]

Expert Review — 1 findings

See inline comments for details.

[MauiBot]

🔍 AI-Generated Review (multi-model)

[major] CollectionView iOS/MacCatalyst — This makes non-grouped grid layouts add item spacing between a global Header/Footer and the items. When IsGrouped is false but Header or Footer is set, hasHeader/hasFooter comes from headerFooterInfo, and the call below applies ContentInsets whenever VerticalItemSpacing/HorizontalItemSpacing is non-zero. That changes ordinary grid header/footer spacing even though the new boundary spacing is for grouped section headers/footers; e.g., a vertical grid with Header and VerticalItemSpacing=12 now gets an extra 12pt gap before the first row. Gate this spacing to groupingInfo.IsGrouped (or otherwise separate global header/footer behavior) so non-grouped grids keep their existing layout.

[Copilot]

Pull request overview

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

[kubaflo]

Could you please update snapshot?

[MauiBot]

AI Review Summary

@Shalini-Ashokan — new AI review results are available based on this last commit: bbfa36e. To request a fresh review after new comments or commits, comment /review rerun.

---

🗂️ Review Sessions — click to expand

🚦 Gate — Test Before & After Fix

Gate Result: ⚠️ INCONCLUSIVE

Platform: WINDOWS · Base: main · Merge base: a96cb62b

📷 New snapshot test — no baseline yet — the test calls VerifyScreenshot but its baseline image is not committed (brand-new snapshot tests get their baseline added separately). The gate cannot validate a snapshot with nothing to compare against, so this is inconclusive, not a fix failure. Download the snapshots-diff artifact, confirm the rendering, and commit the baseline PNG.

Test	Without Fix (expect FAIL)	With Fix (expect PASS)
🖥️ Issue35700 Issue35700	📷 NEW SNAPSHOT (no baseline)	📷 NEW SNAPSHOT (no baseline)

🔴 Without fix — 🖥️ Issue35700: ⚠️ ENV ERROR · 445s

Error-relevant lines (filtered from the build log):

     at VisualTestUtils.VisualRegressionTester.Fail(String message) in /_/src/TestUtils/src/VisualTestUtils/VisualRegressionTester.cs:line 162
   at VisualTestUtils.VisualRegressionTester.VerifyMatchesSnapshot(String name, ImageSnapshot actualImage, String environmentName, ITestContext testContext) in /_/src/TestUtils/src/VisualTestUtils/VisualRegressionTester.cs:line 84
   at Microsoft.Maui.TestCases.Tests.UITest.<VerifyScreenshot>g__Verify|13_0(String name, <>c__DisplayClass13_0&) in /_/src/Controls/tests/TestCases.Shared.Tests/UITest.cs:line 477
   at Microsoft.Maui.TestCases.Tests.UITest.VerifyScreenshot(String name, Nullable`1 retryDelay, Nullable`1 retryTimeout, Int32 cropLeft, Int32 cropRight, Int32 cropTop, Int32 cropBottom, Double tolerance, Boolean includeTitleBar) in /_/src/Controls/tests/TestCases.Shared.Tests/UITest.cs:line 309
   at Microsoft.Maui.TestCases.Tests.Issues.Issue35700.GroupedCollectionViewGridLayoutRendersCorrectly() in /_/src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue35700.cs:line 18
   at System.Reflection.MethodBaseInvoker.InterpretedInvoke_Method(Object obj, IntPtr* args)
   at System.Reflection.MethodBaseInvoker.InvokeWithNoArgs(Object obj, BindingFlags invokeAttr)

🟢 With fix — 🖥️ Issue35700: ⚠️ ENV ERROR · 443s

Error-relevant lines (filtered from the build log):

     at VisualTestUtils.VisualRegressionTester.Fail(String message) in /_/src/TestUtils/src/VisualTestUtils/VisualRegressionTester.cs:line 162
   at VisualTestUtils.VisualRegressionTester.VerifyMatchesSnapshot(String name, ImageSnapshot actualImage, String environmentName, ITestContext testContext) in /_/src/TestUtils/src/VisualTestUtils/VisualRegressionTester.cs:line 84
   at Microsoft.Maui.TestCases.Tests.UITest.<VerifyScreenshot>g__Verify|13_0(String name, <>c__DisplayClass13_0&) in /_/src/Controls/tests/TestCases.Shared.Tests/UITest.cs:line 477
   at Microsoft.Maui.TestCases.Tests.UITest.VerifyScreenshot(String name, Nullable`1 retryDelay, Nullable`1 retryTimeout, Int32 cropLeft, Int32 cropRight, Int32 cropTop, Int32 cropBottom, Double tolerance, Boolean includeTitleBar) in /_/src/Controls/tests/TestCases.Shared.Tests/UITest.cs:line 309
   at Microsoft.Maui.TestCases.Tests.Issues.Issue35700.GroupedCollectionViewGridLayoutRendersCorrectly() in /_/src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue35700.cs:line 18
   at System.Reflection.MethodBaseInvoker.InterpretedInvoke_Method(Object obj, IntPtr* args)
   at System.Reflection.MethodBaseInvoker.InvokeWithNoArgs(Object obj, BindingFlags invokeAttr)

⚠️ Failure Details

• ⚠️ Issue35700 without fix: New snapshot test — baseline image not yet created; the gate cannot validate a brand-new VerifyScreenshot test (the baseline PNG is added separately by a maintainer)
• ⚠️ Issue35700 with fix: New snapshot test — baseline image not yet created; the gate cannot validate a brand-new VerifyScreenshot test (the baseline PNG is added separately by a maintainer)

📁 Fix files reverted (2 files)

• src/Controls/src/Core/Handlers/Items/StructuredItemsViewHandler.Windows.cs
• src/Controls/src/Core/Handlers/Items2/iOS/LayoutFactory2.cs

---

📱 UI Tests — CollectionView

Detected UI test categories: CollectionView

❌ Deep UI tests — 323 passed, 1 failed across 1 category on platform-pool agent (replaces in-process counts above). 1 new snapshot test need a baseline PNG (added separately by a maintainer — not a regression).

🧪 UI Test Execution Results (deep, platform pool)

Category	Tests	Snapshot diffs
CollectionView	323/336 (1 ❌, 1 ⚠ new baseline)	2 diff PNGs

❌ CollectionView — 1 failed test

VerifyDefaultScrollToRequested

VisualTestUtils.VisualTestFailedException : 
Snapshot different than baseline: VerifyDefaultScrollToRequested.png (0.52% difference)
If the correct baseline has changed (this isn't a a bug), then update the baseline image.
See test attachment or download the build artifacts to get the new snapshot file.

More info: https://aka.ms/visual-test-workflow
at VisualTestUtils.VisualRegressionTester.Fail(String message) in /_/src/TestUtils/src/VisualTestUtils/VisualRegressionTester.cs:line 162
   at VisualTestUtils.VisualRegressionTester.VerifyMatchesSnapshot(String name, ImageSnapshot actualImage, String environmentName, ITestContext testContext) in /_/src/TestUtils/src/VisualTestUtils/VisualRegressionTester.cs:line 123
   at Microsoft.Maui.TestCases.Tests.UITest.<VerifyScreenshot>g__Verify|13_0(String name, <>c__DisplayClass13_0&) in /_/src/Controls/tests/TestCases.Shared.Tests/UITest.cs:line 477
   at Microsoft.Maui.TestCases.Tests.UITest.VerifyScreenshot(String name, Nullable`1 ret
...

⚠️ CollectionView — 1 new snapshot test need a baseline PNG

These tests call VerifyScreenshot but their baseline image isn't committed yet (brand-new snapshot tests get their baseline added separately by a maintainer). There's nothing to compare against, so this is not a regression — download the drop-deep-uitests artifact, confirm the rendering, and commit the baseline PNG.

• GroupedCollectionViewGridLayoutRendersCorrectly

🔍 AI analysis of failures — PR-related vs unrelated

🔍 AI-generated triage (GitHub Copilot CLI) — a heuristic judgement of whether each deep UI test failure is connected to this PR's changes. Verify before relying on it.

Mixed / uncertain: see the grouped assessment below.

• ✗ PR-related — New grouped CollectionView grid screenshot baseline on Windows (~1 test): GroupedCollectionViewGridLayoutRendersCorrectly is a new UI test added by this PR and failed because the Windows baseline snapshot was not added, while the PR also changes Windows CollectionView grid item container alignment.
• ℹ Uncertain — Existing CollectionView scroll screenshot on Windows (~1 test): VerifyDefaultScrollToRequested exercises the same Windows CollectionView handler area touched by the PR, but the small 0.52% visual diff could also be ordinary snapshot drift without the image artifact.

Strongest signal: one failure is directly from a new PR-added screenshot test missing its Windows baseline; inspect the VerifyDefaultScrollToRequested diff artifact to decide whether the new vertical stretch alignment changed existing CollectionView rendering.

📎 Download drop-deep-uitests artifact (TRX + snapshot diffs)

---

📋 Pre-Flight — Context & Validation

Issue: #36545 - [windows, iOS & macOS]Grouped CollectionView with GridItemsLayout renders inconsistent layout across platforms
PR: #36561 - Fix inconsistent Grouped CollectionView (GridItemsLayout) rendering on Windows and iOS/macOS
Platforms Affected: Windows, iOS, MacCatalyst
Files Changed: 2 implementation, 2 test

Key Findings

• PR fixes Windows grouped grid item sizing by setting VerticalContentAlignment=Stretch on GridViewItem containers.
• PR fixes iOS/MacCatalyst grouped grid header/item spacing by applying grouped-only compositional layout section insets and inter-section spacing to grid layouts.
• Prior AI review flagged non-grouped iOS grid header/footer spacing; current code addresses it by gating spacing on groupingInfo.IsGrouped && mainAxisSpacing > 0.
• New UI test metadata still says Android/#35700 although the fixed issue is #36545 for Windows/iOS/macOS.

Code Review Summary

Verdict: NEEDS_DISCUSSION
Confidence: low
Errors: 0 | Warnings: 1 | Suggestions: 2

Key code review findings:

• Warning src/Controls/tests/TestCases.HostApp/Issues/Issue35700.cs:6-8, src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue35700.cs:11: UI test metadata targets the wrong issue/platform.
• Suggestion src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue35700.cs:18: screenshot test should use retry timeout.
• Suggestion src/Controls/tests/TestCases.HostApp/Issues/Issue35700.cs:19: horizontal grouped grid path remains untested.

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
PR	PR #36561	Windows: stretch grid item container vertically. iOS/MacCatalyst: share header/footer boundary spacing helper and call it for grouped grids.	⚠️ INCONCLUSIVE (Gate)	StructuredItemsViewHandler.Windows.cs, LayoutFactory2.cs, UI tests	Original PR; gate build/run previously inconclusive.

---

🔬 Code Review — Deep Analysis

Code Review — PR #36561

Independent Assessment

What this changes: Fixes grouped CollectionView grid rendering: Windows grid cells stretch vertically; iOS/MacCatalyst grouped grid layouts now apply section/header spacing.
Inferred motivation: Make grouped GridItemsLayout spacing/sizing consistent across Windows, iOS, and MacCatalyst.

Reconciliation with PR Narrative

Author claims: Windows cell sizing plus iOS/macOS grouped header spacing fix for #36545.
Agreement/disagreement: Code matches the claimed implementation. Test metadata still references Android/#35700, which conflicts with this PR’s actual fixed issue/platforms.

Prior Review Reconciliation

Prior Error Finding	Source	Status	Evidence
Non-grouped iOS grid layouts could receive new header/footer spacing	MauiBot/Copilot inline comments	Fixed / obsolete	Current code gates spacing with groupingInfo.IsGrouped && mainAxisSpacing > 0 at LayoutFactory2.cs:258.

Blast Radius Assessment

• Runs for all instances: Windows change affects all Windows grid CollectionView item containers; iOS change affects grouped grid layouts with spacing.
• Startup impact: No.
• Static/shared state: No.

CI Status

• Required-check result: undetermined via required-check command; gh pr checks --required failed because gh is unauthenticated.
• Classification: Public check-runs for head bbfa36e show maui-pr success; required-check status still not verifiable here.
• Action taken: Capped confidence; no LGTM due undetermined required-check surface.

Findings

Warning — New UI test metadata targets the wrong issue/platform

src/Controls/tests/TestCases.HostApp/Issues/Issue35700.cs:6-8 and src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue35700.cs:11

The PR fixes #36545 for Windows/iOS/macOS, but the new test page and test description reference Android/#35700. This makes triage and platform intent misleading. Consider renaming/updating metadata to the fixed issue and affected platforms.

Suggestion — Screenshot test should use retry timeout

src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue35700.cs:18

WaitForElement only proves the CollectionView exists, not that grouped cells have fully rendered. Prefer VerifyScreenshot(retryTimeout: TimeSpan.FromSeconds(2)).

Suggestion — Horizontal grouped grid path remains untested

src/Controls/tests/TestCases.HostApp/Issues/Issue35700.cs:19

The new iOS helper handles horizontal and vertical grouped grids, but the test only exercises vertical layout.

Failure-Mode Probing

• Non-grouped iOS grid with header/footer: no new inset, because spacing is gated by groupingInfo.IsGrouped.
• Handler disconnect/reconnect: no new subscriptions/resources.
• Null/default spacing: zero spacing short-circuits safely.

Verdict: NEEDS_DISCUSSION

Confidence: low
Summary: Core handler changes look sound, and prior major spacing concern appears fixed. I would discuss/fix the misleading test metadata before merge; CI required-check status could not be verified with gh here.

---

🛠️ Fix — Analysis & Comparison

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
1	maui-expert-reviewer	Grouped Grid Slot Normalization	FAIL	StructuredItemsViewHandler.Windows.cs	Uses FrameworkElement.VerticalAlignment on grouped multi-span GridViewItem containers; failed before test due missing/outdated build tasks.
2	maui-expert-reviewer	Grouped Grid Inner Spacing	BLOCKED	StructuredItemsViewHandler.Windows.cs	Moves grouped multi-span item spacing from Margin to Padding; blocked by Windows HostApp build stall after build-task recovery.
3	maui-expert-reviewer	Remeasure Windows Item After Realization	BLOCKED	ItemContentControl.cs	Invalidates measure after content realization; blocked by same Windows HostApp build stall and has broader blast radius.
PR	PR #36561	Windows: stretch GridViewItem content vertically; iOS/MacCatalyst: grouped-only section boundary insets + inter-section spacing for grouped grids.	INCONCLUSIVE (Gate)	StructuredItemsViewHandler.Windows.cs, LayoutFactory2.cs, UI tests	Original PR; gate was previously inconclusive and was not rerun.

Cross-Pollination

Model	Round	New Ideas?	Details
gpt-5.5 / maui-expert-reviewer	1	Yes	Candidate 1: grouped grid slot normalization via container VerticalAlignment.
gpt-5.5 / maui-expert-reviewer	2	Yes	Candidate 2: grouped grid spacing geometry via inner padding.
gpt-5.5 / maui-expert-reviewer	3	Yes	Candidate 3: stale item-host measurement revalidation after realization.
gpt-5.5 / maui-expert-reviewer	4	No	Remaining variations collapse into the PR's direct content-alignment fix or broaden blast radius without testable evidence.

Exhausted: Yes
Selected Fix: PR's fix — It is the most direct Windows fix among reviewed approaches, keeps iOS/MacCatalyst spacing scoped to grouped grids after prior review feedback, and avoids candidate 2/3's broader behavioral risks. No alternative candidate passed tests or was demonstrably better because local Windows HostApp testing was blocked by build environment stalls.

Test Environment Notes

• Gate verification was not rerun, per instruction.
• Candidate tests used the Windows-targeted command: pwsh .github\scripts\BuildAndRunHostApp.ps1 -Platform windows -TestFilter "FullyQualifiedName~Issue35700".
• Candidate 1 failed before test execution with Maui.InTree.targets reporting required MSBuild tasks were not built/out of date.
• One recovery attempt was made with dotnet build Microsoft.Maui.BuildTasks.slnf; it exceeded the useful retry window and was stopped.
• Candidates 2 and 3 progressed past the initial build-task error but stalled during the Windows HostApp dotnet build; both were stopped and marked blocked.

---

🏁 Report — Final Recommendation

Comparative Report — PR #36561

Candidate ranking

Rank	Candidate	Regression result	Assessment
1	pr-plus-reviewer	Inconclusive / unverified	Best candidate. Keeps the PR's localized Windows and iOS/MacCatalyst fixes and applies safe reviewer feedback for test metadata, screenshot reliability, and minor iOS cleanup.
2	pr	Inconclusive / unverified	Core fix is sound and complete for the reported Windows + iOS/MacCatalyst behavior, but leaves misleading test metadata and a flaky screenshot risk.
3	try-fix-2	Blocked	Windows-only alternative that changes grouped grid spacing geometry by moving margin into padding. Higher visual/selection/hit-test risk and does not address iOS/MacCatalyst.
4	try-fix-3	Blocked	Broader Windows item-host measurement invalidation. Higher blast radius across all Windows item realization paths and does not address iOS/MacCatalyst.
5	try-fix-1	Fail	Windows-only container-slot alignment alternative. It failed before useful test execution and does not address iOS/MacCatalyst; ranked below inconclusive/blocked candidates per the failed-result rule.

Comparative analysis

The submitted PR fix is the strongest technical baseline. On Windows, setting VerticalContentAlignment=Stretch on the grid item container targets the content-presenter sizing issue directly without rethreading grouped state or changing spacing geometry. On iOS/MacCatalyst, moving the existing header/footer boundary-spacing logic into a shared helper and invoking it for grouped grid layouts closes the list-vs-grid behavior gap while keeping non-grouped grids unaffected.

pr-plus-reviewer improves that baseline without changing the behavioral model. Correcting the UI test issue number, description, and affected platforms makes the regression test discoverable and prevents platform filtering/triage confusion. Adding a screenshot retry reduces flake risk. Simplifying the grid helper variables removes dead fallback logic created by the grouped-only spacing gate.

The try-fix candidates are weaker. try-fix-1 and try-fix-2 only address the Windows side and leave the iOS/MacCatalyst root cause unresolved. try-fix-2 also changes margin/padding semantics, which can affect selection visuals and hit testing. try-fix-3 has the broadest blast radius because it invalidates measurement for all Windows item hosts after realization, not just grouped grids.

Winner

Winner: pr-plus-reviewer

Rationale: It combines the PR's sound, localized cross-platform implementation with safe expert-review improvements. No try-fix candidate passed regression verification or provided a complete Windows+iOS/MacCatalyst replacement, and the only candidate marked failed is ranked below the non-failing candidates.

---

🧭 Next Steps — review latest findings

No alternative fix was selected for this run. Review the session findings and CI results before merging.

[MauiBot]

Expert Review — 4 findings

See inline comments for details.

[MauiBot]

🔍 AI-Generated Review (multi-model)

[moderate] Regression Prevention and Test Coverage — The issue metadata does not match this PR: it references GitHub issue 35700, an Android description, and PlatformAffected.Android, while the fix targets issue #36545 in Windows and iOS/MacCatalyst CollectionView handlers. This makes future blame/triage and platform filtering misleading. Please update the issue number, description, affected platforms, and the matching shared test Issue string.

[MauiBot]

🔍 AI-Generated Review (multi-model)

[minor] Complexity Reduction — hasHeader/hasFooter fall back to headerFooterInfo when not grouped, but ApplyHeaderFooterBoundarySpacing is gated by groupingInfo.IsGrouped && mainAxisSpacing > 0, so the ungrouped branch can never affect behavior. Consider simplifying to groupingInfo.HasHeader / groupingInfo.HasFooter to match the list layout path, unless ungrouped header/footer spacing is intentionally being added.

[MauiBot]

🔍 AI-Generated Review (multi-model)

[minor] Regression Prevention and Test Coverage — The test only covers vertical grouped GridItemsLayout, but the iOS/MacCatalyst layout change handles both vertical and horizontal scroll directions. Consider adding horizontal grouped-grid coverage so the leading/trailing inset path is also protected.

[MauiBot]

🔍 AI-Generated Review (multi-model)

[minor] Regression Prevention and Test Coverage — VerifyScreenshot() runs without a retryTimeout. Since this test validates subtle layout/spacing differences, using the retry-based screenshot helper would make it less sensitive to late layout passes.