MauiPersianToolkit 3.0.2

Maui Persian Toolkit

MauiPersianToolkit is a .NET MAUI UI toolkit for Persian / RTL apps: calendars, inputs, pickers, dialogs, and theming — with native popups, light/dark themes, and built-in fa / en / ar chrome strings. No CommunityToolkit dependency.

Key features

Calendar

• Persian (Jalali), Gregorian, and Hijri calendars
• Correct week starts (Sat→Fri for Persian/Hijri, Sun→Sat for Gregorian)
• DatePicker with Single / Multiple / Range via CalendarOptions
• Inline DatePickerView or popup field (popup content is created lazily on first open)
• Pluggable ICalendarService + unit tests

Controls

Dialogs & overlays (native)

• Alert / Confirm / Prompt / Custom — sync + *Async APIs on IDialogService
• Toast & Snackbar (Android, iOS, Windows)
• Popup host API — no third-party popup package

Theme

• Follows AppTheme (system / light / dark)
• Semantic Pdt* tokens + AppThemeBinding
• Override via UseMauiPersianToolkit, App.xaml, or PersianTheme.Configure

Localization

• Built-in catalogs: fa, en, ar
• PersianToolkitStrings / PersianToolkitStringId for chrome (Accept, Today, SelectTime, …)
• Extra languages via AdditionalCatalogs; XAML {mpt:Localize Today}

Performance notes

• Date/time popup sheets are created on first tap, not on page Loaded
• Theme seeding uses a cached snapshot (fast path if already seeded)
• Tree rows avoid per-cell theme copies; gallery shadows deferred where possible

Project stats

• Version: 3.0.0
• TFMs: net10.0, Android, iOS, Windows
• Dependencies: Microsoft.Maui.Controls only
• License: MIT
• Sample: PersianUISamples — categorized gallery with theme + language switcher

Installation

Install-Package MauiPersianToolkit

dotnet add package MauiPersianToolkit

Getting started

1. Register in MauiProgram.cs

builder
    .UseMauiApp<App>()
    .ConfigureFonts(fonts =>
    {
        fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
    })
    .UseMauiPersianToolkit(options =>
    {
        options.DefaultCalendarType = CalendarType.Persian;
        options.Localization.Culture = "fa"; // fa | en | ar

        // Optional theme overrides
        // options.Theme.Accent = Colors.Teal;
    });

Fonts (IranianSans, FontAwesome), handlers, dialog service, and theme defaults are registered for you.

2. Theme styles in App.xaml (recommended)

<Application xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:persian="clr-namespace:MauiPersianToolkit.Resources;assembly=MauiPersianToolkit"
             x:Class="YourApp.App">
    <Application.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <persian:PersianStyles/>
            </ResourceDictionary.MergedDictionaries>
            
            
        </ResourceDictionary>
    </Application.Resources>
</Application>

If you skip merging, UseMauiPersianToolkit still injects defaults when the app or first control starts. You can also call PersianTheme.EnsureApplicationStyles() early in App.

3. XAML namespace

xmlns:pui="clr-namespace:MauiPersianToolkit.Controls;assembly=MauiPersianToolkit"
xmlns:mpt="http://schemas.mauipersiantoolkit.com/2026/toolkit"

4. Quick control examples

DatePicker (calendar type & selection live on CalendarOptions):

<pui:DatePicker PlaceHolder="تاریخ"
                DisplayFormat="yyyy/MM/dd"
                Icon="&#xf073;"
                SelectedPersianDate="{Binding SelectedDate}"
                CalendarOption="{Binding CalendarOption}"/>

public CalendarOptions CalendarOption { get; } = new()
{
    CalendarType = CalendarType.Persian,      // or Gregorian / Hijri
    SelectionMode = SelectionMode.Single,     // Single | Multiple | Range
    AutoCloseAfterSelectDate = true,
    SelectDayColor = Color.FromArgb("#5B2BDF"),
};

TimePicker:

<pui:TimePicker PlaceHolder="ساعت جلسه"
                SelectedTime="{Binding MeetingTime}"
                DisplayFormat="HH:mm"
                Is24Hour="True"
                MinuteInterval="5"/>

AutoCompleteView:

<pui:AutoCompleteView PlaceHolder="شهر"
                     ItemsSource="{Binding Cities}"
                     DisplayProperty="Title"
                     Text="{Binding CityText}"
                     SelectedItem="{Binding SelectedCity}"
                     Options="{Binding CityOptions}"/>

public AutoCompleteOptions CityOptions { get; } = new()
{
    FilterMode = AutoCompleteFilterMode.Contains,
    MinimumPrefixLength = 1,
    MaxSuggestions = 8,
    UseNativeSuggestions = true,
    ShowClearButton = true,
    OpenOnFocus = true,
};

Inputs / layout:

<pui:EntryView PlaceHolder="نام" Icon="&#xf007;" Text="{Binding Name}"/>
<pui:EditorView Title="شرح" PlaceHolder="متن…" Text="{Binding Notes}"/>
<pui:PickerView PlaceHolder="انتخاب" ItemsSource="{Binding Items}"
                DisplayProperty="Title" SelectionMode="Single"/>
<pui:TabView SelectedTabColor="{StaticResource PdtAccent}">
    <pui:TabView.ItemsSource>
        <pui:TabItemView Title="اول" Icon="&#xf015;">…</pui:TabItemView>
        <pui:TabItemView Title="دوم" Icon="&#xf1b2;">…</pui:TabItemView>
    </pui:TabView.ItemsSource>
</pui:TabView>
<pui:Expander IsExpanded="False">
    <pui:Expander.Header>
        <Label Text="Header" FontFamily="IranianSans"/>
    </pui:Expander.Header>
    <Label Text="Body"/>
</pui:Expander>

Calendar APIs

var persian = CalendarServiceFactory.GetService(CalendarType.Persian);
string date = persian.ToCalendarDate(DateTime.Now);       // e.g. 1403/…
DateTime g = persian.ToGregorianDate("1403/05/25");

DateTime.Now.ToPersianDate();
DateTime.Now.ToCalendarDate(CalendarType.Hijri);
"1403/05/25".ToDateTime();

Custom calendars: implement ICalendarService and register with CalendarServiceFactory.RegisterService(...).

Dialogs (IDialogService)

Registered as a singleton by UseMauiPersianToolkit. Prefer async APIs when you need a result:

await dialogs.AlertAsync("پیام", "عنوان");

bool ok = await dialogs.ConfirmAsync(new ConfirmConfig
{
    Title = "حذف",
    Message = "ادامه می‌دهید؟",
    Icon = MessageIcon.QUESTION,
});

PromptResult prompt = await dialogs.PromptAsync(new PromptConfig
{
    Title = "نام",
    Placeholder = "…",
});

dialogs.Toast(new ToastConfig { Message = "ذخیره شد" });
dialogs.Snackbar(new SnackbarConfig
{
    Message = "حذف شد",
    AcceptText = "بازگردانی",
    Duration = TimeSpan.FromSeconds(5),
});

Toast / Snackbar (static helpers)

await Toast.Make("Saved", ToastDuration.Short).Show();
await Snackbar.Make("Deleted", () => { /* undo */ }, "Undo", TimeSpan.FromSeconds(3)).Show();

Theme tokens

Constants: PersianThemeKeys. Defaults: PersianStyles.

PersianTheme.Configure(theme =>
{
    theme.SurfaceDark = Color.FromArgb("#111827");
    theme.Accent = Colors.Orange;
});

Localization

Built-in: fa, en, ar.

builder.UseMauiPersianToolkit(options =>
{
    options.Localization.Culture = "ar";
    options.Localization.StringOverrides[PersianToolkitStringId.Ok] = "متوجه شدم";
});

// Runtime
PersianToolkitStrings.SetCulture("en");

XAML: {mpt:Localize Today}. After a runtime culture change, recreate or navigate back to the page so bindings refresh.

Sample app (PersianUISamples)

Full gallery of every control, grouped by category:

• Shell flyout + home overview
• Theme switcher: System / Light / Dark
• Language switcher: فارسی / English / العربية
• Each page shows real BindableProperty configuration and config hints

Run:

dotnet build ./PersianUISamples/PersianUISamples.csproj -f net10.0-android

Tests

dotnet test ./MauiPersianToolkit.Test/MauiPersianToolkit.Test.csproj

Coverage includes calendar conversion, week layout, Hijri display, localization, AutoComplete filtering, TimePicker, dialogs, expander, tree flatten, and popup options.

Contributing

1. Fork → feature branch → PR
2. Match existing style; add tests for new behavior
3. Update this README when APIs or controls change

License

MIT — see LICENSE.

Links

• NuGet
• Repository
• Issues
• Homepage

Status