379 lines
19 KiB
Markdown
379 lines
19 KiB
Markdown
---
|
|
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>
|