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


# Date Selection 01 Summary — Day Navigation and Date Picker

**Status:** Complete.
**Scope level:** XHIGH implementation plan.
**Primary outcome:** The Flutter desktop app can switch the visible planning day,
load the correct persisted timeline for that day, and keep date-specific task
state durable across app restarts.

---

## Current repo facts this plan is based on

1. The compact Flutter UI already has top-bar calendar, left-arrow, and
   right-arrow controls, but their callbacks are placeholders.
2. The top bar currently receives only a display-ready `dateLabel`.
3. `TodayScreenController` currently reads one fixed day through a callback.
4. The composition currently owns a single `CivilDate` and creates command
   controllers with that fixed local date.
5. `GetTodayStateQuery.execute` already accepts a requested `CivilDate`.
6. Scheduler commands such as scheduling, completing, and uncompleting already
   accept a local date for planning context.
7. After Persistence Plan 1, app state should be backed by an on-disk SQLite
   `ApplicationUnitOfWork`, not static demo seed data.

---

## Product behavior

1. Clicking the left arrow moves the selected date back one day.
2. Clicking the right arrow moves the selected date forward one day.
3. Clicking the displayed date opens a date picker.
4. Choosing a date immediately reloads the Today timeline for that date.
5. Date switching does not mutate tasks by itself.
6. Scheduling a backlog task while viewing a future or past date schedules into
   the selected date's planning window, subject to backend scheduling rules.
7. Completing a task uses the real current clock for completion metadata, not
   the selected date as fake time.
8. Date-specific task placement and done/not-done state survive close/reopen.
9. If completion happened on a different local date than the scheduled slot, the
   card must show the completion date, not only the completion time.

---

## Definition of done

Date Selection 01 is complete when all of the following are true:

1. `TopBar` exposes working previous-day, next-day, and date-picker callbacks.
2. The displayed date is an accessible button, not static text.
3. The selected date is owned by controller/composition state and is not hardcoded
   into demo composition.
4. Switching dates reloads `GetTodayStateQuery` with the selected `CivilDate`.
5. Command controllers run schedule/complete/uncomplete actions against the
   current selected date.
6. Any selected modal card is cleared or resynced safely when the date changes.
7. Tasks scheduled on tomorrow or a previous day persist and reload on that day.
8. Completed state persists when completion happens from a non-current selected
   day.
9. Completion presentation includes date context whenever completed local date
   differs from scheduled local date.
10. Widgets do not contain Drift, SQL, repository, or scheduling-engine logic.
11. Existing compact timeline visuals remain stable except for the intended date
    controls and completion-date text.
12. Backend, Flutter, and lifecycle validation gates pass, or unavailable gates
    are documented.

---

## Non-goals

1. No week/month calendar view.
2. No drag-and-drop scheduling.
3. No recurring task support.
4. No calendar sync.
5. No changes to the scheduling algorithm except bug fixes discovered while
   validating selected-date command behavior.
6. No broad redesign of the compact timeline.
7. No task-pushing menu; that is handled by Task Pushing 01.
8. No backup/restore or export/import UI.

---

## Architecture rule

Date selection is UI/session state. Scheduling truth remains in the backend
read/command layer:

```text
TopBar date controls
  -> selected-date controller/state
  -> Today read controller executes GetTodayStateQuery(date)
  -> command controller passes selected CivilDate to use cases
  -> ApplicationUnitOfWork persists domain changes
  -> UI refreshes from read models
```

The selected date may choose which read model to request. It must not cause UI
widgets to compute task placement or conflict resolution.

---

## Completion notes

Date Selection 01 is complete on the `date-selection-01-day-navigation` branch
and is intentionally awaiting behavior review before merge.

Implemented behavior:

1. A selected-date controller owns previous, next, and direct date selection.
2. Today reads use the selected `CivilDate` and ignore stale in-flight results.
3. Top-bar previous/next/date-picker controls reload the selected day and keep
   the compact dark UI accessible.
4. Schedule, complete, and uncomplete commands read the selected date at
   execution time.
5. Future-day schedule, completion, uncompletion, and reopen behavior are covered
   with SQLite-backed lifecycle tests.
6. Cross-date completion shows date + time while same-day completion remains
   compact.

Validation status is recorded in
`DATE_SELECTION_01_BLOCK_06_VALIDATION_HANDOFF.md`.

---

## Important implementation decision

Do not make `DemoSchedulerComposition.date` the durable date-navigation model.
After Persistence Plan 1, the app should have a real runtime composition that can
create read and command controllers for whichever date is currently selected.
Use a selected-date controller or date-aware Today controller so date changes are
explicit, testable, and not hidden in widget-local rebuilds.
