@lerx/promise-modal 0.8.3 → 0.8.5

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

@@ -1,234 +1,45 @@
-import type { ComponentType, ReactNode } from 'react';
-import type { Fn } from '../../@aileron/declare';
-import type { BackgroundComponent, FooterOptions, ForegroundComponent, ModalBackground, PromptContentProps, PromptFooterRender, PromptInputProps } from '../../types';
-interface PromptProps<InputValue, BackgroundValue = any> {
-    group?: string;
-    title?: ReactNode;
-    subtitle?: ReactNode;
-    content?: ReactNode | ComponentType<PromptContentProps>;
-    defaultValue?: InputValue;
-    Input: Fn<[props: PromptInputProps<InputValue>], ReactNode>;
-    disabled?: Fn<[value: InputValue], boolean>;
-    returnOnCancel?: boolean;
-    background?: ModalBackground<BackgroundValue>;
-    footer?: PromptFooterRender<InputValue> | FooterOptions | false;
-    dimmed?: boolean;
-    manualDestroy?: boolean;
-    closeOnBackdropClick?: boolean;
-    ForegroundComponent?: ForegroundComponent;
-    BackgroundComponent?: BackgroundComponent;
-}
+import type { PromptNode } from '../../core';
+import type { PromptProps } from './type';
 /**
- * Displays a promise-based prompt modal that collects user input.
- *
- * Creates a modal dialog with a custom input component and confirmation/cancel buttons.
- * The promise resolves with the input value when confirmed, or rejects when cancelled
- * (unless `returnOnCancel` is true).
+ * Creates and manages a Prompt modal.
  *
  * @typeParam InputValue - Type of the value collected from user input
  * @typeParam BackgroundValue - Type of background data passed to BackgroundComponent
- * @param props - Prompt dialog configuration options
- * @returns Promise that resolves with the user's input value
- * @throws Rejects when cancelled (unless returnOnCancel is true)
+ * @param args - Prompt modal configuration options
+ * @returns Object containing modalNode and promiseHandler
+ *
+ * @remarks
+ * - modalNode: The created modal node instance
+ * - promiseHandler: Promise that resolves with user input value
+ * - Input component receives value, onChange, onConfirm, onCancel, and context props
+ * - Use disabled function to control confirm button's enabled state
+ * - If returnOnCancel is false (default), promise rejects on cancel
+ * - If returnOnCancel is true, returns defaultValue on cancel
  *
  * @example
- * Basic text input:
  * ```tsx
- * const name = await prompt<string>({
+ * const { modalNode, promiseHandler } = promptHandler<string>({
  *   title: 'Enter Your Name',
- *   content: 'Please enter your full name for the certificate.',
  *   Input: ({ value, onChange, onConfirm }) => (
  *     <input
  *       type="text"
  *       value={value || ''}
  *       onChange={(e) => onChange(e.target.value)}
  *       onKeyPress={(e) => e.key === 'Enter' && onConfirm()}
- *       autoFocus
- *     />
- *   ),
- *   defaultValue: 'John Doe',
- * });
- * ```
- *
- * @example
- * Number input with validation:
- * ```tsx
- * const age = await prompt<number>({
- *   title: 'Enter Your Age',
- *   content: 'Must be between 18 and 100',
- *   Input: ({ value, onChange }) => (
- *     <input
- *       type="number"
- *       min="18"
- *       max="100"
- *       value={value || ''}
- *       onChange={(e) => onChange(parseInt(e.target.value))}
  *     />
  *   ),
- *   disabled: (value) => !value || value < 18 || value > 100,
- *   defaultValue: 25,
+ *   defaultValue: '',
  * });
- * ```
- *
- * @example
- * Select dropdown:
- * ```tsx
- * interface Theme {
- *   id: string;
- *   name: string;
- *   primary: string;
- * }
- *
- * const theme = await prompt<Theme>({
- *   title: 'Choose Theme',
- *   Input: ({ value, onChange }) => (
- *     <select
- *       value={value?.id || ''}
- *       onChange={(e) => {
- *         const selected = themes.find(t => t.id === e.target.value);
- *         onChange(selected);
- *       }}
- *     >
- *       <option value="">Select a theme...</option>
- *       {themes.map(theme => (
- *         <option key={theme.id} value={theme.id}>
- *           {theme.name}
- *         </option>
- *       ))}
- *     </select>
- *   ),
- *   disabled: (value) => !value,
- * });
- * ```
  *
- * @example
- * Multi-field form:
- * ```tsx
- * interface UserData {
- *   username: string;
- *   email: string;
- *   subscribe: boolean;
- * }
- *
- * const userData = await prompt<UserData>({
- *   title: 'Create Account',
- *   Input: ({ value, onChange }) => {
- *     const data = value || { username: '', email: '', subscribe: false };
- *
- *     return (
- *       <div className="form">
- *         <input
- *           placeholder="Username"
- *           value={data.username}
- *           onChange={(e) => onChange({ ...data, username: e.target.value })}
- *         />
- *         <input
- *           type="email"
- *           placeholder="Email"
- *           value={data.email}
- *           onChange={(e) => onChange({ ...data, email: e.target.value })}
- *         />
- *         <label>
- *           <input
- *             type="checkbox"
- *             checked={data.subscribe}
- *             onChange={(e) => onChange({ ...data, subscribe: e.target.checked })}
- *           />
- *           Subscribe to newsletter
- *         </label>
- *       </div>
- *     );
- *   },
- *   disabled: (value) => !value?.username || !value?.email,
- * });
- * ```
- *
- * @example
- * File upload:
- * ```tsx
- * const file = await prompt<File>({
- *   title: 'Upload Avatar',
- *   content: 'Select an image file (max 5MB)',
- *   Input: ({ value, onChange }) => (
- *     <div>
- *       <input
- *         type="file"
- *         accept="image/*"
- *         onChange={(e) => {
- *           const file = e.target.files?.[0];
- *           if (file && file.size <= 5 * 1024 * 1024) {
- *             onChange(file);
- *           }
- *         }}
- *       />
- *       {value && (
- *         <div>
- *           <img src={URL.createObjectURL(value)} alt="Preview" />
- *           <p>{value.name} ({(value.size / 1024).toFixed(1)} KB)</p>
- *         </div>
- *       )}
- *     </div>
- *   ),
- *   disabled: (value) => !value,
- * });
- * ```
- *
- * @example
- * With error handling:
- * ```tsx
  * try {
- *   const email = await prompt<string>({
- *     title: 'Reset Password',
- *     content: 'Enter your email to receive a reset link',
- *     Input: ({ value, onChange, context }) => (
- *       <EmailInput
- *         value={value}
- *         onChange={onChange}
- *         error={context.error}
- *       />
- *     ),
- *   });
- *
- *   await sendResetEmail(email);
- * } catch (error) {
- *   // User cancelled the prompt
- *   console.log('Password reset cancelled');
+ *   const name = await promiseHandler;
+ *   console.log('User entered:', name);
+ * } catch {
+ *   console.log('User cancelled');
  * }
  * ```
- *
- * @example
- * Custom footer with validation:
- * ```tsx
- * const password = await prompt<string>({
- *   title: 'Set New Password',
- *   Input: ({ value, onChange }) => (
- *     <PasswordInput value={value} onChange={onChange} />
- *   ),
- *   footer: ({ value, onChange, onConfirm, onCancel, disabled }) => (
- *     <div>
- *       <PasswordStrength password={value} />
- *       <div className="buttons">
- *         <button onClick={onCancel}>Cancel</button>
- *         <button
- *           onClick={onConfirm}
- *           disabled={disabled}
- *           className={disabled ? 'disabled' : 'primary'}
- *         >
- *           Set Password
- *         </button>
- *       </div>
- *     </div>
- *   ),
- *   disabled: (value) => !value || value.length < 8,
- * });
- * ```
- *
- * @remarks
- * - The Input component receives value, onChange, onConfirm, onCancel, and context props
- * - Use the `disabled` function to control when the confirm button is enabled
- * - Set `returnOnCancel: true` to return defaultValue instead of rejecting on cancel
- * - The promise rejects when cancelled (unless returnOnCancel is set)
- * - Use onConfirm prop in Input to handle Enter key submission
  */
-export declare const prompt: <InputValue, BackgroundValue = any>({ group, title, subtitle, content, defaultValue, Input, disabled, returnOnCancel, background, footer, dimmed, manualDestroy, closeOnBackdropClick, ForegroundComponent, BackgroundComponent, }: PromptProps<InputValue, BackgroundValue>) => Promise<InputValue>;
-export {};
+export declare const promptHandler: <InputValue, BackgroundValue = any>(args: PromptProps<InputValue, BackgroundValue>) => {
+    readonly modalNode: PromptNode<InputValue, BackgroundValue>;
+    readonly promiseHandler: Promise<InputValue>;
+};

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

@@ -0,0 +1,105 @@
+import type { AlertProps, ConfirmProps, PromptProps } from './type';
+/**
+ * Displays a promise-based alert modal.
+ *
+ * @typeParam BackgroundValue - Type of background data passed to BackgroundComponent
+ * @param args - Alert modal configuration options
+ * @returns Promise that resolves when the modal is closed
+ *
+ * @example
+ * ```tsx
+ * await alert({
+ *   title: 'Success!',
+ *   content: 'Your changes have been saved.',
+ * });
+ * ```
+ *
+ * @example
+ * With subtype styling:
+ * ```tsx
+ * alert({
+ *   subtype: 'error',
+ *   title: 'Operation Failed',
+ *   content: 'Unable to connect to server.',
+ * });
+ * ```
+ */
+export declare const alert: <BackgroundValue = any>(args: AlertProps<BackgroundValue>) => Promise<void>;
+/**
+ * Displays a promise-based confirmation modal with boolean result.
+ *
+ * @typeParam BackgroundValue - Type of background data passed to BackgroundComponent
+ * @param args - Confirmation modal configuration options
+ * @returns Promise that resolves to true if confirmed, false if cancelled
+ *
+ * @example
+ * ```tsx
+ * const shouldDelete = await confirm({
+ *   title: 'Delete Item?',
+ *   content: 'This action cannot be undone.',
+ * });
+ *
+ * if (shouldDelete) {
+ *   await deleteItem();
+ * }
+ * ```
+ *
+ * @example
+ * Destructive action warning:
+ * ```tsx
+ * const shouldProceed = await confirm({
+ *   subtype: 'error',
+ *   title: 'Delete Account',
+ *   content: 'All data will be permanently lost.',
+ *   footer: {
+ *     confirm: 'Delete Account',
+ *     cancel: 'Keep Account',
+ *     confirmDanger: true,
+ *   },
+ * });
+ * ```
+ */
+export declare const confirm: <BackgroundValue = any>(args: ConfirmProps<BackgroundValue>) => Promise<boolean>;
+/**
+ * Displays a promise-based prompt modal to collect user input.
+ *
+ * @typeParam InputValue - Type of the value collected from user input
+ * @typeParam BackgroundValue - Type of background data passed to BackgroundComponent
+ * @param args - Prompt modal configuration options
+ * @returns Promise that resolves with user input value
+ * @throws Rejects when cancelled (unless returnOnCancel is true)
+ *
+ * @example
+ * ```tsx
+ * const name = await prompt<string>({
+ *   title: 'Enter Your Name',
+ *   Input: ({ value, onChange, onConfirm }) => (
+ *     <input
+ *       type="text"
+ *       value={value || ''}
+ *       onChange={(e) => onChange(e.target.value)}
+ *       onKeyPress={(e) => e.key === 'Enter' && onConfirm()}
+ *       autoFocus
+ *     />
+ *   ),
+ *   defaultValue: 'John Doe',
+ * });
+ * ```
+ *
+ * @example
+ * Number input with validation:
+ * ```tsx
+ * const age = await prompt<number>({
+ *   title: 'Enter Your Age',
+ *   Input: ({ value, onChange }) => (
+ *     <input
+ *       type="number"
+ *       value={value || ''}
+ *       onChange={(e) => onChange(parseInt(e.target.value))}
+ *     />
+ *   ),
+ *   disabled: (value) => !value || value < 18 || value > 100,
+ * });
+ * ```
+ */
+export declare const prompt: <InputValue, BackgroundValue = any>(args: PromptProps<InputValue, BackgroundValue>) => Promise<InputValue>;

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

@@ -0,0 +1,99 @@
+import type { ComponentType, ReactNode } from 'react';
+import type { Fn } from '../../@aileron/declare';
+import type { AlertContentProps, AlertFooterRender, BackgroundComponent, ConfirmContentProps, ConfirmFooterRender, FooterOptions, ForegroundComponent, ModalBackground, PromptContentProps, PromptFooterRender, PromptInputProps } from '../../types';
+export interface AlertProps<BackgroundValue> {
+    /** Modal group identifier for managing related modals */
+    group?: string;
+    /** Alert subtype that affects UI styling */
+    subtype?: 'info' | 'success' | 'warning' | 'error';
+    /** Modal title */
+    title?: ReactNode;
+    /** Modal subtitle */
+    subtitle?: ReactNode;
+    /** Modal content. Can be a ReactNode or a component */
+    content?: ReactNode | ComponentType<AlertContentProps>;
+    /** Background layer data and configuration */
+    background?: ModalBackground<BackgroundValue>;
+    /** Footer configuration. Can be a render function, options object, or false */
+    footer?: AlertFooterRender | Pick<FooterOptions, 'confirm' | 'hideConfirm'> | false;
+    /** Abort signal to cancel the modal */
+    signal?: AbortSignal;
+    /** Whether to dim the background */
+    dimmed?: boolean;
+    /** Modal animation duration in milliseconds */
+    duration?: number;
+    /** If true, keeps modal in DOM after closing (for animations) */
+    manualDestroy?: boolean;
+    /** Whether to close modal on backdrop click */
+    closeOnBackdropClick?: boolean;
+    /** Custom foreground component */
+    ForegroundComponent?: ForegroundComponent;
+    /** Custom background component */
+    BackgroundComponent?: BackgroundComponent;
+}
+export interface ConfirmProps<BackgroundValue> {
+    /** Modal group identifier for managing related modals */
+    group?: string;
+    /** Confirmation subtype that affects UI styling */
+    subtype?: 'info' | 'success' | 'warning' | 'error';
+    /** Modal title */
+    title?: ReactNode;
+    /** Modal subtitle */
+    subtitle?: ReactNode;
+    /** Modal content. Can be a ReactNode or a component */
+    content?: ReactNode | ComponentType<ConfirmContentProps>;
+    /** Background layer data and configuration */
+    background?: ModalBackground<BackgroundValue>;
+    /** Footer configuration. Can be a render function, options object, or false */
+    footer?: ConfirmFooterRender | FooterOptions | false;
+    /** Abort signal to cancel the modal */
+    signal?: AbortSignal;
+    /** Whether to dim the background */
+    dimmed?: boolean;
+    /** Modal animation duration in milliseconds */
+    duration?: number;
+    /** If true, keeps modal in DOM after closing (for animations) */
+    manualDestroy?: boolean;
+    /** Whether to close modal on backdrop click */
+    closeOnBackdropClick?: boolean;
+    /** Custom foreground component */
+    ForegroundComponent?: ForegroundComponent;
+    /** Custom background component */
+    BackgroundComponent?: BackgroundComponent;
+}
+export interface PromptProps<InputValue, BackgroundValue = any> {
+    /** Modal group identifier for managing related modals */
+    group?: string;
+    /** Modal title */
+    title?: ReactNode;
+    /** Modal subtitle */
+    subtitle?: ReactNode;
+    /** Modal content. Can be a ReactNode or a component */
+    content?: ReactNode | ComponentType<PromptContentProps>;
+    /** Initial value for the input field */
+    defaultValue?: InputValue;
+    /** Input component that receives value, onChange, and other props */
+    Input: Fn<[props: PromptInputProps<InputValue>], ReactNode>;
+    /** Validation function. Returns true to disable the confirm button */
+    disabled?: Fn<[value: InputValue], boolean>;
+    /** If true, returns defaultValue instead of rejecting on cancel */
+    returnOnCancel?: boolean;
+    /** Background layer data and configuration */
+    background?: ModalBackground<BackgroundValue>;
+    /** Footer configuration. Can be a render function, options object, or false */
+    footer?: PromptFooterRender<InputValue> | FooterOptions | false;
+    /** Abort signal to cancel the modal */
+    signal?: AbortSignal;
+    /** Whether to dim the background */
+    dimmed?: boolean;
+    /** Modal animation duration in milliseconds */
+    duration?: number;
+    /** If true, keeps modal in DOM after closing (for animations) */
+    manualDestroy?: boolean;
+    /** Whether to close modal on backdrop click */
+    closeOnBackdropClick?: boolean;
+    /** Custom foreground component */
+    ForegroundComponent?: ForegroundComponent;
+    /** Custom background component */
+    BackgroundComponent?: BackgroundComponent;
+}

package/dist/core/node/ModalNode/AbstractNode.d.ts

@@ -10,21 +10,23 @@ export declare abstract class AbstractNode<T, B> {
     readonly title?: ReactNode;
     readonly subtitle?: ReactNode;
     readonly background?: ModalBackground<B>;
+    readonly dimmed: boolean;
+    readonly duration: number;
     readonly manualDestroy: boolean;
     readonly closeOnBackdropClick: boolean;
-    readonly dimmed: boolean;
     readonly ForegroundComponent?: ForegroundComponent;
     readonly BackgroundComponent?: BackgroundComponent;
     get alive(): boolean;
     get visible(): boolean;
-    constructor({ id, initiator, group, title, subtitle, background, dimmed, manualDestroy, closeOnBackdropClick, resolve, ForegroundComponent, BackgroundComponent, }: AbstractNodeProps<T, B>);
+    set handleResolve(handleResolve: Fn<[result: T | null]>);
+    constructor({ id, initiator, group, title, subtitle, background, dimmed, duration, manualDestroy, closeOnBackdropClick, handleResolve, ForegroundComponent, BackgroundComponent, }: AbstractNodeProps<T, B>);
+    abstract onClose(): void;
+    abstract onConfirm(): void;
+    protected onResolve(result: T | null): void;
     subscribe(listener: Fn): () => void;
     publish(): void;
-    protected resolve(result: T | null): void;
     onDestroy(): void;
     onShow(): void;
     onHide(): void;
-    abstract onClose(): void;
-    abstract onConfirm(): void;
 }
 export {};

package/dist/core/node/ModalNode/AlertNode.d.ts

@@ -2,12 +2,12 @@ import type { ComponentType, ReactNode } from 'react';
 import type { AlertContentProps, AlertFooterRender, AlertModal, FooterOptions, ManagedEntity } from '../../../types';
 import { AbstractNode } from './AbstractNode';
 type AlertNodeProps<B> = AlertModal<B> & ManagedEntity;
-export declare class AlertNode<B> extends AbstractNode<null, B> {
+export declare class AlertNode<B = any> extends AbstractNode<null, B> {
     readonly type: 'alert';
     readonly subtype?: 'info' | 'success' | 'warning' | 'error';
     readonly content?: ReactNode | ComponentType<AlertContentProps>;
     readonly footer?: AlertFooterRender | Pick<FooterOptions, 'confirm' | 'hideConfirm'> | false;
-    constructor({ id, group, initiator, type, subtype, title, subtitle, content, footer, background, dimmed, manualDestroy, closeOnBackdropClick, resolve, ForegroundComponent, BackgroundComponent, }: AlertNodeProps<B>);
+    constructor({ id, group, initiator, type, subtype, title, subtitle, content, footer, background, dimmed, duration, manualDestroy, closeOnBackdropClick, handleResolve, ForegroundComponent, BackgroundComponent, }: AlertNodeProps<B>);
     onClose(): void;
     onConfirm(): void;
 }

package/dist/core/node/ModalNode/ConfirmNode.d.ts

@@ -2,12 +2,12 @@ import type { ComponentType, ReactNode } from 'react';
 import type { ConfirmContentProps, ConfirmFooterRender, ConfirmModal, FooterOptions, ManagedEntity } from '../../../types';
 import { AbstractNode } from './AbstractNode';
 type ConfirmNodeProps<B> = ConfirmModal<B> & ManagedEntity;
-export declare class ConfirmNode<B> extends AbstractNode<boolean, B> {
+export declare class ConfirmNode<B = any> extends AbstractNode<boolean, B> {
     readonly type: 'confirm';
     readonly subtype?: 'info' | 'success' | 'warning' | 'error';
     readonly content?: ReactNode | ComponentType<ConfirmContentProps>;
     readonly footer?: ConfirmFooterRender | FooterOptions | false;
-    constructor({ id, group, initiator, type, subtype, title, subtitle, content, footer, background, dimmed, manualDestroy, closeOnBackdropClick, resolve, ForegroundComponent, BackgroundComponent, }: ConfirmNodeProps<B>);
+    constructor({ id, group, initiator, type, subtype, title, subtitle, content, footer, background, dimmed, duration, manualDestroy, closeOnBackdropClick, handleResolve, ForegroundComponent, BackgroundComponent, }: ConfirmNodeProps<B>);
     onClose(): void;
     onConfirm(): void;
 }

package/dist/core/node/ModalNode/PromptNode.d.ts

@@ -3,7 +3,7 @@ import type { Fn } from '../../../@aileron/declare';
 import type { FooterOptions, ManagedEntity, PromptContentProps, PromptFooterRender, PromptInputProps, PromptModal } from '../../../types';
 import { AbstractNode } from './AbstractNode';
 type PromptNodeProps<T, B> = PromptModal<T, B> & ManagedEntity;
-export declare class PromptNode<T, B> extends AbstractNode<T, B> {
+export declare class PromptNode<T = any, B = any> extends AbstractNode<T, B> {
     #private;
     readonly type: 'prompt';
     readonly content?: ReactNode | ComponentType<PromptContentProps>;
@@ -12,7 +12,7 @@ export declare class PromptNode<T, B> extends AbstractNode<T, B> {
     readonly disabled?: Fn<[value: T], boolean>;
     readonly returnOnCancel?: boolean;
     readonly footer?: PromptFooterRender<T> | FooterOptions | false;
-    constructor({ id, group, initiator, type, title, subtitle, content, defaultValue, Input, disabled, returnOnCancel, footer, background, dimmed, manualDestroy, closeOnBackdropClick, resolve, ForegroundComponent, BackgroundComponent, }: PromptNodeProps<T, B>);
+    constructor({ id, group, initiator, type, title, subtitle, content, defaultValue, Input, disabled, returnOnCancel, footer, background, dimmed, duration, manualDestroy, closeOnBackdropClick, handleResolve, ForegroundComponent, BackgroundComponent, }: PromptNodeProps<T, B>);
     onChange(value: T): void;
     onConfirm(): void;
     onClose(): void;

package/dist/helpers/closeModal.d.ts

@@ -0,0 +1,2 @@
+import type { ModalNode } from '../core';
+export declare const closeModal: (modalNode: ModalNode, refresh?: boolean) => NodeJS.Timeout | undefined;

package/dist/helpers/subscribeAbortSignal.d.ts

@@ -0,0 +1,2 @@
+import type { ModalNode } from '../core';
+export declare const subscribeAbortSignal: (modalNode: ModalNode, signal: AbortSignal | undefined) => (() => void) | null;

package/dist/hooks/useModal.d.ts

@@ -0,0 +1,6 @@
+import { type AlertProps, type ConfirmProps, type PromptProps } from '../core';
+export declare const useModal: () => {
+    readonly alert: <BackgroundValue = any>(args: AlertProps<BackgroundValue>) => Promise<void>;
+    readonly confirm: <BackgroundValue = any>(args: ConfirmProps<BackgroundValue>) => Promise<boolean>;
+    readonly prompt: <InputValue, BackgroundValue = any>(args: PromptProps<InputValue, BackgroundValue>) => Promise<InputValue>;
+};