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

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

package/lib/Transfer/component.json

@@ -0,0 +1,157 @@
+{
+    "name": "Transfer",
+    "category": "Data Entry",
+    "description": "穿梭框,双栏穿梭选择框",
+    "semantic": {
+        "intent": [
+            "多项选择",
+            "数据移动",
+            "分类归纳"
+        ],
+        "useCases": [
+            "权限配置",
+            "角色分配",
+            "字段筛选"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准穿梭框(多选 + 内置搜索)"
+        }
+    },
+    "states": [
+        "default",
+        "disabled"
+    ],
+    "idealProps": {
+        "data": {
+            "type": "Array<ItemDataProps>",
+            "default": "[]",
+            "itemSchema": {
+                "key": { "type": "string", "description": "唯一标识（与 value[] 对比；改字段名时用 customKey）" },
+                "name": { "type": "string", "description": "显示名" },
+                "description": { "type": "string", "description": "描述文字" },
+                "checked": { "type": "boolean", "description": "是否已勾选" },
+                "disabled": { "type": "boolean", "description": "是否禁用" },
+                "hide": { "type": "boolean", "description": "是否隐藏" },
+                "tagColor": { "type": "string", "description": "tag 色" }
+            },
+            "description": "数据源(**真实 prop 名是 data 不是 dataSource**);**对外导出类型名是 IItemDataProps**(有 I 前缀,src/index.ts 重命名导出),业务侧 import 用 `import { IItemDataProps } from '@para-ui/core/Transfer'`;ItemDataProps = { key?: string; name?: string; description?: string; checked?: boolean; disabled?: boolean; hide?: boolean; tagColor?: string; [k: string]: unknown };src/Transfer/box.tsx:49。**业务 any[] 数据**:若字段名不是 key/name(例如 id/label),建议父层 map 适配成 IItemDataProps 形状,或用 customKey 让 value 比对换字段"
+        },
+        "value": {
+            "type": "Array<string>",
+            "default": "[]",
+            "description": "右侧框已选中的 key 集合(**真实 prop 名是 value 不是 targetKeys**);受控数组,组件内部按 customKey 比对 data 分流到左右两侧;src/Transfer/index.tsx:236 useEffect 监听 value/data 同步"
+        },
+        "onChange": {
+            "type": "(keys: Array<string>) => void",
+            "description": "右侧 key 集合变化回调(穿梭 / 排序 / 上下移动都会触发);**回参是 key 数组不是 item 对象数组**;src/Transfer/index.tsx:150"
+        },
+        "onSort": {
+            "type": "(keys: Array<string>) => void",
+            "description": "右侧拖拽排序 / 上下移动后回调;触发时机:rightData splice 之后;src/Transfer/index.tsx:170 / 190 / 230;onChange 在 onSort 之前也会触发一次(同步右侧 key 序列)"
+        },
+        "customKey": {
+            "type": "string",
+            "default": "key",
+            "description": "自定义唯一键字段名;改这个会让 value 比对 data[customKey] 而非 data.key — 适用于业务数据自带 id/code 不想 rename 为 key 的场景"
+        },
+        "titles": {
+            "type": "Array<string>",
+            "default": "['左侧', '右侧']",
+            "description": "[左侧标题, 右侧标题];默认值来自 i18n localeJson(zh: '左侧'/'右侧',en: 'Left'/'Right');传两元数组覆盖"
+        },
+        "multiple": {
+            "type": "boolean",
+            "default": "true",
+            "description": "是否多选;false 时每侧 checkbox 单选语义,选中新项自动清空旧选"
+        },
+        "trim": {
+            "type": "boolean",
+            "default": "false",
+            "description": "搜索时是否去除首尾空格(toUpperCase 大小写不敏感是固定行为,trim 只控空格)"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": "false",
+            "description": "整体禁用(组件层);若只想禁某条 item,用 ItemDataProps.disabled — 二者独立可叠加"
+        },
+        "render": {
+            "type": "(item: ItemDataProps) => void",
+            "description": "对每条 item 的预处理 hook(在 useEffect 分流前调用,可改 item 字段);**注意是副作用函数(返回 void),不是返回 ReactNode 的 render prop** — 与 rightIcon 易混(rightIcon 才是返回 ReactNode);src/Transfer/index.tsx:242"
+        },
+        "rightIcon": {
+            "type": "(item: ItemDataProps) => ReactNode",
+            "description": "每行右侧自定义渲染(放 Help 图标 / Popover 等);返回 ReactNode,与 render 副作用 hook 不同"
+        }
+    },
+    "do": [
+        "在源数据量大且需要多选时使用 Transfer",
+        "提供清晰的 List Title",
+        "value 始终保持 string[] 类型(组件内部按 customKey 比对)"
+    ],
+    "dont": [
+        "在移动端使用 Transfer(交互困难)",
+        "数据量极小(<5)时使用 Transfer(推荐 Checkbox Group)",
+        "把 dataSource / targetKeys 当 prop 名(那是 Ant Design 命名,本组件实际是 data / value)",
+        "期待 onSelectChange / onCheck 回调(本组件无 checkbox 勾选未穿梭的回调 — onChange 仅在穿梭/排序/移动完成后触发;若需追踪'选中变化'只能在 onChange 后由 left/right key 集合推导)",
+        "期待 size / compact / dense prop(本组件不支持紧凑模式;紧凑视觉只能由外层 div 套 fontSize/padding 模拟,无法影响内部间距)",
+        "期待 showSearch prop(搜索是内置默认开启 — 仅 trim 控制空格策略)"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(keys: Array<string>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "穿梭（右→左或左→右）完成时触发：keys 是右侧框所有 key 的当前顺序数组",
+                "上下移动排序后触发：keys 反映排序后的顺序（onSort 也会在此之前触发）",
+                "拖拽排序完成后触发：onEndSort → onChange 顺序触发，keys 是最新右侧顺序"
+            ],
+            "commonMistakes": [
+                "把 onChange 的回参当做 ItemDataProps[] 对象数组——实际是 key 字符串数组",
+                "期望 onChange 在勾选（checkbox）时触发——onChange 只在穿梭/排序完成后触发，不追踪 checkbox 中间状态",
+                "期望 onChange 只在穿梭时触发——排序（onSort）也会同时触发 onChange"
+            ]
+        },
+        "onSort": {
+            "signature": "(keys: Array<string>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "右侧列表拖拽排序结束时触发：keys 是排序后右侧的 key 顺序数组",
+                "点击上/下移动按钮后触发：先触发 onSort 再触发 onChange",
+                "用于服务端保存排序：onSort={(keys) => saveOrder(keys)}"
+            ],
+            "commonMistakes": [
+                "只监听 onSort 不监听 onChange——右侧 key 顺序同时写入了 onChange，两者都会触发",
+                "期望 onSort 在左侧操作时触发——onSort 只针对右侧列表排序，左侧没有排序功能"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "data 的 TypeScript 导出类型名是 IItemDataProps（有 I 前缀），不是 ItemDataProps",
+            "wrong": "import { ItemDataProps } from '@para-ui/core/Transfer'  // 不存在此导出",
+            "right": "import { IItemDataProps } from '@para-ui/core/Transfer'  // src/Transfer/index.tsx 重命名导出"
+        },
+        {
+            "issue": "value 是 string[] 不是 ItemDataProps[]，传对象数组导致右侧显示为空",
+            "wrong": "value={[{ key: 'a', name: '选项A' }]}  // 传对象数组，内部 indexOf 比对会失败",
+            "right": "value={['a']}  // 传 key 字符串数组，对应 data 中每项的 customKey 字段值"
+        },
+        {
+            "issue": "自定义 key 字段时需同步传 customKey，否则 value 比对不到 data",
+            "wrong": "// 数据字段是 id 但没传 customKey\ndata={[{ id: '001', name: '项目A' }]} value={['001']}  // 比对用 data.key，找不到",
+            "right": "data={[{ id: '001', name: '项目A' }]} value={['001']} customKey='id'  // 告知组件用 id 做 key"
+        },
+        {
+            "issue": "render 是副作用 hook 不是 render prop，返回 void 不是 ReactNode",
+            "wrong": "render={(item) => <span>{item.name}</span>}  // 假设 render 返回 ReactNode 渲染到列表项",
+            "right": "// render 用于预处理 item 字段（副作用），自定义列表项显示用 rightIcon\nrender={(item) => { item.name = item.label; }}  // 修改 item 字段"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Transfer",
+        "adapter": null
+    }
+}