# @snowui-design-system/resource-react 项目计划

## 项目概述

本项目旨在从 `@snowui-design-system/resource-base` 包中读取处理后的素材文件，自动生成 React 组件，提供给 React 项目使用。

## 目标

- ✅ 从 `core` 包读取处理后的素材文件
- ✅ 自动生成 React 组件（图标、头像、背景等）
- ✅ 支持 TypeScript 类型定义
- ✅ 支持 Tree-shaking
- ✅ 输出 ES Module 和 CommonJS 格式
- ✅ 支持多权重图标（regular、thin、light、bold、fill、duotone）

## 项目执行步骤

### 阶段 1：项目基础设置

#### 步骤 1.1：确认项目结构

**目标**：确保项目目录结构正确

**操作**：
```bash
cd resource-react
```

**目录结构应该是**：
```
resource-react/
├── src/
│   ├── icons/          # 图标组件（待生成）
│   ├── avatars/        # 头像组件（待生成）
│   ├── backgrounds/    # 背景组件（待生成）
│   └── vectors/        # 矢量图组件（待生成）
├── dist/               # 构建输出目录
├── package.json
└── tsconfig.json       # 需要创建
```

**验收标准**：
- [ ] 目录结构存在
- [ ] `package.json` 配置正确
- [ ] `src/` 目录下各子目录已创建

---

#### 步骤 1.2：创建 TypeScript 配置

**目标**：创建 `tsconfig.json` 配置文件

**操作**：
创建 `resource-react/tsconfig.json` 文件

**配置内容**：
```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM"],
    "jsx": "react",
    "declaration": true,
    "declarationMap": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": false
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

**验收标准**：
- [ ] `tsconfig.json` 文件已创建
- [ ] 配置项正确
- [ ] TypeScript 编译无错误

---

#### 步骤 1.3：创建 tsup 构建配置

**目标**：配置 tsup 打包工具

**操作**：
创建 `resource-react/tsup.config.ts` 文件

**配置内容**：
```typescript
import { defineConfig } from 'tsup';

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],
  dts: true,
  splitting: false,
  sourcemap: true,
  clean: true,
  external: ['react'],
});
```

**验收标准**：
- [ ] `tsup.config.ts` 文件已创建
- [ ] 配置支持 CJS 和 ESM 格式
- [ ] 支持类型定义生成

---

### 阶段 2：创建基础库文件

#### 步骤 2.1：创建图标基础组件

**目标**：创建通用的图标基础组件

**操作**：
创建 `resource-react/src/lib/IconBase.tsx`

**功能要求**：
- 支持 ref 转发
- 支持 size、color、weight 等 props
- 支持多权重切换
- 支持自定义 className

**验收标准**：
- [ ] `IconBase.tsx` 文件已创建
- [ ] 组件支持所有必需的 props
- [ ] TypeScript 类型定义完整

---

#### 步骤 2.2：创建类型定义文件

**目标**：创建类型定义文件

**操作**：
创建 `resource-react/src/lib/types.ts`

**需要定义的类型**：
- `IconWeight`：图标权重类型
- `IconProps`：图标组件 props 类型
- `AvatarProps`：头像组件 props 类型
- `BackgroundProps`：背景组件 props 类型

**验收标准**：
- [ ] `types.ts` 文件已创建
- [ ] 所有类型定义完整
- [ ] 类型导出正确

---

#### 步骤 2.3：创建工具函数

**目标**：创建辅助工具函数

**操作**：
创建 `resource-react/src/lib/utils.ts`

**功能要求**：
- 命名转换函数（kebab-case ↔ PascalCase）
- 权重验证函数
- 其他辅助函数

**验收标准**：
- [ ] `utils.ts` 文件已创建
- [ ] 工具函数实现正确
- [ ] 函数有完整的类型定义

---

### 阶段 3：创建生成脚本

#### 步骤 3.1：创建脚本目录结构

**目标**：在项目根目录创建生成脚本

**操作**：
在 `snowui/scripts/` 目录下创建生成脚本

**目录结构**：
```
snowui/
└── scripts/
    ├── generate-react.ts    # React 生成脚本（主入口）
    └── utils/
        ├── read-assets.ts   # 读取 core 包素材
        ├── svg-to-jsx.ts    # SVG 转 JSX
        └── generate-component.ts  # 生成组件代码
```

**验收标准**：
- [ ] 脚本目录结构已创建
- [ ] 所有脚本文件占位符已创建

---

#### 步骤 3.2：实现读取素材工具

**目标**：从 core 包读取处理后的素材文件

**操作**：
创建 `scripts/utils/read-assets.ts`

**功能要求**：
- 读取 `resource-base/assets/icons/<weight>/` 目录下的 SVG 文件
- 读取 `resource-base/assets/avatars/` 目录下的文件
- 读取 `resource-base/assets/backgrounds/` 目录下的文件
- 解析文件名，提取名称和权重信息
- 返回结构化的素材数据

**数据结构**：
```typescript
interface IconAsset {
  name: string;
  kebabName: string;
  pascalName: string;
  weights: Record<IconWeight, string>; // weight -> SVG content
}

interface MaterialAsset {
  name: string;
  kebabName: string;
  pascalName: string;
  files: Array<{
    format: string;
    path: string;
    content: Buffer | string;
  }>;
}
```

**验收标准**：
- [ ] `read-assets.ts` 文件已创建
- [ ] 能够正确读取所有素材文件
- [ ] 返回的数据结构正确
- [ ] 支持错误处理

---

#### 步骤 3.3：实现 SVG 转 JSX 工具

**目标**：将 SVG 内容转换为 React JSX

**操作**：
创建 `scripts/utils/svg-to-jsx.ts`

**功能要求**：
- 使用 `@svgr/core` 将 SVG 转换为 React 组件
- 处理 SVG 属性（如 `currentColor`）
- 优化 SVG 内容
- 生成 JSX 字符串

**验收标准**：
- [ ] `svg-to-jsx.ts` 文件已创建
- [ ] SVG 正确转换为 JSX
- [ ] 支持 `currentColor` 等属性
- [ ] 生成的 JSX 格式正确

---

#### 步骤 3.4：实现组件生成工具

**目标**：生成 React 组件代码

**操作**：
创建 `scripts/utils/generate-component.ts`

**功能要求**：
- 生成图标组件代码
- 生成头像组件代码
- 生成背景组件代码
- 支持多权重图标
- 生成 TypeScript 类型

**生成的组件模板**：
```typescript
// 图标组件模板
import * as React from 'react';
import type { IconProps } from '../lib/types';
import IconBase from '../lib/IconBase';

const weights = {
  regular: <svg>...</svg>,
  thin: <svg>...</svg>,
  // ...
};

export const IconName: React.FC<IconProps> = React.forwardRef((props, ref) => (
  <IconBase ref={ref} {...props} weights={weights} />
));

IconName.displayName = 'IconName';
```

**验收标准**：
- [ ] `generate-component.ts` 文件已创建
- [ ] 能够生成正确的组件代码
- [ ] 代码格式正确
- [ ] 包含完整的类型定义

---

#### 步骤 3.5：实现主生成脚本

**目标**：创建主生成脚本，整合所有功能

**操作**：
创建 `scripts/generate-react.ts`

**功能要求**：
- 读取 core 包的素材
- 生成所有图标组件
- 生成所有头像组件
- 生成所有背景组件
- 生成索引文件（导出所有组件）
- 生成类型定义文件
- 支持增量生成
- 输出生成进度和统计信息

**执行流程**：
1. 读取 core 包素材
2. 为每个图标生成组件文件
3. 为每个素材生成组件文件
4. 生成 `src/index.ts` 导出文件
5. 输出统计信息

**验收标准**：
- [ ] `generate-react.ts` 文件已创建
- [ ] 脚本能够完整执行
- [ ] 生成所有组件文件
- [ ] 生成索引文件
- [ ] 输出正确的统计信息

---

### 阶段 4：生成组件文件

#### 步骤 4.1：生成图标组件

**目标**：为所有图标生成 React 组件

**操作**：
运行生成脚本

```bash
cd resource-react
pnpm run generate
```

**生成的文件结构**：
```
resource-react/src/icons/
├── IconFourLeafClover.tsx
├── IconXCircleS.tsx
└── ...
```

**验收标准**：
- [ ] 所有图标组件已生成
- [ ] 组件文件格式正确
- [ ] 支持所有权重
- [ ] TypeScript 类型正确

---

#### 步骤 4.2：生成头像组件

**目标**：为所有头像生成 React 组件

**操作**：
在生成脚本中添加头像生成逻辑

**生成的文件结构**：
```
resource-react/src/avatars/
├── AvatarByewind.tsx
└── ...
```

**验收标准**：
- [ ] 所有头像组件已生成
- [ ] 组件支持不同格式（PNG、SVG 等）
- [ ] 组件 props 类型正确

---

#### 步骤 4.3：生成背景组件

**目标**：为所有背景生成 React 组件

**操作**：
在生成脚本中添加背景生成逻辑

**生成的文件结构**：
```
resource-react/src/backgrounds/
├── Gradient01.tsx
└── ...
```

**验收标准**：
- [ ] 所有背景组件已生成
- [ ] 组件支持不同格式
- [ ] 组件 props 类型正确

---

#### 步骤 4.4：生成索引文件

**目标**：创建统一的导出文件

**操作**：
生成 `resource-react/src/index.ts`

**内容要求**：
- 导出所有图标组件
- 导出所有头像组件
- 导出所有背景组件
- 导出类型定义
- 导出工具函数

**验收标准**：
- [ ] `index.ts` 文件已生成
- [ ] 所有组件都已导出
- [ ] 导出语句格式正确
- [ ] 支持 Tree-shaking

---

### 阶段 5：构建和测试

#### 步骤 5.1：配置构建脚本

**目标**：确保构建脚本正常工作

**操作**：
运行构建命令

```bash
cd resource-react
pnpm run build
```

**验收标准**：
- [ ] 构建成功完成
- [ ] 生成 `dist/` 目录
- [ ] 生成 `.d.ts` 类型文件
- [ ] 生成 CJS 和 ESM 格式

---

#### 步骤 5.2：创建测试应用

**目标**：创建测试应用验证组件

**操作**：
在 `demo-react/` 中创建测试应用（如果不存在）

**测试内容**：
- 导入图标组件
- 导入头像组件
- 导入背景组件
- 测试不同权重
- 测试不同 props

**验收标准**：
- [ ] 测试应用能够运行
- [ ] 所有组件正常渲染
- [ ] 类型检查通过
- [ ] 无运行时错误

---

#### 步骤 5.3：编写使用文档

**目标**：创建使用文档

**操作**：
创建或更新 `resource-react/README.md`

**内容要求**：
- 安装说明
- 使用示例
- API 文档
- 类型定义说明
- 常见问题

**验收标准**：
- [ ] README.md 文件已创建
- [ ] 文档内容完整
- [ ] 示例代码正确
- [ ] 文档格式正确

---

### 阶段 6：优化和完善

#### 步骤 6.1：性能优化

**目标**：优化组件性能

**操作**：
- 使用 `React.memo` 优化组件
- 优化 SVG 渲染
- 减少包体积

**验收标准**：
- [ ] 组件渲染性能良好
- [ ] 包体积合理
- [ ] Tree-shaking 正常工作

---

#### 步骤 6.2：添加别名支持

**目标**：支持图标别名

**操作**：
在生成脚本中处理别名

**功能要求**：
- 从 core 包读取别名信息
- 生成别名导出
- 保持向后兼容

**验收标准**：
- [ ] 别名功能正常工作
- [ ] 别名导出正确
- [ ] 文档已更新

---

#### 步骤 6.3：完善类型定义

**目标**：完善 TypeScript 类型定义

**操作**：
- 添加 JSDoc 注释
- 完善类型约束
- 添加类型导出

**验收标准**：
- [ ] 所有类型定义完整
- [ ] JSDoc 注释完整
- [ ] 类型检查无错误

---

## 依赖安装

### 必需的依赖

```bash
cd resource-react

# 安装依赖
pnpm add react @types/react

# 安装开发依赖
pnpm add -D typescript tsup @svgr/core @svgr/plugin-svgo
```

### 可选依赖

```bash
# 如果需要使用 svgo 优化
pnpm add -D svgo
```

---

## 执行顺序总结

1. **基础设置**（步骤 1.1 - 1.3）
   - 确认项目结构
   - 创建 TypeScript 配置
   - 创建 tsup 配置

2. **创建基础库**（步骤 2.1 - 2.3）
   - 创建 IconBase 组件
   - 创建类型定义
   - 创建工具函数

3. **创建生成脚本**（步骤 3.1 - 3.5）
   - 创建脚本目录
   - 实现读取素材工具
   - 实现 SVG 转 JSX
   - 实现组件生成工具
   - 实现主生成脚本

4. **生成组件**（步骤 4.1 - 4.4）
   - 生成图标组件
   - 生成头像组件
   - 生成背景组件
   - 生成索引文件

5. **构建和测试**（步骤 5.1 - 5.3）
   - 配置构建脚本
   - 创建测试应用
   - 编写使用文档

6. **优化完善**（步骤 6.1 - 6.3）
   - 性能优化
   - 添加别名支持
   - 完善类型定义

---

## 验收标准（总体）

- [ ] 所有组件能够从 core 包自动生成
- [ ] 生成的组件支持 TypeScript
- [ ] 构建成功，输出正确的格式
- [ ] 测试应用能够正常使用所有组件
- [ ] 文档完整清晰
- [ ] 代码质量良好，无错误和警告

---

## 注意事项

1. **依赖 core 包**：确保在生成前，core 包已经处理完所有素材
2. **文件路径**：注意脚本中的路径是相对于项目根目录的
3. **命名规范**：保持与 core 包的命名规范一致（kebab-case）
4. **类型安全**：确保所有生成的代码都有完整的类型定义
5. **向后兼容**：考虑未来可能的 API 变更，保持向后兼容

---

## 后续计划

- [ ] 支持 SSR（服务端渲染）
- [ ] 添加单元测试
- [ ] 添加 Storybook 文档
- [ ] 支持自定义主题
- [ ] 支持动画效果

---

## 参考资源

- [Phosphor Icons React](https://github.com/phosphor-icons/phosphor-react) - 参考实现
- [SVGR 文档](https://react-svgr.com/) - SVG 转 React 组件工具
- [tsup 文档](https://tsup.egoist.dev/) - TypeScript 打包工具