@trackunit/react-modal 1.12.0 → 1.12.7

package/src/index.d.ts

@@ -1,6 +1,6 @@
 export * from "./modal/Modal";
-export * from "./modal/ModalBackdrop";
 export * from "./modal/ModalBody/ModalBody";
 export * from "./modal/ModalFooter/ModalFooter";
 export * from "./modal/ModalHeader/ModalHeader";
+export * from "./modal/modalStackRegistry";
 export * from "./modal/useModal";

package/src/modal/Modal.d.ts

@@ -1,10 +1,10 @@
 import { Size } from "@trackunit/react-components";
 import { PropsWithChildren, ReactElement } from "react";
-import { BaseUseModalActionArgs, UseModalReturnValue } from "./useModal";
+import { UseModalReturnValue } from "./useModal";
 /**
  * Modal props extend the return type of useModal and add presentational-only props.
  */
-export type ModalProps<TOnCloseFnArgs extends BaseUseModalActionArgs = [], TOnOpenFnArgs extends BaseUseModalActionArgs = []> = PropsWithChildren<UseModalReturnValue<TOnCloseFnArgs, TOnOpenFnArgs> & {
+export type ModalProps = PropsWithChildren<UseModalReturnValue & {
     /**
      * The size of the modal card.
      */
@@ -34,9 +34,9 @@ export type ModalProps<TOnCloseFnArgs extends BaseUseModalActionArgs = [], TOnOp
  *  );
  * };
  *
- * 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>
@@ -46,6 +46,6 @@ export type ModalProps<TOnCloseFnArgs extends BaseUseModalActionArgs = [], TOnOp
  * ```
  */
 export declare const Modal: {
-    <TOnCloseFnArgs extends BaseUseModalActionArgs = [], TOnOpenFnArgs extends BaseUseModalActionArgs = []>({ children, isOpen, role, "data-testid": dataTestId, className, size, onBackdropClick, floatingUi, ref, }: ModalProps<TOnCloseFnArgs, TOnOpenFnArgs>): ReactElement;
+    ({ children, isOpen, role, "data-testid": dataTestId, className, size, floatingUi, ref, }: ModalProps): ReactElement;
     displayName: string;
 };

package/src/modal/Modal.stories.d.ts

@@ -1,10 +1,10 @@
 import { StoryObjWithOptionalArgs } from "@trackunit/shared-utils";
 import { ReactElement } from "react";
-type Story = StoryObjWithOptionalArgs<typeof meta, "ref" | "isOpen" | "close" | "open" | "toggle" | "onBackdropClick" | "floatingUi" | "children" | "closeOnOutsideClick">;
+type Story = StoryObjWithOptionalArgs<typeof meta, "ref" | "isOpen" | "close" | "open" | "toggle" | "floatingUi" | "children">;
 declare const meta: {
     title: string;
     component: {
-        <TOnCloseFnArgs extends import("./useModal").BaseUseModalActionArgs = [], TOnOpenFnArgs extends import("./useModal").BaseUseModalActionArgs = []>({ children, isOpen, role, "data-testid": dataTestId, className, size, onBackdropClick, floatingUi, ref, }: import("./Modal").ModalProps<TOnCloseFnArgs, TOnOpenFnArgs>): ReactElement;
+        ({ children, isOpen, role, "data-testid": dataTestId, className, size, floatingUi, ref, }: import("./Modal").ModalProps): ReactElement;
         displayName: string;
     };
     tags: string[];
@@ -34,13 +34,6 @@ declare const meta: {
                 category: string;
             };
         };
-        onBackdropClick: {
-            control: false;
-            description: string;
-            table: {
-                category: string;
-            };
-        };
         open: {
             control: false;
             description: string;
@@ -69,16 +62,6 @@ declare const meta: {
                 category: string;
             };
         };
-        closeOnOutsideClick: {
-            control: false;
-            description: string;
-            table: {
-                category: string;
-                defaultValue: {
-                    summary: string;
-                };
-            };
-        };
         size: {
             control: {
                 type: "select";
@@ -98,3 +81,4 @@ export declare const PackageName: () => ReactElement;
 export declare const Default: Story;
 export declare const WithScrollableContent: Story;
 export declare const MultiColumnLayout: Story;
+export declare const UnsavedChangesConfirmation: Story;

package/src/modal/Modal.variants.d.ts

@@ -5,5 +5,10 @@ export declare const cvaModalContainer: (props?: import("class-variance-authorit
  * Returns the CSS properties for the modal card based on the size.
  */
 export declare const getModalCardCSSVariables: (size: Size) => CSSProperties;
-export declare const cvaModalCard: (props?: import("class-variance-authority/dist/types").ClassProp | undefined) => string;
-export declare const cvaModalBackdrop: (props?: import("class-variance-authority/dist/types").ClassProp | undefined) => string;
+export declare const cvaModalCard: (props?: ({
+    animation?: "fade" | "rise" | null | undefined;
+} & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;
+export declare const cvaModalBackdrop: (props?: ({
+    isFrontmost?: boolean | null | undefined;
+    shouldAnimate?: boolean | null | undefined;
+} & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;

package/src/modal/ModalHeader/ModalHeader.d.ts

@@ -1,5 +1,5 @@
 import { CommonProps } from "@trackunit/react-components";
-import { ReactElement, ReactNode } from "react";
+import { MouseEventHandler, ReactNode } from "react";
 export interface ModalHeaderProps extends CommonProps {
     /**
      * Main title displayed in the modal header.
@@ -9,11 +9,11 @@ export interface ModalHeaderProps extends CommonProps {
      * Optional subtitle displayed below the main title.
      * Not rendered when undefined.
      */
-    subHeading?: string | null | ReactElement;
+    subHeading?: ReactNode;
     /**
      * Click handler for the close button.
      */
-    onClose: () => void;
+    onClickClose: MouseEventHandler<HTMLButtonElement>;
     /**
      * The id of the element.
      */
@@ -21,7 +21,7 @@ export interface ModalHeaderProps extends CommonProps {
     /**
      * Children to render in the header
      */
-    children?: ReactNode | null;
+    children?: ReactNode;
     /**
      * Items to render next to the heading
      */
@@ -74,9 +74,9 @@ export interface ModalHeaderProps extends CommonProps {
  * @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.
  */
 export declare const ModalHeader: import("react").ForwardRefExoticComponent<ModalHeaderProps & import("react").RefAttributes<HTMLDivElement>>;

package/src/modal/ModalHeader/ModalHeader.stories.d.ts

@@ -14,7 +14,7 @@ declare const meta: {
         };
     };
     argTypes: {
-        onClose: {
+        onClickClose: {
             action: string;
         };
     };

package/src/modal/modalStackRegistry.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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
+ */
+/**
+ * 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`.
+ */
+export declare 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.
+ */
+export declare const IFRAME_MODAL_STACK_MESSAGE_TYPE = "IRIS_APP_IFRAME_MODAL_STACK_CHANGE";
+/**
+ * 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
+ */
+export declare const modalStackRegistry: {
+    register: (id: string) => void;
+    unregister: (id: string) => void;
+    getStackPosition: (id: string) => number;
+    getStackSize: () => number;
+    /** Get the number of modals open in the host (only relevant for Iris apps in iframes) */
+    getHostModalCount: () => number;
+    /** Get the number of modals open in iframes (only relevant for host) */
+    getIframeModalCount: () => number;
+    /** Set the host modal count (called when receiving messages from host) */
+    setHostModalCount: (count: number) => void;
+    /** Set the iframe modal count (called when receiving messages from iframes) */
+    setIframeModalCount: (count: number) => void;
+    subscribe: (listener: () => void) => (() => void);
+};

package/src/modal/useModal.d.ts

@@ -1,19 +1,97 @@
-import { UseFloatingOptions, UseFloatingReturn } from "@floating-ui/react";
+import { UseDismissProps, UseFloatingReturn, useInteractions } from "@floating-ui/react";
 import { UseFloatingReturn as UseFloatingReturn_Dom } from "@floating-ui/react-dom";
-import { UseInteractionsReturn } from "@floating-ui/react/dist/floating-ui.react";
-import { AriaRole, MouseEvent, Ref } from "react";
-type BaseUseModalActionArg = string | number | boolean | null | undefined | [] | object | MouseEvent;
-export type BaseUseModalActionArgs = {} & Array<BaseUseModalActionArg>;
-type OnCloseFn<TOnCloseFnArgs extends BaseUseModalActionArgs> = (...args: TOnCloseFnArgs) => void;
-type OnOpenFn<TOnOpenFnArgs extends BaseUseModalActionArgs> = (...args: TOnOpenFnArgs) => void;
-export type UseModalProps<TOnCloseFnArgs extends BaseUseModalActionArgs = [], TOnOpenFnArgs extends BaseUseModalActionArgs = []> = {
+import { AriaRole, Ref } from "react";
+/**
+ * Reasons why a modal's open state changed.
+ * - `escape-key`: User pressed the ESC key
+ * - `outside-press`: User clicked outside the modal
+ * - `programmatic`: The close() function was called (e.g., from a close button)
+ */
+export type ModalCloseReason = "escape-key" | "outside-press" | "programmatic";
+/**
+ * Callback fired BEFORE the modal closes on ESC or outside click.
+ * Return `false` (or Promise resolving to `false`) to prevent closing.
+ *
+ * @example
+ * // With confirmation dialog
+ * onBeforeClose: async (event, reason) => {
+ *   if (reason === "escape-key") return true; // Allow ESC to close without confirmation
+ *   const result = await confirm({ title: "Discard changes?" });
+ *   return result === "PRIMARY";
+ * }
+ */
+type OnBeforeCloseFn = (event?: Event, reason?: ModalCloseReason) => boolean | Promise<boolean>;
+/**
+ * Options for configuring modal dismissal behavior.
+ * Maps directly to FloatingUI's useDismiss options.
+ *
+ * @see https://floating-ui.com/docs/usedismiss
+ */
+export type ModalDismissOptions = Omit<UseDismissProps, "enabled">;
+export type UseModalProps = {
+    /**
+     * Whether the modal is open (controlled mode).
+     *
+     * Prefer uncontrolled mode using `modal.open()` and `modal.close()`.
+     *
+     * **Controlled mode limitations:**
+     * - `onBeforeClose` only fires for ESC, outside click, and `modal.close()` calls
+     * - `onBeforeClose` does NOT fire for browser back/forward, link navigation, or external state changes
+     *
+     * **Alternatives:**
+     * - Use `defaultOpen` to start the modal in open state
+     * - If you need to manage modal state from a parent, lift the whole `useModal()` instance to the parent
+     * - Only use `isOpen` for route-based modals where the modal is always open when the route is active
+     */
     isOpen?: boolean;
-    onClose?: OnCloseFn<TOnCloseFnArgs>;
-    onOpen?: OnOpenFn<TOnOpenFnArgs>;
-    onOpenChange?: UseFloatingOptions["onOpenChange"];
+    /**
+     * Whether the modal should start open (uncontrolled mode).
+     * Unlike `isOpen`, this only sets the initial state and does not trigger `onOpen`.
+     */
+    defaultOpen?: boolean;
+    /**
+     * Callback fired when the modal closes.
+     */
+    onClose?: (event?: Event, reason?: ModalCloseReason) => void;
+    /**
+     * Callback fired when the modal opens.
+     */
+    onOpen?: (event?: Event) => void;
+    /**
+     * Callback fired when the modal open state changes.
+     * Alternative to using separate onOpen/onClose callbacks.
+     */
+    onOpenChange?: (open: boolean, event?: Event, reason?: ModalCloseReason) => void;
+    /**
+     * Callback fired BEFORE the modal closes on ESC, outside click, or close().
+     * Return `false` (or Promise resolving to `false`) to prevent closing.
+     *
+     * @example
+     * // With confirmation dialog for unsaved changes
+     * onBeforeClose: async () => {
+     *   if (!isDirty) return true;
+     *   const result = await confirm({ title: "Discard changes?" });
+     *   return result === "PRIMARY";
+     * }
+     */
+    onBeforeClose?: OnBeforeCloseFn;
+    /**
+     * The root element to render the modal portal into.
+     */
     rootElement?: HTMLElement;
-    closeOnEsc?: boolean;
-    closeOnOutsideClick?: boolean;
+    /**
+     * Configuration for modal dismissal behavior.
+     * Maps directly to FloatingUI's useDismiss options.
+     *
+     * @default { escapeKey: true, outsidePress: true }
+     * @example
+     * // Disable outside click dismissal
+     * dismiss: { outsidePress: false }
+     */
+    dismiss?: ModalDismissOptions;
+    /**
+     * Custom ref for the modal container.
+     */
     ref?: Ref<HTMLDivElement>;
     /**
      * The aria role for the modal.
@@ -24,9 +102,9 @@ type FloatingUiProps = {
     refs: UseFloatingReturn_Dom["refs"];
     rootElement?: HTMLElement;
     context: UseFloatingReturn["context"];
-    getFloatingProps: UseInteractionsReturn["getFloatingProps"];
+    getFloatingProps: ReturnType<typeof useInteractions>["getFloatingProps"];
 };
-export type UseModalReturnValue<TOnCloseFnArgs extends BaseUseModalActionArgs = [], TOnOpenFnArgs extends BaseUseModalActionArgs = []> = {
+export type UseModalReturnValue = {
     /**
      * The ref for the modal.
      */
@@ -35,26 +113,18 @@ export type UseModalReturnValue<TOnCloseFnArgs extends BaseUseModalActionArgs =
      * Whether the modal is open.
      */
     isOpen: boolean;
-    /**
-     * Whether the modal should close when the user clicks outside of the modal.
-     */
-    closeOnOutsideClick: boolean;
-    /**
-     * The callback function to call when the user clicks outside of the modal.
-     */
-    onBackdropClick: () => void;
     /**
      * A function to call for opening the modal.
      */
-    open: OnOpenFn<TOnOpenFnArgs>;
+    open: () => void;
     /**
      * A function to call for toggling the modal visibility.
      */
-    toggle: (...args: TOnOpenFnArgs | TOnCloseFnArgs) => void;
+    toggle: () => void;
     /**
      * A function to call for closing the modal.
      */
-    close: OnCloseFn<TOnCloseFnArgs>;
+    close: () => void;
     /**
      * The floating UI properties for the modal.
      */
@@ -71,5 +141,5 @@ export type UseModalReturnValue<TOnCloseFnArgs extends BaseUseModalActionArgs =
  * - const modal = useModal();
  * - <Modal {...modal} size="medium" />
  */
-export declare const useModal: <TOnCloseFnArgs extends BaseUseModalActionArgs = [], TOnOpenFnArgs extends BaseUseModalActionArgs = []>(props?: UseModalProps<TOnCloseFnArgs, TOnOpenFnArgs>) => UseModalReturnValue<TOnCloseFnArgs, TOnOpenFnArgs>;
+export declare const useModal: (props?: UseModalProps) => UseModalReturnValue;
 export {};

package/src/modal/useModalStack.d.ts

@@ -0,0 +1,25 @@
+type UseModalStackResult = {
+    /**
+     * How many modals are in front of this one (0 = frontmost)
+     */
+    depthFromFront: number;
+    /**
+     * Current number of open modals in the stack
+     */
+    stackSize: number;
+    /**
+     * The stack size when this modal opened (stable after open, useful for one-time decisions)
+     */
+    stackSizeAtOpen: number;
+};
+/**
+ * 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
+ */
+export declare const useModalStack: (isOpen: boolean) => UseModalStackResult;
+export {};

package/src/translation.d.ts

@@ -1,4 +1,5 @@
-import { NamespaceTransProps, TransForLibs, TranslationResource } from "@trackunit/i18n-library-translation";
+import { NamespaceTransProps, TransForLibs, TranslationResource, useNamespaceTranslation } from "@trackunit/i18n-library-translation";
+import { ReactElement } from "react";
 import defaultTranslations from "./locales/en/translation.json";
 /** A type for all available translation keys in this library */
 export type TranslationKeys = keyof typeof defaultTranslations;
@@ -14,11 +15,7 @@ export declare const translations: TranslationResource<TranslationKeys>;
 /**
  *  Local useTranslation for this specific library
  */
-export declare const useTranslation: () => [TransForLibs<never>, import("i18next").i18n, boolean] & {
-    t: TransForLibs<never>;
-    i18n: import("i18next").i18n;
-    ready: boolean;
-};
+export declare const useTranslation: () => ReturnType<typeof useNamespaceTranslation<TranslationKeys>>;
 /**
  * Type of the t function for the local useTranslation for this specific library
  */
@@ -26,7 +23,7 @@ export type TranslationFunction = TransForLibs<TranslationKeys>;
 /**
  * Trans for this specific library.
  */
-export declare const Trans: (props: NamespaceTransProps<TranslationKeys>) => import("react/jsx-runtime").JSX.Element;
+export declare const Trans: (props: NamespaceTransProps<TranslationKeys>) => ReactElement;
 /**
  * Registers the translations for this library
  */

package/src/modal/ModalBackdrop.d.ts

@@ -1,12 +0,0 @@
-import { ReactNode } from "react";
-export interface ModalBackdropProps {
-    onClick: () => void;
-    children: ReactNode;
-}
-/**
- * The Backdrop for the modal.
- *
- * @param {ModalBackdropProps} props - The props for the ModalBackdrop component
- * @returns {ReactElement} ModalBackdrop component
- */
-export declare const ModalBackdrop: ({ children, onClick }: ModalBackdropProps) => import("react/jsx-runtime").JSX.Element;