antd-overlay 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # antd-overlay
 
-Ant Design Modal/Drawer 命令式调用方案。
+Ant Design Modal/Drawer/Tour 命令式调用方案。
 
 [![npm version](https://img.shields.io/npm/v/antd-overlay.svg)](https://www.npmjs.com/package/antd-overlay)
 [![license](https://img.shields.io/npm/l/antd-overlay.svg)](https://github.com/RaineySpace/antd-overlay/blob/main/LICENSE)
@@ -8,7 +8,7 @@ Ant Design Modal/Drawer 命令式调用方案。
 ## 特性
 
 - 🚀 **命令式调用** - 通过函数调用打开/关闭覆盖层，无需在业务里维护 `open` 状态
-- 🎨 **动画支持** - 正确处理打开/关闭动画（Modal 使用 `afterClose`，Drawer 使用 `afterOpenChange`），避免动画未完成就卸载
+- 🎨 **动画支持** - 正确处理打开/关闭动画（Modal 使用 `afterClose`，Drawer 使用 `afterOpenChange`；Tour 默认直接卸载）
 - 🌍 **全局挂载** - 支持跨组件调用，覆盖层挂载到 `AntdOverlayProvider` 统一容器
 - 📦 **类型安全** - 完整的 TypeScript 类型支持
 - 🔧 **灵活扩展** - `useOverlay` + `propsAdapter` 可对接自定义覆盖层组件
@@ -38,7 +38,7 @@ yarn add antd-overlay
 
 ```bash
 pnpm install
-pnpm dev:demo    # 启动 Vite 演示（demo/：Modal / Drawer / useOverlay）
+pnpm dev:demo    # 启动 Vite 演示（demo/：Modal / Drawer / Tour / useOverlay）
 pnpm build       # 使用 tsup 构建 dist
 pnpm typecheck   # TypeScript 检查
 ```
@@ -137,7 +137,7 @@ function GlobalUsage() {
 
 `openModal(...)` 返回 `OverlayController`：可调用 `update` 传入要更新的字段（与当前已保存的 props 及 Hook 的 `defaultProps` **浅合并**，同名键以本次 `update` 入参为准）、`close` 关闭（会尊重动画配置）。
 
-`customOk` 关闭语义（适用于 `useOverlay` / `useModal` / `useDrawer`）：
+`customOk` 关闭语义（适用于 `useOverlay` / `useModal` / `useDrawer` / `useTour`）：
 
 - 同步回调正常返回：自动关闭覆盖层
 - 异步回调 `Promise resolve`：在 Promise 完成后自动关闭覆盖层
@@ -152,7 +152,7 @@ function GlobalUsage() {
 - `docs/ai/api-manifest.json`：机器可读 API 清单
 - `docs/ai/contracts.json`：能力、约束、错误语义和推荐模板
 
-若 AI 生成的是全局 Hook（`useGlobalModal`、`useGlobalDrawer`、`useGlobalOverlay`）用法，务必同时生成 `AntdOverlayProvider` 包裹代码。
+若 AI 生成的是全局 Hook（`useGlobalModal`、`useGlobalDrawer`、`useGlobalTour`、`useGlobalOverlay`）用法，务必同时生成 `AntdOverlayProvider` 包裹代码。
 
 ## API
 
@@ -167,11 +167,13 @@ function GlobalUsage() {
 - `children: React.ReactNode`
 - `defaultModalProps?: Partial<ModalProps>` — 默认 Modal 属性，与每次 `open` / `update` 传入的 props 合并（传入方优先）
 - `defaultDrawerProps?: Partial<DrawerProps>` — 同上，作用于 Drawer
+- `defaultTourProps?: Partial<TourProps>` — 同上，作用于 Tour
 
 ```tsx
 <AntdOverlayProvider
   defaultModalProps={{ centered: true, maskClosable: false }}
   defaultDrawerProps={{ width: 600 }}
+  defaultTourProps={{ mask: true }}
 >
   <App />
 </AntdOverlayProvider>
@@ -179,7 +181,7 @@ function GlobalUsage() {
 
 #### `useAntdOverlayContext()`
 
-读取 Context（含 `holders`、`addHolder`、`removeHolder` 及默认 Modal/Drawer 配置）。**必须在 `AntdOverlayProvider` 内使用**；一般供扩展或库内集成，业务侧很少直接使用。
+读取 Context（含 `holders`、`addHolder`、`removeHolder` 及默认 Modal/Drawer/Tour 配置）。**必须在 `AntdOverlayProvider` 内使用**；一般供扩展或库内集成，业务侧很少直接使用。
 
 ### Modal Hooks
 
@@ -220,6 +222,58 @@ export const {
 
 生成 `{ useDrawer, useGlobalDrawer }`。
 
+### Tour Hooks
+
+#### `useTour<T>(Component, options?)` / `useGlobalTour<T>(Component, options?)`
+
+语义与 Modal / Drawer 侧相同，选项类型为 `UseTourOptions<T>`（`T` 由 Tour 组件推断；同样支持 `animation`、`defaultProps`、顶层 Tour 属性及组件自定义扩展字段）。
+
+Tour 没有类似 Modal `afterClose` 或 Drawer `afterOpenChange` 的关闭动画完成回调，因此 `useTour` / `useGlobalTour` 默认使用 `animation: false`，关闭时直接卸载；如调用方显式传入 `animation`，会尊重传入值。
+
+```tsx
+import { Tour } from 'antd';
+import { CustomTourProps, useTour } from 'antd-overlay';
+
+const GuideTour: React.FC<CustomTourProps> = ({ customClose, customOk, ...props }) => {
+  void customClose;
+  void customOk;
+  return <Tour {...props} />;
+};
+
+function Page() {
+  const targetRef = React.useRef<HTMLButtonElement>(null);
+  const [openTour, holder] = useTour(GuideTour, {
+    mask: true,
+  });
+
+  return (
+    <>
+      <button
+        ref={targetRef}
+        onClick={() =>
+          openTour({
+            steps: [
+              {
+                title: '第一步',
+                description: '这里是引导内容',
+                target: () => targetRef.current,
+              },
+            ],
+          })
+        }
+      >
+        打开 Tour
+      </button>
+      {holder}
+    </>
+  );
+}
+```
+
+#### `generateUseTourHook<T>(Component)`
+
+生成 `{ useTour, useGlobalTour }`。
+
 ### 通用 Overlay Hooks
 
 #### `useOverlay<T>(Component, options?)`
@@ -247,6 +301,77 @@ const [openOverlay, holder] = useOverlay(MyOverlay, {
 
 生成绑定组件的 `useOverlay` / `useGlobalOverlay`；调用时可再传 `options` 与 `defaultOptions` 浅合并。
 
+### Promise Hooks
+
+如果业务流程希望在调用处直接 `await` 用户的确认结果，使用 Promise 版本：
+
+- `usePromiseOverlay<T>(Component, options?) => [openPromise, holder]`
+- `useGlobalPromiseOverlay<T>(Component, options?) => openPromise`
+- `generateUsePromiseOverlayHook<T>(Component, defaultOptions?) => { usePromiseOverlay, useGlobalPromiseOverlay }`
+- `usePromiseModal<T>(Component, options?) => [openPromise, holder]`
+- `useGlobalPromiseModal<T>(Component, options?) => openPromise`
+- `generateUsePromiseModalHook<T>(Component) => { usePromiseModal, useGlobalPromiseModal }`
+- `usePromiseDrawer<T>(Component, options?) => [openPromise, holder]`
+- `useGlobalPromiseDrawer<T>(Component, options?) => openPromise`
+- `generateUsePromiseDrawerHook<T>(Component) => { usePromiseDrawer, useGlobalPromiseDrawer }`
+
+`openPromise(initialize?)` 返回 `Promise<V | undefined>`，`V` 由组件 `CustomOverlayProps<V>` 的 `customOk` 入参类型推断。
+
+**行为契约：**
+
+| 场景 | 外层 Promise | 覆盖层 |
+| --- | --- | --- |
+| `customOk(value)` 同步成功 | `resolve(value)` —— 入参，非 customOk 返回值 | 自动关闭 |
+| `customOk(value)` 异步 resolve | resolve 后 `resolve(value)` | 自动关闭 |
+| `customOk` 同步抛错 / 异步 reject | `reject(error)`，错误透传给 `await` 调用方 | **保持打开** |
+| `customClose` / antd 取消按钮 / 蒙层 / esc | `resolve(undefined)` | 自动关闭 |
+| 同一 hook 实例再次 `openPromise` | 前一个 Promise 立即 `resolve(undefined)` | 旧覆盖层被新一次打开覆盖 |
+| 调用 `usePromise*` 的组件卸载 | `resolve(undefined)` | — |
+
+Promise 仅结算一次（幂等）；解析时机为决策时刻，**不等待关闭动画**。
+
+```tsx
+import { usePromiseModal, CustomModalProps } from 'antd-overlay';
+import { Modal } from 'antd';
+
+interface ConfirmModalProps extends CustomModalProps<{ value: string }> {
+  initialValue?: string;
+}
+
+const ConfirmModal: React.FC<ConfirmModalProps> = ({
+  open,
+  customClose,
+  customOk,
+  initialValue = '',
+}) => {
+  const [value, setValue] = React.useState(initialValue);
+  return (
+    <Modal open={open} onCancel={customClose} onOk={() => customOk?.({ value })}>
+      <input value={value} onChange={(e) => setValue(e.target.value)} />
+    </Modal>
+  );
+};
+
+function Page() {
+  const [openConfirm, holder] = usePromiseModal(ConfirmModal);
+
+  const handleClick = async () => {
+    const result = await openConfirm({ initialValue: 'hello' });
+    if (result === undefined) return; // 用户取消 / 关闭
+    console.log(result.value);
+  };
+
+  return (
+    <>
+      <button onClick={handleClick}>Open</button>
+      {holder}
+    </>
+  );
+}
+```
+
+如需在 `customOk` 中做异步校验：抛错 / reject 即可让 `await` 进入 `catch`，覆盖层会保持打开供用户修改后重新提交。
+
 ### 类型定义
 
 #### `CustomOverlayProps<T, R>`
@@ -261,9 +386,9 @@ interface CustomOverlayProps<T = any, R = void> {
 
 如需本地验证异步行为，可运行 demo 中的 `AsyncCustomOkDemo`（包含 Overlay / Modal / Drawer 的异步成功与失败场景）。
 
-#### `CustomModalProps<T, R>` / `CustomDrawerProps<T, R>`
+#### `CustomModalProps<T, R>` / `CustomDrawerProps<T, R>` / `CustomTourProps<T, R>`
 
-分别为 `ModalProps` / `DrawerProps` 与 `CustomOverlayProps` 的交叉类型。
+分别为 `ModalProps` / `DrawerProps` / `TourProps` 与 `CustomOverlayProps` 的交叉类型。
 
 #### `InternalOverlayProps<T>`
 
@@ -456,7 +581,7 @@ function ProgressModal() {
 
 ```
 ┌─────────────────────────────────────────────────────────┐
-│                    useModal / useDrawer                 │  业务层封装
+│               useModal / useDrawer / useTour            │  业务层封装
 ├─────────────────────────────────────────────────────────┤
 │              useOverlay / useGlobalOverlay              │  核心逻辑层
 ├─────────────────────────────────────────────────────────┤

package/dist/index.cjs

@@ -12,7 +12,8 @@ var AntdOverlayContext = React2.createContext(null);
 function AntdOverlayProvider({
   children,
   defaultModalProps,
-  defaultDrawerProps
+  defaultDrawerProps,
+  defaultTourProps
 }) {
   const [holders, setHolders] = React2.useState([]);
   const addHolder = React2.useCallback((holder) => {
@@ -22,8 +23,15 @@ function AntdOverlayProvider({
     setHolders((prev) => prev.filter((h) => h !== holder));
   }, []);
   const value = React2.useMemo(
-    () => ({ holders, addHolder, removeHolder, defaultModalProps, defaultDrawerProps }),
-    [holders, addHolder, removeHolder, defaultModalProps, defaultDrawerProps]
+    () => ({
+      holders,
+      addHolder,
+      removeHolder,
+      defaultModalProps,
+      defaultDrawerProps,
+      defaultTourProps
+    }),
+    [holders, addHolder, removeHolder, defaultModalProps, defaultDrawerProps, defaultTourProps]
   );
   return /* @__PURE__ */ jsxRuntime.jsxs(AntdOverlayContext.Provider, { value, children: [
     children,
@@ -266,17 +274,275 @@ function generateUseDrawerHook(DrawerComponent) {
     useGlobalDrawer: (options) => useGlobalDrawer(DrawerComponent, options)
   };
 }
+var createTourPropsAdapter = (defaultProps) => {
+  return (props, state) => {
+    const result = {
+      ...defaultProps,
+      ...props,
+      open: state.open,
+      customClose: state.onClose,
+      onClose: (current) => {
+        props?.onClose?.(current);
+        state.onClose();
+      }
+    };
+    if (result.customOk) {
+      result.customOk = wrapCustomOk(result.customOk, state.onClose);
+    }
+    return result;
+  };
+};
+function useTour(TourComponent, options) {
+  const context = useAntdOverlayContext();
+  const propsAdapter = React2.useMemo(
+    () => createTourPropsAdapter(context?.defaultTourProps),
+    [context?.defaultTourProps]
+  );
+  return useOverlay(TourComponent, {
+    animation: false,
+    ...options,
+    keyPrefix: "use-tour",
+    propsAdapter
+  });
+}
+function useGlobalTour(TourComponent, options) {
+  const context = useAntdOverlayContext();
+  const propsAdapter = React2.useMemo(
+    () => createTourPropsAdapter(context?.defaultTourProps),
+    [context?.defaultTourProps]
+  );
+  return useGlobalOverlay(TourComponent, {
+    animation: false,
+    ...options,
+    keyPrefix: "use-tour",
+    propsAdapter
+  });
+}
+function generateUseTourHook(TourComponent) {
+  return {
+    useTour: (options) => useTour(TourComponent, options),
+    useGlobalTour: (options) => useGlobalTour(TourComponent, options)
+  };
+}
+var createSettler = (rawResolve, rawReject) => {
+  let settled = false;
+  return {
+    resolve: (value) => {
+      if (settled) return;
+      settled = true;
+      rawResolve(value);
+    },
+    reject: (err) => {
+      if (settled) return;
+      settled = true;
+      rawReject(err);
+    }
+  };
+};
+var passthroughAdapter = (props, state) => {
+  const result = {
+    ...props,
+    open: state.open,
+    customClose: state.onClose
+  };
+  if (result.customOk) {
+    result.customOk = wrapCustomOk(result.customOk, state.onClose);
+  }
+  return result;
+};
+var withPromiseAdapter = (innerAdapter, settleRef) => {
+  return (props, state) => {
+    const inner = innerAdapter(props, state);
+    const innerCustomOk = inner.customOk;
+    const innerCustomClose = inner.customClose;
+    return {
+      ...inner,
+      customOk: ((value) => {
+        if (innerCustomOk) {
+          try {
+            const result = innerCustomOk(value);
+            if (result instanceof Promise) {
+              return result.then(
+                (resolved) => {
+                  settleRef.current?.resolve(value);
+                  return resolved;
+                },
+                (err) => {
+                  settleRef.current?.reject(err);
+                  throw err;
+                }
+              );
+            }
+            settleRef.current?.resolve(value);
+            return result;
+          } catch (err) {
+            settleRef.current?.reject(err);
+            throw err;
+          }
+        }
+        settleRef.current?.resolve(value);
+        state.onClose();
+        return void 0;
+      }),
+      customClose: () => {
+        settleRef.current?.resolve(void 0);
+        innerCustomClose();
+      }
+    };
+  };
+};
+var makePromiseOpener = (openOverlay, settleRef) => {
+  return (initialize) => {
+    settleRef.current?.resolve(void 0);
+    let rawResolve = () => void 0;
+    let rawReject = () => void 0;
+    const promise = new Promise((resolve, reject) => {
+      rawResolve = resolve;
+      rawReject = reject;
+    });
+    settleRef.current = createSettler(rawResolve, rawReject);
+    openOverlay(initialize);
+    return promise;
+  };
+};
+function usePromiseOverlay(OverlayComponent, options = {}) {
+  const settleRef = React2.useRef(null);
+  const { propsAdapter: userAdapter, ...rest } = options;
+  const wrappedAdapter = React2.useMemo(
+    () => withPromiseAdapter(
+      userAdapter ?? passthroughAdapter,
+      settleRef
+    ),
+    [userAdapter]
+  );
+  const [openOverlay, holder] = useOverlay(OverlayComponent, {
+    ...rest,
+    propsAdapter: wrappedAdapter
+  });
+  React2.useEffect(() => {
+    return () => {
+      settleRef.current?.resolve(void 0);
+    };
+  }, []);
+  const openPromise = React2.useMemo(() => makePromiseOpener(openOverlay, settleRef), [openOverlay]);
+  return [openPromise, holder];
+}
+function useGlobalPromiseOverlay(OverlayComponent, options = {}) {
+  const settleRef = React2.useRef(null);
+  const { propsAdapter: userAdapter, ...rest } = options;
+  const wrappedAdapter = React2.useMemo(
+    () => withPromiseAdapter(
+      userAdapter ?? passthroughAdapter,
+      settleRef
+    ),
+    [userAdapter]
+  );
+  const openOverlay = useGlobalOverlay(OverlayComponent, {
+    ...rest,
+    propsAdapter: wrappedAdapter
+  });
+  React2.useEffect(() => {
+    return () => {
+      settleRef.current?.resolve(void 0);
+    };
+  }, []);
+  return React2.useMemo(() => makePromiseOpener(openOverlay, settleRef), [openOverlay]);
+}
+function generateUsePromiseOverlayHook(OverlayComponent, defaultOptions) {
+  return {
+    usePromiseOverlay: (options) => usePromiseOverlay(OverlayComponent, {
+      ...defaultOptions,
+      ...options
+    }),
+    useGlobalPromiseOverlay: (options) => useGlobalPromiseOverlay(OverlayComponent, {
+      ...defaultOptions,
+      ...options
+    })
+  };
+}
+function usePromiseModal(ModalComponent, options) {
+  const context = useAntdOverlayContext();
+  const propsAdapter = React2.useMemo(
+    () => createModalPropsAdapter(context?.defaultModalProps),
+    [context?.defaultModalProps]
+  );
+  return usePromiseOverlay(ModalComponent, {
+    ...options,
+    keyPrefix: "use-modal",
+    propsAdapter
+  });
+}
+function useGlobalPromiseModal(ModalComponent, options) {
+  const context = useAntdOverlayContext();
+  const propsAdapter = React2.useMemo(
+    () => createModalPropsAdapter(context?.defaultModalProps),
+    [context?.defaultModalProps]
+  );
+  return useGlobalPromiseOverlay(ModalComponent, {
+    ...options,
+    keyPrefix: "use-modal",
+    propsAdapter
+  });
+}
+function generateUsePromiseModalHook(ModalComponent) {
+  return {
+    usePromiseModal: (options) => usePromiseModal(ModalComponent, options),
+    useGlobalPromiseModal: (options) => useGlobalPromiseModal(ModalComponent, options)
+  };
+}
+function usePromiseDrawer(DrawerComponent, options) {
+  const context = useAntdOverlayContext();
+  const propsAdapter = React2.useMemo(
+    () => createDrawerPropsAdapter(context?.defaultDrawerProps),
+    [context?.defaultDrawerProps]
+  );
+  return usePromiseOverlay(DrawerComponent, {
+    ...options,
+    keyPrefix: "use-drawer",
+    propsAdapter
+  });
+}
+function useGlobalPromiseDrawer(DrawerComponent, options) {
+  const context = useAntdOverlayContext();
+  const propsAdapter = React2.useMemo(
+    () => createDrawerPropsAdapter(context?.defaultDrawerProps),
+    [context?.defaultDrawerProps]
+  );
+  return useGlobalPromiseOverlay(DrawerComponent, {
+    ...options,
+    keyPrefix: "use-drawer",
+    propsAdapter
+  });
+}
+function generateUsePromiseDrawerHook(DrawerComponent) {
+  return {
+    usePromiseDrawer: (options) => usePromiseDrawer(DrawerComponent, options),
+    useGlobalPromiseDrawer: (options) => useGlobalPromiseDrawer(DrawerComponent, options)
+  };
+}
 
 exports.AntdOverlayProvider = AntdOverlayProvider;
 exports.generateUseDrawerHook = generateUseDrawerHook;
 exports.generateUseModalHook = generateUseModalHook;
 exports.generateUseOverlayHook = generateUseOverlayHook;
+exports.generateUsePromiseDrawerHook = generateUsePromiseDrawerHook;
+exports.generateUsePromiseModalHook = generateUsePromiseModalHook;
+exports.generateUsePromiseOverlayHook = generateUsePromiseOverlayHook;
+exports.generateUseTourHook = generateUseTourHook;
 exports.useAntdOverlayContext = useAntdOverlayContext;
 exports.useDrawer = useDrawer;
 exports.useGlobalDrawer = useGlobalDrawer;
 exports.useGlobalModal = useGlobalModal;
 exports.useGlobalOverlay = useGlobalOverlay;
+exports.useGlobalPromiseDrawer = useGlobalPromiseDrawer;
+exports.useGlobalPromiseModal = useGlobalPromiseModal;
+exports.useGlobalPromiseOverlay = useGlobalPromiseOverlay;
+exports.useGlobalTour = useGlobalTour;
 exports.useModal = useModal;
 exports.useOverlay = useOverlay;
+exports.usePromiseDrawer = usePromiseDrawer;
+exports.usePromiseModal = usePromiseModal;
+exports.usePromiseOverlay = usePromiseOverlay;
+exports.useTour = useTour;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map