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

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