x-next 1.12.0 → 1.14.0

package/AI_USAGE/components/tag.md

@@ -0,0 +1,292 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Tag AI 使用
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+先读 [通用接入](../core.md)。公开导出：`Tag`；主要模型：v-model:visible、v-model:checked。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./tag-api.md)，包含本组件族全部子组件和别名。
+
+按需样式：`x-next/style/tag`（包含 base.css、tag.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
+
+## 场景用法
+
+以下示例从本地 `src/docs/components/tag.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./tag-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于标记状态、属性、分类或筛选条件，常见于列表、表格、详情页和筛选区域。
+
+
+### 何时使用
+
+- 标记对象的状态、分类、来源或属性。
+- 展示可关闭的筛选条件。
+- 用作轻量级的可选项，但不承载复杂表单交互。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tag } from 'x-next';
+
+</script>
+<template>
+<Tag>默认标签</Tag>
+  <Tag color="blue">蓝色标签</Tag>
+  <Tag color="green">绿色标签</Tag>
+  <Tag color="#0f766e">自定义颜色</Tag>
+</template>
+```
+
+### 内置颜色
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tag } from 'x-next';
+const colors = [
+  'red',
+  'orangered',
+  'orange',
+  'gold',
+  'lime',
+  'green',
+  'cyan',
+  'blue',
+  'better-blue',
+  'purple',
+  'pink-purple',
+  'magenta',
+  'gray',
+];
+</script>
+<template>
+<Tag v-for="color in colors" :key="color" :color="color">
+    {{ color }}
+  </Tag>
+</template>
+```
+
+### 尺寸
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tag } from 'x-next';
+
+</script>
+<template>
+<Tag size="small">小型标签</Tag>
+  <Tag>中型标签</Tag>
+  <Tag size="large">大型标签</Tag>
+</template>
+```
+
+### 带边框
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tag } from 'x-next';
+
+</script>
+<template>
+<Tag bordered>默认边框</Tag>
+  <Tag color="blue" bordered>蓝色边框</Tag>
+  <Tag color="green" bordered>绿色边框</Tag>
+  <Tag color="magenta" bordered>品红边框</Tag>
+</template>
+```
+
+### 可关闭
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tag, Button } from 'x-next';
+import { ref } from 'vue';
+
+const visible = ref(true);
+const closeCount = ref(0);
+const handleClose = () => { closeCount.value += 1; };
+</script>
+<template>
+<Tag closable>可关闭</Tag>
+  <Tag color="orange" closable @close="handleClose">关闭事件</Tag>
+  <Tag v-model:visible="visible" color="purple" closable>受控显示</Tag>
+  <Button size="mini" @click="visible = true">重置</Button>
+  <span aria-live="polite">关闭事件：{{ closeCount }}</span>
+</template>
+```
+
+### 可选择
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tag } from 'x-next';
+import { ref } from 'vue';
+
+const checked = ref(true);
+</script>
+<template>
+<Tag selectable>默认可选</Tag>
+  <Tag color="red" selectable :default-checked="false">未选中</Tag>
+  <Tag v-model:checked="checked" color="better-blue" selectable>受控选择</Tag>
+  <span>当前：{{ checked ? '已选' : '未选' }}</span>
+</template>
+```
+
+### 加载中
+
+`loading` 展示加载图标，保持文字不透明；它不会阻止选择或关闭。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tag } from 'x-next';
+
+</script>
+<template>
+<Tag loading>同步中</Tag>
+  <Tag color="blue" loading>发布中</Tag>
+  <Tag color="#0f766e" loading>自定义颜色</Tag>
+</template>
+```
+
+### 图标与自定义关闭图标
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tag } from 'x-next';
+
+</script>
+<template>
+<Tag color="green">
+    <template #icon>
+      <span aria-hidden="true">✓</span>
+    </template>
+    已完成
+  </Tag>
+  <Tag color="orange" closable>
+    <template #close-icon>
+      <span aria-hidden="true">x</span>
+    </template>
+    自定义关闭
+  </Tag>
+</template>
+```
+
+### 动态编辑
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tag, Input } from 'x-next';
+import { ref } from 'vue';
+
+const dynamicTags = ref(['Vue', 'TypeScript', 'VitePress']);
+const editing = ref(false);
+const newTag = ref('');
+
+const removeTag = (tag: string) => {
+  dynamicTags.value = dynamicTags.value.filter((item) => item !== tag);
+};
+
+const addTag = () => {
+  const value = newTag.value.trim();
+  if (value && !dynamicTags.value.includes(value)) {
+    dynamicTags.value.push(value);
+  }
+  newTag.value = '';
+  editing.value = false;
+};
+const nativeEvents = { click: () => { editing.value = true; } };
+</script>
+<template>
+<Tag v-for="tag in dynamicTags" :key="tag" closable @close="removeTag(tag)">
+    {{ tag }}
+  </Tag>
+  <Input
+    v-if="editing"
+    v-model="newTag"
+    size="mini"
+    placeholder="新增标签"
+    style="width: 96px"
+    @press-enter="addTag"
+    @blur="addTag"
+  />
+  <Tag v-else bordered v-on="nativeEvents">+ 新增</Tag>
+</template>
+```
+
+### 不换行
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Tag } from 'x-next';
+
+</script>
+<template>
+<Tag nowrap style="max-width: 180px">
+    这是一段很长但不会换行的标签内容
+  </Tag>
+</template>
+```
+
+### 亮暗颜色与选择反馈
+
+内置色的文字色与背景分开定义。取消选择后恢复默认文字和透明背景，再次选中恢复对应颜色；悬浮仍有默认弱底反馈。下例可切换局部暗色，并通过页面计数确认 `check` 回调。
+
+这里用 `visible=true` 展示受控关闭：按钮会触发 `close`，父层未更新 visible 时标签仍保留，关闭不会触发选择。自定义色默认用白字，亮色背景需显式覆盖 `--x-tag-custom-color-text`，组件不自动推导任意 CSS 背景的前景色。页面为暗色时，请先切回亮色观察局部对照；`dark=false` 不会重置暗色祖先。
+
+`selectable` 当前支持鼠标切换，尚未提供键盘选择和独立 disabled 属性；关闭按钮可通过 Tab 聚焦后用 Enter 或 Space 激活。
+
+```vue
+<script setup lang="ts">
+const visible = ref(true);
+
+import { ref } from 'vue';
+import { ConfigProvider as XConfigProvider, Switch as XSwitch, Tag as XTag } from 'x-next';
+import 'x-next/style.css';
+
+const dark = ref(false);
+const checks = ref(0);
+const closes = ref(0);
+const colors = ['red', 'orangered', 'orange', 'gold', 'lime', 'green', 'cyan', 'blue', 'better-blue', 'purple', 'pink-purple', 'magenta', 'gray'];
+</script>
+<template>
+<label><XSwitch v-model="dark" />切换标签暗色</label>
+  <XConfigProvider :dark="dark" class="color-scope">
+    <div class="color-row">
+      <XTag v-for="color in colors" :key="color" :color="color" selectable bordered closable :visible="true" @check="checks++" @close="closes++">{{ color }}</XTag>
+      <XTag color="gold" loading>加载颜色</XTag>
+      <XTag color="#ffb800" selectable style="--x-tag-custom-color-text: var(--x-color-constant-dark)">自定义亮色</XTag>
+    </div>
+    <p aria-live="polite">选择事件：{{ checks }}；关闭事件：{{ closes }}</p>
+  </XConfigProvider>
+</template>
+<style scoped>
+.color-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+}
+.color-scope {
+  padding: 16px;
+  color: var(--x-color-text-primary);
+  background: var(--x-color-bg-surface);
+}
+</style>
+```
+
+### TagColor
+
+`red`、`orangered`、`orange`、`gold`、`lime`、`green`、`cyan`、`blue`、`better-blue`、`purple`、`pink-purple`、`magenta`、`gray`
+
+
+
+返回 [AI 索引](../index.md)。先查本页与 [本地 API](./tag-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/textarea-api.md

@@ -0,0 +1,55 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Textarea 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Textarea API
+
+公开声明：`dist/components/form-textarea/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| modelValue | 绑定值 | undefined &#124; string | 否 | 未声明 |
+| defaultValue | 默认值，非受控模式 | undefined &#124; string | 否 | "" |
+| placeholder | 占位提示 | undefined &#124; string | 否 | 未声明 |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| error | 是否为错误状态 | undefined &#124; false &#124; true | 否 | false |
+| size | 组件尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 未声明 |
+| maxLength | 最大长度；传入 errorOnly 时仅展示错误状态，不截断输入 | undefined &#124; number &#124; { length: number; errorOnly?: boolean; } | 否 | 0 |
+| showWordLimit | 是否显示字数统计 | undefined &#124; false &#124; true | 否 | false |
+| allowClear | 是否允许清空 | undefined &#124; false &#124; true | 否 | false |
+| autoSize | 是否自适应高度，可配置最小和最大行数 | undefined &#124; false &#124; true &#124; { minRows?: number; maxRows?: number; } | 否 | false |
+| wordLength | 自定义字符长度计算方法 | undefined &#124; (value: string) => number | 否 | 未声明 |
+| wordSlice | 自定义超长截取方法，通常与 wordLength 一起使用 | undefined &#124; (value: string, maxLength: number) => string | 否 | 未声明 |
+| textareaAttrs | 透传给内部 textarea 的原生属性 | undefined &#124; { [x: string]: any; } | 否 | 未声明 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:modelValue | 值更新时触发 | undefined &#124; (value: string) => any |
+| input | 用户输入时触发 | undefined &#124; (value: string, ev: Event) => any |
+| change | 文本域失焦且值变化时触发 | undefined &#124; (value: string, ev: Event) => any |
+| clear | 点击清除按钮时触发 | undefined &#124; (ev: MouseEvent) => any |
+| focus | 获取焦点时触发 | undefined &#124; (ev: FocusEvent) => any |
+| blur | 失去焦点时触发 | undefined &#124; (ev: FocusEvent) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| suffix | 后缀内容 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法 / 暴露值
+
+| 名称 | 公开类型 |
+| --- | --- |
+| focus | () => void |
+| blur | () => void |
+
+
+返回 [Textarea 用法](./textarea.md)。

package/AI_USAGE/components/textarea.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Textarea AI 使用
 
-适用版本：x-next@1.12.0；来源指纹：`9f9adf42b42dc1e551f500aabdcb7fb07b69a93ea44ff3dc1d16dab1a4c85843`。
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
 
-先读 [通用接入](../core.md)。公开导出：`Textarea`；模型：v-model；已核对事件：input、change、clear。
+先读 [通用接入](../core.md)。公开导出：`Textarea`；主要模型：v-model。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./textarea-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`x-next/style/form-textarea`（包含 base.css、form-textarea.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
 
+## 已核验行为与示例
+
 [组件文档与 live demo](https://x-next.yjmf.com/components/textarea)。`v-model` 为字符串，`input/change/clear` 与输入生命周期联动。原生 id、name、aria、rows、readonly 用 `textareaAttrs`，不支持组件层的 readonly prop；autoSize 控制自动高度。
 
 ```vue
@@ -28,4 +30,325 @@ const readonlyAttrs = { id: 'saved-summary', name: 'savedSummary', 'aria-label':
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/textarea.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./textarea-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于多行文本输入，适合备注、描述、评论等较长内容。
+
+
+### 何时使用
+
+- 需要输入多行内容，例如备注、描述、审批意见、评论。
+- 需要限制或提示字数，并在输入时展示统计。
+- 需要根据内容自动调整高度。
+- 需要在表单中展示禁用、只读、错误等状态。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Textarea } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('用于搭建业务系统的 Vue 3 组件库');
+</script>
+<template>
+<Textarea v-model="value" placeholder="请输入描述" />
+</template>
+```
+
+### 可清除
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Textarea } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('这段内容可以一键清空');
+</script>
+<template>
+<Textarea v-model="value" allow-clear placeholder="请输入内容" />
+</template>
+```
+
+### 字数统计
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Textarea } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('Textarea 支持字数统计和清除操作');
+</script>
+<template>
+<Textarea
+    v-model="value"
+    :max-length="80"
+    show-word-limit
+    allow-clear
+    placeholder="请输入不超过 80 个字符"
+  />
+</template>
+```
+
+### 仅提示错误
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Textarea } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('这段内容允许超出限制，但会进入错误状态');
+</script>
+<template>
+<Textarea
+    v-model="value"
+    :max-length="{ length: 20, errorOnly: true }"
+    show-word-limit
+    allow-clear
+  />
+</template>
+```
+
+### 自适应高度
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Textarea } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('自适应高度会随内容增长，并在达到 maxRows 后出现滚动条。');
+</script>
+<template>
+<Textarea
+    v-model="value"
+    :auto-size="{ minRows: 2, maxRows: 5 }"
+    :max-length="160"
+    show-word-limit
+    allow-clear
+  />
+</template>
+```
+
+### 动态切换自适应高度
+
+开启后立即按内容计算高度；关闭后恢复手动纵向拉伸。修改 `minRows`、`maxRows` 或 `size` 时会重新计算。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Checkbox, Textarea } from 'x-next';
+import { ref } from 'vue';
+const enabled = ref(false);
+const value = ref('第一行\n第二行\n第三行\n第四行');
+</script>
+<template>
+<Checkbox v-model="enabled">启用自动高度（2 至 4 行）</Checkbox>
+  <Textarea v-model="value" :auto-size="enabled ? { minRows: 2, maxRows: 4 } : false" allow-clear />
+</template>
+```
+
+### 尺寸
+
+各尺寸档会同时调整最小高度、字号与内边距；`size` 变化后自适应高度会重新计算。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Textarea } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('四种尺寸的文本域');
+</script>
+<template>
+<Textarea v-model="value" size="mini" />
+  <Textarea v-model="value" size="small" />
+  <Textarea v-model="value" size="medium" />
+  <Textarea v-model="value" size="large" />
+</template>
+```
+
+### 禁用与状态
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Textarea } from 'x-next';
+import { ref } from 'vue';
+
+const disabledValue = ref('禁用状态不可编辑');
+const readonlyValue = ref('只读状态通过 textareaAttrs 透传给原生 textarea');
+const errorValue = ref('错误状态用于校验失败提示');
+</script>
+<template>
+<Textarea v-model="disabledValue" disabled />
+  <Textarea v-model="readonlyValue" :textarea-attrs="{ readonly: true }" />
+  <Textarea v-model="errorValue" error show-word-limit :max-length="20" />
+</template>
+```
+
+### 后缀内容
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Textarea } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('审批备注需要更明确的填写状态');
+</script>
+<template>
+<Textarea v-model="value" :max-length="80" show-word-limit>
+    <template #suffix>
+      <span>备注</span>
+    </template>
+  </Textarea>
+</template>
+```
+
+### 原生属性
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Textarea } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('内部 textarea 可以接收 rows、name、required 等原生属性');
+</script>
+<template>
+<Textarea
+    v-model="value"
+    :textarea-attrs="{ rows: 4, name: 'description', required: true, autocomplete: 'off' }"
+  />
+</template>
+```
+
+### 自定义长度计算
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Textarea } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('中文算 2，English 算 1');
+
+const getMixedLength = (value: string) =>
+  Array.from(value).reduce((total, char) => total + (char.charCodeAt(0) > 255 ? 2 : 1), 0);
+
+const sliceMixedLength = (value: string, maxLength: number) => {
+  let total = 0;
+  let result = '';
+
+  for (const char of Array.from(value)) {
+    const next = total + (char.charCodeAt(0) > 255 ? 2 : 1);
+    if (next > maxLength) break;
+    total = next;
+    result += char;
+  }
+
+  return result;
+};
+</script>
+<template>
+<Textarea
+    v-model="value"
+    :max-length="20"
+    show-word-limit
+    :word-length="getMixedLength"
+    :word-slice="sliceMixedLength"
+    allow-clear
+  />
+</template>
+```
+
+### 事件
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Textarea } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('修改内容后失焦会触发 change');
+const logs = ref<string[]>([]);
+
+const pushLog = (message: string) => {
+  logs.value = [message, ...logs.value].slice(0, 5);
+};
+</script>
+<template>
+<Textarea
+    v-model="value"
+    allow-clear
+    :max-length="80"
+    show-word-limit
+    @input="(value) => pushLog(`input: ${value.length}`)"
+    @change="(value) => pushLog(`change: ${value.length}`)"
+    @clear="() => pushLog('clear')"
+    @focus="() => pushLog('focus')"
+    @blur="() => pushLog('blur')"
+  />
+  <div>
+    <div v-for="(log, index) in logs" :key="`${index}-${log}`">{{ log }}</div>
+  </div>
+</template>
+```
+
+### 在 Form 中校验
+
+组件放进 `x-form-item` 后会自动继承 Form 的尺寸与禁用状态，并按 FormItem 的校验规则展示错误。默认 `validateTrigger` 为 `change`，即值变化时触发校验。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, Textarea, Space, Button } from 'x-next';
+import { reactive, ref } from 'vue';
+import type { FormInstance, FieldRule } from 'x-next';
+
+const formState = reactive({ description: "" });
+const formRules: Record<string, FieldRule[]> = {
+  description: [{ required: 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="description" label="描述">
+      <Textarea v-model="formState.description" placeholder="请输入描述" allow-clear />
+    </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](./textarea-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。