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

Domain Pitfalls

Domain: Kimai heatmap plugin v1.1 -- visualization modes, TomSelect entity pickers, cascading filters, display toggle Researched: 2026-04-08 Confidence: HIGH (based on direct source analysis of existing plugin code and Kimai's KimaiFormSelect internals)

Critical Pitfalls

Mistakes that cause rewrites or major issues.

Pitfall 1: KimaiFormSelect Depends on Kimai's Plugin Container -- Cannot Use It Standalone

What goes wrong: SEED-001 suggests using Kimai's KimaiFormSelect.js with data-api-url, data-related-select, and data-empty-url attributes to get cascading for free. But KimaiFormSelect._activateApiSelects() calls this.getContainer().getPlugin('api') to make API requests (line 433-435). This requires the select to be inside a form that Kimai's JS plugin system initialized via activateForm(). The heatmap widget is a dashboard card, not a Symfony form.

Why it happens: Kimai's form system (KimaiFormSelect, KimaiFormPlugin) is tightly coupled to Kimai's JS plugin container and form lifecycle. The cascading logic in _activateApiSelects registers a delegated change event listener on document, but the handler calls this.getContainer().getPlugin('api') which requires the KimaiFormSelect instance to have been created by Kimai's app initialization. Our widget's IIFE bundle runs independently.

Consequences: Adding data-api-url and data-related-select attributes to <select> elements in the widget card will silently fail. No errors, just dead selects that do not cascade.

Prevention: Roll your own cascade with plain fetch() calls to Kimai's API routes or (better) custom controller endpoints. The widget is already fetch-driven. Three more fetch-based selects is consistent with the existing pattern. Use plain <select> elements styled with Tabler CSS. Add TomSelect only if the UX demands it.

Detection: Change the customer picker and observe whether the project picker updates. If it does not, you hit this.

Pitfall 2: Destroying and Recreating SVG Without Cleaning Up Tooltips

What goes wrong: The current renderHeatmap() starts with container.innerHTML = '' (line 184) but tooltips are appended to document.body (line 267). When switching visualization modes (year -> week -> day), each render creates a new tooltip. The existing cleanup at line 263 (document.querySelectorAll('.heatmap-tooltip').forEach(el => el.remove())) only runs inside renderHeatmap -- if new modes have their own render functions without this cleanup, tooltips accumulate.

Why it happens: The tooltip is necessarily outside the SVG container (fixed positioning to escape overflow clipping). Each render function must know to clean up the shared tooltip.

Consequences: Multiple .heatmap-tooltip divs on the page. Stale tooltip positioning. Memory leaks on repeated mode switches.

Prevention: Extract tooltip into a shared module that all visualization modes import. One tooltip div, created on first use, reused across mode switches. A single cleanup() function that any render path calls before rebuilding.

Detection: Switch modes 5+ times, inspect document.body children for orphaned .heatmap-tooltip elements.

Pitfall 3: Hour-Level Aggregation Query Performance

What goes wrong: Day-mode and combined day/hour views need time-of-day data. The current getDailyAggregation() groups by DATE(t.date) which benefits from Kimai's date index. An hour-level query (HOUR(t.begin) or EXTRACT(HOUR FROM t.begin)) applies a function to the column, defeating index usage. GROUP BY HOUR over a full year of data scans every row for that user.

Why it happens: MySQL/MariaDB cannot use an index when a function wraps the indexed column.

Consequences: Slow queries for users with thousands of entries. For personal use (likely <10K entries) it is noticeable latency (~200-500ms), not catastrophic. But it makes mode switching feel sluggish.

Prevention:

1. Limit hour-level queries to a narrow date range (one week or one month, not a full year). The UI for day-mode should show a specific date range anyway.
2. For the combined matrix, fetch raw timesheet entries for the selected range and aggregate in PHP rather than doing a complex GROUP BY.
3. Profile with EXPLAIN on the actual query against the dev database.

Detection: Mode switch to day-view takes noticeably longer than year-view load.

Moderate Pitfalls

Pitfall 4: Mode State Lost on Filter Change

What goes wrong: User switches to week-mode, then changes the project filter. The filter's fetch callback re-renders the visualization, but defaults back to year-mode because the mode selection is not part of the render state. The current doRender() function (line 339-344) always calls renderHeatmap() -- the year view.

Why it happens: The current architecture has no shared state object. Mode and filter are independent UI controls that both trigger re-renders, but neither knows about the other's state.

Consequences: User frustration. Every filter change resets the view mode. Feels broken.

Prevention: Introduce a state object BEFORE adding the first new mode:

interface WidgetState {
  mode: 'year' | 'week' | 'day' | 'combined';
  metric: 'hours' | 'count';
  filters: { customerId: number | null; projectId: number | null; activityId: number | null };
  data: HeatmapData | null;
}

All UI actions (mode switch, filter change, metric toggle) update state, then call a single render(state) dispatcher that picks the right visualization function.

Phase warning: This refactor MUST happen before adding any new visualization mode. Retrofitting state management after multiple modes exist is painful and error-prone.

Pitfall 5: Cascading API Response Format Assumptions

What goes wrong: Kimai's /api/projects?customer=X returns objects with parentTitle (customer name), id, name, and more. Activities can be "global" (no project parent). If you build your own cascade, you must handle this format correctly -- or your own simplified format if you use custom controller endpoints.

Why it happens: Kimai's API response shape is designed for KimaiFormSelect._updateSelect() which groups by parentTitle into optgroups. Rolling your own cascade means either parsing the same format or defining your own.

Prevention: Use custom controller endpoints (like the existing getUserProjects()) that return a simple [{id, name}] format. This avoids parsing Kimai's complex API response structure with optgroups and parentTitle. Handle edge cases:

• Customer with no projects -> empty project list
• Project with no activities -> empty activity list
• Global activities (no project association) -> include them when no project filter is set

Pitfall 6: Color Scale Domain Mismatch Across Modes

What goes wrong: Year-mode uses max(data.days, d => d.hours) as the scale ceiling (typically 8-12). Week-mode aggregates by day-of-week over a year (totals could be 200+). Day-mode shows hour slots (0-3 range). Reusing one color scale makes week-mode cells all dark and day-mode cells all light.

Why it happens: Each mode has fundamentally different value ranges. Easy to forget when the scale is set up once in shared code.

Prevention: Each mode computes its own color scale domain from its own data. Extract scale creation into a factory function that accepts a data array. Never share a global scale instance.

Pitfall 7: TomSelect Bundle Size Duplication

What goes wrong: Importing tom-select in heatmap.ts and bundling with esbuild ships a second copy (~50KB min) alongside Kimai's own TomSelect that Webpack Encore already loaded.

Why it happens: The plugin ships a standalone IIFE bundle independent of Kimai's module system. No shared module resolution between them.

Prevention: Do NOT bundle TomSelect. Options:

1. Best for personal use: Plain <select> elements with Tabler CSS. For <50 projects, native browser select works fine. No TomSelect needed.
2. If TomSelect is needed: Check if window.TomSelect exists at runtime (Kimai may expose it globally). Mark as external in esbuild config.
3. Fallback: Accept the duplication if autocomplete search is essential and Kimai does not expose a global.

Recommendation: Start with plain selects. Add TomSelect only if the list sizes demand it.

Pitfall 8: Kimai API Auth from Widget Context

What goes wrong: If the cascade pickers call Kimai's standard API routes (/api/customers, /api/projects), those routes may require API token authentication depending on Kimai configuration.

Why it happens: Dashboard widgets run in authenticated session context, so session cookies are sent. Kimai's API accepts session auth for browser requests. But some Kimai installations restrict API access to token-only.

Prevention: Add thin controller endpoints in the plugin itself (/heatmap/customers, /heatmap/projects, /heatmap/activities) that call Kimai's repositories directly, exactly like the existing getUserProjects() method. This avoids API auth concerns entirely and lets you shape the response format.

Detection: 401 responses when cascade pickers try to fetch data. Test by calling /api/customers from browser console on the dashboard page.

Minor Pitfalls

Pitfall 9: ResizeObserver vs Window Resize

What goes wrong: Current code uses window.addEventListener('resize'). Different modes have different natural widths (week-mode is much narrower than year-mode). Kimai's sidebar toggle changes container width without a window resize event.

Prevention: Use ResizeObserver on the container element instead. It fires on any container size change regardless of cause.

Pitfall 10: Entry Count Toggle Is Not Just a CSS Swap

What goes wrong: The hours/count toggle seems trivial -- just show d.hours vs d.count. But the color scale domain must change (hours: 0-12 vs count: 0-20+), tooltips must show different labels, and stats must recalculate.

Prevention: Treat the metric toggle as a state change that triggers a full re-render with the appropriate color scale, tooltip format, and stats calculation. The backend already returns both hours and count in DayEntry, so no API changes needed.

Pitfall 11: Week Start Preference Must Propagate to All Modes

What goes wrong: Year-mode respects data-week-start (monday/sunday). Week-mode aggregation (day-of-week buckets) must also respect this -- Monday-first vs Sunday-first changes which column is "day 0". Day-mode hour bucketing is unaffected but the combined day/hour matrix is.

Prevention: Include weekStart in the state object passed to all visualization modes. Test both configurations explicitly in Vitest.

Pitfall 12: Multiple Render Functions Diverging Over Time

What goes wrong: Starting with one renderHeatmap() and adding renderWeekMode(), renderDayMode(), renderCombinedMode() as separate functions. Over time, bug fixes (tooltip positioning, accessibility, theme colors) get applied to one function but not others.

Prevention: Extract shared concerns (tooltip management, color scale creation, cell click handling, stats rendering) into utility functions that all modes use. Each mode only implements its unique layout logic (grid generation, axis labels, cell positioning).

Phase-Specific Warnings

Phase Topic	Likely Pitfall	Mitigation
State management refactor	Pitfall 4 (mode state lost on filter)	Implement state object BEFORE adding any new mode
Entity pickers / cascade	Pitfall 1 (KimaiFormSelect needs form lifecycle)	Roll your own cascade with fetch + plain selects
Entity pickers / cascade	Pitfall 7 (TomSelect bundle duplication)	Start with plain selects, no TomSelect
Cascade API endpoints	Pitfall 5 (API response format), Pitfall 8 (auth)	Own controller endpoints returning simple format
Week/day modes	Pitfall 2 (tooltip cleanup), Pitfall 6 (color scale per mode)	Shared tooltip manager, per-mode scale factory
Day/hour visualization	Pitfall 3 (hour aggregation query perf)	Narrow date range for hour-level queries
Hours/count toggle	Pitfall 10 (not just CSS)	Full re-render with different scale and stats
All new modes	Pitfall 11 (week start), Pitfall 12 (code divergence)	Shared utilities, weekStart in state, test both configs

Sources

• dev/kimai/assets/js/forms/KimaiFormSelect.js lines 386-447: cascade logic via _activateApiSelects, getContainer().getPlugin('api') dependency at line 433
• dev/kimai/src/Form/Extension/SelectWithApiDataExtension.php: wires data-api-url, data-related-select, data-empty-url onto Symfony EntityType form views only
• dev/kimai/src/Form/Type/ProjectType.php lines 124-137: api_data option configures activity cascade route
• assets/src/heatmap.ts: tooltip on document.body (line 267), innerHTML cleanup (line 184), resize handler (lines 392-398), doRender always calls year-view (line 341)
• src/Service/HeatmapService.php: daily aggregation via DATE(t.date) GROUP BY (lines 24-31)
• assets/src/types.ts: DayEntry has both hours and count fields
• .claude/projects/.../memory/project_kimai_lessons.md: Phase 1-2 lessons on DI, widget system, testing