@lerx/promise-modal 0.2.8 → 0.2.9

package/dist/hooks/useModalAnimation.d.ts

@@ -3,5 +3,217 @@ interface ModalAnimationHandler {
     onVisible?: Fn;
     onHidden?: Fn;
 }
+/**
+ * Hook that triggers animation callbacks based on modal visibility changes.
+ *
+ * Uses requestAnimationFrame to ensure callbacks are executed at the optimal time
+ * for animations. Callbacks are triggered on the next frame after visibility changes,
+ * allowing for smooth CSS transitions and JavaScript animations.
+ *
+ * @param visible - Current visibility state of the modal
+ * @param handler - Object containing onVisible and onHidden callbacks
+ *
+ * @example
+ * Basic fade animation:
+ * ```tsx
+ * function FadeModal({ visible }) {
+ *   const modalRef = useRef<HTMLDivElement>(null);
+ *
+ *   useModalAnimation(visible, {
+ *     onVisible: () => {
+ *       if (modalRef.current) {
+ *         modalRef.current.style.opacity = '0';
+ *         modalRef.current.style.transform = 'scale(0.9)';
+ *
+ *         requestAnimationFrame(() => {
+ *           modalRef.current.style.opacity = '1';
+ *           modalRef.current.style.transform = 'scale(1)';
+ *         });
+ *       }
+ *     },
+ *     onHidden: () => {
+ *       if (modalRef.current) {
+ *         modalRef.current.style.opacity = '0';
+ *         modalRef.current.style.transform = 'scale(0.9)';
+ *       }
+ *     },
+ *   });
+ *
+ *   return (
+ *     <div
+ *       ref={modalRef}
+ *       style={{
+ *         transition: 'all 300ms ease',
+ *         opacity: 0,
+ *       }}
+ *     >
+ *       Modal Content
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Slide animation with dynamic direction:
+ * ```tsx
+ * function SlideModal({ visible, direction = 'bottom' }) {
+ *   const modalRef = useRef<HTMLDivElement>(null);
+ *
+ *   const getTransform = (hidden: boolean) => {
+ *     if (!hidden) return 'translate(0, 0)';
+ *
+ *     switch (direction) {
+ *       case 'top': return 'translate(0, -100%)';
+ *       case 'bottom': return 'translate(0, 100%)';
+ *       case 'left': return 'translate(-100%, 0)';
+ *       case 'right': return 'translate(100%, 0)';
+ *     }
+ *   };
+ *
+ *   useModalAnimation(visible, {
+ *     onVisible: () => {
+ *       if (modalRef.current) {
+ *         modalRef.current.style.transform = getTransform(false);
+ *       }
+ *     },
+ *     onHidden: () => {
+ *       if (modalRef.current) {
+ *         modalRef.current.style.transform = getTransform(true);
+ *       }
+ *     },
+ *   });
+ *
+ *   return (
+ *     <div
+ *       ref={modalRef}
+ *       style={{
+ *         transition: 'transform 400ms cubic-bezier(0.4, 0, 0.2, 1)',
+ *         transform: getTransform(true),
+ *       }}
+ *     >
+ *       // Content
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Complex animation sequence:
+ * ```tsx
+ * function SequenceModal({ visible }) {
+ *   const overlayRef = useRef<HTMLDivElement>(null);
+ *   const contentRef = useRef<HTMLDivElement>(null);
+ *
+ *   useModalAnimation(visible, {
+ *     onVisible: () => {
+ *       // Animate overlay first
+ *       if (overlayRef.current) {
+ *         overlayRef.current.style.opacity = '0';
+ *         requestAnimationFrame(() => {
+ *           overlayRef.current.style.opacity = '1';
+ *         });
+ *       }
+ *
+ *       // Then animate content with delay
+ *       setTimeout(() => {
+ *         if (contentRef.current) {
+ *           contentRef.current.style.transform = 'scale(0.8)';
+ *           contentRef.current.style.opacity = '0';
+ *
+ *           requestAnimationFrame(() => {
+ *             contentRef.current.style.transform = 'scale(1)';
+ *             contentRef.current.style.opacity = '1';
+ *           });
+ *         }
+ *       }, 150);
+ *     },
+ *     onHidden: () => {
+ *       // Reverse animation
+ *       if (contentRef.current) {
+ *         contentRef.current.style.transform = 'scale(0.8)';
+ *         contentRef.current.style.opacity = '0';
+ *       }
+ *
+ *       setTimeout(() => {
+ *         if (overlayRef.current) {
+ *           overlayRef.current.style.opacity = '0';
+ *         }
+ *       }, 150);
+ *     },
+ *   });
+ *
+ *   return (
+ *     <>
+ *       <div
+ *         ref={overlayRef}
+ *         className="modal-overlay"
+ *         style={{ transition: 'opacity 300ms' }}
+ *       />
+ *       <div
+ *         ref={contentRef}
+ *         className="modal-content"
+ *         style={{ transition: 'all 300ms ease' }}
+ *       >
+ *         // Content
+ *       </div>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * With class-based animations:
+ * ```tsx
+ * function ClassAnimatedModal({ visible }) {
+ *   const [animationClass, setAnimationClass] = useState('');
+ *
+ *   useModalAnimation(visible, {
+ *     onVisible: () => setAnimationClass('modal-enter'),
+ *     onHidden: () => setAnimationClass('modal-exit'),
+ *   });
+ *
+ *   return (
+ *     <div className={`modal ${animationClass}`}>
+ *       // Content
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Integrating with animation libraries:
+ * ```tsx
+ * function SpringModal({ visible }) {
+ *   const springRef = useRef<SpringRef>(null);
+ *
+ *   useModalAnimation(visible, {
+ *     onVisible: () => {
+ *       springRef.current?.start({
+ *         from: { opacity: 0, scale: 0.8 },
+ *         to: { opacity: 1, scale: 1 },
+ *       });
+ *     },
+ *     onHidden: () => {
+ *       springRef.current?.start({
+ *         to: { opacity: 0, scale: 0.8 },
+ *       });
+ *     },
+ *   });
+ *
+ *   return (
+ *     <animated.div ref={springRef}>
+ *       // Content
+ *     </animated.div>
+ *   );
+ * }
+ * ```
+ *
+ * @remarks
+ * - Uses useLayoutEffect to ensure DOM updates before animations
+ * - Callbacks are wrapped in requestAnimationFrame for optimal timing
+ * - Handler reference is kept fresh without causing re-renders
+ * - Automatically cancels pending animation frames on cleanup
+ * - Perfect for coordinating CSS transitions and JS animations
+ */
 export declare const useModalAnimation: (visible: boolean, handler: ModalAnimationHandler) => void;
 export {};

package/dist/hooks/useSubscribeModal.d.ts

@@ -1,2 +1,116 @@
 import type { ModalNode } from '../core';
+/**
+ * Hook that subscribes to modal state changes and triggers re-renders.
+ *
+ * Listens to any changes in the modal node (visibility, alive state, content, etc.)
+ * and returns a version number that increments on each change. This allows components
+ * to react to modal state changes without directly accessing the modal state.
+ *
+ * @param modal - The modal node to subscribe to
+ * @returns Version number that increments on each modal state change
+ *
+ * @example
+ * Basic usage to react to modal changes:
+ * ```tsx
+ * function ModalContent({ modalId }) {
+ *   const { modal } = useModal(modalId);
+ *   const version = useSubscribeModal(modal);
+ *
+ *   // Component re-renders whenever modal state changes
+ *   return (
+ *     <div>
+ *       <p>Modal is {modal?.visible ? 'visible' : 'hidden'}</p>
+ *       <p>Update count: {version}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Triggering side effects on modal state changes:
+ * ```tsx
+ * function ModalLogger({ modalId }) {
+ *   const { modal } = useModal(modalId);
+ *   const version = useSubscribeModal(modal);
+ *
+ *   useEffect(() => {
+ *     if (version === 0) return; // Skip initial render
+ *
+ *     console.log('Modal state changed:', {
+ *       visible: modal?.visible,
+ *       alive: modal?.alive,
+ *       type: modal?.type,
+ *     });
+ *   }, [version, modal]);
+ *
+ *   return null;
+ * }
+ * ```
+ *
+ * @example
+ * Conditional rendering based on modal state:
+ * ```tsx
+ * function ModalAnimation({ modalId, children }) {
+ *   const { modal } = useModal(modalId);
+ *   const version = useSubscribeModal(modal);
+ *   const [shouldRender, setShouldRender] = useState(false);
+ *
+ *   useEffect(() => {
+ *     if (modal?.visible) {
+ *       setShouldRender(true);
+ *     } else if (!modal?.alive) {
+ *       // Delay unmount for exit animation
+ *       setTimeout(() => setShouldRender(false), 300);
+ *     }
+ *   }, [version, modal]);
+ *
+ *   if (!shouldRender) return null;
+ *
+ *   return (
+ *     <div className={modal?.visible ? 'fade-in' : 'fade-out'}>
+ *       {children}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Tracking specific modal properties:
+ * ```tsx
+ * function ModalProgressTracker({ modalId }) {
+ *   const { modal } = useModal(modalId);
+ *   const version = useSubscribeModal(modal);
+ *   const [history, setHistory] = useState([]);
+ *
+ *   useEffect(() => {
+ *     if (!modal) return;
+ *
+ *     setHistory(prev => [...prev, {
+ *       timestamp: Date.now(),
+ *       visible: modal.visible,
+ *       value: modal.value,
+ *     }]);
+ *   }, [version]); // Only depend on version, not modal
+ *
+ *   return (
+ *     <div>
+ *       <h4>Modal State History</h4>
+ *       {history.map((entry, i) => (
+ *         <div key={i}>
+ *           {new Date(entry.timestamp).toLocaleTimeString()}:
+ *           {entry.visible ? 'Shown' : 'Hidden'}
+ *           (value: {JSON.stringify(entry.value)})
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @remarks
+ * - Returns 0 on initial render, increments on each change
+ * - Automatically unsubscribes when component unmounts or modal changes
+ * - More efficient than directly depending on modal object in useEffect
+ * - Use this when you need to react to any modal state change
+ */
 export declare const useSubscribeModal: (modal?: ModalNode) => number;

package/dist/index.cjs

@@ -426,7 +426,7 @@ const DEFAULT_OPTIONS = {
     manualDestroy: false,
 };
 const ConfigurationContextProvider = react.memo(({ ForegroundComponent, BackgroundComponent, TitleComponent, SubtitleComponent, ContentComponent, FooterComponent, options: inputOptions, children, }) => {
-    const memoized = hook.useMemorize({
+    const constant = hook.useConstant({
         BackgroundComponent,
         ForegroundComponent: ForegroundComponent || FallbackForegroundFrame,
         TitleComponent: TitleComponent || FallbackTitle,
@@ -436,17 +436,17 @@ const ConfigurationContextProvider = react.memo(({ ForegroundComponent, Backgrou
     });
     const options = hook.useSnapshot(inputOptions);
     const value = react.useMemo(() => ({
-        ForegroundComponent: memoized.ForegroundComponent,
-        BackgroundComponent: memoized.BackgroundComponent,
-        TitleComponent: memoized.TitleComponent,
-        SubtitleComponent: memoized.SubtitleComponent,
-        ContentComponent: memoized.ContentComponent,
-        FooterComponent: memoized.FooterComponent,
+        ForegroundComponent: constant.ForegroundComponent,
+        BackgroundComponent: constant.BackgroundComponent,
+        TitleComponent: constant.TitleComponent,
+        SubtitleComponent: constant.SubtitleComponent,
+        ContentComponent: constant.ContentComponent,
+        FooterComponent: constant.FooterComponent,
         options: {
             ...DEFAULT_OPTIONS,
             ...options,
         },
-    }), [memoized, options]);
+    }), [constant, options]);
     return (jsxRuntime.jsx(ConfigurationContext.Provider, { value: value, children: children }));
 });
 

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { useConfigurationOptions as useModalOptions, useConfigurationDuration as useModalDuration, useConfigurationBackdrop as useModalBackdrop, } from './providers';
 export { useBootstrap as useInitializeModal, BootstrapProvider as ModalProvider, type BootstrapProviderHandle as ModalProviderHandle, type BootstrapProviderProps as ModalProviderProps, } from './bootstrap';
-export { useSubscribeModal } from './hooks/useSubscribeModal';
-export { useDestroyAfter } from './hooks/useDestroyAfter';
 export { useActiveModalCount } from './hooks/useActiveModalCount';
+export { useDestroyAfter } from './hooks/useDestroyAfter';
 export { useModalAnimation } from './hooks/useModalAnimation';
+export { useSubscribeModal } from './hooks/useSubscribeModal';
 export { alert, confirm, prompt } from './core';
 export type { ModalOptions, ModalFrameProps, FooterComponentProps, ModalBackground, PromptInputProps, AlertContentProps, ConfirmContentProps, PromptContentProps, WrapperComponentProps, } from './types';

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { createContext, useContext, useMemo, forwardRef, memo, useRef, useState, useLayoutEffect, useCallback, Fragment, useEffect, useImperativeHandle } from 'react';
 import { convertMsFromDuration } from '@winglet/common-utils/convert';
-import { useMemorize, useSnapshot, useReference, useOnMountLayout, useHandle, useVersion, useOnMount } from '@winglet/react-utils/hook';
+import { useConstant, useSnapshot, useReference, useOnMountLayout, useHandle, useVersion, useOnMount } from '@winglet/react-utils/hook';
 import { polynomialHash } from '@winglet/common-utils/hash';
 import { getRandomString, counterFactory } from '@winglet/common-utils/lib';
 import { styleManagerFactory, destroyScope } from '@winglet/style-utils/style-manager';
@@ -424,7 +424,7 @@ const DEFAULT_OPTIONS = {
     manualDestroy: false,
 };
 const ConfigurationContextProvider = memo(({ ForegroundComponent, BackgroundComponent, TitleComponent, SubtitleComponent, ContentComponent, FooterComponent, options: inputOptions, children, }) => {
-    const memoized = useMemorize({
+    const constant = useConstant({
         BackgroundComponent,
         ForegroundComponent: ForegroundComponent || FallbackForegroundFrame,
         TitleComponent: TitleComponent || FallbackTitle,
@@ -434,17 +434,17 @@ const ConfigurationContextProvider = memo(({ ForegroundComponent, BackgroundComp
     });
     const options = useSnapshot(inputOptions);
     const value = useMemo(() => ({
-        ForegroundComponent: memoized.ForegroundComponent,
-        BackgroundComponent: memoized.BackgroundComponent,
-        TitleComponent: memoized.TitleComponent,
-        SubtitleComponent: memoized.SubtitleComponent,
-        ContentComponent: memoized.ContentComponent,
-        FooterComponent: memoized.FooterComponent,
+        ForegroundComponent: constant.ForegroundComponent,
+        BackgroundComponent: constant.BackgroundComponent,
+        TitleComponent: constant.TitleComponent,
+        SubtitleComponent: constant.SubtitleComponent,
+        ContentComponent: constant.ContentComponent,
+        FooterComponent: constant.FooterComponent,
         options: {
             ...DEFAULT_OPTIONS,
             ...options,
         },
-    }), [memoized, options]);
+    }), [constant, options]);
     return (jsx(ConfigurationContext.Provider, { value: value, children: children }));
 });
 

package/dist/providers/ConfigurationContext/useConfigurationContext.d.ts

@@ -1,7 +1,280 @@
+/**
+ * Hook that provides access to the complete modal configuration context.
+ *
+ * Returns all configuration including component overrides and options.
+ * This is the most comprehensive hook for accessing modal configuration,
+ * useful when you need multiple configuration values or custom components.
+ *
+ * @returns Complete configuration context with components and options
+ */
 export declare const useConfigurationContext: () => import("./ConfigurationContext").ConfigurationContextProps;
+/**
+ * Hook that provides only the modal options from configuration.
+ *
+ * Convenient when you only need access to options like duration, backdrop,
+ * and behavior settings without the component definitions.
+ *
+ * @returns Modal options object with all settings
+ *
+ * @example
+ * Basic usage:
+ * ```tsx
+ * function ModalBackdrop() {
+ *   const options = useConfigurationOptions();
+ *
+ *   return (
+ *     <div
+ *       className="modal-backdrop"
+ *       style={{
+ *         backgroundColor: options.backdrop,
+ *         transition: `opacity ${options.duration} ease`
+ *       }}
+ *       onClick={options.closeOnBackdropClick ? handleClose : undefined}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Conditional behavior based on options:
+ * ```tsx
+ * function ModalCloseButton({ onClose }) {
+ *   const { closeOnBackdropClick, manualDestroy } = useConfigurationOptions();
+ *   const [isClosing, setIsClosing] = useState(false);
+ *
+ *   const handleClick = () => {
+ *     if (manualDestroy) {
+ *       setIsClosing(true);
+ *       // Trigger close animation
+ *       setTimeout(onClose, 300);
+ *     } else {
+ *       onClose();
+ *     }
+ *   };
+ *
+ *   // Hide close button if backdrop click is disabled
+ *   if (!closeOnBackdropClick) return null;
+ *
+ *   return (
+ *     <button
+ *       onClick={handleClick}
+ *       className={isClosing ? 'closing' : ''}
+ *     >
+ *       ×
+ *     </button>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Options-aware animations:
+ * ```tsx
+ * function AnimatedContent({ visible, children }) {
+ *   const options = useConfigurationOptions();
+ *   const contentRef = useRef<HTMLDivElement>(null);
+ *
+ *   useEffect(() => {
+ *     if (!contentRef.current) return;
+ *
+ *     const element = contentRef.current;
+ *     element.style.transition = `all ${options.duration} ease`;
+ *
+ *     if (visible) {
+ *       element.style.opacity = '1';
+ *       element.style.transform = 'scale(1)';
+ *     } else {
+ *       element.style.opacity = '0';
+ *       element.style.transform = 'scale(0.95)';
+ *     }
+ *   }, [visible, options.duration]);
+ *
+ *   return <div ref={contentRef}>{children}</div>;
+ * }
+ * ```
+ */
 export declare const useConfigurationOptions: () => Required<import("../..").ModalOptions>;
+/**
+ * Hook that provides modal animation duration in multiple formats.
+ *
+ * Returns both the original duration string and converted milliseconds,
+ * useful for JavaScript animations and timing calculations.
+ *
+ * @returns Object with duration string and milliseconds number
+ *
+ * @example
+ * Basic animation timing:
+ * ```tsx
+ * function TimedModal() {
+ *   const { duration, milliseconds } = useConfigurationDuration();
+ *   const [phase, setPhase] = useState<'entering' | 'visible' | 'leaving'>();
+ *
+ *   useEffect(() => {
+ *     if (phase === 'entering') {
+ *       const timer = setTimeout(() => setPhase('visible'), milliseconds);
+ *       return () => clearTimeout(timer);
+ *     }
+ *   }, [phase, milliseconds]);
+ *
+ *   return (
+ *     <div
+ *       className={`modal-${phase}`}
+ *       style={{ animationDuration: duration }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Synchronized animations:
+ * ```tsx
+ * function ModalWithStaggeredElements({ items }) {
+ *   const { duration, milliseconds } = useConfigurationDuration();
+ *   const itemDelay = milliseconds / items.length;
+ *
+ *   return (
+ *     <div className="modal">
+ *       {items.map((item, index) => (
+ *         <div
+ *           key={item.id}
+ *           className="modal-item"
+ *           style={{
+ *             animationDuration: duration,
+ *             animationDelay: `${index * itemDelay}ms`
+ *           }}
+ *         >
+ *           {item.content}
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Progress indicators:
+ * ```tsx
+ * function ModalProgress({ onComplete }) {
+ *   const { milliseconds } = useConfigurationDuration();
+ *   const [progress, setProgress] = useState(0);
+ *
+ *   useEffect(() => {
+ *     const startTime = Date.now();
+ *     const interval = setInterval(() => {
+ *       const elapsed = Date.now() - startTime;
+ *       const percent = Math.min((elapsed / milliseconds) * 100, 100);
+ *       setProgress(percent);
+ *
+ *       if (percent >= 100) {
+ *         clearInterval(interval);
+ *         onComplete();
+ *       }
+ *     }, 16); // ~60fps
+ *
+ *     return () => clearInterval(interval);
+ *   }, [milliseconds, onComplete]);
+ *
+ *   return (
+ *     <div className="progress-bar">
+ *       <div
+ *         className="progress-fill"
+ *         style={{ width: `${progress}%` }}
+ *       />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @remarks
+ * - Supports various duration formats: '300ms', '0.3s', '1s', etc.
+ * - Automatically converts to milliseconds for JavaScript timing
+ * - Useful for coordinating CSS and JS animations
+ */
 export declare const useConfigurationDuration: () => {
     duration: `${number}ms`;
     milliseconds: number;
 };
+/**
+ * Hook that provides the modal backdrop color configuration.
+ *
+ * Convenient accessor for backdrop styling, supporting any valid CSS color format.
+ *
+ * @returns Backdrop color string
+ *
+ * @example
+ * Basic backdrop:
+ * ```tsx
+ * function ModalOverlay({ visible }) {
+ *   const backdrop = useConfigurationBackdrop();
+ *
+ *   if (!visible) return null;
+ *
+ *   return (
+ *     <div
+ *       className="fixed inset-0"
+ *       style={{ backgroundColor: backdrop }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Animated backdrop with opacity:
+ * ```tsx
+ * function AnimatedBackdrop({ visible }) {
+ *   const backdrop = useConfigurationBackdrop();
+ *   const [opacity, setOpacity] = useState(0);
+ *
+ *   // Parse backdrop color and apply custom opacity
+ *   const backdropWithOpacity = useMemo(() => {
+ *     if (backdrop.startsWith('rgba')) {
+ *       return backdrop.replace(/[\d.]+\)$/, `${opacity})`);
+ *     }
+ *     return `${backdrop}${Math.round(opacity * 255).toString(16).padStart(2, '0')}`;
+ *   }, [backdrop, opacity]);
+ *
+ *   useEffect(() => {
+ *     setOpacity(visible ? 1 : 0);
+ *   }, [visible]);
+ *
+ *   return (
+ *     <div
+ *       className="backdrop"
+ *       style={{
+ *         backgroundColor: backdropWithOpacity,
+ *         transition: 'opacity 300ms ease'
+ *       }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * Theme-aware backdrop:
+ * ```tsx
+ * function ThemedBackdrop() {
+ *   const backdrop = useConfigurationBackdrop();
+ *   const { theme } = useTheme();
+ *
+ *   const adjustedBackdrop = useMemo(() => {
+ *     if (theme === 'dark') {
+ *       // Make backdrop darker in dark mode
+ *       return backdrop.replace('0.5', '0.8');
+ *     }
+ *     return backdrop;
+ *   }, [backdrop, theme]);
+ *
+ *   return (
+ *     <div
+ *       className="modal-backdrop"
+ *       style={{ backgroundColor: adjustedBackdrop }}
+ *     />
+ *   );
+ * }
+ * ```
+ *
+ * @remarks
+ * - Supports all CSS color formats: hex, rgb, rgba, hsl, etc.
+ * - Default backdrop is typically semi-transparent black
+ * - Can be overridden at provider level or per-modal
+ */
 export declare const useConfigurationBackdrop: () => import("../../@aileron/declare").Color;