@chainpay/component/README.md

A React-based payment component library that supports multiple payment channels and internationalization.

# ChainPay Component

A React-based payment component library that supports multiple payment channels and internationalization.

## Features

- 🚀 Support for React 18 and React 19
- 🌍 Multi-language support (Chinese, English, Japanese, Korean, and 8 languages in total)
- 🎨 Support for dark/light themes
- 📱 Responsive design
- ⚡ TypeScript support
- 🔄 Automatic polling of payment status
- 💫 Elegant loading and error handling

## Installation

```bash
npm install @chainpay/component
# or
yarn add @chainpay/component
# or
pnpm add @chainpay/component
```

## Dependencies

Ensure your project has the following dependencies installed:

```bash
npm install react react-dom antd i18next react-i18next tailwindcss
```

## Quick Start

### 1. Import Component and Styles

```tsx
import { useChainPay, ChainPayLng } from "@chainpay/component";
import "@chainpay/component/dist/style.css";
```

### 2. Basic Usage

```tsx
import React from 'react';
import { useChainPay, ChainPayLng } from "@chainpay/component";
import "@chainpay/component/dist/style.css";

function PaymentExample() {

  const { showPayModal } = useChainPay({
    // dark: true,
    language: "en",
    currency: '¥',
    appId: "app-77cccd53-b091-4dee-98f9-a44d641ac128",
    getSignInfoFn: async (params) => {
      return await getSign(params)  // Return signature information
    },
    onError(error) {
      console.log("error", error);
    },
    onSuccess() {
      console.log("success");
    },
    onClose() {
      console.log("close");
    },
    onCountDownTimeout() {
      console.log("countDownTimeout");
    }
  });

  return (
    <div>
      <button onClick={() => {
        showPayModal({
          amount: 100,
        })
      }}>
        Initiate Payment
      </button>
    </div>
  );
}

export default PaymentExample;
```

## API Documentation

### useChainPay(options)

Returns an object containing the `showPayModal` and `closePayModal` methods.

#### Parameters (ChainPayProps)

| Parameter | Type | Default | Required | Description |
|------|------|--------|------|------|
| `appId` | `string` | - | ✅ | Application ID |
| `amount` | `number` | - | ❌ | Payment amount |
| `currency` | `string` | - | ❌ | Currency symbol |
| `language` | `LngType` | `'zh-CN'` | ❌ | Interface language |
| `dark` | `boolean` | `false` | ❌ | Enable dark theme |
| `getSignInfoFn` | `function` | - | ❌ | Function to get signature information |
| `onSuccess` | `function` | - | ❌ | Payment success callback |
| `onError` | `function` | - | ❌ | Payment error callback |
| `onClose` | `function` | - | ❌ | Modal close callback |
| `onBack` | `function` | - | ❌ | Back button callback |
| `onCountDownTimeout` | `function` | - | ❌ | Countdown timeout callback |

#### Supported Languages

```typescript
enum ChainPayLng {
  "en" = "en",        // English
  "zh-CN" = "zh-CN",  // Simplified Chinese
  "zh-TW" = "zh-TW",  // Traditional Chinese
  "ko" = "ko",        // Korean
  "ja" = "ja",        // Japanese
  "ms" = "ms",        // Malay
  "vi" = "vi",        // Vietnamese
  "th" = "th"         // Thai
}
```

#### Function Signatures

```typescript
// Function to get order information
getSignInfoFn?: (data: object) => Promise<any>;
```

### showPayModal(props)

Displays the payment modal. Parameters are the same as `useChainPay`, but parameters in `showPayModal` have higher priority.

### closePayModal()

Manually closes the payment modal.

## Advanced Usage

### Custom Theme

```tsx
const { showPayModal } = useChainPay({
  dark: true, // Enable dark theme
  // Other configurations...
});
```

### Dynamic Language Switching

```tsx
const { showPayModal } = useChainPay({
  language: ChainPayLng['zh-CN'], // Use Chinese
  // Other configurations...
});

// Switch language when displaying the modal
showPayModal({
  language: ChainPayLng.en, // Switch to English
  amount: 100
});
```

### Error Handling

```tsx
const { showPayModal } = useChainPay({
  onError: (error) => {
    // Handle payment errors
    console.error('Payment failed:', error);
    // Can display error message to the user
  }
});
```

## Important Notes

⚠️ **React 19 Compatibility**: If you encounter `ReactCurrentDispatcher` errors in React 19 projects, please refer to the [React 19 Compatibility Guide](./REACT19_COMPATIBILITY.md).

### Quick Solutions for React 19 Errors

If you encounter the error `TypeError: Cannot read properties of undefined (reading 'ReactCurrentDispatcher')`:

1. **Temporary Solution**: Install a compatible version in your project
   ```bash
   npm install @chainpay/component@latest
   # If problems persist, clear cache
   rm -rf node_modules package-lock.json
   npm install
   ```

2. **Ensure JSX Transform is Configured Correctly** (Vite projects):
   ```javascript
   // vite.config.js
   import { defineConfig } from 'vite'
   import react from '@vitejs/plugin-react'
   
   export default defineConfig({
     plugins: [react()]
   })
   ```

3. **Additional Configuration for Next.js Projects**:
   ```javascript
   // next.config.js
   module.exports = {
     transpilePackages: ['@chainpay/component']
   }
   ```

## React 19 Compatibility

This component library fully supports React 19. If you encounter `ReactCurrentDispatcher` related errors during use, please refer to the [React 19 Compatibility Guide](./REACT19_COMPATIBILITY.md).

## Notes

1. **Must Import Style File**: Ensure you import the CSS file before using the component
2. **peerDependencies**: Make sure all required dependencies are installed
3. **API Functions**: `getSignInfoFn` should return a Promise
4. **Error Handling**: It is recommended to implement complete error handling logic in production environments

## License

MIT License

## Support

If you encounter any issues or have feature suggestions, please submit an issue on GitHub.