---
phase: 02-ranking-dashboard-ui
plan: 02
subsystem: ui
tags: [react, dnd-kit, trpc, ranking, drag-and-drop, sheet-panel]

# Dependency graph
requires:
  - phase: 02-01
    provides: RankingDashboard stub, saveReorder mutation, Ranking tab entry point
provides:
  - Full RankingDashboard component with drag-and-drop reorder, AI vs override visual states, and Sheet-based juror evaluation detail panel
affects: [02-03-advance-projects]

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "useRef init guard: initialized.current prevents localOrder re-init from server data on every re-render — eliminates snap-back"
    - "Fire-and-forget mutation inside setLocalOrder callback: setLocalOrder runs synchronously first, mutation fires async, no onSuccess invalidation"
    - "Double cast via unknown: Prisma JsonValue cast to RankedProjectEntry[] requires (json ?? []) as unknown as RankedProjectEntry[]"
    - "getFullDetail response shape: { project, assignments, stats } — title accessed as projectDetail.project.title"

key-files:
  created: []
  modified:
    - src/components/admin/round/ranking-dashboard.tsx

key-decisions:
  - "Double cast (as unknown as RankedProjectEntry[]) required for Prisma JsonValue — direct cast rejected by TypeScript strict mode"
  - "getFullDetail returns { project, assignments, stats } shape, not flat — project title accessed via .project.title"
  - "saveReorder mutation has no onSuccess invalidation — avoids triggering re-fetch that would reset localOrder"

patterns-established:
  - "SortableProjectRow sub-component defined above export in same file (no separate file needed for inline sub-components)"
  - "Per-category drag context: separate DndContext per category prevents cross-category drag"

requirements-completed: [DASH-01, DASH-02, DASH-03, DASH-04]

# Metrics
duration: 8min
completed: 2026-02-27
---

# Phase 2 Plan 02: Full RankingDashboard Component Summary

**Full RankingDashboard with per-category drag-and-drop (dnd-kit), AI vs override rank badges, snap-back-proof localOrder state, and lazy-loaded Sheet detail panel showing per-juror evaluation breakdown**

## Performance

- **Duration:** ~8 min
- **Started:** 2026-02-27T08:40:00Z
- **Completed:** 2026-02-27T08:48:11Z
- **Tasks:** 1
- **Files modified:** 1

## Accomplishments

- Replaced RankingDashboard stub with full 486-line implementation
- DASH-01: Ranked project list per category (STARTUP / BUSINESS_CONCEPT) with composite score, pass rate, and evaluator count displayed per row
- DASH-02: Drag-and-drop reorder via GripVertical handle using dnd-kit (DndContext + SortableContext + useSortable), fire-and-forget saveReorder mutation
- DASH-03: localOrder stored in useState with useRef guard (`initialized.current`) — init fires once on first snapshot load, never re-initialized from server data; no snap-back
- DASH-04: Sheet panel opens on row click, lazy-loads `trpc.project.getFullDetail` (enabled only when selectedProjectId is set), displays stats summary and per-juror evaluation list filtered to SUBMITTED assignments for the current round
- AI-order rows display dark-blue rank badge (#N); admin-reordered rows display amber `#N (override)` badge
- "Run Ranking" button in header card calls `triggerAutoRank`, resets `initialized.current` to allow re-init on new snapshot
- Empty categories show a placeholder message instead of an empty drag zone
- TypeScript strict mode: 0 errors; build: PASSED

## Task Commits

| Task | Name | Commit | Files |
|------|------|--------|-------|
| 1 | Build full RankingDashboard component | 6512e4e | src/components/admin/round/ranking-dashboard.tsx |

## Files Created/Modified

- `src/components/admin/round/ranking-dashboard.tsx` — Full component replacing stub (486 lines → includes SortableProjectRow sub-component + RankingDashboard main export)

## Decisions Made

- **Double cast via unknown**: `(json ?? []) as unknown as RankedProjectEntry[]` — TypeScript strict mode rejects direct cast from Prisma `JsonValue`; intermediate `unknown` is required. Matches pattern from Phase 01-03.
- **getFullDetail response shape**: The procedure returns `{ project, assignments, stats }` (not flat) — `projectDetail.project.title`, not `projectDetail.title`.
- **No onSuccess invalidation in saveReorder**: Calling `utils.ranking.getSnapshot.invalidate()` in `onSuccess` would trigger a re-fetch that resets `localOrder` to server data, causing snap-back. Mutation only shows toast on error.
- **Per-category DndContext**: Separate `DndContext` per category prevents accidental cross-category drags.

## Deviations from Plan

None — plan executed exactly as written. All type errors encountered were auto-fixed inline (Rule 1 — double cast pattern, Rule 1 — response shape).

### Auto-fixed Issues

**1. [Rule 1 - Bug] Prisma JsonValue cast requires double cast via unknown**
- **Found during:** Task 1 (typecheck)
- **Issue:** `(snapshot.startupRankingJson ?? []) as RankedProjectEntry[]` — TypeScript strict mode rejects because `JsonValue` and `RankedProjectEntry[]` don't sufficiently overlap
- **Fix:** Changed to `as unknown as RankedProjectEntry[]` (identical pattern used in Phase 01-03)
- **Files modified:** ranking-dashboard.tsx
- **Commit:** 6512e4e (same task commit)

**2. [Rule 1 - Bug] getFullDetail response shape — title not on root**
- **Found during:** Task 1 (typecheck)
- **Issue:** `projectDetail?.title` — getFullDetail returns `{ project, assignments, stats }`, not a flat object
- **Fix:** Changed to `projectDetail?.project.title`
- **Files modified:** ranking-dashboard.tsx
- **Commit:** 6512e4e (same task commit)

## Issues Encountered

None beyond the two auto-fixed type errors above.

## User Setup Required

None.

## Next Phase Readiness

- RankingDashboard fully functional — admin can view ranked projects, drag to reorder, see juror-level evaluation details in Sheet panel
- Plan 03 can now add the "Advance Projects" action button to the dashboard header
- saveReorder mutation is append-only audit log — Plan 03 can read latest reorder per category to determine final advance order
- Build and typecheck both pass with 0 errors

---
*Phase: 02-ranking-dashboard-ui*
*Completed: 2026-02-27*