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

package/MultiBox/component.json

@@ -0,0 +1,216 @@
+{
+    "name": "MultiBox",
+    "category": "Data Entry",
+    "description": "键值对列表输入组件(支持增删行、补全、行级禁用)。内部用 Record<string,string>[] 作为受控值类型,默认字段名为 label/value,可通过 replaceFields 改成业务字段名",
+    "semantic": {
+        "intent": [
+            "键值录入",
+            "参数配置",
+            "可增删行的键值对编辑"
+        ],
+        "useCases": [
+            "HTTP Headers 编辑器",
+            "环境变量 / 配置项",
+            "URL Query 参数",
+            "Dictionary / Map 类型业务数据录入"
+        ],
+        "riskLevel": "normal"
+    },
+    "protocolSummary": "**核心:value 类型是 Record<string, string>[],默认字段名 label / value**。业务类型(如 `{key, value}[]` 或 `{name, val}[]`)通过 replaceFields 映射进来。**replaceFields 是 partial override**(L115 实证),只写 `{key: 'k'}` 会保留默认的 `value: 'value'` 映射。onChange 回调返回的字段名跟随 replaceFields(双向联动)",
+    "typeCastingGuide": {
+        "issue": "R23 通过率 2/5 fail 根因:业务类型如 `{key: string; value: string}[]` 想透传给 MultiBox.value(类型为 `Record<string,string>[]`),sub-agent 写 `value as Record<string,string>[]` —— **TS 5.x nominal 类型严格,即使结构兼容也拒绝直接 as cast** (TS2352 'may be a mistake because neither type sufficiently overlaps')",
+        "wrongPattern": "// ❌ 错误:TS 5.x 拒绝\nconst value = headers as Record<string, string>[];\nconst handleChange = (val: Record<string, string>[]) => setHeaders(val as HeaderPair[]);",
+        "correctPatternA": "**推荐:不要 cast,直接用 Record<string, string>[] 业务类型**\n```ts\ninterface HttpEditor {\n  headers: Record<string, string>[];  // 业务类型直接用 MultiBox 期望类型\n  onHeadersChange: (next: Record<string, string>[]) => void;\n}\n<MultiBox value={headers} onChange={onHeadersChange} replaceFields={{ key: 'key', value: 'value' }} />\n```\n业务接口字段名是 `key`/`value` 时,Record<string,string>[] 本来就能容纳,无需自定义业务类型",
+        "correctPatternB": "**如必须保留自定义业务类型 + 双向 cast:用 unknown 中转**\n```ts\ninterface HeaderPair { key: string; value: string; }\nconst handleChange = (val: Record<string, string>[]) => {\n  onHeadersChange(val as unknown as HeaderPair[]);\n};\n<MultiBox\n  value={headers as unknown as Record<string, string>[]}\n  onChange={handleChange}\n  replaceFields={{ key: 'key', value: 'value' }}\n/>\n```\n**注意 unknown 中转是逃避 TS 严格 cast 校验,业务有责任保证字段名真的兼容**",
+        "correctPatternC": "**改 replaceFields 适配业务字段名**(最干净):\n```ts\n// 业务数据是 {name, val}[],不是 {key, value}[]\nconst data: {name: string; val: string}[] = [...];\n<MultiBox\n  value={data as unknown as Record<string, string>[]}\n  onChange={(v) => setData(v as unknown as {name:string;val:string}[])}\n  replaceFields={{ key: 'name', value: 'val' }}  // ← 让 src 按 'name'/'val' 解析\n/>\n```"
+    },
+    "replaceFieldsBehavior": {
+        "default": "{ key: 'label', value: 'value' }",
+        "mergeSemantics": "**partial override(浅合并)**:src 内部 `{ ...defaultReplaceFields, ...userReplaceFields }`。只写一个字段会保留另一个默认。例如 `replaceFields={{ key: 'name' }}` 等价于 `{ key: 'name', value: 'value' }`",
+        "outputBinding": "onChange 回调返回的 val 数组中每项字段名**跟随 replaceFields 设置**(双向联动)。即:`replaceFields={{ key: 'name' }}` 时 onChange 收到的 val 是 `{ name: string; value: string }[]` 形态",
+        "warning": "改 replaceFields 后必须同步改 value/defaultValue 元素的字段名,单改一侧(只改 replaceFields 没改 value 数据)会导致 src 找不到字段,显示空内容"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error"
+    ],
+    "idealProps": {
+        "size": {
+            "type": "enum",
+            "values": [
+                "small",
+                "medium",
+                "large"
+            ],
+            "default": "large",
+            "description": "控件大小(影响 TextField 行高 + padding,具体像素由 SCSS 变量决定)"
+        },
+        "label": {
+            "type": "ReactNode",
+            "description": "标题"
+        },
+        "labelTooltip": {
+            "type": "LabelTooltipProps",
+            "description": "标题旁帮助提示"
+        },
+        "labelSign": {
+            "type": "ReactNode",
+            "description": "标题旁次级提示(短文本/标签)"
+        },
+        "placeholderKey": {
+            "type": "ReactNode",
+            "description": "键侧提示语"
+        },
+        "placeholderValue": {
+            "type": "ReactNode",
+            "description": "值侧提示语"
+        },
+        "separator": {
+            "type": "ReactNode",
+            "default": "':'",
+            "description": "键/值之间的分隔符 UI"
+        },
+        "value": {
+            "type": "Record<string, string>[]",
+            "description": "**受控值**。每项是一行键/值对象,默认按 'label'/'value' 字段名解析,可通过 replaceFields 改字段名。**业务类型如 `{key, value}[]` 与 Record<string,string>[] 的 TS cast 处理见 typeCastingGuide**"
+        },
+        "defaultValue": {
+            "type": "Record<string, string>[]",
+            "description": "**非受控初始值**;形态同 value。仅 mount + 引用变化时灌入"
+        },
+        "onChange": {
+            "type": "(val: Record<string, string>[]) => void",
+            "description": "值变化回调;val 是**完整对象数组**(不是 string[]),字段名跟随 replaceFields 设置"
+        },
+        "replaceFields": {
+            "type": "{ key?: string; value?: string }",
+            "default": "{ key: 'label', value: 'value' }",
+            "description": "**partial override**(浅合并默认值,见 replaceFieldsBehavior.mergeSemantics)。改后:1) value/defaultValue 元素字段名必须同步改 2) onChange 回调返回的字段名也跟随改(双向联动)。**单改一侧 src 找不到字段,显示空内容**"
+        },
+        "required": {
+            "type": "boolean",
+            "default": "false",
+            "description": "是否必填(影响 label 后是否显示红星 * 等视觉)"
+        },
+        "disabled": {
+            "type": "boolean | { [name: string]: boolean }[]",
+            "default": "false",
+            "description": "**两种形态**:1) `true` 整体禁用所有行所有字段;2) `{ [name: string]: boolean }[]` **行级 + 字段级禁用**——数组每项对应一行,对象 key 对应 replaceFields 的字段名(默认 'label'/'value'),value 为 true 时禁用该行该字段。例如 `[{label: true, value: false}, {label: false, value: true}]` 禁用第 1 行的 key 列 + 第 2 行的 value 列"
+        },
+        "disabledTooltip": {
+            "type": "TooltipProps",
+            "description": "禁用态 hover 提示"
+        },
+        "helperText": {
+            "type": "ReactNode | Record<string, ReactNode>[]",
+            "description": "**两种形态**:① ReactNode/string = 整体错误提示文字(typeof === 'string' 时激活 error 视觉,所有行都标红);② Record<string, ReactNode>[] = **row-level + 字段级错误**,数组每项对应一行,对象 key 对应 replaceFields 字段名,value 为错误文本"
+        },
+        "hideErrorDom": {
+            "type": "boolean | null",
+            "description": "见 HelperText 同名 prop:true=无错误不渲染,false=都渲染(布局稳定),null=永不渲染"
+        },
+        "fetchSuggestionsKey": {
+            "type": "(val: string, cb: (data: Record<string, unknown>[]) => void) => void",
+            "description": "**键侧补全数据源**(用户输入 key 时调用)。**cb 接受 Record<string, unknown>[]** 不是 string[]。每项至少要有 label 字段(显示在下拉),value 字段(选中后填回)。例:`cb([{label: 'Content-Type', value: 'Content-Type'}, ...])`。**通常与 fetchSuggestionsValue 成对使用**"
+        },
+        "fetchSuggestionsValue": {
+            "type": "(val: string, cb: (data: Record<string, unknown>[]) => void) => void",
+            "description": "**值侧补全数据源**;cb 形态同 fetchSuggestionsKey"
+        },
+        "keyOtherProps": {
+            "type": "(index: number, val: string) => TextFieldProps",
+            "description": "键侧 TextField 的额外 props(按 index 区分行,可实现某行只读 / 加 prefix 等)"
+        },
+        "valueOtherProps": {
+            "type": "(index: number, val: string) => TextFieldProps",
+            "description": "值侧 TextField 的额外 props"
+        }
+    },
+    "commonMisconceptions": {
+        "M1": {
+            "wrong": "用 `as Record<string, string>[]` 把业务类型 `HeaderPair[]` / `EnvVar[]` 强制转给 MultiBox.value",
+            "result": "**TS 5.x 报错 TS2352** 'Conversion may be a mistake because neither type sufficiently overlaps' —— TS nominal 类型严格,即使结构兼容也拒绝。R23 MultiBox-001/002/003 fail 都是这个",
+            "fix": "**3 种方案**(详见 typeCastingGuide):A) 业务直接用 Record<string,string>[] 类型(最干净);B) 用 `as unknown as` 中转(逃避 TS 严格 cast);C) 改 replaceFields 适配业务字段名 + unknown 中转"
+        },
+        "M2": {
+            "wrong": "改 replaceFields 字段名但忘记同步改 value 数据: `replaceFields={{ key: 'name' }} value={[{label: 'x', value: 'y'}]}`(value 仍按默认 label/value 字段名)",
+            "result": "src 按 replaceFieldsCom.key='name' 在 value 元素里找 `.name` 字段,**找不到 → 显示空内容**",
+            "fix": "改 replaceFields 时必须同步改 value 元素字段名:`replaceFields={{ key: 'name' }} value={[{name: 'x', value: 'y'}]}`(注意 value 字段也要保留或同时改 replaceFields.value)"
+        },
+        "M3": {
+            "wrong": "假设 replaceFields 是完全替换语义: `replaceFields={{ key: 'k' }}` 期望 value 字段名也是 'k'",
+            "result": "**replaceFields 是 partial override**(浅合并),只写 key 会保留默认 value:'value'。所以 `value={[{k: 'x', val: 'y'}]}` 不工作,需写成 `[{k: 'x', value: 'y'}]`",
+            "fix": "1) 单字段改:确保 value 用对应字段名 + 默认 value:'value';2) 双字段都改:`replaceFields={{ key: 'k', value: 'v' }}` 双向同步"
+        },
+        "M4": {
+            "wrong": "假设 disabled 只是 boolean: `disabled={ rowIndex === 0 }`",
+            "result": "整体禁用整个 MultiBox,而非'第 1 行禁用'。**disabled 支持 `{ [name]: boolean }[]` 形态做行级 + 字段级禁用**",
+            "fix": "用对象数组形态:`disabled={[{label: true, value: false}, {label: false, value: false}]}`(第 1 行 key 列禁用,其他全开)"
+        },
+        "M5": {
+            "wrong": "用 helperText: string 期望某行某列单独红框",
+            "result": "**string 形态的 helperText 激活整体错误视觉**(所有行标红),不是 row-level",
+            "fix": "row-level + 字段级错误:用 `Record<string, ReactNode>[]` 形态: `helperText={[{label: 'key 重复'}, {}, {value: '格式错误'}]}`(第 1 行 key 列报错 + 第 3 行 value 列报错)"
+        }
+    },
+    "do": [
+        "**优先用 Record<string, string>[] 作为业务类型**,避免 TS cast(M1 patternA)",
+        "**必须自定义业务类型**:用 `as unknown as` 中转(M1 patternB)",
+        "**业务字段名不叫 label/value**:同时改 replaceFields **和** value/defaultValue 数据字段名(M2/M3)",
+        "行级禁用:用 `disabled={[{label/value: boolean}]}` 对象数组形态(M4)",
+        "行级错误:用 `helperText={[{label/value: errorMsg}]}` 对象数组形态(M5)",
+        "自动补全:fetchSuggestionsKey 和 fetchSuggestionsValue 通常成对使用,cb 接受 `{label, value}` 对象数组(不是 string[])"
+    ],
+    "dont": [
+        "**不要**直接 `as Record<string, string>[]` 强制 cast 业务类型——TS5 严格拒绝(M1)",
+        "**不要**单改 replaceFields 而不改 value 字段名——src 找不到字段(M2)",
+        "**不要**假设 replaceFields 完全替换——是 partial override(M3)",
+        "**不要**假设 disabled 只能 boolean——对象数组形态做行级禁用(M4)",
+        "**不要**用 string helperText 期望 row-level 错误——整体激活(M5)",
+        "键或值过长时不做截断/省略——TextField 自身样式",
+        "复杂嵌套对象录入——MultiBox 仅 2 层(key + value),换 FieldForm + dynamicFields"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: Record<string, string>[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "onChange={(val) => setHeaders(val)} — val 是完整对象数组，字段名跟随 replaceFields 设置（默认 label/value）",
+                "增/删行也触发 onChange，val 是操作后完整的新数组（不是 diff）",
+                "行内 TextField 值变化实时触发 onChange（不是 onBlur）"
+            ],
+            "commonMistakes": [
+                "期望 onChange 返回 string[]——实际返回 Record<string, string>[]（对象数组），需取对应字段：val.map(v => v.value)",
+                "用 as Record<string, string>[] 把业务类型传给 onChange setter——TS 5.x 拒绝结构兼容 cast，需用 as unknown as 中转",
+                "只处理 onChange 不处理新增/删除——增删操作也走同一 onChange，val 是全量数组，不是操作了哪一行"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "业务类型 `{key: string; value: string}[]` 与 `Record<string, string>[]` 在 TS 5.x 不能直接 as cast",
+            "wrong": "const headers: {key: string; value: string}[] = []; <MultiBox value={headers as Record<string, string>[]} /> // TS2352 拒绝",
+            "right": "<MultiBox value={headers as unknown as Record<string, string>[]} replaceFields={{ key: 'key', value: 'value' }} /> // unknown 中转"
+        },
+        {
+            "issue": "改 replaceFields.key 但不改 value 数据字段名，src 找不到字段显示空",
+            "wrong": "replaceFields={{ key: 'name' }} value={[{label: 'x', value: 'y'}]} // src 按 'name' 读，label 字段被忽略",
+            "right": "replaceFields={{ key: 'name' }} value={[{name: 'x', value: 'y'}]} // replaceFields 和数据字段名必须同步"
+        },
+        {
+            "issue": "disabled 只传 boolean 期望行级禁用——boolean true 是整体禁用，行级需用对象数组",
+            "wrong": "disabled={rowIndex === 0} // 期望第一行禁用，实际 disabled=true 时整体禁用所有行",
+            "right": "disabled={[{label: true, value: false}, {label: false, value: false}]} // 对象数组：第一行 key 列禁用"
+        }
+    ],
+    "mapping": {
+        "realComponent": "MultiBox",
+        "adapter": null
+    }
+}

package/Notification/component.json

@@ -0,0 +1,184 @@
+{
+    "name": "Notification",
+    "category": "Feedback",
+    "description": "全局通知提醒框，通过命令式 API（Notification.open / .success / .info / .warning / .error）触发，支持角落定位、标题 + 内容 + 操作按钮、可关闭回调、key 管理",
+    "semantic": {
+        "intent": [
+            "系统通知",
+            "重要提醒",
+            "复杂反馈"
+        ],
+        "useCases": [
+            "系统升级通知",
+            "后台任务完成提醒",
+            "带操作按钮的系统消息"
+        ],
+        "riskLevel": "normal"
+    },
+    "protocolSummary": "**命令式 API，不是 React 组件**。调用方式:\n```\nNotification.success({ message: '标题', description: '内容', duration: 3 })\nNotification.info({ message: '提示', description: '详情' })\nNotification.warning({ message: '警告', description: '说明' })\nNotification.error({ message: '错误', description: '信息' })\nNotification.open({ message: '标题', description: '内容', type: 'success' })  // open 是 success/info/warning/error 的底层\nNotification.close('my-key')  // 关闭指定 key 的通知\nNotification.destroy()  // 关闭所有通知\nNotification.config({ placement, top, maxCount, duration })  // 全局配置\n```\n**duration 单位是秒**（与 Message.duration 毫秒不同！）。默认 5 秒自动关闭；传 null 不自动关闭。",
+    "variants": {
+        "success": { "meaning": "成功（绿色 ✓ 图标）" },
+        "info": { "meaning": "普通信息（蓝色 i 图标）" },
+        "warning": { "meaning": "警告（黄色 ! 图标）" },
+        "error": { "meaning": "错误（红色 × 图标）" }
+    },
+    "states": [
+        "opening",
+        "closing"
+    ],
+    "idealProps": {
+        "message": {
+            "type": "ReactNode",
+            "description": "通知标题（必填），通知卡片上方的粗体文字"
+        },
+        "description": {
+            "type": "ReactNode",
+            "description": "通知正文内容；与 message 同时出现时，message 作为标题，description 作为正文"
+        },
+        "duration": {
+            "type": "number | null",
+            "default": 5,
+            "description": "**自动关闭延时，单位秒**（注意：与 Message 组件的毫秒单位不同！）；传 null 不自动关闭（需用户点击关闭按钮或调用 Notification.close(key)）"
+        },
+        "placement": {
+            "type": "enum",
+            "values": ["topLeft", "topRight", "bottomLeft", "bottomRight"],
+            "default": "topRight",
+            "description": "弹出位置，4 个角落，topRight 最常用"
+        },
+        "key": {
+            "type": "string",
+            "description": "通知唯一标志；传了 key 才能用 Notification.close(key) 程序性关闭；同一 key 再次 open 会更新已有通知"
+        },
+        "onClose": {
+            "type": "() => void",
+            "description": "关闭时触发（自动关闭 + 用户手动关闭都触发）"
+        },
+        "onClick": {
+            "type": "() => void",
+            "description": "点击通知内容区域（非关闭按钮）时触发"
+        },
+        "btn": {
+            "type": "ReactNode",
+            "description": "通知卡片底部自定义操作区域（如 '立即更新' 按钮）"
+        },
+        "icon": {
+            "type": "ReactNode",
+            "description": "自定义图标，覆盖 type 默认图标"
+        },
+        "top": {
+            "type": "number",
+            "default": 20,
+            "description": "topLeft/topRight 时距顶部距离（px）"
+        },
+        "bottom": {
+            "type": "number",
+            "default": 20,
+            "description": "bottomLeft/bottomRight 时距底部距离（px）"
+        },
+        "getContainer": {
+            "type": "() => HTMLElement",
+            "description": "渲染容器，默认 document.body"
+        }
+    },
+    "commonPatterns": {
+        "basic": "Notification.success({ message: '操作成功', description: '数据已保存', duration: 3 })",
+        "persistent": "Notification.warning({ message: '需要确认', description: '请及时处理', duration: null, key: 'warn-1' });\n// 处理完成后：\nNotification.close('warn-1');",
+        "withButton": "Notification.info({\n    message: '发现新版本',\n    description: 'v2.0.0 已发布',\n    duration: null,\n    key: 'update',\n    btn: <Button onClick={() => { window.open(releaseUrl); Notification.close('update'); }}>立即更新</Button>\n});",
+        "globalConfig": "Notification.config({ placement: 'topRight', top: 60, maxCount: 5, duration: 3 });"
+    },
+    "commandApi": {
+        "Notification.open": {
+            "signature": "(args: ArgsProps) => void",
+            "description": "打开通知，所有 ideaProps 字段均为 ArgsProps 的字段"
+        },
+        "Notification.success": {
+            "signature": "(args: ArgsProps) => void",
+            "description": "等价于 Notification.open({...args, type: 'success'})"
+        },
+        "Notification.info": {
+            "signature": "(args: ArgsProps) => void"
+        },
+        "Notification.warning": {
+            "signature": "(args: ArgsProps) => void",
+            "description": "Notification.warn 是 Notification.warning 的别名"
+        },
+        "Notification.error": {
+            "signature": "(args: ArgsProps) => void"
+        },
+        "Notification.close": {
+            "signature": "(key: string) => void",
+            "description": "关闭指定 key 的通知，遍历所有 placement 实例"
+        },
+        "Notification.destroy": {
+            "signature": "() => void",
+            "description": "销毁所有通知实例（包括已显示的和正在动画的）"
+        },
+        "Notification.config": {
+            "signature": "(options: ConfigProps) => void",
+            "description": "全局配置，应用入口调用一次"
+        }
+    },
+    "do": [
+        "用于比 Message 更重要的、需要用户关注的全局通知（如系统升级、任务完成）",
+        "**duration 单位是秒**（默认 5），不是毫秒——与 Message 组件不同",
+        "需要程序性关闭时传 key 字段并用 Notification.close(key)",
+        "App 入口调用 Notification.config 设置全局 placement / maxCount / duration"
+    ],
+    "dont": [
+        "频繁使用 Notification 打断用户操作——轻提示用 Message，重要操作确认用 FunctionModal",
+        "堆叠过多——配合 maxCount 限制同时显示数量",
+        "把 duration 写成毫秒——duration 是秒，写 3000 会导致通知 3000 秒后才关闭"
+    ],
+    "events": {
+        "onClose": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "Notification.info({ message: '提示', onClose: () => console.log('已关闭') }) — 自动关闭和手动关闭都触发",
+                "持久通知 + 关闭回调：Notification.warning({ message: '警告', duration: null, key: 'w1', onClose: () => markAsRead() })",
+                "配合 key 程序关闭：Notification.close('w1') 也会触发 onClose"
+            ],
+            "commonMistakes": [
+                "期望 onClose 签名是 (e) => void——实际无参 () => void",
+                "传了 onClose 但没有显式关闭路径——duration=null 时通知不自动关闭，onClose 永不触发（除非用户点 × 或程序调用 close）",
+                "在 onClose 里再次调 Notification.open 期望实现替换效果——会新开一条通知，建议用 key 复用已有实例"
+            ]
+        },
+        "onClick": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "Notification.info({ message: '新消息', onClick: () => router.push('/messages') }) — 点击跳转",
+                "onClick 不关闭通知——需在 onClick 里手动调 Notification.close(key) 或让 duration 到期",
+                "onClick 和 btn 的 onClick 独立——通知区域点击 + 底部按钮点击是两个独立事件"
+            ],
+            "commonMistakes": [
+                "期望点击通知后自动关闭——onClick 不触发关闭，需在 onClick 里手动 Notification.close(args.key)",
+                "在 btn 里写关闭逻辑而不传 key——没有 key 就无法调 Notification.close，需预先生成 key",
+                "期望 onClick 阻止通知关闭——点击关闭按钮（×）触发的是关闭逻辑，不能被 onClick 拦截"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "duration 单位是秒，不是毫秒——与 Message 不一致是常见陷阱",
+            "wrong": "Notification.success({ message: '成功', duration: 3000 }) // 3000 秒后才关闭！不是 3 秒",
+            "right": "Notification.success({ message: '成功', duration: 3 }) // 3 秒后自动关闭"
+        },
+        {
+            "issue": "Notification 是命令式 API，default export 是 api 对象，不是 React 组件，不能写 JSX",
+            "wrong": "import Notification from '@para-ui/core/Notification'; return <Notification message='提示' />; // JSX 类型错误",
+            "right": "import Notification from '@para-ui/core/Notification'; Notification.info({ message: '提示' }); // 命令式调用"
+        },
+        {
+            "issue": "message 类型是 ReactNode，但 ArgsProps 中 message 是必填字段，不传会导致 TS 报错",
+            "wrong": "Notification.open({ description: '内容' }) // TS2345: Property 'message' is missing",
+            "right": "Notification.open({ message: '标题', description: '内容' }) // message 必填"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Notification",
+        "adapter": null
+    }
+}

package/OperateBtn/component.json

@@ -0,0 +1,134 @@
+{
+    "name": "OperateBtn",
+    "category": "General",
+    "description": "表格列操作按钮组，将多个行操作收纳为图标按钮 + 更多浮层，常配合 Table 使用",
+    "semantic": {
+        "intent": [
+            "行操作",
+            "批量操作",
+            "操作收纳"
+        ],
+        "useCases": [
+            "表格操作列",
+            "卡片操作区",
+            "工具栏"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "loading"
+    ],
+    "idealProps": {
+        "list": {
+            "type": "OperateBtnListProps[]",
+            "itemSchema": {
+                "key": { "type": "string", "description": "唯一标识（与组件 key prop 配合，用于 loadingMapping 索引）" },
+                "label": { "type": "ReactNode", "description": "按钮显示文案" },
+                "icon": { "type": "ReactNode", "description": "按钮图标（外显按钮展示区域，显示 icon 而非 label）" },
+                "disabled": { "type": "boolean", "description": "是否禁用" },
+                "danger": { "type": "boolean", "description": "是否为危险按钮（红色）" },
+                "toolTipTitle": { "type": "ReactNode", "description": "hover tooltip 文案；外显按钮默认取 toolTipTitle ?? label 作 tooltip" },
+                "popConfirmProps": { "type": "PopConfirmProps", "description": "点击弹出气泡确认框的配置" },
+                "onClick": { "type": "(item: OperateBtnListProps, e: any) => void | Promise<boolean|any>", "description": "单项点击事件（优先级高于组件级 onClick）；Promise resolve(false) 关闭 loading" }
+            },
+            "description": "按钮列表配置（每项含 label/icon/key/disabled/danger/toolTipTitle/popConfirmProps/onClick）"
+        },
+        "showNum": {
+            "type": "number",
+            "default": 3,
+            "description": "前 N 个按钮外显，超出折叠到更多浮层；⚠️ 仅 list.length > showNum + 1 才出现更多按钮（差值严格大于 1），若 list.length === showNum+1 最后一个也外显不进更多"
+        },
+        "key": {
+            "type": "string",
+            "default": "key",
+            "description": "指定 list 项中作为 loadingMapping 索引的字段名（不是 React key，是 list 项对象里用于 loadingMapping 映射的字段路径名）"
+        },
+        "size": {
+            "type": "enum",
+            "values": ["small", "medium", "large"],
+            "default": "small",
+            "description": "按钮大小；表格行内推荐 small"
+        },
+        "placement": {
+            "type": "Placement",
+            "default": "bottom-end",
+            "description": "外显按钮 Tooltip 及更多浮层的定位方向（src/OperateBtn/index.tsx:88 interface 实证，默认 bottom-end）"
+        },
+        "clickCloseMore": {
+            "type": "boolean",
+            "default": true,
+            "description": "点击 list 项后是否自动关闭更多浮层"
+        },
+        "onClick": {
+            "type": "(item: OperateBtnListProps, e: any) => void | Promise<boolean | any>",
+            "description": "组件级点击事件；list 项自带 item.onClick 时对本项失效（item.onClick 优先级更高）；非受控 loading 下 Promise resolve(false) 表示失败、保持按钮 loading；resolve(true/undefined) 关闭 loading"
+        },
+        "loadingMapping": {
+            "type": "{[name: string]: boolean}",
+            "description": "受控 loading 映射；键 = item[key] 字段值；传入后 onClick 返回值不再控制 loading，由外部控制"
+        },
+        "popoverClassName": {
+            "type": "string",
+            "description": "更多浮层的自定义 className（src/OperateBtn/index.tsx:73 interface 实证）"
+        }
+    },
+    "do": [
+        "表格行内操作首选 OperateBtn，将编辑/删除/查看等图标按钮组合为一组，超出 showNum 自动收纳到更多",
+        "危险操作（删除等）配合 list[i].popConfirmProps 弹二次确认，避免误操作",
+        "提供 loading 状态反馈：短请求用内置非受控 loading（onClick 返回 Promise），长请求或多处联动用 loadingMapping 受控",
+        "list 每项必须有 icon 或 toolTipTitle 其中之一，外显按钮以图标展示，tooltip 才能给用户提示操作语义"
+    ],
+    "dont": [
+        "不要在 loadingMapping 键中使用数组下标——键应匹配 item[key] 字段（默认 item.key），而非 list 索引",
+        "危险操作不加 popConfirmProps 确认直接删除",
+        "操作按钮超过 5 个不分组——超出部分应通过 showNum 折叠，或拆分为多个操作区"
+    ],
+    "events": {
+        "onClick": {
+            "signature": "(item: OperateBtnListProps, e: any) => void | Promise<boolean | any>",
+            "asyncSupported": true,
+            "examples": [
+                "基本同步点击：onClick={(item, e) => { handleAction(item); }}",
+                "异步操作自动 loading：onClick={async (item, e) => { await deleteRow(item.id); return true; }} // resolve(true) 关闭 loading",
+                "配合 key prop 做受控 loading：loadingMapping={{ [row.id]: isDeleting }} // 外部控制 loading 状态"
+            ],
+            "commonMistakes": [
+                "item.onClick 与组件级 onClick 混用——item.onClick 存在时组件级 onClick 对该项失效，二选一即可",
+                "期望 Promise resolve(false) 关闭 loading——resolve(false) 是失败语义，loading 保持；resolve(true/undefined) 才关闭",
+                "同时传 loadingMapping 又在 onClick 里 return Promise——传 loadingMapping 后 Promise 返回值不影响 loading，由外部 state 控制"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "OperateBtnListProps 的 key 字段与 React 的 key 属性同名但语义不同",
+            "wrong": "// 期望 React key：\nlist={[{ key: 'edit', label: '编辑', icon: <Edit /> }]}  // OperateBtn 的 key prop 用于 loadingMapping 索引，不是 React reconcile key",
+            "right": "// loadingMapping 键要和 list 项里的 key 字段值对应：\nlist={[{ key: 'edit', label: '编辑', icon: <Edit /> }]}\nloadingMapping={{ edit: isLoading }}"
+        },
+        {
+            "issue": "OperateBtnProps.key 是字符串（字段路径名），不是数组下标",
+            "wrong": "<OperateBtn key='id' list={list} loadingMapping={{ 0: true }} />  // 用数组下标做 mapping 键",
+            "right": "<OperateBtn key='id' list={list} loadingMapping={{ [list[0].id]: true }} />  // 键应是 item[keyProp] 的值"
+        },
+        {
+            "issue": "list 每项的 onClick 签名是 (item, e)，不是单参数 (e)",
+            "wrong": "list={[{ icon: <Edit />, onClick: (e) => e.stopPropagation() }]}  // 签名不匹配",
+            "right": "list={[{ icon: <Edit />, onClick: (item, e) => { e.stopPropagation(); handleEdit(item); } }]}"
+        },
+        {
+            "issue": "@para-ui/icons 中不存在 View 和 Share 图标，使用会导致 TS2307 模块找不到",
+            "wrong": "import View from '@para-ui/icons/View';  // TS2307: 找不到模块\nimport Share from '@para-ui/icons/Share'; // TS2307: 找不到模块",
+            "right": "import PreviewOpen from '@para-ui/icons/PreviewOpen';  // 查看/预览\nimport More from '@para-ui/icons/More';  // 更多操作\n// 可用图标：Edit, Delete, Copy, More, PreviewOpen, PreviewClose 等"
+        }
+    ],
+    "mapping": {
+        "realComponent": "OperateBtn",
+        "adapter": null
+    }
+}