# Phase 22: Add-from-Catalog & Thread Integration - Research

**Researched:** 2026-04-06
**Domain:** React modals, Zustand state, TanStack Query mutations, catalog-to-collection/thread flows
**Confidence:** HIGH

## Summary

This phase wires the stub "Add" buttons in the catalog search overlay and global item detail page to actual add-to-collection and add-to-thread flows. The backend infrastructure is fully ready: `createItemSchema` and `createCandidateSchema` both accept `globalItemId`, the item service creates reference items with global item data merge, and thread resolution already handles catalog-linked candidates. The work is entirely frontend: two new modal components, UIStore state slices, toast notifications, and handler wiring.

The existing codebase provides strong patterns to follow. `CreateThreadModal` demonstrates the modal pattern (backdrop + form + Zustand open/close). `useCreateItem()` and `useCreateCandidate(threadId)` are the exact mutation hooks needed. The `CatalogSearchOverlay` already distinguishes `catalogSearchMode === "collection"` vs `"thread"`, and `handleAddStub` is the single integration point to replace.

**Primary recommendation:** Build two standalone modal components (AddToCollectionModal, AddToThreadModal), add a lightweight toast system (sonner), extend UIStore with modal + session state, and wire the overlay/detail page handlers. No backend changes needed.

<user_constraints>
## User Constraints (from CONTEXT.md)

### Locked Decisions
- D-01 through D-05: Add-to-Collection modal with category dropdown, optional notes, optional purchase price, success toast, standalone lightweight component
- D-06 through D-09: Add-to-Thread modal with thread picker for active threads, success toast, empty state with "Create Thread First"
- D-10 through D-13: Start Thread flow creates thread + first candidate in one action, subsequent adds default to just-created thread
- D-14 through D-15: Global item detail page gets both "Add to Collection" and "Add to Thread" buttons
- D-16 through D-19: Replace handleAddStub, mode-based handler dispatch, session-level selectedThreadId
- D-20 through D-22: UIStore modal states for addToCollectionModal, addToThreadModal, catalogSessionThreadId

### 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
- Whether thread picker shows thread category alongside name
- Exact field ordering in add-to-collection modal
- Whether purchase price field uses currency formatting input or plain number

### Deferred Ideas (OUT OF SCOPE)
- "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
- "Quick add" without any confirmation (one-tap add with defaults)
- Quantity selection during add (default to 1)
</user_constraints>

<phase_requirements>
## Phase Requirements

| ID | Description | Research Support |
|----|-------------|------------------|
| CATFLOW-03 | User can add a catalog item to collection as a reference item with personal fields | AddToCollectionModal calls `useCreateItem()` with `globalItemId` + `categoryId` + optional notes/purchasePriceCents. Service layer already merges global item data. |
| CATFLOW-05 | Thread candidates can be added from catalog with global item link | AddToThreadModal calls `useCreateCandidate(threadId)` with `globalItemId` and global item data. Schema already supports `globalItemId` on candidates. |
| CATFLOW-06 | Thread resolution with catalog-linked candidate creates reference item with auto-link | Already implemented in `resolveThread()` (thread.service.ts:312+). Branches on `candidate.globalItemId` to create reference item. No new work needed -- verify with E2E test. |
</phase_requirements>

## Standard Stack

### Core (already in project)
| Library | Purpose | Why Standard |
|---------|---------|--------------|
| React 19 | UI components | Project framework |
| Zustand | UIStore modal/session state | Established pattern for all UI state |
| TanStack React Query | Mutations and cache invalidation | Established pattern for all data ops |
| Framer Motion | Modal animations | Already used for overlay animations |

### Supporting (new addition)
| Library | Purpose | Why |
|---------|---------|-----|
| sonner | Toast notifications | Lightweight (< 5KB), headless-friendly, works with Tailwind. No toast lib exists in project yet. |

### Alternatives Considered
| Instead of | Could Use | Tradeoff |
|------------|-----------|----------|
| sonner | Custom inline toast | Sonner handles stacking, auto-dismiss, accessibility out of the box |
| sonner | react-hot-toast | Both good; sonner has better default styling and smaller bundle |
| Separate modals | Single CatalogAddModal with mode switch | Two separate modals is cleaner -- different form fields, different submit logic |

**Installation:**
```bash
bun add sonner
```

**Discretion note:** Sonner is recommended but any lightweight toast approach works. A custom 20-line toast component using `useState` + `setTimeout` is also viable if avoiding new dependencies is preferred.

## Architecture Patterns

### New Component Structure
```
src/client/components/
  AddToCollectionModal.tsx    # Category picker + notes + purchase price
  AddToThreadModal.tsx        # Thread picker + "New Thread..." option
  Toast.tsx                   # Sonner <Toaster /> wrapper (or custom)
```

### Pattern 1: Modal with Zustand State
**What:** Modal open/close controlled by UIStore, form state local to component
**When to use:** All modals in this project
**Example:**
```typescript
// UIStore slice
addToCollectionModal: { open: boolean; globalItemId: number | null; globalItemName: string | null },
openAddToCollection: (globalItemId: number, globalItemName: string) =>
  set({ addToCollectionModal: { open: true, globalItemId, globalItemName } }),
closeAddToCollection: () =>
  set({ addToCollectionModal: { open: false, globalItemId: null, globalItemName: null } }),
```

### Pattern 2: Session Thread Tracking
**What:** Remember selected thread within a catalog search session
**When to use:** When user adds multiple items to same thread
**Example:**
```typescript
// UIStore
catalogSessionThreadId: number | null,
setCatalogSessionThreadId: (id: number | null) => set({ catalogSessionThreadId: id }),
// Reset when overlay closes:
closeCatalogSearch: () => set({
  catalogSearchOpen: false,
  catalogSearchMode: null,
  catalogSessionThreadId: null, // auto-reset
}),
```

### Pattern 3: Category Auto-Match
**What:** Pre-select user's category that matches global item's category name
**When to use:** Add-to-collection modal
**Recommendation:** Auto-select matching category by name comparison (case-insensitive). Falls back to first category if no match.
```typescript
const matchedCategory = categories?.find(
  (c) => c.name.toLowerCase() === globalItemCategory?.toLowerCase()
);
const defaultCategoryId = matchedCategory?.id ?? categories?.[0]?.id ?? null;
```

### Pattern 4: Combined Thread Creation + Candidate Add
**What:** Create thread and add first candidate in sequential mutations
**When to use:** "New Thread..." option in thread picker, or first add in "Start Thread" flow
**Example:**
```typescript
async function handleCreateThreadAndAddCandidate() {
  const thread = await createThread.mutateAsync({ name: threadName, categoryId });
  await createCandidate.mutateAsync({
    name: `${globalItem.brand} ${globalItem.model}`,
    globalItemId: globalItem.id,
    categoryId: thread.categoryId,
    weightGrams: globalItem.weightGrams,
    priceCents: globalItem.priceCents,
  });
  setCatalogSessionThreadId(thread.id);
  toast.success(`Created "${threadName}" with first candidate`);
}
```

### Anti-Patterns to Avoid
- **Don't pass full global item objects through UIStore:** Store only `globalItemId` + `globalItemName` in UIStore. Fetch full data in the modal via `useGlobalItem(id)` if needed, or pass additional fields as modal props.
- **Don't create a new `useCreateCandidate` variant:** The existing hook takes `threadId` as parameter -- use it directly. For the combined flow, call `useCreateThread().mutateAsync()` first to get the thread ID.
- **Don't modify backend routes or schemas:** Everything needed is already in place. `createItemSchema` has `globalItemId`, `createCandidateSchema` has `globalItemId`.

## Don't Hand-Roll

| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| Toast notifications | Custom notification system | sonner (or simple inline toast) | Stacking, auto-dismiss, accessibility, animation |
| Modal backdrop/focus trap | Custom portal + focus management | Existing pattern from CreateThreadModal | Consistent with codebase, already works |
| Category matching logic | Complex fuzzy matcher | Simple case-insensitive string equality | Categories are user-created, exact match is reliable enough |

## Common Pitfalls

### Pitfall 1: useCreateCandidate Requires Known threadId
**What goes wrong:** The `useCreateCandidate(threadId)` hook takes `threadId` at call time (hook parameter), not in the mutation payload. For the "New Thread..." flow, the thread doesn't exist yet when the hook is initialized.
**Why it happens:** Hook is designed for use within a thread detail view where threadId is known.
**How to avoid:** Use `apiPost` directly for the combined create-thread-then-add-candidate flow, OR call `useCreateCandidate` with a ref/state that updates after thread creation and trigger mutation after. Simplest: use `mutateAsync` on create thread, then call `apiPost` for the candidate with the returned thread ID.
**Warning signs:** Hook called with `0` or `null` threadId.

### Pitfall 2: Query Invalidation After Combined Operations
**What goes wrong:** Creating a thread + candidate requires invalidating both `["threads"]` and `["threads", newThreadId]` query keys. Missing one leaves stale data.
**Why it happens:** Two separate mutations, each with partial invalidation.
**How to avoid:** After combined create, invalidate `["threads"]` broadly. The `useCreateThread` hook already does this. For the candidate, manually call `queryClient.invalidateQueries({ queryKey: ["threads"] })`.

### Pitfall 3: Modal State Not Reset on Close
**What goes wrong:** Opening modal again shows previous form data.
**Why it happens:** Local state not cleared when UIStore `open` changes to false.
**How to avoid:** Use `useEffect` watching `open` state to reset form fields, same pattern as `CreateThreadModal` which resets on category load.

### Pitfall 4: CatalogSearchOverlay Closes Before Modal Opens
**What goes wrong:** User clicks "Add" on a catalog card, overlay closes (via existing close behavior), modal has no context.
**Why it happens:** The overlay's handleAddStub might be confused with card click navigation.
**How to avoid:** The "Add" button already calls `e.stopPropagation()` to prevent card click. The modal should open ON TOP of the overlay (higher z-index), not replace it. Overlay stays open while modal is visible.

### Pitfall 5: Global Item Category Is a String, User Categories Are Objects
**What goes wrong:** Trying to match `globalItem.category` (string like "Shelter") against `categories[].id` (number).
**Why it happens:** Global items store category as a plain string field, not a foreign key.
**How to avoid:** Match on `categories[].name` (string comparison), not on ID.

## Code Examples

### AddToCollectionModal Core Structure
```typescript
// Follows CreateThreadModal pattern exactly
function AddToCollectionModal() {
  const { open, globalItemId, globalItemName } = useUIStore((s) => s.addToCollectionModal);
  const close = useUIStore((s) => s.closeAddToCollection);
  const { data: categories } = useCategories();
  const createItem = useCreateItem();

  const [categoryId, setCategoryId] = useState<number | null>(null);
  const [notes, setNotes] = useState("");
  const [purchasePriceCents, setPurchasePriceCents] = useState<number | undefined>();

  if (!open || !globalItemId) return null;

  function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    if (!categoryId || !globalItemId) return;
    createItem.mutate({
      name: globalItemName ?? "Unknown Item", // Required by schema, service overwrites for reference items
      categoryId,
      globalItemId,
      notes: notes || undefined,
      purchasePriceCents: purchasePriceCents || undefined,
    }, {
      onSuccess: () => {
        toast.success("Added to Collection");
        close();
      },
    });
  }
  // ... render modal form
}
```

### Handler Wiring in CatalogSearchOverlay
```typescript
// Replace handleAddStub
function handleAdd(e: React.MouseEvent, item: { id: number; brand: string; model: string }) {
  e.stopPropagation();
  if (catalogSearchMode === "collection") {
    openAddToCollection(item.id, `${item.brand} ${item.model}`);
  } else if (catalogSearchMode === "thread") {
    openAddToThread(item.id, `${item.brand} ${item.model}`);
  }
}
```

### Thread Picker with "New Thread..." Option
```typescript
const { data: threads } = useThreads(); // defaults to active only
const activeThreads = threads?.filter((t) => t.status === "active") ?? [];

<select value={selectedThreadId ?? ""} onChange={handleThreadSelect}>
  {activeThreads.length === 0 && (
    <option value="" disabled>No active threads</option>
  )}
  {activeThreads.map((t) => (
    <option key={t.id} value={t.id}>
      {t.name} ({t.categoryName})
    </option>
  ))}
  <option value="new">+ New Thread...</option>
</select>
```

## State of the Art

| Old Approach | Current Approach | When Changed | Impact |
|--------------|------------------|--------------|--------|
| Slide-out panels for item edit | Full page routes for detail | Phase 21 | Modals are now lightweight overlays, not form-heavy panels |
| Manual item creation only | Reference items via globalItemId | Phase 19 | createItem service auto-merges global data |
| No toast system | Need toast for add confirmations | Phase 22 (this phase) | First toast usage in codebase |

## Validation Architecture

### Test Framework
| Property | Value |
|----------|-------|
| Framework | Bun test + Playwright |
| Config file | `playwright.config.ts` (E2E), `bunfig.toml` (unit) |
| Quick run command | `bun test tests/services/item.service.test.ts` |
| Full suite command | `bun test && bun run test:e2e` |

### Phase Requirements -> Test Map
| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|--------|----------|-----------|-------------------|-------------|
| CATFLOW-03 | Add catalog item to collection as reference item | E2E | `bun run test:e2e -- --grep "add from catalog"` | No -- Wave 0 |
| CATFLOW-05 | Add catalog item as thread candidate | E2E | `bun run test:e2e -- --grep "catalog candidate"` | No -- Wave 0 |
| CATFLOW-06 | Thread resolution preserves catalog link | unit | `bun test tests/services/thread.service.test.ts` | Partial -- resolve tests exist but may not cover globalItemId branch |

### Sampling Rate
- **Per task commit:** `bun test tests/services/item.service.test.ts tests/services/thread.service.test.ts`
- **Per wave merge:** `bun test && bun run test:e2e`
- **Phase gate:** Full suite green before verify

### Wave 0 Gaps
- [ ] E2E test for add-from-catalog-to-collection flow
- [ ] E2E test for add-from-catalog-to-thread flow
- [ ] Verify existing thread resolution test covers globalItemId candidate branch

## Sources

### Primary (HIGH confidence)
- Direct codebase inspection of all referenced files
- `src/shared/schemas.ts` -- confirmed `globalItemId` on both `createItemSchema` and `createCandidateSchema`
- `src/server/services/item.service.ts` -- confirmed reference item creation pattern
- `src/server/services/thread.service.ts:312+` -- confirmed catalog-linked resolution branch
- `src/client/stores/uiStore.ts` -- confirmed existing modal state patterns
- `src/client/components/CreateThreadModal.tsx` -- confirmed modal component pattern
- `src/client/hooks/useItems.ts`, `useCandidates.ts`, `useThreads.ts` -- confirmed mutation hooks

### Secondary (MEDIUM confidence)
- sonner library recommendation based on ecosystem knowledge (lightweight, Tailwind-compatible)

## Metadata

**Confidence breakdown:**
- Standard stack: HIGH -- all core libraries already in project, only sonner is new (optional)
- Architecture: HIGH -- patterns directly derived from existing codebase components
- Pitfalls: HIGH -- identified from actual code inspection of hook signatures and data types

**Research date:** 2026-04-06
**Valid until:** 2026-05-06 (stable -- no moving targets, all frontend work against existing backend)