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


# Date Selection 01 Block 03 — Top-Bar Navigation and Date Picker

**Status:** Complete.
**Goal:** Wire the visible top-bar controls to selected-date state while
preserving the compact dark UI.

---

## Block outcome

After this block, the user can click previous/next day arrows and open a date
picker from the displayed date.

Implementation notes:

1. Wired `TopBar` previous, next, and choose-date callbacks through the screen
   scaffold.
2. Converted the date label to an accessible button that opens Flutter's themed
   date picker.
3. Preserved modal safety by closing selected cards when changing dates.

---

## Chunk 3.1 — Refactor `TopBar` callback API

### Tasks

1. Add `onPreviousDate`, `onNextDate`, and `onDatePressed` callbacks to `TopBar`.
2. Keep callbacks nullable only if tests/demo previews need disabled controls.
3. Convert current placeholder `onPressed: () {}` values into real callback
   invocations.
4. Preserve the current metrics and layout unless a callback affordance requires
   minor spacing updates.
5. Add tooltips/accessibility labels:
   - Previous day,
   - Next day,
   - Choose date.

### Acceptance criteria

- `TopBar` no longer contains inert date controls in normal app mode.
- Button hit targets remain usable at compact width.
- Existing top-bar visual snapshots/widget tests are updated only for intentional
  changes.

---

## Chunk 3.2 — Make the date label a button

### Tasks

1. Replace the static date label area with an accessible button-like control.
2. Keep the visual treatment calm and compact; avoid bright native-calendar
   styling that clashes with the dark theme.
3. Ensure the button still scales/truncates cleanly at the current compact
   breakpoint.
4. Preserve keyboard focus and screen-reader semantics.
5. Keep the top-left `Today` title as the surface name unless product direction
   explicitly changes it.

### Acceptance criteria

- Clicking the displayed date opens the picker callback.
- Keyboard users can focus and activate the date control.
- The date label still renders correctly for long month names.

---

## Chunk 3.3 — Implement date picker presentation

### Tasks

1. Use Flutter's date picker if it can be themed cleanly for the current dark UI;
   otherwise implement a small scoped picker surface.
2. Initialize the picker to the currently selected date.
3. On selection, convert the picked date to `CivilDate` without accidentally
   shifting it through UTC/local-time conversions.
4. On cancel, leave selected date unchanged.
5. Boundaries can remain broad in V1 unless existing product rules define a
   scheduling horizon.
6. Keep date picker state outside scheduler core.

### Acceptance criteria

- Picking a date reloads the timeline for that exact civil date.
- Canceling the picker performs no read refresh and no task mutation.
- Date conversion tests cover at least one non-UTC owner timezone if timezone
  test utilities are available.

---

## Chunk 3.4 — Wire top-bar controls through the screen scaffold

### Tasks

1. Thread date callbacks from the selected-date owner through
   `_TodayScreenScaffold` into `TopBar`.
2. Ensure empty/loading/failure states still render top-bar date controls where
   appropriate.
3. Ensure date switching while a modal is open clears selection before or during
   reload.
4. Keep `TimelineView` unaware of date-picker mechanics.

### Acceptance criteria

- Previous/next/date-picker interactions work from ready and empty states.
- Timeline widgets continue to receive only card/range/selection inputs.
- No scheduler/domain imports are added to presentational top-bar widgets unless
  already required by app-layer boundaries.

---

## Block acceptance criteria

- The top-bar date controls are interactive.
- The date label opens a picker.
- UI remains compact and dark-themed.
- Date controls are accessible and test-covered.

## Validation after block

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