kimai-plugin-heatmap/.planning/milestones/v1.0-phases/phase-4/04-RESEARCH.md

Phase 4 Research: Heatmap Interaction

Researched: 2026-04-08

Kimai Timesheet Navigation

Route

• Route name: timesheet
• URL: /timesheet
• Date filtering uses toolbar form with dateRange parameter
• Query param format for date filtering needs experimentation, but likely: /timesheet?dateRange=2026-04-08+-+2026-04-08 or similar DateRange format

Click-through approach

Navigate to /timesheet with the clicked date. The Twig template should pass the timesheet base URL via a data-timesheet-url attribute. The JS builds the full URL with date params.

Project Filtering

API endpoint

• GET /api/projects?visible=1&orderBy=name returns JSON array of projects
• Each project has id, name, customer fields
• This is a standard Kimai API endpoint with auth

Current HeatmapController

Already supports ?project=<id> query param for filtering aggregation data. No backend changes needed.

UI approach

• Render a <select> dropdown above the heatmap
• Fetch project list from /api/projects on init
• On change, re-fetch heatmap data with ?project=<id> and re-render
• "All projects" as default option (no filter)

Implementation Notes

• Click navigation and project filtering are independent features
• Both are JS-only changes + template updates (no new PHP code needed)
• Tests: mock fetch responses, verify click handlers set window.location, verify dropdown triggers re-render