specs/004-dashboard-filtering/spec.md

Ref: main   Size: 7.0 KiB

# Feature Specification: Dashboard Filtering

**Feature Branch**: `004-dashboard-filtering`
**Created**: 2026-03-21
**Status**: Draft
**Input**: User description: "Allow filtering of issues/patches from dashboard. Add the ability to filter the issue and patch lists in the TUI dashboard. Users should be able to filter by status (open/closed) and search by title text. A '/' key activates a filter/search input bar, typing filters the visible list in real-time. Escape clears the filter. The status bar should show the active filter. This builds on the existing TUI in src/tui.rs."

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Text Search Filtering (Priority: P1)

A user browsing the TUI dashboard has many issues or patches and wants to quickly find a specific one by title. They press `/` to activate search mode, type a few characters, and the list narrows in real-time to show only items whose titles contain the typed text. Pressing Escape exits search mode and clears the filter, restoring the full list.

**Why this priority**: This is the core filtering interaction — without text search, the feature has no value.

**Independent Test**: Can be fully tested by launching the dashboard with multiple items, pressing `/`, typing partial title text, and verifying only matching items appear. Delivers immediate value for navigating large lists.

**Acceptance Scenarios**:

1. **Given** the dashboard is showing a list of issues, **When** the user presses `/`, **Then** a search input bar appears at the bottom of the screen and the dashboard enters search mode.
2. **Given** search mode is active, **When** the user types characters, **Then** the visible list updates in real-time to show only items whose titles contain the typed text (case-insensitive).
3. **Given** search mode is active with a filter applied, **When** the user presses Escape, **Then** the search bar disappears, the filter is cleared, and the full list is restored.
4. **Given** search mode is active, **When** the user presses Backspace, **Then** the last character is removed from the search input and the filter updates accordingly.
5. **Given** a filter is active and no items match, **When** the list is empty, **Then** the detail pane shows a "no matches" indicator.

---

### User Story 2 - Status Filter Cycling (Priority: P2)

A user wants to see only open or only closed issues/patches. They cycle through status filters (open, closed, all) to narrow the list by item state.

**Why this priority**: Status filtering complements text search and helps users focus on actionable items versus historical ones.

**Independent Test**: Can be tested by toggling between status filter modes and verifying the list contents change to reflect only items of the selected status.

**Acceptance Scenarios**:

1. **Given** the dashboard is showing issues, **When** the user cycles the status filter, **Then** the list shows only items matching the selected status (open, closed, or all).
2. **Given** a status filter is active, **When** the user switches tabs, **Then** the status filter applies to the new tab as well.
3. **Given** a status filter is set to "closed", **When** there are no closed items, **Then** the list is empty and the detail pane indicates no items match.

---

### User Story 3 - Combined Filtering with Status Bar Feedback (Priority: P3)

A user applies both a text search and a status filter simultaneously. The status bar at the bottom of the dashboard shows what filters are currently active so the user always knows why the list may be narrowed.

**Why this priority**: Combining filters and showing active filter state prevents confusion and completes the filtering experience.

**Independent Test**: Can be tested by activating both a text search and a status filter, verifying the list shows only items matching both criteria, and confirming the status bar displays the active filters.

**Acceptance Scenarios**:

1. **Given** a text filter "bug" and status filter "open" are both active, **When** the list renders, **Then** only open items with "bug" in their title are shown.
2. **Given** any filter is active, **When** the user looks at the status bar, **Then** it displays the current filter state (e.g., search text and status filter).
3. **Given** filters are active and the user presses Escape, **When** the search bar closes, **Then** the text filter is cleared but the status filter remains.

---

### Edge Cases

- What happens when the user presses `/` while already in search mode? The keypress is treated as a literal `/` character appended to the search input.
- What happens when the user types a very long search string? The input is displayed with truncation to fit the status bar width.
- What happens when items are refreshed (`r` key) while a filter is active? The filter remains applied to the refreshed data.
- What happens when the user navigates to a selected item and then activates a filter that hides it? The selection resets to the first visible item, or clears if no items match.

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: System MUST provide a search mode activated by the `/` key that displays an input bar for typing filter text.
- **FR-002**: System MUST filter the visible list in real-time as the user types, matching against item titles (case-insensitive substring match).
- **FR-003**: System MUST clear the text filter and exit search mode when the user presses Escape.
- **FR-004**: System MUST allow cycling between status filters: open only, closed only, and all.
- **FR-005**: System MUST combine text and status filters — an item must match both criteria to be visible.
- **FR-006**: System MUST display the active filter state in the status bar at the bottom of the dashboard.
- **FR-007**: System MUST reset the list selection to the first matching item when the filter changes cause the current selection to become hidden.
- **FR-008**: System MUST support Backspace to delete characters from the search input while in search mode.
- **FR-009**: System MUST preserve active filters when refreshing data with the `r` key.
- **FR-010**: System MUST apply filters consistently across both the Issues and Patches tabs.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: Users can locate a specific item in a list of 50+ items in under 5 seconds using text search.
- **SC-002**: Filtering feedback is immediate — the list updates with each keystroke with no perceptible delay.
- **SC-003**: Users can determine what filters are active at any time by glancing at the status bar.
- **SC-004**: All existing keyboard shortcuts continue to function when no filter is active (no regressions).

## Assumptions

- The `/` key is not currently bound to any other action in the TUI and is available for search activation.
- Case-insensitive substring matching is sufficient; regex or fuzzy matching is out of scope.
- The existing `show_all` boolean will be replaced or extended by the new status filter cycling mechanism.
- Filter state is ephemeral — it does not persist across dashboard sessions.