npm package: @mathwiz/ui-components
Description: A collection of reusable UI components for React applications within the mathwiz ecosystem.
Author: mathwiz Team
Latest version: 0.1.34

# @mathwiz/ui-components

一个基于 React + TypeScript + Vite + Storybook 构建的小学数学益智教育网站 UI 组件库。专注于开发高质量、可复用的 UI 组件，支持小学数学教育平台的快速开发。

## 📦 组件库信息

- **包名**: `@mathwiz/ui-components`
- **版本**: 0.1.33
- **描述**: 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** - 年级单元浏览上下文

### 数学练习组件
- **MathSessionPage** - 完整的数学练习页面
- **MathSessionContainer** - 数学练习业务容器
- **MathCard** - 题目展示组件
- **MathGraph** - 几何图形组件
- **useSessionStore** - 数学练习状态管理
- **useSessionCalculations** - 会话计算 Hook
- **useGeometryManagement** - 几何图形管理 Hook
- **useSessionEventHandlers** - 事件处理 Hook

### 数据与工具
- **数据类型** - 完整的 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.7
npm install lucide-react@^0.541.0
npm install zustand@^5.0.8
```

### 必需依赖说明

#### HeroUI 依赖
- **版本**: `@heroui/react@^2.8.7`
- **作用**: 提供基础 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>
  );
}
```

## 🎯 样式系统与引入指南 (v0.1.20+)

### 核心原则
组件库采用 **责任分层** 样式架构，确保样式可控、无冲突：

1. **组件库不打包第三方样式**：只输出自有样式
2. **组件库不包含全局样式重置**：避免与业务项目样式冲突
3. **业务项目全权控制样式引入**：自行决定引入哪些第三方样式及其版本
4. **明确的依赖声明**：通过文档和开发环境警告提示必要依赖

### 样式引入步骤

#### 1. 安装组件库
```bash
npm install @mathwiz/ui-components
```

#### 2. 引入组件库样式
在业务项目的入口文件（通常是 `main.tsx` 或 `App.tsx`）中添加：

```typescript
// 引入组件库样式
import '@mathwiz/ui-components/style.css';

// 引入组件库设计令牌（可选，如需主题定制）
import '@mathwiz/ui-components/style.css?tokens';
```

#### 3. 引入第三方样式依赖
根据实际使用的组件，引入对应的第三方样式：

```typescript
// 如果使用 EquationRender 组件（需要 KaTeX）
import 'katex/dist/katex.min.css';

// 如果使用 MathGraph 组件（需要 JSXGraph）
import 'jsxgraph/distrib/jsxgraph.css';

// 其他第三方样式...
```

#### 4. 引入业务项目自定义样式
```typescript
// 业务项目全局样式
import './index.css';
import './App.css';
```

### 样式加载顺序
推荐加载顺序确保样式优先级正确：
```
业务项目入口 (main.tsx)
├── 第三方全局样式 (katex.min.css, jsxgraph.css)
├── 组件库样式 (style.css)
└── 业务自定义样式
```

### 版本要求
- **新项目**：使用 `@mathwiz/ui-components >= 0.1.21`
- **迁移项目**：参考 `docs/样式引入指南.md`

### 重要版本更新
- **v0.1.21**：移除全局样式重置，避免与业务项目样式冲突
- **v0.1.20**：移除组件内部动态CSS导入，改为业务项目手动引入
- **v0.1.19**：修复样式文件命名冲突问题
- **v0.1.18**：引入设计令牌系统

### 使用示例
```typescript
// 业务项目入口文件 (main.tsx)
import 'katex/dist/katex.min.css';      // 第三方样式
import '@mathwiz/ui-components/style.css'; // 组件库样式
import './index.css';                   // 业务项目样式

// 然后正常使用组件
import { MathWizHeader, EquationRender } from '@mathwiz/ui-components';
```

### 数据集成

组件库支持多种数据集成方式：

#### 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.7`
3. **样式继承**: 组件库继承 HeroUI 的主题系统，支持自定义主题
4. **类型安全**: 完整的 TypeScript 类型定义
5. **无障碍访问**: 所有组件都支持键盘导航和屏幕阅读器

### 故障排除

#### 样式不显示
- 检查是否使用了 `<HeroUIProvider>`
- 确认 HeroUI 版本正确
- 检查浏览器控制台是否有错误

#### 组件不渲染
- 检查 props 类型是否正确
- 确认数据格式符合类型定义
- 查看 Storybook 中的使用示例

#### 样式系统常见问题

##### 问题1：公式显示不正确
**症状**：EquationRender组件渲染的公式样式异常（颜色、间距、字体错误）
**解决方案**：
1. 确认已正确引入 `katex/dist/katex.min.css`
2. 检查浏览器开发者工具的 Network 面板，确认 CSS 文件已加载
3. 检查 Elements 面板，确认公式元素有正确的 CSS 类名（如 `.katex`）

##### 问题2：构建产物过大
**症状**：构建后出现大体积的 CSS 文件（>1MB）
**可能原因**：
1. 字体文件被内联为 Base64
2. 第三方样式被重复打包
**解决方案**：
1. 检查 Vite 配置的 `assetsInlineLimit` 设置
2. 确保组件库版本 >= 0.1.21
3. 运行构建分析工具：`npx vite-bundle-analyzer`

##### 问题3：样式污染（组件库影响业务项目布局）
**症状**：引入组件库样式后，业务项目的布局被破坏
**可能原因**：
1. 组件库版本 < 0.1.21 可能包含全局重置样式
2. 组件库样式意外影响了业务项目的全局样式
**解决方案**：
1. 升级组件库到版本 >= 0.1.21（已移除全局重置样式）
2. 检查组件库 `style.css` 文件是否包含全局选择器
3. 在业务项目中显式定义全局重置样式

##### 问题4：开发环境警告频繁
**症状**：控制台显示 "KaTeX CSS 未检测到" 警告
**解决方案**：
1. 确认已正确引入 KaTeX CSS
2. 如果确认已引入但警告仍出现，可参考 `docs/样式引入指南.md` 中的临时解决方案

### 样式系统禁止事项
❌ **禁止在组件库中添加全局样式重置**（如 `* { margin: 0; }`）
❌ **禁止在组件内部动态导入CSS**（会产生冗余构建产物）
❌ **禁止打包第三方全局样式到组件库中**（业务项目应控制版本）
❌ **禁止覆盖业务项目的全局样式**（保持样式责任分离）

## 📖 组件故事

### 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**: ^19.1.1
- **TypeScript**: ~5.8.3
- **Vite**: ^7.1.2
- **Storybook**: ^9.1.3
- **Zustand**: ^5.0.0 (状态管理)
- **HeroUI**: ^2.8.7 (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