@cloudtower/eagle 490.0.5 → 490.0.6

package/docs/core/WizardDialog/guide.md

@@ -0,0 +1,322 @@
+# WizardDialog
+
+## 简介
+
+WizardDialog 是基于 ImmersiveDialog 的多步骤向导对话框组件，自动管理步骤导航、步骤指示器和按钮文案切换。非最后一步时确定按钮显示"下一步"并触发 `onNextStep`；最后一步显示"确定"并触发 `onOk`。左侧内置垂直步骤条（Steps），底部自动展示"上一步"按钮（第一步时隐藏）。
+
+## 何时使用
+
+- 多步骤表单（如"创建虚拟机"需要依次填写基本信息、网络配置、存储配置）
+- 分步操作流程（需要引导用户按顺序完成一系列操作）
+- 需要在步骤之间做校验、阻止用户跳到下一步的场景
+
+不要使用：
+
+- 简单确认操作 --> 请用 `SmallDialog`
+- 不需要步骤的全屏操作 --> 请用 `ImmersiveDialog`
+- 包含表单但无需分步 --> 请用 `MediumDialog`
+
+## 基础用法
+
+```tsx
+import React from "react";
+import { WizardDialog, Button } from "@cloudtower/eagle";
+import { usePushModal, usePopModal } from "@cloudtower/eagle";
+
+const CreateVmDialog: React.FC = () => {
+  const popModal = usePopModal();
+
+  return (
+    <WizardDialog
+      title="创建虚拟机"
+      steps={[
+        {
+          title: "基本信息",
+          children: <div>填写虚拟机名称、描述等基本信息</div>,
+        },
+        {
+          title: "网络配置",
+          children: <div>选择网络、配置 IP 地址</div>,
+        },
+        {
+          title: "存储配置",
+          children: <div>选择存储策略、配置磁盘</div>,
+        },
+      ]}
+      onOk={(e) => {
+        console.log("提交创建");
+        popModal();
+      }}
+    >
+    </WizardDialog>
+  );
+};
+
+// 使用方式
+const App = () => {
+  const pushModal = usePushModal();
+
+  return (
+    <Button
+      type="primary"
+      onClick={() =>
+        pushModal({
+          component: () => <CreateVmDialog />,
+          props: { name: "CreateVmDialog" },
+        })
+      }
+    >
+      创建虚拟机
+    </Button>
+  );
+};
+```
+
+## 常见模式
+
+### 模式一：基础向导
+
+最简单的多步骤向导，步骤之间自由导航，最后一步提交。
+
+```tsx
+import React from "react";
+import { WizardDialog, Button } from "@cloudtower/eagle";
+import { usePushModal, usePopModal } from "@cloudtower/eagle";
+
+const BasicWizardDialog: React.FC = () => {
+  const popModal = usePopModal();
+
+  return (
+    <WizardDialog
+      title="初始化集群"
+      steps={[
+        {
+          title: "选择节点",
+          children: <div>从列表中选择要加入集群的节点</div>,
+        },
+        {
+          title: "网络设置",
+          children: <div>配置集群网络参数</div>,
+        },
+        {
+          title: "确认信息",
+          children: <div>确认集群配置信息无误后提交</div>,
+        },
+      ]}
+      onOk={(e) => {
+        console.log("提交集群初始化");
+        popModal();
+      }}
+    >
+    </WizardDialog>
+  );
+};
+
+const App = () => {
+  const pushModal = usePushModal();
+
+  return (
+    <Button
+      type="primary"
+      onClick={() =>
+        pushModal({
+          component: () => <BasicWizardDialog />,
+          props: { name: "BasicWizardDialog" },
+        })
+      }
+    >
+      初始化集群
+    </Button>
+  );
+};
+```
+
+### 模式二：带校验的向导（onNextStep 阻止导航）
+
+这是 WizardDialog 最核心的模式。通过 `onNextStep` 回调返回 `false` 来阻止用户在校验未通过时跳到下一步。注意：组件内部使用严格等于 `=== false` 判断，因此只有显式返回 `false` 才会阻止导航，返回 `undefined`（即不返回值）不会阻止。
+
+```tsx
+import React, { useState } from "react";
+import { WizardDialog, Button } from "@cloudtower/eagle";
+import { usePushModal, usePopModal } from "@cloudtower/eagle";
+
+const ValidatedWizardDialog: React.FC = () => {
+  const popModal = usePopModal();
+  const [vmName, setVmName] = useState("");
+  const [network, setNetwork] = useState("");
+  const [error, setError] = useState<string>();
+
+  return (
+    <WizardDialog
+      title="创建虚拟机"
+      error={error}
+      steps={[
+        {
+          title: "基本信息",
+          children: (
+            <div>
+              <label>虚拟机名称</label>
+              <input
+                value={vmName}
+                onChange={(e) => {
+                  setVmName(e.target.value);
+                  setError(undefined);
+                }}
+                placeholder="请输入虚拟机名称"
+              />
+            </div>
+          ),
+        },
+        {
+          title: "网络配置",
+          children: (
+            <div>
+              <label>网络</label>
+              <input
+                value={network}
+                onChange={(e) => {
+                  setNetwork(e.target.value);
+                  setError(undefined);
+                }}
+                placeholder="请选择网络"
+              />
+            </div>
+          ),
+        },
+        {
+          title: "确认",
+          children: (
+            <div>
+              <p>虚拟机名称：{vmName}</p>
+              <p>网络：{network}</p>
+            </div>
+          ),
+        },
+      ]}
+      onNextStep={(nextStep) => {
+        // nextStep 是即将跳转到的步骤索引
+        if (nextStep === 1 && !vmName.trim()) {
+          setError("请输入虚拟机名称");
+          return false; // 阻止导航
+        }
+        if (nextStep === 2 && !network.trim()) {
+          setError("请选择网络");
+          return false; // 阻止导航
+        }
+        setError(undefined);
+        // 不返回值（即返回 undefined），允许导航
+      }}
+      onOk={(e) => {
+        console.log("提交创建", { vmName, network });
+        popModal();
+      }}
+    >
+    </WizardDialog>
+  );
+};
+
+const App = () => {
+  const pushModal = usePushModal();
+
+  return (
+    <Button
+      type="primary"
+      onClick={() =>
+        pushModal({
+          component: () => <ValidatedWizardDialog />,
+          props: { name: "ValidatedWizardDialog" },
+        })
+      }
+    >
+      创建虚拟机
+    </Button>
+  );
+};
+```
+
+### 模式三：受控模式向导
+
+通过外部 state 控制当前步骤，配合 `onStepChange` 同步状态。适用于需要在父组件中根据步骤变化执行额外逻辑的场景。
+
+```tsx
+import React, { useState } from "react";
+import { WizardDialog, Button } from "@cloudtower/eagle";
+import { usePushModal, usePopModal } from "@cloudtower/eagle";
+
+const ControlledWizardDialog: React.FC = () => {
+  const popModal = usePopModal();
+  const [currentStep, setCurrentStep] = useState(0);
+
+  return (
+    <WizardDialog
+      title="部署应用"
+      step={currentStep}
+      onStepChange={(step) => {
+        console.log("步骤变化:", step);
+        setCurrentStep(step);
+      }}
+      onPrevStep={(step) => {
+        console.log("返回上一步:", step);
+      }}
+      onNextStep={(step) => {
+        console.log("进入下一步:", step);
+      }}
+      steps={[
+        {
+          title: "选择镜像",
+          children: <div>当前步骤：{currentStep + 1} / 3</div>,
+        },
+        {
+          title: "配置资源",
+          children: <div>当前步骤：{currentStep + 1} / 3</div>,
+        },
+        {
+          title: "确认部署",
+          children: <div>当前步骤：{currentStep + 1} / 3</div>,
+        },
+      ]}
+      onOk={(e) => {
+        console.log("确认部署");
+        popModal();
+      }}
+    >
+    </WizardDialog>
+  );
+};
+
+const App = () => {
+  const pushModal = usePushModal();
+
+  return (
+    <Button
+      type="primary"
+      onClick={() =>
+        pushModal({
+          component: () => <ControlledWizardDialog />,
+          props: { name: "ControlledWizardDialog" },
+        })
+      }
+    >
+      部署应用
+    </Button>
+  );
+};
+```
+
+## 关键说明
+
+- **按钮文案自动切换**：非最后一步时，确认按钮文案自动显示为 `nextText`（默认"下一步"）；最后一步时显示为 `okText`（默认"确认"）。
+- **onNextStep 校验机制**：`onNextStep` 返回值严格等于 `false`（`=== false`）时阻止导航到下一步。返回 `undefined`、`null`、`true` 或其他值均不会阻止。这是该组件最核心的交互模式。
+- **onOk 仅在最后一步触发**：非最后一步点击确认按钮时触发的是 `onNextStep`，不会触发 `onOk`。
+- **onOk 签名**：`onOk` 的签名为 `(e: React.MouseEvent) => void`，与 ImmersiveDialog 一致。需要使用 `usePopModal()` 获取 `popModal` 函数手动关闭弹窗。
+- **步骤内容保留**：默认情况下所有步骤内容均保留在 DOM 中（通过 `display: none` 隐藏），表单状态不会丢失。如需销毁非当前步骤的内容，可设置 `destroyOtherStep={true}`。
+- **"上一步"按钮**：当步骤索引大于 0 时，底部左侧自动展示"上一步"按钮（带左箭头图标）。第一步时不显示。
+- **footerLeftAction 被占用**：WizardDialog 内部使用 `footerLeftAction` 渲染"上一步"按钮，因此外部传入的 `footerLeftAction` 会被覆盖。
+
+## 相关组件
+
+- `ImmersiveDialog` -- 全屏沉浸式对话框，WizardDialog 的基础组件，适用于不需要步骤的全屏操作
+- `SmallDialog` -- 轻量级对话框（492px），适用于简单确认和信息提示
+- `MediumDialog` -- 中等尺寸对话框（720px），适用于包含表单输入的场景
+- `DeleteDialog` -- 删除确认对话框，封装了删除场景的标准样式和交互（位于 `@cloudtower/eagle` 的 coreX 模块）
+- `Steps` -- 步骤条组件，WizardDialog 内部使用的步骤指示器

package/docs/coreX/DeleteDialog/guide.md

@@ -0,0 +1,161 @@
+# DeleteDialog
+
+## 简介
+
+DeleteDialog 是一个预设了删除确认样式的对话框组件，基于 SmallDialog 封装。确认按钮默认使用危险（红色）样式以突出操作风险，支持异步删除（confirmLoading）和 footer 错误信息展示。固定宽度 492px。
+
+## 何时使用
+
+- 删除单个或多个资源前需要用户二次确认
+- 需要展示删除操作的风险提示（主描述 + 辅助说明）
+- 异步删除操作需要 loading 状态和错误反馈
+
+不要使用：
+
+- 操作被拒绝/不可执行的反馈 --> 请用 `RejectDialog`
+- 包含表单输入的删除确认 --> 请用 `MediumDialog`
+- 非删除类的简单确认 --> 请用 `SmallDialog`
+
+## 基础用法
+
+```tsx
+import React from "react";
+import {
+  DeleteDialog,
+  Button,
+  KitStoreProvider,
+  ModalStack,
+} from "@cloudtower/eagle";
+import { usePushModal } from "@cloudtower/eagle";
+
+const App = () => {
+  const pushModal = usePushModal();
+
+  return (
+    <Button
+      type="primary"
+      danger
+      onClick={() =>
+        pushModal({
+          component: () => (
+            <DeleteDialog
+              title="删除虚拟机"
+              description="确定要删除虚拟机 vm-prod-01 吗？"
+              secondaryDesc="删除后数据将无法恢复。"
+              onOk={(popModal) => {
+                console.log("confirmed delete");
+                popModal();
+              }}
+            />
+          ),
+          props: {},
+        })
+      }
+    >
+      删除虚拟机
+    </Button>
+  );
+};
+```
+
+## 常见模式
+
+### 模式一：异步删除 + 错误处理
+
+适用于删除操作需要调用 API 的场景。通过 `confirmLoading` 控制按钮加载状态，`error` 展示操作失败信息。
+
+```tsx
+import React, { useState } from "react";
+import { DeleteDialog, Button } from "@cloudtower/eagle";
+import { usePushModal } from "@cloudtower/eagle";
+
+const AsyncDeleteDialog = () => {
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string>();
+
+  return (
+    <DeleteDialog
+      title="删除集群"
+      description="确定要删除集群 cluster-01 吗？"
+      secondaryDesc="删除过程中请耐心等待。"
+      confirmLoading={loading}
+      error={error}
+      onOk={async (popModal) => {
+        setLoading(true);
+        setError(undefined);
+        try {
+          await deleteCluster("cluster-01");
+          popModal();
+        } catch {
+          setError("删除失败，请重试");
+        } finally {
+          setLoading(false);
+        }
+      }}
+    />
+  );
+};
+
+// 使用方式
+const App = () => {
+  const pushModal = usePushModal();
+
+  return (
+    <Button
+      type="primary"
+      danger
+      onClick={() =>
+        pushModal({ component: () => <AsyncDeleteDialog />, props: {} })
+      }
+    >
+      删除集群
+    </Button>
+  );
+};
+```
+
+### 模式二：自定义按钮文案
+
+适用于需要更明确的按钮文案来引导用户决策的场景。
+
+```tsx
+import React from "react";
+import { DeleteDialog, Button } from "@cloudtower/eagle";
+import { usePushModal } from "@cloudtower/eagle";
+
+const App = () => {
+  const pushModal = usePushModal();
+
+  return (
+    <Button
+      type="primary"
+      danger
+      onClick={() =>
+        pushModal({
+          component: () => (
+            <DeleteDialog
+              title="删除数据盘"
+              description="该数据盘中可能包含重要数据，删除后将无法恢复。"
+              cancelText="暂不删除"
+              okText="确认删除"
+              onOk={(popModal) => {
+                console.log("confirmed delete disk");
+                popModal();
+              }}
+            />
+          ),
+          props: {},
+        })
+      }
+    >
+      删除数据盘
+    </Button>
+  );
+};
+```
+
+## 相关组件
+
+- `SmallDialog`: 底层对话框组件（492px），DeleteDialog 基于其封装
+- `RejectDialog`: 操作拒绝反馈对话框，用于告知用户操作无法执行的原因
+- `MediumDialog`: 中型对话框（720px），适用于包含表单的删除确认

package/docs/coreX/RejectDialog/guide.md

@@ -0,0 +1,185 @@
+# RejectDialog
+
+## 简介
+
+RejectDialog 是操作拒绝反馈对话框，基于 SmallDialog 封装。用于告知用户某个操作无法执行及其原因，通过 `type` 属性（RejectDialogType 枚举）支持四种模式：Single（单个对象拒绝）、All（批量全部拒绝）、Part（批量部分拒绝）、Custom（自定义内容）。仅 Part 模式显示确认按钮（允许用户继续操作未被拒绝的部分）。
+
+## 何时使用
+
+- 单个资源操作被拒绝，需要展示拒绝原因（Single 模式）
+- 批量操作中全部资源都不可操作，需要逐一列出原因（All 模式）
+- 批量操作中部分资源不可操作，用户可选择跳过并继续（Part 模式）
+- 标准模式无法满足的特殊拒绝反馈（Custom 模式）
+
+不要使用：
+
+- 删除确认场景 --> 请用 `DeleteDialog`
+- 通用确认/提示场景 --> 请用 `SmallDialog`
+- 包含表单的操作反馈 --> 请用 `MediumDialog`
+
+## 基础用法
+
+```tsx
+import React from "react";
+import {
+  RejectDialog,
+  RejectDialogType,
+  Button,
+  KitStoreProvider,
+  ModalStack,
+} 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>
+  );
+};
+```
+
+## 常见模式
+
+### 模式一：单个对象拒绝 - 多条原因
+
+适用于单个资源有多个拒绝原因需要列出的场景。支持有序列表（ordered）、无序列表（unordered）和资源列表（resource）三种列表样式。
+
+```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={[
+                "虚拟机当前状态为运行中，需要先关机",
+                "存在未完成的数据备份任务",
+                "该虚拟机已被安全策略锁定",
+              ]}
+              listType="ordered"
+              description="请解决以上问题后重试"
+            />
+          ),
+          props: {},
+        })
+      }
+    >
+      删除虚拟机
+    </Button>
+  );
+};
+```
+
+### 模式二：批量全部拒绝
+
+适用于批量操作中所有资源均被拒绝的场景。content 使用 `{ [对象名]: [原因列表] }` 格式。
+
+```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.All}
+              title="无法删除选中的虚拟机"
+              content={{
+                "vm-master-01": ["作为集群主节点，需要先迁移控制平面"],
+                "vm-db-01": ["当前为主数据库节点", "有活跃的数据库连接"],
+              }}
+              description="以下虚拟机无法执行删除操作"
+              secondaryDesc="建议在业务低峰期执行删除操作"
+            />
+          ),
+          props: {},
+        })
+      }
+    >
+      批量删除虚拟机
+    </Button>
+  );
+};
+```
+
+### 模式三：批量部分拒绝
+
+适用于批量操作中部分资源可继续操作的场景。Part 模式会显示确认按钮（默认 danger 样式），通过 `okButtonProps={{ danger: false }}` 可改为非危险样式。
+
+```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.Part}
+              title="升级虚拟机工具"
+              description="选中的 3 个虚拟机中，有 1 个可以升级。"
+              content={{
+                vm1: ["无需升级"],
+                vm2: ["未安装虚拟机工具"],
+              }}
+              partialDescription="2 个虚拟机无法升级，继续操作将跳过这些虚拟机。"
+              okText="部分升级"
+              okButtonProps={{ danger: false }}
+              onOk={(popModal) => {
+                console.log("执行部分升级");
+                popModal();
+              }}
+            />
+          ),
+          props: {},
+        })
+      }
+    >
+      批量升级虚拟机工具
+    </Button>
+  );
+};
+```
+
+## 相关组件
+
+- `SmallDialog`: 底层对话框组件（492px），RejectDialog 基于其封装
+- `DeleteDialog`: 删除确认对话框，用于需要用户确认的删除操作
+- `MediumDialog`: 中型对话框（720px），适用于包含表单的复杂反馈场景