npm package: @kdesigner/components
Description: KDesigner Universal Component Library with React and Vue support
Author: KDesigner Team
Latest version: 0.0.0-alpha.3

# @kdesigner/components

基于 AMIS UI 6.11 的现代化组件库，采用组件和 renderer 分层架构设计。

## 特性

- 🎨 **基于 AMIS UI 6.11** - 充分利用 AMIS 的设计系统和功能基础
- 🏗️ **分层架构** - 组件层与 renderer 层解耦，提高灵活性
- 📦 **TypeScript 支持** - 完整的类型定义和类型安全
- 🧪 **完整测试覆盖** - 单元测试、集成测试、端到端测试
- 🔧 **现代化构建** - Vite + TypeScript + ESM/CommonJS 双格式输出
- ♿ **可访问性支持** - 符合 WCAG 标准，支持键盘导航和屏幕阅读器
- 🌍 **国际化支持** - 内置多语言支持机制

## 安装

### 基础安装

```bash
# 使用 pnpm（推荐）
pnpm add @kdesigner/components

# 使用 npm
npm install @kdesigner/components

# 使用 yarn
yarn add @kdesigner/components
```

### 必需依赖 (Peer Dependencies)

本组件库基于 AMIS UI 构建，需要安装以下必需依赖：

```bash
# 安装必需的 peer dependencies
pnpm add amis-ui@^6.11.0 react@^18.2.0 react-dom@^18.2.0

# 或使用 npm
npm install amis-ui@^6.11.0 react@^18.2.0 react-dom@^18.2.0

# 或使用 yarn
yarn add amis-ui@^6.11.0 react@^18.2.0 react-dom@^18.2.0
```

**重要说明：**

- `amis-ui` 是必需依赖，组件库基于此构建
- `react` 和 `react-dom` 版本需要保持一致
- 如果缺少这些依赖，安装后会自动提示安装指导

### 依赖检查

安装后会自动检查 peer dependencies，如有缺失会提供安装指导。

## 📚 文档

- [完整文档](./docs/README.md) - 查看所有文档
- [Scripts 使用指南](./docs/SCRIPTS.md) - npm scripts 使用说明
- [自动化导出系统](./docs/AUTO_EXPORTS.md) - 自动化导出系统使用指南
- [Tree Shaking 指南](./docs/TREE_SHAKING.md) - 按需引入和 Tree Shaking 配置

安装完成后，可以运行以下命令检查依赖是否正确安装：

```bash
# 检查 peer dependencies
pnpm run check-peer-deps

# 或在项目中使用
npx @kdesigner/components check-peer-deps
```

## 快速开始

```tsx
import React from 'react'
import { Upload } from '@kdesigner/components'
import '@kdesigner/components/dist/style.css'

function App() {
  const handleChange = info => {
    console.log('文件上传状态变化:', info)
  }

  return (
    <div>
      <Upload
        action='/api/upload'
        onChange={handleChange}
        accept='image/*'
        maxCount={5}
      >
        <button>点击上传</button>
      </Upload>
    </div>
  )
}

export default App
```

## 组件列表

### 当前可用组件

- **Upload** - 文件上传组件（开发中）
  - 支持多种上传方式（拖拽、点击选择、粘贴）
  - 文件类型和大小限制
  - 上传进度显示和错误处理
  - 自定义上传逻辑支持

### 计划中的组件

- **Button** - 按钮组件
- **Input** - 输入框组件
- **Select** - 选择器组件
- **Form** - 表单组件
- **Modal** - 模态框组件
- **Table** - 表格组件

## 架构设计

### 分层架构

```
┌─────────────────────────────────────┐
│           Renderer 层               │
│        (其他包中实现)                │
├─────────────────────────────────────┤
│           组件层 (本包)              │
│     纯组件实现，不包含 renderer      │
├─────────────────────────────────────┤
│           AMIS 基础层               │
│      基于 AMIS UI 6.11 构建         │
└─────────────────────────────────────┘
```

### 目录结构

```
src/
├── components/          # 组件目录
│   ├── Upload/          # Upload 组件
│   └── index.ts         # 组件统一导出
├── hooks/               # 全局自定义 hooks
├── utils/               # 全局工具函数
├── types/               # 全局类型定义
├── styles/              # 全局样式
│   ├── variables.scss   # SCSS 变量
│   ├── mixins.scss      # SCSS 混入
│   └── index.scss       # 样式入口
├── core/                # 核心功能
└── index.ts             # 库入口文件
```

## 开发

### 环境要求

- Node.js >= 18.0.0
- pnpm >= 8.15.0
- TypeScript >= 5.3.0

### 开发命令

```bash
# 安装依赖
pnpm install

# 开发模式（监听文件变化）
pnpm dev

# 构建
pnpm build

# 运行测试
pnpm test

# 运行测试（监听模式）
pnpm test:watch

# 测试覆盖率
pnpm test:coverage

# 代码检查
pnpm lint

# 代码检查并修复
pnpm lint:fix

# 代码格式化
pnpm format

# 检查代码格式
pnpm format:check

# 类型检查
pnpm type-check

# 质量检查（包含 lint + type-check + test）
pnpm quality-check

# 验证构建产物
pnpm verify:build

# 验证导出配置
pnpm verify:exports

# 验证类型定义
pnpm verify:types

# 检查构建完整性
pnpm check:integrity

# 检查 peer dependencies
pnpm check:peer-deps
```

### 测试

组件库使用 Vitest 作为测试框架，配合 @testing-library/react 进行组件测试。

```bash
# 运行所有测试
pnpm test

# 运行特定测试文件
pnpm test Upload.test.tsx

# 生成测试覆盖率报告
pnpm test:coverage
```

测试覆盖率要求：

- 整体覆盖率：≥ 90%
- 语句覆盖率：≥ 90%
- 分支覆盖率：≥ 85%
- 函数覆盖率：≥ 90%

## 构建产物

构建后将生成以下文件：

```
dist/
├── index.esm.js          # ES 模块版本
├── index.esm.js.map      # ES 模块 source map
├── index.cjs.js          # CommonJS 版本
├── index.cjs.js.map      # CommonJS source map
├── index.d.ts            # TypeScript 类型定义
├── style.css             # 样式文件
└── style.css.map         # 样式 source map
```

## 代码质量

### ESLint 配置

使用 `@kdesigner/eslint-config` (auto 包) 进行智能代码检查：

```javascript
// eslint.config.js
import autoConfig from '@kdesigner/eslint-config'

export default [
  ...autoConfig
  // 项目特定规则
]
```

### TypeScript 配置

启用严格模式，确保类型安全：

```json
{
  "compilerOptions": {
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  }
}
```

## 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 开启 Pull Request

### 开发规范

- 所有新功能必须包含测试
- 遵循 TypeScript 严格模式
- 使用语义化提交消息
- 确保代码通过 ESLint 检查
- 更新相关文档

## 许可证

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

## 更新日志

详见 [CHANGELOG.md](./CHANGELOG.md)。

## 支持

- 📖 [文档](https://kdesigner.dev/components)
- 🐛 [问题反馈](https://github.com/kdesigner/kdesigner/issues)
- 💬 [讨论区](https://github.com/kdesigner/kdesigner/discussions)
- 📧 [邮件支持](mailto:support@kdesigner.dev)