# Requirements: Kimai Heatmap Plugin v1.1

**Defined:** 2026-04-08
**Core Value:** At a glance, see where your time went -- a visual map of tracking activity that makes patterns obvious

## v1.1 Requirements

Requirements for Modes & Filtering milestone. Each maps to roadmap phases.

### Visualization Modes

- [ ] **VIZ-01**: Mode switcher UI allows toggling between year, week, day, and combined views
- [ ] **VIZ-02**: Week-mode renders day-of-week aggregation showing which weekdays are busiest
- [ ] **VIZ-03**: Day-mode renders time-of-day heatmap showing when during the day work happens
- [ ] **VIZ-04**: Combined mode renders 7x24 day/hour punchcard matrix
- [ ] **VIZ-05**: Hours vs entry-count toggle switches color scale metric across all modes

### Entity Pickers & Filtering

- [ ] **FILT-01**: Customer->project->activity cascading TomSelect pickers replace plain <select>
- [ ] **FILT-02**: Activity filtering narrows heatmap data to a specific activity
- [ ] **FILT-03**: Customer filtering narrows heatmap data to all projects under a customer

### Backend

- [ ] **API-01**: API endpoint accepts mode param returning hour-level and day/hour aggregation data
- [ ] **API-02**: API endpoint accepts activity and customer filter params with own controller endpoints

### Polish

- [ ] **POL-01**: Color scale legend gradient bar showing value range for current mode/metric

### Testing

- [ ] **TEST-01**: Vitest tests for mode switcher, each renderer, and display toggle
- [ ] **TEST-02**: Vitest tests for TomSelect cascade behavior and filter integration
- [ ] **TEST-03**: PHPUnit tests for hour-level and day/hour aggregation queries

## Future Requirements

- Configurable time range selector (3 months, 6 months, year, custom)
- Persistent filter/mode state via URL params or localStorage
- Animated transitions between visualization modes
- Responsive widget sizing adapting to dashboard column width

## Out of Scope

| Feature | Reason |
|---------|--------|
| Billable vs non-billable split | Personal time tracking, not client billing |
| Real-time / live updates | Page reload sufficient for daily-granularity data |
| Export/share heatmap as image | No audience for personal use |
| Multi-user comparison | Personal tracking tool |
| Mobile-specific layout | Desktop Kimai dashboard only |
| Reuse Kimai's KimaiFormSelect.js | Coupled to Kimai's plugin container, cannot work in widget context |
| Reuse Kimai's API routes for pickers | Require IsGranted('API') permission, need own endpoints |

## Traceability

| Requirement | Phase | Status |
|-------------|-------|--------|
| VIZ-01 | Phase 7 | Pending |
| VIZ-02 | Phase 7 | Pending |
| VIZ-03 | Phase 9 | Pending |
| VIZ-04 | Phase 9 | Pending |
| VIZ-05 | Phase 7 | Pending |
| FILT-01 | Phase 10 | Pending |
| FILT-02 | Phase 8 | Pending |
| FILT-03 | Phase 8 | Pending |
| API-01 | Phase 8 | Pending |
| API-02 | Phase 8 | Pending |
| POL-01 | Phase 9 | Pending |
| TEST-01 | Phase 7 | Pending |
| TEST-02 | Phase 10 | Pending |
| TEST-03 | Phase 8 | Pending |

**Coverage:**
- v1.1 requirements: 14 total
- Mapped to phases: 14
- Unmapped: 0

---
*Requirements defined: 2026-04-08*
*Traceability updated: 2026-04-08*