docs(22): capture phase context
This commit is contained in:
@@ -0,0 +1,147 @@
|
||||
# Phase 22: Add-from-Catalog & Thread Integration - Context
|
||||
|
||||
**Gathered:** 2026-04-06
|
||||
**Status:** Ready for planning
|
||||
|
||||
<domain>
|
||||
## Phase Boundary
|
||||
|
||||
Wire the actual add-to-collection and add-to-thread flows from the catalog search overlay and global item detail pages. Currently, the CatalogSearchOverlay has a stub `handleAddStub` and the global item detail page has a console.log placeholder. This phase makes those buttons functional: adding a catalog item to collection creates a reference item with `globalItemId`, and adding to a thread creates a candidate with `globalItemId`. Thread resolution with catalog-linked candidates already works (Phase 19).
|
||||
|
||||
</domain>
|
||||
|
||||
<decisions>
|
||||
## Implementation Decisions
|
||||
|
||||
### Add-to-Collection Flow
|
||||
- **D-01:** Clicking "Add" on a catalog search card (in collection mode) or "Add to Collection" on the global item detail page opens a compact confirmation modal.
|
||||
- **D-02:** The modal contains: category dropdown (pre-populated from user's categories, defaulting to the global item's category if a match exists), optional notes field, optional purchase price field, and "Add to Collection" / "Cancel" buttons.
|
||||
- **D-03:** Submitting the modal calls `POST /api/items` with `globalItemId` set to the catalog item's ID, plus the personal fields (categoryId, notes, purchasePriceCents). Name, weight, price come from global item via service layer merge (Phase 19 pattern).
|
||||
- **D-04:** After successful add, show a brief success toast ("Added to Collection"). User stays in the search overlay (or remains on the detail page) to continue browsing/adding.
|
||||
- **D-05:** The modal reuses form field patterns from ItemForm (category dropdown, notes textarea) but is a standalone lightweight component — not the full ItemForm.
|
||||
|
||||
### Add-to-Thread Flow (Existing Thread)
|
||||
- **D-06:** When `catalogSearchMode === "thread"` and user clicks "Add" on a search card, show a modal with a thread picker dropdown listing active (non-resolved) threads.
|
||||
- **D-07:** User selects a thread, then the modal creates a candidate via `POST /api/threads/:threadId/candidates` with `globalItemId`, `name` (from global item brand+model), `categoryId` (from thread's category), and other global item data.
|
||||
- **D-08:** After successful candidate add, show success toast ("Added to [Thread Name]"). User stays in search overlay.
|
||||
- **D-09:** If no active threads exist, the thread picker shows an empty state with a "Create Thread First" link/button that opens the existing CreateThreadModal.
|
||||
|
||||
### Start New Thread Flow (FAB "Start Thread")
|
||||
- **D-10:** "Start Thread" from FAB opens catalog search in thread mode (`catalogSearchMode === "thread"`).
|
||||
- **D-11:** When the user clicks "Add" on the first item and no thread is selected yet, show a combined modal: thread name + category fields (matching CreateThreadModal) plus the candidate is auto-added upon thread creation.
|
||||
- **D-12:** After the thread is created with its first candidate, subsequent "Add" clicks in the same search session default to adding to the just-created thread (thread ID stored in overlay state).
|
||||
- **D-13:** The thread picker dropdown (D-06) also includes a "New Thread..." option that triggers the combined creation flow.
|
||||
|
||||
### Global Item Detail Page Integration
|
||||
- **D-14:** The "Add to Collection" button on `/global-items/:id` triggers the same add-to-collection modal (D-01-D-05), passing the global item's data.
|
||||
- **D-15:** Add an "Add to Thread" button alongside "Add to Collection" on the detail page, triggering the thread picker modal (D-06-D-09).
|
||||
|
||||
### Catalog Search Overlay Updates
|
||||
- **D-16:** Replace `handleAddStub` with actual handler that opens the appropriate modal based on `catalogSearchMode`.
|
||||
- **D-17:** In "collection" mode, Add button opens add-to-collection modal directly.
|
||||
- **D-18:** In "thread" mode, Add button opens thread picker modal.
|
||||
- **D-19:** Add a session-level `selectedThreadId` state to CatalogSearchOverlay (or UIStore) to remember the thread selection within a search session.
|
||||
|
||||
### UIStore / State Changes
|
||||
- **D-20:** Add modal state: `addToCollectionModal: { open: boolean; globalItemId: number | null }`.
|
||||
- **D-21:** Add modal state: `addToThreadModal: { open: boolean; globalItemId: number | null; globalItemName: string | null }`.
|
||||
- **D-22:** Add session thread tracking: `catalogSessionThreadId: number | null` — reset when overlay closes.
|
||||
|
||||
### Claude's Discretion
|
||||
- Modal animation style and exact layout proportions
|
||||
- Whether category dropdown auto-selects based on global item category name match or leaves unselected
|
||||
- Toast notification library/pattern (existing toast pattern if one exists, or simple inline notification)
|
||||
- Whether the thread picker shows thread category alongside name
|
||||
- Exact field ordering in the add-to-collection modal
|
||||
- Whether purchase price field uses currency formatting input or plain number
|
||||
|
||||
</decisions>
|
||||
|
||||
<canonical_refs>
|
||||
## Canonical References
|
||||
|
||||
**Downstream agents MUST read these before planning or implementing.**
|
||||
|
||||
### Design Spec
|
||||
- `docs/superpowers/specs/2026-04-05-catalog-driven-gear-flow-design.md` — Full catalog-driven gear flow vision. Phase 22 implements Flows 1 and 2 (add-to-collection, add-to-thread).
|
||||
|
||||
### Key Components to Modify
|
||||
- `src/client/components/CatalogSearchOverlay.tsx` — Replace `handleAddStub` with real handlers (lines 111-114)
|
||||
- `src/client/routes/global-items/$globalItemId.tsx` — Wire "Add to Collection" button (line 133)
|
||||
- `src/client/stores/uiStore.ts` — Add modal states for add-to-collection and add-to-thread
|
||||
|
||||
### Existing Hooks/Mutations to Use
|
||||
- `src/client/hooks/useItems.ts` — `useCreateItem()` for adding reference items to collection
|
||||
- `src/client/hooks/useCandidates.ts` — `useCreateCandidate(threadId)` for adding catalog items as thread candidates
|
||||
- `src/client/hooks/useGlobalItems.ts` — `useGlobalItem(id)` for fetching global item details
|
||||
|
||||
### Schemas (support globalItemId already)
|
||||
- `src/shared/schemas.ts` — `createItemSchema` has `globalItemId` optional field (line 13), `createCandidateSchema` has `globalItemId` (line 63)
|
||||
|
||||
### Services (reference item pattern already works)
|
||||
- `src/server/services/item.service.ts` — Creates reference items when `globalItemId` is provided
|
||||
- `src/server/services/thread.service.ts` — `resolveThread()` handles catalog-linked candidates (line 312+)
|
||||
|
||||
### Prior Phase Context
|
||||
- `.planning/phases/19-reference-item-model-tags-schema/19-CONTEXT.md` — Reference item model decisions (D-01 through D-13)
|
||||
- `.planning/phases/20-fab-full-screen-catalog-search/20-CONTEXT.md` — Catalog search overlay decisions, UIStore patterns
|
||||
- `.planning/phases/21-item-catalog-detail-pages/21-CONTEXT.md` — Detail page stubs that need wiring
|
||||
|
||||
### Requirements
|
||||
- `.planning/REQUIREMENTS.md` — CATFLOW-03, CATFLOW-05, CATFLOW-06
|
||||
|
||||
</canonical_refs>
|
||||
|
||||
<code_context>
|
||||
## Existing Code Insights
|
||||
|
||||
### Reusable Assets
|
||||
- `useCreateItem()` hook — creates items via POST /api/items, already supports `globalItemId` field
|
||||
- `useCreateCandidate(threadId)` hook — creates candidates via POST /api/threads/:threadId/candidates, supports `globalItemId`
|
||||
- `CreateThreadModal` — modal pattern with form fields, can inform the combined thread+candidate creation modal
|
||||
- `CatalogSearchOverlay` — already has `catalogSearchMode` to distinguish collection vs thread flows
|
||||
- `useCategories()` hook — for category dropdown in confirmation modal
|
||||
- `useThreads()` hook — for thread picker dropdown
|
||||
- `useFormatters()` — weight/price formatting for modal display
|
||||
- `useGlobalItem(id)` — fetch individual global item details
|
||||
|
||||
### Established Patterns
|
||||
- Zustand UIStore for modal open/close state
|
||||
- TanStack React Query mutations with `invalidateQueries` on success
|
||||
- Compact modals with backdrop dimming (CreateThreadModal pattern)
|
||||
- `apiPost` for creating resources
|
||||
- Category dropdown pattern from ItemForm (select with category list)
|
||||
|
||||
### Integration Points
|
||||
- `CatalogSearchOverlay.tsx` line 111-114 — `handleAddStub` replacement
|
||||
- `global-items/$globalItemId.tsx` line 133 — "Add to Collection" button wiring
|
||||
- `uiStore.ts` — new modal state slices
|
||||
- New components: `AddToCollectionModal`, `AddToThreadModal` (or combined `CatalogAddModal`)
|
||||
|
||||
</code_context>
|
||||
|
||||
<specifics>
|
||||
## Specific Ideas
|
||||
|
||||
- The add-to-collection modal should be lightweight — category picker + optional notes + purchase price. Not a full item form. One click to add.
|
||||
- Thread picker should show thread name and category for easy identification.
|
||||
- The "Start Thread" flow should feel seamless — user picks an item, names their thread, and the candidate is created in one action.
|
||||
- Success feedback should be non-intrusive (toast, not a redirect) to support adding multiple items in one session.
|
||||
|
||||
</specifics>
|
||||
|
||||
<deferred>
|
||||
## Deferred Ideas
|
||||
|
||||
- "Add Manually" link in catalog search empty state — Phase 23
|
||||
- Manual entry fallback for items not in catalog — Phase 23
|
||||
- Bulk add multiple items at once — future phase
|
||||
- "Quick add" without any confirmation (one-tap add with defaults) — future optimization
|
||||
- Quantity selection during add (default to 1) — could be future enhancement
|
||||
|
||||
</deferred>
|
||||
|
||||
---
|
||||
|
||||
*Phase: 22-add-from-catalog-thread-integration*
|
||||
*Context gathered: 2026-04-06*
|
||||
@@ -0,0 +1,79 @@
|
||||
# Phase 22: Add-from-Catalog & Thread Integration - Discussion Log
|
||||
|
||||
> **Audit trail only.** Do not use as input to planning, research, or execution agents.
|
||||
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
|
||||
|
||||
**Date:** 2026-04-06
|
||||
**Phase:** 22-add-from-catalog-thread-integration
|
||||
**Areas discussed:** Add-to-Collection Confirmation UX, Add-to-Thread Flow, Post-Add Behavior, Thread Selection Context
|
||||
**Mode:** --auto (all defaults auto-selected)
|
||||
|
||||
---
|
||||
|
||||
## Add-to-Collection Confirmation UX
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Compact modal dialog | Small modal with category picker, notes, purchase price, and confirm button | ✓ |
|
||||
| Inline card expansion | Expand the card in-place to show form fields | |
|
||||
| Full-page form | Navigate to a dedicated add page | |
|
||||
|
||||
**User's choice:** [auto] Compact modal dialog (recommended default)
|
||||
**Notes:** Aligns with existing modal patterns (CreateThreadModal). Minimal friction — one confirmation step as specified in success criteria.
|
||||
|
||||
---
|
||||
|
||||
## Add-to-Thread Flow
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Thread picker dropdown in modal | Modal with dropdown of active threads, instant candidate creation | ✓ |
|
||||
| Auto-add to most recent thread | Skip selection, add to last-used thread | |
|
||||
| Thread list with search | Full thread list with search filtering | |
|
||||
|
||||
**User's choice:** [auto] Thread picker dropdown in modal (recommended default)
|
||||
**Notes:** Active threads are typically few, so a simple dropdown suffices. Includes empty state handling when no threads exist.
|
||||
|
||||
---
|
||||
|
||||
## Post-Add Behavior
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Success toast, stay in search | Brief notification, user continues browsing | ✓ |
|
||||
| Navigate to the item/thread | Redirect to the newly created item or thread | |
|
||||
| Close overlay | Dismiss search overlay after add | |
|
||||
|
||||
**User's choice:** [auto] Success toast, stay in search (recommended default)
|
||||
**Notes:** Supports adding multiple items in one session — common use case when researching gear.
|
||||
|
||||
---
|
||||
|
||||
## Thread Selection Context
|
||||
|
||||
| Option | Description | Selected |
|
||||
|--------|-------------|----------|
|
||||
| Create thread when first candidate added | Combined modal: thread creation + first candidate in one step | ✓ |
|
||||
| Create thread first, then search | Require thread creation before entering search | |
|
||||
| Always show thread picker | No special first-add flow | |
|
||||
|
||||
**User's choice:** [auto] Create thread when first candidate added (recommended default)
|
||||
**Notes:** Seamless flow — user finds an item first, then names the thread. Subsequent adds in same session default to the just-created thread.
|
||||
|
||||
---
|
||||
|
||||
## Claude's Discretion
|
||||
|
||||
- Modal animation and layout proportions
|
||||
- Category auto-selection logic
|
||||
- Toast notification pattern
|
||||
- Thread picker display details
|
||||
- Field ordering in modals
|
||||
- Purchase price input formatting
|
||||
|
||||
## Deferred Ideas
|
||||
|
||||
- Manual entry fallback (Phase 23)
|
||||
- Bulk add multiple items
|
||||
- Quick one-tap add without confirmation
|
||||
- Quantity selection during add
|
||||
Reference in New Issue
Block a user