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-v1.1.0-blue)](https://git.marketally.com/misc/bmc.maui/packages)

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)
- [Supporter Verification](#supporter-verification)
- [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** - Crisp SVG-based logos via MAUI asset pipeline, authentic Buy Me a Coffee colors and styling
- **Supporter Verification** - Auto-hide controls for users who have already supported you via the BMC API
- **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

### NuGet Package

Add the MarketAlly NuGet source to your `NuGet.config`:

```xml
<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="MarketAlly" value="https://git.marketally.com/api/packages/misc/nuget/index.json" />
  </packageSources>
</configuration>
```

Then add the package reference:

```xml
<PackageReference Include="BuyMeCofee.Maui" Version="1.1.0" />
```

Or via CLI:

```bash
dotnet add package BuyMeCofee.Maui --version 1.1.0
```

### Register in 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" />
```

#### 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 |
| `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 |
| `SupporterEmail` | `string?` | `null` | Email to check against supporters list |
| `HideIfSupporter` | `bool` | `false` | Auto-hide if email is a verified supporter |

### 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" />
```

#### 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) |
| `SupporterEmail` | `string?` | `null` | Email to check against supporters list |
| `HideIfSupporter` | `bool` | `false` | Auto-hide if email is a verified supporter |

### 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

```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}");
}
```

#### 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 |
| `SupporterEmail` | `string?` | `null` | Email to check against supporters list |
| `HideIfSupporter` | `bool` | `false` | Auto-hide if email is a verified supporter |

#### 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; }
    public int Amount { get; init; }
    public string? Name { get; init; }
    public string? Message { get; init; }
    public bool IsMonthly { get; init; }
}
```

## Supporter Verification

The library can automatically check if a user has already supported you via the Buy Me a Coffee API. When verified, controls can auto-hide themselves — useful for removing donation prompts for existing supporters.

### Setup

Get your API access token from [Buy Me a Coffee Developer Dashboard](https://developers.buymeacoffee.com/).

Configure the token in `MauiProgram.cs`:

```csharp
builder.UseBuyMeACoffee(options =>
{
    options.AccessToken = "your_bmc_api_token";
    options.CacheDuration = TimeSpan.FromHours(1); // default
});
```

### Usage

Add `SupporterEmail` and `HideIfSupporter` to any control:

```xml
<bmc:BuyMeACoffeeButton
    Username="yourname"
    Theme="Yellow"
    SupporterEmail="{Binding CurrentUserEmail}"
    HideIfSupporter="True" />
```

When `HideIfSupporter` is `true` and the email matches a one-time supporter or active member, the control sets `IsVisible = false`.

The service queries both `/api/v1/supporters` (one-time) and `/api/v1/subscriptions` (members) endpoints, caches results in memory, and fails silently if the API is unreachable.

## Theming

### Button Themes

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

```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
}
```

### Brand Colors Reference

```csharp
public static class BmcColors
{
    public const string CupYellow = "#FFDD00";
    public const string BrandDark = "#0D0C22";
    public const string WidgetPurple = "#6C5CE7";
    public const string WhiteStroke = "#E0E0E0";
}
```

## API Reference

### Extension Methods

```csharp
// Basic registration (no API features)
public static MauiAppBuilder UseBuyMeACoffee(this MauiAppBuilder builder);

// With API configuration (enables supporter verification)
public static MauiAppBuilder UseBuyMeACoffee(this MauiAppBuilder builder, Action<BmcOptions> configure);
```

### BmcOptions

```csharp
public class BmcOptions
{
    public string? AccessToken { get; set; }
    public TimeSpan CacheDuration { get; set; } = TimeSpan.FromHours(1);
}
```

### 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 |

## Dependencies

```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" />
```

## Support This Project

If this library saved you time, consider buying me a coffee:

[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/logikonline)

## Contributing

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

## 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.