@cloudtower/eagle 0.0.0-no-uikit-1 → 0.0.0-theme-rc-1

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 模块）