# Phase 5: Discovery Navigation Framework - Context

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

<domain>
## Phase Boundary

Establish the discovery-mode system with four modes (By Status Updated, By Ship Date, By Recipient, By Product Shipped), a left-side tab strip for switching, and global keyboard navigation (Up/Down mode cycling, Esc home/reset, Home/End scroll). This phase delivers the navigation shell and mode state machine; actual search, option grids, and filtering are Phase 6.

</domain>

<decisions>
## Implementation Decisions

### Tab panel design
- Slim icon strip (~48px wide), icon-only tabs with tooltip labels on hover showing full mode name.
- Active tab indicated with left accent bar + lighter background highlight (both).
- Always visible — permanent fixture, never auto-hides.
- Positioned below the title bar at the left edge; title bar remains full-width above. Tab strip starts at the same Y as the card grid content region.

### Mode switching behavior
- Instant content swap on mode switch — no animation or transition. Cards immediately replace with new mode's sort order.
- All four modes show the same card set, re-sorted by the mode's criterion (status update date, ship date, recipient name, product shipped).
- Default mode on app launch is By Status Updated.
- Keyboard mode switch (Up/Down arrows) triggers a brief flash/pulse on the newly active tab for confirmation. Click-based switching does not flash.

### Esc behavior
- Esc once: clears any active filters and scrolls to top of current mode (mode home).
- Double-Esc within 500ms window: switches to default mode (By Status Updated). Timed window — not state-based sequential logic.
- Visual feedback on Esc: tab flash + brief toast message (e.g., "Filters cleared" or "Back to Status Updated").

### Keyboard navigation scope
- Home key scrolls to top of card grid; End key scrolls to bottom.
- Global shortcuts (Up/Down/Esc/Home/End) suppressed only when a TextInput has focus (note editing, future search input). All other times, global keys are active.
- Layered Esc dismissal: if summary popup is open, Esc closes popup first. Mode navigation Esc only fires after popup is dismissed.
- Phase 5 keyboard is mode switching only — no card-level keyboard navigation (Tab/arrow within grid).
- App window grabs focus on launch — keyboard shortcuts active immediately without requiring a click.

### Claude's Discretion
- Exact icon choices for the four mode tabs.
- Toast message styling, duration, and positioning.
- Tab flash animation duration and easing.
- Exact tab strip background color and hover states for inactive tabs.

</decisions>

<code_context>
## Existing Code Insights

### Reusable Assets
- `crates/app/src/dashboard/state.rs`: Established enum-based UI state pattern (CardRefreshState, CardEditState, DashboardSelectionState) — natural model for DiscoveryMode enum and mode state machine.
- `crates/app/ui/card.slint`: FocusScope + key-pressed pattern already used for summary popup Esc handler — same pattern extends to global key handling.
- `crates/app/src/dashboard/projection.rs`: Snapshot projection pipeline maps service data to card view models — mode switching will need sort variants in this pipeline.

### Established Patterns
- Dashboard state uses per-card runtime flags in `crates/app/src/dashboard/mod.rs` for transient UI states — discovery mode state fits alongside these.
- Card grid layout in `crates/app/ui/dashboard.slint` uses fixed 3-column manual positioning — adding the tab strip requires adjusting the grid's x-offset and available width.
- PopupWindow close-on-click:false with explicit FocusScope Escape handler — Esc layering must respect this existing pattern.

### Integration Points
- `crates/app/ui/dashboard.slint`: Main layout needs restructuring to add tab strip region left of the card grid.
- `crates/app/src/dashboard/view_model.rs`: Sort order logic per mode will need to be added to the view model layer.
- `crates/app/src/dashboard/mod.rs`: Global keyboard event handling and mode state transitions will live here.

</code_context>

<specifics>
## Specific Ideas

- Tab strip should feel like a permanent rail — always present, never distracting. Think VS Code activity bar energy but slimmer.
- Keyboard-first users should feel the mode switch immediately via the tab flash — no ambiguity about which mode is active after pressing Up/Down.
- Toast messages on Esc give explicit confirmation of what happened ("Filters cleared" vs "Back to Status Updated") so the user never wonders if their keypress registered.

</specifics>

<deferred>
## Deferred Ideas

- Home/End key support for scrolling noted here but may be straightforward enough to include in Phase 5 implementation.
- Card-level keyboard navigation (Tab through cards, arrow keys within grid) — future phase.

</deferred>

---

*Phase: 05-discovery-navigation-framework*
*Context gathered: 2026-03-06*