GearBox/.planning/phases/20-fab-full-screen-catalog-search/20-CONTEXT.md

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

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

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

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

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

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

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

---

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