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

package/es/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/es/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
+    }
+}