@cloudtower/eagle 490.0.6 → 490.0.8

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

@@ -1,78 +1,149 @@
 /// <reference types="react" />
 import { InputProps } from "antd/lib/input";
 import { SrcType } from "../BaseIcon";
+/**
+ * @description 搜索输入框组件，基于 Input 封装，提供防抖搜索、结果导航（上一个/下一个）和最近搜索历史功能。
+ * 支持受控和非受控两种模式，适用于表格内搜索、页面全局搜索等场景。
+ *
+ * @example
+ * 基础搜索（带防抖）：
+ * ```tsx
+ * import React, { useState } from "react";
+ * import { SearchInput } from "@cloudtower/eagle";
+ *
+ * const App = () => {
+ *   const [keyword, setKeyword] = useState("");
+ *   return (
+ *     <SearchInput
+ *       debounceWait={300}
+ *       onChange={(value) => setKeyword(value)}
+ *     />
+ *   );
+ * };
+ * ```
+ *
+ * @example
+ * 带结果导航（显示匹配数和上下翻页）：
+ * ```tsx
+ * import React from "react";
+ * import { SearchInput } from "@cloudtower/eagle";
+ *
+ * const App = () => (
+ *   <SearchInput
+ *     total={10}
+ *     onChange={(value) => console.log("搜索:", value)}
+ *     onSearchNext={(value, current) => console.log("下一个:", current)}
+ *     onSearchPrev={(value, current) => console.log("上一个:", current)}
+ *   />
+ * );
+ * ```
+ *
+ * @example
+ * 启用最近搜索历史：
+ * ```tsx
+ * import React from "react";
+ * import { SearchInput } from "@cloudtower/eagle";
+ *
+ * const App = () => (
+ *   <SearchInput
+ *     enableRecentSearch
+ *     recentSearchLocalStorageKey="vm-search"
+ *     maxRecentCount={5}
+ *     onChange={(value) => console.log(value)}
+ *   />
+ * );
+ * ```
+ *
+ * @see Input 基础输入框
+ * @see Cascader 级联选择器（内置了 SearchInput 作为搜索区域）
+ */
 export type SearchInputProps = Omit<InputProps, "value" | "onChange"> & {
     /**
-     * 配置 value 时，需把 debounceWait 设置为 0 ，否则输入时会有卡顿的问题
+     * 输入框的值，用于受控模式。
+     * 配置 value 时，需把 debounceWait 设置为 0，否则输入时会有卡顿的问题
      */
     value?: InputProps["value"];
     /**
-     * 防抖延迟的时间，单位为毫秒，默认为 300ms
+     * 防抖延迟时间，单位为毫秒。输入停止后延迟指定时间再触发 onChange
+     * @default 300
      */
     debounceWait?: number;
     /**
-     * 搜索结果的总数
+     * 搜索结果的总数。设置后，当同时提供 onSearchNext 和 onSearchPrev 时，
+     * 输入框后缀区域将显示 "current/total" 计数器和上下翻页按钮
      */
     total?: number;
     /**
-     * 当前选中的结果索引，可用于外部控制当前位置
+     * 当前选中的结果索引（从 1 开始），可用于外部控制当前位置。
      * 如果不提供，组件将内部管理此状态
      */
     current?: number;
     /**
-     * 搜索下一个结果时的回调函数
+     * 点击"下一个"按钮或按下 Enter 键时的回调。
+     * 需同时提供 onSearchPrev 才会显示导航按钮
+     * @param value - 当前搜索关键词
+     * @param current - 导航后的结果索引
      */
     onSearchNext?: (value: string, current: number) => void;
     /**
-     * 搜索上一个结果时的回调函数
+     * 点击"上一个"按钮时的回调。
+     * 需同时提供 onSearchNext 才会显示导航按钮
+     * @param value - 当前搜索关键词
+     * @param current - 导航后的结果索引
      */
     onSearchPrev?: (value: string, current: number) => void;
     /**
-     * 输入内容改变时的回调函数
+     * 输入内容改变时的回调函数（经过防抖处理后触发）
+     * @param value - 当前输入的搜索关键词
      */
     onChange: (value: string) => void;
     /**
-     * 搜索的图标
+     * 自定义搜索图标（输入框前缀），替换默认的放大镜图标
      */
     searchIcon?: SrcType;
     /**
-     * 上一个图标
+     * 自定义"上一个"按钮的默认态图标
      */
     prefixIcon?: SrcType;
     /**
-     * 上一个 hover 时的图标
+     * 自定义"上一个"按钮的 hover 态图标
      */
     prefixHoverIcon?: SrcType;
     /**
-     * 下一个图标
+     * 自定义"下一个"按钮的默认态图标
      */
     nextIcon?: SrcType;
     /**
-     * 下一个 hover 时的图标
+     * 自定义"下一个"按钮的 hover 态图标
      */
     nextHoverIcon?: SrcType;
     /**
-     * 清空图标
+     * 自定义清空按钮的默认态图标
      */
     clearIcon?: SrcType;
     /**
-     * 清空 hover 时的图标
+     * 自定义清空按钮的 hover 态图标
      */
     clearHoverIcon?: SrcType;
     /**
-     * 搜索框高度，默认为 276
+     * 搜索框宽度
+     * @default 276
      */
     width?: number | string;
     /**
-     * 是否开启最近搜索功能
+     * 是否开启最近搜索功能。开启后，聚焦空输入框时会显示最近搜索记录的下拉菜单。
+     * 搜索记录通过 localStorage 持久化存储
+     * @default false
      */
     enableRecentSearch?: boolean;
     /**
-     * 最近搜索的本地存储键
+     * 最近搜索记录在 localStorage 中的存储键名。
+     * 开启 enableRecentSearch 时必须提供，不同业务场景应使用不同的 key 以隔离数据
      */
     recentSearchLocalStorageKey?: string;
     /**
-     * 最多展示多少条最新的搜索记录，默认 5 条
+     * 最近搜索记录的最大展示条数
+     * @default 5
      */
     maxRecentCount?: number;
 };

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

@@ -19,6 +19,12 @@ export declare const TagSpan: import("@linaria/react").StyledComponent<import("r
 export declare const FullView: import("@linaria/react").StyledComponent<import("react").ClassAttributes<HTMLDivElement> & import("react").HTMLAttributes<HTMLDivElement> & Record<never, unknown>>;
 export declare const NameTag: import("@linaria/react").StyledComponent<import("react").ClassAttributes<HTMLSpanElement> & import("react").HTMLAttributes<HTMLSpanElement> & Record<never, unknown>>;
 export declare const FormItemDiv: import("@linaria/react").StyledComponent<import("react").ClassAttributes<HTMLDivElement> & import("react").HTMLAttributes<HTMLDivElement> & Record<never, unknown>>;
+/**
+ * FieldTitle 组件
+ * 使用场景：用于表单字段的标题展示
+ * 使用地方：主要在 Modal 等表单容器中使用
+ * 注意：默认字体大小为 12px，可通过 --field-title-font-size CSS 变量覆盖
+ */
 export declare const FieldTitle: import("@linaria/react").StyledComponent<import("react").ClassAttributes<HTMLDivElement> & import("react").HTMLAttributes<HTMLDivElement> & Record<never, unknown>>;
 export declare const ExpandArrow: import("@linaria/react").StyledComponent<import("react").ClassAttributes<HTMLElement> & import("react").HTMLAttributes<HTMLElement> & Record<never, unknown>>;
 export declare const WarningAlert: import("@linaria/core").LinariaClassName;

package/dist/src/core/Table/table.type.d.ts

@@ -1,4 +1,4 @@
-/// <reference types="react" />
+import React from "react";
 import { ColumnsType, ColumnType, TableProps as AntdTableProps } from "antd/lib/table";
 import { TableRowSelection, ExpandableConfig } from "antd/lib/table/interface";
 import { ITableSkeletonProps } from "./TableSkeleton";
@@ -12,39 +12,155 @@ type Columns<T> = ColumnsType<T>[0];
 export interface RequiredColumnProps<T> extends Omit<Columns<T>, "onHeaderCell" | "onCell" | "title"> {
     key: Exclude<Columns<T>["key"], undefined | number>;
     dataIndex: Exclude<ColumnType<T>["dataIndex"], undefined>;
+    /**
+     * 是否支持排序。设置为 true 时，点击表头可触发排序。
+     * @default false
+     */
     sortable?: boolean;
+    /**
+     * 列宽度。支持数字（像素）或字符串（如 "20%"）。
+     */
     width?: number | string;
     onHeaderCell?: (column: ColumnType<T>) => any;
     onCell?: (column: T) => any;
     /**
-     * removed params for title function
-     * because we need to cast the function in customize column
-     * which cannot access the header params
+     * 列标题。支持 React 节点或返回 React 节点的函数。
+     * 注意：函数形式不接收参数，与 antd 原生 title 函数签名不同。
      */
     title: React.ReactNode | (() => React.ReactNode);
+    /**
+     * 是否允许用户自定义该列。用于列配置功能。
+     * @default true
+     */
     customizable?: boolean;
 }
 export type SorterOrder = "descend" | "ascend" | undefined;
+/**
+ * 表格组件，基于 antd Table 二次封装，提供统一的 CloudTower 表格样式。
+ *
+ * @description
+ * 用于展示结构化数据列表，支持排序、行选择、展开行、加载状态、错误状态等功能。
+ * 数据源要求每条记录包含 id 字段作为唯一标识。
+ *
+ * @example
+ * // 基础用法
+ * import { Table } from "@cloudtower/eagle";
+ *
+ * interface VMData {
+ *   id: string;
+ *   name: string;
+ *   status: string;
+ *   cpu: number;
+ * }
+ *
+ * const columns = [
+ *   { key: "name", title: "名称", dataIndex: "name" },
+ *   { key: "status", title: "状态", dataIndex: "status" },
+ *   { key: "cpu", title: "CPU", dataIndex: "cpu" },
+ * ];
+ *
+ * <Table<VMData> columns={columns} dataSource={vms} />
+ *
+ * @example
+ * // 带行选择
+ * import { Table } from "@cloudtower/eagle";
+ * import { useState } from "react";
+ *
+ * const [selectedKeys, setSelectedKeys] = useState<string[]>([]);
+ *
+ * <Table<VMData>
+ *   columns={columns}
+ *   dataSource={vms}
+ *   rowSelection={{
+ *     selectedRowKeys: selectedKeys,
+ *     onChange: (keys) => setSelectedKeys(keys as string[]),
+ *   }}
+ * />
+ *
+ * @example
+ * // 带排序和加载状态
+ * import { Table } from "@cloudtower/eagle";
+ *
+ * <Table<VMData>
+ *   columns={columns}
+ *   dataSource={vms}
+ *   loading={isLoading}
+ *   onSorterChange={(order, key) => {
+ *     console.log("排序:", order, key);
+ *   }}
+ * />
+ *
+ * @see TableForm - 表格表单，用于行内编辑场景
+ * @see SummaryTable - 摘要表格，用于键值对信息展示
+ * @see BatchOperation - 批量操作工具栏，配合行选择使用
+ */
 export interface TableProps<T extends {
     id: string;
 }> {
+    /**
+     * 是否显示边框。
+     * @default false
+     */
     bordered?: boolean;
+    /**
+     * 是否显示加载状态。为 true 时显示骨架屏加载动画。
+     * @default false
+     */
     loading?: boolean;
     /**
-     *  This means errorEl.
+     * 错误状态内容。传入后将覆盖 dataSource，显示错误信息而非数据。
      */
     error?: React.ReactNode | string;
+    /**
+     * 数据源数组。每条记录必须包含 id 字段作为唯一标识。
+     */
     dataSource: T[] | undefined;
+    /**
+     * 列配置数组。定义表格的列结构。
+     */
     columns: RequiredColumnProps<T>[];
+    /**
+     * 排序变化回调。当用户点击可排序列的表头时触发。
+     * @param order - 排序方向："descend"（降序）、"ascend"（升序）、null（取消排序）
+     * @param key - 排序列的 key
+     */
     onSorterChange?: (order: SorterOrder | null, key?: string | number) => void;
+    /**
+     * 行点击回调。
+     * @deprecated 请使用 onRow 替代
+     * @param record - 点击行的数据记录
+     * @param index - 行索引
+     * @param evt - 鼠标事件
+     */
     onRowClick?: (record: T, index: number, evt: React.MouseEvent<HTMLElement, MouseEvent>) => void;
+    /**
+     * 行样式类名函数。根据行数据和索引返回自定义类名。
+     */
     rowClassName?: (record: T, index: number) => string;
+    /**
+     * 表格滚动配置。
+     * @example
+     * // 固定表头，内容区滚动
+     * scroll={{ y: 400 }}
+     * // 水平滚动
+     * scroll={{ x: 1200 }}
+     */
     scroll?: {
         x?: number | string | true;
         y?: number | string;
     };
+    /**
+     * 列宽调整回调。启用 resizable 后，用户拖拽调整列宽时触发。
+     */
     onResize?: (column: RequiredColumnProps<T>[]) => void;
+    /**
+     * 是否允许调整列宽。
+     * @default false
+     */
     resizable?: boolean;
+    /**
+     * 自定义表格组件。用于覆盖默认的 table/thead/tbody 渲染。
+     */
     components?: {
         table?: (props: any) => any;
         header?: {
@@ -58,25 +174,63 @@ export interface TableProps<T extends {
             cell?: (props: any) => any;
         };
     };
+    /**
+     * 行操作菜单组件。在每行末尾渲染操作按钮或菜单。
+     */
     RowMenu?: React.FC<{
         record: T;
         index: number;
     }>;
+    /**
+     * 行选择配置。启用后显示复选框列，支持单选或多选。
+     * @see https://ant.design/components/table-cn#rowSelection
+     */
     rowSelection?: TableRowSelection<T>;
+    /**
+     * 空数据时的显示内容。
+     */
     empty?: string | React.ReactNode;
+    /**
+     * 表格布局方式。
+     * - "fixed"：固定布局，列宽由第一行决定
+     * - "auto"：自动布局，列宽由内容决定
+     * @default "fixed"
+     */
     tableLayout?: "fixed" | "auto";
     /**
-     * @deprecated use loading instead
+     * 初始化加载状态。
+     * @deprecated 请使用 loading 替代
      */
     initLoading?: boolean;
+    /**
+     * 行的唯一标识字段。支持字符串或函数。
+     * @default "id"
+     */
     rowKey?: AntdTableProps<T>["rowKey"];
+    /**
+     * 表格容器引用。用于获取表格尺寸信息。
+     */
     wrapper?: React.MutableRefObject<HTMLDivElement | null>;
+    /**
+     * 分页配置。传入后将启用前端分页，通常用于骨架屏行数计算。
+     */
     pagination?: {
         current: number;
         pageSize: number;
     };
+    /**
+     * 行属性配置。用于设置行事件（如 onClick、onMouseEnter 等）。
+     * @see https://ant.design/components/table-cn#onRow
+     */
     onRow?: AntdTableProps<T>["onRow"];
+    /**
+     * 骨架屏配置。自定义加载状态下的骨架屏样式。
+     */
     skeletonProps?: ITableSkeletonProps;
+    /**
+     * 展开行配置。用于渲染可展开的行内容。
+     * @see https://ant.design/components/table-cn#expandable
+     */
     expandable?: ExpandableConfig<T>;
 }
 export {};

package/dist/stories/docs/core/Table.stories.d.ts

@@ -1,77 +1,66 @@
+import React from "react";
 import { Table } from "../../../src/core";
 import { StoryObj } from "@storybook/react";
-import React from "react";
 declare const meta: {
     component: <T extends {
         id: string;
     }>(props: import("../../../src/core").TableProps<T>) => React.JSX.Element;
     title: "Core/Table | 表格组件";
+    parameters: {
+        docs: {
+            description: {
+                component: string;
+            };
+        };
+    };
 };
 export default meta;
 type Story = StoryObj<typeof Table>;
 /**
- * 在 loading error 不存在的情况下
- *
- * 显示表格数据
+ * 基础表格展示，仅配置 columns 和 dataSource。
  */
-export declare const ShowData: Story;
+export declare const Basic: Story;
 /**
- * 自定义骨架屏表头，表身高度
+ * 带排序功能的表格，点击表头触发排序回调。
  */
-export declare const CustomHeight: Story;
+export declare const WithSorter: Story;
 /**
- * 初始化 loading
+ * 带行选择的表格，支持多选和全选。
  */
-export declare const InitLoading: Story;
+export declare const WithRowSelection: Story;
 /**
- * 使用分页作为骨架数量 loading
+ * 带行操作菜单的表格，在每行末尾渲染操作按钮。
  */
-export declare const LoadingSkeletonWithPageSize: Story;
+export declare const WithRowMenu: Story;
 /**
- * 在 loading error dataSource 存在值的情况下
- *
- * 显示 loading
+ * 加载状态，显示骨架屏动画。
  */
-export declare const ShowLoadingWithDataAndError: Story;
+export declare const Loading: Story;
 /**
- * 在 error dataSource 存在值的情况下
- *
- * 显示 error
+ * 自定义骨架屏配置，可调整行数、表头高度、行高度。
  */
-export declare const ShowError: Story;
+export declare const CustomSkeleton: Story;
 /**
- * 在 loading dataSource 存在值的情况下
- *
- * 显示 loading
+ * 错误状态，显示错误信息替代数据。
  */
-export declare const ShowLoadingWithData: Story;
+export declare const ErrorState: Story;
 /**
- * 在 error loading dataSource 不存在值的情况下
- *
- * 显示空表格
+ * 空数据状态，显示空状态提示。
  */
-export declare const ShowEmpty: Story;
+export declare const Empty: Story;
 /**
- * 仅存在 loading 的情况
- *
- * 显示 Loading
+ * 固定表头，内容区滚动。
  */
-export declare const ShowLoadingWithEmpty: Story;
+export declare const FixedHeader: Story;
 /**
- * 在 error false 的情况
- *
- * 显示 data
+ * 可展开行，点击展开显示详细信息。
  */
-export declare const ErrorFalse: Story;
+export declare const Expandable: Story;
 /**
- * 在 error loading dataSource 不存在值的情况下
- *
- * 固定表头显示空表格
+ * 使用 onRow 设置行事件。
  */
-export declare const ShowEmptyForFixd: Story;
+export declare const WithOnRow: Story;
 /**
- * 在 loading error 不存在的情况下
- *
- * 显示表格数据，表格可以展开
+ * @deprecated 请使用 loading 替代
  */
-export declare const ShowCanExpandData: Story;
+export declare const InitLoading: Story;