@vjdesigns/vjdesigns-ui 0.0.0-stage → 2.0.0

package/dist/components/overlays/HoverCard/HoverCard.mjs

@@ -0,0 +1,173 @@
+import { useControllableState as e } from "../../../hooks/useControllableState.mjs";
+import { OverlayLayerProvider as t, useOverlayLayer as n } from "../../../hooks/useOverlayLayer.mjs";
+import { useDismiss as r } from "../../../hooks/useDismiss.mjs";
+import { useFloatingPosition as i } from "../../../hooks/useFloatingPosition.mjs";
+import { getFocusable as a } from "../../../hooks/useFocusTrap.mjs";
+import { getChildRef as o } from "../../../utils/refs.mjs";
+import { useMergedRef as s } from "../../../hooks/useMergedRef.mjs";
+import { cx as c } from "../../../utils/cx.mjs";
+import { cloneSlot as l } from "../../../utils/slot.mjs";
+import { Portal as u } from "../../utilities/Portal/Portal.mjs";
+import d from "./HoverCard.module.css.mjs";
+import { createContext as f, useCallback as p, useContext as m, useEffect as h, useId as g, useRef as _, useState as v } from "react";
+import { jsx as y, jsxs as b } from "react/jsx-runtime";
+//#region src/components/overlays/HoverCard/HoverCard.tsx
+var x = f(null);
+function S(e) {
+	let t = m(x);
+	if (!t) throw Error(`${e} must be rendered inside <HoverCard>.`);
+	return t;
+}
+function C(e) {
+	try {
+		return e.matches(":focus-visible");
+	} catch {
+		return !0;
+	}
+}
+var w = ({ children: t, open: n, defaultOpen: r = !1, onOpenChange: i, openDelay: a = 500, closeDelay: o = 300 }) => {
+	let [s, c] = e({
+		value: n,
+		defaultValue: r,
+		onChange: i
+	}), l = _(null), u = _(null), d = _(void 0), f = `hovercard-${g()}`, m = p(() => {
+		window.clearTimeout(d.current), d.current = void 0;
+	}, []);
+	h(() => m, [m]);
+	let v = p((e) => {
+		m(), c(e);
+	}, [m, c]), b = (e, t) => {
+		m(), t <= 0 ? v(e) : d.current = window.setTimeout(() => v(e), t);
+	}, S = {
+		open: s,
+		setOpen: v,
+		scheduleOpen: () => {
+			s ? m() : b(!0, a);
+		},
+		scheduleClose: () => {
+			s ? b(!1, o) : m();
+		},
+		cancelTimer: m,
+		triggerRef: l,
+		contentRef: u,
+		contentId: f
+	};
+	return /* @__PURE__ */ y(x.Provider, {
+		value: S,
+		children: t
+	});
+}, T = ({ children: e }) => {
+	let t = S("HoverCard.Trigger"), n = s(t.triggerRef, o(e)), r = _(!1), i = _(!1), c = {
+		"data-state": t.open ? "open" : "closed",
+		onPointerEnter: (e) => {
+			e.pointerType !== "touch" && t.scheduleOpen();
+		},
+		onPointerLeave: (e) => {
+			e.pointerType !== "touch" && !r.current && t.scheduleClose();
+		},
+		onFocus: (e) => {
+			!i.current && C(e.currentTarget) && (r.current = !0, t.scheduleOpen());
+		},
+		onBlur: (e) => {
+			r.current = !1;
+			let n = e.relatedTarget;
+			n && t.contentRef.current?.contains(n) || (t.open ? t.setOpen(!1) : t.cancelTimer());
+		},
+		onKeyDown: (e) => {
+			if (e.key !== "Tab" || e.shiftKey || !t.open) return;
+			let n = t.contentRef.current, r = n ? a(n)[0] : void 0;
+			r && (e.preventDefault(), r.focus());
+		},
+		onPointerDown: () => {
+			i.current = !0, window.setTimeout(() => i.current = !1, 0), t.setOpen(!1);
+		}
+	};
+	return l(e, c, n);
+}, E = {
+	sm: d.sm,
+	md: d.md,
+	lg: d.lg
+}, D = ({ container: e, ...t }) => {
+	let n = S("HoverCard.Content");
+	return n.open ? /* @__PURE__ */ y(u, {
+		container: e,
+		children: /* @__PURE__ */ y(k, {
+			...t,
+			ctx: n
+		})
+	}) : null;
+}, O = 20, k = ({ ctx: e, placement: o = "bottom", offset: l = 8, size: u = "md", showArrow: f = !1, className: p, style: m, children: g, ref: x, onPointerEnter: S, onPointerLeave: C, onKeyDown: w, onBlur: T, ...D }) => {
+	let k = _(null), A = s(e.contentRef, x), j = i(e.triggerRef, k, {
+		open: !0,
+		placement: o,
+		offset: l,
+		arrowPadding: O
+	}), M = j.placement.split("-")[0], N = j.arrow ? j.arrow.x ?? j.arrow.y ?? null : null, P = n({ active: !0 });
+	r([k, e.triggerRef], {
+		active: !0,
+		layer: P,
+		onDismiss: (t) => {
+			let n = !!e.contentRef.current?.contains(document.activeElement);
+			e.setOpen(!1), t.type === "keydown" && n && e.triggerRef.current?.focus();
+		}
+	});
+	let [F, I] = v("ltr");
+	h(() => {
+		let t = e.triggerRef.current;
+		t && I(getComputedStyle(t).direction === "rtl" ? "rtl" : "ltr");
+	}, [e.triggerRef]);
+	let L = (t) => {
+		if (w?.(t), t.defaultPrevented || t.key !== "Tab") return;
+		let n = e.contentRef.current, r = e.triggerRef.current;
+		if (!n || !r) return;
+		let i = a(n), o = document.activeElement;
+		if (t.shiftKey && (o === i[0] || o === n)) t.preventDefault(), r.focus();
+		else if (!t.shiftKey && o === i[i.length - 1]) {
+			let i = a(document.body).find((e) => !n.contains(e) && !!(r.compareDocumentPosition(e) & Node.DOCUMENT_POSITION_FOLLOWING));
+			t.preventDefault(), e.setOpen(!1), (i ?? r).focus();
+		}
+	}, R = (t) => {
+		T?.(t);
+		let n = t.relatedTarget;
+		n && !e.contentRef.current?.contains(n) && n !== e.triggerRef.current && e.setOpen(!1);
+	}, z = {
+		...m,
+		...N === null ? null : { "--_arrow-pos": `${N}px` }
+	};
+	return /* @__PURE__ */ y(t, {
+		layer: P,
+		children: /* @__PURE__ */ y("div", {
+			ref: k,
+			className: d.positioner,
+			style: j.style,
+			dir: F,
+			children: /* @__PURE__ */ b("div", {
+				...D,
+				ref: A,
+				id: e.contentId,
+				className: c(d.content, E[u], p),
+				style: z,
+				"data-side": M,
+				"data-state": "open",
+				onPointerEnter: (t) => {
+					S?.(t), t.pointerType !== "touch" && e.cancelTimer();
+				},
+				onPointerLeave: (t) => {
+					C?.(t), t.pointerType !== "touch" && (e.contentRef.current?.contains(document.activeElement) || e.scheduleClose());
+				},
+				onKeyDown: L,
+				onBlur: R,
+				children: [g, f && /* @__PURE__ */ y("span", {
+					className: d.arrow,
+					"data-side": M,
+					"aria-hidden": "true"
+				})]
+			})
+		})
+	});
+}, A = Object.assign(w, {
+	Trigger: T,
+	Content: D
+});
+//#endregion
+export { A as HoverCard, D as HoverCardContent, T as HoverCardTrigger };

package/dist/components/overlays/HoverCard/HoverCard.module.css.cjs.js

@@ -0,0 +1 @@
+var e=`_positioner_1ej8b_7`,t=`_content_1ej8b_12`,n=`_sm_1ej8b_37`,r=`_md_1ej8b_42`,i=`_lg_1ej8b_47`,a=`_arrow_1ej8b_85`,o={positioner:e,content:t,"hovercard-in":`_hovercard-in_1ej8b_1`,sm:n,md:r,lg:i,arrow:a};exports.arrow=a,exports.content=t,exports.default=o,exports.lg=i,exports.md=r,exports.positioner=e,exports.sm=n;

package/dist/components/overlays/HoverCard/HoverCard.module.css.mjs

@@ -0,0 +1,12 @@
+//#region src/components/overlays/HoverCard/HoverCard.module.css
+var e = "_positioner_1ej8b_7", t = "_content_1ej8b_12", n = "_sm_1ej8b_37", r = "_md_1ej8b_42", i = "_lg_1ej8b_47", a = "_arrow_1ej8b_85", o = {
+	positioner: e,
+	content: t,
+	"hovercard-in": "_hovercard-in_1ej8b_1",
+	sm: n,
+	md: r,
+	lg: i,
+	arrow: a
+};
+//#endregion
+export { a as arrow, t as content, o as default, i as lg, r as md, e as positioner, n as sm };

package/dist/components/overlays/HoverCard/index.d.ts

@@ -0,0 +1 @@
+export * from './HoverCard';

package/dist/components/overlays/Modal/ConfirmModal.cjs.js

@@ -0,0 +1 @@
+const e=require("../../../hooks/useControllableState.cjs.js"),t=require("../../utilities/LocaleProvider/LocaleProvider.cjs.js"),n=require("../../../utils/cx.cjs.js"),r=require("../../primitives/Button/Button.cjs.js"),i=require("../../primitives/Icon/icons.cjs.js"),a=require("./Modal.module.css.cjs.js"),o=require("./ModalContent.cjs.js"),s=require("./Modal.cjs.js");let c=require("react"),l=require("react/jsx-runtime");function u({open:u,defaultOpen:d=!1,onOpenChange:f,trigger:p,title:m,description:h,children:g,confirmLabel:_,cancelLabel:v,confirmLoadingText:y,tone:b=`primary`,onConfirm:x,onCancel:S,size:C=`sm`,finalFocusRef:w}){let T=t.useMessages(),E=_??T.modal.confirm,D=v??T.modal.cancel,[O,k]=e.useControllableState({value:u,defaultValue:d,onChange:f}),[A,j]=(0,c.useState)(!1),M=(0,c.useRef)(null),N=e=>{if(!e){if(A)return;S?.()}k(e)},P=async()=>{if(A)return;let e=x?.();if(e&&typeof e.then==`function`){j(!0);try{await e,k(!1)}catch{}finally{j(!1)}return}k(!1)},F=b===`danger`?i.WarningIcon:i.InfoIcon;return(0,l.jsxs)(s.Modal,{open:O,onOpenChange:N,role:`alertdialog`,size:C,showClose:!1,closeOnEscape:!A,initialFocusRef:M,finalFocusRef:w,children:[p&&(0,l.jsx)(s.ModalTrigger,{children:p}),(0,l.jsxs)(o.ModalContent,{children:[(0,l.jsxs)(s.ModalHeader,{children:[(0,l.jsx)(`span`,{className:n.cx(a.default.confirmIcon,b===`danger`&&a.default.confirmIconDanger),"aria-hidden":`true`,children:(0,l.jsx)(F,{size:`lg`})}),(0,l.jsx)(s.ModalTitle,{children:m}),h!=null&&(0,l.jsx)(s.ModalDescription,{children:h})]}),g!=null&&(0,l.jsx)(s.ModalBody,{children:g}),(0,l.jsxs)(s.ModalFooter,{children:[(0,l.jsx)(r.Button,{ref:M,variant:`outline`,tone:`neutral`,disabled:A,onClick:()=>N(!1),children:D}),(0,l.jsx)(r.Button,{variant:`solid`,tone:b,loading:A,loadingText:y,onClick:P,children:E})]})]})]})}exports.ConfirmModal=u;

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

@@ -0,0 +1,47 @@
+import { ReactElement, ReactNode, RefObject } from 'react';
+import { ModalSize } from './Modal';
+/** Confirm button color. `danger` is for destructive actions (delete, remove, discard). */
+export type ConfirmModalTone = "primary" | "danger";
+export interface ConfirmModalProps {
+    /** Whether the dialog is open (controlled). Pair with `onOpenChange`. */
+    open?: boolean;
+    /** Whether the dialog starts open (uncontrolled). @default false */
+    defaultOpen?: boolean;
+    /** Called with the next open state. */
+    onOpenChange?: (open: boolean) => void;
+    /** Optional element (usually a `Button`) that opens the dialog. */
+    trigger?: ReactElement;
+    /** Question or statement the user must respond to, e.g. "Delete this team?". */
+    title: ReactNode;
+    /** Consequences of the action, e.g. "This can't be undone." Wired to `aria-describedby`. */
+    description?: ReactNode;
+    /** Extra content between the description and the actions. */
+    children?: ReactNode;
+    /** Label of the confirm button. Name the action ("Delete team"), not "OK". @default "Confirm" */
+    confirmLabel?: ReactNode;
+    /** Label of the cancel button. @default "Cancel" */
+    cancelLabel?: ReactNode;
+    /** Text shown and announced next to the spinner while `onConfirm` is pending. */
+    confirmLoadingText?: ReactNode;
+    /** Confirm button color; `danger` also shows a warning icon. @default "primary" */
+    tone?: ConfirmModalTone;
+    /**
+     * Called when the user confirms. May return a promise: the confirm
+     * button shows a spinner and the dialog stays open (Escape and Cancel are
+     * disabled) until it settles. It closes on success; on rejection it stays
+     * open so you can show an error.
+     */
+    onConfirm?: () => void | Promise<unknown>;
+    /** Called when the user cancels (Cancel button or Escape). */
+    onCancel?: () => void;
+    /** Width on screens 640px and wider. @default "sm" */
+    size?: ModalSize;
+    /** Element to focus after closing. Defaults to the trigger. */
+    finalFocusRef?: RefObject<HTMLElement | null>;
+}
+/**
+ * A ready-made confirmation (`role="alertdialog"`) built on `Modal`.
+ * Initial focus goes to Cancel, the least destructive action. Pressing the
+ * overlay does not close it; Escape and Cancel do.
+ */
+export declare function ConfirmModal({ open: openProp, defaultOpen, onOpenChange, trigger, title, description, children, confirmLabel: confirmLabelProp, cancelLabel: cancelLabelProp, confirmLoadingText, tone, onConfirm, onCancel, size, finalFocusRef, }: ConfirmModalProps): import("react").JSX.Element;

package/dist/components/overlays/Modal/ConfirmModal.mjs

@@ -0,0 +1,76 @@
+import { useControllableState as e } from "../../../hooks/useControllableState.mjs";
+import { useMessages as t } from "../../utilities/LocaleProvider/LocaleProvider.mjs";
+import { cx as n } from "../../../utils/cx.mjs";
+import { Button as r } from "../../primitives/Button/Button.mjs";
+import { InfoIcon as i, WarningIcon as a } from "../../primitives/Icon/icons.mjs";
+import o from "./Modal.module.css.mjs";
+import { ModalContent as s } from "./ModalContent.mjs";
+import { Modal as c, ModalBody as l, ModalDescription as u, ModalFooter as d, ModalHeader as f, ModalTitle as p, ModalTrigger as m } from "./Modal.mjs";
+import { useRef as h, useState as g } from "react";
+import { jsx as _, jsxs as v } from "react/jsx-runtime";
+//#region src/components/overlays/Modal/ConfirmModal.tsx
+function y({ open: y, defaultOpen: b = !1, onOpenChange: x, trigger: S, title: C, description: w, children: T, confirmLabel: E, cancelLabel: D, confirmLoadingText: O, tone: k = "primary", onConfirm: A, onCancel: j, size: M = "sm", finalFocusRef: N }) {
+	let P = t(), F = E ?? P.modal.confirm, I = D ?? P.modal.cancel, [L, R] = e({
+		value: y,
+		defaultValue: b,
+		onChange: x
+	}), [z, B] = g(!1), V = h(null), H = (e) => {
+		if (!e) {
+			if (z) return;
+			j?.();
+		}
+		R(e);
+	}, U = async () => {
+		if (z) return;
+		let e = A?.();
+		if (e && typeof e.then == "function") {
+			B(!0);
+			try {
+				await e, R(!1);
+			} catch {} finally {
+				B(!1);
+			}
+			return;
+		}
+		R(!1);
+	}, W = k === "danger" ? a : i;
+	return /* @__PURE__ */ v(c, {
+		open: L,
+		onOpenChange: H,
+		role: "alertdialog",
+		size: M,
+		showClose: !1,
+		closeOnEscape: !z,
+		initialFocusRef: V,
+		finalFocusRef: N,
+		children: [S && /* @__PURE__ */ _(m, { children: S }), /* @__PURE__ */ v(s, { children: [
+			/* @__PURE__ */ v(f, { children: [
+				/* @__PURE__ */ _("span", {
+					className: n(o.confirmIcon, k === "danger" && o.confirmIconDanger),
+					"aria-hidden": "true",
+					children: /* @__PURE__ */ _(W, { size: "lg" })
+				}),
+				/* @__PURE__ */ _(p, { children: C }),
+				w != null && /* @__PURE__ */ _(u, { children: w })
+			] }),
+			T != null && /* @__PURE__ */ _(l, { children: T }),
+			/* @__PURE__ */ v(d, { children: [/* @__PURE__ */ _(r, {
+				ref: V,
+				variant: "outline",
+				tone: "neutral",
+				disabled: z,
+				onClick: () => H(!1),
+				children: I
+			}), /* @__PURE__ */ _(r, {
+				variant: "solid",
+				tone: k,
+				loading: z,
+				loadingText: O,
+				onClick: U,
+				children: F
+			})] })
+		] })]
+	});
+}
+//#endregion
+export { y as ConfirmModal };

package/dist/components/overlays/Modal/Modal.cjs.js

@@ -0,0 +1 @@
+const e=require("../../../hooks/useControllableState.cjs.js"),t=require("../../utilities/LocaleProvider/LocaleProvider.cjs.js"),n=require("../../../utils/refs.cjs.js"),r=require("../../../utils/cx.cjs.js"),i=require("../../primitives/Typography/Typography.cjs.js"),a=require("./ModalContext.cjs.js"),o=require("./Modal.module.css.cjs.js"),s=require("./ModalContent.cjs.js"),c=require("./useScrollRegion.cjs.js");let l=require("react"),u=require("react/jsx-runtime");function d({open:n,defaultOpen:r=!1,onOpenChange:i,size:o=`md`,placement:s=`center`,mobileLayout:c=`sheet`,scrollBehavior:d=`inside`,role:f=`dialog`,closeOnOverlayPress:p,closeOnEscape:m=!0,initialFocusRef:h,finalFocusRef:g,showClose:_=!0,closeLabel:v,children:y}){let b=t.useMessages(),x=v??b.modal.close,[S,C]=e.useControllableState({value:n,defaultValue:r,onChange:i}),w=(0,l.useRef)(null),T=(0,l.useRef)(null),E=(0,l.useId)(),[D,O]=(0,l.useState)(null),[k,A]=(0,l.useState)(null);(0,l.useLayoutEffect)(()=>{if(!S)return;let e=document.activeElement;T.current=e instanceof HTMLElement&&e!==document.body?e:null},[S]);let j=(0,l.useCallback)(e=>(O(e),()=>O(t=>t===e?null:t)),[]),M=(0,l.useCallback)(e=>(A(e),()=>A(t=>t===e?null:t)),[]),N=(0,l.useMemo)(()=>({open:S,setOpen:e=>C(e),size:o,placement:s,mobileLayout:c,scrollBehavior:d,role:f,closeOnOverlayPress:p??f!==`alertdialog`,closeOnEscape:m,showClose:_,closeLabel:x,initialFocusRef:h,finalFocusRef:g,triggerRef:w,returnFocusRef:T,defaultTitleId:`${E}-title`,defaultDescriptionId:`${E}-description`,titleId:D,descriptionId:k,registerTitle:j,registerDescription:M}),[S,C,o,s,c,d,f,p,m,_,x,h,g,E,D,k,j,M]);return(0,u.jsx)(a.ModalContext.Provider,{value:N,children:y})}function f({children:e}){let t=a.useModalContext(`Modal.Trigger`),r=(0,l.isValidElement)(e)?e:null,i=r?.props.ref,o=(0,l.useMemo)(()=>n.mergeRefs(i,t.triggerRef),[i,t.triggerRef]);return r?(0,l.cloneElement)(r,{ref:o,"aria-haspopup":`dialog`,"aria-expanded":t.open,onClick:e=>{r.props.onClick?.(e),e.defaultPrevented||t.setOpen(!0)}}):e}function p({children:e}){let t=a.useModalContext(`Modal.Close`);if(!(0,l.isValidElement)(e))return e;let n=e;return(0,l.cloneElement)(n,{"data-modal-close":``,onClick:e=>{n.props.onClick?.(e),e.defaultPrevented||t.setOpen(!1)}})}function m({className:e,...t}){return(0,u.jsx)(`div`,{...t,className:r.cx(o.default.header,e)})}function h({level:e=2,size:t=`2xl`,id:n,className:s,...c}){let d=a.useModalContext(`Modal.Title`),f=n??d.defaultTitleId,{registerTitle:p}=d;return(0,l.useLayoutEffect)(()=>p(f),[p,f]),(0,u.jsx)(i.Heading,{...c,id:f,level:e,size:t,weight:`black`,className:r.cx(o.default.title,s)})}function g({id:e,className:t,...n}){let s=a.useModalContext(`Modal.Description`),c=e??s.defaultDescriptionId,{registerDescription:d}=s;return(0,l.useLayoutEffect)(()=>d(c),[d,c]),(0,u.jsx)(i.Text,{...n,id:c,tone:`muted`,size:`md`,className:r.cx(o.default.description,t)})}function _({className:e,ref:t,scrollRegionLabel:i,...s}){let d=a.useModalContext(`Modal.Body`),[f,p]=c.useScrollRegion(d.scrollBehavior===`inside`),m=(0,l.useMemo)(()=>n.mergeRefs(t,f),[t,f]),h=p?{tabIndex:0,role:`region`,"aria-label":i,"aria-labelledby":i?void 0:d.titleId??void 0}:{};return(0,u.jsx)(`div`,{...h,...s,ref:m,"data-modal-body":``,className:r.cx(o.default.body,e)})}function v({className:e,...t}){return(0,u.jsx)(`div`,{...t,"data-modal-footer":``,className:r.cx(o.default.footer,e)})}var y=Object.assign(d,{Trigger:f,Content:s.ModalContent,Header:m,Title:h,Description:g,Body:_,Footer:v,Close:p});exports.Modal=y,exports.ModalBody=_,exports.ModalClose=p,exports.ModalContent=s.ModalContent,exports.ModalDescription=g,exports.ModalFooter=v,exports.ModalHeader=m,exports.ModalTitle=h,exports.ModalTrigger=f;

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

@@ -0,0 +1,150 @@
+import { ComponentPropsWithRef, ReactElement, ReactNode, RefObject } from 'react';
+import { HeadingLevel, TypographySize } from '../../primitives/Typography';
+import { ModalContent } from './ModalContent';
+import { ModalMobileLayout, ModalPlacement, ModalRole, ModalScrollBehavior, ModalSize } from './ModalContext';
+export type { ModalMobileLayout, ModalPlacement, ModalRole, ModalScrollBehavior, ModalSize, } from './ModalContext';
+export type { ModalContentProps } from './ModalContent';
+export { ModalContent };
+export interface ModalProps {
+    /** Whether the modal is open (controlled). Pair with `onOpenChange`. */
+    open?: boolean;
+    /** Whether the modal starts open (uncontrolled). @default false */
+    defaultOpen?: boolean;
+    /** Called with the next open state when the modal opens or closes. */
+    onOpenChange?: (open: boolean) => void;
+    /**
+     * Width on screens 640px and wider: `sm` 30rem, `md` 40rem, `lg` 48rem,
+     * `xl` 64rem, `full` the whole viewport. Below 640px every size except
+     * `full` becomes a full-width sheet at the bottom of the screen.
+     * @default "md"
+     */
+    size?: ModalSize;
+    /** Vertical position on screens 640px and wider (and on small screens with `mobileLayout="card"`). @default "center" */
+    placement?: ModalPlacement;
+    /**
+     * Layout below 640px: a bottom `sheet`, or a `card` inset from the edges
+     * and positioned by `placement`. Ignored when `size="full"`. @default "sheet"
+     */
+    mobileLayout?: ModalMobileLayout;
+    /**
+     * `inside`: the modal fits the viewport and `Modal.Body` scrolls.
+     * `outside`: the modal grows and the overlay scrolls. @default "inside"
+     */
+    scrollBehavior?: ModalScrollBehavior;
+    /**
+     * Close when the overlay (backdrop) is pressed.
+     * @default true, or false when `role="alertdialog"`
+     */
+    closeOnOverlayPress?: boolean;
+    /** Close when Escape is pressed (topmost modal only). @default true */
+    closeOnEscape?: boolean;
+    /**
+     * Element to focus when the modal opens. By default focus goes to the
+     * first focusable element in `Modal.Body` (not the close button), then
+     * the dialog itself. For `alertdialog` it goes to the least destructive
+     * action: a `Modal.Close` in the footer.
+     */
+    initialFocusRef?: RefObject<HTMLElement | null>;
+    /**
+     * Element to focus when the modal closes. By default focus returns to
+     * the element that was focused before opening (usually the trigger).
+     */
+    finalFocusRef?: RefObject<HTMLElement | null>;
+    /**
+     * ARIA role. Use `alertdialog` for confirmations that need a response;
+     * it also stops overlay presses from closing the modal by default.
+     * @default "dialog"
+     */
+    role?: ModalRole;
+    /** Show the built-in close button in the top-end corner. @default true */
+    showClose?: boolean;
+    /** Accessible name of the built-in close button. Localize it here. @default "Close" */
+    closeLabel?: string;
+    /** `Modal.Trigger` and `Modal.Content`. */
+    children?: ReactNode;
+}
+/**
+ * An accessible modal dialog (WAI-ARIA APG "Dialog (Modal)" pattern).
+ * `Modal` holds the open state; compose it from `Modal.Trigger`,
+ * `Modal.Content`, `Modal.Header`, `Modal.Title`, `Modal.Description`,
+ * `Modal.Body`, `Modal.Footer`, and `Modal.Close`.
+ *
+ * Accessibility:
+ * - `role="dialog"` (or `alertdialog`) with `aria-modal="true"`, named by
+ *   `Modal.Title` and described by `Modal.Description`.
+ * - While open, everything outside is `inert` (plus `aria-hidden`), page
+ *   scrolling is locked, and Tab / Shift+Tab stay inside.
+ * - Escape closes the topmost modal. Focus returns to the trigger (or
+ *   `finalFocusRef`) on close.
+ * - Stacked modals work: only the topmost one is active.
+ */
+declare function ModalRoot({ open: openProp, defaultOpen, onOpenChange, size, placement, mobileLayout, scrollBehavior, role, closeOnOverlayPress, closeOnEscape, initialFocusRef, finalFocusRef, showClose, closeLabel: closeLabelProp, children, }: ModalProps): import("react").JSX.Element;
+export interface ModalTriggerProps {
+    /**
+     * A single element that opens the modal, usually a `Button`. It receives
+     * `aria-haspopup="dialog"`, `aria-expanded`, and an `onClick` (its own
+     * `onClick` runs first; call `event.preventDefault()` to cancel opening).
+     */
+    children: ReactElement;
+}
+/** Wraps a button so pressing it opens the modal. Focus returns to it on close. */
+export declare function ModalTrigger({ children }: ModalTriggerProps): ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
+export interface ModalCloseProps {
+    /**
+     * A single element that closes the modal, usually a `Button` such as
+     * "Cancel". Its own `onClick` runs first; call `event.preventDefault()`
+     * to keep the modal open. In an `alertdialog`, the first `Modal.Close`
+     * in the footer gets initial focus as the least destructive action.
+     */
+    children: ReactElement;
+}
+/** Wraps a button so pressing it closes the modal. */
+export declare function ModalClose({ children }: ModalCloseProps): ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
+export type ModalHeaderProps = ComponentPropsWithRef<"div">;
+/** Top section holding `Modal.Title` and `Modal.Description`. Leaves room for the close button. */
+export declare function ModalHeader({ className, ...rest }: ModalHeaderProps): import("react").JSX.Element;
+export interface ModalTitleProps extends Omit<ComponentPropsWithRef<"h2">, "color"> {
+    /** Heading level, chosen to fit the document outline. @default 2 */
+    level?: HeadingLevel;
+    /** Visual size. @default "2xl" */
+    size?: TypographySize;
+}
+/**
+ * The dialog's heading. Required: it names the dialog via
+ * `aria-labelledby` (a dev warning appears when it is missing and the
+ * content has no `aria-label`).
+ */
+export declare function ModalTitle({ level, size, id, className, ...rest }: ModalTitleProps): import("react").JSX.Element;
+export type ModalDescriptionProps = Omit<ComponentPropsWithRef<"p">, "color">;
+/** Supporting text under the title, wired to the dialog's `aria-describedby`. Keep it short. */
+export declare function ModalDescription({ id, className, ...rest }: ModalDescriptionProps): import("react").JSX.Element;
+export interface ModalBodyProps extends ComponentPropsWithRef<"div"> {
+    /**
+     * Accessible name of the body while it scrolls (it becomes a focusable
+     * region so keyboard users can scroll it). Defaults to the title.
+     */
+    scrollRegionLabel?: string;
+}
+/**
+ * Main content. With `scrollBehavior="inside"` this is the part that
+ * scrolls; when it overflows it becomes a focusable, labelled region so it
+ * can be scrolled with the keyboard.
+ */
+export declare function ModalBody({ className, ref, scrollRegionLabel, ...rest }: ModalBodyProps): import("react").JSX.Element;
+export type ModalFooterProps = ComponentPropsWithRef<"div">;
+/**
+ * Actions row, end-aligned. Put the least destructive action first
+ * ("Cancel", then "Save"). Below 640px the buttons stack full width with
+ * the last (primary) action on top.
+ */
+export declare function ModalFooter({ className, ...rest }: ModalFooterProps): import("react").JSX.Element;
+export declare const Modal: typeof ModalRoot & {
+    Trigger: typeof ModalTrigger;
+    Content: ({ overlayClassName, className, children, ref, onFocus, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, ...rest }: import('./ModalContent').ModalContentProps) => import("react").JSX.Element | null;
+    Header: typeof ModalHeader;
+    Title: typeof ModalTitle;
+    Description: typeof ModalDescription;
+    Body: typeof ModalBody;
+    Footer: typeof ModalFooter;
+    Close: typeof ModalClose;
+};

package/dist/components/overlays/Modal/Modal.mjs

@@ -0,0 +1,153 @@
+import { useControllableState as e } from "../../../hooks/useControllableState.mjs";
+import { useMessages as t } from "../../utilities/LocaleProvider/LocaleProvider.mjs";
+import { mergeRefs as n } from "../../../utils/refs.mjs";
+import { cx as r } from "../../../utils/cx.mjs";
+import { Heading as i, Text as a } from "../../primitives/Typography/Typography.mjs";
+import { ModalContext as o, useModalContext as s } from "./ModalContext.mjs";
+import c from "./Modal.module.css.mjs";
+import { ModalContent as l } from "./ModalContent.mjs";
+import { useScrollRegion as u } from "./useScrollRegion.mjs";
+import { cloneElement as d, isValidElement as f, useCallback as p, useId as m, useLayoutEffect as h, useMemo as g, useRef as _, useState as v } from "react";
+import { jsx as y } from "react/jsx-runtime";
+//#region src/components/overlays/Modal/Modal.tsx
+function b({ open: n, defaultOpen: r = !1, onOpenChange: i, size: a = "md", placement: s = "center", mobileLayout: c = "sheet", scrollBehavior: l = "inside", role: u = "dialog", closeOnOverlayPress: d, closeOnEscape: f = !0, initialFocusRef: b, finalFocusRef: x, showClose: S = !0, closeLabel: C, children: w }) {
+	let T = t(), E = C ?? T.modal.close, [D, O] = e({
+		value: n,
+		defaultValue: r,
+		onChange: i
+	}), k = _(null), A = _(null), j = m(), [M, N] = v(null), [P, F] = v(null);
+	h(() => {
+		if (!D) return;
+		let e = document.activeElement;
+		A.current = e instanceof HTMLElement && e !== document.body ? e : null;
+	}, [D]);
+	let I = p((e) => (N(e), () => N((t) => t === e ? null : t)), []), L = p((e) => (F(e), () => F((t) => t === e ? null : t)), []), R = g(() => ({
+		open: D,
+		setOpen: (e) => O(e),
+		size: a,
+		placement: s,
+		mobileLayout: c,
+		scrollBehavior: l,
+		role: u,
+		closeOnOverlayPress: d ?? u !== "alertdialog",
+		closeOnEscape: f,
+		showClose: S,
+		closeLabel: E,
+		initialFocusRef: b,
+		finalFocusRef: x,
+		triggerRef: k,
+		returnFocusRef: A,
+		defaultTitleId: `${j}-title`,
+		defaultDescriptionId: `${j}-description`,
+		titleId: M,
+		descriptionId: P,
+		registerTitle: I,
+		registerDescription: L
+	}), [
+		D,
+		O,
+		a,
+		s,
+		c,
+		l,
+		u,
+		d,
+		f,
+		S,
+		E,
+		b,
+		x,
+		j,
+		M,
+		P,
+		I,
+		L
+	]);
+	return /* @__PURE__ */ y(o.Provider, {
+		value: R,
+		children: w
+	});
+}
+function x({ children: e }) {
+	let t = s("Modal.Trigger"), r = f(e) ? e : null, i = r?.props.ref, a = g(() => n(i, t.triggerRef), [i, t.triggerRef]);
+	return r ? d(r, {
+		ref: a,
+		"aria-haspopup": "dialog",
+		"aria-expanded": t.open,
+		onClick: (e) => {
+			r.props.onClick?.(e), e.defaultPrevented || t.setOpen(!0);
+		}
+	}) : e;
+}
+function S({ children: e }) {
+	let t = s("Modal.Close");
+	if (!f(e)) return e;
+	let n = e;
+	return d(n, {
+		"data-modal-close": "",
+		onClick: (e) => {
+			n.props.onClick?.(e), e.defaultPrevented || t.setOpen(!1);
+		}
+	});
+}
+function C({ className: e, ...t }) {
+	return /* @__PURE__ */ y("div", {
+		...t,
+		className: r(c.header, e)
+	});
+}
+function w({ level: e = 2, size: t = "2xl", id: n, className: a, ...o }) {
+	let l = s("Modal.Title"), u = n ?? l.defaultTitleId, { registerTitle: d } = l;
+	return h(() => d(u), [d, u]), /* @__PURE__ */ y(i, {
+		...o,
+		id: u,
+		level: e,
+		size: t,
+		weight: "black",
+		className: r(c.title, a)
+	});
+}
+function T({ id: e, className: t, ...n }) {
+	let i = s("Modal.Description"), o = e ?? i.defaultDescriptionId, { registerDescription: l } = i;
+	return h(() => l(o), [l, o]), /* @__PURE__ */ y(a, {
+		...n,
+		id: o,
+		tone: "muted",
+		size: "md",
+		className: r(c.description, t)
+	});
+}
+function E({ className: e, ref: t, scrollRegionLabel: i, ...a }) {
+	let o = s("Modal.Body"), [l, d] = u(o.scrollBehavior === "inside"), f = g(() => n(t, l), [t, l]), p = d ? {
+		tabIndex: 0,
+		role: "region",
+		"aria-label": i,
+		"aria-labelledby": i ? void 0 : o.titleId ?? void 0
+	} : {};
+	return /* @__PURE__ */ y("div", {
+		...p,
+		...a,
+		ref: f,
+		"data-modal-body": "",
+		className: r(c.body, e)
+	});
+}
+function D({ className: e, ...t }) {
+	return /* @__PURE__ */ y("div", {
+		...t,
+		"data-modal-footer": "",
+		className: r(c.footer, e)
+	});
+}
+var O = Object.assign(b, {
+	Trigger: x,
+	Content: l,
+	Header: C,
+	Title: w,
+	Description: T,
+	Body: E,
+	Footer: D,
+	Close: S
+});
+//#endregion
+export { O as Modal, E as ModalBody, S as ModalClose, l as ModalContent, T as ModalDescription, D as ModalFooter, C as ModalHeader, w as ModalTitle, x as ModalTrigger };

package/dist/components/overlays/Modal/Modal.module.css.cjs.js

@@ -0,0 +1 @@
+var e=`_root_8lyks_39`,t=`_overlay_8lyks_55`,n=`_overlayIn_8lyks_1`,r=`_overlayOut_8lyks_1`,i=`_positioner_8lyks_97`,a=`_scrollInside_8lyks_121`,o=`_scrollOutside_8lyks_129`,s=`_positionerFull_8lyks_137`,c=`_placementCenter_8lyks_147`,l=`_placementTop_8lyks_149`,u=`_content_8lyks_161`,d=`_contentInSheet_8lyks_1`,f=`_contentOutSheet_8lyks_1`,p=`_sizeSm_8lyks_233`,m=`_sizeMd_8lyks_235`,h=`_sizeLg_8lyks_237`,g=`_sizeXl_8lyks_239`,_=`_sizeFull_8lyks_247`,v=`_inner_8lyks_269`,y=`_closeButton_8lyks_287`,b=`_header_8lyks_305`,x=`_hasClose_8lyks_319`,S=`_title_8lyks_327`,C=`_description_8lyks_343`,w=`_body_8lyks_355`,T=`_footer_8lyks_421`,E=`_confirmIcon_8lyks_449`,D=`_confirmIconDanger_8lyks_473`,O=`_contentIn_8lyks_1`,k=`_contentOut_8lyks_1`,A=`_mobileCard_8lyks_627`,j={root:e,overlay:t,overlayIn:n,overlayOut:r,positioner:i,scrollInside:a,scrollOutside:o,positionerFull:s,placementCenter:c,placementTop:l,content:u,contentInSheet:d,contentOutSheet:f,sizeSm:p,sizeMd:m,sizeLg:h,sizeXl:g,sizeFull:_,inner:v,closeButton:y,header:b,hasClose:x,title:S,description:C,body:w,footer:T,confirmIcon:E,confirmIconDanger:D,contentIn:O,contentOut:k,mobileCard:A};exports.body=w,exports.closeButton=y,exports.confirmIcon=E,exports.confirmIconDanger=D,exports.content=u,exports.contentIn=O,exports.contentInSheet=d,exports.contentOut=k,exports.contentOutSheet=f,exports.default=j,exports.description=C,exports.footer=T,exports.hasClose=x,exports.header=b,exports.inner=v,exports.mobileCard=A,exports.overlay=t,exports.overlayIn=n,exports.overlayOut=r,exports.placementCenter=c,exports.placementTop=l,exports.positioner=i,exports.positionerFull=s,exports.root=e,exports.scrollInside=a,exports.scrollOutside=o,exports.sizeFull=_,exports.sizeLg=h,exports.sizeMd=m,exports.sizeSm=p,exports.sizeXl=g,exports.title=S;