@lerx/promise-modal 0.2.7 → 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 { ModalFrameProps, FooterComponentProps, ModalBackground, PromptInputProps, AlertContentProps, ConfirmContentProps, PromptContentProps, WrapperComponentProps, } from './types';
+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/ConfigurationContext.d.ts

@@ -1,6 +1,5 @@
 import { type ComponentType } from 'react';
-import type { Color, Duration } from '../../@aileron/declare';
-import type { BackgroundComponent, FooterComponentProps, ForegroundComponent, WrapperComponentProps } from '../../types';
+import type { BackgroundComponent, FooterComponentProps, ForegroundComponent, ModalOptions, WrapperComponentProps } from '../../types';
 export interface ConfigurationContextProps {
     ForegroundComponent: ForegroundComponent;
     BackgroundComponent?: BackgroundComponent;
@@ -8,11 +7,6 @@ export interface ConfigurationContextProps {
     SubtitleComponent: ComponentType<WrapperComponentProps>;
     ContentComponent: ComponentType<WrapperComponentProps>;
     FooterComponent: ComponentType<FooterComponentProps>;
-    options: {
-        duration: Duration;
-        backdrop: Color;
-        manualDestroy: boolean;
-        closeOnBackdropClick: boolean;
-    };
+    options: Required<ModalOptions>;
 }
 export declare const ConfigurationContext: import("react").Context<ConfigurationContextProps>;

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

@@ -1,6 +1,5 @@
 import { type ComponentType, type PropsWithChildren } from 'react';
-import type { Color, Duration } from '../../@aileron/declare';
-import type { FooterComponentProps, ModalFrameProps, WrapperComponentProps } from '../../types';
+import type { FooterComponentProps, ModalFrameProps, ModalOptions, WrapperComponentProps } from '../../types';
 export interface ConfigurationContextProviderProps {
     BackgroundComponent?: ComponentType<ModalFrameProps>;
     ForegroundComponent?: ComponentType<ModalFrameProps>;
@@ -8,15 +7,6 @@ export interface ConfigurationContextProviderProps {
     SubtitleComponent?: ComponentType<WrapperComponentProps>;
     ContentComponent?: ComponentType<WrapperComponentProps>;
     FooterComponent?: ComponentType<FooterComponentProps>;
-    options?: {
-        /** Modal transition time(ms, s) */
-        duration?: Duration;
-        /** Modal backdrop color */
-        backdrop?: Color;
-        /** Whether to destroy the modal manually */
-        manualDestroy?: boolean;
-        /** Whether to close the modal when the backdrop is clicked */
-        closeOnBackdropClick?: boolean;
-    };
+    options?: ModalOptions;
 }
 export declare const ConfigurationContextProvider: import("react").MemoExoticComponent<({ ForegroundComponent, BackgroundComponent, TitleComponent, SubtitleComponent, ContentComponent, FooterComponent, options: inputOptions, children, }: PropsWithChildren<ConfigurationContextProviderProps>) => import("react/jsx-runtime").JSX.Element>;