From aba6c6f41aab2cff0377a6a4499f4918c382c41a Mon Sep 17 00:00:00 2001 From: Jean-Luc Makiola Date: Mon, 16 Mar 2026 12:52:24 +0100 Subject: [PATCH] docs(08): capture phase context --- .../08-CONTEXT.md | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 .planning/phases/08-search-filter-and-candidate-status/08-CONTEXT.md diff --git a/.planning/phases/08-search-filter-and-candidate-status/08-CONTEXT.md b/.planning/phases/08-search-filter-and-candidate-status/08-CONTEXT.md new file mode 100644 index 0000000..cda2ad7 --- /dev/null +++ b/.planning/phases/08-search-filter-and-candidate-status/08-CONTEXT.md @@ -0,0 +1,98 @@ +# Phase 8: Search, Filter, and Candidate Status - Context + +**Gathered:** 2026-03-16 +**Status:** Ready for planning + + +## 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. + + + + +## 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) + + + + +## 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 `