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

package/lib/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/lib/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;

package/lib/PopConfirm/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const e=require("../_virtual/jsx-runtime.js"),s=require("react"),Y=require("../node_modules/@para-ui/icons/CheckCircleF/index.js"),Z=require("../node_modules/@para-ui/icons/WarningCircle/index.js"),ee=require("../node_modules/@para-ui/icons/CloseCircleF/index.js"),ne=require("../node_modules/@para-ui/icons/WarningCircleF/index.js"),b=require("../Button/index.js"),se=require("../Tooltip/index.js"),i=require("clsx"),te=require("../GlobalContext/useFormatMessage.js"),oe=require("./lang/index.js"),f=require("../GlobalContext/constant.js"),re=require("../GlobalContext/usePopupContainer.js");;/* empty css            */const ie={success:e.jsxRuntimeExports.jsx(Y.CheckCircleF,{}),warning:e.jsxRuntimeExports.jsx(ne.WarningCircleF,{}),error:e.jsxRuntimeExports.jsx(ee.CloseCircleF,{}),info:e.jsxRuntimeExports.jsx(Z.WarningCircle,{})},q=w=>{const{trigger:N="click",type:k="warning",title:t,content:c,description:j,icon:P,okText:$,cancelText:T,onOk:y,onCancel:B,okButtonProps:a,cancelButtonProps:F,placement:I="top-start",className:O,overlayClassName:M,style:S,children:_,open:l=!1,controllable:u=!1,showCancel:z=!0,bubble:W=!0,okButtonDanger:D,countdown:o,countdownTime:C=5,actions:V,onClose:p,onCountdownFinish:A,getPopupContainer:G,...H}=w,g=te.default("PopConfirm",oe.default),R=s.useRef(),J=re.default(R,G),[x,m]=s.useState(!1),r=s.useRef(),[d,h]=s.useState(C),E=s.useMemo(()=>o&&d>=1,[o,d]);s.useEffect(()=>(o&&(x?(h(C),r.current=setInterval(()=>{h(n=>n<=1?(A?.(),clearInterval(r.current),0):n-1)},1e3)):clearInterval(r.current)),()=>{clearInterval(r.current)}),[x,o]);const K=()=>{B?.(),v()},L=()=>{y?.(),v()},v=()=>{u||(m(!1),p?.())},Q=n=>{u?l&&p?.():(m(n),n||p?.())};s.useEffect(()=>{u&&m(l)},[l]);const U=()=>{const n=e.jsxRuntimeExports.jsxs(e.jsxRuntimeExports.Fragment,{children:[z&&e.jsxRuntimeExports.jsx(b.Button,{className:`${f.$prefixCls}-popconfirm-btn`,onClick:K,variant:"outlined",size:"small",...F,children:T??g({id:"cancel"})}),e.jsxRuntimeExports.jsx(b.Button,{className:`${f.$prefixCls}-popconfirm-btn`,onClick:L,variant:"contained",size:"small",...a,danger:D??a?.danger,disabled:E?!0:a?.disabled,children:E?`${d}s`:$??g({id:"ok"})})]});return e.jsxRuntimeExports.jsxs("div",{className:i("popconfirm-wrapper"),style:S,onClick:X=>{W||X.stopPropagation()},children:[e.jsxRuntimeExports.jsxs("div",{className:"popconfirm-message",children:[e.jsxRuntimeExports.jsx("span",{className:"popconfirm-message-icon",children:P||ie[k]}),e.jsxRuntimeExports.jsxs("div",{className:"popconfirm-message-body",children:[t&&e.jsxRuntimeExports.jsx("div",{className:"popconfirm-message-title",children:t}),c&&e.jsxRuntimeExports.jsx("div",{className:i("popconfirm-message-content",t?"":"without-title"),children:c}),j&&e.jsxRuntimeExports.jsx("div",{className:i("popconfirm-message-description",t||c?"":"without-title-or-content"),children:j})]})]}),e.jsxRuntimeExports.jsx("div",{className:"popconfirm-btns",children:V??n})]})};return e.jsxRuntimeExports.jsx(se.Tooltip,{...H,ref:R,trigger:N,open:x,arrow:!1,placement:I,title:U(),onVisibleChange:Q,overlayClassName:i(`${f.$prefixCls}-popconfirm`,M,O),getPopupContainer:J,children:_})};exports.PopConfirm=q;exports.default=q;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const e=require("../_virtual/jsx-runtime.js"),s=require("react"),Y=require("../para-ui-core/node_modules/@para-ui/icons/CheckCircleF/index.js"),Z=require("../para-ui-core/node_modules/@para-ui/icons/WarningCircle/index.js"),ee=require("../para-ui-core/node_modules/@para-ui/icons/CloseCircleF/index.js"),ne=require("../para-ui-core/node_modules/@para-ui/icons/WarningCircleF/index.js"),b=require("../Button/index.js"),se=require("../Tooltip/index.js"),i=require("clsx"),te=require("../GlobalContext/useFormatMessage.js"),oe=require("./lang/index.js"),f=require("../GlobalContext/constant.js"),re=require("../GlobalContext/usePopupContainer.js");;/* empty css            */const ie={success:e.jsxRuntimeExports.jsx(Y.CheckCircleF,{}),warning:e.jsxRuntimeExports.jsx(ne.WarningCircleF,{}),error:e.jsxRuntimeExports.jsx(ee.CloseCircleF,{}),info:e.jsxRuntimeExports.jsx(Z.WarningCircle,{})},q=w=>{const{trigger:N="click",type:k="warning",title:t,content:c,description:j,icon:P,okText:$,cancelText:T,onOk:y,onCancel:B,okButtonProps:a,cancelButtonProps:F,placement:I="top-start",className:O,overlayClassName:M,style:S,children:_,open:l=!1,controllable:u=!1,showCancel:z=!0,bubble:W=!0,okButtonDanger:D,countdown:o,countdownTime:C=5,actions:V,onClose:p,onCountdownFinish:A,getPopupContainer:G,...H}=w,g=te.default("PopConfirm",oe.default),R=s.useRef(null),J=re.default(R,G),[x,m]=s.useState(!1),r=s.useRef(),[d,h]=s.useState(C),E=s.useMemo(()=>o&&d>=1,[o,d]);s.useEffect(()=>(o&&(x?(h(C),r.current=setInterval(()=>{h(n=>n<=1?(A?.(),clearInterval(r.current),0):n-1)},1e3)):clearInterval(r.current)),()=>{clearInterval(r.current)}),[x,o]);const K=()=>{B?.(),v()},L=()=>{y?.(),v()},v=()=>{u||(m(!1),p?.())},Q=n=>{u?l&&p?.():(m(n),n||p?.())};s.useEffect(()=>{u&&m(l)},[l]);const U=()=>{const n=e.jsxRuntimeExports.jsxs(e.jsxRuntimeExports.Fragment,{children:[z&&e.jsxRuntimeExports.jsx(b.Button,{className:`${f.$prefixCls}-popconfirm-btn`,onClick:K,variant:"outlined",size:"small",...F,children:T??g({id:"cancel"})}),e.jsxRuntimeExports.jsx(b.Button,{className:`${f.$prefixCls}-popconfirm-btn`,onClick:L,variant:"contained",size:"small",...a,danger:D??a?.danger,disabled:E?!0:a?.disabled,children:E?`${d}s`:$??g({id:"ok"})})]});return e.jsxRuntimeExports.jsxs("div",{className:i("popconfirm-wrapper"),style:S,onClick:X=>{W||X.stopPropagation()},children:[e.jsxRuntimeExports.jsxs("div",{className:"popconfirm-message",children:[e.jsxRuntimeExports.jsx("span",{className:"popconfirm-message-icon",children:P||ie[k]}),e.jsxRuntimeExports.jsxs("div",{className:"popconfirm-message-body",children:[t&&e.jsxRuntimeExports.jsx("div",{className:"popconfirm-message-title",children:t}),c&&e.jsxRuntimeExports.jsx("div",{className:i("popconfirm-message-content",t?"":"without-title"),children:c}),j&&e.jsxRuntimeExports.jsx("div",{className:i("popconfirm-message-description",t||c?"":"without-title-or-content"),children:j})]})]}),e.jsxRuntimeExports.jsx("div",{className:"popconfirm-btns",children:V??n})]})};return e.jsxRuntimeExports.jsx(se.Tooltip,{...H,ref:R,trigger:N,open:x,arrow:!1,placement:I,title:U(),onVisibleChange:Q,overlayClassName:i(`${f.$prefixCls}-popconfirm`,M,O),getPopupContainer:J,children:_})};exports.PopConfirm=q;exports.default=q;
 //# sourceMappingURL=index.js.map

package/lib/PopMenu/component.json

@@ -0,0 +1,131 @@
+{
+    "name": "PopMenu",
+    "category": "Navigation",
+    "description": "下拉级联菜单，支持分组、子菜单嵌套和受控选中态，基于 Popover 实现",
+    "semantic": {
+        "intent": [
+            "更多操作",
+            "收纳命令",
+            "选择"
+        ],
+        "useCases": [
+            "操作栏更多",
+            "导航菜单",
+            "过滤器"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准下拉菜单"
+        }
+    },
+    "states": [
+        "visible",
+        "hidden"
+    ],
+    "idealProps": {
+        "data": {
+            "type": "PopMenuListItemProps[] | PopMenuGroupItemProps[]",
+            "description": "菜单数据源；**PopMenuListItemProps** = { name: string（必填，唯一 key）; title?: string（显示文案）; disabled?: boolean; disabledTip?: string; help?: string; render?: (handle: IPopMenuHandler) => ReactElement（自定义渲染）; onClick?: (name, item?, path?) => void; children?: PopMenuListItemProps[]（子菜单）}；**PopMenuGroupItemProps** = { list: PopMenuListItemProps[] }（用于分组，混合传时未分组项自动聚合到末尾组）"
+        },
+        "direction": {
+            "type": "enum",
+            "values": ["left", "right"],
+            "default": "left",
+            "description": "弹出方向；left=右侧展开（默认 placement=bottomRight）；right=左侧展开（默认 placement=bottomLeft）"
+        },
+        "onChange": {
+            "type": "(value: TPopMenuValue) => void",
+            "description": "选中项变化时的回调；**TPopMenuValue = string[]**（选中路径数组）；每次点击叶子节点时触发"
+        },
+        "onClick": {
+            "type": "(name: string, item?: PopMenuListItemProps, path?: string[]) => void",
+            "description": "点击菜单项时的回调；name=当前项的 name 字段；path=从根到当前项的 name 路径数组（不含当前项）"
+        },
+        "value": {
+            "type": "TPopMenuValue",
+            "description": "当前选中的菜单路径数组（受控）；**TPopMenuValue = string[]**；每个元素是对应层级的 name 值"
+        },
+        "children": {
+            "type": "ReactNode",
+            "description": "触发浮层的目标节点（包裹在内层 div 里，ref 由 PopMenu 内部管理，可传任意 ReactNode）"
+        },
+        "menuClassName": {
+            "type": "string",
+            "description": "菜单列表容器的自定义 className（src/PopMenu/index.tsx:28 interface 实证）"
+        },
+        "menuStyle": {
+            "type": "React.CSSProperties",
+            "description": "菜单列表容器的自定义样式"
+        },
+        "contentClassName": {
+            "type": "string",
+            "description": "触发节点外层 div 的自定义 className"
+        },
+        "contentStyle": {
+            "type": "React.CSSProperties",
+            "description": "触发节点外层 div 的自定义样式"
+        }
+    },
+    "do": [
+        "收纳低频操作——标准场景传 data 数组，每项必须有 name 字段（唯一 key）",
+        "Label 简短清晰，子菜单层级不超过 2 层",
+        "危险操作通过 PopMenuListItemProps.disabled + disabledTip 做防误操作提示",
+        "需要自定义菜单项（如带图标/颜色）时用 render 函数，形参 handle.closeMenu() 可手动关闭浮层"
+    ],
+    "dont": [
+        "Dropdown 层级过深 (>2)——嵌套层级过多用户迷失，超过 2 层改用 Modal 表单",
+        "Dropdown 内放置过度复杂的表单",
+        "用数组下标作为 name——name 用于选中值追踪，必须全局唯一字符串"
+    ],
+    "events": {
+        "onClick": {
+            "signature": "(name: string, item?: PopMenuListItemProps, path?: string[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "基本点击：onClick={(name, item) => { handleAction(name); }}",
+                "获取完整路径：onClick={(name, item, path) => { console.log([...path, name]); }}  // path 是父级 name 数组，不含当前",
+                "自定义渲染中关闭浮层：render={(handle) => <div onClick={() => { doAction(); handle.closeMenu(); }}>自定义项</div>}"
+            ],
+            "commonMistakes": [
+                "期望 onClick 在父节点（有 children 的项）点击时触发——有子菜单的节点展开子菜单，不触发 onClick；只有叶子节点触发",
+                "用 item.name 做显示文案——显示文案是 item.title；item.name 是唯一 key",
+                "假设 path 包含当前节点——path 只包含父级路径，不含当前点击项；完整路径是 [...path, name]"
+            ]
+        },
+        "onChange": {
+            "signature": "(value: TPopMenuValue) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控选中：onChange={(val) => setValue(val)}",
+                "value 是 string[]，如 ['group1', 'item2'] 表示选中了 group1 下的 item2"
+            ],
+            "commonMistakes": [
+                "假设 value 是单个字符串——TPopMenuValue = string[]，即使只有一级也是数组",
+                "onClick 和 onChange 重复处理同一逻辑——onClick 含 name+item+path 更精细；onChange 只有路径数组"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "data 中每个 item 的 name 字段必填（string），缺少会导致选中态追踪失效",
+            "wrong": "data={[{ title: '编辑' }, { title: '删除' }]}  // 缺少 name 字段，TS 报错",
+            "right": "data={[{ name: 'edit', title: '编辑' }, { name: 'delete', title: '删除' }]}"
+        },
+        {
+            "issue": "TPopMenuValue 是 string[]，value 和 onChange 的类型都是数组，不是单个字符串",
+            "wrong": "value='edit' onChange={(val: string) => setValue(val)}  // 类型不匹配",
+            "right": "value={['edit']} onChange={(val: string[]) => setValue(val)}"
+        },
+        {
+            "issue": "PopMenuListItemProps.render 的形参是 IPopMenuHandler 对象，不是 React event",
+            "wrong": "render={(e) => <div onClick={() => e.preventDefault()}>...</div>}  // e 不是事件",
+            "right": "render={(handle) => <div onClick={() => { doAction(); handle.closeMenu(); }}>...</div>}  // handle.closeMenu() 关闭浮层"
+        }
+    ],
+    "mapping": {
+        "realComponent": "PopMenu",
+        "adapter": null
+    }
+}

package/lib/PopMenu/hooks.d.ts

@@ -1,5 +1,5 @@
 import { default as React } from 'react';
-export declare const useComponentWidth: (efts: any[]) => {
+export declare const useComponentWidth: (efts: React.DependencyList) => {
     width: number;
     ref: React.RefObject<HTMLDivElement>;
 };

package/lib/PopMenu/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const n=require("../_virtual/jsx-runtime.js"),r=require("clsx"),S=require("react"),m=require("../GlobalContext/constant.js"),I=require("../Popover/index.js"),d=require("./context.js"),$=require("./hooks.js");;/* empty css            */const k=require("./list.js"),l=u=>{const{overlayClassName:x,data:h,children:i,menuClassName:f,menuStyle:v,contentClassName:j,contentStyle:y,value:C,onChange:g,onClick:P,path:R,...e}=u,{width:q,ref:M}=$.useComponentWidth([i]),c=S.useRef(),{handle:a,menuIndex:E}=d.usePopMenuContext(),N=()=>{const o=[],s={list:[]};return h.forEach(t=>{typeof t=="object"&&t!==null&&"list"in t?o.push(t):s.list.push(t)}),s.list?.length&&o.push(s),n.jsxRuntimeExports.jsx(n.jsxRuntimeExports.Fragment,{children:o.map((t,p)=>n.jsxRuntimeExports.jsx(k.default,{direction:e.direction,list:t.list,className:r(f,{"pop-menu-separator":p!==o.length-1}),style:v},p))})},b=()=>e.placement?e.placement:e.direction==="right"?"bottomLeft":"bottomRight";return n.jsxRuntimeExports.jsx(d.PopMenuProvider,{value:{menuIndex:E+1,path:R||[],direction:e.direction||"left",props:u,value:C||[],onChange:g||(()=>{}),onClick:P||(()=>{}),handle:{closeMenu:()=>{typeof e?.visible>"u"&&(c?.current?.close(),a&&a?.closeMenu?.())}}},children:n.jsxRuntimeExports.jsx(I.Popover,{...e,isPopover:!0,ref:c,overlayClassName:r(`${m.$prefixCls}-pop-menu`,x),overlayInnerStyle:{minWidth:q,...e.overlayInnerStyle},content:N(),placement:b(),children:n.jsxRuntimeExports.jsx("div",{ref:M,className:r(`${m.$prefixCls}-pop-menu-content`,j),style:y,children:i})})})};l.displayName="PopMenu";exports.PopMenu=l;exports.default=l;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const n=require("../_virtual/jsx-runtime.js"),r=require("clsx"),S=require("react"),m=require("../GlobalContext/constant.js"),I=require("../Popover/index.js"),d=require("./context.js"),$=require("./hooks.js");;/* empty css            */const k=require("./list.js"),l=u=>{const{overlayClassName:x,data:h,children:i,menuClassName:f,menuStyle:v,contentClassName:j,contentStyle:y,value:C,onChange:g,onClick:P,path:R,...e}=u,{width:q,ref:M}=$.useComponentWidth([i]),c=S.useRef(null),{handle:a,menuIndex:E}=d.usePopMenuContext(),N=()=>{const o=[],s={list:[]};return h.forEach(t=>{typeof t=="object"&&t!==null&&"list"in t?o.push(t):s.list.push(t)}),s.list?.length&&o.push(s),n.jsxRuntimeExports.jsx(n.jsxRuntimeExports.Fragment,{children:o.map((t,p)=>n.jsxRuntimeExports.jsx(k.default,{direction:e.direction,list:t.list,className:r(f,{"pop-menu-separator":p!==o.length-1}),style:v},p))})},b=()=>e.placement?e.placement:e.direction==="right"?"bottomLeft":"bottomRight";return n.jsxRuntimeExports.jsx(d.PopMenuProvider,{value:{menuIndex:E+1,path:R||[],direction:e.direction||"left",props:u,value:C||[],onChange:g||(()=>{}),onClick:P||(()=>{}),handle:{closeMenu:()=>{typeof e?.visible>"u"&&(c?.current?.close(),a&&a?.closeMenu?.())}}},children:n.jsxRuntimeExports.jsx(I.Popover,{...e,isPopover:!0,ref:c,overlayClassName:r(`${m.$prefixCls}-pop-menu`,x),overlayInnerStyle:{minWidth:q,...e.overlayInnerStyle},content:N(),placement:b(),children:n.jsxRuntimeExports.jsx("div",{ref:M,className:r(`${m.$prefixCls}-pop-menu-content`,j),style:y,children:i})})})};l.displayName="PopMenu";exports.PopMenu=l;exports.default=l;
 //# sourceMappingURL=index.js.map

package/lib/PopMenu/item.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const t=require("../_virtual/jsx-runtime.js"),p=require("clsx"),E=require("react"),v=require("../GlobalContext/constant.js"),N=require("./context.js"),M=require("./index.js"),I=require("../node_modules/@para-ui/icons/Right/index.js"),V=require("../AutoTips/index.js"),_=require("../Tooltip/index.js"),k=require("../Help/index.js"),y=s=>{const{title:x,children:o,disabled:m}=s,{direction:u,props:r,handle:a,menuIndex:c,value:h,onChange:j,path:i,onClick:f}=N.usePopMenuContext(),[R,g]=E.useState(!1),C=()=>t.jsxRuntimeExports.jsx("div",{className:"item-arrow",children:t.jsxRuntimeExports.jsx(I.Right,{})}),b=h?.[c],q=(e,l)=>{if(l){a.closeMenu();const n=[...i];n[c]=e.name,j(n),e.onClick&&e.onClick(e.name,e,i),f?.(e.name,e,i)}},d=(e,l)=>{if(e.render)return e?.render(a);{const n=t.jsxRuntimeExports.jsxs(t.jsxRuntimeExports.Fragment,{children:[t.jsxRuntimeExports.jsx(V.default,{children:x}),e.help&&t.jsxRuntimeExports.jsx(k.default,{className:"item-help",title:e.help}),o?C():null]});return e.disabled?t.jsxRuntimeExports.jsx(_.Tooltip,{title:e.disabledTip,disabled:e.disabled,className:"pop-menu-item",children:t.jsxRuntimeExports.jsx("div",{className:"pop-menu-item pop-menu-item-disabled",children:n})}):t.jsxRuntimeExports.jsx("div",{className:p("pop-menu-item",{"pop-menu-item-select":b===e.name},{"pop-menu-item-hover":R}),onClick:()=>q(e,l),children:n})}};return o&&!m?t.jsxRuntimeExports.jsx(M.PopMenu,{...r,data:o,placement:u==="right"?"right-start":"left-start",className:p(`${v.$prefixCls}-pop-menu-item-content`,r.contentClassName),overlayInnerStyle:{minWidth:"auto",...r.overlayInnerStyle},contentClassName:"item-content",offset:[u==="right"?4:-4,-5],path:[...i,s.name],onVisibleChange:e=>{r.onVisibleChange?.(e),g(e)},children:d(s,!1)}):d(s,!0)};exports.default=y;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const t=require("../_virtual/jsx-runtime.js"),p=require("clsx"),E=require("react"),v=require("../GlobalContext/constant.js"),N=require("./context.js"),M=require("./index.js"),I=require("../para-ui-core/node_modules/@para-ui/icons/Right/index.js"),V=require("../AutoTips/index.js"),_=require("../Tooltip/index.js"),k=require("../Help/index.js"),y=s=>{const{title:x,children:o,disabled:m}=s,{direction:u,props:r,handle:a,menuIndex:c,value:h,onChange:j,path:i,onClick:f}=N.usePopMenuContext(),[R,g]=E.useState(!1),C=()=>t.jsxRuntimeExports.jsx("div",{className:"item-arrow",children:t.jsxRuntimeExports.jsx(I.Right,{})}),b=h?.[c],q=(e,l)=>{if(l){a.closeMenu();const n=[...i];n[c]=e.name,j(n),e.onClick&&e.onClick(e.name,e,i),f?.(e.name,e,i)}},d=(e,l)=>{if(e.render)return e?.render(a);{const n=t.jsxRuntimeExports.jsxs(t.jsxRuntimeExports.Fragment,{children:[t.jsxRuntimeExports.jsx(V.default,{children:x}),e.help&&t.jsxRuntimeExports.jsx(k.default,{className:"item-help",title:e.help}),o?C():null]});return e.disabled?t.jsxRuntimeExports.jsx(_.Tooltip,{title:e.disabledTip,disabled:e.disabled,className:"pop-menu-item",children:t.jsxRuntimeExports.jsx("div",{className:"pop-menu-item pop-menu-item-disabled",children:n})}):t.jsxRuntimeExports.jsx("div",{className:p("pop-menu-item",{"pop-menu-item-select":b===e.name},{"pop-menu-item-hover":R}),onClick:()=>q(e,l),children:n})}};return o&&!m?t.jsxRuntimeExports.jsx(M.PopMenu,{...r,data:o,placement:u==="right"?"right-start":"left-start",className:p(`${v.$prefixCls}-pop-menu-item-content`,r.contentClassName),overlayInnerStyle:{minWidth:"auto",...r.overlayInnerStyle},contentClassName:"item-content",offset:[u==="right"?4:-4,-5],path:[...i,s.name],onVisibleChange:e=>{r.onVisibleChange?.(e),g(e)},children:d(s,!1)}):d(s,!0)};exports.default=y;
 //# sourceMappingURL=item.js.map

package/lib/Popover/component.json

@@ -0,0 +1,165 @@
+{
+    "name": "Popover",
+    "category": "Data Display",
+    "description": "点击/鼠标移入元素，弹出气泡式的卡片浮层，支持标题+内容的富内容承载",
+    "semantic": {
+        "intent": [
+            "展示详情",
+            "复杂操作",
+            "承载内容"
+        ],
+        "useCases": [
+            "用户信息卡片",
+            "复杂筛选配置",
+            "帮助文档预览"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "visible",
+        "hidden"
+    ],
+    "idealProps": {
+        "content": {
+            "type": "ReactNode",
+            "description": "卡片内容主体"
+        },
+        "title": {
+            "type": "string | ReactNode",
+            "description": "卡片标题。**不传时浮层不渲染标题区**（无空白占位）；如需仅展示 content，省略 title 即可"
+        },
+        "children": {
+            "type": "ReactElement",
+            "description": "**触发浮层的目标节点**——必须是『单一可接收 ref 的 React 元素』（rc-tooltip 内部约束，需挂 ref 监听事件）。传 string / Fragment / 多个并列节点会导致 ref 挂载失败、触发不生效。当业务方接到 ReactNode 类型的 trigger 节点（可能是字符串 / Fragment / 数组）时，外层包一层 `<span style={{ display: 'inline-block' }}>` 兜底"
+        },
+        "placement": {
+            "type": "enum",
+            "values": [
+                "top",
+                "left",
+                "right",
+                "bottom",
+                "topLeft",
+                "topRight",
+                "bottomLeft",
+                "bottomRight",
+                "leftTop",
+                "leftBottom",
+                "rightTop",
+                "rightBottom"
+            ],
+            "default": "bottom",
+            "description": "弹出位置（src/Popover/index.tsx:65 实证默认 `bottom`，非 `top`）"
+        },
+        "trigger": {
+            "type": "enum",
+            "values": [
+                "hover",
+                "focus",
+                "click",
+                "contextMenu"
+            ],
+            "default": "click",
+            "description": "触发行为。`contextMenu` 时由内部 rc-tooltip 自动 preventDefault 浏览器原生右键菜单。**仅支持单值，不支持数组形式**——多种触发需用受控模式（visible + onVisibleChange + 业务方自行监听多种事件）"
+        },
+        "visible": {
+            "type": "boolean",
+            "default": false,
+            "description": "**控制显示（受控，src 真实主名）**——Popover 继承 TooltipProps，src/Tooltip/index.tsx:25 取 `visible ?? open`，visible 优先。新代码任选其一；不要同时传。**受控语义**：传 visible 后 Popover 完全受控，用户的 click / hover / contextMenu 不会自动切换内部 state，仅触发 onVisibleChange 让父组件决定是否改 visible（请求改变 vs 直接改变）"
+        },
+        "open": {
+            "type": "boolean",
+            "default": false,
+            "description": "`visible` 的别名（antd 风格）"
+        },
+        "onVisibleChange": {
+            "type": "function",
+            "signature": "(visible: boolean) => void",
+            "description": "**显示隐藏回调（src 真实事件名是 onVisibleChange，不是 onOpenChange）**。受控时仍会被调用——表示父组件应改变 visible；非受控时由 Popover 内部 state 切换并同时回调"
+        },
+        "arrow": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否显示箭头（src/Popover/index.tsx:69 实证默认 `false`，非 `true`）"
+        },
+        "getPopupContainer": {
+            "type": "function",
+            "signature": "(triggerNode: HTMLElement) => HTMLElement",
+            "description": "指定弹层的挂载容器（src/Tooltip/interface.tsx:41 实证，Popover 继承 TooltipProps）。默认挂载到 body；传入函数返回目标 DOM 节点可实现局部定位（如 Modal 内的 Popover 挂载到 Modal 容器，避免层叠问题）。**函数在浮层首次展示时调用**，须确保此时目标 DOM 已挂载"
+        },
+        "mouseEnterDelay": {
+            "type": "number",
+            "default": 0.1,
+            "description": "鼠标移入后弹出延迟（单位：秒，src/Popover/index.tsx:67 defaultProps 实证默认 0.1）。`trigger='hover'` 时生效；设为 0 则立即弹出"
+        },
+        "mouseLeaveDelay": {
+            "type": "number",
+            "default": 0.1,
+            "description": "鼠标移出后消失延迟（单位：秒，src/Popover/index.tsx:68 defaultProps 实证默认 0.1）。`trigger='hover'` 时生效；用于防止鼠标从 trigger 移至浮层时浮层闪烁消失"
+        },
+        "defaultVisible": {
+            "type": "boolean",
+            "default": false,
+            "description": "⚠️ **非受控初始可见性**（rc-tooltip prop，src/Popover/index.tsx:193 defaultProps 实证默认 false）。与 `visible`/`open` 互斥——传 `visible` 后为受控模式，`defaultVisible` 失效。**仅控制首次渲染时的初始展开状态**，之后由 trigger 事件驱动内部 state，父组件无需管理"
+        }
+    },
+    "do": [
+        "当内容较多或包含交互（如按钮、链接）时使用 Popover",
+        "提供清晰的关闭方式（如果不是 hover 触发）",
+        "**children 必须是单一可接收 ref 的 React 元素**：`<Button>` / `<span>` / 自定义 forwardRef 组件均可；传业务接到的 ReactNode 时外层包 `<span style={{display:'inline-block'}}>` 兜底",
+        "**省略 title 不渲染标题区**（无空白占位）；只展示 content 时直接不传 title 即可（覆盖『无标题快速详情』场景）",
+        "**右键菜单场景**：`trigger='contextMenu'`，内部自动 preventDefault；可配合 `visible + onVisibleChange` 实现『点击菜单项后关闭浮层』",
+        "**外部按钮控制显隐**：用 `visible + onVisibleChange` 受控；trigger prop 决定 onVisibleChange 被调用的时机（hover/click/contextMenu）",
+        "**纯受控 + 任意 trigger 时父组件应忽略 onVisibleChange 请求**(DEFECT-001)：trigger 缺 'none' / 'manual' 选项，纯受控场景下用户点击/悬停/右键仍触发 onVisibleChange — 父组件直接保留 visible state 不响应即可，不要主动反向 setState；不需要交互时通过 unmount 完全屏蔽"
+    ],
+    "dont": [
+        "仅用于展示简单文本（应使用 Tooltip）",
+        "弹出层级过深或遮挡关键信息",
+        "**不要给 children 传字符串 / Fragment / 数组**——rc-tooltip 内部约束需挂 ref 监听事件，非元素 children 会让触发失效；如必须传 ReactNode，外层包 inline-block span",
+        "**不要传 `onOpenChange`**——src 真实事件名是 `onVisibleChange`，传 onOpenChange 不会触发任何回调",
+        "**不要给 trigger 传数组**（如 `['click', 'contextMenu']`）——src 类型仅单值字符串联合；多种触发用受控模式自行监听",
+        "不要假设传 visible 后 trigger 仍会切换内部 state——受控模式下 trigger 仅决定 onVisibleChange 被调用的时机，由父组件决定是否真改 visible"
+    ],
+    "events": {
+        "onVisibleChange": {
+            "signature": "(visible: boolean) => void",
+            "asyncSupported": false,
+            "examples": [
+                "非受控监听：onVisibleChange={(v) => console.log('浮层', v ? '展开' : '收起')}",
+                "受控开关：visible={open} onVisibleChange={(v) => setOpen(v)}",
+                "点击浮层内关闭按钮后同步状态：onVisibleChange={(v) => { if (!v) setOpen(false); }}"
+            ],
+            "commonMistakes": [
+                "事件名写成 onOpenChange——Popover 的事件名是 onVisibleChange，onOpenChange 不会触发",
+                "受控时在 onVisibleChange 里 setState(false) 来关闭——可行，但若 trigger='click' 则点击外部也会触发关闭，需确保 state 正确响应",
+                "同时传 visible 和 open——visible 优先，二者同时传会造成混乱，任选其一"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "trigger 不支持数组，只支持单字符串联合类型",
+            "wrong": "trigger={['click', 'hover']}  // TS 类型报错，src 仅支持单值",
+            "right": "trigger='click'  // 单一触发；需多种触发时用 visible + onVisibleChange 受控模式"
+        },
+        {
+            "issue": "onVisibleChange 事件名——src 真实字段名，不是 antd v5 的 onOpenChange",
+            "wrong": "onOpenChange={(v) => setOpen(v)}  // 不会触发，TS 可能不报错（spread 透传），但无效果",
+            "right": "onVisibleChange={(v) => setOpen(v)}"
+        },
+        {
+            "issue": "children 须是单一 ReactElement，传 string 或 Fragment 导致触发失效且无 TS 报错",
+            "wrong": "// TS 接受 ReactNode，但 rc-tooltip 运行时挂 ref 失败：\n<Popover content={...}>{someStringOrFragment}</Popover>",
+            "right": "<Popover content={...}><span style={{ display: 'inline-block' }}>{someStringOrFragment}</span></Popover>"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Popover",
+        "adapter": null
+    }
+}

package/lib/Popover/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"),i=require("react"),f=require("../Tooltip/index.js"),u=require("../GlobalContext/constant.js"),v=require("../GlobalContext/usePopupContainer.js"),d=require("clsx");;/* empty css            */const o=i.forwardRef((s,r)=>{const{title:n,content:l,...p}=s,e=i.useRef(),x=v.default(e,s.getPopupContainer);i.useEffect(()=>{r&&(typeof r=="function"?r(e.current):r.current=e.current)},[e.current]);const m=c=>!n&&!l?null:t.jsxRuntimeExports.jsxs(t.jsxRuntimeExports.Fragment,{children:[n&&t.jsxRuntimeExports.jsx("div",{className:`${c}-title`,children:n}),t.jsxRuntimeExports.jsx("div",{className:`${c}-inner-content`,children:l})]}),a=`${u.$rcPrefixCls}-popover`;return t.jsxRuntimeExports.jsx(f.Tooltip,{...p,isPopover:!0,prefixCls:a,overlayClassName:d(`${u.$prefixCls}-popover`,s.overlayClassName),ref:e,title:m(a),transitionName:`${u.$rcPrefixCls}-popover-zoom-big`,getPopupContainer:x})});o.displayName="Popover";o.defaultProps={placement:"bottom",trigger:"click",mouseEnterDelay:.1,mouseLeaveDelay:.1,arrow:!1};exports.Popover=o;exports.default=o;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const t=require("../_virtual/jsx-runtime.js"),i=require("react"),f=require("../Tooltip/index.js"),u=require("../GlobalContext/constant.js"),v=require("../GlobalContext/usePopupContainer.js"),d=require("clsx");;/* empty css            */const o=i.forwardRef((s,r)=>{const{title:n,content:l,...p}=s,e=i.useRef(null),x=v.default(e,s.getPopupContainer);i.useEffect(()=>{r&&(typeof r=="function"?r(e.current):r.current=e.current)},[e.current]);const m=c=>!n&&!l?null:t.jsxRuntimeExports.jsxs(t.jsxRuntimeExports.Fragment,{children:[n&&t.jsxRuntimeExports.jsx("div",{className:`${c}-title`,children:n}),t.jsxRuntimeExports.jsx("div",{className:`${c}-inner-content`,children:l})]}),a=`${u.$rcPrefixCls}-popover`;return t.jsxRuntimeExports.jsx(f.Tooltip,{...p,isPopover:!0,prefixCls:a,overlayClassName:d(`${u.$prefixCls}-popover`,s.overlayClassName),ref:e,title:m(a),transitionName:`${u.$rcPrefixCls}-popover-zoom-big`,getPopupContainer:x})});o.displayName="Popover";o.defaultProps={placement:"bottom",trigger:"click",mouseEnterDelay:.1,mouseLeaveDelay:.1,arrow:!1};exports.Popover=o;exports.default=o;
 //# sourceMappingURL=index.js.map