## Overview

The Project Leader Chart View widget provides an interactive Highcharts visualization of time tracking data from a project manager's perspective. It displays booked time hours aggregated by projects over a selected date range, allowing project managers to analyze time distribution across the projects they manage. The widget is part of the CTTS (cplace Time Tracking System) and presents time bookings broken down by project across months.

## Use Cases

### Project Manager Time Overview
Project managers can view an aggregated overview of time bookings across all their projects, visualize how team members allocate time across different projects, 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 projects side-by-side, calculate total hours booked across all visible projects, and toggle visibility of individual project series to focus on specific projects.

### Representative View
Project managers can view time tracking data on behalf of other users through "representative mode" where authorized users can access reports for others. This is particularly useful for managers overseeing multiple team members' time allocations.

### 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 time is distributed across projects from a management perspective
- Identify trends, imbalances, or anomalies in time allocation
- Get a visual overview of time bookings without manually aggregating tabular data
- Monitor team time allocation across multiple projects
- Analyze time tracking patterns for strategic planning

### 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.projectmanagerReportGrid`).

### Permission Requirements

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

### 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 users if authorized)
- Series visibility toggles (show/hide individual project series)
- Standard Highcharts interactions (zoom, hover for details)

## 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.

## 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`) - 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
- **Project Leader Chart** (`cf.cplace.ctts.main.projectmanagerReportChart`) - This widget; 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 with more detailed, tabular information and configuration for displaying additional person attributes

### 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, representative storage context, and configuration options.