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

package/es/CollapseBox/component.json

@@ -0,0 +1,84 @@
+{
+    "name": "CollapseBox",
+    "category": "Layout",
+    "description": "折叠盒子，用于控制内容的展开/收起动画",
+    "semantic": {
+        "intent": [
+            "动画容器",
+            "展开收起"
+        ],
+        "useCases": [
+            "手风琴",
+            "下拉内容",
+            "详情展开"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "expanded",
+        "collapsed"
+    ],
+    "idealProps": {
+        "in": {
+            "type": "boolean",
+            "default": false,
+            "description": "【核心受控 prop】控制展开/收起状态;true=展开渲染 children,false=收起;父层需用 useState<boolean> 维护此状态(R21 §5.1 4 high 揭示此 prop 必须在 docs 显式列出)"
+        },
+        "children": {
+            "type": "React.ReactNode",
+            "description": "折叠区域内容;接受任意 ReactNode(多个并列元素亦可,内部已包 wrapper div 测高度)"
+        },
+        "collapsedHeight": {
+            "type": "string | number",
+            "default": "0px",
+            "description": "收起状态最小高度;默认 0px 等同完全隐藏;常用 '60px' 实现部分预览;与 unmountOnExit=true 同传时失效(子树被卸载)"
+        },
+        "unmountOnExit": {
+            "type": "boolean",
+            "default": false,
+            "description": "收起时是否卸载子节点(true=卸载,false=保留 DOM);与 collapsedHeight 互斥:true 时 collapsedHeight 无效"
+        },
+        "timeout": {
+            "type": "'auto' | number | { appear?: number; enter?: number; exit?: number }",
+            "default": "'auto'",
+            "description": "动画时长(ms);'auto' 按内容高度计算;number 时 enter/exit 共用;{enter, exit} 分别指定;不支持 'fast'/'slow' 字符串关键字"
+        }
+    },
+    "do": [
+        "用于需要平滑展开/收起动画的场景，通过 `in` prop 控制展开状态（父组件用 useState<boolean> 维护）",
+        "设置 collapsedHeight（如 '60px'）实现内容预览折叠效果，同时保持收起时不完全消失",
+        "需要节省性能时设置 unmountOnExit=true，收起时卸载子树（但与 collapsedHeight 互斥——unmountOnExit=true 时 collapsedHeight 无效）"
+    ],
+    "dont": [
+        "同时设置 unmountOnExit=true 和 collapsedHeight——两者互斥，unmountOnExit=true 时子树卸载，collapsedHeight 无效",
+        "频繁（>10次/秒）切换 in 状态——动画计时器不会被提前中断，快速切换会产生视觉抖动",
+        "在不需要动画的场景使用（直接用 CSS display:none 或 conditional render 性能更好）"
+    ],
+    "events": {},
+    "typescriptPitfalls": [
+        {
+            "issue": "in prop 是关键字，需要用引号或通过变量传入；TypeScript 下直接写 in= 可能触发解析问题",
+            "wrong": "// 变量名与关键字冲突：\nconst in = true;  // TS 语法错误，in 是保留关键字",
+            "right": "// 用非关键字变量名：\nconst isOpen = true; <CollapseBox in={isOpen}>"
+        },
+        {
+            "issue": "timeout 的对象形式类型是 { appear?: number; enter?: number; exit?: number }，不支持字符串关键字",
+            "wrong": "<CollapseBox timeout='fast' />  // TS 报错：'fast' 不在联合类型中",
+            "right": "<CollapseBox timeout='auto' />  // 只有 'auto' 是字符串关键字；具体毫秒用 number"
+        },
+        {
+            "issue": "collapsedHeight 同时接受 string 和 number，number 类型会被转为带 px 后缀的字符串",
+            "wrong": "// 期望传百分比：\ncollapsedHeight={50}  // 解析为 '50px' 而非 '50%'",
+            "right": "// 百分比需传字符串：\ncollapsedHeight='50%'  // 或 collapsedHeight='60px'"
+        }
+    ],
+    "mapping": {
+        "realComponent": "CollapseBox",
+        "adapter": null
+    }
+}

package/es/CollapseLayout/component.json

@@ -0,0 +1,155 @@
+{
+    "name": "CollapseLayout",
+    "category": "Layout",
+    "description": "折叠布局，支持分区域折叠的布局组件",
+    "semantic": {
+        "intent": [
+            "分区布局",
+            "可伸缩面板"
+        ],
+        "useCases": [
+            "侧边栏",
+            "详情面板",
+            "代码编辑器"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "left": {
+            "meaning": "左侧折叠"
+        },
+        "right": {
+            "meaning": "右侧折叠"
+        },
+        "top": {
+            "meaning": "顶部折叠"
+        },
+        "bottom": {
+            "meaning": "底部折叠"
+        }
+    },
+    "states": [
+        "expanded",
+        "collapsed"
+    ],
+    "idealProps": {
+        "type": {
+            "type": "enum",
+            "values": [
+                "left",
+                "right",
+                "top",
+                "bottom"
+            ],
+            "default": "left",
+            "description": "可折叠侧(displayContent)的位置;left/top displayContent 在前,right/bottom 在后"
+        },
+        "open": {
+            "type": "boolean",
+            "default": false,
+            "description": "软受控展开状态;父改 open 强制同步,但用户点击不反向通知父端(双向同步需配合 onClickBtn)"
+        },
+        "zoomLength": {
+            "type": "number",
+            "default": 0,
+            "description": "可折叠侧最大尺寸(横向时宽,纵向时高,单位由 unit 决定);0=不显示可折叠侧"
+        },
+        "minDragLength": {
+            "type": "number",
+            "default": 100,
+            "description": "拖拽分隔条时的最小尺寸(单位固定 px,与 unit 无关)"
+        },
+        "unit": {
+            "type": "string",
+            "default": "px",
+            "description": "zoomLength / spacing 的尺寸单位(px/rem/%);不影响 minDragLength"
+        },
+        "spacing": {
+            "type": "number",
+            "default": 20,
+            "description": "defaultContent 与 displayContent 间距(单位同 unit)"
+        },
+        "defaultContent": {
+            "type": "ReactNode",
+            "description": "自适应侧内容(始终占据剩余空间)"
+        },
+        "displayContent": {
+            "type": "ReactNode",
+            "description": "可折叠侧内容(尺寸由 zoomLength / 拖拽决定)"
+        },
+        "showLabel": {
+            "type": "string",
+            "description": "收起态时按钮文字"
+        },
+        "hideLabel": {
+            "type": "string",
+            "description": "展开态时按钮文字"
+        },
+        "onClickBtn": {
+            "type": "function",
+            "signature": "(bol?: boolean, duration?: number) => void",
+            "description": "切换按钮回调;bol=新状态(true 展开),duration=动画 ms(内部根据可折叠侧尺寸计算)"
+        },
+        "onDragEnd": {
+            "type": "function",
+            "signature": "() => void",
+            "description": "用户拖拽分隔条结束回调(松开鼠标触发,不带新尺寸)"
+        }
+    },
+    "do": [
+        "用于需要可折叠侧边栏的场景（如代码编辑器左侧文件树）——传 type='left'、defaultContent=主内容、displayContent=侧栏内容、zoomLength=侧栏宽度",
+        "支持拖拽调整大小：用户拖动分隔条时组件内部更新 zoomLength；拖拽结束后通过 onDragEnd 回调通知父组件",
+        "配合 onClickBtn 监听折叠/展开按钮点击：onClickBtn(bol, duration) 的 bol=新展开状态，duration=动画毫秒数（按内容尺寸计算）"
+    ],
+    "dont": [
+        "嵌套多层 CollapseLayout（嵌套会导致 zoomLength/spacing 计算混乱）",
+        "把 open prop 当做完全受控——open 是软受控（父改 open 会同步），但用户点击按钮后不会反向通知父端；双向同步需配合 onClickBtn 回调"
+    ],
+    "events": {
+        "onClickBtn": {
+            "signature": "(bol?: boolean, duration?: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "监听展开/收起切换：onClickBtn={(isOpen, animMs) => { setOpen(isOpen); console.log('动画时长', animMs, 'ms'); }}",
+                "bol=true 表示点击后变为展开状态，bol=false 表示变为收起状态",
+                "duration 由组件内部根据可折叠侧当前尺寸计算（高度/宽度越大动画越长）"
+            ],
+            "commonMistakes": [
+                "期望 open prop 变化时触发 onClickBtn——只有用户点击按钮才触发，外部修改 open 不触发",
+                "假设 onClickBtn 不传时用户点击无效——不传 onClickBtn 时用户点击仍然工作，只是父端感知不到状态变化"
+            ]
+        },
+        "onDragEnd": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "拖拽结束后保存新尺寸：onDragEnd={() => saveLayout(constData.current.zoomLength)}",
+                "注意：onDragEnd 不携带新的 zoomLength 值，需在外部另行记录"
+            ],
+            "commonMistakes": [
+                "期望 onDragEnd 回调携带新的尺寸值——实际是无参回调，新尺寸由组件内部 constData.current.zoomLength 维护，外部感知需另起方案"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "zoomLength 和 spacing 的单位由 unit prop 决定，minDragLength 单位固定为 px",
+            "wrong": "// 错误：以为 minDragLength 受 unit='rem' 影响\nzoomLength={20} unit='rem' minDragLength={5}  // minDragLength=5 依然是 px，不是 rem",
+            "right": "// minDragLength 始终 px，zoomLength/spacing 受 unit 影响：\nzoomLength={20} unit='rem' minDragLength={100}  // 最小拖拽 100px"
+        },
+        {
+            "issue": "open prop 是软受控，不传时组件内部自维护展开状态",
+            "wrong": "// 仅传 open 不传 onClickBtn，以为可以完全受控\n<CollapseLayout open={externalOpen} />  // 用户点击后内部状态更新但外部 externalOpen 不变，下次 open 变化时会强制同步覆盖",
+            "right": "// 双向同步需配合 onClickBtn：\n<CollapseLayout open={isOpen} onClickBtn={(bol) => setIsOpen(!!bol)} />"
+        },
+        {
+            "issue": "defaultContent 和 displayContent 是 ReactNode 类型，不是 children",
+            "wrong": "<CollapseLayout><MySidebar /></CollapseLayout>  // children 不渲染",
+            "right": "<CollapseLayout defaultContent={<MainContent />} displayContent={<Sidebar />} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "CollapseLayout",
+        "adapter": null
+    }
+}

package/es/ColorPicker/component.json

@@ -0,0 +1,142 @@
+{
+    "name": "ColorPicker",
+    "category": "Data Entry",
+    "description": "颜色选择器，提供 SketchPicker/ChromePicker/SwatchesPicker/CompactPicker 四种变体，输出 hex/rgb/hsl 等多种格式",
+    "semantic": {
+        "intent": [
+            "颜色选择",
+            "主题定制"
+        ],
+        "useCases": [
+            "设计工具",
+            "个性化设置",
+            "图表配色"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "SketchPicker": {
+            "meaning": "default export · 完整调色板 + 预设色板 + clear/onClear 自定义清除按钮"
+        },
+        "ChromePicker": {
+            "meaning": "具名 export · Chrome 浏览器风格 + hex/rgb/hsl 切换 · 无 clear"
+        },
+        "SwatchesPicker": {
+            "meaning": "具名 export · 色样网格 · 无调色板/无透明度"
+        },
+        "CompactPicker": {
+            "meaning": "具名 export · 紧凑色板 + hex 输入 · 无透明度"
+        }
+    },
+    "states": [
+        "default"
+    ],
+    "idealProps": {
+        "color": {
+            "type": "string | HSLColor | RGBColor",
+            "description": "受控当前颜色;string 接受 hex(3/4/6/8 位)"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(color: ColorResult, event?: ChangeEvent) => void",
+            "description": "实时颜色变化(每次拖动/输入都触发,高频);color 是 ColorResult { hex, rgb, hsl, hsv, source }"
+        },
+        "onChangeComplete": {
+            "type": "function",
+            "signature": "(color: ColorResult, event?: ChangeEvent) => void",
+            "description": "完成态回调(仅鼠标释放/失焦触发,低频);用于避免高频副作用"
+        },
+        "clear": {
+            "type": "boolean",
+            "default": false,
+            "description": "仅 SketchPicker 有效;开启右下角清除方块"
+        },
+        "onClear": {
+            "type": "function",
+            "signature": "() => void",
+            "description": "仅 SketchPicker;clear=true 时点击清除按钮触发,业务方需自行 setColor 重置"
+        },
+        "disableAlpha": {
+            "type": "boolean",
+            "default": false,
+            "description": "禁用透明度滑块(影响 ColorResult.rgb/hsl/hsv 是否含 a)"
+        },
+        "presetColors": {
+            "type": "string[]",
+            "description": "预设色板;传 [] 隐藏(SketchPicker/SwatchesPicker 有效)"
+        },
+        "width": {
+            "type": "string | number",
+            "description": "picker 整体宽度"
+        }
+    },
+    "do": [
+        "默认 export 为 SketchPicker（功能最完整）；需要 Chrome 风格用 ChromePicker，紧凑色板用 CompactPicker，仅色样网格用 SwatchesPicker",
+        "高频更新场景（onChange 触发频繁）建议用 onChangeComplete 避免副作用（如 API 调用）被每次拖动触发",
+        "需要清除按钮：传 clear={true} + onClear 回调（仅 SketchPicker 支持）；onClear 触发时自行 setColor 重置颜色值"
+    ],
+    "dont": [
+        "在移动端使用 SketchPicker / ChromePicker——触摸精度有限，改用 SwatchesPicker（固定色板）",
+        "忽略颜色对比度验证——选色后需业务方自行检查 WCAG 对比度",
+        "把 onChange 的 color 参数当 string 直接用——实际是 ColorResult 对象，取 hex 值需用 color.hex"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(color: ColorResult, event?: ChangeEvent) => void",
+            "asyncSupported": false,
+            "examples": [
+                "取 hex 值：<SketchPicker onChange={(color) => setHex(color.hex)} />",
+                "取 rgba：onChange={(color) => setRgba(`rgba(${color.rgb.r},${color.rgb.g},${color.rgb.b},${color.rgb.a})`)}",
+                "高频触发（每次拖动都触发），需要低频回调改用 onChangeComplete"
+            ],
+            "commonMistakes": [
+                "把 color 参数当 string 用——color 是 ColorResult 对象，取 hex 值需 color.hex（含 # 前缀），取 rgb 需 color.rgb.r/g/b",
+                "直接把 onChange 当 onChangeComplete 用——onChange 在拖动过程中高频触发，onChangeComplete 仅在鼠标释放时触发",
+                "disableAlpha=true 时仍期望 color.rgb.a 有值——禁用透明度后 a 字段可能为 undefined"
+            ]
+        },
+        "onChangeComplete": {
+            "signature": "(color: ColorResult, event?: ChangeEvent) => void",
+            "asyncSupported": false,
+            "examples": [
+                "低频保存：<SketchPicker onChangeComplete={(color) => saveColor(color.hex)} />",
+                "只在鼠标释放/输入失焦时触发，适合触发 API 调用或状态持久化"
+            ],
+            "commonMistakes": [
+                "把 onChangeComplete 和 onChange 都传，在 onChange 里做副作用——重复触发，只需传一个"
+            ]
+        },
+        "onClear": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "仅 SketchPicker 有效：<SketchPicker clear onClear={() => setColor(undefined)} />",
+                "onClear 触发时组件不自动清空 color prop，需业务方 setColor 重置"
+            ],
+            "commonMistakes": [
+                "ChromePicker/CompactPicker/SwatchesPicker 传 clear/onClear 无效——这两个 prop 仅 SketchPicker 支持"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "onChange 的 color 参数是 ColorResult 对象，不是字符串，直接作为 string 使用会 TS 报错",
+            "wrong": "onChange={(color) => setHex(color)}  // color 是 ColorResult 对象，不是 string",
+            "right": "onChange={(color) => setHex(color.hex)}  // 取 hex 字符串"
+        },
+        {
+            "issue": "clear/onClear 仅 SketchPicker（默认 export）支持，传给其他变体无效且 TS 可能报类型错误",
+            "wrong": "import { ChromePicker } from '@para-ui/core'; <ChromePicker clear onClear={...} />  // ChromePicker 无这两个 prop",
+            "right": "import ColorPicker from '@para-ui/core';  // 默认 export 是 SketchPicker\n<ColorPicker clear onClear={() => setColor(undefined)} />"
+        },
+        {
+            "issue": "presetColors 传 [] 隐藏预设色板，而非传 null/undefined",
+            "wrong": "<ColorPicker presetColors={null} />  // TS 类型错误：null 不是 string[]",
+            "right": "<ColorPicker presetColors={[]} />  // 传空数组隐藏预设色板区域"
+        }
+    ],
+    "mapping": {
+        "realComponent": "ColorPicker",
+        "adapter": null
+    }
+}

package/es/ComboSelect/component.json

@@ -0,0 +1,181 @@
+{
+    "name": "ComboSelect",
+    "category": "Data Entry",
+    "description": "组合选择器，支持表格、树、列表多种模式",
+    "semantic": {
+        "intent": [
+            "复杂选择",
+            "多模式选择"
+        ],
+        "useCases": [
+            "人员选择",
+            "组织架构",
+            "资源选择"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "table": {
+            "meaning": "表格模式"
+        },
+        "tree": {
+            "meaning": "树形模式"
+        },
+        "list": {
+            "meaning": "列表模式"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error"
+    ],
+    "idealProps": {
+        "mode": {
+            "type": "enum",
+            "values": [
+                "table",
+                "tree",
+                "list"
+            ],
+            "default": "table",
+            "description": "选择器模式;tree 启用 fullPath*,table 接受 TableProps,list 无 Table/Tree props"
+        },
+        "value": {
+            "type": "SelectOpt[] | SelectOpt",
+            "description": "受控值;checkable=true 数组(多选),checkable=false 单值(单选);字段名遵循 replaceFields"
+        },
+        "defaultValue": {
+            "type": "SelectOpt[] | SelectOpt",
+            "description": "非受控默认值,与 value 互斥;类型规则同 value"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(options: SelectOpt[] | SelectOpt, originData?: TreeNodeProps[] | TreeNodeProps) => void",
+            "description": "value 变更回调;第二参 originData 是底层原数据透传(replaceFields 映射前的形态)"
+        },
+        "checkable": {
+            "type": "boolean",
+            "default": true,
+            "description": "单选 / 多选模式开关;直接影响 value/defaultValue/onChange 类型"
+        },
+        "replaceFields": {
+            "type": "object",
+            "default": "{ key: 'key', title: 'title', children: 'children' }",
+            "description": "入参字段映射;决定 value 里对象用什么字段名"
+        },
+        "outputFields": {
+            "type": "object",
+            "default": "{ outputKey: 'key', outputTitle: 'label' }",
+            "description": "出参字段映射(独立于 replaceFields);决定 onChange options 里字段名"
+        },
+        "showSearch": {
+            "type": "boolean",
+            "default": false,
+            "description": "显示搜索框;配合 realTimeSearch/searchPlaceholder/onSearch 使用"
+        },
+        "allowClear": {
+            "type": "boolean",
+            "default": false,
+            "description": "允许清空;触发 onClear 后组件自动清内部 state,父端需同步父 state"
+        },
+        "url": {
+            "type": "string",
+            "description": "远程数据源 URL;配合 ctx/method/params 一组使用,替代 TableProps.data / TreeProps.treeData"
+        },
+        "method": {
+            "type": "enum",
+            "values": [
+                "Get",
+                "Post"
+            ],
+            "default": "Get",
+            "description": "请求方法;注意首字母大写,不是 GET/POST"
+        }
+    },
+    "epics": [
+        "ComboSelect-api-rework-epic.md (R20 W-3 起草 · 议题 A 泛型化 / 议题 B 字段映射对称 / R21 user 评审)"
+    ],
+    "do": [
+        "用于需要复杂选择逻辑的场景（人员选择、组织架构、资源选择），简单场景用 Select",
+        "配合服务端搜索减少数据量（url + params + showSearch + onSearch）",
+        "checkable=false 单选时，value/onChange 的 options 是 SelectOpt 对象而非数组——不要用数组 API",
+        "replaceFields 和 outputFields 独立控制：replaceFields 控制入参字段映射，outputFields 控制 onChange 出参字段映射，两者不互通"
+    ],
+    "dont": [
+        "简单选择场景使用（应使用 Select，ComboSelect 引入了 Table/Tree 等重依赖）",
+        "数据量极大时不分页（远程模式需配合 TableProps.pagination 或分页参数控制）",
+        "不要假设 onOk 和 onChange 触发时机相同——showPopoverActions=true 时用 onOk/onCancel；不显示 footer 时只有 onChange"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(options: SelectOpt[] | SelectOpt, originData?: TreeNodeProps[] | TreeNodeProps) => void",
+            "asyncSupported": false,
+            "examples": [
+                "多选（checkable=true）：options 是 SelectOpt[] 数组，每项含 outputFields 指定的字段",
+                "单选（checkable=false）：options 是单个 SelectOpt 对象（不是数组），originData 是原始树节点",
+                "清空时（allowClear=true 触发 onClear）：onChange 额外触发，checkable=true 时 options=[]，checkable=false 时 options={}"
+            ],
+            "commonMistakes": [
+                "checkable=false 时把 options 当数组处理——单选模式 options 是 SelectOpt 对象，直接 .key 取值，不能 .map()",
+                "忽略 outputFields 对出参字段的影响——默认 outputFields={ outputKey:'key', outputTitle:'label' }，出参对象的 key 名是 outputKey/outputTitle，不是原始的 replaceFields 字段名",
+                "假设 onOk 等价 onChange——showPopoverActions=false 时没有 onOk，所有变更走 onChange；showPopoverActions=true 时点「确定」才触发 onOk",
+                "onTagRemove 返回 false 阻止删除后仍期望 onChange 触发——src 实证（index.tsx:236）返回 false 时直接 return，不会触发 onChange"
+            ]
+        },
+        "onOk": {
+            "signature": "(options: SelectedOptions) => void",
+            "asyncSupported": false,
+            "examples": [
+                "showPopoverActions=true 时用户点「确定」按钮触发，options 为当前选中列表",
+                "适合「选择后需要二次确认」场景——弹框有确认/取消按钮"
+            ],
+            "commonMistakes": [
+                "showPopoverActions=false 时期望 onOk 触发——不会，此时直接监听 onChange",
+                "onOk 和 onChange 同时监听导致重复处理——showPopoverActions=true 时推荐只用 onOk，不依赖 onChange"
+            ]
+        },
+        "onSearch": {
+            "signature": "(searchKey: string) => void",
+            "asyncSupported": false,
+            "examples": [
+                "showSearch=true 时用户输入触发，searchKey 为当前输入字符串",
+                "服务端搜索：在 onSearch 中更新请求参数，配合 params 刷新数据"
+            ],
+            "commonMistakes": [
+                "不传 onSearch 时期望服务端搜索——不传则组件做客户端过滤（realTimeSearch=true 时），服务端搜索必须传 onSearch"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "checkable=false 单选时 onChange 的 options 是 SelectOpt 对象而非数组，直接用数组方法报错",
+            "wrong": "onChange={(options) => options.map(o => o.key)}  // checkable=false 时 options 是对象，没有 .map()",
+            "right": "onChange={(options) => { if (Array.isArray(options)) { /* 多选 */ } else { /* 单选，options 是 SelectOpt */ } }}"
+        },
+        {
+            "issue": "method 字段首字母大写（'Get'|'Post'），传 'GET'/'POST' 会被忽略",
+            "wrong": "method='GET'  // 源码 interface 定义是 'Get' | 'Post'，大小写不同",
+            "right": "method='Get'  // 或 method='Post'（src/ComboSelect/interface.tsx 实证）"
+        },
+        {
+            "issue": "SelectOpt 是 { disabled?: boolean; closable?: boolean; [key: string]: any }，索引签名允许任意字段，但不应假设 key/title 字段名——取决于 outputFields",
+            "wrong": "const key = options[0].key  // 假设出参字段名是 key，实际由 outputFields.outputKey 决定",
+            "right": "const { outputKey = 'key' } = outputFields || {}; const key = options[0][outputKey];"
+        },
+        {
+            "issue": "value 类型随 checkable 变化，单独声明 useState 类型需要联合",
+            "wrong": "const [val, setVal] = useState<SelectOpt[]>()  // checkable=false 时 value 是 SelectOpt，不是数组",
+            "right": "const [val, setVal] = useState<SelectOpt[] | SelectOpt | undefined>()"
+        },
+        {
+            "issue": "嵌套 TableProps 时必须用 Para UI 的 headData（不是 antd 的 columns），字段结构也不同",
+            "wrong": "TableProps={{ columns: [{ title: '姓名', dataIndex: 'title' }] }}  // TS2353: 'columns' does not exist in type TableProps",
+            "right": "TableProps={{ headData: [{ name: 'title', label: '姓名', width: 200 }] }}  // headData 每项用 { name, label, width? }，name 对应数据字段 key，label 是表头显示文字"
+        }
+    ],
+    "mapping": {
+        "realComponent": "ComboSelect",
+        "adapter": null
+    }
+}