@cloudtower/eagle 490.0.5 → 490.0.6

package/dist/src/core/TableForm/types.d.ts

@@ -1,86 +1,122 @@
 /// <reference types="react" />
 import { ColumnBodyImpls } from "../../core/TableForm/Columns";
 import { ButtonProps } from "../Button";
+/** 单元格错误信息，key 为列标识 */
 export type ErrorInfo = Record<string, {
     errorMessage: string;
     isError: boolean;
 }>;
+/**
+ * 表单校验触发模式
+ */
 export declare enum ValidateTriggerType {
+    /** 标准模式：首次 blur 后触发校验，之后每次 change 也触发 */
     Normal = 0,
+    /** 激进模式：每次 change 都触发校验 */
     Aggressive = 1,
+    /** 惰性模式：仅 blur 时触发校验 */
     Lazy = 2
 }
+/**
+ * 自定义列渲染函数的参数
+ */
 export type CustomizedColumnRenderProps = {
+    /** 当前单元格的值 */
     value?: any;
+    /** 当前行索引（header 行时为 undefined） */
     rowIndex?: number;
+    /** 值变更回调 */
     onChange: (value: any) => void;
+    /** 是否禁用 */
     disabled?: boolean;
+    /** 失焦回调 */
     onBlur?: () => void;
+    /** 占位文本 */
     placeholder?: string;
+    /** 是否为表头行（批量填充行） */
     isHeader: boolean;
+    /** 是否处于错误状态 */
     error?: boolean;
+    /** 当前行的完整数据 */
     formValue: any;
 };
+/**
+ * TableForm 列配置。
+ * 每列可选择内置类型（text/input/password/checkbox/affix）或通过 render 自定义渲染。
+ */
 export type TableFormColumn = {
     /**
-     * 列类型，指定后会使用 ColumnBodyImpls 枚举渲染单元格，否则使用 render 函数渲染
-     * @enum {number}
+     * 列类型，使用内置列组件渲染单元格
+     * - "text": 只读文本展示
+     * - "input": 文本输入框
+     * - "password": 密码输入框（可切换显示/隐藏）
+     * - "checkbox": 复选框
+     * - "affix": 带前缀/后缀的输入框
+     *
+     * 不指定 type 时需提供 render 函数自定义渲染。
      */
     type?: keyof typeof ColumnBodyImpls;
-    /**
-     * 列标题
-     */
+    /** 列标题，显示在表头 */
     title?: string | React.ReactNode;
-    /**
-     * 列唯一标识
-     */
+    /** 列唯一标识，同时作为行数据对象的 key */
     key: string;
     /**
-     * 列副标题，只在 `disableBatchFilling` 为 `false`，且 `type` 为 'text' 时生效
+     * 列副标题。仅当 disableBatchFilling 为 false 且 type 为 "text" 时显示。
+     * 若需要在任何情况下显示副标题，请使用 subTitleRender。
      */
     subTitle?: string;
     /**
      * 列副标题颜色
+     * - "": 默认颜色
+     * - "primary": 主色
+     * - "success": 成功色
+     * - "warning": 警告色
+     * - "danger": 危险色
      */
     subTitleColor?: "" | "primary" | "success" | "warning" | "danger";
     /**
-     * 列副标题渲染函数，优先级高于 `subTitle`，即使 `disableBatchFilling` 为 `true` 也会生效
+     * 列副标题自定义渲染函数。优先级高于 subTitle，即使 disableBatchFilling 为 true 也会生效。
      */
     subTitleRender?: (props: CustomizedColumnRenderProps) => React.ReactNode;
-    /**
-     * 列单元格图标
-     */
+    /** 列单元格图标 */
     bodyIcon?: any;
-    /**
-     * 列单元格错误图标
-     */
+    /** 列单元格错误状态图标 */
     bodyErrorIcon?: any;
-    /**
-     * 列宽度
-     */
+    /** 列宽度 */
     width?: number | string;
+    /** 覆盖单元格显示文本（仅 text 类型） */
     displayText?: string;
+    /** 单元格默认值，新增行时使用 */
     defaultValue?: any;
+    /** 是否隐藏该列 */
     hidden?: boolean;
+    /** 输入框占位文本 */
     placeholder?: string;
+    /**
+     * 批量填充时是否自动递增末尾数字。
+     * 例如输入 "host0"，各行会自动填充为 "host0"、"host1"、"host2"...
+     */
     autoIncrease?: boolean;
+    /** 禁用 affix 类型的前缀输入（仅 type="affix" 时生效） */
     disablePrefix?: boolean;
+    /** 禁用 affix 类型的后缀输入（仅 type="affix" 时生效） */
     disableSuffix?: boolean;
+    /** 自定义数据，透传给列渲染组件 */
     customData?: any;
     /**
      * 列对齐方式
+     * @default "left"
      */
     align?: "left" | "right" | "center";
-    /**
-     * 列行描述渲染函数
-     */
+    /** 列行描述渲染函数，在单元格下方渲染额外说明 */
     renderDescription?: (props: RenderRowDescriptionProps) => React.ReactNode;
     /**
-     * 列单元格渲染函数
+     * 自定义单元格渲染函数。不指定 type 时必须提供此函数。
+     * 即使指定了 type，render 也会覆盖内置渲染。
      */
     render?: (props: CustomizedColumnRenderProps) => React.ReactNode;
     /**
-     * 列验证函数
+     * 列级别校验函数。返回错误信息字符串表示校验失败，返回 undefined 表示通过。
      */
     validator?: (params: {
         value: any;
@@ -99,6 +135,7 @@ export interface ColumnHeaderCellProps {
     onBlur?: (key: string, error?: string) => void;
     onVisibleChange?: (visible: boolean) => void;
 }
+/** 行数据类型，key 为列标识，value 为单元格值 */
 export type DataType = {
     [columnKey: string]: any;
 };
@@ -120,20 +157,36 @@ export interface ColumnBodyCellProps {
     error?: string | null;
     onValidate?: (id: string, isValid: boolean) => void;
 }
+/** 添加行按钮的 Props */
 export type AddRowButtonProps = {
+    /** 行添加配置 */
     config: RowAddConfigurations;
+    /** 自定义样式 */
     style?: React.CSSProperties;
+    /** 列配置，用于生成空行默认值 */
     columns: TableFormColumn[];
+    /** 添加行回调 */
     addData: (data: DataType[]) => void;
+    /** 当前表格数据 */
     data: DataType[];
 };
+/**
+ * 行添加配置
+ */
 export type RowAddConfigurations = {
+    /** 是否允许添加行 */
     addible: boolean;
+    /** 添加按钮文案，支持字符串或返回 ReactNode 的函数 */
     text?: (() => React.ReactNode) | string;
+    /** 添加按钮的额外属性 */
     buttonProps?: ButtonProps;
+    /** 最大行数限制，达到上限后添加按钮禁用 */
     maximum?: number;
+    /** 添加按钮区域的自定义类名 */
     className?: string;
+    /** 添加按钮右侧的额外操作区域 */
     extraAction?: React.ReactNode;
+    /** 完全自定义添加按钮组件 */
     CustomizedButton?: (props: AddRowButtonProps) => React.ReactElement;
 };
 export interface TableFormRowsProps extends Pick<TableFormProps, "columns" | "disabled" | "deleteConfig" | "disableBatchFilling" | "validateTriggerType" | "renderRowDescription" | "rowValidator" | "onBodyBlur" | "row" | "errors"> {
@@ -146,123 +199,218 @@ export interface TableFormRowsProps extends Pick<TableFormProps, "columns" | "di
     rowSplitType?: TableFormRowSplitType;
     onValidate?: (id: string, isValid: boolean) => void;
 }
+/** 行描述渲染函数的参数 */
 export type RenderRowDescriptionProps = {
+    /** 当前行索引 */
     rowIndex: number;
+    /** 当前行数据 */
     rowData: DataType;
+    /** 表头批量填充的最新值 */
     latestData?: DataType[];
 };
+/**
+ * @deprecated 请使用 TableFormRowConfiguration 的 deletable + disableActions 替代
+ */
 export type DeletableConfigurations = {
     deletable: boolean;
     specifyRowDeleteDisabled?: (rowIndex: number, allData: DataType[]) => boolean;
 };
+/** 行操作类型 */
 export type TableFormRowActions = "delete";
+/** 行分隔样式类型 */
 export type TableFormRowSplitType = "border" | "zebraMarking";
+/**
+ * 表格行配置。统一管理行级别的交互行为，替代已废弃的 draggable/deleteConfig/rowSplitType/renderRowDescription/rowValidator。
+ */
 export type TableFormRowConfiguration = {
+    /**
+     * 行分隔样式
+     * - "border": 边框分隔（默认）
+     * - "zebraMarking": 斑马纹分隔
+     */
     splitType?: TableFormRowSplitType;
+    /** 是否允许拖拽排序 */
     draggable?: boolean;
+    /**
+     * 是否允许删除行。传 boolean 控制全部行，传函数可按行索引动态控制。
+     */
     deletable?: boolean | ((rowIndex: number, allData: DataType[]) => boolean);
+    /** 行描述文本数组，按索引对应每一行 */
     descriptions?: (string | React.ReactNode)[];
+    /**
+     * 禁用指定行操作。传数组禁用所有行的指定操作，传函数可按行索引动态控制。
+     */
     disableActions?: TableFormRowActions[] | ((rowIndex: number, allData: DataType[]) => TableFormRowActions[] | undefined);
+    /** 行级别校验函数。返回错误信息字符串表示校验失败，返回 undefined 表示通过。 */
     validator?: (rowIndex: number, rowData: DataType) => string | undefined;
+    /** 自定义行描述渲染函数，按行返回描述内容 */
     customizedDescription?: (props: RenderRowDescriptionProps) => React.ReactNode | string;
 };
+/**
+ * 表格错误信息数组，按行索引对应。
+ * 每项可以是：
+ * - string: 行级别错误信息
+ * - { [columnKey]: string | null }: 单元格级别错误信息
+ * - null: 该行无错误
+ */
 export type TableFormErrorsType = (string | {
     [columnKey: string]: string | null;
 } | null)[];
+/**
+ * TableForm 是行内编辑的表格表单组件，适用于批量数据录入场景。
+ * 支持多种列类型（文本/输入/密码/复选框/前后缀/自定义）、表头批量填充、
+ * 行的增删和拖拽排序、三种校验模式、以及外部错误信息注入。
+ *
+ * @example
+ * ```tsx
+ * import React, { useRef } from "react";
+ * import { TableForm } from "@cloudtower/eagle";
+ * import type { TableFormColumn, TableFormHandle } from "@cloudtower/eagle";
+ *
+ * const columns: TableFormColumn[] = [
+ *   { key: "name", title: "主机名", type: "input", autoIncrease: true },
+ *   { key: "ip", title: "管理 IP", type: "input",
+ *     validator: ({ value }) => !value ? "IP 不能为空" : undefined },
+ *   { key: "password", title: "密码", type: "password" },
+ * ];
+ *
+ * const App = () => {
+ *   const ref = useRef<TableFormHandle>(null);
+ *   return (
+ *     <TableForm
+ *       ref={ref}
+ *       columns={columns}
+ *       defaultData={[{ name: "host0", ip: "", password: "" }]}
+ *       rowAddConfig={{ addible: true, maximum: 10 }}
+ *       row={{ deletable: true, draggable: true }}
+ *       onBodyChange={(data) => console.log("数据变更:", data)}
+ *     />
+ *   );
+ * };
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 自定义列渲染
+ * import React from "react";
+ * import { TableForm, Select } from "@cloudtower/eagle";
+ * import type { TableFormColumn } from "@cloudtower/eagle";
+ *
+ * const columns: TableFormColumn[] = [
+ *   { key: "name", title: "名称", type: "input" },
+ *   {
+ *     key: "role",
+ *     title: "角色",
+ *     defaultValue: "worker",
+ *     render({ isHeader, value, onChange, placeholder, ...rest }) {
+ *       return (
+ *         <Select
+ *           size="small"
+ *           value={value}
+ *           onChange={onChange}
+ *           placeholder={isHeader ? "批量选择" : "请选择"}
+ *           options={[
+ *             { label: "Master", value: "master" },
+ *             { label: "Worker", value: "worker" },
+ *           ]}
+ *         />
+ *       );
+ *     },
+ *   },
+ * ];
+ * ```
+ *
+ * @see Form 标准表单容器，适用于非表格化的表单场景
+ * @see SortableList 可拖拽排序列表，适用于纯排序（无编辑）场景
+ */
 export type TableFormProps = {
-    /**
-     * 表格默认数据
-     */
+    /** 表格初始数据，每项为一行数据对象，key 对应列的 key */
     defaultData?: DataType[];
-    /**
-     * 表格列配置
-     */
+    /** 表格列配置数组 */
     columns: TableFormColumn[];
     /**
-     * 表格是否禁用单元格默认控件
+     * 是否禁用所有单元格的默认控件（输入框、复选框等）
+     * @default false
      */
     disabled?: boolean;
-    /**
-     * 表格行添加配置
-     */
+    /** 行添加配置，包含添加按钮文案、最大行数等 */
     rowAddConfig?: RowAddConfigurations;
     /**
-     * @deprecated use "row" configuration instead
+     * @deprecated 请使用 row 配置的 deletable + disableActions 替代
      */
     deleteConfig?: DeletableConfigurations;
     /**
      * 表格大小
+     * @default "default"
      */
     size?: "default" | "large" | "small";
     /**
-     * @deprecated use "row" configuration instead
+     * @deprecated 请使用 row.draggable 替代
      */
     draggable?: boolean;
     /**
-     * 表格是否禁用批量填充
+     * 是否禁用表头批量填充功能。禁用后表头只显示标题，不显示输入控件。
+     * @default false
      */
     disableBatchFilling?: boolean;
-    /**
-     * 表格类名
-     */
+    /** 自定义类名 */
     className?: string;
     /**
-     * @deprecated use "row" configuration instead
+     * @deprecated 请使用 row.splitType 替代
      */
     rowSplitType?: TableFormRowSplitType;
     /**
-     * 表格验证触发类型，使用 ValidateTriggerType 枚举
-     * @enum {number}
+     * 校验触发模式
+     * - Normal: 首次 blur 后触发，之后每次 change 也触发
+     * - Aggressive: 每次 change 都触发
+     * - Lazy: 仅 blur 时触发
+     * @default ValidateTriggerType.Normal
      */
     validateTriggerType?: ValidateTriggerType;
-    /**
-     * 表格最大高度
-     */
+    /** 表格最大高度，超出后出现滚动条 */
     maxHeight?: number | string;
-    /**
-     * 表格行配置
-     */
+    /** 表格行配置，统一管理拖拽、删除、分隔样式、行描述、行校验等 */
     row?: TableFormRowConfiguration;
     /**
-     * 表格行错误信息
+     * 外部注入的错误信息数组，按行索引对应。
+     * 支持行级别（字符串）和单元格级别（对象）两种格式。
      */
     errors?: TableFormErrorsType;
     /**
-     * @deprecated use "row" configuration instead
+     * @deprecated 请使用 row.customizedDescription 替代
      */
     renderRowDescription?: (props: RenderRowDescriptionProps) => React.ReactNode;
     /**
-     * @deprecated use "row" configuration instead
+     * @deprecated 请使用 row.validator 替代
      */
     rowValidator?: (rowIndex: number, rowData: DataType) => string | undefined;
-    /**
-     * 表格头部数据变化的回调
-     */
+    /** 表头批量填充值变更回调 */
     onHeaderChange?: (data: any[], columnKey: string) => void;
-    /**
-     * 表格头部数据失去焦点时的回调
-     */
+    /** 表头批量填充输入框失焦回调 */
     onHeaderBlur?: (data: any[], columnKey: string) => void;
-    /**
-     * 表格行数据变化的回调
-     */
+    /** 行数据变更回调。data 为完整表格数据，rowIndex 和 columnKey 标识变更位置。 */
     onBodyChange?: (value: DataType[], rowIndex?: number, columnKey?: string) => void;
-    /**
-     * 表格行数据添加的回调
-     */
+    /** 新增行回调。value 为新增后的完整数据，rowIndex 为新行索引。 */
     onBodyAdd?: (value: DataType[], rowIndex: number) => void;
-    /**
-     * 表格行数据失去焦点时的回调
-     */
+    /** 行数据失焦回调 */
     onBodyBlur?: (value: DataType, rowIndex?: number, columnKey?: string) => void;
     /**
-     * 是否隐藏空表格
+     * 是否在无数据时隐藏表格（仅显示添加按钮）
+     * @default false
      */
     hideEmptyTable?: boolean;
 };
+/**
+ * TableForm 的 ref handle，通过 useRef<TableFormHandle> 获取。
+ * 提供命令式操作表格数据和校验的方法。
+ */
 export type TableFormHandle = {
+    /** 设置表格数据并触发 onBodyChange 回调 */
     setData: (data: DataType[]) => void;
+    /** 设置表格数据但不触发 onBodyChange 回调（静默更新） */
     setDataWithoutTriggerChange: (data: DataType[]) => void;
+    /** 触发全表校验（所有行、所有列） */
     validateWholeFields: () => void;
+    /** 返回当前表格是否全部校验通过 */
     isValid: () => boolean;
 };

package/dist/src/core/WizardDialog/type.d.ts

@@ -1,31 +1,165 @@
 /// <reference types="react" />
 import { ImmersiveDialogProps } from "../../core/ImmersiveDialog/type";
+/**
+ * 基于 ImmersiveDialog 的多步骤向导对话框。
+ *
+ * @description
+ * 自动管理步骤导航、步骤指示器和按钮文案切换。
+ * 非最后一步时，确定按钮显示"下一步"并触发 `onNextStep`；
+ * 最后一步时显示"确定"并触发 `onOk`。左侧面板默认渲染垂直步骤条。
+ * 通过 `usePushModal` 打开。
+ *
+ * @example
+ * ```tsx
+ * // 基础三步向导——创建集群
+ * import { WizardDialog } from "@cloudtower/eagle";
+ * import { usePushModal } from "@cloudtower/eagle/KitStoreProvider";
+ *
+ * const pushModal = usePushModal();
+ *
+ * pushModal({
+ *   component: () => (
+ *     <WizardDialog
+ *       title="创建集群"
+ *       steps={[
+ *         { title: "基本信息", children: <ClusterBasicForm /> },
+ *         { title: "网络配置", children: <ClusterNetworkForm /> },
+ *         { title: "确认创建", children: <ClusterConfirmPanel /> },
+ *       ]}
+ *       onOk={(e) => handleCreate()}
+ *     />
+ *   ),
+ *   props: { name: "CreateClusterWizard" },
+ * });
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 带步骤校验的向导——onNextStep 返回 false 阻止导航
+ * <WizardDialog
+ *   title="创建虚拟机"
+ *   steps={steps}
+ *   onNextStep={(nextStep) => {
+ *     if (!validateCurrentStep()) {
+ *       message.error("请完善当前步骤的必填项");
+ *       return false; // 阻止跳转到下一步
+ *     }
+ *   }}
+ *   onOk={(e) => handleSubmit()}
+ * />
+ * ```
+ *
+ * 注意以下继承属性在 WizardDialog 中有特殊行为：
+ * - `footerLeftAction`：WizardDialog 内部使用此属性渲染"上一步"按钮，外部传入会被覆盖。
+ * - `isContentFull`：WizardDialog 内部强制设为 `false`，外部传入无效。
+ *
+ * @see ImmersiveDialog 基础全屏对话框组件
+ * @see Steps 步骤条组件
+ */
 export type WizardDialogProps = ImmersiveDialogProps & {
-    /** 当前步骤 */
+    /**
+     * 当前步骤索引（从 0 开始）。
+     *
+     * @description
+     * 传入此属性时进入受控模式，步骤切换完全由外部状态驱动；
+     * 不传时为非受控模式，组件内部自动管理当前步骤。
+     *
+     * @default 0
+     */
     step?: number;
-    /** 步骤配置数组 */
+    /**
+     * 步骤配置数组，每项定义一个向导步骤。
+     *
+     * @description
+     * 每个步骤包含 `title`（显示在左侧步骤条中的标题）和
+     * `children`（该步骤的主体内容，通常为表单或信息面板）。
+     * 步骤数量决定导航行为：非最后一步点击确定按钮触发 `onNextStep`，
+     * 最后一步触发 `onOk`。
+     */
     steps?: {
-        /** 步骤标题 */
+        /** 步骤标题，显示在左侧垂直步骤条中 */
         title: string;
-        /** 步骤内容渲染 */
+        /** 步骤内容，通常为表单或信息展示面板 */
         children: React.ReactNode;
     }[];
-    /** 是否隐藏步骤 */
+    /**
+     * 是否隐藏左侧步骤指示器。
+     *
+     * @description
+     * 设为 `true` 时不渲染默认的垂直步骤条。
+     * 可配合 `left` 属性放置自定义的步骤指示器或其他导航内容。
+     *
+     * @default false
+     */
     hideSteps?: boolean;
-    /** 左侧自定义内容 */
+    /**
+     * 左侧面板自定义内容。
+     *
+     * @description
+     * 传入后将替换默认的步骤指示器。常用于自定义步骤导航样式。
+     */
     left?: React.ReactNode;
-    /** 右侧自定义内容 */
+    /**
+     * 右侧面板自定义内容。
+     *
+     * @description
+     * 渲染在主内容区域右侧的额外面板。
+     */
     right?: React.ReactNode;
-    /** 是否销毁其他步骤内容 */
+    /**
+     * 是否销毁非当前步骤的内容。
+     *
+     * @description
+     * - `true`：仅渲染当前步骤，切换时销毁前一步骤的 DOM，节省内存。
+     * - `false`：所有步骤始终保留在 DOM 中，通过 `display: none` 隐藏非当前步骤。
+     *   适用于需要保留表单状态的场景（如用户在步骤间来回切换时不丢失已填写的数据）。
+     *
+     * @default false
+     */
     destroyOtherStep?: boolean;
-    /** 上一步的文本 */
+    /**
+     * "上一步"按钮的自定义文本。
+     *
+     * @default t("common.prev_step")（i18n：上一步 / Previous）
+     */
     prevText?: string;
-    /** 上一步的回调 */
+    /**
+     * 点击"上一步"按钮时的回调。
+     *
+     * @param step - 即将跳转到的步骤索引（当前步骤 - 1）
+     */
     onPrevStep?: (step: number) => void;
-    /** 下一步的文本 */
+    /**
+     * "下一步"按钮的自定义文本。
+     *
+     * @description
+     * 仅在非最后一步时显示，替换确定按钮的默认"下一步"文案。
+     *
+     * @default t("common.next_step")（i18n：下一步 / Next）
+     */
     nextText?: string;
-    /** 下一步的回调 */
+    /**
+     * 点击"下一步"时的回调，支持阻止导航。
+     *
+     * @description
+     * 在非最后一步点击确定按钮时触发。这是实现步骤校验的核心机制：
+     * - 返回 `false` 将**阻止**导航到下一步（可用于表单校验失败时阻止前进）。
+     * - 返回 `void`（不返回值）或返回非 `false` 值时正常跳转到下一步。
+     *
+     * 注意：仅严格等于 `false`（`=== false`）时才阻止，返回 `undefined` 或其他假值不会阻止。
+     *
+     * @param step - 即将跳转到的步骤索引（当前步骤 + 1）
+     * @returns 返回 `false` 阻止导航，返回 `void` 允许导航
+     */
     onNextStep?: (step: number) => void | boolean;
-    /** 步骤改变时的回调 */
+    /**
+     * 步骤发生变化时的回调。
+     *
+     * @description
+     * 无论是通过"上一步"、"下一步"按钮，还是点击左侧步骤条直接跳转，
+     * 步骤变化后都会触发此回调。适合用于同步外部状态或埋点。
+     *
+     * @param step - 变化后的新步骤索引
+     */
     onStepChange?: (step: number) => void;
 };

package/dist/src/core/index.d.ts

@@ -162,7 +162,6 @@ export { default as Overflow } from "./Overflow";
 export { default as Pagination } from "./Pagination";
 export { default as Percent } from "./Percent";
 export { default as Radio } from "./Radio";
-export { default as SearchInput } from "./SearchInput";
 export { default as Second } from "./Second";
 export { default as SegmentControl } from "./SegmentControl";
 export { default as Select } from "./Select";