@mathwiz/ui-components 0.1.16 → 0.1.22

package/README.md

@@ -5,7 +5,7 @@
 ## 📦 组件库信息
 
 - **包名**: `@mathwiz/ui-components`
-- **版本**: 0.1.8
+- **版本**: 0.1.21
 - **描述**: 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)
@@ -155,7 +155,7 @@ import { MathWizHeader } from '@mathwiz/ui-components';
 npm install @mathwiz/ui-components
 
 # 安装必需的第三方依赖
-npm install @heroui/react@^2.8.4
+npm install @heroui/react@^2.8.7
 npm install lucide-react@^0.541.0
 npm install zustand@^5.0.8
 ```
@@ -163,7 +163,7 @@ npm install zustand@^5.0.8
 ### 必需依赖说明
 
 #### HeroUI 依赖
-- **版本**: `@heroui/react@^2.8.4`
+- **版本**: `@heroui/react@^2.8.7`
 - **作用**: 提供基础 UI 组件和样式系统
 - **必需**: 所有组件都依赖 HeroUI 的样式和主题系统
 
@@ -362,50 +362,82 @@ function CustomThemeApp() {
 }
 ```
 
-### CSS 自动注入功能 (v0.1.6+)
+## 🎯 样式系统与引入指南 (v0.1.20+)
 
-从版本 0.1.6 开始，组件库使用 CSS 自动注入技术，所有样式会自动注入到 JavaScript bundle 中：
+### 核心原则
+组件库采用 **责任分层** 样式架构，确保样式可控、无冲突：
 
-#### 技术实现
-- 使用 `vite-plugin-css-injected-by-js` 插件
-- 运行时自动创建 `<style>` 标签并注入 CSS 内容
-- 包含完整的 CSS 变量系统（设计令牌）
-- 所有组件样式自动加载
+1. **组件库不打包第三方样式**：只输出自有样式
+2. **组件库不包含全局样式重置**：避免与业务项目样式冲突
+3. **业务项目全权控制样式引入**：自行决定引入哪些第三方样式及其版本
+4. **明确的依赖声明**：通过文档和开发环境警告提示必要依赖
 
-#### 使用优势
-- **零配置使用** - 无需额外导入 CSS 文件
-- **样式完整性** - 确保所有组件样式正确显示
-- **性能优化** - CSS 与 JavaScript 一起打包，减少 HTTP 请求
-- **主题支持** - 完整的 CSS 变量系统支持主题定制
+### 样式引入步骤
 
-#### 样式范围
-自动注入的样式包括：
-- ✅ MathWizHeader 组件样式
-- ✅ Sidebar 组件样式
-- ✅ ContentAccordion 组件样式
-- ✅ GradeUnitBrowserPage 页面样式
-- ✅ 所有基础组件样式
-- ✅ CSS 变量系统（设计令牌）
+#### 1. 安装组件库
+```bash
+npm install @mathwiz/ui-components
+```
+
+#### 2. 引入组件库样式
+在业务项目的入口文件（通常是 `main.tsx` 或 `App.tsx`）中添加：
 
-#### 使用示例
 ```typescript
-// 正确 - 无需额外导入样式，样式自动注入
-import { MathWizHeader } from '@mathwiz/ui-components';
+// 引入组件库样式
+import '@mathwiz/ui-components/style.css';
 
-// 错误 - 不需要手动导入 CSS 文件
-// import '@mathwiz/ui-components/dist/styles.css'; // 不需要
+// 引入组件库设计令牌（可选，如需主题定制）
+import '@mathwiz/ui-components/style.css?tokens';
 ```
 
-### 样式导入说明
+#### 3. 引入第三方样式依赖
+根据实际使用的组件，引入对应的第三方样式：
 
-组件库自带完整的样式系统，无需额外导入 CSS 文件：
+```typescript
+// 如果使用 EquationRender 组件（需要 KaTeX）
+import 'katex/dist/katex.min.css';
+
+// 如果使用 MathGraph 组件（需要 JSXGraph）
+import 'jsxgraph/distrib/jsxgraph.css';
 
+// 其他第三方样式...
+```
+
+#### 4. 引入业务项目自定义样式
 ```typescript
-// 正确 - 无需额外导入样式
-import { MathWizHeader } from '@mathwiz/ui-components';
+// 业务项目全局样式
+import './index.css';
+import './App.css';
+```
+
+### 样式加载顺序
+推荐加载顺序确保样式优先级正确：
+```
+业务项目入口 (main.tsx)
+├── 第三方全局样式 (katex.min.css, jsxgraph.css)
+├── 组件库样式 (style.css)
+└── 业务自定义样式
+```
+
+### 版本要求
+- **新项目**：使用 `@mathwiz/ui-components >= 0.1.21`
+- **迁移项目**：参考 `docs/样式引入指南.md`
 
-// 错误 - 不需要导入外部 CSS
-// import '@mathwiz/ui-components/dist/styles.css'; // 不需要
+### 重要版本更新
+- **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';
 ```
 
 ### 数据集成
@@ -473,7 +505,7 @@ function App() {
 ### 注意事项
 
 1. **必需包装**: 所有组件必须在 `<HeroUIProvider>` 内部使用
-2. **版本兼容**: 确保 HeroUI 版本为 `^2.8.4`
+2. **版本兼容**: 确保 HeroUI 版本为 `^2.8.7`
 3. **样式继承**: 组件库继承 HeroUI 的主题系统，支持自定义主题
 4. **类型安全**: 完整的 TypeScript 类型定义
 5. **无障碍访问**: 所有组件都支持键盘导航和屏幕阅读器
@@ -490,6 +522,47 @@ function App() {
 - 确认数据格式符合类型定义
 - 查看 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 故事结构
@@ -622,12 +695,12 @@ const preview: Preview = {
 ## 🏗️ 技术架构
 
 ### 核心依赖
-- **React**: ^18.3.1
+- **React**: ^19.1.1
 - **TypeScript**: ~5.8.3
 - **Vite**: ^7.1.2
 - **Storybook**: ^9.1.3
-- **Zustand**: ^5.0.8 (状态管理)
-- **HeroUI**: ^2.8.4 (UI 组件库)
+- **Zustand**: ^5.0.0 (状态管理)
+- **HeroUI**: ^2.8.7 (UI 组件库)
 - **Lucide React**: ^0.541.0 (图标库)
 
 ### 开发工具