@skiddph/prui 0.7.0 → 0.9.0

package/dist/core/modal.d.ts

@@ -7,6 +7,12 @@ import * as React from "react";
  * false = shake feedback, and an imperative confirmModal() that renders a
  * typed confirmation dialog imperatively and resolves a Promise<boolean>.
  * Restyled onto PRUI tokens instead of hardcoded hex.
+ *
+ * Built on the shared overlay infrastructure (core/overlay): portaled to the
+ * body, focus-trapped with initial focus and focus restoration, Escape is
+ * answered only by the topmost overlay, and the background is aria-hidden +
+ * inert where supported while open. prefers-reduced-motion disables the
+ * shake/scale/fade choreography.
  */
 export type ModalSize = "xs" | "sm" | "md" | "lg" | "xl";
 export interface ModalProps {
@@ -32,11 +38,12 @@ export interface ModalProps {
     /** Accessible label. */
     ariaLabel?: string;
     className?: string;
+    /** Inline style applied to the modal content element. */
+    style?: React.CSSProperties;
+    /** Initial focus target: the first focusable, the dialog itself, a specific element, or none. */
+    initialFocus?: React.RefObject<HTMLElement | null> | "first" | "container" | false;
 }
-export declare function Modal({ open, onClose, children, disableDefaultClose, closeOnOverlayClick, size, xs, sm, md, lg, xl, maxWidth, padding, noPadding, showCloseButton, ariaLabel, className, }: ModalProps): React.JSX.Element | null;
-export declare namespace Modal {
-    var displayName: string;
-}
+export declare const Modal: React.ForwardRefExoticComponent<ModalProps & React.RefAttributes<HTMLDivElement>>;
 export type ConfirmModalType = "success" | "warning" | "danger" | "error" | "info";
 export interface ConfirmModalOptions {
     title: string;
@@ -49,7 +56,9 @@ export interface ConfirmModalOptions {
 /**
  * confirmModal({ title, message, type }) => Promise<boolean>
  * Renders the confirmation modal imperatively; resolves true on confirm,
- * false on cancel/Escape/overlay-shake close. Focus-trapped like the original.
+ * false on cancel/Escape/overlay-shake close. Focus-trapped via the shared
+ * overlay infrastructure: initial focus lands on the confirm action and
+ * focus returns to the invoker on close.
  */
 export declare function confirmModal(options: ConfirmModalOptions): Promise<boolean>;
 export declare const modalPropsMeta: PropsMeta;

package/dist/core/modal.js

@@ -1,155 +1,170 @@
-import { jsx as e, jsxs as d } from "react/jsx-runtime";
-import * as r from "react";
-import { createRoot as I } from "react-dom/client";
-import { X as K } from "lucide-react";
-import { cn as Y } from "./cn.js";
-const P = {
+import { jsx as e, jsxs as a } from "react/jsx-runtime";
+import * as o from "react";
+import { createRoot as X } from "react-dom/client";
+import { X as q } from "lucide-react";
+import { cn as G } from "./cn.js";
+import { useReducedMotion as B, useOverlay as F, Portal as H } from "./overlay.js";
+import { getPruiDictionary as J } from "../i18n.js";
+const O = {
   xs: { width: "320px", minWidth: "280px" },
   sm: { width: "448px", minWidth: "320px" },
   md: { width: "640px", minWidth: "384px" },
   lg: { width: "896px", minWidth: "512px" },
   xl: { width: "1152px", minWidth: "640px" }
-}, D = {
+}, K = {
   xs: "24px 32px",
   sm: "24px 32px",
   md: "32px 40px",
   lg: "32px 40px",
   xl: "40px 48px"
-};
-function O({
-  open: n,
-  onClose: o,
+}, Q = o.forwardRef(function({
+  open: r,
+  onClose: n,
   children: W,
-  disableDefaultClose: u = !1,
-  closeOnOverlayClick: L = !0,
+  disableDefaultClose: p = !1,
+  closeOnOverlayClick: M = !0,
   size: y,
-  xs: T,
-  sm: S,
-  md: z,
-  lg: f,
-  xl: v,
-  maxWidth: E,
-  padding: N,
-  noPadding: h = !1,
-  showCloseButton: M = !0,
-  ariaLabel: x,
-  className: k
-}) {
-  const l = y ?? (T ? "xs" : S ? "sm" : f ? "lg" : v ? "xl" : "md"), [R, g] = r.useState(n), [c, m] = r.useState(!1), [w, i] = r.useState(!1), C = r.useRef(null);
-  if (r.useEffect(() => {
-    if (n) {
-      g(!0);
+  xs: S,
+  sm: T,
+  md: N,
+  lg: m,
+  xl: b,
+  maxWidth: R,
+  padding: z,
+  noPadding: w = !1,
+  showCloseButton: k = !0,
+  ariaLabel: f,
+  className: h,
+  style: s,
+  initialFocus: P = "first"
+}, l) {
+  const v = y ?? (S ? "xs" : T ? "sm" : m ? "lg" : b ? "xl" : "md"), [x, i] = o.useState(r), [d, u] = o.useState(!1), [g, L] = o.useState(!1), A = o.useRef(null), C = B(), E = () => {
+    C || (L(!0), setTimeout(() => L(!1), 500));
+  };
+  o.useEffect(() => {
+    if (r) {
+      if (i(!0), C) {
+        u(!0);
+        return;
+      }
       const t = setTimeout(() => {
-        m(!0), document.body.classList.add("modal-open");
+        u(!0);
       }, 10);
       return () => clearTimeout(t);
     }
-    m(!1), document.body.classList.remove("modal-open");
-  }, [n]), r.useEffect(() => () => document.body.classList.remove("modal-open"), []), r.useEffect(() => {
-    if (!n) return;
-    const t = (p) => {
-      p.key === "Escape" && (u ? (i(!0), setTimeout(() => i(!1), 500)) : o());
-    };
-    return document.addEventListener("keydown", t), () => document.removeEventListener("keydown", t);
-  }, [n, u, o]), !R && !c) return null;
-  const a = (t) => {
+    u(!1), C && i(!1);
+  }, [r, C]);
+  const { ref: V } = F({
+    open: r,
+    onEscape: () => {
+      if (p)
+        return E(), !1;
+      n();
+    },
+    initialFocus: P
+  });
+  if (!x && !d) return null;
+  const I = (t) => {
     if (t.target === t.currentTarget) {
-      if (u || !L) {
-        i(!0), setTimeout(() => i(!1), 500);
+      if (p || !M) {
+        E();
         return;
       }
-      o();
+      n();
     }
-  }, s = P[l], b = h ? "0" : N ?? D[l];
-  return /* @__PURE__ */ e(
+  }, j = O[v], D = w ? "0" : z ?? K[v];
+  return /* @__PURE__ */ e(H, { children: /* @__PURE__ */ e("div", { ref: V, children: /* @__PURE__ */ e(
     "div",
     {
-      className: "prui-modal-overlay fixed inset-0 z-[10000] flex justify-center overflow-y-auto p-4",
+      className: "prui-modal-overlay fixed inset-0 z-[var(--prui-z-modal)] flex justify-center overflow-y-auto p-4",
       style: {
         alignItems: "flex-start",
         paddingTop: "10vh",
-        backgroundColor: "rgba(0, 0, 0, 0.55)",
+        backgroundColor: "var(--prui-scrim)",
         backdropFilter: "blur(4px)",
-        opacity: c ? 1 : 0,
-        transition: "opacity 0.3s cubic-bezier(0.25, 0.1, 0.25, 1)"
+        opacity: d ? 1 : 0,
+        transition: "opacity var(--prui-duration-slow) var(--prui-ease-out)"
       },
-      onClick: a,
+      onClick: I,
       onMouseDown: (t) => {
-        t.target === t.currentTarget && a(t);
+        t.target === t.currentTarget && I(t);
       },
-      children: /* @__PURE__ */ d(
+      children: /* @__PURE__ */ a(
         "div",
         {
-          ref: C,
+          ref: (t) => {
+            A.current = t, typeof l == "function" ? l(t) : l && (l.current = t);
+          },
           role: "dialog",
           "aria-modal": "true",
-          "aria-label": x,
-          className: Y(
+          "aria-label": f,
+          className: G(
             "prui-modal-content relative h-fit m-auto w-full",
-            w && "prui-modal-shake",
-            k
+            g && "prui-modal-shake",
+            h
           ),
           style: {
-            width: s.width,
-            minWidth: s.minWidth,
-            maxWidth: E ?? s.width,
-            padding: b,
+            width: j.width,
+            minWidth: j.minWidth,
+            maxWidth: R ?? j.width,
+            padding: D,
             backgroundColor: "var(--prui-surface)",
             border: "1px solid var(--prui-line)",
             borderRadius: "var(--prui-radius-3)",
-            boxShadow: "0 20px 25px -5px rgba(0, 0, 0, 0.4), 0 10px 10px -5px rgba(0, 0, 0, 0.2)",
+            boxShadow: "var(--prui-shadow-modal)",
             color: "var(--prui-fg)",
-            transform: c ? "scale(1) translateY(0)" : "scale(0.95) translateY(8px)",
-            opacity: c ? 1 : 0,
-            transition: "transform 0.3s cubic-bezier(0.25, 0.1, 0.25, 1), opacity 0.3s cubic-bezier(0.25, 0.1, 0.25, 1)"
+            transform: d ? "scale(1) translateY(0)" : "scale(0.95) translateY(8px)",
+            opacity: d ? 1 : 0,
+            transition: "transform var(--prui-duration-slow) var(--prui-ease-out), opacity var(--prui-duration-slow) var(--prui-ease-out)",
+            ...s
           },
           onTransitionEnd: () => {
-            n || g(!1);
+            r || i(!1);
           },
           children: [
-            M && !u ? /* @__PURE__ */ e(
+            W,
+            k && !p ? /* @__PURE__ */ e(
               "button",
               {
                 type: "button",
-                onClick: o,
+                onClick: n,
                 "aria-label": "Close modal",
                 className: "absolute right-4 top-4 flex h-10 w-10 cursor-pointer items-center justify-center rounded-[var(--prui-radius)] text-[var(--prui-dim)] transition-all hover:bg-[var(--prui-raise)] hover:text-[var(--prui-fg)]",
-                children: /* @__PURE__ */ e(K, { className: "h-4 w-4", "aria-hidden": !0 })
+                children: /* @__PURE__ */ e(q, { className: "h-4 w-4", "aria-hidden": !0 })
               }
-            ) : null,
-            W
+            ) : null
           ]
         }
       )
     }
-  );
-}
-O.displayName = "Modal";
-const B = {
+  ) }) });
+});
+Q.displayName = "Modal";
+const Y = {
   success: "var(--prui-ok)",
   warning: "var(--prui-warn)",
   danger: "var(--prui-danger)",
   error: "var(--prui-danger)",
   info: "var(--prui-brand)",
   default: "var(--prui-brand)"
-}, A = ({ type: n }) => {
-  const o = B[n ?? "default"];
-  switch (n) {
+}, U = ({ type: c }) => {
+  const r = Y[c ?? "default"];
+  switch (c) {
     case "success":
-      return /* @__PURE__ */ d("svg", { width: "24", height: "24", viewBox: "0 0 24 24", fill: "none", style: { color: o }, children: [
+      return /* @__PURE__ */ a("svg", { width: "24", height: "24", viewBox: "0 0 24 24", fill: "none", style: { color: r }, "aria-hidden": !0, children: [
         /* @__PURE__ */ e("path", { d: "M9 12l2 2 4-4", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round" }),
         /* @__PURE__ */ e("circle", { cx: "12", cy: "12", r: "9", stroke: "currentColor", strokeWidth: "2" })
       ] });
     case "warning":
-      return /* @__PURE__ */ e("svg", { width: "24", height: "24", viewBox: "0 0 24 24", fill: "none", style: { color: o }, children: /* @__PURE__ */ e("path", { d: "M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.694-.833-2.464 0L4.34 16.5c-.77.833.192 2.5 1.732 2.5z", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round" }) });
+      return /* @__PURE__ */ e("svg", { width: "24", height: "24", viewBox: "0 0 24 24", fill: "none", style: { color: r }, "aria-hidden": !0, children: /* @__PURE__ */ e("path", { d: "M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.694-.833-2.464 0L4.34 16.5c-.77.833.192 2.5 1.732 2.5z", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round" }) });
     case "danger":
     case "error":
-      return /* @__PURE__ */ d("svg", { width: "24", height: "24", viewBox: "0 0 24 24", fill: "none", style: { color: o }, children: [
+      return /* @__PURE__ */ a("svg", { width: "24", height: "24", viewBox: "0 0 24 24", fill: "none", style: { color: r }, "aria-hidden": !0, children: [
         /* @__PURE__ */ e("circle", { cx: "12", cy: "12", r: "9", stroke: "currentColor", strokeWidth: "2" }),
-        /* @__PURE__ */ e("path", { d: "M15 9l-6 6m0-6l6 6", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round" })
+        /* @__PURE__ */ e("path", { d: "M15 9l-6 6m0-6l6 6", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round" })
       ] });
     case "info":
-      return /* @__PURE__ */ d("svg", { width: "24", height: "24", viewBox: "0 0 24 24", fill: "none", style: { color: o }, children: [
+      return /* @__PURE__ */ a("svg", { width: "24", height: "24", viewBox: "0 0 24 24", fill: "none", style: { color: r }, "aria-hidden": !0, children: [
         /* @__PURE__ */ e("circle", { cx: "12", cy: "12", r: "9", stroke: "currentColor", strokeWidth: "2" }),
         /* @__PURE__ */ e("path", { d: "M12 8v4m0 4h.01", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round" })
       ] });
@@ -157,109 +172,100 @@ const B = {
       return null;
   }
 };
-function G(n) {
-  const { title: o, message: W, confirmText: u = "Confirm", cancelText: L = "Cancel", type: y, size: T = "sm" } = n, S = B[y ?? "default"];
-  return new Promise((z) => {
-    const f = document.createElement("div");
-    document.body.appendChild(f);
-    const v = I(f), E = () => {
+function oe(c) {
+  const r = J(), { title: n, message: W, confirmText: p = r.confirm, cancelText: M = r.cancel, type: y, size: S = "sm" } = c, T = Y[y ?? "default"];
+  return new Promise((N) => {
+    const m = document.createElement("div");
+    document.body.appendChild(m);
+    const b = X(m), R = () => {
       setTimeout(() => {
-        v.unmount(), f.remove();
+        b.unmount(), m.remove();
       }, 320);
-    }, N = () => {
-      const [h, M] = r.useState(!1), [x, k] = r.useState(!1), [l, R] = r.useState(!1), g = r.useRef(null), c = r.useRef(null);
-      r.useEffect(() => {
-        const i = setTimeout(() => {
-          M(!0), k(!0), document.body.classList.add("modal-open");
+    }, z = () => {
+      const [w, k] = o.useState(!1), [f, h] = o.useState(!1), [s, P] = o.useState(!1), l = o.useRef(null), v = o.useRef(null), x = B();
+      o.useEffect(() => {
+        if (x) {
+          k(!0), h(!0);
+          return;
+        }
+        const g = setTimeout(() => {
+          k(!0), h(!0);
         }, 10);
-        return () => clearTimeout(i);
-      }, []);
-      const m = (i) => {
-        R(!0), k(!1), document.body.classList.remove("modal-open"), setTimeout(() => {
-          E(), z(i);
-        }, 300);
-      };
-      if (r.useEffect(() => {
-        var C;
-        if (!h || l) return;
-        (C = c.current) == null || C.focus();
-        const i = (a) => {
-          if (l) return;
-          if (a.key === "Escape") {
-            a.preventDefault(), m(!1);
-            return;
-          }
-          if (a.key !== "Tab") return;
-          const s = [g.current, c.current].filter((j) => !!j);
-          if (!s.length) return;
-          const b = s[0], t = s[s.length - 1], p = document.activeElement;
-          !p || !s.some((j) => j === p) ? (a.preventDefault(), b.focus()) : a.shiftKey && p === b ? (a.preventDefault(), t.focus()) : !a.shiftKey && p === t && (a.preventDefault(), b.focus());
-        };
-        return document.addEventListener("keydown", i), () => document.removeEventListener("keydown", i);
-      }, [h, l]), !h) return null;
-      const w = P[T];
-      return /* @__PURE__ */ e(
+        return () => clearTimeout(g);
+      }, [x]);
+      const i = (g) => {
+        P(!0), h(!1), setTimeout(() => {
+          R(), N(g);
+        }, x ? 0 : 300);
+      }, { ref: d } = F({
+        open: w && !s,
+        onEscape: () => (s || i(!1), !1),
+        initialFocus: v
+      });
+      if (!w) return null;
+      const u = O[S];
+      return /* @__PURE__ */ e("div", { ref: d, children: /* @__PURE__ */ e(
         "div",
         {
-          className: "prui-modal-overlay fixed inset-0 z-[10001] flex justify-center overflow-y-auto p-4",
+          className: "prui-modal-overlay fixed inset-0 z-[var(--prui-z-confirm)] flex justify-center overflow-y-auto p-4",
           style: {
             alignItems: "flex-start",
             paddingTop: "12vh",
-            backgroundColor: "rgba(0, 0, 0, 0.55)",
+            backgroundColor: "var(--prui-scrim)",
             backdropFilter: "blur(4px)",
-            opacity: x ? 1 : 0,
-            transition: "opacity 0.3s cubic-bezier(0.25, 0.1, 0.25, 1)"
+            opacity: f ? 1 : 0,
+            transition: "opacity var(--prui-duration-slow) var(--prui-ease-out)"
           },
-          children: /* @__PURE__ */ d(
+          children: /* @__PURE__ */ a(
             "div",
             {
               role: "alertdialog",
               "aria-modal": "true",
-              "aria-label": o,
+              "aria-label": n,
               className: "prui-modal-content relative m-auto w-full",
               style: {
-                width: w.width,
-                minWidth: w.minWidth,
+                width: u.width,
+                minWidth: u.minWidth,
                 backgroundColor: "var(--prui-surface)",
                 border: "1px solid var(--prui-line)",
                 borderRadius: "var(--prui-radius-3)",
-                boxShadow: "0 20px 25px -5px rgba(0,0,0,0.4), 0 10px 10px -5px rgba(0,0,0,0.2)",
+                boxShadow: "var(--prui-shadow-modal)",
                 color: "var(--prui-fg)",
-                transform: x ? "scale(1) translateY(0)" : "scale(0.95) translateY(8px)",
-                opacity: x ? 1 : 0,
-                transition: "transform 0.3s cubic-bezier(0.25,0.1,0.25,1), opacity 0.3s cubic-bezier(0.25,0.1,0.25,1)"
+                transform: f ? "scale(1) translateY(0)" : "scale(0.95) translateY(8px)",
+                opacity: f ? 1 : 0,
+                transition: "transform var(--prui-duration-slow) var(--prui-ease-out), opacity var(--prui-duration-slow) var(--prui-ease-out)"
               },
               children: [
-                /* @__PURE__ */ d("div", { className: "flex items-start gap-3 p-4 pb-2", children: [
-                  /* @__PURE__ */ e(A, { type: y }),
-                  /* @__PURE__ */ d("div", { className: "min-w-0", children: [
-                    /* @__PURE__ */ e("h2", { className: "m-0 text-lg font-semibold leading-normal", style: { color: "var(--prui-fg)" }, children: o }),
+                /* @__PURE__ */ a("div", { className: "flex items-start gap-3 p-4 pb-2", children: [
+                  /* @__PURE__ */ e(U, { type: y }),
+                  /* @__PURE__ */ a("div", { className: "min-w-0", children: [
+                    /* @__PURE__ */ e("h2", { className: "m-0 text-lg font-semibold leading-normal", style: { color: "var(--prui-fg)" }, children: n }),
                     /* @__PURE__ */ e("p", { className: "mt-2 text-sm leading-normal", style: { color: "var(--prui-dim)" }, children: W })
                   ] })
                 ] }),
-                /* @__PURE__ */ d("div", { className: "flex items-center justify-end gap-3 px-4 pb-4", children: [
+                /* @__PURE__ */ a("div", { className: "flex items-center justify-end gap-3 px-4 pb-4", children: [
                   /* @__PURE__ */ e(
                     "button",
                     {
                       type: "button",
-                      ref: g,
-                      disabled: l,
-                      onClick: () => m(!1),
+                      ref: l,
+                      disabled: s,
+                      onClick: () => i(!1),
                       className: "cursor-pointer rounded-[var(--prui-radius)] border px-4 py-2 text-sm font-medium transition-all disabled:opacity-60",
                       style: { background: "transparent", borderColor: "var(--prui-line)", color: "var(--prui-fg)" },
-                      children: L
+                      children: M
                     }
                   ),
                   /* @__PURE__ */ e(
                     "button",
                     {
                       type: "button",
-                      ref: c,
-                      disabled: l,
-                      onClick: () => m(!0),
+                      ref: v,
+                      disabled: s,
+                      onClick: () => i(!0),
                       className: "cursor-pointer rounded-[var(--prui-radius)] border border-transparent px-4 py-2 text-sm font-medium text-white transition-all disabled:opacity-60",
-                      style: { backgroundColor: S },
-                      children: u
+                      style: { backgroundColor: T },
+                      children: p
                     }
                   )
                 ] })
@@ -267,12 +273,12 @@ function G(n) {
             }
           )
         }
-      );
+      ) });
     };
-    v.render(/* @__PURE__ */ e(N, {}));
+    b.render(/* @__PURE__ */ e(z, {}));
   });
 }
-const H = {
+const ae = {
   name: "Modal",
   props: [
     { name: "open", type: "boolean", default: null, control: "boolean" },
@@ -283,9 +289,10 @@ const H = {
     { name: "noPadding", type: "boolean", default: "false", control: "boolean" },
     { name: "showCloseButton", type: "boolean", default: "true", control: "boolean" },
     { name: "padding", type: "string (CSS)", default: "per-size", control: "text" },
-    { name: "maxWidth", type: "string (CSS)", default: "per-size", control: "text" }
+    { name: "maxWidth", type: "string (CSS)", default: "per-size", control: "text" },
+    { name: "initialFocus", type: 'ref | "first" | "container" | false', default: '"first"', control: "none" }
   ]
-}, J = {
+}, ie = {
   name: "confirmModal",
   props: [
     { name: "title", type: "string", default: null, control: "text" },
@@ -296,8 +303,8 @@ const H = {
   ]
 };
 export {
-  O as Modal,
-  G as confirmModal,
-  J as confirmModalPropsMeta,
-  H as modalPropsMeta
+  Q as Modal,
+  oe as confirmModal,
+  ie as confirmModalPropsMeta,
+  ae as modalPropsMeta
 };

package/dist/core/overlay.d.ts

@@ -0,0 +1,93 @@
+import { PropsMeta } from './props-meta';
+import * as React from "react";
+/**
+ * Shared overlay infrastructure.
+ *
+ * Every floating surface in PRUI (Modal, Dialog, Drawer, Sheet, Command
+ * Palette, Dropdown, Tooltip, Popover, Toast, confirmModal) builds on the
+ * primitives in this file instead of duplicating focus/escape/scroll logic:
+ *
+ * - <Portal> renders into document.body (or a custom container).
+ * - useReducedMotion() mirrors prefers-reduced-motion.
+ * - useOverlayStack() registers the overlay so only the TOPMOST one answers
+ *   Escape, and nested dialogs stack correctly.
+ * - useFocusTrap() cycles Tab/Shift+Tab inside the overlay, moves initial
+ *   focus in, and restores focus to the invoker on close.
+ * - useScrollLock() is counter-based so nested overlays cannot unlock each
+ *   other's body lock.
+ * - useInertBackground() hides the rest of the page from assistive tech
+ *   (aria-hidden + the native inert attribute where supported).
+ * - useOverlay() composes all of the above for modal surfaces.
+ */
+export declare function Portal({ children, container, }: {
+    children: React.ReactNode;
+    container?: HTMLElement | null;
+}): React.ReactPortal | null;
+/** True when the user asked the OS for reduced motion. */
+export declare function useReducedMotion(): boolean;
+/** All focusable elements inside root, in DOM order. */
+export declare function getFocusable(root: HTMLElement | null): HTMLElement[];
+/** Register an overlay; returns its stack id. */
+export declare function pushOverlay(element: HTMLElement | null): symbol;
+/** Unregister an overlay by id. */
+export declare function removeOverlay(id: symbol): void;
+/** True when `id` is the topmost registered overlay. */
+export declare function isTopOverlay(id: symbol): boolean;
+/** Number of currently open overlays (for nesting decisions). */
+export declare function overlayCount(): number;
+/**
+ * Registers/unregisters an overlay in the stack while `active`.
+ * Registration happens in effect order (= mount order = nesting order), so
+ * the last-registered open overlay is the topmost. Returns
+ * [setElement, isTop] — setElement keeps the stack entry's DOM node current
+ * for inert-background exemption.
+ */
+export declare function useOverlayStack(active: boolean): {
+    setElement: (el: HTMLElement | null) => void;
+    isTop: () => boolean;
+};
+/**
+ * Calls onEscape for Escape keydowns while active AND topmost in the overlay
+ * stack. Returning false from onEscape marks the key handled-but-blocked
+ * (e.g. the Modal shake) and stops the event from leaking to lower overlays.
+ */
+export declare function useEscapeKey(active: boolean, isTop: () => boolean, onEscape: () => boolean | void): void;
+/** Locks body scroll while active. Nest-safe: the last overlay to unlock wins. */
+export declare function useScrollLock(active: boolean): void;
+/**
+ * Hides everything outside the overlay element from assistive technology
+ * while active. Elements registered as open overlay portals (this overlay
+ * and any nested ones) stay reachable. SSR-safe no-op.
+ */
+export declare function useInertBackground(active: boolean, element: HTMLElement | null): void;
+export interface FocusTrapOptions {
+    active: boolean;
+    /** Container to trap inside. */
+    container: HTMLElement | null;
+    /** Focus target on activation: a ref, "first" focusable, or the container. */
+    initialFocus?: React.RefObject<HTMLElement | null> | "first" | "container" | false;
+    /** Return focus to the pre-open active element on deactivate. */
+    restoreFocus?: boolean;
+}
+export declare function useFocusTrap({ active, container, initialFocus, restoreFocus }: FocusTrapOptions): void;
+export interface UseOverlayOptions {
+    open: boolean;
+    /** Escape behavior; return false to block (e.g. shake). Default closes via onEscape. */
+    onEscape?: () => boolean | void;
+    /** Modal: trap focus, lock scroll, inert the background. Default true. */
+    modal?: boolean;
+    initialFocus?: React.RefObject<HTMLElement | null> | "first" | "container" | false;
+    restoreFocus?: boolean;
+}
+/**
+ * The composite hook for modal overlays: stack registration, topmost-only
+ * Escape, scroll locking, background inertness, focus trapping, initial
+ * focus and focus restoration. Returns props to spread on the portaled
+ * wrapper element.
+ */
+export declare function useOverlay({ open, onEscape, modal, initialFocus, restoreFocus, }: UseOverlayOptions): {
+    ref: (el: HTMLElement | null) => void;
+    element: HTMLElement | null;
+    top: () => boolean;
+};
+export declare const overlayPropsMeta: PropsMeta;