@trackunit/react-modal 1.20.10 → 1.20.11

package/index.cjs.js

@@ -266,238 +266,6 @@ 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 = react.useId();
-    // Subscribe to stack changes to re-render when stack updates
-    const localStackSize = react.useSyncExternalStore(modalStackRegistry.subscribe, modalStackRegistry.getStackSize, modalStackRegistry.getStackSize);
-    // Subscribe to host modal count (only relevant for Iris apps in iframes)
-    const hostModalCount = react.useSyncExternalStore(modalStackRegistry.subscribe, modalStackRegistry.getHostModalCount, modalStackRegistry.getHostModalCount);
-    // Subscribe to iframe modal count (only relevant for host)
-    const iframeModalCount = react.useSyncExternalStore(modalStackRegistry.subscribe, modalStackRegistry.getIframeModalCount, modalStackRegistry.getIframeModalCount);
-    const stackPosition = react.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
-    react.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 react.useMemo(() => ({ depthFromFront, stackSize: totalStackSize, stackSizeAtOpen }), [depthFromFront, totalStackSize, stackSizeAtOpen]);
-};
-
 /** Scale factor per modal depth level (5% smaller per level back) */
 const SCALE_FACTOR_PER_LEVEL = 0.05;
 /**
@@ -535,7 +303,7 @@ 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, }) => {
+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
@@ -544,8 +312,6 @@ const Modal = ({ children, isOpen, role = "dialog", "data-testid": dataTestId, c
     // Merge the custom ref from useModal with FloatingUI's setFloating ref
     const mergedRef = react$1.useMergeRefs([refs.setFloating, ref]);
     useModalFooterBorder(cardRef, { enabled: isOpen, footerClass: "border-t pt-4" });
-    // Track modal stack position for stacked modal styling
-    const { depthFromFront, stackSizeAtOpen } = useModalStack(isOpen);
     const isFrontmost = depthFromFront === 0;
     return (jsxRuntime.jsx(reactComponents.Portal, { root: rootElement, children: isOpen ? (jsxRuntime.jsx(react$1.FloatingOverlay, { className: cvaModalBackdrop({ isFrontmost, shouldAnimate: stackSizeAtOpen === 0 }), lockScroll: true, children: jsxRuntime.jsx(react$1.FloatingFocusManager, { context: context, restoreFocus: restoreFocus, children: jsxRuntime.jsx("div", { "aria-modal": true, className: cvaModalContainer(), ref: mergedRef, role: role, 
                     // Scale down modals that are behind the frontmost
@@ -763,6 +529,238 @@ const ModalHeader = react.forwardRef(({ heading, subHeading, onClickClose, "data
         }), "data-testid": dataTestId, id: id, ref: ref, children: [jsxRuntime.jsxs("div", { className: cvaHeadingContainer(), children: [jsxRuntime.jsxs("div", { className: cvaTitleContainer(), children: [jsxRuntime.jsx(reactComponents.Heading, { variant: "tertiary", children: heading }), accessories] }), Boolean(subHeading) ? (jsxRuntime.jsx(reactComponents.Text, { size: "small", subtle: true, children: subHeading })) : null, children] }), jsxRuntime.jsx("div", { className: cvaIconContainer(), children: jsxRuntime.jsx(reactComponents.IconButton, { className: "!h-min", "data-testid": dataTestId ? `${dataTestId}-close-button` : "modal-close-button", icon: jsxRuntime.jsx(reactComponents.Icon, { name: "XMark", size: "small" }), onClick: onClickClose, size: "small", variant: "ghost-neutral" }) })] }));
 });
 
+/**
+ * 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 = react.useId();
+    // Subscribe to stack changes to re-render when stack updates
+    const localStackSize = react.useSyncExternalStore(modalStackRegistry.subscribe, modalStackRegistry.getStackSize, modalStackRegistry.getStackSize);
+    // Subscribe to host modal count (only relevant for Iris apps in iframes)
+    const hostModalCount = react.useSyncExternalStore(modalStackRegistry.subscribe, modalStackRegistry.getHostModalCount, modalStackRegistry.getHostModalCount);
+    // Subscribe to iframe modal count (only relevant for host)
+    const iframeModalCount = react.useSyncExternalStore(modalStackRegistry.subscribe, modalStackRegistry.getIframeModalCount, modalStackRegistry.getIframeModalCount);
+    const stackPosition = react.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
+    react.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 react.useMemo(() => ({ depthFromFront, stackSize: totalStackSize, stackSizeAtOpen }), [depthFromFront, totalStackSize, stackSizeAtOpen]);
+};
+
 /**
  * A hook to handle the state and configuration of Modal components.
  *
@@ -858,7 +856,8 @@ const useModal = (props) => {
         whileElementsMounted: react$1.autoUpdate,
         middleware: [react$1.shift()],
     });
-    const dismiss = react$1.useDismiss(context, dismissOptions);
+    const { depthFromFront, stackSizeAtOpen } = useModalStack(isOpen);
+    const dismiss = react$1.useDismiss(context, { ...dismissOptions, enabled: depthFromFront === 0 });
     const { getFloatingProps } = react$1.useInteractions([dismiss]);
     const open = react.useCallback(() => {
         onOpenRef.current?.();
@@ -914,7 +913,22 @@ const useModal = (props) => {
             getFloatingProps,
         },
         role,
-    }), [isOpen, toggle, open, close, customRef, refs, rootElement, context, getFloatingProps, role]);
+        depthFromFront,
+        stackSizeAtOpen,
+    }), [
+        isOpen,
+        toggle,
+        open,
+        close,
+        customRef,
+        refs,
+        rootElement,
+        context,
+        getFloatingProps,
+        role,
+        depthFromFront,
+        stackSizeAtOpen,
+    ]);
 };
 
 /*

package/index.esm.js

@@ -2,7 +2,7 @@ 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, useId, useSyncExternalStore, useMemo, useRef, forwardRef, useState, useContext, useEffect, useCallback } from 'react';
+import { useLayoutEffect, useRef, forwardRef, useId, useSyncExternalStore, useMemo, useState, useContext, useEffect, useCallback } from 'react';
 import { cvaMerge } from '@trackunit/css-class-variance-utilities';
 import { ModalDialogContext } from '@trackunit/react-core-contexts-api';
 
@@ -264,238 +264,6 @@ 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 useMemo(() => ({ depthFromFront, stackSize: totalStackSize, stackSizeAtOpen }), [depthFromFront, totalStackSize, stackSizeAtOpen]);
-};
-
 /** Scale factor per modal depth level (5% smaller per level back) */
 const SCALE_FACTOR_PER_LEVEL = 0.05;
 /**
@@ -533,7 +301,7 @@ 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, }) => {
+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
@@ -542,8 +310,6 @@ const Modal = ({ children, isOpen, role = "dialog", "data-testid": dataTestId, c
     // 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" });
-    // 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, restoreFocus: restoreFocus, children: jsx("div", { "aria-modal": true, className: cvaModalContainer(), ref: mergedRef, role: role, 
                     // Scale down modals that are behind the frontmost
@@ -761,6 +527,238 @@ const ModalHeader = forwardRef(({ heading, subHeading, onClickClose, "data-testi
         }), "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" }) })] }));
 });
 
+/**
+ * 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 useMemo(() => ({ depthFromFront, stackSize: totalStackSize, stackSizeAtOpen }), [depthFromFront, totalStackSize, stackSizeAtOpen]);
+};
+
 /**
  * A hook to handle the state and configuration of Modal components.
  *
@@ -856,7 +854,8 @@ const useModal = (props) => {
         whileElementsMounted: autoUpdate,
         middleware: [shift()],
     });
-    const dismiss = useDismiss(context, dismissOptions);
+    const { depthFromFront, stackSizeAtOpen } = useModalStack(isOpen);
+    const dismiss = useDismiss(context, { ...dismissOptions, enabled: depthFromFront === 0 });
     const { getFloatingProps } = useInteractions([dismiss]);
     const open = useCallback(() => {
         onOpenRef.current?.();
@@ -912,7 +911,22 @@ const useModal = (props) => {
             getFloatingProps,
         },
         role,
-    }), [isOpen, toggle, open, close, customRef, refs, rootElement, context, getFloatingProps, role]);
+        depthFromFront,
+        stackSizeAtOpen,
+    }), [
+        isOpen,
+        toggle,
+        open,
+        close,
+        customRef,
+        refs,
+        rootElement,
+        context,
+        getFloatingProps,
+        role,
+        depthFromFront,
+        stackSizeAtOpen,
+    ]);
 };
 
 /*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-modal",
-  "version": "1.20.10",
+  "version": "1.20.11",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
@@ -8,7 +8,7 @@
   },
   "dependencies": {
     "@floating-ui/react": "^0.26.25",
-    "@trackunit/react-components": "1.21.7",
+    "@trackunit/react-components": "1.21.8",
     "@trackunit/css-class-variance-utilities": "1.11.92",
     "@trackunit/shared-utils": "1.13.92",
     "@floating-ui/react-dom": "2.1.2",
@@ -16,6 +16,7 @@
     "@trackunit/i18n-library-translation": "1.17.6"
   },
   "peerDependencies": {
+    "@tanstack/react-router": "^1.114.29",
     "react": "^19.0.0"
   },
   "module": "./index.esm.js",

package/src/modal/Modal.d.ts

@@ -61,6 +61,6 @@ export type ModalProps = PropsWithChildren<UseModalReturnValue & {
  * @returns {ReactElement} Modal component
  */
 export declare const Modal: {
-    ({ children, isOpen, role, "data-testid": dataTestId, className, size, floatingUi, ref, restoreFocus, }: ModalProps): ReactElement;
+    ({ children, isOpen, role, "data-testid": dataTestId, className, size, floatingUi, ref, restoreFocus, depthFromFront, stackSizeAtOpen, }: ModalProps): ReactElement;
     displayName: string;
 };

package/src/modal/useModal.d.ts

@@ -133,6 +133,16 @@ export type UseModalReturnValue = {
      * The aria role for the modal.
      */
     role?: AriaRole;
+    /**
+     * How many modals are stacked in front of this one (0 = frontmost).
+     * Used by Modal for visual stacking (scale, backdrop).
+     */
+    depthFromFront: number;
+    /**
+     * The total modal stack size when this modal opened.
+     * Used by Modal for animation decisions.
+     */
+    stackSizeAtOpen: number;
 };
 /**
  * A hook to handle the state and configuration of Modal components.