@trackunit/react-modal 1.21.4 → 1.21.7

package/index.esm.js

@@ -1,10 +1,10 @@
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { registerTranslations } from '@trackunit/i18n-library-translation';
-import { useMergeRefs, FloatingOverlay, FloatingFocusManager, useFloating, shift, autoUpdate, useDismiss, useInteractions } from '@floating-ui/react';
-import { Portal, Card, Button, Heading, Text, IconButton, Icon, useWatch } from '@trackunit/react-components';
-import { useLayoutEffect, useRef, forwardRef, useId, useSyncExternalStore, useMemo, useState, useContext, useEffect, useCallback } from 'react';
+import { useMergeRefs, FloatingFocusManager, FloatingOverlay, useFloating, shift, autoUpdate, useDismiss, useInteractions } from '@floating-ui/react';
+import { useOverflowBorder, useSheetSnap, useWatch, Card, Portal, Sheet, Button, Heading, Text, IconButton, Icon, useContainerBreakpoints, useViewportBreakpoints, useTimeout, SHEET_TRANSITION_DURATION_MS } from '@trackunit/react-components';
+import { useRef, useCallback, useState, useReducer, useMemo, forwardRef, useId, useSyncExternalStore, useLayoutEffect, useContext, useEffect } from 'react';
 import { cvaMerge } from '@trackunit/css-class-variance-utilities';
-import { ModalDialogContext } from '@trackunit/react-core-contexts-api';
+import { ModalDialogContext, ErrorHandlingContext } from '@trackunit/react-core-contexts-api';
 
 var defaultTranslations = {
 	
@@ -90,30 +90,49 @@ const modalSizeConfigs = {
         maxHeight: "min(80dvh, 1000px)",
     },
 };
+const viewportPercentToContainerUnits = (viewportWidthPercent) => viewportWidthPercent.replaceAll("dvw", "cqw");
 /**
  * Returns the CSS properties for the modal card based on the size.
  */
-const getModalCardCSSVariables = (size) => {
+const getModalCardCSSVariables = (size, options) => {
     const config = modalSizeConfigs[size];
+    const useContainerWidthUnits = options?.useContainerWidthUnits === true;
+    const viewportWidthPercent = useContainerWidthUnits
+        ? viewportPercentToContainerUnits(config.viewportWidthPercent)
+        : config.viewportWidthPercent;
+    const viewportSpan = useContainerWidthUnits ? "100cqw" : "100dvw";
     // eslint-disable-next-line @trackunit/no-typescript-assertion
     return {
         "--modal-min-width": config.minWidth,
-        "--modal-viewport-width-percent": config.viewportWidthPercent,
+        "--modal-viewport-width-percent": viewportWidthPercent,
         "--modal-padding-offset": config.paddingOffset,
         "--modal-breakpoint": config.breakpoint,
         "--modal-transition-rate": config.transitionRate,
         "--modal-max-width": config.maxWidth,
         "--modal-max-height": config.maxHeight,
+        "--modal-viewport-span": viewportSpan,
     };
 };
+/**
+ * Layout contract that modal children depend on. Applied to the children's
+ * immediate container in both card mode (the Card) and sheet mode (the
+ * aria-modal wrapper). Ensures ModalHeader/ModalBody/ModalFooter experience
+ * an identical flex/container-query environment regardless of rendering mode.
+ *
+ * Does NOT include overflow-y — scrolling is owned by the parent:
+ * in card mode by the Card element (`cvaModalCard`), in sheet mode by the
+ * Sheet's scroll area. A nested overflow here would absorb content height,
+ * preventing Sheet's fit-height measurement from seeing the true size.
+ */
+const cvaModalContentEnvironment = cvaMerge(["flex", "flex-col", "min-h-0", "@container"]);
 const cvaModalCard = cvaMerge([
     "m-auto",
     "shadow-2xl",
+    "min-h-0",
     "overflow-y-auto",
-    "w-[clamp(var(--modal-min-width),calc(var(--modal-viewport-width-percent)-var(--modal-padding-offset)-((100dvw-var(--modal-breakpoint))*var(--modal-transition-rate))),var(--modal-max-width))]",
+    "w-[clamp(var(--modal-min-width),calc(var(--modal-viewport-width-percent)-var(--modal-padding-offset)-((var(--modal-viewport-span)-var(--modal-breakpoint))*var(--modal-transition-rate))),var(--modal-max-width))]",
     "max-h-[var(--modal-max-height)]",
-    "@container", // This is used to target the container size for all children
-    // Re-enable pointer events for modal content (container has pointer-events-none)
+    "@container",
     "pointer-events-auto",
 ], {
     variants: {
@@ -122,25 +141,20 @@ const cvaModalCard = cvaMerge([
             fade: "animate-fade-in-fast",
             // Stacked modals: fade + rise from below
             rise: "animate-fade-in-rising",
+            // No animation (used during formfactor transitions to avoid flicker)
+            none: [],
         },
     },
     defaultVariants: {
         animation: "fade",
     },
 });
-const cvaModalBackdrop = cvaMerge([
-    "flex",
-    "justify-center",
-    // "items-center",
-    "fixed",
-    "inset-0",
-    "min-h-[100dvh]",
-    "min-w-[100dvw]",
-    "w-full",
-    "h-full",
-    "z-overlay",
-], {
+const cvaModalBackdrop = cvaMerge(["flex", "justify-center", "inset-0", "w-full", "h-full", "z-overlay"], {
     variants: {
+        contained: {
+            true: ["absolute"],
+            false: ["fixed", "min-h-[100dvh]", "min-w-[100dvw]"],
+        },
         isFrontmost: {
             // Frontmost modal shows backdrop
             true: ["bg-black/50", "backdrop-saturate-150"],
@@ -159,118 +173,72 @@ const cvaModalBackdrop = cvaMerge([
     },
 });
 
-function resolveRootEl(refLike) {
-    if (refLike && typeof refLike === "object" && "current" in refLike) {
-        return refLike.current;
+/** Reducer tracking formfactor transitions (card/sheet) while the modal is open. */
+const modalModeSwitchReducer = (state, action) => {
+    if (action.mode === state.prevMode && action.isOpen === state.prevIsOpen) {
+        return state;
     }
-    return refLike;
-}
+    return {
+        prevMode: action.mode,
+        prevIsOpen: action.isOpen,
+        isModeSwitching: action.mode !== state.prevMode && action.isOpen && state.prevIsOpen
+            ? true
+            : !action.isOpen
+                ? false
+                : state.isModeSwitching,
+    };
+};
+
 /**
  * Observes the modal body within the given root element and toggles a top border on the footer
  * when the body becomes vertically scrollable.
  *
- * Behavior:
- * - Locates elements via stable data-attributes (by default: [data-modal-body], [data-modal-footer]).
- * - Recomputes on resize, DOM mutations within the body, scroll events, and image load/error events.
- * - Cleans up all observers/listeners on unmount or dependency change.
- *
- * Edge cases:
- * - If either body or footer is missing, the hook does nothing.
- * - No DOM mutations occur when `enabled` is false.
+ * Thin wrapper around `useOverflowBorder` with modal-specific defaults.
  *
  * @param rootRef Root element that contains both the modal body and footer.
  * @param options Optional configuration.
- * @param options.footerClass CSS class(es) toggled on the footer when the body is scrollable. Accepts string or string[]. Defaults to "border-t".
+ * @param options.footerClass CSS class(es) toggled on the footer when the body is scrollable. Defaults to "border-t".
  * @param options.enabled Whether the hook is active. Defaults to true.
  * @param options.bodySelector CSS selector to locate the body element. Defaults to "[data-modal-body]".
  * @param options.footerSelector CSS selector to locate the footer element. Defaults to "[data-modal-footer]".
  */
 const useModalFooterBorder = (rootRef, { footerClass = "border-t", enabled = true, bodySelector = "[data-modal-body]", footerSelector = "[data-modal-footer]", } = {}) => {
-    useLayoutEffect(() => {
-        if (!enabled)
-            return;
-        let cleanup;
-        let cancelled = false;
-        const classes = Array.isArray(footerClass)
-            ? footerClass.filter(Boolean)
-            : String(footerClass).split(/\s+/).filter(Boolean);
-        let attempts = 0;
-        const MAX_ATTEMPTS = 20;
-        const tryInit = () => {
-            if (cancelled)
-                return;
-            const root = resolveRootEl(rootRef);
-            if (!root) {
-                if (attempts++ < MAX_ATTEMPTS)
-                    requestAnimationFrame(tryInit);
-                return;
-            }
-            const bodyEl = root.querySelector(bodySelector);
-            const footerEl = root.querySelector(footerSelector);
-            if (!bodyEl || !footerEl) {
-                if (attempts++ < MAX_ATTEMPTS)
-                    requestAnimationFrame(tryInit);
-                return;
-            }
-            const update = () => {
-                const hasScrollbar = bodyEl.scrollHeight > bodyEl.clientHeight;
-                classes.forEach(cls => footerEl.classList.toggle(cls, hasScrollbar));
-            };
-            update();
-            const ro = new ResizeObserver(update);
-            ro.observe(bodyEl);
-            const attachImgListeners = (node) => {
-                const imgs = node.querySelectorAll("img"); // NodeListOf<HTMLImageElement>
-                imgs.forEach(img => {
-                    if (!img.complete) {
-                        const once = () => update();
-                        img.addEventListener("load", once, { once: true });
-                        img.addEventListener("error", once, { once: true });
-                    }
-                });
-            };
-            attachImgListeners(bodyEl);
-            const mo = new MutationObserver(muts => {
-                update();
-                for (const m of muts) {
-                    m.addedNodes.forEach(n => {
-                        if (n instanceof HTMLImageElement) {
-                            if (!n.complete) {
-                                const once = () => update();
-                                n.addEventListener("load", once, { once: true });
-                                n.addEventListener("error", once, { once: true });
-                            }
-                        }
-                        else if (n instanceof HTMLElement) {
-                            attachImgListeners(n);
-                        }
-                    });
-                }
-            });
-            mo.observe(bodyEl, { childList: true, subtree: true, characterData: true });
-            bodyEl.addEventListener("scroll", update, { passive: true });
-            cleanup = () => {
-                ro.disconnect();
-                mo.disconnect();
-                bodyEl.removeEventListener("scroll", update);
-                classes.forEach(cls => footerEl.classList.remove(cls));
-            };
-        };
-        requestAnimationFrame(tryInit);
-        return () => {
-            cancelled = true;
-            cleanup?.();
-        };
-    }, [enabled, footerClass, bodySelector, footerSelector, rootRef]);
+    useOverflowBorder(rootRef, {
+        scrollAreaSelector: bodySelector,
+        targetSelector: footerSelector,
+        toggleClass: footerClass,
+        enabled,
+    });
 };
 
 /** Scale factor per modal depth level (5% smaller per level back) */
 const SCALE_FACTOR_PER_LEVEL = 0.05;
+/** Maximum number of stacked modals visible behind the frontmost one. */
+const MAX_VISIBLE_STACK_BEHIND = 2;
+/**
+ * Inline styles for the Sheet container element in sheet mode.
+ * pointer-events: none lets interactions pass through when Sheet returns null
+ * (shouldRender=false). Sheet's inner panel has pointer-events-auto so it
+ * remains interactive when open.
+ */
+const SHEET_CONTAINER_STYLE = {
+    bottom: 0,
+    containerType: "size",
+    left: 0,
+    pointerEvents: "none",
+    position: "fixed",
+    right: 0,
+    top: 0,
+    zIndex: "var(--z-overlay)",
+};
 /**
  * Modal presents critical information or requests user input in an overlay dialog that interrupts the current workflow.
  * It renders inside a Portal with a backdrop overlay, focus trapping, and proper accessibility roles.
  * Modals must always be used together with the `useModal` hook, which manages open/close state and Floating UI integration.
  *
+ * When the container width is below the "sm" breakpoint (480px), the Modal
+ * automatically renders as a bottom Sheet with gesture support.
+ *
  * Compose the modal body with `ModalHeader`, `ModalBody`, and `ModalFooter` for consistent structure.
  *
  * ### When to use
@@ -301,21 +269,99 @@ const SCALE_FACTOR_PER_LEVEL = 0.05;
  * @param {ModalProps} props - The props for the Modal component
  * @returns {ReactElement} Modal component
  */
-const Modal = ({ children, isOpen, role = "dialog", "data-testid": dataTestId, className, size, floatingUi, ref, restoreFocus = true, depthFromFront, stackSizeAtOpen, }) => {
-    // For dialogs/modals, Floating UI recommends not using floatingStyles since the modal
-    // is viewport-centered via CSS, not positioned relative to a reference element.
-    // See: https://floating-ui.com/docs/dialog
+const Modal = ({ children, container, dismiss, isOpen, mode, requestClose, role = "dialog", "data-testid": dataTestId, className, size, stack, floatingUi, ref, sheetDefaultSize = "fit", restoreFocus = true, onCloseComplete, }) => {
+    const { depthFromFront, stackSizeAtOpen } = stack;
     const { rootElement, refs, context, getFloatingProps } = floatingUi;
     const cardRef = useRef(null);
-    // Merge the custom ref from useModal with FloatingUI's setFloating ref
     const mergedRef = useMergeRefs([refs.setFloating, ref]);
-    useModalFooterBorder(cardRef, { enabled: isOpen, footerClass: "border-t pt-4" });
-    const isFrontmost = depthFromFront === 0;
-    return (jsx(Portal, { root: rootElement, children: isOpen ? (jsx(FloatingOverlay, { className: cvaModalBackdrop({ isFrontmost, shouldAnimate: stackSizeAtOpen === 0 }), lockScroll: true, children: jsx(FloatingFocusManager, { context: context, restoreFocus: restoreFocus, children: jsx("div", { "aria-modal": true, className: cvaModalContainer(), ref: mergedRef, role: role, 
-                    // Scale down modals that are behind the frontmost
-                    style: isFrontmost ? undefined : { transform: `scale(${1 - depthFromFront * SCALE_FACTOR_PER_LEVEL})` }, ...getFloatingProps(), children: jsx(Card, { className: cvaModalCard({ className, animation: stackSizeAtOpen === 0 ? "fade" : "rise" }), "data-testid": dataTestId, ref: cardRef, style: getModalCardCSSVariables(size), children: children }) }) }) })) : null }));
+    const sheetRef = useRef(null);
+    const sheetRefCallback = useCallback((el) => {
+        sheetRef.current = el;
+    }, []);
+    const sheetPanelRef = useMergeRefs([refs.setFloating, sheetRefCallback]);
+    const handleSheetCloseComplete = useCallback(() => {
+        onCloseComplete();
+    }, [onCloseComplete]);
+    // Container element for the Sheet when no external container is provided.
+    // Uses useState as a callback ref so mounting triggers a re-render.
+    // The div is kept alive for the full duration mode is "sheet" so that
+    // the Sheet's close animation can complete inside it.
+    const [sheetContainer, setSheetContainer] = useState(null);
+    useModalFooterBorder(mode === "sheet" ? sheetRef : cardRef, { enabled: isOpen, footerClass: "border-t pt-4" });
+    const isVisibleInStack = depthFromFront <= MAX_VISIBLE_STACK_BEHIND;
+    // Detect formfactor transitions (card ↔ sheet) while the modal is already open.
+    const [modeState, dispatchMode] = useReducer(modalModeSwitchReducer, {
+        prevMode: mode,
+        prevIsOpen: isOpen,
+        isModeSwitching: false,
+    });
+    if (mode !== modeState.prevMode || isOpen !== modeState.prevIsOpen) {
+        dispatchMode({ type: "SYNC", mode, isOpen });
+    }
+    const { state: sheetState, snap: sheetSnap, onGeometryChange: sheetOnGeometryChange, onSnap: sheetOnSnap, onClickHandle: sheetOnClickHandle, } = useSheetSnap({ defaultSize: sheetDefaultSize, isOpen });
+    const onCloseGesture = useMemo(() => (dismiss.gesture ? () => requestClose(undefined, "gesture") : undefined), [dismiss.gesture, requestClose]);
+    // In card mode, there is no close animation so notify useModal immediately
+    // so it can call closeModal() without delay.
+    // In sheet mode, Sheet's onCloseComplete handles this instead.
+    useWatch({
+        value: isOpen,
+        onChange: (current, prev) => {
+            if (!current && prev && mode === "card") {
+                onCloseComplete();
+            }
+        },
+    });
+    const stackScale = 1 - Math.min(depthFromFront, MAX_VISIBLE_STACK_BEHIND) * SCALE_FACTOR_PER_LEVEL;
+    const sheetContainerStyle = useMemo(() => {
+        const style = {
+            ...SHEET_CONTAINER_STYLE,
+            ...(container !== undefined ? { position: "absolute" } : {}),
+            "--sheet-stack-scale": `${stackScale}`,
+        };
+        return style;
+    }, [container, stackScale]);
+    const isContained = container?.current !== null && container?.current !== undefined;
+    const cardModeInner = useMemo(() => {
+        if (mode !== "card" || !isOpen || !isVisibleInStack) {
+            return null;
+        }
+        return (jsx(FloatingFocusManager, { context: context, restoreFocus: restoreFocus, children: jsx("div", { "aria-modal": true, className: cvaModalContainer(), ref: mergedRef, role: role, style: depthFromFront === 0 ? undefined : { transform: `scale(${1 - depthFromFront * SCALE_FACTOR_PER_LEVEL})` }, ...getFloatingProps(), children: jsx(Card, { className: cvaModalCard({
+                        className,
+                        animation: modeState.isModeSwitching ? "none" : stackSizeAtOpen === 0 ? "fade" : "rise",
+                    }), "data-modal-content": true, "data-testid": dataTestId, ref: cardRef, style: getModalCardCSSVariables(size, { useContainerWidthUnits: container !== undefined }), children: children }) }) }));
+    }, [
+        mode,
+        isOpen,
+        isVisibleInStack,
+        context,
+        restoreFocus,
+        mergedRef,
+        role,
+        depthFromFront,
+        getFloatingProps,
+        className,
+        modeState.isModeSwitching,
+        stackSizeAtOpen,
+        dataTestId,
+        size,
+        container,
+        children,
+    ]);
+    if (mode === "sheet") {
+        return (jsxs(Portal, { root: rootElement, children: [isContained ? (jsx(Portal, { root: container.current, children: jsx("div", { ref: setSheetContainer, style: sheetContainerStyle }) })) : container === undefined ? (jsx("div", { ref: setSheetContainer, style: sheetContainerStyle })) : null, jsx(Sheet, { container: sheetContainer, "data-testid": dataTestId, entryAnimation: modeState.isModeSwitching ? "never" : "always", isOpen: isOpen, onClickHandle: sheetOnClickHandle, onCloseComplete: handleSheetCloseComplete, onCloseGesture: onCloseGesture, onGeometryChange: sheetOnGeometryChange, onSnap: sheetOnSnap, ref: sheetPanelRef, snap: sheetSnap, snapping: true, state: sheetState, trapFocus: false, variant: depthFromFront === 0 ? "modal" : "default", children: jsx(FloatingFocusManager, { context: context, restoreFocus: restoreFocus, children: jsx("div", { "aria-modal": true, className: cvaModalContentEnvironment({ className: "flex-grow" }), "data-modal-content": true, ref: ref, role: role, ...getFloatingProps(), children: children }) }) })] }));
+    }
+    if (cardModeInner === null) {
+        return jsx(Portal, { root: rootElement, children: null });
+    }
+    if (isContained) {
+        return (jsx(Portal, { root: rootElement, children: jsx(Portal, { root: container.current, children: jsx("div", { className: cvaModalBackdrop({
+                        contained: true,
+                        isFrontmost: depthFromFront === 0,
+                        shouldAnimate: stackSizeAtOpen === 0,
+                    }), children: cardModeInner }) }) }));
+    }
+    return (jsx(Portal, { root: rootElement, children: jsx(FloatingOverlay, { className: cvaModalBackdrop({ isFrontmost: depthFromFront === 0, shouldAnimate: stackSizeAtOpen === 0 }), lockScroll: true, children: cardModeInner }) }));
 };
-Modal.displayName = "Modal";
 
 const cvaModalBodyContainer = cvaMerge([
     "flex",
@@ -372,6 +418,7 @@ const ModalBody = forwardRef(({ children, id, "data-testid": dataTestId, classNa
 
 const cvaModalFooterContainer = cvaMerge([
     "flex",
+    "flex-none",
     // flex-wrap
     "justify-end",
     "flex-row",
@@ -595,11 +642,6 @@ const ModalHeader = forwardRef(({ heading, subHeading, onClickClose, "data-testi
  * - `stackSize`: Total modals open (local + host + iframe)
  * - `stackSizeAtOpen`: Stack size when this modal opened (for animation decisions)
  *
- * This enables the Modal component to:
- * - Scale down non-frontmost modals (visual stacking effect)
- * - Show backdrop only on the frontmost modal
- * - Choose appropriate animations based on whether it's opening over another modal
- *
  * @module modalStackRegistry
  */
 let modalStack = [];
@@ -756,7 +798,11 @@ const useModalStack = (isOpen) => {
     const depthFromFront = localDepthFromFront + hostModalCount;
     // Get the total stack size when this modal opened (stable once set)
     const stackSizeAtOpen = modalOpenState.get(modalId) ?? 0;
-    return useMemo(() => ({ depthFromFront, stackSize: totalStackSize, stackSizeAtOpen }), [depthFromFront, totalStackSize, stackSizeAtOpen]);
+    return useMemo(() => ({
+        depthFromFront,
+        stackSize: totalStackSize,
+        stackSizeAtOpen,
+    }), [depthFromFront, totalStackSize, stackSizeAtOpen]);
 };
 
 /**
@@ -767,9 +813,18 @@ const useModalStack = (isOpen) => {
  * - <Modal {...modal} size="medium" />
  */
 const useModal = (props) => {
-    const { isOpen: controlledIsOpen, defaultOpen, rootElement, dismiss: dismissOptions, onClose, onOpen, onOpenChange, onBeforeClose, ref: customRef, role, } = props ?? {};
+    const { isOpen: controlledIsOpen, defaultOpen, rootElement, dismiss: dismissOptions, onClose, onOpen, onOpenChange, onBeforeClose, ref: customRef, role, container, } = props ?? {};
+    const nullRef = useRef(null);
+    const containerBreakpoints = useContainerBreakpoints(container ?? nullRef, { skip: !container });
+    const viewportBreakpoints = useViewportBreakpoints({ skip: !!container });
+    const viewportCanDetect = viewportBreakpoints.isXs;
+    const mode = (container ? containerBreakpoints.isSm : !viewportCanDetect || viewportBreakpoints.isSm)
+        ? "card"
+        : "sheet";
     const [internalIsOpen, setIsOpen] = useState(defaultOpen ?? false);
-    const isOpen = typeof controlledIsOpen === "boolean" ? controlledIsOpen : internalIsOpen;
+    const [openDeferred, setOpenDeferred] = useState(false);
+    const openIdRef = useRef(0);
+    const isOpen = typeof controlledIsOpen === "boolean" ? controlledIsOpen && !openDeferred : internalIsOpen;
     const ref = useRef(null);
     // Prevents multiple confirmation dialogs from stacking when user rapidly triggers dismiss
     const isPendingCloseRef = useRef(false);
@@ -792,39 +847,80 @@ const useModal = (props) => {
         throw new Error("useModal must be used within the ModalDialogContextProvider");
     }
     const { openModal, closeModal } = modalDialogContext;
-    // Sync controlled isOpen state with iframe size controller
-    // This ensures the iframe resizes correctly when using controlled mode
+    const errorHandling = useContext(ErrorHandlingContext);
+    // Tracks whether a close is in-flight waiting for the Sheet's close animation
+    // to complete before calling closeModal() to resize the iframe back.
+    const pendingCloseModalRef = useRef(false);
+    const { startTimeout: startCloseTimeout, stopTimeout: stopCloseTimeout } = useTimeout({
+        onTimeout: () => {
+            if (pendingCloseModalRef.current) {
+                pendingCloseModalRef.current = false;
+                void closeModal();
+                errorHandling?.captureException(new Error("Modal close animation safety timeout: transitionend callback never fired"), { level: "warning" });
+            }
+        },
+        duration: SHEET_TRANSITION_DURATION_MS + 100,
+    });
+    const startPendingCloseModal = useCallback(() => {
+        pendingCloseModalRef.current = true;
+        startCloseTimeout();
+    }, [startCloseTimeout]);
+    const onCloseComplete = useCallback(() => {
+        if (pendingCloseModalRef.current) {
+            pendingCloseModalRef.current = false;
+            stopCloseTimeout();
+            void closeModal();
+        }
+    }, [stopCloseTimeout, closeModal]);
+    // Sync controlled isOpen state with iframe size controller.
+    // Defers rendering until the iframe has finished resizing to fullscreen
+    // so the modal animation plays after the resize, not during it.
     useWatch({
         value: controlledIsOpen,
         immediate: true,
         skip: typeof controlledIsOpen !== "boolean",
         onChange: (current, prev) => {
             if (current && !prev) {
-                void openModal();
+                const id = ++openIdRef.current;
+                const result = openModal();
+                if (result instanceof Promise) {
+                    setOpenDeferred(true);
+                    void result.then(() => {
+                        if (openIdRef.current === id) {
+                            setOpenDeferred(false);
+                        }
+                    });
+                }
             }
             else if (!current && prev) {
-                void closeModal();
+                openIdRef.current++;
+                setOpenDeferred(false);
+                startPendingCloseModal();
             }
         },
     });
-    // Cleanup: notify context when component unmounts while modal is open
+    // Cleanup: notify context when component unmounts while modal is open.
+    // Calls closeModal() directly (no animation to wait for during unmount).
     useEffect(() => {
         return () => {
+            stopCloseTimeout();
+            pendingCloseModalRef.current = false;
             if (isOpenRef.current) {
                 void closeModal();
             }
         };
-    }, [closeModal]);
+    }, [closeModal, stopCloseTimeout]);
     const handleClose = useCallback((event, reason) => {
+        openIdRef.current++;
+        setOpenDeferred(false);
         setIsOpen(false);
         onCloseRef.current?.(event, reason);
         onOpenChangeRef.current?.(false, event, reason);
-        void closeModal();
-    }, [closeModal]);
+        startPendingCloseModal();
+    }, [startPendingCloseModal]);
     const { refs, context } = useFloating({
         open: isOpen,
         onOpenChange: (newIsOpen, event, reason) => {
-            // Opening - just update state (same as original)
             if (newIsOpen) {
                 setIsOpen(true);
                 return;
@@ -854,30 +950,33 @@ const useModal = (props) => {
         whileElementsMounted: autoUpdate,
         middleware: [shift()],
     });
-    const { depthFromFront, stackSizeAtOpen } = useModalStack(isOpen);
-    const dismiss = useDismiss(context, { ...dismissOptions, enabled: depthFromFront === 0 });
-    const { getFloatingProps } = useInteractions([dismiss]);
-    const open = useCallback(() => {
+    const resolvedDismiss = useMemo(() => ({
+        escapeKey: dismissOptions?.escapeKey ?? true,
+        outsidePress: dismissOptions?.outsidePress ?? true,
+        gesture: dismissOptions?.gesture ?? true,
+    }), [dismissOptions]);
+    const stack = useModalStack(isOpen);
+    const dismissInteraction = useDismiss(context, { ...dismissOptions, enabled: stack.depthFromFront === 0 });
+    const { getFloatingProps } = useInteractions([dismissInteraction]);
+    const open = useCallback(async () => {
+        const id = ++openIdRef.current;
         onOpenRef.current?.();
         onOpenChangeRef.current?.(true);
-        setIsOpen(true);
-        void openModal();
+        await openModal();
+        if (openIdRef.current === id) {
+            setIsOpen(true);
+        }
     }, [openModal]);
-    const close = useCallback(() => {
-        // If onBeforeClose is provided, check it before closing
+    const requestClose = useCallback((event, reason) => {
         if (onBeforeCloseRef.current) {
-            // Already handling a close attempt, ignore this one
             if (isPendingCloseRef.current) {
                 return;
             }
             isPendingCloseRef.current = true;
-            void Promise.resolve(onBeforeCloseRef.current(undefined, "programmatic"))
+            void Promise.resolve(onBeforeCloseRef.current(event, reason))
                 .then(shouldClose => {
                 if (shouldClose) {
-                    onCloseRef.current?.(undefined, "programmatic");
-                    onOpenChangeRef.current?.(false, undefined, "programmatic");
-                    setIsOpen(false);
-                    void closeModal();
+                    handleClose(event, reason);
                 }
             })
                 .finally(() => {
@@ -885,17 +984,15 @@ const useModal = (props) => {
             });
             return;
         }
-        onCloseRef.current?.(undefined, "programmatic");
-        onOpenChangeRef.current?.(false, undefined, "programmatic");
-        setIsOpen(false);
-        void closeModal();
-    }, [closeModal]);
+        handleClose(event, reason);
+    }, [handleClose]);
+    const close = useCallback(() => requestClose(undefined, "programmatic"), [requestClose]);
     const toggle = useCallback(() => {
         if (isOpen) {
             close();
         }
         else {
-            open();
+            void open();
         }
     }, [isOpen, open, close]);
     return useMemo(() => ({
@@ -903,6 +1000,7 @@ const useModal = (props) => {
         toggle,
         open,
         close,
+        requestClose,
         ref: customRef ?? ref,
         floatingUi: {
             refs,
@@ -911,21 +1009,28 @@ const useModal = (props) => {
             getFloatingProps,
         },
         role,
-        depthFromFront,
-        stackSizeAtOpen,
+        dismiss: resolvedDismiss,
+        onCloseComplete,
+        stack,
+        mode,
+        container,
     }), [
         isOpen,
         toggle,
         open,
         close,
+        requestClose,
         customRef,
         refs,
         rootElement,
         context,
         getFloatingProps,
         role,
-        depthFromFront,
-        stackSizeAtOpen,
+        resolvedDismiss,
+        onCloseComplete,
+        stack,
+        mode,
+        container,
     ]);
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-modal",
-  "version": "1.21.4",
+  "version": "1.21.7",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -8,12 +8,12 @@
   },
   "dependencies": {
     "@floating-ui/react": "^0.26.25",
-    "@trackunit/react-components": "1.21.15",
+    "@trackunit/react-components": "1.21.18",
     "@trackunit/css-class-variance-utilities": "1.11.97",
     "@trackunit/shared-utils": "1.13.97",
     "@floating-ui/react-dom": "2.1.2",
-    "@trackunit/react-core-contexts-api": "1.15.10",
-    "@trackunit/i18n-library-translation": "1.18.2"
+    "@trackunit/react-core-contexts-api": "1.15.11",
+    "@trackunit/i18n-library-translation": "1.18.3"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.114.29",