create-yss-spec 2.1.9 → 2.1.11

package/template/.cursor/skills/yss-ui/assets/docs/components/monaco.md

@@ -0,0 +1,369 @@
+---
+toc: content
+---
+
+## Y-Monaco 代码编辑器
+
+基于 `monaco-editor` 的 Vue3 组件封装，支持按需加载、只读置灰、应用内全屏、语言与主题切换等能力。
+
+## 基础使用
+<code src="./demos/monaco/basic.vue"></code>
+
+## 只读（置灰）
+<code src="./demos/monaco/readonly.vue"></code>
+
+## 差异对比编辑器 (DiffEditor)
+<code src="./demos/monaco/diff-basic.vue"></code>
+
+## 应用内全屏（非浏览器全屏）
+<code src="./demos/monaco/fullscreen.vue"></code>
+
+## 可拖拽缩放
+<code src="./demos/monaco/resizable.vue"></code>
+
+## 语言与主题切换
+<code src="./demos/monaco/switch-lang-theme.vue"></code>
+
+## SQL 表/字段提示 + 格式化
+
+在传入 `sqlSchema` 后，编辑器会根据表与列提供补全
+
+```ts
+// schema 示例
+const sqlSchema = {
+  schema: 'public',
+  tables: [
+    {
+      name: 'users',
+      columns: [
+        { name: 'id', type: 'int' },
+        { name: 'name', type: 'varchar' },
+      ],
+    },
+    {
+      name: 'orders',
+      columns: [
+        { name: 'order_id', type: 'int' },
+        { name: 'user_id', type: 'int' },
+      ],
+    },
+  ],
+};
+```
+
+<code src="./demos/monaco/sql-schema.vue"></code>
+
+## 日志查看器模式
+
+启用 `logMode` 后，组件专为日志场景优化，支持增量追加、滚动触底加载、行数限制等功能，适用于实时日志流、服务日志监控等场景。
+
+### 实时日志流
+<code src="./demos/monaco/log-viewer.vue"></code>
+
+### 历史日志加载
+<code src="./demos/monaco/history-log-viewer.vue"></code>
+
+## 与 Formily 结合
+<code src="./demos/monaco/monaco.vue"></code>
+
+## API
+
+### YMonaco Props
+
+#### 基础配置
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| modelValue | `string` | `''` | 编辑器内容（支持 v-model 双向绑定） |
+| language | `string` | `'sql'` | 语法高亮语言，详见下方"语言支持" |
+| theme | `string` | `'vs'` | 编辑器主题：`vs`（明亮）/ `vs-dark`（深色）/ `hc-black`（高对比度） |
+| width | `number \| string` | `'100%'` | 编辑器宽度，支持数字（px）或 CSS 字符串 |
+| height | `number \| string` | `300` | 编辑器高度，支持数字（px）或 CSS 字符串 |
+| options | `Record<string, unknown>` | `{}` | Monaco Editor 原生配置选项（会与默认配置合并） |
+| readonly | `boolean` | `false` | 是否只读（只读模式下内容置灰，无法编辑） |
+| autoLayout | `boolean` | `true` | 是否自动布局（容器尺寸变化时自动调整编辑器） |
+| showBorder | `boolean` | `true` | 是否显示组件边框 |
+| nls | `boolean` | `false` | 是否启用中文本地化（按需加载 `monaco-editor-nls`） |
+
+#### 全屏与缩放
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| fullscreenTarget | `string \| HTMLElement` | `document.documentElement` | 应用内全屏时的目标容器（选择器字符串或 DOM 元素），默认填充整个视口 |
+| resizable | `boolean` | `true` | 是否启用容器拖拽缩放功能 |
+| resizeDirections | `Array<'e' \| 's' \| 'se'>` | `['se','e','s']` | 允许的拖拽方向：`e`（右边）、`s`（下边）、`se`（右下角） |
+| minWidth | `number` | `240` | 拖拽时的最小宽度（像素） |
+| minHeight | `number` | `160` | 拖拽时的最小高度（像素） |
+| maxWidth | `number` | `-` | 拖拽时的最大宽度（像素），不设置则不限制 |
+| maxHeight | `number` | `-` | 拖拽时的最大高度（像素），不设置则不限制 |
+| freeHeightResize | `boolean` | `true` | 高度拖拽是否不受父容器限制（true 时仅受 min/maxHeight 约束） |
+
+#### SQL 模式
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| sqlSchema | `SqlSchema` | `-` | SQL 表/字段提示数据源，详见下方"SqlSchema 类型" |
+| sqlSuggest | `boolean` | `true` | 是否启用 SQL 智能提示（表名、字段名补全） |
+
+#### 日志查看器模式
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| logMode | `boolean` | `false` | 是否启用日志查看器模式（支持增量追加、滚动触底加载、行数限制） |
+| maxLines | `number` | `10000` | 日志模式下的最大保留行数，超出时自动删除头部旧日志（建议 5000-20000） |
+| scrollThreshold | `number` | `50` | 滚动触底检测阈值（行数），距底部小于此值时触发 `scroll-end` 事件 |
+| autoScroll | `boolean` | `true` | 追加内容后是否自动滚动到底部（仅当用户在底部附近时生效） |
+
+#### 工具栏配置
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| showToolbar | `boolean` | `true` | 是否显示悬浮工具栏 |
+| toolbarOptions | `object` | `{ copy: true, fullscreen: true, download: false }` | 工具栏按钮开关：`copy` (复制), `fullscreen` (全屏), `download` (下载) |
+
+---
+
+### 插槽 (Slots)
+
+| 插槽名 | 说明 | 参数 |
+| --- | --- | --- |
+| toolbar | 自定义工具栏的**全部内容**，这将完全替换默认的按钮。 | `{ editor, fullscreen, toggleFullscreen }` |
+| toolbar-prefix | 在默认按钮（复制、全屏、下载）**之前**插入自定义内容，保留默认按钮。 | `{ editor, fullscreen, toggleFullscreen }` |
+| toolbar-suffix | 在默认按钮（复制、全屏、下载）**之后**插入自定义内容，保留默认按钮。 | `{ editor, fullscreen, toggleFullscreen }` |
+
+**示例**：
+
+```html
+<YMonaco>
+  <!-- 前置按钮 -->
+  <template #toolbar-prefix>
+    <y-button>前置操作</y-button>
+  </template>
+
+  <!-- 默认按钮（复制/全屏）会自动显示在中间 -->
+
+  <!-- 后置按钮 -->
+  <template #toolbar-suffix>
+    <y-button>后置操作</y-button>
+  </template>
+</YMonaco>
+```
+
+**完全自定义示例 (覆盖默认)**
+
+```html
+<YMonaco>
+  <template #toolbar="{ editor, fullscreen, toggleFullscreen }">
+    <y-button @click="myCustomAction(editor)">自定义按钮</y-button>
+    <y-button @click="toggleFullscreen">
+      {{ fullscreen ? '退出全屏' : '全屏' }}
+    </y-button>
+  </template>
+</YMonaco>
+```
+
+---
+
+### 语言支持（language 可选值）
+
+Monaco Editor 支持丰富的编程语言语法高亮和智能提示：
+
+#### 常用语言
+- **Web 开发**：`javascript`、`typescript`、`html`、`css`、`scss`、`less`、`json`、`xml`、`markdown`
+- **数据库**：`sql`、`mysql`、`pgsql`、`redis`、`graphql`
+- **配置文件**：`yaml`、`ini`、`dockerfile`、`shell`、`bat`、`powershell`
+- **后端语言**：`python`、`java`、`go`、`csharp`、`cpp`、`php`、`ruby`、`rust`、`scala`、`swift`、`kotlin`、`lua`
+
+#### 增强功能
+- **SQL**：内置表/字段智能提示、格式化兜底（右键菜单）
+- **JSON**：内置格式化功能
+- **JavaScript / TypeScript**：自动加载 Language Service，提供高级智能提示
+
+#### 完整列表
+所有语言与 Monaco 的 [basic-languages](https://github.com/microsoft/monaco-editor/tree/main/src/basic-languages) 同名即可按需加载。
+
+---
+
+### 事件
+
+| 事件名 | 参数 | 说明 |
+| --- | --- | --- |
+| update:modelValue | `value: string` | 内容变化时触发（v-model 同步） |
+| change | `value: string` | 内容变化时触发（与 update:modelValue 同时触发） |
+| blur | `{ editor, monaco }` | 编辑器失焦时触发，返回编辑器实例和 Monaco API |
+| selectedText | `(text: string, selection: any)` | 选中文本变化时触发，返回选中的文本和选区对象 |
+| run | `{ sql: string; isAll: boolean }` | SQL 模式专用：右键菜单选择"运行 SQL"或按 Ctrl/Cmd+Enter 时触发 |
+| scroll-end | `-` | 日志模式专用：滚动到底部时触发（可用于懒加载更多日志） |
+| line-exceed | `lines: number` | 日志模式专用：日志行数超出 `maxLines` 限制时触发 |
+
+---
+
+### 实例方法（通过 ref 调用）
+
+| 方法名 | 参数 | 返回值 | 说明 |
+| --- | --- | --- | --- |
+| getInstance | - | `editor \| null` | 获取 Monaco Editor 原生实例 |
+| setValue | `value: string` | `void` | 设置编辑器内容（会触发 change 事件） |
+| setLanguage | `lang: string` | `void` | 切换语法高亮语言 |
+| setTheme | `theme: string` | `void` | 切换编辑器主题 |
+| toggleReadonly | `readonly?: boolean` | `void` | 切换只读状态（不传参则反转当前状态） |
+| toggleFullscreen | - | `void` | 切换应用内全屏（非浏览器全屏 API） |
+| insertText | `text: string` | `void` | 在当前光标位置插入文本（使用 snippet 机制） |
+| insertTextAtPosition | `text: string` | `void` | 在当前光标位置插入文本 |
+| layout | - | `void` | 手动触发编辑器布局重计算（容器尺寸变化时） |
+| appendContent | `text: string` | `void` | **日志模式专用**：在末尾追加内容（增量追加，性能优于 setValue） |
+| clearContent | - | `void` | **日志模式专用**：清空编辑器内容 |
+| scrollToBottom | - | `void` | **日志模式专用**：滚动到编辑器底部 |
+| getLineCount | - | `number` | **日志模式专用**：获取当前总行数 |
+
+---
+
+### 类型定义
+
+#### SqlSchema
+
+用于 SQL 模式的表/字段智能提示：
+
+```typescript
+interface SqlSchema {
+  schema?: string;  // 可选的 schema 名称（如 "public"）
+  tables: Array<{
+    name: string;  // 表名（可含 schema 前缀，如 "public.users"）
+    columns: Array<{
+      name: string;     // 字段名
+      type?: string;    // 字段类型（可选）
+      comment?: string; // 字段注释（可选）
+    }>;
+  }>;
+}
+```
+
+**使用示例**：
+```typescript
+const sqlSchema = {
+  schema: 'public',
+  tables: [
+    {
+      name: 'users',
+      columns: [
+        { name: 'id', type: 'int', comment: '用户ID' },
+        { name: 'name', type: 'varchar(100)' },
+        { name: 'email', type: 'varchar(255)' },
+      ],
+    },
+    {
+      name: 'orders',
+      columns: [
+        { name: 'order_id', type: 'int' },
+        { name: 'user_id', type: 'int' },
+        { name: 'amount', type: 'decimal(10,2)' },
+      ],
+    },
+  ],
+};
+```
+
+---
+
+## YMonacoDiff (差异对比编辑器)
+
+### Diff Props
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| original | `string` | `''` | 原始内容（左侧显示） |
+| value | `string` | `''` | 修改后内容（右侧显示，支持 v-model:value 双向绑定） |
+| **其余属性** | - | - | 继承 `YMonaco` 的所有配置（除 `modelValue` 外） |
+
+### Diff 事件
+
+| 事件名 | 参数 | 说明 |
+| --- | --- | --- |
+| update:value | `value: string` | 修改后内容变化时触发（v-model:value 同步） |
+| change | `value: string` | 修改后内容变化时触发 |
+
+### Diff 实例方法
+
+| 方法名 | 参数 | 返回值 | 说明 |
+| --- | --- | --- | --- |
+| getInstance | - | `diffEditor \| null` | 获取 Monaco DiffEditor 原生实例 |
+| setOriginal | `value: string` | `void` | 设置原始内容（左侧） |
+| setValue | `value: string` | `void` | 设置修改后内容（右侧） |
+| setLanguage | `lang: string` | `void` | 切换两侧编辑器的语言 |
+| setTheme | `theme: string` | `void` | 切换两侧编辑器的主题 |
+| layout | - | `void` | 手动触发布局重计算 |
+
+---
+
+## 使用技巧
+
+### 1. 日志查看器最佳实践
+
+```
+<template>
+  <YMonaco
+    ref="logViewer"
+    log-mode
+    :max-lines="5000"
+    :auto-scroll="true"
+    language="shell"
+    theme="vs-dark"
+    :readonly="true"
+    @scroll-end="loadMoreLogs"
+  />
+</template>
+
+<script setup>
+const logViewer = ref();
+const loadMoreLogs = async () => {
+  const logs = await fetchLogsFromServer();
+  logViewer.value.appendContent(logs.join('\n'));
+};
+</script>
+```
+
+### 2. SQL 编辑器配置
+
+```
+<YMonaco
+  v-model="sqlCode"
+  language="sql"
+  :sql-schema="tableSchema"
+  :options="{
+    fontSize: 14,
+    minimap: { enabled: false },
+    formatOnPaste: true,
+  }"
+  @run="handleRunSql"
+/>
+```
+
+### 3. 响应式布局
+
+组件默认开启 `autoLayout`，容器尺寸变化时会自动重新布局。如需手动控制，可调用 `layout()` 方法。
+
+### 4. 全屏模式
+
+- **应用内全屏**：使用 `toggleFullscreen()` 方法，编辑器固定定位填充目标容器
+- **非浏览器全屏**：不依赖 Fullscreen API，兼容性更好
+- **自定义目标**：通过 `fullscreenTarget` 指定全屏区域
+
+---
+
+## 注意事项
+
+1. **CSS 导入**：Monaco 编辑器的 CSS 需要在主项目中全局导入一次：
+   ```ts
+   import 'monaco-editor/min/vs/editor/editor.main.css';
+   ```
+
+2. **Worker 加载**：✅ 组件库已内置 Worker 本地加载支持，**无需任何配置**即可在内网环境使用。
+
+3. **性能优化**：
+   - 日志模式下建议使用 `appendContent` 而非 `setValue`
+   - 启用 `autoLayout` 时避免频繁改变容器尺寸
+   - 超大文件（>100MB）建议设置 `autoLayout: false` 并手动调用 `layout()`
+
+4. **主题切换**：切换主题后会立即生效，无需重新创建编辑器实例
+
+5. **只读模式**：只读模式下仍可通过 `setValue` 或 `appendContent` 方法修改内容

package/template/.cursor/skills/yss-ui/assets/docs/components/sheet.md

@@ -0,0 +1,169 @@
+---
+toc: content
+---
+
+# Sheet 协同表格
+
+YSheet 是基于 [Univer](https://univer.ai/) 封装的电子表格组件，提供类似 Excel 的编辑体验。
+
+## 基础用法
+
+<code id="demo-sheet-basic" src="./demos/sheet/basic/index.vue"></code>
+
+## API
+
+### Props
+
+| 参数 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| modelValue | 工作簿数据，支持 v-model 双向绑定 | `IWorkbookData` | - |
+| height | 容器高度 | `string \| number` | `'100%'` |
+| locale | 语言配置 | `'zh-CN' \| 'en-US'` | `'zh-CN'` |
+| darkMode | 是否启用暗黑模式 | `boolean` | `false` |
+| config | Univer 核心配置 (IUniverSheetsCorePresetConfig) | `Partial<Config>` | `{ header: true, toolbar: true, footer: {}, contextMenu: true, formulaBar: true }` |
+| readonly | 是否只读模式 | `boolean` | `false` |
+| extraPresets | 额外的 Preset 包 | `any[]` | `[]` |
+| extraPlugins | 额外的插件 | `any[]` | `[]` |
+| extraLocales | 额外的语言包 | `Record<string, any>` | `{}` |
+| permissionConfig | 权限管控配置 | `IPermissionConfig` | - |
+| collaborationConfig | 协同编辑配置 | `ICollaborationConfig` | - |
+
+### Config 配置详解
+
+`config` 属性透传给 `UniverSheetsCorePreset`，支持其所有配置项。以下列出常用配置：
+
+```typescript
+interface IUniverSheetsCorePresetConfig {
+  /** 容器元素 (内部自动处理) */
+  container: HTMLElement;
+  /** 是否显示头部 (默认 true) */
+  header?: boolean;
+  /** 是否显示工具栏 (默认 true) */
+  toolbar?: boolean;
+  /** 是否显示底部状态栏/SheetBar (默认 {}) */
+  footer?: boolean | {
+    sheetBar?: boolean;
+    statisticBar?: boolean;
+    menus?: boolean;
+    zoomSlider?: boolean;
+  };
+  /** 是否显示右键菜单 (默认 true) */
+  contextMenu?: boolean;
+  /** 是否显示公式栏 (默认 true) */
+  formulaBar?: boolean;
+  /** 菜单配置 (用于隐藏/禁用菜单项) */
+  menu?: Record<string, MenuItemConfig>;
+  /** 表格特有配置 */
+  sheets?: {
+    /** 保护区域阴影策略 */
+    protectedRangeShadow?: boolean | 'always' | 'non-editable' | 'non-viewable' | 'none';
+    [key: string]: any;
+  };
+  [key: string]: any;
+}
+```
+
+#### 配置示例
+
+```html
+<YSheet
+  :config="{
+    header: false, // 隐藏头部
+    sheets: {
+      protectedRangeShadow: false // 隐藏保护区域阴影
+    },
+    menu: {
+      'sheet.contextMenu.permission': { hidden: true } // 隐藏特定的右键菜单
+    }
+  }"
+/>
+```
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| update:modelValue | 数据变化时触发 | `(value: IWorkbookData) => void` |
+| workbook-created | 工作簿创建完成时触发 | `(workbook: Workbook) => void` |
+| error | 错误回调 | `(error: Error) => void` |
+
+### Methods
+
+通过 `ref` 可以获取到组件实例并调用以下方法：
+
+| 方法名 | 说明 | 参数 | 返回值 |
+| --- | --- | --- | --- |
+| getUniverAPI | 获取 Univer Facade API 实例 | - | `FUniver \| null` |
+| getWorkbook | 获取当前工作簿 | - | `Workbook` |
+| save | 保存数据 | - | `IWorkbookData \| null` |
+| reload | 重新加载数据 | `(data: IWorkbookData) => void` | - |
+| dispose | 销毁实例 | - | - |
+
+## IWorkbookData 数据结构
+
+```typescript
+interface IWorkbookData {
+  id: string                    // 工作簿 ID
+  name: string                  // 工作簿名称
+  locale: 'zh-CN' | 'en-US'     // 语言
+  sheetOrder: string[]          // Sheet 顺序
+  sheets: {
+    [sheetId: string]: {
+      id: string
+      name: string
+      cellData: {
+        [row: number]: {
+          [col: number]: {
+            v: any              // 单元格值
+            s?: object          // 样式(可选)
+          }
+        }
+      }
+      rowCount: number
+      columnCount: number
+    }
+  }
+  styles?: object               // 样式定义(可选)
+}
+```
+
+## 导出包说明
+
+为了方便在业务代码中使用 Univer 的进阶功能（如绘图、公式等），组件库已内置并导出以下核心对象，**无需在项目中单独安装 `@univerjs/*` 依赖**：
+
+| 导出名 | 说明 | 来源包 |
+| --- | --- | --- |
+| `LocaleType` | 语言类型枚举 | `@univerjs/presets` |
+| `UniverSheetsDrawingPreset` | 绘图 Preset（用于图片/形状/浮动元素此等） | `@univerjs/preset-sheets-drawing` |
+| `UniverPresetSheetsDrawingZhCN` | 绘图中文语言包 | `@univerjs/preset-sheets-drawing/locales/zh-CN` |
+
+### 示例：启用绘图功能
+
+```typescript
+import {
+  YSheet,
+  UniverSheetsDrawingPreset,
+  UniverPresetSheetsDrawingZhCN,
+  LocaleType
+} from '@yss-ui/components';
+
+// 引入样式 (如果未全局引入)
+import '@univerjs/preset-sheets-drawing/lib/index.css';
+
+const extraPresets = [UniverSheetsDrawingPreset()];
+const extraLocales = {
+  [LocaleType.ZH_CN]: UniverPresetSheetsDrawingZhCN
+};
+```
+
+## 注意事项
+
+1. **容器高度**: 必须为容器设置明确的高度，否则 Univer 无法正常渲染
+2. **数据更新**: 必须通过 Facade API 更新数据，禁止直接修改 `IWorkbookData` 对象
+3. **内存管理**: 组件销毁时会自动调用 `dispose()` 方法，避免内存泄漏
+4. **依赖体积**: 该组件依赖 React、RxJS 等库，会增加约 2-3MB 的打包体积
+
+## 更多资料
+
+- [Univer 官方文档](https://docs.univer.ai/)
+- [Univer GitHub](https://github.com/dream-num/univer)

package/template/.cursor/skills/yss-ui/assets/docs/components/split-pane.md

@@ -0,0 +1,45 @@
+---
+toc: content
+---
+
+# SplitPane 分割面板
+
+可调节宽度的侧边栏分割布局组件，常用于左侧树/菜单、右侧内容的布局场景。
+
+## 典型场景：Tree + Table
+
+左侧资源树，右侧数据表格的经典后台管理布局。
+
+<code src="./demos/split-pane/tree-table-layout/index.vue"></code>
+
+## API
+
+### Props
+
+| 属性 | 说明 | 类型 | 默认值 |
+| --- | --- | --- | --- |
+| initialWidth | 初始左侧宽度（px） | `number` | `280` |
+| leftWidth | 左侧宽度（受控），可使用 `v-model:leftWidth` | `number` | - |
+| minWidth | 左侧最小宽度（px） | `number` | `200` |
+| maxWidth | 左侧最大宽度（px） | `number` | `480` |
+| collapsible | 是否可折叠 | `boolean` | `true` |
+| collapsed | 折叠状态（受控），可使用 `v-model:collapsed` | `boolean` | `false` |
+| gutterSize | 分割线宽度（px） | `number` | `6` |
+| storageKey | 本地存储 key，用于持久化宽度 | `string` | - |
+
+### Events
+
+| 事件名 | 说明 | 回调参数 |
+| --- | --- | --- |
+| update:collapsed | 折叠状态改变时触发 | `(collapsed: boolean) => void` |
+| update:leftWidth | 宽度改变时触发 | `(width: number) => void` |
+| resize | 拖拽调整宽度时触发 | `({ width: number }) => void` |
+| toggle | 点击折叠/展开时触发 | `(collapsed: boolean) => void` |
+
+### Slots
+
+| 插槽名 | 说明 |
+| --- | --- |
+| left | 左侧面板内容 |
+| right | 右侧面板内容 |
+