noob-components/.trellis/spec/frontend/quality-guidelines.md

Quality Guidelines

Code quality standards for frontend development.

---

Overview

(To be filled by the team)

---

Forbidden Patterns

(To be filled by the team)

---

Required Patterns

(To be filled by the team)

---

Testing Requirements

(To be filled by the team)

---

Development Workflow

Package Changes Testing

When making changes to packages/ directory and testing with examples/:

1. Vite dev server auto-reloads: The dev server (bun run dev) automatically reloads changes in packages/ when you access the example pages
2. Verify changes took effect: Modify DEV_MODE_TS in packages/manage/router/index.vue - this string is displayed at .el-menu .menu-footer (bottom of sidebar menu). Changing it forces the app to refresh.
3. Build before finishing: Run bun run build:lib to ensure the library builds correctly with your changes

// In packages/manage/router/index.vue - change this string to force refresh
const DEV_MODE_TS = "2026-03-26T03:50:00.000Z";  // Update timestamp to force reload

Quick Test Cycle

# 1. Make changes to packages/
# 2. Dev server auto-reloads when accessing example pages
# 3. Modify DEV_MODE_TS in packages/manage/router/index.vue if changes don't appear
# 4. Run build when done to verify
bun run build:lib

Browser Automation with agent-browser

When using agent-browser for testing:

DO: Use CSS selectors with wait instead of fixed timeouts

# Good - waits for element to appear
agent-browser wait ".el-table-v2__row" && agent-browser snapshot

# Bad - arbitrary timeout, may be too short or waste time
agent-browser wait 3000

DO: Check console for errors after page interaction

agent-browser click "@e1" && agent-browser console

DO: Navigate with hash routes properly

# Hash-based SPA routes need explicit navigation
agent-browser navigate http://localhost:5173/#/table-v2

Common wait patterns:

• agent-browser wait --load networkidle - for page navigation
• agent-browser wait ".my-selector" - for element appearance
• agent-browser wait --url "**/pattern" - for URL changes

---

Common Mistakes / Gotchas

el-table-v2 probe row timing

When using a probe row to dynamically measure row height for el-table-v2's virtual scrolling:

Problem: Using a single requestAnimationFrame causes inconsistent row heights (first 3 rows taller than rest).

Cause: el-table-v2's virtual scroller calculates positions based on estimatedRowHeight, but a single frame isn't enough for it to fully settle.

Solution: Use TWO requestAnimationFrame calls before measuring:

await nextTick();
await new Promise(resolve => requestAnimationFrame(resolve));  // Frame 1
await new Promise(resolve => requestAnimationFrame(resolve));  // Frame 2 - el-table-v2 now settled
const height = probeRowRef.value?.offsetHeight;

Verification: All rows should have identical heights and consistent spacing.

---

Code Review Checklist

(To be filled by the team)