## Overview

The CTTS (Collaborative Time Tracking System) Time Booking Widget is the primary interface for employees to enter, track, and manage their work hours across projects and activities. This widget provides an interactive grid-based interface where users can book time to various targets (projects, tasks, activities) on a daily, weekly, or monthly basis. It serves as the central data entry point for the entire CTTS time tracking ecosystem.

## Key Features

### Interactive Time Entry
Users can enter time bookings in multiple formats:
- **Hour and minute format** (e.g., 8:30)
- **Decimal format** (e.g., 8.5 or 8,5 depending on locale)
- **Configurable time increments** (1 second, 1 minute, 15 minutes, 30 minutes, 1 hour)

### Multiple View Modes
The widget supports different time period views:
- **Daily View**: Granular day-by-day time entry
- **Weekly View**: Week-at-a-glance with daily columns
- **Monthly View**: Complete month overview with optional single-value entry per month

### Calendar Integration
- Visual calendar picker for easy date navigation
- Week selection support (configurable clickable weeks)
- "Today" button for quick navigation to current period
- Highlights holidays and non-working days

### Target Management
- Add multiple booking targets (projects, activities, tasks)
- Favorites system for frequently used targets
- Subsequent booking support (booking to past periods with restrictions)
- Workspace filtering (optionally restrict targets to current workspace)

### Data Validation and Controls
- **Maximum booking time per day** validation
- **Overbooking limits** with warnings
- **Negative bookings** support (if configured)
- **Month locking/release** functionality for approval workflows
- **Difference display** showing target vs. actual hours
- **Real-time calculation** of daily and period totals

### Representative Mode
Users with appropriate permissions can book time on behalf of other employees (substitute/delegation functionality).

## Use Cases

### Daily Time Tracking
An employee starts their workday and uses the widget to:
1. Navigate to the current week
2. Select projects from their favorites or add new targets
3. Enter hours worked per project per day
4. See real-time totals and ensure they don't exceed daily limits
5. Save their time bookings at the end of the day or week

### Project Time Allocation
A consultant working on multiple client projects:
1. Adds all active client projects to their booking grid
2. Distributes their 8-hour workday across 3 different projects
3. Uses the percentage distribution view to see time allocation patterns
4. Reviews weekly totals to ensure project budgets are tracked correctly

### Month-End Approval Workflow
At the end of the month:
1. Employee reviews all time bookings for the month
2. Clicks "Release Month" to submit for approval
3. Manager reviews released bookings in project manager report widgets
4. If corrections needed, manager revokes release status
5. Employee makes corrections and re-releases for approval

### Substitute Time Entry
An administrative assistant books time on behalf of team members:
1. Selects a team member via representative mode
2. Enters time bookings for that person
3. Bookings are attributed to the selected employee
4. Assistant can switch between multiple employees as needed

### Subsequent Booking (Retroactive Entry)
An employee realizes they forgot to book time from two weeks ago:
1. Uses "Add Subsequent Booking" feature
2. System checks if retroactive booking is within allowed time frame (e.g., last 2 months)
3. Employee adds the missed booking target and enters historical time
4. System validates against month locking rules

## Design Considerations

### When to Use This Widget
- Primary time entry interface for employee time tracking
- Need for flexible daily, weekly, or monthly time booking views
- Requirements for time validation and approval workflows
- Multi-project time allocation tracking
- Integration with project management and billing systems

### Configuration Decisions

**View Mode Selection**
- **Weekly View** (default): Best balance between overview and detail for most users
- **Monthly View**: Suitable for high-level time tracking or simplified booking scenarios
- **Daily View**: When granular control is needed, though less commonly used

**Time Format**
- **Punctual (0:00)**: More intuitive for users thinking in hours and minutes
- **Decimal (0.00 or 0,00)**: Better for billing calculations and integrations

**Validation Rules**
Consider organizational policies:
- Maximum daily hours (prevent overbooking)
- Overbook tolerance (allow slight overages)
- Negative bookings (corrections, time off)
- Holiday booking restrictions
- Month locking for approval cycles

### Integration Patterns

The CTTS Main Widget is the data source for:
- **Employee Report Widgets** (`cf.cplace.ctts.main.employeeReportGrid`, `cf.cplace.ctts.main.employeeReportChart`): Display time bookings from employee perspective
- **Project Manager Report Widgets** (`cf.cplace.ctts.main.projectmanagerReportGrid`, `cf.cplace.ctts.main.projectmanagerReportChart`): Aggregate time bookings by project
- **Time Tracking Export**: Generate reports for billing, payroll, or compliance
- **Project Capacity Planning**: Analyze resource allocation and availability

## Common Pitfalls

### Incorrect Permission Configuration
The widget checks group membership via app configuration. Users without proper group assignment see "You cannot make time bookings because you are not a member of a group with editing rights." Ensure all users who need to book time are in the configured allowed groups.

### Month Locking Confusion
Released/locked months cannot be edited without revoking the release. This is by design for approval workflows, but can confuse users who try to make corrections to past months.

### Workspace Filtering Unexpected Results
When "Show data from this workspace only" is enabled, users may not see expected targets if those pages are in different workspaces. This is intentional for multi-tenant scenarios but can be surprising.

### Time Format Mismatches
Users might enter "8:30" when decimal format is configured, or vice versa. The widget validates format, but clear user communication about the expected format prevents frustration.

### Subsequent Booking Time Limits
Users attempting to book time beyond the configured subsequent booking limit (e.g., trying to book 3 months ago when limit is 2 months) will be blocked. The time limit must be configured appropriately for organizational needs.

## Related Widgets

### cf.cplace.ctts.main.employeeReportGrid
Displays the same time booking data entered via the main widget, but from a reporting perspective focused on individual employee views. Use together to provide both data entry and analysis capabilities.

### cf.cplace.ctts.main.projectmanagerReportGrid
Shows aggregated time bookings by project for project manager oversight. The main widget creates the data that this reporting widget displays in project-centric views.

### cf.cplace.ctts.main.employeeReportChart
Chart-based visualization alternative to the employee report grid, showing the same employee-focused time tracking data in graphical format.

### cf.cplace.ctts.main.projectmanagerReportChart
Chart-based visualization alternative to the project manager report grid, providing graphical views of project time allocation.

## Alternative Patterns

### Simple Form Widget
For basic time entry without advanced features like validation, approval workflows, or multi-project allocation, consider using `cf.cplace.simpleForm.widget` with custom time tracking attributes.

### Table Widget with Inline Editing
For read-heavy time tracking scenarios where most interaction is viewing rather than editing, an `embeddedSearchAsTable` with inline editing might be simpler than the full CTTS solution.

### External Time Tracking Integration
Organizations with existing time tracking systems (Jira, Toggl, Harvest) may prefer to integrate those systems via API rather than implementing CTTS for time entry.