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


# Date Selection 01 Block 02 — Selected-Date State and Reads

**Status:** Complete.
**Goal:** Make Today screen loading date-aware without changing task state.

---

## Block outcome

After this block, app/controller code can load Today data for any selected
`CivilDate`. The visual top-bar buttons may still be disabled until Block 03.

Implementation notes:

1. Added `SelectedDateController` with no-op repeated selection and explicit
   previous/next day movement.
2. Made `TodayScreenController` read through the selected date, clear selected
   cards on date change, and protect newer loads from stale in-flight reads.
3. Added controller coverage for direct selection, previous/next, empty reads,
   failures, and rapid navigation.

---

## Chunk 2.1 — Add selected-date state API

### Tasks

1. Add the selected-date owner chosen in Block 01.
2. Expose the current selected `CivilDate`.
3. Expose commands to:
   - select a specific date,
   - move to previous day,
   - move to next day,
   - optionally return to current owner-local day if the current UI has a
     calendar/today affordance.
4. Ensure repeated selection of the current date is a no-op.
5. Ensure date changes notify exactly the controllers/widgets that need a
   reload.

### Acceptance criteria

- Date state can be tested without rendering the full app.
- Date mutation does not call scheduler command use cases.
- Date mutation can trigger read refresh in one predictable place.

---

## Chunk 2.2 — Make Today reads accept a date parameter

### Tasks

1. Replace fixed-date read callbacks with date-aware read callbacks, for example:
   `Future<ApplicationResult<TodayState>> Function(CivilDate date)`.
2. Update `TodayScreenController.load` or equivalent to load the selected date.
3. Keep `GetTodayStateRequest.date` as the canonical read parameter.
4. Preserve `includeNextFlexibleItem: true` unless a later product decision
   changes it.
5. Avoid filtering persisted tasks in widgets to simulate a day switch.

### Acceptance criteria

- Loading July 2 and July 3 calls the backend query twice with distinct
  `CivilDate` values.
- The controller maps each returned `TodayState` into `TodayScreenData` normally.
- Empty state for a selected date still shows the selected date label.

---

## Chunk 2.3 — Sync modal selection and timeline scroll state on date changes

### Tasks

1. Decide whether selected task modals should close on date change or resync only
   if the same task still appears on the new day.
2. Preferred V1 behavior: clear selected card when selected date changes.
3. Reset timeline scroll target/request state when switching days unless a
   specific target is requested after read refresh.
4. Ensure date changes cannot leave a modal open for a task that is no longer in
   `TodayScreenData.cards`.

### Acceptance criteria

- Open task modal closes when moving to another date.
- Timeline cards from the previous date are not reused after reload.
- No stale selected-card exception appears during rapid date changes.

---

## Chunk 2.4 — Preserve loading, empty, and failure states per selected date

### Tasks

1. Show loading while the selected date's read is in progress.
2. Show empty state if the selected date has no timeline cards.
3. Show failure state with the selected date unchanged if the read fails.
4. Avoid falling back to the previous date's data after a failed new-date read.
5. Prevent older in-flight reads from overwriting newer selected-date results.

### Acceptance criteria

- Rapid previous/next clicks settle on the latest selected date.
- Failure for one date does not corrupt the selected-date controller.
- Empty selected dates remain navigable.

---

## Block acceptance criteria

- Today reads are selected-date aware.
- Date changes are read-only state transitions.
- Modal/selection state cannot leak across dates.
- Controller tests cover previous, next, direct jump, empty date, and read
  failure.

## Validation after block

```sh
cd apps/focus_flow_flutter
flutter test test/controllers
flutter test test/app
```

If tests are organized differently after Persistence Plan 1, run the nearest
controller/app tests and document the command used.
