x-next 1.13.0 → 1.15.0

package/AI_USAGE/components/timeline.md

@@ -0,0 +1,312 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Timeline AI 使用
+
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
+
+先读 [通用接入](../core.md)。公开导出：`Timeline, TimelineItem`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./timeline-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/timeline`（包含 base.css、timeline.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/timeline.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./timeline-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于按时间或步骤顺序展示事件进展。
+
+
+### 何时使用
+
+- 展示项目、审批、任务、运维事件等按时间或顺序推进的记录。
+- 展示阶段性状态，并用节点颜色、图标或线型强调关键事件。
+- 需要比 Steps 更偏历史记录和详情描述的场景。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Timeline, TimelineItem } from 'x-next';
+
+</script>
+<template>
+<Timeline>
+    <TimelineItem label="2026-05-28">创建文档站</TimelineItem>
+    <TimelineItem label="2026-05-29" dot-color="#0f766e">补齐组件示例</TimelineItem>
+    <TimelineItem label="2026-06-02">审查 Timeline</TimelineItem>
+  </Timeline>
+</template>
+```
+
+### 倒序展示
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, Timeline, TimelineItem } from 'x-next';
+import { ref } from 'vue';
+
+const reverseTimeline = ref(false);
+</script>
+<template>
+<Button size="mini" @click="reverseTimeline = !reverseTimeline">
+    {{ reverseTimeline ? '恢复正序' : '切换倒序' }}
+  </Button>
+  <Timeline :reverse="reverseTimeline">
+    <TimelineItem label="09:30">提交需求</TimelineItem>
+    <TimelineItem label="11:00">完成评审</TimelineItem>
+    <TimelineItem label="16:20">发布修复</TimelineItem>
+  </Timeline>
+</template>
+```
+
+### 轴线样式
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Timeline, TimelineItem } from 'x-next';
+
+</script>
+<template>
+<Timeline line-type="dashed">
+    <TimelineItem label="阶段一">确认范围</TimelineItem>
+    <TimelineItem label="阶段二">开发联调</TimelineItem>
+    <TimelineItem label="阶段三">灰度发布</TimelineItem>
+  </Timeline>
+
+  <Timeline line-type="dotted">
+    <TimelineItem label="检查点">自动化校验</TimelineItem>
+    <TimelineItem label="检查点">人工验收</TimelineItem>
+  </Timeline>
+</template>
+```
+
+### 节点颜色
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, Timeline, TimelineItem } from 'x-next';
+import { ref } from 'vue';
+
+const dynamicDotColor = ref('#0f766e');
+
+const toggleDotColor = () => {
+  dynamicDotColor.value = dynamicDotColor.value === '#0f766e' ? '#dc2626' : '#0f766e';
+};
+</script>
+<template>
+<Button size="mini" @click="toggleDotColor">切换当前节点颜色</Button>
+  <Timeline>
+    <TimelineItem label="成功" dot-color="#16a34a">构建通过</TimelineItem>
+    <TimelineItem label="当前" :dot-color="dynamicDotColor">等待复查</TimelineItem>
+    <TimelineItem label="失败" dot-color="#dc2626">发现阻塞问题</TimelineItem>
+  </Timeline>
+</template>
+```
+
+### 自定义图标
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Timeline, TimelineItem } from 'x-next';
+
+</script>
+<template>
+<Timeline>
+    <TimelineItem label="已创建" dot-color="#16a34a">任务已进入队列</TimelineItem>
+    <TimelineItem label="处理中">
+      <template #dot>
+        <span class="timeline-demo-dot-icon">!</span>
+      </template>
+      正在处理异常分支
+    </TimelineItem>
+    <TimelineItem label="完成">等待最终确认</TimelineItem>
+  </Timeline>
+</template>
+<style scoped>
+.timeline-demo-dot-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 14px;
+  height: 14px;
+  border: 1px solid rgb(245 158 11 / 28%);
+  border-radius: 50%;
+  color: #f59e0b;
+  font-size: 10px;
+  font-weight: 700;
+  line-height: 1;
+  background: #fff;
+  box-shadow: 0 0 0 3px rgb(245 158 11 / 12%);
+  box-sizing: border-box;
+}
+</style>
+```
+
+### 节点类型
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Timeline, TimelineItem } from 'x-next';
+
+</script>
+<template>
+<Timeline>
+    <TimelineItem label="已完成" dot-color="#16a34a">构建通过</TimelineItem>
+    <TimelineItem label="待处理" dot-type="hollow">等待审批</TimelineItem>
+    <TimelineItem label="异常">
+      <template #dot>
+        <span class="timeline-demo-dot-icon">!</span>
+      </template>
+      发现风险
+    </TimelineItem>
+  </Timeline>
+</template>
+```
+
+### 单项轴线
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Timeline, TimelineItem } from 'x-next';
+
+</script>
+<template>
+<Timeline>
+    <TimelineItem label="阶段一" line-type="dashed">确认范围</TimelineItem>
+    <TimelineItem label="阶段二" line-color="#f59e0b">等待联调</TimelineItem>
+    <TimelineItem label="阶段三">发布完成</TimelineItem>
+  </Timeline>
+</template>
+```
+
+### 幽灵节点
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Timeline, TimelineItem } from 'x-next';
+
+</script>
+<template>
+<Timeline pending="同步中">
+    <TimelineItem label="09:30">提交任务</TimelineItem>
+    <TimelineItem label="10:00">完成处理</TimelineItem>
+  </Timeline>
+</template>
+```
+
+### 自定义幽灵节点
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Timeline, TimelineItem } from 'x-next';
+
+</script>
+<template>
+<Timeline pending="等待确认">
+    <template #dot>
+      <span class="timeline-demo-pending-dot"></span>
+    </template>
+    <TimelineItem label="创建">提交申请</TimelineItem>
+    <TimelineItem label="审批">主管复核</TimelineItem>
+  </Timeline>
+</template>
+```
+
+### 展示模式
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Timeline, TimelineItem } from 'x-next';
+
+</script>
+<template>
+<Timeline mode="alternate">
+    <TimelineItem label="需求">确认范围</TimelineItem>
+    <TimelineItem label="开发">实现能力</TimelineItem>
+    <TimelineItem label="验证" position="right">构建检查</TimelineItem>
+  </Timeline>
+
+  <Timeline mode="right">
+    <TimelineItem label="09:00">提交</TimelineItem>
+    <TimelineItem label="10:30">复核</TimelineItem>
+    <TimelineItem label="15:00">完成</TimelineItem>
+  </Timeline>
+</template>
+```
+
+### 横向时间线
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Timeline, TimelineItem } from 'x-next';
+
+</script>
+<template>
+<Timeline direction="horizontal" mode="alternate" pending>
+    <TimelineItem label="需求">确认范围</TimelineItem>
+    <TimelineItem label="开发">实现能力</TimelineItem>
+    <TimelineItem label="验证">构建检查</TimelineItem>
+  </Timeline>
+</template>
+```
+
+### 标签位置
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Timeline, TimelineItem } from 'x-next';
+
+</script>
+<template>
+<Timeline label-position="relative">
+    <TimelineItem label="2026-06-01">确认范围</TimelineItem>
+    <TimelineItem label="2026-06-02">实现改造</TimelineItem>
+    <TimelineItem label="2026-06-03">完成验证</TimelineItem>
+  </Timeline>
+</template>
+```
+
+### 标签和描述
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Timeline, TimelineItem } from 'x-next';
+
+</script>
+<template>
+<Timeline>
+    <TimelineItem label="需求">
+      <template #description>收集业务侧变更范围和验收标准。</template>
+    </TimelineItem>
+    <TimelineItem>
+      <template #label>开发</template>
+      <template #description>实现组件修复，并同步文档示例。</template>
+    </TimelineItem>
+    <TimelineItem label="验证">
+      <template #description>执行构建和文档站构建。</template>
+    </TimelineItem>
+  </Timeline>
+</template>
+```
+
+### 已知限制
+
+- 暂未提供 Timeline 专项自动化测试，交付前需通过文档构建和截图复查。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./timeline-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/tooltip-api.md

@@ -0,0 +1,77 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Tooltip 完整公开 API
+
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Tooltip API
+
+公开声明：`dist/components/tooltip/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| popupVisible | 气泡是否可见，受控模式，支持 v-model:popup-visible | undefined &#124; false &#124; true | 否 | undefined |
+| defaultPopupVisible | 默认是否可见，非受控模式 | undefined &#124; false &#124; true | 否 | false |
+| trigger | 触发方式 | undefined &#124; "click" &#124; "hover" &#124; "focus" &#124; "contextMenu" &#124; ("click" &#124; "hover" &#124; "focus" &#124; "contextMenu")[] | 否 | "hover" |
+| disabled | 是否禁用 Tooltip | undefined &#124; false &#124; true | 否 | false |
+| content | 提示内容 | undefined &#124; string &#124; number | 否 | 未声明 |
+| position | 弹出位置 | undefined &#124; "top" &#124; "bottom" &#124; "right" &#124; "left" &#124; "tl" &#124; "tr" &#124; "bl" &#124; "br" &#124; "lt" &#124; "rt" &#124; "lb" &#124; "rb" | 否 | "top" |
+| mini | 是否展示为迷你尺寸 | undefined &#124; false &#124; true | 否 | false |
+| backgroundColor | 气泡与箭头背景色 | undefined &#124; string | 否 | 未声明 |
+| contentClass | 气泡内容类名 | undefined &#124; string &#124; { [x: string]: boolean; } &#124; (string &#124; Record<string, boolean>)[] | 否 | 未声明 |
+| contentStyle | 气泡内容样式 | undefined &#124; CSSProperties | 否 | 未声明 |
+| arrowClass | 箭头类名 | undefined &#124; string &#124; { [x: string]: boolean; } &#124; (string &#124; Record<string, boolean>)[] | 否 | 未声明 |
+| arrowStyle | 箭头样式 | undefined &#124; CSSProperties | 否 | 未声明 |
+| popupContainer | 弹层挂载容器 | undefined &#124; string &#124; HTMLElement | 否 | 未声明 |
+| popupOffset | 弹层偏移距离 | undefined &#124; number | 否 | 10 |
+| popupTranslate | 弹层移动距离 | undefined &#124; [number, number] &#124; { top?: [number, number] &#124; undefined; bottom?: [number, number] &#124; undefined; right?: [number, number] &#124; undefined; left?: [number, number] &#124; undefined; tl?: [number, number] &#124; undefined; tr?: [number, number] &#124; undefined; bl?: [number, number] &#124; undefined; br?: [number, number] &#124; undefined; lt?: [number, number] &#124; undefined; rt?: [number, number] &#124; undefined; lb?: [number, number] &#124; undefined; rb?: [number, number] &#124; undefined; } | 否 | 未声明 |
+| showArrow | 是否展示箭头 | undefined &#124; false &#124; true | 否 | true |
+| alignPoint | 是否跟随鼠标位置，常用于右键菜单 | undefined &#124; false &#124; true | 否 | false |
+| popupStyle | 弹层定位节点样式 | undefined &#124; CSSProperties | 否 | 未声明 |
+| animationName | 弹出动画名称 | undefined &#124; string | 否 | "x-zoom-in-fade-out" |
+| duration | 动画持续时间 | undefined &#124; number &#124; { enter: number; leave: number; } | 否 | 未声明 |
+| mouseEnterDelay | 鼠标移入延迟，单位毫秒 | undefined &#124; number | 否 | 100 |
+| mouseLeaveDelay | 鼠标移出延迟，单位毫秒 | undefined &#124; number | 否 | 100 |
+| focusDelay | 聚焦延迟，单位毫秒 | undefined &#124; number | 否 | 0 |
+| popupHoverStay | hover 触发时移入浮层是否保持显示 | undefined &#124; false &#124; true | 否 | true |
+| blurToClose | focus 触发时失焦是否关闭 | undefined &#124; false &#124; true | 否 | true |
+| clickToClose | 点击触发器时是否允许关闭 | undefined &#124; false &#124; true | 否 | true |
+| clickOutsideToClose | 点击外部是否关闭 | undefined &#124; false &#124; true | 否 | true |
+| unmountOnClose | 关闭时是否卸载弹层节点 | undefined &#124; false &#124; true | 否 | true |
+| autoFitPopupWidth | 是否将弹层宽度设为触发器宽度 | undefined &#124; false &#124; true | 否 | false |
+| autoFitPopupMinWidth | 是否将弹层最小宽度设为触发器宽度 | undefined &#124; false &#124; true | 否 | false |
+| autoFixPosition | 触发器尺寸变化时是否重新定位 | undefined &#124; false &#124; true | 否 | true |
+| updateAtScroll | 容器滚动时是否更新弹层位置 | undefined &#124; false &#124; true | 否 | false |
+| autoFitPosition | 是否自动调整位置适配视口 | undefined &#124; false &#124; true | 否 | true |
+| renderToBody | 是否挂载到 body | undefined &#124; false &#124; true | 否 | true |
+| preventFocus | 点击弹层元素时是否阻止获取焦点 | undefined &#124; false &#124; true | 否 | false |
+| scrollToClose | 滚动时是否关闭 | undefined &#124; false &#124; true | 否 | false |
+| scrollToCloseDistance | 滚动关闭阈值 | undefined &#124; number | 否 | 0 |
+| openedClass | 打开时给触发元素添加的类名 | undefined &#124; string &#124; { [x: string]: boolean; } &#124; (string &#124; Record<string, boolean>)[] | 否 | 未声明 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:popupVisible | 显隐状态变化时触发，用于 v-model:popup-visible | undefined &#124; (visible: boolean) => any |
+| popupVisibleChange | 显隐状态变化时触发 | undefined &#124; (visible: boolean) => any |
+| show | 显示动画结束后触发 | undefined &#124; () => any |
+| hide | 隐藏动画结束后触发 | undefined &#124; () => any |
+| resize | 内部尺寸变化时触发 | undefined &#124; () => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 触发提示的元素 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| content | 自定义提示内容，优先级高于 content prop | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+返回 [Tooltip 用法](./tooltip.md)。

package/AI_USAGE/components/tooltip.md

@@ -0,0 +1,182 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Tooltip AI 使用
+
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
+
+先读 [通用接入](../core.md)。公开导出：`Tooltip`；主要模型：v-model:popup-visible。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./tooltip-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/tooltip`（包含 base.css、trigger.css、tooltip.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/tooltip.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./tooltip-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于解释图标、按钮或截断文本。
+
+
+### 何时使用
+
+- 需要在鼠标悬停、键盘聚焦或点击时展示短文本说明。
+- 说明内容较短，不承载复杂结构或操作。
+- 复杂卡片、标题和操作按钮请优先使用 [Popover 气泡卡片](./popover.md)。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tooltip, Button } from 'x-next';
+
+</script>
+<template>
+<Tooltip content="这是一段提示内容">
+    <Button>悬浮查看</Button>
+  </Tooltip>
+
+  <Tooltip content="键盘聚焦也可查看" :trigger="['hover', 'focus']">
+    <Button>聚焦查看</Button>
+  </Tooltip>
+</template>
+```
+
+### 弹出位置
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tooltip, Button } from 'x-next';
+
+</script>
+<template>
+<Tooltip content="上方" position="top">
+    <Button>Top</Button>
+  </Tooltip>
+  <Tooltip content="右侧" position="right">
+    <Button>Right</Button>
+  </Tooltip>
+</template>
+```
+
+### 迷你尺寸和颜色
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tooltip, Button } from 'x-next';
+
+</script>
+<template>
+<Tooltip content="1234" mini>
+    <Button>迷你尺寸</Button>
+  </Tooltip>
+
+  <Tooltip content="蓝色提示" background-color="#165dff">
+    <Button>蓝色</Button>
+  </Tooltip>
+</template>
+```
+
+### 禁用和空内容
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tooltip, Button } from 'x-next';
+
+</script>
+<template>
+<Tooltip content="禁用后不会展示" disabled>
+    <Button>禁用提示</Button>
+  </Tooltip>
+
+  <Tooltip content="需要管理员权限">
+    <Button disabled>禁用按钮提示</Button>
+  </Tooltip>
+
+  <Tooltip>
+    <Button>空内容不展示</Button>
+  </Tooltip>
+
+  <Tooltip :content="0">
+    <Button>数字 0</Button>
+  </Tooltip>
+</template>
+```
+
+### 受控显隐和事件
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, Tooltip } from 'x-next';
+import { ref } from 'vue';
+
+const visible = ref(false);
+</script>
+<template>
+<Button @click="visible = !visible">切换显隐</Button>
+  <Tooltip
+    v-model:popup-visible="visible"
+    trigger="click"
+    content="受控 Tooltip"
+    @popup-visible-change="(nextVisible) => console.log(nextVisible)"
+  >
+    <Button>点击触发</Button>
+  </Tooltip>
+</template>
+```
+
+### 自定义内容
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tooltip, Button } from 'x-next';
+
+</script>
+<template>
+<Tooltip>
+    <Button>查看状态</Button>
+    <template #content>
+      <div>
+        <strong>构建完成</strong>
+        <span>耗时 12.4s，产物已更新。</span>
+      </div>
+    </template>
+  </Tooltip>
+</template>
+```
+
+### 更多触发能力
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tooltip, Button } from 'x-next';
+import { ref } from 'vue';
+
+const visible = ref(false);
+</script>
+<template>
+<Tooltip content="没有箭头" :show-arrow="false">
+    <Button>隐藏箭头</Button>
+  </Tooltip>
+
+  <Tooltip v-model:popup-visible="visible" trigger="contextMenu" align-point content="跟随右键位置">
+    <Button>右键触发</Button>
+  </Tooltip>
+</template>
+```
+
+### 导出项
+
+| 名称 | 说明 |
+| --- | --- |
+| `Tooltip` | 主组件 |
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./tooltip-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。