toph/kimai-plugin-heatmap
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(03-01): complete JS toolchain plan

Browse source 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Christopher Mühl 2026-04-08 13:13:15 +02:00
parent 032b6f87ff
commit d95585cebf
No known key found for this signature in database
GPG key ID: 925AC7D69955293F
3 changed files with 84 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

26
.planning/ROADMAP.md
View file

@ -12,8 +12,8 @@ Build a Kimai dashboard widget that displays a GitHub-style activity heatmap of
Decimal phases appear between their surrounding integers in numeric order.
- [ ] **Phase 1: Dev Environment** - Nix flake with local Kimai instance and seeded test data
- [ ] **Phase 2: Plugin Scaffold + Data Layer** - Symfony bundle, dashboard widget, aggregation API with PHPUnit tests
- [x] **Phase 1: Dev Environment** - Nix flake with local Kimai instance and seeded test data
- [x] **Phase 2: Plugin Scaffold + Data Layer** - Symfony bundle, dashboard widget, aggregation API with PHPUnit tests
- [ ] **Phase 3: Core Heatmap Rendering** - d3.js calendar grid with color mapping, labels, tooltips, theme integration, and JS tests
- [ ] **Phase 4: Heatmap Interaction** - Click-through navigation, project/activity filtering, interaction tests
- [ ] **Phase 5: Polish** - Streak indicator, summary stats, weekend styling
@ -33,7 +33,7 @@ Decimal phases appear between their surrounding integers in numeric order.
Plans:
- [x] 01-01: Nix flake, process-compose, setup script, .gitignore
- [ ] 01-02: Plugin scaffold + Kimai bootstrap verification
- [x] 01-02: Plugin scaffold + Kimai bootstrap verification
### Phase 2: Plugin Scaffold + Data Layer
**Goal**: Plugin is recognized by Kimai, shows a widget on the dashboard, and serves aggregated daily time data via API
@ -44,11 +44,11 @@ Plans:
2. A widget placeholder appears on the Kimai dashboard
3. The API endpoint returns JSON with per-day aggregated hours and entry counts, correctly grouped by the user's timezone
4. PHPUnit tests pass for the data aggregation service and API endpoint
**Plans**: TBD
**Plans**: phase-2/PLAN.md
Plans:
- [ ] 02-01: TBD
- [ ] 02-02: TBD
- [x] 02-01: HeatmapService, PHPUnit tests, API controller
- [x] 02-02: Dashboard widget + template + DashboardSubscriber
### Phase 3: Core Heatmap Rendering
**Goal**: The dashboard widget renders a fully styled d3.js calendar heatmap from live Kimai data
@ -60,13 +60,13 @@ Plans:
3. Day-of-week labels appear on the Y-axis and month boundary labels along the top
4. Days with no tracked time render with a distinct "no data" color
5. Colors use Kimai's theme CSS variables (works with both light and dark themes)
**Plans**: TBD
**Plans**: phase-3/PLAN.md
**UI hint**: yes
Plans:
- [ ] 03-01: TBD
- [ ] 03-02: TBD
- [ ] 03-03: TBD
- [x] 03-01: JS toolchain — npm, esbuild, TypeScript, Vitest
- [ ] 03-02: d3 calendar heatmap with color scale, labels, tooltips + Vitest tests
- [ ] 03-03: Twig template integration + asset serving
### Phase 4: Heatmap Interaction
**Goal**: Users can click through to daily details and filter the heatmap by project or activity
@ -106,8 +106,8 @@ Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5
| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Dev Environment | 0/2 | Not started | - |
| 2. Plugin Scaffold + Data Layer | 0/2 | Not started | - |
| 3. Core Heatmap Rendering | 0/3 | Not started | - |
| 1. Dev Environment | 2/2 | Done | 2026-04-08 |
| 2. Plugin Scaffold + Data Layer | 2/2 | Done | 2026-04-08 |
| 3. Core Heatmap Rendering | 1/3 | In progress | - |
| 4. Heatmap Interaction | 0/2 | Not started | - |
| 5. Polish | 0/2 | Not started | - |

12
.planning/STATE.md
View file

@ -3,8 +3,8 @@ gsd_state_version: 1.0
milestone: v1.0
milestone_name: milestone
status: executing
stopped_at: Completed 02-01-PLAN
last_updated: "2026-04-08T10:50:36.592Z"
stopped_at: Completed 03-01-PLAN.md
last_updated: "2026-04-08T11:12:34.889Z"
last_activity: 2026-04-08
progress:
total_phases: 5
@ -26,7 +26,7 @@ See: .planning/PROJECT.md (updated 2026-04-08)
## Current Position
Phase: 2 of 5 (Plugin Scaffold + Data Layer)
Plan: 1 of 2 in current phase
Plan: 2 of 2 in current phase
Status: Ready to execute
Last activity: 2026-04-08
@ -53,6 +53,7 @@ Progress: [██░░░░░░░░] 20%
*Updated after each plan completion*
| Phase 2 P02-01 | 5min | 5 tasks | 8 files |
| Phase 03 P01 | 3min | 4 tasks | 7 files |
## Accumulated Context
@ -72,6 +73,7 @@ Recent decisions affecting current work:
- [Phase 1]: PHP memory_limit=1G required for Kimai cache warmup
- [Phase 1]: process-compose API server disabled (-p 0) to avoid port 8080 conflict
- [Phase 2]: Removed final from HeatmapService to allow PHPUnit mocking
- [Phase 03]: IIFE format with KimaiHeatmap global for browser compat
### Pending Todos
@ -83,6 +85,6 @@ None yet.
## Session Continuity
Last session: 2026-04-08T10:50:36.590Z
Stopped at: Completed 02-01-PLAN
Last session: 2026-04-08T11:12:34.887Z
Stopped at: Completed 03-01-PLAN.md
Resume file: None

64
.planning/phase-3/03-01-SUMMARY.md Normal file
View file

@ -0,0 +1,64 @@
---
phase: "03"
plan: "01"
subsystem: js-toolchain
tags: [typescript, esbuild, vitest, d3]
dependency_graph:
requires: []
provides: [js-build-pipeline, ts-type-checking, js-test-runner]
affects: [assets/, Resources/public/]
tech_stack:
added: [esbuild, typescript, vitest, jsdom, d3-scale, d3-selection, d3-time, d3-time-format, d3-scale-chromatic, d3-array]
patterns: [iife-bundle, esm-source]
key_files:
created:
- package.json
- tsconfig.json
- vitest.config.ts
- assets/src/heatmap.ts
- assets/test/heatmap.test.ts
- Resources/public/heatmap.js
modified:
- .gitignore
decisions:
- "IIFE format with KimaiHeatmap global name for browser compatibility"
- "ES2022 target with bundler moduleResolution"
- "jsdom environment for vitest d3 testing"
metrics:
duration: "3min"
completed: "2026-04-08"
---
# Phase 3 Plan 01: JS Toolchain Setup Summary
**One-liner:** esbuild + TypeScript + Vitest pipeline for d3 heatmap development with jsdom test environment.
## What Was Done
1. **package.json** -- Created with build/test scripts, installed d3 sub-modules as runtime deps and typescript/esbuild/vitest as dev deps
2. **tsconfig.json** -- Strict TS config targeting ES2022 with bundler module resolution
3. **vitest.config.ts** -- jsdom environment with globals enabled
4. **Placeholder source and test** -- `assets/src/heatmap.ts` stub and passing test in `assets/test/heatmap.test.ts`
5. **.gitignore** -- Added `.phpunit.result.cache`
## Verification Results
- `npm run build` -- Produces `Resources/public/heatmap.js` (537b minified)
- `npm test` -- 2 tests pass (570ms)
- `npx tsc --noEmit` -- No type errors
## Deviations from Plan
### Auto-fixed Issues
**1. [Rule 2 - Missing] Added .phpunit.result.cache to .gitignore**
- **Found during:** Task 4 verification
- **Issue:** PHPUnit result cache file was showing as untracked
- **Fix:** Added to .gitignore
- **Files modified:** .gitignore
## Commits
| Task | Commit | Description |
|------|--------|-------------|
| 1-4 | 032b6f8 | feat: add JS toolchain -- esbuild, TypeScript, Vitest |