@kayak-sj/design 1.0.49 → 1.0.51

package/dist/components/k-editor/utils/editorValue.d.ts

@@ -1,31 +1,71 @@
 import { KEditorModelValue, KEditorValue } from '../types';
-/** 从 string / { html } 中取出 HTML，供 setHtml 与只读展示使用 */
+/**
+ * 从 string / `{ html }` 中取出 HTML，供 `setHtml` 与只读展示使用。
+ *
+ * @param value - KEditor v-model（string 或 `{ html, length? }`）
+ * @returns HTML 字符串；空值时返回 `''`
+ */
 export declare function getEditorHtml(value: KEditorModelValue): string;
 /**
  * HTML → 纯文本（去标签与常见实体），供回填 / 校验字数使用。
- * 与编辑器 getText() 结果对齐的近似实现（无 DOM 依赖，可在 Node/SSR 用）。
+ * 与编辑器 `getText()` 结果对齐的近似实现（无 DOM 依赖，可在 Node/SSR 用）。
+ *
+ * @param html - 富文本 HTML
+ * @returns 去标签后的纯文本
  */
 export declare function stripEditorHtml(html: string): string;
 /**
  * 字数统计（对齐 legacy k-editor）。
- * 去除  、换行与空白后计字符数。入参应为纯文本（如 editor.getText()）。
+ * 去除 ` `、换行与空白后计字符数。入参应为纯文本（如 `editor.getText()`）。
+ *
+ * @param text - 纯文本
+ * @returns 字数
  */
 export declare function countEditorWords(text: string): number;
 /**
- * 按 HTML 计字：先去标签再走 countEditorWords。
- * 表单校验 / 接口回填 length 请用此方法，勿用 html.length。
+ * 按 HTML 计字：先去标签再走 {@link countEditorWords}。
+ * 表单校验 / 接口回填 `length` 请用此方法，勿用 `html.length`。
+ *
+ * @param html - 富文本 HTML
+ * @returns 字数
  */
 export declare function countEditorHtmlWords(html: string): number;
-/** 从 v-model 值取字数（string | { html, length }）；表单 validator 可直接传入 value */
+/**
+ * 从 v-model 值取字数（string | `{ html, length }`）；表单 validator 可直接传入 value。
+ *
+ * @param value - KEditor v-model 或未知表单值
+ * @returns 字数；空值时返回 `0`
+ */
 export declare function getEditorWordCount(value: KEditorModelValue | unknown): number;
-/** 构造 emit 载荷；无内容时 html 归一为 '' */
+/**
+ * 构造 emit 载荷；无内容时 `html` 归一为 `''`。
+ *
+ * @param html - 当前 HTML
+ * @param length - 字数（通常来自 {@link countEditorHtmlWords}）
+ * @returns `{ html, length }`
+ */
 export declare function buildEditorEmitValue(html: string, length: number): KEditorValue;
 /**
  * 接口 HTML → KEditor v-model。
- * length 与编辑器字数统计一致，供 setValues / 默认值回填。
+ * `length` 与编辑器字数统计一致，供 `setValues` / 默认值回填。
+ *
+ * @param html - 接口返回的 HTML；`null` / `undefined` 按空串处理
+ * @returns `{ html, length }`
  */
 export declare function toKEditorValue(html?: string | null): KEditorValue;
-/** 解析 maxWordCount / maxLength；无效或非正数返回 undefined（不限制） */
+/**
+ * 解析 `maxWordCount` / `maxLength`；无效或非正数返回 `undefined`（不限制）。
+ *
+ * @param maxWordCount - 优先使用的字数上限
+ * @param maxLength - 兼容旧字段名
+ * @returns 正数上限，或 `undefined` 表示不限制
+ */
 export declare function resolveMaxWordCount(maxWordCount?: number | string, maxLength?: number | string): number | undefined;
-/** 外部 modelValue 变更时，仅比较 html 避免重复 setHtml */
+/**
+ * 外部 `modelValue` 变更时，仅比较 html 避免重复 `setHtml`。
+ *
+ * @param a - 旧值
+ * @param b - 新值
+ * @returns 两者 HTML 是否相同
+ */
 export declare function isSameEditorHtml(a: KEditorModelValue, b: KEditorModelValue): boolean;

package/dist/components/k-form/composables/useFormSchema.d.ts

@@ -5,6 +5,11 @@ import { KFormConfigItem, KFormSchemaField } from '../types';
  *
  * 不 mutate 入参，每次根据当前 model 重新计算 display / readonly / disabled / options。
  * 替代旧版 formConfigFactory + FMSetDisplay 突变 formConfigs 的写法。
+ *
+ * @typeParam T - 表单 model 类型
+ * @param field - 带 `visibleWhen` / `optionsFromModel` 等声明的 schema 字段
+ * @param model - 当前表单 model（用于求值依赖）
+ * @returns 可直接交给 `KForm` 的 `KFormConfigItem`
  */
 export declare function resolveSchemaField<T>(field: KFormSchemaField<T>, model: T): KFormConfigItem;
 export interface UseFormSchemaOptions {
@@ -17,6 +22,12 @@ export interface UseFormSchemaOptions {
 /**
  * 根据 model 派生表单 schema（computed，只读）。
  *
+ * @typeParam T - 表单 model 类型
+ * @param baseFields - 静态或响应式 schema 字段列表
+ * @param model - 表单 model（plain / ref / getter）
+ * @param options - 见 {@link UseFormSchemaOptions}；`excludeHidden` 控制是否剔除隐藏字段
+ * @returns 解析后的 `KFormConfigItem[]` computed，可绑 `:form-configs`
+ *
  * @example
  * ```ts
  * const model = ref({ menu_type: 'C', grant: '0' })
@@ -28,5 +39,10 @@ export declare function useFormSchema<T>(baseFields: MaybeRefOrGetter<KFormSchem
 /**
  * 批量设置字段可见性（返回新 schema，不 mutate 原数组）。
  * 便于从旧版 FMSetDisplay 迁移到一次性映射。
+ *
+ * @typeParam T - 表单 model 类型
+ * @param fields - 原始 schema 字段列表
+ * @param visibility - 按字段 `id` 索引的显隐映射；未出现的字段保持原样
+ * @returns 写入 `visibleWhen` 后的新 schema 数组
  */
 export declare function mapFieldVisibility<T>(fields: KFormSchemaField<T>[], visibility: Partial<Record<string, boolean>>): KFormSchemaField<T>[];

package/dist/components/k-form/composables/useKFormFields.d.ts

@@ -6,8 +6,13 @@ export interface FieldOption {
     disabled?: boolean;
 }
 /**
- * 表单项展示层逻辑：可见性过滤、查询区 hideLabel、字典选项、flex 布局。
- * 字典通过 inject(DICT_KEY)，与 KTable 列翻译共用同一数据源。
+ * 表单项展示层逻辑：可见性过滤、查询区 `hideLabel`、字典选项、flex 布局。
+ * 字典通过 `inject(DICT_KEY)`，与 KTable 列翻译共用同一数据源。
+ *
+ * @param options.formConfigs - 表单字段配置（响应式）
+ * @param options.layout - 布局选项（含 `hideLabel` 等）
+ * @param options.formReadonly - 整表只读时跳过校验、渲染纯文本
+ * @returns `normalizedConfigs` 与字段 options / rules / 样式辅助方法
  */
 export declare function useKFormFields(options: {
     formConfigs: Ref<KFormConfigItem[]>;

package/dist/components/k-form/composables/useKFormModel.d.ts

@@ -4,10 +4,27 @@ import { KFormConfigItem } from '../types';
  * 表单 model 单一数据源。
  *
  * 两种模式：
- * - **非受控**（查询面板）：仅内部 formModel，通过 getParams / validateFields 取值
- * - **受控**（v-model）：父级 model 为真相，内部 formModel 与之双向同步
+ * - **非受控**（查询面板）：仅内部 `formModel`，通过 `getParams` / `validateFields` 取值
+ * - **受控**（v-model）：父级 model 为真相，内部 `formModel` 与之双向同步
  *
- * - firsthandModel：reset 时恢复的快照（受控 / 非受控均记录；受控 reset 后会 publish 回父级）
+ * - `firsthandModel`：reset 时恢复的快照（受控 / 非受控均记录；受控 reset 后会 publish 回父级）
+ *
+ * @param options.formConfigs - 表单字段配置（响应式）
+ * @param options.modelValue - v-model 绑定值（受控模式）
+ * @param options.data - @deprecated 优先使用 `modelValue`
+ * @param options.controlled - `props.modelValue !== undefined` 时为 true
+ * @param options.onChange - 模型变更回调（受控时用于 `emit('update:modelValue')`）
+ * @returns `formModel` 与字段读写 / 重置方法，供 `KForm.vue` 使用
+ *
+ * @example
+ * ```ts
+ * const { formModel, setFieldsValue, getVisibleFieldsValue, resetFormModel } = useKFormModel({
+ *   formConfigs,
+ *   modelValue,
+ *   controlled,
+ *   onChange: (values) => emit('update:modelValue', values)
+ * })
+ * ```
  */
 export declare function useKFormModel(options: {
     formConfigs: Ref<KFormConfigItem[]>;

package/dist/components/k-form/composables/useKFormTemplateRef.d.ts

@@ -8,6 +8,10 @@ import { KFormInstance } from '../types';
  *
  * `T` 约束为 `object`：业务表单 interface 可直接作泛型，无需 `extends Record<string, unknown>`。
  *
+ * @typeParam T - 表单 model 类型
+ * @param key - 模板 `ref` 同名字符串，如 `baseFormRef`
+ * @returns 指向 `KFormInstance<T>` 的 template ref（挂载前请用可选链）
+ *
  * @example
  * ```ts
  * const formRef = useKFormTemplateRef<SupplierBaseForm>('baseFormRef')

package/dist/components/k-form/formComponent/componentRegistry.d.ts

@@ -1,10 +1,17 @@
 import { Component } from 'vue';
 /** formConfigs.component 字段 → Vue 子组件 */
 export declare const FORM_COMPONENT_MAP: Record<string, Component>;
-/** 未命中注册表时返回 Fallback，避免未知 component 静默空白 */
+/**
+ * 未命中注册表时返回 Fallback，避免未知 component 静默空白。
+ *
+ * @param componentType - `formConfigs.component` 字符串名
+ * @returns 注册表中的组件，或 Fallback
+ */
 export declare function resolveFormComponent(componentType: string): Component;
 /**
- * 注册业务扩展表单控件（运行时写入 FORM_COMPONENT_MAP）。
- * 类型侧请在 cms-base 将组件名追加到 CmsFormComponentType。
+ * 注册业务扩展表单控件（运行时写入 {@link FORM_COMPONENT_MAP}）。
+ * 类型侧请在 cms-base 将组件名追加到 `CmsFormComponentType`。
+ *
+ * @param components - `component` 名 → Vue 组件的映射，如 `{ OrgTreeSelect: OrgTreeSelect }`
  */
 export declare function registerFormComponents(components: Record<string, Component>): void;

package/dist/components/k-form/utils/fieldValue.d.ts

@@ -36,61 +36,98 @@ export type TimePickerType = 'time' | 'timerange';
 /**
  * 收窄为选项控件可绑定的 value。
  * ElOption 仅接受 string / number，其余类型转为 string。
+ *
+ * @param value - 原始字段值
+ * @returns `string | number`
  */
 export declare function toOptionValue(value: unknown): OptionFieldValue;
 /**
  * 收窄为标量字段值。
  * null / undefined 返回 undefined；其余非标量类型转为 string。
+ *
+ * @param value - 原始字段值
+ * @returns `string | number | boolean | undefined`
  */
 export declare function toScalarValue(value: unknown): ScalarFieldValue;
 /**
  * 收窄为 Input / Textarea 等文本控件可绑定的 string。
  * null / undefined 返回空字符串。
+ *
+ * @param value - 原始字段值
+ * @returns 文本；空值时为 `''`
  */
 export declare function toStringValue(value: unknown): string;
 /**
  * 收窄为 CheckboxGroup / SelectMultiple 可绑定的数组。
  * 非数组返回 []；仅保留 string / number 元素。
+ *
+ * @param value - 原始字段值
+ * @returns `(string | number)[]`
  */
 export declare function toCheckboxGroupValue(value: unknown): CheckboxGroupValue;
 /**
  * 收窄为 InputNumber 可绑定的 number。
  * 空值、NaN、无法解析的字符串返回 undefined。
+ *
+ * @param value - 原始字段值
+ * @returns 有效数字，或 `undefined`
  */
 export declare function toNumberValue(value: unknown): number | undefined;
 /**
  * 收窄为 ElDatePicker model-value 可接受的值。
  * 范围值要求长度为 2 且元素类型一致（全 Date 或全 string）；其余情况回退为 string。
+ *
+ * @param value - 原始字段值
+ * @returns DatePicker 可绑定值
  */
 export declare function toDatePickerValue(value: unknown): DatePickerFieldValue;
 /**
  * 校验并收窄 ElDatePicker type。
- * 不在白名单内时回退为 'date'。
+ * 不在白名单内时回退为 `'date'`。
+ *
+ * @param type - schema 透传的 type 字符串
+ * @returns 合法的 {@link DatePickerType}
  */
 export declare function toDatePickerType(type?: string): DatePickerType;
 /**
  * 收窄为 ElTimePicker model-value 可接受的值。
  * 范围值要求长度为 2 且元素类型一致（全 Date 或全 string）；其余情况回退为 string。
+ *
+ * @param value - 原始字段值
+ * @returns TimePicker 可绑定值
  */
 export declare function toTimePickerValue(value: unknown): TimePickerFieldValue;
 /**
  * 校验并收窄 ElTimePicker type。
- * 不在白名单内时回退为 'time'。
+ * 不在白名单内时回退为 `'time'`。
+ *
+ * @param type - schema 透传的 type 字符串
+ * @returns `'time' | 'timerange'`
  */
 export declare function toTimePickerType(type?: string): TimePickerType;
 /**
  * 收窄为 ElCascader model-value 可接受的值。
  * 数组仅保留 string / number 路径段；对象原样透传；其余转为 string。
+ *
+ * @param value - 原始字段值
+ * @returns Cascader 可绑定值
  */
 export declare function toCascaderValue(value: unknown): CascaderFieldValue;
 /**
  * 收窄为 TreeSelect options 树数据。
  * 非数组返回空数组。
+ *
+ * @param data - 原始 options
+ * @returns 树节点数组
  */
 export declare function toTreeSelectData(data: unknown): TreeSelectData;
 /**
  * 在 TreeSelect 树数据中按节点 value 查找 label，供只读态展示。
- * 默认字段名 value / label / children，与 ElTreeSelect 及机构树数据一致。
+ * 默认字段名 `value` / `label` / `children`，与 ElTreeSelect 及机构树数据一致。
+ *
+ * @param data - 树 options
+ * @param targetValue - 当前选中值
+ * @returns 匹配节点的 label；未找到时为 `undefined`
  */
 export declare function findTreeSelectLabel(data: TreeSelectData, targetValue: unknown): string | undefined;
 /** Cascader 节点字段映射（对齐 ElCascader props） */
@@ -102,11 +139,21 @@ export type CascaderFieldMap = {
 /**
  * 按 Cascader 路径从 options 解析只读文案（默认用 ` / ` 拼接，对齐 ElCascader separator）。
  * 路径段找不到对应节点时回退为原始值文案。
+ *
+ * @param options - Cascader options 树
+ * @param value - 当前选中值（叶子或路径数组）
+ * @param fieldMap - 节点字段映射，默认 `value` / `label` / `children`
+ * @param separator - 路径拼接符，默认 `' / '`
+ * @returns 只读展示文案
  */
 export declare function findCascaderReadonlyText(options: unknown[] | undefined, value: unknown, fieldMap?: CascaderFieldMap, separator?: string): string;
 /**
  * 只读态展示文案。
- * null / undefined / 空字符串返回 fallback（默认 '--'）。
+ * null / undefined / 空字符串返回 fallback（默认 `'--'`）。
+ *
+ * @param value - 原始字段值
+ * @param fallback - 空值占位，默认 `'--'`
+ * @returns 展示字符串
  */
 export declare function formatReadonlyText(value: unknown, fallback?: string): string;
 export {};

package/dist/components/k-form/utils/formRules.d.ts

@@ -2,6 +2,12 @@ import { FormItemRule } from 'element-plus';
 /**
  * 按组件类型合并默认校验规则。
  * 隐藏项 / 只读项 / 表单 readonly 时不附加规则（由 KForm 侧判断）。
+ *
+ * - `Input` + `type: number|phone|money|percentage` → 追加格式校验
+ * - `InputMixInput` + `required` → 追加两侧均必填校验
+ *
+ * @param item - 含 `component` / `componentProps` / `rules` 的字段配置
+ * @returns 合并后的 `FormItemRule[]`（含业务自定义 `rules`）
  */
 export declare function resolveFormItemRules(item: {
     component: string | import('vue').Component;

package/dist/components/k-form/utils/resolveFormFieldComponent.d.ts

@@ -1,12 +1,25 @@
 import { Component } from 'vue';
 import { KFormBuiltInComponentType, KFormComponentRef } from '../types';
-/** component 是否为内置控件名字符串 */
+/**
+ * `component` 是否为内置控件名字符串。
+ *
+ * @param component - schema 上的 `component` 字段
+ * @returns 是否为 {@link KFormBuiltInComponentType}
+ */
 export declare function isBuiltinFormComponentType(component: KFormComponentRef): component is KFormBuiltInComponentType;
-/** component 是否为业务自定义 Vue 组件（对齐 legacy formConfigs 直接 import 写法） */
+/**
+ * `component` 是否为业务自定义 Vue 组件（对齐 legacy formConfigs 直接 import 写法）。
+ *
+ * @param component - schema 上的 `component` 字段
+ * @returns 是否为 Vue `Component` 对象 / 函数
+ */
 export declare function isCustomFormComponent(component: KFormComponentRef): component is Component;
 /**
  * 解析表单项实际渲染组件。
  * - 字符串 → formComponent 注册表
  * - Component 对象 → 直接使用（legacy 兼容）
+ *
+ * @param component - 内置控件名或自定义组件
+ * @returns 可渲染的 Vue 组件
  */
 export declare function resolveFormFieldComponent(component: KFormComponentRef): Component;

package/dist/components/k-handle-page/useHandlePageInit.d.ts

@@ -6,7 +6,19 @@ export interface UseHandlePageInitOptions {
     immediate?: boolean;
 }
 /**
- * KHandlePage 维护页 init 加载态：包裹 initPage，编辑/详情态展示局部 loading。
+ * KHandlePage 维护页 init 加载态：包裹 `initPage`，编辑/详情态展示局部 loading。
+ *
+ * @param init - 页面初始化异步函数（如拉详情、机构树）
+ * @param options - 加载态与是否 `onMounted` 自动执行，见 {@link UseHandlePageInitOptions}
+ * @returns `pageLoading` 绑到 `KHandlePage`；`runInit` 供弹窗等手动触发
+ *
+ * @example
+ * ```ts
+ * const { pageLoading, runInit } = useHandlePageInit(async () => {
+ *   await loadDetail()
+ * })
+ * // <KHandlePage :loading="pageLoading">...</KHandlePage>
+ * ```
  */
 export declare function useHandlePageInit(init: () => Promise<void>, options?: UseHandlePageInitOptions): {
     pageLoading: import('vue').Ref<boolean, boolean>;

package/dist/components/k-icon/resolveLucideIcon.d.ts

@@ -1,9 +1,28 @@
 import { Component } from 'vue';
-/** kebab-case slug → PascalCase（与 lucide-vue-next 导出一致） */
+/**
+ * kebab-case slug → PascalCase（与 `lucide-vue-next` 导出名一致）。
+ *
+ * @param name - Lucide slug，如 `chevron-down`
+ * @returns PascalCase 导出名，如 `ChevronDown`
+ */
 export declare function toLucidePascalName(name: string): string;
-/** PascalCase → kebab-case（与 lucide.dev slug 一致） */
+/**
+ * PascalCase → kebab-case（与 lucide.dev slug 一致）。
+ *
+ * @param name - PascalCase 导出名，如 `ChevronDown`
+ * @returns kebab-case slug，如 `chevron-down`
+ */
 export declare function pascalToKebab(name: string): string;
-/** 按 Lucide slug 解析图标组件 */
+/**
+ * 按 Lucide slug 解析图标组件；未命中或空名时返回占位组件。
+ *
+ * @param name - Lucide kebab slug；空 / `#` 时走占位
+ * @returns 可渲染的 Vue 组件
+ */
 export declare function resolveLucideIcon(name?: string): Component;
-/** 返回全部 Lucide 图标 kebab 名称（去重、排序，供图标选择器使用） */
+/**
+ * 返回全部 Lucide 图标 kebab 名称（去重、排序，供图标选择器使用）。
+ *
+ * @returns 已排序的 kebab slug 列表（结果有模块级缓存）
+ */
 export declare function getAllLucideKebabNames(): string[];

package/dist/components/k-table/composables/useColumnDisplay.d.ts

@@ -22,6 +22,10 @@ export interface UseColumnDisplayOptions<T = Record<string, unknown>> {
  * - `tableKey` 为空时使用随机 key，仅内存态、不写入 localStorage
  * - `required` / selection / index / radio 列始终显示且不可在面板取消
  * - 显隐变更后通过 `onLayout` 调用 ElTable.doLayout 刷新布局
+ *
+ * @typeParam T - 表格行数据类型
+ * @param options - 见 {@link UseColumnDisplayOptions}
+ * @returns `visibleColumns` / `selectorItems` 与显隐写入、重置方法
  */
 export declare function useColumnDisplay<T = Record<string, unknown>>(options: UseColumnDisplayOptions<T>): {
     columnDisplay: import('vue').Ref<Record<string, boolean>, Record<string, boolean>>;

package/dist/components/k-table/composables/useKTable.d.ts

@@ -72,18 +72,43 @@ export interface KTableEmits<T> {
     /** 透传 ElTable `sort-change`（列头排序变化） */
     (event: 'sort-change', data: KTableSortChangeData): void;
 }
+/**
+ * {@link useKTable} 入参（由 `KTable.vue` 传入，页面侧通常不直接调用）。
+ *
+ * @typeParam T - 表格行数据类型
+ */
 interface UseKTableOptions<T> {
     /** SFC 经 withDefaults 合并后的 props */
     props: ResolvedKTableProps<T>;
     emit: KTableEmits<T>;
     attrs: Record<string, unknown>;
     slots: Slots;
-    /** 由 SFC 顶层声明，供模板 :ref 绑定 */
+    /** 由 SFC 顶层声明，供模板 `:ref` 绑定 */
     tableRef: Ref<TableInstance | undefined>;
     queryRef: Ref<KPanelQueryInstance | undefined>;
 }
 /**
- * KTable 编排层：聚合分页 / 查询 / 数据请求 / 列显隐等子 composable。
+ * KTable 编排层：聚合分页 / 查询 / 数据请求 / 列显隐 / 单选 / 树懒加载 / 行拖拽。
+ *
+ * 向 SFC 返回模板绑定态与 `defineExpose` 实例方法；不直接操作 DOM。
+ * 页面侧请通过 {@link useKTableTemplateRef} 拿到 {@link KTableInstance}，勿直接调用本函数。
+ *
+ * @typeParam T - 表格行数据类型
+ * @param options - 见 {@link UseKTableOptions}
+ * @returns 模板绑定（`tableProps` / `renderColumns` / handlers）与 expose 方法（`refresh` / `getSelection` 等）
+ *
+ * @example
+ * ```ts
+ * // KTable.vue 内部
+ * const tableRef = ref<TableInstance>()
+ * const queryRef = ref<KPanelQueryInstance>()
+ * const api = useKTable({ props, emit, attrs, slots, tableRef, queryRef })
+ * defineExpose({
+ *   refresh: api.refresh,
+ *   getSelection: api.getSelection,
+ *   // ...
+ * })
+ * ```
  */
 export declare function useKTable<T>(options: UseKTableOptions<T>): {
     showQuery: import('vue').ComputedRef<boolean>;

package/dist/components/k-table/composables/useKTableCrossPageSelection.d.ts

@@ -28,4 +28,30 @@ export type UseKTableCrossPageSelectionReturn<T> = {
     onSelectionChange: (rows: T[]) => void;
     onRadioChange: (row: T) => void;
 };
+/**
+ * KTable 弹窗/列表跨页多选回显。
+ *
+ * 消费侧典型用法：打开弹框时 `setSelection(已选)`，表格绑
+ * `@data-loaded="onDataLoaded"` + `@selection-change="onSelectionChange"`。
+ * 不把草稿选择写进 KTable 内部，避免污染表格数据层。
+ *
+ * @typeParam T - 表格行数据类型
+ * @param options - 行主键、表格实例与勾选模式，见 {@link UseKTableCrossPageSelectionOptions}
+ * @returns 草稿 `selection` 与事件处理器，见 {@link UseKTableCrossPageSelectionReturn}
+ *
+ * @example
+ * ```ts
+ * const { selection, tableRef, setSelection, onDataLoaded, onSelectionChange } =
+ *   useKTableCrossPageSelection<UserRow>({ rowKey: 'user_id' })
+ *
+ * // 打开弹窗时回填已选
+ * setSelection([...pickedUsers])
+ *
+ * // <KTable
+ * //   ref="tableRef"
+ * //   @data-loaded="onDataLoaded"
+ * //   @selection-change="onSelectionChange"
+ * // />
+ * ```
+ */
 export declare function useKTableCrossPageSelection<T = Record<string, unknown>>(options: UseKTableCrossPageSelectionOptions<T>): UseKTableCrossPageSelectionReturn<T>;

package/dist/components/k-table/composables/useKTableTemplateRef.d.ts

@@ -5,5 +5,15 @@ import { KTableInstance } from './useKTable';
  *
  * `useTemplateRef` 挂载前 value 为 null，但页面 composable 侧通常按已挂载实例使用；
  * 类型上省略 null，调用处请继续用 `tableRef.value?.refresh()` 等可选链。
+ *
+ * @typeParam T - 表格行数据类型
+ * @param key - 模板 `ref` 同名字符串，如 `tableRef`
+ * @returns 指向 `KTableInstance<T>` 的 template ref（挂载前请用可选链）
+ *
+ * @example
+ * ```ts
+ * const tableRef = useKTableTemplateRef<UserRow>('tableRef')
+ * await tableRef.value?.refresh()
+ * ```
  */
 export declare function useKTableTemplateRef<T = Record<string, unknown>>(key: string): Ref<KTableInstance<T>>;

package/dist/components/k-table/composables/useTableColumns.d.ts

@@ -3,15 +3,27 @@ import { KTableColumn } from '../types';
  * 归一化列配置：
  * - `selectionShow` 为 true 且无 selection 列时，自动前置多选列
  * - `prop: 'operates'` 且无 type 时，自动补 `type: 'operates'`（兼容旧 tableConfig）
+ *
+ * @typeParam T - 表格行数据类型
+ * @param columns - 原始列配置
+ * @param selectionShow - 是否自动插入多选列，默认 `false`
+ * @returns 归一化后的新列数组（有变更时为新引用）
  */
 export declare function normalizeColumns<T>(columns: KTableColumn<T>[], selectionShow?: boolean): KTableColumn<T>[];
 /**
- * 将 KTableColumn 转为 ElTableColumn 可绑定的 props，并填充旧版默认样式约定。
+ * 将 `KTableColumn` 转为 ElTableColumn 可绑定的 props，并填充旧版默认样式约定。
+ *
+ * @typeParam T - 表格行数据类型
+ * @param column - 单列配置
+ * @returns 可 `v-bind` 到 `ElTableColumn` 的 props 对象
  */
 export declare function convertColumnBind<T>(column: KTableColumn<T>): Record<string, unknown>;
 /**
  * 列单元格展示值 hook。
- * 通过 inject(DICT_KEY) 获取字典服务，保持 design 与 cms-base 解耦。
+ * 通过 `inject(DICT_KEY)` 获取字典服务，保持 design 与 cms-base 解耦。
+ *
+ * @param nullValueFormat - 空值占位文案，默认 `'--'`
+ * @returns `getCellDisplayValue(column, row, index)` 计算展示文本
  */
 export declare function useCellValue(nullValueFormat?: string): {
     getCellDisplayValue: <T>(column: KTableColumn<T>, row: T, index: number) => string;

package/dist/components/k-table/composables/useTableData.d.ts

@@ -1,24 +1,47 @@
 import { MaybeRefOrGetter, Ref } from 'vue';
 import { KTableResponseConfig } from '../types';
 import { useTablePagination } from './useTablePagination';
-/** 列表请求函数；直接传 CMS 接口即可，响应体由 responseConfig 解析 */
+/** 列表请求函数；直接传 CMS 接口即可，响应体由 `responseConfig` 解析 */
 export type TableAction = (params: Record<string, unknown>) => Promise<unknown>;
+/**
+ * {@link useTableData} 入参。
+ *
+ * @typeParam T - 表格行数据类型
+ */
 export interface UseTableDataOptions<T> {
-    /** 列表查询接口；传入后进入 action 模式，由组件内部管理 tableData */
+    /** 列表查询接口；传入后进入 action 模式，由组件内部管理 `tableData` */
     action?: TableAction;
     /** 请求外置固定参数，与分页、查询条件合并后发出；可传具体对象，无需 extends Record */
     params?: MaybeRefOrGetter<Record<string, any> | undefined>;
     /** 接口响应字段映射 */
     responseConfig?: MaybeRefOrGetter<KTableResponseConfig | undefined>;
-    /** 与 useTablePagination 共享的分页状态 */
+    /** 与 {@link useTablePagination} 共享的分页状态 */
     pagination: ReturnType<typeof useTablePagination>;
-    /** 查询条件，与 params 合并后作为请求参数 */
+    /** 查询条件，与 `params` 合并后作为请求参数 */
     queryParams?: MaybeRefOrGetter<Record<string, unknown> | undefined>;
-    /** 数据加载完成回调，用于 emit data-loaded */
+    /** 数据加载完成回调，用于 emit `data-loaded` */
     onDataLoaded?: (data: T[], total: number) => void;
     /** action 首屏会自动请求时，首帧直接展示加载态，避免闪现空状态 */
     initialLoading?: boolean;
 }
+/**
+ * action 模式下管理表格数据：请求、解析响应、写入分页 total。
+ *
+ * @typeParam T - 表格行数据类型
+ * @param options - 见 {@link UseTableDataOptions}
+ * @returns `tableData` / `loading` / `loaded`；`fetchData` 发起请求；`refresh` 可重置页码后重拉
+ *
+ * @example
+ * ```ts
+ * const pagination = useTablePagination({ hasAction: ref(true) })
+ * const { tableData, loading, fetchData, refresh } = useTableData<UserRow>({
+ *   action: fetchUsers,
+ *   queryParams,
+ *   pagination,
+ *   onDataLoaded: (rows, total) => emit('data-loaded', rows, total)
+ * })
+ * ```
+ */
 export declare function useTableData<T>(options: UseTableDataOptions<T>): {
     tableData: Ref<T[], T[]>;
     loading: Ref<boolean, boolean>;

package/dist/components/k-table/composables/useTablePagination.d.ts

@@ -13,6 +13,9 @@ export interface UseTablePaginationOptions {
  * 管理表格分页状态，产出 KPagination 可绑定的 props。
  *
  * action 模式下 `total` 由接口回填；非 action 模式下同步外部分页字段。
+ *
+ * @param options - 外部分页配置与是否 action 模式，见 {@link UseTablePaginationOptions}
+ * @returns `state` / `bindProps` / `indexOffset` 与页码写入方法
  */
 export declare function useTablePagination(options: UseTablePaginationOptions): {
     state: Ref<{

package/dist/components/k-table/composables/useTableRadio.d.ts

@@ -5,6 +5,15 @@ export interface UseTableRadioOptions<T> {
     /** 行唯一键字段名，与 KTable rowKey 对齐 */
     rowKey: MaybeRefOrGetter<string>;
 }
+/**
+ * 单选列（`type: 'radio'`）选中态。
+ *
+ * 存在 radio 列时 {@link useKTable} 默认开启 `highlight-current-row`（可通过 attrs 关闭）。
+ *
+ * @typeParam T - 表格行数据类型
+ * @param options - 列配置与 `rowKey`，见 {@link UseTableRadioOptions}
+ * @returns `radioSelected` / `hasRadioColumn` 与选中写入方法
+ */
 export declare function useTableRadio<T>(options: UseTableRadioOptions<T>): {
     radioSelected: import('vue').Ref<string | number | boolean, string | number | boolean>;
     hasRadioColumn: import('vue').ComputedRef<boolean>;