78 lines
3.8 KiB
Markdown
78 lines
3.8 KiB
Markdown
# Kimai Heatmap Plugin
|
|
|
|
## What This Is
|
|
|
|
A Kimai dashboard widget that displays a GitHub-style activity heatmap visualizing time tracking data. Built as a Symfony bundle plugin for personal time tracking, rendering an interactive d3.js calendar heatmap with click-through navigation, project filtering, streak tracking, and summary stats.
|
|
|
|
## Core Value
|
|
|
|
At a glance, see where your time went — a visual map of tracking activity that makes patterns obvious without clicking through reports.
|
|
|
|
## Requirements
|
|
|
|
### Validated
|
|
|
|
- ✓ Dashboard widget renders a d3.js calendar heatmap of time entries — v1.0
|
|
- ✓ Filterable by project — v1.0
|
|
- ✓ Clicking a day cell navigates to Kimai's timesheet view filtered to that day — v1.0
|
|
- ✓ Color scheme uses Kimai's theme CSS variables — v1.0 (partial: tooltip/labels/empty use CSS vars, color scale hardcoded green)
|
|
- ✓ Nix flake/devshell provides a local Kimai instance with seeded database — v1.0
|
|
- ✓ PHPUnit tests for backend (API, data aggregation) — v1.0
|
|
- ✓ JavaScript tests for the d3 heatmap component — v1.0
|
|
- ✓ Streak indicator, summary stats, weekend styling — v1.0
|
|
|
|
### Active
|
|
|
|
- [ ] Switchable visualization modes (year, week, day, combined day/hour)
|
|
- [ ] Native TomSelect entity pickers with customer→project→activity cascade
|
|
- [ ] Activity filtering via cascading pickers
|
|
- [ ] Toggle between hours-per-day and entry-count display
|
|
|
|
## Current Milestone: v1.1 Modes & Filtering
|
|
|
|
**Goal:** Multiple visualization modes and richer filtering using Kimai-native UI components
|
|
|
|
**Target features:**
|
|
- Switchable views: year-mode, week-mode (day-of-week), day-mode (time-of-day), combined day/hour
|
|
- Native TomSelect entity pickers replacing plain `<select>` — customer→project→activity cascade
|
|
- Activity filtering (descoped from v1.0)
|
|
- Toggle between hours-per-day and entry-count display
|
|
|
|
### Out of Scope
|
|
|
|
- Billable hours tracking features — personal time tracking only
|
|
- Mobile-specific layout — desktop Kimai dashboard only
|
|
- Export/sharing of heatmap images — no audience for personal use
|
|
- Real-time updates — refresh on page load is fine
|
|
- Custom color theme picker — Kimai theme integration is sufficient
|
|
- Configurable time range selector — deferred to future milestone
|
|
- Multi-user comparison — personal tracking tool
|
|
|
|
## Context
|
|
|
|
Shipped v1.0 with ~650 LOC source (PHP + TypeScript) and ~730 LOC tests.
|
|
Tech stack: Symfony bundle (PHP 8.2), d3.js v7 (TypeScript), esbuild, Vitest, PHPUnit.
|
|
Dev environment: Nix flake with process-compose, MariaDB 11.4, Kimai 2.52.0.
|
|
|
|
## Constraints
|
|
|
|
- **Tech stack**: Symfony bundle (PHP) + d3.js (JavaScript), must conform to Kimai plugin architecture
|
|
- **Testing**: TDD approach — PHPUnit for backend, JS tests for frontend heatmap
|
|
- **Dev environment**: Nix flake/devshell with local Kimai and seeded DB for manual testing
|
|
- **Compatibility**: Must work with current Kimai release
|
|
|
|
## Key Decisions
|
|
|
|
| Decision | Rationale | Outcome |
|
|
|----------|-----------|---------|
|
|
| d3.js for visualization | Flexible, well-suited for calendar heatmaps | ✓ Good |
|
|
| Symfony bundle (not local plugin) | Standard Kimai plugin distribution | ✓ Good |
|
|
| Kimai theme CSS vars | Visual consistency with dashboard | ⚠️ Partial — color scale hardcoded green (Tabler lacks green scale vars) |
|
|
| TDD with PHPUnit + Vitest | Prevent regressions from AI-generated code | ✓ Good — 30+ tests |
|
|
| Nix flake for dev environment | Reproducible local Kimai instance | ✓ Good |
|
|
| IIFE format with KimaiHeatmap global | Browser compat without Kimai's Webpack Encore | ✓ Good |
|
|
| Ship prebuilt JS in Resources/public/ | Avoids hooking into Kimai's build pipeline | ✓ Good |
|
|
| Descope activity filtering | Project filter sufficient for personal use | ✓ Acceptable |
|
|
|
|
---
|
|
*Last updated: 2026-04-08 after v1.1 milestone start*
|