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

package/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/SelectInput/component.json

@@ -0,0 +1,184 @@
+{
+    "name": "SelectInput",
+    "category": "Data Entry",
+    "description": "下拉输入框，结合下拉选择和文本输入",
+    "semantic": {
+        "intent": [
+            "组合输入",
+            "带搜索的选择"
+        ],
+        "useCases": [
+            "分类选择",
+            "带输入的下拉",
+            "联想输入"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "any",
+            "description": "受控值;multiple=true 时为数组,multiple=false(默认)时为单值;必须配合 onChange。**单值类型**:list 项 value 字段值(string / number 取决于 SelectOptionBase.value 实际类型)"
+        },
+        "defaultValue": {
+            "type": "any",
+            "description": "非受控默认值;类型规则同 value"
+        },
+        "onChange": {
+            "type": "(val, e) => void",
+            "description": "值变化回调。**实际签名**(协议 SI1):multiple=false → `(val: string | undefined, e: SyntheticEvent) => void`(清空时 val 为 undefined);multiple=true → `(val: string[], e) => void`。**val 是 list 项 value 字段值**(不是整个对象);业务 `(next: string) => void` 透传桥接:`onChange={(val) => onChange((val ?? '') as string)}` 显式过 undefined"
+        },
+        "list": {
+            "type": "SelectOptionBase[]",
+            "itemSchema": {
+                "label": { "type": "ReactNode", "required": true, "description": "选项显示文案" },
+                "value": { "type": "any", "required": true, "description": "选项值（onChange 回调的 val 是此字段值）" },
+                "children": { "type": "any[]", "description": "子选项" },
+                "disabled": { "type": "boolean", "description": "是否禁用" }
+            },
+            "description": "下拉选项数组;项 = `{ label: ReactNode, value: any, children?: any[], disabled?: boolean }`。空数组或不传时 showSelect 自动 false。**string[] 转换**(协议 SI5):`options.map(opt => ({label: opt, value: opt}))`"
+        },
+        "multiple": {
+            "type": "boolean",
+            "default": false,
+            "description": "多选模式;true 时 value 必须为数组"
+        },
+        "showSelect": {
+            "type": "boolean",
+            "description": "是否显示下拉浮层;未显式传时,有 list 自动 true,无 list 自动 false。显式 false 退化为纯输入框"
+        },
+        "showName": {
+            "type": "string",
+            "default": "label",
+            "description": "list 项中显示名字段名"
+        },
+        "showValue": {
+            "type": "string",
+            "default": "value",
+            "description": "list 项中选中值字段名"
+        },
+        "searchModel": {
+            "type": "'outside' | 'inside'",
+            "values": ["outside", "inside"],
+            "default": "inside",
+            "description": "搜索框位置(协议 SI3);outside=输入框永远显示在触发按钮位置(联想标签 / 主搜);inside=输入框在浮层展开后才显示(二级筛选)。**fetchSuggestions / 联想推荐 outside**"
+        },
+        "fetchSuggestions": {
+            "type": "(val: string, cb: (data: SelectOptionBase[]) => void) => void",
+            "description": "异步联想搜索;与 list 互斥。**搭配 searchModel='outside'**(协议 SI3 / SI4)"
+        },
+        "onEnterInput": {
+            "type": "(val: string) => void",
+            "description": "回车事件;val=当前输入框原始文本(非 list 项 value)。**输入新分类必传**(协议 SI4):用户输入下拉外文本时 onChange 不触发,只有 onEnterInput 能捕获"
+        },
+        "blurChangeValueBol": {
+            "type": "boolean",
+            "default": false,
+            "description": "失焦时是否将输入框文本写回 value;适合搜索式输入立即生效场景"
+        },
+        "labelMode": {
+            "type": "'outside' | 'inside'",
+            "values": ["outside", "inside"],
+            "default": "outside",
+            "description": "标题位置(注:此 prop 命名与 searchModel 不同语义)"
+        },
+        "overLine": {
+            "type": "boolean",
+            "default": false,
+            "description": "已选项是否换行;true=超出 chip 换行,false=单行 + 折叠 '+N'"
+        },
+        "disabled": {
+            "type": "boolean | any[]",
+            "description": "禁用;布尔禁全部,数组按 value 禁用部分选项"
+        },
+        "size": {
+            "type": "'small' | 'medium' | 'large'",
+            "values": ["small", "medium", "large"],
+            "default": "large",
+            "description": "尺寸"
+        }
+    },
+    "crossPropInteractions": [
+        "multiple + onChange 签名 = 两套 union(false 时 val 可 undefined / true 时 val: string[])",
+        "fetchSuggestions + searchModel = 推荐配 outside(协议 SI3)",
+        "showSelect=false → 强制 searchModel='outside'(纯输入框模式)",
+        "onEnterInput + outside = 输入新分类的标准组合(协议 SI4)",
+        "list 项 value + showValue = 决定 onChange val 实际类型"
+    ],
+    "commonMisconceptions": [
+        "❌ onChange 单参直接透传 `onChange={onChange}` — 实际是双参 + val 可 undefined,TS 不符",
+        "❌ onChange val 是整个 SelectOptionBase 对象 — 实际是 value 字段值",
+        "❌ outside 模式下纯输入回车自动 onChange — 实际需要 onEnterInput 捕获",
+        "❌ fetchSuggestions 默认走 outside — 默认 inside,需显式 searchModel='outside'",
+        "❌ string[] 直接传 list — 必须 map 成 SelectOptionBase[] {label, value}"
+    ],
+    "do": [
+        "在需要选择并输入的场景使用（比 Select 更自由，比 TextField 带下拉）",
+        "支持联想搜索：配合 fetchSuggestions + searchModel='outside' 实现外部输入即触发联想",
+        "输入新值回车捕获：配合 onEnterInput 处理用户输入了下拉列表外的文本场景",
+        "list 必须传 SelectOptionBase[]：string[] 数组先 map 成 `{label: opt, value: opt}` 形式"
+    ],
+    "dont": [
+        "选项过多时不分页（应配合 fetchSuggestions 做异步分页）",
+        "忽略键盘操作（onEnterInput 是捕获回车新建条目的关键入口）",
+        "直接把 string[] 传给 list——必须 map 成 `[{label, value}]` 形式（协议 SI5）"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: T | T[] | undefined, e: React.SyntheticEvent) => void",
+            "asyncSupported": false,
+            "examples": [
+                "单选时 val 为选中项 value 字段值（清空时 val 为 undefined，不是 ''）",
+                "多选时 val 为已选项 value 字段值数组",
+                "受控桥接：onChange={(val) => setVal((val ?? '') as string)}"
+            ],
+            "commonMistakes": [
+                "直接传 onChange={setValue} 时 TS 报签名不匹配——需要 (val, _e) => setValue(val ?? '')",
+                "期望输入框回车触发 onChange——outside 模式下用户输入未选中选项时不触发 onChange，只触发 onEnterInput",
+                "误以为 val 是整个 SelectOptionBase 对象——val 是 value 字段值（由 showValue 决定）"
+            ]
+        },
+        "onEnterInput": {
+            "signature": "(val: string) => void",
+            "asyncSupported": false,
+            "examples": [
+                "用户在输入框回车时触发，val 为输入框的原始字符串",
+                "新建标签场景：onEnterInput={(newTag) => setTags([...tags, newTag])}"
+            ],
+            "commonMistakes": [
+                "与 onChange 混淆——onEnterInput 是捕获「选项外文本回车」，onChange 是选项选中",
+                "忘记传 onEnterInput 导致用户输入新值回车无任何响应"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "onChange 签名有第二参 e: SyntheticEvent，单参函数直接传报 TS 错误",
+            "wrong": "onChange={setVal}  // setVal: (v: string) => void，缺少 e 参数",
+            "right": "onChange={(val, _e) => setVal(val ?? '')}  // 显式声明两参，_e 忽略"
+        },
+        {
+            "issue": "list 传 string[] 直接报 TS 不兼容 SelectOptionBase[]",
+            "wrong": "list={['option1', 'option2']}  // string 不满足 SelectOptionBase 接口",
+            "right": "list={['option1', 'option2'].map(s => ({ label: s, value: s }))}  // 转换为 SelectOptionBase[]"
+        },
+        {
+            "issue": "SelectInput extends SelectProps（Single | Multiple 联合），在泛型 T 未能被推断时 onChange 的 val 参数可能隐式 any（TS7006），需要显式标注参数类型",
+            "wrong": "onChange={(val, _e) => setValue(val as string)}  // TS7006: val 隐式 any（泛型推断失败时）",
+            "right": "// 单选模式：\nonChange={(val: string | undefined, _e: React.SyntheticEvent) => setValue(val)}\n// 多选模式：\nonChange={(val: string[], _e: React.SyntheticEvent) => setValues(val ?? [])}"
+        }
+    ],
+    "mapping": {
+        "realComponent": "SelectInput",
+        "adapter": null
+    }
+}

package/Selector/component.json

@@ -0,0 +1,203 @@
+{
+    "name": "Selector",
+    "category": "Data Entry",
+    "description": "选择器组件，支持分页、搜索、多选等功能",
+    "semantic": {
+        "intent": [
+            "复杂选择",
+            "数据筛选"
+        ],
+        "useCases": [
+            "人员选择",
+            "组织选择",
+            "资源分配"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "lr": {
+            "meaning": "左右布局"
+        },
+        "tb": {
+            "meaning": "上下布局"
+        },
+        "list": {
+            "meaning": "列表布局"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "Record<string, any>[] | Record<string, any>",
+            "description": "受控值;radio 模式为单对象(初始无选可传 null),check 模式为对象数组;无 selectMode 时无效。**最小回显格式**(协议 S1):value 对象只需含 rowKey 字段即可匹配回显;外部 string[] keys 反查 = `items.filter(it => keys.includes(it[rowKey]))`"
+        },
+        "defaultValue": {
+            "type": "Record<string, any>[] | Record<string, any>",
+            "description": "非受控默认值;类型规则同 value"
+        },
+        "onChange": {
+            "type": "(val, node, rowData) => void",
+            "description": "值变化回调;**radio 模式 val 为 Record<string,any>**(单对象 / null),**check 模式 val 为 Record<string,any>[]**(数组 / null);node=出站处理后数据(若传 backDataFieldConfig 则字段映射)、rowData=原始;**出站 keys 提取**:`val.map(it => it[rowKey])`(协议 S1);onSelect 返回 true 时不触发"
+        },
+        "onSelect": {
+            "type": "(item, bol, isAllCheck) => boolean | Promise<boolean>",
+            "description": "勾选事件;返回 true 阻断 onChange(二次确认场景);先于 onChange 触发"
+        },
+        "layout": {
+            "type": "'lr' | 'tb' | 'list'",
+            "values": ["lr", "tb", "list"],
+            "default": "lr",
+            "description": "布局;lr=左右、tb=上下、list=纯列表(无已选区,适合内嵌)。**三种 layout 的 value/onChange 受控行为完全一致**(协议 S4),只有视觉差异"
+        },
+        "selectMode": {
+            "type": "'radio' | 'check'",
+            "values": ["radio", "check"],
+            "description": "选择模式;radio=单选;check=多选+全选;undefined=只读浏览"
+        },
+        "nodeMode": {
+            "type": "'leaf' | 'branch'",
+            "values": ["leaf", "branch"],
+            "default": "branch",
+            "description": "节点选择粒度;leaf=只选叶子;branch=分支/叶子皆可"
+        },
+        "rowKey": {
+            "type": "string",
+            "default": "'key'",
+            "description": "唯一标识字段(协议 S2);**影响 disabled/disabledChild 数组匹配 + value 对象匹配 + 缓存 + 出站 val.key**;data 用 id 时必须传 `rowKey='id'`"
+        },
+        "data": {
+            "type": "SelectorAnyJson[]",
+            "description": "本地数据源;与 url 互斥"
+        },
+        "url": {
+            "type": "string",
+            "description": "远程数据请求地址;搭配 method/params/paramsCallback 使用"
+        },
+        "pagination": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否远程分页;仅 url 模式生效"
+        },
+        "search": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否显示搜索框。**本地 data 模式内置关键词过滤无需 onSearch**(协议 S5);url 远程自动重发请求;自定义场景传 onSearch"
+        },
+        "searchTrigger": {
+            "type": "'onChange' | 'onEnter'",
+            "values": ["onChange", "onEnter"],
+            "default": "onChange",
+            "description": "搜索触发时机;onEnter 适合远程节流"
+        },
+        "fieldConfig": {
+            "type": "SelectorFieldConfigProps",
+            "description": "入站字段映射(mainTitle/subTitle/img/tag/info/children/parentId/key/type · 省略时自动应用默认值,详见 api.ts default 列)"
+        },
+        "backDataFieldConfig": {
+            "type": "SelectorFieldConfigProps",
+            "description": "出站字段映射;onChange 数据字段名转换;默认同 fieldConfig(出站字段名与入站一致)"
+        },
+        "disabled": {
+            "type": "string[] | boolean",
+            "default": false,
+            "description": "禁用;布尔禁全部,数组按 rowKey 禁用部分"
+        },
+        "isAllCheck": {
+            "type": "boolean",
+            "default": true,
+            "description": "复选模式下是否显示全选;仅 selectMode=check 生效"
+        }
+    },
+    "crossPropInteractions": [
+        "value + rowKey = 最小回显对象只需含 rowKey 字段(默认 'key')",
+        "selectMode + value 类型:radio→单对象/null,check→对象数组/null",
+        "layout='list' + value/onChange = 受控行为与 lr/tb 完全一致(协议 S4)",
+        "search + 本地 data = 内置过滤,无需 onSearch;+ url = 自动重发请求",
+        "rowKey + data + disabled[] = 三者用同一字段名匹配,改 rowKey 须全链路对齐"
+    ],
+    "commonMisconceptions": [
+        "❌ value 必须传完整对象(label/subTitle 等)— 仅需 rowKey 字段即可回显",
+        "❌ 本地 data + search 必须传 onSearch — 组件内置过滤,本地场景省略 onSearch",
+        "❌ layout='list' 不支持受控 value/onChange — 三种 layout 行为一致",
+        "❌ radio 模式初始无选不能传 null — 可传 null 或省略 value prop",
+        "❌ data 用 id 字段不改 rowKey — 必须传 rowKey='id' 否则静默 fail"
+    ],
+    "do": [
+        "支持服务端分页和搜索",
+        "提供面包屑导航",
+        "selectMode=check 多选场景显式传 value 数组 + onChange 接数组",
+        "data 本地数据源场景与 url 远程数据源场景二选一,不要同时传"
+    ],
+    "dont": [
+        "数据量大时不分页",
+        "忽略禁用状态",
+        "selectMode 切换为 radio 时仍把 value 设为数组(类型不匹配)",
+        "onSelect 返回 true 阻断 onChange 后忘记自行更新 value(导致 UI 与 state 不同步)"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: SelectorAnyJson[] | SelectorAnyJson | null, node: SelectorAnyJson, rowData: SelectorAnyJson) => void",
+            "asyncSupported": false,
+            "examples": [
+                "radio 模式：val 是单个 Record<string,any>，出站取 key 用 val[rowKey]",
+                "check 模式：val 是 Record<string,any>[]，出站取 key 列表用 val.map(it => it[rowKey])",
+                "清空时 val 为 null——受控外部 string[] 兜底：setSelected(val ? val.map(it => it[rowKey]) : [])"
+            ],
+            "commonMistakes": [
+                "误把 val 当 rowKey string[] 使用——onChange 返回对象/数组，取 key 需 val[rowKey] 或 map",
+                "忘记 rowKey 对齐——data 用 id 字段时传了 rowKey='id' 但 onChange 还用 val.key 取值（实际是 val.id）",
+                "radio 模式期望 val 是数组——radio 模式 val 始终是单对象（或 null），不是 [item]"
+            ]
+        },
+        "onSelect": {
+            "signature": "(item: SelectorAnyJson | SelectorAnyJson[], bol: boolean, isAllCheck: boolean) => Promise<boolean | void> | (boolean | void)",
+            "asyncSupported": true,
+            "examples": [
+                "返回 true 阻断 onChange：二次确认场景在 onSelect 里弹 Dialog，确认后手动调用 onChange 逻辑",
+                "返回 void/false 不阻断，onChange 正常触发",
+                "全选时 item 是 SelectorAnyJson[]（当前页所有项），isAllCheck=true"
+            ],
+            "commonMistakes": [
+                "返回 true 阻断 onChange 后忘记自行更新 value——UI 与 state 不同步",
+                "误以为 onSelect 和 onChange 是同一回调——onSelect 先触发且返回值控制是否触发 onChange"
+            ]
+        },
+        "onSearch": {
+            "signature": "(val: string, reqParams: SearchFuncProps) => Promise<SearchReqDataProps> | SearchReqDataProps",
+            "asyncSupported": true,
+            "examples": [
+                "自定义搜索：return { data: { data: filteredList } }（不分页）",
+                "分页搜索：return { data: { data: { list: arr, total: 100 } } }（pagination=true）"
+            ],
+            "commonMistakes": [
+                "本地 data 场景传了 onSearch——本地模式内置过滤无需 onSearch，传了会覆盖内置逻辑",
+                "返回格式错误：不分页应返回 data.data = SelectorAnyJson[]，分页应返回 data.data = { list, total }"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "data 用非 key 字段作唯一 ID 时忘记传 rowKey，导致选中值匹配静默失败",
+            "wrong": "data={[{ id: '1', label: 'A' }]} value={[{ id: '1' }]}  // 内部用 .key 匹配，id 字段被忽略",
+            "right": "data={[{ id: '1', label: 'A' }]} rowKey='id' value={[{ id: '1' }]}  // rowKey 告知用 id 字段"
+        },
+        {
+            "issue": "radio 模式 value 传对象数组，check 模式 value 传单对象——类型反了",
+            "wrong": "selectMode='radio' value={[{ key: '1' }]}  // radio 应为单对象",
+            "right": "selectMode='radio' value={{ key: '1' }}  // 单对象；check 模式才用数组"
+        },
+        {
+            "issue": "disabled 数组传整个对象而非 rowKey 值列表，禁用匹配不生效",
+            "wrong": "disabled={[{ key: '1', label: 'A' }]}  // src 内部 disabled.indexOf(item.key) 查 string/number",
+            "right": "disabled={['1', '2']}  // 传 rowKey 值的 string[] 列表"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Selector",
+        "adapter": null
+    }
+}