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

package/lib/Modal/component.json

@@ -0,0 +1,277 @@
+{
+    "name": "Modal",
+    "category": "Feedback",
+    "description": "模态对话框，用于需用户处理事务，又不希望跳转页面的场景",
+    "semantic": {
+        "intent": [
+            "通知",
+            "确认",
+            "复杂输入",
+            "详情查看"
+        ],
+        "useCases": [
+            "删除确认",
+            "表单填写",
+            "信息详情",
+            "重要预警"
+        ],
+        "riskLevel": "high"
+    },
+    "variants": {
+        "confirm": {
+            "meaning": "确认框，通常只包含文本和确定/取消按钮"
+        },
+        "info": {
+            "meaning": "信息框，展示详情或通知"
+        }
+    },
+    "states": [
+        "open",
+        "loading"
+    ],
+    "idealProps": {
+        "open": {
+            "type": "boolean",
+            "default": false,
+            "description": "模态框是否可见。**`visible` 是同义旧别名**（src:33-35 二者都存在），新代码推荐用 open。**Modal 完全受控**(DEFECT-008):src/Modal/index.tsx:160-167 handleCancel/handleOk **不修改 open 内部状态**,只调 props.onCancel/onOk;父组件必须自行 setOpen(false) 才会关闭。不存在\"非受控自动关闭\"模式。未传 `open` 时可用 `defaultOpen` 启用非受控模式（v5.x.next 议题 #2 新增）"
+        },
+        "defaultOpen": {
+            "type": "boolean",
+            "description": "**(v5.x.next 议题 #2 引入)** 非受控模式初始 open 值。未传 `open` 时启用非受控 — Modal 内部维护 open state，关闭路径自动 setOpen(false)，业务方不需要手动管理 open state（公告类/一次性 Modal 推荐）。与 React `<input defaultValue>` 惯例一致。同时传 open + defaultOpen → open 优先，dev warn 提示"
+        },
+        "visible": {
+            "type": "boolean",
+            "default": false,
+            "description": "**@deprecated v5.x.next 改用 `open`（命名对齐业界 antd5/Chakra/Radix/MUI）；v6.0 移除（BREAKING-CHANGES §B-Modal-props-rework 子条 #3-A）。** `open` 的旧别名；与 open 二选一即可，新代码推荐用 open"
+        },
+        "title": {
+            "type": "ReactNode",
+            "description": "标题"
+        },
+        "onOk": {
+            "type": "function",
+            "signature": "() => void",
+            "description": "**@deprecated v5.x.next 改用 `onSubmit`（语义更清晰:submit 比 ok 更准确表达\"确认提交\"行为，对齐表单语义）；v6.0 移除（BREAKING-CHANGES §B-Modal-props-rework）。** 点击确定回调（旧名）"
+        },
+        "onSubmit": {
+            "type": "function",
+            "signature": "(e?: React.MouseEvent) => void | Promise<void>",
+            "description": "**(v5.x.next 议题 #M1 引入)** 点击确定回调（推荐新 API,语义清晰）。与 `onOk` 同义但 submit 比 ok 更准确表达\"确认提交\"行为。同时传 `onOk + onSubmit` → `onSubmit` 优先调用,`onOk` 跳过(避免业务函数重复触发);仅传 `onOk` → 旧行为不变(onOk 仍触发)。dev 环境若检测到只传 `onOk` 会 console.warn 1 次提示迁移"
+        },
+        "onCancel": {
+            "type": "function",
+            "signature": "() => boolean | void",
+            "description": "点击取消、ESC、遮罩、右上角叉的回调；返回 false 阻止关闭"
+        },
+        "onClose": {
+            "type": "function",
+            "signature": "(reason: 'cancel' | 'ok' | 'esc' | 'mask' | 'x') => void",
+            "description": "@deprecated v5.x.next 改用 onDismiss + onOk + onCancel 三回调；v6.0 移除。**(R6 §B3 阶段 1 引入,最低支持版本 5.x.next)** 任意路径关闭统一回调,reason 字面联合区分关闭来源。**与 onCancel/onOk 共存为叠加触发**(src 实证):取消按钮 → onCancel + onClose('cancel');确定按钮 → onOk + onClose('ok');ESC/蒙层/X → onCancel + onClose('esc'|'mask'|'x')。**推荐写法** — 业务方在 onClose 里统一 setOpen(false) + reason 分支(埋点 / 重置 state),不再写 `onCancel={fn} onOk={fn}` 双绑兜底;若旧代码 onOk + onClose 共存,onOk 应只处理 'ok' 路径(submit),onClose 处理其他 4 种,避免业务函数重复触发(R3 4/9 + R5 5/9 sub-agent 持续踩坑)。**X 按钮在 showCancel=false 时仍显示并触发 reason='x'**(X 由 hideHeader 控制,不受 showCancel 影响);**Modal 完全受控** — onClose 未传或未在 onClose 内 setOpen(false),Modal 不会自动关闭。阶段 3 v6 移除单独 onCancel/onOk(BREAKING)。详见 BREAKING-CHANGES §B3 + discussions/Modal-unified-onClose.md"
+        },
+        "onDismiss": {
+            "type": "function",
+            "signature": "(reason: ModalDismissReason) => void",
+            "description": "**(v5.x.next γ 方案 议题 #1 引入)** 非按钮关闭路径（X/ESC/蒙层）的专用回调。仅传 onDismiss（不传 onClose）时走新单触发行为：X 按钮仅调 `onDismiss('x')`，ESC 仅调 `onDismiss('esc')`，蒙层仅调 `onDismiss('mask')`。**onOk/onCancel/onDismiss 三回调职责互斥**（对比旧 onClose 5 路径统一触发会导致双触发）。推荐迁移路径：删 onClose，改用 onDismiss 处理非按钮路径。详见 BREAKING-CHANGES §B-Modal-props-rework"
+        },
+        "showCancel": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示取消按钮。**仅控制取消按钮显隐**,不影响右上角 X 按钮(X 由 hideHeader 控制;showCancel=false 时 X 仍显示并仍可点击触发关闭走 onClose reason='x' / onCancel 路径)。showCancel=false 时 onCancel 可省略(走 onClose 统一处理)"
+        },
+        "showActions": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示底部 actions 按钮区(确定 + 取消按钮统一区域)。**典型场景**:登录/复杂表单内嵌时设为 false 隐藏默认底部,业务自行在 children 内放置提交按钮"
+        },
+        "confirmLoading": {
+            "type": "boolean",
+            "default": false,
+            "description": "确定按钮 loading 状态（顶层快捷方式，等价于 okButtonProps={{ loading }}）。**loading 期间确定按钮自动 disabled 不响应点击**（src/Modal/index.tsx:258 透传 Button.loading,Button 自身已 `disabled={disabled \\|\\| hasLoading}`,见 BREAKING-CHANGES §A2）——业务无需再叠 okButtonProps.disabled。"
+        },
+        "destroyOnClose": {
+            "type": "boolean",
+            "default": false,
+            "description": "关闭时销毁子元素；下次打开重建。表单类内嵌内容用此 prop 重置状态"
+        },
+        "maskClosable": {
+            "type": "boolean",
+            "default": false,
+            "description": "点击蒙层是否允许关闭。**与 disableBackdropClick 是同一能力的双 prop（DEFECT-001）**，src 实际：`!disableBackdropClick \\|\\| maskClosable`。**强烈推荐用 disableBackdropClick 替代 maskClosable**——后者是冗余且易混淆"
+        },
+        "closeOnBackdrop": {
+            "type": "boolean",
+            "description": "**(R6 §B6 阶段 1 引入)** 是否允许蒙层点击关闭(正向命名,业界对齐 antd `maskClosable` / chakra `closeOnOverlayClick`)。显式传值优先 — 未传时 fallback 旧 `disableBackdropClick`(默认 true 即禁用,反业界直觉)。**推荐用 closeOnBackdrop={true}** 替代 `disableBackdropClick={false}` 双重否定写法。阶段 3 v6 移除 disableBackdropClick 后默认 true。详见 BREAKING-CHANGES §B6"
+        },
+        "disableBackdropClick": {
+            "type": "boolean",
+            "default": true,
+            "description": "**@deprecated v5.x.next 改用 `closeOnBackdrop`(正向命名,业界对齐);v6 移除(BREAKING-CHANGES §B6 阶段 3)**。⚠️ 默认 true（即默认禁用蒙层点击关闭）——与多数 Modal 库默认允许的直觉相反（DEFECT-002,R5 9/9 sub-agent 全部明确感知反业界直觉）。需要允许点击遮罩关闭推荐显式传 `closeOnBackdrop={true}`(新 prop) 或旧写法 `disableBackdropClick={false}`(deprecated)"
+        },
+        "closeOnEsc": {
+            "type": "boolean",
+            "description": "**(R6 §B6 阶段 1 引入)** 是否允许 Escape 键关闭(正向命名,业界对齐 antd `keyboard` / chakra `closeOnEsc`)。显式传值优先 — 未传时 fallback 旧 `disableEscapeKeyDown`(默认 true 即禁用,反业界直觉)。**推荐用 closeOnEsc={true}** 替代 `disableEscapeKeyDown={false}` 双重否定。阶段 3 v6 移除 disableEscapeKeyDown 后默认 true。详见 BREAKING-CHANGES §B6"
+        },
+        "disableEscapeKeyDown": {
+            "type": "boolean",
+            "default": true,
+            "description": "**@deprecated v5.x.next 改用 `closeOnEsc`(正向命名,业界对齐);v6 移除(BREAKING-CHANGES §B6 阶段 3)**。⚠️ 默认 true（即默认禁用 ESC 关闭）——同样与多数库直觉相反"
+        },
+        "restoreFocusOnClose": {
+            "type": "boolean",
+            "description": "**(R6 §B6 阶段 1 引入)** 关闭后是否将焦点恢复到原触发元素(正向命名,业界对齐 mui `restoreFocus`)。等价 `focusTriggerAfterClose` 的正向 alias — 显式传值优先,未传时 fallback `focusTriggerAfterClose`(默认 true)。**推荐用 restoreFocusOnClose** 命名;v6 路径只保留 restoreFocusOnClose。详见 BREAKING-CHANGES §B6"
+        },
+        "size": {
+            "type": "enum",
+            "values": [
+                "sm",
+                "md",
+                "lg",
+                "auto",
+                "fullScreen"
+            ],
+            "default": "md",
+            "description": "尺寸枚举。**`size='fullScreen'` 与独立 prop `fullScreen={true}` 是同一能力的双 prop（DEFECT-003）**——src 实际 `fullScreen \\|\\| size === 'fullScreen'`。**推荐用 size='fullScreen'**（与其他尺寸取值同 prop，更一致）"
+        },
+        "fullScreen": {
+            "type": "boolean",
+            "default": false,
+            "description": "全屏开关;与 size='fullScreen' 同义,推荐用 size='fullScreen'。**全屏模式内容区高度行为**:启用时 dialog 容器追加 `.{prefix}-fullscreen` 类,内容区自动 height: 100vh + overflow: auto;contentStyle padding 由父级控制,无需业务方再写 style 撑高"
+        },
+        "centered": {
+            "type": "boolean",
+            "default": true,
+            "description": "**Modal 默认垂直居中**（DEFECT-004:src/Modal/index.tsx:64+129+301 实证,默认值 true,启用时根容器追加 `.{prefix}-centered` 类）。无需 style transform 等 hack 实现居中——直接使用默认即可。如需顶部对齐请显式传 `centered={false}`。"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "落在 Modal **dialog 外层容器**（DEFECT-007:与 contentStyle 区分,后者仅作用于内容区 DOM）。常用于覆盖整体边距 / z-index / position 等容器级属性。"
+        },
+        "contentStyle": {
+            "type": "React.CSSProperties",
+            "description": "落在 Modal **内容区 DOM 节点**（DEFECT-007:src/Modal/index.tsx:224 实证)。覆盖 contentHeight 等内容区限定样式。需要整体 dialog 样式请用 style。"
+        },
+        "width": {
+            "type": "string | number",
+            "description": "Modal dialog 容器整体宽度。与 `contentWidth` 区分：contentWidth 仅控制内容区，width 控制整体——业务侧『自定义宽度』优先用 width"
+        },
+        "okText": {
+            "type": "string",
+            "description": "确认按钮文字"
+        },
+        "cancelText": {
+            "type": "string",
+            "description": "取消按钮文字"
+        },
+        "actions": {
+            "type": "function | ReactNode",
+            "signature": "((buttons: ReactNode[]) => ReactNode[]) | ReactNode",
+            "description": "⚠️ **完全自定义底部操作栏**（src/Modal/index.tsx:69 实证）。两种用法：① 传 `ReactNode` 完全替换底部按钮区（隐藏默认确定/取消按钮，渲染自定义内容）；② 传函数 `(buttons) => ReactNode[]` 接收默认按钮数组后按需增删/改造再返回。**与 `footer` 区分**：`footer` 语义相同但 actions 是更语义化的命名（两者 src 并存，任选一即可）。**与 `showActions` 区分**：showActions=false 是整体隐藏，actions 是替换内容——需要完全自定义按钮组合时用 actions，需要隐藏整个底部区域时用 showActions=false"
+        }
+    },
+    "do": [
+        "保持模态框内容简洁，避免过于复杂的流程",
+        "**新代码统一用 `open` 而非 `visible`**——visible 是旧别名",
+        "**`onDismiss` + `onOk` + `onCancel` 三回调首推(v5.x.next γ 方案)**：`onDismiss` 处理非按钮路径（X/ESC/蒙层），`onOk` 处理确定按钮，`onCancel` 处理取消按钮，三者职责互斥，无双触发问题",
+        "**旧写法（不推荐）**：`onClose(reason)` 顶层回调在任意路径关闭时触发，v5.x.next 已标 @deprecated，v6.0 移除。如仍使用，在 onClose 里统一 setOpen(false) + reason 分支（reason ∈ 'cancel'|'ok'|'esc'|'mask'|'x'）",
+        "**全屏模态用 `size='fullScreen'`**——与其他尺寸取值同 prop；fullScreen={true} 是冗余别名",
+        "**点击蒙层关闭：用 `closeOnBackdrop={true}`(R6 §B6 阶段 1 推荐,正向命名,业界对齐)** — 替代旧 `disableBackdropClick={false}` 双重否定写法;`maskClosable` 仍是冗余双 prop,推荐用 closeOnBackdrop。同理 `closeOnEsc={true}` 替代 `disableEscapeKeyDown={false}`;`restoreFocusOnClose` 替代旧 `focusTriggerAfterClose` 正向 alias",
+        "**Modal 默认垂直居中**（centered=true）——无需 style transform 居中 hack。需要顶部对齐显式传 centered={false}",
+        "整体 dialog 样式用 `style`,内容区限定样式用 `contentStyle`——两者作用 DOM 节点不同(DEFECT-007)",
+        "整体宽度自定义用 `width`（不是 contentWidth——后者仅控制内容区）",
+        "重要操作（如不可逆删除）应使 ESC + 蒙层都不能关闭——保留默认 `closeOnEsc=undefined / closeOnBackdrop=undefined`(fallback 旧 disable* 默认 true 即锁定);旧写法 `disableEscapeKeyDown=true / disableBackdropClick=true` 仍工作但不推荐",
+        "需要关闭后重置内嵌表单状态时使用 `destroyOnClose={true}`",
+        "确定按钮 loading 状态用 `confirmLoading={true}`——loading 期间按钮自动 disabled,业务无需再叠 okButtonProps.disabled"
+    ],
+    "dont": [
+        "在模态框上再叠加模态框（多层嵌套）",
+        "在模态框中放置过长的表单（应考虑独立页面）",
+        "不要混用 visible 与 open 双 prop——只传一个",
+        "不要既传 fullScreen 又传 size='fullScreen'——只传一个，推荐 size",
+        "不要既传 disableBackdropClick 又传 maskClosable——只传一个,推荐 closeOnBackdrop(R6 §B6 阶段 1 引入正向命名)",
+        "不要假设 disableBackdropClick / disableEscapeKeyDown 默认值是 false——它们默认 true（即默认禁用），与多数库直觉相反;v6 路径已 rename 为 closeOnBackdrop / closeOnEsc / restoreFocusOnClose 正向 prop"
+    ],
+    "events": {
+        "onSubmit": {
+            "signature": "(e?: React.MouseEvent<HTMLElement>) => void | Promise<void>",
+            "asyncSupported": true,
+            "examples": [
+                "推荐新写法：async onSubmit 处理异步提交，confirmLoading 配合显示 loading 状态",
+                "onSubmit 与 onOk 同义，同时传时 onSubmit 优先，onOk 被跳过（src/Modal/index.tsx:230-234 实证）",
+                "表单提交场景：onSubmit 内调 formRef.current.check?.()，失败 return，成功后关闭 Modal"
+            ],
+            "commonMistakes": [
+                "同时传 onOk + onSubmit，期望两者都执行 → src 优先调 onSubmit，onOk 被跳过",
+                "假设 async onSubmit 执行完成后 Modal 自动关闭 → Modal 完全受控，必须在 onSubmit 内手动 setOpen(false)",
+                "传 onOk 而不传 onSubmit 时触发 dev warn → src 检测到仅有 onOk 会 console.warn 一次提示迁移到 onSubmit"
+            ]
+        },
+        "onCancel": {
+            "signature": "(e?: React.MouseEvent<HTMLElement>) => boolean | void",
+            "asyncSupported": false,
+            "examples": [
+                "点击取消按钮触发，业务方在回调里 setOpen(false) 关闭 Modal",
+                "返回 false 阻止关闭（src/Modal/index.tsx:interface 签名实证）",
+                "showCancel=false 时用户无法触发 onCancel，X/ESC/蒙层改走 onDismiss"
+            ],
+            "commonMistakes": [
+                "假设 onCancel 在 X 按钮/ESC/蒙层点击时也触发 → v5.x.next 新模式下传了 onDismiss 且不传 onClose 时，X/ESC/mask 仅调 onDismiss，不双触发 onCancel",
+                "不在 onCancel 内 setOpen(false) → Modal 是完全受控组件，不自动关闭",
+                "假设 onCancel 和 onClose 等价 → onClose 是 deprecated 的统一路径回调（v6 移除），onCancel 只绑取消按钮"
+            ]
+        },
+        "onDismiss": {
+            "signature": "(reason: 'esc' | 'mask' | 'x') => void",
+            "asyncSupported": false,
+            "examples": [
+                "推荐新写法（v5.x.next）：`onDismiss={(r) => { if (r !== 'esc') setOpen(false); }}` 区分关闭来源",
+                "仅传 onDismiss 不传 onClose → 新单触发行为：X/ESC/mask 只调 onDismiss，不再同时触发 onCancel",
+                "同时传 onClose（无论是否传 onDismiss）→ 旧兼容行为：维持 R6 双触发（onCancel + onClose）"
+            ],
+            "commonMistakes": [
+                "假设 onDismiss 的 reason 包含 'cancel' 或 'ok' → ModalDismissReason 只有 'esc' | 'mask' | 'x'，按钮路径不走这里",
+                "同时传 onClose + onDismiss 并期望单触发 → 同时传 onClose 时维持旧双触发行为，只有删 onClose 才能用新单触发",
+                "在 onDismiss 内不 setOpen(false) → Modal 完全受控，必须手动关闭"
+            ]
+        },
+        "onClose": {
+            "signature": "(reason: 'cancel' | 'ok' | 'esc' | 'mask' | 'x') => void",
+            "asyncSupported": false,
+            "examples": [
+                "（旧写法，已 @deprecated）统一处理所有关闭路径，reason 区分来源",
+                "迁移示例：删 onClose 改用 onDismiss + onOk + onCancel 三回调",
+                "如仍使用：`onClose={(r) => { setOpen(false); if (r==='ok') submit(); }}` 在 onClose 里统一 setOpen + 分支处理"
+            ],
+            "commonMistakes": [
+                "传了 onClose 后期望 onOk + onClose('ok') 不重复触发业务逻辑 → 两者叠加触发（src:230-237 实证），需在 onOk 只做提交，在 onClose 里判断 reason='ok' 再 setOpen(false)",
+                "在 v6 前就依赖 onClose 的确定/取消路径 → v6.0 移除 onClose，应迁移到新三回调模式",
+                "假设 onClose 在 Modal 组件 unmount 时触发 → onClose 仅在用户主动关闭时触发，不是生命周期回调"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "ModalCloseReason 和 ModalDismissReason 是不同的类型，不能混用",
+            "wrong": "onDismiss={(reason: 'cancel' | 'ok' | 'esc' | 'mask' | 'x') => ...}  // onDismiss 参数是 ModalDismissReason，无 'cancel'/'ok'",
+            "right": "import { ModalDismissReason } from '@para-ui/core'; onDismiss={(reason: ModalDismissReason) => ...}  // ModalDismissReason = 'esc' | 'mask' | 'x'"
+        },
+        {
+            "issue": "disableBackdropClick / disableEscapeKeyDown 默认值是 true（禁用），与多数库默认允许的直觉相反",
+            "wrong": "// 期望默认允许点击蒙层关闭 → 实际默认 disableBackdropClick=true 即禁用蒙层关闭",
+            "right": "<Modal closeOnBackdrop={true} closeOnEsc={true} />  // 正向命名，明确允许蒙层和ESC关闭（src/Modal/index.tsx:201-204 实证）"
+        },
+        {
+            "issue": "onSubmit 支持 async，onOk 的旧签名不明确支持 Promise",
+            "wrong": "onOk={async () => { await doSubmit(); setOpen(false); }}  // onOk 已 deprecated，且类型签名不含 Promise",
+            "right": "onSubmit={async (e) => { await doSubmit(); setOpen(false); }}  // onSubmit 签名: (e?) => void | Promise<void>"
+        },
+        {
+            "issue": "actions prop 接受函数形式时返回值类型是 ReactNode[] 不是 ReactNode",
+            "wrong": "actions={(btns) => <div>{btns}</div>}  // 返回 ReactNode，TS 报类型不匹配",
+            "right": "actions={(btns) => [...btns, <Button key='extra'>额外按钮</Button>]}  // 返回 ReactNode[] 数组"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Modal",
+        "adapter": null
+    }
+}

package/lib/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/lib/Modal/index.js

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

package/lib/Modal/interface.d.ts

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