docs: create milestone v1.1 roadmap (5 phases)

.planning/REQUIREMENTS.md

@@ -1,7 +1,7 @@
 # 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
+**Core Value:** At a glance, see where your time went -- a visual map of tracking activity that makes patterns obvious
 
 ## v1.1 Requirements
 
@@ -17,7 +17,7 @@ Requirements for Modes & Filtering milestone. Each maps to roadmap phases.
 
 ### Entity Pickers & Filtering
 
-- [ ] **FILT-01**: Customer→project→activity cascading TomSelect pickers replace plain <select>
+- [ ] **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
 
@@ -59,25 +59,26 @@ Requirements for Modes & Filtering milestone. Each maps to roadmap phases.
 
 | Requirement | Phase | Status |
 |-------------|-------|--------|
-| VIZ-01 | - | Pending |
+| VIZ-01 | Phase 7 | Pending |
-| VIZ-02 | - | Pending |
+| VIZ-02 | Phase 7 | Pending |
-| VIZ-03 | - | Pending |
+| VIZ-03 | Phase 9 | Pending |
-| VIZ-04 | - | Pending |
+| VIZ-04 | Phase 9 | Pending |
-| VIZ-05 | - | Pending |
+| VIZ-05 | Phase 7 | Pending |
-| FILT-01 | - | Pending |
+| FILT-01 | Phase 10 | Pending |
-| FILT-02 | - | Pending |
+| FILT-02 | Phase 8 | Pending |
-| FILT-03 | - | Pending |
+| FILT-03 | Phase 8 | Pending |
-| API-01 | - | Pending |
+| API-01 | Phase 8 | Pending |
-| API-02 | - | Pending |
+| API-02 | Phase 8 | Pending |
-| POL-01 | - | Pending |
+| POL-01 | Phase 9 | Pending |
-| TEST-01 | - | Pending |
+| TEST-01 | Phase 7 | Pending |
-| TEST-02 | - | Pending |
+| TEST-02 | Phase 10 | Pending |
-| TEST-03 | - | Pending |
+| TEST-03 | Phase 8 | Pending |
 
 **Coverage:**
 - v1.1 requirements: 14 total
-- Mapped to phases: 0
+- Mapped to phases: 14
-- Unmapped: 14
+- Unmapped: 0
 
 ---
 *Requirements defined: 2026-04-08*
+*Traceability updated: 2026-04-08*

.planning/ROADMAP.md

@@ -3,6 +3,7 @@
 ## Milestones
 
 - ✅ **v1.0 MVP** — Phases 1-5 (shipped 2026-04-08) — [archive](milestones/v1.0-ROADMAP.md)
+- 🚧 **v1.1 Modes & Filtering** — Phases 6-10 (in progress)
 
 ## Phases
 
@@ -17,8 +18,83 @@
 
 </details>
 
+### v1.1 Modes & Filtering
+
+- [ ] **Phase 6: Renderer Architecture** - Refactor monolithic renderHeatmap into strategy-pattern mode system with state management
+- [ ] **Phase 7: Mode Switcher + Week Mode** - First visible v1.1 feature: mode switcher UI, week-mode renderer, hours/count toggle
+- [ ] **Phase 8: Backend Aggregation + Filtering** - Hour-level and day/hour aggregation queries, activity/customer filtering, custom endpoints
+- [ ] **Phase 9: Day + Combined Modes** - Day-of-week and time-of-day renderers, combined punchcard matrix, color scale legend
+- [ ] **Phase 10: Entity Pickers** - TomSelect cascading customer/project/activity pickers replacing plain selects
+
+## Phase Details
+
+### Phase 6: Renderer Architecture
+**Goal**: Existing year-view heatmap works identically but through a mode-dispatched renderer system ready for new visualization modes
+**Depends on**: Phase 5 (v1.0 shipped codebase)
+**Requirements**: None (architectural enabler -- all v1.1 features depend on this refactor)
+**Success Criteria** (what must be TRUE):
+  1. Year-view heatmap renders identically to v1.0 behavior (no visual regression)
+  2. Tooltip, color scale, and cell click handler are extracted as shared utilities reusable by any renderer
+  3. A HeatmapState object tracks mode, display metric, and filters -- UI changes flow through state
+  4. Adding a new visualization mode requires only implementing a ModeRenderer interface and registering it
+**Plans**: TBD
+
+### Phase 7: Mode Switcher + Week Mode
+**Goal**: Users can switch between year and week visualization modes and toggle between hours and entry-count display
+**Depends on**: Phase 6
+**Requirements**: VIZ-01, VIZ-02, VIZ-05, TEST-01
+**Success Criteria** (what must be TRUE):
+  1. A segmented control in the widget header lets the user switch between year and week views
+  2. Week-mode shows a day-of-week aggregation heatmap revealing which weekdays are busiest
+  3. Hours/count toggle switches the color scale metric across both year and week modes without re-fetching data
+  4. Switching modes preserves the current filter selection
+  5. Vitest tests cover mode switcher interaction, week renderer output, and display toggle behavior
+**Plans**: TBD
+**UI hint**: yes
+
+### Phase 8: Backend Aggregation + Filtering
+**Goal**: Backend serves hour-level and day/hour aggregation data and accepts activity and customer filter params via custom endpoints
+**Depends on**: Phase 6
+**Requirements**: API-01, API-02, FILT-02, FILT-03, TEST-03
+**Success Criteria** (what must be TRUE):
+  1. API endpoint accepts a mode param and returns hourly aggregation data (for day-mode) and day/hour aggregation data (for combined mode)
+  2. Activity filter param narrows heatmap data to entries matching a specific activity
+  3. Customer filter param narrows heatmap data to all projects under a selected customer
+  4. Custom cascade endpoints (/heatmap/customers, /heatmap/projects, /heatmap/activities) return entity lists using session auth (not API auth)
+  5. PHPUnit tests cover hourly aggregation, day/hour aggregation, and filter parameter handling
+**Plans**: TBD
+
+### Phase 9: Day + Combined Modes
+**Goal**: Users can view time-of-day and day/hour punchcard visualizations with a color scale legend
+**Depends on**: Phase 7 (mode switcher), Phase 8 (backend aggregation data)
+**Requirements**: VIZ-03, VIZ-04, POL-01
+**Success Criteria** (what must be TRUE):
+  1. Day-mode renders a time-of-day heatmap showing when during the day work happens (24 hour slots)
+  2. Combined mode renders a 7x24 punchcard matrix showing day-of-week vs hour-of-day patterns
+  3. Mode switcher now offers all four modes (year, week, day, combined) and all work end-to-end
+  4. A color scale legend gradient bar shows the value range for the current mode and metric
+**Plans**: TBD
+**UI hint**: yes
+
+### Phase 10: Entity Pickers
+**Goal**: Users filter the heatmap using Kimai-native TomSelect pickers with customer/project/activity cascade
+**Depends on**: Phase 8 (custom cascade endpoints)
+**Requirements**: FILT-01, TEST-02
+**Success Criteria** (what must be TRUE):
+  1. Customer, project, and activity pickers use TomSelect with search/autocomplete replacing plain select elements
+  2. Selecting a customer filters the project picker to that customer's projects and the activity picker to matching activities
+  3. Selecting a project filters the activity picker to that project's activities
+  4. Clearing a parent picker resets child pickers and updates the heatmap accordingly
+  5. Vitest tests cover cascade behavior, empty states, and filter-to-heatmap integration
+**Plans**: TBD
+**UI hint**: yes
+
 ## Progress
 
+**Execution Order:**
+Phases execute in numeric order: 6 -> 7 -> 8 -> 9 -> 10
+Note: Phases 7 and 8 can execute in parallel (both depend only on Phase 6).
+
 | Phase | Milestone | Plans Complete | Status | Completed |
 |-------|-----------|----------------|--------|-----------|
 | 1. Dev Environment | v1.0 | 2/2 | Complete | 2026-04-08 |
@@ -26,3 +102,8 @@
 | 3. Core Heatmap Rendering | v1.0 | 3/3 | Complete | 2026-04-08 |
 | 4. Heatmap Interaction | v1.0 | 2/2 | Complete | 2026-04-08 |
 | 5. Polish | v1.0 | 2/2 | Complete | 2026-04-08 |
+| 6. Renderer Architecture | v1.1 | 0/? | Not started | - |
+| 7. Mode Switcher + Week Mode | v1.1 | 0/? | Not started | - |
+| 8. Backend Aggregation + Filtering | v1.1 | 0/? | Not started | - |
+| 9. Day + Combined Modes | v1.1 | 0/? | Not started | - |
+| 10. Entity Pickers | v1.1 | 0/? | Not started | - |

.planning/STATE.md

@@ -2,12 +2,12 @@
 gsd_state_version: 1.0
 milestone: v1.1
 milestone_name: Modes & Filtering
-status: defining_requirements
+status: ready_to_plan
-stopped_at: Milestone v1.1 started
+stopped_at: Roadmap created for v1.1 (Phases 6-10)
-last_updated: "2026-04-08T22:00:00.000Z"
+last_updated: "2026-04-08T23:00:00.000Z"
 last_activity: 2026-04-08
 progress:
-  total_phases: 0
+  total_phases: 5
   completed_phases: 0
   total_plans: 0
   completed_plans: 0
@@ -21,19 +21,40 @@ progress:
 See: .planning/PROJECT.md (updated 2026-04-08)
 
 **Core value:** At a glance, see where your time went -- a visual map of tracking activity that makes patterns obvious
-**Current focus:** v1.1 Modes & Filtering — defining requirements
+**Current focus:** v1.1 Modes & Filtering -- Phase 6 ready to plan
 
 ## Current Position
 
-Phase: Not started (defining requirements)
+Phase: 6 of 10 (Renderer Architecture)
-Plan: —
+Plan: --
-Status: Defining requirements
+Status: Ready to plan
-Last activity: 2026-04-08 — Milestone v1.1 started
+Last activity: 2026-04-08 -- Roadmap created for v1.1 (5 phases, 14 requirements mapped)
 
 Progress: [░░░░░░░░░░] 0%
 
+## Performance Metrics
+
+**Velocity (v1.0):**
+- Total plans completed: 11
+- Phases completed: 5
+
+**v1.1:** No plans executed yet.
+
+## Accumulated Context
+
+### Decisions
+
+- Renderer refactor (strategy pattern) must happen before any new modes
+- Week-mode uses client-side aggregation of existing DayEntry data (no backend changes)
+- TomSelect must be bundled (not available as Kimai global), deferred to last phase
+- Custom controller endpoints needed for entity data (Kimai API routes require IsGranted('API'))
+
+### Blockers/Concerns
+
+None yet.
+
 ## Session Continuity
 
 Last session: 2026-04-08
-Stopped at: Milestone v1.1 started
+Stopped at: Roadmap created for v1.1 milestone
 Resume file: None