179 lines
8.7 KiB
Markdown
179 lines
8.7 KiB
Markdown
# Technology Stack: v1.1 Additions
|
|
|
|
**Project:** Kimai Heatmap Plugin v1.1
|
|
**Researched:** 2026-04-08
|
|
**Scope:** NEW stack additions only. Existing validated stack (PHP 8.2, Symfony 6.4, d3 v7, TypeScript, esbuild, Vitest, PHPUnit) is not re-evaluated.
|
|
|
|
## New Dependencies
|
|
|
|
### TomSelect (Entity Pickers)
|
|
|
|
| Technology | Version | Purpose | Why | Confidence |
|
|
|------------|---------|---------|-----|------------|
|
|
| tom-select | ^2.4.3 | Customer/project/activity cascading pickers | Kimai uses TomSelect 2.4.3 for all its entity pickers. Matching the version ensures visual consistency with Kimai's existing selects. ~16KB gzipped complete, ~12KB base. | HIGH |
|
|
| @types/tom-select | latest | TypeScript definitions | Type safety for TomSelect API calls (constructor options, instance methods like `clear()`, `sync()`, `destroy()`). | HIGH |
|
|
|
|
**Why bundle TomSelect ourselves instead of reusing Kimai's instance:**
|
|
|
|
Kimai bundles TomSelect inside its Webpack Encore build (`app` entry point). It is NOT exposed as a `window` global. Our plugin ships as a standalone IIFE via esbuild, loaded separately from Kimai's bundle. There is no way to import from Kimai's Webpack chunks at runtime.
|
|
|
|
Verified by examining: `dev/kimai/webpack.config.js` (no `externals` or global exposure), `dev/kimai/assets/js/forms/KimaiFormSelect.js` (imports TomSelect as ESM module), and `dev/kimai/assets/js/KimaiLoader.js` (all form plugins are internal to the Kimai container system).
|
|
|
|
**CSS consideration:** Kimai already loads TomSelect's CSS via its Sass pipeline. Our TomSelect instances will inherit Kimai's existing `.ts-wrapper`, `.ts-control`, `.ts-dropdown` styles automatically. We do NOT need to bundle TomSelect CSS -- only the JS.
|
|
|
|
**Import strategy:** Use `tom-select/dist/js/tom-select.complete` (includes change_listener plugin needed for cascading) or cherry-pick `tom-select/src/tom-select` + specific plugins. The complete bundle is fine at 16KB gzipped given we already bundle d3 modules.
|
|
|
|
### No New d3 Modules Needed
|
|
|
|
The existing d3 dependencies are sufficient for all four visualization modes:
|
|
|
|
| Mode | Layout Approach | d3 Modules Used |
|
|
|------|----------------|-----------------|
|
|
| Year (existing) | Week columns x 7 day rows | d3-selection, d3-scale, d3-time, d3-time-format, d3-array |
|
|
| Week | 7 columns (Mon-Sun), single row of aggregated values | d3-selection, d3-scale, d3-array |
|
|
| Day (time-of-day) | 24 columns (hours), 7 rows (days-of-week) | d3-selection, d3-scale, d3-array |
|
|
| Combined (day/hour) | Date columns x 24 hour rows, or 7 day-of-week columns x 24 hour rows | d3-selection, d3-scale, d3-array, d3-time |
|
|
|
|
All modes render SVG rect grids -- the same pattern as the year view. The difference is in data aggregation (backend) and grid layout math (frontend), not in d3 capabilities.
|
|
|
|
`d3-shape` (listed in v1.0 STACK.md) was never added to package.json and is not needed. Rectangles are drawn with `rect` elements via d3-selection, not d3-shape.
|
|
|
|
## Backend Additions
|
|
|
|
### New Query Aggregations
|
|
|
|
The existing `HeatmapService::getDailyAggregation()` groups by `DATE(t.date)`. New modes need:
|
|
|
|
| Mode | SQL Aggregation | New Method |
|
|
|------|----------------|------------|
|
|
| Week (day-of-week) | `GROUP BY DAYOFWEEK(t.date)` | `getWeekdayAggregation()` |
|
|
| Day (time-of-day) | `GROUP BY HOUR(t.begin)` | `getHourlyAggregation()` |
|
|
| Combined | `GROUP BY DAYOFWEEK(t.date), HOUR(t.begin)` | `getDayHourAggregation()` |
|
|
|
|
These are Doctrine DQL queries using the same `TimesheetRepository` and `QueryBuilder` pattern as the existing method. No new PHP packages needed.
|
|
|
|
**Note:** Kimai stores `t.begin` (start time) and `t.end` (end time) on timesheet entries. For hourly breakdown, use `HOUR(t.begin)` to assign each entry to its starting hour. Multi-hour entries will be attributed to their start hour for simplicity; splitting across hours would require duration-proportional allocation (complex, defer to future).
|
|
|
|
### New Controller Endpoints
|
|
|
|
The existing `HeatmapController::data()` endpoint needs:
|
|
- `mode` query param (`year|week|day|combined`, default `year`)
|
|
- `customer` query param (for cascading filter support)
|
|
- `activity` query param (for activity filtering)
|
|
|
|
These are additions to the existing controller, not new bundles or packages.
|
|
|
|
### Entity Cascade Endpoints
|
|
|
|
**Decision: Use our own endpoints, NOT Kimai's API routes.**
|
|
|
|
Kimai's API routes (`get_customers`, `get_projects`, `get_activities`) are guarded by `#[IsGranted('API')]`, which requires the user to have the API permission. Dashboard widget users may not have API access. Additionally, Kimai's cascading logic lives in `KimaiFormSelect.js` which depends on `KimaiContainer.getPlugin('api')` -- the entire Kimai plugin system that our standalone widget cannot access.
|
|
|
|
Instead, add lightweight endpoints to our own `HeatmapController`:
|
|
- `GET /heatmap/customers` -- customers the user has timesheet entries for
|
|
- `GET /heatmap/projects?customer={id}` -- projects filtered by customer
|
|
- `GET /heatmap/activities?project={id}` -- activities filtered by project
|
|
|
|
These use `IS_AUTHENTICATED_REMEMBERED` + `view_own_timesheet` (same as our existing data endpoint) and query only entities the user has actually tracked time against. This is better UX anyway -- no empty customers/projects cluttering the pickers.
|
|
|
|
## UI Additions
|
|
|
|
### Mode Switcher
|
|
|
|
Use Tabler's `btn-group` (segmented control) for mode switching. Tabler is Kimai's UI framework and is already loaded. No additional CSS or JS framework needed.
|
|
|
|
```html
|
|
<div class="btn-group" role="group">
|
|
<button class="btn btn-sm btn-outline-primary active">Year</button>
|
|
<button class="btn btn-sm btn-outline-primary">Week</button>
|
|
<button class="btn btn-sm btn-outline-primary">Day</button>
|
|
<button class="btn btn-sm btn-outline-primary">Combined</button>
|
|
</div>
|
|
```
|
|
|
|
### Display Toggle (Hours vs Entry Count)
|
|
|
|
Same pattern -- `btn-group` or a simple toggle. The data is already in `DayEntry` (`hours` and `count` fields). This is purely a frontend change to switch which field drives the color scale.
|
|
|
|
## What NOT to Add
|
|
|
|
| Temptation | Why Not |
|
|
|------------|---------|
|
|
| `d3-axis` | The new modes don't need formal axes. Simple text labels (like the existing month/day labels) are sufficient and lighter. |
|
|
| `d3-shape` | We draw rectangles with `<rect>`, not path generators. |
|
|
| `d3-transition` | Animations between mode switches would be nice but add complexity. Defer to polish. |
|
|
| `chart.js` or `cal-heatmap` | Same rationale as v1.0 -- raw d3 gives us full control over Kimai theme integration. |
|
|
| TomSelect CSS bundle | Already loaded by Kimai's Sass pipeline. Bundling it would cause style conflicts. |
|
|
| Kimai's `KimaiFormSelect.js` | Depends on `KimaiContainer` plugin system. Our widget is standalone IIFE. |
|
|
| `luxon` or `date-fns` | d3-time and d3-time-format handle all our date math. No need for another date library. |
|
|
|
|
## Updated Type Definitions
|
|
|
|
New types needed in `types.ts`:
|
|
|
|
```typescript
|
|
// Visualization modes
|
|
type HeatmapMode = 'year' | 'week' | 'day' | 'combined';
|
|
|
|
// Display metric toggle
|
|
type DisplayMetric = 'hours' | 'count';
|
|
|
|
// Hourly data for day/combined modes
|
|
interface HourEntry {
|
|
hour: number; // 0-23
|
|
dayOfWeek: number; // 0-6 (Monday=0)
|
|
hours: number;
|
|
count: number;
|
|
}
|
|
|
|
// Weekday aggregation for week mode
|
|
interface WeekdayEntry {
|
|
dayOfWeek: number; // 0-6
|
|
hours: number;
|
|
count: number;
|
|
}
|
|
|
|
// Entity picker options
|
|
interface CustomerOption {
|
|
id: number;
|
|
name: string;
|
|
}
|
|
|
|
interface ActivityOption {
|
|
id: number;
|
|
name: string;
|
|
}
|
|
```
|
|
|
|
## Installation Commands
|
|
|
|
```bash
|
|
# New runtime dependency
|
|
npm install tom-select@^2.4.3
|
|
|
|
# New dev dependency (check if types ship with tom-select itself first)
|
|
npm install -D @types/tom-select
|
|
```
|
|
|
|
No new PHP/Composer dependencies required.
|
|
|
|
## esbuild Consideration
|
|
|
|
TomSelect's package includes CSS files. When importing from `tom-select`, esbuild may try to bundle CSS. Since Kimai already loads TomSelect CSS, import only the JS entry point:
|
|
|
|
```typescript
|
|
import TomSelect from 'tom-select/dist/js/tom-select.complete';
|
|
```
|
|
|
|
This avoids CSS duplication and style conflicts.
|
|
|
|
## Sources
|
|
|
|
- Kimai TomSelect integration: `dev/kimai/assets/js/forms/KimaiFormSelect.js` (local source, verified)
|
|
- Kimai webpack config: `dev/kimai/webpack.config.js` (local source, confirmed no TomSelect global exposure)
|
|
- Kimai API permissions: `dev/kimai/src/API/ProjectController.php` (local source, `#[IsGranted('API')]`)
|
|
- Kimai API cascading pattern: `dev/kimai/src/Form/Extension/SelectWithApiDataExtension.php` (local source)
|
|
- Kimai package.json: `dev/kimai/package.json` (local source, `tom-select: ^2.4.3`)
|
|
- [tom-select on npm](https://www.npmjs.com/package/tom-select) -- v2.5.2 latest, ~16KB gzipped
|
|
- [tom-select v2.5.2 on Bundlephobia](https://bundlephobia.com/package/tom-select) -- bundle size analysis
|
|
- [TomSelect documentation](https://tom-select.js.org/)
|