dirham_symbol 0.5.1

The complete UAE Dirham (AED) currency toolkit for Flutter. Features official font symbol glyph, e-commerce sale prices, animated counters, currency text fields, and extensions.

UAE Dirham Symbol & Currency Suite for Flutter 🇦🇪

The all-in-one UAE Dirham (AED) currency toolkit for Flutter. Designed for modern E-Commerce, FinTech, and Banking apps across Dubai, Abu Dhabi, and the GCC.

Includes the official UAE Dirham font symbol glyph, live currency input formatters, strikethrough sale pricing, animated price counters, pure string formatters, Fils subunit math, and global theme support.

---

✨ Features

• 💎 Official UAE Symbols: Native Font Glyph (DirhamIcon) + Arabic (د.إ) + Latin (AED, Dh).
• ⚡ Expressive Extensions: .toDirham(), .toDirhamString(), .toDirhamCompact(), .toDirhamSale(), .toDirhamBadge(), .toDirhamAnimated().
• 💳 FinTech Input Formatter: Real-time thousands masking (1,250.00) with DirhamInputFormatter & ready-to-use DirhamTextField.
• 🏷️ E-Commerce Sale Pricing: Slashed original prices + discounted prices + auto-calculated discount badges (Save 25%).
• 📊 Animated Balance & Price Counter: Smooth ticker animation for carts, balances, and checkout totals.
• 🪙 Subunit (Fils) Math: Seamless conversions (10.50 AED ↔ 1050 Fils) for Stripe, Checkout.com, and payment gateways.
• 🔤 Pure String Formatting: Return strings without widgets (DirhamFormatter.format(...)) for APIs, notifications, & PDFs.
• 🎨 App-Wide Theme: Configure default symbol type, locale, and decimals with DirhamTheme.
• 🌐 Eastern Arabic Numerals: Full support for Arabic-Indic numerals (١٢٣٤٥٦٧٨٩٠).
• 🛡️ 100% Backward Compatible: Drop-in upgrade with zero breaking changes.

---

📦 Installation

Add dirham_symbol to your pubspec.yaml:

dependencies:
  dirham_symbol: ^0.5.0

Import in your Dart code:

import 'package:dirham_symbol/dirham_symbol.dart';

---

🚀 Quick Start

1. Extension Methods (Fastest)

// Basic price widgets
99.99.toDirham()                                  // Official icon + 99.99
250.toDirham(symbolType: DirhamSymbolType.arabic)  // 250 د.إ
"1500".toDirham(showDecimals: true)               // 1,500.00 AED

// Inline text with prefix/suffix
149.99.toDirhamText(prefix: 'Starting from', suffix: 'only!')

// Price ranges
50.toDirhamRange(150, symbolType: DirhamSymbolType.arabic) // د.إ 50 - د.إ 150

---

2. Pure String Formatting (No Widgets)

Generate formatted strings for API requests, push notifications, native bridges, or PDF receipts:

// Standard formatted string
1500.toDirhamString()                             // "AED 1,500"
1500.50.toDirhamString(symbolType: DirhamSymbolType.arabic, showDecimals: true) // "1,500.50 د.إ"

// Compact format for large numbers
1500.toDirhamCompact()                            // "AED 1.5K"
2500000.toDirhamCompact(symbolType: DirhamSymbolType.arabic) // "2.5M د.إ"

// Parse numeric values from dirty strings
"AED 1,250.50".cleanDirhamAmount()                // 1250.50

---

3. E-Commerce Sale Prices & Badges 🛍️

Showcase discounts with original strikethrough price, sale price, and automatic percentage/savings badges:

// Auto-calculates -25% discount badge
200.toDirhamSale(150)

// Detailed customization
DirhamSalePrice(
  originalAmount: 500,
  saleAmount: 350,
  badgeType: DirhamDiscountBadgeType.percentage, // or .saveAmount
  symbolType: DirhamSymbolType.arabic,
  axis: Axis.horizontal,                         // or Axis.vertical
)

// Promotional badges and chips
DirhamBadge(
  amount: 100,
  prefix: 'Free delivery over',
  backgroundColor: Colors.green.shade50,
  textColor: Colors.green.shade900,
)

---

4. FinTech Currency Input & Form Field 💳

A plug-and-play Material 3 currency input with live comma separation, decimal locking, and currency prefix/suffix:

// Ready-to-use Form Field
DirhamTextField(
  initialAmount: 250.0,
  showClearButton: true,
  decoration: InputDecoration(
    labelText: 'Transfer Amount',
    border: OutlineInputBorder(),
  ),
  onAmountChanged: (double? amount) {
    print('Entered AED: $amount');
  },
  onFilsChanged: (int? fils) {
    print('Amount in Fils: $fils'); // e.g. 25000
  },
)

// Or use the formatter with your own TextField
TextField(
  keyboardType: TextInputType.numberWithOptions(decimal: true),
  inputFormatters: [
    DirhamInputFormatter(decimalDigits: 2, maxAmount: 100000),
  ],
)

---

5. Animated Balance & Price Ticker ⚡

Smoothly animate balance updates, shopping cart additions, and price changes:

AnimatedDirhamPrice(
  amount: _cartTotal,
  duration: Duration(milliseconds: 600),
  curve: Curves.easeOutCubic,
  showDecimals: true,
  style: TextStyle(fontSize: 24, fontWeight: FontWeight.bold),
)

---

6. Subunit (Fils) Math 🪙

Seamlessly handle Fils for payment integrations (1 AED = 100 Fils):

// Convert AED to Fils
10.50.toFils()              // 1050

// Convert Fils to AED
5000.filsToDirham()         // 50.0
5000.filsToDirhamString()   // "AED 50.00"
5000.filsToDirhamWidget()   // DirhamPrice Widget

---

7. App-Wide Global Theme 🎨

Set your default symbol type, locale, and decimal preferences once at the root:

DirhamTheme(
  data: DirhamThemeData(
    symbolType: DirhamSymbolType.arabic, // Defaults all widgets to 'د.إ'
    showDecimals: true,
    spacing: 6.0,
  ),
  child: MyApp(),
)

---

🔣 Symbol Types

Type	Output	Use Case
DirhamSymbolType.icon	🇦🇪 Official Font Glyph	Modern UAE apps (Official brand glyph)
DirhamSymbolType.arabic	د.إ	Arabic & RTL interfaces
DirhamSymbolType.aed	AED	Standard international apps & banking
DirhamSymbolType.dh	Dh	Compact abbreviations

---

🔠 Native Font Glyph & Text Integration

Render the official Dirham symbol using the high-performance bundled font directly as a widget or text style:

// Native Widget
DirhamIcon(
  size: 32,
  color: Color(0xFF007A3D),
  fontWeight: FontWeight.bold,
)

// Or as a raw TextStyle
Text(
  kDirhamGlyph,
  style: TextStyle(
    fontFamily: kDirhamFontFamily,
    package: kDirhamPackage,
    fontSize: 24,
  ),
)

---

📱 Screenshots

🌟 Dirham Icon & Symbols (Light)	🛍️ E-Commerce Sale Prices (Dark)	💳 FinTech & Forms

---

🛡️ Backward Compatibility

Upgrading from 0.3.x or 0.2.x is 100% safe. All existing widget declarations, parameters, and extension signatures continue to work identically without any breaking changes.

---

📄 License

MIT License - see LICENSE for details.

Developed with ❤️ for the Flutter & UAE Developer Community.