MauiPersianToolkit

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

MauiPersianToolkit

★ 42 Open GitHub ↗

Persian Calendar / Date Picker, & some other controls for .NET MAUI

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Maui Persian Toolkit

[![NuGet](https://img.shields.io/nuget/v/MauiPersianToolkit.svg)](https://www.nuget.org/packages/MauiPersianToolkit/)
[![License](https://img.shields.io/github/license/RezaShaban/MauiPersianToolkit)](https://raw.githubusercontent.com/RezaShaban/MauiPersianToolkit/master/LICENSE)
[![Build](https://github.com/RezaShaban/MauiPersianToolkit/actions/workflows/dotnet.yml/badge.svg)](https://github.com/RezaShaban/MauiPersianToolkit/actions)
[![Tests](https://img.shields.io/badge/tests-20%2B%20passing-brightgreen)](https://github.com/RezaShaban/MauiPersianToolkit/actions)
[![.NET 8](https://img.shields.io/badge/.NET-8.0-blueviolet)](https://dotnet.microsoft.com/)

`MauiPersianToolkit` is a comprehensive library for **.NET MAUI** that provides a variety of Persian language UI controls and components with full support for multiple calendar systems. This library is designed to help developers create modern, cross-platform applications with support for Persian language and right-to-left (RTL) layouts.

## ✨ Key Features

### 📅 Advanced Calendar System
- **Multiple Calendar Support**: Persian (Jalali), Gregorian, and Islamic (Hijri) calendars
- **Flexible DatePicker**: Single, Multiple, and Range selection modes
- **Calendar Service Architecture**: Strategy pattern for extensible calendar implementations
- **Full Calendar Validation**: Automatic week alignment and day-of-week positioning
- **20+ Unit Tests**: Comprehensive test coverage for calendar functionality

### 🎨 UI Controls
- **Persian DatePicker**: Customizable date picker with multiple selection modes
- **TreeView**: Supports None, Single, and Multiple selection modes with hierarchy support
- **TabView**: Customizable tab control with multiple tabs and dynamic content
- **SlideButton**: Interactive slideable button for confirmation actions
- **Picker**: Single and Multiple selection pickers with enhanced UI
- **Entry & Editor**: Enhanced text entry controls with Persian language and RTL support
- **Expander**: Expandable and collapsible container for dynamic content
- **CheckBox, Button, Circle Image**: Custom-styled UI components

### 💬 Dialog System
- **Alert Dialog**: Simple message dialog
- **Confirm Dialog**: Dialog with confirmation options
- **Prompt Dialog**: Dialog to capture user input
- **Custom Dialog**: Fully customizable dialog with any content

### 🛠️ Developer Tools
- **Converters**: PersianDateConverter, PersianDateTimeConverter, and more
- **Extensions**: Calendar extensions for easy date manipulation
- **Custom Fonts**: Built-in support for IranianSans and FontAwesome fonts
- **RTL Support**: Full right-to-left layout support for all controls

## 📋 Project Statistics

- **Version**: 2.0.7
- **Target Framework**: .NET 8.0+
- **Platforms**: Windows, iOS, Android
- **License**: MIT
- **Tests**: 20+ unit tests (Calendar Service + Week Layout)
- **Code Quality**: CI/CD with automated testing on every PR

## 🚀 Installation

You can install the `MauiPersianToolkit` package via NuGet Package Manager or .NET CLI:

### NuGet Package Manager
```powershell
Install-Package MauiPersianToolkit
```

### .NET CLI
```bash
dotnet add package MauiPersianToolkit
```

## 🎯 Getting Started

### 1. Startup Configuration

Add the Persian Toolkit to your MauiApp in `MauiProgram.cs`:

```csharp
public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
                fonts.AddFont("IranianSans.ttf", "IranianSans");
            })
            .UseMauiCommunityToolkit()
            .UsePersianUIControls();  // Add this line
        
        return builder.Build();
    }
}
```

### 2. Basic XAML Usage

```xml
<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:persian="clr-namespace:MauiPersianToolkit.Controls;assembly=MauiPersianToolkit"
             x:Class="YourApp.MainPage"
             Title="Persian Toolkit Demo">

<Label Text="Entry Field" FontSize="16" FontAttributes="Bold"/>
            <persian:EntryView 
                PlaceHolder="Enter your name" 
                Text="{Binding UserName}" />

<Label Text="Expandable Section" FontSize="16" FontAttributes="Bold"/>
            <persian:Expander IsExpanded="False" Header="Click to expand">
                <Label Text="This content is hidden until expanded" Padding="10"/>
            </persian:Expander>

</StackLayout>
    </ScrollView>
</ContentPage>
```

### 3. Calendar System Usage

#### Using Calendar Services Directly

```csharp
using MauiPersianToolkit.Services.Calendar;
using MauiPersianToolkit.Enums;

// Get calendar service
var persianService = CalendarServiceFactory.GetService(CalendarType.Persian);
var gregorianService = CalendarServiceFactory.GetService(CalendarType.Gregorian);
var hijriService = CalendarServiceFactory.GetService(CalendarType.Hijri);

// Convert dates
var today = DateTime.Now;
string persianDate = persianService.ToCalendarDate(today);      // "1403/05/25"
string gregorianDate = gregorianService.ToCalendarDate(today);  // "2024/08/16"
string hijriDate = hijriService.ToCalendarDate(today);          // "1446/02/21"

// Parse dates back
var parsed = persianService.ToGregorianDate("1403/05/25");

// Get calendar information
int year = persianService.GetYear(today);
int month = persianService.GetMonth(today);
string monthName = persianService.GetMonthName(month);
bool isLeap = persianService.IsLeapYear(year);
DayOfWeek holiday = persianService.GetLastDayOfWeek();  // Friday for Persian
```

#### Using Extension Methods (Backward Compatible)

```csharp
using MauiPersianToolkit;

DateTime today = DateTime.Now;

// Convert to Persian (default)
string persianDate = today.ToPersianDate();  // "1403/05/25"

// Convert to other calendars
string gregorianDate = today.ToCalendarDate(CalendarType.Gregorian);
string hijriDate = today.ToCalendarDate(CalendarType.Hijri);

// Parse back
var parsed = "1403/05/25".ToDateTime();
var gregorianParsed = "2024/08/16".ToDateTime(CalendarType.Gregorian);
```

### 4. Dialog Usage

```csharp
using MauiPersianToolkit.Services.Dialog;
using MauiPersianToolkit.Models;

public partial class MainPage : ContentPage
{
    private readonly IDialogService _dialogService;
    
    public MainPage(IDialogService dialogService)
    {
        InitializeComponent();
        _dialogService = dialogService;
    }

// Alert Dialog
    private async void ShowAlert()
    {
        await _dialogService.Alert("This is an alert message");
    }

// Confirm Dialog
    private async void ShowConfirm()
    {
        var config = new ConfirmConfig
        {
            Title = "Confirm Action",
            Message = "Are you sure?",
            AcceptText = "Yes",
            CancelText = "No",
            OnAction = (result) =>
            {
                if (result)
                    Debug.WriteLine("User confirmed");
                else
                    Debug.WriteLine("User cancelled");
            }
        };
        
        await _dialogService.Confirm(config);
    }

// Prompt Dialog
    private async void ShowPrompt()
    {
        var config = new PromptConfig
        {
            Title = "Enter Name",
            Message = "Please enter your name:",
            Placeholder = "Name",
            AcceptText = "OK",
            CancelText = "Cancel",
            OnAction = (result) =>
            {
                if (result.IsOk)
                    Debug.WriteLine($"User entered: {result.Input}");
            }
        };
        
        await _dialogService.Prompt(config);
    }

// Custom Dialog
    private async void ShowCustomDialog()
    {
        var customContent = new StackLayout
        {
            Children =
            {
                new EntryView { PlaceHolder = "Name" },
                new EntryView { PlaceHolder = "Email" },
                new persian:DatePicker { PlaceHolder = "Birth Date" }
            }
        };

## 📚 Examples and Documentation

### Calendar Service Examples
See `MauiPersianToolkit/Examples/CalendarServiceExamples.cs` for:
- Extension methods usage
- Calendar service factory usage
- Calendar conversions
- DatePicker control usage
- Custom calendar registration

### Calendar Tests
The project includes comprehensive unit tests:

**CalendarServiceTests** - 7 tests covering:
- Date conversion roundtrip
- Month boundaries
- Holiday detection
- Month names
- Leap year validation
- DatePickerViewModel integration
- Date formatting

**CalendarWeekLayoutTests** - 13+ tests covering:
- Consecutive days alignment
- Week structure (7 columns per week)
- Persian calendar day positioning
- Gregorian calendar day positioning
- Empty cells before first day
- End of month positioning
- Multiple month validation
- Holiday day placement
- Specific date column placement

Run tests:
```bash
dotnet test ./MauiPersianToolkit.Test/MauiPersianToolkit.Test.csproj
```

## 🔧 Customization

All controls are designed to be easily customizable:

### Custom Calendar Type

Implement `ICalendarService` for custom calendar support:

```csharp
public class MyCustomCalendarService : ICalendarService
{
    // Implement interface methods
    public string ToCalendarDate(DateTime gregorianDate) { /* ... */ }
    public DateTime ToGregorianDate(string calendarDate) { /* ... */ }
    // ... other methods
}

// Register with factory
CalendarServiceFactory.RegisterService(
    CalendarType.Custom, 
    new MyCustomCalendarService()
);
```

### Style Customization

Customize colors, fonts, and behaviors:

```xml
<persian:DatePicker
    PlaceHolder="Select Date"
    SelectDayColor="Blue"
    CanSelectHolidays="False"
    DisplayFormat="yyyy/MM/dd" />
```

## 🧪 Testing

The project includes a comprehensive test suite:

```
MauiPersianToolkit.Test/
├── CalendarServiceTests.cs (7 tests)
├── CalendarWeekLayoutTests.cs (13+ tests)
└── CalendarWeekLayoutTests.README.md (documentation)
```

### GitHub Actions CI/CD

Automated testing on every commit:
- ✅ Build validation
- ✅ Unit tests execution
- ✅ Calendar-specific tests
- ✅ Code coverage reports

See `.github/workflows/` for CI/CD configuration.

## 📄 License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

## 🤝 Contributing

We welcome contributions! Follow these steps:

1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/YourFeature`)
3. **Commit** your changes (`git commit -m 'Add YourFeature'`)
4. **Push** to the branch (`git push origin feature/YourFeature`)
5. **Open** a Pull Request

### Contribution Guidelines

- Follow existing code style and conventions
- Add unit tests for new features
- Update documentation as needed
- Ensure all tests pass locally
- Provide clear PR description

## 🙏 Acknowledgments

- .NET MAUI Community for excellent framework and tools
- CommunityToolkit.Maui for reusable components
- All contributors and users for feedback and suggestions

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/RezaShaban/MauiPersianToolkit/issues)
- **Discussions**: [GitHub Discussions](https://github.com/RezaShaban/MauiPersianToolkit/discussions)
- **Website**: [Project Homepage](https://rezashaban.github.io/MauiPersianToolkit)

## 🔗 Quick Links

- [NuGet Package](https://www.nuget.org/packages/MauiPersianToolkit/)
- [GitHub Repository](https://github.com/RezaShaban/MauiPersianToolkit)
- [Documentation](https://github.com/RezaShaban/MauiPersianToolkit/wiki)
- [Issues & Bugs](https://github.com/RezaShaban/MauiPersianToolkit/issues)

## 📊 Project Status

| Component | Status | Coverage |
|-----------|--------|----------|
| Core Library | ✅ Stable | Mature |
| Calendar System | ✅ Stable | 3 calendars |
| UI Controls | ✅ Stable | 10+ controls |
| Dialog System | ✅ Stable | 4 types |
| Unit Tests | ✅ Complete | 20+ tests |
| Documentation | ✅ Complete | Full |

---

**Happy Coding! 🚀**

Start building beautiful Persian-enabled applications with MauiPersianToolkit today!

MauiPersianToolkit

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README