@skiddph/prui 0.7.0 → 0.8.0

package/dist/core/dropdown.js

@@ -1,89 +1,174 @@
-import { jsxs as p, jsx as a } from "react/jsx-runtime";
-import * as l from "react";
-import { cn as i } from "./cn.js";
-const k = ({
-  items: f,
+import { jsxs as I, jsx as p } from "react/jsx-runtime";
+import * as o from "react";
+import { cn as x } from "./cn.js";
+import { useOverlayStack as P, useEscapeKey as _ } from "./overlay.js";
+import { typeaheadIndex as $, endIndex as q, homeIndex as B, moveIndex as R } from "./list-nav.js";
+const F = "[role='menuitem'], [role='menuitemcheckbox'], [role='menuitemradio']", H = o.forwardRef(function({
+  items: N,
   trigger: m,
-  children: v,
-  open: u,
-  defaultOpen: b = !1,
-  onOpenChange: d,
-  align: y = "start",
-  className: w
-}) => {
-  const [x, g] = l.useState(b), c = u !== void 0, n = c ? u : x, s = l.useRef(null), o = (e) => {
-    c || g(e), d == null || d(e);
-  };
-  return l.useEffect(() => {
-    if (!n) return;
-    const e = (r) => {
-      s.current && !s.current.contains(r.target) && o(!1);
-    }, t = (r) => {
-      r.key === "Escape" && o(!1);
+  children: A,
+  open: h,
+  defaultOpen: K = !1,
+  onOpenChange: b,
+  align: C = "start",
+  className: S
+}, i) {
+  const [j, M] = o.useState(K), D = h !== void 0, r = D ? h : j, v = o.useRef(null), c = o.useRef(null), y = o.useRef(null), [d, w] = o.useState(-1), E = o.useRef({ buffer: "", at: 0 }), s = (e) => {
+    var n, t;
+    if (D || M(e), b == null || b(e), !e) {
+      w(-1), E.current = { buffer: "", at: 0 };
+      const a = document.activeElement;
+      a && ((n = c.current) != null && n.contains(a)) && ((t = y.current) == null || t.focus());
+    }
+  }, { setElement: T, isTop: L } = P(r);
+  _(r, L, () => {
+    s(!1);
+  }), o.useEffect(() => {
+    if (!r) return;
+    const e = (n) => {
+      v.current && !v.current.contains(n.target) && s(!1);
     };
-    return document.addEventListener("mousedown", e), document.addEventListener("keydown", t), () => {
-      document.removeEventListener("mousedown", e), document.removeEventListener("keydown", t);
+    return document.addEventListener("mousedown", e), () => document.removeEventListener("mousedown", e);
+  });
+  const f = o.useCallback(() => {
+    const e = c.current;
+    return e ? Array.from(e.querySelectorAll(F)) : [];
+  }, []), u = (e) => {
+    var t;
+    w(e), (t = f()[e]) == null || t.focus();
+  };
+  o.useEffect(() => {
+    var t;
+    if (!r) return;
+    const e = f(), n = e.findIndex((a) => !a.disabled);
+    n >= 0 ? (w(n), (t = e[n]) == null || t.focus()) : c.current && c.current.focus();
+  }, [r, f]);
+  const U = (e) => {
+    const n = f(), t = (a) => {
+      var l;
+      return !((l = n[a]) != null && l.disabled);
     };
-  }), /* @__PURE__ */ p("div", { ref: s, className: i("prui-dropdown relative inline-block", w), "data-state": n ? "open" : "closed", children: [
-    /* @__PURE__ */ a(
-      "div",
+    switch (e.key) {
+      case "ArrowDown":
+        e.preventDefault(), u(R(d, 1, n.length, { enabled: t }));
+        break;
+      case "ArrowUp":
+        e.preventDefault(), u(R(d, -1, n.length, { enabled: t }));
+        break;
+      case "Home":
+        e.preventDefault(), u(B(n.length, t));
+        break;
+      case "End":
+        e.preventDefault(), u(q(n.length, t));
+        break;
+      case "Tab":
+        s(!1);
+        break;
+      case "Enter":
+      case " ":
+        break;
+      default:
+        if (e.key.length === 1) {
+          const a = () => n.map((z) => z.textContent ?? ""), { index: l } = $(a, E.current, e.key, d);
+          l >= 0 && l !== d && (e.preventDefault(), u(l));
+        }
+    }
+  }, g = () => {
+    s(!0);
+  };
+  let k;
+  if (o.isValidElement(m)) {
+    const e = m;
+    k = o.cloneElement(e, {
+      ref: (n) => {
+        y.current = n;
+        const t = e.props.ref;
+        typeof t == "function" ? t(n) : t && typeof t == "object" && (t.current = n);
+      },
+      "aria-haspopup": "menu",
+      "aria-expanded": r,
+      onClick: (n) => {
+        const t = e.props.onClick;
+        t == null || t(n), n.defaultPrevented || s(!r);
+      },
+      onKeyDown: (n) => {
+        const t = e.props.onKeyDown;
+        t == null || t(n), !n.defaultPrevented && (n.key === "ArrowDown" || n.key === "Enter" || n.key === " ") && (r || (n.preventDefault(), g()));
+      }
+    });
+  } else
+    k = /* @__PURE__ */ p(
+      "button",
       {
-        role: "button",
-        tabIndex: 0,
+        type: "button",
+        ref: (e) => {
+          y.current = e;
+        },
         "aria-haspopup": "menu",
-        "aria-expanded": n,
-        onClick: () => o(!n),
+        "aria-expanded": r,
+        onClick: () => s(!r),
         onKeyDown: (e) => {
-          (e.key === "Enter" || e.key === " ") && (e.preventDefault(), o(!n));
+          (e.key === "ArrowDown" || e.key === "Enter" || e.key === " ") && !r && (e.preventDefault(), g());
         },
         children: m
       }
-    ),
-    n ? /* @__PURE__ */ a(
+    );
+  return /* @__PURE__ */ I("div", { ref: (e) => {
+    v.current = e, typeof i == "function" ? i(e) : i && (i.current = e);
+  }, className: x("prui-dropdown relative inline-block", S), "data-state": r ? "open" : "closed", children: [
+    k,
+    r ? /* @__PURE__ */ p(
       "div",
       {
+        ref: (e) => {
+          c.current = e, T((e == null ? void 0 : e.parentElement) ?? null);
+        },
         role: "menu",
-        className: i(
-          "prui-dropdown-menu absolute z-50 mt-1 min-w-40 rounded-[var(--prui-radius)] border border-[var(--prui-line)]",
-          "bg-[var(--prui-surface)] p-1 shadow-lg",
-          y === "end" ? "right-0" : "left-0"
+        tabIndex: -1,
+        onKeyDown: U,
+        className: x(
+          "prui-dropdown-menu absolute z-[var(--prui-z-overlay)] mt-1 min-w-40 rounded-[var(--prui-radius)] border border-[var(--prui-line)]",
+          "bg-[var(--prui-surface)] p-1 shadow-[var(--prui-shadow-md)] outline-none",
+          C === "end" ? "right-0" : "left-0"
         ),
-        children: v ?? (f ?? []).map((e, t) => /* @__PURE__ */ p(l.Fragment, { children: [
-          e.separatorBefore ? /* @__PURE__ */ a("div", { className: "my-1 h-px bg-[var(--prui-line)]" }) : null,
-          /* @__PURE__ */ a(
+        children: A ?? (N ?? []).map((e, n) => /* @__PURE__ */ I(o.Fragment, { children: [
+          e.separatorBefore ? /* @__PURE__ */ p("div", { className: "my-1 h-px bg-[var(--prui-line)]" }) : null,
+          /* @__PURE__ */ p(
             "button",
             {
               type: "button",
               role: "menuitem",
+              tabIndex: -1,
               disabled: e.disabled,
               onClick: () => {
-                var r;
-                e.disabled || (o(!1), (r = e.onSelect) == null || r.call(e));
+                var t;
+                e.disabled || (s(!1), (t = e.onSelect) == null || t.call(e));
               },
-              className: i(
+              className: x(
                 "flex w-full items-center rounded-[calc(var(--prui-radius)-1px)] px-2.5 py-1.5 text-left text-sm",
-                "hover:bg-[var(--prui-raise)] cursor-pointer disabled:opacity-50 disabled:pointer-events-none",
+                "hover:bg-[var(--prui-raise)] focus-visible:bg-[var(--prui-raise)] outline-none cursor-pointer disabled:opacity-50 disabled:pointer-events-none",
                 e.danger ? "text-[var(--prui-danger)]" : "text-[var(--prui-fg)]"
               ),
               children: e.label
             }
           )
-        ] }, `${e.label}-${t}`))
+        ] }, `${e.label}-${n}`))
       }
     ) : null
   ] });
-};
-k.displayName = "Dropdown";
-const E = {
+});
+H.displayName = "Dropdown";
+const Q = {
   name: "Dropdown",
   props: [
     { name: "items", type: "DropdownItem[]", default: "[]", control: "object" },
     { name: "trigger", type: "ReactNode", default: null, control: "none" },
     { name: "align", type: "'start' | 'end'", default: "'start'", control: "select", options: ["start", "end"] },
-    { name: "onOpenChange", type: "(open: boolean) => void", default: null, control: "none" }
+    { name: "onOpenChange", type: "(open: boolean) => void", default: null, control: "none" },
+    { name: "open", type: "boolean", default: "undefined", control: "boolean" }
   ]
 };
 export {
-  k as Dropdown,
-  E as dropdownPropsMeta
+  H as Dropdown,
+  Q as dropdownPropsMeta
 };

package/dist/core/file-upload.d.ts

@@ -0,0 +1,28 @@
+import { PropsMeta } from './props-meta';
+import * as React from "react";
+/**
+ * FileUpload: an accessible dropzone + file picker. The dropzone is a real
+ * button wrapping a visually-hidden input (keyboard + screen reader
+ * native); drag events highlight the zone. Files render as a removable
+ * list. Accept/multiple mirror the native input attributes.
+ */
+export interface FileUploadProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onError"> {
+    /** Accepted file types (native input accept syntax). */
+    accept?: string;
+    /** Allow multiple files. Default true. */
+    multiple?: boolean;
+    /** Validate/reject files; return an error message string or null. */
+    validate?: (file: File) => string | null;
+    onFiles?: (files: File[]) => void;
+    /** Control the visible file list externally. */
+    files?: File[];
+    /** Max file size in bytes per file. */
+    maxSize?: number;
+    /** Primary dropzone copy. */
+    hint?: React.ReactNode;
+    disabled?: boolean;
+    /** Hide the selected-files list (caller renders their own). */
+    hideList?: boolean;
+}
+export declare const FileUpload: React.ForwardRefExoticComponent<FileUploadProps & React.RefAttributes<HTMLInputElement>>;
+export declare const fileUploadPropsMeta: PropsMeta;

package/dist/core/file-upload.js

@@ -0,0 +1,111 @@
+import { jsxs as h, jsx as t } from "react/jsx-runtime";
+import * as i from "react";
+import { UploadCloud as M, File as S, X as T } from "lucide-react";
+import { cn as k } from "./cn.js";
+import { usePruiI18n as z } from "../i18n.js";
+function C(n) {
+  return n < 1024 ? `${n} B` : n < 1024 * 1024 ? `${(n / 1024).toFixed(1)} KB` : `${(n / 1024 / 1024).toFixed(1)} MB`;
+}
+const K = i.forwardRef(function({ accept: F, multiple: v = !0, validate: p, onFiles: o, files: b, maxSize: f, hint: R, disabled: l, hideList: B, className: j, ...A }, s) {
+  const { t: y } = z(), [E, N] = i.useState([]), [$, m] = i.useState(!1), [g, I] = i.useState([]), x = b !== void 0, u = x ? b : E, w = i.useRef(null), D = (e) => {
+    if (l) return;
+    const r = [], a = [];
+    for (const d of Array.from(e)) {
+      const U = f != null && d.size > f ? `${d.name} is larger than ${C(f)}.` : (p == null ? void 0 : p(d)) ?? null;
+      U ? r.push(U) : a.push(d);
+    }
+    I(r);
+    const c = v ? [...u, ...a] : a.slice(-1);
+    x || N(c), o == null || o(c);
+  }, L = (e) => {
+    const r = u.filter((a, c) => c !== e);
+    x || N(r), o == null || o(r);
+  };
+  return /* @__PURE__ */ h("div", { className: k("prui-file-upload flex flex-col gap-2", j), ...A, children: [
+    /* @__PURE__ */ h(
+      "button",
+      {
+        type: "button",
+        disabled: l,
+        "aria-describedby": g.length ? "prui-file-upload-errors" : void 0,
+        onClick: () => {
+          var e;
+          return (e = w.current) == null ? void 0 : e.click();
+        },
+        onDragOver: (e) => {
+          e.preventDefault(), l || m(!0);
+        },
+        onDragLeave: () => m(!1),
+        onDrop: (e) => {
+          var r, a;
+          e.preventDefault(), m(!1), (a = (r = e.dataTransfer) == null ? void 0 : r.files) != null && a.length && D(e.dataTransfer.files);
+        },
+        "data-dragging": $ || void 0,
+        "data-disabled": l || void 0,
+        className: k(
+          "flex cursor-pointer flex-col items-center justify-center gap-2 rounded-[var(--prui-radius)] border border-dashed p-8 text-sm",
+          "transition-colors outline-none focus-visible:ring-2 focus-visible:ring-[var(--prui-brand)]",
+          $ ? "border-[var(--prui-brand)] bg-[var(--prui-brand)]/10 text-[var(--prui-brand)]" : "border-[var(--prui-line)] bg-[var(--prui-background)] text-[var(--prui-dim)] hover:border-[var(--prui-dim)]",
+          l && "opacity-50 cursor-not-allowed"
+        ),
+        children: [
+          /* @__PURE__ */ t(M, { className: "h-6 w-6", "aria-hidden": !0 }),
+          /* @__PURE__ */ t("span", { children: R ?? y.dropFiles })
+        ]
+      }
+    ),
+    /* @__PURE__ */ t(
+      "input",
+      {
+        ref: (e) => {
+          w.current = e, typeof s == "function" ? s(e) : s && (s.current = e);
+        },
+        type: "file",
+        accept: F,
+        multiple: v,
+        disabled: l,
+        className: "sr-only",
+        tabIndex: -1,
+        "aria-hidden": !0,
+        onChange: (e) => {
+          var r;
+          (r = e.target.files) != null && r.length && D(e.target.files), e.target.value = "";
+        }
+      }
+    ),
+    g.length > 0 ? /* @__PURE__ */ t("div", { id: "prui-file-upload-errors", role: "alert", className: "flex flex-col gap-1 text-xs text-[var(--prui-danger)]", children: g.map((e, r) => /* @__PURE__ */ t("span", { children: e }, r)) }) : null,
+    !B && u.length > 0 ? /* @__PURE__ */ t("ul", { className: "flex flex-col gap-1", "data-testid": "file-upload-list", children: u.map((e, r) => /* @__PURE__ */ h("li", { className: "flex items-center gap-2 rounded-[var(--prui-radius-1)] bg-[var(--prui-raise)] px-3 py-2 text-sm text-[var(--prui-fg)]", children: [
+      /* @__PURE__ */ t(S, { className: "h-4 w-4 shrink-0 text-[var(--prui-dim)]", "aria-hidden": !0 }),
+      /* @__PURE__ */ t("span", { className: "min-w-0 flex-1 truncate", children: e.name }),
+      /* @__PURE__ */ t("span", { className: "text-xs text-[var(--prui-dim)]", children: C(e.size) }),
+      /* @__PURE__ */ t(
+        "button",
+        {
+          type: "button",
+          "aria-label": `${y.removeFile}: ${e.name}`,
+          onClick: () => L(r),
+          className: "rounded-[var(--prui-radius-1)] p-1 text-[var(--prui-dim)] transition-colors hover:text-[var(--prui-danger)] cursor-pointer",
+          children: /* @__PURE__ */ t(T, { className: "h-3.5 w-3.5", "aria-hidden": !0 })
+        }
+      )
+    ] }, `${e.name}-${r}`)) }) : null
+  ] });
+});
+K.displayName = "FileUpload";
+const q = {
+  name: "FileUpload",
+  props: [
+    { name: "accept", type: "string (input accept)", default: "undefined", control: "text" },
+    { name: "multiple", type: "boolean", default: "true", control: "boolean" },
+    { name: "onFiles", type: "(files: File[]) => void", default: null, control: "none" },
+    { name: "files", type: "File[]", default: "internal state", control: "none" },
+    { name: "maxSize", type: "number (bytes)", default: "undefined", control: "number" },
+    { name: "validate", type: "(file: File) => string | null", default: null, control: "none" },
+    { name: "hint", type: "ReactNode", default: "'Drag files here or click to browse'", control: "text" },
+    { name: "hideList", type: "boolean", default: "false", control: "boolean" }
+  ]
+};
+export {
+  K as FileUpload,
+  q as fileUploadPropsMeta
+};

package/dist/core/index.d.ts

@@ -2,6 +2,8 @@
 export { cn } from './cn';
 export { resolveSurface, withSurface, type SurfaceProps, type SurfaceRadius, type SurfaceTexture, type SurfaceElevation } from './surface';
 export type { PropsMeta, PropMeta, PropControl } from './props-meta';
+export { Portal, useReducedMotion, useFocusTrap, useEscapeKey, useScrollLock, useInertBackground, useOverlay, useOverlayStack, pushOverlay, removeOverlay, isTopOverlay, overlayCount, getFocusable, overlayPropsMeta, } from './overlay';
+export { moveIndex, homeIndex, endIndex, typeaheadIndex } from './list-nav';
 export { Button, buttonPropsMeta, type ButtonProps, type ButtonVariant, type ButtonSize, } from './button';
 export { Input, inputPropsMeta, Textarea, textareaPropsMeta, type InputProps, type TextareaProps, } from './input';
 export { Label, labelPropsMeta, Separator, separatorPropsMeta, type LabelProps, type SeparatorProps } from './label';
@@ -13,3 +15,22 @@ export { Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription, Di
 export { Dropdown, dropdownPropsMeta, type DropdownProps, type DropdownItem, } from './dropdown';
 export { ScrollArea, scrollAreaPropsMeta, type ScrollAreaProps } from './scroll-area';
 export { Modal, confirmModal, modalPropsMeta, confirmModalPropsMeta, type ModalProps, type ModalSize, type ConfirmModalOptions, type ConfirmModalType, } from './modal';
+export { computePosition, useAnchoredPosition, type AnchorSide, type AnchorAlign, type AnchoredPosition } from './anchor';
+export { Spinner, spinnerPropsMeta, type SpinnerProps, type SpinnerSize } from './spinner';
+export { Skeleton, skeletonPropsMeta, type SkeletonProps } from './skeleton';
+export { Alert, alertPropsMeta, type AlertProps, type AlertVariant } from './alert';
+export { Progress, progressPropsMeta, type ProgressProps } from './progress';
+export { Toaster, toast, dismissAllToasts, toasterPropsMeta, toastPropsMeta, type ToasterProps, type ToastOptions, type ToastVariant, type ToastHandle } from './toast';
+export { Tooltip, tooltipPropsMeta, type TooltipProps } from './tooltip';
+export { Popover, popoverPropsMeta, type PopoverProps } from './popover';
+export { Drawer, Sheet, drawerPropsMeta, sheetPropsMeta, type DrawerProps, type DrawerSide } from './drawer';
+export { Checkbox, checkboxPropsMeta, type CheckboxProps } from './checkbox';
+export { RadioGroup, Radio, radioGroupPropsMeta, type RadioGroupProps, type RadioProps } from './radio';
+export { Combobox, comboboxPropsMeta, type ComboboxProps, type ComboboxOption } from './combobox';
+export { Accordion, AccordionItem, accordionPropsMeta, type AccordionProps, type AccordionItemProps } from './accordion';
+export { Breadcrumb, BreadcrumbItem, BreadcrumbEllipsis, breadcrumbPropsMeta, type BreadcrumbProps, type BreadcrumbItemProps } from './breadcrumb';
+export { TreeView, treeViewPropsMeta, type TreeViewProps, type TreeViewItem } from './tree-view';
+export { Timeline, timelinePropsMeta, type TimelineProps, type TimelineItemData, type TimelineVariant } from './timeline';
+export { Calendar, calendarPropsMeta, toDateKey, fromDateKey, type CalendarProps } from './calendar';
+export { DatePicker, DateRangePicker, datePickerPropsMeta, dateRangePickerPropsMeta, type DatePickerProps, type DateRangePickerProps, type DateRange } from './date-picker';
+export { FileUpload, fileUploadPropsMeta, type FileUploadProps } from './file-upload';

package/dist/core/list-nav.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared list/menus keyboard navigation helpers.
+ *
+ * Pure index math plus a typeahead buffer, reused by Dropdown, Select,
+ * CommandPalette, the nav rail flyout, Combobox and any roving-tabIndex
+ * list. No DOM assumptions: callers own focus and rendering.
+ */
+/** Next index for ArrowUp/ArrowDown (and Left/Right in horizontal lists). */
+export declare function moveIndex(current: number, delta: 1 | -1, length: number, opts?: {
+    loop?: boolean;
+    enabled?: (index: number) => boolean;
+}): number;
+/** Home / End clamps. */
+export declare function homeIndex(length: number, enabled?: (i: number) => boolean): number;
+export declare function endIndex(length: number, enabled?: (i: number) => boolean): number;
+/**
+ * Typeahead: given the item labels, find the next item whose label starts
+ * with the accumulated prefix (searching forward from the active item,
+ * wrapping). Case-insensitive; resets after `resetMs` of inactivity.
+ */
+export declare function typeaheadIndex(labels: () => string[], state: {
+    buffer: string;
+    at: number;
+}, key: string, activeIndex: number, resetMs?: number): {
+    index: number;
+    buffer: string;
+};

package/dist/core/list-nav.js

@@ -0,0 +1,51 @@
+function m(n, r, t, f = {}) {
+  if (t <= 0) return -1;
+  const { loop: o = !0, enabled: u } = f;
+  if (n < 0)
+    return r > 0 ? h(0, 1, t, u) : h(t - 1, -1, t, u);
+  let i = n;
+  for (let e = 0; e < t; e++) {
+    if (i = i + r, i >= t || i < 0) {
+      if (!o) return n;
+      i = i < 0 ? t - 1 : 0;
+    }
+    if (!u || u(i)) return i;
+  }
+  return n;
+}
+function h(n, r, t, f) {
+  for (let o = n; o >= 0 && o < t; o += r)
+    if (!f || f(o)) return o;
+  return -1;
+}
+function p(n, r) {
+  return h(0, 1, n, r);
+}
+function w(n, r) {
+  return h(n - 1, -1, n, r);
+}
+function a(n, r, t, f, o = 500) {
+  var x, b;
+  if (t.length !== 1) return { index: f, buffer: r.buffer };
+  const u = Date.now(), e = u - r.at < o ? r.buffer + t.toLowerCase() : t.toLowerCase();
+  r.buffer = e, r.at = u;
+  const c = n().map((s) => s.trim().toLowerCase());
+  for (let s = 1; s <= c.length; s++) {
+    const d = (f + s) % c.length;
+    if ((x = c[d]) != null && x.startsWith(e)) return { index: d, buffer: e };
+  }
+  if (e.length > 1) {
+    const s = e[e.length - 1];
+    for (let d = 1; d <= c.length; d++) {
+      const l = (f + d) % c.length;
+      if ((b = c[l]) != null && b.startsWith(s)) return { index: l, buffer: e };
+    }
+  }
+  return { index: f, buffer: e };
+}
+export {
+  w as endIndex,
+  p as homeIndex,
+  m as moveIndex,
+  a as typeaheadIndex
+};

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;