# Phase 8: Search, Filter, and Candidate Status - Context

**Gathered:** 2026-03-16
**Status:** Ready for planning

<domain>
## Phase Boundary

Users can find collection items quickly via text search and category filter, track candidate purchase progress with status badges, and use an icon-aware category dropdown on both gear and planning tabs. Side-by-side comparison, ranking, and impact preview are separate phases.

</domain>

<decisions>
## Implementation Decisions

### Search & filter bar
- Sticky toolbar above the item grid on the gear tab, stays visible on scroll
- Search input + category dropdown side by side in the toolbar
- Client-side filtering on every keystroke (no debounce needed for <1000 items)
- Search matches item names only (not category names) — category filtering is the dropdown's job
- When any filter is active, items display as a flat grid (no category group headers)
- Filters reset when switching between gear/planning/setups tabs

### Candidate status
- Three statuses: researching (default), ordered, arrived
- Status badge appears in the existing pill row alongside weight/price/category pills
- Badge shows icon + text label (e.g., magnifying glass + "researching", truck + "ordered", check + "arrived")
- Muted/neutral color scheme for status badges — gray tones, not semantic colors. Color reserved for weight/price pills
- Click the status badge to open a small popup menu showing all three status options (allows jumping to any status, including backward)
- New candidates default to "researching" status
- Requires `status` column on `thread_candidates` table (schema migration)

### Filter feedback
- "Showing X of Y items" count displayed when filters are active — placement at Claude's discretion
- No combined "clear all" button — user clears search text and resets category dropdown individually
- "No items match your search" simple text message for empty filter results (no suggestions)

### Icon-aware category dropdown
- Shared `CategoryFilterDropdown` component used on both gear tab and planning tab
- Separate from the existing `CategoryPicker` component (which is a form combobox for category selection/creation)
- "All categories" as the first option — selecting it clears the category filter
- Searchable dropdown — includes a search input inside the dropdown for filtering categories
- Trigger button shows the selected category's Lucide icon + name when a category is selected

### Claude's Discretion
- Exact toolbar styling (padding, borders, background)
- Filter result count placement (in toolbar or above grid)
- Status popup menu implementation details
- Specific gray tone values for status badges
- Keyboard accessibility patterns for the dropdown and status menu
- Icon choices for status badges (magnifying glass, truck, check are suggestions)

</decisions>

<code_context>
## Existing Code Insights

### Reusable Assets
- `CategoryPicker` (`src/client/components/CategoryPicker.tsx`): Combobox with icon display, search, keyboard nav, and category creation. Pattern reference for the new filter dropdown, but not reusable directly since it's a form input, not a filter
- `LucideIcon` (`src/client/lib/iconData.ts`): Dynamic icon renderer used throughout the app — reuse for dropdown icons and status badges
- `useCategories` hook: Already fetches all categories with icons — drives the dropdown options
- `useItems` hook: Returns all items — client-side filtering can operate on this data
- `CollectionTabs` / `ThreadTabs`: Tab component with pill styling — existing navigation pattern
- `CandidateCard`: Currently has weight/price/category pill row — status badge slots in here

### Established Patterns
- Client-side state for filter/tab state (`useState` in route components, not Zustand)
- URL params for tab navigation (`?tab=gear`)
- React Query for server data, Zustand for UI state (panels/dialogs only)
- Pill badges: blue-50/blue-400 for weight, green-50/green-500 for price, gray-50/gray-600 for category

### Integration Points
- `CollectionView` function in `src/client/routes/collection/index.tsx`: Search/filter toolbar goes here, above the category-grouped items
- `PlanningView` function: Replace existing `<select>` category filter with shared `CategoryFilterDropdown`
- `CandidateCard`: Add status prop and badge to the pill row
- `thread_candidates` table in `src/db/schema.ts`: Add `status` column with default "researching"
- Candidate API routes + services: Need to handle status field in CRUD operations

</code_context>

<specifics>
## Specific Ideas

No specific requirements — open to standard approaches

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

*Phase: 08-search-filter-and-candidate-status*
*Context gathered: 2026-03-16*
