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

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;

package/es/PopConfirm/index.js

@@ -1,9 +1,9 @@
 import { j as e } from "../_virtual/jsx-runtime.js";
 import { useRef as N, useState as b, useMemo as _, useEffect as k } from "react";
-import { CheckCircleF as ee } from "../node_modules/@para-ui/icons/CheckCircleF/index.js";
-import { WarningCircle as ne } from "../node_modules/@para-ui/icons/WarningCircle/index.js";
-import { CloseCircleF as oe } from "../node_modules/@para-ui/icons/CloseCircleF/index.js";
-import { WarningCircleF as se } from "../node_modules/@para-ui/icons/WarningCircleF/index.js";
+import { CheckCircleF as ee } from "../para-ui-core/node_modules/@para-ui/icons/CheckCircleF/index.js";
+import { WarningCircle as ne } from "../para-ui-core/node_modules/@para-ui/icons/WarningCircle/index.js";
+import { CloseCircleF as oe } from "../para-ui-core/node_modules/@para-ui/icons/CloseCircleF/index.js";
+import { WarningCircleF as se } from "../para-ui-core/node_modules/@para-ui/icons/WarningCircleF/index.js";
 import { Button as P } from "../Button/index.js";
 import { Tooltip as re } from "../Tooltip/index.js";
 import t from "clsx";
@@ -48,7 +48,7 @@ const ae = {
     onCountdownFinish: G,
     getPopupContainer: H,
     ...K
-  } = T, x = te("PopConfirm", ie), h = N(), L = ce(h, H), [p, f] = b(!1), r = N(), [d, j] = b(g), v = _(() => s && d >= 1, [s, d]);
+  } = T, x = te("PopConfirm", ie), h = N(null), L = ce(h, H), [p, f] = b(!1), r = N(), [d, j] = b(g), v = _(() => s && d >= 1, [s, d]);
   k(() => (s && (p ? (j(g), r.current = setInterval(() => {
     j((n) => n <= 1 ? (G?.(), clearInterval(r.current), 0) : n - 1);
   }, 1e3)) : clearInterval(r.current)), () => {

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

@@ -1,7 +1,7 @@
 import { j as n } from "../_virtual/jsx-runtime.js";
 import s from "clsx";
 import I from "react";
-import { $prefixCls as m } from "../GlobalContext/constant.js";
+import { $prefixCls as c } from "../GlobalContext/constant.js";
 import { Popover as S } from "../Popover/index.js";
 import { usePopMenuContext as $, PopMenuProvider as k } from "./context.js";
 import { useComponentWidth as w } from "./hooks.js";
@@ -9,7 +9,7 @@ import './index.css';/* empty css           */
 import E from "./list.js";
 const L = (l) => {
   const {
-    overlayClassName: u,
+    overlayClassName: m,
     data: f,
     children: i,
     menuClassName: d,
@@ -21,19 +21,19 @@ const L = (l) => {
     onClick: g,
     path: P,
     ...e
-  } = l, { width: j, ref: M } = w([i]), a = I.useRef(), { handle: p, menuIndex: N } = $(), R = () => {
+  } = l, { width: j, ref: M } = w([i]), a = I.useRef(null), { handle: p, menuIndex: N } = $(), R = () => {
     const o = [], r = { list: [] };
     return f.forEach((t) => {
       typeof t == "object" && t !== null && "list" in t ? o.push(t) : r.list.push(t);
-    }), r.list?.length && o.push(r), /* @__PURE__ */ n.jsx(n.Fragment, { children: o.map((t, c) => /* @__PURE__ */ n.jsx(
+    }), r.list?.length && o.push(r), /* @__PURE__ */ n.jsx(n.Fragment, { children: o.map((t, u) => /* @__PURE__ */ n.jsx(
       E,
       {
         direction: e.direction,
         list: t.list,
-        className: s(d, { "pop-menu-separator": c !== o.length - 1 }),
+        className: s(d, { "pop-menu-separator": u !== o.length - 1 }),
         style: h
       },
-      c
+      u
     )) });
   }, b = () => e.placement ? e.placement : e.direction === "right" ? "bottomLeft" : "bottomRight";
   return /* @__PURE__ */ n.jsx(
@@ -63,7 +63,7 @@ const L = (l) => {
           ...e,
           isPopover: !0,
           ref: a,
-          overlayClassName: s(`${m}-pop-menu`, u),
+          overlayClassName: s(`${c}-pop-menu`, m),
           overlayInnerStyle: { minWidth: j, ...e.overlayInnerStyle },
           content: R(),
           placement: b(),
@@ -71,7 +71,7 @@ const L = (l) => {
             "div",
             {
               ref: M,
-              className: s(`${m}-pop-menu-content`, y),
+              className: s(`${c}-pop-menu-content`, y),
               style: v,
               children: i
             }

package/es/PopMenu/item.js

@@ -4,7 +4,7 @@ import I from "react";
 import { $prefixCls as V } from "../GlobalContext/constant.js";
 import { usePopMenuContext as k } from "./context.js";
 import { PopMenu as y } from "./index.js";
-import { Right as M } from "../node_modules/@para-ui/icons/Right/index.js";
+import { Right as M } from "../para-ui-core/node_modules/@para-ui/icons/Right/index.js";
 import w from "../AutoTips/index.js";
 import { Tooltip as P } from "../Tooltip/index.js";
 import R from "../Help/index.js";

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

@@ -6,7 +6,7 @@ import P from "../GlobalContext/usePopupContainer.js";
 import g from "clsx";
 import './index.css';/* empty css           */
 const m = l.forwardRef((o, t) => {
-  const { title: n, content: s, ...c } = o, e = l.useRef(), u = P(e, o.getPopupContainer);
+  const { title: n, content: s, ...c } = o, e = l.useRef(null), u = P(e, o.getPopupContainer);
   v(() => {
     t && (typeof t == "function" ? t(e.current) : t.current = e.current);
   }, [e.current]);