@para-ui/core 5.0.0-beta.12 → 5.0.0-beta.13

package/es/Modal/index.d.ts

@@ -1,12 +1,33 @@
 import { default as React, ReactNode } from 'react';
 import { ButtonProps } from '../Button';
 import { Confirm, ConfirmObject } from './Confirm';
+import { ModalDismissReason } from './interface';
 type ModalSize = 'sm' | 'md' | 'lg' | 'auto' | 'fullScreen';
+/**
+ * Modal onClose 关闭路径标识(R6 §B3 阶段 1 引入,见 BREAKING-CHANGES §B3 + discussions/Modal-unified-onClose.md)
+ * - 'cancel' = 取消按钮
+ * - 'ok' = 确定按钮
+ * - 'esc' = 键盘 Escape 关闭(若 keyboard 启用)
+ * - 'mask' = 蒙层点击关闭(若 maskClosable 启用)
+ * - 'x' = 右上角 X 按钮
+ */
+export type ModalCloseReason = 'cancel' | 'ok' | 'esc' | 'mask' | 'x';
 export interface ModalProps {
-    /** 对话框是否可见 */
+    /**
+     * @deprecated v5.x.next 改用 `open`（命名对齐业界 antd5/Chakra/Radix/MUI）；v6.0 移除 visible prop + fallback。详见 BREAKING-CHANGES §B-Modal-props-rework 子条 #3-A
+     * `open` 的旧别名；与 open 二选一即可，新代码推荐用 open
+     */
     visible?: boolean;
     /** 打开 */
     open?: boolean;
+    /**
+     * **(v5.x.next 议题 #2 引入)** 非受控模式初始 open 值。
+     * 未传 `open`（且未传 `visible`）时启用非受控 — Modal 内部维护 open state，
+     * 关闭路径自动 setOpen(false)，业务方不需要手动管理 open state。
+     * 与 React `<input defaultValue>` 惯例一致。
+     * 同时传 open + defaultOpen → open 优先（受控模式），dev warn 提示。
+     */
+    defaultOpen?: boolean;
     /** 确定按钮 loading */
     confirmLoading?: boolean;
     /** 标题 */
@@ -27,10 +48,48 @@ export interface ModalProps {
     showCancel?: boolean;
     /** 是否显示右上角的关闭按钮 */
     closable?: boolean;
-    /** 点击确定回调 */
+    /**
+     * @deprecated v5.x.next 改用 `onSubmit`（语义更清晰:submit 比 ok 更准确表达"确认提交"行为，对齐表单语义）；v6.0 移除 onOk。详见 BREAKING-CHANGES §B-Modal-props-rework
+     * 点击确定回调（旧名）
+     */
     onOk?: (e?: React.MouseEvent<HTMLElement>) => void;
+    /**
+     * **(v5.x.next 议题 #M1 引入)** 点击确定回调（推荐新 API,语义清晰）。
+     * 与 `onOk` 同义但 submit 比 ok 更准确表达"确认提交"行为。同时传 `onOk + onSubmit` → `onSubmit` 优先调用,`onOk` 跳过(避免业务函数重复触发)；
+     * 仅传 `onOk` → 旧行为不变(onOk 仍触发)。dev 环境若检测到只传 `onOk` 会 console.warn 1 次提示迁移。
+     */
+    onSubmit?: (e?: React.MouseEvent<HTMLElement>) => void | Promise<void>;
     /** 点击模态框右上角叉、取消按钮,return false 不关闭 */
     onCancel?: (e?: React.MouseEvent<HTMLElement>) => boolean | void;
+    /**
+     * @deprecated v5.x.next 改用 onDismiss（X/ESC/mask）+ onOk（确定）+ onCancel（取消）三回调职责互斥；v6.0 移除 onClose。详见 BREAKING-CHANGES §B-Modal-props-rework
+     *
+     * **(R6 §B3 阶段 1 引入)** 任意路径关闭都触发的统一回调,reason 区分关闭来源(`'cancel' | 'ok' | 'esc' | 'mask' | 'x'`)。
+     *
+     * 与 onCancel/onOk 共存(阶段 3 v6 移除单独 onCancel/onOk → BREAKING):
+     * - 取消按钮关闭 → 同时调 onCancel + onClose('cancel')
+     * - 确定按钮关闭 → 同时调 onOk + onClose('ok')
+     * - ESC 关闭 → 同时调 onCancel + onClose('esc')
+     * - 蒙层关闭 → 同时调 onCancel + onClose('mask')
+     * - X 按钮关闭 → 同时调 onCancel + onClose('x')
+     *
+     * 推荐写法 — 业务方在 onClose 里统一 setOpen(false) + reason 分支(埋点 / 重置 state 等),不再写双绑 `onCancel={fn} onOk={fn}` 兜底。
+     * 详见 BREAKING-CHANGES §B3 + discussions/Modal-unified-onClose.md
+     */
+    onClose?: (reason: ModalCloseReason) => void;
+    /**
+     * **(v5.x.next γ 方案 议题 #1 引入)** 非按钮关闭路径（X / ESC / 蒙层）的专用回调。
+     * 职责显式互斥：
+     * - onOk = 仅确定按钮
+     * - onCancel = 仅取消按钮
+     * - onDismiss = 仅 X / ESC / mask 三种"非按钮关闭"
+     *
+     * 仅传 onDismiss（不传 onClose）→ 新单触发行为：3 个非按钮路径仅调 onDismiss，不双触发。
+     * 同时传 onClose（无论是否也传 onDismiss）→ 旧兼容行为：维持 R6 双触发（onCancel + onClose）。
+     * 迁移时推荐：删 onClose，改用 onDismiss（理由见 discussions/Modal-props-rework.md §3.1）。
+     * 详见 BREAKING-CHANGES §B-Modal-props-rework。
+     */
+    onDismiss?: (reason: ModalDismissReason) => void;
     afterClose?: () => void;
     /** 大小 */
     size?: ModalSize;
@@ -40,13 +99,20 @@ export interface ModalProps {
     width?: string | number;
     /** 确认按钮文字 */
     okText?: ReactNode;
-    /** 确认按钮类型 */
-    okType?: string;
     /** 取消按钮文字 */
     cancelText?: ReactNode;
     /** 点击蒙层是否允许关闭 */
     maskClosable?: boolean;
+    /**
+     * @deprecated v5.x.next 改用 `closeOnBackdrop`(正向命名,业界对齐 antd `maskClosable` / chakra `closeOnOverlayClick`);v6 移除。
+     * 默认 `true`(即默认禁用蒙层关闭),与多数 Modal 库默认开放的直觉相反。详见 BREAKING-CHANGES §B6。
+     */
     disableBackdropClick?: boolean;
+    /**
+     * **(R6 §B6 阶段 1 引入)** 是否允许蒙层点击关闭(正向命名,业界对齐)。显式传值优先 — 未传时 fallback 旧 `disableBackdropClick`(默认 true 即禁用)。
+     * 阶段 3 v6 移除 `disableBackdropClick` 后默认 `true`(允许蒙层关闭)。详见 BREAKING-CHANGES §B6
+     */
+    closeOnBackdrop?: boolean;
     /** 强制渲染 Modal */
     forceRender?: boolean;
     /** 确定按钮属性 */
@@ -73,7 +139,21 @@ export interface ModalProps {
     mask?: boolean;
     /** 是否支持键盘esc关闭 */
     keyboard?: boolean;
+    /**
+     * @deprecated v5.x.next 改用 `closeOnEsc`(正向命名,业界对齐 antd `keyboard` / chakra `closeOnEsc`);v6 移除。
+     * 默认 `true`(即默认禁用 ESC 关闭),与多数 Modal 库默认开放的直觉相反。详见 BREAKING-CHANGES §B6。
+     */
     disableEscapeKeyDown?: boolean;
+    /**
+     * **(R6 §B6 阶段 1 引入)** 是否允许 Escape 键关闭(正向命名,业界对齐)。显式传值优先 — 未传时 fallback 旧 `disableEscapeKeyDown`(默认 true 即禁用)。
+     * 阶段 3 v6 移除 `disableEscapeKeyDown` 后默认 `true`(允许 ESC 关闭)。详见 BREAKING-CHANGES §B6
+     */
+    closeOnEsc?: boolean;
+    /**
+     * **(R6 §B6 阶段 1 引入)** 关闭后是否将焦点恢复到原触发元素(正向命名,业界对齐 mui `restoreFocus`)。等价 `focusTriggerAfterClose` 的正向 alias — 显式传值优先,未传时 fallback `focusTriggerAfterClose`(默认 true)。
+     * 注:`disableEnforceFocus` 仅 component.json/api.ts 文档层警示词,src 实际控制由 `focusTriggerAfterClose` 反向承担;v6 路径只保留 `restoreFocusOnClose`。详见 BREAKING-CHANGES §B6
+     */
+    restoreFocusOnClose?: boolean;
     /** 右上角关闭图标 */
     closeIcon?: ReactNode;
     /** 自定义渲染对话框 */
@@ -90,7 +170,7 @@ export interface ModalProps {
     contentHeight?: number | string;
     /** 内容样式 */
     contentStyle?: React.CSSProperties;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export declare const Modal: React.FC<ModalProps>;
 export { Confirm };

package/es/Modal/index.js

@@ -1,70 +1,107 @@
 import { j as t } from "../_virtual/jsx-runtime.js";
-import p from "react";
-import le from "rc-dialog";
-import { Button as m } from "../Button/index.js";
-import { Close as ae } from "../node_modules/@para-ui/icons/Close/index.js";
-import ie from "../GlobalContext/useFormatMessage.js";
-import ce from "./lang/index.js";
-import { Confirm as Ne } from "./Confirm/index.js";
-import C from "clsx";
-import { $prefixCls as y } from "../GlobalContext/constant.js";
-import me from "../AutoTips/index.js";
+import s from "react";
+import Me from "rc-dialog";
+import { Button as C } from "../Button/index.js";
+import { Close as Ae } from "../node_modules/@para-ui/icons/Close/index.js";
+import $e from "../GlobalContext/useFormatMessage.js";
+import Re from "./lang/index.js";
+import { Confirm as qe } from "./Confirm/index.js";
+import H from "clsx";
+import { $prefixCls as F } from "../GlobalContext/constant.js";
+import je from "../AutoTips/index.js";
 import './index.css';/* empty css           */
-let u;
-const ue = (o) => {
-  u = {
-    x: o.pageX,
-    y: o.pageY
+let h;
+const ze = (e) => {
+  h = {
+    x: e.pageX,
+    y: e.pageY
   }, setTimeout(() => {
-    u = null;
+    h = null;
   }, 100);
 };
-window.document.documentElement && document.documentElement.addEventListener("click", ue, !0);
-const we = (o) => {
+window.document.documentElement && document.documentElement.addEventListener("click", ze, !0);
+const Le = (e) => {
   const {
-    open: $,
-    visible: b = !1,
-    closeIcon: S,
-    centered: w = !0,
-    focusTriggerAfterClose: j = !0,
-    title: z,
-    footer: N,
-    showActions: B = !0,
-    actions: F,
-    header: d,
-    hideHeader: H = !1,
-    showCancel: M = !0,
-    maskClosable: v = !1,
-    disableBackdropClick: A = !0,
-    keyboard: T = !1,
-    disableEscapeKeyDown: E = !0,
-    fullScreen: P,
-    customizeSize: I,
-    style: D,
-    bodyStyle: L,
-    contentWidth: O,
-    contentHeight: f,
-    contentStyle: h,
-    size: s = "md",
-    children: R,
-    closable: W = !0,
-    mask: g = !0,
-    ..._
-  } = o, J = P || s === "fullScreen", x = ie("Modal", ce), e = `${y}-modal`, a = (n) => {
-    o.onCancel?.(n);
-  }, K = (n) => {
-    o.onOk?.(n);
-  }, X = () => {
-    const n = {
-      sm: `${e}-sm`,
-      md: `${e}-md`,
-      lg: `${e}-lg`,
-      auto: `${e}-auto`,
-      fullScreen: `${e}-fullscreen`
+    open: u,
+    visible: f,
+    defaultOpen: k,
+    closeIcon: G,
+    centered: I = !0,
+    focusTriggerAfterClose: T = !0,
+    title: _,
+    footer: V,
+    showActions: K = !0,
+    actions: P,
+    header: p,
+    hideHeader: W = !1,
+    showCancel: X = !0,
+    maskClosable: L = !1,
+    disableBackdropClick: J = !0,
+    closeOnBackdrop: x,
+    keyboard: Y = !1,
+    disableEscapeKeyDown: q = !0,
+    closeOnEsc: v,
+    restoreFocusOnClose: g,
+    fullScreen: Q,
+    customizeSize: U,
+    style: Z,
+    bodyStyle: ee,
+    contentWidth: oe,
+    contentHeight: E,
+    contentStyle: N,
+    size: r = "md",
+    children: ne,
+    closable: te = !0,
+    mask: O = !0,
+    ...se
+  } = e, w = $e("Modal", Re), S = e.onClose !== void 0, b = s.useRef(!1);
+  s.useEffect(() => {
+    process.env.NODE_ENV !== "production" && S && !b.current && (b.current = !0, console.warn(
+      "[Modal] onClose 已在 v5.x.next 标记为 @deprecated，将在 v6.0 移除。请迁移到 onDismiss（处理 X/ESC/mask 关闭）+ onOk（确定按钮）+ onCancel（取消按钮）三回调模式。详见 BREAKING-CHANGES §B-Modal-props-rework。"
+    ));
+  }, [S]);
+  const y = f !== void 0, B = s.useRef(!1);
+  s.useEffect(() => {
+    process.env.NODE_ENV !== "production" && y && !B.current && (B.current = !0, console.warn(
+      "[Modal] visible 已在 v5.x.next 标记为 @deprecated，将在 v6.0 移除。请改用 open prop。详见 BREAKING-CHANGES §B-Modal-props-rework 子条 #3-A"
+    ));
+  }, [y]);
+  const M = e.onOk !== void 0, A = e.onSubmit !== void 0, $ = s.useRef(!1);
+  s.useEffect(() => {
+    process.env.NODE_ENV !== "production" && M && !A && !$.current && ($.current = !0, console.warn(
+      "[Modal] onOk 已在 v5.x.next 标记为 @deprecated，将在 v6.0 移除。请改用 onSubmit prop（语义更清晰）。详见 BREAKING-CHANGES §B-Modal-props-rework"
+    ));
+  }, [M, A]);
+  const l = u !== void 0 || f !== void 0, [le, i] = s.useState(k ?? !1), re = l ? u ?? f ?? !1 : le, R = k !== void 0, j = u !== void 0;
+  s.useEffect(() => {
+    process.env.NODE_ENV !== "production" && j && R && console.warn(
+      "[Modal] 同时传 open + defaultOpen，defaultOpen 被忽略（open 优先，受控模式）。详见 BREAKING-CHANGES §B-Modal-props-rework 子条 #2"
+    );
+  }, [j, R]);
+  const z = s.useRef(l);
+  s.useEffect(() => {
+    z.current !== l && (process.env.NODE_ENV !== "production" && console.warn("[Modal] open 受控/非受控状态运行时切换，React 不支持此模式，请保持一致。"), z.current = l);
+  }, [l]);
+  const ae = Q || r === "fullScreen", n = `${F}-modal`, ce = v !== void 0 ? v : !q, ie = x !== void 0 ? x : !J, de = g !== void 0 ? g : T, ue = (o) => {
+    e.onCancel?.(o), e.onClose?.("cancel"), l || i(!1);
+  }, fe = (o) => {
+    e.onClose !== void 0 ? (e.onCancel?.(o), e.onClose("x")) : e.onDismiss?.("x"), l || i(!1);
+  }, me = (o) => {
+    const a = o && o.type === "keydown" ? "esc" : "mask";
+    e.onClose !== void 0 ? (e.onCancel?.(o), e.onClose(a)) : e.onDismiss?.(a), l || i(!1);
+  }, Ce = (o) => {
+    e.onSubmit ? e.onSubmit(o) : e.onOk?.(o), e.onClose?.("ok"), l || i(!1);
+  }, he = () => {
+    const o = {
+      sm: `${n}-sm`,
+      md: `${n}-md`,
+      lg: `${n}-lg`,
+      auto: `${n}-auto`,
+      fullScreen: `${n}-fullscreen`
     };
-    if (!h)
-      return J ? n.fullScreen : n[s];
-  }, Y = () => !s || s === "fullScreen" || s === "auto" ? void 0 : {
+    if (!N)
+      return ae ? o.fullScreen : o[r];
+  }, ke = () => !r || r === "fullScreen" || r === "auto" ? void 0 : {
     sm: {
       width: 430,
       maxHeight: 118
@@ -77,94 +114,94 @@ const we = (o) => {
       width: 948,
       maxHeight: 478
     }
-  }[s], q = () => g ? `${e}-with-mask` : `${e}-without-mask`, G = () => ({ ...I, ...D }), Q = () => {
-    const { maxHeight: n, width: i } = Y() || {};
+  }[r], pe = () => O ? `${n}-with-mask` : `${n}-without-mask`, xe = () => ({ ...U, ...Z }), ve = () => {
+    const { maxHeight: o, width: a } = ke() || {};
     return {
       // contentWidth 和 contentHeight 优先级总是最高
-      maxHeight: f || n || "calc(100vh - 142px)",
-      width: O || i,
-      height: f,
+      maxHeight: E || o || "calc(100vh - 142px)",
+      width: oe || a,
+      height: E,
       // minHeight: contentHeight || 118,
-      ...L,
-      ...h
+      ...ee,
+      ...N
     };
-  }, U = () => {
-    if (H) return null;
-    if (d) return d;
-    const n = W && /* @__PURE__ */ t.jsx(
-      m.IconButton,
+  }, ge = () => {
+    if (W) return null;
+    if (p) return p;
+    const o = te && /* @__PURE__ */ t.jsx(
+      C.IconButton,
       {
-        onClick: a,
-        className: `${e}-close`,
+        onClick: fe,
+        className: `${n}-close`,
         variant: "outlined",
         size: "small",
-        children: S || /* @__PURE__ */ t.jsx(ae, { className: `${e}-close-icon` })
+        children: G || /* @__PURE__ */ t.jsx(Ae, { className: `${n}-close-icon` })
       }
     );
     return /* @__PURE__ */ t.jsxs(t.Fragment, { children: [
-      /* @__PURE__ */ t.jsx(me, { className: `${e}-title-text`, children: z }),
-      n
+      /* @__PURE__ */ t.jsx(je, { className: `${n}-title-text`, children: _ }),
+      o
     ] });
-  }, V = () => {
-    if (!B) return null;
-    const { okText: n, cancelText: i, okButtonProps: te, cancelButtonProps: ne, confirmLoading: oe = !1 } = o, se = /* @__PURE__ */ t.jsx(
-      m,
+  }, Ee = () => {
+    if (!K) return null;
+    const { okText: o, cancelText: a, okButtonProps: we, cancelButtonProps: Se, confirmLoading: be = !1 } = e, ye = /* @__PURE__ */ t.jsx(
+      C,
       {
         variant: "contained",
         size: "large",
-        loading: oe,
-        onClick: K,
-        ...te,
-        children: n ?? x({ id: "ok" })
+        loading: be,
+        onClick: Ce,
+        ...we,
+        children: o ?? w({ id: "ok" })
       }
-    ), k = [M && /* @__PURE__ */ t.jsx(
-      m,
+    ), D = [X && /* @__PURE__ */ t.jsx(
+      C,
       {
         variant: "outlined",
         size: "large",
-        onClick: a,
-        ...ne,
-        children: i ?? x({ id: "cancel" })
+        onClick: ue,
+        ...Se,
+        children: a ?? w({ id: "cancel" })
       }
-    ), se], l = F ?? N;
-    if (typeof l == "function") {
-      const r = l(k);
-      return /* @__PURE__ */ t.jsx(t.Fragment, { children: Array.isArray(r) ? r.map((c, re) => /* @__PURE__ */ t.jsx(p.Fragment, { children: c }, re)) : r });
-    } else if (l)
-      return l;
-    return /* @__PURE__ */ t.jsx(t.Fragment, { children: k.map((r, c) => /* @__PURE__ */ t.jsx(p.Fragment, { children: r }, c)) });
-  }, Z = C(o.wrapClassName, {
-    [`${e}-centered`]: w
-  }), ee = C(o.className, `${y}-scrollbar-small`, X(), q());
+    ), ye], d = P ?? V;
+    if (typeof d == "function") {
+      const c = d(D);
+      return /* @__PURE__ */ t.jsx(t.Fragment, { children: Array.isArray(c) ? c.map((m, Be) => /* @__PURE__ */ t.jsx(s.Fragment, { children: m }, Be)) : c });
+    } else if (d)
+      return d;
+    return /* @__PURE__ */ t.jsx(t.Fragment, { children: D.map((c, m) => /* @__PURE__ */ t.jsx(s.Fragment, { children: c }, m)) });
+  }, Ne = H(e.wrapClassName, {
+    [`${n}-centered`]: I
+  }), Oe = H(e.className, `${F}-scrollbar-small`, he(), pe());
   return /* @__PURE__ */ t.jsx(
-    le,
+    Me,
     {
-      ..._,
-      mask: g,
-      visible: $ ?? b,
-      title: U(),
-      footer: V(),
-      style: G(),
-      bodyStyle: Q(),
-      prefixCls: e,
-      className: ee,
-      wrapClassName: Z,
-      mousePosition: u,
-      onClose: a,
+      ...se,
+      mask: O,
+      visible: re,
+      title: ge(),
+      footer: Ee(),
+      style: xe(),
+      bodyStyle: ve(),
+      prefixCls: n,
+      className: Oe,
+      wrapClassName: Ne,
+      mousePosition: h,
+      onClose: me,
       closable: !1,
       closeIcon: null,
-      maskClosable: !A || v,
-      keyboard: !E || T,
-      focusTriggerAfterClose: j,
-      transitionName: `${e}-zoom`,
-      maskTransitionName: `${e}-fade`,
-      children: R
+      maskClosable: ie || L,
+      keyboard: ce || Y,
+      focusTriggerAfterClose: de,
+      transitionName: `${n}-zoom`,
+      maskTransitionName: `${n}-fade`,
+      children: ne
     }
   );
 };
 export {
-  Ne as Confirm,
-  we as Modal,
-  we as default
+  qe as Confirm,
+  Le as Modal,
+  Le as default
 };
 //# sourceMappingURL=index.js.map

package/es/Modal/interface.d.ts

@@ -0,0 +1 @@
+export type ModalDismissReason = 'esc' | 'mask' | 'x';