@cplace/test-mcp-server 1.0.0 → 1.1.0

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-cplaceReportGeneration-generateReportWidget/research.md

@@ -0,0 +1,295 @@
+# Generate Report Widget Research
+
+## Widget Information
+- **Widget ID**: `cf.cplace.cplaceReportGeneration.generateReportWidget`
+- **Widget Name**: Report Creation
+- **Repository**: `cplace-office-reports`
+- **Definition Class**: `cf.cplace.officeReports/src/main/java/cf/cplace/officeReports/script/GenerateReportWidgetDefinition.java`
+- **App**: cplace Report Generation
+
+## 1. Purpose & Description
+
+### Short Description
+This widget provides a button for generating and downloading Office reports (Word, PowerPoint, Excel) based on configurable templates and Low-Code scripts that pull data from cplace.
+
+### Detailed Description
+The Generate Report Widget is a user interface component that enables users to trigger the generation of Office documents (Word, PowerPoint, or Excel) directly from within cplace pages. When clicked, the widget button initiates a background job that executes a Low-Code script to populate a pre-defined Office template with data from cplace, then makes the generated report available for download or automatically attaches it to a specified page.
+
+The widget integrates with the broader cplace Office Reports functionality, which allows administrators to create Report Configuration pages that define:
+- The Office template to use (DOCX, PPTX, or XLSX)
+- A Low-Code script that specifies what data to include and how to populate template placeholders
+- File naming conventions
+- Attachment targets and behaviors
+
+**Key Characteristics:**
+- Class-level documentation (line 52-54 in GenerateReportWidgetDefinition.java): "Widget for the generation of reports. Can be hidden with custom logic by implementing CheckAccessInterceptors.AsPluginExtension on GenerateReportHandler."
+- Default button label: "Generate Report"
+- Default widget title: "Report {0}" (where {0} is the name of the linked Report Configuration)
+- Widget description: "Widget for generating and downloading Office reports"
+
+## 2. Use Cases
+
+### Primary Use Cases
+
+1. **On-Demand Report Generation from Page Context**
+   - Users need to generate a formatted Office document based on the current page's data
+   - Example: Generate a project status report (Word/PowerPoint) from a project page showing current milestones, risks, and team members
+   - The widget button appears on the page, and clicking it triggers report generation with the page as context
+
+2. **Batch Report Generation from Search Results**
+   - Users need to generate a report containing data from multiple pages matching specific criteria
+   - Example: Generate an Excel report listing all active projects in a portfolio with their KPIs
+   - The widget is configured with a search query, and the Low-Code script accesses all search results to populate the report
+
+3. **Report Generation from Table Selections**
+   - Users need to generate reports based on specific rows they've selected in a connected table widget
+   - Example: User selects 5 tasks from a table and generates a detailed task report for just those items
+   - The widget can be configured to work with table selections or the entire table result set
+
+4. **Custom Report with Additional User Input**
+   - Users need to provide additional data at report generation time that isn't stored in cplace
+   - Example: Generate a project report and prompt user to enter a comment or reporting period
+   - The widget can trigger a dialog to collect additional data before generating the report
+
+5. **Automated Document Attachment to Pages**
+   - System needs to automatically attach generated reports to specific pages for record-keeping
+   - Example: Monthly status report is generated and automatically attached to the project page's document attribute
+   - The widget can be configured to attach reports to the embedding page or a related page
+
+### Integration Scenarios
+
+- **Embedded in Attributes Group Widgets**: The widget can be embedded inside AttributesGroupWidgetDefinition or ConnectedAttributesGroupWidgetDefinition (lines 93-98 in GenerateReportWidgetDefinition.java)
+- **Page Actions**: Can be integrated as a page action for report generation workflows
+- **Dashboard Widgets**: Can be placed on dashboards for quick access to frequently generated reports
+
+## 3. Configuration Concepts
+
+### Core Configuration Attributes
+
+#### 3.1 Report Configuration (Required)
+- **Attribute**: `REPORT_CONFIGURATION` (SinglePageReferenceAttributeDef)
+- **Purpose**: Links to a Report Configuration page that defines the template, script, and report behavior
+- **Type Constraint**: Must reference a page of type `cf.cplace.officeReports.configuration`
+- **Description**: This is the master configuration that defines:
+  - Report template (Office document with placeholders)
+  - Low-Code script for data population
+  - Report type (Word/PowerPoint/Excel)
+  - Default attachment behaviors
+
+#### 3.2 Data Source
+- **Attribute**: `DATA_SOURCE` (AttributeGroupingAttributeDef)
+- **Purpose**: Defines where the data for the report comes from
+- **Options**:
+  - **Search Data Source**: Define a search query whose results will be available to the report script
+  - **Connected Table Data Source**: Pull data from a connected table widget on the same page
+  - **Selection Data Source**: Use manually selected pages
+
+**Search-related sub-attributes**:
+- `SEARCH`: JSON search configuration (optional)
+- `SORT_COLUMN`: Sorting criteria for search results
+- `SORT_ORDER`: Sort direction (ascending/descending)
+
+**Connected Table sub-attributes**:
+- `CONNECTED_TABLE`: Widget ID of the connected table
+- `CONNECTED_TABLE_SELECTION_ONLY`: Boolean flag - if true, only generate report for selected table rows
+
+#### 3.3 Presentation & Labeling
+- **Title** (`TITLE`): Optional custom title for the widget (defaults to "Report {ReportConfigName}")
+- **Button Label** (`BUTTON_LABEL`): Custom text for the generation button (defaults to "Generate Report")
+- **Show Frame** (`SHOW_FRAME`): Boolean to control whether widget displays in a frame (default: true)
+
+#### 3.4 File Naming
+- **File Name** (`FILENAME`): Custom name for the generated file (no spaces allowed)
+- **Fixed Filename** (`IS_FILENAME_FIXED`): When true, no timestamp/UUID is appended to filename
+  - Enables version history for documents
+  - Warning: Overwrites existing files with same name without confirmation
+
+#### 3.5 Output Format
+- **Generate Report as PDF** (`GENERATE_REPORT_AS_PDF`): Convert the Office document to PDF format (default: false)
+
+#### 3.6 Attachment Configuration
+- **Attach to Widget Embedding Page** (`ATTACH_TO_WIDGET_EMBEDDING_PAGE`): Automatically attach the generated report to the page where the widget is embedded (default: false)
+- **Attachment Page Attribute** (`ATTACHMENT_PAGE_ATTRIBUTE`): Specific document attribute on the embedding page to attach the report to
+- **Attachment Type** (`ATTACHMENT_TYPE`): Document type classification for the attached file
+
+#### 3.7 Additional Data Collection
+- **Additional Data Type** (`ADDITIONAL_DATA_TYPE`): Enables a dialog for collecting extra information at generation time
+- **Additional Data Attributes** (`ADDITIONAL_DATA_ATTRIBUTES`): Specific attributes to collect in the dialog
+- **Additional Data Dialog Title** (`ADDITIONAL_DATA_TYPE_DIALOG_TITLE`): Custom title for the data collection dialog
+
+### Configuration Modes
+
+The widget supports three primary data source modes:
+
+1. **Search Mode**: Report script receives search results as `pagesInfo` binding
+2. **Connected Table Mode**: Report script can access table data and selections
+3. **Direct Mode**: Report script works with the embedding page only (`embeddingPage` binding)
+
+### Migration Support
+The widget includes comprehensive migration support (lines 187-247 in GenerateReportWidgetDefinition.java):
+- Automatic attribute name migration when type definitions change
+- Search configuration migration
+- Sort column and additional data attribute migration
+- Data source grouping migration (e.g., "connectedTableWithOptionalSelection" → "ConnectedTableDataSourceAttributeGroup")
+
+## 4. Technical Architecture
+
+### Frontend Components
+
+**TypeScript Controller**: `GenerateReportWidgetCtrl.ts`
+- Manages button click handler
+- Listens for table refresh and selection events
+- Builds handler URL with connected table selection parameters
+- Integrates with AngularJS widget framework
+
+**Key Frontend Behaviors**:
+- Responds to `widgets.tableRefresh` events to update connected table selection context
+- Responds to `AbstractFlexiCtrl.EVENT_ROW_SELECTION_CHANGED` events for table row selections
+- Dynamically builds handler URL with selection parameters
+
+### Backend Components
+
+**Handler**: `GenerateReportHandler.java`
+- Validates access to report configuration
+- Handles additional data collection workflow (if configured)
+- Creates and starts `GenerateReportJob` in a separate thread
+- Returns job status as JSON
+
+**Job Execution**: `GenerateReportJob`
+- Background job for report generation
+- Executes Low-Code script with bindings:
+  - `report`: Report builder object
+  - `embeddingPage`: The page where widget is embedded
+  - `pagesInfo`: Search results (if search configured)
+  - `additionalData`: User-provided additional data (if configured)
+  - `configInfo`: Helper for accessing images/presentations
+  - `log`: Logging helper for user feedback
+- Populates template placeholders
+- Generates final Office document
+- Handles file attachment and download
+
+### Widget State
+
+The widget exposes state information via `GenerateReportWidgetState`:
+- `widgetId`: Unique widget identifier
+- `reportButtonName`: Displayed button label
+- `embeddedIn`: UID of the embedding page
+- `definingWidgetId`: ID of defining widget (if nested)
+- `connectedTableWidgetId`: Connected table reference
+- `hasAdditionalDataType`: Whether additional data collection is enabled
+
+### Access Control
+
+- Widget can be hidden dynamically by implementing `CheckAccessInterceptors.AsPluginExtension` on `GenerateReportHandler`
+- Report configuration accessibility is checked before generation
+- Widget automatically hides if handler URL is empty (e.g., due to access restrictions)
+
+## 5. Related Components
+
+### Sister Widgets in Office Reports Plugin
+
+1. **cf.cplace.officeReports.headlineForReports**
+   - Purpose: Display visual report type indicator on Report Configuration pages
+   - Relationship: Used in Report Configuration page layouts
+
+2. **cf.cplace.officeReports.scriptPlaceholders**
+   - Purpose: Display and manage script-defined placeholders
+   - Relationship: Configuration aid for Report Configuration pages
+
+3. **cf.cplace.officeReports.templatePlaceholders**
+   - Purpose: Display placeholders found in Office templates
+   - Relationship: Configuration aid for Report Configuration pages
+
+### Dependencies
+
+- **Report Configuration Type** (`cf.cplace.officeReports.configuration`): Master configuration entity
+- **Office Templates**: Word, PowerPoint, or Excel files with placeholder markers
+- **Low-Code Scripts**: JavaScript/TypeScript code for data extraction and population
+- **Document Attachment System**: cplace's document management for file storage
+
+### Report Types Supported
+
+From `ReportType` enum:
+- **Word** (DOCX): Text-heavy reports, letters, documentation
+- **PowerPoint** (PPTX): Presentations, visual reports, slide decks
+- **Excel** (XLSX): Data tables, spreadsheets, numerical reports
+
+## 6. Key Insights & Observations
+
+### Design Philosophy
+- **Separation of Concerns**: Widget configuration is separate from Report Configuration, allowing reuse of the same report template with different data sources
+- **Progressive Enhancement**: Basic usage requires minimal configuration; advanced features (additional data, attachments) are opt-in
+- **Async Job Pattern**: Report generation happens in background jobs to avoid blocking the UI for long-running operations
+
+### Flexibility Features
+- Can work with or without a search configuration
+- Supports both bulk generation and selective generation (via table selections)
+- Can generate reports for download or auto-attach them to pages
+- Supports runtime data collection via additional data dialogs
+
+### Common Patterns
+- Widget typically embedded on entity pages (project pages, portfolio pages, etc.)
+- Report Configuration is created once and referenced by multiple widget instances
+- Low-Code scripts use template placeholders to define substitution points
+
+### Limitations & Constraints
+- Can only be embedded in AttributesGroup or ConnectedAttributesGroup widgets
+- Filename must not contain spaces
+- Fixed filenames overwrite without confirmation (when enabled)
+- Report configuration must be accessible to the user
+
+### Version History Support
+The fixed filename feature (line 112-116 in CplaceReportGenerationWidgetTypes.java) enables document version history by preventing automatic timestamp/UUID suffixes. This allows cplace to track versions of repeatedly generated reports with the same name.
+
+## 7. Research Sources
+
+### Primary Sources Analyzed
+1. **GenerateReportWidgetDefinition.java** (`/Users/thomasbuechner/dev/repos/cplace-office-reports/cf.cplace.officeReports/src/main/java/cf/cplace/officeReports/script/GenerateReportWidgetDefinition.java`)
+   - Lines 1-279: Complete widget definition including configuration, substitution, and migration logic
+
+2. **CplaceReportGenerationWidgetTypes.java** (`/Users/thomasbuechner/dev/repos/cplace-office-reports/cf.cplace.officeReports/src/main/java/cf/cplace/officeReports/CplaceReportGenerationWidgetTypes.java`)
+   - Lines 36-236: GENERATE_REPORT_WIDGET configuration type definition with all attributes
+
+3. **GenerateReportHandler.java** (`/Users/thomasbuechner/dev/repos/cplace-office-reports/cf.cplace.officeReports/src/main/java/cf/cplace/officeReports/handler/GenerateReportHandler.java`)
+   - Lines 1-127: Handler logic for report generation requests
+
+4. **GenerateReportWidgetCtrl.ts** (`/Users/thomasbuechner/dev/repos/cplace-office-reports/cf.cplace.officeReports/assets/ts/controllers/GenerateReportWidgetCtrl.ts`)
+   - Lines 1-84: Frontend controller for button interactions and table integration
+
+5. **messages_en.properties** (`/Users/thomasbuechner/dev/repos/cplace-office-reports/cf.cplace.officeReports/build/resources/main/cf/cplace/officeReports/messages_en.properties`)
+   - Lines 1-100: English localization messages including widget names, descriptions, and help text
+
+6. **OfficeReportsAppTypes.java** (`/Users/thomasbuechner/dev/repos/cplace-office-reports/cf.cplace.officeReports/src/main/java/cf/cplace/officeReports/OfficeReportsAppTypes.java`)
+   - Lines 1-150: Report Configuration type definition and related types
+
+### Key Findings from Code Analysis
+
+- **Widget Kind**: `"cf.cplace.cplaceReportGeneration.generateReportWidget"` (line 58 in GenerateReportWidgetDefinition.java)
+- **App Context**: Part of `cplaceReportGenerationApp` within the Office Reports Plugin
+- **Embedding Constraints**: Explicitly restricts embedding to AttributesGroup variants (lines 93-98)
+- **Template System**: Uses `WidgetTemplateSubstitution` pattern for rendering
+- **Access Control**: Leverages `CheckAccessInterceptors` for dynamic visibility
+- **State Management**: Implements `WidgetState` interface for serializable state exposure
+
+## 8. Documentation Strategy Recommendations
+
+### Essential Topics for User Documentation
+1. **Getting Started Guide**: Step-by-step process for creating first report (Report Config → Template Upload → Script → Widget Placement)
+2. **Data Source Configuration**: Detailed explanation of search vs. table vs. selection modes
+3. **Low-Code Script Reference**: Available bindings, common patterns, template placeholder syntax
+4. **Template Guidelines**: How to create templates with placeholders for Word/PowerPoint/Excel
+5. **Attachment Workflows**: Configuring automatic attachment to pages
+
+### Advanced Topics
+1. **Additional Data Collection**: Creating dialogs for runtime user input
+2. **Table Integration**: Working with connected table selections
+3. **Access Control**: Implementing custom visibility logic
+4. **Version History**: Using fixed filenames for versioned documents
+5. **PDF Generation**: Converting Office documents to PDF
+
+### Common Pitfalls to Document
+- Filename restrictions (no spaces)
+- Fixed filename overwrite behavior
+- Access requirements for Report Configuration
+- Embedding limitations (only in attribute groups)
+- Report Configuration page setup requirements

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-ctts-main-employeeReportChart/research.md

@@ -0,0 +1,230 @@
+# Research: Employee Report Chart Widget
+
+**Widget ID:** `cf.cplace.ctts.main.employeeReportChart`
+**Repository:** `cplace-ctts`
+**Definition Class:** `cf.cplace.ctts.main/src/main/java/cf/cplace/ctts/main/script/EmployeeReportChartWidgetDefinition.java`
+**Widget Name:** "Employees chart view Time Tracking" (EN) / "Mitarbeiter Chart Report Zeiterfassung" (DE)
+
+---
+
+## Purpose
+
+The Employee Report Chart Widget is a time tracking visualization widget that displays an employee's booked working hours across different targets (projects/tasks) over a specified time period in a stacked column chart format using Highcharts.
+
+**1-2 Sentence Description:**
+This widget displays a visual chart report of an employee's time bookings, showing working hours distributed across different booking targets (projects/tasks) over a configurable date range. It provides an interactive Highcharts-based visualization with the ability to filter series, view totals, and optionally view reports on behalf of other employees through a representative mode.
+
+---
+
+## Use Cases
+
+### Primary Use Case: Employee Time Tracking Overview
+**Who:** Employees, managers, administrators
+**When:** When users need a visual overview of time spent across different projects/tasks
+**What:** Users can:
+- View time bookings aggregated by month across a selected date range
+- See hours distributed across different booking targets (projects, tasks, etc.)
+- Identify time allocation patterns and workload distribution
+- Track total working hours per month
+
+### Use Case: Representative/Substitute Reporting
+**Who:** Managers, administrators, team leads, substitutes
+**When:** When someone needs to view or manage time tracking on behalf of another employee
+**What:** Users with appropriate permissions can:
+- Select another employee to view their time tracking data
+- Generate reports for team members or substitutes
+- Return to their own time tracking view
+- This is useful for managers reviewing team time allocation or when covering for someone
+
+### Use Case: Time Period Analysis
+**Who:** All users
+**When:** When analyzing time allocation over specific periods
+**What:** Users can:
+- Select custom start and end months using date pickers
+- View historical time tracking data
+- Analyze trends across multiple months
+- Compare time distribution between different periods
+
+### Use Case: Target-Specific Analysis
+**Who:** All users
+**When:** When focusing on specific projects or tasks
+**What:** Users can:
+- Show/hide individual targets (projects/tasks) in the chart
+- Toggle all targets on/off at once
+- View the total hours for currently visible targets
+- Analyze time spent on specific projects by filtering out others
+
+---
+
+## Configuration Concepts
+
+### Access Control
+- **Allowed Groups Configuration**: The widget respects access control based on group membership
+  - Configured through `MainAppConfiguration.ALLOWED_GROUPS`
+  - Users not in allowed groups see a warning message: "$(AlertMessageNotAllowed)$"
+  - Access is checked via `PrincipalTool.isPersonInGroup()`
+
+### Date Range Selection
+- **From/To Date Pickers**: Month-level granularity date selection
+  - Users can select start month/year and end month/year
+  - Date range is stored per user, per space, and per report type
+  - Managed by `ReportDateRangeStore` for persistence across sessions
+  - Available years are calculated based on user's booking history
+
+### Representative Mode
+- **Representative Storage**: `RepresentativeTool.EMPLOYEE_REPORTS`
+  - Separate storage for employee reports representative mode
+  - Allows viewing another employee's data
+  - Button toggles between "Select Representative" and "Own Time Management"
+  - Shows current representative's name when active
+  - Managed through `RepresentativeEditHandler` and `RepresentativeClearHandler`
+
+### Chart Visualization
+- **Highcharts Configuration**: Interactive stacked column chart
+  - X-axis: Months in selected date range (e.g., "January 2024", "February 2024")
+  - Y-axis: Working hours
+  - Series: Each booking target (project/task) as a separate series
+  - Total Hours bar: Aggregated total for each month
+  - Tooltips: Show hours and percentage per target when hovering
+  - Legend: Clickable to show/hide individual targets
+
+### Data Display Features
+- **Show/Hide Series**: Toggle button to display or hide all targets at once
+- **Total Visible Hours**: Dynamic calculation showing sum of currently visible target hours
+  - Updates when toggling series visibility
+  - Displayed in HH:MM format
+- **Series Filtering**: Click legend items to show/hide specific targets
+  - Total recalculates based on visible series
+
+### Time Tracking Export Integration
+- **Optional Export Functionality**: If configured, shows time tracking export button
+  - Configured through `TimeTrackingExportAppConfiguration.EXPORT_TEMPLATES`
+  - Allows exporting time tracking data in configured formats
+  - Handled by `TimeTrackingExportEditHandler`
+
+---
+
+## Context and Relationships
+
+### Related Widgets
+This widget is part of a suite of time tracking reporting widgets:
+
+1. **EmployeeReportGridWidgetDefinition** (`cf.cplace.ctts.main.employeeReportGrid`)
+   - Grid/table view of the same employee time tracking data
+   - Provides detailed, editable tabular representation
+   - Complementary to the chart widget
+
+2. **ProjectmanagerReportChartWidgetDefinition** (`cf.cplace.ctts.main.projectmanagerReportChart`)
+   - Similar chart widget but from project manager perspective
+   - Shows time bookings across employees for specific projects
+   - Uses similar chart rendering but different data aggregation
+
+3. **ProjectmanagerReportGridWidgetDefinition** (`cf.cplace.ctts.main.projectmanagerReportGrid`)
+   - Grid view for project manager reports
+
+4. **MainWidgetDefinition** (`cf.cplace.ctts.main.main`)
+   - Main time tracking widget for day-to-day time entry
+   - Source of the data visualized in this report widget
+
+### Data Flow
+1. **Data Source**: Time bookings stored in database (table with columns: `udate`, `utarget`, `uuser`, `ubookedtime`)
+2. **Backend Handler**: `ReportHandler` processes AJAX requests
+   - Calls `ReportEmployeeManager.generateReportData()` for EMPLOYEE_VIEW report type
+   - Aggregates bookings by month and target
+   - Returns `EmployeeReportResponseData` as JSON
+3. **Frontend Controller**: `CttsEmployeeChartCtrl` manages chart display
+   - Requests data via `CttsReportDataService`
+   - Builds Highcharts visualization
+   - Handles user interactions (date changes, series toggling, representative selection)
+
+### Prerequisites
+- **CTTS Plugin**: Part of the cplace Time Tracking System (CTTS)
+- **User Permissions**: Users must be in configured allowed groups
+- **Time Bookings**: Requires existing time booking data to display
+- **Page Context**: Widget must be embedded in a page within a workspace/space
+
+### Technology Stack
+- **Backend**: Java (widget definition, data handlers)
+- **Frontend**: AngularJS (directive, controller)
+- **Charting**: Highcharts library
+- **Templating**: cplace template system with HTM templates
+- **Data Transport**: JSON via AJAX handlers
+
+---
+
+## Technical Implementation Notes
+
+### Key Classes and Files
+
+**Backend (Java):**
+- `EmployeeReportChartWidgetDefinition.java` - Widget definition class
+- `ReportWidgetSubstitution.java` - Template substitution base class
+- `ReportHandler.java` - HTTP handler for report data requests
+- `ReportEmployeeManager.java` - Business logic for employee report generation
+- `RepresentativeTool.java` - Manages representative/substitute mode
+
+**Frontend (TypeScript/JavaScript):**
+- `cfCplaceCttsEmployeeChart.ts` - AngularJS directive
+- `CttsEmployeeChartCtrl.ts` - Chart controller logic
+- `CttsReportDataService.ts` - Service for data fetching and state management
+
+**Templates:**
+- `employeeReportChartWidgetDefinition.htm` - Widget wrapper template
+- `angularTemplates.htm` - Contains Angular template at `/cf.cplace.ctts.main/cfCplaceCttsEmployeeChart`
+
+**Translations:**
+- `messages_en.properties` / `messages_de.properties` - Localized strings
+
+### Configuration Points
+
+1. **Access Control**: `MainAppConfiguration.ALLOWED_GROUPS`
+2. **Export Templates**: `TimeTrackingExportAppConfiguration.EXPORT_TEMPLATES` (optional)
+3. **Report Type**: Fixed to `ReportTypes.EMPLOYEE_VIEW` for this widget
+4. **Representative Storage**: Uses `RepresentativeTool.EMPLOYEE_REPORTS` storage instance
+
+### Key Features Summary
+
+| Feature | Description |
+|---------|-------------|
+| Chart Type | Stacked column chart (Highcharts) |
+| Date Range | Month-level selection, stored per user |
+| Series | One per booking target + total hours |
+| Interactivity | Toggle series, hover tooltips, legend filtering |
+| Representative Mode | View other employees' data with permissions |
+| Data Refresh | Automatic on date change or save events |
+| Localization | Full i18n support (EN/DE confirmed) |
+| Export | Optional integration with time tracking export |
+
+---
+
+## Recommendations for Documentation
+
+When creating end-user documentation, consider:
+
+1. **Visual Examples**: Include screenshots showing:
+   - The chart with multiple targets
+   - Date range selection interface
+   - Representative mode selection
+   - Toggle series functionality
+   - Tooltip display on hover
+
+2. **Workflow Documentation**: Document common workflows:
+   - How to select a date range
+   - How to view reports for team members (representative mode)
+   - How to focus on specific projects by hiding others
+   - How to interpret the total hours display
+
+3. **Permission Requirements**: Clearly explain:
+   - Which user groups can access the widget
+   - Who can use representative mode
+   - Any workspace/space-level permissions needed
+
+4. **Relationship to Other Widgets**: Explain:
+   - Difference between chart and grid views
+   - How this relates to the main time tracking widget
+   - When to use employee vs. project manager reports
+
+5. **Troubleshooting**: Address common issues:
+   - No data displayed (no bookings in selected period)
+   - Access denied messages (group membership)
+   - Representative mode not available (permissions)