@cloudtower/eagle 490.0.5 → 490.0.6

package/dist/src/coreX/Dialogs/DeleteDialog/DeleteDialog.type.d.ts

@@ -1,25 +1,116 @@
 /// <reference types="react" />
+/**
+ * DeleteDialog 是一个预设了删除确认样式的对话框组件，基于 SmallDialog 封装。
+ * 确认按钮默认使用危险（红色）样式，适用于需要用户二次确认的删除操作。
+ * 支持异步删除（confirmLoading）和错误信息展示。
+ *
+ * @example
+ * ```tsx
+ * import React from "react";
+ * import { DeleteDialog, Button } from "@cloudtower/eagle";
+ * import { usePushModal } from "@cloudtower/eagle";
+ *
+ * const App = () => {
+ *   const pushModal = usePushModal();
+ *   return (
+ *     <Button
+ *       danger
+ *       onClick={() =>
+ *         pushModal({
+ *           component: () => (
+ *             <DeleteDialog
+ *               title="删除虚拟机"
+ *               description="确定要删除虚拟机 vm-prod-01 吗？"
+ *               secondaryDesc="删除后数据将无法恢复。"
+ *               onOk={(popModal) => {
+ *                 console.log("confirmed");
+ *                 popModal();
+ *               }}
+ *             />
+ *           ),
+ *           props: {},
+ *         })
+ *       }
+ *     >
+ *       删除
+ *     </Button>
+ *   );
+ * };
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 异步删除 + 错误处理
+ * import React, { useState } from "react";
+ * import { DeleteDialog } from "@cloudtower/eagle";
+ *
+ * const AsyncDeleteDialog = () => {
+ *   const [loading, setLoading] = useState(false);
+ *   const [error, setError] = useState<string>();
+ *
+ *   return (
+ *     <DeleteDialog
+ *       title="删除集群"
+ *       description="确定要删除集群 cluster-01 吗？"
+ *       confirmLoading={loading}
+ *       error={error}
+ *       onOk={async () => {
+ *         setLoading(true);
+ *         setError(undefined);
+ *         try {
+ *           await deleteCluster("cluster-01");
+ *         } catch {
+ *           setError("删除失败，请重试");
+ *         } finally {
+ *           setLoading(false);
+ *         }
+ *       }}
+ *     />
+ *   );
+ * };
+ * ```
+ *
+ * @see SmallDialog 底层对话框组件，DeleteDialog 基于其封装
+ * @see RejectDialog 操作被拒绝/不可执行时的反馈对话框
+ */
 export interface DeleteDialogProps {
     /** 弹窗标题 */
     title: React.ReactNode;
-    /** 主要描述文本 */
+    /** 主要描述文本，说明删除操作的影响 */
     description?: React.ReactNode;
-    /** 辅助说明文本 */
+    /** 辅助说明文本，显示在 description 下方，使用次要颜色 */
     secondaryDesc?: React.ReactNode;
-    /** 取消按钮文案 */
+    /**
+     * 取消按钮文案
+     * @default "取消"（i18n: common.cancel）
+     */
     cancelText?: string;
-    /** 确认按钮文案 */
+    /**
+     * 确认按钮文案
+     * @default "删除"（i18n: common.delete）
+     */
     okText?: string;
-    /** 点击确认按钮回调 */
+    /**
+     * 点击确认按钮回调。参数 popModal 用于关闭弹窗。
+     * 异步场景下可配合 confirmLoading 使用，操作完成后手动调用 popModal() 关闭。
+     */
     onOk?: (popModal: () => void) => void;
-    /** 点击取消按钮或关闭弹窗回调 */
+    /**
+     * 点击取消按钮或关闭弹窗回调。参数 popModal 用于关闭弹窗。
+     */
     onCancel?: (popModal: () => void) => void;
     /** 自定义类名 */
     className?: string;
-    /** 确认按钮加载状态 */
+    /**
+     * 确认按钮加载状态。设为 true 后按钮显示 loading 且不可点击。
+     * @default false
+     */
     confirmLoading?: boolean;
-    /** 展示在 modal footer 的错误文案 */
+    /** 展示在 modal footer 的错误文案，用于显示删除操作失败信息 */
     error?: React.ReactNode;
-    /** 是否展示在 modal footer 的错误图标, 默认展示 */
+    /**
+     * 是否展示 modal footer 的错误图标
+     * @default true
+     */
     showFooterErrorIcon?: boolean;
 }

package/dist/src/coreX/Dialogs/RejectDialog/RejectDialog.type.d.ts

@@ -1,74 +1,181 @@
 /// <reference types="react" />
 import type { ButtonProps } from "../../../core/Button";
+/** 拒绝原因，字符串类型 */
 export type RejectReason = string;
+/** 多个对象的拒绝原因映射，key 为对象名称，value 为原因列表 */
 export type RejectContent = Record<string, RejectReason[]>;
+/**
+ * RejectDialog 的类型枚举，决定对话框的展示模式
+ */
 export declare enum RejectDialogType {
+    /** 单个对象被拒绝，展示拒绝原因列表 */
     Single = "RejectSingle",
+    /** 批量操作中全部对象被拒绝，展示每个对象的拒绝原因 */
     All = "RejectAll",
+    /** 批量操作中部分对象被拒绝，可选择继续操作未被拒绝的部分 */
     Part = "RejectPart",
+    /** 自定义内容模式，完全自定义对话框内容 */
     Custom = "RejectCustom"
 }
+/**
+ * RejectDialog 基础属性，所有类型共享
+ */
 interface BaseRejectDialogProps {
     /** 弹窗标题 */
     title: React.ReactNode;
-    /** 在描述文本之前的内容 */
+    /** 在描述文本之前的自定义内容区域，用于展示背景信息 */
     beforeDescription?: React.ReactNode;
-    /** 补充描述文本 */
+    /** 补充描述文本，显示在 beforeDescription 之后、拒绝内容之前 */
     description?: React.ReactNode;
-    /** 取消按钮文案 */
+    /**
+     * 取消按钮文案
+     * @default "取消"（i18n: common.cancel）
+     */
     cancelText?: string;
-    /** 点击取消按钮或关闭弹窗回调 */
+    /** 点击取消按钮或关闭弹窗回调。参数 popModal 用于关闭弹窗。 */
     onCancel?: (popModal: () => void) => void;
-    /** 确认按钮属性 */
+    /** 确认按钮的额外属性，可用于覆盖按钮样式（如 danger: false） */
     okButtonProps?: ButtonProps;
-    /** 弹窗宽度 */
+    /** 弹窗宽度，覆盖 SmallDialog 默认的 492px */
     width?: number;
     /** 自定义类名 */
     className?: string;
-    /** 自定义footer类名 */
+    /** 自定义 footer 类名 */
     footerClassName?: string;
 }
+/**
+ * 单个对象拒绝模式。
+ * 展示一个对象被拒绝的原因，支持单条文本或多条原因列表。
+ */
 interface SingleRejectDialogProps extends BaseRejectDialogProps {
     type: RejectDialogType.Single;
-    /** 拒绝原因，可以是单个字符串或字符串数组 */
+    /** 拒绝原因。单条原因传字符串，多条原因传字符串数组。 */
     content: string | string[];
-    /** 列表类型 */
+    /**
+     * 列表类型，仅当 content 为数组时生效
+     * - "ordered": 有序编号列表
+     * - "unordered": 无序圆点列表
+     * - "resource": 资源列表样式（带背景色和可选图标）
+     * @default "ordered"
+     */
     listType?: "ordered" | "unordered" | "resource";
-    /** 灰色的进一步描述 */
+    /** 灰色的进一步描述，显示在拒绝原因上方 */
     secondaryDesc?: React.ReactNode;
-    /** 资源图标 */
+    /** 资源图标，仅当 listType 为 "resource" 时显示在每项前面 */
     resourceIcon?: React.ReactNode;
 }
+/**
+ * 批量全部拒绝模式。
+ * 所有选中对象均被拒绝，展示每个对象名称及其拒绝原因。
+ * 该模式不显示确认按钮，仅提供关闭操作。
+ */
 interface MultiAllRejectDialogProps extends BaseRejectDialogProps {
     type: RejectDialogType.All;
     /** 灰色的进一步描述 */
     secondaryDesc?: React.ReactNode;
-    /** 多个对象的拒绝原因，格式为 { [对象名]: string[] } */
+    /** 多个对象的拒绝原因，格式为 { [对象名]: [原因1, 原因2, ...] } */
     content: RejectContent;
-    /** 资源图标 */
+    /** 资源图标，显示在每个对象名称前面 */
     resourceIcon?: React.ReactNode;
 }
+/**
+ * 批量部分拒绝模式。
+ * 部分选中对象被拒绝，用户可选择继续操作未被拒绝的对象。
+ * 该模式显示确认按钮（默认 danger 样式），点击后执行部分操作。
+ */
 interface MultiPartialRejectDialogProps extends BaseRejectDialogProps {
     type: RejectDialogType.Part;
     /** 灰色的进一步描述 */
     secondaryDesc?: React.ReactNode;
-    /** 多个对象的拒绝原因，格式为 { [对象名]: string[] } */
+    /** 多个对象的拒绝原因，格式为 { [对象名]: [原因1, 原因2, ...] } */
     content: Record<string, string[]>;
-    /** 资源图标 */
+    /** 资源图标，显示在每个对象名称前面 */
     resourceIcon?: React.ReactNode;
-    /** 部分拒绝时的额外说明 */
+    /** 部分拒绝时的额外说明，展示在分割线下方，说明将跳过被拒绝的对象 */
     partialDescription: React.ReactNode;
-    /** 确认按钮文案 */
+    /** 确认按钮文案，如"部分升级" */
     okText?: string;
-    /** 点击确认按钮回调 */
+    /**
+     * 点击确认按钮回调。参数 popModal 用于关闭弹窗。
+     * 仅在 Part 模式下有效。
+     */
     onOk?: (popModal: () => void) => void;
 }
+/**
+ * 自定义内容模式。
+ * 完全自定义对话框内容，适用于标准模式无法满足的特殊拒绝场景。
+ * 该模式不显示确认按钮。
+ */
 interface CustomRejectDialogProps extends BaseRejectDialogProps {
     type: RejectDialogType.Custom;
-    /** 自定义内容 */
+    /** 自定义内容区域，替代标准的拒绝原因列表 */
     customContent: React.ReactNode;
     /** 确认按钮文案 */
     okText?: string;
 }
+/**
+ * RejectDialog 是操作拒绝反馈对话框，基于 SmallDialog 封装。
+ * 用于告知用户某个操作无法执行及其原因，支持四种模式：
+ * - Single: 单个对象被拒绝
+ * - All: 批量操作全部被拒绝
+ * - Part: 批量操作部分被拒绝（可继续操作未被拒绝的部分）
+ * - Custom: 自定义内容
+ *
+ * 通过 type 属性（RejectDialogType 枚举）区分不同模式，使用 TypeScript 可辨识联合类型。
+ *
+ * @example
+ * ```tsx
+ * // 单个对象拒绝
+ * import React from "react";
+ * import { RejectDialog, RejectDialogType, Button } from "@cloudtower/eagle";
+ * import { usePushModal } from "@cloudtower/eagle";
+ *
+ * const App = () => {
+ *   const pushModal = usePushModal();
+ *   return (
+ *     <Button
+ *       onClick={() =>
+ *         pushModal({
+ *           component: () => (
+ *             <RejectDialog
+ *               type={RejectDialogType.Single}
+ *               title="无法删除虚拟机"
+ *               content="虚拟机正在运行中，请先关机再执行删除操作"
+ *               description="请解决以上问题后重试"
+ *             />
+ *           ),
+ *           props: {},
+ *         })
+ *       }
+ *     >
+ *       删除虚拟机
+ *     </Button>
+ *   );
+ * };
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 批量部分拒绝
+ * import React from "react";
+ * import { RejectDialog, RejectDialogType } from "@cloudtower/eagle";
+ *
+ * <RejectDialog
+ *   type={RejectDialogType.Part}
+ *   title="升级虚拟机工具"
+ *   description="选中的 3 个虚拟机中，有 1 个可以升级。"
+ *   content={{ vm1: ["无需升级"], vm2: ["未安装虚拟机工具"] }}
+ *   partialDescription="2 个虚拟机无法升级，继续操作将跳过这些虚拟机。"
+ *   okText="部分升级"
+ *   onOk={(popModal) => {
+ *     console.log("执行部分升级");
+ *     popModal();
+ *   }}
+ * />
+ * ```
+ *
+ * @see SmallDialog 底层对话框组件
+ * @see DeleteDialog 删除确认对话框，用于需要用户确认的删除操作
+ */
 export type RejectDialogProps = SingleRejectDialogProps | MultiAllRejectDialogProps | MultiPartialRejectDialogProps | CustomRejectDialogProps;
 export {};

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

@@ -1,9 +1,39 @@
 import { ImmersiveDialog } from "../../../src/core/ImmersiveDialog";
 import React from "react";
-export declare const CenterImmersiveDialog: () => React.JSX.Element;
-export declare const FullContentImmersiveDialog: () => React.JSX.Element;
-export declare const ScrollableImmersiveDialog: () => React.JSX.Element;
-declare const story: {
+/**
+ * 居中内容
+ */
+export declare const CenterImmersiveDialog: {
+    (): React.JSX.Element;
+    storyName: string;
+};
+/**
+ * 全宽内容
+ */
+export declare const FullContentImmersiveDialog: {
+    (): React.JSX.Element;
+    storyName: string;
+};
+/**
+ * 可滚动内容
+ */
+export declare const ScrollableImmersiveDialog: {
+    (): React.JSX.Element;
+    storyName: string;
+};
+/**
+ * ImmersiveDialog 组件
+ *
+ * 全屏沉浸式对话框，适用于需要大面积操作空间的复杂表单和详情编辑。多步骤向导请使用 WizardDialog。
+ *
+ * ### 特性
+ * - 全屏展示，占满视口（留 10px 边距）
+ * - 支持三栏布局：左侧导航（192px）+ 中间内容（648px）+ 右侧辅助信息（192px）
+ * - `isContentFull` 模式隐藏左右面板，内容区占满宽度
+ * - 底部操作栏支持 `footerLeftAction` 自定义左侧区域
+ * - 内置初始化加载和错误重试状态
+ */
+declare const meta: {
     title: "Core/ImmersiveDialog | 全屏弹窗";
     component: typeof ImmersiveDialog;
     decorators: ((Story: import("@storybook/types").PartialStoryFn<import("@storybook/react/dist/types-0fc72a6d").R, {
@@ -95,17 +125,55 @@ declare const story: {
         initializingError?: React.ReactNode;
         children?: React.ReactNode;
     }>) => React.JSX.Element)[];
+    parameters: {
+        docs: {
+            description: {
+                component: string;
+            };
+        };
+    };
 };
-export default story;
+export default meta;
 /**
  * 带错误信息的对话框
  */
-export declare const WithError: () => React.JSX.Element;
+export declare const WithError: {
+    (): React.JSX.Element;
+    storyName: string;
+};
 /**
  * 初始化状态
  */
-export declare const Initializing: () => React.JSX.Element;
+export declare const Initializing: {
+    (): React.JSX.Element;
+    storyName: string;
+};
 /**
  * 不展示 footer
  */
-export declare const NoFooter: () => React.JSX.Element;
+export declare const NoFooter: {
+    (): React.JSX.Element;
+    storyName: string;
+};
+/**
+ * 三栏布局
+ *
+ * 演示 ImmersiveDialog 的核心三栏布局特性：左侧导航菜单 + 中间详情内容 + 右侧属性面板。
+ * 适合资源详情查看、配置编辑等非向导场景。
+ * 如需多步骤向导流程，请使用 WizardDialog。
+ */
+export declare const TwoPanelLayout: {
+    (): React.JSX.Element;
+    storyName: string;
+};
+/**
+ * 底部左侧操作区域
+ *
+ * 演示通过 `footerLeftAction` 在底部左侧放置辅助操作按钮。
+ * 此处展示"重置为默认值"按钮的典型用法。
+ * 如需"上一步"按钮等向导场景，请使用 WizardDialog。
+ */
+export declare const FooterLeftAction: {
+    (): React.JSX.Element;
+    storyName: string;
+};

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

@@ -20,32 +20,66 @@ export default meta;
 /**
  * 基础用法
  */
-export declare const Basic: () => React.JSX.Element;
+export declare const Basic: {
+    (): React.JSX.Element;
+    storyName: string;
+};
 /**
  * 表单配置对话框
  */
-export declare const FormConfiguration: () => React.JSX.Element;
+export declare const FormConfiguration: {
+    (): React.JSX.Element;
+    storyName: string;
+};
 /**
  * 数据展示对话框
  */
-export declare const DataDisplay: () => React.JSX.Element;
+export declare const DataDisplay: {
+    (): React.JSX.Element;
+    storyName: string;
+};
 /**
  * 带错误信息的对话框
  */
-export declare const WithError: () => React.JSX.Element;
+export declare const WithError: {
+    (): React.JSX.Element;
+    storyName: string;
+};
 /**
  * 长内容对话框
  */
-export declare const LongContent: () => React.JSX.Element;
+export declare const LongContent: {
+    (): React.JSX.Element;
+    storyName: string;
+};
 /**
  * 初始化状态
  */
-export declare const Initializing: () => React.JSX.Element;
+export declare const Initializing: {
+    (): React.JSX.Element;
+    storyName: string;
+};
 /**
  * 内容占满视窗
  */
-export declare const ContentFull: () => React.JSX.Element;
+export declare const ContentFull: {
+    (): React.JSX.Element;
+    storyName: string;
+};
 /**
  * 不展示 footer
  */
-export declare const NoFooter: () => React.JSX.Element;
+export declare const NoFooter: {
+    (): React.JSX.Element;
+    storyName: string;
+};
+/**
+ * SmallDialog 与 MediumDialog 的选型对比，帮助开发者在两者间做出正确选择。
+ *
+ * - **SmallDialog (492px)**：适合简单确认、删除提示、信息提示等简短交互
+ * - **MediumDialog (720px)**：适合表单填写、数据展示、多字段配置等需要更多空间的场景
+ */
+export declare const SizeComparison: {
+    (): React.JSX.Element;
+    storyName: string;
+};

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

@@ -1,4 +1,4 @@
-import SearchInput from "../../../src/core/SearchInput";
+import { SearchInput } from "../../../src/core/SearchInput";
 import type { StoryObj } from "@storybook/react";
 /**
  * * tower legacy 组件， 带 debounce 的搜索框
@@ -45,3 +45,8 @@ export declare const withTotal: Story;
  * 展示如何使用 current prop 控制搜索项目的当前索引
  */
 export declare const ExternallyControlled: Story;
+/**
+ * 带最近搜索的示例
+ * 展示如何使用 enableRecentSearch prop 启用最近搜索功能
+ */
+export declare const withRecentSearch: Story;

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

@@ -17,29 +17,108 @@ declare const meta: CoreMeta<typeof SmallDialog>;
 export default meta;
 /**
  * 基础用法
+ *
+ * 演示最基本的 SmallDialog 用法：通过 `usePushModal` 打开弹窗，
+ * 在 `onOk`/`onCancel` 回调中调用 `popModal()` 关闭弹窗。
  */
-export declare const Basic: () => React.JSX.Element;
+export declare const Basic: {
+    (): React.JSX.Element;
+    storyName: string;
+};
 /**
  * 确认删除对话框
+ *
+ * 演示危险操作确认场景：通过 `okButtonProps={{ danger: true }}` 将确认按钮标红，
+ * 自定义 `okText` 和 `cancelText` 按钮文案。
+ */
+/**
+ * 确认删除
+ *
+ * 演示用 SmallDialog 原始 API 实现删除确认弹窗。
+ * 生产环境中推荐直接使用 DeleteDialog，它已内置 danger 按钮和删除语义。
  */
-export declare const DeleteConfirmation: () => React.JSX.Element;
+export declare const DeleteConfirmation: {
+    (): React.JSX.Element;
+    storyName: string;
+};
 /**
  * 只有取消按钮
+ *
+ * 通过 `showOk={false}` 隐藏确认按钮，仅展示关闭按钮。
+ * 适用于纯信息提示场景。取消按钮样式自动从 `quiet` 变为 `ordinary`。
  */
-export declare const CancelOnly: () => React.JSX.Element;
+export declare const CancelOnly: {
+    (): React.JSX.Element;
+    storyName: string;
+};
 /**
  * 带错误信息的对话框
+ *
+ * 演示 `error` 属性：在 footer 区域显示错误文案（最多 3 行，超出后 tooltip 展示）。
+ * 首次点击"提交"模拟验证失败并显示错误，再次点击成功关闭。
  */
-export declare const WithError: () => React.JSX.Element;
+export declare const WithError: {
+    (): React.JSX.Element;
+    storyName: string;
+};
 /**
  * 长内容对话框
+ *
+ * 演示内容溢出时的滚动行为。包含长标题截断和长内容滚动两种场景。
  */
-export declare const LongContent: () => React.JSX.Element;
+export declare const LongContent: {
+    (): React.JSX.Element;
+    storyName: string;
+};
 /**
  * 初始化状态
+ *
+ * 演示 `initializing`、`initializingError` 属性的三种场景：
+ * 持续加载（骨架屏）、加载成功、加载失败后重试。
  */
-export declare const Initializing: () => React.JSX.Element;
+export declare const Initializing: {
+    (): React.JSX.Element;
+    storyName: string;
+};
 /**
  * 不展示 footer
+ *
+ * 通过 `hideFooter` 隐藏底部按钮区域，适用于纯展示内容的场景。
+ * 用户仍可通过右上角关闭按钮或遮罩层关闭弹窗。
+ */
+export declare const NoFooter: {
+    (): React.JSX.Element;
+    storyName: string;
+};
+/**
+ * 自定义标题渲染
+ *
+ * 通过 `TitleRender` 属性完全接管标题区域的渲染逻辑。
+ * 默认标题使用 `Typo.Display.d2_bold_title` 样式，
+ * 自定义时可添加图标、状态标签等额外元素。
+ */
+export declare const CustomTitle: {
+    (): React.JSX.Element;
+    storyName: string;
+};
+/**
+ * 异步提交
+ *
+ * 演示 `confirmLoading` + `onOk` 异步提交的完整流程，
+ * 这是最常见的业务模式：点击确认后显示 loading 状态，
+ * 异步操作完成后关闭弹窗，失败时展示错误信息并保持弹窗打开。
+ */
+export declare const AsyncSubmit: {
+    (): React.JSX.Element;
+    storyName: string;
+};
+/**
+ * 自定义按钮样式
+ *
+ * 通过 `okButtonProps` 和 `cancelButtonProps` 自定义确认和取消按钮的样式，
+ * 包括 `danger`、`disabled`、`type` 等属性。属性会透传给 Button 组件。
  */
-export declare const NoFooter: () => React.JSX.Element;
+export declare const ButtonCustomization: {
+    (): React.JSX.Element;
+    storyName: string;
+};