antd-overlay 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,10 +1,11 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ModalProps, DrawerProps } from 'antd';
+import { ModalProps, DrawerProps, TourProps } from 'antd';
 import * as React$1 from 'react';
 import React__default from 'react';
 
 type DefaultModalProps = Partial<ModalProps>;
 type DefaultDrawerProps = Partial<DrawerProps>;
+type DefaultTourProps = Partial<TourProps>;
 /**
  * AntdOverlay Context 的值类型
  *
@@ -23,12 +24,14 @@ interface AntdOverlayContextValue {
     defaultModalProps?: DefaultModalProps;
     /** 默认 Drawer 属性 */
     defaultDrawerProps?: DefaultDrawerProps;
+    /** 默认 Tour 属性 */
+    defaultTourProps?: DefaultTourProps;
 }
 /**
  * AntdOverlay 容器提供者组件
  *
  * 用于管理全局覆盖层的挂载点。所有通过 useGlobalOverlay、useGlobalModal、
- * useGlobalDrawer 等 Hook 创建的覆盖层都会被挂载到这个 Provider 下。
+ * useGlobalDrawer、useGlobalTour 等 Hook 创建的覆盖层都会被挂载到这个 Provider 下。
  *
  * 渲染结构：
  * ```
@@ -73,15 +76,18 @@ interface AntdOverlayProviderProps {
     defaultModalProps?: DefaultModalProps;
     /** 默认 Drawer 属性 */
     defaultDrawerProps?: DefaultDrawerProps;
+    /** 默认 Tour 属性 */
+    defaultTourProps?: DefaultTourProps;
 }
 /**
  * AntdOverlayProvider 组件
  * @param children - 子节点
  * @param defaultModalProps - 默认 Modal 属性
  * @param defaultDrawerProps - 默认 Drawer 属性
+ * @param defaultTourProps - 默认 Tour 属性
  * @returns React.ReactNode
  */
-declare function AntdOverlayProvider({ children, defaultModalProps, defaultDrawerProps, }: AntdOverlayProviderProps): react_jsx_runtime.JSX.Element;
+declare function AntdOverlayProvider({ children, defaultModalProps, defaultDrawerProps, defaultTourProps, }: AntdOverlayProviderProps): react_jsx_runtime.JSX.Element;
 /**
  * 获取 AntdOverlay Context 的 Hook
  *
@@ -678,4 +684,157 @@ declare function generateUseDrawerHook<T extends CustomDrawerProps>(DrawerCompon
     useGlobalDrawer: (options?: UseDrawerOptions<T>) => OverlayOpener<T>;
 };
 
-export { AntdOverlayProvider, type AntdOverlayProviderProps, type CustomDrawerProps, type CustomModalProps, type CustomOverlayProps, type DefaultDrawerProps, type DefaultModalProps, type InternalOverlayProps, type OverlayController, type OverlayOpener, type UseDrawerOptions, type UseModalOptions, type UseOverlayOptions, generateUseDrawerHook, generateUseModalHook, generateUseOverlayHook, useAntdOverlayContext, useDrawer, useGlobalDrawer, useGlobalModal, useGlobalOverlay, useModal, useOverlay };
+/**
+ * 自定义 Tour 组件的属性接口
+ * 继承 Ant Design TourProps 并添加自定义属性
+ *
+ * @template T - customOk 回调的参数类型
+ * @template R - customOk 回调的返回类型
+ */
+interface CustomTourProps<T = any, R = void> extends TourProps, CustomOverlayProps<T, R> {
+}
+/**
+ * useTour Hook 的配置选项
+ * 排除了 propsAdapter 和 keyPrefix，这些由内部自动处理。
+ * 与 {@link UseOverlayOptions} 一致：可在顶层或 defaultProps 中传入默认 Tour 属性。
+ */
+type UseTourOptions<T extends CustomTourProps = CustomTourProps> = Omit<UseOverlayOptions<T>, 'propsAdapter' | 'keyPrefix'>;
+/**
+ * Tour 管理 Hook
+ *
+ * @returns 元组 [openTour, contextHolder]
+ */
+declare function useTour<T extends CustomTourProps>(TourComponent: React.FC<T>, options?: UseTourOptions<T>): [OverlayOpener<T>, React.ReactNode];
+/**
+ * 全局 Tour 管理 Hook
+ *
+ * 与 useTour 的区别：无需手动渲染 contextHolder，Tour 会自动挂载到全局容器。
+ */
+declare function useGlobalTour<T extends CustomTourProps>(TourComponent: React.FC<T>, options?: UseTourOptions<T>): OverlayOpener<T>;
+/**
+ * 生成绑定了特定 Tour 组件的 Hook 工厂函数
+ */
+declare function generateUseTourHook<T extends CustomTourProps>(TourComponent: React.FC<T>): {
+    useTour: (options?: UseTourOptions<T>) => [OverlayOpener<T>, React$1.ReactNode];
+    useGlobalTour: (options?: UseTourOptions<T>) => OverlayOpener<T>;
+};
+
+/**
+ * @file usePromiseOverlay - 命令式 Promise 风格的覆盖层管理 Hook
+ * @description
+ * 在 useOverlay / useGlobalOverlay 之上叠加 Promise 语义：
+ * - opener 返回 `Promise<V | undefined>`
+ * - customOk(value) 成功 → resolve(value)（解析值为入参，非 customOk 返回值）
+ * - 任意非 OK 关闭路径（customClose / 蒙层 / antd 取消按钮 / 组件卸载 / 再次 open 抢占）→ resolve(undefined)
+ * - customOk 抛错 / Promise reject → reject(error)，覆盖层保持打开
+ *
+ * 实现思路：通过包装 propsAdapter 拦截 customOk 与 customClose；
+ * 让内层适配器（默认 / Modal / Drawer）先完成 defaultProps 合并与 wrapCustomOk 的
+ * 自动关闭链路，再在外层包一层用于结算 Promise。这样 Provider 上的
+ * defaultModalProps.customOk / defaultDrawerProps.customOk 也能被正常消费。
+ */
+
+/**
+ * 从覆盖层组件 props 推断 customOk 入参类型
+ *
+ * - 若 `T['customOk']` 为 `(value: V) => any`，则 `V`
+ * - 若组件未声明 `customOk`，则 `never`（外层 Promise 实际类型为 `Promise<undefined>`）
+ */
+type CustomOkValue<T extends CustomOverlayProps> = T['customOk'] extends ((value: infer V) => unknown) | undefined ? V : never;
+/**
+ * usePromiseOverlay 系列的 opener 类型
+ *
+ * 调用 opener 即打开覆盖层并返回 Promise<V | undefined>。
+ */
+type PromiseOverlayOpener<T extends CustomOverlayProps, V = CustomOkValue<T>> = (initialize?: InternalOverlayProps<T>) => Promise<V | undefined>;
+/**
+ * usePromiseOverlay 的配置选项（与 useOverlay 完全一致）
+ */
+type UsePromiseOverlayOptions<T extends CustomOverlayProps> = UseOverlayOptions<T>;
+/**
+ * usePromiseOverlay
+ *
+ * @returns `[openPromise, holder]`
+ * @example
+ * const [openPromise, holder] = usePromiseOverlay(MyOverlay, {
+ *   propsAdapter: (props, state) => ({ ...props, open: state.open, customClose: state.onClose }),
+ * });
+ * const value = await openPromise({ ...props });
+ */
+declare function usePromiseOverlay<T extends CustomOverlayProps>(OverlayComponent: React__default.FC<T>, options?: UsePromiseOverlayOptions<T>): [PromiseOverlayOpener<T>, React__default.ReactNode];
+/**
+ * useGlobalPromiseOverlay
+ *
+ * 与 usePromiseOverlay 等价，但 holder 自动挂载到 AntdOverlayProvider。
+ * 必须在 AntdOverlayProvider 内部使用。
+ */
+declare function useGlobalPromiseOverlay<T extends CustomOverlayProps>(OverlayComponent: React__default.FC<T>, options?: UsePromiseOverlayOptions<T>): PromiseOverlayOpener<T>;
+/**
+ * 生成绑定特定组件的 Promise 版 Hook 工厂
+ *
+ * @example
+ * export const {
+ *   usePromiseOverlay: useMyPromiseOverlay,
+ *   useGlobalPromiseOverlay: useGlobalMyPromiseOverlay,
+ * } = generateUsePromiseOverlayHook(MyOverlay, { propsAdapter });
+ */
+declare function generateUsePromiseOverlayHook<T extends CustomOverlayProps>(OverlayComponent: React__default.FC<T>, defaultOptions?: UsePromiseOverlayOptions<T>): {
+    usePromiseOverlay: (options?: UsePromiseOverlayOptions<T>) => [PromiseOverlayOpener<T, CustomOkValue<T>>, React__default.ReactNode];
+    useGlobalPromiseOverlay: (options?: UsePromiseOverlayOptions<T>) => PromiseOverlayOpener<T, CustomOkValue<T>>;
+};
+
+/**
+ * @file usePromiseModal - Promise 风格的 Modal 管理 Hook
+ * @description
+ * 在 usePromiseOverlay 上使用 Modal 专用的 propsAdapter，行为与 useModal 完全对齐：
+ * - opener 返回 `Promise<V | undefined>`
+ * - customOk(value) → resolve(value)；非 OK 关闭 → resolve(undefined)；customOk 抛错 / reject → reject 透传
+ *
+ * @example
+ * const [openConfirm, holder] = usePromiseModal(ConfirmModal);
+ * const result = await openConfirm({ title: 'Confirm?' });
+ * if (result === undefined) return; // 用户取消
+ */
+
+/**
+ * usePromiseModal 的配置选项（与 useModal 一致：不含 propsAdapter / keyPrefix）
+ */
+type UsePromiseModalOptions<T extends CustomModalProps = CustomModalProps> = UseModalOptions<T>;
+declare function usePromiseModal<T extends CustomModalProps>(ModalComponent: React__default.FC<T>, options?: UsePromiseModalOptions<T>): [PromiseOverlayOpener<T>, React__default.ReactNode];
+declare function useGlobalPromiseModal<T extends CustomModalProps>(ModalComponent: React__default.FC<T>, options?: UsePromiseModalOptions<T>): PromiseOverlayOpener<T>;
+/**
+ * 生成绑定了特定 Modal 组件的 Promise Hook 工厂
+ */
+declare function generateUsePromiseModalHook<T extends CustomModalProps>(ModalComponent: React__default.FC<T>): {
+    usePromiseModal: (options?: UsePromiseModalOptions<T>) => [PromiseOverlayOpener<T>, React__default.ReactNode];
+    useGlobalPromiseModal: (options?: UsePromiseModalOptions<T>) => PromiseOverlayOpener<T>;
+};
+
+/**
+ * @file usePromiseDrawer - Promise 风格的 Drawer 管理 Hook
+ * @description
+ * 在 usePromiseOverlay 上使用 Drawer 专用的 propsAdapter，行为与 useDrawer 完全对齐：
+ * - opener 返回 `Promise<V | undefined>`
+ * - customOk(value) → resolve(value)；非 OK 关闭 → resolve(undefined)；customOk 抛错 / reject → reject 透传
+ *
+ * @example
+ * const [openPromiseDrawer, holder] = usePromiseDrawer(MyDrawer);
+ * const result = await openPromiseDrawer({ title: 'Edit' });
+ * if (result === undefined) return; // 用户取消
+ */
+
+/**
+ * usePromiseDrawer 的配置选项（与 useDrawer 一致：不含 propsAdapter / keyPrefix）
+ */
+type UsePromiseDrawerOptions<T extends CustomDrawerProps = CustomDrawerProps> = UseDrawerOptions<T>;
+declare function usePromiseDrawer<T extends CustomDrawerProps>(DrawerComponent: React__default.FC<T>, options?: UsePromiseDrawerOptions<T>): [PromiseOverlayOpener<T>, React__default.ReactNode];
+declare function useGlobalPromiseDrawer<T extends CustomDrawerProps>(DrawerComponent: React__default.FC<T>, options?: UsePromiseDrawerOptions<T>): PromiseOverlayOpener<T>;
+/**
+ * 生成绑定了特定 Drawer 组件的 Promise Hook 工厂
+ */
+declare function generateUsePromiseDrawerHook<T extends CustomDrawerProps>(DrawerComponent: React__default.FC<T>): {
+    usePromiseDrawer: (options?: UsePromiseDrawerOptions<T>) => [PromiseOverlayOpener<T>, React__default.ReactNode];
+    useGlobalPromiseDrawer: (options?: UsePromiseDrawerOptions<T>) => PromiseOverlayOpener<T>;
+};
+
+export { AntdOverlayProvider, type AntdOverlayProviderProps, type CustomDrawerProps, type CustomModalProps, type CustomOkValue, type CustomOverlayProps, type CustomTourProps, type DefaultDrawerProps, type DefaultModalProps, type DefaultTourProps, type InternalOverlayProps, type OverlayController, type OverlayOpener, type PromiseOverlayOpener, type UseDrawerOptions, type UseModalOptions, type UseOverlayOptions, type UsePromiseDrawerOptions, type UsePromiseModalOptions, type UsePromiseOverlayOptions, type UseTourOptions, generateUseDrawerHook, generateUseModalHook, generateUseOverlayHook, generateUsePromiseDrawerHook, generateUsePromiseModalHook, generateUsePromiseOverlayHook, generateUseTourHook, useAntdOverlayContext, useDrawer, useGlobalDrawer, useGlobalModal, useGlobalOverlay, useGlobalPromiseDrawer, useGlobalPromiseModal, useGlobalPromiseOverlay, useGlobalTour, useModal, useOverlay, usePromiseDrawer, usePromiseModal, usePromiseOverlay, useTour };

package/dist/index.js

@@ -6,7 +6,8 @@ var AntdOverlayContext = createContext(null);
 function AntdOverlayProvider({
   children,
   defaultModalProps,
-  defaultDrawerProps
+  defaultDrawerProps,
+  defaultTourProps
 }) {
   const [holders, setHolders] = useState([]);
   const addHolder = useCallback((holder) => {
@@ -16,8 +17,15 @@ function AntdOverlayProvider({
     setHolders((prev) => prev.filter((h) => h !== holder));
   }, []);
   const value = 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__ */ jsxs(AntdOverlayContext.Provider, { value, children: [
     children,
@@ -260,7 +268,253 @@ 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 = 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 = 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 = useRef(null);
+  const { propsAdapter: userAdapter, ...rest } = options;
+  const wrappedAdapter = useMemo(
+    () => withPromiseAdapter(
+      userAdapter ?? passthroughAdapter,
+      settleRef
+    ),
+    [userAdapter]
+  );
+  const [openOverlay, holder] = useOverlay(OverlayComponent, {
+    ...rest,
+    propsAdapter: wrappedAdapter
+  });
+  useEffect(() => {
+    return () => {
+      settleRef.current?.resolve(void 0);
+    };
+  }, []);
+  const openPromise = useMemo(() => makePromiseOpener(openOverlay, settleRef), [openOverlay]);
+  return [openPromise, holder];
+}
+function useGlobalPromiseOverlay(OverlayComponent, options = {}) {
+  const settleRef = useRef(null);
+  const { propsAdapter: userAdapter, ...rest } = options;
+  const wrappedAdapter = useMemo(
+    () => withPromiseAdapter(
+      userAdapter ?? passthroughAdapter,
+      settleRef
+    ),
+    [userAdapter]
+  );
+  const openOverlay = useGlobalOverlay(OverlayComponent, {
+    ...rest,
+    propsAdapter: wrappedAdapter
+  });
+  useEffect(() => {
+    return () => {
+      settleRef.current?.resolve(void 0);
+    };
+  }, []);
+  return 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 = useMemo(
+    () => createModalPropsAdapter(context?.defaultModalProps),
+    [context?.defaultModalProps]
+  );
+  return usePromiseOverlay(ModalComponent, {
+    ...options,
+    keyPrefix: "use-modal",
+    propsAdapter
+  });
+}
+function useGlobalPromiseModal(ModalComponent, options) {
+  const context = useAntdOverlayContext();
+  const propsAdapter = 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 = useMemo(
+    () => createDrawerPropsAdapter(context?.defaultDrawerProps),
+    [context?.defaultDrawerProps]
+  );
+  return usePromiseOverlay(DrawerComponent, {
+    ...options,
+    keyPrefix: "use-drawer",
+    propsAdapter
+  });
+}
+function useGlobalPromiseDrawer(DrawerComponent, options) {
+  const context = useAntdOverlayContext();
+  const propsAdapter = 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)
+  };
+}
 
-export { AntdOverlayProvider, generateUseDrawerHook, generateUseModalHook, generateUseOverlayHook, useAntdOverlayContext, useDrawer, useGlobalDrawer, useGlobalModal, useGlobalOverlay, useModal, useOverlay };
+export { AntdOverlayProvider, generateUseDrawerHook, generateUseModalHook, generateUseOverlayHook, generateUsePromiseDrawerHook, generateUsePromiseModalHook, generateUsePromiseOverlayHook, generateUseTourHook, useAntdOverlayContext, useDrawer, useGlobalDrawer, useGlobalModal, useGlobalOverlay, useGlobalPromiseDrawer, useGlobalPromiseModal, useGlobalPromiseOverlay, useGlobalTour, useModal, useOverlay, usePromiseDrawer, usePromiseModal, usePromiseOverlay, useTour };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map