x-next 1.13.0 → 1.15.0

package/AI_USAGE/components/rate.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Rate AI 使用
 
-适用版本：x-next@1.13.0；来源指纹：`18e9b8eefa53b4bd91134fb4486778509ccf3a8d614a1bd387a6d469b623ddcf`。
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
 
-先读 [通用接入](../core.md)。公开导出：`Rate`；模型：v-model；已核对事件：change。
+先读 [通用接入](../core.md)。公开导出：`Rate`；主要模型：v-model。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./rate-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`x-next/style/rate`（包含 base.css、rate.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
 
+## 已核验行为与示例
+
 [组件文档与 live demo](https://x-next.yjmf.com/components/rate)。数值模型默认非受控值为 `0`，`count=5`；`allowHalf`、`allowClear`、`readonly`、`disabled` 默认关闭。启用半星后步长为 `0.5`，值限制在有效数量内；没有 `size` 属性。
 
 `change(value)` 返回 `number`，`hover-change(value)` 返回 `number | undefined`。`character` 插槽提供 `index`、`value`、`count`、`disabled`；`tooltips` 为提示数组。
@@ -27,4 +29,232 @@ function changed(value: number) { feedback.value = value ? `评分 ${value}` : '
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/rate.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./rate-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于评分、打星或展示满意度等级，适合评价表单、质量反馈和评分结果展示。
+
+
+### 何时使用
+
+- 需要用户快速给出等级评价时。
+- 需要在详情、列表或卡片中展示评分结果时。
+- 评分项数量较少，并且每个等级含义容易理解时。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Rate } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref(3);
+</script>
+<template>
+<Rate v-model="value" />
+</template>
+```
+
+### 半星评分
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Rate } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref(2.5);
+</script>
+<template>
+<Rate v-model="value" allow-half />
+</template>
+```
+
+### 可清除
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Rate } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref(4);
+</script>
+<template>
+<Rate v-model="value" allow-clear />
+</template>
+```
+
+### 只读和禁用
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Rate } from 'x-next';
+import { ref } from 'vue';
+
+const readonlyValue = ref(3.5);
+const disabledValue = ref(2);
+</script>
+<template>
+<Rate v-model="readonlyValue" allow-half readonly />
+  <Rate v-model="disabledValue" disabled />
+</template>
+```
+
+### 自定义数量
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Rate } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref(6);
+</script>
+<template>
+<Rate v-model="value" :count="8" />
+</template>
+```
+
+### 自定义字符
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Rate } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref(3);
+</script>
+<template>
+<Rate v-model="value">
+    <template #character="{ index }">
+      <span>{{ index + 1 }}</span>
+    </template>
+  </Rate>
+</template>
+```
+
+### 自定义颜色和笑脸分级
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Rate } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref(4);
+const scoreColors = {
+  2: '#f53f3f',
+  4: '#ff7d00',
+  5: '#00b42a',
+};
+</script>
+<template>
+<Rate v-model="value" :color="scoreColors" />
+  <Rate v-model="value" grading />
+</template>
+```
+
+### 提示文本
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Rate } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref(3);
+const tooltipTexts = ['很差', '一般', '还行', '不错', '很好'];
+</script>
+<template>
+<Rate v-model="value" :tooltips="tooltipTexts" />
+  <p>{{ tooltipTexts[value - 1] }}</p>
+</template>
+```
+
+### 事件
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Rate } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref(2);
+const hoverValue = ref<number | undefined>();
+const log = ref('等待操作');
+</script>
+<template>
+<Rate
+    v-model="value"
+    allow-half
+    allow-clear
+    @change="(nextValue) => log = `change: ${nextValue}`"
+    @hover-change="(nextValue) => hoverValue = nextValue"
+  />
+  <p>{{ log }}，hover：{{ hoverValue ?? '-' }}</p>
+</template>
+```
+
+### 表单组合
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, Rate, Space, Button } from 'x-next';
+import { reactive, ref } from 'vue';
+import type { FormInstance, FieldRule } from 'x-next';
+const formRef = ref<FormInstance>();
+const formModel = reactive({ score: 0 });
+const formResult = ref('点击校验查看结果');
+const handleFormValidate = async () => {
+  const errors = await formRef.value!.validate();
+  formResult.value = errors
+    ? `校验失败：${Object.values(errors).map((error) => error.message).join('；')}`
+    : '校验通过';
+};
+const handleFormReset = () => {
+  formRef.value!.resetFields();
+  formResult.value = '已重置';
+};
+import type { HTMLAttributes } from 'vue';
+const nativeAttrs1 = { "aria-label": "服务评分" } satisfies HTMLAttributes;
+</script>
+<template>
+<Form ref="formRef" :model="formModel" layout="vertical">
+    <FormItem label="服务评分" field="score" :rules="[{ type: 'number', min: 1, message: '请选择至少 1 分' }]">
+      <Rate v-bind="nativeAttrs1" v-model="formModel.score" allow-half allow-clear  />
+    </FormItem>
+    <FormItem>
+      <Space>
+        <Button type="primary" @click="handleFormValidate">校验</Button>
+        <Button @click="handleFormReset">重置</Button>
+      </Space>
+    </FormItem>
+  </Form>
+  <p role="status">{{ formResult }}</p>
+</template>
+```
+
+### 键盘交互
+
+`allowClear` 只影响重复点击同一评分；方向键、Home、End 和数字键始终定位到目标分值，在边界重复操作不会切换为 0。
+
+| 按键 | 行为 |
+| --- | --- |
+| `ArrowRight` / `ArrowUp` | 增加评分 |
+| `ArrowLeft` / `ArrowDown` | 减少评分 |
+| `Home` | 清零 |
+| `End` | 选择最大评分 |
+| `0-9` | 在评分总数范围内快速设置对应分值 |
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./rate-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/resize-box-api.md

@@ -0,0 +1,56 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# ResizeBox 完整公开 API
+
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## ResizeBox API
+
+公开声明：`dist/components/resize-box/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| width | 宽度 | undefined &#124; number | 否 | 未声明 |
+| height | 高度 | undefined &#124; number | 否 | 未声明 |
+| minWidth | 最小宽度 | undefined &#124; number | 否 | 0 |
+| maxWidth | 最大宽度 | undefined &#124; number | 否 | 未声明 |
+| minHeight | 最小高度 | undefined &#124; number | 否 | 0 |
+| maxHeight | 最大高度 | undefined &#124; number | 否 | 未声明 |
+| component | 渲染的 HTML 标签 | undefined &#124; string | 否 | "div" |
+| directions | 可拖拽方向 | undefined &#124; ("top" &#124; "bottom" &#124; "right" &#124; "left")[] | 否 | 工厂函数（每个实例初始化；有效值见行为说明） |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:width | 宽度变化时触发 | undefined &#124; (width: number) => any |
+| update:height | 高度变化时触发 | undefined &#124; (height: number) => any |
+| movingStart | 拖拽开始时触发 | undefined &#124; (ev: MouseEvent) => any |
+| moving | 拖拽或键盘调整中触发 | undefined &#124; (size: { width: number; height: number; }, ev: MouseEvent &#124; KeyboardEvent) => any |
+| movingEnd | 拖拽结束时触发 | undefined &#124; (ev: MouseEvent) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| resize-trigger | 自定义拖拽杆内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| resize-trigger-icon | 自定义拖拽杆图标 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type DirectionType = 'left' | 'right' | 'top' | 'bottom';
+```
+
+
+返回 [ResizeBox 用法](./resize-box.md)。

package/AI_USAGE/components/resize-box.md

@@ -0,0 +1,231 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# ResizeBox AI 使用
+
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
+
+先读 [通用接入](../core.md)。公开导出：`ResizeBox`；主要模型：v-model:width、v-model:height。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./resize-box-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/resize-box`（包含 base.css、resize-box.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/resize-box.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./resize-box-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于需要拖拽改变尺寸的面板、侧栏或编辑器区域。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ResizeBox } from 'x-next';
+import { ref } from 'vue';
+
+const width = ref(260);
+const height = ref(120);
+</script>
+<template>
+<ResizeBox
+    v-model:width="width"
+    v-model:height="height"
+    :max-width="520"
+    :max-height="260"
+    :directions="['right', 'bottom']"
+    class="demo-resize-box"
+  >
+    拖动右侧或底部边缘
+  </ResizeBox>
+</template>
+```
+
+### 受控尺寸
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Space, Button, ResizeBox } from 'x-next';
+import { ref } from 'vue';
+const controlledWidth = ref(280);
+const controlledHeight = ref(140);
+
+const width = controlledWidth;
+const height = controlledHeight;
+</script>
+<template>
+<Space>
+    <Button @click="width = 240">宽 240</Button>
+    <Button @click="width = 320">宽 320</Button>
+    <Button @click="height = 120">高 120</Button>
+    <Button @click="height = 180">高 180</Button>
+  </Space>
+  <ResizeBox
+    v-model:width="width"
+    v-model:height="height"
+    :max-width="520"
+    :max-height="260"
+    :directions="['right', 'bottom']"
+  >
+    {{ width }} x {{ height }}
+  </ResizeBox>
+</template>
+```
+
+### 尺寸限制
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ResizeBox } from 'x-next';
+import { ref } from 'vue';
+const limitedWidth = ref(280);
+const limitedHeight = ref(140);
+
+const width = limitedWidth;
+const height = limitedHeight;
+</script>
+<template>
+<ResizeBox
+    v-model:width="width"
+    v-model:height="height"
+    :min-width="200"
+    :max-width="360"
+    :min-height="100"
+    :max-height="220"
+    :directions="['right', 'bottom']"
+  >
+    宽度 200-360，高度 100-220
+  </ResizeBox>
+</template>
+```
+
+### 四方向拖拽
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ResizeBox } from 'x-next';
+import { ref } from 'vue';
+const directionWidth = ref(300);
+const directionHeight = ref(160);
+
+const width = directionWidth;
+const height = directionHeight;
+</script>
+<template>
+<ResizeBox
+    v-model:width="width"
+    v-model:height="height"
+    :max-width="520"
+    :max-height="260"
+    :directions="['left', 'right', 'top', 'bottom']"
+  >
+    四个方向均可拖拽
+  </ResizeBox>
+</template>
+```
+
+### 自定义触发杆
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ResizeBox } from 'x-next';
+import { ref } from 'vue';
+const customWidth = ref(280);
+const customHeight = ref(120);
+
+const width = customWidth;
+const height = customHeight;
+</script>
+<template>
+<ResizeBox
+    v-model:width="width"
+    v-model:height="height"
+    :max-width="520"
+    :max-height="260"
+    :directions="['right', 'bottom']"
+  >
+    自定义触发内容
+    <template #resize-trigger="{ direction }">
+      <div class="demo-resize-trigger">
+        {{ direction === 'right' ? '拖动' : '调整高度' }}
+      </div>
+    </template>
+  </ResizeBox>
+</template>
+```
+
+### 自定义触发图标
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ResizeBox } from 'x-next';
+
+</script>
+<template>
+<ResizeBox :width="260" :height="120" :max-width="520" :directions="['right']">
+    自定义图标
+    <template #resize-trigger-icon="{ direction }">
+      <span>{{ direction === 'right' ? '⋮' : '⋯' }}</span>
+    </template>
+  </ResizeBox>
+</template>
+```
+
+### 拖拽事件
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { ResizeBox } from 'x-next';
+import { ref } from 'vue';
+const eventWidth = ref(300);
+const eventHeight = ref(140);
+const eventLogs = ref<string[]>([]);
+const pushLog = (message: string) => {
+  eventLogs.value = [message, ...eventLogs.value].slice(0, 4);
+};
+
+const width = eventWidth;
+const height = eventHeight;
+</script>
+<template>
+<ResizeBox
+    v-model:width="width"
+    v-model:height="height"
+    :max-width="520"
+    :max-height="260"
+    :directions="['right', 'bottom']"
+    @moving-start="pushLog('开始拖拽')"
+    @moving="(size) => pushLog(`拖拽中：${size.width} x ${size.height}`)"
+    @moving-end="pushLog('结束拖拽')"
+  >
+    查看事件日志
+  </ResizeBox>
+</template>
+```
+
+### 配合 LayoutSidebar
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Layout, LayoutSidebar, LayoutContent } from 'x-next';
+
+</script>
+<template>
+<Layout>
+    <LayoutSidebar :width="220" :resize-directions="['right']">
+      可调整侧栏
+    </LayoutSidebar>
+    <LayoutContent>内容区域</LayoutContent>
+  </Layout>
+</template>
+```
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./resize-box-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/scrollbar-api.md

@@ -0,0 +1,77 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Scrollbar 完整公开 API
+
+适用版本：x-next@1.15.0；来源指纹：`47ea153587c8d0b3bf318977b10bde9f8dd4acff90c5818541ba6513252ad362`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Scrollbar API
+
+公开声明：`dist/components/scrollbar-v2/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| type | 滚动条类型，embed 悬浮在内容上，track 保留轨道空间 | undefined &#124; "embed" &#124; "track" | 否 | "embed" |
+| outerClass | 外层自定义类名 | undefined &#124; string &#124; { [x: string]: any; } &#124; unknown[] | 否 | 未声明 |
+| outerStyle | 外层自定义样式 | undefined &#124; null &#124; string &#124; false &#124; CSSProperties &#124; StyleValue[] | 否 | 未声明 |
+| hide | 隐藏自定义滚动条，内部兼容选项，不建议业务直接使用 | undefined &#124; false &#124; true | 否 | false |
+| disableHorizontal | 禁用横向滚动并隐藏横向自定义滚动条 | undefined &#124; false &#124; true | 否 | false |
+| disableVertical | 禁用纵向滚动并隐藏纵向自定义滚动条 | undefined &#124; false &#124; true | 否 | false |
+| horizontalWheel | 纯横向滚动时将鼠标滚轮转换为横向滚动，滚动到边界后放行页面滚动 | undefined &#124; false &#124; true | 否 | false |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| scroll | 内容滚动时触发 | undefined &#124; (ev: Event) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 滚动内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法 / 暴露值
+
+| 名称 | 公开类型 |
+| --- | --- |
+| scrollTo | (options?: number &#124; { left?: number; top?: number; }, y?: number) => void |
+| scrollTop | (top: number) => void |
+| scrollLeft | (left: number) => void |
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+interface ThumbData {
+    ratio: number;
+    thumbSize: number;
+    max: number;
+}
+
+interface ThumbMap {
+    size: 'width' | 'height';
+    direction: 'left' | 'top';
+    client: 'clientX' | 'clientY';
+}
+
+interface ScrollbarProps {
+    type?: 'track' | 'embed';
+    outerClass?: any;
+    outerStyle?: any;
+    /**
+     * Internal compatibility option for composite components.
+     * Hides custom thumbs but keeps native scrolling available.
+     */
+    hide?: boolean;
+    disableHorizontal?: boolean;
+    disableVertical?: boolean;
+    horizontalWheel?: boolean;
+}
+```
+
+
+返回 [Scrollbar 用法](./scrollbar.md)。