@easypost/easy-ui 1.0.0-alpha.120 → 1.0.0-alpha.122

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @easypost/easy-ui
 
+## 1.0.0-alpha.122
+
+### Minor Changes
+
+- f17a7b7: Add `childNestingBehavior` and `selfNestingBehavior` props to `Modal.Trigger` and `ModalContainer` to control how modals stack when nested. The connection between a parent and a nested child can resolve to `stack` (both keep their backdrops — the default) or `replace` (the nested modal hides the modal beneath it).
+
+  Configure it from either end: `childNestingBehavior` is set on the parent, applies to its children, and cascades down the tree; `selfNestingBehavior` is set on the child, applies only to its own connection to its parent, does not cascade, and overrides the parent's `childNestingBehavior` for that connection. `selfNestingBehavior` is useful for surgically changing one nested modal in a large tree without touching its parent.
+
+### Patch Changes
+
+- f17a7b7: Fix third-party overlays (e.g. Stripe Link/autofill) locking up when their modal (`allowsThirdPartyOverlays`) is nested inside another modal. A surrounding focus-trapping modal kept hiding the page (`inert`) and containing focus, which re-broke the injected overlay. A modal now automatically relaxes its focus trap and background hiding while it has an open `allowsThirdPartyOverlays` descendant, then restores them when that descendant closes. Modals without such a descendant are unaffected.
+- f17a7b7: Fix react-aria overlays (e.g. `Select`, `Menu`) not closing on outside click when rendered inside a `Modal` that uses `allowsThirdPartyOverlays`. The modal box was tagged `data-react-aria-top-layer`, which made react-aria treat every click inside the modal as "not outside" for all overlays. Modals now keep nested overlays dismissable while preserving the third-party overlay behavior: the modal stays visible under a surrounding modal, clicking a nested modal no longer dismisses the one beneath it, and genuine third-party overlays (e.g. Stripe) still don't dismiss the modal.
+
+## 1.0.0-alpha.121
+
+### Minor Changes
+
+- e47ec8f: Add `allowsThirdPartyOverlays` to `Modal.Trigger` and `ModalContainer`. When enabled, the modal stops trapping focus and stops applying `aria-hidden`/`inert` to the rest of the page, so third-party overlays that render outside the modal (e.g. Stripe Link/autofill, reCAPTCHA) remain focusable and clickable instead of locking up.
+
 ## 1.0.0-alpha.120
 
 ### Patch Changes

package/Modal/Modal.d.ts

@@ -5,6 +5,7 @@ import { ModalHeader } from "./ModalHeader";
 import { ModalTrigger } from "./ModalTrigger";
 import { ModalContainer } from "./ModalContainer";
 import { useModalTrigger } from "./context";
+import type { ModalNestingBehavior } from "./context";
 type ModalSize = "sm" | "md" | "lg" | "xl";
 export type ModalProps = {
     /**
@@ -49,4 +50,5 @@ export declare namespace Modal {
     var Footer: typeof ModalFooter;
 }
 export { ModalContainer, useModalTrigger };
+export type { ModalNestingBehavior };
 //# sourceMappingURL=Modal.d.ts.map

package/Modal/Modal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Modal.d.ts","sourceRoot":"","sources":["../../src/Modal/Modal.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAc,SAAS,EAAmB,MAAM,OAAO,CAAC;AAGtE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAI5C,KAAK,SAAS,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE3C,MAAM,MAAM,UAAU,GAAG;IACvB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,UAAU,qBAqCtC;yBArCe,KAAK;;;;;;AAsErB,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"Modal.d.ts","sourceRoot":"","sources":["../../src/Modal/Modal.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAc,SAAS,EAAmB,MAAM,OAAO,CAAC;AAGtE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AAItD,KAAK,SAAS,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE3C,MAAM,MAAM,UAAU,GAAG;IACvB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,UAAU,qBAqCtC;yBArCe,KAAK;;;;;;AAsErB,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,CAAC;AAC3C,YAAY,EAAE,oBAAoB,EAAE,CAAC"}

package/Modal/Modal.nesting.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Modal.nesting.test.d.ts.map

package/Modal/Modal.nesting.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Modal.nesting.test.d.ts","sourceRoot":"","sources":["../../src/Modal/Modal.nesting.test.tsx"],"names":[],"mappings":""}

package/Modal/Modal.stories.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Modal.stories.d.ts","sourceRoot":"","sources":["../../src/Modal/Modal.stories.tsx"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAQvD,OAAO,EAAE,KAAK,EAAmC,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAM9C,KAAK,UAAU,GAAG,QAAQ,CAAC,OAAO,KAAK,CAAC,CAAC;AACzC,KAAK,iBAAiB,GAAG,QAAQ,CAAC,OAAO,YAAY,CAAC,CAAC;AAEvD,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,OAAO,KAAK,CAQ5B,CAAC;AAEF,eAAe,IAAI,CAAC;AAEpB,eAAO,MAAM,MAAM,EAAE,UAkBpB,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,UA6CtB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,iBA6B5B,CAAC;AAEF,eAAO,MAAM,IAAI,EAAE,UAwBlB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,iBAwBzB,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,iBAwBxB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,iBAyBzB,CAAC;AAEF,eAAO,MAAM,MAAM,EAAE,iBA4FpB,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,UAqBxB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,UA0B5B,CAAC"}
+{"version":3,"file":"Modal.stories.d.ts","sourceRoot":"","sources":["../../src/Modal/Modal.stories.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAcvD,OAAO,EAAE,KAAK,EAAmC,MAAM,SAAS,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,KAAK,UAAU,GAAG,QAAQ,CAAC,OAAO,KAAK,CAAC,CAAC;AACzC,KAAK,iBAAiB,GAAG,QAAQ,CAAC,OAAO,YAAY,CAAC,CAAC;AAEvD,QAAA,MAAM,IAAI,EAAE,IAAI,CAAC,OAAO,KAAK,CAQ5B,CAAC;AAEF,eAAe,IAAI,CAAC;AAEpB,eAAO,MAAM,MAAM,EAAE,UAkBpB,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,UA6CtB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,iBA6B5B,CAAC;AAEF,eAAO,MAAM,IAAI,EAAE,UAwBlB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,iBAwBzB,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,iBAwBxB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,iBAyBzB,CAAC;AAEF,eAAO,MAAM,MAAM,EAAE,iBAgKpB,CAAC;AA8EF,eAAO,MAAM,UAAU,EAAE,UAqBxB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,UA0B5B,CAAC"}

package/Modal/ModalContainer.d.ts

@@ -1,4 +1,5 @@
 import React, { ReactNode } from "react";
+import { ModalNestingBehavior } from "./context";
 type ModalContainerProps = {
     /**
      * Modal wrap content.
@@ -8,6 +9,29 @@ type ModalContainerProps = {
      * Whether or not the modal is dismissable.
      */
     isDismissable?: boolean;
+    /**
+     * Disables focus trapping and background aria-hiding so the modal can host
+     * third-party overlays (e.g. Stripe Link/autofill, reCAPTCHA) that render
+     * outside the modal. Use sparingly — see `ModalUnderlay` for the tradeoffs.
+     *
+     * @default false
+     */
+    allowsThirdPartyOverlays?: boolean;
+    /**
+     * Controls how this modal's nested children stack relative to it, and cascades
+     * to descendant modals. `stack` gives each child its own backdrop, and
+     * `replace` hides this modal while a child is open. When unset, it inherits the
+     * nearest ancestor modal's value (or `stack` at the root).
+     */
+    childNestingBehavior?: ModalNestingBehavior;
+    /**
+     * Controls how this modal stacks relative to its parent, overriding the
+     * parent's `childNestingBehavior` for just this modal. `stack` keeps both
+     * backdrops, and `replace` hides the parent while this modal is open. Local to
+     * this modal — it does not cascade. Useful for surgically changing one nested
+     * modal in a larger tree without touching its parent.
+     */
+    selfNestingBehavior?: ModalNestingBehavior;
     /**
      * Handler that is called when the overlay is closed.
      */

package/Modal/ModalContainer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ModalContainer.d.ts","sourceRoot":"","sources":["../../src/Modal/ModalContainer.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAgB,SAAS,EAA0B,MAAM,OAAO,CAAC;AAM/E,KAAK,mBAAmB,GAAG;IACzB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,qBA0CxD"}
+{"version":3,"file":"ModalContainer.d.ts","sourceRoot":"","sources":["../../src/Modal/ModalContainer.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAgB,SAAS,EAA0B,MAAM,OAAO,CAAC;AAI/E,OAAO,EAAE,oBAAoB,EAAwB,MAAM,WAAW,CAAC;AAEvE,KAAK,mBAAmB,GAAG;IACzB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;OAMG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAEnC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAE5C;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,oBAAoB,CAAC;IAE3C;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,mBAAmB,qBA2DxD"}

package/Modal/ModalTrigger.d.ts

@@ -1,4 +1,5 @@
 import React, { ReactElement } from "react";
+import { ModalNestingBehavior } from "./context";
 export type CloseableModalElement = (close: () => void) => ReactElement;
 export type ModalTriggerProps = {
     /**
@@ -11,8 +12,33 @@ export type ModalTriggerProps = {
     defaultOpen?: boolean;
     /**
      * Whether or not the modal can be dismissed.
+     *
+     * @default true
      */
     isDismissable?: boolean;
+    /**
+     * Disables focus trapping and background aria-hiding so the modal can host
+     * third-party overlays (e.g. Stripe Link/autofill, reCAPTCHA) that render
+     * outside the modal. Use sparingly — see `ModalUnderlay` for the tradeoffs.
+     *
+     * @default false
+     */
+    allowsThirdPartyOverlays?: boolean;
+    /**
+     * Controls how this modal's nested children stack relative to it, and cascades
+     * to descendant modals. `stack` gives each child its own backdrop, and
+     * `replace` hides this modal while a child is open. When unset, it inherits the
+     * nearest ancestor modal's value (or `stack` at the root).
+     */
+    childNestingBehavior?: ModalNestingBehavior;
+    /**
+     * Controls how this modal stacks relative to its parent, overriding the
+     * parent's `childNestingBehavior` for just this modal. `stack` keeps both
+     * backdrops, and `replace` hides the parent while this modal is open. Local to
+     * this modal — it does not cascade. Useful for surgically changing one nested
+     * modal in a larger tree without touching its parent.
+     */
+    selfNestingBehavior?: ModalNestingBehavior;
     /**
      * Whether the modal is open by default (controlled).
      */

package/Modal/ModalTrigger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ModalTrigger.d.ts","sourceRoot":"","sources":["../../src/Modal/ModalTrigger.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,YAAY,EAAgB,MAAM,OAAO,CAAC;AAM1D,MAAM,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,MAAM,IAAI,KAAK,YAAY,CAAC;AAExE,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;OAEG;IACH,QAAQ,EAAE,CAAC,YAAY,EAAE,qBAAqB,GAAG,YAAY,CAAC,CAAC;IAE/D;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CAC1C,CAAC;AAEF,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,qBA8BpD"}
+{"version":3,"file":"ModalTrigger.d.ts","sourceRoot":"","sources":["../../src/Modal/ModalTrigger.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,YAAY,EAAgB,MAAM,OAAO,CAAC;AAI1D,OAAO,EAAE,oBAAoB,EAAwB,MAAM,WAAW,CAAC;AAEvE,MAAM,MAAM,qBAAqB,GAAG,CAAC,KAAK,EAAE,MAAM,IAAI,KAAK,YAAY,CAAC;AAExE,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;OAEG;IACH,QAAQ,EAAE,CAAC,YAAY,EAAE,qBAAqB,GAAG,YAAY,CAAC,CAAC;IAE/D;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;OAMG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAEnC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAE5C;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,oBAAoB,CAAC;IAE3C;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CAC1C,CAAC;AAEF,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,qBA2CpD"}

package/Modal/ModalUnderlay.d.ts

@@ -13,6 +13,19 @@ type ModalUnderlayProps = {
      * Whether or not the modal is dismissable.
      */
     isDismissable?: boolean;
+    /**
+     * When `true`, the modal stops trapping focus and stops hiding the rest of
+     * the page from assistive technologies (`aria-hidden`/`inert`). Use this only
+     * for modals that intentionally host third-party overlays — e.g. Stripe
+     * Link/autofill or reCAPTCHA — which render themselves into the document
+     * *outside* the modal. react-aria's focus trap and `inert` would otherwise
+     * blur and lock up those overlays. This trades away the modal's focus
+     * containment and background hiding, so reach for it only when a third-party
+     * overlay requires it.
+     *
+     * @default false
+     */
+    allowsThirdPartyOverlays?: boolean;
 };
 export declare function ModalUnderlay(props: ModalUnderlayProps): React.JSX.Element;
 export {};

package/Modal/ModalUnderlay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ModalUnderlay.d.ts","sourceRoot":"","sources":["../../src/Modal/ModalUnderlay.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAMpD,KAAK,kBAAkB,GAAG;IACxB;;OAEG;IACH,KAAK,EAAE,mBAAmB,CAAC;IAE3B;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,qBAgCtD"}
+{"version":3,"file":"ModalUnderlay.d.ts","sourceRoot":"","sources":["../../src/Modal/ModalUnderlay.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,SAAS,EAAgC,MAAM,OAAO,CAAC;AAMvE,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAgBpD,KAAK,kBAAkB,GAAG;IACxB;;OAEG;IACH,KAAK,EAAE,mBAAmB,CAAC;IAE3B;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;;;;;;;OAWG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC,CAAC;AAuBF,wBAAgB,aAAa,CAAC,KAAK,EAAE,kBAAkB,qBAUtD"}

package/Modal/context.d.ts

@@ -2,6 +2,17 @@ import React, { ReactNode } from "react";
 import { FocusableElement } from "@react-types/shared";
 import { DOMAttributes, RefObject } from "react";
 import { OverlayTriggerState } from "react-stately";
+/**
+ * Controls how one modal in a nested stack presents relative to the modal it
+ * connects to. The same value describes that connection from either end —
+ * `childNestingBehavior` (set on the parent, cascades down) and
+ * `selfNestingBehavior` (set on the child, local) — and resolves to:
+ *
+ * - `stack` — both modals keep their own backdrops; modals simply stack.
+ * - `replace` — the nested modal hides the modal beneath it, so only the topmost
+ *   modal is visible.
+ */
+export type ModalNestingBehavior = "stack" | "replace";
 export type ModalContextType = {
     dialogProps: DOMAttributes<FocusableElement>;
     titleProps: DOMAttributes<FocusableElement>;
@@ -14,17 +25,73 @@ export type ModalContextType = {
 type ModalTriggerContextType = {
     isDismissable: boolean;
     state: OverlayTriggerState;
-    hasOpenNestedModal: boolean;
-    setHasOpenNestedModal: (hasOpenNestedModal: boolean) => void;
+    /**
+     * Whether this modal currently has one or more open nested modals whose
+     * connection resolved to `replace`. When true, this modal hides itself so the
+     * nested modal takes its place.
+     */
+    hasReplacingChild: boolean;
+    /**
+     * The resolved behavior this modal imposes on its children's connections.
+     * Cascades: a child that sets neither `childNestingBehavior` nor
+     * `selfNestingBehavior` inherits this value.
+     */
+    childNestingBehavior: ModalNestingBehavior;
+    /**
+     * The resolved behavior of this modal's connection to its parent. Drives this
+     * modal's own rendering — suppressing its backdrop or hiding its parent.
+     */
+    selfNestingBehavior: ModalNestingBehavior;
+    /**
+     * Registers an open nested modal with this modal. The `replaces` argument
+     * records whether that nested modal's connection resolved to `replace`.
+     * Returns a cleanup that unregisters it. Callers invoke this from an effect
+     * tied to the nested modal's open state so the count stays accurate across
+     * open/close/unmount.
+     */
+    registerNested: (replaces: boolean) => () => void;
+    /**
+     * Whether an open descendant modal (at any depth) hosts third-party overlays
+     * (`allowsThirdPartyOverlays`). A focus-trapping modal reads this to stop
+     * hiding/trapping the page while such a descendant is open, so the descendant's
+     * injected overlay (e.g. Stripe Link) isn't `inert`'d or robbed of focus.
+     */
+    hasOpenThirdPartyDescendant: boolean;
+    /**
+     * Registers that this modal's subtree contains an open third-party-overlay
+     * modal, propagating up to every ancestor. Returns a cleanup that unregisters
+     * it. Like {@link registerNested}, callers invoke this from an effect tied to
+     * open state so the count stays accurate across open/close/unmount.
+     */
+    registerThirdPartyOverlay: () => () => void;
 };
 export type ModalTriggerProviderProps = Pick<ModalTriggerContextType, "state" | "isDismissable"> & {
     children: ReactNode;
+    /**
+     * How this modal's nested children present relative to it. Cascades to
+     * descendants. Defaults to the nearest ancestor's value, or `stack` at the
+     * root.
+     */
+    childNestingBehavior?: ModalNestingBehavior;
+    /**
+     * How this modal presents relative to its parent. Local to this modal (does
+     * not cascade) and overrides the parent's `childNestingBehavior` for this one
+     * connection. Defaults to the parent's `childNestingBehavior`.
+     */
+    selfNestingBehavior?: ModalNestingBehavior;
+    /**
+     * Whether this modal hosts third-party overlays itself. Used to register this
+     * modal's subtree with focus-trapping ancestors so they can relax while it's
+     * open. This is the underlay's behavior; the provider only needs it to drive
+     * registration.
+     */
+    allowsThirdPartyOverlays?: boolean;
 };
 export declare const ModalContext: React.Context<ModalContextType | null>;
 export declare const useModalContext: () => ModalContextType;
 export declare const ModalTriggerContext: React.Context<ModalTriggerContextType | null>;
 export declare const useModalTriggerContext: () => ModalTriggerContextType;
 export declare const useModalTrigger: () => OverlayTriggerState;
-export declare function ModalTriggerProvider({ state, isDismissable, children, }: ModalTriggerProviderProps): React.JSX.Element;
+export declare function ModalTriggerProvider({ state, isDismissable, childNestingBehavior, selfNestingBehavior, allowsThirdPartyOverlays, children, }: ModalTriggerProviderProps): React.JSX.Element;
 export {};
 //# sourceMappingURL=context.d.ts.map

package/Modal/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/Modal/context.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EACL,aAAa,EACb,SAAS,EAKV,MAAM,OAAO,CAAC;AACf,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEpD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,WAAW,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IAC7C,UAAU,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IAC5C,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,OAAO,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC1C,oBAAoB,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACvD,oBAAoB,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CACxD,CAAC;AAEF,KAAK,uBAAuB,GAAG;IAC7B,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,EAAE,mBAAmB,CAAC;IAC3B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,qBAAqB,EAAE,CAAC,kBAAkB,EAAE,OAAO,KAAK,IAAI,CAAC;CAC9D,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAC1C,uBAAuB,EACvB,OAAO,GAAG,eAAe,CAC1B,GAAG;IACF,QAAQ,EAAE,SAAS,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,YAAY,wCAA+C,CAAC;AAEzE,eAAO,MAAM,eAAe,wBAM3B,CAAC;AAEF,eAAO,MAAM,mBAAmB,+CACqB,CAAC;AAEtD,eAAO,MAAM,sBAAsB,+BAMlC,CAAC;AAEF,eAAO,MAAM,eAAe,2BAG3B,CAAC;AAEF,wBAAgB,oBAAoB,CAAC,EACnC,KAAK,EACL,aAAa,EACb,QAAQ,GACT,EAAE,yBAAyB,qBAU3B"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/Modal/context.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EACL,aAAa,EACb,SAAS,EAMV,MAAM,OAAO,CAAC;AAKf,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEpD;;;;;;;;;GASG;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,SAAS,CAAC;AAEvD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,WAAW,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IAC7C,UAAU,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAAC;IAC5C,aAAa,EAAE,OAAO,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,OAAO,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAC1C,oBAAoB,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACvD,oBAAoB,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;CACxD,CAAC;AAEF,KAAK,uBAAuB,GAAG;IAC7B,aAAa,EAAE,OAAO,CAAC;IACvB,KAAK,EAAE,mBAAmB,CAAC;IAC3B;;;;OAIG;IACH,iBAAiB,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,oBAAoB,EAAE,oBAAoB,CAAC;IAC3C;;;OAGG;IACH,mBAAmB,EAAE,oBAAoB,CAAC;IAC1C;;;;;;OAMG;IACH,cAAc,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,MAAM,IAAI,CAAC;IAClD;;;;;OAKG;IACH,2BAA2B,EAAE,OAAO,CAAC;IACrC;;;;;OAKG;IACH,yBAAyB,EAAE,MAAM,MAAM,IAAI,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAC1C,uBAAuB,EACvB,OAAO,GAAG,eAAe,CAC1B,GAAG;IACF,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IAC5C;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,oBAAoB,CAAC;IAC3C;;;;;OAKG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC,CAAC;AAEF,eAAO,MAAM,YAAY,wCAA+C,CAAC;AAEzE,eAAO,MAAM,eAAe,wBAM3B,CAAC;AAEF,eAAO,MAAM,mBAAmB,+CACqB,CAAC;AAEtD,eAAO,MAAM,sBAAsB,+BAMlC,CAAC;AAEF,eAAO,MAAM,eAAe,2BAG3B,CAAC;AAiIF,wBAAgB,oBAAoB,CAAC,EACnC,KAAK,EACL,aAAa,EACb,oBAAoB,EACpB,mBAAmB,EACnB,wBAAgC,EAChC,QAAQ,GACT,EAAE,yBAAyB,qBAkB3B"}

package/Modal/index.js

@@ -35,14 +35,16 @@ const jsxRuntime = require("react/jsx-runtime");
 const React = require("react");
 const utilities_css = require("../utilities/css.js");
 const utilities_useScrollbar = require("../utilities/useScrollbar.js");
+const mergeProps = require("../__chunks__/mergeProps-DLPcevok.js");
 const Button = require("../__chunks__/Button-CQdi4TMV.js");
 const Close = require("../__chunks__/Close-BQ2IlPyf.js");
 const HorizontalStack = require("../__chunks__/HorizontalStack-CWdKKY8L.js");
 const Icon = require("../__chunks__/Icon-BRlbo3RF.js");
 const Text = require("../__chunks__/Text-DkzMEqky.js");
 const VerticalStack = require("../__chunks__/VerticalStack-BHkiocKU.js");
-const useModalOverlay = require("../__chunks__/useModalOverlay-C4Gci3MA.js");
+const ariaHideOutside = require("../__chunks__/ariaHideOutside-Dl8SH3FU.js");
 const Overlay = require("../__chunks__/Overlay-BNP_t3v4.js");
+const FocusScope = require("../__chunks__/FocusScope-CncDnO-E.js");
 const useOverlayTrigger = require("../__chunks__/useOverlayTrigger-DP9RbCAF.js");
 const useIntersectionDetection = require("../__chunks__/useIntersectionDetection-DI5n4zwA.js");
 const useDialog = require("../__chunks__/useDialog-uxNR0maK.js");
@@ -66,16 +68,75 @@ const useModalTrigger = () => {
   const modalTriggerContext = useModalTriggerContext();
   return modalTriggerContext.state;
 };
-function ModalTriggerProvider({ state, isDismissable, children }) {
-  const [hasOpenNestedModal, setHasOpenNestedModal] = React.useState(false);
-  const context = React.useMemo(() => {
-    return {
-      hasOpenNestedModal,
-      setHasOpenNestedModal,
-      state,
-      isDismissable
+function useModalNesting({ childNestingBehavior, selfNestingBehavior, allowsThirdPartyOverlays, isOpen }) {
+  var _a, _b;
+  const parentContext = React.useContext(ModalTriggerContext);
+  const [replacingChildCount, setReplacingChildCount] = React.useState(0);
+  const [thirdPartyDescendantCount, setThirdPartyDescendantCount] = React.useState(0);
+  const childNesting = (_a = childNestingBehavior != null ? childNestingBehavior : parentContext == null ? void 0 : parentContext.childNestingBehavior) != null ? _a : "stack";
+  const selfNesting = (_b = selfNestingBehavior != null ? selfNestingBehavior : parentContext == null ? void 0 : parentContext.childNestingBehavior) != null ? _b : "stack";
+  const registerNested = React.useCallback((replaces) => {
+    if (!replaces) {
+      return () => {
+      };
+    }
+    setReplacingChildCount((count) => count + 1);
+    let released = false;
+    return () => {
+      if (released) {
+        return;
+      }
+      released = true;
+      setReplacingChildCount((count) => Math.max(0, count - 1));
+    };
+  }, []);
+  const parentRegisterNested = parentContext == null ? void 0 : parentContext.registerNested;
+  const selfReplacesParent = selfNesting === "replace";
+  mergeProps.$f0a04ccd8dbdd83b$export$e5c5a5f917a5871c(() => {
+    if (!parentRegisterNested || !isOpen) {
+      return;
+    }
+    return parentRegisterNested(selfReplacesParent);
+  }, [parentRegisterNested, isOpen, selfReplacesParent]);
+  const registerThirdPartyOverlay = React.useCallback(() => {
+    setThirdPartyDescendantCount((count) => count + 1);
+    let released = false;
+    return () => {
+      if (released) {
+        return;
+      }
+      released = true;
+      setThirdPartyDescendantCount((count) => Math.max(0, count - 1));
     };
-  }, [hasOpenNestedModal, state, isDismissable]);
+  }, []);
+  const parentRegisterThirdPartyOverlay = parentContext == null ? void 0 : parentContext.registerThirdPartyOverlay;
+  const hasThirdPartyInSubtree = allowsThirdPartyOverlays || thirdPartyDescendantCount > 0;
+  mergeProps.$f0a04ccd8dbdd83b$export$e5c5a5f917a5871c(() => {
+    if (!parentRegisterThirdPartyOverlay || !isOpen || !hasThirdPartyInSubtree) {
+      return;
+    }
+    return parentRegisterThirdPartyOverlay();
+  }, [parentRegisterThirdPartyOverlay, isOpen, hasThirdPartyInSubtree]);
+  return React.useMemo(() => ({
+    hasReplacingChild: replacingChildCount > 0,
+    childNestingBehavior: childNesting,
+    selfNestingBehavior: selfNesting,
+    registerNested,
+    hasOpenThirdPartyDescendant: thirdPartyDescendantCount > 0,
+    registerThirdPartyOverlay
+  }), [replacingChildCount, childNesting, selfNesting, registerNested, thirdPartyDescendantCount, registerThirdPartyOverlay]);
+}
+function ModalTriggerProvider({ state, isDismissable, childNestingBehavior, selfNestingBehavior, allowsThirdPartyOverlays = false, children }) {
+  const nesting = useModalNesting({
+    childNestingBehavior,
+    selfNestingBehavior,
+    allowsThirdPartyOverlays,
+    isOpen: state.isOpen
+  });
+  const context = React.useMemo(() => __spreadProps(__spreadValues({}, nesting), {
+    state,
+    isDismissable
+  }), [nesting, state, isDismissable]);
   return jsxRuntime.jsx(ModalTriggerContext.Provider, {
     value: context,
     children
@@ -215,34 +276,94 @@ function ModalHeader(props) {
     })
   });
 }
+const MODAL_BOX_ATTRIBUTE = "data-easy-ui-modal-box";
+function shouldCloseOnInteractOutside(target) {
+  return !target.closest(`[${MODAL_BOX_ATTRIBUTE}]`);
+}
 function ModalUnderlay(props) {
-  const _a = props, { state, children } = _a, overlayProps = __objRest(_a, ["state", "children"]);
-  const { isDismissable = true } = overlayProps;
+  return props.allowsThirdPartyOverlays ? jsxRuntime.jsx(ThirdPartyOverlayUnderlay, __spreadValues({}, props)) : jsxRuntime.jsx(FocusTrappingUnderlay, __spreadValues({}, props));
+}
+function FocusTrappingUnderlay(props) {
+  const { state, children, isDismissable = true } = props;
+  const { hasOpenThirdPartyDescendant } = useModalTriggerContext();
+  const shouldTrap = !hasOpenThirdPartyDescendant;
   const ref = React.useRef(null);
-  const { modalProps, underlayProps } = useModalOverlay.$8ac8429251c45e4b$export$dbc0f175b25fb0fb(__spreadProps(__spreadValues({}, overlayProps), {
+  const { overlayProps, underlayProps } = ariaHideOutside.$a11501f3d1d39e6c$export$ea8f71083e90600f({
+    isOpen: state.isOpen,
+    onClose: state.close,
     isDismissable,
-    isKeyboardDismissDisabled: !isDismissable
-  }), state, ref);
-  const { hasOpenNestedModal } = useModalTriggerContext();
-  const className = utilities_css.classNames(styles.underlayBg, hasOpenNestedModal && styles.underlayBgHidden);
+    isKeyboardDismissDisabled: !isDismissable,
+    shouldCloseOnInteractOutside
+  }, ref);
+  ariaHideOutside.$49c51c25361d4cd2$export$ee0f7cc6afcd1c18({
+    isDisabled: !state.isOpen
+  });
+  React.useEffect(() => {
+    if (state.isOpen && shouldTrap && ref.current) {
+      return ariaHideOutside.$5e3802645cc19319$export$1c3ebcada18427bf([ref.current], {
+        shouldUseInert: true
+      });
+    }
+  }, [state.isOpen, shouldTrap]);
+  return jsxRuntime.jsx(ModalUnderlayContent, {
+    modalProps: overlayProps,
+    underlayProps,
+    modalRef: ref,
+    shouldContainFocus: shouldTrap,
+    children
+  });
+}
+function ThirdPartyOverlayUnderlay(props) {
+  const { state, children, isDismissable = true } = props;
+  const ref = React.useRef(null);
+  const { overlayProps, underlayProps } = ariaHideOutside.$a11501f3d1d39e6c$export$ea8f71083e90600f({
+    isOpen: state.isOpen,
+    onClose: state.close,
+    isDismissable,
+    isKeyboardDismissDisabled: !isDismissable,
+    shouldCloseOnInteractOutside
+  }, ref);
+  ariaHideOutside.$49c51c25361d4cd2$export$ee0f7cc6afcd1c18({
+    isDisabled: !state.isOpen
+  });
+  return jsxRuntime.jsx(ModalUnderlayContent, {
+    modalProps: overlayProps,
+    underlayProps,
+    modalRef: ref,
+    keepVisibleUnderModal: true,
+    children
+  });
+}
+function ModalUnderlayContent({ modalProps, underlayProps, modalRef, children, keepVisibleUnderModal = false, shouldContainFocus = false }) {
+  const { hasReplacingChild } = useModalTriggerContext();
+  const className = utilities_css.classNames(styles.underlayBg, hasReplacingChild && styles.underlayBgHidden);
   return jsxRuntime.jsx(Overlay.$337b884510726a0d$export$c6fdb837b070b4ff, {
-    children: jsxRuntime.jsx("div", __spreadProps(__spreadValues({
-      className
-    }, underlayProps), {
-      children: jsxRuntime.jsxs("div", __spreadProps(__spreadValues({}, modalProps), {
-        ref,
-        className: styles.underlayBox,
-        children: [jsxRuntime.jsx("div", {
-          className: styles.underlayEdge
-        }), children, jsxRuntime.jsx("div", {
-          className: styles.underlayEdge
-        })]
+    disableFocusManagement: true,
+    children: jsxRuntime.jsx(FocusScope.$9bf71ea28793e738$export$20e40289641fbbb6, {
+      contain: shouldContainFocus,
+      restoreFocus: true,
+      children: jsxRuntime.jsx("div", __spreadProps(__spreadValues({
+        className
+      }, underlayProps), {
+        children: jsxRuntime.jsxs("div", __spreadProps(__spreadValues(__spreadProps(__spreadValues({}, modalProps), {
+          ref: modalRef,
+          className: styles.underlayBox
+        }), {
+          [MODAL_BOX_ATTRIBUTE]: "true"
+        }), {
+          "data-live-announcer": keepVisibleUnderModal ? "true" : void 0,
+          children: [jsxRuntime.jsx("div", {
+            className: styles.underlayEdge
+          }), children, jsxRuntime.jsx("div", {
+            className: styles.underlayEdge
+          })]
+        }))
       }))
-    }))
+    })
   });
 }
 function ModalTrigger(props) {
-  const _a = props, { children, isDismissable = true } = _a, inTriggerProps = __objRest(_a, ["children", "isDismissable"]);
+  const _a = props, { children, isDismissable = true, allowsThirdPartyOverlays = false, childNestingBehavior, selfNestingBehavior } = _a, inTriggerProps = __objRest(_a, ["children", "isDismissable", "allowsThirdPartyOverlays", "childNestingBehavior", "selfNestingBehavior"]);
   const state = Overlay.$fc909762b330b746$export$61c6a8c84e605fb6(inTriggerProps);
   const { triggerProps, overlayProps } = useOverlayTrigger.$628037886ba31236$export$f9d5c8beee7d008d({
     type: "dialog"
@@ -254,6 +375,9 @@ function ModalTrigger(props) {
   return jsxRuntime.jsxs(ModalTriggerProvider, {
     state,
     isDismissable,
+    childNestingBehavior,
+    selfNestingBehavior,
+    allowsThirdPartyOverlays,
     children: [React.cloneElement(trigger, triggerProps), state.isOpen && jsxRuntime.jsx(ModalUnderlay, __spreadProps(__spreadValues({}, props), {
       state,
       children: React.cloneElement(typeof modal === "function" ? modal(state.close) : modal, overlayProps)
@@ -261,7 +385,7 @@ function ModalTrigger(props) {
   });
 }
 function ModalContainer(props) {
-  const { children, isDismissable = true, onDismiss = () => {
+  const { children, isDismissable = true, allowsThirdPartyOverlays = false, childNestingBehavior, selfNestingBehavior, onDismiss = () => {
   } } = props;
   const childArray = React.Children.toArray(children);
   if (childArray.length > 1) {
@@ -291,9 +415,13 @@ function ModalContainer(props) {
   return jsxRuntime.jsx(ModalTriggerProvider, {
     state,
     isDismissable,
+    childNestingBehavior,
+    selfNestingBehavior,
+    allowsThirdPartyOverlays,
     children: state.isOpen && jsxRuntime.jsx(ModalUnderlay, {
       state,
       isDismissable,
+      allowsThirdPartyOverlays,
       children: lastChild ? React.cloneElement(lastChild, overlayProps) : null
     })
   });

package/Modal/index.mjs

@@ -30,17 +30,19 @@ var __objRest = (source, exclude) => {
   return target;
 };
 import { jsx, jsxs } from "react/jsx-runtime";
-import React__default, { createContext, useState, useMemo, useContext, cloneElement, useRef } from "react";
+import React__default, { createContext, useMemo, useContext, useState, useCallback, useRef, useEffect, cloneElement } from "react";
 import { classNames, variationName } from "../utilities/css.mjs";
 import { useScrollbar } from "../utilities/useScrollbar.mjs";
+import { a as $f0a04ccd8dbdd83b$export$e5c5a5f917a5871c } from "../__chunks__/mergeProps-COnPag8r.mjs";
 import { B as Button } from "../__chunks__/Button-JL1YQxJ5.mjs";
 import { C as Close } from "../__chunks__/Close-Cq6Q6MN6.mjs";
 import { H as HorizontalStack } from "../__chunks__/HorizontalStack-CJavrBHm.mjs";
 import { I as Icon } from "../__chunks__/Icon-BIpaQJ_I.mjs";
 import { T as Text } from "../__chunks__/Text-D6oT5WJQ.mjs";
 import { V as VerticalStack } from "../__chunks__/VerticalStack-DoMqBfYD.mjs";
-import { $ as $8ac8429251c45e4b$export$dbc0f175b25fb0fb } from "../__chunks__/useModalOverlay-BmYXH7rq.mjs";
+import { $ as $a11501f3d1d39e6c$export$ea8f71083e90600f, a as $49c51c25361d4cd2$export$ee0f7cc6afcd1c18, b as $5e3802645cc19319$export$1c3ebcada18427bf } from "../__chunks__/ariaHideOutside-BYq9cUwo.mjs";
 import { d as $337b884510726a0d$export$c6fdb837b070b4ff, a as $fc909762b330b746$export$61c6a8c84e605fb6 } from "../__chunks__/Overlay-Dkjxuk6V.mjs";
+import { c as $9bf71ea28793e738$export$20e40289641fbbb6 } from "../__chunks__/FocusScope-B_FktBGw.mjs";
 import { $ as $628037886ba31236$export$f9d5c8beee7d008d } from "../__chunks__/useOverlayTrigger-CIVwezu3.mjs";
 import { u as useIntersectionDetection } from "../__chunks__/useIntersectionDetection-BvUmtDgl.mjs";
 import { $ as $40df3f8667284809$export$d55e7ee900f34e93 } from "../__chunks__/useDialog-nKMoC_Cs.mjs";
@@ -64,16 +66,75 @@ const useModalTrigger = () => {
   const modalTriggerContext = useModalTriggerContext();
   return modalTriggerContext.state;
 };
-function ModalTriggerProvider({ state, isDismissable, children }) {
-  const [hasOpenNestedModal, setHasOpenNestedModal] = useState(false);
-  const context = useMemo(() => {
-    return {
-      hasOpenNestedModal,
-      setHasOpenNestedModal,
-      state,
-      isDismissable
+function useModalNesting({ childNestingBehavior, selfNestingBehavior, allowsThirdPartyOverlays, isOpen }) {
+  var _a, _b;
+  const parentContext = useContext(ModalTriggerContext);
+  const [replacingChildCount, setReplacingChildCount] = useState(0);
+  const [thirdPartyDescendantCount, setThirdPartyDescendantCount] = useState(0);
+  const childNesting = (_a = childNestingBehavior != null ? childNestingBehavior : parentContext == null ? void 0 : parentContext.childNestingBehavior) != null ? _a : "stack";
+  const selfNesting = (_b = selfNestingBehavior != null ? selfNestingBehavior : parentContext == null ? void 0 : parentContext.childNestingBehavior) != null ? _b : "stack";
+  const registerNested = useCallback((replaces) => {
+    if (!replaces) {
+      return () => {
+      };
+    }
+    setReplacingChildCount((count) => count + 1);
+    let released = false;
+    return () => {
+      if (released) {
+        return;
+      }
+      released = true;
+      setReplacingChildCount((count) => Math.max(0, count - 1));
+    };
+  }, []);
+  const parentRegisterNested = parentContext == null ? void 0 : parentContext.registerNested;
+  const selfReplacesParent = selfNesting === "replace";
+  $f0a04ccd8dbdd83b$export$e5c5a5f917a5871c(() => {
+    if (!parentRegisterNested || !isOpen) {
+      return;
+    }
+    return parentRegisterNested(selfReplacesParent);
+  }, [parentRegisterNested, isOpen, selfReplacesParent]);
+  const registerThirdPartyOverlay = useCallback(() => {
+    setThirdPartyDescendantCount((count) => count + 1);
+    let released = false;
+    return () => {
+      if (released) {
+        return;
+      }
+      released = true;
+      setThirdPartyDescendantCount((count) => Math.max(0, count - 1));
     };
-  }, [hasOpenNestedModal, state, isDismissable]);
+  }, []);
+  const parentRegisterThirdPartyOverlay = parentContext == null ? void 0 : parentContext.registerThirdPartyOverlay;
+  const hasThirdPartyInSubtree = allowsThirdPartyOverlays || thirdPartyDescendantCount > 0;
+  $f0a04ccd8dbdd83b$export$e5c5a5f917a5871c(() => {
+    if (!parentRegisterThirdPartyOverlay || !isOpen || !hasThirdPartyInSubtree) {
+      return;
+    }
+    return parentRegisterThirdPartyOverlay();
+  }, [parentRegisterThirdPartyOverlay, isOpen, hasThirdPartyInSubtree]);
+  return useMemo(() => ({
+    hasReplacingChild: replacingChildCount > 0,
+    childNestingBehavior: childNesting,
+    selfNestingBehavior: selfNesting,
+    registerNested,
+    hasOpenThirdPartyDescendant: thirdPartyDescendantCount > 0,
+    registerThirdPartyOverlay
+  }), [replacingChildCount, childNesting, selfNesting, registerNested, thirdPartyDescendantCount, registerThirdPartyOverlay]);
+}
+function ModalTriggerProvider({ state, isDismissable, childNestingBehavior, selfNestingBehavior, allowsThirdPartyOverlays = false, children }) {
+  const nesting = useModalNesting({
+    childNestingBehavior,
+    selfNestingBehavior,
+    allowsThirdPartyOverlays,
+    isOpen: state.isOpen
+  });
+  const context = useMemo(() => __spreadProps(__spreadValues({}, nesting), {
+    state,
+    isDismissable
+  }), [nesting, state, isDismissable]);
   return jsx(ModalTriggerContext.Provider, {
     value: context,
     children
@@ -213,34 +274,94 @@ function ModalHeader(props) {
     })
   });
 }
+const MODAL_BOX_ATTRIBUTE = "data-easy-ui-modal-box";
+function shouldCloseOnInteractOutside(target) {
+  return !target.closest(`[${MODAL_BOX_ATTRIBUTE}]`);
+}
 function ModalUnderlay(props) {
-  const _a = props, { state, children } = _a, overlayProps = __objRest(_a, ["state", "children"]);
-  const { isDismissable = true } = overlayProps;
-  const ref = React__default.useRef(null);
-  const { modalProps, underlayProps } = $8ac8429251c45e4b$export$dbc0f175b25fb0fb(__spreadProps(__spreadValues({}, overlayProps), {
+  return props.allowsThirdPartyOverlays ? jsx(ThirdPartyOverlayUnderlay, __spreadValues({}, props)) : jsx(FocusTrappingUnderlay, __spreadValues({}, props));
+}
+function FocusTrappingUnderlay(props) {
+  const { state, children, isDismissable = true } = props;
+  const { hasOpenThirdPartyDescendant } = useModalTriggerContext();
+  const shouldTrap = !hasOpenThirdPartyDescendant;
+  const ref = useRef(null);
+  const { overlayProps, underlayProps } = $a11501f3d1d39e6c$export$ea8f71083e90600f({
+    isOpen: state.isOpen,
+    onClose: state.close,
     isDismissable,
-    isKeyboardDismissDisabled: !isDismissable
-  }), state, ref);
-  const { hasOpenNestedModal } = useModalTriggerContext();
-  const className = classNames(styles.underlayBg, hasOpenNestedModal && styles.underlayBgHidden);
+    isKeyboardDismissDisabled: !isDismissable,
+    shouldCloseOnInteractOutside
+  }, ref);
+  $49c51c25361d4cd2$export$ee0f7cc6afcd1c18({
+    isDisabled: !state.isOpen
+  });
+  useEffect(() => {
+    if (state.isOpen && shouldTrap && ref.current) {
+      return $5e3802645cc19319$export$1c3ebcada18427bf([ref.current], {
+        shouldUseInert: true
+      });
+    }
+  }, [state.isOpen, shouldTrap]);
+  return jsx(ModalUnderlayContent, {
+    modalProps: overlayProps,
+    underlayProps,
+    modalRef: ref,
+    shouldContainFocus: shouldTrap,
+    children
+  });
+}
+function ThirdPartyOverlayUnderlay(props) {
+  const { state, children, isDismissable = true } = props;
+  const ref = useRef(null);
+  const { overlayProps, underlayProps } = $a11501f3d1d39e6c$export$ea8f71083e90600f({
+    isOpen: state.isOpen,
+    onClose: state.close,
+    isDismissable,
+    isKeyboardDismissDisabled: !isDismissable,
+    shouldCloseOnInteractOutside
+  }, ref);
+  $49c51c25361d4cd2$export$ee0f7cc6afcd1c18({
+    isDisabled: !state.isOpen
+  });
+  return jsx(ModalUnderlayContent, {
+    modalProps: overlayProps,
+    underlayProps,
+    modalRef: ref,
+    keepVisibleUnderModal: true,
+    children
+  });
+}
+function ModalUnderlayContent({ modalProps, underlayProps, modalRef, children, keepVisibleUnderModal = false, shouldContainFocus = false }) {
+  const { hasReplacingChild } = useModalTriggerContext();
+  const className = classNames(styles.underlayBg, hasReplacingChild && styles.underlayBgHidden);
   return jsx($337b884510726a0d$export$c6fdb837b070b4ff, {
-    children: jsx("div", __spreadProps(__spreadValues({
-      className
-    }, underlayProps), {
-      children: jsxs("div", __spreadProps(__spreadValues({}, modalProps), {
-        ref,
-        className: styles.underlayBox,
-        children: [jsx("div", {
-          className: styles.underlayEdge
-        }), children, jsx("div", {
-          className: styles.underlayEdge
-        })]
+    disableFocusManagement: true,
+    children: jsx($9bf71ea28793e738$export$20e40289641fbbb6, {
+      contain: shouldContainFocus,
+      restoreFocus: true,
+      children: jsx("div", __spreadProps(__spreadValues({
+        className
+      }, underlayProps), {
+        children: jsxs("div", __spreadProps(__spreadValues(__spreadProps(__spreadValues({}, modalProps), {
+          ref: modalRef,
+          className: styles.underlayBox
+        }), {
+          [MODAL_BOX_ATTRIBUTE]: "true"
+        }), {
+          "data-live-announcer": keepVisibleUnderModal ? "true" : void 0,
+          children: [jsx("div", {
+            className: styles.underlayEdge
+          }), children, jsx("div", {
+            className: styles.underlayEdge
+          })]
+        }))
       }))
-    }))
+    })
   });
 }
 function ModalTrigger(props) {
-  const _a = props, { children, isDismissable = true } = _a, inTriggerProps = __objRest(_a, ["children", "isDismissable"]);
+  const _a = props, { children, isDismissable = true, allowsThirdPartyOverlays = false, childNestingBehavior, selfNestingBehavior } = _a, inTriggerProps = __objRest(_a, ["children", "isDismissable", "allowsThirdPartyOverlays", "childNestingBehavior", "selfNestingBehavior"]);
   const state = $fc909762b330b746$export$61c6a8c84e605fb6(inTriggerProps);
   const { triggerProps, overlayProps } = $628037886ba31236$export$f9d5c8beee7d008d({
     type: "dialog"
@@ -252,6 +373,9 @@ function ModalTrigger(props) {
   return jsxs(ModalTriggerProvider, {
     state,
     isDismissable,
+    childNestingBehavior,
+    selfNestingBehavior,
+    allowsThirdPartyOverlays,
     children: [cloneElement(trigger, triggerProps), state.isOpen && jsx(ModalUnderlay, __spreadProps(__spreadValues({}, props), {
       state,
       children: cloneElement(typeof modal === "function" ? modal(state.close) : modal, overlayProps)
@@ -259,7 +383,7 @@ function ModalTrigger(props) {
   });
 }
 function ModalContainer(props) {
-  const { children, isDismissable = true, onDismiss = () => {
+  const { children, isDismissable = true, allowsThirdPartyOverlays = false, childNestingBehavior, selfNestingBehavior, onDismiss = () => {
   } } = props;
   const childArray = React__default.Children.toArray(children);
   if (childArray.length > 1) {
@@ -289,9 +413,13 @@ function ModalContainer(props) {
   return jsx(ModalTriggerProvider, {
     state,
     isDismissable,
+    childNestingBehavior,
+    selfNestingBehavior,
+    allowsThirdPartyOverlays,
     children: state.isOpen && jsx(ModalUnderlay, {
       state,
       isDismissable,
+      allowsThirdPartyOverlays,
       children: lastChild ? cloneElement(lastChild, overlayProps) : null
     })
   });

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@easypost/easy-ui",
-  "version": "1.0.0-alpha.120",
+  "version": "1.0.0-alpha.122",
   "sideEffects": [
     "**/*.css"
   ],
   "dependencies": {
+    "@react-aria/overlays": "^3.31.0",
     "@easypost/easy-ui-icons": "1.0.0-alpha.55",
     "@easypost/easy-ui-tokens": "1.0.0-alpha.17",
     "@react-aria/toast": "^3.0.9",