@para-ui/core 5.0.0-beta.9 → 5.0.1

package/Message/component.json

@@ -0,0 +1,246 @@
+{
+    "name": "Message",
+    "category": "Feedback",
+    "description": "全局展示操作反馈信息(顶部条状提示)。**通过 4 个静态方法触发,非 React 组件挂载**。**关键 API 形态:`Message.{type}(config, duration?)` —— config 是 MsgTypeProps 对象或纯 string,duration 是【独立的第 2 参数】,不是 MsgTypeProps 的字段**(见 commonMisconceptions.M1)",
+    "semantic": {
+        "intent": [
+            "通知用户操作结果",
+            "瞬态状态提示",
+            "顶部条状反馈"
+        ],
+        "useCases": [
+            "提交成功 / 失败反馈",
+            "操作警告(无需用户确认的轻提示)",
+            "瞬态错误信息",
+            "loading 场景(workaround,无原生 loading 类型,见 limitations.L2)"
+        ],
+        "riskLevel": "low"
+    },
+    "protocolSummary": "**4 类型 × 2 参数签名**:\n```\nMessage.info(config, duration?)\nMessage.success(config, duration?)\nMessage.warn(config, duration?)\nMessage.error(config, duration?)\n```\n- `config: string | MsgTypeProps` —— 字符串(直接当 text)或对象(完整配置)\n- `duration?: number` —— **独立第 2 参数**(毫秒),默认 5000,传 0 / 负数 / NaN 时不自动关闭\n\n**3 个全局方法**:\n```\nMessage.clear()       // 关闭当前所有 Message\nMessage.destroyAll()  // clear 的别名\nMessage.config({ maxCount?, duration? })  // 修改全局默认值\n```",
+    "limitations": {
+        "L1_no_onClose_callback": {
+            "issue": "**MsgTypeProps 不支持 onClose / onDismiss / onAfterClose 回调** —— 用户手动关闭或自动关闭后无法触发回调",
+            "rootCause": "src/Message/index.tsx 未暴露 callback 字段",
+            "workaround": "如果业务需要'关闭后执行 X':\n1. **如果是自动关闭**:用 `setTimeout(handler, duration)` 自己计时(精度误差 ~50ms)\n2. **如果是手动关闭(close 按钮)**:Message 本身没法监听,需要换 Toast / Snackbar / Modal 组件"
+        },
+        "L2_no_loading_variant": {
+            "issue": "**没有 Message.loading 方法 / loading variant** —— variants 只有 info/success/warn/error 4 种",
+            "rootCause": "src/Message/index.tsx 未实现 loading 静态方法",
+            "workaround": "用 `Message.info({ text: '加载中...', icon: <Loading />, close: true }, 0)`(duration=0 不自动关闭),loading 完成后调 `Message.clear()` 关闭。**注意**:icon prop 需要传入 Loading 图标组件 ReactNode",
+            "alternative": "需要真正的 loading 视觉(spinner / 进度) → 用 Loading 组件 / Spin 组件,不要硬塞 Message"
+        }
+    },
+    "variants": {
+        "info": {
+            "meaning": "普通信息(蓝色 i 图标)"
+        },
+        "success": {
+            "meaning": "操作成功(绿色 ✓ 图标)"
+        },
+        "warn": {
+            "meaning": "警告(黄色 ! 图标)"
+        },
+        "error": {
+            "meaning": "错误(红色 × 图标)"
+        }
+    },
+    "states": [
+        "opening",
+        "closing"
+    ],
+    "idealProps": {
+        "text": {
+            "type": "string",
+            "description": "主文本(标题)。也可以把整个 config 简化成纯字符串:`Message.info('提交成功', 3000)` 等同于 `Message.info({ text: '提交成功' }, 3000)`"
+        },
+        "desc": {
+            "type": "string",
+            "description": "副描述文案;**出现时 text 会自动加粗变标题**,desc 作为下方说明文本"
+        },
+        "icon": {
+            "type": "ReactNode",
+            "description": "自定义图标(覆盖 type 默认图标)。loading 场景常传入 `<Loading />` 图标组件配合 duration=0。**与 hideIcon 互斥**(同时传 hideIcon 优先)"
+        },
+        "hideIcon": {
+            "type": "boolean",
+            "default": false,
+            "description": "隐藏图标,显示纯文本提示。**与 icon 互斥**"
+        },
+        "close": {
+            "type": "boolean",
+            "description": "**强制显示关闭按钮**。undefined 时按 duration 推断:duration>0 不显示关闭按钮(自动关闭即可),duration<=0 或 NaN 显示关闭按钮(需要用户手动关闭)"
+        },
+        "maxCount": {
+            "type": "number",
+            "default": "Infinity",
+            "description": "同时显示最大条数。per-call(MsgTypeProps.maxCount)或全局(Message.config({ maxCount: N }))"
+        },
+        "html": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否把 text 当 innerHTML 渲染。**仅可信来源使用**(避免 XSS)"
+        },
+        "className": {
+            "type": "string",
+            "description": "提示容器的 className"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "提示容器的 style"
+        }
+    },
+    "staticMethods": {
+        "info": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void",
+            "callExample": "// 正确:\nMessage.info('提交成功', 3000)\nMessage.info({ text: '提交成功', desc: '已保存到草稿' }, 3000)\nMessage.info({ text: '加载中', icon: <Loading />, close: true }, 0)\n\n// 错误(M1):\nMessage.info({ text: '提交成功', duration: 3000 })  // ❌ duration 不是 MsgTypeProps 的字段!"
+        },
+        "success": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void"
+        },
+        "warn": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void"
+        },
+        "error": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void"
+        },
+        "clear": {
+            "signature": "() => void",
+            "description": "关闭当前页面所有 Message 实例"
+        },
+        "destroyAll": {
+            "signature": "() => void",
+            "description": "clear 的别名(deprecated 倾向 —— **新代码推荐 clear**)"
+        },
+        "config": {
+            "signature": "(config: { maxCount?: number; duration?: number }) => void",
+            "description": "修改全局默认值(影响后续 Message.{type} 调用)"
+        }
+    },
+    "commonMisconceptions": {
+        "M1": {
+            "wrong": "把 duration 写进 MsgTypeProps 对象: `Message.info({ text: '提交成功', duration: 3000 })`",
+            "result": "**TS 报错 TS2353 'duration does not exist in type MsgTypeProps'** —— R23 Message-005 fail 根因",
+            "fix": "duration 是 Message.{type}() 的**独立第 2 参数**: `Message.info({ text: '提交成功' }, 3000)` 或纯字符串形式 `Message.info('提交成功', 3000)`"
+        },
+        "M2": {
+            "wrong": "传 onClose / onDismiss / onAfterClose 回调期望关闭时触发: `Message.info({ text: '已删除', onClose: handleAfterClose })`",
+            "result": "**MsgTypeProps 无 callback 字段**——TS 报错 或者字段被静默忽略,handleAfterClose 永不触发(L1)",
+            "fix": "1. 自动关闭后回调:用 `setTimeout(handleAfterClose, duration)`(精度 ~50ms 误差)。2. 手动关闭监听:Message 不支持,换 Toast / Snackbar"
+        },
+        "M3": {
+            "wrong": "调用 `Message.loading('加载中...', 0)` 期望显示 loading 类型",
+            "result": "**Message 没有 loading 静态方法**(只有 info/success/warn/error)——runtime 报 `Message.loading is not a function`(L2)",
+            "fix": "用 `Message.info({ text: '加载中...', icon: <Loading />, close: true }, 0)` workaround(duration=0 + Loading 图标),完成后 `Message.clear()`。或者用真正的 Loading 组件而不是 Message"
+        },
+        "M4": {
+            "wrong": "默认 duration 是 0(永远不自动关闭): `Message.info('已保存')` 期望一直显示",
+            "result": "默认 duration = 5000 ms(自动 5 秒后关闭) —— `Message.info('已保存')` 会 5 秒后消失",
+            "fix": "想永久显示用 `Message.info('已保存', 0)` 或显式传 `0` / 负数 / NaN"
+        },
+        "M5": {
+            "wrong": "用 `Message.config({ duration: 0 })` 永久禁用全局自动关闭,然后期望每次 `Message.info('x')` 不自动消失",
+            "result": "**Message.config 修改的是全局默认值**,生效但 per-call 第 2 参数会覆盖。可以用,但容易和 per-call duration 互相覆盖出 bug",
+            "fix": "per-call 显式传 duration 更直观: `Message.info('x', 0)`。全局 config 适合统一调小默认 duration(如 3000)"
+        }
+    },
+    "completeExample": "// 1. 最基础:字符串简写 + 默认 5 秒自动关闭\nimport Message from '@para-ui/core/Message';\nMessage.info('提交成功');\nMessage.success('保存成功', 3000);  // 3 秒后自动关闭\n\n// 2. 完整对象配置(text + desc + icon)\nMessage.info({\n    text: '操作成功',\n    desc: '订单 #1234 已提交,5 个工作日内处理完成'\n}, 8000);\n\n// 3. 不自动关闭 + 显示关闭按钮\nMessage.warn({\n    text: '需要用户确认',\n    close: true\n}, 0);  // duration=0 不自动关闭\n\n// 4. loading 场景 workaround (L2)\nimport Loading from '@para-ui/icons/Loading';\nMessage.info({\n    text: '上传中...',\n    icon: <Loading />,\n    close: false\n}, 0);  // duration=0 不自动关闭\n// 上传完成后:\nawait uploadFile();\nMessage.clear();\nMessage.success('上传成功', 2000);\n\n// 5. 关闭回调 workaround (L1)\nMessage.info('已保存', 3000);\nsetTimeout(() => onAfterClose(), 3000);  // 自己计时,精度 ~50ms\n\n// 6. 全局配置\nMessage.config({ duration: 3000, maxCount: 3 });  // 后续 Message 默认 3 秒,最多 3 条同显",
+    "do": [
+        "**优先用字符串简写**: `Message.info('提交成功', 3000)` —— 不需要对象时省心",
+        "**duration 永远是第 2 参数**(M1) —— 不要写在 MsgTypeProps 对象里",
+        "**长内容用 text + desc 双字段**,desc 出现时 text 自动加粗",
+        "**永久显示**:传 duration=0 / 负数 / NaN,通常配合 close=true 让用户手动关闭",
+        "**全局默认值调整**:用 Message.config({ duration, maxCount }),只在 app 启动时调一次",
+        "loading 场景:用 info + Loading icon + duration=0 workaround(L2)"
+    ],
+    "dont": [
+        "**不要**把 duration 写在 MsgTypeProps 对象里——是第 2 参数(M1,这是 R23 Message-005 fail 根因)",
+        "**不要**传 onClose / onDismiss 回调——MsgTypeProps 无 callback 字段(M2,L1)",
+        "**不要**调 Message.loading —— 不存在,用 info + icon workaround(M3,L2)",
+        "**不要**假设默认 duration 是 0——默认 5000 ms(M4)",
+        "在 Message 中展示过多文字 / 表单 / 复杂交互 —— 换 Modal",
+        "滥用 error 类型 —— 重要错误应结合页面内错误提示"
+    ],
+    "events": {
+        "info": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "Message.info('操作成功')  — 字符串简写,默认 5000ms 自动关闭",
+                "Message.info({ text: '操作成功', desc: '已保存到草稿' }, 3000)  — 对象配置 + 独立 duration 第 2 参数",
+                "Message.info({ text: '加载中...', icon: <Loading />, close: true }, 0)  — duration=0 不自动关闭,显示关闭按钮"
+            ],
+            "commonMistakes": [
+                "把 duration 写进 MsgTypeProps 对象:Message.info({ text: '成功', duration: 3000 }) → TS2353 报错,duration 不是 MsgTypeProps 字段",
+                "调用 Message.loading() → Message 没有 loading 方法,只有 info/success/warn/error,调用报 'not a function'",
+                "传 onClose/onAfterClose 回调 → MsgTypeProps 无 callback 字段,静默忽略,回调永不触发"
+            ]
+        },
+        "success": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "Message.success('保存成功', 2000)  — 2 秒后自动关闭",
+                "Message.success({ text: '上传完成', desc: '共 3 个文件' })  — 含副描述"
+            ],
+            "commonMistakes": [
+                "假设 success 和 info 签名不同 → 4 种类型签名完全相同,都是 (config, duration?) => void"
+            ]
+        },
+        "warn": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "Message.warn({ text: '需要确认', close: true }, 0)  — 永久显示 + 显示关闭按钮"
+            ],
+            "commonMistakes": [
+                "传 onClose 期望点击关闭按钮后回调 → 不支持 onClose,只能用 setTimeout 模拟"
+            ]
+        },
+        "error": {
+            "signature": "(config: string | MsgTypeProps, duration?: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "Message.error('操作失败,请重试', 8000)  — 错误类型展示 8 秒"
+            ],
+            "commonMistakes": [
+                "假设 error 方法接受 Error 对象 → config 必须是 string 或 MsgTypeProps,需手动取 error.message"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "duration 是 Message.{type}() 的独立第 2 参数,不是 MsgTypeProps 对象的字段",
+            "wrong": "Message.info({ text: '操作成功', duration: 3000 })  // TS2353: 'duration' does not exist in type MsgTypeProps",
+            "right": "Message.info({ text: '操作成功' }, 3000)  // 或 Message.info('操作成功', 3000)"
+        },
+        {
+            "issue": "MsgTypeProps 不含 onClose / onAfterClose / onDismiss 回调字段",
+            "wrong": "Message.success({ text: '已删除', onClose: () => refetch() })  // TS 报错 或 字段静默被忽略",
+            "right": "Message.success('已删除', 3000); setTimeout(() => refetch(), 3000);  // 用 setTimeout 自己计时"
+        },
+        {
+            "issue": "Message 没有 loading 静态方法(只有 info/success/warn/error)",
+            "wrong": "Message.loading('上传中...')  // 运行时 TypeError: Message.loading is not a function",
+            "right": "Message.info({ text: '上传中...', close: false }, 0);  // duration=0 + 用 Message.clear?.() 关闭"
+        },
+        {
+            "issue": "MessageObject 导出的是对象实例,不是 React 组件,不能写 <Message> JSX",
+            "wrong": "import Message from '@para-ui/core/Message'; return <Message type='success' text='ok' />;  // JSX 类型错误",
+            "right": "import { Message } from '@para-ui/core/Message'; Message.success('ok');  // 命令式调用,不是 JSX 渲染"
+        },
+        {
+            "issue": "从 @para-ui/core 直接导入 Message 拿到的是 JSX 组件(默认导出)，不是 MessageObject，所有方法 success/error/info/warn/clear/config 均不存在",
+            "wrong": "import { Message } from '@para-ui/core';  // TS2339: Property 'success' does not exist on type '() => Element'",
+            "right": "import { Message } from '@para-ui/core/Message';  // 子路径导入拿到具名 MessageObject 实例"
+        },
+        {
+            "issue": "MessageObject 接口的 clear 和 config 是可选方法（带 ?），直接调用不加可选链会报 TS2722",
+            "wrong": "Message.clear();   // TS2722: Cannot invoke an object which is possibly 'undefined'\nMessage.config({ duration: 3000 });  // 同上",
+            "right": "Message.clear?.();   // 可选链调用\nMessage.config?.({ duration: 3000 });  // 或先检查: if (Message.config) Message.config({ duration: 3000 })"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Message",
+        "adapter": null
+    }
+}

package/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
+    }
+}