@lerx/promise-modal 0.2.8 → 0.3.0

package/dist/bootstrap/BootstrapProvider/BootstrapProvider.d.ts

@@ -1,4 +1,119 @@
 import type { BootstrapProviderHandle } from './type';
+/**
+ * Provider component that bootstraps the promise-modal system.
+ *
+ * Sets up the modal rendering infrastructure by creating a portal anchor point
+ * and managing the lifecycle of modal components. Can be initialized automatically
+ * on mount or manually via ref handle.
+ *
+ * @example
+ * Basic usage with automatic initialization:
+ * ```tsx
+ * import { ModalProvider, alert, confirm } from '@lerx/promise-modal';
+ *
+ * function App() {
+ *   return (
+ *     <ModalProvider>
+ *       <button onClick={() => alert({ title: 'Hello!' })}>Alert</button>
+ *       <button onClick={() => confirm({ title: 'Confirm?' })}>Confirm</button>
+ *     </ModalProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Custom modal components:
+ * ```tsx
+ * const CustomForeground = ({ children, visible }) => (
+ *   <div className={`modal ${visible ? 'show' : 'hide'}`}>
+ *     {children}
+ *   </div>
+ * );
+ *
+ * const CustomTitle = ({ children }) => (
+ *   <h2 className="modal-title">{children}</h2>
+ * );
+ *
+ * <ModalProvider
+ *   ForegroundComponent={CustomForeground}
+ *   TitleComponent={CustomTitle}
+ *   options={{
+ *     duration: 300,
+ *     backdrop: 'rgba(0, 0, 0, 0.5)',
+ *     closeOnBackdropClick: false,
+ *   }}
+ * >
+ *   <App />
+ * </ModalProvider>
+ * ```
+ *
+ * @example
+ * Manual initialization with custom anchor:
+ * ```tsx
+ * function CustomModalContainer() {
+ *   const modalRef = useRef<ModalProviderHandle>(null);
+ *   const containerRef = useRef<HTMLDivElement>(null);
+ *
+ *   useEffect(() => {
+ *     if (containerRef.current) {
+ *       modalRef.current?.initialize(containerRef.current);
+ *     }
+ *   }, []);
+ *
+ *   return (
+ *     <ModalProvider ref={modalRef}>
+ *       <div className="app-layout">
+ *         <main>Main Content</main>
+ *         <div ref={containerRef} className="modal-container" />
+ *       </div>
+ *     </ModalProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * With routing integration:
+ * ```tsx
+ * import { useLocation } from 'react-router-dom';
+ *
+ * function useRouterPathname() {
+ *   const location = useLocation();
+ *   return { pathname: location.pathname };
+ * }
+ *
+ * <ModalProvider usePathname={useRouterPathname}>
+ *   <RouterApp />
+ * </ModalProvider>
+ * ```
+ *
+ * @example
+ * Sharing context with modals:
+ * ```tsx
+ * const ThemeContext = createContext({ theme: 'light' });
+ *
+ * function ThemedModal() {
+ *   const { theme } = useContext(ThemeContext);
+ *   return <div className={`modal-${theme}`}>...</div>;
+ * }
+ *
+ * <ModalProvider
+ *   context={{ userId: currentUser.id }}
+ *   ContentComponent={({ children, context }) => (
+ *     <ThemeContext.Provider value={{ theme: context.theme }}>
+ *       {children}
+ *     </ThemeContext.Provider>
+ *   )}
+ * >
+ *   <App />
+ * </ModalProvider>
+ * ```
+ *
+ * @remarks
+ * - Without a ref, the provider initializes automatically on mount
+ * - With a ref, you must call `initialize()` manually with target element
+ * - All modals created within this provider share the same configuration
+ * - The provider creates a portal for rendering modals outside the React tree
+ */
 export declare const BootstrapProvider: import("react").ForwardRefExoticComponent<{
     usePathname?: import("../../@aileron/declare").Fn<[], {
         pathname: string;

package/dist/bootstrap/BootstrapProvider/useBootstrap.d.ts

@@ -1,4 +1,186 @@
 import type { BootstrapProviderProps } from './type';
+/**
+ * Hook for bootstrapping the promise-modal system without a provider component.
+ *
+ * Provides the same functionality as BootstrapProvider but as a hook, allowing
+ * more flexible integration patterns. Returns a portal element and an initialize
+ * function for manual control.
+ *
+ * @param props - Configuration options (same as BootstrapProvider)
+ * @param props.mode - 'auto' for automatic initialization, 'manual' for explicit control
+ * @returns Object containing portal element and initialize function
+ *
+ * @example
+ * Basic usage with automatic initialization:
+ * ```tsx
+ * function App() {
+ *   const { portal } = useBootstrap({
+ *     options: {
+ *       duration: 200,
+ *       backdrop: 'rgba(0, 0, 0, 0.8)',
+ *     },
+ *   });
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => alert({ title: 'Hello!' })}>Alert</button>
+ *       <button onClick={() => confirm({ title: 'Confirm?' })}>Confirm</button>
+ *       {portal}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Manual initialization with custom container:
+ * ```tsx
+ * function CustomModalApp() {
+ *   const { portal, initialize } = useBootstrap({
+ *     mode: 'manual',
+ *     ForegroundComponent: CustomModal,
+ *     options: {
+ *       closeOnBackdropClick: false,
+ *     },
+ *   });
+ *
+ *   useEffect(() => {
+ *     const container = document.getElementById('modal-root');
+ *     if (container) {
+ *       initialize(container);
+ *     }
+ *   }, [initialize]);
+ *
+ *   return (
+ *     <div>
+ *       <main>App Content</main>
+ *       <div id="modal-root" />
+ *       {portal}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Integration with state management:
+ * ```tsx
+ * function ConnectedApp() {
+ *   const user = useSelector(selectCurrentUser);
+ *   const theme = useSelector(selectTheme);
+ *
+ *   const { portal } = useBootstrap({
+ *     context: { userId: user?.id, theme },
+ *     ContentComponent: ({ children, context }) => (
+ *       <div data-theme={context.theme}>
+ *         {children}
+ *       </div>
+ *     ),
+ *   });
+ *
+ *   const handleDelete = async () => {
+ *     const confirmed = await confirm({
+ *       title: 'Delete Account',
+ *       content: `Are you sure, ${user.name}?`,
+ *     });
+ *     if (confirmed) {
+ *       dispatch(deleteAccount());
+ *     }
+ *   };
+ *
+ *   return (
+ *     <>
+ *       <button onClick={handleDelete}>Delete Account</button>
+ *       {portal}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Multiple modal systems:
+ * ```tsx
+ * function MultiModalApp() {
+ *   // System modals (errors, confirmations)
+ *   const { portal: systemPortal } = useBootstrap({
+ *     ForegroundComponent: SystemModal,
+ *     options: { backdrop: 'rgba(255, 0, 0, 0.8)' },
+ *   });
+ *
+ *   // Feature modals (forms, wizards)
+ *   const { portal: featurePortal } = useBootstrap({
+ *     ForegroundComponent: FeatureModal,
+ *     options: { backdrop: 'rgba(0, 0, 255, 0.8)' },
+ *   });
+ *
+ *   return (
+ *     <>
+ *       <SystemSection />
+ *       <FeatureSection />
+ *       {systemPortal}
+ *       {featurePortal}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * With custom hooks for specific modal types:
+ * ```tsx
+ * function useConfirmDialog() {
+ *   const { portal } = useBootstrap({
+ *     TitleComponent: ({ children }) => (
+ *       <h3 className="confirm-title">
+ *         <Icon name="warning" />
+ *         {children}
+ *       </h3>
+ *     ),
+ *     FooterComponent: ({ onConfirm, onClose }) => (
+ *       <div className="confirm-footer">
+ *         <button onClick={onClose}>Cancel</button>
+ *         <button onClick={onConfirm} className="danger">
+ *           Confirm
+ *         </button>
+ *       </div>
+ *     ),
+ *   });
+ *
+ *   const confirmAction = useCallback(
+ *     (title: string, content: string) => {
+ *       return confirm({ title, content });
+ *     },
+ *     [],
+ *   );
+ *
+ *   return { portal, confirmAction };
+ * }
+ *
+ * function App() {
+ *   const { portal, confirmAction } = useConfirmDialog();
+ *
+ *   const handleDelete = async () => {
+ *     const confirmed = await confirmAction(
+ *       'Delete Item',
+ *       'This action cannot be undone.',
+ *     );
+ *     if (confirmed) {
+ *       // Perform deletion
+ *     }
+ *   };
+ *
+ *   return (
+ *     <>
+ *       <button onClick={handleDelete}>Delete</button>
+ *       {portal}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @remarks
+ * - Use `mode: 'manual'` when you need to control the initialization timing
+ * - The portal element must be rendered in your component tree
+ * - Each hook instance creates an independent modal system
+ * - Context changes will affect all modals created after the change
+ */
 export declare const useBootstrap: ({ usePathname: useExternalPathname, ForegroundComponent, BackgroundComponent, TitleComponent, SubtitleComponent, ContentComponent, FooterComponent, options, context, mode, }?: BootstrapProviderProps & {
     mode?: "manual" | "auto";
 }) => {

package/dist/core/handle/alert.d.ts

@@ -1,12 +1,12 @@
 import type { ComponentType, ReactNode } from 'react';
 import type { AlertContentProps, AlertFooterRender, BackgroundComponent, FooterOptions, ForegroundComponent, ModalBackground } from '../../types';
-interface AlertProps<B> {
+interface AlertProps<BackgroundValue> {
     group?: string;
     subtype?: 'info' | 'success' | 'warning' | 'error';
     title?: ReactNode;
     subtitle?: ReactNode;
     content?: ReactNode | ComponentType<AlertContentProps>;
-    background?: ModalBackground<B>;
+    background?: ModalBackground<BackgroundValue>;
     footer?: AlertFooterRender | Pick<FooterOptions, 'confirm' | 'hideConfirm'> | false;
     dimmed?: boolean;
     manualDestroy?: boolean;
@@ -14,5 +14,146 @@ interface AlertProps<B> {
     ForegroundComponent?: ForegroundComponent;
     BackgroundComponent?: BackgroundComponent;
 }
-export declare const alert: <B = any>({ group, subtype, title, subtitle, content, background, footer, dimmed, manualDestroy, closeOnBackdropClick, ForegroundComponent, BackgroundComponent, }: AlertProps<B>) => Promise<void>;
+/**
+ * Displays a promise-based alert modal that resolves when the user acknowledges.
+ *
+ * Creates a modal dialog with a single action button (typically "OK" or "Confirm").
+ * The promise resolves when the user clicks the button or closes the modal.
+ *
+ * @typeParam BackgroundValue - Type of background data passed to BackgroundComponent
+ * @param props - Alert configuration options
+ * @returns Promise that resolves when the alert is dismissed
+ *
+ * @example
+ * Basic alert:
+ * ```tsx
+ * await alert({
+ *   title: 'Success!',
+ *   content: 'Your changes have been saved.',
+ * });
+ * console.log('Alert closed');
+ * ```
+ *
+ * @example
+ * Alert with subtype styling:
+ * ```tsx
+ * // Error alert
+ * alert({
+ *   subtype: 'error',
+ *   title: 'Operation Failed',
+ *   content: 'Unable to connect to server. Please try again later.',
+ * });
+ *
+ * // Success alert
+ * alert({
+ *   subtype: 'success',
+ *   title: 'Upload Complete',
+ *   content: 'Your file has been successfully uploaded.',
+ * });
+ *
+ * // Warning alert
+ * alert({
+ *   subtype: 'warning',
+ *   title: 'Storage Almost Full',
+ *   content: 'You have used 90% of your storage quota.',
+ * });
+ * ```
+ *
+ * @example
+ * Custom content component:
+ * ```tsx
+ * const ErrorDetails = ({ onConfirm }) => (
+ *   <div className="error-details">
+ *     <p>Error Code: 500</p>
+ *     <p>Time: {new Date().toLocaleString()}</p>
+ *     <details>
+ *       <summary>Stack Trace</summary>
+ *       <pre>{error.stack}</pre>
+ *     </details>
+ *   </div>
+ * );
+ *
+ * alert({
+ *   title: 'Application Error',
+ *   content: ErrorDetails,
+ *   subtype: 'error',
+ * });
+ * ```
+ *
+ * @example
+ * Custom footer:
+ * ```tsx
+ * alert({
+ *   title: 'Terms Updated',
+ *   content: 'Our terms of service have been updated.',
+ *   footer: ({ onConfirm, context }) => (
+ *     <div className="custom-footer">
+ *       <a href="/terms" target="_blank">Read Terms</a>
+ *       <button onClick={onConfirm}>I Understand</button>
+ *     </div>
+ *   ),
+ * });
+ * ```
+ *
+ * @example
+ * Alert with background animation:
+ * ```tsx
+ * alert({
+ *   title: 'Achievement Unlocked!',
+ *   content: 'You completed your first task!',
+ *   background: {
+ *     data: { type: 'confetti', color: 'gold' },
+ *   },
+ *   BackgroundComponent: ({ background, visible }) => (
+ *     <ConfettiAnimation
+ *       active={visible}
+ *       color={background.data.color}
+ *     />
+ *   ),
+ * });
+ * ```
+ *
+ * @example
+ * Non-closeable critical alert:
+ * ```tsx
+ * alert({
+ *   title: 'System Maintenance',
+ *   content: 'The system will restart in 5 minutes. Please save your work.',
+ *   closeOnBackdropClick: false,
+ *   footer: {
+ *     confirm: 'Got it',
+ *   },
+ *   manualDestroy: true,
+ * });
+ * ```
+ *
+ * @example
+ * Chaining alerts:
+ * ```tsx
+ * async function showWelcomeTour() {
+ *   await alert({
+ *     title: 'Welcome!',
+ *     content: 'Let\'s take a quick tour of the app.',
+ *   });
+ *
+ *   await alert({
+ *     title: 'Dashboard',
+ *     content: 'This is where you\'ll see your daily summary.',
+ *   });
+ *
+ *   await alert({
+ *     title: 'Get Started',
+ *     content: 'You\'re all set! Start exploring the app.',
+ *     subtype: 'success',
+ *   });
+ * }
+ * ```
+ *
+ * @remarks
+ * - The promise always resolves (never rejects) unless an error occurs during modal creation
+ * - Use `manualDestroy: true` to keep the modal in DOM after closing (for animations)
+ * - Set `closeOnBackdropClick: false` to prevent closing by clicking outside
+ * - The `group` prop can be used to manage multiple related modals
+ */
+export declare const alert: <BackgroundValue = any>({ group, subtype, title, subtitle, content, background, footer, dimmed, manualDestroy, closeOnBackdropClick, ForegroundComponent, BackgroundComponent, }: AlertProps<BackgroundValue>) => Promise<void>;
 export {};

package/dist/core/handle/confirm.d.ts

@@ -1,12 +1,12 @@
 import type { ComponentType, ReactNode } from 'react';
 import type { BackgroundComponent, ConfirmContentProps, ConfirmFooterRender, FooterOptions, ForegroundComponent, ModalBackground } from '../../types';
-interface ConfirmProps<B> {
+interface ConfirmProps<BackgroundValue> {
     group?: string;
     subtype?: 'info' | 'success' | 'warning' | 'error';
     title?: ReactNode;
     subtitle?: ReactNode;
     content?: ReactNode | ComponentType<ConfirmContentProps>;
-    background?: ModalBackground<B>;
+    background?: ModalBackground<BackgroundValue>;
     footer?: ConfirmFooterRender | FooterOptions | false;
     dimmed?: boolean;
     manualDestroy?: boolean;
@@ -14,5 +14,152 @@ interface ConfirmProps<B> {
     ForegroundComponent?: ForegroundComponent;
     BackgroundComponent?: BackgroundComponent;
 }
-export declare const confirm: <B = any>({ group, subtype, title, subtitle, content, background, footer, dimmed, manualDestroy, closeOnBackdropClick, ForegroundComponent, BackgroundComponent, }: ConfirmProps<B>) => Promise<boolean>;
+/**
+ * Displays a promise-based confirmation modal that resolves with a boolean result.
+ *
+ * Creates a modal dialog with two action buttons (typically "OK/Cancel" or "Yes/No").
+ * The promise resolves with `true` when confirmed, `false` when cancelled.
+ *
+ * @typeParam BackgroundValue - Type of background data passed to BackgroundComponent
+ * @param props - Confirmation dialog configuration options
+ * @returns Promise that resolves to true if confirmed, false if cancelled
+ *
+ * @example
+ * Basic confirmation:
+ * ```tsx
+ * const shouldDelete = await confirm({
+ *   title: 'Delete Item?',
+ *   content: 'This action cannot be undone.',
+ * });
+ *
+ * if (shouldDelete) {
+ *   await deleteItem();
+ * }
+ * ```
+ *
+ * @example
+ * Destructive action with warning:
+ * ```tsx
+ * const shouldProceed = await confirm({
+ *   subtype: 'error',
+ *   title: 'Delete Account',
+ *   content: 'Are you sure you want to delete your account? All data will be permanently lost.',
+ *   footer: {
+ *     confirm: 'Delete Account',
+ *     cancel: 'Keep Account',
+ *     confirmDanger: true,
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * Custom content with details:
+ * ```tsx
+ * const ConfirmDetails = ({ onConfirm, onCancel }) => (
+ *   <div>
+ *     <p>The following items will be affected:</p>
+ *     <ul>
+ *       <li>15 documents</li>
+ *       <li>42 images</li>
+ *       <li>3 videos</li>
+ *     </ul>
+ *     <p>Total size: 1.2 GB</p>
+ *   </div>
+ * );
+ *
+ * const confirmed = await confirm({
+ *   title: 'Move to Trash?',
+ *   content: ConfirmDetails,
+ * });
+ * ```
+ *
+ * @example
+ * Custom footer with additional actions:
+ * ```tsx
+ * confirm({
+ *   title: 'Save Changes?',
+ *   content: 'You have unsaved changes.',
+ *   footer: ({ onConfirm, onCancel, context }) => (
+ *     <div className="save-dialog-footer">
+ *       <button onClick={onCancel}>Don\'t Save</button>
+ *       <button onClick={() => {
+ *         saveAsDraft();
+ *         onCancel();
+ *       }}>Save as Draft</button>
+ *       <button onClick={onConfirm} className="primary">
+ *         Save and Publish
+ *       </button>
+ *     </div>
+ *   ),
+ * });
+ * ```
+ *
+ * @example
+ * Conditional confirmation flow:
+ * ```tsx
+ * async function deleteWithConfirmation(item) {
+ *   // First confirmation
+ *   const confirmDelete = await confirm({
+ *     title: `Delete "${item.name}"?`,
+ *     content: 'This item will be moved to trash.',
+ *   });
+ *
+ *   if (!confirmDelete) return;
+ *
+ *   // Check if item has dependencies
+ *   if (item.dependencies.length > 0) {
+ *     const confirmForce = await confirm({
+ *       subtype: 'warning',
+ *       title: 'Item has dependencies',
+ *       content: `${item.dependencies.length} other items depend on this. Delete anyway?`,
+ *       footer: {
+ *         confirm: 'Force Delete',
+ *         confirmDanger: true,
+ *       },
+ *     });
+ *
+ *     if (!confirmForce) return;
+ *   }
+ *
+ *   await deleteItem(item.id);
+ * }
+ * ```
+ *
+ * @example
+ * With loading state:
+ * ```tsx
+ * const shouldExport = await confirm({
+ *   title: 'Export Data',
+ *   content: 'Export may take several minutes for large datasets.',
+ *   footer: ({ onConfirm, onCancel }) => {
+ *     const [loading, setLoading] = useState(false);
+ *
+ *     const handleExport = async () => {
+ *       setLoading(true);
+ *       await startExport();
+ *       onConfirm();
+ *     };
+ *
+ *     return (
+ *       <>
+ *         <button onClick={onCancel}>Cancel</button>
+ *         <button
+ *           onClick={handleExport}
+ *           disabled={loading}
+ *         >
+ *           {loading ? 'Exporting...' : 'Start Export'}
+ *         </button>
+ *       </>
+ *     );
+ *   },
+ * });
+ * ```
+ *
+ * @remarks
+ * - Returns `true` only when explicitly confirmed via the confirm action
+ * - Returns `false` for cancel action or backdrop click (if enabled)
+ * - Use `subtype` to indicate severity (error for destructive actions)
+ * - The `footer` prop allows complete customization of button layout and behavior
+ */
+export declare const confirm: <BackgroundValue = any>({ group, subtype, title, subtitle, content, background, footer, dimmed, manualDestroy, closeOnBackdropClick, ForegroundComponent, BackgroundComponent, }: ConfirmProps<BackgroundValue>) => Promise<boolean>;
 export {};