From 3b302ad7411c54a515292d99c379018327840eb2 Mon Sep 17 00:00:00 2001
From: hechang27-sprt <hechang27@outlook.com>
Date: Tue, 7 Apr 2026 09:05:21 +0800
Subject: [PATCH] docs(frontend): add Vue 3 template ref auto-unwrap gotchas

Add common mistakes section for:
- Vue 3 refs nested in objects not auto-unwrapped in templates
- Virtual scrolling overscan behavior with small datasets

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../spec/frontend/component-guidelines.md     | 39 +++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/.trellis/spec/frontend/component-guidelines.md b/.trellis/spec/frontend/component-guidelines.md
index c9daf77..afec38f 100644
--- a/.trellis/spec/frontend/component-guidelines.md
+++ b/.trellis/spec/frontend/component-guidelines.md
@@ -157,6 +157,45 @@ Element Plus `el-table` (v1) and `el-table-v2` (virtualized) have completely dif
 
 When using new Element Plus components, verify required props - they will cause runtime errors if omitted.
 
+### 4. Vue 3 Template Ref Auto-Unwrap Gotchas
+
+Vue 3 `<script setup>` auto-unwraps refs in templates, but with important limitations:
+
+**Works - Top-level refs:**
+```typescript
+const count = ref(0);
+// Template: {{ count }} ✓ (auto-unwrapped)
+```
+
+**Broken - Refs nested in objects:**
+```typescript
+const virtualizer = useVirtualRows(...);
+// Template: {{ virtualizer.visibleRows }} ✗ (NOT auto-unwrapped)
+```
+
+**Fixed - Destructure refs for template use:**
+```typescript
+const virtualizer = useVirtualRows(...);
+const { visibleRows, totalHeight } = virtualizer;
+// Template: {{ visibleRows }} ✓ (auto-unwrapped top-level ref)
+```
+
+**TypeScript also fails** when refs are nested in objects - TypeScript sees `virtualizer.visibleRows` as type `ComputedRef | true | VirtualRow[]` instead of `VirtualRow[]`.
+
+**Rule**: Always destructure refs from composable return objects when they will be used directly in templates.
+
+### 5. Virtual Scrolling Overscan with Small Datasets
+
+Virtual scrolling with `overscan` may render ALL rows even when scrolled if:
+- Total row heights < viewport height + (overscan × average row height)
+- Dataset is small (e.g., 10 rows with 60px each = 600px total)
+
+With overscan=5 and 10 rows (600px total) and viewport 300px:
+- Overscan renders rows -5 to +5 from viewport edge
+- This covers all 10 rows regardless of scroll position
+
+This is NOT a bug - it's expected behavior. Virtual scrolling only culls rows when the dataset exceeds viewport + overscan capacity.
+
 ---
 
 ## Accessibility