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


# Date Selection 01 Block 05 — Completion Date Presentation

**Status:** Complete.
**Goal:** Show enough completion timestamp context when the completed date and
scheduled date differ.

---

## Block outcome

After this block, completed timeline cards still look compact for normal same-day
completion, but they show date context when completion happened on a different
local date than the scheduled slot.

Implementation notes:

1. Timeline read models carry actual start/end completion context.
2. Flutter presentation mapping shows date + time when completion metadata falls
   on a different local date than the scheduled slot.
3. Model and persistence-backed tests cover same-day and cross-date completion
   labels.

---

## Chunk 5.1 — Add completion date fields to presentation models

### Tasks

1. Extend `TimelineCardModel` or an equivalent presentation model with one or
   more explicit completion fields:
   - completed local date,
   - completed time text,
   - display-ready completed date/time text,
   - whether date context is required.
2. Keep raw `DateTime` handling out of leaf widgets where possible.
3. Use owner timezone/local-date semantics rather than comparing UTC calendar
   days directly.
4. Preserve existing `completedTimeText` behavior for same-day cards if it is
   still useful.

### Acceptance criteria

- Presentation mapper can decide whether date context is required.
- Widgets receive display-ready text or simple presentation flags.
- Existing same-day completed card tests continue to pass with minimal changes.

---

## Chunk 5.2 — Define date-context display rules

### Required V1 rule

Show date + time when:

1. `completedAt` local date differs from the scheduled local date, or
2. actual completion interval local date differs from the scheduled local date.

### Optional V1-friendly rule

Also show date + time when the selected date is not the current owner-local day,
if testing shows users need that context while reviewing previous/future days.
Keep this optional rule behind a clearly named mapper helper so it can be changed
without rewriting widgets.

### Tasks

1. Implement a single helper that compares scheduled and completed local dates.
2. Prefer exact labels like `Completed Jul 2, 8:05 AM` over vague labels like
   `Completed yesterday` for V1.
3. Keep same-day labels compact, for example `Completed at: 8:05 AM`.
4. Add tests for:
   - scheduled and completed same date,
   - scheduled date differs from completed date,
   - completed timestamp present but actual interval absent,
   - actual interval present but completed timestamp absent if the domain can
     produce that state.

### Acceptance criteria

- Cross-date completion never renders as time-only.
- Same-day completion remains compact.
- Date formatting is deterministic in tests.

---

## Chunk 5.3 — Update compact card and modal text

### Tasks

1. Update timeline card subtitle text to include completion date context when
   required.
2. Update selected-task modal metadata if it repeats completion time.
3. Ensure long date/time strings fit in compact card constraints without
   overflowing over reward/difficulty controls.
4. Add tooltip/semantic label if the visible compact text must be shortened.

### Acceptance criteria

- Completed cross-date cards are readable in compact timeline mode.
- The selected-task modal shows the same completion date truth as the card.
- Text overflow behavior is intentional and tested.

---

## Chunk 5.4 — Add persistence-backed presentation tests

### Tasks

1. Create or reuse a temp SQLite runtime test that schedules a task on one day
   and completes it on another command clock day.
2. Reopen the database/runtime.
3. Load the scheduled day.
4. Assert the card contains completion date + time.
5. Load the completion day if the task also appears there by backend design;
   assert presentation remains consistent.

### Acceptance criteria

- Cross-date completion display survives close/reopen.
- UI presentation is based on persisted task timestamps, not transient widget
  state.

---

## Block acceptance criteria

- Completion-date presentation covers cross-date completion.
- Same-day completion remains compact.
- Card and modal text agree.
- Presentation tests cover persisted reload.

## Validation after block

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