From 79e15a1232c4cdcd849be7bb7aa67fb8b95ca416 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christopher=20M=C3=BChl?= Date: Thu, 9 Apr 2026 10:48:42 +0200 Subject: [PATCH] docs(07): research phase domain --- .../07-mode-switcher-week-mode/07-RESEARCH.md | 395 ++++++++++++++++++ 1 file changed, 395 insertions(+) create mode 100644 .planning/phases/07-mode-switcher-week-mode/07-RESEARCH.md diff --git a/.planning/phases/07-mode-switcher-week-mode/07-RESEARCH.md b/.planning/phases/07-mode-switcher-week-mode/07-RESEARCH.md new file mode 100644 index 0000000..d740232 --- /dev/null +++ b/.planning/phases/07-mode-switcher-week-mode/07-RESEARCH.md @@ -0,0 +1,395 @@ +# Phase 7: Mode Switcher + Week Mode - Research + +**Researched:** 2026-04-09 +**Domain:** d3.js visualization modes, Tabler UI segmented controls, client-side data aggregation +**Confidence:** HIGH + +## Summary + +Phase 7 adds two UI controls (mode switcher and hours/count toggle) and one new renderer (WeekModeRenderer) to the existing strategy-pattern architecture from Phase 6. The infrastructure is solid -- `ModeRenderer` interface, renderer registry, `HeatmapState` with `mode` and `metric` fields, and shared utilities (color scale, tooltip, date-utils) are all in place. The new work is: (1) render two Tabler `nav-segmented` controls in the widget header, (2) wire their click handlers to update `state.mode` and `state.metric` then call `doRender()`, and (3) implement `WeekModeRenderer` that aggregates `DayEntry[]` by weekday and renders 7 colored cells. + +Tabler provides a native `nav-segmented` component that matches the "segmented control" design from CONTEXT.md decisions. No custom CSS needed for the control itself -- just Tabler classes. The week-mode renderer is straightforward d3 work: group existing data by day-of-week (0-6), sum hours/count per weekday, render 7 rectangles with the shared `buildColorScale()`. The `getDayLabels()` and weekday-index calculation in `date-utils.ts` already handle start-of-week preference. + +**Primary recommendation:** Build controls in JS (not Twig) since they interact with `HeatmapState`; keep the Twig template unchanged. Register `WeekModeRenderer` alongside `YearModeRenderer` at module level. + + +## User Constraints (from CONTEXT.md) + +### Locked Decisions +- D-01: Segmented control in widget header row (Kimai Tabler card header area), next to title +- D-02: "Year" and "Week" as the two mode options (Day/Combined in Phase 9) +- D-03: Active mode highlighted using Kimai/Tabler CSS conventions +- D-04: Week-mode horizontal layout -- 7 cells, one per weekday, colored by aggregated metric +- D-05: Day labels alongside cells, respecting user's start-of-week from `state.weekStart` +- D-06: Client-side aggregation of existing DayEntry[] grouped by weekday (no backend changes) +- D-07: Tooltip on hover: weekday name + aggregated value +- D-08: Hours/Count toggle is a separate small segmented control +- D-09: Placed adjacent to mode switcher in header +- D-10: Toggles `state.metric` between 'hours' and 'count', triggers re-render without re-fetch +- D-11: Affects color scale in both year and week modes + +### Claude's Discretion +- Exact sizing/spacing of week-mode cells +- Whether week-mode cells are clickable (and what click-through shows) +- Stats row behavior when in week mode +- Exact Tabler CSS classes for segmented controls +- Animation/transition when switching modes + +### Deferred Ideas (OUT OF SCOPE) +None + + + +## Phase Requirements + +| ID | Description | Research Support | +|----|-------------|------------------| +| VIZ-01 | Mode switcher UI allows toggling between year, week, day, and combined views | Tabler `nav-segmented` component; only Year/Week for this phase per D-02 | +| VIZ-02 | Week-mode renders day-of-week aggregation showing busiest weekdays | WeekModeRenderer with client-side DayEntry grouping by weekday | +| VIZ-05 | Hours vs entry-count toggle switches color scale metric across all modes | Separate `nav-segmented` control toggling `state.metric`; `buildColorScale()` already metric-aware | +| TEST-01 | Vitest tests for mode switcher, each renderer, and display toggle | Test patterns established in existing 9 test files; jsdom environment | + + +## Standard Stack + +### Core (already installed -- no new packages) +| Library | Version | Purpose | Why Standard | +|---------|---------|---------|--------------| +| d3-selection | ^3.0.0 | DOM manipulation for week cells | Already in use for year renderer | +| d3-scale | ^4.0.2 | Color scale for week cells | `buildColorScale()` already wraps this | +| d3-array | ^3.2.4 | `max()` for scale domain | Already in shared/color-scale.ts | +| vitest | ^4.1.3 | Test runner | Already configured with jsdom | + +No new npm packages required. [VERIFIED: package.json in codebase] + +### Tabler CSS (bundled with Kimai) +| Component | Classes | Purpose | +|-----------|---------|---------| +| Segmented control | `nav nav-segmented`, `nav-link`, `active` | Mode switcher and metric toggle | +| Small variant | `nav-sm` | Compact toggle for hours/count | + +[CITED: docs.tabler.io/ui/components/segmented-control] + +## Architecture Patterns + +### Project Structure (new files only) +``` +assets/ + src/ + renderers/ + week.ts # NEW: WeekModeRenderer + ui/ + controls.ts # NEW: mode switcher + metric toggle DOM builders + test/ + week.test.ts # NEW: WeekModeRenderer tests + controls.test.ts # NEW: UI control interaction tests +``` + +### Pattern 1: WeekModeRenderer (Strategy Pattern Extension) + +**What:** New renderer implementing `ModeRenderer` interface, registered via `registerRenderer()`. + +**When to use:** Rendering the week-mode aggregation view. + +**Example:** +```typescript +// assets/src/renderers/week.ts +import type { ModeRenderer, RenderContext } from './types'; +import { registerRenderer } from './registry'; +import { buildColorScale } from '../shared/color-scale'; +import { createTooltip, showTooltip, hideTooltip } from '../shared/tooltip'; + +interface WeekdayAggregate { + dayIndex: number; // 0-6, relative to weekStart + label: string; // "Mon", "Tue", etc. + totalHours: number; + totalCount: number; + dayCount: number; // number of occurrences for averaging +} + +export class WeekModeRenderer implements ModeRenderer { + readonly mode = 'week'; + private tooltip: HTMLDivElement | null = null; + + render(ctx: RenderContext): void { + // 1. Aggregate DayEntry[] by weekday + // 2. Build 7-cell horizontal SVG + // 3. Color via buildColorScale() using ctx.state.metric + // 4. Attach tooltip handlers + } + + destroy(): void { + this.tooltip?.remove(); + this.tooltip = null; + } +} + +// Module-level registration +registerRenderer(new WeekModeRenderer()); +``` + +### Pattern 2: UI Controls (JS-driven, not Twig) + +**What:** Build mode switcher and metric toggle as DOM elements in `heatmap.ts` init, inserted into the widget header area. + +**Why JS not Twig:** Controls must interact with `HeatmapState` and call `doRender()`. Putting them in Twig would require a separate event-binding pass and Twig has no knowledge of JS state. Building them in JS during init keeps the coupling clean. + +**Example:** +```typescript +// assets/src/ui/controls.ts +export interface ControlCallbacks { + onModeChange: (mode: string) => void; + onMetricChange: (metric: string) => void; +} + +export function createModeControl( + activeMode: string, + modes: Array<{ key: string; label: string }>, + onChange: (mode: string) => void, +): HTMLElement { + const nav = document.createElement('nav'); + nav.className = 'nav nav-segmented'; + nav.setAttribute('role', 'tablist'); + + for (const m of modes) { + const btn = document.createElement('button'); + btn.className = 'nav-link' + (m.key === activeMode ? ' active' : ''); + btn.setAttribute('role', 'tab'); + btn.textContent = m.label; + btn.addEventListener('click', () => { + nav.querySelectorAll('.nav-link').forEach(b => b.classList.remove('active')); + btn.classList.add('active'); + onChange(m.key); + }); + nav.appendChild(btn); + } + return nav; +} + +export function createMetricControl( + activeMetric: string, + onChange: (metric: string) => void, +): HTMLElement { + // Same pattern, nav-sm for compact size + const nav = document.createElement('nav'); + nav.className = 'nav nav-segmented nav-sm'; + // ... buttons for 'Hours' and 'Count' + return nav; +} +``` + +### Pattern 3: Weekday Aggregation (Client-Side) + +**What:** Group `DayEntry[]` by day-of-week index, summing hours and counts. + +**Key detail:** Must respect `state.weekStart`. The existing `date-utils.ts` calculates `dayOfWeek` as `(jsDay + 6) % 7` for Monday start and `jsDay` for Sunday start. Reuse the same logic. + +```typescript +function aggregateByWeekday( + days: DayEntry[], + weekStart: string, +): WeekdayAggregate[] { + const buckets = new Array(7).fill(null).map((_, i) => ({ + dayIndex: i, + label: '', // filled from getDayLabels or full-name variant + totalHours: 0, + totalCount: 0, + dayCount: 0, + })); + + for (const d of days) { + const jsDay = new Date(d.date + 'T00:00:00').getDay(); + const idx = weekStart === 'sunday' ? jsDay : (jsDay + 6) % 7; + buckets[idx].totalHours += d.hours; + buckets[idx].totalCount += d.count; + buckets[idx].dayCount += 1; + } + return buckets; +} +``` + +### Pattern 4: Control Placement in Widget Header + +**What:** Insert controls into the card header alongside the existing title. + +**Approach:** The Twig template uses `@theme/embeds/card.html.twig`. The `{% block box_title %}` currently holds just `{{ title }}`. Two options: + +1. **Modify Twig** to add a placeholder `
` in `box_title` block -- then JS populates it. +2. **Pure JS** -- find the `.card-header` parent of `#heatmap-container` and inject controls. + +**Recommendation:** Option 1 -- add a controls placeholder in Twig. This is cleaner because it ensures the layout structure is correct even before JS loads, and avoids fragile DOM traversal. + +```twig +{% block box_title %} +
+ {{ title }} +
+
+{% endblock %} +``` + +Then in `heatmap.ts`, build controls and append to `#heatmap-controls`. + +### Anti-Patterns to Avoid +- **Merging mode switcher and metric toggle into one control:** CONTEXT.md D-08 explicitly says separate controls. +- **Re-fetching data on metric toggle:** D-10 says re-render without re-fetch. The data already has both `hours` and `count` fields. +- **Building week renderer from scratch without shared utilities:** `buildColorScale()`, tooltip helpers, and `getDayLabels()` are all reusable. + +## Don't Hand-Roll + +| Problem | Don't Build | Use Instead | Why | +|---------|-------------|-------------|-----| +| Segmented control UI | Custom toggle buttons with manual styling | Tabler `nav-segmented` classes | Native Kimai theme integration, accessible markup | +| Color scale | New scale for week cells | `buildColorScale()` from shared/color-scale.ts | Already metric-aware, consistent across modes | +| Tooltips | New tooltip logic | `createTooltip/showTooltip/hideTooltip` from shared/tooltip.ts | Consistent behavior, already tested | +| Weekday ordering | Hard-coded day arrays | Reuse `(jsDay + 6) % 7` pattern from date-utils.ts | Already handles Monday/Sunday start | + +## Common Pitfalls + +### Pitfall 1: Weekday Index Mismatch Between Aggregation and Labels +**What goes wrong:** Aggregation uses one weekday ordering, labels use another, so Tuesday's data shows on Monday's cell. +**Why it happens:** JS `Date.getDay()` returns 0=Sunday. The existing code remaps for Monday-start. If aggregation and label generation use different mappings, they desync. +**How to avoid:** Use the exact same index formula as `generateCells()` in date-utils.ts: `weekStart === 'sunday' ? jsDay : (jsDay + 6) % 7`. Map labels using the same index. +**Warning signs:** Tests with known weekday data showing wrong labels. + +### Pitfall 2: Empty Aggregate Buckets Confuse Color Scale +**What goes wrong:** Weekdays with zero entries get passed to `buildColorScale()` which sets domain `[0, maxVal]`, and zero values map to the lowest color bucket instead of showing as empty. +**Why it happens:** `buildColorScale` maps any value in `[0, maxVal]` to a color. Zero is technically in-domain. +**How to avoid:** Either (a) filter out zero-value weekdays before passing to color scale and render them as empty cells, or (b) treat weekdays with `dayCount === 0` as empty (no fill), similar to how year-mode handles null entries. +**Warning signs:** All 7 cells colored even when user tracked on only 3 weekdays. + +### Pitfall 3: Controls Not Reflecting State After Re-render +**What goes wrong:** Mode or metric changes correctly, but if `doRender()` rebuilds the entire container, controls get destroyed. +**Why it happens:** `heatmap.ts`'s `doRender()` calls `renderer.render(ctx)` which does `ctx.container.innerHTML = ''` on the SVG area. If controls are inside the SVG area, they vanish. +**How to avoid:** Controls live outside the SVG area container (in the card header via `#heatmap-controls`). The renderer only clears `svgArea`, not the card header. +**Warning signs:** Controls disappear after first interaction. + +### Pitfall 4: Stats Row Showing Year-Specific Data in Week Mode +**What goes wrong:** Streak counter and "busiest day" stats show in week mode where they don't make contextual sense. +**Why it happens:** `renderStats()` is called unconditionally after every `doRender()`. +**How to avoid:** Either skip `renderStats()` when mode is 'week', or show week-appropriate stats (e.g., busiest weekday, average per weekday). Simplest: hide stats in week mode for now. +**Warning signs:** "Busiest: Mon, Jan 13" showing below a weekday aggregation view. + +## Code Examples + +### Weekday Aggregation with Full Labels +```typescript +// Full weekday names for tooltips (D-07 wants "Monday: 42.5h") +const WEEKDAY_NAMES_MONDAY = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday']; +const WEEKDAY_NAMES_SUNDAY = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday']; + +function getWeekdayNames(weekStart: string): string[] { + return weekStart === 'sunday' ? WEEKDAY_NAMES_SUNDAY : WEEKDAY_NAMES_MONDAY; +} +``` + +### Week-Mode SVG Layout (7 horizontal cells) +```typescript +// Larger cells since only 7 vs 365 +const cellWidth = 60; +const cellHeight = 40; +const cellGap = 4; +const labelWidth = 50; // space for "Mon", "Tue" labels +const svgWidth = labelWidth + 7 * (cellWidth + cellGap); +const svgHeight = cellHeight + 20; // room for value text below + +// Layout: label | rect | label | rect | ... +// Or: 7 rects in a row with labels below/beside +``` + +### Wiring Controls to State in heatmap.ts +```typescript +// In init(), after building wrapper: +const controlsContainer = document.getElementById('heatmap-controls'); +if (controlsContainer) { + const modeControl = createModeControl(state.mode, [ + { key: 'year', label: 'Year' }, + { key: 'week', label: 'Week' }, + ], (mode) => { + state.mode = mode as HeatmapMode; + doRender(); + }); + + const metricControl = createMetricControl(state.metric, (metric) => { + state.metric = metric as DisplayMetric; + doRender(); + }); + + controlsContainer.appendChild(modeControl); + controlsContainer.appendChild(metricControl); +} +``` + +## Validation Architecture + +### Test Framework +| Property | Value | +|----------|-------| +| Framework | Vitest 4.1.3 + jsdom | +| Config file | `vitest.config.ts` | +| Quick run command | `npm test` | +| Full suite command | `npm test` | + +### Phase Requirements to Test Map +| Req ID | Behavior | Test Type | Automated Command | File Exists? | +|--------|----------|-----------|-------------------|-------------| +| VIZ-01 | Mode switcher renders Year/Week buttons, click changes active state | unit | `npx vitest run assets/test/controls.test.ts` | Wave 0 | +| VIZ-02 | Week renderer aggregates by weekday, renders 7 cells with correct colors | unit | `npx vitest run assets/test/week.test.ts` | Wave 0 | +| VIZ-05 | Metric toggle switches state.metric, re-renders with different color values | unit | `npx vitest run assets/test/controls.test.ts` | Wave 0 | +| TEST-01 | All mode/renderer/toggle tests pass | suite | `npm test` | Wave 0 | + +### Sampling Rate +- **Per task commit:** `npm test` +- **Per wave merge:** `npm test` (single suite) +- **Phase gate:** Full suite green before `/gsd-verify-work` + +### Wave 0 Gaps +- [ ] `assets/test/week.test.ts` -- WeekModeRenderer rendering and aggregation tests +- [ ] `assets/test/controls.test.ts` -- mode switcher and metric toggle interaction tests + +## Security Domain + +No security-relevant ASVS categories apply to this phase. It is purely client-side UI rendering with no authentication, input handling from users, cryptography, or access control changes. Data comes from the existing authenticated API endpoint. + +## Assumptions Log + +| # | Claim | Section | Risk if Wrong | +|---|-------|---------|---------------| +| A1 | Tabler `nav-segmented` classes are available in Kimai's bundled Tabler version | Architecture Patterns | Controls would need custom CSS; verify in running Kimai instance | +| A2 | The `card-header` area in Kimai's card embed template has enough space for controls next to the title | Architecture Patterns | May need to adjust Twig layout or use a different placement | + +## Open Questions + +1. **Stats row in week mode** + - What we know: Year-mode shows streak, total hours, avg hours, busiest day + - What's unclear: Whether these make sense in week mode (streak is year-concept) + - Recommendation: Hide stats in week mode initially; can add week-specific stats later if wanted + +2. **Week-mode cell click behavior** + - What we know: Year-mode clicks navigate to timesheet for that date + - What's unclear: What clicking "Monday" in week-mode should do (filter timesheet by weekday? no-op?) + - Recommendation: No click handler for week cells initially -- the aggregation isn't tied to a single date + +## Sources + +### Primary (HIGH confidence) +- Codebase: `assets/src/renderers/types.ts`, `registry.ts`, `year.ts` -- ModeRenderer contract and reference implementation +- Codebase: `assets/src/state.ts`, `assets/src/types.ts` -- HeatmapState with mode/metric fields already defined +- Codebase: `assets/src/shared/color-scale.ts` -- buildColorScale already metric-aware +- Codebase: `assets/src/shared/date-utils.ts` -- weekday index calculation with start-of-week support + +### Secondary (MEDIUM confidence) +- [Tabler segmented control docs](https://docs.tabler.io/ui/components/segmented-control) -- `nav nav-segmented` markup pattern [CITED: docs.tabler.io/ui/components/segmented-control] + +### Tertiary (LOW confidence) +- None + +## Metadata + +**Confidence breakdown:** +- Standard stack: HIGH -- no new packages, all already installed and tested +- Architecture: HIGH -- extends well-established strategy pattern from Phase 6 +- Pitfalls: HIGH -- based on direct codebase analysis of existing patterns + +**Research date:** 2026-04-09 +**Valid until:** 2026-05-09 (stable -- no external dependency changes expected)