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


# Task Pushing 01 Block 03 — Push Button Card UI

**Status:** Complete.
**Goal:** Render the full right-side Push button on past incomplete cards.

---

## Block outcome

After this block, past incomplete planned flexible cards visibly show a `Push`
button beside the reward/difficulty icons. The menu may still be stubbed until
Block 04.

## Implementation notes

1. `TaskTimelineCard` renders a full Push button beside reward/difficulty
   controls when `TimelineCardModel.showPastTaskPushButton` is true.
2. Text reserves additional right-side space while Push is visible, and trailing
   controls remain above the text layer.
3. Hover quick actions are not built while the full Push button is visible.
4. Widget tests cover render state, completed/future exclusions, hover
   suppression, and callback activation.

---

## Chunk 3.1 — Place the Push button in trailing controls

### Tasks

1. Add a compact `Push` button component in the timeline card trailing-controls
   area.
2. Position it next to reward and difficulty icons as requested.
3. Give it visual priority over time text if the layout overlaps.
4. Keep card height and density consistent with the compact timeline.
5. Use calm styling that reads as actionable without becoming visually loud.

### Acceptance criteria

- Push button appears at the right side of eligible cards.
- Reward/difficulty icons remain visible and aligned.
- The time label does not visually cover the button.

---

## Chunk 3.2 — Implement z-order and hover suppression

### Tasks

1. Ensure the Push button is painted above any time text or hover affordance that
   would otherwise overlap it.
2. Disable hover quick-action rendering while the Push button is visible.
3. Confirm normal hover actions still appear on non-past eligible flexible tasks.
4. Confirm the Push button remains clickable when the card is selected/hovered.

### Acceptance criteria

- The Push button wins hit testing in its visible area.
- Hover controls do not appear over or under the Push button.
- No double-action UI appears for the same card.

---

## Chunk 3.3 — Add accessibility and keyboard behavior

### Tasks

1. Add a tooltip and semantic label such as `Push overdue task`.
2. Ensure the button can receive keyboard focus.
3. Ensure pressing Enter/Space triggers the same callback as clicking.
4. Ensure disabled/unavailable push state, if any, is announced correctly.

### Acceptance criteria

- Keyboard and screen-reader users can discover and activate Push.
- The button label is specific enough to distinguish it from hover quick actions.

---

## Chunk 3.4 — Add visual/widget tests

### Required tests

1. Past incomplete flexible card renders Push.
2. Completed past flexible card does not render Push.
3. Future flexible card does not render Push.
4. Past incomplete flexible card does not render hover quick actions.
5. Normal planned flexible card still renders hover quick actions when hovered.
6. Push button callback fires once when tapped.

### Acceptance criteria

- UI behavior is covered without requiring real SQLite.
- Tests use presentation models rather than hand-building domain scheduler state
  inside widgets.

---

## Block acceptance criteria

- Push button renders in the correct card state.
- Push button placement and z-order satisfy the visual requirement.
- Hover quick actions are suppressed only while Push is visible.
- Accessibility behavior is covered.

## Validation after block

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