339 lines
13 KiB
Markdown
339 lines
13 KiB
Markdown
# UI Plan 1 — Compact Today Timeline Mockup Implementation
|
||
|
||
**Status:** Planned
|
||
**Plan folder:** `Codex Documentation/Current Software Plan/UI Plan 1 - Compact Today Timeline Mockup/`
|
||
**Primary target:** Replace the current/provisional Flutter UI with the first real compact Today timeline screen and selected-task modal shown in the bundled mockups.
|
||
**Execution mode:** Run all chunks at `xhigh`; this plan intentionally does not repeat per-chunk thinking labels.
|
||
|
||
---
|
||
|
||
## 1. Purpose
|
||
|
||
This plan gives Codex a detailed, implementation-ready sequence for building only the current requested UI slice:
|
||
|
||
1. A desktop-first Flutter Today screen in compact mode.
|
||
2. A backend-backed deterministic seed for the current day.
|
||
3. Rendering of the seeded timeline from application/domain read state.
|
||
4. One interaction only: clicking a task card opens the selected-task modal.
|
||
5. Clicking outside the modal or pressing the modal close button dismisses it.
|
||
6. All other visible controls remain present and enabled-looking, but intentionally no-op.
|
||
|
||
Do **not** implement Backlog screens, task creation, schedule review, editing flows, drag-and-drop, notifications, Shield/Recovery, reports, settings, persistence-backed runtime wiring, or real command behavior in this plan.
|
||
|
||
---
|
||
|
||
## 2. Source truth and repo observations
|
||
|
||
### Source truth
|
||
|
||
Use these sources, in this order, when implementing:
|
||
|
||
1. Repo files and `AGENTS.md`.
|
||
2. This plan folder.
|
||
3. Mockup images in this plan folder.
|
||
4. Human documentation already in the repo.
|
||
|
||
Preserve the core architectural rule: the Flutter UI renders backend/application state and sends user intent; it does not duplicate scheduling rules.
|
||
|
||
### Important repo observation from this planning pass
|
||
|
||
The extracted zip includes:
|
||
|
||
- `AGENTS.md`, which says active plans live under `Codex Documentation/Current Software Plan/` and Flutter UI work starts under `apps/focus_flow_flutter/`.
|
||
- `README.md` and completed plan docs that refer to `apps/focus_flow_flutter/`.
|
||
- No actual `apps/focus_flow_flutter/` directory in the extracted tree.
|
||
|
||
So the first implementation block must verify whether the working repo has an app directory. If it is missing, create it. If it exists in Codex's working copy, replace only the provisional UI slice needed here and preserve any useful conventions.
|
||
|
||
---
|
||
|
||
## 3. Mockup references
|
||
|
||
Clean semi-strict references:
|
||
|
||
- `mockups/clean/main_screen_compact.png`
|
||
- `mockups/clean/task_selected_modal.png`
|
||
|
||
Annotated implementation references:
|
||
|
||
- `mockups/annotated/main_screen_compact_notes.png`
|
||
- `mockups/annotated/task_selected_modal_notes.png`
|
||
|
||
Mockup handling rule:
|
||
|
||
- Treat the clean mockups as semi-strict visual truth.
|
||
- Use annotated versions for implementation notes only.
|
||
- Deviations are allowed only for unavoidable Flutter/platform font metrics, pixel rounding, safe minimum hit targets, and small responsive adjustments.
|
||
- Do not introduce a white app background.
|
||
- Do not grey out no-op buttons. They should look usable, but their handlers should intentionally do nothing.
|
||
|
||
---
|
||
|
||
## 4. Feature scope
|
||
|
||
### In scope
|
||
|
||
- Flutter desktop app shell under `apps/focus_flow_flutter/`.
|
||
- Dark theme visual tokens matching the mockups.
|
||
- Compact Today top bar and sidebar.
|
||
- Date header and static navigation controls.
|
||
- Compact/Normal segmented toggle with Compact selected.
|
||
- Settings button visible as a no-op.
|
||
- Next required task banner.
|
||
- Timeline rail from 4:00 PM through 8:45 PM.
|
||
- Timeline rows/cards for seeded tasks.
|
||
- Reward icon using solid sparkle/star shapes.
|
||
- Difficulty icon with exactly five vertical bars, filled according to difficulty.
|
||
- Selected-task modal for any task card click.
|
||
- Close modal on outside click and close icon.
|
||
- Widget tests for rendering and modal behavior.
|
||
- Root/core purity checks and Flutter forbidden-import checks.
|
||
|
||
### Out of scope
|
||
|
||
- Real navigation between Today/Backlog/Projects/Reports/Settings.
|
||
- Actual Done, Push, Move to Backlog, Break up, calendar, settings, or normal-mode behavior.
|
||
- Task creation/editing drawers.
|
||
- Schedule review.
|
||
- Persistence-backed SQLite runtime composition.
|
||
- Notifications.
|
||
- Backup/restore or export/import UI.
|
||
- Week/month/calendar views.
|
||
- Drag-and-drop.
|
||
- Shield/Recovery flows.
|
||
|
||
---
|
||
|
||
## 5. Target visual composition
|
||
|
||
Build at desktop density first. The mockups are 1586×992 and should be used as the primary visual reference.
|
||
|
||
### App shell
|
||
|
||
- Rounded outer app frame with a dark navy/near-black background.
|
||
- Left sidebar approximately 250 px wide at mockup width.
|
||
- Main content region with generous horizontal gutters.
|
||
- Mac-style red/yellow/green window controls in the sidebar top-left. These are decorative/no-op.
|
||
- Brand row with sparkle icon and `FocusFlow`.
|
||
- Sidebar navigation rows:
|
||
- Today active, magenta-tinted fill and outline.
|
||
- Backlog, Projects, Reports, Settings inactive.
|
||
- All sidebar rows are visible/no-op except Today is visually active.
|
||
|
||
### Header/top controls
|
||
|
||
- `Today` title.
|
||
- Calendar icon button, previous arrow, date label, next arrow.
|
||
- Date should be derived from selected current day in runtime, but widget tests may use a fixed date to match the mockup.
|
||
- Segmented control with `Compact` selected and `Normal` unselected/no-op.
|
||
- Settings button visible/no-op.
|
||
|
||
### Required banner
|
||
|
||
- Full-width magenta/pink glass panel under the header.
|
||
- Sparkle icon on the left.
|
||
- Text: `Next required task: Pay bill at 6:00 PM` for the default seed.
|
||
- Text should be derived from the backend/read-model selected next required item, not hard-coded inside the widget.
|
||
- `Show upcoming` button visible/no-op.
|
||
|
||
### Timeline rail
|
||
|
||
- Left time labels from 4:00 PM through 8:45 PM in 15-minute intervals.
|
||
- Major hour labels brighter; quarter-hour labels muted.
|
||
- Vertical rail with circular dots on hour positions.
|
||
- Horizontal grid lines across the timeline.
|
||
- Timeline is not scroll-driven for this slice at the mockup height. If viewport height is smaller, allow main content to scroll without changing card styling.
|
||
|
||
### Task cards
|
||
|
||
Render cards from the backend-backed `TodayState.timelineItems` or a UI adapter derived directly from those items.
|
||
|
||
Default seed must visually include:
|
||
|
||
1. `Clean coffee maker`, green flexible task, 15 min.
|
||
2. Completed surprise row `Cleaned kitchen counter`, grey/disabled-looking completed styling.
|
||
3. `Pay bill`, pink required task, 6:00–6:10 PM.
|
||
4. `Doctor appointment`, blue required/inflexible task, 6:30–7:15 PM.
|
||
5. `Free Slot`, purple protected rest/free slot, 7:15–8:15 PM.
|
||
6. Later completed surprise row `Cleaned kitchen counter`, grey/disabled-looking completed styling.
|
||
|
||
Card buttons/icons are no-op. Clicking anywhere on a task/free-slot card may open the modal for that card, but the acceptance path only requires opening the modal for `Pay bill`.
|
||
|
||
### Reward and difficulty indicators
|
||
|
||
Reward icon:
|
||
|
||
- Use solid sparkle/star shapes, not only line-art outlines.
|
||
- Pink/purple depending on task color context.
|
||
- Badge background should match the dark glass style.
|
||
|
||
Difficulty icon:
|
||
|
||
- Exactly five rounded vertical bars.
|
||
- Fill count is based on difficulty:
|
||
- `notSet`: zero filled or hidden if no difficulty should be shown.
|
||
- `veryEasy`: 1 filled.
|
||
- `easy`: 2 filled.
|
||
- `medium`: 3 filled.
|
||
- `hard`: 4 filled.
|
||
- `veryHard`: 5 filled.
|
||
- Unfilled bars are outlines only.
|
||
- Medium effort in the modal must show three filled bars.
|
||
|
||
### Selected-task modal
|
||
|
||
- Centered overlay on the timeline.
|
||
- Underlying timeline remains visible; use a very light transparent scrim only if needed for click-away handling.
|
||
- Header contains status ring, title, type label, and time range.
|
||
- Close button in the top-right.
|
||
- Two metadata tiles:
|
||
- Reward level.
|
||
- Difficulty/effort.
|
||
- Four action buttons in a 2×2 grid:
|
||
- Done.
|
||
- Push.
|
||
- Move to Backlog.
|
||
- Break up.
|
||
- All modal buttons are enabled-looking but no-op.
|
||
- Footer text: `Options apply after confirmation.`
|
||
|
||
---
|
||
|
||
## 6. Architecture expectations
|
||
|
||
### Package and dependency boundary
|
||
|
||
- Flutter app lives under `apps/focus_flow_flutter/`.
|
||
- Keep the app outside the root Dart workspace unless a later plan explicitly changes the workspace.
|
||
- UI code may import public package entry points such as `package:scheduler_core/scheduler_core.dart`.
|
||
- UI code must not import:
|
||
- `package:scheduler_core/src/...`
|
||
- Drift.
|
||
- SQLite adapters.
|
||
- notification platform implementations.
|
||
- backup/export internals.
|
||
- OS APIs directly for this slice.
|
||
|
||
### State ownership
|
||
|
||
- Use a small UI controller/composition layer that queries backend/application state.
|
||
- The widget tree should receive display models and callbacks.
|
||
- The widget tree must not calculate canonical schedule placement or conflict resolution.
|
||
- Timeline geometry for painting rows is UI layout logic and is allowed.
|
||
- Mapping backend read models to color/icon tokens is UI presentation logic and is allowed.
|
||
|
||
### Seed ownership
|
||
|
||
The seed must be static and deterministic, but not a hand-coded widget list. Use backend/application objects as if the real calls had already produced scheduled task state.
|
||
|
||
Acceptable approach:
|
||
|
||
- Build `ProjectProfile`, `OwnerSettings`, and `Task` domain objects.
|
||
- Insert them into `InMemoryApplicationUnitOfWork` as initial state.
|
||
- Query `GetTodayStateQuery` for the selected current day.
|
||
- Render the returned state.
|
||
|
||
Do not bypass the read query by creating Flutter-only timeline items.
|
||
|
||
---
|
||
|
||
## 7. Block list
|
||
|
||
Execute the block files in this folder in order:
|
||
|
||
1. `UI_PLAN_1_BLOCK_01_REPO_AND_SCOPE_GUARDRAILS.md`
|
||
2. `UI_PLAN_1_BLOCK_02_APP_SHELL_VISUAL_SYSTEM.md`
|
||
3. `UI_PLAN_1_BLOCK_03_BACKEND_SEEDED_TODAY_STATE.md`
|
||
4. `UI_PLAN_1_BLOCK_04_COMPACT_TIMELINE_CARDS.md`
|
||
5. `UI_PLAN_1_BLOCK_05_TASK_SELECTION_MODAL.md`
|
||
6. `UI_PLAN_1_BLOCK_06_TESTING_VALIDATION_HANDOFF.md`
|
||
|
||
Each block contains chunks, implementation details, acceptance criteria, and breakpoints.
|
||
|
||
---
|
||
|
||
## 8. Expected final changed areas
|
||
|
||
Likely implementation changes after Codex executes this plan:
|
||
|
||
```text
|
||
apps/focus_flow_flutter/
|
||
lib/
|
||
main.dart
|
||
app/focus_flow_app.dart
|
||
app/demo_scheduler_composition.dart
|
||
controllers/today_screen_controller.dart
|
||
models/today_screen_models.dart
|
||
theme/focus_flow_theme.dart
|
||
theme/focus_flow_tokens.dart
|
||
widgets/app_shell.dart
|
||
widgets/sidebar.dart
|
||
widgets/top_bar.dart
|
||
widgets/required_banner.dart
|
||
widgets/timeline/timeline_geometry.dart
|
||
widgets/timeline/timeline_axis.dart
|
||
widgets/timeline/timeline_view.dart
|
||
widgets/timeline/task_timeline_card.dart
|
||
widgets/timeline/reward_icon.dart
|
||
widgets/timeline/difficulty_bars.dart
|
||
widgets/task_selection_modal.dart
|
||
test/
|
||
today_screen_render_test.dart
|
||
task_selection_modal_test.dart
|
||
visual_token_test.dart
|
||
forbidden_imports_test.dart
|
||
```
|
||
|
||
Exact file names may vary if the working repo already has conventions, but keep the same boundaries.
|
||
|
||
---
|
||
|
||
## 9. Validation summary
|
||
|
||
Minimum validation after implementation:
|
||
|
||
```sh
|
||
cd apps/focus_flow_flutter
|
||
flutter pub get
|
||
dart format lib test
|
||
flutter analyze
|
||
flutter test
|
||
cd ../..
|
||
scripts/test.sh
|
||
```
|
||
|
||
Also run a forbidden-import scan for the app `lib/` and `test/` directories.
|
||
|
||
If Flutter is unavailable in the execution environment, Codex must still make the changes, run all available Dart/root validations, and explicitly report Flutter validation as unverified due to toolchain absence.
|
||
|
||
---
|
||
|
||
## 10. Risks and mitigation
|
||
|
||
| Risk | Mitigation |
|
||
|---|---|
|
||
| App directory may be absent despite docs referencing it. | Block 1 verifies and creates/reconciles `apps/focus_flow_flutter/`. |
|
||
| Pixel-perfect matching can be brittle across platforms/fonts. | Match layout, color system, icon semantics, spacing, and behavior; avoid fragile exact-font assumptions. |
|
||
| UI could accidentally duplicate scheduler logic. | Seed/query through application/domain read state and keep scheduling decisions out of widgets. |
|
||
| No-op controls may look disabled if normal disabled widgets are used. | Use enabled-looking buttons with empty callbacks or inert callbacks. |
|
||
| Current day requirement conflicts with mockup date. | Runtime defaults to current owner-local date; tests/demo screenshots may use a fixed clock matching the mockup. |
|
||
| Difficulty/reward icon drift. | Implement custom painters and test fill counts/semantics. |
|
||
|
||
---
|
||
|
||
## 11. Definition of done
|
||
|
||
UI Plan 1 is complete when:
|
||
|
||
- The app launches to the compact Today screen.
|
||
- The screen visually tracks the clean mockups closely.
|
||
- Timeline content comes from backend/application seed/query flow.
|
||
- Static seed data is deterministic and tied to the selected current day.
|
||
- All visible controls are present and enabled-looking.
|
||
- Only task-card selection, outside-click close, and close icon behavior are functional.
|
||
- Modal action buttons are no-op.
|
||
- Difficulty icons have five bars and correct fill counts.
|
||
- Reward icons use solid sparkle/star forms.
|
||
- Flutter analyze/test pass.
|
||
- Root backend tests still pass or are explicitly reported if not runnable.
|
||
- No forbidden imports or core purity regressions are introduced.
|