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

package/es/ScrollBar/component.json

@@ -0,0 +1,115 @@
+{
+    "name": "ScrollBar",
+    "category": "Layout",
+    "description": "滚动条美化:既支持全局 CSS 主题(默认场景),也提供 stand-alone 自驱动组件(虚拟列表/Canvas 等高级场景)",
+    "semantic": {
+        "intent": [
+            "美化原生滚动条",
+            "自驱动滚动指示器"
+        ],
+        "useCases": [
+            "固定高度内容溢出滚动(模式 A)",
+            "横向画廊(模式 A)",
+            "侧边栏/抽屉内容(模式 A)",
+            "虚拟列表/Canvas 自定义滚动(模式 B)"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "themedNative": {
+            "meaning": "模式 A:全局 className 主题 + native overflow(99% 场景推荐);使用 className `paraui-v4-scrollbar-{small|medium|large}{-deep}?` + native overflow:auto,不需要 import 任何组件"
+        },
+        "selfDriven": {
+            "meaning": "模式 B:<ScrollBar> stand-alone 组件,业务侧自驱动 scroll state(虚拟列表/Canvas 高级场景);组件本身不接受 children"
+        }
+    },
+    "states": [
+        "default",
+        "scrolling"
+    ],
+    "idealProps": {
+        "type": {
+            "type": "'horizontal' | 'vertical'",
+            "values": ["horizontal", "vertical"],
+            "default": "'vertical'",
+            "description": "(模式 B)滚动条方向"
+        },
+        "size": {
+            "type": "'small' | 'medium' | 'large'",
+            "values": ["small", "medium", "large"],
+            "default": "'large'",
+            "description": "(模式 B)滚动条粗细;small/medium 同款细(4px),large 粗(8px)"
+        },
+        "color": {
+            "type": "'deep' | 'light'",
+            "values": ["deep", "light"],
+            "default": "'light'",
+            "description": "(模式 B)配色;light 浅背景,deep 深背景"
+        },
+        "scrollTotalLength": {
+            "type": "number",
+            "description": "(模式 B)内容总滚动距离(px);= contentTotalSize - visualWindowSize;业务侧从 scrollHeight - clientHeight 计算并传入"
+        },
+        "scrollLength": {
+            "type": "number",
+            "description": "(模式 B)当前滚动距离(px);业务侧从 native scrollTop/scrollLeft 同步进来;变化时组件移动滑块位置"
+        },
+        "onScroll": {
+            "type": "function",
+            "signature": "(val: number) => void",
+            "description": "(模式 B)用户拖拽滚动条时回调;val = 用户操作后业务侧应同步到 native 元素的 scrollTop/scrollLeft 值"
+        },
+        "themedClassName": {
+            "type": "string (literal)",
+            "description": "(模式 A)在 native overflow 容器上加 className,从下面选一个:'paraui-v4-scrollbar-small' / 'paraui-v4-scrollbar-medium' / 'paraui-v4-scrollbar-large' / '*-deep' 深色变体;src/Styles/scrollbar.scss 实现 ::-webkit-scrollbar-* 美化"
+        }
+    },
+    "do": [
+        "默认场景(限高容器 + 子内容溢出)用模式 A:className 主题 + native overflow:auto",
+        "横向滚动用 overflowX:auto + className 'paraui-v4-scrollbar-small' 等主题",
+        "虚拟列表 / Canvas 等业务侧已有 scroll state 的场景用模式 B:<ScrollBar /> 组件 + scrollTotalLength + scrollLength",
+        "深色背景上的滚动条用 *-deep 变体(浅色背景上保持默认或显式 light)"
+    ],
+    "dont": [
+        "**不要给 <ScrollBar> 组件传 children**(它不是 scroll 容器,是 visual indicator)",
+        "不要在普通业务场景重复实现 scrollTotalLength/scrollLength 计算 — 用模式 A className 即可",
+        "不要嵌套两层 ScrollBar 容器(双滚动条体验差)",
+        "不要忘了模式 B 必须搭配 native overflow:hidden 的容器才能视觉上接管滚动"
+    ],
+    "events": {
+        "onScroll": {
+            "signature": "(val: number) => void",
+            "asyncSupported": false,
+            "examples": [
+                "用户拖拽滚动条时触发，val = 应同步到 native 元素的 scrollTop/scrollLeft 值",
+                "onScroll={(val) => { nativeRef.current.scrollTop = val; setScrollLength(val); }}",
+                "双向绑定：业务侧同时监听 native onScroll 更新 scrollLength prop，ScrollBar.onScroll 更新 native scrollTop"
+            ],
+            "commonMistakes": [
+                "只传 onScroll 未更新 native 元素的 scrollTop——val 是期望值，需业务侧手动同步到 DOM",
+                "onScroll 和 scrollLength 没有形成闭环——用户拖 scrollbar 时 onScroll 触发更新 scrollTop；native 滚动时 onScroll 不触发，需监听 native onScroll 更新 scrollLength"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "ScrollBar 组件的 Props interface 名是 Props（不是 ScrollBarProps），外部无法直接 import 类型",
+            "wrong": "import { ScrollBarProps } from '@para-ui/core/ScrollBar'  // 类型未导出",
+            "right": "// 直接使用 JSX 不需要类型引用；如需类型可自行 declare 或用 React.ComponentProps<typeof ScrollBar>"
+        },
+        {
+            "issue": "scrollTotalLength 传错含义——应是「可滚动距离」不是「内容总高度」",
+            "wrong": "scrollTotalLength={contentHeight}  // 期望传内容总高度——实际应传 scrollHeight - clientHeight",
+            "right": "scrollTotalLength={scrollHeight - clientHeight}  // = contentTotalSize - visualWindowSize"
+        },
+        {
+            "issue": "模式 A（className 主题）不需要 import ScrollBar 组件，直接加 className 即可",
+            "wrong": "import ScrollBar from '@para-ui/core/ScrollBar'; <ScrollBar>...</ScrollBar>  // ScrollBar 不接受 children",
+            "right": "<div className='paraui-v4-scrollbar-small' style={{overflowY: 'auto'}}>...</div>  // 模式 A 不 import 组件"
+        }
+    ],
+    "mapping": {
+        "realComponent": "ScrollBar",
+        "adapter": null
+    }
+}

package/es/Search/component.json

@@ -0,0 +1,177 @@
+{
+    "name": "Search",
+    "category": "Data Entry",
+    "description": "搜索框组件，支持受控/非受控模式、清空按钮、回车和点击按钮触发搜索",
+    "semantic": {
+        "intent": [
+            "搜索",
+            "过滤"
+        ],
+        "useCases": [
+            "列表搜索",
+            "全局搜索",
+            "筛选"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "focused"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "string",
+            "description": "受控输入值（src/Search/index.tsx:26 实证）。与 `defaultValue` 互斥——传 value 后为受控模式，内部 state 不自动更新，需配合 onChange 手动同步"
+        },
+        "defaultValue": {
+            "type": "string",
+            "description": "非受控初始值（src/Search/index.tsx:24 实证）。组件 mount 时一次性设置，之后内部管理输入 state。与 value 互斥——不要同时传"
+        },
+        "placeholder": {
+            "type": "string | ReactNode",
+            "description": "输入框占位文案（src/Search/index.tsx:22 实证，类型 ReactNode，实际用 string 即可）。默认空字符串"
+        },
+        "allowClear": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示清空按钮（src/Search/index.tsx:28 实证，默认 true）。清空时触发 `onClear` 回调"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(val: string, event: React.ChangeEvent<HTMLInputElement> | null) => void",
+            "description": "输入值变化回调（src/Search/index.tsx:30 实证签名，两参：val 字符串值 + event 原生事件）。⚠️ **第一参是 string 值，不是 event**——区别于原生 input onChange。当点击搜索按钮且未传 onClickBtn 时也会触发 onChange（event 此时为 null）"
+        },
+        "onClickBtn": {
+            "type": "function",
+            "signature": "(val: string) => void",
+            "description": "点击右侧搜索按钮的回调（src/Search/index.tsx:40 实证签名）。参数 val 为当前输入框的值。⚠️ **若不传 onClickBtn，点击按钮会 fallback 触发 onChange**（src:99-104）。`onClickRightIcon` 是其已废弃别名"
+        },
+        "onEnter": {
+            "type": "function",
+            "signature": "(event: React.KeyboardEvent<HTMLInputElement>) => void",
+            "description": "回车键按下的回调（src/Search/index.tsx:46 实证签名）。通常与 onClickBtn 配合覆盖「按钮触发搜索」和「回车触发搜索」两种路径"
+        },
+        "onClear": {
+            "type": "function",
+            "signature": "() => void",
+            "description": "点击清空按钮的回调（src/Search/index.tsx:44 实证签名，无参）。清空后输入框值变为空字符串；allowClear=true 时清空按钮才可见"
+        },
+        "onFocus": {
+            "type": "function",
+            "signature": "(event: React.FocusEvent<HTMLInputElement>) => void",
+            "description": "输入框获得焦点的回调（src/Search/index.tsx:34 实证签名）"
+        },
+        "onBlur": {
+            "type": "function",
+            "signature": "(event: React.FocusEvent<HTMLInputElement>) => void",
+            "description": "输入框失去焦点的回调（src/Search/index.tsx:32 实证签名）"
+        },
+        "size": {
+            "type": "enum",
+            "values": [
+                "small",
+                "medium",
+                "large"
+            ],
+            "default": "large",
+            "description": "控件大小（src/Search/index.tsx:18 实证，默认 large）"
+        },
+        "radius": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否使用圆角样式（src/Search/index.tsx:20 实证）"
+        },
+        "onClickRightIcon": {
+            "type": "function",
+            "signature": "(val: string) => void",
+            "description": "⚠️ **已废弃，请使用 `onClickBtn`**（src/Search/index.tsx:41 注释实证）。点击输入框右侧图标的回调，与 onClickBtn 同时触发"
+        },
+        "onKeydown": {
+            "type": "function",
+            "signature": "(event: React.KeyboardEvent<HTMLInputElement>) => void",
+            "description": "键盘按下事件回调（src/Search/index.tsx:36 实证）。⚠️ **注意拼写：onKeydown（非 onKeyDown）**，prop 名首字母 d 小写"
+        },
+        "onKeyUp": {
+            "type": "function",
+            "signature": "(event: React.KeyboardEvent<HTMLInputElement>) => void",
+            "description": "键盘抬起事件回调（src/Search/index.tsx:38 实证）"
+        }
+    },
+    "do": [
+        "支持回车搜索：同时传 onEnter 和 onClickBtn 覆盖「回车触发」和「点击按钮触发」两条路径",
+        "提供清空按钮：allowClear 默认 true，清空时只触发 onClear，不触发 onChange",
+        "受控模式：传 value + onChange 实现受控；onChange 第一参是 string 值（不是 event）",
+        "非受控模式：只传 defaultValue，内部管理输入 state；不要同时传 value 和 defaultValue"
+    ],
+    "dont": [
+        "不要把 onChange 的第一参当 event 使用——Search.onChange 签名是 (val: string, event) 而非 antd Input.onChange 的 (event) 签名",
+        "不要忽略 onClickBtn 为空时点击搜索按钮的 fallback 行为——未传 onClickBtn 时点击会触发 onChange（event 为 null）",
+        "搜索时不给反馈（网络搜索场景应配合 loading 状态）"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: string, event: React.ChangeEvent<HTMLInputElement> | null) => void",
+            "asyncSupported": false,
+            "examples": [
+                "用户实时输入时触发，val 是当前输入框字符串值",
+                "点击右侧搜索按钮且未传 onClickBtn 时也触发，此时 event 为 null",
+                "受控用法：const [keyword, setKeyword] = useState(''); <Search value={keyword} onChange={(val) => setKeyword(val)} />"
+            ],
+            "commonMistakes": [
+                "误按 antd Input 习惯写 onChange={(e) => setValue(e.target.value)} — 第一参是 string 不是 event",
+                "期望清空按钮触发 onChange — 清空只触发 onClear，需同时监听 onClear 来清空外部 state",
+                "忘记 onClickBtn 未传时 onChange event 参数可能为 null — 应做 null 判断再访问 event.target"
+            ]
+        },
+        "onClickBtn": {
+            "signature": "(val: string) => void",
+            "asyncSupported": false,
+            "examples": [
+                "用户点击右侧搜索图标时触发，val 为当前输入框的值",
+                "通常与 onEnter 一起传：点击和回车都调用同一个 search 函数"
+            ],
+            "commonMistakes": [
+                "不传 onClickBtn 时点击按钮 fallback 触发 onChange（event=null）— 若只需按钮触发必须显式传 onClickBtn",
+                "与 onClickRightIcon 混淆 — onClickRightIcon 是 onClickBtn 的已废弃别名，二者同时触发"
+            ]
+        },
+        "onEnter": {
+            "signature": "(event: React.KeyboardEvent<HTMLInputElement>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "用户在输入框按回车键触发，event 是 KeyboardEvent",
+                "取当前值：event.currentTarget.value 或从外部 state 直接读 keyword"
+            ],
+            "commonMistakes": [
+                "与 onClickBtn 语义重复时未合并为同一个函数 — 可在父组件定义 handleSearch 同时传给两个 prop",
+                "假设 onEnter 触发时 onChange 也会触发 — 回车不会触发 onChange，需在 onEnter 里单独处理搜索逻辑"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "onChange 签名与原生 input onChange 不同，第一参是 string 值而非 event",
+            "wrong": "onChange={(e) => setVal(e.target.value)}  // TS 报 string 没有 .target 属性",
+            "right": "onChange={(val) => setVal(val)}  // val: string 直接使用"
+        },
+        {
+            "issue": "onKeydown prop 名小写 d，不是 onKeyDown（驼峰 D）",
+            "wrong": "<Search onKeyDown={handler} />  // prop 名不存在，静默无效",
+            "right": "<Search onKeydown={handler} />  // src/Search/index.tsx:36 interface 实证 onKeydown 小写 d"
+        },
+        {
+            "issue": "onClickRightIcon 已废弃，运行时与 onClickBtn 同时触发造成双重执行",
+            "wrong": "<Search onClickRightIcon={handleSearch} />  // 废弃 API，src 注释明确不建议使用",
+            "right": "<Search onClickBtn={handleSearch} />  // 推荐替代 prop"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Search",
+        "adapter": null
+    }
+}

package/es/Search/index.d.ts

@@ -33,7 +33,7 @@ export interface SearchProps {
     onClear?: () => void;
     /** 回车事件 */
     onEnter?: (event: React.KeyboardEvent<HTMLInputElement>) => void;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export declare const Search: FunctionComponent<SearchProps>;
 export default Search;

package/es/Select/component.json

@@ -0,0 +1,244 @@
+{
+    "name": "Select",
+    "category": "Form",
+    "description": "下拉选择器，支持单选、多选、搜索和树形数据",
+    "semantic": {
+        "intent": [
+            "选择选项",
+            "搜素选择",
+            "多选"
+        ],
+        "useCases": [
+            "表单选择",
+            "数据筛选",
+            "标签输入"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "default": {
+            "meaning": "标准选择器"
+        },
+        "multiple": {
+            "meaning": "多选选择器"
+        },
+        "search": {
+            "meaning": "带搜索的选择器"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error",
+        "open",
+        "loading"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "T | T[] | undefined",
+            "description": "当前选中的值（受控）。**Select 是泛型组件 `Select<T extends SelectOptionValue, Item extends SelectOptionBase>`**——传 `<Select<'zh-CN'|'en-US'>>` 收紧 value 类型避免 as 强转（DEFECT-003）；single=undefined 表示无选中、multiple=[] 表示空选"
+        },
+        "defaultValue": {
+            "type": "T | T[]",
+            "description": "默认值（非受控）；同时传 value + defaultValue 时以 value 为准"
+        },
+        "onChange": {
+            "type": "(val: T | T[] | undefined, e: React.SyntheticEvent) => void",
+            "description": "选中值变化回调。**签名 `(val: T | T[] | undefined, e: React.SyntheticEvent) => void`**（DEFECT-001:src/Select/index.tsx:151/168/240 实证 — 带 e、带泛型 T、明确清空时 val=undefined 而非 '' 或 null）。**multiple=false 时** val 为 `T | undefined`（单选清空 → undefined）；**multiple=true 时** val 为 `T[]`（空数组 [] 表已清空）。第二参数 e 是合成事件，业务侧不需要可省略。**泛型用法见 docs/view/select/api.ts 顶部 \"泛型签名\" 注释段**"
+        },
+        "list": {
+            "type": "Item[]",
+            "description": "数据源。`Item extends SelectOptionBase`，即 `{ label?: ReactNode; value?: string|number|boolean; disabled?: boolean; children?: SelectOptionBase[] }`。**自定义字段名时（如 cityName/cityCode），interface 必须 extends SelectOptionBase 或加 `label?/value?` 可选字段，否则 TypeScript 报不兼容错误。** 推荐：`interface MyOption extends SelectOptionBase { cityName: string; cityCode: string }` 配合 `showName='cityName' showValue='cityCode'`"
+        },
+        "renderContent": {
+            "type": "function",
+            "signature": "(item: Item, type: boolean | 'more') => ReactNode",
+            "description": "自定义选项 / 选中态渲染（DEFECT-002）。**第二参数 type 三态**：`type === false` → 渲染选中态（在选择框中回显）；`type === true` → 渲染下拉浮层中的每一项；`type === 'more'` → 渲染下拉浮层底部的『更多』占位项。historic 命名 isSelect 实际语义按 type 三态对应"
+        },
+        "placeholder": {
+            "type": "ReactNode",
+            "description": "选择框默认文字"
+        },
+        "disabled": {
+            "type": "boolean | any[]",
+            "default": false,
+            "description": "禁用控制。boolean=整体禁用；any[]=**禁用部分选项的 value 列表**（src 实证 `disabled.indexOf(val)`，传 value 数组而非 option 对象数组或索引）"
+        },
+        "allowClear": {
+            "type": "boolean",
+            "default": false,
+            "description": "支持清除"
+        },
+        "search": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否使能搜索（不传 fetchSuggestions 时按 showName 字段做客户端 includes 子串匹配）"
+        },
+        "multiple": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否多选"
+        },
+        "size": {
+            "type": "enum",
+            "values": [
+                "small",
+                "medium",
+                "large"
+            ],
+            "default": "large"
+        },
+        "label": {
+            "type": "ReactNode",
+            "description": "标签文本"
+        },
+        "labelMode": {
+            "type": "enum",
+            "values": [
+                "outside",
+                "inside"
+            ],
+            "default": "outside"
+        },
+        "showName": {
+            "type": "string",
+            "default": "label",
+            "required": false,
+            "description": "数据源的显示字段名，默认 'label'。⚠️ AI 常见错误：数据源字段名不是 label 时忘记传此 prop，导致下拉无文字或显示 undefined。正确做法：数据格式为 { name, id } 时传 showName='name'"
+        },
+        "showValue": {
+            "type": "string",
+            "default": "value",
+            "required": false,
+            "description": "数据源的取值字段名，默认 'value'。⚠️ AI 常见错误：数据源字段名不是 value 时忘记传此 prop，导致 onChange 返回 undefined 或选中异常。正确做法：数据格式为 { name, id } 时传 showValue='id'"
+        },
+        "childrenName": {
+            "type": "string",
+            "default": "children",
+            "required": false,
+            "description": "数据源的子级字段名，默认 'children'，树形 Select 时使用。数据格式为 { name, id, subItems } 时传 childrenName='subItems'"
+        },
+        "fetchSuggestions": {
+            "type": "(inputValue: string, callback: (suggestions: any[]) => void) => void",
+            "required": false,
+            "description": "异步搜索回调，search=true 时生效。用户输入时触发，通过 callback 返回建议列表。⚠️ 传了 fetchSuggestions 则客户端 includes 过滤失效，建议列表完全由 callback 控制"
+        },
+        "searchModel": {
+            "type": "enum",
+            "values": ["outside", "inside"],
+            "default": "inside",
+            "required": false,
+            "description": "搜索框位置，outside=浮层外（触发框变搜索框）/ inside=浮层内（下拉顶部搜索框，默认）"
+        },
+        "onClear": {
+            "type": "() => void",
+            "required": false,
+            "description": "点击清空按钮时触发，allowClear=true 时有效"
+        },
+        "onEnterInput": {
+            "type": "(val: string) => void",
+            "required": false,
+            "description": "搜索框回车事件，val 为当前搜索框输入值"
+        }
+    },
+    "commonMisconceptions": [
+        "AI 常见错误：数据源字段名不是 label/value 时，忘记传 showName/showValue，导致下拉无数据或显示异常。正确做法：数据格式为 { name, id } 时，应传 showName='name' showValue='id'",
+        "AI 常见错误：自定义 interface（如 { cityName, cityCode }）直接传给 list，TypeScript 报 '不满足 SelectOptionBase'——正确做法：interface MyOption extends SelectOptionBase { cityName: string; cityCode: string }，或在 interface 里加 label?/value? 可选字段",
+        "AI 常见错误：onChange 单选清空时误以为 val 为 '' 或 null——实际为 undefined（DEFECT-001）",
+        "AI 常见错误：按 renderContent 参数名 isSelect 字面理解——实际按 type 三态（false=选中回显/true=下拉项/'more'=占位）（DEFECT-002）"
+    ],
+    "do": [
+        "选项过多时应当使用 search 开启搜索功能",
+        "使用 list 属性传入其数据源以优化性能",
+        "**显式收紧 value 泛型**：`<Select<'zh-CN'|'en-US'> value={lang} ... />`，避免 as 强转（DEFECT-003）",
+        "renderContent 用 type 取值区分三态：`type === false` 选中态、`type === true` 下拉项、`type === 'more'` 占位项",
+        "disabled 数组传 value 列表（不是 option 对象、不是索引）"
+    ],
+    "dont": [
+        "选项少于 5 个时建议优先使用 Radio.Group",
+        "直接在 options 中渲染过于复杂的 DOM 结构",
+        "不要假设 onChange 单选清空时 val 为 \\'\\\\'\\\\' 或 null——实际为 undefined（DEFECT-001）",
+        "不要按 renderContent 参数名 isSelect 字面理解——实际按 type 三态（DEFECT-002）"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: T | T[] | undefined, e: React.SyntheticEvent) => void",
+            "asyncSupported": false,
+            "examples": [
+                "单选时接收选中项 value（清空时 val 为 undefined，不是 '' 或 null）",
+                "多选时接收当前已选项的 value 数组（清空时 val 为 []）",
+                "结合泛型收紧类型：<Select<number> onChange={(val) => setId(val)} />（val 推断为 number | undefined）"
+            ],
+            "commonMistakes": [
+                "假设单选清空时 val 为 ''——实际为 undefined（src/Select/index.tsx:151 `onChange?: (val: T | undefined, e: React.SyntheticEvent) => void`）",
+                "忽略第二参数 e（SyntheticEvent），直接写 onChange={handleChange} 时 TypeScript 报签名不匹配——应写 (val, _e) => handle(val)",
+                "多选模式下假设 val 不会是数组——multiple=true 时 val 始终是 T[]，即使只选了一项也是 [item]",
+                "假设 onChange 只在点击选项时触发——清空按钮（allowClear=true）也触发 onChange，此时 val 为 undefined 或 []"
+            ]
+        },
+        "onEnter": {
+            "signature": "(val: T | T[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "单选模式：用户在选中项后按回车，val 为当前选中的单值",
+                "多选模式：val 为当前已选的 T[] 数组"
+            ],
+            "commonMistakes": [
+                "与 onEnterInput 混淆——onEnter 是选中回车（在选项上回车），onEnterInput 是搜索框输入回车（val 为搜索字符串）",
+                "假设 onEnter 一定触发——仅在 search=true 或 input=true 模式下且搜索框/输入框有焦点时有效"
+            ]
+        },
+        "onClear": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "用户点击清空图标时触发（需 allowClear=true），此时 onChange 也会同时触发"
+            ],
+            "commonMistakes": [
+                "只监听 onClear 而不监听 onChange——受控模式下还需在 onChange 中同步清空 state",
+                "allowClear=false 时期望 onClear 触发——不会触发，清空按钮不显示"
+            ]
+        },
+        "onEnterInput": {
+            "signature": "(val: string) => void",
+            "asyncSupported": false,
+            "examples": [
+                "搜索框回车时触发，val 为当前输入的字符串——适合实现「按回车新建标签」场景"
+            ],
+            "commonMistakes": [
+                "与 onEnter 混淆——onEnterInput 是搜索输入框回车，onEnter 是选项选中回车"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "onChange 签名带第二参数 e: React.SyntheticEvent，直接传函数时签名不匹配",
+            "wrong": "onChange={setLang}  // setLang: (val: string) => void，少了 e 参数",
+            "right": "onChange={(val, _e) => setLang(val ?? '')}  // 显式声明，保持签名兼容"
+        },
+        {
+            "issue": "自定义数据结构未 extends SelectOptionBase，直接传给 list 报类型错误",
+            "wrong": "interface CityOpt { cityName: string; cityCode: string } // 无 label/value，不兼容 SelectOptionBase",
+            "right": "interface CityOpt extends SelectOptionBase { cityName: string; cityCode: string } // 配合 showName='cityName' showValue='cityCode'"
+        },
+        {
+            "issue": "disabled 传对象数组而非 value 列表，运行时选项不禁用",
+            "wrong": "disabled={[{ label: 'A', value: 'a' }]}  // 传了整个 option 对象，indexOf 永远匹配不到",
+            "right": "disabled={['a', 'b']}  // 传禁用项的 value（取值字段）列表（src 实证 disabled.indexOf(val)）"
+        },
+        {
+            "issue": "多选模式 value 传单值而非数组，受控不生效",
+            "wrong": "<Select multiple value={'a'} />  // multiple=true 时 value 应为 T[]",
+            "right": "<Select multiple value={['a']} />  // 多选 value 始终是数组"
+        },
+        {
+            "issue": "renderContent 用 isSelect 命名的第二参数字面理解为 boolean，忽略 'more' 态",
+            "wrong": "renderContent={(item, isSelect) => isSelect ? <Selected /> : <Option />}  // 漏掉 isSelect==='more' 分支",
+            "right": "renderContent={(item, type) => type === false ? <Selected /> : type === 'more' ? <MoreTag /> : <Option />}"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Select",
+        "adapter": null
+    }
+}