GearBox/.planning/phases/21-item-catalog-detail-pages/21-CONTEXT.md

Phase 21: Item & Catalog Detail Pages - Context

Gathered: 2026-04-06 Status: Ready for planning

## Phase Boundary

Create full detail pages for collection items (/items/:id) and enhance the existing catalog detail page (/global-items/:id). Remove slide-out panels for items and candidates from the root layout. Add edit mode toggle on private detail pages. Thread candidates get their own detail route. No visual distinction between reference items and standalone items — same layout, some fields may be empty.

## Implementation Decisions

Private Item Detail Page (/items/:id)

• D-01: New route at /items/:id — full page showing all item data (name, weight, price, category, notes, product link, image, quantity, purchase price).
• D-02: Hero section at top — large product image (or placeholder), item name as title, key specs as badges (weight, price, category).
• D-03: Personal section below — notes, quantity, purchase price, product link. For reference items, this data comes from the COALESCE merge (transparent, no visual distinction).
• D-04: Edit mode toggle — "Edit" button in top-right corner. When toggled, fields become editable inputs (same styling as current ItemForm). Save/Cancel buttons appear. Uses existing updateItem mutation.
• D-05: No inline editing by default — page is read-only until edit button is pressed. Clean aesthetic.
• D-06: Back navigation — link at top to return to collection (/collection).
• D-07: Actions — duplicate item, delete item (with confirmation), available in a menu or as buttons.

Public Catalog Detail Page (/global-items/:id)

• D-08: Enhance existing route at /global-items/:id — currently has basic info. Add "Add to Collection" button.
• D-09: Layout: hero image, brand + model title, manufacturer specs (weight, price, category), description, owner count badge.
• D-10: "Add to Collection" button — prominent, top-right or below hero. Uses same flow as Phase 22's add-from-catalog (stub for now, like the search overlay's Add button).
• D-11: No edit functionality on public page — catalog items are admin-curated (future).
• D-12: Accessible from catalog search overlay — clicking a result card navigates here (currently cards only have an Add button).

Candidate Detail Page (/threads/:threadId/candidates/:candidateId)

• D-13: New route for candidate details within thread context. Shows candidate data (name, weight, price, notes, pros, cons, status, product link, image).
• D-14: Edit mode toggle — same pattern as item detail. Uses existing updateCandidate mutation.
• D-15: Back navigation — returns to parent thread (/threads/:threadId).
• D-16: Thread-specific actions: "Pick as winner" (resolve), delete candidate.

Navigation Changes

• D-17: ItemCard click → navigates to /items/:id instead of opening edit panel.
• D-18: CandidateCard click → navigates to /threads/:threadId/candidates/:candidateId instead of opening candidate panel.
• D-19: Catalog search result card click → navigates to /global-items/:id. The "Add" button stays as quick-add action (separate from card click).
• D-20: CandidateListItem click → same as CandidateCard, navigates to detail page.

Panel Removal

• D-21: Remove item SlideOutPanel instances from __root.tsx (both add and edit modes).
• D-22: Remove candidate SlideOutPanel instances from __root.tsx.
• D-23: Remove openAddPanel, openEditPanel, closePanelx, panelMode, editingItemId` from UIStore (item panel state).
• D-24: Remove openCandidateEditPanel, closeCandidatePanel, candidatePanelMode, editingCandidateId from UIStore.
• D-25: Keep SlideOutPanel.tsx component file — may be used for other panels later.
• D-26: Keep ItemForm.tsx and CandidateForm.tsx — their form logic/validation can be reused in detail page edit mode.

Adding New Items

• D-27: The "add item" flow now goes through catalog search (FAB → CatalogSearchOverlay). No more direct "add item" panel. The empty state in CollectionView already opens catalog search (fixed earlier).
• D-28: Adding candidates to threads — currently uses candidate add panel. For now, keep a simple "Add Candidate" button on the thread page that opens a minimal form/modal (not a slide-out). Detail: Claude's discretion on the exact pattern.

Claude's Discretion

• Exact layout proportions and spacing for detail pages
• Whether to use tabs or sections for organizing detail page content
• How the edit mode transition animates (if at all)
• "Add Candidate" button pattern on thread page (inline form, modal, or navigate to add route)
• Whether to show a "Linked to catalog" indicator on private items (subtle, not prominent)
• Mobile layout adaptations for detail pages

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Existing Routes to Modify/Enhance

• src/client/routes/global-items/$globalItemId.tsx — Existing catalog detail page (enhance with Add button, better layout)

Components to Modify

• src/client/components/ItemCard.tsx — Change click handler from openEditPanel to navigate
• src/client/components/CandidateCard.tsx — Change click handler to navigate
• src/client/components/CandidateListItem.tsx — Change click handler to navigate
• src/client/routes/__root.tsx — Remove SlideOutPanel instances
• src/client/stores/uiStore.ts — Remove panel state
• src/client/components/CatalogSearchOverlay.tsx — Add card click navigation to /global-items/:id

Components to Reuse

• src/client/components/ItemForm.tsx — Form fields/validation for edit mode
• src/client/components/CandidateForm.tsx — Candidate form fields for edit mode
• src/client/components/SlideOutPanel.tsx — Keep file, remove usage

Services (no changes needed)

• src/server/services/item.service.ts — getItemById already returns merged data via COALESCE
• src/server/services/thread.service.ts — getThreadWithCandidates returns candidate data

Design Spec

• docs/superpowers/specs/2026-04-05-catalog-driven-gear-flow-design.md — Overall vision

Requirements

• .planning/REQUIREMENTS.md — DETAIL-01 through DETAIL-05

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

• global-items/$globalItemId.tsx — Existing catalog detail page pattern to extend
• ItemForm.tsx — Form fields (name, weight, price, quantity, category, notes, productUrl, image) reusable for edit mode
• CandidateForm.tsx — Candidate form fields reusable for edit mode
• Badge pattern from GlobalItemCard/ItemCard — weight/price/category chips
• useItem(id) hook — fetches single item with merged data
• useUpdateItem mutation — for edit mode save
• useDeleteItem mutation — for delete action
• useDuplicateItem mutation — for duplicate action

Established Patterns

• TanStack Router file-based routes with createFileRoute
• Route params via $paramName convention
• Framer Motion for page transitions (AnimatePresence)
• Light/airy minimalist design (Tailwind CSS v4, white backgrounds, lots of whitespace)
• max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 for page content containment

Integration Points

• src/client/routes/items/ — New directory for item detail route
• src/client/routes/threads/$threadId/candidates/ — New directory for candidate detail route
• src/client/routes/__root.tsx — Remove panel instances, keep FabMenu and CatalogSearchOverlay
• src/client/stores/uiStore.ts — Clean up panel state

</code_context>

## Specific Ideas

• Detail pages should feel spacious and gallery-like — big image, clean typography, generous whitespace
• Edit mode should feel seamless — fields transform from display text to inputs, no jarring layout shift
• The "Add to Collection" button on the catalog detail page should be prominent but not overwhelming
• Back navigation should be consistent: "← Back to collection" or "← Back to thread"

## Deferred Ideas

• Reviews/ratings section on detail pages — future phase
• Community stats (average weight, price history) — future phase
• Setup appearances ("This item is in 3 setups") — future phase
• "Similar items" recommendation section — future phase
• Image gallery with multiple photos — future phase

---

Phase: 21-item-catalog-detail-pages Context gathered: 2026-04-06