kimai-plugin-heatmap/.planning/research/FEATURES.md

# Feature Landscape

**Domain:** Time-tracking activity heatmap dashboard widget (Kimai plugin)
**Researched:** 2026-04-08
**Overall confidence:** MEDIUM (based on training data knowledge of GitHub, GitLab, WakaTime, RescueTime, Toggl, and open-source heatmap libraries; no live verification available)

## Reference Products Analyzed

| Product | Heatmap Style | Key Insight |
|---------|--------------|-------------|
| GitHub contribution graph | Year-long calendar grid, 5 color levels, tooltips | The gold standard UX -- simple, instantly understood, no configuration needed |
| GitLab activity calendar | Same layout as GitHub, slightly different color scheme | Proves the pattern is universal for developer audiences |
| WakaTime | Calendar heatmap + line charts + breakdowns by language/project | Heavier analytics layer on top of the basic heatmap |
| RescueTime | Daily productivity scores, category breakdowns, hour-of-day patterns | Focus on productivity categorization, not raw activity |
| Toggl Track insights | Weekly/monthly bar charts, project pie charts, calendar view | More report-centric than heatmap-centric |
| cal-heatmap (JS library) | Configurable calendar heatmap, multiple layouts | Popular open-source implementation, good API reference |

## Table Stakes

Features users expect from any calendar heatmap. Missing any of these makes the widget feel broken or incomplete.

| Feature | Why Expected | Complexity | Notes |
|---------|--------------|------------|-------|
| Calendar grid layout (weeks x days) | This IS the product -- the GitHub-style grid is the universally recognized pattern | Medium | d3.js renders SVG grid; each cell = one day |
| Color intensity mapping | Users expect darker = more activity, lighter = less; this is how every heatmap works | Low | 4-5 discrete color levels (empty, low, medium, high, very high) |
| Tooltip on hover | Every reference product shows exact values on hover; without it users stare at colors guessing | Low | Show date, hours tracked, entry count |
| Sensible default time range | GitHub shows 1 year; users expect to see something useful without configuration | Low | Default to trailing 12 months |
| Day-of-week labels | Mon/Wed/Fri labels on the Y-axis for orientation | Low | Standard in GitHub/GitLab graphs |
| Month labels | Column headers showing month boundaries | Low | Standard in all calendar heatmaps |
| Empty state | Days with no entries should render as a distinct "no data" color, not be invisible | Low | Light gray or the theme's muted background color |
| Click-through to detail | Clicking a day should take you somewhere useful | Low | Navigate to Kimai timesheet view filtered to that date (already in PROJECT.md requirements) |
| Theme integration | Must not look like a foreign element glued onto the dashboard | Low | Use Kimai CSS variables for colors |

## Differentiators

Features that elevate the widget beyond a static pretty picture. Not expected by default, but each adds meaningful value for a personal time-tracking use case.

| Feature | Value Proposition | Complexity | Notes |
|---------|-------------------|------------|-------|
| Toggle between hours and entry count | Different questions: "how much did I work?" vs "how consistently did I track?" -- GitHub only shows one metric | Low | Button or toggle in widget header; already in PROJECT.md requirements |
| Project/activity filter | Focus on one project at a time to see its cadence | Medium | Dropdown populated from Kimai data; re-renders heatmap on change |
| Configurable time range | See last 3 months, 6 months, full year, or custom range | Medium | Range selector in widget header; affects data query and grid size |
| Streak indicator | "Current streak: 12 days" -- gamification that motivates consistency | Low | Simple calculation: count consecutive non-zero days ending at today |
| Summary stats row | Total hours, average hours/day, busiest day -- quick numbers alongside the visual | Low | Small text row below or above the heatmap |
| Weekend vs weekday distinction | Subtle visual indicator (border, opacity) for weekends | Low | Helps distinguish work patterns from weekend work |
| Responsive widget sizing | Widget that adapts if Kimai dashboard column width changes | Medium | SVG viewBox scaling; cell size calculation based on container width |

## Anti-Features

Things to deliberately NOT build. Each would add complexity without serving the core "at a glance, see where your time went" purpose.

| Anti-Feature | Why Avoid | What to Do Instead |
|--------------|-----------|-------------------|
| Real-time updates / live refresh | Overengineered for a dashboard widget; page reload is fine for daily granularity data | Refresh data on page load only |
| Billable vs non-billable split | Out of scope per PROJECT.md; this is personal tracking, not client billing | Single aggregate view |
| Export/share heatmap as image | Out of scope per PROJECT.md; no audience to share with for personal use | Users can screenshot if needed |
| Hour-of-day heatmap (2D matrix) | Different visualization entirely; scope creep that doubles the frontend work | Stick to the calendar grid; could be a separate widget later |
| Drill-down charts within the widget | Clicking a day to show a pie chart of projects within the widget adds major complexity | Click-through to Kimai's existing timesheet/report views instead |
| Multi-user comparison | Personal tracking tool, not a team dashboard | Single-user view only |
| Goal setting / targets | Adds state management, settings UI, persistence -- a separate feature domain | Streak indicator covers the motivational angle simply |
| Animated transitions on data change | Cool but adds JS complexity for near-zero utility on a dashboard widget | Instant re-render on filter change |
| Mobile-specific layout | Out of scope per PROJECT.md; Kimai dashboard is a desktop experience | Standard responsive SVG is sufficient |
| Custom color theme picker | Theme integration with Kimai variables is sufficient; custom palettes add a settings UI nobody needs | Use Kimai theme variables, pick a single well-tested palette |

## Feature Dependencies

```
Calendar grid layout
  --> Color intensity mapping (needs the grid to color)
  --> Tooltip on hover (needs cells to attach to)
  --> Click-through to detail (needs cells to click)
  --> Empty state (needs grid cells for empty days)
  --> Day/Month labels (needs the grid structure)

Toggle hours/count
  --> Requires backend to return BOTH hours and count per day
  --> Re-maps color intensity without re-fetching data

Project/activity filter
  --> Requires backend filter parameter in data API
  --> Dropdown populated via separate Kimai API call (projects list)
  --> Triggers data re-fetch + full heatmap re-render

Configurable time range
  --> Requires backend date range parameter in data API
  --> Affects grid dimensions (fewer weeks = smaller grid)
  --> Triggers data re-fetch + full heatmap re-render

Streak indicator
  --> Depends on the same daily aggregation data as the heatmap
  --> No additional backend work if heatmap data is already loaded

Summary stats
  --> Depends on the same daily aggregation data as the heatmap
  --> Pure frontend calculation from existing data
```

## MVP Recommendation

**Phase 1 -- Core heatmap (all table stakes):**
1. Calendar grid with color intensity (the product itself)
2. Tooltips on hover
3. Day/month labels and empty state
4. Click-through to Kimai timesheet view
5. Kimai theme integration

**Phase 2 -- Interactivity (high-value differentiators):**
1. Toggle between hours and entry count
2. Project/activity filter dropdown
3. Configurable time range

**Phase 3 -- Polish (low-effort differentiators):**
1. Streak indicator
2. Summary stats row
3. Weekend distinction

**Defer indefinitely:**
- Hour-of-day matrix, export, goals, animations, multi-user -- all anti-features for this context.

**Rationale:** Phase 1 delivers a complete, useful widget. Phase 2 adds the interactivity that makes it genuinely better than just looking at Kimai's existing reports. Phase 3 is cheap polish that improves daily experience but isn't blocking.

## Sources

- GitHub contribution graph: well-known UX pattern (5 color levels, year grid, tooltips, contribution count)
- GitLab activity calendar: same pattern, confirms universality
- WakaTime dashboard: adds analytics layer (coding time heatmap, project breakdowns, streak tracking)
- RescueTime: productivity scoring approach, hour-of-day patterns
- Toggl Track insights: report-centric visualizations, project breakdowns
- cal-heatmap.com: popular open-source JS calendar heatmap library, API design reference
- All sourced from training data (no live verification available) -- MEDIUM confidence