ep-craft 0.1.42 → 0.2.0

package/dist-ai/components/cascader.json

@@ -0,0 +1,531 @@
+{
+  "entry": {
+    "category": "form",
+    "events": [
+      {
+        "description": "绑定值变化时触发",
+        "name": "update:modelValue",
+        "params": "(value: CascaderValue | null)"
+      },
+      {
+        "description": "选中值变化时触发",
+        "name": "change",
+        "params": "(value: CascaderValue | null)"
+      },
+      {
+        "description": "聚焦时触发",
+        "name": "focus",
+        "params": "(evt: FocusEvent)"
+      },
+      {
+        "description": "失焦时触发",
+        "name": "blur",
+        "params": "(evt: FocusEvent)"
+      },
+      {
+        "description": "清空时触发",
+        "name": "clear",
+        "params": "—"
+      },
+      {
+        "description": "下拉框显示/隐藏时触发",
+        "name": "visibleChange",
+        "params": "(visible: boolean)"
+      },
+      {
+        "description": "展开节点变化时触发",
+        "name": "expandChange",
+        "params": "(value: CascaderValue)"
+      },
+      {
+        "description": "移除标签时触发",
+        "name": "removeTag",
+        "params": "(value: CascaderNode[\"valueByOption\"])"
+      }
+    ],
+    "exampleOmittedReason": null,
+    "examples": [
+      {
+        "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue'\nimport { EpCascader } from 'ep-craft'\n\nconst value = ref([])\nconst options = [\n  {\n    value: 'zhejiang',\n    label: '浙江省',\n    children: [\n      { value: 'hangzhou', label: '杭州市' },\n      { value: 'ningbo', label: '宁波市' },\n    ],\n  },\n  {\n    value: 'jiangsu',\n    label: '江苏省',\n    children: [{ value: 'nanjing', label: '南京市' }],\n  },\n]\n</script>\n\n<template>\n  <ep-cascader v-model=\"value\" :options=\"options\" placeholder=\"请选择地区\" />\n</template>",
+        "id": "cascader-1",
+        "language": "vue",
+        "title": "级联选择"
+      }
+    ],
+    "exposes": [
+      {
+        "description": "获取当前选中的节点，参数 leafOnly 为是否仅返回叶子节点",
+        "name": "getCheckedNodes",
+        "type": "(leafOnly?: boolean) => CascaderNode[]"
+      },
+      {
+        "description": "级联面板实例",
+        "name": "cascaderPanelRef",
+        "type": "Ref<CascaderPanelInstance | undefined>"
+      },
+      {
+        "description": "切换下拉框显示状态",
+        "name": "togglePopperVisible",
+        "type": "(visible?: boolean) => void"
+      },
+      {
+        "description": "下拉框内容元素引用",
+        "name": "contentRef",
+        "type": "Ref<HTMLElement | undefined>"
+      },
+      {
+        "description": "当前选中值的展示文本",
+        "name": "presentText",
+        "type": "ComputedRef<string>"
+      }
+    ],
+    "hot": false,
+    "id": "component:cascader",
+    "keywords": {
+      "en": [
+        "cascader",
+        "cascade",
+        "form"
+      ],
+      "zh": [
+        "级联选择器",
+        "表单"
+      ]
+    },
+    "kind": "component",
+    "name": "EpCascader",
+    "nonUseCases": [
+      "仅展示静态文本或只读数据时"
+    ],
+    "props": [
+      {
+        "alias": null,
+        "defaultText": null,
+        "description": "输入框尺寸",
+        "hasDefault": false,
+        "name": "size",
+        "required": false,
+        "type": "'large' | 'default' | 'small'"
+      },
+      {
+        "alias": null,
+        "defaultText": null,
+        "description": "输入框占位符",
+        "hasDefault": false,
+        "name": "placeholder",
+        "required": false,
+        "type": "string"
+      },
+      {
+        "alias": null,
+        "defaultText": null,
+        "description": "是否禁用",
+        "hasDefault": true,
+        "name": "disabled",
+        "required": false,
+        "type": "boolean"
+      },
+      {
+        "alias": null,
+        "defaultText": "false",
+        "description": "是否可清空",
+        "hasDefault": false,
+        "name": "clearable",
+        "required": false,
+        "type": "boolean"
+      },
+      {
+        "alias": null,
+        "defaultText": "CircleClose",
+        "description": "自定义清空图标",
+        "hasDefault": true,
+        "name": "clearIcon",
+        "required": false,
+        "type": "string | Component"
+      },
+      {
+        "alias": null,
+        "defaultText": "false",
+        "description": "是否可搜索选项",
+        "hasDefault": false,
+        "name": "filterable",
+        "required": false,
+        "type": "boolean"
+      },
+      {
+        "alias": null,
+        "defaultText": null,
+        "description": "自定义搜索逻辑，返回是否命中",
+        "hasDefault": true,
+        "name": "filterMethod",
+        "required": false,
+        "type": "(node: CascaderNode, keyword: string) => boolean"
+      },
+      {
+        "alias": null,
+        "defaultText": "' / '",
+        "description": "选项标签分隔符",
+        "hasDefault": true,
+        "name": "separator",
+        "required": false,
+        "type": "string"
+      },
+      {
+        "alias": null,
+        "defaultText": "true",
+        "description": "输入框是否显示选中值的完整路径",
+        "hasDefault": true,
+        "name": "showAllLevels",
+        "required": false,
+        "type": "boolean"
+      },
+      {
+        "alias": null,
+        "defaultText": "false",
+        "description": "多选时是否折叠标签",
+        "hasDefault": false,
+        "name": "collapseTags",
+        "required": false,
+        "type": "boolean"
+      },
+      {
+        "alias": null,
+        "defaultText": "1",
+        "description": "折叠时最多展示的标签数，需开启 collapse-tags",
+        "hasDefault": true,
+        "name": "maxCollapseTags",
+        "required": false,
+        "type": "number"
+      },
+      {
+        "alias": null,
+        "defaultText": "false",
+        "description": "折叠标签悬停时是否展示全部标签",
+        "hasDefault": false,
+        "name": "collapseTagsTooltip",
+        "required": false,
+        "type": "boolean"
+      },
+      {
+        "alias": null,
+        "defaultText": null,
+        "description": "折叠标签提示框最大高度",
+        "hasDefault": false,
+        "name": "maxCollapseTagsTooltipHeight",
+        "required": false,
+        "type": "string | number"
+      },
+      {
+        "alias": null,
+        "defaultText": "300",
+        "description": "搜索输入防抖延迟，单位 ms",
+        "hasDefault": true,
+        "name": "debounce",
+        "required": false,
+        "type": "number"
+      },
+      {
+        "alias": null,
+        "defaultText": null,
+        "description": "搜索前的钩子，返回 false 或 reject 则中止搜索",
+        "hasDefault": true,
+        "name": "beforeFilter",
+        "required": false,
+        "type": "(value: string) => boolean | Promise<any>"
+      },
+      {
+        "alias": null,
+        "defaultText": "bottom-start",
+        "description": "下拉框位置",
+        "hasDefault": true,
+        "name": "placement",
+        "required": false,
+        "type": "string"
+      },
+      {
+        "alias": null,
+        "defaultText": "['bottom-start', 'bottom', 'top-start', 'top', 'right', 'left']",
+        "description": "下拉框备选位置",
+        "hasDefault": true,
+        "name": "fallbackPlacements",
+        "required": false,
+        "type": "string[]"
+      },
+      {
+        "alias": null,
+        "defaultText": null,
+        "description": "下拉框自定义类名",
+        "hasDefault": false,
+        "name": "popperClass",
+        "required": false,
+        "type": "string | object | array"
+      },
+      {
+        "alias": null,
+        "defaultText": null,
+        "description": "下拉框自定义样式",
+        "hasDefault": true,
+        "name": "popperStyle",
+        "required": false,
+        "type": "StyleValue"
+      },
+      {
+        "alias": null,
+        "defaultText": null,
+        "description": "是否将下拉框 teleport 到 body",
+        "hasDefault": true,
+        "name": "teleported",
+        "required": false,
+        "type": "boolean"
+      },
+      {
+        "alias": null,
+        "defaultText": "light",
+        "description": "提示框主题",
+        "hasDefault": true,
+        "name": "effect",
+        "required": false,
+        "type": "'dark' | 'light'"
+      },
+      {
+        "alias": null,
+        "defaultText": "info",
+        "description": "标签类型",
+        "hasDefault": true,
+        "name": "tagType",
+        "required": false,
+        "type": "'primary' | 'success' | 'info' | 'warning' | 'danger'"
+      },
+      {
+        "alias": null,
+        "defaultText": "light",
+        "description": "标签主题",
+        "hasDefault": true,
+        "name": "tagEffect",
+        "required": false,
+        "type": "'light' | 'dark' | 'plain'"
+      },
+      {
+        "alias": null,
+        "defaultText": "true",
+        "description": "是否触发表单校验",
+        "hasDefault": true,
+        "name": "validateEvent",
+        "required": false,
+        "type": "boolean"
+      },
+      {
+        "alias": null,
+        "defaultText": "true",
+        "description": "下拉框未激活且该值为 false 时是否销毁",
+        "hasDefault": true,
+        "name": "persistent",
+        "required": false,
+        "type": "boolean"
+      },
+      {
+        "alias": null,
+        "defaultText": "child",
+        "description": "多选时展示父节点还是子节点",
+        "hasDefault": true,
+        "name": "showCheckedStrategy",
+        "required": false,
+        "type": "'parent' | 'child'"
+      },
+      {
+        "alias": null,
+        "defaultText": "false",
+        "description": "点击节点时是否勾选/取消勾选",
+        "hasDefault": false,
+        "name": "checkOnClickNode",
+        "required": false,
+        "type": "boolean"
+      },
+      {
+        "alias": null,
+        "defaultText": "true",
+        "description": "是否显示单选/多选前缀",
+        "hasDefault": true,
+        "name": "showPrefix",
+        "required": false,
+        "type": "boolean"
+      },
+      {
+        "alias": null,
+        "defaultText": "false",
+        "description": "下拉框宽度是否与输入框一致，传数字时为固定宽度",
+        "hasDefault": false,
+        "name": "fitInputWidth",
+        "required": false,
+        "type": "boolean | number"
+      },
+      {
+        "alias": "v-model",
+        "defaultText": null,
+        "description": "绑定值",
+        "hasDefault": false,
+        "name": "modelValue",
+        "required": false,
+        "type": "CascaderValue | null"
+      },
+      {
+        "alias": null,
+        "defaultText": "[]",
+        "description": "选项数据，`value` / `label` 键名可通过 `props` 自定义",
+        "hasDefault": true,
+        "name": "options",
+        "required": false,
+        "type": "CascaderOption[]"
+      },
+      {
+        "alias": null,
+        "defaultText": "{}",
+        "description": "配置选项，见下方 `props` 说明",
+        "hasDefault": true,
+        "name": "props",
+        "required": false,
+        "type": "CascaderProps"
+      },
+      {
+        "alias": null,
+        "defaultText": "false",
+        "description": "是否启用虚拟滚动",
+        "hasDefault": false,
+        "name": "virtualScroll",
+        "required": false,
+        "type": "boolean"
+      },
+      {
+        "alias": null,
+        "defaultText": "34",
+        "description": "虚拟滚动下的节点高度",
+        "hasDefault": true,
+        "name": "itemSize",
+        "required": false,
+        "type": "number"
+      },
+      {
+        "alias": null,
+        "defaultText": "204",
+        "description": "虚拟滚动下的菜单高度",
+        "hasDefault": true,
+        "name": "height",
+        "required": false,
+        "type": "number"
+      },
+      {
+        "alias": null,
+        "defaultText": null,
+        "description": "",
+        "hasDefault": false,
+        "name": "emptyValues",
+        "required": false,
+        "type": "unknown"
+      },
+      {
+        "alias": null,
+        "defaultText": null,
+        "description": "",
+        "hasDefault": true,
+        "name": "valueOnClear",
+        "required": false,
+        "type": "unknown"
+      }
+    ],
+    "related": [
+      "EpSelect",
+      "EpCascaderPanel"
+    ],
+    "relations": {
+      "children": [
+        "EpCascaderPanel"
+      ],
+      "combos": [
+        "EpCascader + EpCascaderPanel"
+      ],
+      "parents": [],
+      "requiredChildren": []
+    },
+    "slots": [
+      {
+        "description": "自定义节点标签内容，参数为 `{ node, data }`",
+        "name": "default"
+      },
+      {
+        "description": "自定义标签内容，参数为 `{ data, deleteTag }`",
+        "name": "tag"
+      },
+      {
+        "description": "无数据时的内容",
+        "name": "empty"
+      },
+      {
+        "description": "输入框前缀内容",
+        "name": "prefix"
+      },
+      {
+        "description": "自定义搜索建议项内容，参数为 `{ item }`",
+        "name": "suggestion-item"
+      },
+      {
+        "description": "下拉面板头部",
+        "name": "header"
+      },
+      {
+        "description": "下拉面板底部",
+        "name": "footer"
+      }
+    ],
+    "slug": "cascader",
+    "summary": "级联选择器，表单数据录入控件",
+    "tag": "ep-cascader",
+    "useCases": [
+      "表单中收集或编辑级联选择器数据",
+      "与 EpForm、EpFormItem 组合完成校验"
+    ],
+    "variants": [
+      {
+        "dimension": "size",
+        "values": [
+          "large",
+          "default",
+          "small"
+        ],
+        "when": "按容器空间与信息密度选择尺寸"
+      },
+      {
+        "dimension": "state",
+        "values": [
+          "disabled"
+        ],
+        "when": "通过布尔属性切换禁用、加载或选中状态"
+      },
+      {
+        "dimension": "effect",
+        "values": [
+          "dark",
+          "light"
+        ],
+        "when": "通过视觉修饰属性调整外观效果"
+      }
+    ],
+    "visual": {
+      "cssVars": [
+        "--el-border-color",
+        "--el-border-radius-base",
+        "--el-color-primary",
+        "--el-font-size-base"
+      ],
+      "density": "中等",
+      "shape": "矩形输入框",
+      "slotContent": [
+        "default：自定义节点标签内容，参数为 `{ node, data }`",
+        "tag：自定义标签内容，参数为 `{ data, deleteTag }`",
+        "empty：无数据时的内容"
+      ]
+    }
+  },
+  "generatedAt": "2026-11-03T03:09:12.050Z",
+  "libraryVersion": "0.2.0",
+  "schemaVersion": 1
+}

package/dist-ai/components/cascader.md

@@ -0,0 +1,146 @@
+# EpCascader
+
+`ep-cascader` · form（表单） · `component:cascader`
+
+## 摘要
+
+级联选择器，表单数据录入控件
+
+## 适用场景
+
+- 适用：表单中收集或编辑级联选择器数据
+- 适用：与 EpForm、EpFormItem 组合完成校验
+- 不适用：仅展示静态文本或只读数据时
+
+## 关键词
+
+- 中文：级联选择器、表单
+- English: cascader, cascade, form
+
+## 变体
+
+- size: large/default/small（按容器空间与信息密度选择尺寸）
+- state: disabled（通过布尔属性切换禁用、加载或选中状态）
+- effect: dark/light（通过视觉修饰属性调整外观效果）
+
+## Props
+
+- size ('large' | 'default' | 'small')：输入框尺寸
+- placeholder (string)：输入框占位符
+- disabled (boolean，默认 见文档)：是否禁用
+- clearable (boolean)：是否可清空
+- clearIcon (string | Component，默认 CircleClose)：自定义清空图标
+- filterable (boolean)：是否可搜索选项
+- filterMethod ((node: CascaderNode, keyword: string) => boolean，默认 见文档)：自定义搜索逻辑，返回是否命中
+- separator (string，默认 ' / ')：选项标签分隔符
+- showAllLevels (boolean，默认 true)：输入框是否显示选中值的完整路径
+- collapseTags (boolean)：多选时是否折叠标签
+- maxCollapseTags (number，默认 1)：折叠时最多展示的标签数，需开启 collapse-tags
+- collapseTagsTooltip (boolean)：折叠标签悬停时是否展示全部标签
+- maxCollapseTagsTooltipHeight (string | number)：折叠标签提示框最大高度
+- debounce (number，默认 300)：搜索输入防抖延迟，单位 ms
+- beforeFilter ((value: string) => boolean | Promise<any>，默认 见文档)：搜索前的钩子，返回 false 或 reject 则中止搜索
+- placement (string，默认 bottom-start)：下拉框位置
+- fallbackPlacements (string[]，默认 ['bottom-start', 'bottom', 'top-start', 'top', 'right', 'left'])：下拉框备选位置
+- popperClass (string | object | array)：下拉框自定义类名
+- popperStyle (StyleValue，默认 见文档)：下拉框自定义样式
+- teleported (boolean，默认 见文档)：是否将下拉框 teleport 到 body
+- effect ('dark' | 'light'，默认 light)：提示框主题
+- tagType ('primary' | 'success' | 'info' | 'warning' | 'danger'，默认 info)：标签类型
+- tagEffect ('light' | 'dark' | 'plain'，默认 light)：标签主题
+- validateEvent (boolean，默认 true)：是否触发表单校验
+- persistent (boolean，默认 true)：下拉框未激活且该值为 false 时是否销毁
+- showCheckedStrategy ('parent' | 'child'，默认 child)：多选时展示父节点还是子节点
+- checkOnClickNode (boolean)：点击节点时是否勾选/取消勾选
+- showPrefix (boolean，默认 true)：是否显示单选/多选前缀
+- fitInputWidth (boolean | number)：下拉框宽度是否与输入框一致，传数字时为固定宽度
+- modelValue（别名 v-model） (CascaderValue | null)：绑定值
+- options (CascaderOption[]，默认 [])：选项数据，`value` / `label` 键名可通过 `props` 自定义
+- props (CascaderProps，默认 {})：配置选项，见下方 `props` 说明
+- virtualScroll (boolean)：是否启用虚拟滚动
+- itemSize (number，默认 34)：虚拟滚动下的节点高度
+- height (number，默认 204)：虚拟滚动下的菜单高度
+- emptyValues (unknown)
+- valueOnClear (unknown，默认 见文档)
+
+## Events
+
+- update:modelValue((value: CascaderValue | null))：绑定值变化时触发
+- change((value: CascaderValue | null))：选中值变化时触发
+- focus((evt: FocusEvent))：聚焦时触发
+- blur((evt: FocusEvent))：失焦时触发
+- clear(—)：清空时触发
+- visibleChange((visible: boolean))：下拉框显示/隐藏时触发
+- expandChange((value: CascaderValue))：展开节点变化时触发
+- removeTag((value: CascaderNode["valueByOption"]))：移除标签时触发
+
+## Slots
+
+- default：自定义节点标签内容，参数为 `{ node, data }`
+- tag：自定义标签内容，参数为 `{ data, deleteTag }`
+- empty：无数据时的内容
+- prefix：输入框前缀内容
+- suggestion-item：自定义搜索建议项内容，参数为 `{ item }`
+- header：下拉面板头部
+- footer：下拉面板底部
+
+## Exposes
+
+- getCheckedNodes((leafOnly?: boolean) => CascaderNode[])：获取当前选中的节点，参数 leafOnly 为是否仅返回叶子节点
+- cascaderPanelRef(Ref<CascaderPanelInstance | undefined>)：级联面板实例
+- togglePopperVisible((visible?: boolean) => void)：切换下拉框显示状态
+- contentRef(Ref<HTMLElement | undefined>)：下拉框内容元素引用
+- presentText(ComputedRef<string>)：当前选中值的展示文本
+
+## 关系
+
+- 子级：EpCascaderPanel
+- 常用组合：EpCascader + EpCascaderPanel
+
+## 视觉提示
+
+- 形状：矩形输入框
+- 密度：中等
+- 插槽内容：default：自定义节点标签内容，参数为 `{ node, data }`；tag：自定义标签内容，参数为 `{ data, deleteTag }`；empty：无数据时的内容
+- CSS 变量：--el-border-color、--el-border-radius-base、--el-color-primary、--el-font-size-base
+
+## 示例
+
+### 级联选择
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { EpCascader } from 'ep-craft'
+
+const value = ref([])
+const options = [
+  {
+    value: 'zhejiang',
+    label: '浙江省',
+    children: [
+      { value: 'hangzhou', label: '杭州市' },
+      { value: 'ningbo', label: '宁波市' },
+    ],
+  },
+  {
+    value: 'jiangsu',
+    label: '江苏省',
+    children: [{ value: 'nanjing', label: '南京市' }],
+  },
+]
+</script>
+
+<template>
+  <ep-cascader v-model="value" :options="options" placeholder="请选择地区" />
+</template>
+```
+
+## 相关条目
+
+- EpSelect
+- EpCascaderPanel
+
+---
+
+ep-craft 0.2.0