# Phase 6: Advanced Discovery and Fuzzy Search - Context

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

<domain>
## Phase Boundary

Complete instant search and layered discovery workflows for recipients and products. This phase adds fuzzy search that begins on any keystroke, recipient and product option grids with filtered card-view transitions, and a bottom-bar multi-select filter component. The discovery mode shell (tab strip, Up/Down cycling, Esc behavior) was delivered in Phase 5; this phase fills in the interactive content within each mode.

</domain>

<decisions>
## Implementation Decisions

### Fuzzy search activation & display
- Always-visible search bar positioned inline with the "Refresh All" button, above the card grid area.
- Search bar auto-focuses when the user starts typing any character — no explicit Ctrl+F or click-to-activate needed.
- Search matches against recipient name and item/product summary fields (not notes or status text).
- Results shown by filtering cards in-place — non-matching cards are removed from the grid, grid re-layouts to show only matches.
- Result count badge displayed near the search input (e.g., "12 results") as feedback while typing.
- Search is global across all modes — always filters against ALL cards regardless of active discovery mode.

### Option grid layout
- **By Recipient mode:** Alphabetical tile grid with A-Z section headers. Clickable name tiles arranged in a responsive grid, grouped alphabetically.
- **By Product Shipped mode:** Tile grid with item image thumbnails alongside product names. Visually richer than recipient grid to leverage existing image data.
- Fuzzy search also filters option grid tiles — typing in the search bar while on the option grid hides non-matching tiles.

### Grid-to-card transition
- Clicking an option tile replaces the option grid with filtered card view showing only matching cards.
- A breadcrumb or back-arrow at top indicates filtered state.
- Esc returns from filtered card view back to the option grid.

### Bottom bar multi-select filtering
- Horizontal chip bar along the bottom edge of the card grid area.
- Chips are toggleable — selected chips are highlighted with the accent color.
- Available in ALL four discovery modes, not just Recipient and Product.
- All modes include status values (Not Shipped, Label Created, In Transit, Delivered, Return In Transit, Returned) as a universal filter dimension in the chip bar.
- Multi-select logic: Claude's discretion (OR/union is the natural fit since recipients and products are disjoint per card).
- Horizontal scroll when chips overflow — single row, compact fixed height. Subtle scroll indicator at edges.

### Per-mode state persistence
- Search text persists per-mode — each discovery mode remembers its own search text. Switching away and back restores the previous search text for that mode.
- Bottom-bar filter selections also persist per-mode — each mode remembers its own chip selections independently.

### Esc behavior (extending Phase 5)
- Three-layer Esc dismissal when search is active:
  1. First Esc: defocuses the search input (search text remains visible, cards stay filtered).
  2. Second Esc: clears the search text (restores unfiltered view for current mode).
  3. Third Esc: mode home (clears bottom-bar filters, scrolls to top).
- Double-Esc within 500ms window still resets to default mode (By Status Updated) — this Phase 5 behavior is preserved.
- If in filtered card view (from option grid tile click), Esc returns to the option grid before clearing search.

### Claude's Discretion
- Fuzzy matching algorithm choice (substring, trigram, edit distance).
- Search debounce timing.
- Exact chip bar height, spacing, and scroll indicator styling.
- Breadcrumb/back-arrow design in filtered card view.
- How option grid tiles respond to hover/focus states.
- Tile grid column count and responsive breakpoints.
- How the result count badge is positioned and styled.

</decisions>

<code_context>
## Existing Code Insights

### Reusable Assets
- `crates/app/src/dashboard/discovery.rs`: `DiscoveryMode` enum with `next()`, `prev()`, `index()`, `label()` methods; `DiscoveryState` with Esc timing logic; `sort_cards_by_mode()` — all directly extended for Phase 6.
- `crates/app/src/dashboard/projection.rs`: Snapshot projection pipeline and `sort_cards_by_mode` re-export — search filtering can layer on top of mode sorting.
- `crates/app/ui/dashboard.slint`: Global FocusScope with key-pressed handler, Flickable card grid, toast overlay — search bar and bottom bar add to this layout.
- `crates/app/ui/tab-strip.slint`: Tab strip component with active-index and flash-active — no changes needed but integration point for mode switching.

### Established Patterns
- Dark mode palette: `#1a1e2a` background, `#242838` cards, `#4a7cff` accent — all new UI (search bar, tiles, chips) should use this palette.
- `text-input-focused` property on DashboardWindow suppresses global key handlers — search TextInput will set this when focused.
- Per-card view model (`DashboardCardViewModel`) with `recipient_name`, `item_summary` fields — these are the fuzzy match targets.
- Toast overlay pattern at bottom-center — can coexist with bottom chip bar (toast floats above).

### Integration Points
- `crates/app/ui/dashboard.slint`: Add search bar component above card grid, option grid as alternative content area, bottom chip bar below card grid.
- `crates/app/src/dashboard/discovery.rs`: Extend `DiscoveryState` with per-mode search text, filter selections, and view state (option grid vs filtered cards).
- `crates/app/src/dashboard/mod.rs`: Wire search input callbacks, tile click handlers, chip toggle handlers, and extended Esc layering logic.
- `crates/app/src/dashboard/view_model.rs`: Add search/filter projection that combines fuzzy match + mode sort + bottom-bar filter.

</code_context>

<specifics>
## Specific Ideas

- Search bar should feel like it's always there and ready — not a hidden feature that needs discovering. The user just starts typing.
- Option grids should feel like a quick phonebook-style lookup — scan alphabetically, click, see the cards. Not a complex filtering UI.
- Bottom bar chips should feel lightweight — quick toggles, not a configuration panel. Status chips are universal across all modes.
- Per-mode state persistence means the user can jump between modes without losing their place — each mode is like its own workspace.

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope.

</deferred>

---

*Phase: 06-advanced-discovery-and-fuzzy-search*
*Context gathered: 2026-03-07*