exploria-ui-mcp-server 2.0.0

package/dist/README.md

@@ -0,0 +1,633 @@
+# Exploria UI
+
+## 项目简介
+
+🚀 下一代 Vue 3.6 + Vite UI 组件库，基于 OXC 工具链构建，采用 **Monorepo 架构**，提供丰富的组件、插件、工具和指令，满足各类业务场景需求。
+
+### 核心特性
+
+- **完整生态**：包含组件集、插件集、工具集和指令集四大核心模块
+- **组件丰富**：覆盖多种业务场景，提供高质量 UI 组件
+- **易用性强**：API 设计对齐 Element Plus，零学习成本
+- **类型安全**：TypeScript 全量类型支持
+- **性能优异**：基于 Vue 3.6 和 Vite 构建，加载速度快
+- **现代工具链**：集成 OXC 工具链，提供极速的代码检查和格式化
+
+### 架构说明
+
+本项目采用 **Monorepo 架构**，通过 pnpm 工作区管理多个包，实现代码复用、统一构建和版本管理。核心代码位于 `packages/exploria-ui/` 目录，示例应用位于 `src/` 目录，便于组件库开发和演示。
+
+### 主要开发者
+
+**作者：liketype** - 本组件库的核心开发者，微信号：yywd479
+
+## 技术栈
+
+| 类别         | 技术栈             | 说明                                |
+| ------------ | ------------------ | ----------------------------------- |
+| **框架**     | Vue 3.6            | 最新 Composition API + 性能优化     |
+| **构建工具** | Vite               | 极速的前端构建工具                  |
+| **开发语言** | TypeScript         | 类型安全的 JavaScript 超集          |
+| **样式方案** | SCSS + Animate.css | 强大的 CSS 预处理器 + 动画库        |
+| **工具链**   | OXC                | Rust 编写的极速代码检查和格式化工具 |
+
+## 核心架构
+
+Exploria UI 组件库由五个核心部分构成，形成完整的 UI 解决方案：
+
+### 1. 组件集
+
+组件集是 Exploria UI 的核心，包含丰富的 UI 组件，按功能划分为多个模块：
+
+- **基础组件**：按钮、图标、下划线、卡片、数字角标等基础 UI 元素
+- **数据组件**：表格、列表、轮播图等数据展示组件
+- **表单组件**：输入框、选择器、复选框等表单控件
+- **反馈组件**：对话框、消息提示、通知等用户反馈组件
+- **布局组件**：容器、分割线、滚动条等布局元素
+- **导航组件**：标签页、下拉菜单等导航组件
+- **高级组件**：虚拟列表、水印、滚动视差等高级功能组件
+- **3D组件**：立方体等 3D 可视化组件
+
+### 5. MCP Server
+
+MCP (Model Context Protocol) Server 是 Exploria UI 组件库的 AI 辅助服务，允许 AI 工具访问组件库的文档和 API 信息，帮助开发者更好地使用组件库。
+
+#### 功能特性
+
+- **AI 辅助开发**：让 AI 工具能够获取最新的组件文档和 API 信息
+- **实时文档访问**：AI 工具可以通过 MCP Server 实时获取组件库的最新文档
+- **标准化 API**：提供统一的 API 接口，支持多种 AI 工具集成
+- **简单易用**：配置简单，易于集成到各种开发环境
+
+#### 快速开始
+
+```bash
+# 启动 MCP Server 开发模式
+pnpm run mcp:dev
+
+# 构建 MCP Server
+pnpm run mcp:build
+
+# 启动生产模式的 MCP Server
+pnpm run mcp:start
+```
+
+#### 配置和使用
+
+1. **启动 MCP Server**：使用上述命令启动 MCP Server
+2. **访问配置页面**：在浏览器中打开文档网站，点击顶部导航栏的 "MCP Server" 选项
+3. **配置服务器地址**：在配置页面中输入 MCP Server 地址（默认：http://localhost:3000）
+4. **测试连接**：点击 "测试连接" 按钮，确保 MCP Server 运行正常
+5. **保存配置**：点击 "保存配置" 按钮保存设置
+6. **配置 AI 工具**：根据您使用的 AI 工具，添加 MCP Server 地址
+
+#### API 端点
+
+- **GET /health**：健康检查
+- **POST /mcp/query**：处理 AI 工具的查询请求
+- **GET /mcp/components**：获取组件列表
+- **GET /mcp/components/:name**：获取单个组件详情
+
+#### 示例提问
+
+```
+# 向 AI 工具提问
+"Exploria UI 的 EButton 组件有哪些属性？"
+"如何使用 Exploria UI 的 EDialog 组件？"
+"Exploria UI 的表单组件有哪些？"
+```
+
+#### 样式系统
+
+组件集内置完整的样式系统，分为主题系统和尺寸系统两大核心子系统：
+
+##### 主题系统（状态系统）
+
+主题系统定义了组件库的视觉风格和色彩方案，主要包含：
+
+- **主色调**：primaryColor
+- **次要色**：secondaryColor
+- **背景色**：backgroundColor
+- **文字色**：textColor
+- **边框色**：borderColor
+- **状态色**：successColor、warningColor、errorColor
+
+##### 尺寸系统
+
+尺寸系统定义了组件库的空间关系和视觉层次，主要包含：
+
+- **字体大小**：基础字体大小、小字体、大字体
+- **间距系统**：基础间距、小间距、大间距
+- **圆角系统**：基础圆角、小圆角、大圆角
+- **阴影系统**：基础阴影、浅阴影、深阴影
+
+##### 样式文件组织
+
+基础样式文件位于 `components/style/base/` 目录下，包含：
+`colors.scss`、`background-colors.scss`、`border-colors.scss`、`font-sizes.scss` 等。
+
+组件样式采用 SCSS 编写，使用 BEM 命名规范，通过 var 变量形式与基础样式的变量进行关联，确保样式的一致性和可维护性。
+
+组件样式文件位于 `components/style/components/` 目录下，每个组件对应一个独立的样式文件，如：
+`e-button.scss`、`e-input.scss`、`e-dialog.scss` 等。
+
+### 2. 主题定制功能
+
+Exploria UI 提供了强大的主题定制功能，支持实时调整主题变量并预览效果。主题定制功能位于 `src/views/ThemeCustomization/` 目录下，包含以下特性：
+
+- **实时预览**：修改主题变量后实时更新预览效果
+- **双系统设计**：清晰分离主题系统和尺寸系统，便于管理和定制
+- **完整的变量覆盖**：支持自定义所有核心主题和尺寸变量
+- **一键重置**：快速恢复默认主题配置
+
+#### 主题定制使用方法
+
+1. 进入主题定制页面：在示例应用中导航到「主题定制」页面
+2. 调整主题变量：在左侧表单中修改主题系统或尺寸系统的变量值
+3. 实时预览效果：右侧实时显示修改后的组件样式
+4. 重置主题：点击「重置主题」按钮恢复默认配置
+
+#### 主题变量示例
+
+```typescript
+// 主题系统示例
+primaryColor: '#409eff',      // 主色调
+secondaryColor: '#6c757d',    // 次要色
+backgroundColor: '#ffffff',   // 背景色
+textColor: '#303133',         // 文字色
+
+// 尺寸系统示例
+fontSizeBase: '14px',         // 基础字体大小
+spacingBase: '16px',          // 基础间距
+borderRadiusBase: '4px',      // 基础圆角
+boxShadowBase: '0 2px 12px 0 rgba(0, 0, 0, 0.1)',  // 基础阴影
+```
+
+### 3. 插件集
+
+插件集提供可扩展的功能模块，用于增强组件库的能力：
+
+- **SVG 精灵构建器**：自动构建 SVG 精灵图，优化图标加载
+- **图片预加载构建器**：预加载图片资源，提升用户体验
+- **SVG 兼容修复**：解决 SVG 在不同浏览器的兼容问题
+
+### 4. 工具集
+
+工具集包含各类实用工具函数，简化开发流程：
+
+- **DOM 操作工具**：便捷的 DOM 操作方法
+- **动画工具**：基于 Animate.css 的动画封装
+- **图表工具**：ECharts 图表的封装和扩展
+- **事件总线**：全局事件管理
+- **本地存储工具**：增强的 localStorage 操作
+- **时间工具**：日期时间格式化和计算
+- **UUID 工具**：生成唯一标识符
+- **图片工具**：图片处理和优化
+- **Three.js 工具**：3D 渲染相关工具
+
+### 5. 指令集
+
+指令集提供实用的 Vue 自定义指令，扩展 Vue 的能力：
+
+- **拖拽指令**：实现元素拖拽功能
+- **尺寸观察指令**：监听元素尺寸变化
+- **滑入动画指令**：元素进入视口时的动画效果
+
+## 快速开始
+
+### 前置要求
+
+- **Node.js**: `>= 20.x`
+- **pnpm**: `>= 10.x`
+
+### 安装依赖
+
+```bash
+pnpm install
+```
+
+### 开发模式
+
+```bash
+pnpm run dev
+```
+
+访问 `http://localhost:5173` 查看应用。
+
+### 生产构建
+
+```bash
+# 构建生产版本
+pnpm run build
+
+# 预览生产构建
+pnpm run preview
+```
+
+### 代码质量
+
+```bash
+# 代码检查
+pnpm run lint
+
+# 代码格式化
+pnpm run format
+```
+
+## 测试
+
+### 测试框架
+
+项目使用 [Vitest](https://vitest.dev/) 作为测试框架，提供极速的单元测试体验。
+
+### 测试命令
+
+#### 运行所有测试
+
+```bash
+pnpm test
+```
+
+#### 监视模式运行测试
+
+```bash
+pnpm test:watch
+```
+
+### 测试文件结构
+
+测试文件采用以下命名规范和目录结构：
+
+```
+└── components/
+    └── basic/
+        └── EButton/
+            ├── EButton.other          # 组件文件
+            └── __tests__/            # 测试目录（双下划线包裹，符合行业标准）
+                └── EButton.spec.ts   # 测试文件（.spec.ts 后缀）
+```
+
+### 测试执行前置条件
+
+1. **安装依赖**：确保已执行 `pnpm install` 安装所有依赖
+2. **环境要求**：Node.js >= 20.x，pnpm >= 10.x
+3. **组件结构**：被测试组件需按照标准目录结构组织
+
+### 测试结果解读
+
+运行测试后，你会看到类似以下的输出：
+
+```
+ RUN  v4.0.18 C:/Users/.../exploria-ui-document
+
+ ✓ packages/exploria-ui/src/components/basic/EButton/__tests__/EButton.spec.ts (4 tests) 39ms
+ ✓ packages/exploria-ui/src/components/basic/ESvgIcon/__tests__/ESvgIcon.spec.ts (3 tests) 29ms
+ ↓ packages/exploria-ui/src/components/advanced/EWatermark/__tests__/EWatermark.spec.ts (3 tests | 3 skipped) 10ms
+
+ Test Files  7 passed | 1 skipped (8)
+      Tests  27 passed | 3 skipped (30)
+   Start at  23:25:17
+   Duration  2.26s
+```
+
+#### 结果说明
+
+- **Test Files**：测试文件数量，包括通过和跳过的文件
+- **Tests**：测试用例数量，包括通过和跳过的用例
+- **Duration**：测试执行总时长
+- **✓**：测试通过
+- **×**：测试失败
+- **↓**：测试跳过（通常是因为环境限制，如 Canvas API 不可用）
+
+### 常见测试问题排查
+
+#### 1. 测试文件未被发现
+
+**问题**：运行测试时显示 "No test files found"
+
+**排查步骤**：
+
+- 检查测试文件是否位于 `__tests__` 目录下
+- 检查测试文件是否以 `.spec.ts` 或 `.test.ts` 结尾
+- 检查 `vitest.config.ts` 中的 `include` 配置是否正确
+
+#### 2. 组件依赖缺失
+
+**问题**：测试运行时出现 "Module not found" 错误
+
+**排查步骤**：
+
+- 确保已执行 `pnpm install` 安装所有依赖
+- 检查组件导入路径是否正确
+- 检查是否缺少必要的 peer dependencies
+
+#### 3. DOM API 不可用
+
+**问题**：测试运行时出现 "Cannot read properties of null" 或 DOM API 相关错误
+
+**排查步骤**：
+
+- 检查测试环境是否配置了 `jsdom`（已在 vitest.config.ts 中配置）
+- 对于 Canvas API 相关错误，考虑在测试中跳过或模拟 Canvas API
+
+#### 4. 测试用例失败
+
+**问题**：测试用例执行失败
+
+**排查步骤**：
+
+- 查看测试失败的详细错误信息
+- 检查组件实现是否符合预期
+- 检查测试用例的断言是否正确
+- 考虑使用 `console.log` 调试测试用例
+
+### 编写测试用例
+
+测试用例应遵循以下原则：
+
+1. **测试命名清晰**：测试用例名称应能准确描述测试内容
+2. **测试覆盖全面**：覆盖组件的主要功能和边界情况
+3. **测试独立运行**：每个测试用例应能独立运行，不依赖其他测试
+4. **测试断言明确**：使用清晰的断言语句，便于理解测试意图
+
+#### 测试用例示例
+
+```typescript
+import { mount } from '@other/test-index';
+import EButton from '../EButton.other';
+
+describe('EButton', () => {
+    it('should render correctly', () => {
+        const wrapper = mount(EButton, {
+            slots: {
+                default: 'Button',
+            },
+        });
+        expect(wrapper.text()).toBe('Button');
+    });
+
+    it('should handle click event', async () => {
+        const handleClick = vi.fn();
+        const wrapper = mount(EButton, {
+            slots: {
+                default: 'Button',
+            },
+            props: {
+                onClick: handleClick,
+            },
+        });
+        await wrapper.trigger('click');
+        expect(handleClick).toHaveBeenCalled();
+    });
+});
+```
+
+### 测试最佳实践
+
+1. **优先测试公共 API**：测试组件的公共接口，而非内部实现细节
+2. **使用快照测试**：对于 UI 组件，考虑使用快照测试确保 UI 一致性
+3. **模拟外部依赖**：对于外部依赖（如 API 调用），使用模拟（mock）避免测试依赖外部服务
+4. **保持测试简洁**：每个测试用例应只测试一个功能点
+5. **定期运行测试**：在开发过程中定期运行测试，确保代码质量
+
+## 项目结构
+
+### 根目录结构
+
+**Monorepo 架构**的核心结构如下：
+
+```
+exploria-ui-document/
+├── .cursor/                    # Cursor 编辑器配置
+├── .idea/                      # IDE 配置文件
+├── .trae/                      # Trae AI 相关配置
+│   ├── rules/                  # 项目规则配置
+│   └── skills/                 # 设计技巧和最佳实践集合
+│       ├── logicflow-instance/ # LogicFlow 实例设计技巧
+│       └── logicflow-node-resize/ # LogicFlow 节点缩放技巧
+├── dist/                       # 示例应用构建输出目录
+├── node_modules/               # 项目依赖包
+├── packages/                   # 【Monorepo核心】包目录，管理多个子包
+│   └── exploria-ui/            # Exploria UI 组件库核心包
+├── public/                     # 静态资源目录
+├── src/                        # 示例应用源码，用于组件库演示
+├── 设计稿件/                     # 设计稿目录
+├── .gitignore                  # Git 忽略配置
+├── index.html                  # 示例应用入口文件
+├── LICENSE                     # 项目许可证
+├── oxfmtrc.json                # OXC 格式化配置
+├── oxlintrc.json               # OXC 代码检查配置
+├── package.json                # 根项目配置
+├── pnpm-lock.yaml              # pnpm 依赖锁定文件
+├── pnpm-workspace.yaml         # 【Monorepo核心】pnpm 工作区配置文件
+├── README.md                   # 项目主文档
+├── tsconfig.json               # TypeScript 配置
+├── vite.config.ts              # Vite 配置
+├── vitest.config.ts            # Vitest 测试配置
+└── 一键更新网站.bat              # 网站更新脚本
+```
+
+### 核心目录说明
+
+#### 1. packages/exploria-ui/（组件库核心）
+
+```
+packages/exploria-ui/
+├── dist/                       # 组件库构建输出目录
+│   ├── components/             # 组件构建输出
+│   ├── directives/             # 指令构建输出
+│   ├── plugins/                # 插件构建输出
+│   ├── utils/                  # 工具构建输出
+│   └── index.css               # 样式输出
+├── scripts/                    # 构建脚本目录
+├── src/                        # 组件库源代码
+│   ├── components/             # 组件集
+│   ├── directives/             # 指令集
+│   ├── plugins/                # 插件集
+│   └── utils/                  # 工具集
+├── package.json                # 组件库配置
+├── README.md                   # 组件库文档
+├── tsconfig.json               # 组件库 TypeScript 配置
+└── vite.config.ts              # 组件库 Vite 配置
+```
+
+#### 2. src/（示例应用）
+
+示例应用用于演示组件库的使用，包含各种组件的示例代码和文档。
+
+#### 3. .trae/skills/（设计技巧）
+
+该目录包含项目的设计技巧和最佳实践，每个技巧以独立目录形式存在，包含详细的使用说明和示例代码。
+
+##### 现有技巧
+
+- **logicflow-instance**：LogicFlow 实例设计技巧，涵盖实例创建、数据管理、渲染优化等内容
+- **logicflow-node-resize**：LogicFlow 节点缩放技巧，提供可复用的节点缩放配置和实现方案，支持矩形、椭圆、菱形和HTML节点的缩放功能
+
+##### 技巧格式
+
+每个技巧目录包含一个 `SKILL.md` 文件，内容包括：
+
+- 功能介绍
+- 触发条件
+- 核心概念
+- 使用方法
+- 设计技巧
+- 注意事项
+- 扩展建议
+- 最佳实践
+- 常见问题与解决方案
+
+### 组件库构建输出结构
+
+组件库构建后生成的 `dist` 目录结构如下：
+
+```
+dist/
+├── components/                 # 组件集
+│   ├── advanced/              # 高级组件（虚拟列表、水印等）
+│   ├── basic/                 # 基础组件（按钮、图标等）
+│   ├── data/                  # 数据组件（表格、轮播图等）
+│   ├── feedback/              # 反馈组件（对话框、消息提示等）
+│   ├── form/                  # 表单组件（输入框、选择器等）
+│   ├── geometry/              # 几何组件
+│   ├── hooks/                 # 组件钩子函数
+│   ├── layout/                # 布局组件
+│   └── navigation/            # 导航组件（标签页等）
+├── directives/                # 指令集
+├── plugins/                   # 插件集
+├── utils/                     # 工具集
+└── index.css                  # 全局样式
+```
+
+## 组件库开发
+
+### 进入组件库目录
+
+```bash
+cd packages/exploria-ui
+```
+
+### 构建组件库
+
+```bash
+# 带监听模式构建组件库（包含组件、指令、工具函数）
+pnpm run build:watch
+
+# 带监听模式构建插件
+pnpm run build:plugins:watch
+
+# 类型检查
+pnpm run type-check
+```
+
+### 发布组件库
+
+```bash
+pnpm run pub
+```
+
+## 配置说明
+
+### OXC 配置
+
+- **oxfmtrc.json**：OXC 代码格式化配置，用于统一代码风格
+- **oxlintrc.json**：OXC 代码检查配置，用于保证代码质量
+
+### TypeScript 配置
+
+- **tsconfig.json**：项目 TypeScript 配置，支持 Vue 3 组件类型检查
+
+### Vite 配置
+
+- **vite.config.ts**：Vite 构建配置，包含组件库构建和示例应用构建配置
+
+## CSS 命名规范
+
+本项目采用 BEM (Block, Element, Modifier) 命名规范来组织 CSS 代码，特别是选择题相关组件。BEM 命名规范可以使 CSS 代码更加结构化、可维护和可扩展。
+
+### BEM 命名格式
+
+```css
+/* Block */
+.e-<component-name>
+
+/* Element */
+.e-<component-name>__<element-name>
+
+/* Modifier */
+.e-<component-name>--<modifier-name>
+.e-<component-name>__<element-name>--<modifier-name>
+```
+
+### SCSS 语法规范
+
+在 SCSS 环境下，BEM 修饰符必须使用全写形式，禁止使用嵌套的 `&--modifier` 写法。这种写法有利于代码定位和维护。
+
+#### 禁止的写法
+
+```scss
+// 禁止：嵌套的BEM修饰符
+.e-checkbox {
+    &--checked {
+        /* 选中状态样式 */
+    }
+}
+```
+
+#### 推荐的写法
+
+```scss
+// 推荐：全写的BEM选择器
+.e-checkbox {
+    /* 根元素样式 */
+}
+
+/* 复选框选中状态 */
+.e-checkbox--checked {
+    /* 选中状态样式 */
+}
+```
+
+### 选择题组件 BEM 命名示例
+
+- **复选框组件**：`.e-checkbox`
+- **复选框图标**：`.e-checkbox__icon`
+- **复选框标签**：`.e-checkbox__label`
+- **复选框选中状态**：`.e-checkbox--checked`
+- **复选框禁用状态**：`.e-checkbox--disabled`
+- **单选框组件**：`.e-radio`
+- **单选框图标**：`.e-radio__icon`
+- **单选框标签**：`.e-radio__label`
+- **单选框选中状态**：`.e-radio--checked`
+
+## 浏览器支持
+
+| 浏览器  | 最低版本 |
+| ------- | -------- |
+| Chrome  | 90+      |
+| Firefox | 88+      |
+| Safari  | 15+      |
+| Edge    | 90+      |
+
+## 贡献指南
+
+欢迎提交 Issue 和 Pull Request！请遵循以下规范：
+
+1. **代码规范**：遵循 OXC 配置
+2. **提交信息**：使用 [Conventional Commits](https://www.conventionalcommits.org/zh-hans/)
+3. **组件开发**：参考现有组件的目录结构
+4. **文档更新**：同步更新相关文档
+
+## 许可证
+
+本项目基于 [MIT License](LICENSE) 开源。
+
+## 联系方式
+
+- **作者：liketype** - 微信号：yywd479
+- 项目地址：<https://gitee.com/exploria-team/exploria-ui-example.git>
+
+---
+
+Built with ❤️ using Vue 3.6 + Vite + OXC

package/dist/components/advanced/e_parallax_scrolling/Document.vue

@@ -0,0 +1,23 @@
+<script setup lang="ts">
+import DemoBox from '@/components/DemoBox/DemoBox.vue';
+import Using from './Using.vue';
+import UsingRaw from './Using.vue?raw';
+import PageLayout from '@/components/PageLayout.vue';
+</script>
+
+<template>
+    <PageLayout>
+        <DemoBox title="介绍">
+            <h2>EParallaxScrolling 视差滚动</h2>
+            <p>
+                视差滚动组件用于在滚动页面时展示不同元素的不同滚动速度，提升用户体验。
+            </p>
+        </DemoBox>
+        <DemoBox :code="UsingRaw" title="基本用法">
+            <Using />
+            <template #description>
+                按钮有五种类型：主按钮、次按钮、虚线按钮、文本按钮和链接按钮。主按钮在同一个操作区域最多出现一次。
+            </template>
+        </DemoBox>
+    </PageLayout>
+</template>

package/dist/components/advanced/e_parallax_scrolling/Using.vue

@@ -0,0 +1,20 @@
+<script setup lang="ts">
+import { EParallaxScrolling } from 'exploria-ui';
+
+const imgList = [
+    new URL('./img.png', import.meta.url).pathname,
+    new URL('./img.png', import.meta.url).pathname,
+    new URL('./img_1.png', import.meta.url).pathname,
+    new URL('./img.png', import.meta.url).pathname,
+];
+</script>
+
+<template>
+    <EParallaxScrolling :img-list="imgList" />
+</template>
+
+<style scoped lang="scss">
+.parallax-scrolling {
+    height: 300px;
+}
+</style>

package/dist/components/advanced/e_rolling_follow/Document.vue

@@ -0,0 +1,21 @@
+<script setup lang="ts">
+import DemoBox from '@/components/DemoBox/DemoBox.vue';
+import Using from './Using.vue';
+import UsingRaw from './Using.vue?raw';
+import PageLayout from '@/components/PageLayout.vue';
+</script>
+
+<template>
+    <PageLayout>
+        <DemoBox title="介绍">
+            <h2>ERollingFollow 滚动跟随</h2>
+            <p>滚动跟随组件用于在滚动页面时，某个元素跟随滚动而滚动。</p>
+        </DemoBox>
+        <DemoBox :code="UsingRaw" title="基本用法">
+            <Using />
+            <template #description>
+                按钮有五种类型：主按钮、次按钮、虚线按钮、文本按钮和链接按钮。主按钮在同一个操作区域最多出现一次。
+            </template>
+        </DemoBox>
+    </PageLayout>
+</template>