x-next 1.13.0 → 1.14.0

package/AI_USAGE/components/space.md

@@ -0,0 +1,145 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Space AI 使用
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+先读 [通用接入](../core.md)。公开导出：`Space`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./space-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/space`（包含 base.css、space.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/space.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./space-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于在行内或纵向排列的一组元素之间设置统一间距。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Space, Button } from 'x-next';
+
+</script>
+<template>
+<Space size="medium">
+    <Button>取消</Button>
+    <Button type="primary">确定</Button>
+    <Button status="danger">删除</Button>
+  </Space>
+</template>
+```
+
+### 垂直间距
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Space, Alert } from 'x-next';
+
+</script>
+<template>
+<Space direction="vertical" size="medium">
+    <Alert type="info">第一条提示</Alert>
+    <Alert type="success">第二条提示</Alert>
+    <Alert type="warning">第三条提示</Alert>
+  </Space>
+</template>
+```
+
+### 间距尺寸
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Space, Tag } from 'x-next';
+
+</script>
+<template>
+<Space size="mini">
+    <Tag>mini</Tag>
+    <Tag>mini</Tag>
+    <Tag>mini</Tag>
+  </Space>
+  <Space size="medium">
+    <Tag>medium</Tag>
+    <Tag>medium</Tag>
+    <Tag>medium</Tag>
+  </Space>
+  <Space :size="24">
+    <Tag>24px</Tag>
+    <Tag>24px</Tag>
+    <Tag>24px</Tag>
+  </Space>
+</template>
+```
+
+### 对齐方式
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Space, Button, Tag } from 'x-next';
+
+</script>
+<template>
+<Space align="start">
+    <Button>顶部对齐</Button>
+    <Tag size="large">Large Tag</Tag>
+    <span style="font-size: 12px">小字号文本</span>
+  </Space>
+  <Space align="baseline">
+    <Button>基线对齐</Button>
+    <Tag size="large">Large Tag</Tag>
+    <span style="font-size: 12px">小字号文本</span>
+  </Space>
+</template>
+```
+
+### 撑满宽度
+
+`fill` 让组件自身撑满父容器宽度，并让每个间距项等分可用空间；垂直方向的间距项会拉伸交叉轴，宽度 100% 的表单控件因此能真正撑满。横向排列不需要 `fill` 时，用 `block` 配合 `style="width: 100%"`。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Space, Button, Input } from 'x-next';
+
+</script>
+<template>
+<Space block align="space-between" style="width: 100%">
+    <Button>上一页</Button>
+    <Button type="primary">下一页</Button>
+  </Space>
+  <Space fill direction="vertical" size="medium">
+    <Input placeholder="第一行撑满" />
+    <Input placeholder="第二行撑满" />
+  </Space>
+</template>
+```
+
+### 分隔符
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Space, Link } from 'x-next';
+
+</script>
+<template>
+<Space>
+    <template #split>
+      <span>/</span>
+    </template>
+    <Link>首页</Link>
+    <Link>组件</Link>
+    <Link>Space</Link>
+  </Space>
+</template>
+```
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./space-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/spin-api.md

@@ -0,0 +1,43 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Spin 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Spin API
+
+公开声明：`dist/components/spin/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| display | 容器显示方式 | undefined &#124; "block" &#124; "inline" | 否 | "inline" |
+| size | 图标或点状动画单点尺寸 | undefined &#124; number | 否 | 未声明 |
+| loading | 是否为加载中状态，仅容器模式下覆盖内容 | undefined &#124; false &#124; true | 否 | false（Vue Boolean 转换） |
+| delay | 延迟显示加载态的毫秒数，避免快速请求闪烁；仅容器模式生效，结束时立即收起 | undefined &#124; number | 否 | 0 |
+| dot | 是否使用点状动画 | undefined &#124; false &#124; true &#124; "default" &#124; "color" | 否 | false（Vue Boolean 转换） |
+| tip | 提示内容 | undefined &#124; string | 否 | 未声明 |
+| hideIcon | 是否隐藏图标 | undefined &#124; false &#124; true | 否 | false |
+| tipShimmer | 提示文字是否开启扫光效果，需要同时设置 tip | undefined &#124; false &#124; true | 否 | false |
+
+### Events
+
+未声明组件 emits；原生事件与包装透传按本页用法核实。
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 容器模式下的内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| icon | 自定义图标，会向第一个组件注入 spin 属性 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| element | 自定义加载元素 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| tip | 自定义提示内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+
+返回 [Spin 用法](./spin.md)。

package/AI_USAGE/components/spin.md

@@ -0,0 +1,205 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Spin AI 使用
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+先读 [通用接入](../core.md)。公开导出：`Spin`；主要模型：无。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./spin-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/spin`（包含 base.css、spin.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/spin.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./spin-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于局部区域或页面等待状态。
+
+
+### 何时使用
+
+- 页面、卡片、表格等区域正在等待异步数据。
+- 操作提交后需要短暂阻止用户继续操作当前区域。
+- 需要用提示文本降低等待过程中的不确定感。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Spin } from 'x-next';
+
+</script>
+<template>
+<Spin />
+  <Spin tip="加载中" />
+</template>
+```
+
+### 尺寸
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Spin } from 'x-next';
+
+</script>
+<template>
+<Spin :size="16" />
+  <Spin :size="24" />
+  <Spin :size="36" tip="处理中" />
+</template>
+```
+
+### 容器模式
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, Spin } from 'x-next';
+import { ref } from 'vue';
+
+const loading = ref(true);
+</script>
+<template>
+<Button size="small" @click="loading = !loading">
+    {{ loading ? '结束加载' : '开始加载' }}
+  </Button>
+  <Spin :loading="loading" display="block" tip="加载中">
+    <div class="panel">
+      <strong>内容区域</strong>
+      <p>加载时遮罩会覆盖内容，并暂时阻止内部控件聚焦。</p>
+      <Button size="small">区域操作</Button>
+    </div>
+  </Spin>
+</template>
+```
+
+### 点状动画
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Spin } from 'x-next';
+
+</script>
+<template>
+<Spin dot />
+  <Spin dot="color" />
+  <Spin dot="color" :size="10" tip="同步中" />
+</template>
+```
+
+### 隐藏图标
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Spin } from 'x-next';
+
+</script>
+<template>
+<Spin hide-icon tip="正在连接服务" />
+  <Spin :loading="true" display="block" hide-icon tip="正在保存">
+    <div class="panel">表单内容</div>
+  </Spin>
+</template>
+```
+
+### 自定义内容
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Spin } from 'x-next';
+
+</script>
+<template>
+<Spin tip="自定义图标">
+    <template #icon>
+      <span class="custom-icon">⌁</span>
+    </template>
+  </Spin>
+  <Spin tip="自定义元素">
+    <template #element>
+      <span class="custom-loading" aria-hidden="true"></span>
+    </template>
+  </Spin>
+  <Spin>
+    <template #tip>
+      <span>请稍候，正在处理</span>
+    </template>
+  </Spin>
+</template>
+```
+
+### 文案扫光
+
+`tipShimmer` 让提示文字出现一条横向扫过的光带，比静止文案更醒目。仅对 `tip` prop 生效（自定义 `tip` 插槽内容结构未知，不参与扫光）。
+
+光带颜色与周期由两个 token 控制，可在主题层或局部覆盖：
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Spin } from 'x-next';
+
+</script>
+<template>
+<Spin tip="加载中" tip-shimmer />
+  <Spin tip="正在同步数据" tip-shimmer :size="32" />
+</template>
+```
+
+### 延迟显示
+
+快速请求往往几十毫秒内就结束。直接切 `loading` 会让遮罩闪一下又消失，观感比不加加载态更差。`delay` 让加载态延后出现，这段时间内结束的请求不会有任何闪烁。
+
+`delay` 只延迟**出现**：加载结束时立即收起遮罩，不会让已加载好的内容再被多盖一段时间。因此快请求不闪、慢请求也不拖。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Button, Spin } from 'x-next';
+import { ref } from 'vue';
+
+const loading = ref(false);
+
+// 120ms 结束：早于 delay，遮罩不出现，不会闪
+const runFast = () => {
+  loading.value = true;
+  window.setTimeout(() => {
+    loading.value = false;
+  }, 120);
+};
+
+// 1.2s 结束：遮罩在 300ms 时出现
+const runSlow = () => {
+  loading.value = true;
+  window.setTimeout(() => {
+    loading.value = false;
+  }, 1200);
+};
+</script>
+<template>
+<Button @click="runFast">快请求（120ms 结束）</Button>
+  <Button @click="runSlow">慢请求（1.2s 结束）</Button>
+  <Spin :loading="loading" :delay="300" display="block" tip="加载中">
+    <div class="panel">内容区域</div>
+  </Spin>
+</template>
+```
+
+### 交互说明
+
+- 容器模式下，`loading` 为 `true` 时会显示遮罩，并给内容区域加上不可聚焦状态。不支持 `inert` 的旧浏览器会退化为给内部可聚焦元素临时加 `tabindex="-1"`，加载结束后还原。
+- `delay` 只对容器模式生效；独立形态本身就是加载指示器，`loading` 与 `delay` 都不参与。
+- Spin 根节点默认带有加载语义；没有提示文本时会使用默认可访问名称。
+- `icon` 插槽会向第一个组件注入 `spin` 属性；若传入普通元素，可自行添加动画样式，或使用 `element` 插槽完全自定义。
+- 开启系统「减弱动态效果」后，图标旋转、点状动画与文案扫光都会停止；扫光会还原成纯色，避免光带停在文字上留下一块亮斑。
+- 提示文字的行高由组件显式声明（`--x-line-height-base`），不继承宿主行高，因此在任意项目里高度一致。
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./spin-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/steps-api.md

@@ -0,0 +1,111 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Steps 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Step API
+
+公开声明：`dist/components/steps/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| title | 步骤标题 | undefined &#124; string | 否 | 未声明 |
+| description | 步骤描述 | undefined &#124; string | 否 | 未声明 |
+| status | 步骤状态，设置后会覆盖 Steps 自动计算 | undefined &#124; "error" &#124; "wait" &#124; "process" &#124; "finish" | 否 | 未声明 |
+| disabled | 是否禁用点击 | undefined &#124; false &#124; true | 否 | false |
+
+### Events
+
+未声明组件 emits；原生事件与包装透传按本页用法核实。
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| node | 自定义节点 | any |
+| description | 自定义描述内容 | any |
+| icon | 自定义图标 | any |
+| default | 自定义标题内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+declare const STEPS_TYPES: readonly ["default", "arrow", "dot", "navigation"];
+
+type StepsType = typeof STEPS_TYPES[number];
+
+declare const STEP_STATUSES: readonly ["wait", "process", "finish", "error"];
+
+type StepStatus = typeof STEP_STATUSES[number];
+
+interface StepData {
+    step: number;
+    status: StepStatus;
+}
+```
+
+
+## Steps API
+
+公开声明：`dist/components/steps/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| type | 步骤条类型 | undefined &#124; "default" &#124; "dot" &#124; "arrow" &#124; "navigation" | 否 | "default" |
+| direction | 显示方向 | undefined &#124; "horizontal" &#124; "vertical" | 否 | "horizontal" |
+| labelPlacement | 标签描述放置位置 | undefined &#124; "horizontal" &#124; "vertical" | 否 | "horizontal" |
+| current | 当前步骤，按 1 开始计数 | undefined &#124; number | 否 | undefined |
+| defaultCurrent | 默认步骤，非受控模式 | undefined &#124; number | 否 | 1 |
+| status | 当前步骤状态 | undefined &#124; "error" &#124; "wait" &#124; "process" &#124; "finish" | 否 | "process" |
+| lineLess | 是否使用无连接线样式 | undefined &#124; false &#124; true | 否 | false |
+| small | 是否使用小尺寸，dot 模式不生效 | undefined &#124; false &#124; true | 否 | false |
+| changeable | 是否可点击切换 | undefined &#124; false &#124; true | 否 | false |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:current | 当前步骤变化时触发 | undefined &#124; (step: number) => any |
+| change | 当前步骤变化时触发 | undefined &#124; (step: number, ev: Event) => any |
+
+### Slots
+
+公开类型未逐项声明插槽；本页场景说明列出实际使用的插槽，不将任意插槽视为已支持。
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+declare const STEPS_TYPES: readonly ["default", "arrow", "dot", "navigation"];
+
+type StepsType = typeof STEPS_TYPES[number];
+
+declare const STEP_STATUSES: readonly ["wait", "process", "finish", "error"];
+
+type StepStatus = typeof STEP_STATUSES[number];
+
+interface StepData {
+    step: number;
+    status: StepStatus;
+}
+```
+
+
+返回 [Steps 用法](./steps.md)。