VirtualizingStackPanel - Warmup for IVirtualizedDataTemplates

VirtualizingStackPanel can handle items with (very) different heights (no scroll jumping, no layout cycles)
IVirtualizingDataTemplate implementation for ItemsControls (not only ItemContainers are re-used but also the Content)

Author: gentledepp

VARIABLE_HEIGHT_TEST.md

@@ -0,0 +1,201 @@
+# Variable Height Testing Setup
+
+## Changes Made to ComplexVirtualizationPage
+
+### Modified Files:
+1. `samples/ControlCatalog/ViewModels/ComplexVirtualizationPageViewModel.cs`
+
+### What Was Changed:
+
+#### 1. Enhanced SampleText Array (Line 162-179)
+Added 15 text samples with **extreme length variance**:
+- **Very short**: "A", "Brief.", "Short text." (1-10 characters)
+- **Short**: Single sentences (~50-60 characters)
+- **Medium**: Standard Lorem Ipsum sentences (~100-120 characters)
+- **Long**: Extended Lorem Ipsum paragraphs (~200-250 characters)
+- **Very long**: Excessive verbose sentence (~300+ characters)
+
+This creates text that will wrap from 0 lines to 5+ lines depending on container width.
+
+#### 2. Person Bio Length (Lines 33-43)
+**Old**: 0-4 sentences
+**New**: Weighted distribution 0-11 sentences:
+- 9% - No bio (0 sentences)
+- 18% - Very short (1 sentence, ~1 line)
+- 27% - Short (2-3 sentences, ~2-3 lines)
+- 18% - Medium (4-5 sentences, ~3-4 lines)
+- 18% - Long (6-8 sentences, ~5-7 lines)
+- 9% - Very long (9-11 sentences, ~8-10 lines)
+
+**Skills**: Increased from 2-7 to 2-10 skills
+
+#### 3. Task Description Length (Lines 69-78)
+**Old**: 1-5 sentences
+**New**: Weighted distribution 1-12 sentences:
+- 18% - Very short (1 sentence)
+- 27% - Short (2-3 sentences)
+- 27% - Medium (4-6 sentences)
+- 18% - Long (7-9 sentences)
+- 9% - Very long (10-12 sentences)
+
+**Subtasks**: Increased from 2-6 to 2-8 subtasks
+
+#### 4. Product Description Length (Lines 110-119)
+**Old**: 0-3 sentences (50% chance)
+**New**: Weighted distribution 0-8 sentences:
+- 11% - No description
+- 22% - Very short (1 sentence)
+- 22% - Short (2-3 sentences)
+- 22% - Medium (4-5 sentences)
+- 22% - Long (6-8 sentences)
+
+**Tags**: Increased from 1-10 to 1-12 tags
+
+#### 5. Photo Caption Length (Lines 135-144)
+**Old**: 0-4 sentences
+**New**: Weighted distribution 0-8 sentences:
+- 11% - No caption
+- 22% - Very short (1 sentence)
+- 22% - Short (2-3 sentences)
+- 22% - Medium (4-5 sentences)
+- 22% - Long (6-8 sentences)
+
+**Comments**: Increased from 1-5 to 1-7 comments
+
+---
+
+## Expected Item Height Variance
+
+With these changes, item heights will vary **dramatically**:
+
+### Minimum Heights (No text content):
+- **PersonItem**: ~150px (header + name/email + phone only)
+- **TaskItem**: ~120px (header + title + progress bar only)
+- **ProductItem**: ~100px (header + name + price only)
+- **PhotoItem**: ~120px (image + header + title + location only)
+
+### Maximum Heights (Full text content):
+- **PersonItem**: ~800px+ (long bio + 10 skills)
+- **TaskItem**: ~900px+ (very long description + 8 subtasks)
+- **ProductItem**: ~600px+ (long description + 12 tags)
+- **PhotoItem**: ~700px+ (long caption + 7 comments)
+
+### Height Ratio:
+- **Minimum to Maximum**: ~5:1 to 8:1 ratio
+- **Average height variance**: Items will randomly range from 100px to 900px
+
+---
+
+## How to Test
+
+### 1. Enable Tracing (Optional)
+In your XAML or code, enable tracing on the VirtualizingStackPanel:
+```csharp
+var stackPanel = listBox.ItemsPanelRoot as VirtualizingStackPanel;
+if (stackPanel != null)
+{
+    stackPanel.IsTracingEnabled = true;
+}
+```
+
+### 2. Run the ControlCatalog Sample
+```bash
+cd samples/ControlCatalog
+dotnet run
+```
+
+### 3. Navigate to ComplexVirtualizationPage
+In the ControlCatalog, find and click on "Content Virtualization Demo"
+
+### 4. Observe Scrolling Behavior
+
+**What to look for:**
+
+#### ✅ Good Behavior (Distance-based gap tolerance working):
+- Smooth scrolling up and down
+- No "RECYCLING ALL" messages during normal scrolling
+- Debug output shows gaps like:
+  ```
+  GapBefore=5 items (650px/605px), Disjunct=False
+  GapBefore=8 items (1040px/605px), Disjunct=True → RECYCLING (expected for large gap)
+  ```
+- Items vary wildly in height, but scrolling remains smooth
+
+#### ❌ Bad Behavior (If distance-based tolerance wasn't working):
+- Frequent "RECYCLING ALL" messages
+- Stuttering/janky scrolling
+- Gap calculations ignoring actual pixel distances:
+  ```
+  GapBefore=5 items (5000px/605px), Disjunct=False → BAD! Should recycle
+  ```
+
+### 5. Test Scenarios
+
+#### Scenario A: Slow Smooth Scrolling
+- Scroll slowly from top to bottom
+- Expected: No recycling, all gaps handled incrementally
+- Debug shows: `GapBefore/After` values staying below thresholds
+
+#### Scenario B: Fast Scrolling
+- Rapidly scroll down/up
+- Expected: Occasional recycling when gaps exceed viewport size
+- Debug shows: `Disjunct=True` only when gap distance > 605px
+
+#### Scenario C: Jump to End
+- Scroll all the way to bottom quickly
+- Expected: One "RECYCLING ALL" as viewport jumps far
+- Debug shows: Large gap distance triggering disjunct
+
+#### Scenario D: Scroll Up from End
+- At bottom, scroll slowly upward
+- Expected: No recycling until gap exceeds 605px (100% of viewport)
+- This was the original issue - now fixed!
+
+---
+
+## Debug Output Example
+
+With tracing enabled, you should see output like:
+
+```
+[VSP] CalculateMeasureViewport: Anchor=15 (u=2340.50), Realized=[10-30] (Count=21),
+      GapBefore=5 items (650px/605px), GapAfter=-15 items (-1950px/302px),
+      Disjunct=True, ViewportSize=605px
+[VSP] RECYCLING ALL - HasReachedEnd=False, HasReachedStart=False, ItemCount=5000
+
+[VSP] CalculateMeasureViewport: Anchor=42 (u=6500.00), Realized=[40-58] (Count=19),
+      GapBefore=2 items (260px/605px), GapAfter=-16 items (-2080px/302px),
+      Disjunct=False, ViewportSize=605px
+```
+
+**Key metrics to watch:**
+- **Gap pixel distance**: Should accurately reflect estimated height × item count
+- **Disjunct decision**: Should be `True` only when pixel distance exceeds thresholds
+- **ViewportSize**: Should match your window's visible area
+
+---
+
+## Verification Checklist
+
+- [ ] Items have wildly varying heights (100px to 900px range)
+- [ ] Text wraps across multiple lines in many items
+- [ ] Scrolling is smooth without excessive recycling
+- [ ] "RECYCLING ALL" only appears on large jumps
+- [ ] Debug output shows pixel-based gap calculations
+- [ ] Backward scrolling (up) tolerates larger gaps than forward scrolling
+- [ ] No layout cycle warnings during normal scrolling
+
+---
+
+## Performance Comparison
+
+### Before Distance-Based Tolerance:
+- Fixed 2-item gap tolerance
+- Small items: Frequent unnecessary recycling (e.g., 5 tiny items = 100px, incorrectly recycled)
+- Large items: Inadequate recycling (e.g., 3 huge items = 2700px, incorrectly kept)
+
+### After Distance-Based Tolerance:
+- Dynamic tolerance based on viewport size
+- Small items: Many items can be realized without recycling (gap < 605px)
+- Large items: Fewer items trigger recycling (gap > 605px)
+- Adaptive: Works perfectly regardless of item size distribution