## Overview

Used to display events in a calendar view.

The Calendar Widget transforms cplace pages into interactive calendar events by mapping date attributes to visual calendar entries. It provides a unified calendar view for displaying multiple event types from one or more spaces, with support for event categorization through event classes, color-coding, and interactive filtering.

The widget operates on an Event Type Configuration model where cplace types are mapped to calendar events through configuration pages stored in each space. Each event type specifies start and end date attributes, default colors, and optional display name patterns. Event classes provide fine-grained categorization within event types based on attribute values (e.g., status, priority).

Four calendar view modes are supported: Month View (default), Week View, Day View, and List Year View. The widget requires the cplace Calendar App to be installed in target spaces where events are configured.

## Use Cases

- **Project Timeline Visualization**: Display project milestones, tasks, or phases to understand temporal distribution and identify scheduling conflicts across multiple projects.

- **Resource Scheduling**: Track resource availability, bookings, or absences across team members with event classes for different absence types (vacation, sick leave, training).

- **Multi-Type Event Aggregation**: Combine different event types (meetings, deadlines, releases) into a single calendar view for executive dashboards showing all important dates.

- **Compliance and Deadline Tracking**: Monitor regulatory deadlines, audit dates, or compliance milestones with categorization by priority or regulatory body.

- **Event Management**: Display and manage conferences, workshops, or company events with categorization by event type.

## Design Considerations

- **Event Selection**: Events can be defined via search queries (fine-grained control) or by selecting shown event types (simpler configuration). Search-based selection requires specifying the embedding space.

- **Interactive Features**: Optional year selector provides slider navigation when multiple years have events. Event class filtering allows users to show/hide events by category with color-coded buttons showing event counts.

- **Event Creation**: When enabled, displays action buttons to create events directly from the calendar, adapting to show a dropdown for multiple types or a single button for one type.

- **Multi-Space Support**: Can aggregate events from multiple spaces, with each space maintaining its own event type configurations.

- **Color Hierarchy**: Colors are resolved from event class first, then event type, with a default cplace blue fallback.

- **Performance**: Configuration is cached globally per space, and events load dynamically for the visible date range only.

## Related Patterns/Alternatives

- **Table Widget**: For tabular display of the same time-based data when calendar visualization is not needed.
- **Timeline/Gantt Widgets**: For duration-focused visualization with dependency relationships between items.
- **Board Widget**: For status-focused views of items that happen to have dates.
- **Connected Table Filter**: Can be combined with the calendar for additional filtering capabilities.