diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index 3b408c8..cba6c7b 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -1,7 +1,7 @@ # Requirements: Kimai Heatmap Plugin v1.1 **Defined:** 2026-04-08 -**Core Value:** At a glance, see where your time went — a visual map of tracking activity that makes patterns obvious +**Core Value:** At a glance, see where your time went -- a visual map of tracking activity that makes patterns obvious ## v1.1 Requirements @@ -17,7 +17,7 @@ Requirements for Modes & Filtering milestone. Each maps to roadmap phases. ### Entity Pickers & Filtering -- [ ] **FILT-01**: Customer→project→activity cascading TomSelect pickers replace plain - [ ] **FILT-02**: Activity filtering narrows heatmap data to a specific activity - [ ] **FILT-03**: Customer filtering narrows heatmap data to all projects under a customer @@ -59,25 +59,26 @@ Requirements for Modes & Filtering milestone. Each maps to roadmap phases. | Requirement | Phase | Status | |-------------|-------|--------| -| VIZ-01 | - | Pending | -| VIZ-02 | - | Pending | -| VIZ-03 | - | Pending | -| VIZ-04 | - | Pending | -| VIZ-05 | - | Pending | -| FILT-01 | - | Pending | -| FILT-02 | - | Pending | -| FILT-03 | - | Pending | -| API-01 | - | Pending | -| API-02 | - | Pending | -| POL-01 | - | Pending | -| TEST-01 | - | Pending | -| TEST-02 | - | Pending | -| TEST-03 | - | Pending | +| VIZ-01 | Phase 7 | Pending | +| VIZ-02 | Phase 7 | Pending | +| VIZ-03 | Phase 9 | Pending | +| VIZ-04 | Phase 9 | Pending | +| VIZ-05 | Phase 7 | Pending | +| FILT-01 | Phase 10 | Pending | +| FILT-02 | Phase 8 | Pending | +| FILT-03 | Phase 8 | Pending | +| API-01 | Phase 8 | Pending | +| API-02 | Phase 8 | Pending | +| POL-01 | Phase 9 | Pending | +| TEST-01 | Phase 7 | Pending | +| TEST-02 | Phase 10 | Pending | +| TEST-03 | Phase 8 | Pending | **Coverage:** - v1.1 requirements: 14 total -- Mapped to phases: 0 -- Unmapped: 14 +- Mapped to phases: 14 +- Unmapped: 0 --- *Requirements defined: 2026-04-08* +*Traceability updated: 2026-04-08* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index b92cf05..0fe38b9 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -3,6 +3,7 @@ ## Milestones - ✅ **v1.0 MVP** — Phases 1-5 (shipped 2026-04-08) — [archive](milestones/v1.0-ROADMAP.md) +- 🚧 **v1.1 Modes & Filtering** — Phases 6-10 (in progress) ## Phases @@ -17,8 +18,83 @@ +### v1.1 Modes & Filtering + +- [ ] **Phase 6: Renderer Architecture** - Refactor monolithic renderHeatmap into strategy-pattern mode system with state management +- [ ] **Phase 7: Mode Switcher + Week Mode** - First visible v1.1 feature: mode switcher UI, week-mode renderer, hours/count toggle +- [ ] **Phase 8: Backend Aggregation + Filtering** - Hour-level and day/hour aggregation queries, activity/customer filtering, custom endpoints +- [ ] **Phase 9: Day + Combined Modes** - Day-of-week and time-of-day renderers, combined punchcard matrix, color scale legend +- [ ] **Phase 10: Entity Pickers** - TomSelect cascading customer/project/activity pickers replacing plain selects + +## Phase Details + +### Phase 6: Renderer Architecture +**Goal**: Existing year-view heatmap works identically but through a mode-dispatched renderer system ready for new visualization modes +**Depends on**: Phase 5 (v1.0 shipped codebase) +**Requirements**: None (architectural enabler -- all v1.1 features depend on this refactor) +**Success Criteria** (what must be TRUE): + 1. Year-view heatmap renders identically to v1.0 behavior (no visual regression) + 2. Tooltip, color scale, and cell click handler are extracted as shared utilities reusable by any renderer + 3. A HeatmapState object tracks mode, display metric, and filters -- UI changes flow through state + 4. Adding a new visualization mode requires only implementing a ModeRenderer interface and registering it +**Plans**: TBD + +### Phase 7: Mode Switcher + Week Mode +**Goal**: Users can switch between year and week visualization modes and toggle between hours and entry-count display +**Depends on**: Phase 6 +**Requirements**: VIZ-01, VIZ-02, VIZ-05, TEST-01 +**Success Criteria** (what must be TRUE): + 1. A segmented control in the widget header lets the user switch between year and week views + 2. Week-mode shows a day-of-week aggregation heatmap revealing which weekdays are busiest + 3. Hours/count toggle switches the color scale metric across both year and week modes without re-fetching data + 4. Switching modes preserves the current filter selection + 5. Vitest tests cover mode switcher interaction, week renderer output, and display toggle behavior +**Plans**: TBD +**UI hint**: yes + +### Phase 8: Backend Aggregation + Filtering +**Goal**: Backend serves hour-level and day/hour aggregation data and accepts activity and customer filter params via custom endpoints +**Depends on**: Phase 6 +**Requirements**: API-01, API-02, FILT-02, FILT-03, TEST-03 +**Success Criteria** (what must be TRUE): + 1. API endpoint accepts a mode param and returns hourly aggregation data (for day-mode) and day/hour aggregation data (for combined mode) + 2. Activity filter param narrows heatmap data to entries matching a specific activity + 3. Customer filter param narrows heatmap data to all projects under a selected customer + 4. Custom cascade endpoints (/heatmap/customers, /heatmap/projects, /heatmap/activities) return entity lists using session auth (not API auth) + 5. PHPUnit tests cover hourly aggregation, day/hour aggregation, and filter parameter handling +**Plans**: TBD + +### Phase 9: Day + Combined Modes +**Goal**: Users can view time-of-day and day/hour punchcard visualizations with a color scale legend +**Depends on**: Phase 7 (mode switcher), Phase 8 (backend aggregation data) +**Requirements**: VIZ-03, VIZ-04, POL-01 +**Success Criteria** (what must be TRUE): + 1. Day-mode renders a time-of-day heatmap showing when during the day work happens (24 hour slots) + 2. Combined mode renders a 7x24 punchcard matrix showing day-of-week vs hour-of-day patterns + 3. Mode switcher now offers all four modes (year, week, day, combined) and all work end-to-end + 4. A color scale legend gradient bar shows the value range for the current mode and metric +**Plans**: TBD +**UI hint**: yes + +### Phase 10: Entity Pickers +**Goal**: Users filter the heatmap using Kimai-native TomSelect pickers with customer/project/activity cascade +**Depends on**: Phase 8 (custom cascade endpoints) +**Requirements**: FILT-01, TEST-02 +**Success Criteria** (what must be TRUE): + 1. Customer, project, and activity pickers use TomSelect with search/autocomplete replacing plain select elements + 2. Selecting a customer filters the project picker to that customer's projects and the activity picker to matching activities + 3. Selecting a project filters the activity picker to that project's activities + 4. Clearing a parent picker resets child pickers and updates the heatmap accordingly + 5. Vitest tests cover cascade behavior, empty states, and filter-to-heatmap integration +**Plans**: TBD +**UI hint**: yes + ## Progress +**Execution Order:** +Phases execute in numeric order: 6 -> 7 -> 8 -> 9 -> 10 +Note: Phases 7 and 8 can execute in parallel (both depend only on Phase 6). + | Phase | Milestone | Plans Complete | Status | Completed | |-------|-----------|----------------|--------|-----------| | 1. Dev Environment | v1.0 | 2/2 | Complete | 2026-04-08 | @@ -26,3 +102,8 @@ | 3. Core Heatmap Rendering | v1.0 | 3/3 | Complete | 2026-04-08 | | 4. Heatmap Interaction | v1.0 | 2/2 | Complete | 2026-04-08 | | 5. Polish | v1.0 | 2/2 | Complete | 2026-04-08 | +| 6. Renderer Architecture | v1.1 | 0/? | Not started | - | +| 7. Mode Switcher + Week Mode | v1.1 | 0/? | Not started | - | +| 8. Backend Aggregation + Filtering | v1.1 | 0/? | Not started | - | +| 9. Day + Combined Modes | v1.1 | 0/? | Not started | - | +| 10. Entity Pickers | v1.1 | 0/? | Not started | - | diff --git a/.planning/STATE.md b/.planning/STATE.md index 66b43fa..8d85983 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,12 +2,12 @@ gsd_state_version: 1.0 milestone: v1.1 milestone_name: Modes & Filtering -status: defining_requirements -stopped_at: Milestone v1.1 started -last_updated: "2026-04-08T22:00:00.000Z" +status: ready_to_plan +stopped_at: Roadmap created for v1.1 (Phases 6-10) +last_updated: "2026-04-08T23:00:00.000Z" last_activity: 2026-04-08 progress: - total_phases: 0 + total_phases: 5 completed_phases: 0 total_plans: 0 completed_plans: 0 @@ -21,19 +21,40 @@ progress: See: .planning/PROJECT.md (updated 2026-04-08) **Core value:** At a glance, see where your time went -- a visual map of tracking activity that makes patterns obvious -**Current focus:** v1.1 Modes & Filtering — defining requirements +**Current focus:** v1.1 Modes & Filtering -- Phase 6 ready to plan ## Current Position -Phase: Not started (defining requirements) -Plan: — -Status: Defining requirements -Last activity: 2026-04-08 — Milestone v1.1 started +Phase: 6 of 10 (Renderer Architecture) +Plan: -- +Status: Ready to plan +Last activity: 2026-04-08 -- Roadmap created for v1.1 (5 phases, 14 requirements mapped) Progress: [░░░░░░░░░░] 0% +## Performance Metrics + +**Velocity (v1.0):** +- Total plans completed: 11 +- Phases completed: 5 + +**v1.1:** No plans executed yet. + +## Accumulated Context + +### Decisions + +- Renderer refactor (strategy pattern) must happen before any new modes +- Week-mode uses client-side aggregation of existing DayEntry data (no backend changes) +- TomSelect must be bundled (not available as Kimai global), deferred to last phase +- Custom controller endpoints needed for entity data (Kimai API routes require IsGranted('API')) + +### Blockers/Concerns + +None yet. + ## Session Continuity Last session: 2026-04-08 -Stopped at: Milestone v1.1 started +Stopped at: Roadmap created for v1.1 milestone Resume file: None