118 lines
6.6 KiB
Markdown
118 lines
6.6 KiB
Markdown
# 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
|
|
|
|
<details>
|
|
<summary>✅ v1.0 MVP (Phases 1-5) — SHIPPED 2026-04-08</summary>
|
|
|
|
- [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
|
|
|
|
</details>
|
|
|
|
### 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:
|
|
- [ ] 08-01-PLAN.md — Service layer: aggregation methods, cascade queries, filter support
|
|
- [ ] 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 | - |
|