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

# Quality Guidelines

> Code quality standards for frontend development.

---

## Overview

<!--
Document your project's quality standards here.

Questions to answer:
- What patterns are forbidden?
- What linting rules do you enforce?
- What are your testing requirements?
- What code review standards apply?
-->

(To be filled by the team)

---

## Forbidden Patterns

<!-- Patterns that should never be used and why -->

(To be filled by the team)

---

## Required Patterns

<!-- Patterns that must always be used -->

(To be filled by the team)

---

## Testing Requirements

<!-- What level of testing is expected -->

(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

```typescript
// 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

```bash
# 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
```bash
# 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
```bash
agent-browser click "@e1" && agent-browser console
```

**DO**: Navigate with hash routes properly
```bash
# 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:
```typescript
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

<!-- What reviewers should check -->

(To be filled by the team)