@lerx/promise-modal 0.2.8 → 0.3.0

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

@@ -1,21 +1,233 @@
 import type { ComponentType, ReactNode } from 'react';
 import type { BackgroundComponent, FooterOptions, ForegroundComponent, ModalBackground, PromptContentProps, PromptFooterRender, PromptInputProps } from '../../types';
-interface PromptProps<T, B = any> {
+interface PromptProps<InputValue, BackgroundValue = any> {
     group?: string;
     title?: ReactNode;
     subtitle?: ReactNode;
     content?: ReactNode | ComponentType<PromptContentProps>;
-    defaultValue?: T;
-    Input: (props: PromptInputProps<T>) => ReactNode;
-    disabled?: (value: T) => boolean;
+    defaultValue?: InputValue;
+    Input: (props: PromptInputProps<InputValue>) => ReactNode;
+    disabled?: (value: InputValue) => boolean;
     returnOnCancel?: boolean;
-    background?: ModalBackground<B>;
-    footer?: PromptFooterRender<T> | FooterOptions | false;
+    background?: ModalBackground<BackgroundValue>;
+    footer?: PromptFooterRender<InputValue> | FooterOptions | false;
     dimmed?: boolean;
     manualDestroy?: boolean;
     closeOnBackdropClick?: boolean;
     ForegroundComponent?: ForegroundComponent;
     BackgroundComponent?: BackgroundComponent;
 }
-export declare const prompt: <T, B = any>({ group, title, subtitle, content, defaultValue, Input, disabled, returnOnCancel, background, footer, dimmed, manualDestroy, closeOnBackdropClick, ForegroundComponent, BackgroundComponent, }: PromptProps<T, B>) => Promise<T>;
+/**
+ * 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).
+ *
+ * @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)
+ *
+ * @example
+ * Basic text input:
+ * ```tsx
+ * const name = await prompt<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,
+ * });
+ * ```
+ *
+ * @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');
+ * }
+ * ```
+ *
+ * @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 {};

package/dist/hooks/useActiveModalCount.d.ts

@@ -1,3 +1,166 @@
 import type { Fn } from '../@aileron/declare';
 import type { ModalNode } from '../core';
+/**
+ * Hook that counts the number of active modals based on a validation function.
+ *
+ * Provides a reactive count of modals that match specific criteria. By default,
+ * counts visible modals, but can be customized with any validation logic.
+ * Useful for managing overlays, z-index stacking, or conditional UI based on modal count.
+ *
+ * @param validate - Function to determine if a modal should be counted (default: checks visibility)
+ * @param refreshKey - Optional key to force recalculation when changed
+ * @returns Number of modals that pass the validation
+ *
+ * @example
+ * Basic usage - count visible modals:
+ * ```tsx
+ * function ModalOverlay() {
+ *   const activeCount = useActiveModalCount();
+ *
+ *   if (activeCount === 0) return null;
+ *
+ *   return (
+ *     <div
+ *       className="modal-backdrop"
+ *       style={{
+ *         opacity: Math.min(activeCount * 0.3, 0.8),
+ *         zIndex: 1000 + activeCount
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Count modals by type:
+ * ```tsx
+ * function ModalStats() {
+ *   const alertCount = useActiveModalCount(
+ *     (modal) => modal?.type === 'alert' && modal.visible
+ *   );
+ *
+ *   const confirmCount = useActiveModalCount(
+ *     (modal) => modal?.type === 'confirm' && modal.visible
+ *   );
+ *
+ *   const promptCount = useActiveModalCount(
+ *     (modal) => modal?.type === 'prompt' && modal.visible
+ *   );
+ *
+ *   return (
+ *     <div className="modal-stats">
+ *       <p>Alerts: {alertCount}</p>
+ *       <p>Confirms: {confirmCount}</p>
+ *       <p>Prompts: {promptCount}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Prevent interactions when modals are active:
+ * ```tsx
+ * function App() {
+ *   const hasActiveModals = useActiveModalCount() > 0;
+ *
+ *   return (
+ *     <div className={hasActiveModals ? 'app-disabled' : 'app'}>
+ *       <nav className={hasActiveModals ? 'pointer-events-none' : ''}>
+ *         <button disabled={hasActiveModals}>Navigate</button>
+ *       </nav>
+ *       <main inert={hasActiveModals}>
+ *         // Main content
+ *       </main>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Count alive modals (including hidden ones):
+ * ```tsx
+ * function ModalMemoryMonitor() {
+ *   const aliveCount = useActiveModalCount(
+ *     (modal) => modal?.alive === true
+ *   );
+ *
+ *   const hiddenCount = useActiveModalCount(
+ *     (modal) => modal?.alive && !modal.visible
+ *   );
+ *
+ *   return (
+ *     <div className="debug-panel">
+ *       <p>Total alive modals: {aliveCount}</p>
+ *       <p>Hidden (animating out): {hiddenCount}</p>
+ *       <button
+ *         onClick={cleanupHiddenModals}
+ *         disabled={hiddenCount === 0}
+ *       >
+ *         Cleanup Hidden Modals
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Dynamic refresh with dependencies:
+ * ```tsx
+ * function FilteredModalCount({ filter }) {
+ *   const [refreshKey, setRefreshKey] = useState(0);
+ *
+ *   // Count modals matching dynamic filter
+ *   const count = useActiveModalCount(
+ *     (modal) => {
+ *       if (!modal?.visible) return false;
+ *       if (filter.type && modal.type !== filter.type) return false;
+ *       if (filter.group && modal.group !== filter.group) return false;
+ *       return true;
+ *     },
+ *     refreshKey // Force recalculation when key changes
+ *   );
+ *
+ *   // Refresh count when filter changes
+ *   useEffect(() => {
+ *     setRefreshKey(prev => prev + 1);
+ *   }, [filter]);
+ *
+ *   return <div>Matching modals: {count}</div>;
+ * }
+ * ```
+ *
+ * @example
+ * Limit modal stacking:
+ * ```tsx
+ * function LimitedModalProvider({ children, maxModals = 3 }) {
+ *   const activeCount = useActiveModalCount();
+ *
+ *   const openModal = useCallback((modalConfig) => {
+ *     if (activeCount >= maxModals) {
+ *       alert({
+ *         title: 'Too Many Modals',
+ *         content: `Maximum of ${maxModals} modals can be open at once.`,
+ *         subtype: 'warning',
+ *       });
+ *       return Promise.reject(new Error('Modal limit exceeded'));
+ *     }
+ *
+ *     return originalOpenModal(modalConfig);
+ *   }, [activeCount, maxModals]);
+ *
+ *   return (
+ *     <ModalContext.Provider value={{ openModal }}>
+ *       {children}
+ *     </ModalContext.Provider>
+ *   );
+ * }
+ * ```
+ *
+ * @remarks
+ * - Recalculates whenever modal list changes or refreshKey updates
+ * - Default validation counts visible modals only
+ * - Custom validation can check any modal properties
+ * - Efficient memoization prevents unnecessary recalculations
+ * - Use refreshKey to force updates based on external dependencies
+ */
 export declare const useActiveModalCount: (validate?: Fn<[node?: ModalNode], boolean | undefined>, refreshKey?: string | number) => number;

package/dist/hooks/useDestroyAfter.d.ts

@@ -1,3 +1,130 @@
 import type { Duration } from '../@aileron/declare';
 import type { ModalNode } from '../core';
+/**
+ * Hook that automatically destroys a modal after it becomes hidden.
+ *
+ * Monitors the modal's visibility state and schedules destruction after a specified
+ * duration once the modal is hidden but still alive. Useful for cleanup after
+ * closing animations complete.
+ *
+ * @param modalId - ID of the modal to monitor
+ * @param duration - Delay before destruction (ms or duration string like '300ms')
+ *
+ * @example
+ * Basic usage with milliseconds:
+ * ```tsx
+ * function AnimatedModal({ modalId }) {
+ *   // Destroy modal 300ms after it becomes hidden
+ *   useDestroyAfter(modalId, 300);
+ *
+ *   return (
+ *     <div className="modal-with-exit-animation">
+ *       // Modal content
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Using duration string:
+ * ```tsx
+ * function FadeOutModal({ modalId }) {
+ *   // Destroy after CSS animation completes
+ *   useDestroyAfter(modalId, '500ms');
+ *
+ *   const { modal } = useModal(modalId);
+ *
+ *   return (
+ *     <div
+ *       className={modal?.visible ? 'fade-in' : 'fade-out'}
+ *       style={{ animationDuration: '500ms' }}
+ *     >
+ *       // Content
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Conditional destruction based on modal type:
+ * ```tsx
+ * function SmartModal({ modalId }) {
+ *   const { modal } = useModal(modalId);
+ *
+ *   // Different timings for different modal types
+ *   const destroyDelay = useMemo(() => {
+ *     switch (modal?.type) {
+ *       case 'alert': return '200ms';
+ *       case 'confirm': return '300ms';
+ *       case 'prompt': return '400ms';
+ *       default: return 300;
+ *     }
+ *   }, [modal?.type]);
+ *
+ *   useDestroyAfter(modalId, destroyDelay);
+ *
+ *   return <ModalContent modalId={modalId} />;
+ * }
+ * ```
+ *
+ * @example
+ * With custom animations and effects:
+ * ```tsx
+ * function NotificationModal({ modalId }) {
+ *   const { modal } = useModal(modalId);
+ *   const [particles, setParticles] = useState([]);
+ *
+ *   // Cleanup after particle animation
+ *   useDestroyAfter(modalId, '1000ms');
+ *
+ *   useEffect(() => {
+ *     if (!modal?.visible && modal?.alive) {
+ *       // Trigger particle effect on close
+ *       setParticles(generateParticles());
+ *     }
+ *   }, [modal?.visible, modal?.alive]);
+ *
+ *   return (
+ *     <>
+ *       <div className={`notification ${!modal?.visible ? 'explode' : ''}`}>
+ *         // Content
+ *       </div>
+ *       {particles.map(particle => (
+ *         <Particle key={particle.id} {...particle} />
+ *       ))}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Coordinated with manual destruction:
+ * ```tsx
+ * function PersistentModal({ modalId }) {
+ *   const { modal } = useModal(modalId);
+ *   const [shouldPersist, setShouldPersist] = useState(false);
+ *
+ *   // Only auto-destroy if not persisting
+ *   if (!shouldPersist) {
+ *     useDestroyAfter(modalId, '300ms');
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => setShouldPersist(true)}>
+ *         Keep in Background
+ *       </button>
+ *       // Modal content
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @remarks
+ * - Only triggers when modal is hidden (visible: false) but still alive
+ * - Automatically cancels if modal becomes visible again
+ * - Useful for cleanup after exit animations
+ * - Works with both millisecond numbers and duration strings
+ * - The timer resets if modal visibility changes
+ */
 export declare const useDestroyAfter: (modalId: ModalNode["id"], duration: Duration | number) => void;