@mathwiz/ui-components

v0.1.17

Published

18 days ago

A collection of reusable UI components for React applications within the mathwiz ecosystem.

0High
0Medium
0Low

moleusher

react ui components storybook mathwiz

@mathwiz/ui-components

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

📦 组件库信息

包名: @mathwiz/ui-components
版本: 0.1.8
描述: A collection of reusable UI components for React applications within the mathwiz ecosystem.
GitHub: https://github.com/moleusher/mathwiz-UI
Storybook: 本地开发地址

🚀 环境配置

安装依赖

npm install

开发命令

# 启动开发服务器
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

端口检查

# 检查端口占用
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 - 阴影按钮

使用示例

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"
/>

🚀 在实际项目中使用

安装依赖

# 安装组件库
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 的样式系统：

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. 基础页面布局

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. 雷达能力评估页面

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. 自定义主题配置

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 自动注入功能 (v0.1.6+)

从版本 0.1.6 开始，组件库使用 CSS 自动注入技术，所有样式会自动注入到 JavaScript bundle 中：

技术实现

使用 vite-plugin-css-injected-by-js 插件
运行时自动创建 <style> 标签并注入 CSS 内容
包含完整的 CSS 变量系统（设计令牌）
所有组件样式自动加载

使用优势

零配置使用 - 无需额外导入 CSS 文件
样式完整性 - 确保所有组件样式正确显示
性能优化 - CSS 与 JavaScript 一起打包，减少 HTTP 请求
主题支持 - 完整的 CSS 变量系统支持主题定制

样式范围

自动注入的样式包括：

✅ MathWizHeader 组件样式
✅ Sidebar 组件样式
✅ ContentAccordion 组件样式
✅ GradeUnitBrowserPage 页面样式
✅ 所有基础组件样式
✅ CSS 变量系统（设计令牌）

使用示例

// 正确 - 无需额外导入样式，样式自动注入
import { MathWizHeader } from '@mathwiz/ui-components';

// 错误 - 不需要手动导入 CSS 文件
// import '@mathwiz/ui-components/dist/styles.css'; // 不需要

样式导入说明

组件库自带完整的样式系统，无需额外导入 CSS 文件：

// 正确 - 无需额外导入样式
import { MathWizHeader } from '@mathwiz/ui-components';

// 错误 - 不需要导入外部 CSS
// import '@mathwiz/ui-components/dist/styles.css'; // 不需要

数据集成

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

1. 直接传入数据

<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. 使用模拟数据

import { mockUserData, mockExploreItems } from '@mathwiz/ui-components';

<MathWizHeader
  userData={mockUserData}
  exploreItems={mockExploreItems}
/>

3. API 集成

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>
  );
}

注意事项

必需包装: 所有组件必须在 <HeroUIProvider> 内部使用
版本兼容: 确保 HeroUI 版本为 ^2.8.4
样式继承: 组件库继承 HeroUI 的主题系统，支持自定义主题
类型安全: 完整的 TypeScript 类型定义
无障碍访问: 所有组件都支持键盘导航和屏幕阅读器

故障排除

样式不显示

检查是否使用了 <HeroUIProvider>
确认 HeroUI 版本正确
检查浏览器控制台是否有错误

组件不渲染

检查 props 类型是否正确
确认数据格式符合类型定义
查看 Storybook 中的使用示例

📖 组件故事

Storybook 故事结构

默认状态 - 基础组件展示
交互状态 - 悬停、点击等交互效果
参数化样式 - 各种样式变体展示
响应式布局 - 移动端适配
无障碍访问 - 键盘导航和屏幕阅读器支持

主要故事分类

基础组件 - Button, ContentAccordion 等
复合组件 - MathWizHeader, Sidebar 等
数据展示 - RadarChart, AbilityProgressBar 等
页面组件 - GradeUnitBrowserPage 等

🔧 模拟数据与 API

数据契约

用户数据类型

interface UserData {
  id: string;
  name: string;
  avatar: string;
  level: number;
  badges: string[];
  token?: string;
  progress?: {
    overall: number;
    byUnit: Record<string, number>;
  };
}

探索菜单项类型

interface ExploreItem {
  id: string;
  label: string;
  status?: string;
  href?: string;
  target?: string;
  onClick?: (item: ExploreItem) => void;
}

课程单元类型

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 - 获取探索菜单项

模拟数据源

用户数据

const mockUserData = {
  id: 'user-123',
  name: '学生用户',
  avatar: '/avatars/student.png',
  level: 5,
  badges: ['math-beginner', 'quick-learner']
};

探索菜单数据

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 模拟：

// 在 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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@mathwiz/ui-components

📦 组件库信息

🚀 环境配置

安装依赖

开发命令

端口检查

📚 导出的组件

基础 UI 组件

雷达能力评估组件

页面级组件

数学练习组件

数据与工具

🎨 样式参数化配置

MathWizHeader 参数化样式

变体 (variant)

颜色主题 (color)

Logo 尺寸 (logoSize)

探索按钮变体 (exploreButtonVariant)

使用示例

🚀 在实际项目中使用

安装依赖

必需依赖说明

HeroUI 依赖

其他依赖

HeroUIProvider 配置

完整使用示例

1. 基础页面布局

2. 雷达能力评估页面

3. 自定义主题配置

CSS 自动注入功能 (v0.1.6+)

技术实现

使用优势

样式范围

使用示例

样式导入说明

数据集成

1. 直接传入数据

2. 使用模拟数据

3. API 集成

注意事项

故障排除

样式不显示

组件不渲染

📖 组件故事

Storybook 故事结构

主要故事分类

🔧 模拟数据与 API

数据契约

用户数据类型

探索菜单项类型

课程单元类型

API 契约

用户相关 API

课程相关 API

探索菜单 API

模拟数据源

用户数据

探索菜单数据

课程数据

MSW 模拟配置

🏗️ 技术架构

核心依赖

开发工具

Storybook Addons

📁 项目结构

🔒 安全说明

🤝 贡献指南

📄 许可证