@edgex-web/components/README.md

EdgeX Universal UI Components Library - Reusable React components for deposit, withdraw and other common UI patterns

# @edgex-web/components

> ⚠️ **Beta 版本警告**: 这是一个 Beta 版本，功能还在完善中，仅用于测试和开发环境。

EdgeX Universal UI Components Library - Reusable React components for deposit, withdraw and other common UI patterns

## 🎯 项目概述

基于 RFC FE-01 设计，EdgeX Components 是一个独立的 npm 包，旨在解决 EdgeX 项目中 deposit/withdraw 组件 70% 代码重复的问题。采用事件驱动架构，支持全局调用能力。

## ✨ 特性

- 🚀 **现代化技术栈**: TypeScript + React + Vite
- 📦 **独立 npm 包**: 可在任何 React 项目中使用
- 🎪 **事件驱动**: 支持全局调用 `openDeposit()` / `openWithdraw()`
- 🔗 **MPC 钱包支持**: 链-代币关联，智能代币切换
- 🎨 **主题配置**: 支持 light/dark 主题切换
- 🌍 **国际化**: 多语言支持
- 🧪 **高测试覆盖**: 目标 85%+ 测试覆盖率
- 📚 **完整文档**: API 文档和使用指南

## 📦 安装

### Beta 版本 (推荐用于测试)

```bash
# 使用 npm
npm install @edgex-web/components@beta

# 使用 yarn
yarn add @edgex-web/components@beta

# 使用 pnpm
pnpm add @edgex-web/components@beta
```

### 稳定版本 (暂未发布)

```bash
# 使用 npm
npm install @edgex-web/components

# 使用 yarn
yarn add @edgex-web/components

# 使用 pnpm
pnpm add @edgex-web/components
```

## 🏗️ 技术架构

```
edgex-components/
├── src/
│   ├── components/          # React 组件
│   │   ├── Provider/        # 全局配置提供者
│   │   ├── Deposit/         # 充值组件
│   │   └── Withdraw/        # 提现组件
│   ├── hooks/               # React Hooks
│   ├── types/               # TypeScript 类型定义
│   └── test/                # 测试配置
├── dev/                     # 开发环境
└── dist/                    # 构建输出
```

## 🚀 快速开始

### 安装依赖

```bash
# 使用 yarn (推荐)
yarn install

# 或使用 npm
npm install
```

### 开发模式

```bash
# 启动开发服务器
yarn dev

# 访问 http://localhost:5173 查看组件演示
```

### 构建

```bash
# 构建生产版本
yarn build

# 类型检查
yarn type-check

# 运行测试
yarn test

# 测试覆盖率
yarn test:coverage

# 代码检查
yarn lint

# 代码格式化
yarn format
```

## 📖 使用方法

### 基本用法

```tsx
import React from 'react'
import { ComponentProvider, useDeposit, useWithdraw } from '@edgex-web/components'

// 1. 在应用根组件配置 Provider
const App = () => {
  const config = {
    theme: 'light',
    locale: 'en',
    apiBaseUrl: 'https://api.edgex.com',
    debug: true
  }

  return (
    <ComponentProvider config={config}>
      <YourApp />
    </ComponentProvider>
  )
}

// 2. 在任意组件中使用
const TradeComponent = () => {
  const { openDeposit } = useDeposit()
  const { openWithdraw } = useWithdraw()

  const handleDeposit = () => {
    openDeposit({
      type: 'trade',
      symbol: 'USDT',
      onSuccess: (result) => console.log('Success:', result),
      onError: (error) => console.error('Error:', error),
      onCancel: () => console.log('Cancelled')
    })
  }

  return <button onClick={handleDeposit}>充值</button>
}
```

### 事件驱动 API (推荐)

```tsx
import React from 'react'
import {
  DepositManager,
  openDeposit,
  closeDeposit,
  MPCChainTokenSelector
} from '@edgex-web/components'

// 1. 在应用根组件添加 DepositManager
function App() {
  return (
    <div>
      <YourAppContent />
      <DepositManager />
    </div>
  )
}

// 2. 在任意位置调用
function MyComponent() {
  const handleDeposit = () => {
    openDeposit({
      curSelectToken: 'USDT',
      depositAmount: '100',
      onDeposit: async () => {
        console.log('Deposit initiated!')
      }
    })
  }

  return <button onClick={handleDeposit}>Open Deposit</button>
}
```

### MPC 钱包链-代币关联

```tsx
import React, { useState } from 'react'
import { MPCChainTokenSelector, type ChainWithTokens } from '@edgex-web/components'

// 定义链-代币关联数据
const mpcChainList: ChainWithTokens[] = [
  {
    chainId: 1,
    chain: 'Ethereum',
    chainIconUrl: 'https://static.edgex.exchange/icons/logo/ethereum.svg',
    allowDeposit: true,
    blockTime: 12,
    txConfirm: 12,
    tokenList: [
      {
        token: 'USDT',
        symbol: 'USDT',
        iconUrl: 'https://static.edgex.exchange/icons/coin/USDT.svg',
        decimals: 6,
        tokenAddress: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
      },
    ],
  },
  {
    chainId: 42161,
    chain: 'Arbitrum',
    chainIconUrl: 'https://static.edgex.exchange/icons/logo/arbitrum.svg',
    allowDeposit: true,
    blockTime: 1,
    txConfirm: 1,
    tokenList: [
      {
        token: 'USDT',
        symbol: 'USDT',
        iconUrl: 'https://static.edgex.exchange/icons/coin/USDT.svg',
        decimals: 6,
        tokenAddress: '0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9',
      },
      {
        token: 'USDC',
        symbol: 'USDC',
        iconUrl: 'https://static.edgex.exchange/icons/coin/USDC.svg',
        decimals: 6,
        tokenAddress: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
      },
    ],
  },
]

function MPCWalletComponent() {
  const [currentChainId, setCurrentChainId] = useState(1)
  const [currentToken, setCurrentToken] = useState('USDT')

  const currentActiveChain = mpcChainList.find(
    chain => chain.chainId === currentChainId
  ) || mpcChainList[0]

  return (
    <MPCChainTokenSelector
      currentActiveChain={currentActiveChain}
      chainList={mpcChainList}
      onChainChange={setCurrentChainId}
      curSelectToken={currentToken}
      onTokenChange={setCurrentToken}
      t={(key) => key} // 翻译函数
    />
  )
}
```

## 🛠️ 开发工具链

### 已配置的工具

- **构建工具**: Vite 5.x + Rollup
- **类型系统**: TypeScript 5.x
- **测试框架**: Vitest + Testing Library
- **代码质量**: ESLint + Prettier
- **Git Hooks**: Husky + lint-staged
- **包管理**: 支持 npm/yarn/pnpm

### 脚本命令

| 命令 | 描述 |
|------|------|
| `yarn dev` | 启动开发服务器 |
| `yarn build` | 构建生产版本 |
| `yarn test` | 运行测试 |
| `yarn test:coverage` | 生成测试覆盖率报告 |
| `yarn lint` | 代码检查 |
| `yarn format` | 代码格式化 |
| `yarn type-check` | TypeScript 类型检查 |

## 📋 开发状态

### ✅ 已完成

- [x] 项目基础架构搭建
- [x] TypeScript 配置
- [x] 构建工具配置 (Vite + Rollup)
- [x] 测试框架配置 (Vitest + Testing Library)
- [x] 代码质量工具 (ESLint + Prettier + Husky)
- [x] 基础组件结构
- [x] 开发环境设置
- [x] 核心组件开发 (Deposit/Withdraw)
- [x] 事件驱动系统实现
- [x] MPC 钱包链-代币关联功能
- [x] 智能代币切换逻辑
- [x] 完整测试覆盖
- [x] npm 包发布配置

### 🚧 进行中

- [ ] API 文档完善
- [ ] 集成指南编写
- [ ] 性能优化

### 📅 计划中

- [ ] Storybook 集成
- [ ] 更多钱包类型支持
- [ ] 主题系统增强
- [ ] 国际化完善

## 🎯 RFC FE-01 目标

- **减少代码重复**: 从 70% 降至 <10%
- **提升测试覆盖**: 达到 85%+
- **统一用户体验**: 一致的 UI 和交互
- **全局调用能力**: 支持任意位置唤起弹框
- **开发效率**: 降低维护成本 60-80%

## 📄 许可证

MIT License - 详见 [LICENSE](./LICENSE) 文件