@para-ui/core 5.0.0-beta.9 → 5.0.1

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/Search/index.js

@@ -1,7 +1,7 @@
 import { j as i } from "../_virtual/jsx-runtime.js";
 import { useState as N, useEffect as d } from "react";
 import { TextField as B } from "../TextField/index.js";
-import { Search as F } from "../node_modules/@para-ui/icons/Search/index.js";
+import { Search as F } from "../para-ui-core/node_modules/@para-ui/icons/Search/index.js";
 import { $prefixCls as c } from "../GlobalContext/constant.js";
 import './index.css';/* empty css           */
 const b = (e) => {

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

package/es/Select/index.d.ts

@@ -10,7 +10,7 @@ export interface SelectOption extends SelectOptionBase {
     children?: SelectOption[];
 }
 /** Select 共享 props —— 不含随 multiple 变化的 value/defaultValue/onChange/onEnter/multiple */
-export interface SelectBaseProps<T extends SelectOptionValue = SelectOptionValue> extends HelperTextDetailProps {
+export interface SelectBaseProps<T extends SelectOptionValue = SelectOptionValue, Item extends SelectOptionBase = SelectOptionBase> extends HelperTextDetailProps {
     /** 样式class */
     className?: string;
     /** style */
@@ -44,13 +44,13 @@ export interface SelectBaseProps<T extends SelectOptionValue = SelectOptionValue
     /** 是否必填 */
     required?: boolean;
     /** 下拉选项数组 */
-    list: SelectOption[];
+    list: Item[];
     /**
      * 自定义渲染
      * item: 当前想数据
      * type: true 下拉选项 false 已选项 more: 更多选项
      * */
-    renderContent?: (item: SelectOption, type: boolean | 'more') => ReactNode;
+    renderContent?: (item: Item, type: boolean | 'more') => ReactNode;
     /** 下拉选中是否有图标, 默认有 */
     selectCheckIcon?: boolean;
     /** 显示名字段 */
@@ -74,7 +74,7 @@ export interface SelectBaseProps<T extends SelectOptionValue = SelectOptionValue
     /** 更多className */
     morePopoverClassName?: string;
     /** 返回输入建议的方法 */
-    fetchSuggestions?: (val: string, cb: (data: SelectOption[]) => void) => void;
+    fetchSuggestions?: (val: string, cb: (data: Item[]) => void) => void;
     /** 搜索框输入框回车事件 */
     onEnterInput?: (val: string) => void;
     /** 点击清空内容回调 */
@@ -85,7 +85,7 @@ export interface SelectBaseProps<T extends SelectOptionValue = SelectOptionValue
     blurChangeValueBol?: boolean;
 }
 /** 单选模式 */
-export interface SelectSingleProps<T extends SelectOptionValue = SelectOptionValue> extends SelectBaseProps<T> {
+export interface SelectSingleProps<T extends SelectOptionValue = SelectOptionValue, Item extends SelectOptionBase = SelectOptionBase> extends SelectBaseProps<T, Item> {
     /** 是否多选（未传或 false 为单选） */
     multiple?: false;
     /** 默认值（单选） */
@@ -99,7 +99,7 @@ export interface SelectSingleProps<T extends SelectOptionValue = SelectOptionVal
     onEnter?: (val: T) => void;
 }
 /** 多选模式 */
-export interface SelectMultipleProps<T extends SelectOptionValue = SelectOptionValue> extends SelectBaseProps<T> {
+export interface SelectMultipleProps<T extends SelectOptionValue = SelectOptionValue, Item extends SelectOptionBase = SelectOptionBase> extends SelectBaseProps<T, Item> {
     /** 是否多选 */
     multiple: true;
     /** 默认值（多选） */
@@ -115,7 +115,10 @@ export interface SelectMultipleProps<T extends SelectOptionValue = SelectOptionV
  * Select 的 props
  * - `multiple` 未传或为 `false`：value / defaultValue 为 `T`，onChange/onEnter 入参为 `T`（清空时 `undefined`）
  * - `multiple` 为 `true`：value / defaultValue 为 `T[]`，onChange/onEnter 入参为 `T[]`（清空时 `[]`）
+ * - 第二个泛型参数 `Item` 描述 `list` 行项的具体类型，默认 `SelectOptionBase`，
+ *   可传业务侧 DTO 接口（如 `{ label, value, id, time }`）以承载 `renderContent` /
+ *   `fetchSuggestions` 的端到端类型推导。
  */
-export type SelectProps<T extends SelectOptionValue = SelectOptionValue> = SelectSingleProps<T> | SelectMultipleProps<T>;
-declare function Select<T extends SelectOptionValue = SelectOptionValue>(outerProps: SelectProps<T>): import("react/jsx-runtime").JSX.Element;
+export type SelectProps<T extends SelectOptionValue = SelectOptionValue, Item extends SelectOptionBase = SelectOptionBase> = SelectSingleProps<T, Item> | SelectMultipleProps<T, Item>;
+declare function Select<T extends SelectOptionValue = SelectOptionValue, Item extends SelectOptionBase = SelectOptionBase>(outerProps: SelectProps<T, Item>): import("react/jsx-runtime").JSX.Element;
 export default Select;