@lerx/promise-modal 0.8.4 → 0.8.5

package/README.md

@@ -868,6 +868,59 @@ function App() {
 
 ### Hooks
 
+#### `useModal`
+
+Returns modal handler functions that share the component's lifecycle.
+
+**Key Features:**
+
+Unlike static handlers (`alert`, `confirm`, `prompt`), modals created with `useModal` automatically clean up when the component unmounts. This is useful when you want to ensure that modals opened within a specific component are automatically closed when that component is removed.
+
+**Returns:**
+
+- `alert`: Alert modal handler function
+- `confirm`: Confirm modal handler function
+- `prompt`: Prompt modal handler function
+
+```typescript
+import { useModal } from '@lerx/promise-modal';
+
+function MyComponent() {
+  const modal = useModal();
+
+  const handleShowAlert = async () => {
+    // Modal will be automatically cleaned up when MyComponent unmounts
+    await modal.alert({
+      title: 'Notice',
+      content: 'This modal is tied to the component lifecycle.',
+    });
+  };
+
+  const handleShowConfirm = async () => {
+    const result = await modal.confirm({
+      title: 'Confirm',
+      content: 'Do you want to proceed?',
+    });
+    console.log('Result:', result);
+  };
+
+  return (
+    <div>
+      <button onClick={handleShowAlert}>Show Alert</button>
+      <button onClick={handleShowConfirm}>Show Confirm</button>
+    </div>
+  );
+}
+```
+
+**Comparison with Static Handlers:**
+
+| Feature        | Static Handlers               | useModal Hook                |
+| -------------- | ----------------------------- | ---------------------------- |
+| Lifecycle      | Independent of components     | Tied to component lifecycle  |
+| Cleanup        | Manual cleanup required       | Automatic cleanup on unmount |
+| Usage Location | Anywhere (even outside React) | Inside React components only |
+
 #### `useModalOptions`
 
 Read global options for modals.

package/dist/app/ModalManager.d.ts

@@ -1,4 +1,5 @@
 import type { Fn } from '../@aileron/declare';
+import type { ModalNode } from '../core';
 import type { Modal } from '../types';
 export declare class ModalManager {
     #private;
@@ -9,10 +10,12 @@ export declare class ModalManager {
     }): HTMLElement;
     static get anchored(): boolean;
     static get prerender(): Modal[];
-    static set openHandler(handler: Fn<[Modal], void>);
+    static set openHandler(handler: Fn<[Modal], ModalNode>);
+    static set refreshHandler(handler: Fn<[], void>);
+    static refresh(): void;
     static defineStyleSheet(styleId: string, css: string): void;
     static applyStyleSheet(): void;
     static getHashedClassNames(styleId: string): string;
     static reset(): void;
-    static open(modal: Modal): void;
+    static open(modal: Modal): ModalNode;
 }

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

@@ -1,159 +1,27 @@
-import type { ComponentType, ReactNode } from 'react';
-import type { AlertContentProps, AlertFooterRender, BackgroundComponent, FooterOptions, ForegroundComponent, ModalBackground } from '../../types';
-interface AlertProps<BackgroundValue> {
-    group?: string;
-    subtype?: 'info' | 'success' | 'warning' | 'error';
-    title?: ReactNode;
-    subtitle?: ReactNode;
-    content?: ReactNode | ComponentType<AlertContentProps>;
-    background?: ModalBackground<BackgroundValue>;
-    footer?: AlertFooterRender | Pick<FooterOptions, 'confirm' | 'hideConfirm'> | false;
-    dimmed?: boolean;
-    manualDestroy?: boolean;
-    closeOnBackdropClick?: boolean;
-    ForegroundComponent?: ForegroundComponent;
-    BackgroundComponent?: BackgroundComponent;
-}
+import type { AlertNode } from '../../core';
+import type { AlertProps } from './type';
 /**
- * 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.
+ * Creates and manages an Alert 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>
- *   ),
- * });
- * ```
+ * @param args - Alert modal configuration options
+ * @returns Object containing modalNode and promiseHandler
  *
- * @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}
- *     />
- *   ),
- * });
- * ```
+ * @remarks
+ * - modalNode: The created modal node instance
+ * - promiseHandler: Promise that resolves when the modal is closed
  *
  * @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,
+ * const { modalNode, promiseHandler } = alertHandler({
+ *   title: 'Success',
+ *   content: 'Operation completed successfully!',
  * });
- * ```
  *
- * @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',
- *   });
- * }
+ * await promiseHandler; // Wait until modal is closed
  * ```
- *
- * @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 {};
+export declare const alertHandler: <BackgroundValue = any>(args: AlertProps<BackgroundValue>) => {
+    readonly modalNode: AlertNode<BackgroundValue>;
+    readonly promiseHandler: Promise<void>;
+};

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

@@ -1,165 +1,32 @@
-import type { ComponentType, ReactNode } from 'react';
-import type { BackgroundComponent, ConfirmContentProps, ConfirmFooterRender, FooterOptions, ForegroundComponent, ModalBackground } from '../../types';
-interface ConfirmProps<BackgroundValue> {
-    group?: string;
-    subtype?: 'info' | 'success' | 'warning' | 'error';
-    title?: ReactNode;
-    subtitle?: ReactNode;
-    content?: ReactNode | ComponentType<ConfirmContentProps>;
-    background?: ModalBackground<BackgroundValue>;
-    footer?: ConfirmFooterRender | FooterOptions | false;
-    dimmed?: boolean;
-    manualDestroy?: boolean;
-    closeOnBackdropClick?: boolean;
-    ForegroundComponent?: ForegroundComponent;
-    BackgroundComponent?: BackgroundComponent;
-}
+import type { ConfirmNode } from '../../core';
+import type { ConfirmProps } from './type';
 /**
- * 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.
+ * Creates and manages a Confirm modal.
  *
  * @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
+ * @param args - Confirm modal configuration options
+ * @returns Object containing modalNode and promiseHandler
+ *
+ * @remarks
+ * - modalNode: The created modal node instance
+ * - promiseHandler: Promise that resolves to true if confirmed, false if cancelled
+ * - Returns true only when explicitly confirmed via the confirm action
+ * - Returns false for cancel action or backdrop click (if enabled)
  *
  * @example
- * Basic confirmation:
  * ```tsx
- * const shouldDelete = await confirm({
+ * const { modalNode, promiseHandler } = confirmHandler({
  *   title: 'Delete Item?',
  *   content: 'This action cannot be undone.',
  * });
  *
- * if (shouldDelete) {
+ * const confirmed = await promiseHandler;
+ * if (confirmed) {
  *   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 {};
+export declare const confirmHandler: <BackgroundValue = any>(args: ConfirmProps<BackgroundValue>) => {
+    readonly modalNode: ConfirmNode<BackgroundValue>;
+    readonly promiseHandler: Promise<boolean>;
+};

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

@@ -1,3 +1,5 @@
-export { alert } from './alert';
-export { confirm } from './confirm';
-export { prompt } from './prompt';
+export { alertHandler } from './alert';
+export { confirmHandler } from './confirm';
+export { promptHandler } from './prompt';
+export { alert, confirm, prompt } from './static';
+export type { AlertProps, ConfirmProps, PromptProps } from './type';