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

package/PageHeader/component.json

@@ -0,0 +1,112 @@
+{
+    "name": "PageHeader",
+    "category": "Navigation",
+    "description": "页头(应用级顶部导航条):左侧 logo/标题 + 中间横向菜单 + 右侧用户/语言/帮助/按钮区",
+    "semantic": {
+        "intent": [
+            "应用顶部导航",
+            "横向菜单展示",
+            "用户/语言/帮助入口聚合"
+        ],
+        "useCases": [
+            "应用主页头",
+            "管理后台顶栏",
+            "工作台首屏"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准页头(横向菜单 + 右侧功能区)"
+        }
+    },
+    "states": [
+        "default"
+    ],
+    "idealProps": {
+        "leftRender": {
+            "type": "ReactNode",
+            "description": "左侧自定义内容(放 logo / 应用标题 / 返回按钮等);**支持纯文本 / 单行 JSX / 多行复合 JSX**(标题+副标题、返回按钮+标题、面包屑+标题、标题+状态彩标);**注意:不是 title / subTitle / backIcon / breadcrumb / onBack prop**(这些 Ant Design PageHeader 命名本组件均不存在,需要时全部组合进 leftRender ReactNode);典型场景见 docs/view/pageHeader/codeString.ts 注释 7a/7b/7c/7d"
+        },
+        "menuListProps": {
+            "type": "MenuListProps",
+            "description": "横向菜单配置对象;MenuListProps = { list?: MenuChildrenProps[]; selectMenu?: string; onClickMenu?: (item: MenuChildrenProps | false) => void; className?: string; moreCustomize?: ReactNode };src/PageHeader/interface.ts:38"
+        },
+        "footerProps": {
+            "type": "FooterProps",
+            "description": "**右侧功能区聚合对象**(放语言切换 / 用户菜单 / 帮助 / 按钮列表 / 自助跳转 / 自定义);FooterProps = { backSelfcareProps?: BackSelfcareProps; languageProps?: LanguageProps; btnListProps?: BtnListProps; userProps?: UserProps; helpProps?: HelpProps; render?: ReactNode; className?: string };**所有右侧功能都在这个对象里嵌套配置,不是顶层独立 prop**;**helpProps 结构同 BackSelfcareProps**(label/icon/render/onClick/className);**render 是「替换」语义**,传入后整个右侧被替换,其他 5 widget 字段都不渲染(无追加模式);src/PageHeader/interface.ts:162"
+        },
+        "selectMenu": {
+            "type": "string",
+            "description": "当前选中菜单(匹配 menuListProps.list[].path);顶层 selectMenu 会下传到 MenuListProps.selectMenu;src/PageHeader/index.tsx:14"
+        },
+        "onClickMenu": {
+            "type": "(item: MenuChildrenProps | false) => void",
+            "description": "菜单点击回调;**回参 item 是 MenuChildrenProps 对象或 false**(false 表示选中态被清空);MenuChildrenProps = { label?, type?, path?, icon?, children?, ... },典型用法 `item.path` 取菜单路径"
+        },
+        "className": {
+            "type": "string",
+            "description": "外层容器样式 class"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "外层容器内联样式"
+        }
+    },
+    "do": [
+        "logo / 应用名放 leftRender",
+        "横向菜单走 menuListProps.list(树形结构通过 children 嵌套)",
+        "右侧功能(语言 / 用户 / 帮助 / 按钮)统一在 footerProps 对象里嵌套配置",
+        "selectMenu 受控 — 父维护 string 匹配 list[].path"
+    ],
+    "dont": [
+        "把 title / subTitle / extra / onBack / backIcon / breadcrumb / footer 当作顶层 prop 传(全部 Ant Design 命名,**本组件均不存在**)",
+        "把右侧功能字段(languageProps / userProps / btnListProps / helpProps / backSelfcareProps)拆到顶层(必须嵌套在 footerProps 对象里)",
+        "在 menuListProps.list[].type 上随意填值(仅支持 'redirect' | 'router' | 'iframe' | 'snack' | 'snackPage' 五种)",
+        "传 footerProps.render 同时配其他 widget 字段(render 是**替换语义**,会覆盖整个右侧,languageProps/userProps 等都不渲染;无追加模式)",
+        "期望 PageHeader 顶层有 bottomRender / footerRender / statsRender / extraBottom 下方内容区(**本组件不支持下方扩展插槽**;如需统计条/标签栏在 PageHeader 外层 div 包装)",
+        "把「标题 + 副标题」/「返回按钮 + 标题」/「面包屑 + 标题」拆成多个顶层 prop(本组件这类复合内容**全部塞进 leftRender ReactNode**;见 docs/view/pageHeader/codeString.ts 注释 7a/7b/7c)"
+    ],
+    "events": {
+        "onClickMenu": {
+            "signature": "(item: MenuChildrenProps | false) => void",
+            "asyncSupported": false,
+            "examples": [
+                "获取路由路径：onClickMenu={(item) => { if (item) navigate(item.path); }}",
+                "清空选中：onClickMenu={(item) => { if (!item) setSelectMenu(''); else setSelectMenu(item.path); }}",
+                "嵌套子菜单点击：回参 item.children 可能有子项，item.path 是当前点击项的路径，非父级路径"
+            ],
+            "commonMistakes": [
+                "假设 item 永远是对象——回参可能是 false（表示选中态被清空），使用前需判断 if (item)",
+                "直接用 item.label 作路由——应用 item.path；item.label 是显示文案",
+                "不更新 selectMenu 导致菜单高亮不同步——onClickMenu 触发后需 setState(item.path) 回写 selectMenu"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "footerProps 内字段不能拆到 PageHeader 顶层，TS 会报未知 prop",
+            "wrong": "<PageHeader userProps={{ label: '张三' }} languageProps={{ ... }} />  // 这些不是顶层 prop",
+            "right": "<PageHeader footerProps={{ userProps: { label: '张三' }, languageProps: { ... } }} />"
+        },
+        {
+            "issue": "MenuChildrenProps.type 是菜单行为类型，有严格枚举，传错值 TS 不会报错但菜单不响应",
+            "wrong": "list={[{ label: '首页', type: 'link', path: '/home' }]}  // 'link' 不在联合类型",
+            "right": "list={[{ label: '首页', type: 'router', path: '/home' }]}  // 合法值: 'redirect' | 'router' | 'iframe' | 'snack' | 'snackPage'"
+        },
+        {
+            "issue": "onClickMenu 回参是 MenuChildrenProps | false，直接访问属性前需判空",
+            "wrong": "onClickMenu={(item) => navigate(item.path)}  // item 可能是 false，访问 .path 会 TypeError",
+            "right": "onClickMenu={(item) => { if (item && item.path) navigate(item.path); }}"
+        },
+        {
+            "issue": "不要从 @para-ui/core 导入 MenuChildrenProps 用于 onClickMenu 类型标注——PageHeader/interface.ts 和 Menu/interface.ts 各有一个同名 MenuChildrenProps，两者互不兼容，强行标注会导致 TS2322",
+            "wrong": "import { PageHeader, MenuChildrenProps } from '@para-ui/core';\nonClickMenu={(item: MenuChildrenProps | false) => ...}  // MenuChildrenProps 来自 Menu 不来自 PageHeader，类型冲突",
+            "right": "import { PageHeader } from '@para-ui/core';\n// 不标注类型，让 TS 推断，或使用 Parameters<typeof PageHeader>[0]['onClickMenu']\nonClickMenu={(item) => { if (item && item.path) navigate(item.path); }}"
+        }
+    ],
+    "mapping": {
+        "realComponent": "PageHeader",
+        "adapter": null
+    }
+}

package/Pagination/component.json

@@ -0,0 +1,181 @@
+{
+    "name": "Pagination",
+    "category": "Navigation",
+    "description": "分页组件，支持 simple / complex 双模式及自定义布局组合",
+    "semantic": {
+        "intent": [
+            "展示数据",
+            "分批加载",
+            "导航"
+        ],
+        "useCases": [
+            "数据列表",
+            "搜索结果",
+            "评论区"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "simple": {
+            "meaning": "简单模式（仅翻页按钮/数字页码）"
+        },
+        "complex": {
+            "meaning": "复杂模式（含总数 + 每页行数 + 页码 + 跳转）"
+        }
+    },
+    "states": [
+        "default",
+        "disabled"
+    ],
+    "idealProps": {
+        "total": {
+            "type": "number",
+            "default": 0,
+            "description": "数据总数"
+        },
+        "page": {
+            "type": "number",
+            "default": 1,
+            "description": "当前页码(受控)"
+        },
+        "rowsPerPage": {
+            "type": "number[]",
+            "default": [10, 20, 50, 100],
+            "description": "每页行数候选项列表(下拉选项)"
+        },
+        "currentRowsPerPage": {
+            "type": "number",
+            "default": 10,
+            "description": "当前选中的每页行数"
+        },
+        "type": {
+            "type": "enum",
+            "values": [
+                "simple",
+                "complex",
+                "PaginationLayout[]"
+            ],
+            "default": "simple",
+            "description": "分页类型;**'simple'** = 仅翻页按钮/数字(sizes/pageRow/jumper 均不显示);**'complex'** = 完整布局(总数+每页行数+页码+跳转,支持 autoType 响应式收叠);**PaginationLayout[]** = 自定义组合，合法值 'sizes'|'pageRow'|'pager'|'jumper'"
+        },
+        "pagerType": {
+            "type": "enum",
+            "values": [
+                "btn",
+                "num"
+            ],
+            "default": "num",
+            "description": "页码显示模式 btn=上下页按钮 / num=数字页码列表"
+        },
+        "flippingArrow": {
+            "type": "PaginationFlippingArrow[]",
+            "values": [
+                "prev",
+                "next"
+            ],
+            "default": ["prev", "next"],
+            "description": "方向键 layout;传空数组隐藏全部箭头"
+        },
+        "autoType": {
+            "type": "boolean",
+            "default": true,
+            "description": "type=complex 自适应模式(响应宽度自动收叠)"
+        },
+        "resizeLine": {
+            "type": "string | number",
+            "description": "type=complex 时重新计算换行(传值变化触发自适应)"
+        },
+        "pageMaxLimit": {
+            "type": "boolean",
+            "default": true,
+            "description": "当前页超过总页数时自动回落到最大页"
+        },
+        "skipFunc": {
+            "type": "function",
+            "signature": "(num?: number, skipValue?: number) => void",
+            "description": "回车跳页回调；num 是校正后目标页（已 clamp 到 1~totalPage），skipValue 是输入框原始值（未校正）"
+        },
+        "changePage": {
+            "type": "function",
+            "signature": "(num?: number) => void",
+            "description": "页码改变回调（点击页码 / prev / next / 回车跳转时均触发）；num 是目标页码"
+        },
+        "changeRowsPerPage": {
+            "type": "function",
+            "signature": "(num: number) => void",
+            "description": "每页行数改变回调；num 是新选中行数（非下标，是实际数值）"
+        },
+        "getPopupContainer": {
+            "type": "function",
+            "description": "rowsPerPage 下拉的渲染父节点 (triggerNode) => HTMLElement"
+        },
+        "className": {
+            "type": "string",
+            "description": "自定义类名（src/Pagination/index.tsx:33 interface 实证，追加到根容器 div）"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "自定义样式（src/Pagination/index.tsx:35 interface 实证，透传到根容器 div）"
+        }
+    },
+    "do": [
+        "Table 独立分页时：changePage 里更新父组件 page state 并重新请求数据，将最新 page 回传给 Pagination 维持受控",
+        "展示总记录数 + 每页行数切换：使用 type='complex'，changeRowsPerPage 里同时重置 page=1 再发请求",
+        "在数据量较大时使用服务端分页——本地分页仅适合 <200 条",
+        "保持每页数量适中（10-50）"
+    ],
+    "dont": [
+        "在极少量数据（<20）时使用 Pagination",
+        "隐藏当前页码标识",
+        "changePage/changeRowsPerPage 里不更新父组件 page state——Pagination 是受控组件，不回写 page prop 会导致翻页后页码回弹"
+    ],
+    "events": {
+        "changePage": {
+            "signature": "(num?: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控翻页：changePage={(num) => { setPage(num ?? 1); fetchData(num ?? 1, currentRowsPerPage); }}",
+                "配合 Table：changePage={(num) => { tableRef.current.reload({ page: num }); }}",
+                "防止 undefined：changePage={(num) => setPage(num ?? 1)}  // num 在正常翻页时有值，极端情况下可能 undefined"
+            ],
+            "commonMistakes": [
+                "收到 changePage 后不更新 page prop——Pagination 是受控组件，不回写会导致页码状态不一致",
+                "期望 changePage 在组件内部状态已更新后触发——组件内部先 setPageCom(num) 再触发 changePage，父组件需自行维护独立的 page state",
+                "changeRowsPerPage 里忘记重置 page=1——切换每页条数后通常应回到第一页"
+            ]
+        },
+        "changeRowsPerPage": {
+            "signature": "(num: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "切换每页行数并重置页码：changeRowsPerPage={(num) => { setCurrentRowsPerPage(num); setPage(1); fetchData(1, num); }}",
+                "受控写法：currentRowsPerPage={currentRowsPerPage} changeRowsPerPage={(num) => setCurrentRowsPerPage(num)}"
+            ],
+            "commonMistakes": [
+                "忘记同步更新 currentRowsPerPage prop——不回写 prop 导致下拉显示旧值",
+                "假设 num 是下标而非实际行数值——num 是 rowsPerPage 数组里选中的那个数字本身"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "type prop 接受 PaginationLayout[] 数组，但内部枚举是 'sizes'|'pageRow'|'pager'|'jumper'，不是 'complex'|'simple'",
+            "wrong": "type={['simple', 'pager']}  // 'simple' 不在 PaginationLayout 联合类型",
+            "right": "type={['pager', 'jumper']}  // 自定义布局组合只能用 PaginationLayout 枚举值"
+        },
+        {
+            "issue": "changeRowsPerPage 回参 num 是 number，不是可选 number | undefined",
+            "wrong": "(num?: number) => setCurrentRowsPerPage(num ?? 10)  // 多余的 ?? 语法噪音",
+            "right": "(num: number) => setCurrentRowsPerPage(num)  // num 保证有值"
+        },
+        {
+            "issue": "skipFunc 与 changePage 在回车跳页时都会触发，不要做重复请求",
+            "wrong": "skipFunc={(num) => fetchData(num)} changePage={(num) => fetchData(num)}  // 回车时两个都触发，重复请求",
+            "right": "// 只需 changePage 处理翻页逻辑；skipFunc 是可选补充，跳页专用（例如记录跳转日志）"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Pagination",
+        "adapter": null
+    }
+}

package/PasswordRules/component.json

@@ -0,0 +1,105 @@
+{
+    "name": "PasswordRules",
+    "category": "Data Display",
+    "description": "密码规则校验器，实时显示密码强度及各项规则通过/失败状态",
+    "semantic": {
+        "intent": [
+            "密码验证",
+            "规则提示",
+            "安全引导"
+        ],
+        "useCases": [
+            "注册",
+            "修改密码",
+            "安全设置"
+        ],
+        "riskLevel": "high"
+    },
+    "variants": {
+        "icon": {
+            "meaning": "图标模式（✓/✗ 图标指示每条规则）"
+        },
+        "order": {
+            "meaning": "序列模式（1. 2. 3. 数字序号）"
+        }
+    },
+    "states": [
+        "pass",
+        "fail"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "string",
+            "description": "需要校验的密码值；每次 value 变化组件自动重新对所有规则校验并触发 onCheckAll"
+        },
+        "config": {
+            "type": "PasswordRulesConfigProps | PasswordRulesConfigProps[]",
+            "description": "规则配置，单组或多组。**PasswordRulesConfigProps** = { title?: ReactNode; type?: 'icon'|'order'; list?: PasswordRulesConfigItemProps[] }；**PasswordRulesConfigItemProps** = { label?: ReactNode; reg?: RegExp（正则校验）; validator?: (item, value) => boolean | ReactNode（自定义校验，返回 true 表示通过，false 或 ReactNode 表示失败，ReactNode 会替换显示文案）; result?: boolean | ReactNode }；⚠️ validator 优先级高于 reg"
+        },
+        "onCheckAll": {
+            "type": "(bol: boolean | undefined) => void",
+            "description": "全部规则校验结果回调：**true** = 所有规则全部通过；**false** = 所有规则全部未通过；**undefined** = 部分通过（非全通过也非全失败）；value 为 undefined 时也回调 undefined"
+        },
+        "boxShadow": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否带有边框阴影（src/PasswordRules/index.tsx:51 interface 实证）"
+        },
+        "className": {
+            "type": "string",
+            "description": "自定义类名"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "自定义样式"
+        }
+    },
+    "do": [
+        "在密码输入旁实时显示校验结果——value 受控绑定 TextField 的 onChange",
+        "列出所有规则及其状态，配合 onCheckAll 控制提交按钮的 disabled 状态（true 时才允许提交）",
+        "使用 validator 函数处理复杂规则（如「密码不能包含用户名」），返回 ReactNode 可自定义失败文案",
+        "多组规则（如「格式要求」+「强度要求」）传 config 数组，每组可设置独立 title"
+    ],
+    "dont": [
+        "规则不明确——每条 label 应简短描述具体要求（如「至少 8 位字符」）",
+        "规则过于复杂导致用户无法满足——不超过 6 条主要规则",
+        "只用 reg 不提供 validator——复杂规则如「必须包含大小写」建议用 validator 加更友好的提示"
+    ],
+    "events": {
+        "onCheckAll": {
+            "signature": "(bol: boolean | undefined) => void",
+            "asyncSupported": false,
+            "examples": [
+                "控制提交按钮：onCheckAll={(bol) => setCanSubmit(bol === true)}",
+                "显示强度文案：onCheckAll={(bol) => setStrengthText(bol === true ? '强' : bol === false ? '弱' : '中')}",
+                "value 为空时 onCheckAll(undefined)：onCheckAll={(bol) => { if (bol === undefined) { clearStrengthUI(); return; } setValid(bol); }}"
+            ],
+            "commonMistakes": [
+                "把 bol === false 当「有错误」——false 是「全部失败」；undefined 才是「部分通过」（最常见的进行时状态）",
+                "用 onCheckAll 直接控制表单 submit——建议只用它更新 UI 状态，表单提交时再做一次完整校验",
+                "假设 value 初始化时不触发 onCheckAll——组件 mount 后 value 变化（包括 undefined→string）每次都触发"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "PasswordRulesConfigItemProps.validator 返回值类型是 boolean | ReactNode，不能返回 string 以外的 falsy",
+            "wrong": "validator: (item, value) => value.length >= 8  // 返回 false 表示失败，符合要求",
+            "right": "validator: (item, value) => value.length >= 8 ? true : false  // 显式返回 boolean；返回 ReactNode 可自定义失败文案"
+        },
+        {
+            "issue": "config 可以是单对象或数组，直接传数组字面量时类型推断正确，动态构建时需显式标注",
+            "wrong": "const cfg = { title: '格式', list: [...] }; <PasswordRules config={cfg} />  // 单对象 ok\nconst cfgs = [cfg1, cfg2]; <PasswordRules config={cfgs} />  // 数组 ok，但动态 push 时注意类型",
+            "right": "const cfgs: PasswordRulesConfigProps[] = [cfg1, cfg2]; <PasswordRules config={cfgs} />"
+        },
+        {
+            "issue": "onCheckAll 回参 bol 是三值逻辑，用 === 严格比较而非 truthy/falsy",
+            "wrong": "onCheckAll={(bol) => setValid(!!bol)}  // undefined 被 coerce 成 false，与「全部失败」混淆",
+            "right": "onCheckAll={(bol) => setValid(bol === true)}  // 只有全部通过才为 true"
+        }
+    ],
+    "mapping": {
+        "realComponent": "PasswordRules",
+        "adapter": null
+    }
+}

package/PopConfirm/component.json

@@ -0,0 +1,227 @@
+{
+    "name": "PopConfirm",
+    "category": "Feedback",
+    "description": "点击元素，弹出气泡确认框，用于危险操作二次确认",
+    "semantic": {
+        "intent": [
+            "二次确认",
+            "防止误操作",
+            "轻量级确认"
+        ],
+        "useCases": [
+            "删除操作",
+            "风险操作",
+            "状态变更"
+        ],
+        "riskLevel": "high"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "visible",
+        "hidden",
+        "loading"
+    ],
+    "idealProps": {
+        "title": {
+            "type": "string | ReactNode",
+            "description": "确认框标题（src/Popconfirm/index.tsx:117 `title && <div>` 实证：未传时不渲染标题区域）"
+        },
+        "content": {
+            "type": "string | ReactNode",
+            "description": "确认框正文内容（src/Popconfirm/index.tsx:119 `content && <div>` 实证：独立于 title 渲染，支持 ReactNode）"
+        },
+        "onOk": {
+            "type": "function",
+            "signature": "() => void",
+            "description": "点击确认按钮的回调（src/Popconfirm/index.tsx:63 `handleOk` → `onOk?.()` 实证）。签名是 `() => void`，**不接收参数**。⚠️ onOk 调用后组件会自动调 handleClose 关闭弹框（非受控模式下）"
+        },
+        "onCancel": {
+            "type": "function",
+            "signature": "() => void",
+            "description": "点击取消按钮的回调（src/Popconfirm/index.tsx:60 `handleCancel` → `onCancel?.()` 实证）。签名是 `() => void`，**不接收参数**。onCancel 调用后同样会自动 handleClose"
+        },
+        "okText": {
+            "type": "string",
+            "default": "确定",
+            "description": "确认按钮文字（src/Popconfirm/index.tsx:170 `okText ?? intl({id:'ok'})` 实证，未传时使用 i18n 默认值）"
+        },
+        "cancelText": {
+            "type": "string",
+            "default": "取消",
+            "description": "取消按钮文字（src/Popconfirm/index.tsx:158 `cancelText ?? intl({id:'cancel'})` 实证）"
+        },
+        "okButtonProps": {
+            "type": "object",
+            "objectShape": {
+                "disabled": { "type": "boolean", "description": "禁用确认按钮" },
+                "loading": { "type": "boolean", "description": "确认按钮 loading 状态" },
+                "variant": { "type": "'contained' | 'outlined' | 'text'", "description": "按钮样式变体" },
+                "size": { "type": "'small' | 'medium' | 'large'", "description": "按钮尺寸" }
+            },
+            "description": "确认按钮属性（ButtonProps 子集）。⚠️ okButtonDanger=true 时 danger 样式优先级高于 okButtonProps.danger（src:168 `danger={okButtonDanger ?? okButtonProps?.danger}` 实证）"
+        },
+        "trigger": {
+            "type": "enum",
+            "values": [
+                "click",
+                "hover"
+            ],
+            "default": "click",
+            "description": "触发方式（src/Popconfirm/index.tsx:82 解构默认值 'click' 实证）"
+        },
+        "type": {
+            "type": "enum",
+            "values": ["success", "info", "error", "warning"],
+            "default": "warning",
+            "description": "图标类型（src/Popconfirm/index.tsx:83 解构默认 'warning' 实证，`iconMapping` 字典按 type 取对应 icon）"
+        },
+        "open": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否显示弹框（受控，需配合 controllable=true 才生效）。src:175 `controllable && setInOpen(open)` 实证：**单独传 open 不生效——必须同时传 controllable={true}**"
+        },
+        "controllable": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否启用受控模式（src:73 `!controllable` 判断实证）。true 时内部不自动切换 inOpen，完全由 open prop 控制；false(默认) 时为非受控，点击确定/取消自动关闭"
+        },
+        "showCancel": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示取消按钮（src:152-160 `showCancel &&` 实证）"
+        },
+        "okButtonDanger": {
+            "type": "boolean",
+            "default": false,
+            "description": "确认按钮是否显示危险(红色)样式（src:168 优先级高于 okButtonProps.danger）"
+        },
+        "countdown": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否启用确认按钮倒计时（src:92-112 useEffect 实证）。倒计时进行时确认按钮 disabled，倒计时结束自动解除。搭配 countdownTime 设置时长"
+        },
+        "countdownTime": {
+            "type": "number",
+            "default": 5,
+            "description": "倒计时时长（秒，src:88 解构默认值 5 实证）。countdown=true 时生效"
+        },
+        "onClose": {
+            "type": "function",
+            "signature": "() => void",
+            "description": "弹框关闭回调（src:66-72 `handleClose` → `onClose?.()` 实证）。**非受控模式下**：确定/取消/点击外部都会触发 onClose。受控模式（controllable=true）下不触发自动关闭流程"
+        },
+        "onCountdownFinish": {
+            "type": "function",
+            "signature": "() => void",
+            "description": "倒计时完成回调（src:100 `onCountdownFinish?.()` 实证）。countdown=true 时，倒计时到 0 触发"
+        },
+        "placement": {
+            "type": "enum",
+            "values": ["top", "bottom", "left", "right", "top-start", "top-end", "bottom-start", "bottom-end"],
+            "default": "top-start",
+            "description": "弹框弹出位置（src:89 解构默认 'top-start' 实证，透传给 Tooltip placement）"
+        }
+    },
+    "do": [
+        "在执行不可逆或高风险操作前使用 PopConfirm",
+        "提供明确的标题和内容描述（title + content 分层，title 是主判断，content 是补充说明）",
+        "高危操作（如删除）使用 okButtonDanger={true} 突出危险样式，提示用户谨慎操作",
+        "需要强制用户读完提示再确认时使用 countdown={true}，配合 countdownTime 控制等待时长",
+        "受控模式必须 controllable={true} + open={state} 配合使用，单独传 open 无效"
+    ],
+    "dont": [
+        "滥用 PopConfirm 导致用户疲劳（非关键操作不应确认）",
+        "在 PopConfirm 中放置过多复杂内容（应使用 Modal）",
+        "不要假设 onOk/onCancel 有参数——签名是 `() => void`，无参数（src 实证）",
+        "不要单独传 open={true} 而不传 controllable={true}——非受控模式下 open prop 被忽略（src:175 实证）",
+        "不要在 actions 自定义底部按钮后还期望 onOk/onCancel 被触发——传了 actions 时默认按钮区域被完全替换"
+    ],
+    "events": {
+        "onOk": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "点击确认按钮触发，非受控模式下弹框自动关闭",
+                "高危删除操作：onOk 内调 deleteItem(id) 执行删除逻辑",
+                "配合 okButtonDanger={true}：onOk 显示红色按钮，用户点击后执行危险操作"
+            ],
+            "commonMistakes": [
+                "假设 onOk 接收参数（如 event）→ 签名是 () => void，无参数（src:63-65 `onOk?.()` 实证）",
+                "在 onOk 内调 setOpen(false) 手动关闭 → 非受控模式下 handleOk 已自动调 handleClose 关闭，无需手动干预",
+                "假设 async onOk 能自动等待 → PopConfirm 不支持 asyncSupported，onOk 不 await，调用立即返回"
+            ]
+        },
+        "onCancel": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "点击取消按钮触发，弹框自动关闭",
+                "onCancel 内重置临时状态（如清空输入框）",
+                "showCancel=false 时 onCancel 不会被触发（取消按钮不显示）"
+            ],
+            "commonMistakes": [
+                "假设 onCancel 接收 event 参数 → 签名是 () => void（src:60-62 `onCancel?.()` 实证）",
+                "把 onCancel 和 onClose 混用 → onCancel 只绑定取消按钮，onClose 在任何关闭路径后触发",
+                "传 showCancel={false} 后仍期望 onCancel 触发 → 按钮不渲染，用户无法点击触发"
+            ]
+        },
+        "onClose": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "非受控模式下，确定/取消/点击外部都会触发 onClose",
+                "用于清理弹框关闭后的状态（如重置 loading 标志）",
+                "受控模式（controllable=true）下由业务方手动控制 open，onClose 作为通知回调"
+            ],
+            "commonMistakes": [
+                "受控模式下期望 onClose 自动关闭弹框 → controllable=true 时 handleClose 内 setInOpen 不被调用，需业务方 setOpen(false)",
+                "假设 onClose 和 onCancel 是同一个 → onClose 是统一关闭通知，onCancel 只绑取消按钮",
+                "非受控下在 onOk 内又调 setOpen(false) 与 onClose 重复 → 非受控模式已自动关闭"
+            ]
+        },
+        "onCountdownFinish": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "countdown=true 倒计时到 0 时触发，此时确认按钮解禁",
+                "用于记录用户是否耐心等待完整倒计时（埋点场景）",
+                "倒计时完成后触发提示音或动画"
+            ],
+            "commonMistakes": [
+                "仅传 onCountdownFinish 而未传 countdown={true} → countdown=false 时不会启动计时，回调不触发",
+                "假设倒计时完成后弹框自动关闭 → onCountdownFinish 只是通知，不自动关闭，需在回调内手动处理",
+                "假设倒计时单位是毫秒 → countdownTime 单位是秒（src:88 默认值 5 = 5秒）"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "onOk / onCancel 的类型声明是 Function，不是具体签名，直接用 any 会丢类型安全",
+            "wrong": "onOk={(val: any) => doDelete(val)}  // onOk 无参数，val 永远是 undefined",
+            "right": "onOk={() => doDelete(id)}  // 正确：() => void，id 从外部闭包获取"
+        },
+        {
+            "issue": "受控模式需同时传 controllable={true}，单独传 open 无效",
+            "wrong": "<PopConfirm open={isOpen} onClose={() => setIsOpen(false)} />  // open 被忽略，非受控模式",
+            "right": "<PopConfirm open={isOpen} controllable={true} onClose={() => setIsOpen(false)} />"
+        },
+        {
+            "issue": "type 枚举控制图标，不接受 'danger' 等非法值",
+            "wrong": "<PopConfirm type='danger' />  // 'danger' 不在枚举里，iconMapping 会取 undefined",
+            "right": "<PopConfirm type='error' okButtonDanger={true} />  // 危险操作：type='error' 图标 + okButtonDanger 红色按钮"
+        },
+        {
+            "issue": "countdown 倒计时单位是秒，不是毫秒",
+            "wrong": "<PopConfirm countdown={true} countdownTime={3000} />  // 3000 秒 = 50 分钟，几乎不会结束",
+            "right": "<PopConfirm countdown={true} countdownTime={3} />  // 3 秒倒计时"
+        }
+    ],
+    "mapping": {
+        "realComponent": "PopConfirm",
+        "adapter": null
+    }
+}