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

package/docs/core/Table/guide.md

@@ -0,0 +1,199 @@
+# Table
+
+## 简介
+
+Table 是基于 antd Table 二次封装的表格组件，提供统一的 CloudTower 表格样式。用于展示结构化数据列表，支持排序、行选择、展开行、加载状态、错误状态等功能。数据源要求每条记录包含 id 字段作为唯一标识。
+
+## 何时使用
+
+- 展示结构化的数据列表（如虚拟机列表、主机列表、集群列表）
+- 需要排序、筛选、分页等交互功能
+- 需要行选择（单选/多选）进行批量操作
+- 需要展开行显示详细信息
+
+不要使用：
+
+- 行内编辑场景 --> 请用 `TableForm`
+- 键值对信息展示 --> 请用 `SummaryTable`
+- 纯拖拽排序（不需要表格结构） --> 请用 `SortableList`
+
+## 基础用法
+
+```tsx
+import React from "react";
+import { Table } from "@cloudtower/eagle";
+
+interface VMData {
+  id: string;
+  name: string;
+  status: string;
+  cpu: number;
+  memory: number;
+}
+
+const columns = [
+  { key: "name", title: "名称", dataIndex: "name" },
+  { key: "status", title: "状态", dataIndex: "status" },
+  { key: "cpu", title: "CPU (核)", dataIndex: "cpu" },
+  { key: "memory", title: "内存 (MB)", dataIndex: "memory" },
+];
+
+const vms: VMData[] = [
+  {
+    id: "vm-001",
+    name: "web-server-01",
+    status: "running",
+    cpu: 4,
+    memory: 8192,
+  },
+  {
+    id: "vm-002",
+    name: "db-server-01",
+    status: "running",
+    cpu: 8,
+    memory: 16384,
+  },
+];
+
+const App = () => <Table<VMData> columns={columns} dataSource={vms} />;
+```
+
+## 常见模式
+
+### 模式一：行选择
+
+配合 `rowSelection` 实现行选择功能，常用于批量操作场景。
+
+```tsx
+import React, { useState } from "react";
+import { Table } from "@cloudtower/eagle";
+
+interface VMData {
+  id: string;
+  name: string;
+  status: string;
+}
+
+const App = () => {
+  const [selectedKeys, setSelectedKeys] = useState<string[]>([]);
+
+  return (
+    <Table<VMData>
+      columns={columns}
+      dataSource={vms}
+      rowSelection={{
+        selectedRowKeys: selectedKeys,
+        onChange: (keys) => setSelectedKeys(keys as string[]),
+      }}
+    />
+  );
+};
+```
+
+### 模式二：排序功能
+
+通过 `onSorterChange` 回调处理排序逻辑，列配置中设置 `sorter: true` 启用排序。
+
+```tsx
+import React from "react";
+import { Table } from "@cloudtower/eagle";
+
+const columns = [
+  { key: "name", title: "名称", dataIndex: "name", sorter: true },
+  { key: "cpu", title: "CPU", dataIndex: "cpu", sorter: true },
+];
+
+const App = () => {
+  const handleSorterChange = (order, key) => {
+    console.log("排序:", order, key);
+  };
+
+  return (
+    <Table<VMData>
+      columns={columns}
+      dataSource={vms}
+      onSorterChange={handleSorterChange}
+    />
+  );
+};
+```
+
+### 模式三：加载与错误状态
+
+通过 `loading` 显示骨架屏加载状态，通过 `error` 显示错误信息。
+
+```tsx
+import React from "react";
+import { Table } from "@cloudtower/eagle";
+
+const App = () => {
+  const { data, isLoading, isError } = useFetchVMs();
+
+  return (
+    <Table<VMData>
+      columns={columns}
+      dataSource={data}
+      loading={isLoading}
+      error={isError ? "加载失败，请重试" : undefined}
+    />
+  );
+};
+```
+
+### 模式四：可展开行
+
+通过 `expandable` 配置展开行内容，适用于显示详细信息。
+
+```tsx
+import React from "react";
+import { Table } from "@cloudtower/eagle";
+
+const App = () => (
+  <Table<VMData>
+    columns={columns}
+    dataSource={vms}
+    expandable={{
+      expandedRowRender: (record) => (
+        <div>
+          <p>ID: {record.id}</p>
+          <p>详细信息: ...</p>
+        </div>
+      ),
+      rowExpandable: (record) => record.status === "running",
+    }}
+  />
+);
+```
+
+### 模式五：行操作菜单
+
+在列配置中添加操作列，渲染操作按钮或菜单。
+
+```tsx
+import React from "react";
+import { Table, Button, Icon } from "@cloudtower/eagle";
+import { MoreEllipsis316BoldBlueIcon } from "@cloudtower/icons-react";
+
+const columns = [
+  { key: "name", title: "名称", dataIndex: "name" },
+  {
+    key: "action",
+    title: "操作",
+    render: (_, record) => (
+      <Button
+        size="small"
+        type="tertiary"
+        prefixIcon={<Icon src={MoreEllipsis316BoldBlueIcon} />}
+        onClick={() => console.log("操作:", record)}
+      />
+    ),
+  },
+];
+```
+
+## 相关组件
+
+- `TableForm`: 表格表单，用于行内编辑场景
+- `SummaryTable`: 摘要表格，用于键值对信息展示
+- `BatchOperation`: 批量操作工具栏，配合行选择使用
+- `Pagination`: 分页器，用于分页控制

package/docs/core/TableForm/guide.md

@@ -0,0 +1,195 @@
+# TableForm
+
+## 简介
+
+TableForm 是行内编辑的表格表单组件，适用于批量数据录入场景。支持多种内置列类型（text/input/password/checkbox/affix）和自定义列渲染，表头批量填充、行的增删和拖拽排序、三种校验触发模式（Normal/Aggressive/Lazy），以及通过 `errors` 属性注入外部错误信息。通过 `useRef<TableFormHandle>` 可命令式操作数据和校验。
+
+## 何时使用
+
+- 需要批量录入结构化数据（如添加多台主机、配置多个网络接口）
+- 每行数据结构相同，需要行内直接编辑
+- 需要表头批量填充功能（一次输入应用到所有行）
+- 需要行级别的增删和拖拽排序
+
+不要使用：
+
+- 只有单行数据录入 --> 请用 `Form`
+- 纯展示型表格（不需要编辑） --> 请用 `Table`
+- 仅需拖拽排序（不需要编辑） --> 请用 `SortableList`
+
+## 基础用法
+
+```tsx
+import React, { useRef } from "react";
+import { TableForm } from "@cloudtower/eagle";
+import type { TableFormColumn, TableFormHandle } from "@cloudtower/eagle";
+
+const columns: TableFormColumn[] = [
+  { key: "name", title: "主机名", type: "input", autoIncrease: true },
+  {
+    key: "ip",
+    title: "管理 IP",
+    type: "input",
+    validator: ({ value }) => (!value ? "IP 不能为空" : undefined),
+  },
+  { key: "password", title: "密码", type: "password" },
+];
+
+const App = () => {
+  const ref = useRef<TableFormHandle>(null);
+
+  return (
+    <TableForm
+      ref={ref}
+      columns={columns}
+      defaultData={[
+        { name: "host0", ip: "", password: "" },
+        { name: "host1", ip: "", password: "" },
+      ]}
+      rowAddConfig={{ addible: true, maximum: 10 }}
+      row={{ deletable: true }}
+      onBodyChange={(data) => console.log("数据变更:", data)}
+    />
+  );
+};
+```
+
+## 常见模式
+
+### 模式一：批量填充 + 自动递增
+
+适用于需要快速填入相似数据的场景。表头输入框的值会批量应用到所有行，配合 `autoIncrease` 可以自动递增末尾数字。
+
+```tsx
+import React from "react";
+import { TableForm } from "@cloudtower/eagle";
+import type { TableFormColumn } from "@cloudtower/eagle";
+
+const columns: TableFormColumn[] = [
+  {
+    key: "hostname",
+    title: "主机名",
+    type: "input",
+    autoIncrease: true,
+    defaultValue: "host0",
+  },
+  { key: "ip", title: "管理 IP", type: "input" },
+  { key: "enabled", title: "启用", type: "checkbox", align: "center" },
+];
+
+const App = () => (
+  <TableForm
+    columns={columns}
+    defaultData={[
+      { hostname: "host0", ip: "10.0.0.1", enabled: true },
+      { hostname: "host1", ip: "10.0.0.2", enabled: true },
+      { hostname: "host2", ip: "10.0.0.3", enabled: false },
+    ]}
+    onHeaderChange={(data, columnKey) =>
+      console.log("批量填充:", columnKey, data)
+    }
+  />
+);
+```
+
+### 模式二：自定义列渲染
+
+适用于内置列类型无法满足需求的场景。通过 `render` 函数可以渲染任意组件（如 Select、DatePicker 等）。
+
+```tsx
+import React from "react";
+import { TableForm, Select } from "@cloudtower/eagle";
+import type { TableFormColumn } from "@cloudtower/eagle";
+
+const columns: TableFormColumn[] = [
+  { key: "name", title: "名称", type: "input" },
+  {
+    key: "role",
+    title: "角色",
+    defaultValue: "worker",
+    render({ isHeader, value, onChange, placeholder }) {
+      return (
+        <Select
+          size="small"
+          value={value as string}
+          onChange={onChange}
+          placeholder={isHeader ? "批量选择" : "请选择"}
+          options={[
+            { label: "Master", value: "master" },
+            { label: "Worker", value: "worker" },
+          ]}
+        />
+      );
+    },
+    validator({ value }) {
+      if (!value) return "请选择角色";
+    },
+  },
+];
+
+const App = () => (
+  <TableForm
+    columns={columns}
+    defaultData={[{ name: "", role: "worker" }]}
+    rowAddConfig={{ addible: true }}
+    row={{ deletable: true }}
+  />
+);
+```
+
+### 模式三：行配置 + 外部错误注入
+
+适用于校验逻辑在外部（如服务端返回错误）的场景。通过 `row` 统一配置行行为，通过 `errors` 注入外部错误信息。
+
+```tsx
+import React, { useState } from "react";
+import { TableForm } from "@cloudtower/eagle";
+import type { TableFormColumn, TableFormErrorsType } from "@cloudtower/eagle";
+
+const columns: TableFormColumn[] = [
+  { key: "name", title: "名称", type: "input" },
+  { key: "value", title: "值", type: "input" },
+];
+
+const App = () => {
+  const [errors, setErrors] = useState<TableFormErrorsType>([null]);
+
+  return (
+    <TableForm
+      columns={columns}
+      defaultData={[{ name: "key1", value: "" }]}
+      row={{
+        deletable: true,
+        draggable: true,
+        splitType: "zebraMarking",
+        validator: (rowIndex, rowData) =>
+          !rowData.name ? "名称不能为空" : undefined,
+      }}
+      errors={errors}
+      onBodyChange={(data) => {
+        // 模拟服务端校验
+        const newErrors = data.map((row) =>
+          row.value === "error" ? { value: "该值不合法" } : null,
+        );
+        setErrors(newErrors);
+      }}
+    />
+  );
+};
+```
+
+## 废弃说明
+
+以下属性已废弃，请迁移至 `row` 配置：
+
+- `draggable` --> `row.draggable`
+- `deleteConfig` --> `row.deletable` + `row.disableActions`
+- `rowSplitType` --> `row.splitType`
+- `renderRowDescription` --> `row.customizedDescription`
+- `rowValidator` --> `row.validator`
+
+## 相关组件
+
+- `Form`: 标准表单容器，适用于非表格化的表单场景
+- `Table`: 数据展示表格，适用于只读场景
+- `SortableList`: 可拖拽排序列表，适用于纯排序（无编辑）场景

package/docs/core/WizardDialog/guide.md

@@ -0,0 +1,320 @@
+# 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>
+  );
+};
+```
+
+## 关键说明
+
+- **暂时禁用关闭**：继承 `closeDisabled`（默认 `false`），为 `true` 时保留灰色关闭按钮并阻止 Escape、遮罩关闭；`closable=false` 仍隐藏按钮。Footer 取消及步骤导航需独立控制。完整约定见 [ImmersiveDialog 暂时禁用关闭](../ImmersiveDialog/guide.md#暂时禁用关闭)。
+- **首次初始化**：继承 ImmersiveDialog 的 `initializeOnce`，默认为 `true`。成功前允许失败重试，首次成功后忽略后续的加载和初始化错误，避免刷新时卸载步骤内容。设为 false 可恢复完全受控行为；仅切换 `visible` 不重置记录。完整约定见 [ImmersiveDialog 初始化生命周期](../ImmersiveDialog/guide.md#初始化生命周期)。
+- **按钮文案自动切换**：非最后一步时，确认按钮文案自动显示为 `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 内部使用的步骤指示器