## Overview

The Employee Chart View widget provides an interactive Highcharts visualization of time tracking data from an employee's perspective. It displays booked time hours aggregated by booking targets over a selected date range, allowing employees to analyze their time distribution across different work activities. The widget is part of the CTTS (cplace Time Tracking System) and presents time bookings broken down by target (projects, tasks, or other booking categories) across months.

## Use Cases

### Employee Time Overview
Employees can view an aggregated overview of their own time bookings, visualize how they allocate time across different targets (projects, tasks, activities), and identify time distribution patterns over selected date ranges.

### Time Booking Analysis
Analyze time booking trends over months or years, compare time spent on different targets side-by-side, calculate total hours booked across all visible targets, and toggle visibility of individual target series to focus on specific areas of work.

### Representative View
Managers or authorized users can view time tracking data on behalf of other employees through "representative mode". This is particularly useful for supervisors reviewing team member time allocations or HR personnel accessing employee records.

### Date Range Filtering
Users can select custom date ranges (start/end year and month). The widget remembers the last selected date range per user and space, and provides a list of years where time bookings exist for quick selection.

## Design Considerations

### When to Use This Widget

Use this widget when you need to:
- Understand how an employee allocates time across different work targets
- Identify trends, patterns, or anomalies in time distribution
- Get a visual overview of time bookings without manually aggregating tabular data
- Monitor individual time allocation for performance reviews or capacity planning
- Analyze personal time tracking patterns for time management improvement

### Chart vs. Grid

The chart view prioritizes visual analysis and trend spotting over detailed data entry, making it ideal for overview and monitoring scenarios. For detailed tabular views with more granular data and customization options, use the Grid variant instead (`cf.cplace.ctts.main.employeeReportGrid`).

### Permission Requirements

Access to this widget is controlled at the app configuration level through group membership (defined in `ALLOWED_GROUPS`). Only authorized users can access this view. If a user is not in an allowed group, they will see a "View not allowed" message. Employees typically have access to view their own time tracking data.

### Runtime Configuration

Unlike the Grid variant, the Chart widget has no custom configuration options exposed during widget setup. Users configure the widget behavior at runtime through:
- Date range selection (start/end year and month)
- Representative selection (viewing reports for other employees if authorized)
- Series visibility toggles (show/hide individual target series)
- Standard Highcharts interactions (zoom, hover for details with percentages)

### Chart Features

The widget provides rich interactive features:
- **Stacked Bar Chart**: Shows time bookings as stacked bars with each target as a separate series
- **Total Hours Bar**: Automatically calculates and displays total hours per time period
- **Interactive Legend**: Click legend items to show/hide specific targets
- **Hover Tooltips**: Display detailed information including hours and percentages when hovering over chart elements
- **Toggle All Button**: Quickly show or hide all target series at once
- **Visible Target Sum**: Displays the sum of all currently visible targets (excluding the total bar)

## Common Pitfalls

- **Missing Data**: The widget requires time booking data to display meaningful information. The `availableYears` list is generated from existing bookings for the current user.
- **Permission Issues**: Users must be members of groups defined in `ALLOWED_GROUPS` app configuration to access the widget.
- **Configuration Expectations**: Unlike the Grid variant, this widget has no custom configuration options for widget setup. All configuration happens at runtime.
- **Representative Mode Context**: The widget uses `RepresentativeMode.Employee_Reports` for storing representative selections, separate from project manager report contexts.

## Related Patterns

### Time Tracking Report Family

This widget is part of a family of four time tracking report widgets:

- **Employee Report Chart** (`cf.cplace.ctts.main.employeeReportChart`) - This widget; shows time bookings from an employee's perspective using `EMPLOYEE_VIEW` report type
- **Employee Report Grid** (`cf.cplace.ctts.main.employeeReportGrid`) - Table-based view of employee time tracking data with more detailed, tabular information
- **Project Leader Chart** (`cf.cplace.ctts.main.projectmanagerReportChart`) - Shows time bookings from a project manager's perspective using `PROJECT_VIEW` report type
- **Project Leader Grid** (`cf.cplace.ctts.main.projectmanagerReportGrid`) - Table-based view for project managers with configuration options

### Visualization Choice

- **Chart Widgets**: Provide visual, graphical representations using Highcharts for trend analysis and quick overviews
- **Grid Widgets**: Provide detailed tabular views with more granular data and customization options

All four report widgets share a common base architecture (`ReportWidgetSubstitution`) but differ in report type (`EMPLOYEE_VIEW` vs `PROJECT_VIEW`), representative storage context, and configuration options.