synora-react-payment-modal-library/README.md

A comprehensive, production-ready React payment modal component library with multi-currency support, dark/light themes, and multiple payment methods.

# React Payment Modal Library

A comprehensive, production-ready React payment modal component library with multi-currency support, dark/light themes, and multiple payment methods.

## Features

- 🎨 **Beautiful UI**: Modern, professional design with dark/light theme support
- 💳 **Multiple Payment Methods**: Cash, ATM/Card, Bank Transfer, and Cheque payments
- 🌍 **Multi-Currency Support**: Support for USD, EUR, GBP, LKR, INR, JPY, AUD, CAD
- 🎁 **Gift Vouchers & Loyalty Points**: Built-in support for deductions
- ✅ **Form Validation**: Comprehensive validation with clear error messages
- 📱 **Responsive Design**: Works perfectly on all device sizes
- 🔧 **TypeScript**: Full TypeScript support with type definitions
- 🎯 **Production Ready**: Thoroughly tested and optimized

## Installation

```bash
npm install react-payment-modal-library
```

## Peer Dependencies

Make sure you have these installed in your project:

```bash
npm install react react-dom antd lucide-react
```

## Basic Usage

```tsx
import React, { useState } from 'react';
import { PaymentModal, PaymentDetails, Theme } from 'react-payment-modal-library';
import 'antd/dist/reset.css'; // Import Ant Design styles

function App() {
  const [modalVisible, setModalVisible] = useState(false);
  const banks = ["BOC", "NTB", "Commercial Bank", "HNB", "Sampath Bank"];

  const handlePaymentComplete = async (paymentDetails: PaymentDetails) => {
    console.log('Payment Details:', paymentDetails);
    // Process payment details here
    setModalVisible(false);
  };

  return (
    <div>
      <button onClick={() => setModalVisible(true)}>
        Open Payment Modal
      </button>

      <PaymentModal
        banks={banks}
        onPaymentComplete={handlePaymentComplete}
        visible={modalVisible}
        onCancel={() => setModalVisible(false)}
        title="Payment Details"
        theme={Theme.LIGHT}
        amountToPay={2000}
        currency="USD"
      />
    </div>
  );
}

export default App;
```

## Props

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `banks` | `string[]` | ✅ | - | Array of bank names for selection |
| `onPaymentComplete` | `(details: PaymentDetails) => void` | ✅ | - | Callback when payment is completed |
| `visible` | `boolean` | ❌ | `false` | Controls modal visibility |
| `onCancel` | `() => void` | ❌ | - | Callback when modal is cancelled |
| `title` | `string` | ❌ | `"Payment Details"` | Modal title |
| `theme` | `Theme` | ❌ | `Theme.LIGHT` | Theme (LIGHT or DARK) |
| `amountToPay` | `number` | ❌ | - | Pre-filled amount (disables amount input) |
| `currency` | `string` | ❌ | `"USD"` | Currency code (USD, EUR, GBP, etc.) |

## Payment Types

### Cash Payment
- Total Amount
- Gift Voucher Amount
- Loyalty Points Amount
- Amount Tendered
- Change Amount (calculated automatically)

### ATM/Card Payment
- Total Amount
- Gift Voucher Amount
- Loyalty Points Amount
- Card Type (Visa, Mastercard, Amex, Discover)
- Last 4 Digits
- Card Holder Name
- Issuing Bank

### Bank Transfer
- Total Amount
- Gift Voucher Amount
- Loyalty Points Amount
- Account Holder Name
- Account Number
- Bank

### Cheque Payment
- Total Amount
- Account Type
- Cheque Number
- Bank
- Reference Number
- Remarks

## Supported Currencies

- USD (US Dollar)
- EUR (Euro)
- GBP (British Pound)
- LKR (Sri Lankan Rupee)
- INR (Indian Rupee)
- JPY (Japanese Yen)
- AUD (Australian Dollar)
- CAD (Canadian Dollar)

## Themes

```tsx
import { Theme } from 'react-payment-modal-library';

// Light theme
<PaymentModal theme={Theme.LIGHT} />

// Dark theme
<PaymentModal theme={Theme.DARK} />
```

## Advanced Usage

### With Custom Styling

```tsx
import { PaymentModal } from 'react-payment-modal-library';

<PaymentModal
  banks={banks}
  onPaymentComplete={handlePaymentComplete}
  visible={modalVisible}
  onCancel={() => setModalVisible(false)}
  title="Custom Payment Form"
  theme={Theme.DARK}
  amountToPay={1500.50}
  currency="EUR"
/>
```

### Handling Payment Results

```tsx
const handlePaymentComplete = async (paymentDetails: PaymentDetails) => {
  const { paymentType, paymentData } = paymentDetails;
  
  switch (paymentType) {
    case PaymentType.CASH:
      const cashData = paymentData as CashPaymentData;
      console.log('Cash payment:', cashData.amountTendered);
      break;
      
    case PaymentType.ATM:
      const atmData = paymentData as ATMPaymentData;
      console.log('Card payment:', atmData.last_4_digit);
      break;
      
    // Handle other payment types...
  }
  
  // Send to your backend
  await fetch('/api/payments', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(paymentDetails)
  });
};
```

## TypeScript Support

The library is built with TypeScript and provides comprehensive type definitions:

```tsx
import {
  PaymentModal,
  PaymentDetails,
  PaymentType,
  CashPaymentData,
  ATMPaymentData,
  Theme
} from 'react-payment-modal-library';
```

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.