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

package/es/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/es/Pagination/index.js

@@ -1,8 +1,8 @@
 import { j as r } from "../_virtual/jsx-runtime.js";
 import de, { useState as g, useRef as q, useEffect as u, useMemo as w } from "react";
 import xe from "../GlobalContext/index.js";
-import { $prefixCls as z, $rcPrefixCls as he } from "../GlobalContext/constant.js";
-import { TextField as ve } from "../TextField/index.js";
+import { $prefixCls as z, $rcPrefixCls as ve } from "../GlobalContext/constant.js";
+import { TextField as he } from "../TextField/index.js";
 import Pe from "../GlobalContext/useFormatMessage.js";
 import je from "./lang/index.js";
 import be from "../Select/index.js";
@@ -35,7 +35,7 @@ const Oe = (y) => {
     layoutArr: ["jumper", "pageRow", "pager-btn", "sizes", "pager-num"]
   });
   a.current.type = l, a.current.autoType = M, u(() => () => {
-    window.removeEventListener("resize", h), clearTimeout(a.current.timer), clearTimeout(a.current.changePagination);
+    window.removeEventListener("resize", v), clearTimeout(a.current.timer ?? void 0), clearTimeout(a.current.changePagination ?? void 0);
   }, []), u(() => {
     R(S);
   }, [S]), u(() => {
@@ -57,12 +57,12 @@ const Oe = (y) => {
     const e = Math.ceil(m / c);
     Y(e || y.page || 1);
   }, [c, m]), u(() => {
-    l === "complex" && M ? (h(), window.addEventListener("resize", h)) : window.removeEventListener("resize", h);
+    l === "complex" && M ? (v(), window.addEventListener("resize", v)) : window.removeEventListener("resize", v);
   }, [l, M]), u(() => {
-    a.current.type === "complex" && a.current.autoType && h();
+    a.current.type === "complex" && a.current.autoType && v();
   }, [m, c, n, k, W]);
-  const h = () => {
-    clearTimeout(a.current.timer);
+  const v = () => {
+    clearTimeout(a.current.timer ?? void 0);
     const e = x.current;
     e && (e.classList.add(`${z}-pagination-over`), a.current.timer = setTimeout(() => {
       U(a.current.layoutArr.length), a.current.layoutArr.length > 1 && _();
@@ -87,7 +87,7 @@ const Oe = (y) => {
         U(t), t > 3 ? _(t) : x.current.classList.remove(`${z}-pagination-over`);
       } else
         x.current.classList.remove(`${z}-pagination-over`);
-  }, v = (e) => a.current.type instanceof Array && a.current.type.indexOf(e) === -1, P = (e) => {
+  }, h = (e) => a.current.type instanceof Array && a.current.type.indexOf(e) === -1, P = (e) => {
     if (o === null) return !1;
     switch (e) {
       case "jumper":
@@ -144,11 +144,11 @@ const Oe = (y) => {
     const t = /(?=(\B)(\d{3})+$)/g;
     return e.toString().replace(t, ",");
   }, oe = w(() => {
-    if (l === "simple" || v("sizes") || P("sizes"))
+    if (l === "simple" || h("sizes") || P("sizes"))
       return null;
     const e = ae(m);
     return /* @__PURE__ */ r.jsx("div", { className: "total-num pagination-space", children: p({ id: "total" }, { total: e }) });
-  }, [m, k, f, o]), ie = w(() => v("pageRow") || P("pageRow") ? null : /* @__PURE__ */ r.jsx("div", { className: "page-line-memo pagination-space", children: /* @__PURE__ */ r.jsx(
+  }, [m, k, f, o]), ie = w(() => h("pageRow") || P("pageRow") ? null : /* @__PURE__ */ r.jsx("div", { className: "page-line-memo pagination-space", children: /* @__PURE__ */ r.jsx(
     be,
     {
       className: "page-line-select",
@@ -166,7 +166,7 @@ const Oe = (y) => {
   ] }), le = () => /* @__PURE__ */ r.jsxs("div", { className: "jump-next-icon", children: [
     /* @__PURE__ */ r.jsx("span", { children: "..." }),
     /* @__PURE__ */ r.jsx(Ce, {})
-  ] }), ce = () => C !== "num" || l === "simple" ? !0 : l === "complex" ? P("pager-num") : v("pager"), ue = w(() => ce() ? null : /* @__PURE__ */ r.jsxs("div", { className: "pagination-content pagination-space", children: [
+  ] }), ce = () => C !== "num" || l === "simple" ? !0 : l === "complex" ? P("pager-num") : h("pager"), ue = w(() => ce() ? null : /* @__PURE__ */ r.jsxs("div", { className: "pagination-content pagination-space", children: [
     I.indexOf("prev") !== -1 && /* @__PURE__ */ r.jsx("div", { className: "left-page", children: /* @__PURE__ */ r.jsx(
       "div",
       {
@@ -178,7 +178,7 @@ const Oe = (y) => {
     /* @__PURE__ */ r.jsx(
       we,
       {
-        prefixCls: `${he}-pagination`,
+        prefixCls: `${ve}-pagination`,
         current: n,
         pageSize: c,
         total: m,
@@ -196,7 +196,7 @@ const Oe = (y) => {
         children: /* @__PURE__ */ r.jsx(H, {})
       }
     ) })
-  ] }), [m, n, i, c, y.flippingArrow, C, o]), me = () => C === "btn" || l === "simple" ? !1 : l === "complex" ? P("pager-btn") : v("pager"), pe = w(() => me() ? null : /* @__PURE__ */ r.jsxs("div", { className: "pagination-btn-content pagination-space", children: [
+  ] }), [m, n, i, c, y.flippingArrow, C, o]), me = () => C === "btn" || l === "simple" ? !1 : l === "complex" ? P("pager-btn") : h("pager"), pe = w(() => me() ? null : /* @__PURE__ */ r.jsxs("div", { className: "pagination-btn-content pagination-space", children: [
     /* @__PURE__ */ r.jsx(
       G,
       {
@@ -219,10 +219,10 @@ const Oe = (y) => {
         children: p({ id: "nextPage" })
       }
     )
-  ] }), [n, i, C, f, o]), ge = w(() => v("jumper") || P("jumper") ? null : /* @__PURE__ */ r.jsxs("div", { className: "skip-page-memo pagination-space", children: [
+  ] }), [n, i, C, f, o]), ge = w(() => h("jumper") || P("jumper") ? null : /* @__PURE__ */ r.jsxs("div", { className: "skip-page-memo pagination-space", children: [
     /* @__PURE__ */ r.jsx("span", { children: p({ id: "jumpTo" }) }),
     /* @__PURE__ */ r.jsx(
-      ve,
+      he,
       {
         className: "skip-page-text-field",
         size: "large",

package/es/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/es/PasswordRules/index.d.ts

@@ -3,7 +3,7 @@ export interface PasswordRulesConfigItemProps {
     /** 文案 */
     label?: ReactNode;
     /** 正则 正则表达式 */
-    reg?: any;
+    reg?: RegExp;
     /** 自定义校验方法
      *    item: 当前项配置
      *    value: 校验值
@@ -14,7 +14,7 @@ export interface PasswordRulesConfigItemProps {
     validator?: (item: PasswordRulesConfigItemProps, value: string) => boolean | ReactNode;
     /** 校验结果 */
     result?: boolean | ReactNode;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export interface PasswordRulesConfigProps {
     /** 标题 */
@@ -23,7 +23,7 @@ export interface PasswordRulesConfigProps {
     type?: 'icon' | 'order';
     /** 规则列表 */
     list?: PasswordRulesConfigItemProps[];
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export interface PasswordRulesProps {
     /** 样式class */
@@ -43,7 +43,7 @@ export interface PasswordRulesProps {
      * undefined: 未全部通过
      * */
     onCheckAll?: (bol: boolean | undefined) => void;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 declare const PasswordRules: FunctionComponent<PasswordRulesProps>;
 export default PasswordRules;

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

package/es/PopConfirm/index.d.ts

@@ -59,7 +59,7 @@ export interface PopConfirmProps {
     onCountdownFinish?: () => void;
     /** 浮层渲染容器，默认body */
     getPopupContainer?: (triggerNode: HTMLElement) => HTMLElement;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export declare const PopConfirm: FC<PopConfirmProps>;
 export default PopConfirm;