antd-overlay 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,635 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as React$1 from 'react';
+import React__default from 'react';
+import { ModalProps, DrawerProps } from 'antd';
+
+/**
+ * AntdOverlay Context 的值类型
+ *
+ * @property holders - 当前所有已注册的覆盖层 holder 节点
+ * @property addHolder - 注册一个新的 holder 到全局容器
+ * @property removeHolder - 从全局容器移除一个已注册的 holder
+ */
+interface AntdOverlayContextValue {
+    /** 所有已注册的 holder 节点列表 */
+    holders: React__default.ReactNode[];
+    /** 添加 holder 到全局容器 */
+    addHolder: (holder: React__default.ReactNode) => void;
+    /** 从全局容器移除 holder */
+    removeHolder: (holder: React__default.ReactNode) => void;
+}
+/**
+ * AntdOverlay 容器提供者组件
+ *
+ * 用于管理全局覆盖层的挂载点。所有通过 useGlobalOverlay、useGlobalModal、
+ * useGlobalDrawer 等 Hook 创建的覆盖层都会被挂载到这个 Provider 下。
+ *
+ * 渲染结构：
+ * ```
+ * <AntdOverlayContext.Provider>
+ *   {children}           <- 应用的主要内容
+ *   {holders[0]}         <- 全局覆盖层 1
+ *   {holders[1]}         <- 全局覆盖层 2
+ *   ...
+ * </AntdOverlayContext.Provider>
+ * ```
+ *
+ * @param children - 子节点，通常是整个应用
+ *
+ * @example
+ * // 基础用法 - 在应用入口包裹
+ * function App() {
+ *   return (
+ *     <AntdOverlayProvider>
+ *       <Router>
+ *         <Routes />
+ *       </Router>
+ *     </AntdOverlayProvider>
+ *   );
+ * }
+ *
+ * @example
+ * // 与其他 Provider 配合使用
+ * function App() {
+ *   return (
+ *     <ConfigProvider>
+ *       <AntdOverlayProvider>
+ *         <App />
+ *       </AntdOverlayProvider>
+ *     </ConfigProvider>
+ *   );
+ * }
+ */
+declare function AntdOverlayProvider({ children }: {
+    children: React__default.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/**
+ * 获取 AntdOverlay Context 的 Hook
+ *
+ * 返回全局容器的注册和注销方法，供 useGlobalOverlay 系列 Hook 内部使用。
+ *
+ * 注意事项：
+ * - 必须在 AntdOverlayProvider 内部使用
+ * - 如果在 Provider 外部调用，会抛出明确的错误
+ * - 主要供库内部使用，一般不需要在业务代码中直接调用
+ *
+ * @returns AntdOverlayContextValue 包含 holders、addHolder、removeHolder
+ * @throws Error 如果不在 AntdOverlayProvider 内部使用
+ *
+ * @example
+ * // 库内部使用示例（useGlobalOverlay 的实现）
+ * function useGlobalOverlay(Component, options) {
+ *   const { addHolder, removeHolder } = useAntdOverlayContext();
+ *   const [open, holder] = useOverlay(Component, options);
+ *
+ *   useEffect(() => {
+ *     addHolder(holder);
+ *     return () => removeHolder(holder);
+ *   }, [holder]);
+ *
+ *   return open;
+ * }
+ */
+declare function useAntdOverlayContext(): AntdOverlayContextValue;
+
+/**
+ * @file useOverlay - 通用覆盖层管理 Hook
+ * @description
+ * 提供一个与具体 UI 组件无关的覆盖层（Overlay）管理方案。
+ * 支持任意满足 CustomOverlayProps 接口的组件，如 Modal、Drawer、Popover 等。
+ *
+ * 核心设计理念：
+ * 1. 命令式调用 - 通过函数调用打开覆盖层，而非声明式管理 open 状态
+ * 2. 动画支持 - 正确处理打开/关闭动画，避免动画未完成就卸载组件
+ * 3. 全局挂载 - 支持将覆盖层挂载到全局容器，实现跨组件调用
+ * 4. 类型安全 - 完整的 TypeScript 类型支持
+ *
+ * 架构层次：
+ * ┌─────────────────────────────────────────────────────────┐
+ * │                    useModal / useDrawer                 │  <- 业务层封装
+ * ├─────────────────────────────────────────────────────────┤
+ * │              useOverlay / useGlobalOverlay              │  <- 核心逻辑层
+ * ├─────────────────────────────────────────────────────────┤
+ * │                  GlobalHolderProvider                   │  <- 全局容器层
+ * └─────────────────────────────────────────────────────────┘
+ *
+ * @example
+ * // 直接使用 useOverlay（不推荐，建议使用 useModal/useDrawer）
+ * const [openOverlay, holder] = useOverlay(MyOverlayComponent, {
+ *   propsAdapter: (props, state) => ({ ...props, visible: state.open }),
+ * });
+ */
+
+/**
+ * 自定义覆盖层组件必须实现的属性接口
+ *
+ * 这是所有覆盖层组件的基础接口，定义了控制覆盖层所需的最小属性集。
+ * 具体的 UI 组件（如 Modal、Drawer）应该扩展此接口。
+ *
+ * @template T - customOk 回调接收的参数类型，用于传递确认操作的数据
+ * @template R - customOk 回调的返回类型，通常为 void
+ *
+ * @property open - 控制覆盖层的显示/隐藏状态
+ * @property customClose - 关闭覆盖层的回调函数，由 useOverlay 注入
+ * @property customOk - 确认操作的回调函数，调用后会自动关闭覆盖层
+ *
+ * @example
+ * interface MyOverlayProps extends CustomOverlayProps<{ id: number }> {
+ *   title: string;
+ *   data: SomeData;
+ * }
+ *
+ * const MyOverlay: React.FC<MyOverlayProps> = ({
+ *   open,
+ *   customClose,
+ *   customOk,
+ *   title,
+ *   data,
+ * }) => {
+ *   const handleConfirm = () => {
+ *     // 调用 customOk 会自动关闭覆盖层
+ *     customOk?.({ id: data.id });
+ *   };
+ *   return (
+ *     <Modal open={open} onCancel={customClose} onOk={handleConfirm}>
+ *       {title}
+ *     </Modal>
+ *   );
+ * };
+ */
+interface CustomOverlayProps<T = any, R = void> {
+    /** 覆盖层的显示状态 */
+    open?: boolean;
+    /** 关闭覆盖层的回调，由 useOverlay 自动注入 */
+    customClose: () => void;
+    /** 确认操作回调，调用后自动关闭覆盖层 */
+    customOk?: (value: T) => R;
+}
+/**
+ * 内部使用的属性类型
+ * 排除 customClose，因为它由 useOverlay 自动注入，用户无需传递
+ */
+type InternalProps<T extends CustomOverlayProps> = Omit<T, 'customClose'>;
+/**
+ * 覆盖层控制器接口
+ *
+ * 打开覆盖层后返回的控制器对象，用于后续操作（更新属性或关闭）。
+ * 使用 readonly 确保方法引用稳定，不会被意外修改。
+ *
+ * @template T - 覆盖层组件的属性类型
+ *
+ * @example
+ * const controller = openModal({ title: '初始标题' });
+ *
+ * // 动态更新属性
+ * controller.update({ title: '新标题', loading: true });
+ *
+ * // 编程式关闭
+ * controller.close();
+ */
+interface OverlayController<T extends CustomOverlayProps> {
+    /**
+     * 更新覆盖层的属性
+     * @param props - 新的属性对象，会完全替换之前的属性
+     */
+    readonly update: (props: InternalProps<T>) => void;
+    /**
+     * 关闭覆盖层
+     * 如果启用了动画，会等待动画结束后再卸载组件
+     */
+    readonly close: () => void;
+}
+/**
+ * 覆盖层打开函数的类型定义
+ *
+ * @template T - 覆盖层组件的属性类型
+ * @param initialize - 初始化属性，可选
+ * @returns 覆盖层控制器，用于后续的更新和关闭操作
+ *
+ * @example
+ * const openModal: OverlayOpener<MyModalProps> = (props) => {
+ *   // 返回控制器
+ * };
+ *
+ * // 无参数调用
+ * const ctrl1 = openModal();
+ *
+ * // 带初始属性调用
+ * const ctrl2 = openModal({ title: '标题', data: someData });
+ */
+type OverlayOpener<T extends CustomOverlayProps> = (initialize?: InternalProps<T>) => OverlayController<T>;
+/**
+ * useOverlay Hook 的配置选项
+ *
+ * @template T - 覆盖层组件的属性类型
+ *
+ * @property animation - 是否启用动画支持，默认 true
+ *   - true: 关闭时先设置 open=false，等待动画结束后再卸载组件
+ *   - false: 关闭时直接卸载组件，适用于无动画的覆盖层
+ *
+ * @property keyPrefix - React key 的前缀，用于区分不同类型的覆盖层
+ *   - 默认值: 'use-overlay'
+ *   - useModal 使用 'use-modal'
+ *   - useDrawer 使用 'use-drawer'
+ *
+ * @property propsAdapter - 属性适配器函数
+ *   用于将内部状态转换为组件实际需要的属性。
+ *   不同的 UI 组件（Modal、Drawer）有不同的动画回调机制，
+ *   通过适配器实现统一的接口。
+ */
+interface UseOverlayOptions<T extends CustomOverlayProps> {
+    /** 是否启用关闭动画，默认 true */
+    animation?: boolean;
+    /** React key 前缀，用于标识覆盖层类型 */
+    keyPrefix?: string;
+    /**
+     * 属性适配器函数
+     * @param props - 用户传入的属性
+     * @param state - 内部状态，包含 open、onClose、onAnimationEnd
+     * @returns 传递给组件的最终属性
+     */
+    propsAdapter?: (props: InternalProps<T> | undefined, state: {
+        /** 当前的打开状态 */
+        open: boolean;
+        /** 触发关闭的回调 */
+        onClose: () => void;
+        /** 动画结束后的回调，用于卸载组件 */
+        onAnimationEnd: () => void;
+    }) => T;
+}
+/**
+ * 覆盖层管理核心 Hook
+ *
+ * 这是整个库的核心，提供覆盖层的生命周期管理：
+ * - 挂载/卸载控制
+ * - 打开/关闭状态管理
+ * - 动画支持
+ * - 属性更新
+ *
+ * 状态机说明：
+ * ```
+ * [未挂载] --open()--> [已挂载, open=true] --close()--> [已挂载, open=false] --动画结束--> [未挂载]
+ *                                                            │
+ *                                                            └── (animation=false) --> [未挂载]
+ * ```
+ *
+ * @template T - 覆盖层组件的属性类型，必须继承 CustomOverlayProps
+ *
+ * @param OverlayComponent - 覆盖层组件
+ * @param options - 配置选项
+ *
+ * @returns 元组 [openOverlay, contextHolder]
+ * - openOverlay: 打开覆盖层的函数，返回控制器
+ * - contextHolder: 需要渲染到组件树中的 React 节点
+ *
+ * @example
+ * function MyComponent() {
+ *   const [openOverlay, holder] = useOverlay(MyOverlay, {
+ *     animation: true,
+ *     propsAdapter: (props, state) => ({
+ *       ...props,
+ *       visible: state.open,
+ *       onClose: state.onClose,
+ *       afterVisibleChange: (visible) => {
+ *         if (!visible) state.onAnimationEnd();
+ *       },
+ *     }),
+ *   });
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => openOverlay({ title: '标题' })}>打开</button>
+ *       {holder}
+ *     </>
+ *   );
+ * }
+ */
+declare function useOverlay<T extends CustomOverlayProps>(OverlayComponent: React__default.FC<T>, options?: UseOverlayOptions<T>): [OverlayOpener<T>, React__default.ReactNode];
+/**
+ * 全局覆盖层管理 Hook
+ *
+ * 与 useOverlay 的区别：
+ * - useOverlay: 需要手动渲染 contextHolder
+ * - useGlobalOverlay: 自动挂载到 AntdOverlayProvider
+ *
+ * 实现原理：
+ * 1. 内部调用 useOverlay 获取 openOverlay 和 contextHolder
+ * 2. 使用 useEffect 将 contextHolder 注册到全局容器
+ * 3. 组件卸载时自动从全局容器移除
+ *
+ * 使用前提：
+ * - 必须在组件树的上层包裹 AntdOverlayProvider
+ *
+ * @template T - 覆盖层组件的属性类型
+ *
+ * @param OverlayComponent - 覆盖层组件
+ * @param options - 配置选项
+ *
+ * @returns 打开覆盖层的函数（无需再渲染 holder）
+ *
+ * @example
+ * // 1. 先在应用入口包裹 Provider
+ * function App() {
+ *   return (
+ *     <AntdOverlayProvider>
+ *       <YourApp />
+ *     </AntdOverlayProvider>
+ *   );
+ * }
+ *
+ * // 2. 在任意组件中使用
+ * function AnyComponent() {
+ *   const openOverlay = useGlobalOverlay(MyOverlay);
+ *
+ *   return (
+ *     <button onClick={() => openOverlay({ data: someData })}>
+ *       打开全局覆盖层
+ *     </button>
+ *   );
+ * }
+ */
+declare function useGlobalOverlay<T extends CustomOverlayProps>(OverlayComponent: React__default.FC<T>, options?: UseOverlayOptions<T>): OverlayOpener<T>;
+/**
+ * 生成绑定了特定组件的 Hook 工厂函数
+ *
+ * 当某个覆盖层组件在多处使用时，可以使用此函数生成专用 Hook，
+ * 避免每次使用都需要传入组件引用。
+ *
+ * @template T - 覆盖层组件的属性类型
+ *
+ * @param OverlayComponent - 覆盖层组件
+ * @param defaultOptions - 默认配置选项，会与调用时的选项合并
+ *
+ * @returns 包含 useOverlay 和 useGlobalOverlay 的对象
+ *
+ * @example
+ * // 创建专用 Hook
+ * const {
+ *   useOverlay: useMyOverlay,
+ *   useGlobalOverlay: useGlobalMyOverlay,
+ * } = generateUseOverlayHook(MyOverlayComponent, {
+ *   animation: true,
+ *   propsAdapter: myAdapter,
+ * });
+ *
+ * // 使用专用 Hook（无需再传组件）
+ * function SomeComponent() {
+ *   const openOverlay = useGlobalMyOverlay();
+ *   return <button onClick={() => openOverlay()}>打开</button>;
+ * }
+ */
+declare function generateUseOverlayHook<T extends CustomOverlayProps>(OverlayComponent: React__default.FC<T>, defaultOptions?: UseOverlayOptions<T>): {
+    /**
+     * 绑定了特定组件的 useOverlay
+     * @param options - 配置选项，会与 defaultOptions 合并
+     */
+    useOverlay: (options?: UseOverlayOptions<T>) => [OverlayOpener<T>, React__default.ReactNode];
+    /**
+     * 绑定了特定组件的 useGlobalOverlay
+     * @param options - 配置选项，会与 defaultOptions 合并
+     */
+    useGlobalOverlay: (options?: UseOverlayOptions<T>) => OverlayOpener<T>;
+};
+
+/**
+ * 自定义 Modal 组件的属性接口
+ * 继承 Ant Design ModalProps 并添加自定义属性
+ *
+ * @template T - customOk 回调的参数类型
+ * @template R - customOk 回调的返回类型
+ *
+ * @example
+ * const MyModal: React.FC<CustomModalProps<{ name: string }>> = ({
+ *   open,
+ *   customClose,
+ *   customOk,
+ * }) => {
+ *   return (
+ *     <Modal open={open} onCancel={customClose} onOk={() => customOk?.({ name: 'test' })}>
+ *       内容
+ *     </Modal>
+ *   );
+ * };
+ */
+interface CustomModalProps<T = any, R = void> extends ModalProps, CustomOverlayProps<T, R> {
+}
+/**
+ * useModal Hook 的配置选项
+ * 排除了 propsAdapter 和 keyPrefix，这些由内部自动处理
+ */
+type UseModalOptions = Omit<UseOverlayOptions<CustomModalProps>, 'propsAdapter' | 'keyPrefix'>;
+/**
+ * Modal 管理 Hook
+ *
+ * @template T - Modal 组件的属性类型，必须继承 CustomModalProps
+ *
+ * @param ModalComponent - Modal 组件
+ * @param options - 配置选项
+ *
+ * @returns 元组 [openModal, contextHolder]
+ * - openModal: 打开 Modal 的函数
+ * - contextHolder: 需要渲染到组件树中的 React 节点
+ *
+ * @example
+ * function MyPage() {
+ *   const [openModal, modalHolder] = useModal(ConfirmModal);
+ *
+ *   const handleDelete = () => {
+ *     openModal({
+ *       title: '确认删除',
+ *       content: '删除后无法恢复',
+ *     });
+ *   };
+ *
+ *   return (
+ *     <>
+ *       <button onClick={handleDelete}>删除</button>
+ *       {modalHolder}
+ *     </>
+ *   );
+ * }
+ */
+declare function useModal<T extends CustomModalProps>(ModalComponent: React.FC<T>, options?: UseModalOptions): [OverlayOpener<T>, React.ReactNode];
+/**
+ * 全局 Modal 管理 Hook
+ *
+ * 与 useModal 的区别：
+ * - 无需手动渲染 contextHolder
+ * - Modal 会自动挂载到全局容器
+ * - 适合需要跨组件调用的场景
+ *
+ * @template T - Modal 组件的属性类型
+ *
+ * @param ModalComponent - Modal 组件
+ * @param options - 配置选项
+ *
+ * @returns 打开 Modal 的函数
+ *
+ * @example
+ * function DeleteButton() {
+ *   const openConfirm = useGlobalModal(ConfirmModal);
+ *
+ *   return (
+ *     <button onClick={() => openConfirm({ title: '确认删除？' })}>
+ *       删除
+ *     </button>
+ *   );
+ * }
+ */
+declare function useGlobalModal<T extends CustomModalProps>(ModalComponent: React.FC<T>, options?: UseModalOptions): OverlayOpener<T>;
+/**
+ * 生成绑定了特定 Modal 组件的 Hook 工厂函数
+ *
+ * 适用场景：
+ * - 某个 Modal 在多处使用
+ * - 希望简化调用代码
+ * - 需要统一管理某个 Modal 的默认配置
+ *
+ * @template T - Modal 组件的属性类型
+ *
+ * @param ModalComponent - Modal 组件
+ *
+ * @returns 包含 useModal 和 useGlobalModal 的对象
+ *
+ * @example
+ * // 在 Modal 组件文件中导出专用 Hook
+ * const ConfirmModal: React.FC<CustomModalProps> = (props) => {
+ *   // ...
+ * };
+ *
+ * export const {
+ *   useModal: useConfirmModal,
+ *   useGlobalModal: useGlobalConfirmModal,
+ * } = generateUseModalHook(ConfirmModal);
+ *
+ * // 在其他组件中使用
+ * function MyPage() {
+ *   const openConfirm = useGlobalConfirmModal();
+ *   return <button onClick={() => openConfirm()}>确认</button>;
+ * }
+ */
+declare function generateUseModalHook<T extends CustomModalProps>(ModalComponent: React.FC<T>): {
+    useModal: (options?: UseModalOptions) => [OverlayOpener<T>, React$1.ReactNode];
+    useGlobalModal: (options?: UseModalOptions) => OverlayOpener<T>;
+};
+
+/**
+ * 自定义 Drawer 组件的属性接口
+ * 继承 Ant Design DrawerProps 并添加自定义属性
+ *
+ * @template T - customOk 回调的参数类型
+ * @template R - customOk 回调的返回类型
+ *
+ * @example
+ * const MyDrawer: React.FC<CustomDrawerProps<{ id: number }>> = ({
+ *   open,
+ *   customClose,
+ *   customOk,
+ * }) => {
+ *   return (
+ *     <Drawer open={open} onClose={customClose}>
+ *       <Button onClick={() => customOk?.({ id: 1 })}>确认</Button>
+ *     </Drawer>
+ *   );
+ * };
+ */
+interface CustomDrawerProps<T = any, R = void> extends DrawerProps, CustomOverlayProps<T, R> {
+}
+/**
+ * useDrawer Hook 的配置选项
+ * 排除了 propsAdapter 和 keyPrefix，这些由内部自动处理
+ */
+type UseDrawerOptions = Omit<UseOverlayOptions<CustomDrawerProps>, 'propsAdapter' | 'keyPrefix'>;
+/**
+ * Drawer 管理 Hook
+ *
+ * @template T - Drawer 组件的属性类型，必须继承 CustomDrawerProps
+ *
+ * @param DrawerComponent - Drawer 组件
+ * @param options - 配置选项
+ *
+ * @returns 元组 [openDrawer, contextHolder]
+ * - openDrawer: 打开 Drawer 的函数
+ * - contextHolder: 需要渲染到组件树中的 React 节点
+ *
+ * @example
+ * function MyPage() {
+ *   const [openDrawer, drawerHolder] = useDrawer(UserDetailDrawer);
+ *
+ *   const handleViewUser = (userId: number) => {
+ *     openDrawer({ userId, title: '用户详情' });
+ *   };
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => handleViewUser(1)}>查看用户</button>
+ *       {drawerHolder}
+ *     </>
+ *   );
+ * }
+ */
+declare function useDrawer<T extends CustomDrawerProps>(DrawerComponent: React.FC<T>, options?: UseDrawerOptions): [OverlayOpener<T>, React.ReactNode];
+/**
+ * 全局 Drawer 管理 Hook
+ *
+ * 与 useDrawer 的区别：
+ * - 无需手动渲染 contextHolder
+ * - Drawer 会自动挂载到全局容器
+ * - 适合需要跨组件调用的场景
+ *
+ * @template T - Drawer 组件的属性类型
+ *
+ * @param DrawerComponent - Drawer 组件
+ * @param options - 配置选项
+ *
+ * @returns 打开 Drawer 的函数
+ *
+ * @example
+ * function UserCard({ userId }: { userId: number }) {
+ *   const openDetail = useGlobalDrawer(UserDetailDrawer);
+ *
+ *   return (
+ *     <Card onClick={() => openDetail({ userId })}>
+ *       查看详情
+ *     </Card>
+ *   );
+ * }
+ */
+declare function useGlobalDrawer<T extends CustomDrawerProps>(DrawerComponent: React.FC<T>, options?: UseDrawerOptions): OverlayOpener<T>;
+/**
+ * 生成绑定了特定 Drawer 组件的 Hook 工厂函数
+ *
+ * 适用场景：
+ * - 某个 Drawer 在多处使用
+ * - 希望简化调用代码
+ * - 需要统一管理某个 Drawer 的默认配置
+ *
+ * @template T - Drawer 组件的属性类型
+ *
+ * @param DrawerComponent - Drawer 组件
+ *
+ * @returns 包含 useDrawer 和 useGlobalDrawer 的对象
+ *
+ * @example
+ * // 在 Drawer 组件文件中导出专用 Hook
+ * const ProjectMemberDrawer: React.FC<CustomDrawerProps> = (props) => {
+ *   // ...
+ * };
+ *
+ * export const {
+ *   useDrawer: useProjectMemberDrawer,
+ *   useGlobalDrawer: useGlobalProjectMemberDrawer,
+ * } = generateUseDrawerHook(ProjectMemberDrawer);
+ *
+ * // 在其他组件中使用
+ * function ProjectPage() {
+ *   const openMemberDrawer = useGlobalProjectMemberDrawer();
+ *   return <button onClick={() => openMemberDrawer()}>管理成员</button>;
+ * }
+ */
+declare function generateUseDrawerHook<T extends CustomDrawerProps>(DrawerComponent: React.FC<T>): {
+    useDrawer: (options?: UseDrawerOptions) => [OverlayOpener<T>, React$1.ReactNode];
+    useGlobalDrawer: (options?: UseDrawerOptions) => OverlayOpener<T>;
+};
+
+export { AntdOverlayProvider, type CustomDrawerProps, type CustomModalProps, type CustomOverlayProps, type OverlayController, type OverlayOpener, type UseDrawerOptions, type UseModalOptions, type UseOverlayOptions, generateUseDrawerHook, generateUseModalHook, generateUseOverlayHook, useAntdOverlayContext, useDrawer, useGlobalDrawer, useGlobalModal, useGlobalOverlay, useModal, useOverlay };