Issue: #28656 - CollectionView CollectionViewHandler2 does not change ItemsLayout on DataTrigger
PR: #28675 - [iOS] CV2 ItemsLayout update
Author: kubaflo (Jakub Florkowski) - Community contribution
Platforms Affected: iOS only
Labels: platform/ios, area-controls-collectionview, collectionview-cv2, community ✨

Issue Summary

When using CollectionViewHandler2 (CV2) on iOS, changing the ItemsLayout property via a DataTrigger or data binding has no effect. The CollectionView stays in its original layout. This is a regression/gap specific to CollectionViewHandler2 - the old handler handled this correctly.

Root Cause (documented, not analyzed)

The ItemsLayoutProperty was missing from the PropertyMapper in CollectionViewHandler2.iOS.cs. Without a mapper entry, property change notifications are never dispatched to MapItemsLayout, so the platform layout never updates.

Files Changed

Fix files (1):

• src/Controls/src/Core/Handlers/Items2/CollectionViewHandler2.iOS.cs (+1 line, 0 deleted)

Test files (3):

• src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue28656.cs (new - UI test)
• src/Controls/tests/TestCases.HostApp/Issues/Issue28656.xaml (new - XAML host page)
• src/Controls/tests/TestCases.HostApp/Issues/Issue28656.xaml.cs (new - code-behind + ViewModel)

Snapshot files (4):

• Android, iOS, Mac, WinUI snapshots (binary PNG files)

PR Discussion

Notable Context

• PR Refactor ItemsLayout handling: dynamic default + virtual view-managed subscriptions #29638 (supersedes this PR per PureWeen) was closed without merging. Title: "Refactor ItemsLayout handling: dynamic default + virtual view-managed subscriptions"
• PR Refactor ItemsLayout handling: dynamic default + virtual view-managed subscriptions v2 #29683 (v2 of same refactor) is still open and also claims to fix CollectionView CollectionViewHandler2 doesnt change ItemsLayout on DataTrigger #28656 among other issues
• PR Refactor ItemsLayout handling: dynamic default + virtual view-managed subscriptions v2 #29683 is a significantly more complex refactor addressing memory leaks and multiple related issues

Fix Candidates

Result: ⚠️ BLOCKED (Environment Issue)
Platform: ios
Mode: Full Verification

Environment Blocker Explanation

The test CollectionViewShouldChangeItemsLayout uses VerifyScreenshot() and fails with a 2.24% visual difference from the committed baseline snapshot.

Root cause of environment blocker:

• Local machine runs macOS 26 (Liquid Glass)
• CI (where baseline snapshots were captured) runs macOS 14/15
• macOS 26 Liquid Glass renders controls differently from macOS 14/15
• This creates a visual difference unrelated to the functional fix

Evidence that fix files are correct:

• The skill correctly identified fix files: src/Controls/src/Core/Handlers/Items2/CollectionViewHandler2.iOS.cs
• Tests DO fail when the fix is reverted (confirming the mapping entry is the functional fix)
• Failure with fix is 2.24% snapshot diff, NOT a functional/assertion failure

Decision: Treating as environment blocker. Proceeding with code review-based analysis for Report phase.

Fix Candidates

Exhausted: N/A (Phase 3 skipped due to environment blocker - snapshot mismatch on macOS 26 vs CI macOS 14/15)
Selected Fix: PR's fix — the single-line mapper addition is the correct minimal fix

Environment Blocker Notes

Phase 3 (try-fix) was skipped because:

• Tests fail due to 2.24% snapshot diff (macOS 26 Liquid Glass vs macOS 14/15 CI rendering differences)
• This would cause ALL try-fix attempts to appear to fail regardless of fix correctness
• Code review analysis confirms the PR's fix is correct and minimal

✅ Final Recommendation: APPROVE (with suggested improvements)

Summary

PR #28675 fixes a missing property mapper entry in CollectionViewHandler2.iOS.cs that caused ItemsLayout changes to be silently ignored on iOS when using CollectionViewHandler2 (CV2). The fix is a single-line addition that is correct, minimal, and well-targeted. The PR also adds UI tests and snapshot baselines.

Note on Gate: Gate verification was blocked by an environment issue (snapshot comparison fails due to macOS 26 Liquid Glass vs CI's macOS 14/15 rendering differences), not a functional failure. The fix files were correctly identified and tests confirmed they detect the bug (fail without fix).

Note on broader context: PureWeen referenced PR #29683 ("Refactor ItemsLayout handling v2") which also addresses this issue as part of a larger refactor. PR #29638 (the original v1 refactor) is closed. PR #29683 is still open. This PR's minimal fix may ultimately be superseded, but as a standalone fix it is correct.

Root Cause

CollectionViewHandler2.iOS.cs defines its own PropertyMapper<CollectionView, CollectionViewHandler2> (named Mapper). It explicitly lists each property that the handler responds to. The StructuredItemsView.ItemsLayoutProperty was simply absent from this mapper, so when ItemsLayout changed (via DataTrigger, binding, or direct set), no platform update occurred — the MapItemsLayout method was never called.

The fix adds the missing entry:

[StructuredItemsView.ItemsLayoutProperty.PropertyName] = MapItemsLayout,

The MapItemsLayout method (handler.UpdateLayout()) already existed — it was only missing the mapper registration.

Fix Quality Assessment

PR Finalize Review

Title: ⚠️ Needs Improvement

Current: [iOS] CV2 ItemsLayout update
Recommended: [iOS] CollectionViewHandler2: Fix missing ItemsLayout mapper entry

The current title is vague. A better title describes what was missing and what was fixed, making it searchable in git history.

Description: ❌ Needs Improvement

The current description contains only an issue link and before/after videos. It's missing:

1. ❌ Required NOTE block for users waiting on PR builds
2. ❌ Root cause description
3. ❌ Description of change

Suggested description:

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

### Root Cause

`CollectionViewHandler2.iOS.cs` defines a `PropertyMapper` that lists all properties the handler responds to. `StructuredItemsView.ItemsLayoutProperty` was absent from this mapper, so property changes (from DataTriggers, bindings, or direct sets) were silently ignored and never dispatched to `MapItemsLayout`.

### Description of Change

Adds the missing mapper entry to `CollectionViewHandler2.iOS.cs`:
```csharp
[StructuredItemsView.ItemsLayoutProperty.PropertyName] = MapItemsLayout,

The MapItemsLayout method already existed — it only needed to be registered.

Issues Fixed

Fixes #28656

---

### Code Review

#### ✅ Looks Good

- **Fix approach**: Adding the missing mapper entry is the correct and idiomatic fix in MAUI's handler architecture. All other `StructuredItemsView` properties (`HeaderTemplate`, `FooterTemplate`, `Header`, `Footer`, `ItemSizingStrategy`) are present in the mapper — `ItemsLayout` was simply missing.
- **`MapItemsLayout` implementation**: Calls `handler.UpdateLayout()` which is the correct behavior (same as `MapItemSizingStrategy`).
- **Test design**: Tests both layout-switching mechanisms (DataTrigger-based and binding-based) in a single test page.

#### 🟡 Minor Suggestions

1. **Test relies entirely on screenshot comparison** — The test clicks a button and calls `VerifyScreenshot()`. This is fragile because:
   - Screenshot snapshots must be re-captured for each OS/rendering change
   - The test doesn't verify *what* layout changed, only that something visually changed
   - Consider adding an element-count or layout-type assertion as additional validation

2. **`Items` property syntax** — The ViewModel uses collection spread syntax (`[.. Enumerable.Range(...)...]`) which requires C# 12. This is fine for the current .NET target but worth noting. The string interpolation `$"Item {i}"` is correct.

3. **XAML triggers logic is inverted** — In the XAML, when `IsGridLayout == False`, it sets a `GridItemsLayout`. This is counterintuitive (False → Grid). The binding-based CollectionView uses the ViewModel correctly. This doesn't affect the fix but may confuse readers of the test code.

4. **Missing snapshot for iOS** — The PR added snapshots for Android, Mac, and WinUI, but the iOS snapshot file (`TestCases.iOS.Tests/snapshots/ios/CollectionViewShouldChangeItemsLayout.png`) appears to be empty/not properly committed per the reviewer comment from jsuarezruiz.

#### 🔴 No Critical Issues Found

The single-line fix is correct and follows established patterns.

</details>

</details>

---

</details>
<!-- /SECTION:PR-REVIEW -->

<!-- SECTION:PR-FINALIZE -->
<details>
<summary>📋 <strong>Expand PR Finalization Review</strong></summary>

---

<details>

<summary><b>Title: ✅ Good</b></summary>

<br>

**Current:** `[iOS] CV2 ItemsLayout update`
</details>

<details>

<summary><b>Description: ⚠️ Needs Update</b></summary>

<br>

Description needs updates. See details below.
### ✨ Suggested PR Description

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

### Root Cause

`CollectionViewHandler2.iOS.cs` had a `MapItemsLayout` method that calls `UpdateLayout()`, but never registered it in the handler's property mapper dictionary. Without this registration, the handler received no notification when `ItemsLayout` changed at runtime — causing the native UICollectionView layout to remain unchanged regardless of any DataTrigger or binding update.

The legacy `CollectionViewHandler` (Items/) correctly mapped this property; the omission was specific to `CollectionViewHandler2` (Items2/).

### Description of Change

Added one line to the property mapper in `CollectionViewHandler2.iOS.cs`:

```csharp
[StructuredItemsView.ItemsLayoutProperty.PropertyName] = MapItemsLayout,

This ensures that any runtime change to ItemsLayout (via DataTrigger, XAML binding, or code-behind) triggers MapItemsLayout, which calls handler.UpdateLayout() to rebuild the native UICollectionView layout.

Tests Added

• HostApp page (Issue28656.xaml / Issue28656.xaml.cs): Two CollectionViews — one using a XAML DataTrigger to toggle between GridItemsLayout (2-column) and LinearItemsLayout, and one using a direct ViewModel binding to ItemsLayout. A button triggers the layout change.
• NUnit test (Issue28656.cs): Taps the "Change layout type" button and verifies the resulting screenshot.
• Snapshots: Added baselines for iOS, Android, Mac, and Windows.

Issues Fixed

Fixes #28656

Platforms Affected

• iOS (primary — fix is in Items2/iOS handler)
• Android (not affected — no Items2 implementation for Android)
• Windows (not affected)
• Mac Catalyst (Items2/iOS code also applies to MacCatalyst)

Code Review — PR #28675

Code Review Findings

✅ Looks Good

• Fix is minimal and surgical — A single-line addition to the property mapper dictionary is exactly the right approach. Adding [StructuredItemsView.ItemsLayoutProperty.PropertyName] = MapItemsLayout follows the established pattern used by all other properties in the same handler.

• MapItemsLayout already existed — The implementation (handler.UpdateLayout()) was already in place; it just wasn't hooked up. This is a clean fix with no new logic needed.

• Test covers two scenarios — The HostApp page reproduces both the DataTrigger scenario (the original reported issue) and a ViewModel-binding scenario, providing good coverage.

• Snapshots added for all platforms — Even though the issue is iOS-specific, snapshot baselines are correctly added for all four platforms (iOS, Android, Mac, Windows), ensuring the test can run cross-platform.

• Correct category — [Category(UITestCategories.CollectionView)] is appropriate.

🟡 Minor Suggestions

1. XAML DataTrigger condition semantics are inverted (potential confusion)

In Issue28656.xaml, the DataTrigger conditions map IsGridLayout to layouts in a counterintuitive way:

<!-- Value="False" → applies GridItemsLayout (2 columns) -->
<DataTrigger Binding="{Binding IsGridLayout}" Value="False">
    <Setter Property="ItemsLayout">
        <Setter.Value><GridItemsLayout Orientation="Vertical" Span="2"/></Setter.Value>
    </Setter>
</DataTrigger>

<!-- Value="True" → applies LinearItemsLayout -->
<DataTrigger Binding="{Binding IsGridLayout}" Value="True">
    <Setter Property="ItemsLayout">
        <Setter.Value><LinearItemsLayout Orientation="Vertical"/></Setter.Value>
    </Setter>
</DataTrigger>

When IsGridLayout = true, the trigger sets LinearItemsLayout, which is the opposite of what the name implies. This is a test code issue only (not product code), and the test still exercises the fix correctly. However, it could confuse future maintainers.

Suggestion: Rename the ViewModel property to IsLinearLayout or swap the trigger values to match the name semantics. Low-priority for a repro test.

2. Test uses App.Click instead of App.Tap

App.Click("ChangeLayoutButton");

The UI test guidelines show App.Tap() as the standard interaction method. App.Click() may also work but is less idiomatic. Low priority — functionally equivalent.

3. Missing newline at end of files

Both Issue28656.xaml.cs and Issue28656.cs have \ No newline at end of file in the diff. Minor style issue.

🔴 Critical Issues

None.

Summary

The fix itself is correct, minimal, and follows established patterns. The test code has minor naming confusion in the DataTrigger conditions (inverted semantics for IsGridLayout), but this doesn't affect the validity of the test or the fix. No changes to the core fix are recommended.