syncfusion-blazor-calendars

What this skill does

# Implementing Syncfusion Blazor Calendars

## Calendar

The Calendar component is a lightweight, feature-rich date selection component that provides flexible date picking, multiple views (month/year/decade), date range constraints, localization, and accessibility compliance. Use this skill whenever you need to implement date selection, calendar display, or date-based UI interactions.

### When to Use This Skill

**Use this skill when:**
- Building date pickers, calendar widgets, or date selection interfaces
- Adding date range constraints (Min/Max dates)
- Implementing multi-month or drill-down date selection (Year/Decade views)
- Handling date value changes and events
- Styling calendars or customizing appearance
- Supporting international date formats and RTL layouts
- Creating accessible calendar interfaces with keyboard navigation

**Related components:**
- **DatePicker** (date input with calendar dropdown)
- **DateRangePicker** (date range selection)
- **DateTimePicker** (date + time selection)
- **Scheduler** (complex date-based scheduling)

### Component Overview

| Feature | Details |
|---------|---------|
| **Views** | Month (default), Year, Decade - hierarchical drill-down navigation |
| **Selection** | Single date, date ranges (Min/Max), multi-select |
| **Data Types** | `DateTime`, `DateTime?`, `DateOnly` (.NET 6+) |
| **Binding** | One-way, two-way (`@bind-Value`), dynamic |
| **Events** | `ValueChange`, `OnRenderDayCell`, `Created`, `Destroyed`, `Navigated` |
| **Localization** | Multi-language, RTL support, locale customization |
| **Accessibility** | WCAG 2.2 AA, keyboard navigation, screen reader support |
| **Styling** | CSS customization, theme integration, special date highlights |

### Documentation & Navigation Guide

#### Getting Started
📄 **Read:** [references/getting-started.md](references/calendar-getting-started.md)
- Installation & NuGet packages
- Web & Server app setup
- Blazor namespaces & service registration
- Basic calendar implementation
- Min/Max date constraints

#### Calendar Views & Navigation
📄 **Read:** [references/calendar-views.md](references/calendar-calendar-views.md)
- Month, Year, Decade views
- Start & Depth properties
- View restrictions & drill-down navigation
- Restricting date selection depth

#### Date Selection & Data Binding
📄 **Read:** [references/date-selection-binding.md](references/calendar-date-selection-binding.md)
- Value property & date binding
- One-way vs two-way binding (`@bind-Value`)
- DateOnly support (.NET 6+)
- Dynamic value changes
- Date range constraints

#### Events & Interactions
📄 **Read:** [references/events-handling.md](references/calendar-events-handling.md)
- ValueChange event (date selection)
- Selected/DeSelected events (multi-selection)
- OnRenderDayCell event (custom rendering)
- Created & Destroyed lifecycle events
- Navigated event (view changes)
- Event args & reactive patterns
- Using CalendarEvents child component

#### Styling & Customization
📄 **Read:** [references/styling-appearance.md](references/calendar-styling-appearance.md)
- CSS customization patterns
- Background colors, borders, hover states
- Day cell styling
- Header & title customization
- Today button & selected date styling
- Special date highlighting

#### Localization & Globalization
📄 **Read:** [references/localization-globalization.md](references//calendar-localization-globalization.md)
- Locale support & language files
- Right-to-Left (RTL) layouts
- Islamic calendar & custom calendars
- Week customization (first day of week)
- Date format localization

#### Accessibility & Keyboard Navigation
📄 **Read:** [references/accessibility.md](references/calendar-accessibility.md)
- WCAG 2.2 AA compliance
- Screen reader support (WAI-ARIA)
- Keyboard navigation shortcuts
- Focus management & ARIA attributes

#### Advanced Features & Patterns
📄 **Read:** [references/advanced-features.md](references/calendar-advanced-features.md)
- Show/hide other month dates
- Custom cell rendering patterns
- Multiple date selection
- Week number display
- Performance optimization
- Common integration patterns

### Quick Start Example

```razor
@using Syncfusion.Blazor.Calendars

<!-- Basic Calendar -->
<SfCalendar TValue="DateTime?" Value="@SelectedDate"></SfCalendar>

<!-- Calendar with Date Range -->
<SfCalendar TValue="DateTime?" 
    Value="@SelectedDate" 
    Min="@MinDate" 
    Max="@MaxDate">
</SfCalendar>

<!-- Calendar with Value Change Event -->
<SfCalendar TValue="DateTime?" @bind-Value="@SelectedDate">
    <CalendarEvents TValue="DateTime?" ValueChange="@OnDateChanged"></CalendarEvents>
</SfCalendar>

<!-- Multi-Selection Calendar -->
<SfCalendar TValue="DateTime?" 
    IsMultiSelection="true"
    @bind-Values="@SelectedDates">
    <CalendarEvents TValue="DateTime?" 
        Selected="@OnDateSelected"
        DeSelected="@OnDateDeselected">
    </CalendarEvents>
</SfCalendar>

@code {
    public DateTime? SelectedDate { get; set; } = DateTime.Now;
    public DateTime[] SelectedDates { get; set; } = new DateTime[] { };

    private void OnDateChanged(ChangedEventArgs<DateTime?> args)
    {
        SelectedDate = args.Value;
        // Handle date change
    }
    
    private void OnDateSelected(SelectedEventArgs<DateTime?> args)
    {
        // Handle date added to selection
    }
    
    private void OnDateDeselected(DeSelectedEventArgs<DateTime?> args)
    {
        // Handle date removed from selection
    }
}
```

### Common Patterns

#### Pattern 1: Date Range Selection
Define Min and Max boundaries to constrain user selection:
```razor
<SfCalendar TValue="DateTime?" Value="@SelectedDate" 
    Min="@MinDate" Max="@MaxDate"></SfCalendar>
```

#### Pattern 2: Two-Way Data Binding
Keep Calendar in sync with component state:
```razor
<p>Selected: @SelectedDate</p>
<SfCalendar TValue="DateTime?" @bind-Value="@SelectedDate"></SfCalendar>
```

#### Pattern 3: Custom Cell Rendering
Highlight or customize specific date cells during render:
```razor
<SfCalendar TValue="DateTime?">
    <CalendarEvents TValue="DateTime?" OnRenderDayCell="@CustomizeCell"></CalendarEvents>
</SfCalendar>
```

#### Pattern 4: View Restrictions
Limit navigation to specific view levels (e.g., Year → Month only):
```razor
<SfCalendar TValue="DateTime?" 
    Start="CalendarView.Year" 
    Depth="CalendarView.Month"></SfCalendar>
```

#### Pattern 5: Localization
Render calendar in specific language/culture:
```razor
<SfCalendar TValue="DateTime?" EnableRtl="false"></SfCalendar>
```

### Key Props & When to Use

| Property | Type | Purpose | Example |
|----------|------|---------|---------|
| `Value` | `TValue` | Selected date (one-way binding) | `Value="@SelectedDate"` |
| `@bind-Value` | `TValue` | Two-way data binding | `@bind-Value="@SelectedDate"` |
| `Values` | `DateTime[]` | Multiple selected dates (multi-select mode) | `Values="@SelectedDates"` |
| `@bind-Values` | `DateTime[]` | Two-way binding for multi-selection | `@bind-Values="@SelectedDates"` |
| `IsMultiSelection` | `bool` | Enable multiple date selection | `IsMultiSelection="true"` |
| `Min` | `DateTime` | Earliest selectable date (inclusive) | `Min="@minSelectableDate"` |
| `Max` | `DateTime` | Latest selectable date (inclusive) | `Max="@maxSelectableDate"` |
| `Start` | `CalendarView` | Initial view (Month/Year/Decade) | `Start="CalendarView.Year"` |
| `Depth` | `CalendarView` | Deepest view level for drilling | `Depth="CalendarView.Month"` |
| `ShowTodayButton` | `bool` | Display "Today" button in footer | `ShowTodayButton="true"` |
| `CalendarMode` | `CalendarType` | Calendar system (Gregorian/Islamic) | `CalendarMode="CalendarType.Islamic"` |
| `WeekRule` | `CalendarWeekRule` | Week numbering calculation rule | `WeekRule="CalendarWeekRule.FirstDay"` |
| `DayHeaderFormat` | `DayHeaderFormats` | Day header display format | `DayHeaderFormat="DayHeaderFormats.Short"` |
| `EnableRtl` | `bool` | Right-to-left layout | `EnableRtl="true"` |
| `WeekNumber` | `bo