@trackunit/react-modal 1.12.0 → 1.12.8

package/index.esm.js

@@ -1,9 +1,8 @@
 import { jsx, jsxs } from 'react/jsx-runtime';
 import { registerTranslations } from '@trackunit/i18n-library-translation';
-import { FloatingFocusManager, useFloating, shift, autoUpdate, useDismiss, useInteractions } from '@floating-ui/react';
-import { Portal, Card, Button, Heading, Text, IconButton, Icon, useScrollBlock } from '@trackunit/react-components';
-import { zIndex } from '@trackunit/ui-design-tokens';
-import { useRef, useLayoutEffect, forwardRef, useState, useContext, useEffect, useCallback, useMemo } from 'react';
+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, useId, useSyncExternalStore, useRef, forwardRef, useState, useContext, useEffect, useCallback, useMemo } from 'react';
 import { cvaMerge } from '@trackunit/css-class-variance-utilities';
 import { ModalDialogContext } from '@trackunit/react-core-contexts-api';
 
@@ -50,15 +49,14 @@ const setupLibraryTranslations = () => {
 };
 
 const cvaModalContainer = cvaMerge([
-    "h-full",
-    "w-full",
     "flex",
-    "fixed",
-    "inset-0",
-    "min-h-[100dvh]",
-    "min-w-[100dvw]",
-    "overflow-auto",
     "items-center",
+    // Allow clicks to pass through to FloatingOverlay for dismiss behavior
+    "pointer-events-none",
+    // Animate scale changes when stacking modals
+    "transition-transform",
+    "duration-200",
+    "ease-out",
 ]);
 const modalSizeConfigs = {
     small: {
@@ -115,10 +113,25 @@ const cvaModalCard = cvaMerge([
     "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))]",
     "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)
+    "pointer-events-auto",
+], {
+    variants: {
+        animation: {
+            // First modal in stack: simple fade
+            fade: "animate-fade-in-fast",
+            // Stacked modals: fade + rise from below
+            rise: "animate-fade-in-rising",
+        },
+    },
+    defaultVariants: {
+        animation: "fade",
+    },
+});
 const cvaModalBackdrop = cvaMerge([
+    "flex",
     "justify-center",
-    "items-center",
+    // "items-center",
     "fixed",
     "inset-0",
     "min-h-[100dvh]",
@@ -126,28 +139,25 @@ const cvaModalBackdrop = cvaMerge([
     "w-full",
     "h-full",
     "z-overlay",
-    "invisible",
-    "opacity-0",
-    "transition-all",
-    "bg-black/50",
-    "animate-modal-fade",
-]);
-
-/**
- * The Backdrop for the modal.
- *
- * @param {ModalBackdropProps} props - The props for the ModalBackdrop component
- * @returns {ReactElement} ModalBackdrop component
- */
-const ModalBackdrop = ({ children, onClick }) => {
-    const ref = useRef(null);
-    return (jsx("div", { className: cvaModalBackdrop(), onMouseDown: e => {
-            // only react on click on backdrop - accessing first child to get around styled element
-            if (ref.current !== null && e.target === ref.current.children[0]) {
-                onClick();
-            }
-        }, ref: ref, children: children }));
-};
+], {
+    variants: {
+        isFrontmost: {
+            // Frontmost modal shows backdrop
+            true: "bg-black/50",
+            // Non-frontmost modals have transparent backdrop with no transition (avoids flash)
+            false: ["bg-transparent", "transition-none"],
+        },
+        shouldAnimate: {
+            // Only animate backdrop when this is the first/only modal
+            true: "animate-fade-in-fast",
+            false: [],
+        },
+    },
+    defaultVariants: {
+        isFrontmost: true,
+        shouldAnimate: true,
+    },
+});
 
 function resolveRootEl(refLike) {
     if (refLike && typeof refLike === "object" && "current" in refLike) {
@@ -254,6 +264,244 @@ const useModalFooterBorder = (rootRef, { footerClass = "border-t", enabled = tru
     }, [enabled, footerClass, bodySelector, footerSelector, rootRef]);
 };
 
+/**
+ * Modal Stack Registry - Cross-Bundle Modal Awareness
+ *
+ * ## Architecture Overview
+ *
+ * This module provides a registry for tracking open modals across bundle boundaries
+ * (host application + Iris app iframes). It enables proper modal stacking behavior
+ * where modals can visually indicate their depth (scale, backdrop visibility, animations).
+ *
+ * ## Why postMessage Instead of Penpal?
+ *
+ * While most host-iframe communication uses Penpal (RPC-style), modal stack changes
+ * use raw postMessage for these reasons:
+ *
+ * 1. **Package Independence**: This module is part of `@trackunit/react-modal`, a standalone
+ *    UI component library. It should not depend on `iris-app-runtime` to avoid circular
+ *    dependencies and keep the modal component reusable.
+ *
+ * 2. **Broadcast Semantics**: When a host modal opens, ALL iframe modals need to know
+ *    simultaneously (not just one specific connection). postMessage with broadcast
+ *    to all iframes fits this pattern naturally.
+ *
+ * 3. **Low Latency**: Stack count changes need real-time sync for smooth animations
+ *    (scale transforms, backdrop fading). Raw postMessage has less overhead than Penpal.
+ *
+ * 4. **Module Isolation**: Each bundle (host + each iframe) gets its own instance of
+ *    this registry. They need cross-window synchronization, not shared state.
+ *
+ * ## Communication Flow
+ *
+ * ```
+ * ┌─────────────────────────────────────────────────────────────────────┐
+ * │ HOST APPLICATION                                                    │
+ * │                                                                     │
+ * │  modalStackRegistry ←───────────────────────────────────────────┐   │
+ * │       │                                                         │   │
+ * │       │ subscribe()                                             │   │
+ * │       ▼                                                         │   │
+ * │  ModalDialogProviderHost                                        │   │
+ * │       │                                                         │   │
+ * │       ├─► broadcasts MODAL_STACK_MESSAGE_TYPE to all iframes    │   │
+ * │       │                                                         │   │
+ * │       └─► listens for IFRAME_MODAL_STACK_MESSAGE_TYPE ──────────┘   │
+ * │           (aggregates per-iframe, cleans up on iframe removal)      │
+ * └─────────────────────────────────────────────────────────────────────┘
+ *                              │
+ *                    postMessage (bidirectional)
+ *                              │
+ * ┌─────────────────────────────────────────────────────────────────────┐
+ * │ IFRAME (Iris App)                                                   │
+ * │                                                                     │
+ * │  modalStackRegistry (separate instance)                             │
+ * │       │                                                             │
+ * │       ├─► listens for MODAL_STACK_MESSAGE_TYPE from host            │
+ * │       │   (updates hostModalCount)                                  │
+ * │       │                                                             │
+ * │       └─► on register/unregister, broadcasts                        │
+ * │           IFRAME_MODAL_STACK_MESSAGE_TYPE to parent                 │
+ * └─────────────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * ## Usage with useModalStack Hook
+ *
+ * The `useModalStack` hook consumes this registry to calculate:
+ * - `depthFromFront`: How many modals are in front of this one (0 = frontmost)
+ * - `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 = [];
+let hostModalCount = 0;
+let iframeModalCount = 0;
+const listeners = new Set();
+const notify = () => listeners.forEach(listener => listener());
+/**
+ * Message type for host → iframe modal stack communication.
+ * The host broadcasts this to all iframes when its modal count changes.
+ * Iframes listen for this to update their `hostModalCount`.
+ */
+const MODAL_STACK_MESSAGE_TYPE = "IRIS_APP_HOST_MODAL_STACK_CHANGE";
+/**
+ * Message type for iframe → host modal stack communication.
+ * Each iframe sends this to the parent when its modal count changes.
+ * The host aggregates these per-iframe for accurate total tracking.
+ */
+const IFRAME_MODAL_STACK_MESSAGE_TYPE = "IRIS_APP_IFRAME_MODAL_STACK_CHANGE";
+const isInIframe = typeof window !== "undefined" && window.parent !== window;
+/**
+ * Broadcast this iframe's modal count to the parent (host).
+ * Only runs when in an iframe context. Called automatically on register/unregister.
+ */
+const broadcastToParent = (modalCount) => {
+    if (isInIframe) {
+        window.parent.postMessage({ type: IFRAME_MODAL_STACK_MESSAGE_TYPE, data: { iframeModalCount: modalCount } }, "*");
+    }
+};
+/**
+ * Set up the global message listener for cross-bundle modal stack communication.
+ * This listener runs in the same bundle context as the Modal components, ensuring
+ * the correct registry instance is updated.
+ *
+ * Note: The host also has a separate listener in ModalDialogProviderHost that
+ * tracks per-iframe counts and handles cleanup when iframes are removed.
+ */
+if (typeof window !== "undefined") {
+    window.addEventListener("message", event => {
+        // Host → Iframe: Update host modal count
+        if (event.data?.type === MODAL_STACK_MESSAGE_TYPE && typeof event.data?.data?.hostModalCount === "number") {
+            modalStackRegistry.setHostModalCount(event.data.data.hostModalCount);
+        }
+        // Iframe → Host: Update iframe modal count (fallback, primary handler is in ModalDialogProviderHost)
+        if (event.data?.type === IFRAME_MODAL_STACK_MESSAGE_TYPE &&
+            typeof event.data?.data?.iframeModalCount === "number") {
+            modalStackRegistry.setIframeModalCount(event.data.data.iframeModalCount);
+        }
+    });
+}
+/**
+ * Module-level registry to track the stack of open modals.
+ *
+ * This registry enables:
+ * - Tracking modal order within a single bundle (local stack)
+ * - Awareness of modals in other bundles (host ↔ iframe communication)
+ * - Subscriber notifications for React integration via useSyncExternalStore
+ *
+ * Cross-bundle counts:
+ * - `hostModalCount`: Number of modals open in the host (relevant for iframes)
+ * - `iframeModalCount`: Number of modals open in iframes (relevant for host)
+ *
+ * Note: This is intentionally NOT a React hook because:
+ * 1. It needs to be a singleton that persists across React component lifecycles
+ * 2. It must work with postMessage for cross-bundle communication (host ↔ iframe)
+ * 3. The useModalStack hook consumes this registry via useSyncExternalStore for React integration
+ */
+const modalStackRegistry = {
+    register: (id) => {
+        modalStack.push(id);
+        notify();
+        // If in iframe, notify parent of our modal count
+        broadcastToParent(modalStack.length);
+    },
+    unregister: (id) => {
+        modalStack = modalStack.filter(modalId => modalId !== id);
+        notify();
+        // If in iframe, notify parent of our modal count
+        broadcastToParent(modalStack.length);
+    },
+    getStackPosition: (id) => modalStack.indexOf(id),
+    getStackSize: () => modalStack.length,
+    /** Get the number of modals open in the host (only relevant for Iris apps in iframes) */
+    getHostModalCount: () => hostModalCount,
+    /** Get the number of modals open in iframes (only relevant for host) */
+    getIframeModalCount: () => iframeModalCount,
+    /** Set the host modal count (called when receiving messages from host) */
+    setHostModalCount: (count) => {
+        if (hostModalCount !== count) {
+            hostModalCount = count;
+            notify();
+        }
+    },
+    /** Set the iframe modal count (called when receiving messages from iframes) */
+    setIframeModalCount: (count) => {
+        if (iframeModalCount !== count) {
+            iframeModalCount = count;
+            notify();
+        }
+    },
+    subscribe: (listener) => {
+        listeners.add(listener);
+        return () => {
+            listeners.delete(listener);
+        };
+    },
+};
+
+// Track the stack size when each modal opened (includes host modals for proper animation)
+const modalOpenState = new Map();
+/**
+ * Hook to track this modal's position in the stack of open modals.
+ * Returns the depth from front (0 = frontmost, 1 = one modal in front, etc.)
+ *
+ * This hook is aware of modals across bundle boundaries (host + Iris apps)
+ * by listening for host modal count changes via postMessage.
+ *
+ * @param isOpen - Whether the modal is currently open
+ */
+const useModalStack = (isOpen) => {
+    const modalId = useId();
+    // Subscribe to stack changes to re-render when stack updates
+    const localStackSize = useSyncExternalStore(modalStackRegistry.subscribe, modalStackRegistry.getStackSize, modalStackRegistry.getStackSize);
+    // Subscribe to host modal count (only relevant for Iris apps in iframes)
+    const hostModalCount = useSyncExternalStore(modalStackRegistry.subscribe, modalStackRegistry.getHostModalCount, modalStackRegistry.getHostModalCount);
+    // Subscribe to iframe modal count (only relevant for host)
+    const iframeModalCount = useSyncExternalStore(modalStackRegistry.subscribe, modalStackRegistry.getIframeModalCount, modalStackRegistry.getIframeModalCount);
+    const stackPosition = useSyncExternalStore(modalStackRegistry.subscribe, () => modalStackRegistry.getStackPosition(modalId), () => modalStackRegistry.getStackPosition(modalId));
+    // Register/unregister based on open state
+    // useLayoutEffect ensures registration happens before paint to avoid backdrop flash
+    useLayoutEffect(() => {
+        if (isOpen) {
+            // Capture total stack size before registering (includes cross-bundle modals for proper animation)
+            // - hostModalCount: modals in host (relevant for iframes)
+            // - iframeModalCount: modals in iframes (relevant for host)
+            const totalSizeAtOpen = modalStackRegistry.getStackSize() +
+                modalStackRegistry.getHostModalCount() +
+                modalStackRegistry.getIframeModalCount();
+            modalOpenState.set(modalId, totalSizeAtOpen);
+            modalStackRegistry.register(modalId);
+            return () => {
+                modalStackRegistry.unregister(modalId);
+                modalOpenState.delete(modalId);
+            };
+        }
+        return undefined;
+    }, [isOpen, modalId]);
+    // Total stack size includes local modals, host modals, and iframe modals
+    const totalStackSize = localStackSize + hostModalCount + iframeModalCount;
+    // Calculate depth from front (0 = frontmost)
+    // Host modals are always "on top" of Iris app modals, so if hostModalCount > 0,
+    // all Iris app modals have at least that many modals in front of them
+    const localDepthFromFront = stackPosition >= 0 ? localStackSize - 1 - stackPosition : 0;
+    const depthFromFront = localDepthFromFront + hostModalCount;
+    // Get the total stack size when this modal opened (stable once set)
+    const stackSizeAtOpen = modalOpenState.get(modalId) ?? 0;
+    return {
+        depthFromFront,
+        stackSize: totalStackSize,
+        stackSizeAtOpen,
+    };
+};
+
+/** Scale factor per modal depth level (5% smaller per level back) */
+const SCALE_FACTOR_PER_LEVEL = 0.05;
 /**
  * - Modals are used to present critical information or request user input needed to complete a user's workflow.
  * - Modals interrupt a user's workflow by design.
@@ -270,9 +518,9 @@ const useModalFooterBorder = (rootRef, { footerClass = "border-t", enabled = tru
  *  );
  * };
  *
- * const childComponent = ({...modalProps}: UseModalReturnValue) => {
+ * const ChildComponent = ({...modalProps}: UseModalReturnValue) => {
  *  return (* <Modal {...modalProps}>
- *      <ModalHeader onClose={modalProps.close} heading="My Modal" />
+ *      <ModalHeader onClickClose={modalProps.close} heading="My Modal" />
  *      <ModalBody>
  *        <p>This is a modal</p>
  *      </ModalBody>
@@ -281,14 +529,21 @@ const useModalFooterBorder = (rootRef, { footerClass = "border-t", enabled = tru
  * };
  * ```
  */
-const Modal = ({ children, isOpen, role = "dialog", "data-testid": dataTestId, className, size, onBackdropClick, floatingUi, ref, }) => {
+const Modal = ({ children, isOpen, role = "dialog", "data-testid": dataTestId, className, size, floatingUi, ref, }) => {
     // 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 { 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" });
-    return (jsx(Portal, { root: rootElement, children: isOpen ? (jsx(FloatingFocusManager, { context: context, children: jsx("div", { ref: refs.setFloating, style: { zIndex: zIndex.overlay }, ...getFloatingProps(), children: jsx(ModalBackdrop, { onClick: onBackdropClick, children: jsx("div", { "aria-modal": true, className: cvaModalContainer(), ref: ref, role: role, children: jsx(Card, { className: cvaModalCard({ className }), "data-testid": dataTestId, ref: cardRef, style: getModalCardCSSVariables(size), children: children }) }) }) }) })) : null }));
+    // Track modal stack position for stacked modal styling
+    const { depthFromFront, stackSizeAtOpen } = useModalStack(isOpen);
+    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, 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 }));
 };
 Modal.displayName = "Modal";
 
@@ -342,7 +597,7 @@ const cvaModalBodyContainer = cvaMerge([
  * @returns {ReactElement} Modal body wrapper element.
  */
 const ModalBody = forwardRef(({ children, id, "data-testid": dataTestId, className }, ref) => {
-    return (jsx("div", { className: cvaModalBodyContainer({ className }), "data-modal-body": true, "data-testid": dataTestId, id: id, children: children }));
+    return (jsx("div", { className: cvaModalBodyContainer({ className }), "data-modal-body": true, "data-testid": dataTestId, id: id, ref: ref, children: children }));
 });
 
 const cvaModalFooterContainer = cvaMerge([
@@ -487,15 +742,15 @@ const cvaIconContainer = cvaMerge(["flex", "place-items-center"]);
  * @param {ModalHeaderProps} props Component props.
  * @param {string} [props.heading] Main heading text.
  * @param {string} [props.subHeading] Optional subheading content.
- * @param {() => void} props.onClose Close button click handler.
+ * @param {() => void} props.onClickClose Close button click handler.
  * @param {string} [props."data-testid"] Optional test id for the container.
  * @param {string} [props.className] Optional additional class name(s).
- * @returns {ReactElement} The modal header element.
+ * @returns The modal header element.
  */
-const ModalHeader = forwardRef(({ heading, subHeading, onClose, "data-testid": dataTestId, className, id, children, accessories }, ref) => {
+const ModalHeader = forwardRef(({ heading, subHeading, onClickClose, "data-testid": dataTestId, className, id, children, accessories, }, ref) => {
     return (jsxs("div", { className: cvaContainer({
             className,
-        }), "data-testid": dataTestId, id: id, children: [jsxs("div", { className: cvaHeadingContainer(), children: [jsxs("div", { className: cvaTitleContainer(), children: [jsx(Heading, { variant: "tertiary", children: heading }), accessories] }), Boolean(subHeading) ? (jsx(Text, { size: "small", subtle: true, children: subHeading })) : null, children] }), jsx("div", { className: cvaIconContainer(), children: jsx(IconButton, { className: "!h-min", "data-testid": dataTestId ? `${dataTestId}-close-button` : "modal-close-button", icon: jsx(Icon, { name: "XMark", size: "small" }), onClick: onClose, size: "small", variant: "ghost-neutral" }) })] }));
+        }), "data-testid": dataTestId, id: id, ref: ref, children: [jsxs("div", { className: cvaHeadingContainer(), children: [jsxs("div", { className: cvaTitleContainer(), children: [jsx(Heading, { variant: "tertiary", children: heading }), accessories] }), Boolean(subHeading) ? (jsx(Text, { size: "small", subtle: true, children: subHeading })) : null, children] }), jsx("div", { className: cvaIconContainer(), children: jsx(IconButton, { className: "!h-min", "data-testid": dataTestId ? `${dataTestId}-close-button` : "modal-close-button", icon: jsx(Icon, { name: "XMark", size: "small" }), onClick: onClickClose, size: "small", variant: "ghost-neutral" }) })] }));
 });
 
 /**
@@ -506,89 +761,142 @@ const ModalHeader = forwardRef(({ heading, subHeading, onClose, "data-testid": d
  * - <Modal {...modal} size="medium" />
  */
 const useModal = (props) => {
-    const { isOpen: controlledIsOpen, onOpenChange, rootElement, closeOnOutsideClick = true, closeOnEsc = true, onClose, onOpen, ref: customRef, role, } = props ?? {};
-    const [internalIsOpen, setIsOpen] = useState(Boolean(controlledIsOpen));
+    const { isOpen: controlledIsOpen, defaultOpen, rootElement, dismiss: dismissOptions, onClose, onOpen, onOpenChange, onBeforeClose, ref: customRef, role, } = props ?? {};
+    const [internalIsOpen, setIsOpen] = useState(defaultOpen ?? false);
     const isOpen = typeof controlledIsOpen === "boolean" ? controlledIsOpen : internalIsOpen;
-    const { blockScroll, restoreScroll } = useScrollBlock();
     const ref = useRef(null);
+    // Prevents multiple confirmation dialogs from stacking when user rapidly triggers dismiss
+    const isPendingCloseRef = useRef(false);
+    // Store callbacks and state in refs to keep open/close/toggle stable across renders
+    // This prevents cascading re-renders when consumers pass inline callbacks
+    const onCloseRef = useRef(onClose);
+    const onOpenRef = useRef(onOpen);
+    const onOpenChangeRef = useRef(onOpenChange);
+    const onBeforeCloseRef = useRef(onBeforeClose);
+    const isOpenRef = useRef(isOpen);
+    useLayoutEffect(() => {
+        onCloseRef.current = onClose;
+        onOpenRef.current = onOpen;
+        onOpenChangeRef.current = onOpenChange;
+        onBeforeCloseRef.current = onBeforeClose;
+        isOpenRef.current = isOpen;
+    });
     const modalDialogContext = useContext(ModalDialogContext);
     if (!modalDialogContext) {
         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
+    useWatch({
+        value: controlledIsOpen,
+        immediate: true,
+        skip: typeof controlledIsOpen !== "boolean",
+        onChange: (current, prev) => {
+            if (current && !prev) {
+                void openModal();
+            }
+            else if (!current && prev) {
+                void closeModal();
+            }
+        },
+    });
+    // Cleanup: notify context when component unmounts while modal is open
+    useEffect(() => {
+        return () => {
+            if (isOpenRef.current) {
+                void closeModal();
+            }
+        };
+    }, [closeModal]);
+    const handleClose = useCallback((event, reason) => {
+        setIsOpen(false);
+        onCloseRef.current?.(event, reason);
+        onOpenChangeRef.current?.(false, event, reason);
+        void closeModal();
+    }, [closeModal]);
     const { refs, context } = useFloating({
         open: isOpen,
-        onOpenChange: (newIsOpen, event, openChangeReason) => {
+        onOpenChange: (newIsOpen, event, reason) => {
+            // Opening - just update state (same as original)
             if (newIsOpen) {
-                blockScroll();
-            }
-            else {
-                restoreScroll();
+                setIsOpen(true);
+                return;
             }
-            if (onOpenChange) {
-                return onOpenChange(newIsOpen, event, openChangeReason);
+            // Only pass through the modal-relevant reasons
+            const modalReason = reason === "outside-press" || reason === "escape-key" ? reason : undefined;
+            if (modalReason && onBeforeCloseRef.current) {
+                // Already handling a close attempt, ignore this dismiss event
+                if (isPendingCloseRef.current) {
+                    return;
+                }
+                isPendingCloseRef.current = true;
+                void Promise.resolve(onBeforeCloseRef.current(event, modalReason))
+                    .then(shouldClose => {
+                    if (shouldClose) {
+                        handleClose(event, modalReason);
+                    }
+                })
+                    .finally(() => {
+                    isPendingCloseRef.current = false;
+                });
+                return;
             }
-            setIsOpen(newIsOpen);
+            // Normal close flow (no onBeforeClose, or not a dismiss reason)
+            handleClose(event, modalReason);
         },
         whileElementsMounted: autoUpdate,
         middleware: [shift()],
     });
-    const dismiss = useDismiss(context, {
-        escapeKey: closeOnEsc,
-        outsidePress: closeOnOutsideClick,
-    });
+    const dismiss = useDismiss(context, dismissOptions);
     const { getFloatingProps } = useInteractions([dismiss]);
-    // Handles closing and opening the modal outside of Iris apps/outside an iframe.
-    useEffect(() => {
-        if (isOpen) {
-            openModal();
-        }
-        else {
-            closeModal();
-        }
-        // Return cleanup function that ensures modal is closed when component unmounts
-        return () => {
-            closeModal();
-        };
-    }, [isOpen, openModal, closeModal]);
-    const open = useCallback((...args) => {
-        onOpen?.(...args);
-        blockScroll();
+    const open = useCallback(() => {
+        onOpenRef.current?.();
+        onOpenChangeRef.current?.(true);
         setIsOpen(true);
-    }, [onOpen, blockScroll]);
-    const close = useCallback((...args) => {
-        for (const arg of args) {
-            if (!arg || typeof arg !== "object") {
-                continue;
-            }
-            // @ts-ignore
-            if ("preventDefault" in arg) {
-                arg.preventDefault();
-            }
-            // @ts-ignore
-            if ("stopPropagation" in arg) {
-                arg.stopPropagation();
+        void openModal();
+    }, [openModal]);
+    const close = useCallback(() => {
+        // If onBeforeClose is provided, check it before closing
+        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"))
+                .then(shouldClose => {
+                if (shouldClose) {
+                    onCloseRef.current?.(undefined, "programmatic");
+                    onOpenChangeRef.current?.(false, undefined, "programmatic");
+                    setIsOpen(false);
+                    void closeModal();
+                }
+            })
+                .finally(() => {
+                isPendingCloseRef.current = false;
+            });
+            return;
         }
-        onClose?.(...args);
-        restoreScroll();
+        onCloseRef.current?.(undefined, "programmatic");
+        onOpenChangeRef.current?.(false, undefined, "programmatic");
         setIsOpen(false);
-    }, [onClose, restoreScroll]);
-    const toggle = useCallback((...args) => {
+        void closeModal();
+    }, [closeModal]);
+    const toggle = useCallback(() => {
         if (isOpen) {
-            return close(...args);
+            close();
+        }
+        else {
+            open();
         }
-        return open(...args);
-    }, [close, isOpen, open]);
+    }, [isOpen, open, close]);
     return useMemo(() => ({
         isOpen,
-        closeOnOutsideClick,
         toggle,
         open,
         close,
         ref: customRef ?? ref,
-        // @ts-ignore TOnCloseArgs could be instantiated with a different subtype of constraint BaseUseModalActionArgs
-        onBackdropClick: () => (closeOnOutsideClick ? close() : null),
         floatingUi: {
             refs,
             rootElement,
@@ -596,7 +904,7 @@ const useModal = (props) => {
             getFloatingProps,
         },
         role,
-    }), [isOpen, closeOnOutsideClick, toggle, open, close, customRef, refs, rootElement, context, getFloatingProps, role]);
+    }), [isOpen, toggle, open, close, customRef, refs, rootElement, context, getFloatingProps, role]);
 };
 
 /*
@@ -608,4 +916,4 @@ const useModal = (props) => {
  */
 setupLibraryTranslations();
 
-export { Modal, ModalBackdrop, ModalBody, ModalFooter, ModalHeader, useModal };
+export { IFRAME_MODAL_STACK_MESSAGE_TYPE, MODAL_STACK_MESSAGE_TYPE, Modal, ModalBody, ModalFooter, ModalHeader, modalStackRegistry, useModal };

package/package.json

@@ -1,21 +1,20 @@
 {
   "name": "@trackunit/react-modal",
-  "version": "1.12.0",
+  "version": "1.12.8",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "react": "19.0.0",
-    "@trackunit/react-components": "1.15.0",
-    "@trackunit/css-class-variance-utilities": "1.11.0",
-    "@trackunit/i18n-library-translation": "1.11.0",
     "@floating-ui/react": "^0.26.25",
+    "@trackunit/react-components": "1.15.8",
+    "react": "19.0.0",
+    "@trackunit/css-class-variance-utilities": "1.11.7",
+    "@trackunit/shared-utils": "1.13.7",
     "@floating-ui/react-dom": "2.1.2",
-    "@trackunit/ui-design-tokens": "1.11.0",
-    "@trackunit/react-core-contexts-api": "1.12.0",
-    "@trackunit/shared-utils": "1.13.0"
+    "@trackunit/react-core-contexts-api": "1.12.7",
+    "@trackunit/i18n-library-translation": "1.11.7"
   },
   "module": "./index.esm.js",
   "main": "./index.cjs.js",