@trackunit/react-modal 1.21.4 → 1.21.7

package/src/modal/Modal.d.ts

@@ -1,6 +1,6 @@
-import { Size } from "@trackunit/react-components";
-import { PropsWithChildren, ReactElement } from "react";
-import { UseModalReturnValue } from "./useModal";
+import { Size, type SheetDefaultSize } from "@trackunit/react-components";
+import { type PropsWithChildren, type ReactElement } from "react";
+import type { UseModalReturnValue } from "./useModal";
 /**
  * Modal props extend the return type of useModal and add presentational-only props.
  */
@@ -17,6 +17,13 @@ export type ModalProps = PropsWithChildren<UseModalReturnValue & {
      * The test ID applied to the modal.
      */
     "data-testid"?: string;
+    /**
+     * Initial snap size of the sheet when Modal renders in sheet mode.
+     * Only relevant on narrow viewports where the modal becomes a bottom sheet.
+     *
+     * @default "fit"
+     */
+    sheetDefaultSize?: SheetDefaultSize;
     /**
      * Determines if focus should be restored to the nearest tabbable element
      * if the currently focused element inside the modal is removed from the DOM.
@@ -30,6 +37,9 @@ export type ModalProps = PropsWithChildren<UseModalReturnValue & {
  * It renders inside a Portal with a backdrop overlay, focus trapping, and proper accessibility roles.
  * Modals must always be used together with the `useModal` hook, which manages open/close state and Floating UI integration.
  *
+ * When the container width is below the "sm" breakpoint (480px), the Modal
+ * automatically renders as a bottom Sheet with gesture support.
+ *
  * Compose the modal body with `ModalHeader`, `ModalBody`, and `ModalFooter` for consistent structure.
  *
  * ### When to use
@@ -60,7 +70,4 @@ export type ModalProps = PropsWithChildren<UseModalReturnValue & {
  * @param {ModalProps} props - The props for the Modal component
  * @returns {ReactElement} Modal component
  */
-export declare const Modal: {
-    ({ children, isOpen, role, "data-testid": dataTestId, className, size, floatingUi, ref, restoreFocus, depthFromFront, stackSizeAtOpen, }: ModalProps): ReactElement;
-    displayName: string;
-};
+export declare const Modal: ({ children, container, dismiss, isOpen, mode, requestClose, role, "data-testid": dataTestId, className, size, stack, floatingUi, ref, sheetDefaultSize, restoreFocus, onCloseComplete, }: ModalProps) => ReactElement;

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

@@ -1,14 +1,36 @@
 import { Size } from "@trackunit/react-components";
 import { CSSProperties } from "react";
 export declare const cvaModalContainer: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
+type GetModalCardCSSVariablesOptions = Readonly<{
+    /**
+     * When true, width math uses container query units (`cqw`) so the card tracks
+     * the nearest `container-type` ancestor (e.g. Storybook `ResizableBox`) instead
+     * of the viewport. Pass when using `useModal({ container })`.
+     */
+    useContainerWidthUnits: boolean;
+}>;
 /**
  * Returns the CSS properties for the modal card based on the size.
  */
-export declare const getModalCardCSSVariables: (size: Size) => CSSProperties;
+export declare const getModalCardCSSVariables: (size: Size, options?: GetModalCardCSSVariablesOptions) => CSSProperties;
+/**
+ * Layout contract that modal children depend on. Applied to the children's
+ * immediate container in both card mode (the Card) and sheet mode (the
+ * aria-modal wrapper). Ensures ModalHeader/ModalBody/ModalFooter experience
+ * an identical flex/container-query environment regardless of rendering mode.
+ *
+ * Does NOT include overflow-y — scrolling is owned by the parent:
+ * in card mode by the Card element (`cvaModalCard`), in sheet mode by the
+ * Sheet's scroll area. A nested overflow here would absorb content height,
+ * preventing Sheet's fit-height measurement from seeing the true size.
+ */
+export declare const cvaModalContentEnvironment: (props?: import("class-variance-authority/types").ClassProp | undefined) => string;
 export declare const cvaModalCard: (props?: ({
-    animation?: "fade" | "rise" | null | undefined;
+    animation?: "fade" | "rise" | "none" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export declare const cvaModalBackdrop: (props?: ({
+    contained?: boolean | null | undefined;
     isFrontmost?: boolean | null | undefined;
     shouldAnimate?: boolean | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export {};

package/src/modal/modal-mode-switch-reducer.d.ts

@@ -0,0 +1,18 @@
+import type { ModalMode } from "./useModal";
+/**
+ * Tracks formfactor transitions (card ↔ sheet) while the modal is already
+ * open. `isModeSwitching` is true for the committed render after a mode
+ * change and resets when the modal closes.
+ */
+export type ModalModeSwitchState = {
+    readonly prevMode: ModalMode;
+    readonly prevIsOpen: boolean;
+    readonly isModeSwitching: boolean;
+};
+export type ModalModeSwitchAction = {
+    readonly type: "SYNC";
+    readonly mode: ModalMode;
+    readonly isOpen: boolean;
+};
+/** Reducer tracking formfactor transitions (card/sheet) while the modal is open. */
+export declare const modalModeSwitchReducer: (state: ModalModeSwitchState, action: ModalModeSwitchAction) => ModalModeSwitchState;

package/src/modal/modalStackRegistry.d.ts

@@ -66,11 +66,6 @@
  * - `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
  */
 /**

package/src/modal/useModal.d.ts

@@ -1,89 +1,33 @@
 import { UseDismissProps, UseFloatingReturn, useInteractions } from "@floating-ui/react";
 import { UseFloatingReturn as UseFloatingReturn_Dom } from "@floating-ui/react-dom";
-import { AriaRole, Ref } from "react";
+import { type CloseReason, type DismissOptions, type UseOverlayDismissibleProps, type UseOverlayDismissibleReturn } from "@trackunit/react-components";
+import { type AriaRole, type Ref, type RefObject } from "react";
+import { type UseModalStackResult } from "./useModalStack";
 /**
- * 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)
+ * Rendering mode of the Modal. Determined by container/viewport width:
+ * - `"card"`: standard centered card overlay (container width >= 480px)
+ * - `"sheet"`: bottom sheet with gesture support (container width < 480px)
  */
-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>;
+export type ModalMode = "card" | "sheet";
+/** @deprecated Use CloseReason from @trackunit/react-components instead. */
+export type ModalCloseReason = CloseReason;
 /**
  * Options for configuring modal dismissal behavior.
- * Maps directly to FloatingUI's useDismiss options.
+ * Extends shared DismissOptions with 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;
-    /**
-     * 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;
+export type ModalDismissOptions = DismissOptions & Omit<UseDismissProps, "enabled">;
+export type UseModalProps = UseOverlayDismissibleProps & {
     /**
      * The root element to render the modal portal into.
      */
     rootElement?: HTMLElement;
     /**
      * Configuration for modal dismissal behavior.
-     * Maps directly to FloatingUI's useDismiss options.
+     * Extends shared DismissOptions with FloatingUI options.
      *
-     * @default { escapeKey: true, outsidePress: true }
+     * @default { escapeKey: true, outsidePress: true, gesture: true }
      * @example
      * // Disable outside click dismissal
      * dismiss: { outsidePress: false }
@@ -97,6 +41,16 @@ export type UseModalProps = {
      * The aria role for the modal.
      */
     role?: AriaRole;
+    /**
+     * Scopes the modal to a specific container element. When provided, the modal
+     * portals into this container (instead of the document body), uses its width
+     * to determine whether to render as a bottom sheet (container width < 480px),
+     * and positions the backdrop/overlay relative to the container.
+     * Card width uses container query units (`cqw`) so it tracks a `container-type`
+     * ancestor of the portal root (ensure one exists, e.g. Tailwind `@container`).
+     * When omitted, viewport width is used for breakpoint detection and card sizing.
+     */
+    container?: RefObject<HTMLElement | null>;
 };
 type FloatingUiProps = {
     refs: UseFloatingReturn_Dom["refs"];
@@ -104,27 +58,11 @@ type FloatingUiProps = {
     context: UseFloatingReturn["context"];
     getFloatingProps: ReturnType<typeof useInteractions>["getFloatingProps"];
 };
-export type UseModalReturnValue = {
+export type UseModalReturnValue = Omit<UseOverlayDismissibleReturn, "ref"> & {
     /**
-     * The ref for the modal.
+     * The ref for the modal (RefObject or RefCallback).
      */
     ref: Ref<HTMLDivElement>;
-    /**
-     * Whether the modal is open.
-     */
-    isOpen: boolean;
-    /**
-     * A function to call for opening the modal.
-     */
-    open: () => void;
-    /**
-     * A function to call for toggling the modal visibility.
-     */
-    toggle: () => void;
-    /**
-     * A function to call for closing the modal.
-     */
-    close: () => void;
     /**
      * The floating UI properties for the modal.
      */
@@ -134,15 +72,29 @@ export type UseModalReturnValue = {
      */
     role?: AriaRole;
     /**
-     * How many modals are stacked in front of this one (0 = frontmost).
-     * Used by Modal for visual stacking (scale, backdrop).
+     * Resolved dismiss options (defaults applied). Pass to Sheet when in sheet mode.
+     */
+    dismiss: Required<DismissOptions>;
+    /** Called after the modal's close animation has finished, allowing the iframe to resize back. */
+    onCloseComplete: () => void;
+    /** Position and sizing info for this modal within the open-modal stack. */
+    stack: UseModalStackResult;
+    /**
+     * Current rendering mode of the modal.
+     * - `"card"`: standard centered card overlay
+     * - `"sheet"`: bottom sheet with gesture support
+     */
+    mode: ModalMode;
+    /**
+     * The container ref passed to useModal, if any. Forwarded to Modal for
+     * portal and positioning decisions.
      */
-    depthFromFront: number;
+    container: RefObject<HTMLElement | null> | undefined;
     /**
-     * The total modal stack size when this modal opened.
-     * Used by Modal for animation decisions.
+     * Close the modal with a specific reason. Used internally by Modal
+     * to preserve the correct CloseReason for gesture-initiated closes.
      */
-    stackSizeAtOpen: number;
+    requestClose: (event: Event | undefined, reason: CloseReason) => void;
 };
 /**
  * A hook to handle the state and configuration of Modal components.

package/src/modal/useModalFooterBorder.d.ts

@@ -1,4 +1,4 @@
-import { RefObject } from "react";
+import type { RefObject } from "react";
 type Options = {
     footerClass?: string | Array<string>;
     enabled?: boolean;
@@ -11,18 +11,11 @@ type ElementRefLike = ElementRef | RefObject<ElementRef>;
  * Observes the modal body within the given root element and toggles a top border on the footer
  * when the body becomes vertically scrollable.
  *
- * Behavior:
- * - Locates elements via stable data-attributes (by default: [data-modal-body], [data-modal-footer]).
- * - Recomputes on resize, DOM mutations within the body, scroll events, and image load/error events.
- * - Cleans up all observers/listeners on unmount or dependency change.
- *
- * Edge cases:
- * - If either body or footer is missing, the hook does nothing.
- * - No DOM mutations occur when `enabled` is false.
+ * Thin wrapper around `useOverflowBorder` with modal-specific defaults.
  *
  * @param rootRef Root element that contains both the modal body and footer.
  * @param options Optional configuration.
- * @param options.footerClass CSS class(es) toggled on the footer when the body is scrollable. Accepts string or string[]. Defaults to "border-t".
+ * @param options.footerClass CSS class(es) toggled on the footer when the body is scrollable. Defaults to "border-t".
  * @param options.enabled Whether the hook is active. Defaults to true.
  * @param options.bodySelector CSS selector to locate the body element. Defaults to "[data-modal-body]".
  * @param options.footerSelector CSS selector to locate the footer element. Defaults to "[data-modal-footer]".

package/src/modal/useModalStack.d.ts

@@ -1,16 +1,16 @@
-type UseModalStackResult = {
+export type UseModalStackResult = {
     /**
      * How many modals are in front of this one (0 = frontmost)
      */
-    depthFromFront: number;
+    readonly depthFromFront: number;
     /**
      * Current number of open modals in the stack
      */
-    stackSize: number;
+    readonly stackSize: number;
     /**
      * The stack size when this modal opened (stable after open, useful for one-time decisions)
      */
-    stackSizeAtOpen: number;
+    readonly stackSizeAtOpen: number;
 };
 /**
  * Hook to track this modal's position in the stack of open modals.
@@ -22,4 +22,3 @@ type UseModalStackResult = {
  * @param isOpen - Whether the modal is currently open
  */
 export declare const useModalStack: (isOpen: boolean) => UseModalStackResult;
-export {};