ep-craft 0.1.42 → 0.2.0

package/dist-ai/components/watermark.md

@@ -0,0 +1,66 @@
+# EpWatermark
+
+`ep-watermark` · feedback（反馈） · `component:watermark`
+
+## 摘要
+
+水印，状态与结果反馈
+
+## 适用场景
+
+- 适用：展示水印并向用户传达状态
+- 适用：在操作前后提供即时反馈
+- 不适用：无需用户感知状态变化时
+- 不适用：需要完整业务弹窗流程时优先使用 Dialog
+
+## 关键词
+
+- 中文：水印、反馈
+- English: watermark, background, feedback
+
+## Props
+
+- zIndex (number，默认 9)：水印元素的 z-index
+- rotate (number，默认 -22)：水印绘制时旋转角度
+- width (number)：水印的宽度
+- height (number)：水印的高度
+- image (string)：图片源
+- content (string | string[]，默认 见文档)：水印文字内容
+- font ({ color, fontSize, fontWeight, fontFamily, fontStyle, textAlign })：文字样式
+- gap ([number, number]，默认 [100, 100])：水印之间的间距
+- offset ([number, number])：水印距离容器左上角的偏移量
+
+## Slots
+
+- default：添加水印的容器
+
+## 视觉提示
+
+- 形状：行内或块级提示
+- 密度：中等
+- 插槽内容：default：添加水印的容器
+- CSS 变量：--el-color-success、--el-color-warning、--el-color-danger、--el-font-size-base
+
+## 示例
+
+### 文字水印
+
+```vue
+<script setup lang="ts">
+import { EpWatermark } from 'ep-craft'
+</script>
+
+<template>
+  <ep-watermark content="ep-craft">
+    <div style="height: 200px">需要保护的内容区域</div>
+  </ep-watermark>
+</template>
+```
+
+## 相关条目
+
+- EpContainer
+
+---
+
+ep-craft 0.2.0

package/dist-ai/directives/click-outside.json

@@ -0,0 +1,61 @@
+{
+  "entry": {
+    "bindingForm": "v-click-outside=\"handler\"",
+    "category": "interaction",
+    "constraints": [
+      "依赖 document 上的 mousedown/mouseup 监听，仅在浏览器环境可用",
+      "通过 arg 排除触发按钮等元素，避免打开浮层后立即被判定为外部点击",
+      "回调在 mouseup 时触发，需要同时判断 mousedown 与 mouseup 的目标"
+    ],
+    "exampleOmittedReason": null,
+    "examples": [
+      {
+        "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue'\nimport { ClickOutside, EpButton } from 'ep-craft'\n\nconst vClickOutside = ClickOutside\nconst open = ref(false)\n\nconst close = () => {\n  open.value = false\n}\n</script>\n\n<template>\n  <div>\n    <ep-button @click=\"open = true\">打开面板</ep-button>\n    <div v-if=\"open\" v-click-outside=\"close\" class=\"panel\">点击面板以外区域关闭</div>\n  </div>\n</template>",
+        "id": "click-outside-1",
+        "language": "vue",
+        "title": "点击外部关闭"
+      }
+    ],
+    "exportNames": [
+      "ClickOutside"
+    ],
+    "id": "directive:click-outside",
+    "keywords": {
+      "en": [
+        "click-outside",
+        "outside-click",
+        "dismiss"
+      ],
+      "zh": [
+        "点击外部",
+        "点击空白",
+        "关闭浮层"
+      ]
+    },
+    "kind": "directive",
+    "name": "ClickOutside",
+    "options": [
+      {
+        "defaultText": null,
+        "description": "在元素外完成点击时调用",
+        "name": "handler",
+        "required": true,
+        "type": "(mouseup: MouseEvent, mousedown: MouseEvent) => void"
+      },
+      {
+        "defaultText": null,
+        "description": "排除元素，点击这些元素内部不触发回调",
+        "name": "arg",
+        "required": false,
+        "type": "HTMLElement | HTMLElement[]"
+      }
+    ],
+    "registrationName": "click-outside",
+    "serviceId": null,
+    "slug": "click-outside",
+    "summary": "点击外部指令，在目标元素外点击时触发回调"
+  },
+  "generatedAt": "2026-11-03T03:09:12.050Z",
+  "libraryVersion": "0.2.0",
+  "schemaVersion": 1
+}

package/dist-ai/directives/click-outside.md

@@ -0,0 +1,50 @@
+# ClickOutside
+
+`v-click-outside="handler"` · interaction（交互） · `directive:click-outside`
+
+## 摘要
+
+点击外部指令，在目标元素外点击时触发回调
+
+## 关键词
+
+- 中文：点击外部、点击空白、关闭浮层
+- English: click-outside, outside-click, dismiss
+
+## 绑定方式
+
+- 绑定形式：v-click-outside="handler"
+- 选项 handler（(mouseup: MouseEvent, mousedown: MouseEvent) => void，必填）：在元素外完成点击时调用
+- 选项 arg（HTMLElement | HTMLElement[]）：排除元素，点击这些元素内部不触发回调
+- 约束：依赖 document 上的 mousedown/mouseup 监听，仅在浏览器环境可用
+- 约束：通过 arg 排除触发按钮等元素，避免打开浮层后立即被判定为外部点击
+- 约束：回调在 mouseup 时触发，需要同时判断 mousedown 与 mouseup 的目标
+
+## 示例
+
+### 点击外部关闭
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { ClickOutside, EpButton } from 'ep-craft'
+
+const vClickOutside = ClickOutside
+const open = ref(false)
+
+const close = () => {
+  open.value = false
+}
+</script>
+
+<template>
+  <div>
+    <ep-button @click="open = true">打开面板</ep-button>
+    <div v-if="open" v-click-outside="close" class="panel">点击面板以外区域关闭</div>
+  </div>
+</template>
+```
+
+---
+
+ep-craft 0.2.0

package/dist-ai/directives/infinite-scroll.json

@@ -0,0 +1,83 @@
+{
+  "entry": {
+    "bindingForm": "v-infinite-scroll=\"load\"，可设置 infinite-scroll-distance / delay / disabled / immediate",
+    "category": "interaction",
+    "constraints": [
+      "内容不足一屏时会立即触发回调，必须用 disabled 或加载中状态防止重复请求",
+      "只处理向下滚动；向上滚动不会触发加载",
+      "目标元素需要处于可滚动容器中才能持续检测到底部"
+    ],
+    "exampleOmittedReason": null,
+    "examples": [
+      {
+        "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue'\nimport { vInfiniteScroll } from 'ep-craft'\n\nconst items = ref(Array.from({ length: 20 }, (_, index) => `条目 ${index + 1}`))\nconst disabled = ref(false)\n\nconst load = () => {\n  disabled.value = true\n  setTimeout(() => {\n    const start = items.value.length\n    items.value.push(...Array.from({ length: 10 }, (_, index) => `条目 ${start + index + 1}`))\n    disabled.value = false\n  }, 300)\n}\n</script>\n\n<template>\n  <div\n    v-infinite-scroll=\"load\"\n    :infinite-scroll-disabled=\"disabled\"\n    infinite-scroll-distance=\"20\"\n    style=\"height: 240px; overflow: auto\"\n  >\n    <p v-for=\"item in items\" :key=\"item\">{{ item }}</p>\n  </div>\n</template>",
+        "id": "infinite-scroll-1",
+        "language": "vue",
+        "title": "触底加载"
+      }
+    ],
+    "exportNames": [
+      "vInfiniteScroll",
+      "EpInfiniteScroll"
+    ],
+    "id": "directive:infinite-scroll",
+    "keywords": {
+      "en": [
+        "infinite-scroll",
+        "load-more",
+        "scroll"
+      ],
+      "zh": [
+        "无限滚动",
+        "加载更多",
+        "触底"
+      ]
+    },
+    "kind": "directive",
+    "name": "vInfiniteScroll",
+    "options": [
+      {
+        "defaultText": null,
+        "description": "接近底部时触发的加载回调",
+        "name": "value",
+        "required": true,
+        "type": "() => void"
+      },
+      {
+        "defaultText": "0",
+        "description": "距底部多少像素触发，通过 infinite-scroll-distance 设置",
+        "name": "distance",
+        "required": false,
+        "type": "number"
+      },
+      {
+        "defaultText": "200",
+        "description": "滚动回调的节流毫秒数，通过 infinite-scroll-delay 设置",
+        "name": "delay",
+        "required": false,
+        "type": "number"
+      },
+      {
+        "defaultText": "false",
+        "description": "是否禁用触发，通过 infinite-scroll-disabled 设置",
+        "name": "disabled",
+        "required": false,
+        "type": "boolean"
+      },
+      {
+        "defaultText": "true",
+        "description": "挂载时是否立即检查内容高度，通过 infinite-scroll-immediate 设置",
+        "name": "immediate",
+        "required": false,
+        "type": "boolean"
+      }
+    ],
+    "registrationName": "InfiniteScroll",
+    "serviceId": "service:infinite-scroll",
+    "slug": "infinite-scroll",
+    "summary": "无限滚动指令，接近底部时触发加载更多回调"
+  },
+  "generatedAt": "2026-11-03T03:09:12.050Z",
+  "libraryVersion": "0.2.0",
+  "schemaVersion": 1
+}

package/dist-ai/directives/infinite-scroll.md

@@ -0,0 +1,62 @@
+# vInfiniteScroll
+
+`v-infinite-scroll="load"，可设置 infinite-scroll-distance / delay / disabled / immediate` · interaction（交互） · `directive:infinite-scroll`
+
+## 摘要
+
+无限滚动指令，接近底部时触发加载更多回调
+
+## 关键词
+
+- 中文：无限滚动、加载更多、触底
+- English: infinite-scroll, load-more, scroll
+
+## 绑定方式
+
+- 绑定形式：v-infinite-scroll="load"，可设置 infinite-scroll-distance / delay / disabled / immediate
+- 选项 value（() => void，必填）：接近底部时触发的加载回调
+- 选项 distance（number，默认 0）：距底部多少像素触发，通过 infinite-scroll-distance 设置
+- 选项 delay（number，默认 200）：滚动回调的节流毫秒数，通过 infinite-scroll-delay 设置
+- 选项 disabled（boolean，默认 false）：是否禁用触发，通过 infinite-scroll-disabled 设置
+- 选项 immediate（boolean，默认 true）：挂载时是否立即检查内容高度，通过 infinite-scroll-immediate 设置
+- 约束：内容不足一屏时会立即触发回调，必须用 disabled 或加载中状态防止重复请求
+- 约束：只处理向下滚动；向上滚动不会触发加载
+- 约束：目标元素需要处于可滚动容器中才能持续检测到底部
+
+## 示例
+
+### 触底加载
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { vInfiniteScroll } from 'ep-craft'
+
+const items = ref(Array.from({ length: 20 }, (_, index) => `条目 ${index + 1}`))
+const disabled = ref(false)
+
+const load = () => {
+  disabled.value = true
+  setTimeout(() => {
+    const start = items.value.length
+    items.value.push(...Array.from({ length: 10 }, (_, index) => `条目 ${start + index + 1}`))
+    disabled.value = false
+  }, 300)
+}
+</script>
+
+<template>
+  <div
+    v-infinite-scroll="load"
+    :infinite-scroll-disabled="disabled"
+    infinite-scroll-distance="20"
+    style="height: 240px; overflow: auto"
+  >
+    <p v-for="item in items" :key="item">{{ item }}</p>
+  </div>
+</template>
+```
+
+---
+
+ep-craft 0.2.0

package/dist-ai/directives/loading.json

@@ -0,0 +1,89 @@
+{
+  "entry": {
+    "bindingForm": "v-loading=\"loading\" 可配合 fullscreen / lock 修饰符",
+    "category": "feedback",
+    "constraints": [
+      "修饰符 fullscreen 与 lock 分别控制全屏覆盖与滚动锁定",
+      "绑定值从 true 变为 false 时移除遮罩，组件卸载时自动清理",
+      "页面级异步流程或无法访问模板时改用 EpLoading.service"
+    ],
+    "exampleOmittedReason": null,
+    "examples": [
+      {
+        "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue'\nimport { EpButton, vLoading } from 'ep-craft'\n\nconst loading = ref(false)\n\nconst load = async () => {\n  loading.value = true\n  await new Promise((resolve) => setTimeout(resolve, 1000))\n  loading.value = false\n}\n</script>\n\n<template>\n  <div v-loading=\"loading\" style=\"min-height: 120px\">\n    <ep-button @click=\"load\">加载数据</ep-button>\n  </div>\n</template>",
+        "id": "loading-1",
+        "language": "vue",
+        "title": "局部加载"
+      },
+      {
+        "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue'\nimport { EpButton, vLoading } from 'ep-craft'\n\nconst loading = ref(false)\n</script>\n\n<template>\n  <ep-button @click=\"loading = !loading\">切换全屏加载</ep-button>\n  <div v-loading.fullscreen.lock=\"loading\" />\n</template>",
+        "id": "loading-2",
+        "language": "vue",
+        "title": "全屏加载"
+      }
+    ],
+    "exportNames": [
+      "vLoading"
+    ],
+    "id": "directive:loading",
+    "keywords": {
+      "en": [
+        "loading",
+        "spinner",
+        "mask",
+        "directive"
+      ],
+      "zh": [
+        "加载",
+        "遮罩",
+        "等待"
+      ]
+    },
+    "kind": "directive",
+    "name": "vLoading",
+    "options": [
+      {
+        "defaultText": "false",
+        "description": "是否显示加载遮罩",
+        "name": "value",
+        "required": true,
+        "type": "boolean"
+      },
+      {
+        "defaultText": "''",
+        "description": "加载图标下方的文字",
+        "name": "text",
+        "required": false,
+        "type": "string | VNode | VNode[]"
+      },
+      {
+        "defaultText": "false",
+        "description": "自定义加载图标类名",
+        "name": "spinner",
+        "required": false,
+        "type": "boolean | string"
+      },
+      {
+        "defaultText": null,
+        "description": "遮罩背景色",
+        "name": "background",
+        "required": false,
+        "type": "string"
+      },
+      {
+        "defaultText": "''",
+        "description": "加载遮罩的自定义类名",
+        "name": "customClass",
+        "required": false,
+        "type": "string"
+      }
+    ],
+    "registrationName": "loading",
+    "serviceId": "service:loading",
+    "slug": "loading",
+    "summary": "加载指令，在目标元素上显示或移除加载遮罩"
+  },
+  "generatedAt": "2026-11-03T03:09:12.050Z",
+  "libraryVersion": "0.2.0",
+  "schemaVersion": 1
+}

package/dist-ai/directives/loading.md

@@ -0,0 +1,69 @@
+# vLoading
+
+`v-loading="loading" 可配合 fullscreen / lock 修饰符` · feedback（反馈） · `directive:loading`
+
+## 摘要
+
+加载指令，在目标元素上显示或移除加载遮罩
+
+## 关键词
+
+- 中文：加载、遮罩、等待
+- English: loading, spinner, mask, directive
+
+## 绑定方式
+
+- 绑定形式：v-loading="loading" 可配合 fullscreen / lock 修饰符
+- 选项 value（boolean，必填，默认 false）：是否显示加载遮罩
+- 选项 text（string | VNode | VNode[]，默认 ''）：加载图标下方的文字
+- 选项 spinner（boolean | string，默认 false）：自定义加载图标类名
+- 选项 background（string）：遮罩背景色
+- 选项 customClass（string，默认 ''）：加载遮罩的自定义类名
+- 约束：修饰符 fullscreen 与 lock 分别控制全屏覆盖与滚动锁定
+- 约束：绑定值从 true 变为 false 时移除遮罩，组件卸载时自动清理
+- 约束：页面级异步流程或无法访问模板时改用 EpLoading.service
+
+## 示例
+
+### 局部加载
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { EpButton, vLoading } from 'ep-craft'
+
+const loading = ref(false)
+
+const load = async () => {
+  loading.value = true
+  await new Promise((resolve) => setTimeout(resolve, 1000))
+  loading.value = false
+}
+</script>
+
+<template>
+  <div v-loading="loading" style="min-height: 120px">
+    <ep-button @click="load">加载数据</ep-button>
+  </div>
+</template>
+```
+
+### 全屏加载
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { EpButton, vLoading } from 'ep-craft'
+
+const loading = ref(false)
+</script>
+
+<template>
+  <ep-button @click="loading = !loading">切换全屏加载</ep-button>
+  <div v-loading.fullscreen.lock="loading" />
+</template>
+```
+
+---
+
+ep-craft 0.2.0

package/dist-ai/directives/mousewheel.json

@@ -0,0 +1,54 @@
+{
+  "entry": {
+    "bindingForm": "v-mousewheel=\"handler\"",
+    "category": "interaction",
+    "constraints": [
+      "监听器以 passive 方式注册，回调内不能阻止默认滚动",
+      "使用 normalize-wheel-es 归一化不同浏览器的滚轮单位",
+      "需要阻止页面滚动时应使用原生事件并自行配置 passive"
+    ],
+    "exampleOmittedReason": null,
+    "examples": [
+      {
+        "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue'\nimport { Mousewheel } from 'ep-craft'\n\nconst vMousewheel = Mousewheel\nconst direction = ref('none')\n\nconst onWheel = (_event: WheelEvent, normalized: { pixelY: number }) => {\n  direction.value = normalized.pixelY > 0 ? 'down' : 'up'\n}\n</script>\n\n<template>\n  <div v-mousewheel=\"onWheel\" style=\"height: 160px; overflow: auto\">\n    <div style=\"height: 600px\">滚轮方向：{{ direction }}</div>\n  </div>\n</template>",
+        "id": "mousewheel-1",
+        "language": "vue",
+        "title": "监听滚轮方向"
+      }
+    ],
+    "exportNames": [
+      "Mousewheel"
+    ],
+    "id": "directive:mousewheel",
+    "keywords": {
+      "en": [
+        "mousewheel",
+        "wheel",
+        "scroll"
+      ],
+      "zh": [
+        "滚轮",
+        "鼠标滚轮",
+        "滚动方向"
+      ]
+    },
+    "kind": "directive",
+    "name": "Mousewheel",
+    "options": [
+      {
+        "defaultText": null,
+        "description": "滚轮事件回调，normalized 提供统一的方向与像素位移",
+        "name": "handler",
+        "required": true,
+        "type": "(event: WheelEvent, normalized: NormalizedWheelEvent) => void"
+      }
+    ],
+    "registrationName": "mousewheel",
+    "serviceId": null,
+    "slug": "mousewheel",
+    "summary": "滚轮指令，监听滚轮并返回归一化方向与位移"
+  },
+  "generatedAt": "2026-11-03T03:09:12.050Z",
+  "libraryVersion": "0.2.0",
+  "schemaVersion": 1
+}

package/dist-ai/directives/mousewheel.md

@@ -0,0 +1,48 @@
+# Mousewheel
+
+`v-mousewheel="handler"` · interaction（交互） · `directive:mousewheel`
+
+## 摘要
+
+滚轮指令，监听滚轮并返回归一化方向与位移
+
+## 关键词
+
+- 中文：滚轮、鼠标滚轮、滚动方向
+- English: mousewheel, wheel, scroll
+
+## 绑定方式
+
+- 绑定形式：v-mousewheel="handler"
+- 选项 handler（(event: WheelEvent, normalized: NormalizedWheelEvent) => void，必填）：滚轮事件回调，normalized 提供统一的方向与像素位移
+- 约束：监听器以 passive 方式注册，回调内不能阻止默认滚动
+- 约束：使用 normalize-wheel-es 归一化不同浏览器的滚轮单位
+- 约束：需要阻止页面滚动时应使用原生事件并自行配置 passive
+
+## 示例
+
+### 监听滚轮方向
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue'
+import { Mousewheel } from 'ep-craft'
+
+const vMousewheel = Mousewheel
+const direction = ref('none')
+
+const onWheel = (_event: WheelEvent, normalized: { pixelY: number }) => {
+  direction.value = normalized.pixelY > 0 ? 'down' : 'up'
+}
+</script>
+
+<template>
+  <div v-mousewheel="onWheel" style="height: 160px; overflow: auto">
+    <div style="height: 600px">滚轮方向：{{ direction }}</div>
+  </div>
+</template>
+```
+
+---
+
+ep-craft 0.2.0

package/dist-ai/directives/repeat-click.json

@@ -0,0 +1,68 @@
+{
+  "entry": {
+    "bindingForm": "v-repeat-click=\"handler\" 或 v-repeat-click=\"{ handler, interval, delay }\"",
+    "category": "interaction",
+    "constraints": [
+      "只响应鼠标左键；触摸与键盘事件不会触发",
+      "回调在按下时立即执行一次，之后按 delay 与 interval 重复",
+      "需要防抖或禁用时由业务侧控制，指令本身不提供 disabled 选项"
+    ],
+    "exampleOmittedReason": null,
+    "examples": [
+      {
+        "code": "<script setup lang=\"ts\">\nimport { ref } from 'vue'\nimport { EpButton, vRepeatClick } from 'ep-craft'\n\nconst count = ref(0)\n\nconst increase = () => {\n  count.value += 1\n}\n</script>\n\n<template>\n  <ep-button v-repeat-click=\"{ handler: increase, delay: 600, interval: 100 }\">\n    按住连续增加：{{ count }}\n  </ep-button>\n</template>",
+        "id": "repeat-click-1",
+        "language": "vue",
+        "title": "长按连续触发"
+      }
+    ],
+    "exportNames": [
+      "vRepeatClick"
+    ],
+    "id": "directive:repeat-click",
+    "keywords": {
+      "en": [
+        "repeat-click",
+        "long-press",
+        "hold"
+      ],
+      "zh": [
+        "长按",
+        "重复点击",
+        "连发"
+      ]
+    },
+    "kind": "directive",
+    "name": "vRepeatClick",
+    "options": [
+      {
+        "defaultText": null,
+        "description": "首次按下与重复触发时调用的函数",
+        "name": "handler",
+        "required": true,
+        "type": "(...args: unknown[]) => unknown"
+      },
+      {
+        "defaultText": "100",
+        "description": "重复触发的间隔毫秒数",
+        "name": "interval",
+        "required": false,
+        "type": "number"
+      },
+      {
+        "defaultText": "600",
+        "description": "首次触发后进入重复模式前的等待毫秒数",
+        "name": "delay",
+        "required": false,
+        "type": "number"
+      }
+    ],
+    "registrationName": "repeat-click",
+    "serviceId": null,
+    "slug": "repeat-click",
+    "summary": "长按重复点击指令，按住后按间隔持续触发"
+  },
+  "generatedAt": "2026-11-03T03:09:12.050Z",
+  "libraryVersion": "0.2.0",
+  "schemaVersion": 1
+}