@para-ui/core 5.0.0-beta.11 → 5.0.0-beta.13

package/lib/Title/component.json

@@ -0,0 +1,156 @@
+{
+    "name": "Title",
+    "category": "Data Display",
+    "description": "区块标题组件，支持图标、副标题、帮助提示、链接和可折叠内容区",
+    "semantic": {
+        "intent": [
+            "标题展示",
+            "区块标识",
+            "内容折叠"
+        ],
+        "useCases": [
+            "卡片标题",
+            "模块标题",
+            "页面标题",
+            "带折叠的配置区"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认无图标样式（显示左侧竖线 ink 装饰）"
+        },
+        "withIcon": {
+            "meaning": "带图标样式（传 icon prop 后替换左侧竖线，size 生效）"
+        },
+        "collapsible": {
+            "meaning": "可折叠样式（传 collapseContent 或 children 后变为可展开/折叠区）"
+        }
+    },
+    "states": [
+        "default",
+        "collapsed",
+        "expanded"
+    ],
+    "idealProps": {
+        "title": {
+            "type": "ReactNode",
+            "description": "主标题文字，必须传",
+            "required": true
+        },
+        "subTitle": {
+            "type": "ReactNode",
+            "description": "副标题（显示在主标题右侧，支持超长 AutoTips 截断）"
+        },
+        "icon": {
+            "type": "ReactNode",
+            "description": "自定义图标（显示在标题左侧，替换默认竖线装饰；传入时 size prop 生效）"
+        },
+        "collapseContent": {
+            "type": "ReactNode",
+            "description": "可折叠内容区，传入后标题右侧显示展开/折叠箭头；与 children 二选一（children 优先级高于 collapseContent）"
+        },
+        "titleTooltip": {
+            "type": "ReactNode",
+            "description": "标题旁的帮助提示内容，显示 ? 图标，hover 展示内容",
+            "required": false
+        },
+        "titoleTooltipIcon": {
+            "type": "ReactNode",
+            "description": "⚠️ typo：prop 名是 titoleTooltipIcon（原码如此），自定义帮助提示图标节点",
+            "required": false
+        },
+        "link": {
+            "type": "{ href: string; text: ReactNode; target?: string; onClick?: React.MouseEventHandler<HTMLElement> }",
+            "description": "渲染在标题旁的链接",
+            "objectShape": {
+                "href": { "type": "string", "description": "链接地址", "required": true },
+                "text": { "type": "ReactNode", "description": "链接文字", "required": true },
+                "target": { "type": "string", "description": "同 <a> target 属性，如 '_blank'", "required": false },
+                "onClick": { "type": "React.MouseEventHandler<HTMLElement>", "description": "点击链接回调", "required": false }
+            },
+            "required": false
+        },
+        "defaultCollapse": {
+            "type": "boolean",
+            "description": "折叠内容默认是否展开；⚠️ 只有传了 collapseContent 或 children 时才有效",
+            "default": false,
+            "required": false
+        },
+        "placement": {
+            "type": "enum",
+            "values": [
+                "bottom-end", "bottom-start", "bottom",
+                "left-end", "left-start", "left",
+                "right-end", "right-start", "right",
+                "top-end", "top-start", "top"
+            ],
+            "description": "帮助提示方向（titleTooltip 的 Tooltip 弹出方向）",
+            "required": false
+        },
+        "arrow": {
+            "type": "boolean",
+            "description": "帮助提示 Tooltip 是否显示箭头",
+            "required": false
+        },
+        "size": {
+            "type": "enum",
+            "values": ["small", "medium", "large"],
+            "description": "尺寸，仅在传了 icon 时有效（控制图标容器大小）",
+            "default": "medium",
+            "required": false
+        },
+        "collapseClassName": {
+            "type": "string",
+            "description": "折叠容器自定义 className",
+            "required": false
+        }
+    },
+    "do": [
+        "保持标题文字简洁，复杂说明放入 titleTooltip",
+        "有折叠内容区时传 collapseContent 或 children 而非手动实现展开逻辑",
+        "defaultCollapse=true 可让初始态展开（需同时传 collapseContent 或 children）",
+        "link 对象的 target 默认 '_blank'，如需当前页跳转传 target='_self'"
+    ],
+    "dont": [
+        "不要同时传 collapseContent 和 children——组件优先渲染 children（src/Title/index.tsx:164 `children || collapseContent`）",
+        "不要把 size 当通用字体大小控制——size 仅在 icon 存在时控制图标容器，不影响文字大小",
+        "标题文字过长——subTitle 有 AutoTips 截断，但 title 本身不截断，应保持简洁",
+        "层级混乱——嵌套 Title 时保持标题层级与视觉层级一致"
+    ],
+    "events": {
+        "link.onClick": {
+            "signature": "React.MouseEventHandler<HTMLElement>",
+            "asyncSupported": false,
+            "examples": [
+                "link={{ href: '#', text: '查看详情', onClick: (e) => { e.preventDefault(); navigate('/detail'); } }}",
+                "点击链接后进行埋点统计：onClick: (e) => { track('title_link_click'); }"
+            ],
+            "commonMistakes": [
+                "既传 href 又在 onClick 中做跳转——会导致跳转两次，需在 onClick 中 e.preventDefault()",
+                "link.target 不传默认 '_blank'，如需当前页跳转忘记传 target='_self'"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "prop 名 titoleTooltipIcon 有 typo（不是 titleTooltipIcon）",
+            "wrong": "<Title title='设置' titleTooltip='配置说明' titleTooltipIcon={<HelpIcon />} />",
+            "right": "<Title title='设置' titleTooltip='配置说明' titoleTooltipIcon={<HelpIcon />} />  // 注意 titole 而非 title"
+        },
+        {
+            "issue": "defaultCollapse 没传 collapseContent/children 时无效",
+            "wrong": "// 只传 defaultCollapse 没传内容\n<Title title='配置' defaultCollapse={true} />  // 不会显示折叠箭头",
+            "right": "<Title title='配置' defaultCollapse={true} collapseContent={<Form />} />"
+        },
+        {
+            "issue": "children 和 collapseContent 同时传时 children 优先，collapseContent 被忽略",
+            "wrong": "<Title title='配置' collapseContent={<A />}><B /></Title>  // A 组件不会渲染",
+            "right": "// 只传其中一个\n<Title title='配置' collapseContent={<A />} />  // 或 <Title title='配置'><B /></Title>"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Title",
+        "adapter": null
+    }
+}

package/lib/ToggleButton/component.json

@@ -0,0 +1,153 @@
+{
+    "name": "ToggleButton",
+    "category": "Data Entry",
+    "description": "切换按钮，用于单个选中/取消选中操作；ToggleButtonGroup 用于多按钮单选/多选场景",
+    "semantic": {
+        "intent": [
+            "切换选择",
+            "开关",
+            "视图模式切换"
+        ],
+        "useCases": [
+            "视图切换（列表/网格）",
+            "模式选择",
+            "选项卡"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "outlined": {
+            "meaning": "边框样式（默认），有边框的描边按钮"
+        },
+        "text": {
+            "meaning": "文字按钮（无边框），ToggleButtonGroup 中 type='text' 时自动 exclusive=true"
+        },
+        "icon": {
+            "meaning": "纯图标按钮，使用 Button.IconButton 渲染"
+        }
+    },
+    "states": [
+        "selected",
+        "unselected",
+        "disabled"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "T",
+            "description": "按钮绑定的值，点击时通过 onClick 第二参回传；ToggleButtonGroup 通过对比 value 与 group.value 决定 selected 状态"
+        },
+        "selected": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否选中（单独使用时受控）；在 ToggleButtonGroup 内部由 Group 自动计算，不需要手动传"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "不可用状态，阻止点击触发 onClick",
+            "required": false
+        },
+        "width": {
+            "type": "number | string",
+            "description": "按钮宽度",
+            "required": false
+        },
+        "onClick": {
+            "type": "function",
+            "signature": "(event: React.MouseEvent, value: T) => void",
+            "description": "点击回调；⚠️ 第二参 value 是该按钮绑定的 value prop，不是 event.target.value；ToggleButtonGroup 内部会拦截此 prop 替换为 group 逻辑",
+            "required": false
+        },
+        "type": {
+            "type": "enum",
+            "values": ["text", "outlined", "icon"],
+            "default": "outlined",
+            "description": "按钮类型：text=文字按钮（无边框）/ outlined=描边按钮（默认）/ icon=纯图标按钮"
+        },
+        "toolTipTitle": {
+            "type": "ReactNode",
+            "description": "按钮提示文字（hover Tooltip），透传给内部 Button/IconButton",
+            "required": false
+        },
+        "exclusive": {
+            "type": "boolean",
+            "description": "是否单选语义（仅在 ToggleButtonGroup 场景使用；单独使用 ToggleButton 时此 prop 只影响 outlined 样式类名区分）",
+            "required": false
+        }
+    },
+    "subComponents": {
+        "ToggleButtonGroup": {
+            "description": "切换按钮组，管理多个 ToggleButton 的选中状态（单选/多选）",
+            "props": {
+                "data": { "type": "ToggleButtonItemProps<T>[]", "description": "按钮组数据源，每项 { label, value, icon?, selected?, disabled?, toolTipTitle? }" },
+                "value": { "type": "T | T[]", "description": "当前选中值；exclusive=true 时为单值 T，多选时为 T[]" },
+                "exclusive": { "type": "boolean", "default": false, "description": "true=单选模式（选中新项后旧项取消），false=多选模式；⚠️ type='text' 时默认强制 exclusive=true（src/ToggleButton/ToggleButtonGroup.tsx:62）" },
+                "toggleable": { "type": "boolean", "default": true, "description": "exclusive=true 时是否允许取消选中（再次点击已选项恢复未选状态）；toggleable=false 时选中后不能取消" },
+                "onChange": { "type": "(event: React.MouseEvent, value: T | T[] | null) => void", "description": "选中值变化回调；单选取消选中时 value=null（toggleable=true）" },
+                "type": { "type": "enum", "values": ["text", "outlined", "icon"], "default": "outlined", "description": "统一所有子按钮的 type" }
+            }
+        }
+    },
+    "do": [
+        "单选场景使用 ToggleButtonGroup + exclusive=true（或 type='text'）",
+        "多选场景使用 ToggleButtonGroup + value 传数组 + onChange 更新数组",
+        "ToggleButtonGroup 中 data 每项的 value 类型需一致（统一泛型 T）",
+        "type='icon' 时每项 data 需传 icon 字段，label 依然可传（作为 tooltip）"
+    ],
+    "dont": [
+        "选项超过 6 个时避免 ToggleButton 横排——改用 Select 或 RadioGroup",
+        "ToggleButtonGroup 内不要手动传每个 ToggleButton 的 selected——由 Group 自动计算",
+        "不要把 onClick 用于表单提交逻辑——ToggleButton 是展示状态切换的，提交应在父层处理",
+        "不要忽略 exclusive=false（多选）时 value 是数组——onChange 的第二参也是 T[]"
+    ],
+    "events": {
+        "onClick": {
+            "signature": "(event: React.MouseEvent, value: T) => void",
+            "asyncSupported": false,
+            "examples": [
+                "单独使用 ToggleButton：onClick={(e, val) => setSelected(!selected)}",
+                "在 ToggleButtonGroup 内部 onClick 被 Group 拦截，改用 Group 的 onChange",
+                "value 是绑定的 value prop 值（不是 event.target.value）：onClick={(e, val) => console.log(val)}"
+            ],
+            "commonMistakes": [
+                "假设 onClick 第二参是 event.target.value（字符串）——实际是 ToggleButton 的 value prop 值",
+                "在 ToggleButtonGroup 中给子 ToggleButton 传 onClick——Group 内部会覆盖此 prop",
+                "忘记传 selected prop 时单独使用——不传 selected 按钮不显示选中态（默认 false）"
+            ]
+        },
+        "onChange": {
+            "signature": "(event: React.MouseEvent, value: T | T[] | null) => void",
+            "asyncSupported": false,
+            "examples": [
+                "单选模式（exclusive=true）：onChange={(e, val) => setValue(val as T)}",
+                "多选模式：onChange={(e, val) => setValue(val as T[])}",
+                "toggleable=true 且单选时取消选中：value=null，需要 if (val !== null) 判断"
+            ],
+            "commonMistakes": [
+                "单选模式下不处理 value=null——toggleable=true 时点击已选项会传 null",
+                "多选模式下把 value 当 T 而非 T[]——exclusive=false 时 onChange 的 value 是 T[]"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "ToggleButtonGroup 泛型推断问题——value 和 data[].value 类型需一致",
+            "wrong": "// data 的 value 是 string，但 Group.value 传了 number\n<ToggleButtonGroup<string> data={[{label:'A', value:'a'}]} value={1} />",
+            "right": "<ToggleButtonGroup<string> data={[{label:'A', value:'a'}]} value={'a'} onChange={(e,v) => setValue(v as string)} />"
+        },
+        {
+            "issue": "多选模式下 onChange value 类型是 T | T[] | null，需要根据 exclusive 断言",
+            "wrong": "// exclusive=false 但当作单值处理\nonChange={(e, val) => setValue(val as string)}  // val 实际是 string[]",
+            "right": "// exclusive=false 多选\nonChange={(e, val) => setValue(val as string[])}  // 多选时是数组"
+        },
+        {
+            "issue": "type='text' 的 ToggleButtonGroup 默认强制 exclusive=true（src 实证）",
+            "wrong": "// 期望 type='text' + exclusive=false 实现多选文字按钮\n<ToggleButtonGroup type='text' exclusive={false} />  // exclusive 被内部改为 true",
+            "right": "// type='text' 固定单选，多选文字按钮改用 type='outlined' + exclusive={false}"
+        }
+    ],
+    "mapping": {
+        "realComponent": "ToggleButton",
+        "adapter": null
+    }
+}

package/lib/ToggleButton/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const s=require("../_virtual/jsx-runtime.js"),T=require("react"),p=require("../Button/index.js"),b=require("./ToggleButtonGroup.js"),C=require("@paraview/lib"),R=require("clsx"),h=require("../GlobalContext/constant.js"),k=require("../AutoTips/index.js");;/* empty css            */function f(m){const{className:j,style:i,type:e="outlined",children:l,disabled:o=!1,toolTipTitle:u,selected:q=!1,exclusive:$=!1,value:n,width:r,onClick:c,...a}=m,d=T.useRef(C.UUID()).current,t=`${h.$prefixCls}-toggle-button`,x=R(t,j,`toggle-button-${e}`,{[`${t}-${$?"radio":"check"}`]:e==="outlined",[`${t}-selected`]:q,[`${t}-disabled`]:o}),g=B=>{c&&c(B,n)};return e==="icon"?s.jsxRuntimeExports.jsx(p.Button.IconButton,{"data-id":d,...a,variant:"outlined",style:{width:r,...i},className:x,disabled:o,toolTipTitle:u,value:n,onClick:g,children:l}):s.jsxRuntimeExports.jsx(p.Button,{"data-id":d,...a,variant:e==="text"?"text":"outlined",style:{width:r,...i},className:x,disabled:o,toolTipTitle:u,value:n,onClick:g,children:s.jsxRuntimeExports.jsx("span",{className:"toggle-button-text",children:s.jsxRuntimeExports.jsx(k.default,{children:l})})})}exports.ToggleButtonGroup=b.default;exports.ToggleButton=f;exports.default=f;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const s=require("../_virtual/jsx-runtime.js"),T=require("react"),p=require("../Button/index.js"),C=require("./ToggleButtonGroup.js"),R=require("@snack-kit/lib"),$=require("clsx"),h=require("../GlobalContext/constant.js"),k=require("../AutoTips/index.js");;/* empty css            */function f(m){const{className:j,style:i,type:e="outlined",children:l,disabled:o=!1,toolTipTitle:u,selected:q=!1,exclusive:b=!1,value:n,width:r,onClick:c,...a}=m,d=T.useRef(R.UUID()).current,t=`${h.$prefixCls}-toggle-button`,x=$(t,j,`toggle-button-${e}`,{[`${t}-${b?"radio":"check"}`]:e==="outlined",[`${t}-selected`]:q,[`${t}-disabled`]:o}),g=B=>{c&&c(B,n)};return e==="icon"?s.jsxRuntimeExports.jsx(p.Button.IconButton,{"data-id":d,...a,variant:"outlined",style:{width:r,...i},className:x,disabled:o,toolTipTitle:u,value:n,onClick:g,children:l}):s.jsxRuntimeExports.jsx(p.Button,{"data-id":d,...a,variant:e==="text"?"text":"outlined",style:{width:r,...i},className:x,disabled:o,toolTipTitle:u,value:n,onClick:g,children:s.jsxRuntimeExports.jsx("span",{className:"toggle-button-text",children:s.jsxRuntimeExports.jsx(k.default,{children:l})})})}exports.ToggleButtonGroup=C.default;exports.ToggleButton=f;exports.default=f;
 //# sourceMappingURL=index.js.map

package/lib/Tooltip/component.json

@@ -0,0 +1,176 @@
+{
+    "name": "Tooltip",
+    "category": "Data Display",
+    "description": "简单的文字提示气泡框",
+    "semantic": {
+        "intent": [
+            "辅助说明",
+            "信息补充",
+            "操作提示"
+        ],
+        "useCases": [
+            "按钮解释",
+            "被截断文本显示",
+            "图标含义说明"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "visible",
+        "hidden"
+    ],
+    "idealProps": {
+        "title": {
+            "type": "string | ReactNode",
+            "description": "提示文字"
+        },
+        "placement": {
+            "type": "enum",
+            "values": [
+                "top",
+                "left",
+                "right",
+                "bottom",
+                "topLeft",
+                "topRight",
+                "bottomLeft",
+                "bottomRight",
+                "leftTop",
+                "leftBottom",
+                "rightTop",
+                "rightBottom"
+            ],
+            "default": "topLeft",
+            "description": "气泡框位置。配合 `autoAdjustOverflow=true` 可被遮挡时自动翻转。**长 content + maxWidth 较大时优先 top/bottom 减少水平空间冲突**"
+        },
+        "maxWidth": {
+            "type": "string | number",
+            "default": 500,
+            "description": "气泡最大宽度。`number` = px;`string` = 任意合法 CSS 长度(`'200px'` / `'20rem'`)。默认 500px 适合大多数长 title 场景。R23 TT3 docs 协同补强"
+        },
+        "trigger": {
+            "type": "enum",
+            "values": [
+                "hover",
+                "focus",
+                "click",
+                "contextMenu"
+            ],
+            "default": "hover",
+            "description": "触发行为。**`trigger=[]` 受控屏蔽写法已 deprecated(R23 TT2)**——请改用 `visible={false}`。老写法仍可用但 dev 环境 console.warn 一次提示迁移;v6 可能收紧类型不接受空数组,提前迁移"
+        },
+        "visible": {
+            "type": "boolean",
+            "default": "undefined",
+            "description": "**控制浮层显示(受控,src 真实主名)**。**三路语义**(R24 W-2 文档化):`true`=强制显示气泡;`false`=强制隐藏(推荐替代 deprecated `trigger=[]`);`undefined` 或不传=fallback 到 `open`,再 fallback 到 trigger 默认触发逻辑(`visible ?? open ?? trigger 自动`,src/Tooltip/index.tsx:27)。条件受控:`visible={isDisabled ? false : undefined}`"
+        },
+        "open": {
+            "type": "boolean",
+            "default": "undefined",
+            "description": "`visible` 的别名(来自 antd 风格);与 visible 二选一,不要同时传"
+        },
+        "onVisibleChange": {
+            "type": "function",
+            "signature": "(visible: boolean) => void",
+            "description": "**显示隐藏回调(src 真实事件名,非 onOpenChange)**。受控用法配合 visible/open 使用;受控 visible 时 hover/click 仍触发本回调但 Tooltip 不会自更新——必须父组件 setState。**受控 trigger 选择建议**(R24 W-2 R23 TT2 round 标注):新手引导等场景若不希望 hover 持续触发本回调改变 step,建议 `trigger='click'`;**不要用 deprecated `trigger=[]`**(R23 TT2)"
+        },
+        "defaultVisible": {
+            "type": "boolean",
+            "default": false,
+            "description": "初始是否显示气泡（非受控初始值，src/Tooltip/index.tsx:18,193 实证：`useState(props.defaultVisible!)` 作为初始 visible 状态；默认 false。传了 visible/open 受控 prop 后 defaultVisible 被覆盖）"
+        },
+        "mouseEnterDelay": {
+            "type": "number",
+            "default": 0.1,
+            "description": "鼠标移入后延迟显示的时间（单位：秒，src/Tooltip/index.tsx:190 defaultProps 实证：默认 0.1s）。⚠️ **单位是秒不是毫秒**（0.1 = 100ms）"
+        },
+        "mouseLeaveDelay": {
+            "type": "number",
+            "default": 0.1,
+            "description": "鼠标移出后延迟隐藏的时间（单位：秒，src/Tooltip/index.tsx:191 defaultProps 实证：默认 0.1s）。⚠️ **单位是秒不是毫秒**"
+        },
+        "autoAdjustOverflow": {
+            "type": "boolean",
+            "default": true,
+            "description": "气泡被遮挡时是否自动翻转位置（src/Tooltip/index.tsx:64-65,192 实证：默认 true，传入 getPlacements 生成弹出方向配置）"
+        },
+        "followCursor": {
+            "type": "boolean",
+            "default": false,
+            "description": "气泡是否跟随鼠标光标移动（src/Tooltip/index.tsx:122,171-178,194 实证：true 时强制 placement='top' 并在外层 div 监听 mousemove 动态更新 targetOffset；与精确 placement 互斥）"
+        },
+        "overlayClassName": {
+            "type": "string",
+            "description": "气泡浮层的自定义类名（src/Tooltip/index.tsx:115,135 实证：与内置 paraui-tooltip 类合并透传到 RcTooltip overlayClassName）"
+        },
+        "overlayInnerStyle": {
+            "type": "React.CSSProperties",
+            "description": "气泡内容区内联样式（src/Tooltip/index.tsx:116,164 实证：透传到 RcTooltip overlayInnerStyle，作用于内容容器而非浮层外壳）"
+        },
+        "overlayStyle": {
+            "type": "React.CSSProperties",
+            "description": "气泡浮层外壳内联样式（src/Tooltip/index.tsx:117,138-140 实证：与 maxWidth 合并后透传到 RcTooltip overlayStyle）"
+        }
+    },
+    "do": [
+        "提示内容应当精简，避免超过两行文字",
+        "用于解释图标或被截断的文本（配合 AutoTips 使用效果更佳）",
+        "受控场景用 `visible={false}` 替代已废弃的 `trigger=[]` 写法——v6 可能移除空数组支持（src/Tooltip/index.tsx:29-40 dev warn 实证）",
+        "Modal/Dialog 内的 Tooltip 建议传 getPopupContainer 指向 modal 容器，避免 overflow:hidden 截断浮层",
+        "需要叠加禁用视觉图标时用 showForbidIcon={true}（新名）而非 disabled（deprecated），两者源码同路径：`(disabled || showForbidIcon) && <Forbid />`"
+    ],
+    "dont": [
+        "在 Tooltip 中放入复杂交互内容（应使用 Popover）",
+        "提示内容为空——title 为空时 Tooltip 强制不显示（src/Tooltip/index.tsx:42-45 isUntitled 判断）",
+        "不要把 `disabled` 理解为『禁用气泡显示』——src 实现是叠加红色 Forbid 图标，与 antd/mui 同名 prop 含义相反；用 `visible={false}` 来强制隐藏气泡",
+        "不要同时传 visible 和 open——两者是同义别名，优先取 visible，同时传会造成语义混淆（src:27 `props.visible ?? props.open` 实证）",
+        "不要给 mouseEnterDelay / mouseLeaveDelay 传毫秒值（如 100）——单位是秒，传 100 = 100秒延迟"
+    ],
+    "events": {
+        "onVisibleChange": {
+            "signature": "(visible: boolean) => void",
+            "asyncSupported": false,
+            "examples": [
+                "非受控模式下跟踪气泡显示状态：onVisibleChange={(v) => setIsHovered(v)}",
+                "受控模式配合 useState：onVisibleChange={(v) => setVisible(v)}",
+                "新手引导场景：`trigger='click'` + onVisibleChange 控制引导步骤切换（避免 hover 持续触发）"
+            ],
+            "commonMistakes": [
+                "回调名写成 onOpenChange → src 真实回调名是 onVisibleChange，写错无效（RcTooltip 接口名），不会有 TS 报错但回调不触发",
+                "受控模式（visible=xxx）下期望 onVisibleChange 触发后气泡自动更新 → 受控时内部 state 不更新，必须父组件在 onVisibleChange 里 setState",
+                "假设 onVisibleChange 在 title 为空时也会触发 → src:46-50 isUntitled()=true 时 onVisibleChange 不被调用"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "disabled 的语义与 antd/mui 相反——不是禁用气泡而是叠加禁用图标",
+            "wrong": "<Tooltip disabled={isLoading} title='提示'>  // 期望 isLoading 时不显示气泡 → 实际只是叠加红色图标，气泡照常显示",
+            "right": "<Tooltip visible={isLoading ? false : undefined} title='提示'>  // 正确：visible=false 才能强制隐藏气泡"
+        },
+        {
+            "issue": "mouseEnterDelay / mouseLeaveDelay 单位是秒不是毫秒",
+            "wrong": "<Tooltip mouseEnterDelay={500} />  // 500 秒 = 8 分钟才显示",
+            "right": "<Tooltip mouseEnterDelay={0.5} />  // 0.5 秒 = 500ms"
+        },
+        {
+            "issue": "followCursor={true} 时 placement 被强制覆盖为 'top'，设置其他 placement 无效",
+            "wrong": "<Tooltip followCursor={true} placement='bottomRight' />  // placement 被 src:128 强制改为 'top'",
+            "right": "<Tooltip followCursor={true} />  // followCursor 场景只支持 top，无需传 placement"
+        },
+        {
+            "issue": "TooltipProps 继承自 rc-tooltip，overlayStyle 和 overlayInnerStyle 作用 DOM 层级不同",
+            "wrong": "overlayStyle={{ color: 'red' }}  // overlayStyle 作用于浮层外壳，文字颜色无效",
+            "right": "overlayInnerStyle={{ color: 'red' }}  // overlayInnerStyle 作用于内容容器，文字颜色生效"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Tooltip",
+        "adapter": null
+    }
+}

package/lib/Tooltip/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const r=require("../_virtual/jsx-runtime.js"),s=require("react"),Y=require("rc-tooltip"),c=require("./utils.js"),_=require("clsx"),x=require("../GlobalContext/constant.js"),k=require("../node_modules/@para-ui/icons/Forbid/index.js");;/* empty css            */const u=s.forwardRef((e,j)=>{const[P,p]=s.useState(e.defaultVisible),d=s.useRef(null),b=s.useRef(null),[$,w]=s.useState([0,0]);s.useEffect(()=>{("visible"in e||"open"in e)&&p(!!(e.visible??e.open))},[e.visible??e.open]);const m=()=>{const{title:t}=e;return!t&&t!==0},T=t=>{"visible"in e||"open"in e||p(m()?!1:t),m()||e.onVisibleChange?.(t)},g=()=>{const{builtinPlacements:t,autoAdjustOverflow:i}=e;return t||c.default({autoAdjustOverflow:i})},S=(t,i)=>{const l=g(),n=Object.keys(l).find(a=>l[a].points[0]===i.points[0]&&l[a].points[1]===i.points[1]);if(!n)return;const f=t.getBoundingClientRect(),o={top:"50%",left:"50%"};n.indexOf("top")>=0||n.indexOf("Bottom")>=0?o.top=`${f.height-(i.offset?.[1]||0)}px`:(n.indexOf("Top")>=0||n.indexOf("bottom")>=0)&&(o.top=`${-(i.offset?.[1]||0)}px`),n.indexOf("left")>=0||n.indexOf("Right")>=0?o.left=`${f.width-(i.offset?.[0]||0)}px`:(n.indexOf("right")>=0||n.indexOf("Left")>=0)&&(o.left=`${-(i.offset?.[0]||0)}px`),t.style.transformOrigin=`${o.left} ${o.top}`},q=t=>{if(d.current){const i=b.current?.popupRef?.current?.getElement()?.offsetHeight||0,l=i===0?60:30,{x:n,y:f,width:o}=d.current.getBoundingClientRect(),a=t.clientX-(n+o/2),X=t.clientY-f+i+l;setTimeout(()=>{w([-a,-X])})}},{prefixCls:E=`${x.$rcPrefixCls}-tooltip`,getPopupContainer:M,overlayClassName:V,overlayInnerStyle:D,overlayStyle:L,children:v,title:N,placement:A,isPopover:B,followCursor:y,maxWidth:h,disabled:W,...F}=e;let C=P;!("visible"in e||"open"in e)&&m()&&(C=!1);const H=_(!B&&`${x.$prefixCls}-tooltip`,V),O={...L};h&&(O.maxWidth=h);const R={targetOffset:$};return e.offset&&(R.offset=e.offset),r.jsxRuntimeExports.jsx(Y,{...F,prefixCls:E,placement:y?"top":c.mapLegacyPlacement(A),overlayClassName:H,getTooltipContainer:M,ref:j||b,builtinPlacements:g(),overlay:r.jsxRuntimeExports.jsxs(r.jsxRuntimeExports.Fragment,{children:[W&&r.jsxRuntimeExports.jsx(k.Forbid,{className:"disabled-svg"}),N]}),visible:C,align:R,onVisibleChange:T,onPopupAlign:S,overlayStyle:O,overlayInnerStyle:D,arrowContent:null,motion:{motionName:`${x.$rcPrefixCls}-tooltip-zoom-big-fast`,motionDeadline:1e3},children:y?r.jsxRuntimeExports.jsx("div",{style:{display:"inline-block"},ref:d,onMouseMove:q,children:c.getDisabledCompatibleChildren(v)}):c.getDisabledCompatibleChildren(v)})});u.displayName="Tooltip";u.defaultProps={placement:"topLeft",mouseEnterDelay:.1,mouseLeaveDelay:.1,autoAdjustOverflow:!0,defaultVisible:!1,followCursor:!1,maxWidth:500};exports.Tooltip=u;exports.default=u;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const r=require("../_virtual/jsx-runtime.js"),s=require("react"),Y=require("rc-tooltip"),c=require("./utils.js"),k=require("clsx"),g=require("../GlobalContext/constant.js"),z=require("../node_modules/@para-ui/icons/Forbid/index.js");;/* empty css            */const u=s.forwardRef((e,w)=>{const[E,x]=s.useState(e.defaultVisible),d=s.useRef(null),p=s.useRef(null),[P,$]=s.useState([0,0]),b=s.useRef(!1);s.useEffect(()=>{("visible"in e||"open"in e)&&x(!!(e.visible??e.open))},[e.visible??e.open]),s.useEffect(()=>{process.env.NODE_ENV!=="production"&&!b.current&&Array.isArray(e.trigger)&&e.trigger.length===0&&(b.current=!0,console.warn("[Tooltip] `trigger=[]` 受控屏蔽写法已 deprecated,请改用 `visible={false}`(语义更清晰);v6 可能收紧 trigger 类型,提前迁移。"))},[e.trigger]);const m=()=>{const{title:t}=e;return!t&&t!==0},T=t=>{"visible"in e||"open"in e||x(m()?!1:t),m()||e.onVisibleChange?.(t)},v=()=>{const{builtinPlacements:t,autoAdjustOverflow:i}=e;return t||c.default({autoAdjustOverflow:i})},S=(t,i)=>{const l=v(),n=Object.keys(l).find(a=>l[a].points[0]===i.points[0]&&l[a].points[1]===i.points[1]);if(!n)return;const f=t.getBoundingClientRect(),o={top:"50%",left:"50%"};n.indexOf("top")>=0||n.indexOf("Bottom")>=0?o.top=`${f.height-(i.offset?.[1]||0)}px`:(n.indexOf("Top")>=0||n.indexOf("bottom")>=0)&&(o.top=`${-(i.offset?.[1]||0)}px`),n.indexOf("left")>=0||n.indexOf("Right")>=0?o.left=`${f.width-(i.offset?.[0]||0)}px`:(n.indexOf("right")>=0||n.indexOf("Left")>=0)&&(o.left=`${-(i.offset?.[0]||0)}px`),t.style.transformOrigin=`${o.left} ${o.top}`},q=t=>{if(d.current){const i=p.current?.popupRef?.current?.getElement()?.offsetHeight||0,l=i===0?60:30,{x:n,y:f,width:o}=d.current.getBoundingClientRect(),a=t.clientX-(n+o/2),X=t.clientY-f+i+l;setTimeout(()=>{$([-a,-X])})}},{prefixCls:V=`${g.$rcPrefixCls}-tooltip`,getPopupContainer:D,overlayClassName:M,overlayInnerStyle:N,overlayStyle:A,children:y,title:L,placement:W,isPopover:B,followCursor:h,maxWidth:C,disabled:F,showForbidIcon:_,...H}=e;let R=E;!("visible"in e||"open"in e)&&m()&&(R=!1);const I=k(!B&&`${g.$prefixCls}-tooltip`,M),O={...A};C&&(O.maxWidth=C);const j={targetOffset:P};return e.offset&&(j.offset=e.offset),r.jsxRuntimeExports.jsx(Y,{...H,prefixCls:V,placement:h?"top":c.mapLegacyPlacement(W),overlayClassName:I,getTooltipContainer:D,ref:w||p,builtinPlacements:v(),overlay:r.jsxRuntimeExports.jsxs(r.jsxRuntimeExports.Fragment,{children:[(F||_)&&r.jsxRuntimeExports.jsx(z.Forbid,{className:"disabled-svg"}),L]}),visible:R,align:j,onVisibleChange:T,onPopupAlign:S,overlayStyle:O,overlayInnerStyle:N,arrowContent:null,motion:{motionName:`${g.$rcPrefixCls}-tooltip-zoom-big-fast`,motionDeadline:1e3},children:h?r.jsxRuntimeExports.jsx("div",{style:{display:"inline-block"},ref:d,onMouseMove:q,children:c.getDisabledCompatibleChildren(y)}):c.getDisabledCompatibleChildren(y)})});u.displayName="Tooltip";u.defaultProps={placement:"topLeft",mouseEnterDelay:.1,mouseLeaveDelay:.1,autoAdjustOverflow:!0,defaultVisible:!1,followCursor:!1,maxWidth:500};exports.Tooltip=u;exports.default=u;
 //# sourceMappingURL=index.js.map

package/lib/Tooltip/interface.d.ts

@@ -14,12 +14,25 @@ export interface TooltipProps extends Partial<Omit<RcTooltipProps, 'children'>>
     children?: React.ReactNode;
     /** 控制浮层是否显示 */
     open?: boolean;
+    /**
+     * 受控屏蔽气泡显示(推荐替代 `trigger=[]` 受控隐藏写法)。
+     * - `visible !== undefined` → 完全受控,显隐由 visible 控制(覆盖 trigger hover/click 默认行为)
+     * - `visible === undefined`(默认)→ 走 trigger 触发(原行为不变)
+     * 与 `open` 同义,优先级:`visible ?? open`(src/Tooltip/index.tsx)。@since v5.x.next
+     */
+    visible?: boolean;
     /** 跟随光标移动 */
     followCursor?: boolean;
     /** 容器最大宽度 */
     maxWidth?: number | string;
-    /** 禁用标志 */
+    /**
+     * @deprecated v5.x.next 改用 `showForbidIcon`(自描述命名,业界对齐);v6 移除。
+     * 语义不变:在 trigger 旁叠加红色 Forbid SVG 图标(不影响气泡显示)。
+     * 详见 BREAKING-CHANGES §B5。
+     */
     disabled?: boolean;
+    /** 在 trigger 节点旁叠加红色 Forbid 禁用 SVG 图标(原 `disabled` 重命名,自描述命名)。不影响气泡显示行为(气泡仍走 title/visible/trigger 控制)。@since v5.x.next */
+    showForbidIcon?: boolean;
     /** 偏移 */
     offset?: [number, number];
     [name: string]: unknown;

package/lib/Tooltip/utils.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const i=require("../_virtual/jsx-runtime.js"),a=require("rc-tooltip/lib/placements"),r=require("react"),m=require("clsx"),u=require("../GlobalContext/constant.js"),d={adjustX:1,adjustY:1},l={adjustX:0,adjustY:0};function b(t){return typeof t=="boolean"?t?d:l:{...l,...t}}function g(t){const{horizontalArrowShift:o=16,verticalArrowShift:s=8,autoAdjustOverflow:n}=t,e={left:{points:["cr","cl"],offset:[-8,0]},right:{points:["cl","cr"],offset:[8,0]},top:{points:["bc","tc"],offset:[0,-8]},bottom:{points:["tc","bc"],offset:[0,8]},topLeft:{points:["bl","tc"],offset:[-o,-8]},leftTop:{points:["tr","cl"],offset:[-8,-s]},topRight:{points:["br","tc"],offset:[o,-8]},rightTop:{points:["tl","cr"],offset:[8,-s]},bottomRight:{points:["tr","bc"],offset:[o,8]},rightBottom:{points:["bl","cr"],offset:[8,s]},bottomLeft:{points:["tl","bc"],offset:[-o,8]},leftBottom:{points:["br","cl"],offset:[-8,s]}};return Object.keys(e).forEach(f=>{e[f]={...a.placements[f],offset:x(f).offset,overflow:b(n)},e[f].ignoreShake=!0}),e}const h=(t,o)=>{const s={},n={...t};return o.forEach(e=>{t&&e in t&&(s[e]=t[e],delete n[e])}),{picked:s,omitted:n}};function j(t){const o=r.isValidElement(t)?t:i.jsxRuntimeExports.jsx("span",{children:t});if(o.type==="button"&&o.props.disabled){const{picked:s,omitted:n}=h(o.props.style,["position","left","right","top","bottom","float","display","zIndex"]),e={display:"inline-block",...s,cursor:"not-allowed",width:o.props.block?"100%":void 0},f={...n,pointerEvents:"none"},p=r.cloneElement(o,{style:f,className:null});return i.jsxRuntimeExports.jsx("span",{style:e,className:m(o.props.className,`${u.$rcPrefixCls}-tooltip-disabled-compatible-wrapper`),children:p})}return o}function c(t){return{"bottom-end":"bottomRight","bottom-start":"bottomLeft","left-end":"leftBottom","left-start":"leftTop","right-end":"rightBottom","right-start":"rightTop","top-end":"topRight","top-start":"topLeft"}[t]||t}function x(t){const o=c(t);return{left:{offset:[-8,0]},right:{offset:[8,0]},top:{offset:[0,-8]},bottom:{offset:[0,8]},topLeft:{offset:[0,-8]},leftTop:{offset:[-8,0]},topRight:{offset:[0,-8]},rightTop:{offset:[8,0]},bottomRight:{offset:[0,8]},rightBottom:{offset:[8,0]},bottomLeft:{offset:[0,8]},leftBottom:{offset:[-8,0]}}[o]}exports.default=g;exports.getDisabledCompatibleChildren=j;exports.mapLegacyPlacement=c;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const i=require("../_virtual/jsx-runtime.js"),a=require("rc-tooltip/lib/placements"),r=require("react"),m=require("clsx"),u=require("../GlobalContext/constant.js"),d={adjustX:1,adjustY:1},l={adjustX:0,adjustY:0};function b(t){return typeof t=="boolean"?t?d:l:{...l,...t}}function g(t){const{horizontalArrowShift:o=16,verticalArrowShift:s=8,autoAdjustOverflow:n}=t,e={left:{points:["cr","cl"],offset:[-8,0]},right:{points:["cl","cr"],offset:[8,0]},top:{points:["bc","tc"],offset:[0,-8]},bottom:{points:["tc","bc"],offset:[0,8]},topLeft:{points:["bl","tc"],offset:[-o,-8]},leftTop:{points:["tr","cl"],offset:[-8,-s]},topRight:{points:["br","tc"],offset:[o,-8]},rightTop:{points:["tl","cr"],offset:[8,-s]},bottomRight:{points:["tr","bc"],offset:[o,8]},rightBottom:{points:["bl","cr"],offset:[8,s]},bottomLeft:{points:["tl","bc"],offset:[-o,8]},leftBottom:{points:["br","cl"],offset:[-8,s]}};return Object.keys(e).forEach(f=>{e[f]={...a.placements[f],offset:x(f).offset,overflow:b(n)},e[f].ignoreShake=!0}),e}const h=(t,o)=>{const s={},n={...t};return o.forEach(e=>{t&&e in t&&(s[e]=t[e],delete n[e])}),{picked:s,omitted:n}};function j(t){const o=r.isValidElement(t)?t:i.jsxRuntimeExports.jsx("span",{children:t});if(o.props&&o.props.disabled===!0){const{picked:s,omitted:n}=h(o.props.style||{},["position","left","right","top","bottom","float","display","zIndex"]),e={display:"inline-block",...s,cursor:"not-allowed",width:o.props.block?"100%":void 0},f={...n,pointerEvents:"none"},p=r.cloneElement(o,{style:f,className:null});return i.jsxRuntimeExports.jsx("span",{style:e,className:m(o.props.className,`${u.$rcPrefixCls}-tooltip-disabled-compatible-wrapper`),children:p})}return o}function c(t){return{"bottom-end":"bottomRight","bottom-start":"bottomLeft","left-end":"leftBottom","left-start":"leftTop","right-end":"rightBottom","right-start":"rightTop","top-end":"topRight","top-start":"topLeft"}[t]||t}function x(t){const o=c(t);return{left:{offset:[-8,0]},right:{offset:[8,0]},top:{offset:[0,-8]},bottom:{offset:[0,8]},topLeft:{offset:[0,-8]},leftTop:{offset:[-8,0]},topRight:{offset:[0,-8]},rightTop:{offset:[8,0]},bottomRight:{offset:[0,8]},rightBottom:{offset:[8,0]},bottomLeft:{offset:[0,8]},leftBottom:{offset:[-8,0]}}[o]}exports.default=g;exports.getDisabledCompatibleChildren=j;exports.mapLegacyPlacement=c;
 //# sourceMappingURL=utils.js.map