modalio 0.9.0

package/dist/index.d.ts

@@ -0,0 +1,618 @@
+import * as react from 'react';
+import { JSXElementConstructor, ReactNode, Dispatch, ComponentType, Ref } from 'react';
+
+/** Internal key for modal configuration stored in data */
+declare const MODAL_CONFIG_KEY: "__modalConfig";
+/** Internal modal configuration shape */
+interface InternalModalConfig {
+    disableClose?: boolean;
+    keepMounted?: boolean;
+}
+/**
+ * State for a single modal instance
+ */
+interface ModalState {
+    modalId: string;
+    data?: Record<string, unknown>;
+    isOpen?: boolean;
+    delayOpen?: boolean;
+    keepMounted?: boolean;
+}
+/**
+ * Global modal store - maps modal IDs to their state
+ */
+interface ModalStore {
+    [key: string]: ModalState | undefined;
+}
+/**
+ * Modal lifecycle state
+ */
+type ModalLifecycleState = "open" | "closing" | "closed";
+type ModalActionType = "show" | "hide" | "remove" | "set-flags";
+interface ModalAction {
+    type: `modalio/${ModalActionType}`;
+    payload: {
+        modalId: string;
+        data?: Record<string, unknown>;
+        flags?: Record<string, unknown>;
+    };
+}
+/**
+ * Deferred promise with exposed resolve/reject handlers
+ */
+interface DeferredPromise<T = unknown> {
+    resolve: (value: T) => void;
+    reject: (reason: unknown) => void;
+    promise: Promise<T>;
+}
+/**
+ * Read-only state of a modal instance
+ */
+interface ModalReadState<TData = Record<string, unknown>> {
+    /** The modal's unique identifier */
+    readonly modalId: string;
+    /** Data passed to the modal via open() */
+    readonly data: TData | undefined;
+    /** Whether the modal is currently open */
+    readonly isOpen: boolean;
+    /** Whether to keep the modal mounted after closing */
+    readonly keepMounted: boolean;
+}
+/**
+ * Methods for controlling a modal
+ */
+interface ModalControls<TData = Record<string, unknown>> {
+    /** Open the modal with optional data */
+    open: (data?: TData) => Promise<unknown>;
+    /** Close the modal and resolve with a result */
+    close: (result?: unknown) => void;
+    /** Dismiss the modal (close without result, resolves undefined) */
+    dismiss: () => void;
+    /** Remove the modal from the DOM immediately */
+    remove: () => void;
+}
+/**
+ * Internal methods for animation lifecycle (used by adapters)
+ * @internal
+ */
+interface ModalAnimationHandlers {
+    /** Called when closing animation completes */
+    onAnimationEnd: () => void;
+}
+/**
+ * Complete modal handler returned by useModal hook
+ * Combines state, controls, and animation handlers
+ */
+interface ModalHandler<TData = Record<string, unknown>> extends ModalReadState<TData>, ModalControls<TData>, ModalAnimationHandlers {
+}
+/**
+ * Props injected into HOC-wrapped modal components
+ * Note: Uses `modalId` instead of `id` to avoid conflicts with common props
+ */
+interface ModalHocProps {
+    modalId: string;
+    defaultOpen?: boolean;
+    keepMounted?: boolean;
+}
+/**
+ * Extract props from a component type, excluding HOC props
+ */
+type ModalProps<T> = T extends JSXElementConstructor<infer P> ? Omit<P, keyof ModalHocProps> : Record<string, unknown>;
+/**
+ * Props for the ModalProvider component
+ */
+interface ModalProviderProps {
+    children?: ReactNode;
+    /** Optional external dispatch for state management integration */
+    dispatch?: Dispatch<ModalAction>;
+    /** Optional external modal store */
+    modals?: ModalStore;
+}
+/**
+ * Modal reference for programmatic control
+ * Provides lifecycle promises and control methods
+ */
+interface ModalRef<TResult = unknown, TData = unknown> {
+    /** Unique identifier for this modal instance */
+    readonly modalId: string;
+    /** Data passed to the modal */
+    readonly data: TData | undefined;
+    /** Whether the user is allowed to close the modal (via escape/outside click) */
+    disableClose: boolean;
+    /** Close the modal with an optional result */
+    close: (result?: TResult) => void;
+    /** Promise that resolves when the modal opening animation completes */
+    afterOpened: () => Promise<void>;
+    /** Promise that resolves with the result when the modal closing animation completes */
+    afterClosed: () => Promise<TResult | undefined>;
+    /** Promise that resolves when the modal starts closing (before animation) */
+    beforeClosed: () => Promise<TResult | undefined>;
+    /** Update the data passed to the modal */
+    updateData: (data: Partial<TData>) => void;
+    /** Get the current lifecycle state of the modal */
+    getState: () => ModalLifecycleState;
+}
+/**
+ * Configuration for opening a modal
+ */
+interface ModalConfig<TData = unknown> {
+    /** Data to pass to the modal component */
+    readonly data?: TData;
+    /** Keep the modal mounted in DOM after closing (for animation performance) */
+    readonly keepMounted?: boolean;
+    /** Custom ID for the modal (auto-generated if not provided) */
+    readonly modalId?: string;
+    /** Whether clicking outside/escape closes the modal */
+    readonly disableClose?: boolean;
+}
+/**
+ * Props for Radix UI Dialog root component
+ */
+interface RadixDialogProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+}
+/**
+ * Props for Radix UI Dialog content component
+ */
+interface RadixDialogContentProps {
+    onAnimationEndCapture: () => void;
+    onEscapeKeyDown: (e?: Event) => void;
+    onPointerDownOutside: (e?: Event) => void;
+}
+/**
+ * Combined props for Shadcn Dialog
+ */
+interface ShadcnDialogProps extends RadixDialogProps {
+    onClose: () => void;
+    onAnimationEndCapture: () => void;
+}
+
+/**
+ * Options for adapter behavior
+ */
+interface AdapterOptions {
+    /** Prevent closing via escape key or clicking outside */
+    disableClose?: boolean;
+}
+/**
+ * Adapter for Radix UI Dialog root component
+ */
+declare const radixUiDialog: (modal: ModalHandler, options?: AdapterOptions) => RadixDialogProps;
+/**
+ * Adapter for Radix UI Dialog.Content component
+ */
+declare const radixUiDialogContent: (modal: ModalHandler, options?: AdapterOptions) => RadixDialogContentProps;
+/**
+ * Adapter for Radix UI AlertDialog root component
+ */
+declare const radixUiAlertDialog: (modal: ModalHandler, options?: AdapterOptions) => RadixDialogProps;
+/**
+ * Adapter for Radix UI AlertDialog.Content component
+ */
+declare const radixUiAlertDialogContent: (modal: ModalHandler, options?: AdapterOptions) => RadixDialogContentProps;
+/**
+ * Adapter for Shadcn UI Dialog
+ */
+declare const shadcnUiDialog: (modal: ModalHandler, options?: AdapterOptions) => ShadcnDialogProps;
+/**
+ * Adapter for Shadcn UI DialogContent
+ */
+declare const shadcnUiDialogContent: (modal: ModalHandler, options?: AdapterOptions) => RadixDialogContentProps;
+/**
+ * Adapter for Shadcn UI AlertDialog
+ */
+declare const shadcnUiAlertDialog: (modal: ModalHandler, options?: AdapterOptions) => ShadcnDialogProps;
+/**
+ * Adapter for Shadcn UI AlertDialogContent
+ */
+declare const shadcnUiAlertDialogContent: (modal: ModalHandler, options?: AdapterOptions) => RadixDialogContentProps;
+/**
+ * Adapter for Shadcn UI Sheet
+ */
+declare const shadcnUiSheet: (modal: ModalHandler, options?: AdapterOptions) => ShadcnDialogProps;
+/**
+ * Adapter for Shadcn UI SheetContent
+ */
+declare const shadcnUiSheetContent: (modal: ModalHandler, options?: AdapterOptions) => RadixDialogContentProps;
+/**
+ * Adapter for Shadcn UI Popover
+ */
+declare const shadcnUiPopover: (modal: ModalHandler, options?: AdapterOptions) => {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+};
+/**
+ * Props returned by Shadcn UI Drawer adapters
+ */
+interface ShadcnUiDrawerRootProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    dismissible?: boolean;
+}
+/**
+ * Props for Shadcn UI DrawerContent component
+ */
+interface ShadcnUiDrawerContentProps {
+    onAnimationEnd: () => void;
+}
+/**
+ * Adapter for Shadcn UI Drawer
+ */
+declare const shadcnUiDrawer: (modal: ModalHandler, options?: AdapterOptions) => ShadcnUiDrawerRootProps;
+/**
+ * Adapter for Shadcn UI DrawerContent component
+ */
+declare const shadcnUiDrawerContent: (modal: ModalHandler) => ShadcnUiDrawerContentProps;
+/**
+ * Adapter for Radix UI Sheet root component
+ */
+declare const radixUiSheet: (modal: ModalHandler, options?: AdapterOptions) => {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+};
+/**
+ * Adapter for Radix UI Sheet.Content component
+ */
+declare const radixUiSheetContent: (modal: ModalHandler, options?: AdapterOptions) => RadixDialogContentProps;
+/**
+ * Adapter for Radix UI Popover
+ */
+declare const radixUiPopover: (modal: ModalHandler, options?: AdapterOptions) => {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+};
+/**
+ * Props returned by Base UI dialog adapters
+ */
+interface BaseUiDialogRootProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    dismissible?: boolean;
+}
+/**
+ * Props for Base UI Dialog.Portal component
+ */
+interface BaseUiDialogPortalProps {
+    keepMounted?: boolean;
+}
+/**
+ * Props for Base UI Dialog.Popup component
+ */
+interface BaseUiDialogPopupProps {
+    onAnimationEnd: () => void;
+}
+/**
+ * Adapter for Base UI Dialog.Root component
+ */
+declare const baseUiDialog: (modal: ModalHandler, options?: AdapterOptions) => BaseUiDialogRootProps;
+/**
+ * Adapter for Base UI Dialog.Portal component
+ */
+declare const baseUiDialogPortal: (modal: ModalHandler) => BaseUiDialogPortalProps;
+/**
+ * Adapter for Base UI Dialog.Popup component
+ */
+declare const baseUiDialogPopup: (modal: ModalHandler) => BaseUiDialogPopupProps;
+/**
+ * Adapter for Base UI AlertDialog root component
+ */
+declare const baseUiAlertDialog: (modal: ModalHandler, options?: AdapterOptions) => BaseUiDialogRootProps;
+/**
+ * Adapter for Base UI AlertDialog.Portal component
+ */
+declare const baseUiAlertDialogPortal: (modal: ModalHandler) => BaseUiDialogPortalProps;
+/**
+ * Adapter for Base UI AlertDialog.Popup component
+ */
+declare const baseUiAlertDialogPopup: (modal: ModalHandler) => BaseUiDialogPopupProps;
+/**
+ * Props returned by Base UI popover adapters
+ */
+interface BaseUiPopoverRootProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+}
+/**
+ * Props for Base UI Popover.Portal component
+ */
+interface BaseUiPopoverPortalProps {
+    keepMounted?: boolean;
+}
+/**
+ * Props for Base UI Popover.Popup component
+ */
+interface BaseUiPopoverPopupProps {
+    onAnimationEnd: () => void;
+}
+/**
+ * Adapter for Base UI Popover.Root component
+ */
+declare const baseUiPopover: (modal: ModalHandler, options?: AdapterOptions) => BaseUiPopoverRootProps;
+/**
+ * Adapter for Base UI Popover.Portal component
+ */
+declare const baseUiPopoverPortal: (modal: ModalHandler) => BaseUiPopoverPortalProps;
+/**
+ * Adapter for Base UI Popover.Popup component
+ */
+declare const baseUiPopoverPopup: (modal: ModalHandler) => BaseUiPopoverPopupProps;
+/**
+ * Adapter for Base UI Sheet root component
+ */
+declare const baseUiSheet: (modal: ModalHandler, options?: AdapterOptions) => BaseUiDialogRootProps;
+/**
+ * Adapter for Base UI Sheet.Portal component
+ */
+declare const baseUiSheetPortal: (modal: ModalHandler) => BaseUiDialogPortalProps;
+/**
+ * Adapter for Base UI Sheet.Popup component
+ */
+declare const baseUiSheetPopup: (modal: ModalHandler) => BaseUiDialogPopupProps;
+
+/**
+ * Context for the modal store
+ */
+declare const ModalContext: react.Context<ModalStore>;
+/**
+ * Context for the current modal ID (used in HOC-wrapped components)
+ */
+declare const ModalIdContext: react.Context<string | null>;
+/**
+ * Modal Provider - wrap your app with this to enable modal management
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <ModalProvider>
+ *   <App />
+ * </ModalProvider>
+ *
+ * // With external state management (Redux, etc.)
+ * <ModalProvider dispatch={dispatch} modals={modals}>
+ *   <App />
+ * </ModalProvider>
+ * ```
+ */
+declare function ModalProvider({ children, dispatch: givenDispatch, modals: givenModals, }: ModalProviderProps): ReactNode;
+/**
+ * Declarative modal definition component
+ *
+ * @example
+ * ```tsx
+ * <ModalDef id="my-modal" component={MyModal} />
+ * ```
+ */
+declare function ModalDef({ id, component, }: {
+    id: string;
+    component: ComponentType<any>;
+}): ReactNode;
+
+/**
+ * Get the modal ID from a string or component
+ */
+declare const getModalId: (modal: string | ComponentType<Record<string, unknown>>) => string;
+/**
+ * Reducer for modal state management
+ */
+declare const reducer: (state: ModalStore, action: ModalAction) => ModalStore;
+
+/**
+ * Hook to control a modal from within the modal component or from anywhere.
+ * Returns an enhanced handler with state and control methods.
+ *
+ * @example
+ * ```tsx
+ * // Inside a modal component (uses context)
+ * const modal = useModal();
+ *
+ * return (
+ *   <Dialog open={modal.open} onOpenChange={(open) => !open && modal.dismiss()}>
+ *     <DialogContent onAnimationEnd={modal.onAnimationEnd}>
+ *       <Button onClick={() => modal.close(result)}>Save</Button>
+ *       <Button onClick={modal.dismiss}>Cancel</Button>
+ *     </DialogContent>
+ *   </Dialog>
+ * );
+ *
+ * // With a specific modal component
+ * const modal = useModal(MyModal);
+ * modal.open({ userId: '123' });
+ *
+ * // With a string ID
+ * const modal = useModal('my-modal');
+ * ```
+ */
+declare function useModal(modal?: string, data?: Record<string, unknown>): ModalHandler;
+declare function useModal<TProps extends Record<string, unknown>, P extends Partial<ModalProps<React.ComponentType<TProps & ModalHocProps>>>>(modal: React.ComponentType<TProps & ModalHocProps>, data?: P): ModalHandler<TProps>;
+/**
+ * Hook to get typed data passed to a modal
+ * Must be used inside a modal component (within ModalIdContext)
+ *
+ * @example
+ * ```tsx
+ * interface MyModalData {
+ *   userId: string;
+ *   userName: string;
+ * }
+ *
+ * const MyModal = createModal(() => {
+ *   const data = useModalData<MyModalData>();
+ *   const modal = useModal();
+ *
+ *   return (
+ *     <Dialog open={modal.open}>
+ *       <DialogContent>
+ *         <p>User: {data?.userName}</p>
+ *       </DialogContent>
+ *     </Dialog>
+ *   );
+ * });
+ *
+ * // Usage:
+ * open(MyModal, { data: { userId: '123', userName: 'John' } });
+ * ```
+ */
+declare function useModalData<TData = Record<string, unknown>>(): TData | undefined;
+/**
+ * Hook to get the modal config options (disableClose, keepMounted, etc.)
+ * Must be used inside a modal component
+ */
+declare function useModalConfig(): InternalModalConfig;
+
+/** Props for components that accept a ref (React 19+ style) */
+interface RefProp<T> {
+    ref?: Ref<T>;
+}
+
+/**
+ * Close a modal and return a promise that resolves when the animation completes
+ *
+ * @example
+ * ```tsx
+ * await closeModal(MyModal);
+ * await closeModal('my-modal');
+ * ```
+ */
+declare function closeModal<TResult = unknown>(modal: string | React.ComponentType<any>): Promise<TResult>;
+/**
+ * Open a modal and return a ModalRef for controlling it
+ *
+ * @example
+ * ```tsx
+ * // Open a modal with typed data
+ * const modalRef = openModal<{ confirmed: boolean }, { userId: string }>(
+ *   ConfirmModal,
+ *   { data: { userId: '123' } }
+ * );
+ *
+ * // Wait for it to close
+ * const result = await modalRef.afterClosed();
+ * if (result?.confirmed) {
+ *   // User confirmed
+ * }
+ *
+ * // Or close it programmatically
+ * modalRef.close({ confirmed: false });
+ *
+ * // Check lifecycle state
+ * if (modalRef.getState() === 'open') {
+ *   modalRef.close();
+ * }
+ * ```
+ */
+declare function openModal<TResult = unknown, TData = Record<string, unknown>, TProps extends Record<string, unknown> = Record<string, unknown>>(modal: React.ComponentType<TProps & ModalHocProps>, config?: ModalConfig<TData>): ModalRef<TResult, TData>;
+declare function openModal<TResult = unknown, TData = Record<string, unknown>>(modal: string, config?: ModalConfig<TData>): ModalRef<TResult, TData>;
+
+/**
+ * ModalManager namespace - the primary API for managing modals.
+ *
+ * @example
+ * ```tsx
+ * import { ModalManager } from "modalio";
+ *
+ * // Create a modal
+ * const MyModal = ModalManager.create<{ message: string }>(({ message }) => {
+ *   const modal = useModal();
+ *   return (
+ *     <Dialog {...radixDialog(modal)}>
+ *       <DialogContent {...radixDialogContent(modal)}>
+ *         <p>{message}</p>
+ *         <button onClick={() => modal.close(true)}>Confirm</button>
+ *       </DialogContent>
+ *     </Dialog>
+ *   );
+ * });
+ *
+ * // Open it
+ * const result = await ModalManager.open(MyModal, {
+ *   data: { message: "Hello!" }
+ * }).afterClosed();
+ *
+ * // Close it
+ * ModalManager.close(MyModal);
+ *
+ * // Close all modals
+ * ModalManager.closeAll();
+ * ```
+ */
+declare const ModalManager: {
+    /**
+     * Create a modal component with lifecycle management.
+     * Wraps your component with automatic registration and state handling.
+     */
+    readonly create: <TProps extends Record<string, unknown> = Record<string, unknown>, TRef = unknown>(Comp: react.ComponentType<TProps & RefProp<TRef>>) => react.ComponentType<TProps & ModalHocProps & RefProp<TRef>>;
+    /**
+     * Open a modal and return a ModalRef for controlling it.
+     * @returns ModalRef with afterOpened(), afterClosed(), beforeClosed() promises
+     */
+    readonly open: typeof openModal;
+    /**
+     * Close a specific modal by component or ID.
+     * @returns Promise that resolves when the close animation completes
+     */
+    readonly close: typeof closeModal;
+    /**
+     * Close all open modals.
+     * @returns Promise that resolves when all close animations complete
+     */
+    readonly closeAll: () => Promise<void>;
+    /**
+     * Remove a modal from the DOM completely.
+     */
+    readonly remove: (modal: string | React.ComponentType<Record<string, unknown>>) => void;
+    /**
+     * Check if any modals are currently open.
+     */
+    readonly hasOpen: () => boolean;
+    /**
+     * Get array of currently open modal IDs.
+     */
+    readonly getOpen: () => string[];
+    /**
+     * Register a modal component with an ID for later use.
+     */
+    readonly register: (id: string, comp: react.ComponentType<any>, props?: Record<string, unknown>) => void;
+    /**
+     * Unregister a previously registered modal.
+     */
+    readonly unregister: (id: string) => void;
+    /**
+     * Clean up all internal state for a specific modal.
+     */
+    readonly cleanup: (modalId: string) => void;
+    /**
+     * Clean up all modal state (useful for testing).
+     */
+    readonly cleanupAll: () => void;
+    /**
+     * Context provider for modal management.
+     * Must wrap your application.
+     *
+     * @example
+     * ```tsx
+     * function App() {
+     *   return (
+     *     <ModalManager.Provider>
+     *       <YourApp />
+     *     </ModalManager.Provider>
+     *   );
+     * }
+     * ```
+     */
+    readonly Provider: typeof ModalProvider;
+    /**
+     * Declaratively define a modal in JSX.
+     *
+     * @example
+     * ```tsx
+     * <ModalManager.Def component={MyModal} id="my-modal" />
+     *
+     * // Later: open by ID
+     * ModalManager.open("my-modal");
+     * ```
+     */
+    readonly Def: typeof ModalDef;
+};
+
+export { type AdapterOptions, type BaseUiDialogPopupProps, type BaseUiDialogPortalProps, type BaseUiDialogRootProps, type BaseUiPopoverPopupProps, type BaseUiPopoverPortalProps, type BaseUiPopoverRootProps, type DeferredPromise, type InternalModalConfig, MODAL_CONFIG_KEY, type ModalAction, type ModalActionType, type ModalAnimationHandlers, type ModalConfig, ModalContext, type ModalControls, type ModalHandler, type ModalHocProps, ModalIdContext, type ModalLifecycleState, ModalManager, type ModalProps, type ModalProviderProps, type ModalReadState, type ModalRef, type ModalState, type ModalStore, type RadixDialogContentProps, type RadixDialogProps, type ShadcnDialogProps, type ShadcnUiDrawerContentProps, type ShadcnUiDrawerRootProps, baseUiAlertDialog, baseUiAlertDialogPopup, baseUiAlertDialogPortal, baseUiDialog, baseUiDialogPopup, baseUiDialogPortal, baseUiPopover, baseUiPopoverPopup, baseUiPopoverPortal, baseUiSheet, baseUiSheetPopup, baseUiSheetPortal, getModalId, radixUiAlertDialog, radixUiAlertDialogContent, radixUiDialog, radixUiDialogContent, radixUiPopover, radixUiSheet, radixUiSheetContent, reducer, shadcnUiAlertDialog, shadcnUiAlertDialogContent, shadcnUiDialog, shadcnUiDialogContent, shadcnUiDrawer, shadcnUiDrawerContent, shadcnUiPopover, shadcnUiSheet, shadcnUiSheetContent, useModal, useModalConfig, useModalData };