# 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 `