<!-- SPDX-FileCopyrightText: 2026 FocusFlow contributors -->
<!-- SPDX-License-Identifier: AGPL-3.0-only -->

# UI Plan 2 Block 05 — Search, Filter, Sort, Group, and Mode Controls

**Goal:** Implement the Backlog top controls shown in the finalized default mockup with safe, deterministic behavior.

---

## Block outcome

After this block, the Backlog screen has working search/filter/sort/group controls that reload or transform the Backlog board without duplicating scheduling rules.

---

## Chunk 5.1 — Search field

### Tasks

Add search field matching the mockup:

- leading search icon,
- placeholder `Search backlog...`,
- dark outlined field,
- clear affordance when text is non-empty if it fits cleanly.

Behavior:

- Debounce user input lightly or trigger search on change if current data size is small.
- Search across title, subtitle/notes preview, project name, and tags.
- Prefer passing `searchText` into the board query so search is part of the read-model request.

### Acceptance criteria

- Typing filters cards and updates summary counts.
- Clearing search restores all tasks.
- Search does not alter persisted task data.

---

## Chunk 5.2 — Filter menu

### Tasks

Implement `Filters` button and popover/menu.

Minimum filters:

- priority: High, Medium, Low,
- project,
- duration bucket,
- bucket/column,
- missing duration,
- no reward set if existing backlog filter supports it.

Behavior:

- Multi-select where useful.
- Apply and clear controls.
- Active filter count may be shown as a small badge if it does not clutter the mockup.
- Filter state should update board columns and summary from the same result set.

### Acceptance criteria

- Filter button opens a dark popover.
- Applying filters updates columns and summary.
- Clearing filters restores default board.
- Filter logic lives in application read policy or safe query layer, not widget-only scheduling logic.

---

## Chunk 5.3 — Sort dropdown

### Tasks

Implement `Sort: Custom` dropdown.

Sort options:

- Custom/default.
- Priority.
- Reward vs Effort.
- Age.
- Project.
- Times Pushed if available.
- Duration if added to board sorting.

Behavior:

- Sort applies inside each bucket by default.
- Do not reorder bucket columns.
- Stable tie-breaker preserves source/read-model order.

### Acceptance criteria

- Sort selection updates card order.
- `Custom` default matches mockup seed ordering.
- Sort state is visible in the control label.

---

## Chunk 5.4 — Group dropdown

### Tasks

Implement `Group: None` dropdown.

Group options:

- None.
- Project.
- Priority.
- Duration.

Behavior:

- `None` is default and matches mockup.
- Non-none group mode adds compact section dividers inside each column or transforms card ordering only if section dividers are visually too disruptive.
- Summary panel remains based on filtered item set, not group sections.

### Acceptance criteria

- Group dropdown opens and changes state.
- Group none returns the exact default visual organization.
- No overflow or large layout jump when grouping.

---

## Chunk 5.5 — Compact/Board toggle and Settings button

### Tasks

Implement the upper-right controls:

- `Compact` segment.
- `Board` segment active.
- `Settings` button.

Behavior:

- Board is active by default.
- If an existing compact backlog list can be safely reused, clicking Compact may swap to that list. Otherwise, keep Compact inert for this plan and document it in the widget callback TODO.
- Settings remains visible and inert unless there is an existing settings screen.

### Acceptance criteria

- Toggle visually matches mockup.
- Board remains active by default.
- Pressing Compact/Settings does not throw.
- Tests assert Board selected state.

---

## Chunk 5.6 — New Task button shell

### Tasks

Add magenta `+ New Task` button with trailing chevron.

Behavior for this block:

- Button calls a callback or opens a placeholder drawer shell.
- Full create task wiring happens in Block 8.
- Dropdown chevron may later expose quick destination choices; do not implement a broad menu unless already designed.

### Acceptance criteria

- Button matches the mockup visually.
- Button has a stable key for tests.
- Button press is safe before full Block 8 wiring.

BREAKPOINT: Stop here if control behavior requires unresolved product decisions about compact mode or filter semantics.

---

## Block acceptance criteria

- Search/filter/sort/group controls are present and safe.
- Default state matches mockup.
- Interactions update or preserve board data predictably.
- No scheduling rules are duplicated in Flutter.

## Validation after block

```sh
cd apps/focus_flow_flutter
flutter analyze
flutter test
```
