toph/kimai-plugin-heatmap
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
kimai-plugin-heatmap/.planning/seeds/SEED-002-visualization-modes.md

2.1 KiB
Raw Blame History

id status planted planted_during trigger_when scope
SEED-002 dormant 2026-04-08 v1.0 milestone completion v1.1 or next milestone medium

SEED-002: Switchable visualization modes (year/week/day/combined)

Why This Matters

The current year-view heatmap shows broad patterns but hides finer-grained detail. A week-mode (day-of-week aggregation) reveals which weekdays are busiest. A day-mode (time-of-day heatmap) shows when during the day work happens. A combined day/hour matrix gives the full picture. Together, these modes turn the heatmap from a single view into a flexible time-analysis tool.

When to Surface

Trigger: v1.1 or next milestone

This seed should be presented during /gsd-new-milestone when the milestone scope matches any of these conditions:

  • Next milestone after v1.0
  • Milestone includes visualization improvements or display modes
  • Milestone includes the INTR-02 requirement (toggle between display modes)

Scope Estimate

Medium — Each mode is a distinct d3 layout (week grid, hour grid, combined matrix) plus a mode switcher UI element. Likely 1-2 phases: one for the mode switcher + week-mode, one for day-mode + combined.

Breadcrumbs

Related code and decisions found in the current codebase:

  • assets/src/heatmap.ts — current year-view rendering with buildGrid(), renderHeatmap(), week interval logic
  • assets/src/types.ts — DayEntry type (has date, totalHours, entryCount) — day-mode would need hour-level data
  • src/Service/HeatmapService.php — getAggregatedData() groups by DATE — hour-mode would need GROUP BY HOUR
  • src/Controller/HeatmapController.php — API endpoint would need a mode query param
  • REQUIREMENTS.md (archived) — INTR-02: "Toggle between hours-per-day and entry-count display modes" (v2 deferred)

Notes

  • The existing renderHeatmap() function could be refactored to accept a layout strategy
  • Week-mode and day-mode need different backend aggregation queries
  • Consider whether the mode switcher is tabs, a dropdown, or segmented control (Tabler has all three)
  • The combined day/hour matrix is the most complex — may warrant its own phase