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

package/docs/core/MediumDialog/guide.md

@@ -0,0 +1,272 @@
+# MediumDialog
+
+## 简介
+
+MediumDialog 是一个固定 720px 宽度的中型对话框组件，继承 SmallDialog 的全部功能，在此基础上提供更大的显示区域（720px 宽度、60px 水平内边距）和更突出的标题排版（d1s_bold_title）。适用于包含表单输入、内容较多的确认等场景。通过 `isContentFull` 属性可开启全屏模式，使弹窗尺寸变为 `width: calc(100vw - 160px)`、`height: calc(100vh - 80px)`，适合需要大面积展示内容的场景。
+
+## 何时使用
+
+- 包含表单输入的弹窗（如编辑虚拟机配置、创建网络策略）
+- 内容较多的确认弹窗，492px 宽度不够展示时
+- 需要大面积展示内容（如表格、拓扑图）的场景，配合 `isContentFull` 使用
+
+不要使用：
+
+- 简单确认或信息提示 --> 请用 `SmallDialog`
+- 多步骤向导流程 --> 请用 `WizardDialog`
+- 全屏沉浸式操作 --> 请用 `ImmersiveDialog`
+- 删除确认场景 --> 请用 `DeleteDialog`（已封装删除确认样式和交互）
+- 操作被拒绝 / 不可执行的反馈 --> 请用 `RejectDialog`（支持 Single / All / Part / Custom 四种模式）
+
+## 基础用法
+
+```tsx
+import React from "react";
+import {
+  MediumDialog,
+  Button,
+  KitStoreProvider,
+  ModalStack,
+} from "@cloudtower/eagle";
+import { usePushModal } from "@cloudtower/eagle";
+
+const App = () => {
+  const pushModal = usePushModal();
+
+  const openDialog = () => {
+    pushModal({
+      component: () => (
+        <MediumDialog
+          title="编辑虚拟机"
+          onOk={(popModal) => {
+            console.log("保存配置");
+            popModal();
+          }}
+          onCancel={(popModal) => {
+            popModal();
+          }}
+        >
+          <form>
+            <label>虚拟机名称</label>
+            <input defaultValue="vm-prod-01" />
+            <label>CPU (核)</label>
+            <input type="number" defaultValue={4} />
+            <label>内存 (GB)</label>
+            <input type="number" defaultValue={8} />
+          </form>
+        </MediumDialog>
+      ),
+      props: {},
+    });
+  };
+
+  return (
+    <Button type="primary" onClick={openDialog}>
+      编辑虚拟机
+    </Button>
+  );
+};
+```
+
+## 常见模式
+
+### 模式一：表单提交弹窗
+
+适用于在弹窗中包含表单输入的场景。通过 `confirmLoading` 控制提交按钮加载状态，提交成功后再关闭弹窗。
+
+```tsx
+import React, { useState } from "react";
+import { MediumDialog, Button } from "@cloudtower/eagle";
+import { usePushModal } from "@cloudtower/eagle";
+
+const EditVmDialog: React.FC = () => {
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string>();
+
+  return (
+    <MediumDialog
+      title="编辑虚拟机"
+      confirmLoading={loading}
+      error={error}
+      onOk={async (popModal) => {
+        setLoading(true);
+        setError(undefined);
+        try {
+          await saveVmConfig({ name: "vm-prod-01", cpu: 4, memory: 8 });
+          popModal();
+        } catch (e) {
+          setError("保存配置失败，请重试");
+        } finally {
+          setLoading(false);
+        }
+      }}
+    >
+      <form>
+        <label>虚拟机名称</label>
+        <input defaultValue="vm-prod-01" />
+        <label>CPU (核)</label>
+        <input type="number" defaultValue={4} />
+        <label>内存 (GB)</label>
+        <input type="number" defaultValue={8} />
+      </form>
+    </MediumDialog>
+  );
+};
+
+// 使用方式
+const App = () => {
+  const pushModal = usePushModal();
+
+  return (
+    <Button
+      type="primary"
+      onClick={() =>
+        pushModal({ component: () => <EditVmDialog />, props: {} })
+      }
+    >
+      编辑虚拟机
+    </Button>
+  );
+};
+```
+
+### 模式二：数据展示弹窗
+
+适用于在弹窗中展示较多详情信息的场景。利用 `initializing`、`initializingError` 控制加载状态，加载完成后展示数据。
+
+```tsx
+import React, { useEffect, useMemo, useState } from "react";
+import { MediumDialog, Button } from "@cloudtower/eagle";
+import type { MediumDialogProps } from "@cloudtower/eagle";
+import { usePushModal } from "@cloudtower/eagle";
+
+const VmDetailDialog: React.FC = () => {
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string>();
+  const [data, setData] = useState<{
+    name: string;
+    cpu: number;
+    memory: number;
+    disks: string[];
+    nics: string[];
+  }>();
+
+  const fetchData = async () => {
+    setLoading(true);
+    setError(undefined);
+    try {
+      const result = await fetchVmDetail("vm-prod-01");
+      setData(result);
+    } catch (e) {
+      setError("加载虚拟机详情失败");
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    fetchData();
+  }, []);
+
+  const modalProps: Partial<MediumDialogProps> = useMemo(() => {
+    if (loading) {
+      return { title: "", initializing: true, initializingSkeletonRows: 5 };
+    }
+    if (error) {
+      return { title: "", initializingError: error, onOk: fetchData };
+    }
+    return { title: `虚拟机详情 - ${data?.name}` };
+  }, [loading, error, data]);
+
+  return (
+    <MediumDialog showOk={false} cancelText="关闭" {...modalProps}>
+      <p>虚拟机名称：{data?.name}</p>
+      <p>CPU：{data?.cpu} 核</p>
+      <p>内存：{data?.memory} GB</p>
+      <p>磁盘：{data?.disks?.join(", ")}</p>
+      <p>网卡：{data?.nics?.join(", ")}</p>
+    </MediumDialog>
+  );
+};
+
+// 使用方式
+const App = () => {
+  const pushModal = usePushModal();
+
+  return (
+    <Button
+      onClick={() =>
+        pushModal({ component: () => <VmDetailDialog />, props: {} })
+      }
+    >
+      查看虚拟机详情
+    </Button>
+  );
+};
+```
+
+### 模式三：全屏内容弹窗（isContentFull）
+
+适用于需要大面积展示内容（如表格、拓扑图、日志）的场景。开启 `isContentFull` 后弹窗尺寸变为 `width: calc(100vw - 160px)`、`height: calc(100vh - 80px)`，内容区域自动 flex 填充剩余高度。
+
+```tsx
+import React from "react";
+import { MediumDialog, Button } from "@cloudtower/eagle";
+import { usePushModal } from "@cloudtower/eagle";
+
+const App = () => {
+  const pushModal = usePushModal();
+
+  return (
+    <Button
+      onClick={() =>
+        pushModal({
+          component: () => (
+            <MediumDialog
+              title="虚拟机任务日志"
+              isContentFull
+              showOk={false}
+              cancelText="关闭"
+            >
+              <div style={{ flex: 1, overflow: "auto" }}>
+                <pre>
+                  {`[2024-01-15 10:00:01] 开始迁移虚拟机 vm-prod-01
+[2024-01-15 10:00:05] 正在同步内存页...
+[2024-01-15 10:01:30] 内存同步完成，开始切换
+[2024-01-15 10:01:32] 迁移完成，虚拟机已在目标主机上运行`}
+                </pre>
+              </div>
+            </MediumDialog>
+          ),
+          props: {},
+        })
+      }
+    >
+      查看任务日志
+    </Button>
+  );
+};
+```
+
+## 初始化生命周期
+
+MediumDialog 继承 SmallDialog 的 `initializeOnce`，默认为 `true`：成功前允许失败重试，首次成功后忽略后续的加载和初始化错误。需要反复展示骨架屏时，显式设置 `initializeOnce={false}`。完整约定见 [SmallDialog 初始化生命周期](../SmallDialog/guide.md#初始化生命周期)。
+
+## 与 SmallDialog 的差异对比
+
+| 特性           | SmallDialog        | MediumDialog             |
+| -------------- | ------------------ | ------------------------ |
+| 默认宽度       | 492px              | 720px                    |
+| 水平内边距     | 40px               | 60px                     |
+| 标题排版       | `d2_bold_title`    | `d1s_bold_title`         |
+| 骨架屏默认行数 | 2                  | 3                        |
+| 全屏模式       | 不支持             | 支持（`isContentFull`）  |
+| 适用场景       | 简单确认、信息提示 | 表单弹窗、内容较多的确认 |
+
+## 相关组件
+
+- `SmallDialog` -- 小尺寸对话框（492px），适用于简单确认和信息提示
+- `ImmersiveDialog` -- 全屏沉浸式对话框，适用于需要大量操作空间的场景
+- `WizardDialog` -- 向导式对话框，适用于多步骤流程
+- `DeleteDialog` -- 删除确认对话框，封装了删除场景的标准样式和交互（位于 `@cloudtower/eagle` 的 coreX 模块）
+- `RejectDialog` -- 操作拒绝反馈对话框，支持 Single（单条拒绝）、All（全部拒绝）、Part（部分拒绝）、Custom（自定义内容）四种模式（位于 `@cloudtower/eagle` 的 coreX 模块）

package/docs/core/SearchInput/guide.md

@@ -0,0 +1,125 @@
+# SearchInput
+
+## 简介
+
+搜索输入框组件，基于 Input 封装，提供防抖搜索、结果导航（上一个/下一个/计数器）和最近搜索历史功能。支持受控和非受控两种模式，宽度默认 276px。
+
+## 何时使用
+
+- 表格内搜索高亮匹配结果，需要上下翻页定位
+- 页面全局搜索，需要防抖避免频繁请求
+- 需要保留最近搜索记录的搜索场景
+
+不要使用：
+
+- 仅需要简单输入框 --> 请用 `Input`
+- 下拉选择过滤 --> 请用 `Select` 的搜索模式
+- 级联选择中的搜索 --> `Cascader` 已内置 SearchInput
+
+## 基础用法
+
+最简单的搜索框，仅响应输入变化并防抖处理：
+
+```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)}
+    />
+  );
+};
+```
+
+## 常见模式
+
+### 模式一：带结果导航
+
+适用于搜索后需要在匹配结果之间上下翻页的场景（如表格内搜索高亮）。同时提供 `onSearchNext` 和 `onSearchPrev` 后，输入框后缀会显示 "current/total" 计数器和上下翻页按钮。按 Enter 键等同于点击"下一个"。
+
+```tsx
+import React, { useState } from "react";
+import { SearchInput } from "@cloudtower/eagle";
+
+const VmTableSearch = () => {
+  const [matchedVms, setMatchedVms] = useState<string[]>([]);
+
+  return (
+    <SearchInput
+      total={matchedVms.length}
+      onChange={(value) => {
+        // 根据关键词过滤匹配的虚拟机列表
+        const matched = allVms.filter((vm) => vm.name.includes(value));
+        setMatchedVms(matched);
+      }}
+      onSearchNext={(value, current) => {
+        // 滚动到第 current 个匹配结果
+        scrollToVm(matchedVms[current - 1]);
+      }}
+      onSearchPrev={(value, current) => {
+        scrollToVm(matchedVms[current - 1]);
+      }}
+    />
+  );
+};
+```
+
+### 模式二：受控模式（外部控制当前索引）
+
+适用于需要从组件外部控制当前高亮索引的场景，例如同步多个搜索结果视图。通过 `current` prop 传入索引值，组件不再内部管理位置状态。
+
+```tsx
+import React, { useState } from "react";
+import { SearchInput, Button } from "@cloudtower/eagle";
+
+const App = () => {
+  const [value, setValue] = useState("");
+  const [current, setCurrent] = useState(1);
+  const total = 10;
+
+  return (
+    <div>
+      <SearchInput
+        value={value}
+        current={current}
+        total={total}
+        debounceWait={0}
+        onChange={(v) => setValue(v)}
+        onSearchNext={(v, nextCurrent) => setCurrent(nextCurrent)}
+        onSearchPrev={(v, prevCurrent) => setCurrent(prevCurrent)}
+      />
+      <Button onClick={() => setCurrent(1)}>回到第一个</Button>
+    </div>
+  );
+};
+```
+
+注意：使用受控模式（传入 `value`）时，需把 `debounceWait` 设置为 0，否则输入时会有卡顿。
+
+### 模式三：最近搜索历史
+
+启用 `enableRecentSearch` 后，搜索记录会通过 localStorage 持久化存储。聚焦空输入框时自动显示最近搜索记录的下拉菜单，点击记录项可直接填入搜索。不同业务场景应使用不同的 `recentSearchLocalStorageKey` 以隔离数据。
+
+```tsx
+import React from "react";
+import { SearchInput } from "@cloudtower/eagle";
+
+const App = () => (
+  <SearchInput
+    enableRecentSearch
+    recentSearchLocalStorageKey="host-search"
+    maxRecentCount={5}
+    onChange={(value) => console.log("搜索:", value)}
+  />
+);
+```
+
+## 相关组件
+
+- `Input`：基础输入框，SearchInput 基于它封装
+- `Cascader`：级联选择器，内置了 SearchInput 作为搜索区域

package/docs/core/SmallDialog/guide.md

@@ -0,0 +1,241 @@
+# SmallDialog
+
+## 简介
+
+SmallDialog 是一个固定 492px 宽度的轻量级对话框组件，适用于简单确认、信息提示和自定义轻量弹窗场景。通过 `usePushModal` / `popModal` 管理弹窗生命周期，内置初始化加载态、错误信息展示和骨架屏等能力。
+
+## 何时使用
+
+- 简单确认操作（如"确认关闭虚拟机？"）
+- 纯信息提示（隐藏确认按钮，仅展示关闭按钮）
+- 需要异步提交并展示加载状态的轻量弹窗
+- 需要初始化加载数据后再展示内容的弹窗
+
+不要使用：
+
+- 包含表单的场景 --> 请用 `MediumDialog`
+- 多步骤向导流程 --> 请用 `WizardDialog`
+- 全屏沉浸式操作 --> 请用 `ImmersiveDialog`
+- 删除确认场景 --> 请用 `DeleteDialog`（已封装删除确认样式和交互）
+- 操作被拒绝 / 不可执行的反馈 --> 请用 `RejectDialog`（支持 Single / All / Part / Custom 四种模式）
+
+## 基础用法
+
+```tsx
+import React from "react";
+import {
+  SmallDialog,
+  Button,
+  KitStoreProvider,
+  ModalStack,
+} from "@cloudtower/eagle";
+import { usePushModal } from "@cloudtower/eagle";
+
+const App = () => {
+  const pushModal = usePushModal();
+
+  const openDialog = () => {
+    pushModal({
+      component: () => (
+        <SmallDialog
+          title="关闭虚拟机"
+          onOk={(popModal) => {
+            console.log("确认关闭");
+            popModal();
+          }}
+          onCancel={(popModal) => {
+            popModal();
+          }}
+        >
+          <p>确定要关闭虚拟机 "vm-prod-01" 吗？</p>
+        </SmallDialog>
+      ),
+      props: {},
+    });
+  };
+
+  return (
+    <Button type="primary" onClick={openDialog}>
+      关闭虚拟机
+    </Button>
+  );
+};
+```
+
+## 初始化生命周期
+
+`initializeOnce` 默认为 `true`。当 `initializing` 为 false 或未传入，且 `initializingError` 无值时，弹窗记录首次初始化成功。之后忽略这两个属性的变化，后台刷新不会再显示骨架屏或初始化错误页，也不会因此卸载内容中的表单。
+
+- 成功前，加载失败仍展示初始化错误；点击重试可以再次进入骨架屏，多次失败重试也一样。
+- 首次渲染就没有加载和错误时，也会记录成功，例如直接使用缓存数据的场景。
+- 延迟启动请求时，应在准备期间保持 `initializing=true`，避免尚未请求就被视为成功。
+- 记录按组件的一次挂载周期计算。卸载后重新打开会重置；同一实例切换资源时，可通过 `key` 重新挂载。
+- 设置 `initializeOnce={false}` 可恢复完全受控行为，允许反复进入加载和错误状态。已有调用方若依赖此行为，需要显式关闭该选项。
+
+该选项仅处理 `initializing` 和 `initializingError`，不会冻结其他 props。后台刷新时应继续传入正常标题和内容；刷新错误可以在内容区域或通过 `error` 展示。
+
+## 常见模式
+
+### 模式一：异步提交弹窗
+
+适用于点击确认后需要执行异步操作（如 API 请求）的场景。通过 `confirmLoading` 控制按钮加载状态，操作完成后再关闭弹窗。
+
+```tsx
+import React, { useState } from "react";
+import { SmallDialog, Button } from "@cloudtower/eagle";
+import { usePushModal } from "@cloudtower/eagle";
+
+const ShutdownVmDialog: React.FC = () => {
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string>();
+
+  return (
+    <SmallDialog
+      title="关闭虚拟机"
+      confirmLoading={loading}
+      error={error}
+      onOk={async (popModal) => {
+        setLoading(true);
+        setError(undefined);
+        try {
+          await shutdownVm("vm-prod-01");
+          popModal();
+        } catch (e) {
+          setError("关闭虚拟机失败，请重试");
+        } finally {
+          setLoading(false);
+        }
+      }}
+    >
+      <p>确定要关闭虚拟机 "vm-prod-01" 吗？</p>
+      <p>关闭后该虚拟机上运行的所有服务将停止。</p>
+    </SmallDialog>
+  );
+};
+
+// 使用方式
+const App = () => {
+  const pushModal = usePushModal();
+
+  return (
+    <Button
+      type="primary"
+      onClick={() =>
+        pushModal({ component: () => <ShutdownVmDialog />, props: {} })
+      }
+    >
+      关闭虚拟机
+    </Button>
+  );
+};
+```
+
+### 模式二：初始化加载弹窗
+
+适用于弹窗打开后需要先请求数据再展示内容的场景。利用 `initializing`、`initializingError` 和 `initializingSkeletonRows` 三个属性组合控制加载、失败、成功三种状态。
+
+```tsx
+import React, { useEffect, useMemo, useState } from "react";
+import { SmallDialog, Button } from "@cloudtower/eagle";
+import type { SmallDialogProps } from "@cloudtower/eagle";
+import { usePushModal } from "@cloudtower/eagle";
+
+const HostDetailDialog: React.FC = () => {
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string>();
+  const [data, setData] = useState<{ name: string; ip: string }>();
+
+  const fetchData = async () => {
+    setLoading(true);
+    setError(undefined);
+    try {
+      const result = await fetchHostDetail("host-01");
+      setData(result);
+    } catch (e) {
+      setError("加载主机信息失败");
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    fetchData();
+  }, []);
+
+  const modalProps: SmallDialogProps = useMemo(() => {
+    if (loading) {
+      return { title: "", initializing: true, initializingSkeletonRows: 3 };
+    }
+    if (error) {
+      return { title: "", initializingError: error, onOk: fetchData };
+    }
+    return { title: `主机详情 - ${data?.name}` };
+  }, [loading, error, data]);
+
+  return (
+    <SmallDialog {...modalProps}>
+      <p>主机名称：{data?.name}</p>
+      <p>IP 地址：{data?.ip}</p>
+    </SmallDialog>
+  );
+};
+
+// 使用方式
+const App = () => {
+  const pushModal = usePushModal();
+
+  return (
+    <Button
+      onClick={() =>
+        pushModal({ component: () => <HostDetailDialog />, props: {} })
+      }
+    >
+      查看主机详情
+    </Button>
+  );
+};
+```
+
+### 模式三：自定义确认弹窗（纯信息提示）
+
+适用于仅需要展示信息，不需要用户做"确认/取消"选择的场景。通过 `showOk={false}` 隐藏确认按钮，将取消按钮文案改为"我知道了"。
+
+```tsx
+import React from "react";
+import { SmallDialog, Button } from "@cloudtower/eagle";
+import { usePushModal } from "@cloudtower/eagle";
+
+const App = () => {
+  const pushModal = usePushModal();
+
+  return (
+    <Button
+      onClick={() =>
+        pushModal({
+          component: () => (
+            <SmallDialog
+              title="集群升级完成"
+              showOk={false}
+              cancelText="我知道了"
+            >
+              <p>集群 "cluster-prod" 已成功升级到 v4.2.0。</p>
+              <p>所有节点均已完成滚动更新，当前运行状态正常。</p>
+            </SmallDialog>
+          ),
+          props: {},
+        })
+      }
+    >
+      查看升级结果
+    </Button>
+  );
+};
+```
+
+## 相关组件
+
+- `MediumDialog` — 中等尺寸对话框（720px），适用于包含表单输入的场景
+- `ImmersiveDialog` — 全屏沉浸式对话框，适用于需要大量操作空间的场景
+- `WizardDialog` — 向导式对话框，适用于多步骤流程
+- `DeleteDialog` — 删除确认对话框，封装了删除场景的标准样式和交互（位于 `@cloudtower/eagle` 的 coreX 模块）
+- `RejectDialog` — 操作拒绝反馈对话框，支持 Single（单条拒绝）、All（全部拒绝）、Part（部分拒绝）、Custom（自定义内容）四种模式（位于 `@cloudtower/eagle` 的 coreX 模块）