diff --git a/.planning/phases/22-add-from-catalog-thread-integration/22-CONTEXT.md b/.planning/phases/22-add-from-catalog-thread-integration/22-CONTEXT.md new file mode 100644 index 0000000..0d31d35 --- /dev/null +++ b/.planning/phases/22-add-from-catalog-thread-integration/22-CONTEXT.md @@ -0,0 +1,147 @@ +# Phase 22: Add-from-Catalog & Thread Integration - Context + +**Gathered:** 2026-04-06 +**Status:** Ready for planning + + +## 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). + + + + +## 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 + + + + +## 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 + + + + +## 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`) + + + + +## 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. + + + + +## 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 + + + +--- + +*Phase: 22-add-from-catalog-thread-integration* +*Context gathered: 2026-04-06* diff --git a/.planning/phases/22-add-from-catalog-thread-integration/22-DISCUSSION-LOG.md b/.planning/phases/22-add-from-catalog-thread-integration/22-DISCUSSION-LOG.md new file mode 100644 index 0000000..62aaca8 --- /dev/null +++ b/.planning/phases/22-add-from-catalog-thread-integration/22-DISCUSSION-LOG.md @@ -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