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

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

package/SelectorPicker/component.json

@@ -0,0 +1,179 @@
+{
+    "name": "SelectorPicker",
+    "category": "Data Entry",
+    "description": "选择器弹出框，Selector 的弹出框封装",
+    "semantic": {
+        "intent": [
+            "弹出选择",
+            "下拉选择器"
+        ],
+        "useCases": [
+            "表单选择",
+            "快速选择",
+            "弹出式选择"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error"
+    ],
+    "idealProps": {
+        "value": {
+            "type": "Record<string, any>[] | Record<string, any>",
+            "description": "受控选中值;multiple=true 时为对象数组 Record<string,any>[],false 时为单对象 Record<string,any>;清空时 onChange 入参为 null。外部以 string[] key 列表受控时,挂入前用 useMemo data.filter 反查为对象数组(见 api.ts 顶部 C 协议)"
+        },
+        "defaultValue": {
+            "type": "Record<string, any>[] | Record<string, any>",
+            "description": "非受控默认值;类型规则同 value"
+        },
+        "onChange": {
+            "type": "(val: Record<string,any>[] | Record<string,any> | null, node: Record<string,any>, rowData: Record<string,any>) => void",
+            "description": "值变化回调;multiple 时 val 为数组,否则为单对象;清空时 val=null(回写外部 string[] 时需 ?? [] 兜底);node=节点处理后数据、rowData=原始数据"
+        },
+        "multiple": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否多选;true 时 value/defaultValue 必须为数组,onChange 入参 val 也为数组"
+        },
+        "allowClear": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否支持清除已选值;true 时悬停显示清除按钮,触发顺序:onClear() → onChange(null)"
+        },
+        "selectorProps": {
+            "type": "Omit<SelectorProps, 'layout' | 'disabled' | 'value' | 'defaultValue' | 'onChange' | 'selectMode'>",
+            "description": "透传给底层 Selector 的属性(data/url/fieldConfig/rowKey/breadcrumbsHead/searchOption/backDataFieldConfig 等);Omit 列出的字段已被 SelectorPicker 接管不可透传;常用子字段速查见 api.ts 顶部 E 协议"
+        },
+        "tagRender": {
+            "type": "(item: Record<string, any>) => React.ReactNode",
+            "description": "多选 tag 自定义渲染;入参为已选 list 项对象"
+        },
+        "size": {
+            "type": "'small' | 'medium' | 'large'",
+            "values": ["small", "medium", "large"],
+            "default": "large",
+            "description": "输入框尺寸"
+        },
+        "placeholder": {
+            "type": "string",
+            "default": "请选择",
+            "description": "未选中时占位文本"
+        },
+        "getPopupContainer": {
+            "type": "(triggerNode: HTMLElement) => HTMLElement",
+            "description": "浮层挂载容器;默认 body,Modal 内必传 trigger.parentNode 避免点击穿透"
+        },
+        "label": {
+            "type": "React.ReactNode",
+            "description": "标签文案;支持节点(可嵌图标 / Tooltip 触发器)"
+        },
+        "required": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否必填;true 时 label 前渲染红色 *"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "禁用整个选择器(无法点击展开浮层、无法清除)"
+        },
+        "error": {
+            "type": "boolean",
+            "default": false,
+            "description": "错误状态;输入框边框变红,搭配 helperText 显示错误信息"
+        },
+        "helperText": {
+            "type": "React.ReactNode",
+            "description": "辅助文本;error=true 时显示为错误信息,否则显示为常规说明"
+        },
+        "overLine": {
+            "type": "boolean",
+            "description": "多选时已选项是否换行;true 换行,false 单行折叠显示 +N"
+        }
+    },
+    "do": [
+        "配合 Selector 使用(SelectorPicker 是 Selector 的弹出框封装,所有候选数据走 selectorProps.data 透传给底层 Selector)",
+        "外部以 string[](key 列表)受控时,用 useMemo data.find 反查映射为 Record<string,any>[] 后挂入 value(详见 api.ts §C 反向映射模式)",
+        "二次封装业务组件时,JSX 内 **受控 prop 写在 {...pickerProps} spread 之后**,后写覆盖保护受控状态(详见 api.ts §D)",
+        "提供清空功能(allowClear=true + onClear 监听,onChange 入参 val=null 时回写外部 string[] 用 `?? []` 兜底)"
+    ],
+    "dont": [
+        "传 `visible` / `open` / `show` 显隐控制 prop(本组件不存在;父层条件渲染 `{showPicker && <SelectorPicker ... />}` 控制 mount;见 api.ts §A)",
+        "selectorProps 透传 `layout` / `disabled` / `value` / `defaultValue` / `onChange` / `selectMode`(已被 SelectorPicker 接管,类型已 Omit,透传无效)",
+        "selectorProps 写错字段名:`list`(应为 `data`)/ `keys`(应为 `rowKey`)— 内部不消费会静默失败",
+        "二次封装时 `pickerProps?: any` **作为推荐签名**(❌ 不能阻止外部覆盖受控;✅ 推荐 `Omit<SelectorPickerProps, 'value'|'defaultValue'|'onChange'|'multiple'|'selectorProps'>`);**但若需求模板硬性要求 any 签名,见 interpretivePriority 兼容路径**",
+        "弹窗内容过于复杂",
+        "忽略 placeholder"
+    ],
+    "interpretivePriority": {
+        "principle": "**需求模板接口 `pickerProps: any` 与本组件 §D 协议推荐 Omit<...> 冲突时,严格按需求接口签名(api.ts §D-bis 兼容路径)**",
+        "reason": "需求接口(requirements/*.json)是观察者制定的固定 spec · 优化 AI 无权改;§D 协议 Omit<...> 是组件库的安全推荐 · sub-agent 不应擅自改需求接口签名;但 anti-pattern any 接口在运行时仍需保护受控状态 → 通过 JSX spread 顺序(受控 prop 写在 spread 之后)实现",
+        "resolution": "1. 接口签名照搬需求 `pickerProps: any`(不改) ;2. JSX 写法严格遵 §D 协议(`{...pickerProps} value={...} onChange={...} multiple` — 受控 prop 后写覆盖) ;3. 类型安全靠运行时 spread 顺序,不靠类型层面阻断;详见 api.ts §D-bis 完整代码示例",
+        "dataSourceDecisionTree": "data 来源根据需求接口字段决定:(1)接口含 data prop → 直接 selectorProps={{data}} 透传;(2)接口不含 data 字段,只有 pickerProps → 候选数据从 pickerProps.selectorProps.data 透传(`selectorProps={{ ...(pickerProps?.selectorProps ?? {}) }}`),封装层不内置;(3)需求语义为内置固定数据(如部门选择) → 封装层 const data = [...] 然后 selectorProps={{data}};详见 api.ts §D-ter",
+        "antiPatterns": [
+            "❌ 看到需求接口 `pickerProps: any` 后,擅自改为 Omit<...> 违背需求 spec",
+            "❌ 接口写 any,JSX 把 spread 放在受控 prop 之后(`<SelectorPicker value={...} onChange={...} {...pickerProps} />` — 外部 pickerProps 覆盖受控状态)",
+            "❌ 二次封装时,封装层 hardcode 候选数据而不查需求接口字段(需求接口若含 data prop 应透传,不应硬编码)"
+        ],
+        "correctPatterns": [
+            "✅ 接口签名 `pickerProps: any`(照搬需求) + JSX `<SelectorPicker {...pickerProps} value={...} onChange={...} multiple selectorProps={{ data }} />`(受控后写覆盖)",
+            "✅ 看需求接口:若有 data prop → `selectorProps={{ data }}`;若无 data 字段但有 pickerProps → `selectorProps={{ ...(pickerProps?.selectorProps ?? {}) }}`(透传外部数据);若需求要求'内置部门列表'业务语义 → 封装层 const data = [...] hardcode"
+        ]
+    },
+    "events": {
+        "onChange": {
+            "signature": "(val: Record<string,any>[] | Record<string,any> | null, node: Record<string,any>, rowData: Record<string,any>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "单选时 val 是单对象，多选时 val 是对象数组，清空时 val 是 null",
+                "受控外部 string[] 场景：onChange={(val) => setIds(val ? (Array.isArray(val) ? val : [val]).map(it => it[rowKey]) : [])}",
+                "清空时兜底：setIds((val ?? []) instanceof Array ? val.map(it => it.key) : [])"
+            ],
+            "commonMistakes": [
+                "清空时期望 val 是 [] 而非 null——清空时 val=null，需 ?? [] 兜底",
+                "multiple=false 期望 val 是数组——单选 val 是单对象，需按模式分支处理",
+                "忽略第二三参 node/rowData——node 是内部处理后的数据，rowData 是原始数据，两者都是对象 Map（key=rowKey）"
+            ]
+        },
+        "onClear": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "用户点击清除按钮时先触发 onClear，再触发 onChange(null, {}, {})",
+                "受控场景需同时监听 onClear 和 onChange 才能完整捕获清空"
+            ],
+            "commonMistakes": [
+                "只监听 onClear 而不监听 onChange——受控 value 不会自动清空，需在 onChange 里同步 state",
+                "allowClear=false 时期望 onClear 触发——allowClear=false 不显示清除按钮，onClear 不会触发"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "selectorProps 透传了已被 SelectorPicker 接管的字段（如 layout/disabled/value/onChange/selectMode），TypeScript 报 Omit 类型错误",
+            "wrong": "selectorProps={{ layout: 'lr', value: [...], onChange: handler }}  // 这些字段已 Omit",
+            "right": "selectorProps={{ data: [...], rowKey: 'id', fieldConfig: { mainTitle: 'name' } }}  // 只传未 Omit 的字段"
+        },
+        {
+            "issue": "multiple=true 时 value 传单对象而非数组，受控不生效",
+            "wrong": "multiple={true} value={{ key: '1' }}  // multiple 时 value 必须是 Record<string,any>[]",
+            "right": "multiple={true} value={[{ key: '1' }]}  // 数组包裹"
+        },
+        {
+            "issue": "selectorProps 传 data 字段名拼错（如 list/items），候选数据静默失败",
+            "wrong": "selectorProps={{ list: myData }}  // Selector 内部读 data，不读 list",
+            "right": "selectorProps={{ data: myData }}  // Selector prop 名是 data"
+        }
+    ],
+    "mapping": {
+        "realComponent": "SelectorPicker",
+        "adapter": null
+    }
+}