142 lines
7.6 KiB
Markdown
142 lines
7.6 KiB
Markdown
# 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*
|