# Roadmap: Kimai Heatmap Plugin ## 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
✅ v1.0 MVP (Phases 1-5) — SHIPPED 2026-04-08 - [x] Phase 1: Dev Environment (2/2 plans) — completed 2026-04-08 - [x] Phase 2: Plugin Scaffold + Data Layer (2/2 plans) — completed 2026-04-08 - [x] Phase 3: Core Heatmap Rendering (3/3 plans) — completed 2026-04-08 - [x] Phase 4: Heatmap Interaction (2/2 plans) — completed 2026-04-08 - [x] Phase 5: Polish (2/2 plans) — completed 2026-04-08
### 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:** 2 plans Plans: - [x] 06-01-PLAN.md — Type contracts, state, registry, and shared utility extraction - [x] 06-02-PLAN.md — YearModeRenderer, orchestrator rewrite, test migration, visual check ### 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:** 2 plans Plans: - [x] 07-01-PLAN.md — UI controls (mode switcher + metric toggle), Twig template, orchestrator wiring - [x] 07-02-PLAN.md — WeekModeRenderer implementation, registration, visual verification **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:** 2 plans Plans: - [x] 08-01-PLAN.md — Service layer: aggregation methods, cascade queries, filter support - [x] 08-02-PLAN.md — Controller: mode dispatch, cascade endpoints, TS types ### 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 | | 2. Plugin Scaffold + Data Layer | v1.0 | 2/2 | Complete | 2026-04-08 | | 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/2 | Planned | - | | 7. Mode Switcher + Week Mode | v1.1 | 0/2 | Planned | - | | 8. Backend Aggregation + Filtering | v1.1 | 0/2 | Not started | - | | 9. Day + Combined Modes | v1.1 | 0/? | Not started | - | | 10. Entity Pickers | v1.1 | 0/? | Not started | - |