@cloudtower/eagle 0.0.0-testid-rc-0 → 0.0.0-theme-rc-1

package/dist/token.css

@@ -0,0 +1,251 @@
+:root, :root[data-theme="light"] {
+  --text-neutral-primary: #00122E;
+  --text-neutral-secondary: #2C3852BF;
+  --text-neutral-tertiary: #2C385299;
+  --text-neutral-quaternary: #0015404D;
+  --text-neutral-ontint: #FFFFFF;
+  --text-neutral-super: #1D326C;
+  --text-colorful-outstanding: #0080FF;
+  --text-colorful-serious: #F0483E;
+  --text-colorful-notice: #FEA008;
+  --text-colorful-noticedark: #E07F00;
+  --text-colorful-positive: #00BA5D;
+  --text-colorful-positivedark: #008F4C;
+  --text-colorful-purple: #7E41FF;
+  --link-outstandingnormal: #0080FF;
+  --link-outstandinghover: #009DFF;
+  --link-outstandingactive: #005ED1;
+  --link-neutralnormal: #2C3852BF;
+  --link-neutralhover: #2C385299;
+  --link-neutralactive: #172640CC;
+  --link-seriousnormal: #F0483E;
+  --link-serioushover: #FF5252;
+  --link-seriousactive: #C73D31;
+  --fill-neutral-lightwhite: #FFFFFF99;
+  --fill-neutral-trans-1: #EDF1FA99;
+  --fill-neutral-trans-2: #E1E6F199;
+  --fill-neutral-trans-3: #D3DAEB99;
+  --fill-neutral-trans-4: #C0CBE099;
+  --fill-neutral-trans-5: #ACBAD399;
+  --fill-neutral-trans-7: #0A255599;
+  --fill-neutral-trans-8: #172640CC;
+  --fill-neutral-white: #FFFFFF;
+  --fill-neutral-opaque-1: #F2F5FA;
+  --fill-neutral-opaque-2: #EDF0F7;
+  --fill-neutral-opaque-3: #E4E9F2;
+  --fill-neutral-opaque-4: #D8DEEB;
+  --fill-neutral-opaque-5: #CCD4E3;
+  --fill-neutral-opaque-6: #A3B4CC;
+  --fill-neutral-opaque-7: #6B7D99;
+  --fill-neutral-opaque-8: #2D3A56;
+  --fill-purple-base: #7E41FF;
+  --fill-purple-lightactive: #7E41FF33;
+  --fill-purple-lighthover: #7E41FF29;
+  --fill-purple-light: #7E41FF1A;
+  --fill-outstanding-deep: #1D326C;
+  --fill-outstanding-dark: #005ED1;
+  --fill-outstanding-base: #0080FF;
+  --fill-outstanding-bright: #009DFF;
+  --fill-outstanding-lightactive: #0088FF33;
+  --fill-outstanding-lighthover: #0088FF29;
+  --fill-outstanding-light: #0088FF1A;
+  --fill-outstanding-thin: #0088FF0A;
+  --fill-serious-deep: #7D2126;
+  --fill-serious-dark: #C73D31;
+  --fill-serious-base: #F0483E;
+  --fill-serious-bright: #FF5252;
+  --fill-serious-lightactive: #FF4A4A33;
+  --fill-serious-lighthover: #FF4A4A29;
+  --fill-serious-light: #FF4A4A1A;
+  --fill-serious-thin: #FF4A4A0A;
+  --fill-notice-deep: #8E671B;
+  --fill-notice-dark: #E07F00;
+  --fill-notice-base: #FEA008;
+  --fill-notice-bright: #FEBA33;
+  --fill-notice-lightactive: #FEA00833;
+  --fill-notice-lighthover: #FEA00829;
+  --fill-notice-light: #FEA0081A;
+  --fill-notice-thin: #FEA0080A;
+  --fill-positive-deep: #18544F;
+  --fill-positive-dark: #008F4C;
+  --fill-positive-base: #00BA5D;
+  --fill-positive-bright: #23CF6D;
+  --fill-positive-lightactive: #1EC97F33;
+  --fill-positive-lighthover: #1EC97F29;
+  --fill-positive-light: #1EC97F1A;
+  --fill-positive-thin: #1EC97F0A;
+  --stroke-neutral-lightwhite: #FFFFFF99;
+  --stroke-neutral-trans-1: #E1E6F199;
+  --stroke-neutral-trans-2: #D3DAEB99;
+  --stroke-neutral-trans-3: #ACBAD399;
+  --stroke-neutral-trans-4: #6B80A799;
+  --stroke-neutral-white: #FFFFFF;
+  --stroke-neutral-opaque-1: #EDF0F7;
+  --stroke-neutral-opaque-2: #E4E9F2;
+  --stroke-neutral-opaque-3: #CCD4E3;
+  --stroke-neutral-opaque-4: #A3B4CC;
+  --stroke-outstanding-base: #0080FF;
+  --stroke-outstanding-light: #0088FF29;
+  --stroke-serious-base: #F0483E;
+  --stroke-serious-light: #FF4A4A29;
+  --stroke-serious-thin: #FF4A4A1A;
+  --pagebackground-primary: #FFFFFF;
+  --pagebackground-grouped: #EDF0F7;
+  --dim-undermenu: #3F63941A;
+  --dim-single-dialogmask: #101A2966;
+  --dim-double-dialogmask: #101A2999;
+  --chart-blue-blue-1: #ADE5FF;
+  --chart-blue-blue-2: #7FD2FF;
+  --chart-blue-blue-3: #51BCFF;
+  --chart-blue-blue-4: #19A3FF;
+  --chart-blue-blue-5: #008CFF;
+  --chart-blue-blue-6: #0775F2;
+  --chart-blue-blue-7: #1064DA;
+  --chart-blue-blue-8: #0F53C1;
+  --chart-blue-blue-9: #0C3FA6;
+  --chart-blue-blue-10: #05318D;
+  --chart-green-green-1: #A2F0D5;
+  --chart-green-green-2: #80E4BC;
+  --chart-green-green-3: #62D9A4;
+  --chart-green-green-4: #47CD8A;
+  --chart-green-green-5: #21BE6A;
+  --chart-green-green-6: #06AC53;
+  --chart-green-green-7: #0C9646;
+  --chart-green-green-8: #0C8137;
+  --chart-green-green-9: #0A6B29;
+  --chart-green-green-10: #05551B;
+  --chart-purple-purple-1: #E1C1FF;
+  --chart-purple-purple-2: #CFA3FF;
+  --chart-purple-purple-3: #BE89FF;
+  --chart-purple-purple-4: #A66BFF;
+  --chart-purple-purple-5: #8E51FF;
+  --chart-purple-purple-6: #753BF1;
+  --chart-purple-purple-7: #612FD4;
+  --chart-purple-purple-8: #4E27B9;
+  --chart-purple-purple-9: #3D1D9F;
+  --chart-purple-purple-10: #2B1385;
+  --chart-red-red-1: #FFBCC1;
+  --chart-red-red-2: #FFA8A9;
+  --chart-red-red-3: #FF8989;
+  --chart-red-red-4: #FC726E;
+  --chart-red-red-5: #F4554C;
+  --chart-red-red-6: #DE433B;
+  --chart-red-red-7: #BB3935;
+  --chart-red-red-8: #992F2D;
+  --chart-red-red-9: #782725;
+  --chart-red-red-10: #571E1E;
+  --chart-yellow-yellow-1: #FFDE6C;
+  --chart-yellow-yellow-2: #FED158;
+  --chart-yellow-yellow-3: #FEC444;
+  --chart-yellow-yellow-4: #FEB630;
+  --chart-yellow-yellow-5: #FEA819;
+  --chart-yellow-yellow-6: #E79305;
+  --chart-yellow-yellow-7: #BB7A03;
+  --chart-yellow-yellow-8: #926102;
+  --chart-yellow-yellow-9: #6B4803;
+  --chart-yellow-yellow-10: #483100;
+  --chart-pink-pink-1: #FED1FE;
+  --chart-pink-pink-2: #FDBCFD;
+  --chart-pink-pink-3: #F99BF8;
+  --chart-pink-pink-4: #F573F2;
+  --chart-pink-pink-5: #ED5BE5;
+  --chart-pink-pink-6: #E136C6;
+  --chart-pink-pink-7: #CF23A9;
+  --chart-pink-pink-8: #B5158D;
+  --chart-pink-pink-9: #910B6E;
+  --chart-pink-pink-10: #64054B;
+  --chart-cyan-cyan-1: #A0ECEC;
+  --chart-cyan-cyan-2: #83E2E3;
+  --chart-cyan-cyan-3: #67D8D9;
+  --chart-cyan-cyan-4: #3AC4C6;
+  --chart-cyan-cyan-5: #1AACB4;
+  --chart-cyan-cyan-6: #048BA1;
+  --chart-cyan-cyan-7: #00728E;
+  --chart-cyan-cyan-8: #00607B;
+  --chart-cyan-cyan-9: #005068;
+  --chart-cyan-cyan-10: #004155;
+  --white-white: #FFFFFF;
+  --white-white-a60: #FFFFFF99;
+  --gray-gray-10: #F2F5FA;
+  --gray-gray-20: #EDF0F7;
+  --gray-gray-30: #E4E9F2;
+  --gray-gray-40: #D8DEEB;
+  --gray-gray-50: #CCD4E3;
+  --gray-gray-60: #A3B4CC;
+  --gray-gray-70: #6B7D99;
+  --gray-gray-80: #2D3A56;
+  --gray-gray-90: #172640;
+  --gray-gray-100: #0D1B36;
+  --gray-gray-110: #0A1833;
+  --gray-gray-120: #00122E;
+  --gray-gray-a60-1: #EDF1FA99;
+  --gray-gray-a60-2: #E1E6F199;
+  --gray-gray-a60-3: #D3DAEB99;
+  --gray-gray-a60-4: #C0CBE099;
+  --gray-gray-a60-5: #ACBAD399;
+  --gray-gray-a60-6: #6B80A799;
+  --gray-gray-a80-6: #6B80A7CC;
+  --gray-gray-a60-7: #0A255599;
+  --gray-gray-a60-8: #2C385299;
+  --gray-gray-a75-8: #2C3852BF;
+  --gray-gray-a80-9: #172640CC;
+  --gray-gray-a30-10: #0015404D;
+  --blue-blue-90: #1D326C;
+  --blue-blue-60: #005ED1;
+  --blue-blue-50: #0080FF;
+  --blue-blue-40: #009DFF;
+  --blue-blue-a20-50: #0088FF33;
+  --blue-blue-a16-50: #0088FF29;
+  --blue-blue-a10-50: #0088FF1A;
+  --blue-blue-a04-50: #0088FF0A;
+  --red-red-90: #7D2126;
+  --red-red-60: #C73D31;
+  --red-red-50: #F0483E;
+  --red-red-40: #FF5252;
+  --red-red-a20-50: #FF4A4A33;
+  --red-red-a16-50: #FF4A4A29;
+  --red-red-a10-50: #FF4A4A1A;
+  --red-red-a04-50: #FF4A4A0A;
+  --yellow-yellow-90: #8E671B;
+  --yellow-yellow-60: #E07F00;
+  --yellow-yellow-50: #FEA008;
+  --yellow-yellow-40: #FEBA33;
+  --yellow-yellow-a20-50: #FEA00833;
+  --yellow-yellow-a16-50: #FEA00829;
+  --yellow-yellow-a10-50: #FEA0081A;
+  --yellow-yellow-a04-50: #FEA0080A;
+  --green-green-90: #18544F;
+  --green-green-60: #008F4C;
+  --green-green-50: #00BA5D;
+  --green-green-40: #23CF6D;
+  --green-green-a20-50: #1EC97F33;
+  --green-green-a16-50: #1EC97F29;
+  --green-green-a10-50: #1EC97F1A;
+  --green-green-a04-50: #1EC97F0A;
+  --purple-purple-50: #7E41FF;
+  --purple-purple-a20-50: #7E41FF33;
+  --purple-purple-a16-50: #7E41FF29;
+  --purple-purple-a10-50: #7E41FF1A;
+  --gradient-loading: linear-gradient(90deg, #0080ff 0%, #9ecfff 50%, #0080ff 100%);
+  --gradient-light-blue: linear-gradient(180deg,rgba(0, 136, 255, 0.2) 0%,rgba(0, 136, 255, 0.6) 100%);
+  --gradient-dark-blue: radial-gradient(133.15% 133.15% at 4.69% 7.03%, #5BCAFF 0%, #06F 100%);
+  --effect-shadow-dashboardCard-normal: 0px 0px 16px 0px rgba(107,125,153,0.08), 0px 0px 2.003px 0px rgba(107,125,153,0.15);
+  --effect-shadow-dashboardCard-hoverFloat: 0px 0px 4px -2px rgba(10,37,85,0.18), 0px 8px 16px 0px rgba(10,37,85,0.18);
+  --effect-shadow-listItem-hover: 0px 0px 4px 0px rgba(235,239,245,0.6), 0px 8px 16px 0px rgba(129,138,153,0.18);
+  --effect-shadow-listItem-selected: 0px 1px 2px 0px rgba(184,192,204,0.6);
+  --effect-shadow-menu-default: 0px 0px 10px 0px rgba(107,125,153,0.18), 0px 12px 40px 0px rgba(45,58,86,0.3);
+  --effect-shadow-menu-above: 0px 0px 10px 0px rgba(107,125,153,0.18), 0px -12px 40px 0px rgba(45,58,86,0.3);
+  --effect-shadow-button-cta: 0px 1px 2px 0px rgba(44,56,82,0.18);
+  --effect-shadow-button-ordinary: 0px 1px 2px -1px rgba(44,56,82,0.18);
+  --effect-shadow-previewPanel-default: 0px 0px 20px 0px rgba(107,125,153,0.18), 0px 25px 80px 0px rgba(45,58,86,0.3);
+  --effect-shadow-previewPanel-above: 0px 0px 20px 0px rgba(107,125,153,0.18), 0px -25px 80px 0px rgba(45,58,86,0.3);
+  --effect-shadow-tooltip: 0px 1px 4px 0px rgba(29,50,108,0.6);
+  --effect-glow-toast-blue: 0px 2px 12px -4px rgba(0,128,255,0.6);
+  --effect-glow-toast-red: 0px 2px 12px -4px rgba(240,72,62,0.6);
+  --effect-glow-toast-green: 0px 2px 12px -4px rgba(0,186,93,0.6);
+  --effect-glow-toast-yellow: 0px 2px 12px -4px rgba(254,160,8,0.6);
+  --effect-outline-hover: 0px 0px 0px 4px rgba(225,230,241,0.6);
+  --effect-outline-activeFocus: 0px 0px 0px 4px rgba(0,136,255,0.16);
+  --effect-outline-error: 0px 0px 0px 4px rgba(255,74,74,0.16);
+  --effect-outline-notice: 0px 0px 0px 4px rgba(254,160,8,0.16);
+}

package/docs/core/Alert/guide.md

@@ -0,0 +1,126 @@
+# Alert
+
+## 简介
+
+提示框组件，基于 antd Alert 封装。用于页面内的警告或提示信息展示，支持 info / error / warning / success / normal 五种类型。扩展了 action 操作区和展开/收起功能。
+
+## 何时使用
+
+- 表单或页面中展示操作提示、警告、错误信息
+- 内容较长需要折叠展示时，使用 expandConfig 模式
+- 需要在提示信息旁边放置操作按钮（如跳转链接）
+
+不要使用：
+
+- 全局横幅通知 --> 请用 `Banner`
+- 自动消失的轻提示 --> 请用 `message`
+- 需要用户确认的模态提示 --> 请用 `SmallDialog`
+
+## 基础用法
+
+```tsx
+import React from "react";
+import Alert from "@cloudtower/eagle/Alert";
+
+const App = () => <Alert type="info" message="集群升级已完成。" />;
+```
+
+## 常见模式
+
+### 模式一：带操作按钮
+
+适用于提示信息旁需要放置操作入口的场景，如跳转到详情页。
+
+```tsx
+import React from "react";
+import Alert from "@cloudtower/eagle/Alert";
+
+const App = () => (
+  <Alert
+    type="warning"
+    message="主机 node-1 存在未处理的告警。"
+    action={<a>查看详情</a>}
+  />
+);
+```
+
+### 模式二：展开/收起（非受控）
+
+适用于提示内容较长、需要折叠展示的场景。收起时仅显示 message，展开后在 message 下方内联显示 description。
+
+```tsx
+import React from "react";
+import Alert from "@cloudtower/eagle/Alert";
+
+const App = () => (
+  <Alert
+    type="info"
+    message="以下系统服务的版本不适配多管理 IP 模式："
+    description={
+      <ul>
+        <li>可观测性服务 service-A，需升级至 1.4.5 及以上版本</li>
+        <li>CloudTower 代理 agent-A，需升级至 1.3.7 及以上版本</li>
+      </ul>
+    }
+    expandConfig={{}}
+  />
+);
+```
+
+设置默认展开：`expandConfig={{ defaultExpanded: true }}`。
+
+### 模式三：展开/收起（受控）
+
+适用于需要从外部控制展开状态的场景。
+
+```tsx
+import React, { useState } from "react";
+import Alert from "@cloudtower/eagle/Alert";
+
+const App = () => {
+  const [expanded, setExpanded] = useState(false);
+
+  return (
+    <Alert
+      type="info"
+      message="以下系统服务的版本不适配多管理 IP 模式："
+      description={
+        <ul>
+          <li>可观测性服务 service-A，需升级至 1.4.5 及以上版本</li>
+        </ul>
+      }
+      expandConfig={{ expanded, onExpandChange: setExpanded }}
+    />
+  );
+};
+```
+
+### 模式四：可关闭 + 操作 + 展开/收起
+
+多种功能可组合使用。
+
+```tsx
+import React from "react";
+import Alert from "@cloudtower/eagle/Alert";
+
+const App = () => (
+  <Alert
+    type="info"
+    message="以下服务需要升级："
+    description={
+      <ul>
+        <li>备份服务 v2.3.0 -> v2.3.1</li>
+      </ul>
+    }
+    action={<a>立即升级</a>}
+    expandConfig
+    closable
+  />
+);
+```
+
+## 相关组件
+
+- `Banner`：全局横幅通知，固定在页面顶部
+- `message`：全局提示，自动消失
+- `SmallDialog`：需要用户确认的模态提示

package/docs/core/ImmersiveDialog/guide.md

@@ -0,0 +1,323 @@
+# ImmersiveDialog
+
+## 简介
+
+ImmersiveDialog 是一个沉浸式全屏对话框组件，支持左中右三栏布局。默认三栏布局宽度：左侧面板 192px、中间内容区 648px、右侧面板 192px。设置 `isContentFull` 后内容区占满整个对话框，不再渲染左右面板。通过 `usePushModal` / `usePopModal` 管理弹窗生命周期，内置初始化加载态、错误信息展示和骨架屏等能力。
+
+## 何时使用
+
+- 需要大面积内容展示的场景（如详情页、配置面板）
+- 复杂操作流程，需要同时展示导航、内容和辅助信息
+- 需要左侧导航 + 中间表单/内容 + 右侧帮助信息的三栏布局
+
+不要使用：
+
+- 多步骤向导流程 --> 请用 `WizardDialog`
+- 简单确认操作 --> 请用 `SmallDialog`
+- 包含表单的中等复杂度场景 --> 请用 `MediumDialog`
+
+## 布局说明
+
+ImmersiveDialog 提供两种布局模式：
+
+### 三栏布局（默认）
+
+默认模式下，对话框分为左、中、右三栏：
+
+- **左侧面板**（`left`）：宽度 192px，适合放置导航菜单或步骤指示器
+- **中间内容区**（`children`）：宽度 648px，标题和 footer 与中间内容区对齐
+- **右侧面板**（`right`）：宽度 192px，适合放置辅助信息或快捷操作
+
+左右面板为 `position: fixed` 定位，中间内容区可独立滚动。
+
+### 全屏内容模式（`isContentFull`）
+
+设置 `isContentFull={true}` 后，左右面板不再渲染，内容区占满整个对话框宽度（左右各留 40px 内边距）。适用于不需要侧边栏的全屏展示场景。
+
+## 基础用法
+
+```tsx
+import React from "react";
+import { ImmersiveDialog, Button } from "@cloudtower/eagle";
+import { usePushModal, usePopModal } from "@cloudtower/eagle";
+
+const NetworkConfigDialog: React.FC = () => {
+  const popModal = usePopModal();
+
+  return (
+    <ImmersiveDialog
+      title="网络配置"
+      left={<div>导航菜单</div>}
+      right={<div>帮助信息</div>}
+      onOk={() => {
+        console.log("确认保存");
+        popModal();
+      }}
+    >
+      <p>这里是网络配置的主体内容。</p>
+    </ImmersiveDialog>
+  );
+};
+
+// 使用方式
+const App = () => {
+  const pushModal = usePushModal();
+
+  return (
+    <Button
+      type="primary"
+      onClick={() =>
+        pushModal({
+          component: () => <NetworkConfigDialog />,
+          props: { name: "NetworkConfigDialog" },
+        })
+      }
+    >
+      网络配置
+    </Button>
+  );
+};
+```
+
+> **注意**：ImmersiveDialog 的 `onOk` 签名是 `(e: React.MouseEvent) => void`，不会自动关闭弹窗。必须通过 `usePopModal()` 获取 `popModal` 函数手动关闭，这一点与 SmallDialog / MediumDialog 的 `(popModal: () => void) => void` 签名不同。
+
+## 初始化生命周期
+
+`initializeOnce` 默认为 `true`，首次初始化成功后忽略后续的 `initializing` 和 `initializingError`，保留正常标题、内容和 footer。成功前允许失败后多次重试；设置 `initializeOnce={false}` 可恢复完全受控行为。
+
+初始化记录按组件的挂载周期计算。仅切换 `visible`，包括底层 Modal 的 `destroyOnClose` 销毁内容，都不会重置 ImmersiveDialog 自身的记录。切换资源并需要重新初始化时，可通过 `key` 重新挂载。
+
+首次渲染没有加载和错误时也视为成功；延迟请求应在准备期间保持 `initializing=true`。更多调用约定见 [SmallDialog 初始化生命周期](../SmallDialog/guide.md#初始化生命周期)。
+
+## 暂时禁用关闭
+
+`closeDisabled` 默认为 `false`。设为 `true` 时保留灰色且原生禁用的右上角关闭按钮，同时阻止 Escape 和点击遮罩关闭。即使显式设置 `keyboard` 或 `maskClosable` 为 `true`，锁定期间也不会关闭；恢复为 `false` 后按这两项的原有配置处理。
+
+`closable={false}` 优先隐藏关闭按钮，自定义 `closeIcon` 在禁用期间仍会展示。此属性只锁定右上角关闭及其快捷入口，不影响 footer 取消按钮、确认按钮或业务主动调用 `popModal()`。异步任务需要锁定全部退出入口时，应同时设置 `cancelButtonProps.disabled`。
+
+```tsx
+<ImmersiveDialog
+  title="检查环境"
+  closeDisabled={checking}
+  cancelButtonProps={{ disabled: checking }}
+  okButtonProps={{ disabled: checking }}
+>
+  <EnvironmentCheck />
+</ImmersiveDialog>
+```
+
+## 常见模式
+
+### 模式一：三栏布局
+
+适用于需要导航、内容和辅助信息同时展示的场景。左右面板固定定位，中间内容区可滚动。
+
+```tsx
+import React from "react";
+import { ImmersiveDialog, Button } from "@cloudtower/eagle";
+import { usePushModal, usePopModal } from "@cloudtower/eagle";
+
+const ClusterConfigDialog: React.FC = () => {
+  const popModal = usePopModal();
+
+  return (
+    <ImmersiveDialog
+      title="集群配置"
+      left={
+        <ul>
+          <li>基本信息</li>
+          <li>网络设置</li>
+          <li>存储配置</li>
+          <li>高可用</li>
+        </ul>
+      }
+      right={
+        <div>
+          <h4>帮助</h4>
+          <p>集群配置说明文档...</p>
+        </div>
+      }
+      onOk={() => {
+        console.log("保存配置");
+        popModal();
+      }}
+    >
+      <div>
+        <h3>基本信息</h3>
+        <p>集群名称、描述等配置项...</p>
+      </div>
+    </ImmersiveDialog>
+  );
+};
+
+const App = () => {
+  const pushModal = usePushModal();
+
+  return (
+    <Button
+      type="primary"
+      onClick={() =>
+        pushModal({
+          component: () => <ClusterConfigDialog />,
+          props: { name: "ClusterConfigDialog" },
+        })
+      }
+    >
+      集群配置
+    </Button>
+  );
+};
+```
+
+### 模式二：全屏内容（isContentFull）
+
+适用于不需要侧边栏的全屏展示场景，如查看大量数据、展示图表等。
+
+```tsx
+import React from "react";
+import { ImmersiveDialog, Button } from "@cloudtower/eagle";
+import { usePushModal, usePopModal } from "@cloudtower/eagle";
+
+const MonitorDashboardDialog: React.FC = () => {
+  const popModal = usePopModal();
+
+  return (
+    <ImmersiveDialog
+      title="监控面板"
+      isContentFull
+      showOk={false}
+      cancelText="关闭"
+      onCancel={() => {
+        popModal();
+      }}
+    >
+      <div>
+        <h3>CPU 使用率</h3>
+        <p>图表内容...</p>
+        <h3>内存使用率</h3>
+        <p>图表内容...</p>
+      </div>
+    </ImmersiveDialog>
+  );
+};
+
+const App = () => {
+  const pushModal = usePushModal();
+
+  return (
+    <Button
+      onClick={() =>
+        pushModal({
+          component: () => <MonitorDashboardDialog />,
+          props: { name: "MonitorDashboardDialog" },
+        })
+      }
+    >
+      查看监控
+    </Button>
+  );
+};
+```
+
+### 模式三：带 footerLeftAction 的对话框
+
+适用于需要在 footer 左侧放置额外操作（如"重置"按钮、提示文案）的场景。
+
+```tsx
+import React, { useState } from "react";
+import { ImmersiveDialog, Button } from "@cloudtower/eagle";
+import { usePushModal, usePopModal } from "@cloudtower/eagle";
+
+const AdvancedSettingsDialog: React.FC = () => {
+  const popModal = usePopModal();
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string>();
+
+  return (
+    <ImmersiveDialog
+      title="高级设置"
+      isContentFull
+      confirmLoading={loading}
+      error={error}
+      footerLeftAction={
+        <Button type="quiet" onClick={() => console.log("重置为默认值")}>
+          重置为默认值
+        </Button>
+      }
+      onOk={async () => {
+        setLoading(true);
+        setError(undefined);
+        try {
+          await saveSettings();
+          popModal();
+        } catch (e) {
+          setError("保存设置失败，请重试");
+        } finally {
+          setLoading(false);
+        }
+      }}
+    >
+      <div>
+        <h3>高级配置项</h3>
+        <p>配置内容...</p>
+      </div>
+    </ImmersiveDialog>
+  );
+};
+
+const App = () => {
+  const pushModal = usePushModal();
+
+  return (
+    <Button
+      type="primary"
+      onClick={() =>
+        pushModal({
+          component: () => <AdvancedSettingsDialog />,
+          props: { name: "AdvancedSettingsDialog" },
+        })
+      }
+    >
+      高级设置
+    </Button>
+  );
+};
+```
+
+## 关键警告
+
+ImmersiveDialog 的 `onOk` 签名是 `(e: React.MouseEvent) => void`，与 SmallDialog / MediumDialog 的 `(popModal: () => void) => void` **不同**。
+
+- SmallDialog / MediumDialog：`onOk` 回调的第一个参数就是 `popModal` 函数，可以直接调用来关闭弹窗。
+- ImmersiveDialog：`onOk` 回调的参数是原生的鼠标事件对象，**不会自动关闭弹窗**。必须在组件内部通过 `usePopModal()` hook 获取 `popModal` 函数，手动调用来关闭弹窗。
+
+```tsx
+// SmallDialog -- onOk 的参数就是 popModal
+<SmallDialog
+  onOk={(popModal) => {
+    popModal(); // 直接通过参数关闭
+  }}
+/>;
+
+// ImmersiveDialog -- 需要 usePopModal() hook
+const MyDialog = () => {
+  const popModal = usePopModal(); // 必须通过 hook 获取
+
+  return (
+    <ImmersiveDialog
+      onOk={(e) => {
+        // e 是 React.MouseEvent，不是 popModal
+        popModal(); // 通过 hook 返回的函数关闭
+      }}
+    />
+  );
+};
+```
+
+## 相关组件
+
+- `SmallDialog` -- 小型对话框（492px），适用于简单确认和信息提示场景
+- `MediumDialog` -- 中等尺寸对话框（720px），适用于包含表单输入的场景
+- `WizardDialog` -- 向导式对话框，适用于多步骤流程
+- `DeleteDialog` -- 删除确认对话框，封装了删除场景的标准样式和交互（位于 `@cloudtower/eagle` 的 coreX 模块）
+- `RejectDialog` -- 操作拒绝反馈对话框，支持 Single（单条拒绝）、All（全部拒绝）、Part（部分拒绝）、Custom（自定义内容）四种模式（位于 `@cloudtower/eagle` 的 coreX 模块）