# Phase 20: FAB & Full-Screen Catalog Search - Context

**Gathered:** 2026-04-06
**Status:** Ready for planning

<domain>
## Phase Boundary

Replace the current single-action FAB with a global floating action button that shows a mini menu with "Add to Collection" and "Start Thread" options (plus "New Setup" on the setups page). Both options open the same full-screen catalog search overlay with tag filtering. The search overlay shows catalog items with key specs and an "Add" button. This phase builds the discovery UI — the actual add-to-collection and add-to-thread actions are wired in Phase 21.

</domain>

<decisions>
## Implementation Decisions

### FAB Mini Menu
- **D-01:** FAB becomes globally visible on all pages (not just collection view). Position stays `fixed bottom-6 right-6`.
- **D-02:** Tapping FAB opens a mini menu: 2-3 labeled icon buttons fan out vertically above the FAB. Backdrop dims slightly. Tapping backdrop or FAB again closes the menu.
- **D-03:** Menu options: "Add to Collection" (package icon) and "Start New Thread" (search icon). On setups page only, a third option "New Setup" appears.
- **D-04:** Both "Add to Collection" and "Start New Thread" open the same full-screen catalog search overlay, with a `mode` parameter ("collection" or "thread") stored in UIStore.
- **D-05:** "New Setup" triggers the existing setup creation flow (no catalog search needed).
- **D-06:** FAB should not appear on login page or public profile/setup pages (only authenticated routes).

### Full-Screen Catalog Search Overlay
- **D-07:** Implemented as a full-screen overlay (`fixed inset-0 z-50`) managed by UIStore state (`catalogSearchOpen`, `catalogSearchMode`), not a route change. Matches existing modal patterns (CreateThreadModal).
- **D-08:** Layout: back arrow (top-left, closes overlay) + large search input + context indicator text ("Adding to Collection" or "Starting Thread").
- **D-09:** Below search bar: horizontal scrollable row of tag chips for quick filtering.
- **D-10:** Results area: grid of compact cards showing brand + model, weight, price, owner count, and an "Add" button.
- **D-11:** Search queries the existing `GET /api/global-items?q=...&tags=...` endpoint (built in Phase 19).
- **D-12:** Empty state: helpful message when no results, with "Add Manually" link (Phase 22 wires this).
- **D-13:** Loading state: skeleton cards matching the result grid pattern.

### Tag Chips
- **D-14:** Tags fetched from a new `GET /api/tags` endpoint (returns all tags, lightweight).
- **D-15:** Displayed as horizontal scrollable row of `rounded-full` chips. Tapping toggles active state (highlighted). Multiple tags can be active (AND filtering).
- **D-16:** Active chips use a distinct color (e.g., `bg-blue-100 text-blue-700`) vs inactive (`bg-gray-100 text-gray-500`).
- **D-17:** Quick-access chips show common/popular tags first. Could be sorted alphabetically or by frequency — Claude's discretion.

### Search Result Cards
- **D-18:** Reuse/adapt the existing `GlobalItemCard` component pattern — brand + model as title, weight/price/category badges, owner count.
- **D-19:** Each card has an "Add" or "+" button. In Phase 20, this button is present but the action is a stub (Phase 21 wires the actual add flow).
- **D-20:** Cards should be responsive — 1 column on mobile, 2-3 on desktop.

### UIStore Changes
- **D-21:** New state: `catalogSearchOpen: boolean`, `catalogSearchMode: "collection" | "thread" | null`.
- **D-22:** New actions: `openCatalogSearch(mode)`, `closeCatalogSearch()`.
- **D-23:** FAB menu state: `fabMenuOpen: boolean`, `openFabMenu()`, `closeFabMenu()`.

### API Addition
- **D-24:** New endpoint `GET /api/tags` — returns all tags as `{ id, name }[]`. Public (no auth needed, follows GET pattern). Lightweight, cacheable.

### Claude's Discretion
- Animation style for FAB menu (spring, ease, duration)
- Exact tag chip ordering strategy
- Card grid gap and sizing details
- Whether to debounce search input (recommendation: yes, 300ms like existing pattern)
- Skeleton card count during loading
- Whether "Add Manually" link is visible in Phase 20 or deferred entirely to Phase 22

</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 20 implements the FAB and search overlay described in Flow 1.

### Current FAB & Root Layout
- `src/client/routes/__root.tsx` — Current FAB implementation (lines 256-278), root layout structure
- `src/client/stores/uiStore.ts` — UI state management — add catalogSearch and fabMenu states here

### Existing Components to Reuse/Adapt
- `src/client/components/GlobalItemCard.tsx` — Card component with badge pattern for weight/price/category
- `src/client/components/CreateThreadModal.tsx` — Full-screen overlay pattern (fixed inset-0 z-50)
- `src/client/routes/global-items/index.tsx` — Existing catalog search page with debounced input

### API
- `src/server/routes/global-items.ts` — Existing search endpoint to query from overlay
- `src/server/services/global-item.service.ts` — Search with tag filtering (Phase 19)

### Schema
- `src/db/schema.ts` — Tags table for the new GET /api/tags endpoint

### Requirements
- `.planning/REQUIREMENTS.md` — CATFLOW-01, CATFLOW-02

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `GlobalItemCard` — badge pattern (rounded-full chips for weight, price, category) directly applicable for search results
- `CreateThreadModal` — overlay pattern (fixed inset-0 z-50, bg-black/50 backdrop) for the search overlay
- `uiStore.ts` — Zustand store pattern for panel/dialog state, extend with catalog search state
- `useGlobalItems(query)` hook — existing TanStack Query hook for global item search
- Debounce pattern from `global-items/index.tsx` — 300ms timer on search input

### Established Patterns
- Tailwind CSS v4 with light/airy minimalist design (white backgrounds, lots of whitespace)
- Framer Motion for animations (slideVariants in collection, AnimatePresence)
- `rounded-full` chips with color variants for metadata badges
- Fixed position overlays with z-index layering (z-30 backdrop, z-40 panels, z-50 modals)

### Integration Points
- `src/client/routes/__root.tsx` — FAB lives here, needs mini menu upgrade
- `src/client/stores/uiStore.ts` — Add new state slices
- `src/client/hooks/` — Add `useTags()` hook for tag fetching
- `src/server/routes/` — Add tags route or extend global-items route
- `src/server/index.ts` — Register new route if separate tags route

</code_context>

<specifics>
## Specific Ideas

- The FAB mini menu should feel snappy and native — small animation when items appear, not a heavy modal feel.
- The search overlay should feel like a full takeover, similar to how mobile apps handle search (think Google search, App Store search).
- Tag chips should be visually distinct from the result card badges — they're interactive filters, not just display.
- The "Add" button on cards is a stub in this phase — it should look clickable but the actual flow (confirmation step for collection, instant add for threads) is Phase 21.

</specifics>

<deferred>
## Deferred Ideas

- "Add Manually" link wiring — Phase 22
- Actual add-to-collection flow (confirmation step with category picker) — Phase 21
- Actual add-to-thread flow (instant candidate creation) — Phase 21
- Search result sorting/ordering options
- Recent searches or search history
- "Popular items" section when search is empty

</deferred>

---

*Phase: 20-fab-full-screen-catalog-search*
*Context gathered: 2026-04-06*
