Shaunebu.MAUI.CalendarControl 1.0.2

Shaunebu.MAUI.CalendarControl 📅

Overview ✨

Shaunebu.MAUI.CalendarControl is a professional-grade, fully customizable calendar control for .NET MAUI with:

• 4 view modes — Month, Year, Decade, and Century with drill-up/drill-down navigation
• 4 selection modes — None, Single, Multiple, and Range
• 50+ bindable properties — Full theming, styling, and behavioral customization
• Full MVVM support — Commands for navigation, selection, view changes, and display date changes
• Special dates — Custom backgrounds, text colors, indicator dots, and blackout dates
• Swipe navigation — Left/right swipe gestures for month/year/decade/century navigation
• Culture-aware — Localized month names, day names, and week numbering
• Accessibility — AutomationProperties on all day cells with descriptive labels
• Cross-platform — Android, iOS, macOS (Mac Catalyst), and Windows

Feature Highlights 🆚

Installation 📦

dotnet add package Shaunebu.MAUI.CalendarControl

Or via PackageReference:

<ItemGroup>
  <PackageReference Include="Shaunebu.MAUI.CalendarControl" Version="1.0.x" />
</ItemGroup>

Quick Start 🚀

1. Configure in MauiProgram.cs

using Shaunebu.MAUI.CalendarControl;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();

        builder
            .UseMauiApp<App>()
            .UseShaunebuCalendar();

        return builder.Build();
    }
}

2. Add to XAML

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:cal="clr-namespace:Shaunebu.MAUI.CalendarControl;assembly=Shaunebu.MAUI.CalendarControl"
             x:Class="MyApp.MainPage">

    <cal:CalendarView
        SelectionMode="Single"
        ShowWeekNumbers="True"
        ShowTodayButton="True"
        FirstDayOfWeek="Monday"
        SelectionChanged="OnSelectionChanged" />

</ContentPage>

3. Handle Selection in Code-Behind

private void OnSelectionChanged(object sender, DateSelectionChangedEventArgs e)
{
    if (e.NewDate.HasValue)
    {
        DisplayAlert("Selected", e.NewDate.Value.ToShortDateString(), "OK");
    }
}

XAML Configuration Examples 🎨

Basic Calendar with Theming

<cal:CalendarView
    SelectionMode="Single"
    ShowWeekNumbers="True"
    ShowTodayButton="True"
    ShowNavigationArrows="True"
    FirstDayOfWeek="Monday"
    DayNameFormat="Abbreviated"
    HeaderBackground="#1976D2"
    HeaderTextColor="White"
    HeaderFontSize="20"
    DayTextColor="#333333"
    DayFontSize="14"
    TodayTextColor="#1976D2"
    TodayBorderColor="#1976D2"
    TodayBackground="Transparent"
    SelectionBackground="#1976D2"
    SelectionTextColor="White"
    WeekendTextColor="#999999"
    DayNamesTextColor="#888888"
    NavigationArrowColor="White"
    CellCornerRadius="20" />

Multiple Selection Mode

<cal:CalendarView
    x:Name="MultiCalendar"
    SelectionMode="Multiple"
    ShowLeadingAndTrailingDates="True" />

// Access selected dates
var dates = MultiCalendar.SelectedDates; // ObservableCollection<DateTime>

Range Selection Mode

<cal:CalendarView
    x:Name="RangeCalendar"
    SelectionMode="Range"
    RangeSelectionBackground="#331976D2" />

// Access selected range
var range = RangeCalendar.SelectedDateRange; // CalendarDateRange
if (range?.StartDate != null && range?.EndDate != null)
{
    // Use range.Contains(someDate) to check membership
}

Min/Max Date Constraints

<cal:CalendarView
    MinDate="{Binding MinimumDate}"
    MaxDate="{Binding MaximumDate}" />

Localized Calendar

<cal:CalendarView
    Culture="{Binding SelectedCulture}"
    HeaderDateFormat="MMMM yyyy"
    DayNameFormat="Shortest" />

MVVM Integration 🏗

Binding to Commands

<cal:CalendarView
    SelectionMode="Single"
    SelectedDate="{Binding SelectedDate, Mode=TwoWay}"
    DisplayDate="{Binding DisplayDate, Mode=TwoWay}"
    SelectionChangedCommand="{Binding DateSelectedCommand}"
    DisplayDateChangedCommand="{Binding MonthNavigatedCommand}"
    ViewChangedCommand="{Binding ViewDrilledCommand}"
    ForwardCommand="{Binding GoForwardCommand}"
    BackwardCommand="{Binding GoBackwardCommand}"
    GoToTodayCommand="{Binding NavigateToTodayCommand}"
    ResetSelectionCommand="{Binding ClearSelectionCommand}" />

ViewModel Example

public partial class CalendarViewModel : ObservableObject
{
    [ObservableProperty]
    private DateTime? selectedDate = DateTime.Today;

    [ObservableProperty]
    private DateTime displayDate = new(DateTime.Today.Year, DateTime.Today.Month, 1);

    [RelayCommand]
    private void DateSelected(DateSelectionChangedEventArgs e)
    {
        if (e.NewDate.HasValue)
        {
            // Handle date selection
            Debug.WriteLine($"Selected: {e.NewDate.Value:d}");
        }
    }

    [RelayCommand]
    private void MonthNavigated(DisplayDateChangedEventArgs e)
    {
        Debug.WriteLine($"Navigated from {e.OldDate:MMMM yyyy} to {e.NewDate:MMMM yyyy}");
    }
}

Special Dates & Blackout Dates 📌

Configure Special Dates

var calendar = new CalendarView();

// Add special dates with custom styling
calendar.SpecialDates.Add(new CalendarSpecialDate
{
    Date = new DateTime(2025, 12, 25),
    Background = Colors.Red,
    TextColor = Colors.White,
    IndicatorColor = Colors.Gold
});

// Add a blackout date via special dates
calendar.SpecialDates.Add(new CalendarSpecialDate
{
    Date = new DateTime(2025, 1, 1),
    IsBlackout = true
});

// Add blackout dates directly
calendar.BlackoutDates.Add(new DateTime(2025, 7, 4));
calendar.BlackoutDates.Add(new DateTime(2025, 11, 27));

Special Date Properties

Public Methods 🔧

Bindable Properties Reference 📚

Selection Properties

Display & Navigation Properties

Visibility Properties

Formatting Properties

Styling Properties

Command Properties (MVVM)

Events 📡

DateSelectionChangedEventArgs

Architecture Overview 🏗

┌────────────────────────────────────────────────────────────────────┐
│              Shaunebu.MAUI.CalendarControl                         │
├────────────────────────────────────────────────────────────────────┤
│ Controls/                                                          │
│   CalendarView.cs          Main ContentView control (~1500 lines)  │
│     ├─ Bindable Properties   50+ configurable properties           │
│     ├─ Rendering Engine      Month / Year / Decade / Century views │
│     ├─ Selection Handling    Single / Multiple / Range / None      │
│     ├─ Navigation            Forward / Backward / DrillUp / Down   │
│     ├─ MVVM Commands         8 bindable ICommand properties        │
│     └─ Accessibility         AutomationProperties on all cells     │
├────────────────────────────────────────────────────────────────────┤
│ Enums/                                                             │
│   CalendarViewMode.cs       Month | Year | Decade | Century        │
│   CalendarSelectionMode.cs  None | Single | Multiple | Range       │
│   CalendarDayNameFormat.cs  Full | Abbreviated | Shortest          │
├────────────────────────────────────────────────────────────────────┤
│ Models/                                                            │
│   CalendarDateRange.cs      Start/End date range with Contains()   │
│   CalendarSpecialDate.cs    Per-date visual customization model    │
├────────────────────────────────────────────────────────────────────┤
│ Events/                                                            │
│   DateSelectionChangedEventArgs.cs    Multi-mode selection args    │
│   CalendarViewChangedEventArgs.cs     View mode change args        │
│   DisplayDateChangedEventArgs.cs      Display date change args     │
├────────────────────────────────────────────────────────────────────┤
│ Extensions/                                                        │
│   AppBuilderExtensions.cs   UseShaunebuCalendar() registration     │
├────────────────────────────────────────────────────────────────────┤
│ Platforms/                                                         │
│   Android/   iOS/   MacCatalyst/   Windows/                        │
└────────────────────────────────────────────────────────────────────┘

Advanced Usage Scenarios 🔥

Booking / Scheduling Calendar

var calendar = new CalendarView
{
    SelectionMode = CalendarSelectionMode.Range,
    MinDate = DateTime.Today,
    MaxDate = DateTime.Today.AddMonths(6),
    ShowTodayButton = true
};

// Block out unavailable dates
foreach (var bookedDate in existingBookings)
    calendar.BlackoutDates.Add(bookedDate);

// Highlight available premium slots
foreach (var slot in premiumSlots)
{
    calendar.SpecialDates.Add(new CalendarSpecialDate
    {
        Date = slot,
        IndicatorColor = Colors.Gold,
        Background = Color.FromArgb("#FFF8E1")
    });
}

Multi-Tenant Event Calendar

// Mark event dates with color-coded indicators
calendar.SpecialDates.Add(new CalendarSpecialDate
{
    Date = meetingDate,
    IndicatorColor = Colors.Blue
});

calendar.SpecialDates.Add(new CalendarSpecialDate
{
    Date = deadlineDate,
    IndicatorColor = Colors.Red,
    TextColor = Colors.Red
});

calendar.SpecialDates.Add(new CalendarSpecialDate
{
    Date = holidayDate,
    IsBlackout = true
});

Culture-Aware International Calendar

var calendar = new CalendarView
{
    Culture = new CultureInfo("ar-SA"),        // Arabic (Saudi Arabia)
    FirstDayOfWeek = DayOfWeek.Saturday,
    DayNameFormat = CalendarDayNameFormat.Shortest,
    HeaderDateFormat = "MMMM yyyy"
};

Programmatic Navigation

// Navigate to a specific date
calendar.GoToDate(new DateTime(2025, 12, 25));

// Navigate forward/backward
calendar.Forward();
calendar.Backward();

// Jump to today
calendar.GoToToday();

// Clear all selections
calendar.ResetSelection();

Supported Platforms 📱

Troubleshooting 🔧

Calendar Not Rendering

• Ensure UseShaunebuCalendar() is called in MauiProgram.cs
• Verify the XAML namespace: xmlns:cal="clr-namespace:Shaunebu.MAUI.CalendarControl;assembly=Shaunebu.MAUI.CalendarControl"

Selection Not Working

• Check that SelectionMode is not set to None
• Verify the date is not in BlackoutDates or SpecialDates with IsBlackout = true
• Ensure the date is within MinDate / MaxDate bounds

Navigation Arrows Disabled

• The arrows automatically disable when MinDate / MaxDate boundaries are reached
• Verify ShowNavigationArrows is true

View Drill-Up/Down Not Working

• Set AllowViewNavigation="True" (default)
• The header label must be tapped to drill up
• View navigation respects MinView and MaxView bounds

Week Numbers Not Showing

• Set ShowWeekNumbers="True"
• Week numbers use the Culture property's calendar week rule

License 📄

This project is licensed under the MIT License.