create-dwy 0.8.0 → 0.9.1

package/templates/claude-global/skills/dwy-eui/SKILL.md

@@ -1,230 +1,191 @@
 ---
 name: dwy-eui
-description: "@dwydev/eui Vue 3 组件库速查。当用户在使用 Vue 3 构建页面、选择 UI 组件、查询组件 API、写表单/表格/弹层/导航、配置主题或国际化、使用中后台或落地页设计规范时，**必须**使用此 skill。即使用户没有明确说'eui'，只要涉及 Vue 3 组件选型、页面布局、表单设计、数据展示、弹层交互、主题切换，也应触发。"
+description: "@dwydev/eui Vue 3 组件库使用指南。当用户在使用 Vue 3 构建页面、选择 UI 组件、查询组件 API、写表单/表格/弹层/导航、配置主题或国际化、使用中后台或落地页设计规范时，**必须**使用此 skill。即使用户没有明确说 'eui'，只要涉及 Vue 3 组件选型、页面布局、表单设计、数据展示、弹层交互、主题切换，也应触发。"
+eui_baseline_version: "2.1.0"
 ---
 
-# @dwydev/eui 组件速查
+# @dwydev/eui 组件库使用指南
 
-基于 Reka-ui 原语层 + shadcn-vue 设计风格 + Element Plus 式 API 的 Vue 3 组件库。
+Vue 3 组件库：Reka-ui 原语层 + shadcn-vue 设计风格 + Element Plus 式 API + Tailwind CSS 4。
 
-## 集成指南
+本 skill 的索引信息基于 EUI **2.1.0**。消费方项目实际版本可能不同 — 见 [版本兼容规则](#版本兼容规则)。
 
-新项目集成 EUI 时，读取 `references/eui-integration-guide.md`，包含完整的安装、Vite 配置、样式引入、组件注册、主题切换等步骤。
+---
 
-## 设计风格规范
+## 集成与设计规范
 
-- **中后台页面**：读取 `references/eui-design-guide.md`，包含颜色系统、布局规范、排版规范、组件使用规范、交互规范等。
-- **落地页/营销页**：读取 `references/eui-landing-design-guide.md`，包含 Hero、功能展示、社会证明、定价、FAQ 等 Section 模板和动画规范。
+| 场景 | 读取文件 |
+|------|---------|
+| 新项目集成 EUI | `references/eui-integration-guide.md` |
+| 中后台页面设计规范 | `references/eui-design-guide.md` |
+| 落地页/营销页设计规范 | `references/eui-landing-design-guide.md` |
 
 ---
 
-## 命名约定
+## 查 API 标准动作（核心：每次用组件前都做）
 
-- 组件前缀 `E`：`EButton`, `EInput`, `EDialog`
-- Props 类型：`E{Name}Props`（如 `EButtonProps`）
-- Events 类型：`E{Name}Emits`（如 `EInputEmits`）
-- CVA 变体：`{name}Variants`（如 `buttonVariants`）
-- 样式合并工具：`cn()` = clsx + tailwind-merge
-- 尺寸统一类型：`Size = 'sm' | 'default' | 'lg'`
+EUI 有 87 个组件目录、117 个对外组件。**本文档不再镜像 props/emits 列表** —— 因为它们会随版本漂移。AI 想用某个组件时，按下面顺序拿到精确 API：
+
+### 第一步：定位 EUI 真实版本
+
+读消费方项目的 `package.json`，找 `dependencies["@dwydev/eui"]` 或 `peerDependencies["@dwydev/eui"]`。这个版本号才是 AI 写代码的依据，不是 skill frontmatter 里的 baseline。
+
+### 第二步：读 component-manifest.json（一次拿组件地图）
+
+从 EUI 2.1.0 起，npm 包带一份组件清单：
+
+```
+<project-root>/node_modules/@dwydev/eui/dist/component-manifest.json
+```
+
+结构（精简示例）：
+```json
+{
+  "version": "2.1.0",
+  "componentToDir": { "EButton": "button", "ECommandInput": "command" },
+  "directories": {
+    "button":  { "types": "components/button/types.d.ts",  "components": ["EButton"] },
+    "command": { "types": null, "components": ["ECommand", "ECommandInput", "..."] }
+  },
+  "composables": ["useMessage", "useTheme", "..."]
+}
+```
 
-## 查阅完整 API（按需读取源码）
+用法：
+- 知道组件名（如 `EButton`） → 查 `componentToDir["EButton"]` 拿到目录 `"button"`
+- 查 `directories["button"].types` 拿到类型文件相对路径
+- 拼接：`<project-root>/node_modules/@dwydev/eui/dist/{types}` 就是要读的 .d.ts
 
-当需要某个组件的精确 props/slots/events/类型定义时，**必须**读取对应源码文件：
+manifest 不存在的回退：
+- 消费方装的是 EUI < 2.1.0（旧版本没有 manifest） → 直接走第三步用约定路径
+- 仓库无 node_modules（裸 monorepo / 未 install） → 走第三步的 dwy-shared 路径
+
+### 第三步：读组件 types.d.ts（精确 props + emits）
+
+按存在性回退：
 
 ```
-frontend/eui/src/components/{component-name}/types.ts
-frontend/eui/src/components/{component-name}/EName.vue   # 模板和逻辑
+a. 优先：<project-root>/node_modules/@dwydev/eui/dist/components/{kebab}/types.d.ts
+   —— 下游消费方默认场景，含完整 props + emits + JSDoc 注释
+
+b. 次选：<dwy-shared-root>/frontend/eui/src/components/{kebab}/types.ts
+   —— 仅当在 dwy-shared monorepo 内或并列 clone 时可用，等价信息
+
+c. 都拿不到 → 退到本文档下方的 [组件目录索引](#组件目录索引)（粗略，仅做导航）
 ```
 
-组件目录清单（89 个组件）：`frontend/eui/src/components/` 下包含 button、input、table、dialog、date-picker、chart、admin-layout、ai-chat 等。不确定组件名时，先 `ls frontend/eui/src/components/` 查看。
+`{kebab}` 是目录名规则：组件名去 `E` 前缀后转 kebab-case。
+- `EButton` → `button`
+- `EDatePicker` → `date-picker`
+- `EAdminLayout` → `admin-layout`
+- `EAIChat` → `ai-chat`（连续大写视为整体）
+
+**不确定目录名时**：`ls node_modules/@dwydev/eui/dist/components/` 或 `ls frontend/eui/src/components/`，**不要靠猜**。
+
+### 第四步：slots 看 .vue 模板（不在 .d.ts 里）
+
+vue-tsc 输出的 `.d.ts` 中，slots 类型大多被擦平成 `any`。需要 slot 用法（默认插槽、具名插槽、作用域插槽）时，读源码 `.vue` 文件，搜索 `<slot` 看模板里实际定义。
+
+- node_modules 路径下 `.vue` 文件**不存在**（只有 .d.ts），slots 必须回 dwy-shared 源码看
+- 拿不到源码时：参考 reka-ui / shadcn-vue 的同名组件 slots 规范，多数 EUI 组件直接转发
+
+### 第五步：冲突时永远信 node_modules
+
+当本 SKILL.md 的描述与消费方项目的 node_modules `.d.ts` 不一致：**无条件以 node_modules 为准**。本文档是导航与心智模型，不是 API 真相。
 
 ---
 
-## 组件索引
-
-### 基础组件
-
-| 组件 | 用途 | 关键 Props |
-|------|------|-----------|
-| EButton | 按钮 | variant(default/destructive/outline/secondary/ghost/link), size(default/sm/lg/icon), loading, disabled |
-| EBadge | 标签徽章 | variant(default/secondary/destructive/outline) |
-| EAlert | 警告提示 | variant(default/destructive), title, description, closable |
-| ECard | 卡片容器 | title, description |
-| ELabel | 标签文本 | for |
-| ESeparator | 分隔线 | orientation(horizontal/vertical) |
-| ETypography | 排版文本 | variant, as |
-| EKbd | 键盘按键展示 | — |
-| ESpinner | 加载动画 | size(sm/default/lg) |
-| EProgress | 进度条 | modelValue(0-100) |
-| ESkeleton | 骨架屏 | — |
-| EEmpty | 空状态 | title, description, icon |
-| EAvatar | 头像 | src, alt, fallback, size |
-| EImage | 图片 | src, alt, fit, lazy, fallback, preview |
-
-### 表单组件
-
-| 组件 | 用途 | 关键 Props |
-|------|------|-----------|
-| EInput | 输入框 | v-model, type, placeholder, size, clearable, showPassword, disabled, readonly, maxlength, showWordLimit |
-| ETextarea | 多行输入 | v-model, placeholder, rows, autoResize, maxlength, disabled, showWordLimit, minRows, maxRows |
-| ENumberField | 数字输入 | v-model, min, max, step, size, disabled, precision, controlsPosition, placeholder, readonly |
-| ESelect | 下拉选择 | v-model, options(Option[]), placeholder, clearable, size, disabled, filterable, multiple, collapseTags, remote, remoteMethod, loading。**注意：option.value 不能为空字符串**，reka-ui 不支持 |
-| ENativeSelect | 原生 select | v-model, options(SelectOption[]), placeholder, disabled |
-| ECombobox | 组合框 | v-model, options(Option[]), placeholder, emptyText, disabled |
-| EAutocomplete | 自动补全 | v-model, fetchSuggestions(async fn), debounce, placeholder |
-| ECheckbox | 复选框 | v-model, label, disabled, indeterminate, options(Option[]), direction(horizontal/vertical), border |
-| ERadio | 单选组 | v-model, options(Option[]), direction(horizontal/vertical), disabled, optionType(default/button), border, size |
-| ESwitch | 开关 | v-model, label, size, disabled |
-| ETagsInput | 标签输入 | v-model(string[]), placeholder, max, size, disabled |
-| EDatePicker | 日期选择 | v-model, type(date/daterange/month/year), placeholder, startPlaceholder, endPlaceholder, rangeSeparator, format, clearable, disabled, disabledDate, shortcuts(DatePickerShortcut[]) |
-| ETimePicker | 时间选择 | v-model, placeholder, format, hourStep, minuteStep, disabled |
-| EColorPicker | 颜色选择 | v-model, presets(string[]), showAlpha, disabled |
-| ERate | 评分 | v-model, max, allowHalf, showText, disabled |
-| ESlider | 滑块 | v-model(number[]), min, max, step, orientation, disabled |
-| ECascader | 级联选择 | v-model, options(CascaderOption[]), placeholder, filterable, clearable, lazy, loadFn, multiple, collapseTags |
-| ETreeSelect | 树选择 | v-model, data(TreeNode[]), placeholder, multiple, checkable, disabled |
-| EMention | @提及输入 | v-model, options(MentionOption[]), prefix, loading, placeholder |
-| EInputOTP | OTP 验证码 | v-model, length, disabled, placeholder |
-| EPinInput | PIN 输入 | v-model(string[]), length, mask, otp, type(text/number) |
-| EUpload | 文件上传 | v-model(UploadFile[]), action, accept, multiple, limit, listType(text/picture/picture-card), drag, beforeUpload, autoUpload, headers, withCredentials |
-| ETransfer | 穿梭框 | v-model, data(TransferItem[]), filterable, titles([string, string]) |
-| EForm | 表单容器 | model, rules(Zod/FormRule[]), labelWidth, labelPosition(left/right/top), size, disabled, inline |
-| EFormItem | 表单项 | （配合 EForm 使用） |
-| EField | 字段布局 | orientation(vertical/horizontal/responsive), invalid |
-| EInputGroup | 输入组 | 子组件 EInputGroupAddon(align) |
-
-#### 表单强制约束
-
-**禁止使用原生 `<form>` 标签，所有表单必须使用 `<EForm>` 组件。** EForm 内置 vee-validate 校验、provide/inject 上下文传递、统一的 label 布局和 reset/validate API，原生 `<form>` 无法与 EUI 表单体系集成。
+## 版本兼容规则
 
-### 数据展示
+- 本 skill `eui_baseline_version: 2.1.0`，组件索引、composables 列表、踩坑提示都基于这个版本
+- 消费方项目用的是不同版本时（无论更新或更旧），**必须按"查 API 标准动作"流程读 .d.ts**，不要默认本文档准确
+- EUI < 2.1.0 没有 `component-manifest.json`：直接走第三步的 types.d.ts 约定路径
+- 主版本号变更（1.x → 2.x、2.x → 3.x）时，本文档的索引可能完全失效：必须先 `ls node_modules/@dwydev/eui/dist/components/` 重建认知
 
-| 组件 | 用途 | 关键 Props |
-|------|------|-----------|
-| ETable | 表格 | data, columns(TableColumn[]), loading, rowKey, striped, bordered, selectable, selectedKeys, expandable, expandedRowKeys, rowClassName, showSummary, summaryMethod, virtual, virtualRowHeight, resizable |
-| EVirtualTable | 虚拟滚动表格 | columns(VirtualTableColumn[]), data, height, estimateRowHeight, rowKey, loading |
-| EDescriptions | 描述列表 | items(DescriptionItem[]), columns, bordered, title |
-| ETimeline | 时间线 | items(TimelineItem[]), reverse |
-| EStatistic | 统计数值 | title, value, prefix, suffix, precision |
-| ETree | 树形控件 | data(TreeNode[]), v-model, checkable, expandedKeys, defaultExpandAll, lazy, loadFn, draggable, filterMethod, filterQuery, checkStrictly |
-| ECalendar | 日历 | v-model, multiple, disabled, locale, minValue, maxValue |
-| ERangeCalendar | 日期范围日历 | v-model({start, end}), disabled, locale, minValue, maxValue |
-| EPagination | 分页 | v-model, total, pageSize, showSizeChanger, pageSizes, showTotal, jumper, layout, disabled |
-| EBreadcrumb | 面包屑 | items(BreadcrumbItem[]), separator |
+---
 
-### 弹层与反馈
+## 命名约定
+
+- 组件前缀 `E`：`EButton`、`EInput`、`EDialog`
+- Props 类型：`E{Name}Props`（如 `EButtonProps`）
+- Events 类型：`E{Name}Emits`（如 `EInputEmits`）
+- CVA 变体：`{name}Variants`（如 `buttonVariants`）
+- 样式合并工具：`cn()` = clsx + tailwind-merge
+- 尺寸统一类型：`Size = 'sm' | 'default' | 'lg'`
+- 复合组件用 `provide/inject` 共享状态，子组件目录与主组件同处（如 `command/` 下含 ECommand、ECommandInput、ECommandList...）
 
-| 组件 | 用途 | 关键 Props |
-|------|------|-----------|
-| EDialog | 对话框 | v-model:open, title, description, showClose, maxWidth, draggable, closeOnClickModal, closeOnPressEscape, fullscreen, destroyOnClose。内容超出视口时 body 自动滚动，header/footer 固定。**注意：body 区域有 `overflow-y-auto`，首尾位置的 input/select 等表单控件的 focus-ring 会被裁切，需在内容区域添加 `p-1` 或 `py-1` padding 规避** |
-| EDrawer | 抽屉 | v-model:open, title, description, direction(top/right/bottom/left), showClose |
-| ESheet | 侧边面板 | v-model:open, title, description, side(top/right/bottom/left), showClose |
-| EAlertDialog | 确认对话框 | v-model:open, title, description, confirmText, cancelText |
-| ETooltip | 提示气泡 | content, side, sideOffset, delayDuration, disabled |
-| EPopover | 弹出卡片 | v-model:open, side, sideOffset, align |
-| EHoverCard | 悬停卡片 | openDelay, closeDelay |
-| EToast | 轻提示 | position, expand, richColors（配合 `toast()` 函数使用） |
-| EContextMenu | 右键菜单 | items(ContextMenuItem[]) |
+---
 
-### 导航与布局
+## 重要约束与已知陷阱
 
-| 组件 | 用途 | 关键 Props |
-|------|------|-----------|
-| ETabs | 标签页 | v-model, items(TabItem[]), closable, addable, tabPosition(top/bottom/left/right) |
-| EMenu | 侧边菜单 | v-model, items(MenuItem[]), collapsed, router, uniqueOpened, defaultOpeneds |
-| EDropdown | 下拉菜单 | items(DropdownMenuItem[]), side, align, sideOffset, trigger(click/hover), splitButton, buttonText, buttonVariant |
-| EAccordion | 手风琴 | v-model, items(AccordionItemOption[]), multiple, collapsible |
-| ECollapsible | 折叠面板 | v-model(boolean), disabled |
-| EStepper | 步骤条 | v-model, items(StepperItem[]), direction(horizontal/vertical) |
-| ECarousel | 轮播 | loop, direction, showArrows, showDots, autoplay, interval。子组件 ECarouselItem |
-| EScrollArea | 自定义滚动区 | type(auto/always/scroll/hover) |
-| EInfiniteScroll | 无限滚动 | loading, disabled, distance |
-
-### 复合组件
-
-以下组件由多个子组件组合使用，通过 `provide/inject` 共享状态：
-
-| 组件 | 子组件 | 用途 |
-|------|--------|------|
-| ECommand | ECommandInput, ECommandList, ECommandEmpty, ECommandGroup, ECommandItem, ECommandSeparator, ECommandShortcut | 命令面板（配合 useCommand） |
-| ENavigationMenu | ENavigationMenuList, ENavigationMenuItem, ENavigationMenuTrigger, ENavigationMenuContent, ENavigationMenuLink, ENavigationMenuViewport | 导航菜单 |
-| EMenubar | EMenubarMenu, EMenubarTrigger, EMenubarContent, EMenubarItem, EMenubarSeparator, EMenubarCheckboxItem, EMenubarRadioGroup, EMenubarRadioItem, EMenubarSub, EMenubarSubTrigger, EMenubarSubContent | 菜单栏 |
-| EResizable | EResizablePanelGroup(direction), EResizablePanel(defaultSize, minSize, maxSize), EResizableHandle(withHandle) | 可调整大小面板 |
-
-### 其他
-
-| 组件 | 用途 | 关键 Props |
-|------|------|-----------|
-| EConfigProvider | **必须**包裹 App 根组件，提供国际化/尺寸/层级全局配置 | size, zIndex, locale(Record, 含 name 字段为 BCP 47 语言标签，默认 zh-CN) |
-| EToggle | 切换按钮 | v-model, variant(default/outline), size, disabled |
-| EToggleGroup | 切换按钮组 | v-model, type(single/multiple), variant, size, disabled |
-| EButtonGroup | 按钮组 | orientation(horizontal/vertical) |
-| EItem | 列表项 | variant(default/outline/muted), size(default/sm), as |
-| EAspectRatio | 宽高比容器 | ratio |
-| EAffix | 固钉 | offset, position(top/bottom) |
-| EWatermark | 水印 | content, fontSize, rotate, gap, opacity |
-| EChartContainer | 图表容器 | config(ChartConfig), id |
+源码读不出来的"踩坑经验"，每次写 EUI 代码都遵守：
 
-### 业务组件
+### 表单
+- **禁止用原生 `<form>` 标签**，所有表单必须用 `<EForm>`。EForm 内置 vee-validate 校验、provide/inject 上下文、统一 label 布局和 reset/validate API，原生 `<form>` 无法集成
+- `ESelect` 的 `option.value` **不能为空字符串**，reka-ui 不支持
+- 表单校验优先用 zod schema 传给 `EForm` 的 `rules` prop
+
+### 弹层
+- `EDialog` body 区域有 `overflow-y-auto`，**首尾位置的 input/select 等表单控件的 focus-ring 会被裁切**。规避：在内容区域加 `p-1` 或 `py-1` padding
+- 弹层组件统一用 `v-model:open` 控制显隐，不要用 `:visible` / `@update:visible`
+
+### reka-ui 绑定约定
+- 封装 reka-ui 组件时统一用 `v-model`（`modelValue` / `update:modelValue`），**不是** `:checked` / `@update:checked`
+- 自己写组件包 reka-ui 原语时必须用 `v-model` 或 writable computed 绑定
+
+### 全局配置
+- `EConfigProvider` 必须包裹 App 根组件，提供国际化（locale）/ 默认尺寸 / zIndex
+- `locale.name` 字段必须是 BCP 47 语言标签（如 `zh-CN`、`en-US`），默认 `zh-CN`
 
-| 组件 | 用途 | 关键 Props |
-|------|------|-----------|
-| EDataPage | 数据列表页 | columns(TableColumn[]), fetchFn(async), searchable, pageSize。内置表格 + 分页 + 搜索 |
-| EFormDialog | 表单弹窗 | v-model:open, title, size, loading, confirmText, cancelText |
-| EConfirmDialog | 确认弹窗 | v-model:open, title, message, type(info/warning/error), confirmText, cancelText |
-| EAdminLayout | 后台管理布局 | logo, title, menuItems(MenuItem[]), v-model:activeKey, v-model:collapsed, headerHeight, sidebarWidth |
-| EAIChat | AI 对话 | messages(ChatMessage[]), loading, placeholder |
-| ETimetableGrid | 课程表/时间表 | data(TimetableItem[]), startHour, endHour, days |
+### 样式
+- 使用 `cn()` 合并 Tailwind 类名（解决冲突）：`cn('px-2 py-1', isActive && 'bg-primary text-white', className)`
+- 主题切换通过 `useTheme()` 的 `setColorTheme()` / `toggleDark()`，**不要**手动操作 `<html class="dark">`
 
 ---
 
-## Composables
+## Composables 速查
 
-| Composable | 用途 | 返回值 |
-|------------|------|--------|
-| useMessage() | 全局消息提示 | { success, warning, error, info } — 每个接收 string 或 MessageOptions |
-| useNotification() | 通知 | { success, warning, error, info } — 接收 NotificationOptions(title, message, position, duration, onClick, closable) |
-| useMessageBox() | 对话确认 | { alert, confirm, prompt } — 返回 Promise<'confirm' \| 'cancel'> |
-| useToast() | Toast 通知（与 EToast 组件配合使用） | { toast, dismiss, toasts } — toast 接收 ToastOptions(title, description, variant) |
-| useTheme() | 主题管理 | { isDark, theme, setTheme, toggleDark, colorTheme, setColorTheme } |
-| useConfigProvider() | 读取全局配置 | { size, zIndex, locale } |
-| useFormField() | 表单字段上下文 | { id, name, formItemId, valid, isDirty, isTouched, error }（需在 FormField 内使用） |
-| useSecureValue() | 敏感输入安全绑定 | { isComposing, recordCursor, setCursor, setNativeValue, onCompositionStart, onCompositionEnd } — 通过 DOM property 赋值避免密码泄露到 HTML attribute |
+| Composable | 用途 |
+|------------|------|
+| `useMessage()` | 全局消息提示（success / warning / error / info） |
+| `useNotification()` | 通知（含 title / message / position / duration） |
+| `useMessageBox()` | 对话确认（alert / confirm / prompt），返回 Promise |
+| `useTheme()` | 主题管理（isDark / setTheme / setColorTheme / toggleDark） |
+| `useConfigProvider()` | 读取全局配置（size / zIndex / locale） |
+| `useFormField()` | 表单字段上下文（id / name / valid / error），需在 FormField 内使用 |
+| `useSecureValue()` | 敏感输入安全绑定（DOM property 赋值，避免密码泄露到 HTML attribute） |
+
+精确签名读 `<project-root>/node_modules/@dwydev/eui/dist/composables/{name}.d.ts`。
+
+---
 
 ## 主题系统
 
-- **Design Tokens**: CSS 自定义属性，定义在 `tokens.css`，前缀 `--`（如 `--primary`, `--background`）
-- **暗色模式**: `dark.css`，通过 `<html class="dark">` 切换
-- **色彩主题**: 7 种（neutral/blue/green/rose/orange/violet/slate），通过 `useTheme().setColorTheme()` 切换
-- **样式工具**: 使用 `cn()` 合并 Tailwind 类名，自动解决冲突
+- **Design Tokens**：CSS 自定义属性，定义在 `tokens.css`，前缀 `--`（如 `--primary`、`--background`）
+- **暗色模式**：`dark.css`，通过 `<html class="dark">` 切换（用 `useTheme().toggleDark()`，不手写）
+- **色彩主题**：7 种（neutral / blue / green / rose / orange / violet / slate），通过 `useTheme().setColorTheme()` 切换
+- 样式入口：`import '@dwydev/eui/theme'`
 
-```ts
-import { cn } from '@dwydev/eui'
-cn('px-2 py-1', isActive && 'bg-primary text-white', className)
-```
+---
 
-## 通用类型
+## 通用类型速查
+
+精确定义读 `<project-root>/node_modules/@dwydev/eui/dist/types.d.ts`。常用：
 
 ```ts
 type Size = 'sm' | 'default' | 'lg'
 
 interface Option {
   label: string
-  value: string | number
+  value: string | number  // ⚠️ 不能为空字符串
   disabled?: boolean
 }
 
-interface GroupedOption {
-  label: string
-  options: Option[]
-}
-
 interface MenuItem {
   key: string
   label: string
   icon?: string
-  /** Route path for router mode (falls back to key if not provided) */
-  path?: string
+  path?: string           // router 模式下的路由路径
   children?: MenuItem[]
   disabled?: boolean
 }
@@ -239,13 +200,134 @@ interface TableColumn<T = any> {
   align?: 'left' | 'center' | 'right'
   render?: (row: T, index: number) => any
 }
+```
 
-type DatePickerType = 'date' | 'daterange' | 'month' | 'year'
+---
 
-interface DatePickerShortcut {
-  text: string
-  value: Date | Date[] | (() => Date | Date[])
-}
+## 组件目录索引
+
+按用途分类的导航表，**只提供组件名 + 一句话用途**，精确 props/emits 一律按 [查 API 标准动作](#查-api-标准动作核心每次用组件前都做) 读 `types.d.ts`。
+
+### 基础展示
+
+| 组件 | 用途 |
+|------|------|
+| `EButton` | 按钮（含 loading 状态） |
+| `EButtonGroup` | 按钮组 |
+| `EBadge` | 标签徽章 |
+| `EAlert` | 警告提示 |
+| `ECard` | 卡片容器 |
+| `ELabel` | 标签文本 |
+| `ESeparator` | 分隔线 |
+| `ETypography` | 排版文本 |
+| `EKbd` | 键盘按键展示 |
+| `ESpinner` | 加载动画 |
+| `EProgress` | 进度条 |
+| `ESkeleton` | 骨架屏 |
+| `EEmpty` | 空状态 |
+| `EAvatar` | 头像 |
+| `EImage` | 图片（含懒加载/预览） |
+| `EAspectRatio` | 宽高比容器 |
+| `EAffix` | 固钉 |
+| `EWatermark` | 水印 |
+
+### 表单输入
+
+| 组件 | 用途 |
+|------|------|
+| `EForm` / `EFormItem` | 表单容器与表单项（必用，禁用原生 form） |
+| `EField` | 字段布局（垂直/水平/响应式） |
+| `EInput` | 输入框（含 password / clearable / 字数统计） |
+| `EInputGroup` | 输入组（含 prefix/suffix addon） |
+| `ETextarea` | 多行输入（含自适应高度） |
+| `ENumberField` | 数字输入 |
+| `ESelect` | 下拉选择（option.value ≠ ''） |
+| `ENativeSelect` | 原生 select |
+| `ECombobox` | 组合框（可输入下拉） |
+| `EAutocomplete` | 自动补全 |
+| `ECheckbox` | 复选框/复选组 |
+| `ERadio` | 单选组 |
+| `ESwitch` | 开关 |
+| `ETagsInput` | 标签输入 |
+| `EDatePicker` | 日期/范围/月/年选择 |
+| `ETimePicker` | 时间选择 |
+| `EColorPicker` | 颜色选择 |
+| `ERate` | 评分 |
+| `ESlider` | 滑块 |
+| `ECascader` | 级联选择 |
+| `ETreeSelect` | 树选择 |
+| `EMention` | @提及输入 |
+| `EInputOTP` | OTP 验证码 |
+| `EPinInput` | PIN 输入 |
+| `EUpload` | 文件上传（含拖拽/图片墙） |
+| `ETransfer` | 穿梭框 |
 
-type TabPosition = 'top' | 'bottom' | 'left' | 'right'
-```
+### 数据展示
+
+| 组件 | 用途 |
+|------|------|
+| `ETable` | 表格（含排序/选择/展开/虚拟滚动/列固定） |
+| `EVirtualTable` | 虚拟滚动表格（大数据专用） |
+| `EDescriptions` | 描述列表 |
+| `ETimeline` | 时间线 |
+| `EStatistic` | 统计数值 |
+| `ETree` | 树形控件 |
+| `ECalendar` | 日历 |
+| `ERangeCalendar` | 日期范围日历 |
+| `EPagination` | 分页 |
+| `EBreadcrumb` | 面包屑 |
+| `EChartContainer` | 图表容器 |
+
+### 弹层与反馈
+
+| 组件 | 用途 |
+|------|------|
+| `EDialog` | 对话框（v-model:open，body 区域 padding 见踩坑提示） |
+| `EDrawer` | 抽屉 |
+| `ESheet` | 侧边面板 |
+| `EAlertDialog` | 确认对话框 |
+| `ETooltip` | 提示气泡 |
+| `EPopover` | 弹出卡片 |
+| `EHoverCard` | 悬停卡片 |
+| `EToast` | 轻提示（配合 useToast / `toast()`） |
+| `EContextMenu` | 右键菜单 |
+
+### 导航与布局
+
+| 组件 | 用途 |
+|------|------|
+| `ETabs` | 标签页 |
+| `EMenu` | 侧边菜单 |
+| `EDropdown` | 下拉菜单 |
+| `EAccordion` | 手风琴 |
+| `ECollapsible` | 折叠面板 |
+| `EStepper` | 步骤条 |
+| `ECarousel` | 轮播 |
+| `EScrollArea` | 自定义滚动区 |
+| `EInfiniteScroll` | 无限滚动 |
+| `EToggle` / `EToggleGroup` | 切换按钮 |
+| `EItem` | 列表项 |
+| `EResizablePanelGroup` 等 | 可调整大小面板（复合组件） |
+
+### 复合组件（子组件需配合使用）
+
+| 主组件 | 用途 |
+|--------|------|
+| `ECommand` | 命令面板（含 ECommandInput / List / Empty / Group / Item / Separator / Shortcut） |
+| `ENavigationMenu` | 导航菜单（含 List / Item / Trigger / Content / Link / Viewport） |
+| `EMenubar` | 菜单栏（含 Menu / Trigger / Content / Item / Separator / Checkbox / Radio / Sub） |
+| `EResizable` | 可调整大小（含 PanelGroup / Panel / Handle） |
+
+复合组件的全部子组件名查 `component-manifest.json` 的 `directories[{kebab}].components`。
+
+### 业务组件
+
+| 组件 | 用途 |
+|------|------|
+| `EDataPage` | 数据列表页（内置表格 + 分页 + 搜索） |
+| `EFormDialog` | 表单弹窗 |
+| `EConfirmDialog` | 确认弹窗（类型: info / warning / error） |
+| `EAdminLayout` | 后台管理布局（顶部 + 侧边栏 + 主内容） |
+| `EAIChat` | AI 对话 |
+| `ETimetableGrid` | 课程表/时间表 |
+| `EConfigProvider` | 全局配置（必须包裹 App 根） |