docs(11-candidate-ranking): create phase plan
This commit is contained in:
378
.planning/phases/11-candidate-ranking/11-02-PLAN.md
Normal file
378
.planning/phases/11-candidate-ranking/11-02-PLAN.md
Normal file
@@ -0,0 +1,378 @@
|
||||
---
|
||||
phase: 11-candidate-ranking
|
||||
plan: "02"
|
||||
type: execute
|
||||
wave: 2
|
||||
depends_on: ["11-01"]
|
||||
files_modified:
|
||||
- src/client/stores/uiStore.ts
|
||||
- src/client/hooks/useCandidates.ts
|
||||
- src/client/components/CandidateListItem.tsx
|
||||
- src/client/components/CandidateCard.tsx
|
||||
- src/client/routes/threads/$threadId.tsx
|
||||
autonomous: false
|
||||
requirements: [RANK-01, RANK-02, RANK-04, RANK-05]
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "User can drag a candidate card to a new position in list view and it persists after page refresh"
|
||||
- "Top 3 candidates display gold, silver, and bronze medal badges"
|
||||
- "Rank badges appear in both list view and grid view"
|
||||
- "Drag handles are hidden and drag is disabled on resolved threads"
|
||||
- "Rank badges remain visible on resolved threads"
|
||||
- "User can toggle between list and grid view"
|
||||
- "List view is the default view"
|
||||
artifacts:
|
||||
- path: "src/client/components/CandidateListItem.tsx"
|
||||
provides: "Horizontal list-view candidate card with drag handle and rank badge"
|
||||
min_lines: 60
|
||||
- path: "src/client/routes/threads/$threadId.tsx"
|
||||
provides: "View toggle + Reorder.Group wrapping candidates + tempItems flicker prevention"
|
||||
contains: "Reorder.Group"
|
||||
- path: "src/client/hooks/useCandidates.ts"
|
||||
provides: "useReorderCandidates mutation hook"
|
||||
contains: "useReorderCandidates"
|
||||
- path: "src/client/stores/uiStore.ts"
|
||||
provides: "candidateViewMode state"
|
||||
contains: "candidateViewMode"
|
||||
- path: "src/client/components/CandidateCard.tsx"
|
||||
provides: "Rank badge on grid-view cards"
|
||||
contains: "RankBadge"
|
||||
key_links:
|
||||
- from: "src/client/routes/threads/$threadId.tsx"
|
||||
to: "src/client/hooks/useCandidates.ts"
|
||||
via: "useReorderCandidates(threadId)"
|
||||
pattern: "useReorderCandidates"
|
||||
- from: "src/client/hooks/useCandidates.ts"
|
||||
to: "/api/threads/:id/candidates/reorder"
|
||||
via: "apiPatch"
|
||||
pattern: "apiPatch.*candidates/reorder"
|
||||
- from: "src/client/routes/threads/$threadId.tsx"
|
||||
to: "framer-motion"
|
||||
via: "Reorder.Group + Reorder.Item"
|
||||
pattern: "Reorder\\.Group"
|
||||
- from: "src/client/components/CandidateListItem.tsx"
|
||||
to: "framer-motion"
|
||||
via: "Reorder.Item + useDragControls"
|
||||
pattern: "useDragControls"
|
||||
- from: "src/client/stores/uiStore.ts"
|
||||
to: "src/client/routes/threads/$threadId.tsx"
|
||||
via: "candidateViewMode state"
|
||||
pattern: "candidateViewMode"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Build the drag-to-reorder UI with list/grid view toggle, CandidateListItem component, framer-motion Reorder integration, rank badges, and resolved-thread guard.
|
||||
|
||||
Purpose: Delivers the user-facing ranking experience: drag candidates to prioritize, see gold/silver/bronze medals, toggle between compact list and card grid views. All four RANK requirements are covered.
|
||||
Output: Working drag-to-reorder in list view, rank badges in both views, view toggle, resolved-thread readonly mode.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@/home/jlmak/.claude/get-shit-done/workflows/execute-plan.md
|
||||
@/home/jlmak/.claude/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/ROADMAP.md
|
||||
@.planning/STATE.md
|
||||
@.planning/phases/11-candidate-ranking/11-CONTEXT.md
|
||||
@.planning/phases/11-candidate-ranking/11-RESEARCH.md
|
||||
@.planning/phases/11-candidate-ranking/11-01-SUMMARY.md
|
||||
|
||||
<interfaces>
|
||||
<!-- Interfaces created by Plan 01 that this plan depends on -->
|
||||
|
||||
From src/shared/schemas.ts (created in 11-01):
|
||||
```typescript
|
||||
export const reorderCandidatesSchema = z.object({
|
||||
orderedIds: z.array(z.number().int().positive()).min(1),
|
||||
});
|
||||
```
|
||||
|
||||
From src/shared/types.ts (created in 11-01):
|
||||
```typescript
|
||||
export type ReorderCandidates = z.infer<typeof reorderCandidatesSchema>;
|
||||
```
|
||||
|
||||
From src/server/services/thread.service.ts (modified in 11-01):
|
||||
```typescript
|
||||
export function reorderCandidates(db, threadId, orderedIds): { success: boolean; error?: string }
|
||||
// getThreadWithCandidates now returns candidates sorted by sort_order ascending
|
||||
// createCandidate now assigns sort_order = max + 1000 (appends to bottom)
|
||||
```
|
||||
|
||||
API endpoint (created in 11-01):
|
||||
```
|
||||
PATCH /api/threads/:id/candidates/reorder
|
||||
Body: { orderedIds: number[] }
|
||||
Response: { success: true } | { error: string } (400)
|
||||
```
|
||||
|
||||
From src/client/lib/api.ts:
|
||||
```typescript
|
||||
export async function apiPatch<T>(url: string, body: unknown): Promise<T>;
|
||||
```
|
||||
|
||||
From src/client/hooks/useCandidates.ts (existing):
|
||||
```typescript
|
||||
interface CandidateResponse {
|
||||
id: number; threadId: number; name: string;
|
||||
weightGrams: number | null; priceCents: number | null;
|
||||
categoryId: number; notes: string | null; productUrl: string | null;
|
||||
imageFilename: string | null; status: "researching" | "ordered" | "arrived";
|
||||
pros: string | null; cons: string | null;
|
||||
createdAt: string; updatedAt: string;
|
||||
}
|
||||
```
|
||||
|
||||
From src/client/components/CandidateCard.tsx (existing props):
|
||||
```typescript
|
||||
interface CandidateCardProps {
|
||||
id: number; name: string; weightGrams: number | null; priceCents: number | null;
|
||||
categoryName: string; categoryIcon: string; imageFilename: string | null;
|
||||
productUrl?: string | null; threadId: number; isActive: boolean;
|
||||
status: "researching" | "ordered" | "arrived";
|
||||
onStatusChange: (status: "researching" | "ordered" | "arrived") => void;
|
||||
pros?: string | null; cons?: string | null;
|
||||
}
|
||||
```
|
||||
|
||||
From src/client/stores/uiStore.ts (existing patterns):
|
||||
```typescript
|
||||
interface UIState {
|
||||
// ... existing state
|
||||
// Add: candidateViewMode: "list" | "grid"
|
||||
// Add: setCandidateViewMode: (mode: "list" | "grid") => void
|
||||
}
|
||||
```
|
||||
|
||||
From framer-motion (installed v12.37.0):
|
||||
```typescript
|
||||
import { Reorder, useDragControls } from "framer-motion";
|
||||
// Reorder.Group: axis="y", values={items}, onReorder={setItems}
|
||||
// Reorder.Item: value={item}, dragControls={controls}, dragListener={false}
|
||||
// useDragControls: controls.start(pointerEvent) on handle's onPointerDown
|
||||
```
|
||||
|
||||
From lucide-react (confirmed available icons):
|
||||
- grip-vertical (drag handle)
|
||||
- medal (rank badge)
|
||||
- layout-list (list view toggle)
|
||||
- layout-grid (grid view toggle)
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: useReorderCandidates hook + uiStore view mode + CandidateListItem component</name>
|
||||
<files>src/client/hooks/useCandidates.ts, src/client/stores/uiStore.ts, src/client/components/CandidateListItem.tsx</files>
|
||||
<action>
|
||||
1. **useReorderCandidates hook** (`src/client/hooks/useCandidates.ts`):
|
||||
- Import `apiPatch` from `../lib/api`.
|
||||
- Add new exported function:
|
||||
```typescript
|
||||
export function useReorderCandidates(threadId: number) {
|
||||
const queryClient = useQueryClient();
|
||||
return useMutation({
|
||||
mutationFn: (data: { orderedIds: number[] }) =>
|
||||
apiPatch<{ success: boolean }>(
|
||||
`/api/threads/${threadId}/candidates/reorder`,
|
||||
data,
|
||||
),
|
||||
onSettled: () => {
|
||||
queryClient.invalidateQueries({ queryKey: ["threads", threadId] });
|
||||
},
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
2. **uiStore** (`src/client/stores/uiStore.ts`):
|
||||
- Add to the UIState interface:
|
||||
```typescript
|
||||
candidateViewMode: "list" | "grid";
|
||||
setCandidateViewMode: (mode: "list" | "grid") => void;
|
||||
```
|
||||
- Add to the create block:
|
||||
```typescript
|
||||
candidateViewMode: "list",
|
||||
setCandidateViewMode: (mode) => set({ candidateViewMode: mode }),
|
||||
```
|
||||
|
||||
3. **CandidateListItem** (`src/client/components/CandidateListItem.tsx`) — NEW FILE:
|
||||
- Create a horizontal card component for list view.
|
||||
- Import `{ Reorder, useDragControls }` from `framer-motion`.
|
||||
- Import `LucideIcon` from `../lib/iconData`, formatters, hooks (useWeightUnit, useCurrency), useUIStore, StatusBadge.
|
||||
- Props interface:
|
||||
```typescript
|
||||
interface CandidateListItemProps {
|
||||
candidate: CandidateWithCategory; // The full candidate object from thread.candidates
|
||||
rank: number; // 1-based position index
|
||||
isActive: boolean; // thread.status === "active"
|
||||
onStatusChange: (status: "researching" | "ordered" | "arrived") => void;
|
||||
}
|
||||
```
|
||||
Where `CandidateWithCategory` is the candidate shape from `useThread` response (id, name, weightGrams, priceCents, categoryName, categoryIcon, imageFilename, productUrl, status, pros, cons, etc.). Define this type locally or reference the CandidateResponse + category fields.
|
||||
|
||||
- Use `useDragControls()` hook. Return a `Reorder.Item` with `value={candidate}` (the full candidate object, same reference used in Reorder.Group values), `dragControls={controls}`, `dragListener={false}`.
|
||||
|
||||
- Layout (horizontal card):
|
||||
- Outer: `flex items-center gap-3 bg-white rounded-xl border border-gray-100 p-3 hover:border-gray-200 hover:shadow-sm transition-all group`
|
||||
- LEFT: Drag handle (only if `isActive`): GripVertical icon (size 16), `onPointerDown={(e) => controls.start(e)}`, classes: `cursor-grab active:cursor-grabbing text-gray-300 hover:text-gray-500 touch-none shrink-0`
|
||||
- RANK BADGE: Inline `RankBadge` component (see below). Shows medal icon for rank 1-3 with gold/silver/bronze colors. Returns null for rank > 3.
|
||||
- IMAGE THUMBNAIL: 48x48 rounded-lg overflow-hidden shrink-0. If `imageFilename`, show `<img src="/uploads/${imageFilename}" />` with object-cover. Else show `LucideIcon` of `categoryIcon` (size 20) in gray on gray-50 background.
|
||||
- NAME + BADGES: `flex-1 min-w-0` container.
|
||||
- Name: `text-sm font-semibold text-gray-900 truncate`
|
||||
- Badge row: `flex flex-wrap gap-1.5 mt-1` with weight (blue), price (green), category (gray + icon), StatusBadge, pros/cons badge (purple "+/- Notes").
|
||||
- Use same badge pill classes as CandidateCard.
|
||||
- ACTION BUTTONS (hover-reveal, right side): Winner (if isActive), Delete, External link (if productUrl). Use same click handlers as CandidateCard (openResolveDialog, openConfirmDeleteCandidate, openExternalLink from uiStore). Classes: `opacity-0 group-hover:opacity-100 transition-opacity` on a flex container.
|
||||
- Clicking the card body (not handle or action buttons) opens the edit panel: wrap in a clickable area that calls `openCandidateEditPanel(candidate.id)`.
|
||||
|
||||
- **RankBadge** (inline helper or small component in same file):
|
||||
```typescript
|
||||
const RANK_COLORS = ["#D4AF37", "#C0C0C0", "#CD7F32"]; // gold, silver, bronze
|
||||
function RankBadge({ rank }: { rank: number }) {
|
||||
if (rank > 3) return null;
|
||||
return <LucideIcon name="medal" size={16} className="shrink-0" style={{ color: RANK_COLORS[rank - 1] }} />;
|
||||
}
|
||||
```
|
||||
Export `RankBadge` so it can be reused by CandidateCard in grid view.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd /home/jlmak/Projects/jlmak/GearBox && bun run lint 2>&1 | head -30</automated>
|
||||
</verify>
|
||||
<done>CandidateListItem.tsx created with drag handle, rank badge, horizontal layout. useReorderCandidates hook created. uiStore has candidateViewMode. RankBadge exported. Lint passes.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Thread detail page with view toggle, Reorder.Group, rank badges in grid view</name>
|
||||
<files>src/client/routes/threads/$threadId.tsx, src/client/components/CandidateCard.tsx</files>
|
||||
<action>
|
||||
1. **CandidateCard rank badge** (`src/client/components/CandidateCard.tsx`):
|
||||
- Import `RankBadge` from `./CandidateListItem` (or wherever it's exported).
|
||||
- Add `rank?: number` to `CandidateCardProps`.
|
||||
- In the card layout, add `{rank != null && <RankBadge rank={rank} />}` in the badge row (flex-wrap area), positioned as the first badge before weight/price.
|
||||
|
||||
2. **Thread detail page** (`src/client/routes/threads/$threadId.tsx`):
|
||||
- Import `{ Reorder }` from `framer-motion`.
|
||||
- Import `{ useState, useEffect }` from `react`.
|
||||
- Import `CandidateListItem` from `../../components/CandidateListItem`.
|
||||
- Import `useReorderCandidates` from `../../hooks/useCandidates`.
|
||||
- Import `useUIStore` selector for `candidateViewMode` and `setCandidateViewMode`.
|
||||
- Import `LucideIcon` (already imported).
|
||||
|
||||
- **View toggle** in the header area (after the "Add Candidate" button, or in the thread header row):
|
||||
- Two icon buttons: LayoutList and LayoutGrid (from Lucide).
|
||||
- Active button has `bg-gray-200 text-gray-900`, inactive has `text-gray-400 hover:text-gray-600`.
|
||||
- `onClick` calls `setCandidateViewMode("list")` or `setCandidateViewMode("grid")`.
|
||||
- Placed inline in a small toggle group: `flex items-center gap-1 bg-gray-100 rounded-lg p-0.5`
|
||||
|
||||
- **tempItems pattern** for flicker prevention:
|
||||
```typescript
|
||||
const [tempItems, setTempItems] = useState<typeof thread.candidates | null>(null);
|
||||
const displayItems = tempItems ?? thread.candidates;
|
||||
// thread.candidates is already sorted by sort_order from server (11-01)
|
||||
```
|
||||
Reset tempItems to null whenever `thread.candidates` reference changes (use useEffect if needed, or rely on onSettled clearing).
|
||||
|
||||
- **Reorder.Group** (list view, active threads only):
|
||||
- When `candidateViewMode === "list"` AND candidates exist:
|
||||
- If `isActive`: Wrap candidates in `<Reorder.Group axis="y" values={displayItems} onReorder={setTempItems} className="flex flex-col gap-2">`.
|
||||
- Each candidate renders `<CandidateListItem key={candidate.id} candidate={candidate} rank={index + 1} isActive={isActive} onStatusChange={...} />`.
|
||||
- On Reorder.Item `onDragEnd`, trigger the save. The save function:
|
||||
```typescript
|
||||
function handleDragEnd() {
|
||||
if (!tempItems) return;
|
||||
reorderMutation.mutate(
|
||||
{ orderedIds: tempItems.map((c) => c.id) },
|
||||
{ onSettled: () => setTempItems(null) }
|
||||
);
|
||||
}
|
||||
```
|
||||
Attach this to `Reorder.Group` via a wrapper that uses `onPointerUp` or pass as prop to `CandidateListItem`. The cleanest approach: use framer-motion's `onDragEnd` prop on each `Reorder.Item` — when any item finishes dragging, if tempItems differs from server data, fire the mutation.
|
||||
- If `!isActive` (resolved): Render the same `CandidateListItem` components but WITHOUT `Reorder.Group` — just a plain `<div className="flex flex-col gap-2">`. The `isActive={false}` prop hides drag handles. Rank badges remain visible per user decision.
|
||||
|
||||
- When `candidateViewMode === "grid"` AND candidates exist:
|
||||
- Render the existing `<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">` with `CandidateCard` components.
|
||||
- Pass `rank={index + 1}` to each CandidateCard so rank badges appear in grid view too.
|
||||
- Both active and resolved threads use static grid (no drag in grid view per user decision).
|
||||
|
||||
- **Important framer-motion detail**: `Reorder.Group` `values` must be the same array reference as what you iterate. Use `displayItems` for both `values` and `.map()`. The `Reorder.Item` `value` must be the same object reference (not a copy). Since we use the full candidate object, `value={candidate}` where candidate comes from `displayItems.map(...)`.
|
||||
|
||||
- **Empty state**: Keep the existing empty state rendering for both views.
|
||||
|
||||
- **useEffect to clear tempItems**: When `thread.candidates` changes (new data from server), clear tempItems:
|
||||
```typescript
|
||||
useEffect(() => {
|
||||
setTempItems(null);
|
||||
}, [thread?.candidates]);
|
||||
```
|
||||
This ensures that when React Query refetches, tempItems is cleared and we render fresh server data.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd /home/jlmak/Projects/jlmak/GearBox && bun run lint 2>&1 | head -30</automated>
|
||||
</verify>
|
||||
<done>Thread detail page renders list/grid toggle. List view has drag-to-reorder via Reorder.Group with tempItems flicker prevention. Grid view shows rank badges. Resolved threads show static list/grid with rank badges but no drag handles. Lint passes.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking">
|
||||
<name>Task 3: Verify drag-to-reorder ranking experience</name>
|
||||
<files>none</files>
|
||||
<action>
|
||||
Human verifies the complete drag-to-reorder candidate ranking with list/grid view toggle, rank badges (gold/silver/bronze), auto-save persistence, and resolved thread guard.
|
||||
</action>
|
||||
<what-built>Complete drag-to-reorder candidate ranking with list/grid view toggle, rank badges (gold/silver/bronze), auto-save persistence, and resolved thread guard.</what-built>
|
||||
<how-to-verify>
|
||||
1. Start dev servers: `bun run dev:client` and `bun run dev:server`
|
||||
2. Navigate to an existing active thread with 3+ candidates (or create one)
|
||||
3. Verify list view is the default (vertical stack of horizontal cards)
|
||||
4. Verify drag handles (grip icon) appear on the left of each card
|
||||
5. Drag a candidate to a new position — verify it moves smoothly with gap animation
|
||||
6. Release — verify the new order persists (refresh the page to confirm)
|
||||
7. Verify the top 3 candidates show gold, silver, bronze medal icons before their names
|
||||
8. Toggle to grid view — verify rank badges also appear on grid cards
|
||||
9. Toggle back to list view — verify drag still works
|
||||
10. Navigate to a resolved thread — verify NO drag handles, but rank badges ARE visible
|
||||
11. Verify candidates on resolved thread render in their ranked order (static)
|
||||
</how-to-verify>
|
||||
<verify>Human confirms all 11 verification steps pass</verify>
|
||||
<done>All ranking features verified: drag reorder works, persists, shows rank badges in both views, disabled on resolved threads</done>
|
||||
<resume-signal>Type "approved" or describe any issues</resume-signal>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<verification>
|
||||
```bash
|
||||
# Full test suite green
|
||||
bun test
|
||||
|
||||
# Verify all key files exist
|
||||
ls src/client/components/CandidateListItem.tsx
|
||||
grep -n "useReorderCandidates" src/client/hooks/useCandidates.ts
|
||||
grep -n "candidateViewMode" src/client/stores/uiStore.ts
|
||||
grep -n "Reorder.Group" src/client/routes/threads/\$threadId.tsx
|
||||
grep -n "RankBadge" src/client/components/CandidateCard.tsx
|
||||
|
||||
# Lint clean
|
||||
bun run lint
|
||||
```
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- List view shows horizontal cards with drag handles on active threads
|
||||
- Drag-to-reorder works via framer-motion Reorder.Group with grip handle
|
||||
- Order persists after page refresh via PATCH /api/threads/:id/candidates/reorder
|
||||
- tempItems pattern prevents React Query flicker
|
||||
- Top 3 candidates display gold (#D4AF37), silver (#C0C0C0), bronze (#CD7F32) medal badges
|
||||
- Rank badges visible in both list and grid views
|
||||
- Grid/list toggle works with list as default
|
||||
- Resolved threads: no drag handles, rank badges visible, static order
|
||||
- All tests pass, lint clean
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/11-candidate-ranking/11-02-SUMMARY.md`
|
||||
</output>
|
||||
Reference in New Issue
Block a user