@eocrm/design-system 0.6.24 → 0.7.0

package/dist/components/Modal/Content.js

@@ -0,0 +1,79 @@
+'use client';
+import { useModalContext } from "./context.js";
+import { useFocusTrap } from "../_internal/overlay/useFocusTrap.js";
+import { isFocusLost } from "../_internal/overlay/focusRestore.js";
+import { overlayStack } from "../_internal/overlay/useOverlayStack.js";
+import Modal_module_default from "./Modal.module.js";
+import { useEffect, useLayoutEffect, useRef } from "react";
+import clsx from "clsx";
+import { jsx } from "react/jsx-runtime";
+// src/components/Modal/Content.tsx
+/**
+* Dialog container. `role="dialog"`, `aria-modal="true"`, tabIndex=-1 so
+* the focus trap can take over. Owns:
+* - Initial focus on open (either initialFocusRef or the container itself).
+* - Focus trap (active only when this modal is top of the stack).
+* - Escape capture-phase listener (also gated by isTop).
+* - Renders the compound children (Header/Body/Footer/Close) inside the dialog.
+*/
+function Content({ children, className, style }) {
+	const ctx = useModalContext("Content");
+	const { setOpen } = ctx;
+	const initialFocusPendingRef = useRef(true);
+	useLayoutEffect(() => {
+		if (!ctx.open) {
+			initialFocusPendingRef.current = true;
+			return;
+		}
+		if (!ctx.isTop) return;
+		if (!initialFocusPendingRef.current) {
+			queueMicrotask(() => {
+				if (isFocusLost()) ctx.contentRef.current?.focus({ preventScroll: true });
+			});
+			return;
+		}
+		initialFocusPendingRef.current = false;
+		queueMicrotask(() => {
+			(ctx.initialFocusRef?.current ?? ctx.contentRef.current)?.focus({ preventScroll: true });
+		});
+	}, [
+		ctx.open,
+		ctx.isTop,
+		ctx.initialFocusRef,
+		ctx.contentRef
+	]);
+	useEffect(() => {
+		if (!ctx.open) return;
+		function onKeyDown(e) {
+			if (e.key !== "Escape") return;
+			if (!overlayStack.isTop(ctx.modalId)) return;
+			if (overlayStack.hasOpenFloating() || overlayStack.wasEscapeConsumed(e)) return;
+			if (ctx.disableEscapeClose) return;
+			e.preventDefault();
+			setOpen(false);
+		}
+		document.addEventListener("keydown", onKeyDown, true);
+		return () => document.removeEventListener("keydown", onKeyDown, true);
+	}, [
+		ctx.open,
+		ctx.modalId,
+		ctx.disableEscapeClose,
+		setOpen
+	]);
+	useFocusTrap(ctx.contentRef, ctx.open && ctx.isTop);
+	return /* @__PURE__ */ jsx("div", {
+		ref: ctx.contentRef,
+		role: "dialog",
+		"aria-modal": "true",
+		"aria-labelledby": ctx.headingId ?? void 0,
+		"aria-label": !ctx.headingId ? ctx.ariaLabel : void 0,
+		"aria-describedby": ctx.ariaDescribedBy,
+		tabIndex: -1,
+		"data-state": ctx.open ? "open" : "closed",
+		"data-size": ctx.size,
+		className: clsx(Modal_module_default.content, Modal_module_default[`size-${ctx.size}`], className),
+		style,
+		children
+	});
+}
+export { Content };

package/dist/components/Modal/Footer.d.ts

@@ -0,0 +1,10 @@
+import { type HTMLAttributes } from 'react';
+export interface ModalFooterProps extends HTMLAttributes<HTMLDivElement> {
+    /** Horizontal action alignment. Default 'end'. */
+    align?: 'start' | 'end' | 'space-between';
+}
+/**
+ * Pinned action bar at the bottom of the modal, announced as a `role="group"`.
+ * @see docs/components/Modal.md
+ */
+export declare const Footer: import("react").ForwardRefExoticComponent<ModalFooterProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/Modal/Footer.js

@@ -0,0 +1,20 @@
+'use client';
+import Modal_module_default from "./Modal.module.js";
+import { forwardRef } from "react";
+import clsx from "clsx";
+import { jsx } from "react/jsx-runtime";
+// src/components/Modal/Footer.tsx
+/**
+* Pinned action bar at the bottom of the modal, announced as a `role="group"`.
+* @see docs/components/Modal.md
+*/
+var Footer = forwardRef(function Footer({ align = "end", className, children, ...rest }, ref) {
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		role: "group",
+		className: clsx(Modal_module_default.footer, Modal_module_default[`footerAlign-${align}`], className),
+		...rest,
+		children
+	});
+});
+export { Footer };

package/dist/components/Modal/Header.d.ts

@@ -0,0 +1,10 @@
+import { type HTMLAttributes } from 'react';
+export interface ModalHeaderProps extends HTMLAttributes<HTMLDivElement> {
+    /** Show the built-in × close button on the right edge. Default true. */
+    closeButton?: boolean;
+}
+/**
+ * Title bar at the top of the modal: names the dialog and shows a close button unless `closeButton={false}`.
+ * @see docs/components/Modal.md
+ */
+export declare const Header: import("react").ForwardRefExoticComponent<ModalHeaderProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/Modal/Header.js

@@ -0,0 +1,46 @@
+'use client';
+import { Button } from "../Button/Button.js";
+import { useTranslation } from "../../i18n/useTranslation.js";
+import { useModalContext } from "./context.js";
+import { sanitizeId } from "../_internal/refs.js";
+import Modal_module_default from "./Modal.module.js";
+import { forwardRef, useEffect, useId } from "react";
+import clsx from "clsx";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { X } from "lucide-react";
+// src/components/Modal/Header.tsx
+/**
+* Title bar at the top of the modal: names the dialog and shows a close button unless `closeButton={false}`.
+* @see docs/components/Modal.md
+*/
+var Header = forwardRef(function Header({ closeButton = true, className, children, ...rest }, ref) {
+	const t = useTranslation();
+	const ctx = useModalContext("Header");
+	const rawId = useId();
+	const headingId = `modal-heading-${sanitizeId(rawId)}`;
+	useEffect(() => {
+		ctx.setHeadingId(headingId);
+		return () => ctx.setHeadingId(null);
+	}, [ctx, headingId]);
+	return /* @__PURE__ */ jsxs("div", {
+		ref,
+		className: clsx(Modal_module_default.header, className),
+		...rest,
+		children: [/* @__PURE__ */ jsx("h2", {
+			id: headingId,
+			className: Modal_module_default.headerTitle,
+			children
+		}), closeButton && /* @__PURE__ */ jsx(Button, {
+			variant: "ghost",
+			size: "xs",
+			iconOnly: true,
+			"aria-label": t("modal.close"),
+			onClick: () => ctx.setOpen(false),
+			children: /* @__PURE__ */ jsx(X, {
+				size: 16,
+				"aria-hidden": "true"
+			})
+		})]
+	});
+});
+export { Header };

package/dist/components/Modal/Modal.css

@@ -0,0 +1,202 @@
+:root {
+  --modal-overlay-bg: var(--color-bg-overlay);
+  --modal-overlay-bg-blur: var(--color-bg-overlay-blur);
+  --modal-overlay-z: var(--z-modal);
+  --modal-overlay-opacity-hidden: var(--opacity-hidden);
+  --modal-overlay-opacity-visible: var(--opacity-visible);
+  --modal-overlay-transition: var(--transition-base);
+  --modal-bg: var(--color-bg);
+  --modal-radius: var(--radius-lg);
+  --modal-shadow: var(--shadow-lg);
+  --modal-opacity-hidden: var(--opacity-hidden);
+  --modal-opacity-visible: var(--opacity-visible);
+  --modal-transition: var(--transition-base);
+  --modal-content-width-sm: var(--size-modal-sm);
+  --modal-content-width-md: var(--size-modal-md);
+  --modal-content-width-lg: var(--size-modal-lg);
+  --modal-content-width-full: 95vw;
+  --modal-content-height-full: 90dvh;
+  --modal-content-padding-default: var(--space-4);
+  --modal-content-padding-sm: var(--space-3);
+  --modal-title-size-default: var(--font-size-lg);
+  --modal-title-size-sm: var(--font-size-md);
+  --modal-header-gap: var(--space-3);
+  --modal-header-border-color: var(--color-border);
+  --modal-header-title-font-weight: var(--font-weight-semibold);
+  --modal-header-title-fg: var(--color-fg);
+  --modal-footer-gap: var(--space-2);
+  --modal-footer-border-color: var(--color-border);
+}
+
+.Modal__overlay__Hp9_U {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100vw;
+  width: 100dvw;
+  height: 100vh;
+  height: 100dvh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--modal-overlay-bg);
+  z-index: calc(var(--modal-overlay-z) + var(--modal-depth, 0) * 2);
+  opacity: var(--modal-overlay-opacity-visible);
+  transition: opacity var(--modal-overlay-transition);
+  overscroll-behavior: contain;
+  will-change: opacity;
+  contain: layout paint;
+}
+@starting-style {
+  .Modal__overlay__Hp9_U {
+    opacity: var(--modal-overlay-opacity-hidden);
+  }
+}
+
+.Modal__overlay__Hp9_U[data-state=closed] {
+  opacity: var(--modal-overlay-opacity-hidden);
+}
+
+.Modal__overlay__Hp9_U[data-stack-position=hidden] {
+  display: none;
+}
+
+.Modal__overlay__Hp9_U[data-variant=blur] {
+  background: var(--modal-overlay-bg-blur);
+  backdrop-filter: blur(4px);
+  -webkit-backdrop-filter: blur(4px);
+}
+
+.Modal__overlay__Hp9_U[data-overlay-paint=no] {
+  background: transparent;
+  backdrop-filter: none;
+  -webkit-backdrop-filter: none;
+}
+
+.Modal__content__qM5vH {
+  position: relative;
+  --modal-pad: var(--modal-content-padding-default);
+  --modal-title-size: var(--modal-title-size-default);
+  display: flex;
+  flex-direction: column;
+  background: var(--modal-bg);
+  border-radius: var(--modal-radius);
+  box-shadow: var(--modal-shadow);
+  z-index: calc(var(--modal-overlay-z) + var(--modal-depth, 0) * 2 + 1);
+  max-height: calc(100vh - 64px);
+  max-height: calc(100dvh - 64px);
+  width: min(100% - 32px, var(--modal-width, var(--modal-content-width-md)));
+  opacity: var(--modal-opacity-visible);
+  transform: translateY(0) scale(1);
+  transition: opacity var(--modal-transition), transform var(--modal-transition);
+  will-change: opacity, transform;
+  contain: layout paint;
+}
+@starting-style {
+  .Modal__content__qM5vH {
+    opacity: var(--modal-opacity-hidden);
+    transform: translateY(8px) scale(0.96);
+  }
+}
+
+.Modal__content__qM5vH[data-state=closed] {
+  opacity: var(--modal-opacity-hidden);
+  transform: translateY(8px) scale(0.96);
+}
+
+.Modal__size-sm__uL8uL {
+  --modal-width: var(--modal-content-width-sm);
+  --modal-pad: var(--modal-content-padding-sm);
+  --modal-title-size: var(--modal-title-size-sm);
+}
+
+.Modal__size-md__Q48aY {
+  --modal-width: var(--modal-content-width-md);
+}
+
+.Modal__size-lg__vHTPu {
+  --modal-width: var(--modal-content-width-lg);
+}
+
+.Modal__size-full__x6iRB {
+  --modal-width: var(--modal-content-width-full);
+  height: var(--modal-content-height-full);
+}
+
+.Modal__header__cAY25 {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--modal-header-gap);
+  padding: var(--modal-pad);
+  border-bottom: var(--border-width) solid var(--modal-header-border-color);
+}
+
+.Modal__headerTitle__NBPOe {
+  margin: 0;
+  font-size: var(--modal-title-size);
+  font-weight: var(--modal-header-title-font-weight);
+  color: var(--modal-header-title-fg);
+}
+
+.Modal__body__3x28V {
+  padding: var(--modal-pad);
+  overflow-y: auto;
+  flex: 1 1 auto;
+  overscroll-behavior: contain;
+}
+
+.Modal__bodyPaddingNone__82jF5 {
+  padding: 0;
+}
+
+.Modal__footer__8Uszb {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(--modal-footer-gap);
+  padding: var(--modal-pad);
+  border-top: var(--border-width) solid var(--modal-footer-border-color);
+}
+
+.Modal__footerAlign-start__mTnIP {
+  justify-content: flex-start;
+}
+
+.Modal__footerAlign-end__4FQdZ {
+  justify-content: flex-end;
+}
+
+.Modal__footerAlign-space-between__Ppz6J {
+  justify-content: space-between;
+}
+
+@media (max-width: 640px) {
+  .Modal__overlay__Hp9_U {
+    align-items: flex-start;
+  }
+  .Modal__content__qM5vH {
+    width: 100vw;
+    width: 100dvw;
+    height: 100vh;
+    height: 100dvh;
+    max-width: 100vw;
+    max-width: 100dvw;
+    max-height: 100vh;
+    max-height: 100dvh;
+    border-radius: 0;
+  }
+}
+@media (prefers-reduced-motion: reduce) {
+  .Modal__overlay__Hp9_U,
+  .Modal__content__qM5vH {
+    transition: none;
+  }
+  @starting-style {
+    .Modal__overlay__Hp9_U,
+    .Modal__content__qM5vH {
+      opacity: var(--modal-opacity-visible);
+      transform: none;
+    }
+  }
+}

package/dist/components/Modal/Modal.d.ts

@@ -0,0 +1,18 @@
+import { ModalRoot } from './ModalRoot.js';
+import { Close } from './Close.js';
+/**
+ * Compound `<Modal>` family: `Modal.Header`, `Body`, `Footer` and `Close` attached via `Object.assign`.
+ * @see docs/components/Modal.md
+ */
+export declare const Modal: typeof ModalRoot & {
+    Header: import("react").ForwardRefExoticComponent<import("./Header.js").ModalHeaderProps & import("react").RefAttributes<HTMLDivElement>>;
+    Body: import("react").ForwardRefExoticComponent<import("./Body.js").ModalBodyProps & import("react").RefAttributes<HTMLDivElement>>;
+    Footer: import("react").ForwardRefExoticComponent<import("./Footer.js").ModalFooterProps & import("react").RefAttributes<HTMLDivElement>>;
+    Close: typeof Close;
+};
+export type { ModalProps } from './ModalRoot.js';
+export type { ModalSize, ModalOverlayVariant, ModalStackMode } from './context.js';
+export type { ModalHeaderProps } from './Header.js';
+export type { ModalBodyProps } from './Body.js';
+export type { ModalFooterProps } from './Footer.js';
+export type { ModalCloseProps } from './Close.js';

package/dist/components/Modal/Modal.js

@@ -0,0 +1,18 @@
+'use client';
+import { ModalRoot } from "./ModalRoot.js";
+import { Header } from "./Header.js";
+import { Body } from "./Body.js";
+import { Footer } from "./Footer.js";
+import { Close } from "./Close.js";
+// src/components/Modal/Modal.tsx
+/**
+* Compound `<Modal>` family: `Modal.Header`, `Body`, `Footer` and `Close` attached via `Object.assign`.
+* @see docs/components/Modal.md
+*/
+var Modal = Object.assign(ModalRoot, {
+	Header,
+	Body,
+	Footer,
+	Close
+});
+export { Modal };

package/dist/components/Modal/Modal.module.js

@@ -0,0 +1,26 @@
+import "./Modal.css";
+// src/components/Modal/Modal.module.scss
+var overlay = "Modal__overlay__Hp9_U";
+var content = "Modal__content__qM5vH";
+var header = "Modal__header__cAY25";
+var headerTitle = "Modal__headerTitle__NBPOe";
+var body = "Modal__body__3x28V";
+var bodyPaddingNone = "Modal__bodyPaddingNone__82jF5";
+var footer = "Modal__footer__8Uszb";
+var Modal_module_default = {
+	overlay,
+	content,
+	"size-sm": "Modal__size-sm__uL8uL",
+	"size-md": "Modal__size-md__Q48aY",
+	"size-lg": "Modal__size-lg__vHTPu",
+	"size-full": "Modal__size-full__x6iRB",
+	header,
+	headerTitle,
+	body,
+	bodyPaddingNone,
+	footer,
+	"footerAlign-start": "Modal__footerAlign-start__mTnIP",
+	"footerAlign-end": "Modal__footerAlign-end__4FQdZ",
+	"footerAlign-space-between": "Modal__footerAlign-space-between__Ppz6J"
+};
+export { body, bodyPaddingNone, content, Modal_module_default as default, footer, header, headerTitle, overlay };

package/dist/components/Modal/ModalRoot.d.ts

@@ -0,0 +1,111 @@
+import { type CSSProperties, type ReactNode, type RefObject } from 'react';
+import { type ModalOverlayVariant, type ModalSize } from './context.js';
+import { type OverlayStackMode as ModalStackMode } from '../_internal/overlay/index.js';
+export interface ModalProps {
+    /** Controlled open state. Required. */
+    open: boolean;
+    /** Fired when Modal wants to change open state — Esc, overlay click, Close button, programmatic. */
+    onOpenChange: (open: boolean) => void;
+    /**
+     * Size preset. Defaults to `'md'`.
+     * - `'sm'` (400px) — confirms and short prompts.
+     * - `'md'` (560px) — the default; typical forms.
+     * - `'lg'` (800px) — wide forms, tables, previews.
+     * - `'full'` (95vw × 90dvh, fixed height) — long documents, e.g. an HTML email.
+     * See {@link ModalSize}.
+     * @default 'md'
+     */
+    size?: ModalSize;
+    /**
+     * Overlay variant. 'solid' (default) paints a dark dimming layer.
+     * 'blur' uses a light tinted background plus `backdrop-filter: blur(4px)`
+     * for a frosted-glass effect. 'blur' costs an extra compositor layer —
+     * fine for normal use; avoid stacking three blurred modals at once.
+     */
+    overlay?: ModalOverlayVariant;
+    /**
+     * How this modal relates to existing modals in the stack when it opens.
+     *
+     * - `'overlay'` (default): if there's a modal below this one, it stays
+     *   visible underneath. This modal's own overlay paints transparent so
+     *   the parent's dim shows through. Only the bottom modal (depth 0)
+     *   paints the actual dim/blur. The user sees the parent's context behind
+     *   the active modal.
+     * - `'replace'`: any modals below this one are hidden via `display: none`
+     *   (React state preserved). This modal paints its own overlay normally.
+     *   Best for forced-step modals where the parent context is irrelevant.
+     *
+     * Has no effect when this is the only open modal.
+     */
+    stackMode?: ModalStackMode;
+    /**
+     * Disable Escape-to-close. Default false. Combined with `dismissOnOverlayClick: false`
+     * and omitting `<Modal.Close>` produces a fully forced step.
+     */
+    disableEscapeClose?: boolean;
+    /**
+     * When false, clicking the overlay backdrop does NOT close the modal. Default true.
+     */
+    dismissOnOverlayClick?: boolean;
+    /**
+     * Initial focus target on open. Default: the dialog container itself.
+     * Pass a ref to override (e.g. focus the first input in a form).
+     */
+    initialFocusRef?: RefObject<HTMLElement | null>;
+    /**
+     * Where focus goes when the modal closes. Default: back to whatever was
+     * focused when it opened.
+     *
+     * That default breaks whenever the opener is gone by close time — a row's
+     * "⋯" trigger whose row was just deleted, or a button that unmounts in the
+     * same commit that opens the modal (the capture then snapshots `<body>`).
+     * Focus lands on `<body>` and a keyboard user loses their place.
+     *
+     * The ref is read **at close time**, not at open time, so it may be pointed
+     * at whatever still exists once the work is done — the next row's trigger,
+     * the empty state's first button. If it is empty or its element has also
+     * left the document, Modal falls back to the captured opener, and then to
+     * doing nothing, exactly as before this prop existed.
+     *
+     * The target is scrolled into view (`block: 'nearest'`) after focus; the
+     * captured opener is not.
+     *
+     * @example
+     * // The deleted row's trigger is gone on close; aim at the next one.
+     * const returnFocusRef = useRef<HTMLElement | null>(null);
+     * <Modal open={open} onOpenChange={setOpen} returnFocusRef={returnFocusRef}>
+     *   <Modal.Header>Delete mailbox?</Modal.Header>
+     *   <Modal.Footer>
+     *     <Button
+     *       variant="danger"
+     *       onClick={async () => {
+     *         await deleteMailbox(id);
+     *         returnFocusRef.current = nextRowTriggerRef.current ?? connectButtonRef.current;
+     *         setOpen(false);
+     *       }}
+     *     >
+     *       Delete
+     *     </Button>
+     *   </Modal.Footer>
+     * </Modal>
+     */
+    returnFocusRef?: RefObject<HTMLElement | null>;
+    /** Compound children: Header / Body / Footer / Close + any consumer JSX. */
+    children: ReactNode;
+    /** className passes through to the dialog container. */
+    className?: string;
+    /** style passes through to the dialog container. */
+    style?: CSSProperties;
+    /**
+     * Required for a11y when no Modal.Header is rendered. When Header IS rendered,
+     * aria-labelledby auto-binds to the heading id; this prop is then ignored.
+     */
+    'aria-label'?: string;
+    /** Optional id of an external descriptor element; sets aria-describedby on the dialog. */
+    'aria-describedby'?: string;
+}
+/**
+ * Modal dialog: focus-locked, scroll-locked, ARIA-correct overlay panel with stack-aware overlays; controlled `open`.
+ * @see docs/components/Modal.md
+ */
+export declare function ModalRoot({ open, onOpenChange, size, overlay, stackMode, disableEscapeClose, dismissOnOverlayClick, initialFocusRef, returnFocusRef, children, className, style, 'aria-label': ariaLabel, 'aria-describedby': ariaDescribedBy, }: ModalProps): import("react").JSX.Element;

package/dist/components/Modal/ModalRoot.js

@@ -0,0 +1,95 @@
+'use client';
+import { ModalContext } from "./context.js";
+import { isFocusLost, restoreFocusTo } from "../_internal/overlay/focusRestore.js";
+import { useOverlayStack } from "../_internal/overlay/useOverlayStack.js";
+import { useScrollLock } from "../_internal/overlay/useScrollLock.js";
+import { Overlay } from "./Overlay.js";
+import { Content } from "./Content.js";
+import { sanitizeId } from "../_internal/refs.js";
+import { useCallback, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+// src/components/Modal/ModalRoot.tsx
+/**
+* Modal dialog: focus-locked, scroll-locked, ARIA-correct overlay panel with stack-aware overlays; controlled `open`.
+* @see docs/components/Modal.md
+*/
+function ModalRoot({ open, onOpenChange, size = "md", overlay = "solid", stackMode = "overlay", disableEscapeClose = false, dismissOnOverlayClick = true, initialFocusRef, returnFocusRef, children, className, style, "aria-label": ariaLabel, "aria-describedby": ariaDescribedBy }) {
+	const rawId = useId();
+	const modalId = `modal-${sanitizeId(rawId)}`;
+	const contentRef = useRef(null);
+	const [headingId, setHeadingId] = useState(null);
+	const previouslyFocusedRef = useRef(null);
+	const prevOpenRef = useRef(false);
+	const focusEffectGenerationRef = useRef(0);
+	const restoreFocus = useCallback(() => {
+		const captured = previouslyFocusedRef.current;
+		previouslyFocusedRef.current = null;
+		const requested = returnFocusRef?.current ?? null;
+		if (requested && document.contains(requested)) {
+			restoreFocusTo(requested);
+			requested.scrollIntoView?.({ block: "nearest" });
+			return;
+		}
+		if (captured && document.contains(captured)) restoreFocusTo(captured);
+	}, [returnFocusRef]);
+	useLayoutEffect(() => {
+		const generation = ++focusEffectGenerationRef.current;
+		if (open && !prevOpenRef.current) previouslyFocusedRef.current = document.activeElement ?? null;
+		if (!open && prevOpenRef.current) restoreFocus();
+		prevOpenRef.current = open;
+		if (open) return () => {
+			queueMicrotask(() => {
+				if (focusEffectGenerationRef.current === generation && isFocusLost()) restoreFocus();
+			});
+		};
+	}, [open, restoreFocus]);
+	const { depth, isTop, topMode } = useOverlayStack(modalId, open, stackMode);
+	useScrollLock(open);
+	const setOpen = useCallback((next) => {
+		onOpenChange(next);
+	}, [onOpenChange]);
+	useEffect(() => {
+		if (!open) return;
+		if (process.env.NODE_ENV === "production") return;
+		let cancelled = false;
+		queueMicrotask(() => {
+			if (cancelled) return;
+			if (!headingId && !ariaLabel) console.warn("<Modal> must be labelled. Either render <Modal.Header> or pass an `aria-label` prop. Screen-reader users get no announcement otherwise.");
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, [
+		open,
+		headingId,
+		ariaLabel
+	]);
+	const value = {
+		open,
+		setOpen,
+		modalId,
+		contentRef,
+		headingId,
+		setHeadingId,
+		size,
+		overlay,
+		disableEscapeClose,
+		dismissOnOverlayClick,
+		initialFocusRef,
+		ariaLabel,
+		ariaDescribedBy,
+		depth: depth ?? 0,
+		isTop,
+		stackMode,
+		topMode
+	};
+	return /* @__PURE__ */ jsx(ModalContext.Provider, {
+		value,
+		children: open && /* @__PURE__ */ jsx(Overlay, { children: /* @__PURE__ */ jsx(Content, {
+			className,
+			style,
+			children
+		}) })
+	});
+}
+export { ModalRoot };

package/dist/components/Modal/Overlay.d.ts

@@ -0,0 +1,21 @@
+import { type ReactNode } from 'react';
+export interface OverlayProps {
+    children: ReactNode;
+}
+/**
+ * Portaled dimming/blurred backdrop rendered behind the dialog. Owns the
+ * inert-background attribute on body children + the overlay-click
+ * dismissal (only fires when the click target is the overlay itself,
+ * not bubbled from content).
+ *
+ * Carries three data-attributes consumed by SCSS:
+ * - `data-variant`        : 'solid' | 'blur' — visual variant
+ * - `data-stack-position` : 'top' | 'underneath' | 'hidden'
+ *     - 'top'       — this is the topmost open modal
+ *     - 'underneath' — lower modal in overlay-stack mode (stays visible)
+ *     - 'hidden'    — lower modal in replace-stack mode (display: none)
+ * - `data-overlay-paint`  : 'yes' | 'no'
+ *     - 'yes' — this overlay paints its dim/blur background
+ *     - 'no'  — transparent (upper modal in overlay-stack mode)
+ */
+export declare function Overlay({ children }: OverlayProps): import("react").ReactPortal;