diff --git a/.planning/phases/23-manual-entry-fallback/23-RESEARCH.md b/.planning/phases/23-manual-entry-fallback/23-RESEARCH.md new file mode 100644 index 0000000..de30480 --- /dev/null +++ b/.planning/phases/23-manual-entry-fallback/23-RESEARCH.md @@ -0,0 +1,515 @@ +# Phase 23: Manual Entry Fallback - Research + +**Researched:** 2026-04-06 +**Domain:** React UI — inline form view state within CatalogSearchOverlay +**Confidence:** HIGH + +## Summary + +Phase 23 is a pure frontend phase. The goal is to give users a way to add items that do not exist in the global catalog by surfacing a manual entry form inline inside the CatalogSearchOverlay. The backend is already fully capable — `POST /api/items` without a `globalItemId` creates a standalone collection item, and `createItemSchema` accepts the call without that field. Nothing on the server needs to change. + +The implementation has two distinct layers. First, the entry points: an "Add Manually" link in the EmptyState component and a persistent but subtle link below the results area. Second, the inline form view: a new `ManualEntryForm` component rendered inside `CatalogSearchOverlay` when `manualEntryMode` state is true. The form reuses established patterns from `ItemForm` and `AddToCollectionModal` but is lighter and more focused. After a successful save, the results area is replaced by a success card with a non-functional "Submit to Catalog?" button and "Add Another" / "Done" actions. + +There is no new route, no new API endpoint, and no Zustand store change required. All view-switching state is local to `CatalogSearchOverlay` via `useState`. This is the simplest possible scope for the phase. + +**Primary recommendation:** Implement the entire phase as local state inside CatalogSearchOverlay — `manualEntryMode: boolean` and `savedItemName: string | null` — with a new sibling component file `ManualEntryForm.tsx`. + +--- + + +## User Constraints (from CONTEXT.md) + +### Locked Decisions + +- **D-01:** "Add Manually" link appears in the catalog search empty state (when no results match) AND as a subtle persistent link below search results. +- **D-02:** Link text is "Add Manually" or "Can't find it? Add manually" — context-sensitive based on whether a search query exists. +- **D-03:** Manual entry form replaces the search results area inline within CatalogSearchOverlay. No navigation away or additional modal. +- **D-04:** Back arrow at the top returns from the manual form to search results. +- **D-05:** The form is a dedicated ManualEntryForm component rendered inside CatalogSearchOverlay when `manualEntryMode` state is active. +- **D-06:** Required: name. Optional: category (via CategoryPicker), weight (grams), price (cents), notes, purchase price, image upload, product link. +- **D-07:** Reuse field patterns from ItemForm (CategoryPicker, weight/price inputs) but keep the form focused and compact — not the full 315-line ItemForm. +- **D-08:** Submit calls `POST /api/items` without `globalItemId` — creates a standalone collection item. +- **D-09:** After successful save, show an inline success card: "Added [item name] to collection" with a "Submit to Catalog?" button. +- **D-10:** "Submit to Catalog?" button is non-functional — shows a toast "Coming soon" when clicked. No backend action. +- **D-11:** Below the prompt, show "Add Another" (returns to search) and "Done" (closes overlay) buttons. + +### Claude's Discretion + +- Exact form layout proportions and field ordering +- Whether weight/price fields use formatted inputs or plain number inputs +- Animation transitions between search results and manual entry form +- Success card visual styling +- Whether the search query auto-populates the item name field when entering manual mode + +### Deferred Ideas (OUT OF SCOPE) + +- Actual catalog submission backend (admin review, convert to global item) — future phase +- Bulk manual entry — future phase +- Image search / URL paste to auto-populate item details — future phase + + +--- + + +## Phase Requirements + +| ID | Description | Research Support | +|----|-------------|------------------| +| CATFLOW-07 | Manual entry fallback when item not in catalog | Implemented via `manualEntryMode` local state in CatalogSearchOverlay + ManualEntryForm component; `useCreateItem()` hook + `POST /api/items` without `globalItemId` already supported | +| CATFLOW-08 | Non-functional "Submit to catalog?" prompt shown after manual save | Implemented as an inline success card within CatalogSearchOverlay after mutation success; "Submit to Catalog?" button calls `toast("Coming soon")` | + + +--- + +## Standard Stack + +### Core +| Library | Version | Purpose | Why Standard | +|---------|---------|---------|--------------| +| React | 19 (project) | Component rendering and local state | Project stack | +| TanStack React Query | project version | `useCreateItem()` mutation | Established data layer | +| Framer Motion | project version | Animation between search/form views | Already used in CatalogSearchOverlay | +| sonner `toast` | project version | Success/error/coming-soon notifications | Established project pattern | +| Zustand | project version | Overlay open/close state (no change needed) | Established UI state pattern | + +### Supporting +| Library | Version | Purpose | When to Use | +|---------|---------|---------|-------------| +| CategoryPicker | internal | Category selection with search + inline create | Required by D-06 | +| ImageUpload | internal | Image upload with preview | Required by D-06 | + +### Alternatives Considered +| Instead of | Could Use | Tradeoff | +|------------|-----------|----------| +| Local `useState` for mode switching | Zustand UIStore | Local state is simpler; no cross-component coordination needed; CONTEXT.md D-05 implies local state | + +**Installation:** No new packages needed. + +## Architecture Patterns + +### Recommended Project Structure + +No new directories. Two new files: + +``` +src/client/components/ +├── CatalogSearchOverlay.tsx # Modified — add mode state, entry points, conditional rendering +└── ManualEntryForm.tsx # New — standalone form component for manual item entry +``` + +### Pattern 1: Inline View Switching via Local State + +**What:** CatalogSearchOverlay already uses local `useState` for `viewMode`, `filterOpen`, `searchInput`, etc. The same pattern extends naturally to `manualEntryMode`. + +**When to use:** When an overlay needs to transition between views without navigating or spawning a new modal layer. + +**Example:** +```typescript +// Inside CatalogSearchOverlay +const [manualEntryMode, setManualEntryMode] = useState(false); +const [savedItemName, setSavedItemName] = useState(null); + +// Reset when overlay closes (add to existing reset effect) +useEffect(() => { + if (!catalogSearchOpen) { + setManualEntryMode(false); + setSavedItemName(null); + // ... existing resets + } +}, [catalogSearchOpen]); + +// Render switch +{manualEntryMode + ? savedItemName + ? + : + : +} +``` + +**Source:** CatalogSearchOverlay.tsx existing local state pattern (verified by reading the file). + +### Pattern 2: Compact Form Adapted from ItemForm + +**What:** ManualEntryForm mirrors ItemForm's field patterns (validation, CategoryPicker, weight/price conversion) but is a lighter self-contained component — not tied to UIStore. + +**Key adaptation from ItemForm:** +- No `mode: "add" | "edit"` — always add-only +- No `useItems()` call — no need for pre-fill +- No delete button +- Accepts `initialName` prop (auto-populated from search query per CONTEXT.md specifics) +- Accepts `onSuccess(itemName: string)` and `onBack()` callbacks +- `purchasePriceCents` field (from AddToCollectionModal) added alongside the regular `priceCents` field + +**Example component signature:** +```typescript +interface ManualEntryFormProps { + initialName?: string; + onSuccess: (itemName: string) => void; + onBack: () => void; +} +``` + +**Source:** Verified by reading `src/client/components/ItemForm.tsx` and `src/client/components/AddToCollectionModal.tsx`. + +### Pattern 3: useCreateItem without globalItemId + +**What:** The existing `useCreateItem()` mutation accepts `CreateItem` from `src/shared/types`. The `createItemSchema` in `src/shared/schemas.ts` defines `globalItemId` as `.optional()`, so omitting it is fully valid. + +**Example:** +```typescript +createItem.mutate({ + name: form.name.trim(), + categoryId: form.categoryId, + weightGrams: form.weightGrams ? Number(form.weightGrams) : undefined, + priceCents: form.priceDollars ? Math.round(Number(form.priceDollars) * 100) : undefined, + notes: form.notes || undefined, + productUrl: form.productUrl || undefined, + imageFilename: form.imageFilename ?? undefined, + purchasePriceCents: form.purchasePrice ? Math.round(Number(form.purchasePrice) * 100) : undefined, + // globalItemId deliberately omitted +}, { + onSuccess: (item) => onSuccess(item.name), + onError: (err) => setError(err instanceof Error ? err.message : "Failed to save"), +}); +``` + +**Source:** `src/shared/schemas.ts` line 13 (`globalItemId: z.number().int().positive().optional()`), `src/client/hooks/useItems.ts` lines 62-72. + +### Pattern 4: "Add Manually" Entry Points + +**What:** Two placements per D-01 — inside EmptyState and as a persistent link below results. + +**EmptyState adaptation** (line 667 in CatalogSearchOverlay.tsx): +```typescript +function EmptyState({ hasQuery, onAddManually }: { + hasQuery: boolean; + onAddManually: () => void; +}) { + return ( +
+ {/* existing icon + text */} + +
+ ); +} +``` + +**Persistent link below results:** A `div` rendered after the results grid/list, always visible when not in manual entry mode. + +### Pattern 5: Toast for Non-functional Button + +**What:** The "Submit to Catalog?" button (D-10) calls `toast()` from sonner — no backend call. + +```typescript +import { toast } from "sonner"; +// ... + +``` + +**Source:** `toast` from `sonner` is the established project notification mechanism (confirmed in AddToCollectionModal.tsx and CatalogSearchOverlay usage patterns). + +### Anti-Patterns to Avoid + +- **Adding manualEntryMode to Zustand UIStore:** Unnecessary. No other component needs to read this state. CONTEXT.md D-05 says it's local to CatalogSearchOverlay. +- **Reusing ItemForm directly:** ItemForm is 315 lines, tied to UIStore, and has edit/delete logic not needed here. Adapt the patterns, build a fresh focused component. +- **Making the form a full-screen overlay on top of the overlay:** The overlay stays. The form replaces the results area content only (D-03). +- **Emitting a success toast AND showing the success card:** Don't double-notify. The success card IS the success feedback. Skip the `toast.success()` call here (unlike AddToCollectionModal which just closes and toasts). + +## Don't Hand-Roll + +| Problem | Don't Build | Use Instead | Why | +|---------|-------------|-------------|-----| +| Category selection | Custom select | `CategoryPicker` | Has search, inline create, icon display | +| Image upload | Custom file input | `ImageUpload` | Handles upload API call, preview, size validation | +| Price/weight conversion | Custom logic | Adapt from ItemForm | Established pattern: `Math.round(Number(dollars) * 100)` | +| Toast notifications | Custom UI | `toast` from sonner | Global notification system already wired | +| Item creation API call | Custom fetch | `useCreateItem()` | Handles query invalidation, error states | + +**Key insight:** This phase is almost entirely wiring — the building blocks (mutation hook, form components, toast) exist. The work is composing them into a new view state inside CatalogSearchOverlay. + +## Common Pitfalls + +### Pitfall 1: Forgetting to Reset manualEntryMode on Overlay Close + +**What goes wrong:** User closes overlay, reopens it, and the manual entry form is still showing instead of search results. + +**Why it happens:** The reset `useEffect` (lines 76-87 in CatalogSearchOverlay) clears search/filter state when `catalogSearchOpen` changes to false — but new state like `manualEntryMode` and `savedItemName` won't be in that effect unless explicitly added. + +**How to avoid:** Add `setManualEntryMode(false)` and `setSavedItemName(null)` to the existing reset effect that triggers on `!catalogSearchOpen`. + +**Warning signs:** State persists across overlay open/close cycles during testing. + +### Pitfall 2: "Submit to Catalog?" Button Appearing Functional + +**What goes wrong:** A loading spinner, disabled state, or API call is added to the "Submit to Catalog?" button, setting a false expectation. + +**Why it happens:** Developer instinct to make buttons "do something properly." + +**How to avoid:** The button calls `toast("Coming soon")` and nothing else (D-10). No `isPending`, no `disabled`, no API call. + +### Pitfall 3: Back Arrow Wiring + +**What goes wrong:** Back arrow on ManualEntryForm calls `closeCatalogSearch()` instead of returning to search results. + +**Why it happens:** CatalogSearchOverlay already has a back arrow in the header that closes the overlay. ManualEntryForm needs its own back behavior that sets `manualEntryMode(false)`. + +**How to avoid:** The ManualEntryForm header renders its own back arrow button that calls the `onBack` prop — `setManualEntryMode(false)`. Alternatively, CatalogSearchOverlay can make its existing header back arrow context-sensitive: when `manualEntryMode`, go back to results; otherwise close overlay. + +**Warning signs:** Pressing back from the manual form closes the entire overlay instead of returning to search. + +### Pitfall 4: categoryId Validation + +**What goes wrong:** `CategoryPicker` is initialized with `value={0}` which doesn't correspond to a real category, causing `categoryId: 0` to be submitted — this will fail the Zod schema (`z.number().int().positive()`). + +**Why it happens:** Same issue exists in AddToCollectionModal (solved by pre-selecting `categories[0].id` once data loads). + +**How to avoid:** Follow the AddToCollectionModal pattern — initialize `categoryId` as `null`, pre-select `categories[0].id` once categories data loads, block form submission if `categoryId === null`. + +### Pitfall 5: Search Query Not Auto-Populating Item Name + +**What goes wrong:** User types "Ortlieb Gravel Pack" in the search, gets no results, clicks "Add Manually" — the name field is empty. User must retype the name. + +**Why it happens:** `searchInput` is local state in CatalogSearchOverlay and `ManualEntryForm` doesn't receive it. + +**How to avoid:** Pass `searchInput` (or `debouncedQuery`) as the `initialName` prop to `ManualEntryForm`. The CONTEXT.md specifics section explicitly calls this out. This is a Claude's Discretion item but the CONTEXT.md says it "should" happen. + +## Code Examples + +### ManualEntryForm: Minimal Skeleton + +```typescript +// Source: adapted from src/client/components/ItemForm.tsx + AddToCollectionModal.tsx +import { useEffect, useState } from "react"; +import { ArrowLeft } from "lucide-react"; +import { useCategories } from "../hooks/useCategories"; +import { useCreateItem } from "../hooks/useItems"; +import { CategoryPicker } from "./CategoryPicker"; +import { ImageUpload } from "./ImageUpload"; + +interface ManualEntryFormProps { + initialName?: string; + onSuccess: (itemName: string) => void; + onBack: () => void; +} + +export function ManualEntryForm({ initialName, onSuccess, onBack }: ManualEntryFormProps) { + const { data: categories } = useCategories(); + const createItem = useCreateItem(); + + const [name, setName] = useState(initialName ?? ""); + const [categoryId, setCategoryId] = useState(null); + const [weightGrams, setWeightGrams] = useState(""); + const [priceDollars, setPriceDollars] = useState(""); + const [purchasePrice, setPurchasePrice] = useState(""); + const [notes, setNotes] = useState(""); + const [productUrl, setProductUrl] = useState(""); + const [imageFilename, setImageFilename] = useState(null); + const [error, setError] = useState(null); + + useEffect(() => { + if (categories && categories.length > 0 && categoryId === null) { + setCategoryId(categories[0].id); + } + }, [categories, categoryId]); + + function handleSubmit(e: React.FormEvent) { + e.preventDefault(); + if (!name.trim()) { setError("Name is required"); return; } + if (categoryId === null) { setError("Select a category"); return; } + setError(null); + + createItem.mutate({ + name: name.trim(), + categoryId, + weightGrams: weightGrams ? Number(weightGrams) : undefined, + priceCents: priceDollars ? Math.round(Number(priceDollars) * 100) : undefined, + purchasePriceCents: purchasePrice ? Math.round(Number(purchasePrice) * 100) : undefined, + notes: notes || undefined, + productUrl: productUrl || undefined, + imageFilename: imageFilename ?? undefined, + // globalItemId omitted — standalone item + }, { + onSuccess: (item) => onSuccess(item.name), + onError: (err) => setError(err instanceof Error ? err.message : "Failed to save"), + }); + } + + // ... render +} +``` + +### CatalogSearchOverlay: Mode Switch Wiring + +```typescript +// Source: pattern from CatalogSearchOverlay.tsx local state +const [manualEntryMode, setManualEntryMode] = useState(false); +const [savedItemName, setSavedItemName] = useState(null); + +// In existing reset effect: +useEffect(() => { + if (!catalogSearchOpen) { + // ...existing resets... + setManualEntryMode(false); + setSavedItemName(null); + } +}, [catalogSearchOpen]); + +function handleEnterManualMode() { + setManualEntryMode(true); +} + +function handleManualSuccess(itemName: string) { + setSavedItemName(itemName); +} + +function handleAddAnother() { + setManualEntryMode(false); + setSavedItemName(null); +} +``` + +### EmptyState with "Add Manually" Link + +```typescript +// Source: adapted from CatalogSearchOverlay.tsx EmptyState (line 667) +function EmptyState({ hasQuery, onAddManually }: { + hasQuery: boolean; + onAddManually: () => void; +}) { + return ( +
+ {/* existing SVG icon */} +

+ {hasQuery ? "No items found matching your search" : "Search the catalog to find gear"} +

+ +
+ ); +} +``` + +## State of the Art + +| Old Approach | Current Approach | When Changed | Impact | +|--------------|------------------|--------------|--------| +| Static EmptyState (no action) | EmptyState with "Add Manually" CTA | Phase 23 | Removes dead end for missing catalog items | +| No manual path in catalog flow | Inline ManualEntryForm in overlay | Phase 23 | Completes CATFLOW requirements | + +**What changes in Phase 23:** +- `EmptyState` — accepts `onAddManually` prop, gains a text button +- `CatalogSearchOverlay` — gains `manualEntryMode` + `savedItemName` local state, renders ManualEntryForm or SuccessCard conditionally +- New file: `ManualEntryForm.tsx` + +## Open Questions + +1. **Back arrow context-sensitivity** + - What we know: CatalogSearchOverlay header already has a back arrow that calls `closeCatalogSearch()`. ManualEntryForm needs to go back to results, not close the overlay (D-04). + - What's unclear: Whether the planner should (a) make the header back arrow context-aware based on `manualEntryMode`, or (b) have ManualEntryForm render its own internal back arrow in the form header and keep the outer header arrow always closing. + - Recommendation: Option (b) — ManualEntryForm has its own back arrow row (like CatalogSearchOverlay's context text row) to preserve single-responsibility. The planner should specify this explicitly. + +2. **"Add Manually" link in thread mode** + - What we know: `catalogSearchMode` can be "collection" or "thread". The CONTEXT.md does not restrict manual entry to collection mode only. + - What's unclear: If the user is in "thread" mode (adding candidates), does "Add Manually" create a standalone collection item (D-08) or a thread candidate? + - Recommendation: D-08 locks this to `POST /api/items` (collection item), regardless of mode. The planner should note this explicitly to avoid an implementation where thread mode triggers candidate creation instead. + +## Environment Availability + +Step 2.6: SKIPPED — phase is purely frontend code changes with no external tool or service dependencies beyond the existing dev environment. + +## Validation Architecture + +### Test Framework + +| Property | Value | +|----------|-------| +| Framework | Bun test (unit/integration) + Playwright (E2E) | +| Config file | `bunfig.toml` (Bun default), `playwright.config.ts` | +| 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-07 | ManualEntryForm submits `POST /api/items` without `globalItemId` | Integration (service) | `bun test tests/services/item.service.test.ts` | Partial — item creation without globalItemId covered by existing "only name and categoryId are required" test | +| CATFLOW-07 | "Add Manually" link visible in EmptyState | E2E (smoke) | `bun run test:e2e` (collection.spec.ts) | Needs Wave 0 addition | +| CATFLOW-07 | ManualEntryForm renders in overlay on click | E2E | `bun run test:e2e` | Needs Wave 0 addition | +| CATFLOW-07 | Back arrow returns to search results | E2E | `bun run test:e2e` | Needs Wave 0 addition | +| CATFLOW-08 | "Submit to Catalog?" shows "Coming soon" toast | E2E | `bun run test:e2e` | Needs Wave 0 addition | +| CATFLOW-08 | Success card shown after manual save | E2E | `bun run test:e2e` | Needs Wave 0 addition | + +> Note: The backend `createItem` service already has tests covering the standalone item path (no `globalItemId`). The existing test "only name and categoryId are required" (item.service.test.ts line 44) covers CATFLOW-07 at the service layer. The gaps are E2E tests covering the new UI flow. + +### Sampling Rate + +- **Per task commit:** `bun test tests/services/item.service.test.ts` +- **Per wave merge:** `bun test` +- **Phase gate:** `bun test && bun run test:e2e` green before `/gsd:verify-work` + +### Wave 0 Gaps + +- [ ] `e2e/collection.spec.ts` — add test cases for manual entry flow (Add Manually link, ManualEntryForm render, back navigation, success card, Submit to Catalog toast) + +*(Service-level test infrastructure covers the backend path — no new test files needed there. E2E additions only.)* + +## Project Constraints (from CLAUDE.md) + +All directives from CLAUDE.md that apply to this phase: + +| Constraint | Impact on Phase 23 | +|-----------|-------------------| +| Reuse existing components (CategoryPicker, ImageUpload, etc.) | ManualEntryForm MUST use CategoryPicker and ImageUpload — not plain `