@mathwiz/ui-components 0.1.3 → 0.1.5

package/README.md

@@ -1,69 +1,639 @@
-# React + TypeScript + Vite
-
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
-
-Currently, two official plugins are available:
-
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
-
-```js
-export default tseslint.config([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-
-      // Remove tseslint.configs.recommended and replace with this
-      ...tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      ...tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      ...tseslint.configs.stylisticTypeChecked,
-
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
-```
-
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default tseslint.config([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
+# @mathwiz/ui-components
+
+一个基于 React + TypeScript + Vite + Storybook 构建的小学数学益智教育网站 UI 组件库。专注于开发高质量、可复用的 UI 组件，支持小学数学教育平台的快速开发。
+
+## 📦 组件库信息
+
+- **包名**: `@mathwiz/ui-components`
+- **版本**: 0.1.4
+- **描述**: A collection of reusable UI components for React applications within the mathwiz ecosystem.
+- **GitHub**: [https://github.com/moleusher/mathwiz-UI](https://github.com/moleusher/mathwiz-UI)
+- **Storybook**: [本地开发地址](http://localhost:6006)
+
+## 🚀 环境配置
+
+### 安装依赖
+```bash
+npm install
+```
+
+### 开发命令
+```bash
+# 启动开发服务器
+npm run dev          # 端口 5173
+
+# 启动 Storybook
+npm run storybook    # 端口 6006
+
+# 运行测试
+npm test             # 运行所有测试
+npm run test:watch   # 监听模式运行测试
+npm run test:coverage # 生成测试覆盖率报告
+
+# 构建项目
+npm run build          # 构建生产版本
+npm run build-storybook # 构建 Storybook
+```
+
+### 端口检查
+```bash
+# 检查端口占用
+netstat -ano | findstr :6007
+netstat -ano | findstr :6006
+
+# 强制结束进程
+taskkill //F //PID <PID>
+```
+
+## 📚 导出的组件
+
+### 基础 UI 组件
+- **Button** - 按钮组件
+- **ContentAccordion** - 内容折叠面板
+- **Sidebar** - 侧边栏组件
+- **MathWizHeader** - 网站头部组件
+- **Submenu** - 下拉菜单组件
+- **UserProfile** - 用户资料组件
+
+### 雷达能力评估组件
+- **RadarChart** - 雷达图组件
+- **AbilityAssessmentDashboard** - 能力评估仪表板
+- **AbilityProgressBar** - 能力进度条
+- **PersonalizedAdvicePanel** - 个性化建议面板
+- **RecommendationCard** - 推荐卡片
+
+### 页面级组件
+- **GradeUnitBrowserPage** - 年级单元浏览页面
+- **GradeUnitBrowserProvider** - 年级单元浏览上下文
+
+### 数据与工具
+- **数据类型** - 完整的 TypeScript 类型定义
+- **工具函数** - 几何计算等工具函数
+- **数据配置** - 课程数据、用户进度等
+
+## 🎨 样式参数化配置
+
+### MathWizHeader 参数化样式
+
+#### 变体 (variant)
+- `primary` - 主色渐变
+- `secondary` - 副色渐变
+- `gradient` - 自定义渐变
+- `solid` - 纯色背景
+- `bordered` - 边框样式
+
+#### 颜色主题 (color)
+- `default` - 默认主题
+- `primary` - 主色主题
+- `success` - 成功色主题
+- `warning` - 警告色主题
+- `danger` - 危险色主题
+
+#### Logo 尺寸 (logoSize)
+- `sm` - 小号
+- `md` - 中号 (默认)
+- `lg` - 大号
+- `xl` - 超大号
+
+#### 探索按钮变体 (exploreButtonVariant)
+- `solid` - 实心按钮
+- `bordered` - 边框按钮
+- `light` - 轻量按钮
+- `flat` - 扁平按钮
+- `faded` - 淡化按钮
+- `shadow` - 阴影按钮
+
+### 使用示例
+
+```typescript
+import { MathWizHeader } from '@mathwiz/ui-components';
+
+// 基本使用
+<MathWizHeader
+  variant="primary"
+  color="success"
+  logoText="MathWiz"
+/>
+
+// 自定义渐变
+<MathWizHeader
+  variant="gradient"
+  gradientFrom="#8b5cf6"
+  gradientTo="#06b6d4"
+  gradientVia="#3b82f6"
+  height={80}
+  exploreButtonVariant="shadow"
+  exploreButtonColor="primary"
+/>
+
+// 纯色主题
+<MathWizHeader
+  variant="solid"
+  background="#f4f4f5"
+  logoColor="#18181b"
+  exploreButtonVariant="bordered"
+  exploreButtonColor="primary"
+/>
+```
+
+## 🚀 在实际项目中使用
+
+### 安装依赖
+
+```bash
+# 安装组件库
+npm install @mathwiz/ui-components
+
+# 安装必需的第三方依赖
+npm install @heroui/react@^2.8.4
+npm install lucide-react@^0.541.0
+npm install zustand@^5.0.8
+```
+
+### 必需依赖说明
+
+#### HeroUI 依赖
+- **版本**: `@heroui/react@^2.8.4`
+- **作用**: 提供基础 UI 组件和样式系统
+- **必需**: 所有组件都依赖 HeroUI 的样式和主题系统
+
+#### 其他依赖
+- `lucide-react@^0.541.0` - 图标库
+- `zustand@^5.0.8` - 状态管理
+
+### HeroUIProvider 配置
+
+**必须**在项目根组件中使用 `<HeroUIProvider>` 包装，因为组件库的所有组件都依赖 HeroUI 的样式系统：
+
+```typescript
+import React from 'react';
+import { HeroUIProvider } from '@heroui/react';
+import { MathWizHeader, GradeUnitBrowserPage, GradeUnitBrowserProvider } from '@mathwiz/ui-components';
+
+function App() {
+  return (
+    <HeroUIProvider>
+      {/* 使用组件库组件 */}
+      <MathWizHeader
+        logoText="MathWiz"
+        variant="gradient"
+        exploreItems={[
+          { id: 'grade-1', label: '一年级', status: 'new' },
+          { id: 'grade-2', label: '二年级', status: '10%' }
+        ]}
+        userData={{
+          id: 'user-123',
+          name: '学生用户',
+          avatar: '/avatars/student.png',
+          level: 5,
+          badges: ['math-beginner']
+        }}
+      />
+
+      <GradeUnitBrowserProvider>
+        <GradeUnitBrowserPage
+          gradeId="g5"
+          userId="student-123"
+          onLearnAction={(item) => console.log('学习:', item)}
+        />
+      </GradeUnitBrowserProvider>
+    </HeroUIProvider>
+  );
+}
+
+export default App;
+```
+
+### 完整使用示例
+
+#### 1. 基础页面布局
+
+```typescript
+import React from 'react';
+import { HeroUIProvider } from '@heroui/react';
+import {
+  MathWizHeader,
+  Sidebar,
+  GradeUnitBrowserPage,
+  GradeUnitBrowserProvider
+} from '@mathwiz/ui-components';
+
+function MathLearningApp() {
+  return (
+    <HeroUIProvider>
+      <div className="app-layout">
+        <MathWizHeader
+          logoText="MathWiz"
+          variant="gradient"
+          userData={{
+            id: 'user-123',
+            name: '小明同学',
+            avatar: '/avatars/xiaoming.png',
+            level: 5,
+            badges: ['math-beginner', 'quick-learner']
+          }}
+        />
+
+        <div className="main-content">
+          <Sidebar />
+          <div className="content-area">
+            <GradeUnitBrowserProvider>
+              <GradeUnitBrowserPage
+                gradeId="g5"
+                userId="user-123"
+                onLearnAction={(item) => {
+                  // 处理学习动作
+                  console.log('开始学习:', item.title);
+                }}
+              />
+            </GradeUnitBrowserProvider>
+          </div>
+        </div>
+      </div>
+    </HeroUIProvider>
+  );
+}
+```
+
+#### 2. 雷达能力评估页面
+
+```typescript
+import React from 'react';
+import { HeroUIProvider } from '@heroui/react';
+import {
+  MathWizHeader,
+  AbilityAssessmentDashboard,
+  RadarChart,
+  PersonalizedAdvicePanel
+} from '@mathwiz/ui-components';
+
+function AbilityAssessmentPage() {
+  const abilityData = {
+    math: 85,
+    logic: 70,
+    geometry: 90,
+    algebra: 65,
+    statistics: 75
+  };
+
+  return (
+    <HeroUIProvider>
+      <MathWizHeader
+        variant="solid"
+        background="#f8fafc"
+        logoColor="#1e293b"
+        exploreButtonVariant="bordered"
+      />
+
+      <div className="assessment-container">
+        <AbilityAssessmentDashboard
+          studentName="小明"
+          gradeLevel={5}
+          overallScore={77}
+        />
+
+        <div className="charts-section">
+          <RadarChart
+            data={abilityData}
+            title="能力雷达图"
+            size={300}
+          />
+
+          <PersonalizedAdvicePanel
+            strengths={['几何', '数学基础']}
+            weaknesses={['代数', '逻辑推理']}
+            recommendations={[
+              '建议加强代数基础练习',
+              '多做逻辑推理题目',
+              '保持几何学习的优势'
+            ]}
+          />
+        </div>
+      </div>
+    </HeroUIProvider>
+  );
+}
+```
+
+#### 3. 自定义主题配置
+
+```typescript
+import React from 'react';
+import { HeroUIProvider, createTheme } from '@heroui/react';
+import { MathWizHeader } from '@mathwiz/ui-components';
+
+// 自定义主题
+const customTheme = createTheme({
+  type: "light",
+  theme: {
+    colors: {
+      primary: '#8b5cf6',
+      secondary: '#06b6d4',
+      success: '#10b981',
+      warning: '#f59e0b',
+      danger: '#ef4444'
+    }
+  }
+});
+
+function CustomThemeApp() {
+  return (
+    <HeroUIProvider theme={customTheme}>
+      <MathWizHeader
+        variant="primary"
+        color="primary"
+        logoText="MathWiz"
+        exploreButtonVariant="solid"
+        exploreButtonColor="primary"
+      />
+      {/* 其他组件 */}
+    </HeroUIProvider>
+  );
+}
+```
+
+### 样式导入说明
+
+组件库自带完整的样式系统，无需额外导入 CSS 文件：
+
+```typescript
+// 正确 - 无需额外导入样式
+import { MathWizHeader } from '@mathwiz/ui-components';
+
+// 错误 - 不需要导入外部 CSS
+// import '@mathwiz/ui-components/dist/styles.css'; // 不需要
+```
+
+### 数据集成
+
+组件库支持多种数据集成方式：
+
+#### 1. 直接传入数据
+```typescript
+<MathWizHeader
+  userData={{
+    id: 'user-123',
+    name: '学生用户',
+    avatar: '/avatars/student.png',
+    level: 5
+  }}
+  exploreItems={[
+    { id: 'grade-1', label: '一年级', status: 'new' },
+    { id: 'grade-2', label: '二年级', status: '10%' }
+  ]}
+/>
+```
+
+#### 2. 使用模拟数据
+```typescript
+import { mockUserData, mockExploreItems } from '@mathwiz/ui-components';
+
+<MathWizHeader
+  userData={mockUserData}
+  exploreItems={mockExploreItems}
+/>
+```
+
+#### 3. API 集成
+```typescript
+import { useEffect, useState } from 'react';
+import { MathWizHeader, UserData, ExploreItem } from '@mathwiz/ui-components';
+
+function App() {
+  const [userData, setUserData] = useState<UserData>();
+  const [exploreItems, setExploreItems] = useState<ExploreItem[]>([]);
+
+  useEffect(() => {
+    // 从 API 获取数据
+    fetch('/api/user/profile')
+      .then(res => res.json())
+      .then(setUserData);
+
+    fetch('/api/explore/items')
+      .then(res => res.json())
+      .then(data => setExploreItems(data.items));
+  }, []);
+
+  return (
+    <HeroUIProvider>
+      <MathWizHeader
+        userData={userData}
+        exploreItems={exploreItems}
+        isLoading={!userData}
+      />
+    </HeroUIProvider>
+  );
+}
+```
+
+### 注意事项
+
+1. **必需包装**: 所有组件必须在 `<HeroUIProvider>` 内部使用
+2. **版本兼容**: 确保 HeroUI 版本为 `^2.8.4`
+3. **样式继承**: 组件库继承 HeroUI 的主题系统，支持自定义主题
+4. **类型安全**: 完整的 TypeScript 类型定义
+5. **无障碍访问**: 所有组件都支持键盘导航和屏幕阅读器
+
+### 故障排除
+
+#### 样式不显示
+- 检查是否使用了 `<HeroUIProvider>`
+- 确认 HeroUI 版本正确
+- 检查浏览器控制台是否有错误
+
+#### 组件不渲染
+- 检查 props 类型是否正确
+- 确认数据格式符合类型定义
+- 查看 Storybook 中的使用示例
+
+## 📖 组件故事
+
+### Storybook 故事结构
+- **默认状态** - 基础组件展示
+- **交互状态** - 悬停、点击等交互效果
+- **参数化样式** - 各种样式变体展示
+- **响应式布局** - 移动端适配
+- **无障碍访问** - 键盘导航和屏幕阅读器支持
+
+### 主要故事分类
+- **基础组件** - Button, ContentAccordion 等
+- **复合组件** - MathWizHeader, Sidebar 等
+- **数据展示** - RadarChart, AbilityProgressBar 等
+- **页面组件** - GradeUnitBrowserPage 等
+
+## 🔧 模拟数据与 API
+
+### 数据契约
+
+#### 用户数据类型
+```typescript
+interface UserData {
+  id: string;
+  name: string;
+  avatar: string;
+  level: number;
+  badges: string[];
+  token?: string;
+  progress?: {
+    overall: number;
+    byUnit: Record<string, number>;
+  };
+}
+```
+
+#### 探索菜单项类型
+```typescript
+interface ExploreItem {
+  id: string;
+  label: string;
+  status?: string;
+  href?: string;
+  target?: string;
+  onClick?: (item: ExploreItem) => void;
+}
+```
+
+#### 课程单元类型
+```typescript
+interface CourseUnit {
+  id: string;
+  title: string;
+  english: string;
+  category: string;
+  unitNumber: number;
+  progress: number;
+  skills: string[];
+  children: Lesson[];
+  lessonsCount: number;
+  estimatedDuration: string;
+}
+```
+
+### API 契约
+
+#### 用户相关 API
+- `GET /api/user/profile` - 获取用户资料
+- `GET /api/user/grade/units/nav` - 获取年级单元导航
+
+#### 课程相关 API
+- `GET /api/curriculum/grade-5` - 获取五年级课程数据
+- `POST /api/units/:unitId/progress` - 更新单元进度
+- `POST /api/lessons/:lessonId/toggle` - 切换课程完成状态
+
+#### 探索菜单 API
+- `GET /api/explore/items` - 获取探索菜单项
+
+### 模拟数据源
+
+#### 用户数据
+```typescript
+const mockUserData = {
+  id: 'user-123',
+  name: '学生用户',
+  avatar: '/avatars/student.png',
+  level: 5,
+  badges: ['math-beginner', 'quick-learner']
+};
+```
+
+#### 探索菜单数据
+```typescript
+const mockExploreItems = [
+  { id: 'grade-1', label: '一年级', status: 'new' },
+  { id: 'grade-2', label: '二年级', status: '10%' },
+  { id: 'grade-3', label: '三年级', status: '25%' },
+  { id: 'grade-4', label: '四年级', status: '50%' },
+  { id: 'grade-5', label: '五年级', status: '75%' },
+  { id: 'grade-6', label: '六年级', status: 'completed' }
+];
+```
+
+#### 课程数据
+基于可汗学院五年级数学课程结构，包含：
+- 小数乘法
+- 位置（坐标与位置）
+- 小数除法
+- 可能性
+- 简易方程
+- 多边形面积
+- 植树问题
+
+### MSW 模拟配置
+
+组件库集成了 MSW (Mock Service Worker) 用于 API 模拟：
+
+```typescript
+// 在 Storybook 中自动启用 MSW
+import { initialize, mswLoader } from 'msw-storybook-addon';
+initialize();
+
+const preview: Preview = {
+  parameters: {
+    msw: { handlers: [] }
   },
-])
+  loaders: [mswLoader]
+};
+```
+
+## 🏗️ 技术架构
+
+### 核心依赖
+- **React**: ^18.3.1
+- **TypeScript**: ~5.8.3
+- **Vite**: ^7.1.2
+- **Storybook**: ^9.1.3
+- **Zustand**: ^5.0.8 (状态管理)
+- **HeroUI**: ^2.8.4 (UI 组件库)
+- **Lucide React**: ^0.541.0 (图标库)
+
+### 开发工具
+- **Vitest**: ^3.2.4 (单元测试)
+- **Testing Library**: ^16.3.0 (测试工具)
+- **Playwright**: ^1.55.0 (E2E 测试)
+- **MSW**: ^2.11.1 (API 模拟)
+- **ESLint**: ^9.33.0 (代码检查)
+- **Tailwind CSS**: ^4.1.12 (样式框架)
+
+### Storybook Addons
+- @chromatic-com/storybook: ^4.1.1
+- @storybook/addon-docs: ^9.1.3
+- @storybook/addon-a11y: ^9.1.3
+- @storybook/addon-vitest: ^9.1.3
+- msw-storybook-addon: ^2.0.5
+
+## 📁 项目结构
+
+```
+react-storybook-mcp/
+├── src/
+│   ├── components/           # UI 组件
+│   │   ├── gradeNavigate/    # 年级导航相关组件
+│   │   ├── radarAbility/     # 雷达能力评估组件
+│   │   ├── common/           # 通用基础组件
+│   │   └── layout/           # 布局组件
+│   ├── data/                 # 数据文件
+│   ├── store/                # Zustand 状态管理
+│   ├── types/                # TypeScript 类型定义
+│   ├── hooks/                # 自定义 Hooks
+│   └── utils/                # 工具函数
+├── .storybook/               # Storybook 配置
+├── docs/                     # 开发文档
+├── tests/                    # 测试文件
+└── public/                   # 静态资源
 ```
+
+## 🔒 安全说明
+
+本组件库仅用于防御性安全任务，不包含任何恶意代码。所有组件都经过严格的安全审查，确保不会用于凭证发现、爬取敏感信息或其他恶意用途。
+
+## 🤝 贡献指南
+
+欢迎提交 Issue 和 Pull Request！请确保：
+- 遵循 TDD 开发模式
+- 编写完整的 Storybook 故事
+- 通过所有测试
+- 更新相关文档
+
+## 📄 许可证
+
+MIT License

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mathwiz/ui-components",
   "private": false,
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "A collection of reusable UI components for React applications within the mathwiz ecosystem.",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",