bmc.maui/README.md

# BuyMeCoffee.Maui

[![.NET MAUI](https://img.shields.io/badge/.NET%20MAUI-10.0-512BD4?logo=dotnet)](https://dotnet.microsoft.com/apps/maui)
[![Platform](https://img.shields.io/badge/platform-Android%20%7C%20iOS%20%7C%20macOS%20%7C%20Windows-blue)](https://dotnet.microsoft.com/apps/maui)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![NuGet](https://img.shields.io/badge/nuget-coming%20soon-orange)](https://www.nuget.org)

A comprehensive .NET MAUI library for integrating Buy Me a Coffee support into your cross-platform applications. Provides branded buttons, QR codes, and interactive widgets with official BMC styling and theming.

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Controls](#controls)
  - [BuyMeACoffeeButton](#buymeacoffeebutton)
  - [BuyMeACoffeeQrCode](#buymeacoffeeqrcode)
  - [BuyMeACoffeeWidget](#buymeacoffeewidget)
- [Theming](#theming)
- [API Reference](#api-reference)
- [Platform Support](#platform-support)
- [Dependencies](#dependencies)
- [Examples](#examples)
- [Contributing](#contributing)
- [License](#license)

## Features

✅ **BuyMeACoffeeButton** - Branded button with official coffee cup logo and 8 color themes  
✅ **BuyMeACoffeeQrCode** - QR code generator with embedded BMC logo overlay  
✅ **BuyMeACoffeeWidget** - Full-featured support widget with amount selection, name/message fields, and monthly toggle  
✅ **Official Branding** - Uses authentic Buy Me a Coffee colors, logos, and styling  
✅ **Cross-Platform** - Supports Android, iOS, macOS, and Windows  
✅ **Customizable** - Extensive theming and styling options  
✅ **Touch Optimized** - Smooth animations and hover effects  
✅ **QR Code Generation** - High-quality QR codes with error correction level H  

## Installation

### Prerequisites

- .NET 10.0 SDK or later
- .NET MAUI workload installed
- Visual Studio 2022 17.8+ or Visual Studio Code with .NET MAUI extension

### Add to Your Project

1. **Add the project reference** to your .NET MAUI application:

```xml
<ItemGroup>
  <ProjectReference Include="..\BuyMeCofee.Maui\BuyMeCofee.Maui.csproj" />
</ItemGroup>
```

2. **Register the library** in your `MauiProgram.cs`:

```csharp
using BuyMeCofee.Maui;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .UseBuyMeACoffee(); // Add this line
            
        return builder.Build();
    }
}
```

This automatically registers SkiaSharp dependencies required for QR code rendering.

## Quick Start

Add the namespace to your XAML page:

```xml
xmlns:bmc="clr-namespace:BuyMeCofee.Maui.Controls;assembly=BuyMeCofee.Maui"
```

Add a button to your page:

```xml
<bmc:BuyMeACoffeeButton 
    Username="yourname"
    ButtonText="Buy me a coffee"
    Theme="Yellow" />
```

## Controls

### BuyMeACoffeeButton

A branded button that opens your Buy Me a Coffee page in the default browser.

#### Basic Usage

```xml
<bmc:BuyMeACoffeeButton 
    Username="yourname"
    Theme="Yellow" />
```

#### With Custom Styling

```xml
<bmc:BuyMeACoffeeButton 
    Username="yourname"
    ButtonText="Support My Work"
    Theme="Violet"
    CornerRadius="12"
    FontSize="18"
    CupSize="32"
    HorizontalOptions="Center" />
```

#### Custom Theme

```xml
<bmc:BuyMeACoffeeButton 
    Username="yourname"
    Theme="Custom"
    CustomBackgroundColor="#FF6B6B"
    CustomTextColor="White"
    ButtonText="Donate" />
```

#### Code-Behind Example

```csharp
using BuyMeCofee.Maui.Controls;
using BuyMeCofee.Maui.Enums;

var button = new BuyMeACoffeeButton
{
    Username = "yourname",
    ButtonText = "Buy me a coffee",
    Theme = BmcButtonTheme.Blue,
    CornerRadius = 10,
    FontSize = 16,
    CupSize = 28
};

layout.Children.Add(button);
```

#### Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `Username` | `string` | `""` | Your Buy Me a Coffee username/slug |
| `ButtonText` | `string` | `"Buy me a coffee"` | Button label text |
| `Theme` | `BmcButtonTheme` | `Yellow` | Color theme preset (Yellow, Black, White, Blue, Violet, Orange, Red, Green, Custom) |
| `CustomBackgroundColor` | `Color?` | `null` | Background color (Custom theme only) |
| `CustomTextColor` | `Color?` | `null` | Text color (Custom theme only) |
| `CornerRadius` | `double` | `8.0` | Border corner radius |
| `FontSize` | `double` | `16.0` | Button text font size |
| `CupSize` | `double` | `28.0` | Coffee cup logo height |

### BuyMeACoffeeQrCode

Generates a QR code linking to your BMC profile with the coffee cup logo overlaid in the center.

#### Basic Usage

```xml
<bmc:BuyMeACoffeeQrCode 
    Username="yourname"
    Size="250" />
```

#### With Custom Colors

```xml
<bmc:BuyMeACoffeeQrCode 
    Username="yourname"
    Size="300"
    ForegroundColor="DarkBlue"
    BackgroundColor="LightYellow"
    LogoSizeFraction="0.3" />
```

#### Code-Behind Example

```csharp
using BuyMeCofee.Maui.Controls;

var qrCode = new BuyMeACoffeeQrCode
{
    Username = "yourname",
    Size = 250,
    ForegroundColor = Colors.Black,
    BackgroundColor = Colors.White,
    LogoSizeFraction = 0.25
};

layout.Children.Add(qrCode);
```

#### Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `Username` | `string` | `""` | Your Buy Me a Coffee username/slug |
| `Size` | `double` | `200.0` | Width and height of the QR code |
| `ForegroundColor` | `Color` | `Black` | QR code module color |
| `BackgroundColor` | `Color` | `White` | QR code background color |
| `LogoSizeFraction` | `double` | `0.25` | Logo size as fraction of QR code (0.0-0.35) |

### BuyMeACoffeeWidget

A full-featured support widget with amount entry, preset chips, name/message fields, and monthly subscription toggle.

#### Basic Usage

```xml
<bmc:BuyMeACoffeeWidget 
    Username="yourname"
    DisplayName="John Doe" />
```

#### With Custom Configuration

```xml
<bmc:BuyMeACoffeeWidget 
    Username="yourname"
    DisplayName="John Doe"
    DefaultAmount="10"
    SuggestedAmounts="10,25,50,100"
    AccentColor="#6C5CE7"
    ShowMonthlyOption="True"
    SupportButtonText="Send Support"
    HorizontalOptions="Center" />
```

#### Handling Support Events

```xml
<bmc:BuyMeACoffeeWidget 
    x:Name="supportWidget"
    Username="yourname"
    DisplayName="John Doe"
    SupportRequested="OnSupportRequested" />
```

```csharp
private void OnSupportRequested(object sender, SupportRequestedEventArgs e)
{
    Console.WriteLine($"Support requested by: {e.Name ?? "Anonymous"}");
    Console.WriteLine($"Amount: ${e.Amount}");
    Console.WriteLine($"Message: {e.Message ?? "No message"}");
    Console.WriteLine($"Monthly: {e.IsMonthly}");
    
    // Log analytics, show confirmation, etc.
}
```

#### Code-Behind Example

```csharp
using BuyMeCofee.Maui.Controls;
using BuyMeCofee.Maui.Models;

var widget = new BuyMeACoffeeWidget
{
    Username = "yourname",
    DisplayName = "John Doe",
    DefaultAmount = 5,
    SuggestedAmounts = new[] { 25, 50, 100 },
    AccentColor = Color.FromArgb("#6C5CE7"),
    ShowMonthlyOption = true,
    SupportButtonText = "Support"
};

widget.SupportRequested += (sender, e) =>
{
    // Handle support request
    Debug.WriteLine($"Amount: ${e.Amount}, Monthly: {e.IsMonthly}");
};

layout.Children.Add(widget);
```

#### Properties

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `Username` | `string` | `""` | Your Buy Me a Coffee username/slug |
| `DisplayName` | `string` | `""` | Name displayed in header ("Support {DisplayName}") |
| `SuggestedAmounts` | `int[]` | `[25, 50, 100]` | Preset amount chips |
| `DefaultAmount` | `int` | `5` | Initial amount in entry field |
| `AccentColor` | `Color` | `#6C5CE7` | Support button background color |
| `ShowMonthlyOption` | `bool` | `true` | Show "Make this monthly" checkbox |
| `SupportButtonText` | `string` | `"Support"` | Support button label text |

#### Events

| Event | EventArgs | Description |
|-------|-----------|-------------|
| `SupportRequested` | `SupportRequestedEventArgs` | Raised when user taps Support button, before opening browser |

**SupportRequestedEventArgs Properties:**

```csharp
public class SupportRequestedEventArgs : EventArgs
{
    public string Username { get; init; }      // BMC username
    public int Amount { get; init; }           // Support amount
    public string? Name { get; init; }         // Supporter name (optional)
    public string? Message { get; init; }      // Support message (optional)
    public bool IsMonthly { get; init; }       // Monthly subscription toggle
}
```

## Theming

### Button Themes

The library includes 8 official Buy Me a Coffee color themes:

```csharp
public enum BmcButtonTheme
{
    Yellow,   // #FFDD00 - Official BMC brand color
    Black,    // #0D0C22 - Dark theme
    White,    // #FFFFFF - Light theme with stroke
    Blue,     // #5F7FFF
    Violet,   // #BD5CFF
    Orange,   // #FF813F
    Red,      // #FF6073
    Green,    // #78DEC7
    Custom    // Use CustomBackgroundColor and CustomTextColor
}
```

### Theme Examples

```xml
<!-- Official Yellow Theme -->
<bmc:BuyMeACoffeeButton Username="yourname" Theme="Yellow" />

<!-- Dark Theme -->
<bmc:BuyMeACoffeeButton Username="yourname" Theme="Black" />

<!-- Light Theme with Border -->
<bmc:BuyMeACoffeeButton Username="yourname" Theme="White" />

<!-- Violet Theme -->
<bmc:BuyMeACoffeeButton Username="yourname" Theme="Violet" />

<!-- Custom Theme -->
<bmc:BuyMeACoffeeButton 
    Username="yourname" 
    Theme="Custom"
    CustomBackgroundColor="#FF1744"
    CustomTextColor="White" />
```

### Brand Colors Reference

```csharp
public static class BmcColors
{
    public const string CupYellow = "#FFDD00";      // Official cup color
    public const string BrandDark = "#0D0C22";      // Brand dark
    public const string WidgetPurple = "#6C5CE7";   // Widget accent
    public const string WhiteStroke = "#E0E0E0";    // Border color
}
```

## API Reference

### Extension Methods

```csharp
public static class BuyMeACoffeeExtensions
{
    /// <summary>
    /// Registers Buy Me a Coffee controls and their dependencies (SkiaSharp).
    /// Call this in your MauiProgram.cs CreateMauiApp() builder.
    /// </summary>
    public static MauiAppBuilder UseBuyMeACoffee(this MauiAppBuilder builder);
}
```

### Helper Classes

#### BmcThemeResolver

```csharp
public static class BmcThemeResolver
{
    /// <summary>
    /// Resolves a BmcButtonTheme enum to theme colors.
    /// </summary>
    /// <exception cref="InvalidOperationException">Thrown for Custom theme</exception>
    public static BmcThemeInfo Resolve(BmcButtonTheme theme);
}

public record BmcThemeInfo(Color Background, Color TextColor, Color StrokeColor);
```

#### BmcBrandAssets

```csharp
internal static class BmcBrandAssets
{
    internal static ImageSource GetCupLogo();
    internal static Stream GetCupLogoStream();
}
```

### Constants

```csharp
public static class BmcConstants
{
    public const string BaseUrl = "https://buymeacoffee.com/";
    public const string DefaultButtonText = "Buy me a coffee";
    public const string DefaultSupportButtonText = "Support";
    public const double ButtonCornerRadius = 8.0;
    public const double WidgetCornerRadius = 16.0;
    public static readonly int[] DefaultSuggestedAmounts = [25, 50, 100];
}
```

## Platform Support

| Platform | Minimum Version | Status |
|----------|----------------|--------|
| **Android** | API 21 (Android 5.0) | ✅ Supported |
| **iOS** | 15.0+ | ✅ Supported |
| **macOS** (Catalyst) | 15.0+ | ✅ Supported |
| **Windows** | 10.0.17763.0+ | ✅ Supported |

**Note:** On Linux, only Android targets are built by default. iOS and macOS Catalyst require macOS build environment.

## Dependencies

The library requires the following NuGet packages:

```xml
<PackageReference Include="Microsoft.Maui.Controls" Version="$(MauiVersion)" />
<PackageReference Include="QRCoder" Version="1.6.0" />
<PackageReference Include="SkiaSharp.Views.Maui.Controls" Version="3.116.1" />
```

These are automatically installed when you reference the project.

## Examples

### Complete Page Example

```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:bmc="clr-namespace:BuyMeCofee.Maui.Controls;assembly=BuyMeCofee.Maui"
             x:Class="MyApp.SupportPage"
             Title="Support">
    
    <ScrollView>
        <VerticalStackLayout Spacing="20" Padding="20">
            
            <!-- Button Examples -->
            <Label Text="Button Themes" FontSize="20" FontAttributes="Bold" />
            
            <bmc:BuyMeACoffeeButton 
                Username="yourname"
                Theme="Yellow"
                HorizontalOptions="Center" />
            
            <bmc:BuyMeACoffeeButton 
                Username="yourname"
                Theme="Violet"
                ButtonText="Support My Work"
                HorizontalOptions="Center" />
            
            <!-- QR Code -->
            <Label Text="QR Code" FontSize="20" FontAttributes="Bold" Margin="0,20,0,0" />
            
            <bmc:BuyMeACoffeeQrCode 
                Username="yourname"
                Size="250"
                HorizontalOptions="Center" />
            
            <!-- Widget -->
            <Label Text="Support Widget" FontSize="20" FontAttributes="Bold" Margin="0,20,0,0" />
            
            <bmc:BuyMeACoffeeWidget 
                Username="yourname"
                DisplayName="John Doe"
                DefaultAmount="10"
                SuggestedAmounts="10,25,50"
                SupportRequested="OnSupportRequested"
                HorizontalOptions="Center" />
            
        </VerticalStackLayout>
    </ScrollView>
    
</ContentPage>
```

### Dynamic Theme Switching

```csharp
using BuyMeCofee.Maui.Controls;
using BuyMeCofee.Maui.Enums;

public partial class ThemePage : ContentPage
{
    private BuyMeACoffeeButton _button;
    private readonly BmcButtonTheme[] _themes = 
    {
        BmcButtonTheme.Yellow,
        BmcButtonTheme.Black,
        BmcButtonTheme.Blue,
        BmcButtonTheme.Violet,
        BmcButtonTheme.Orange,
        BmcButtonTheme.Red,
        BmcButtonTheme.Green
    };
    private int _currentThemeIndex = 0;
    
    public ThemePage()
    {
        InitializeComponent();
        
        _button = new BuyMeACoffeeButton
        {
            Username = "yourname",
            Theme = _themes[0]
        };
        
        var switchButton = new Button { Text = "Change Theme" };
        switchButton.Clicked += OnSwitchTheme;
        
        var layout = new VerticalStackLayout
        {
            Spacing = 20,
            Padding = 20,
            Children = { _button, switchButton }
        };
        
        Content = layout;
    }
    
    private void OnSwitchTheme(object sender, EventArgs e)
    {
        _currentThemeIndex = (_currentThemeIndex + 1) % _themes.Length;
        _button.Theme = _themes[_currentThemeIndex];
    }
}
```

### Analytics Integration

```csharp
using BuyMeCofee.Maui.Controls;
using BuyMeCofee.Maui.Models;

public partial class AnalyticsPage : ContentPage
{
    public AnalyticsPage()
    {
        InitializeComponent();
        
        var widget = new BuyMeACoffeeWidget
        {
            Username = "yourname",
            DisplayName = "John Doe"
        };
        
        widget.SupportRequested += OnSupportRequested;
        
        Content = widget;
    }
    
    private void OnSupportRequested(object sender, SupportRequestedEventArgs e)
    {
        // Log to analytics service
        AnalyticsService.TrackEvent("SupportRequested", new Dictionary<string, string>
        {
            { "username", e.Username },
            { "amount", e.Amount.ToString() },
            { "is_monthly", e.IsMonthly.ToString() },
            { "has_name", (!string.IsNullOrEmpty(e.Name)).ToString() },
            { "has_message", (!string.IsNullOrEmpty(e.Message)).ToString() }
        });
        
        // Show confirmation
        DisplayAlert("Thank You!", 
            $"You're about to support with ${e.Amount}. Redirecting to Buy Me a Coffee...", 
            "OK");
    }
}
```

## Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

### Development Setup

1. Clone the repository
2. Open in Visual Studio 2022 or VS Code
3. Ensure .NET MAUI workload is installed
4. Build and run the sample project

## License

This project is licensed under the MIT License. See the LICENSE file for details.

---

**Not affiliated with Buy Me a Coffee.** This is an unofficial community library. Buy Me a Coffee and its branding are trademarks of Buy Me a Coffee LLC.