MauiControlsExtras Architecture

This document describes the architectural decisions, patterns, and conventions for the MauiControlsExtras library. All contributors and agents should follow these guidelines when developing new controls or modifying existing ones.

Overview

MauiControlsExtras provides custom controls for .NET MAUI applications, designed to fill gaps for CRUD/LOB (Line of Business) applications. The library emphasizes:

Consistent Styling: All controls share common styling properties through a base class hierarchy
MVVM Support: Every user action has both an event and a corresponding command
Theme Integration: Controls respect global themes while allowing per-instance customization
Optional Behaviors: Interface-based patterns for validation, clipboard, selection, and undo/redo
Internal Reuse: When a library control can fulfill a need, prefer it over standard MAUI controls (e.g., DataGridComboBoxColumn uses our ComboBox, not MAUI Picker)

Project Structure

src/MauiControlsExtras/
├── Base/                           # Base classes and interfaces
│   ├── StyledControlBase.cs        # Core styling (all controls)
│   ├── TextStyledControlBase.cs    # Typography (text controls)
│   ├── ListStyledControlBase.cs    # Collection styling
│   ├── HeaderedControlBase.cs      # Header styling
│   ├── NavigationControlBase.cs    # Navigation state colors
│   ├── AnimatedControlBase.cs      # Animation support
│   ├── IClipboardSupport.cs        # Copy/cut/paste interface
│   ├── ISelectable.cs              # Selection interface
│   ├── IUndoRedo.cs                # Undo/redo interface
│   └── Validation/
│       ├── IValidatable.cs         # Validation interface
│       └── ValidationResult.cs     # Validation result type
├── Theming/
│   ├── IThemeAware.cs              # Theme change notifications
│   ├── ControlsTheme.cs            # Theme definition class
│   └── MauiControlsExtrasTheme.cs  # Static theme manager
├── Controls/                       # Control implementations
│   ├── ComboBox.xaml/.cs
│   └── [other controls]
└── Converters/                     # Value converters
    └── MauiAssetImageConverter.cs

Base Class Hierarchy

Inheritance Design

Controls inherit from the most specific base class that provides the properties they need:

ContentView
    └── StyledControlBase              (colors, borders, shadows)
            ├── TextStyledControlBase      (+ typography)
            │       └── ComboBox, NumericUpDown, TokenEntry, etc.
            ├── ListStyledControlBase      (+ collection styling)
            │       └── TreeView, DataGridView, etc.
            ├── HeaderedControlBase        (+ header styling)
            │       └── Accordion, PropertyGrid, Calendar, etc.
            ├── NavigationControlBase      (+ navigation states)
            │       └── Wizard, TabBar, etc. (step/tab navigation)
            └── AnimatedControlBase        (+ animation support)
                    └── [animated controls]

Choosing a Base Class

Control Type	Base Class	Key Features
Text input controls	`TextStyledControlBase`	Font, text color, placeholder
Dropdown/combo controls	`TextStyledControlBase`	Font, text color, placeholder
List/grid controls	`ListStyledControlBase`	Alternating rows, selection colors, separators
Accordion/expandable	`HeaderedControlBase`	Header styling, border
Wizard/stepper (UI navigation)	`NavigationControlBase`	Active/inactive/visited states
Animated controls	`AnimatedControlBase`	Duration, easing, enable flag
Data navigation (BindingNavigator)	`StyledControlBase`	No per-item visual states
Breadcrumb	`StyledControlBase`	Own active/inactive colors, no visited state
Simple styled controls	`StyledControlBase`	Just colors, borders, shadows

StyledControlBase Properties

All controls inherit these core properties:

// Colors
AccentColor         // Primary accent (default: null, uses theme)
ForegroundColor     // Text/icon color (theme-aware)
DisabledColor       // Disabled state color
ErrorColor          // Validation error color (#D32F2F)
SuccessColor        // Success indication (#388E3C)
WarningColor        // Warning indication (#F57C00)

// Borders
CornerRadius        // Rounded corners (default: 4)
BorderColor         // Normal border (theme-aware)
BorderThickness     // Border width (default: 1)
FocusBorderColor    // Focused state (defaults to AccentColor)
ErrorBorderColor    // Error state (defaults to ErrorColor)
DisabledBorderColor // Disabled state

// Shadows
HasShadow           // Enable shadow (default: false)
ShadowColor         // Shadow color (theme-aware)
ShadowOffset        // Shadow position
ShadowRadius        // Shadow blur
ShadowOpacity       // Shadow transparency

// Elevation
Elevation           // Material-style elevation (0-24)

Effective Properties Pattern

For every nullable property, there is an Effective* computed property that falls back to theme defaults:

// Property definition
public Color? BorderColor { get; set; }

// Effective property (never null)
public Color EffectiveBorderColor =>
    BorderColor ?? MauiControlsExtrasTheme.GetBorderColor();

Rule: Always bind XAML to Effective* properties, not raw properties.

<!-- CORRECT -->
<Border Stroke="{Binding EffectiveBorderColor, Source={x:Reference thisControl}}" />

<!-- WRONG - may be null -->
<Border Stroke="{Binding BorderColor, Source={x:Reference thisControl}}" />

Property Change Notifications

When a property changes, always notify both the raw and effective properties:

private static void OnBorderColorChanged(BindableObject bindable, object oldValue, object newValue)
{
    if (bindable is StyledControlBase control)
    {
        control.OnPropertyChanged(nameof(EffectiveBorderColor)); // Always include
        control.OnBorderColorChanged((Color?)oldValue, (Color?)newValue);
    }
}

Theming System

Theme Structure

ControlsTheme contains all theme values organized by category:

public class ControlsTheme
{
    // Semantic colors
    public Color AccentColor { get; set; }
    public Color ErrorColor { get; set; }
    public Color SuccessColor { get; set; }
    public Color WarningColor { get; set; }

    // Surface colors (separate for light/dark)
    public Color SurfaceColor { get; set; }
    public Color SurfaceColorDark { get; set; }

    // Selection colors
    public Color SelectionBackgroundColor { get; set; }
    public Color SelectionTextColor { get; set; }

    // Typography
    public double DefaultFontSize { get; set; }
    public string? FontFamily { get; set; }

    // Shape
    public double DefaultCornerRadius { get; set; }
    public double DefaultBorderThickness { get; set; }

    // Animation
    public int AnimationDuration { get; set; }
    public Easing AnimationEasing { get; set; }
    public bool EnableAnimations { get; set; }
}

Predefined Themes

The library ships with predefined themes:

ControlsTheme.Default - Balanced defaults
ControlsTheme.Modern - Rounded, subtle shadows
ControlsTheme.Compact - Reduced spacing, smaller radii
ControlsTheme.Fluent - Microsoft Fluent-inspired
ControlsTheme.Material3 - Google Material 3-inspired
ControlsTheme.HighContrast - Accessibility-focused

Using Themes

// Apply a predefined theme
MauiControlsExtrasTheme.ApplyTheme(ControlsTheme.Material3);

// Create a custom theme
var custom = MauiControlsExtrasTheme.CreateCustomTheme(theme =>
{
    theme.AccentColor = Colors.Purple;
    theme.DefaultCornerRadius = 12;
});
MauiControlsExtrasTheme.ApplyTheme(custom);

// Modify current theme
MauiControlsExtrasTheme.ModifyCurrentTheme(theme =>
{
    theme.EnableAnimations = false;
});

Theme-Aware Controls

Controls implement IThemeAware and subscribe to theme changes:

public abstract class StyledControlBase : ContentView, IThemeAware
{
    protected StyledControlBase()
    {
        MauiControlsExtrasTheme.ThemeChanged += OnGlobalThemeChanged;
    }

    public virtual void OnThemeChanged(AppTheme theme)
    {
        // Notify all effective properties
        OnPropertyChanged(nameof(EffectiveBorderColor));
        OnPropertyChanged(nameof(EffectiveForegroundColor));
        // ... etc
    }
}

MAUI Theme Bridge

The library automatically bridges MAUI's Application.RequestedThemeChanged event to the library's ThemeChanged event. This ensures controls update when users toggle Application.Current.UserAppTheme (the standard MAUI approach for Light/Dark switching).

Initialization: The bridge is enabled lazily from StyledControlBase.EnsureThemeSubscription() via MauiControlsExtrasTheme.EnableMauiThemeBridge(). No manual setup is required.
Debounce: A _lastNotifiedTheme guard prevents double-firing when both RaiseThemeChanged() and RequestedThemeChanged fire for the same theme transition.
Idempotent: EnableMauiThemeBridge() is safe to call multiple times — only the first call subscribes.
Null-safe: When Application.Current is null (unit tests, design-time), the bridge is a no-op.

MVVM Command Pattern

Design Rule

Every user action must have both an event AND a command.

// Event (code-behind support)
public event EventHandler<SelectionChangedEventArgs>? SelectionChanged;

// Command (MVVM support)
public ICommand? SelectionChangedCommand { get; set; }
public object? SelectionChangedCommandParameter { get; set; }

Command Invocation Pattern

When an action occurs, invoke both the event and command:

private void OnItemSelected(object item)
{
    var args = new SelectionChangedEventArgs(oldItem, item);

    // Raise event
    SelectionChanged?.Invoke(this, args);

    // Execute command
    var parameter = SelectionChangedCommandParameter ?? item;
    if (SelectionChangedCommand?.CanExecute(parameter) == true)
    {
        SelectionChangedCommand.Execute(parameter);
    }
}

Standard Commands by Action Type

Action	Command Name	Command Parameter
Selection change	`SelectionChangedCommand`	Selected item or custom
Open/expand	`OpenedCommand`	Control instance or null
Close/collapse	`ClosedCommand`	Control instance or null
Clear/reset	`ClearCommand`	None
Validate	`ValidateCommand`	Validation result
Value change	`ValueChangedCommand`	New value

Interface-Based Optional Behaviors

Controls opt-in to behaviors by implementing interfaces. Do NOT add these to base classes.

IContextMenuSupport

For controls that support right-click context menus with platform-specific native implementations:

public interface IContextMenuSupport
{
    ContextMenuItemCollection ContextMenuItems { get; }
    bool ShowDefaultContextMenu { get; set; }
    event EventHandler<ContextMenuOpeningEventArgs>? ContextMenuOpening;
    void ShowContextMenu(Point? position = null);
}

Platform implementations:

Windows: MenuFlyout with FontIcon support
macOS: UIMenu via UIContextMenuInteraction
iOS: UIAlertController (action sheet style)
Android: PopupMenu