From 70ccc7ac80644c95212d71728d9813994c35e285 Mon Sep 17 00:00:00 2001
From: hechang27-sprt <hechang27@outlook.com>
Date: Fri, 3 Apr 2026 19:05:51 +0800
Subject: [PATCH] chore: record journal

---
 .../VIRTUAL-SCROLLING-DEBUG.md                | 95 +++++++++++++++++++
 .trellis/workspace/hechang27-sprt/index.md    |  5 +-
 .../workspace/hechang27-sprt/journal-1.md     | 30 ++++++
 3 files changed, 128 insertions(+), 2 deletions(-)
 create mode 100644 .trellis/tasks/04-03-list-table-v2-tanstack-pretext/VIRTUAL-SCROLLING-DEBUG.md

diff --git a/.trellis/tasks/04-03-list-table-v2-tanstack-pretext/VIRTUAL-SCROLLING-DEBUG.md b/.trellis/tasks/04-03-list-table-v2-tanstack-pretext/VIRTUAL-SCROLLING-DEBUG.md
new file mode 100644
index 0000000..4950ded
--- /dev/null
+++ b/.trellis/tasks/04-03-list-table-v2-tanstack-pretext/VIRTUAL-SCROLLING-DEBUG.md
@@ -0,0 +1,95 @@
+# Virtual Scrolling Debug Notes
+
+## Date: 2026-04-03
+
+## Issue: Virtual Scrolling Not Updating on Scroll
+
+### Symptoms
+- Rows weren't shifting when scrolling programmatically
+- Debug info showed correct scrollTop but rows stayed the same
+- Force re-render (classList toggle) fixed it momentarily
+
+### Root Causes Found
+
+#### 1. Vue Template Ref Auto-Unwrapping
+**Problem**: `virtualizer.visibleRows` is a `ComputedRef` inside an object. Vue 3 auto-unwraps top-level refs in templates, but NOT refs nested inside objects.
+
+**Evidence**:
+```
+TypeScript error: Property 'index' does not exist on type 'true | ComputedRefImpl<any> | VirtualRow[]'
+```
+
+**Fix**: Destructure the needed values from `virtualizer`:
+```typescript
+const { visibleRows, totalHeight: virtualTotalHeight, onScroll } = virtualizer;
+```
+
+#### 2. Vue 3 Template `.value` Usage
+**Problem**: In Vue 3 `<script setup>`, refs are auto-unwrapped in templates. Using `.value` explicitly on refs returned from a hook (inside an object) causes type inference issues.
+
+**Before (broken)**:
+```vue
+<div v-for="row in virtualizer.visibleRows.value">
+```
+
+**After (working)**:
+```vue
+<div v-for="row in visibleRows">
+```
+
+#### 3. Overscan + Small Dataset
+**Problem**: With 10 rows (each ~60px = 600px total) and viewport 306px, overscan=5 means all 10 rows are rendered regardless of scroll position.
+
+**Calculation**:
+- Viewport shows ~5 rows
+- Overscan 5 = render rows -5 to +5 from viewport edge
+- 5 + 5 + visible rows = all 10 rows always visible
+
+**Not a bug** - virtual scrolling only benefits when rows > viewport + overscan.
+
+### Key Code Changes
+
+#### list-table-v2.vue
+```typescript
+// Before: all refs nested in object
+const virtualizer = useVirtualRows(...);
+
+// After: destructure for template auto-unwrap
+const { visibleRows, totalHeight: virtualTotalHeight, onScroll } = virtualizer;
+```
+
+#### useVirtualRows.ts
+```typescript
+// Added safety guard for invalid indices
+const visibleRows = computed<VirtualRow[]>(() => {
+  if (startIndex < 0 || endIndex < startIndex) {
+    return [];
+  }
+  // ... rest of computation
+});
+```
+
+### Debug Techniques Used
+
+1. **Force re-render**: `table.classList.add('x'); requestAnimationFrame(() => table.classList.remove('x'))`
+   - If rows change after force-re-render, reactivity IS working but scroll event isn't triggering updates
+
+2. **Check virtualizer state**: Debug info showed `Visible Rows: 10` and `Total Rows: 10` - all rows were intentionally rendered
+
+3. **Calculate expected behavior**:
+   - viewport = 306px
+   - total content = 660px (10 rows)
+   - max scroll = 354px
+   - overscan = 5 on each side
+
+### Lessons Learned
+
+1. In Vue 3 `<script setup>`, always destructure refs that need to be used in templates
+2. Virtual scrolling benefit is only visible when `total_rows > viewport + (overscan * row_height)`
+3. Vue 3 auto-unwraps top-level refs but NOT refs nested in objects
+4. `console.log` in Vue event handlers doesn't appear in browser console - Vue intercepts events
+5. Programmatic scroll (`scrollTop = x`) doesn't fire scroll events - need to manually dispatch
+
+### Files Modified
+- `packages/base/data/list-table-v2/list-table-v2.vue`
+- `packages/base/data/list-table-v2/useVirtualRows.ts`
diff --git a/.trellis/workspace/hechang27-sprt/index.md b/.trellis/workspace/hechang27-sprt/index.md
index 5a4dd9a..5d1158d 100644
--- a/.trellis/workspace/hechang27-sprt/index.md
+++ b/.trellis/workspace/hechang27-sprt/index.md
@@ -8,7 +8,7 @@
 
 <!-- @@@auto:current-status -->
 - **Active File**: `journal-1.md`
-- **Total Sessions**: 15
+- **Total Sessions**: 16
 - **Last Active**: 2026-04-03
 <!-- @@@/auto:current-status -->
 
@@ -19,7 +19,7 @@
 <!-- @@@auto:active-documents -->
 | File | Lines | Status |
 |------|-------|--------|
-| `journal-1.md` | ~659 | Active |
+| `journal-1.md` | ~689 | Active |
 <!-- @@@/auto:active-documents -->
 
 ---
@@ -29,6 +29,7 @@
 <!-- @@@auto:session-history -->
 | # | Date | Title | Commits |
 |---|------|-------|---------|
+| 16 | 2026-04-03 | Debug list-table-v2 virtual scrolling issues | - |
 | 15 | 2026-04-03 | Rebuild list-table-v2: Scaffold hooks and types | `0f72b83`, `87000d8` |
 | 14 | 2026-04-02 | Fix list-table-v2 fixed column cropping and horizontal scroll | - |
 | 13 | 2026-04-02 | Attempt Pretext row height estimation for el-table-v2 | stashed |
diff --git a/.trellis/workspace/hechang27-sprt/journal-1.md b/.trellis/workspace/hechang27-sprt/journal-1.md
index 7c484ac..2c625f5 100644
--- a/.trellis/workspace/hechang27-sprt/journal-1.md
+++ b/.trellis/workspace/hechang27-sprt/journal-1.md
@@ -657,3 +657,33 @@ packages/base/data/list-table-v2/
 ### Next Steps
 
 - None - task complete
+
+
+## Session 16: Debug list-table-v2 virtual scrolling issues
+
+**Date**: 2026-04-03
+**Task**: Debug list-table-v2 virtual scrolling issues
+
+### Summary
+
+Fixed Vue 3 template ref auto-unwrap issue by destructuring visibleRows from virtualizer. Discovered that overscan=5 with small datasets (10 rows) means all rows render regardless of scroll - not a bug. Text wrapping, height constraint, and TypeScript errors also fixed.
+
+### Main Changes
+
+
+
+### Git Commits
+
+(No commits - planning session)
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete