x-next 1.13.0 → 1.14.0

package/AI_USAGE/components/steps.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Steps AI 使用
 
-适用版本：x-next@1.13.0；来源指纹：`18e9b8eefa53b4bd91134fb4486778509ccf3a8d614a1bd387a6d469b623ddcf`。
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
 
-先读 [通用接入](../core.md)。公开导出：`Steps`；模型：v-model:current；已核对事件：change。
+先读 [通用接入](../core.md)。公开导出：`Step, Steps`；主要模型：v-model:current。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./steps-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`x-next/style/steps`（包含 base.css、steps.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
 
+## 已核验行为与示例
+
 [组件文档与 live demo](https://x-next.yjmf.com/components/steps)。子组件的公开名称是 `Step`。使用 `v-model:current`，序号从 **1** 开始，`defaultCurrent=1`、`status='process'`、`type='default'`、`direction='horizontal'`；点击切换需开启 `changeable`，默认关闭。
 
 `change(step, event)` 返回步骤号和 `Event`。Step 支持 `title`、`description`、`disabled`、`status`；`node` / `icon` 插槽提供步骤与状态，默认 / `description` 插槽可替换文案。业务完成状态由业务自身维护。
@@ -30,4 +32,200 @@ function changed(step: number, _event: Event) { feedback.value = `已切换到
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/steps.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./steps-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于展示流程步骤、进度节点和当前处理状态，适合表单分步、审批流、发布流程和导航式任务。
+
+
+### 何时使用
+
+- 需要明确展示任务拆分后的阶段和当前进度。
+- 需要让用户按步骤完成流程，或在可点击模式下跳转到某个阶段。
+- 需要在流程中标记完成、等待、处理中或错误状态。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Steps, Step } from 'x-next';
+import { ref } from 'vue';
+
+const current = ref(2);
+</script>
+<template>
+<Steps :current="current">
+    <Step title="填写信息" description="录入基础资料" />
+    <Step title="确认订单" description="核对费用和地址" />
+    <Step title="完成提交" description="等待系统处理" />
+  </Steps>
+</template>
+```
+
+### 状态
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Steps, Step } from 'x-next';
+
+</script>
+<template>
+<Steps :current="2" status="error">
+    <Step title="创建任务" description="已完成" />
+    <Step title="执行校验" description="校验失败" />
+    <Step title="发布结果" description="等待修复后继续" />
+  </Steps>
+
+  <Steps :current="2">
+    <Step title="排队" />
+    <Step title="处理中" />
+    <Step title="结束" status="error" description="可单独覆盖 Step 状态" />
+  </Steps>
+</template>
+```
+
+### 标签位置和垂直方向
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Steps, Step } from 'x-next';
+import { ref } from 'vue';
+
+const current = ref(2);
+</script>
+<template>
+<Steps :current="2" label-placement="vertical">
+    <Step title="提交" description="表单资料" />
+    <Step title="审核" description="人工确认" />
+    <Step title="归档" description="流程结束" />
+  </Steps>
+
+  <Steps :current="current" direction="vertical">
+    <Step title="创建项目" description="准备基础配置" />
+    <Step title="配置权限" description="选择成员和角色" />
+    <Step title="启动项目" description="生成工作空间" />
+  </Steps>
+</template>
+```
+
+### 小尺寸和无线条
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Steps, Step } from 'x-next';
+
+</script>
+<template>
+<Steps :current="2" small>
+    <Step title="开始" />
+    <Step title="处理中" />
+    <Step title="完成" />
+  </Steps>
+
+  <Steps :current="2" line-less>
+    <Step title="草稿" description="本地保存" />
+    <Step title="提交" description="等待处理" />
+    <Step title="发布" description="对外可见" />
+  </Steps>
+</template>
+```
+
+### 类型
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Steps, Step } from 'x-next';
+
+</script>
+<template>
+<Steps type="arrow" :current="2">
+    <Step title="选择商品" description="确认清单" />
+    <Step title="支付订单" description="处理中" />
+    <Step title="发货" description="等待仓库" />
+  </Steps>
+
+  <Steps type="dot" :current="2">
+    <Step title="启动" description="初始化" />
+    <Step title="运行" description="任务执行中" />
+    <Step title="收尾" description="生成报告" />
+  </Steps>
+
+  <Steps type="navigation" :current="2">
+    <Step title="账户" description="基础信息" />
+    <Step title="权限" description="角色策略" />
+    <Step title="确认" description="提交配置" />
+  </Steps>
+</template>
+```
+
+### 可点击切换
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Steps, Step } from 'x-next';
+import { ref } from 'vue';
+
+const current = ref(1);
+const handleChange = (step: number) => {
+  current.value = step;
+};
+</script>
+<template>
+<Steps changeable :current="current" @change="handleChange">
+    <Step title="资料" />
+    <Step title="配置" />
+    <Step title="预览" disabled />
+    <Step title="完成" />
+  </Steps>
+  <p>当前步骤：{{ current }}</p>
+</template>
+```
+
+### 自定义内容
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Steps, Step } from 'x-next';
+
+</script>
+<template>
+<Steps :current="2" label-placement="vertical">
+    <Step title="设计">
+      <template #icon="{ step }">{{ step }}</template>
+
+      <template #description>产出交互稿</template>
+    </Step>
+    <Step>
+      <template #node="{ status }">
+        <span>{{ status === 'process' ? '中' : '2' }}</span>
+      </template>
+
+      <template #description>实现页面和接口</template>
+    </Step>
+    <Step title="验收" description="确认上线" />
+  </Steps>
+</template>
+```
+
+### 交互说明
+
+- `current` 按 1 开始计数；受控使用时需要在 `change` 或 `update:current` 中同步外部值。
+- `Step.status` 会覆盖 `Steps` 根据 `current` 和 `status` 自动计算出的状态。
+- `type="arrow"` 和 `type="navigation"` 会强制横向展示。
+- `type="dot"` 会根据方向自动调整标签位置，且不使用 `small` 尺寸。
+- 只有设置 `changeable` 后点击步骤才会触发切换；`disabled` 的步骤不会触发切换。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./steps-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/switch-api.md

@@ -0,0 +1,58 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Switch 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Switch API
+
+公开声明：`dist/components/form-switch/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| modelValue | 绑定值 | undefined &#124; string &#124; number &#124; false &#124; true | 否 | undefined |
+| defaultChecked | 默认选中状态，非受控模式 | undefined &#124; false &#124; true | 否 | false |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| loading | 是否加载中 | undefined &#124; false &#124; true | 否 | false |
+| autofocus | 是否自动获取焦点 | undefined &#124; false &#124; true | 否 | false |
+| type | 开关类型 | undefined &#124; "round" &#124; "circle" &#124; "line" | 否 | "circle" |
+| size | 开关尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 未声明 |
+| checkedValue | 选中时的值 | undefined &#124; string &#124; number &#124; false &#124; true | 否 | true |
+| uncheckedValue | 未选中时的值 | undefined &#124; string &#124; number &#124; false &#124; true | 否 | false |
+| checkedColor | 选中时颜色 | undefined &#124; string | 否 | 未声明 |
+| uncheckedColor | 未选中时颜色 | undefined &#124; string | 否 | 未声明 |
+| beforeChange | 切换前钩子，返回 false 或 Promise reject 时阻止切换 | undefined &#124; (newValue: string &#124; number &#124; boolean) => Promise<boolean &#124; void> &#124; boolean &#124; void | 否 | 未声明 |
+| checkedText | 选中时文案，type="line" 时不显示 | undefined &#124; string | 否 | 未声明 |
+| uncheckedText | 未选中时文案，type="line" 时不显示 | undefined &#124; string | 否 | 未声明 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:modelValue | 值更新时触发 | undefined &#124; (value: string &#124; number &#124; boolean) => any |
+| change | 值变化时触发 | undefined &#124; (value: string &#124; number &#124; boolean, ev: Event) => any |
+| focus | 获取焦点时触发 | undefined &#124; (ev: FocusEvent) => any |
+| blur | 失去焦点时触发 | undefined &#124; (ev: FocusEvent) => any |
+| click | 点击时触发，返回本次尝试切换的目标值 | undefined &#124; (value: string &#124; number &#124; boolean, ev: MouseEvent) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| checked | 选中时文案 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| unchecked | 未选中时文案 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| checked-icon | 选中时按钮图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| unchecked-icon | 未选中时按钮图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法 / 暴露值
+
+| 名称 | 公开类型 |
+| --- | --- |
+| focus | 公开声明未细化（用法和实现已显式暴露） |
+| blur | 公开声明未细化（用法和实现已显式暴露） |
+
+
+返回 [Switch 用法](./switch.md)。

package/AI_USAGE/components/switch.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Switch AI 使用
 
-适用版本：x-next@1.13.0；来源指纹：`18e9b8eefa53b4bd91134fb4486778509ccf3a8d614a1bd387a6d469b623ddcf`。
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
 
-先读 [通用接入](../core.md)。公开导出：`Switch`；模型：v-model；已核对事件：change。
+先读 [通用接入](../core.md)。公开导出：`Switch`；主要模型：v-model。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./switch-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`x-next/style/form-switch`（包含 base.css、form-switch.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
 
+## 已核验行为与示例
+
 [组件文档与 live demo](https://x-next.yjmf.com/components/switch)。普通 `v-model` 支持 `boolean | string | number`；`checkedValue=true`、`uncheckedValue=false`、`defaultChecked=false`，默认 `type='circle'`。`disabled` / `loading` 阻止切换。
 
 `change(value, event)` 返回新值和 `Event`；`beforeChange(newValue)` 可返回布尔值或 Promise，`false` 或拒绝阻止切换。`checked` / `unchecked` 插槽及 `checkedText` / `uncheckedText` 显示两态文案；`type='line'` 或有效尺寸为 `'mini'`（含继承尺寸）时均不显示文案。
@@ -29,4 +31,289 @@ function changed(value: boolean | string | number, _event: Event) {
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/switch.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./switch-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于表达启用/停用、打开/关闭这类二元状态。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Switch } from 'x-next';
+import { ref } from 'vue';
+
+const enabled = ref(false);
+</script>
+<template>
+<Switch v-model="enabled" />
+</template>
+```
+
+### 文案和自定义值
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Switch } from 'x-next';
+const enabled = ref(false);
+
+import { ref } from 'vue';
+
+const status = ref<'enabled' | 'disabled'>('enabled');
+</script>
+<template>
+<Switch
+    v-model="status"
+    checked-value="enabled"
+    unchecked-value="disabled"
+    checked-text="开"
+    unchecked-text="关"
+  />
+  <span>{{ status }}</span>
+</template>
+```
+
+### 类型
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Switch } from 'x-next';
+import { ref } from 'vue';
+const enabled = ref(false);
+</script>
+<template>
+<Switch v-model="enabled" type="circle" />
+  <Switch v-model="enabled" type="round" />
+  <Switch v-model="enabled" type="line" />
+</template>
+```
+
+### 尺寸
+
+四档尺寸的高度依次为 16 / 16 / 24 / 28px；`mini` 与 `small` 目前共用同一档视觉规格。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Switch } from 'x-next';
+import { ref } from 'vue';
+const enabled = ref(false);
+</script>
+<template>
+<Switch v-model="enabled" size="mini" />
+  <Switch v-model="enabled" size="small" />
+  <Switch v-model="enabled" size="medium" checked-text="开" unchecked-text="关" />
+  <Switch v-model="enabled" size="large" checked-text="开" unchecked-text="关" />
+</template>
+```
+
+### 禁用
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Switch } from 'x-next';
+
+</script>
+<template>
+<Switch disabled />
+  <Switch :model-value="true" disabled />
+</template>
+```
+
+### 加载中
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Switch } from 'x-next';
+
+</script>
+<template>
+<Switch loading />
+  <Switch :model-value="true" loading />
+</template>
+```
+
+### 自定义颜色
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Switch } from 'x-next';
+import { ref } from 'vue';
+const enabled = ref(false);
+</script>
+<template>
+<Switch
+    v-model="enabled"
+    checked-color="#0f766e"
+    unchecked-color="#94a3b8"
+    checked-text="启用"
+    unchecked-text="停用"
+  />
+  <Switch
+    v-model="enabled"
+    type="line"
+    checked-color="#0f766e"
+    unchecked-color="#94a3b8"
+  />
+</template>
+```
+
+### 切换前校验
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Switch } from 'x-next';
+import { ref } from 'vue';
+
+const enabled = ref(false);
+const beforeChange = async (nextValue: boolean | string | number) => {
+  await new Promise((resolve) => window.setTimeout(resolve, 600));
+  return nextValue === true;
+};
+</script>
+<template>
+<Switch v-model="enabled" :before-change="beforeChange" />
+</template>
+```
+
+### 自定义图标
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Switch } from 'x-next';
+import { ref } from 'vue';
+const enabled = ref(false);
+</script>
+<template>
+<Switch v-model="enabled">
+    <template #checked-icon>✓</template>
+    <template #unchecked-icon>×</template>
+  </Switch>
+</template>
+```
+
+### 事件回调
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Switch } from 'x-next';
+import { ref } from 'vue';
+
+const enabled = ref(false);
+const eventLog = ref('等待操作');
+const clickCount = ref(0);
+const handleChange = (value: boolean | string | number) => {
+  eventLog.value = `当前值：${value}`;
+};
+const handleClick = (value: boolean | string | number) => {
+  clickCount.value += 1;
+  eventLog.value = `点击第 ${clickCount.value} 次，目标值：${value}`;
+};
+</script>
+<template>
+<Switch v-model="enabled" @change="handleChange" @click="handleClick" />
+  <span>{{ eventLog }}</span>
+</template>
+```
+
+### 原生属性
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Switch } from 'x-next';
+
+import type { ButtonHTMLAttributes } from 'vue';
+const nativeAttrs1 = { "id": "notification-switch", "name": "notification", "aria-label": "通知开关" } satisfies ButtonHTMLAttributes;
+</script>
+<template>
+<Switch v-bind="nativeAttrs1"
+
+
+    autofocus
+
+  />
+</template>
+```
+
+### 方法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Switch, Button } from 'x-next';
+import { ref } from 'vue';
+
+const enabled = ref(false);
+const switchRef = ref();
+</script>
+<template>
+<Switch ref="switchRef" v-model="enabled" />
+  <Button @click="switchRef?.focus()">聚焦</Button>
+  <Button @click="switchRef?.blur()">失焦</Button>
+</template>
+```
+
+### 在 Form 中校验
+
+组件放进 `x-form-item` 后会自动继承 Form 的尺寸与禁用状态，并按 FormItem 的校验规则展示错误。默认 `validateTrigger` 为 `change`，即值变化时触发校验。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, Switch, Space, Button } from 'x-next';
+const enabled = ref(false);
+const status = ref<'enabled' | 'disabled'>('enabled');
+
+import { reactive, ref } from 'vue';
+import type { FormInstance, FieldRule } from 'x-next';
+
+const formState = reactive({ enabled: false });
+const formRules: Record<string, FieldRule[]> = {
+  enabled: [{ type: 'boolean', true: true, message: '需要启用通知' }],
+};
+const formRef = ref<FormInstance>();
+const validateResult = ref('');
+
+const handleValidate = async () => {
+  const errors = await formRef.value!.validate();
+  validateResult.value = errors
+    ? `校验失败：${Object.values(errors).map((error) => error.message).join('；')}`
+    : '校验通过';
+};
+const handleReset = () => {
+  formRef.value!.resetFields();
+  validateResult.value = '已重置';
+};
+</script>
+<template>
+<Form ref="formRef" :model="formState" :rules="formRules">
+    <FormItem field="enabled" label="启用通知">
+      <Switch v-model="formState.enabled" />
+    </FormItem>
+    <FormItem>
+      <Space>
+        <Button type="primary" @click="handleValidate">校验</Button>
+        <Button @click="handleReset">重置</Button>
+      </Space>
+    </FormItem>
+  </Form>
+  <p role="status">{{ validateResult }}</p>
+</template>
+```
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./switch-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。