toph/kimai-plugin-heatmap
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
kimai-plugin-heatmap/.planning/ROADMAP.md

6.4 KiB
Raw Blame History

Roadmap: Kimai Heatmap Plugin

Milestones

  • ✅ v1.0 MVP — Phases 1-5 (shipped 2026-04-08) — archive
  • 🚧 v1.1 Modes & Filtering — Phases 6-10 (in progress)

Phases

✅ v1.0 MVP (Phases 1-5) — SHIPPED 2026-04-08
  • Phase 1: Dev Environment (2/2 plans) — completed 2026-04-08
  • Phase 2: Plugin Scaffold + Data Layer (2/2 plans) — completed 2026-04-08
  • Phase 3: Core Heatmap Rendering (3/3 plans) — completed 2026-04-08
  • Phase 4: Heatmap Interaction (2/2 plans) — completed 2026-04-08
  • 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:
  • 06-01-PLAN.md — Type contracts, state, registry, and shared utility extraction
  • 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:
  • 07-01-PLAN.md — UI controls (mode switcher + metric toggle), Twig template, orchestrator wiring
  • 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: 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
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/? Not started -
9. Day + Combined Modes v1.1 0/? Not started -
10. Entity Pickers v1.1 0/? Not started -