x-next 1.12.0 → 1.14.0

package/AI_USAGE/components/radio-api.md

@@ -0,0 +1,165 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Radio 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Radio API
+
+公开声明：`dist/components/form-radio/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| modelValue | 绑定值 | undefined &#124; string &#124; number &#124; false &#124; true | 否 | undefined |
+| defaultChecked | 默认是否选中，非受控模式 | undefined &#124; false &#124; true | 否 | false |
+| value | 选项值 | undefined &#124; string &#124; number &#124; false &#124; true | 否 | true |
+| name | 原生 input 的 name 属性，优先级高于 RadioGroup 的 name | undefined &#124; string | 否 | 未声明 |
+| id | 原生 input 的 id 属性 | undefined &#124; string | 否 | 未声明 |
+| type | 单选类型 | undefined &#124; "button" &#124; "radio" | 否 | "radio" |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| size | 组件尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 未声明 |
+| uninjectGroupContext | 见场景用法与类型 | undefined &#124; false &#124; true | 否 | false |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:modelValue | 值更新时触发 | undefined &#124; (value: RadioValue) => any |
+| change | 值变化时触发 | undefined &#124; (value: RadioValue, ev: Event) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 单选框文案 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| radio | 自定义单选框图形 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type RadioValue = string | number | boolean;
+
+interface RadioOption {
+    /**
+     * @zh 文案
+     * @en label content
+     */
+    label?: RenderContent;
+    /**
+     * @zh 选项的 `value`
+     * @en The `value` of the option
+     */
+    value: RadioValue;
+    /**
+     * @zh 是否禁用
+     * @en Whether to disable
+     */
+    disabled?: boolean;
+}
+
+declare const RADIO_TYPES: readonly ["radio", "button"];
+
+type RadioType = (typeof RADIO_TYPES)[number];
+
+interface RadioGroupContext {
+    name: 'XRadioGroup';
+    value: RadioValue;
+    size: Size;
+    type: RadioType;
+    disabled: boolean;
+    inputName?: string;
+    slots: Slots;
+    handleChange: (value: RadioValue, e: Event) => void;
+}
+```
+
+
+## RadioGroup API
+
+公开声明：`dist/components/form-radio/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| modelValue | 绑定值 | undefined &#124; string &#124; number &#124; false &#124; true | 否 | undefined |
+| defaultValue | 默认值，非受控模式 | undefined &#124; string &#124; number &#124; false &#124; true | 否 | "" |
+| type | 单选组类型 | undefined &#124; "button" &#124; "radio" | 否 | "radio" |
+| size | 单选组尺寸 | undefined &#124; "mini" &#124; "small" &#124; "medium" &#124; "large" | 否 | 未声明 |
+| options | 选项数据 | undefined &#124; (RadioValue &#124; RadioOption)[] | 否 | 未声明 |
+| name | 传给组内原生 input 的 name 属性，运行时修改会同步 | undefined &#124; string | 否 | 未声明 |
+| ariaLabel | 原生 radiogroup 的 aria-label 属性 | undefined &#124; string | 否 | 未声明 |
+| direction | 排列方向 | undefined &#124; "horizontal" &#124; "vertical" | 否 | "horizontal" |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:modelValue | 值更新时触发 | undefined &#124; (value: RadioValue) => any |
+| change | 值变化时触发 | undefined &#124; (value: RadioValue, ev: Event) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| default | 自定义单选框列表 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| label | 自定义 options 文案 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+| radio | 自定义单选框图形 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法
+
+没有检索到显式 expose 或 Options API methods 的公开方法；不把 setup 内部函数当成稳定实例 API。
+
+### 关联类型定义
+
+以下摘自本组件族声明，供查阅嵌套配置；运行时和值类型均以根入口可导出项为准。
+
+```typescript-reference
+type RadioValue = string | number | boolean;
+
+interface RadioOption {
+    /**
+     * @zh 文案
+     * @en label content
+     */
+    label?: RenderContent;
+    /**
+     * @zh 选项的 `value`
+     * @en The `value` of the option
+     */
+    value: RadioValue;
+    /**
+     * @zh 是否禁用
+     * @en Whether to disable
+     */
+    disabled?: boolean;
+}
+
+declare const RADIO_TYPES: readonly ["radio", "button"];
+
+type RadioType = (typeof RADIO_TYPES)[number];
+
+interface RadioGroupContext {
+    name: 'XRadioGroup';
+    value: RadioValue;
+    size: Size;
+    type: RadioType;
+    disabled: boolean;
+    inputName?: string;
+    slots: Slots;
+    handleChange: (value: RadioValue, e: Event) => void;
+}
+```
+
+
+返回 [Radio 用法](./radio.md)。

package/AI_USAGE/components/radio.md

@@ -1,12 +1,14 @@
 <!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
 # Radio AI 使用
 
-适用版本：x-next@1.12.0；来源指纹：`9f9adf42b42dc1e551f500aabdcb7fb07b69a93ea44ff3dc1d16dab1a4c85843`。
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
 
-先读 [通用接入](../core.md)。公开导出：`Radio`；模型：v-model；已核对事件：change。
+先读 [通用接入](../core.md)。公开导出：`Radio, RadioGroup`；主要模型：v-model。完整 Props、Events、Slots、实例方法与服务签名见 [本地 API](./radio-api.md)，包含本组件族全部子组件和别名。
 
 按需样式：`x-next/style/form-radio`（包含 base.css、form-radio.css）。代码块未单独引样式时在应用入口加载全量样式，或按实际所有组件加载 JS 入口；不要仅因复制一个组件页就漏掉其中的 Button 等组合依赖。
 
+## 已核验行为与示例
+
 [组件文档与 live demo](https://x-next.yjmf.com/components/radio)。`Radio` / `RadioGroup` 的模型和选项值支持 `string | number | boolean`，保留值类型；布尔选项写 `:value="true"`。单个 Radio 的 `value` 默认 `true`，组的非受控默认值为 `''`。
 
 组默认 `type='radio'`、`direction='horizontal'`、`disabled=false`；`change(value, event)` 返回选项值和 `Event`。Radio 默认插槽是文案，组也支持 `options` 和 `label` / `radio` 插槽。
@@ -32,4 +34,258 @@ function changed(value: string | number | boolean, _event: Event) {
 </template>
 ```
 
-返回 [AI 索引](../index.md)。精选示例不是完整 API 表，新能力先查同版本公开类型与组件文档。
+## 场景用法
+
+以下示例从本地 `src/docs/components/radio.md` 显式导入到独立 AI 源，补齐局部注册、状态和样式后进行严格模板检查。上方已核验行为优先；原始 prop 默认值、包装透传和示例业务适配分别查 [完整 API](./radio-api.md) 与场景说明。类型通过不代表所有散文和交互已验证。
+
+### 用途与选型
+
+用于在一组互斥选项中选择一个结果，适合状态切换、筛选条件、配置项选择。
+
+
+### 何时使用
+
+- 多个选项互斥，且用户必须或通常只选择一个。
+- 选项数量较少，需要直接展示全部选项。
+- 需要用按钮样式表达更强的分段控制感。
+
+
+### 基础用法
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { RadioGroup, Radio } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('a');
+</script>
+<template>
+<RadioGroup v-model="value" name="basic-radio">
+    <Radio value="a">选项 A</Radio>
+    <Radio value="b">选项 B</Radio>
+  </RadioGroup>
+</template>
+```
+
+### 选项配置
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { RadioGroup } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('day');
+const options = [
+  { label: '今日', value: 'day' },
+  { label: '本周', value: 'week' },
+  { label: '本月', value: 'month' },
+];
+</script>
+<template>
+<RadioGroup v-model="value" :options="options" name="time-radio" />
+</template>
+```
+
+### 禁用状态
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { RadioGroup } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref('enabled');
+const options = [
+  { label: '启用', value: 'enabled' },
+  { label: '禁用项', value: 'disabled', disabled: true },
+  { label: '归档', value: 'archived' },
+];
+</script>
+<template>
+<RadioGroup v-model="value" :options="options" />
+  <RadioGroup v-model="value" :options="options" disabled />
+</template>
+```
+
+### 按钮样式
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { RadioGroup } from 'x-next';
+import { ref } from 'vue';
+const value = ref('design');
+const options = [{ label: '设计', value: 'design' }, { label: '开发', value: 'dev' }, { label: '测试', value: 'test' }];
+</script>
+<template>
+<RadioGroup v-model="value" type="button" :options="options" />
+</template>
+```
+
+### 尺寸
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { RadioGroup } from 'x-next';
+import { ref } from 'vue';
+const value = ref('design');
+const options = [{ label: '设计', value: 'design' }, { label: '开发', value: 'dev' }, { label: '测试', value: 'test' }];
+</script>
+<template>
+<RadioGroup v-model="value" type="button" size="mini" :options="options" />
+  <RadioGroup v-model="value" type="button" size="small" :options="options" />
+  <RadioGroup v-model="value" type="button" size="medium" :options="options" />
+  <RadioGroup v-model="value" type="button" size="large" :options="options" />
+</template>
+```
+
+### 纵向排列
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { RadioGroup } from 'x-next';
+import { ref } from 'vue';
+const value = ref('design');
+const options = [{ label: '设计', value: 'design' }, { label: '开发', value: 'dev' }, { label: '测试', value: 'test' }];
+</script>
+<template>
+<RadioGroup v-model="value" direction="vertical" :options="options" />
+</template>
+```
+
+### 自定义文案
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { RadioGroup } from 'x-next';
+import { ref } from 'vue';
+const value = ref('design');
+const options = [{ label: '设计', value: 'design' }, { label: '开发', value: 'dev' }, { label: '测试', value: 'test' }];
+</script>
+<template>
+<RadioGroup v-model="value" :options="options">
+    <template #label="{ data }">
+      <span>{{ data.label }}角色</span>
+    </template>
+  </RadioGroup>
+</template>
+```
+
+### 自定义单选框图形
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { RadioGroup } from 'x-next';
+import { ref } from 'vue';
+const value = ref('design');
+const options = [{ label: '设计', value: 'design' }, { label: '开发', value: 'dev' }, { label: '测试', value: 'test' }];
+</script>
+<template>
+<RadioGroup v-model="value" :options="options">
+    <template #radio="{ checked, disabled }">
+      <span :class="{ 'is-checked': checked, 'is-disabled': disabled }" />
+    </template>
+  </RadioGroup>
+</template>
+```
+
+### 布尔值选项
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { RadioGroup } from 'x-next';
+import { ref } from 'vue';
+
+const value = ref(true);
+const options = [
+  { label: '启用', value: true },
+  { label: '停用', value: false },
+];
+</script>
+<template>
+<RadioGroup v-model="value" :options="options" />
+</template>
+```
+
+### 事件
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { RadioGroup } from 'x-next';
+const eventOptions = [
+  { label: '读取', value: 'read' },
+  { label: '写入', value: 'write' },
+  { label: '发布', value: 'publish' },
+];
+
+import { ref } from 'vue';
+
+const value = ref('read');
+const handleChange = (value: string | number | boolean) => {
+  console.log(value);
+};
+const options = eventOptions;
+</script>
+<template>
+<RadioGroup v-model="value" :options="options" @change="handleChange" />
+</template>
+```
+
+### 在 Form 中校验
+
+组件放进 `x-form-item` 后会自动继承 Form 的尺寸与禁用状态，并按 FormItem 的校验规则展示错误。默认 `validateTrigger` 为 `change`，即值变化时触发校验。
+
+```vue
+<script setup lang="ts">
+import 'x-next/style.css';
+import { Form, FormItem, RadioGroup, Radio, Space, Button } from 'x-next';
+import { reactive, ref } from 'vue';
+import type { FormInstance, FieldRule } from 'x-next';
+
+const formState = reactive({ plan: undefined as string | undefined });
+const formRules: Record<string, FieldRule[]> = {
+  plan: [{ 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="plan" label="套餐">
+      <RadioGroup v-model="formState.plan">
+      <Radio value="basic">基础版</Radio>
+      <Radio value="pro">专业版</Radio>
+    </RadioGroup>
+    </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](./radio-api.md)；需要更深类型时查 [公开组件导航](../catalog.md)，不默认上网查找本包用法。

package/AI_USAGE/components/rate-api.md

@@ -0,0 +1,54 @@
+<!-- Generated by pnpm generate:ai-usage. Edit script/ai-usage/content.md and script/ai-usage/. -->
+# Rate 完整公开 API
+
+适用版本：x-next@1.14.0；来源指纹：`014984639d816a2c7e25eb22690c586b0b2e8efba6846bec8a4e424db41a09e9`。
+
+从同版本构建的公开声明、运行时 props/emits 和显式 expose 生成。运行时导入始终使用 `x-next`，声明路径仅作定位。插槽类型未细化时，具体槽名与作用域见本地用法示例。
+
+## Rate API
+
+公开声明：`dist/components/rate/index.d.ts`。 类型中的 undefined 表示可省略；原始 prop 默认值不等于继承配置或服务默认值。
+
+### Props
+
+| 名称 | 用途 | 公开类型 | 必填 | 声明默认值 |
+| --- | --- | --- | --- | --- |
+| count | 评分总数，grading 开启时固定为 5 | undefined &#124; number | 否 | 5 |
+| modelValue | 绑定值 | undefined &#124; number | 否 | undefined |
+| defaultValue | 默认值，非受控模式 | undefined &#124; number | 否 | 0 |
+| allowHalf | 是否允许半选 | undefined &#124; false &#124; true | 否 | false |
+| allowClear | 是否允许再次点击清除 | undefined &#124; false &#124; true | 否 | false |
+| grading | 是否开启笑脸分级 | undefined &#124; false &#124; true | 否 | false |
+| readonly | 是否只读 | undefined &#124; false &#124; true | 否 | false |
+| disabled | 是否禁用 | undefined &#124; false &#124; true | 否 | false |
+| autofocus | 是否自动获取焦点 | undefined &#124; false &#124; true | 否 | false |
+| tabindex | 根节点 tabindex | undefined &#124; string &#124; number | 否 | 0 |
+| tooltips | 每项提示文本 | undefined &#124; string[] | 否 | 未声明 |
+| color | 评分颜色，支持统一颜色或分段阈值颜色 | undefined &#124; string &#124; { [x: number]: string; } | 否 | 未声明 |
+
+### Events
+
+| 事件 | 用途 | 监听器签名（即事件参数） |
+| --- | --- | --- |
+| update:modelValue | 绑定值更新时触发 | undefined &#124; (value: number) => any |
+| change | 评分改变时触发 | undefined &#124; (value: number) => any |
+| hoverChange | 鼠标移入评分项或移出组件时触发 | undefined &#124; (value: number &#124; undefined) => any |
+| focus | 组件获得焦点时触发 | undefined &#124; (ev: FocusEvent) => any |
+| blur | 组件失去焦点时触发 | undefined &#124; (ev: FocusEvent) => any |
+| keydown | 键盘按下时触发 | undefined &#124; (ev: KeyboardEvent) => any |
+
+### Slots
+
+| 名称 | 用途 | 公开类型 |
+| --- | --- | --- |
+| character | 自定义评分符号 | 文档列出的实际插槽；公开类型未细化，作用域见场景用法 |
+
+### 实例方法 / 暴露值
+
+| 名称 | 公开类型 |
+| --- | --- |
+| focus | 公开声明未细化（用法和实现已显式暴露） |
+| blur | 公开声明未细化（用法和实现已显式暴露） |
+
+
+返回 [Rate 用法](./rate.md)。