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

package/Modal/component.json

@@ -0,0 +1,277 @@
+{
+    "name": "Modal",
+    "category": "Feedback",
+    "description": "模态对话框，用于需用户处理事务，又不希望跳转页面的场景",
+    "semantic": {
+        "intent": [
+            "通知",
+            "确认",
+            "复杂输入",
+            "详情查看"
+        ],
+        "useCases": [
+            "删除确认",
+            "表单填写",
+            "信息详情",
+            "重要预警"
+        ],
+        "riskLevel": "high"
+    },
+    "variants": {
+        "confirm": {
+            "meaning": "确认框，通常只包含文本和确定/取消按钮"
+        },
+        "info": {
+            "meaning": "信息框，展示详情或通知"
+        }
+    },
+    "states": [
+        "open",
+        "loading"
+    ],
+    "idealProps": {
+        "open": {
+            "type": "boolean",
+            "default": false,
+            "description": "模态框是否可见。**`visible` 是同义旧别名**（src:33-35 二者都存在），新代码推荐用 open。**Modal 完全受控**(DEFECT-008):src/Modal/index.tsx:160-167 handleCancel/handleOk **不修改 open 内部状态**,只调 props.onCancel/onOk;父组件必须自行 setOpen(false) 才会关闭。不存在\"非受控自动关闭\"模式。未传 `open` 时可用 `defaultOpen` 启用非受控模式（v5.x.next 议题 #2 新增）"
+        },
+        "defaultOpen": {
+            "type": "boolean",
+            "description": "**(v5.x.next 议题 #2 引入)** 非受控模式初始 open 值。未传 `open` 时启用非受控 — Modal 内部维护 open state，关闭路径自动 setOpen(false)，业务方不需要手动管理 open state（公告类/一次性 Modal 推荐）。与 React `<input defaultValue>` 惯例一致。同时传 open + defaultOpen → open 优先，dev warn 提示"
+        },
+        "visible": {
+            "type": "boolean",
+            "default": false,
+            "description": "**@deprecated v5.x.next 改用 `open`（命名对齐业界 antd5/Chakra/Radix/MUI）；v6.0 移除（BREAKING-CHANGES §B-Modal-props-rework 子条 #3-A）。** `open` 的旧别名；与 open 二选一即可，新代码推荐用 open"
+        },
+        "title": {
+            "type": "ReactNode",
+            "description": "标题"
+        },
+        "onOk": {
+            "type": "function",
+            "signature": "() => void",
+            "description": "**@deprecated v5.x.next 改用 `onSubmit`（语义更清晰:submit 比 ok 更准确表达\"确认提交\"行为，对齐表单语义）；v6.0 移除（BREAKING-CHANGES §B-Modal-props-rework）。** 点击确定回调（旧名）"
+        },
+        "onSubmit": {
+            "type": "function",
+            "signature": "(e?: React.MouseEvent) => void | Promise<void>",
+            "description": "**(v5.x.next 议题 #M1 引入)** 点击确定回调（推荐新 API,语义清晰）。与 `onOk` 同义但 submit 比 ok 更准确表达\"确认提交\"行为。同时传 `onOk + onSubmit` → `onSubmit` 优先调用,`onOk` 跳过(避免业务函数重复触发);仅传 `onOk` → 旧行为不变(onOk 仍触发)。dev 环境若检测到只传 `onOk` 会 console.warn 1 次提示迁移"
+        },
+        "onCancel": {
+            "type": "function",
+            "signature": "() => boolean | void",
+            "description": "点击取消、ESC、遮罩、右上角叉的回调；返回 false 阻止关闭"
+        },
+        "onClose": {
+            "type": "function",
+            "signature": "(reason: 'cancel' | 'ok' | 'esc' | 'mask' | 'x') => void",
+            "description": "@deprecated v5.x.next 改用 onDismiss + onOk + onCancel 三回调；v6.0 移除。**(R6 §B3 阶段 1 引入,最低支持版本 5.x.next)** 任意路径关闭统一回调,reason 字面联合区分关闭来源。**与 onCancel/onOk 共存为叠加触发**(src 实证):取消按钮 → onCancel + onClose('cancel');确定按钮 → onOk + onClose('ok');ESC/蒙层/X → onCancel + onClose('esc'|'mask'|'x')。**推荐写法** — 业务方在 onClose 里统一 setOpen(false) + reason 分支(埋点 / 重置 state),不再写 `onCancel={fn} onOk={fn}` 双绑兜底;若旧代码 onOk + onClose 共存,onOk 应只处理 'ok' 路径(submit),onClose 处理其他 4 种,避免业务函数重复触发(R3 4/9 + R5 5/9 sub-agent 持续踩坑)。**X 按钮在 showCancel=false 时仍显示并触发 reason='x'**(X 由 hideHeader 控制,不受 showCancel 影响);**Modal 完全受控** — onClose 未传或未在 onClose 内 setOpen(false),Modal 不会自动关闭。阶段 3 v6 移除单独 onCancel/onOk(BREAKING)。详见 BREAKING-CHANGES §B3 + discussions/Modal-unified-onClose.md"
+        },
+        "onDismiss": {
+            "type": "function",
+            "signature": "(reason: ModalDismissReason) => void",
+            "description": "**(v5.x.next γ 方案 议题 #1 引入)** 非按钮关闭路径（X/ESC/蒙层）的专用回调。仅传 onDismiss（不传 onClose）时走新单触发行为：X 按钮仅调 `onDismiss('x')`，ESC 仅调 `onDismiss('esc')`，蒙层仅调 `onDismiss('mask')`。**onOk/onCancel/onDismiss 三回调职责互斥**（对比旧 onClose 5 路径统一触发会导致双触发）。推荐迁移路径：删 onClose，改用 onDismiss 处理非按钮路径。详见 BREAKING-CHANGES §B-Modal-props-rework"
+        },
+        "showCancel": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示取消按钮。**仅控制取消按钮显隐**,不影响右上角 X 按钮(X 由 hideHeader 控制;showCancel=false 时 X 仍显示并仍可点击触发关闭走 onClose reason='x' / onCancel 路径)。showCancel=false 时 onCancel 可省略(走 onClose 统一处理)"
+        },
+        "showActions": {
+            "type": "boolean",
+            "default": true,
+            "description": "是否显示底部 actions 按钮区(确定 + 取消按钮统一区域)。**典型场景**:登录/复杂表单内嵌时设为 false 隐藏默认底部,业务自行在 children 内放置提交按钮"
+        },
+        "confirmLoading": {
+            "type": "boolean",
+            "default": false,
+            "description": "确定按钮 loading 状态（顶层快捷方式，等价于 okButtonProps={{ loading }}）。**loading 期间确定按钮自动 disabled 不响应点击**（src/Modal/index.tsx:258 透传 Button.loading,Button 自身已 `disabled={disabled \\|\\| hasLoading}`,见 BREAKING-CHANGES §A2）——业务无需再叠 okButtonProps.disabled。"
+        },
+        "destroyOnClose": {
+            "type": "boolean",
+            "default": false,
+            "description": "关闭时销毁子元素；下次打开重建。表单类内嵌内容用此 prop 重置状态"
+        },
+        "maskClosable": {
+            "type": "boolean",
+            "default": false,
+            "description": "点击蒙层是否允许关闭。**与 disableBackdropClick 是同一能力的双 prop（DEFECT-001）**，src 实际：`!disableBackdropClick \\|\\| maskClosable`。**强烈推荐用 disableBackdropClick 替代 maskClosable**——后者是冗余且易混淆"
+        },
+        "closeOnBackdrop": {
+            "type": "boolean",
+            "description": "**(R6 §B6 阶段 1 引入)** 是否允许蒙层点击关闭(正向命名,业界对齐 antd `maskClosable` / chakra `closeOnOverlayClick`)。显式传值优先 — 未传时 fallback 旧 `disableBackdropClick`(默认 true 即禁用,反业界直觉)。**推荐用 closeOnBackdrop={true}** 替代 `disableBackdropClick={false}` 双重否定写法。阶段 3 v6 移除 disableBackdropClick 后默认 true。详见 BREAKING-CHANGES §B6"
+        },
+        "disableBackdropClick": {
+            "type": "boolean",
+            "default": true,
+            "description": "**@deprecated v5.x.next 改用 `closeOnBackdrop`(正向命名,业界对齐);v6 移除(BREAKING-CHANGES §B6 阶段 3)**。⚠️ 默认 true（即默认禁用蒙层点击关闭）——与多数 Modal 库默认允许的直觉相反（DEFECT-002,R5 9/9 sub-agent 全部明确感知反业界直觉）。需要允许点击遮罩关闭推荐显式传 `closeOnBackdrop={true}`(新 prop) 或旧写法 `disableBackdropClick={false}`(deprecated)"
+        },
+        "closeOnEsc": {
+            "type": "boolean",
+            "description": "**(R6 §B6 阶段 1 引入)** 是否允许 Escape 键关闭(正向命名,业界对齐 antd `keyboard` / chakra `closeOnEsc`)。显式传值优先 — 未传时 fallback 旧 `disableEscapeKeyDown`(默认 true 即禁用,反业界直觉)。**推荐用 closeOnEsc={true}** 替代 `disableEscapeKeyDown={false}` 双重否定。阶段 3 v6 移除 disableEscapeKeyDown 后默认 true。详见 BREAKING-CHANGES §B6"
+        },
+        "disableEscapeKeyDown": {
+            "type": "boolean",
+            "default": true,
+            "description": "**@deprecated v5.x.next 改用 `closeOnEsc`(正向命名,业界对齐);v6 移除(BREAKING-CHANGES §B6 阶段 3)**。⚠️ 默认 true（即默认禁用 ESC 关闭）——同样与多数库直觉相反"
+        },
+        "restoreFocusOnClose": {
+            "type": "boolean",
+            "description": "**(R6 §B6 阶段 1 引入)** 关闭后是否将焦点恢复到原触发元素(正向命名,业界对齐 mui `restoreFocus`)。等价 `focusTriggerAfterClose` 的正向 alias — 显式传值优先,未传时 fallback `focusTriggerAfterClose`(默认 true)。**推荐用 restoreFocusOnClose** 命名;v6 路径只保留 restoreFocusOnClose。详见 BREAKING-CHANGES §B6"
+        },
+        "size": {
+            "type": "enum",
+            "values": [
+                "sm",
+                "md",
+                "lg",
+                "auto",
+                "fullScreen"
+            ],
+            "default": "md",
+            "description": "尺寸枚举。**`size='fullScreen'` 与独立 prop `fullScreen={true}` 是同一能力的双 prop（DEFECT-003）**——src 实际 `fullScreen \\|\\| size === 'fullScreen'`。**推荐用 size='fullScreen'**（与其他尺寸取值同 prop，更一致）"
+        },
+        "fullScreen": {
+            "type": "boolean",
+            "default": false,
+            "description": "全屏开关;与 size='fullScreen' 同义,推荐用 size='fullScreen'。**全屏模式内容区高度行为**:启用时 dialog 容器追加 `.{prefix}-fullscreen` 类,内容区自动 height: 100vh + overflow: auto;contentStyle padding 由父级控制,无需业务方再写 style 撑高"
+        },
+        "centered": {
+            "type": "boolean",
+            "default": true,
+            "description": "**Modal 默认垂直居中**（DEFECT-004:src/Modal/index.tsx:64+129+301 实证,默认值 true,启用时根容器追加 `.{prefix}-centered` 类）。无需 style transform 等 hack 实现居中——直接使用默认即可。如需顶部对齐请显式传 `centered={false}`。"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "落在 Modal **dialog 外层容器**（DEFECT-007:与 contentStyle 区分,后者仅作用于内容区 DOM）。常用于覆盖整体边距 / z-index / position 等容器级属性。"
+        },
+        "contentStyle": {
+            "type": "React.CSSProperties",
+            "description": "落在 Modal **内容区 DOM 节点**（DEFECT-007:src/Modal/index.tsx:224 实证)。覆盖 contentHeight 等内容区限定样式。需要整体 dialog 样式请用 style。"
+        },
+        "width": {
+            "type": "string | number",
+            "description": "Modal dialog 容器整体宽度。与 `contentWidth` 区分：contentWidth 仅控制内容区，width 控制整体——业务侧『自定义宽度』优先用 width"
+        },
+        "okText": {
+            "type": "string",
+            "description": "确认按钮文字"
+        },
+        "cancelText": {
+            "type": "string",
+            "description": "取消按钮文字"
+        },
+        "actions": {
+            "type": "function | ReactNode",
+            "signature": "((buttons: ReactNode[]) => ReactNode[]) | ReactNode",
+            "description": "⚠️ **完全自定义底部操作栏**（src/Modal/index.tsx:69 实证）。两种用法：① 传 `ReactNode` 完全替换底部按钮区（隐藏默认确定/取消按钮，渲染自定义内容）；② 传函数 `(buttons) => ReactNode[]` 接收默认按钮数组后按需增删/改造再返回。**与 `footer` 区分**：`footer` 语义相同但 actions 是更语义化的命名（两者 src 并存，任选一即可）。**与 `showActions` 区分**：showActions=false 是整体隐藏，actions 是替换内容——需要完全自定义按钮组合时用 actions，需要隐藏整个底部区域时用 showActions=false"
+        }
+    },
+    "do": [
+        "保持模态框内容简洁，避免过于复杂的流程",
+        "**新代码统一用 `open` 而非 `visible`**——visible 是旧别名",
+        "**`onDismiss` + `onOk` + `onCancel` 三回调首推(v5.x.next γ 方案)**：`onDismiss` 处理非按钮路径（X/ESC/蒙层），`onOk` 处理确定按钮，`onCancel` 处理取消按钮，三者职责互斥，无双触发问题",
+        "**旧写法（不推荐）**：`onClose(reason)` 顶层回调在任意路径关闭时触发，v5.x.next 已标 @deprecated，v6.0 移除。如仍使用，在 onClose 里统一 setOpen(false) + reason 分支（reason ∈ 'cancel'|'ok'|'esc'|'mask'|'x'）",
+        "**全屏模态用 `size='fullScreen'`**——与其他尺寸取值同 prop；fullScreen={true} 是冗余别名",
+        "**点击蒙层关闭：用 `closeOnBackdrop={true}`(R6 §B6 阶段 1 推荐,正向命名,业界对齐)** — 替代旧 `disableBackdropClick={false}` 双重否定写法;`maskClosable` 仍是冗余双 prop,推荐用 closeOnBackdrop。同理 `closeOnEsc={true}` 替代 `disableEscapeKeyDown={false}`;`restoreFocusOnClose` 替代旧 `focusTriggerAfterClose` 正向 alias",
+        "**Modal 默认垂直居中**（centered=true）——无需 style transform 居中 hack。需要顶部对齐显式传 centered={false}",
+        "整体 dialog 样式用 `style`,内容区限定样式用 `contentStyle`——两者作用 DOM 节点不同(DEFECT-007)",
+        "整体宽度自定义用 `width`（不是 contentWidth——后者仅控制内容区）",
+        "重要操作（如不可逆删除）应使 ESC + 蒙层都不能关闭——保留默认 `closeOnEsc=undefined / closeOnBackdrop=undefined`(fallback 旧 disable* 默认 true 即锁定);旧写法 `disableEscapeKeyDown=true / disableBackdropClick=true` 仍工作但不推荐",
+        "需要关闭后重置内嵌表单状态时使用 `destroyOnClose={true}`",
+        "确定按钮 loading 状态用 `confirmLoading={true}`——loading 期间按钮自动 disabled,业务无需再叠 okButtonProps.disabled"
+    ],
+    "dont": [
+        "在模态框上再叠加模态框（多层嵌套）",
+        "在模态框中放置过长的表单（应考虑独立页面）",
+        "不要混用 visible 与 open 双 prop——只传一个",
+        "不要既传 fullScreen 又传 size='fullScreen'——只传一个，推荐 size",
+        "不要既传 disableBackdropClick 又传 maskClosable——只传一个,推荐 closeOnBackdrop(R6 §B6 阶段 1 引入正向命名)",
+        "不要假设 disableBackdropClick / disableEscapeKeyDown 默认值是 false——它们默认 true（即默认禁用），与多数库直觉相反;v6 路径已 rename 为 closeOnBackdrop / closeOnEsc / restoreFocusOnClose 正向 prop"
+    ],
+    "events": {
+        "onSubmit": {
+            "signature": "(e?: React.MouseEvent<HTMLElement>) => void | Promise<void>",
+            "asyncSupported": true,
+            "examples": [
+                "推荐新写法：async onSubmit 处理异步提交，confirmLoading 配合显示 loading 状态",
+                "onSubmit 与 onOk 同义，同时传时 onSubmit 优先，onOk 被跳过（src/Modal/index.tsx:230-234 实证）",
+                "表单提交场景：onSubmit 内调 formRef.current.check?.()，失败 return，成功后关闭 Modal"
+            ],
+            "commonMistakes": [
+                "同时传 onOk + onSubmit，期望两者都执行 → src 优先调 onSubmit，onOk 被跳过",
+                "假设 async onSubmit 执行完成后 Modal 自动关闭 → Modal 完全受控，必须在 onSubmit 内手动 setOpen(false)",
+                "传 onOk 而不传 onSubmit 时触发 dev warn → src 检测到仅有 onOk 会 console.warn 一次提示迁移到 onSubmit"
+            ]
+        },
+        "onCancel": {
+            "signature": "(e?: React.MouseEvent<HTMLElement>) => boolean | void",
+            "asyncSupported": false,
+            "examples": [
+                "点击取消按钮触发，业务方在回调里 setOpen(false) 关闭 Modal",
+                "返回 false 阻止关闭（src/Modal/index.tsx:interface 签名实证）",
+                "showCancel=false 时用户无法触发 onCancel，X/ESC/蒙层改走 onDismiss"
+            ],
+            "commonMistakes": [
+                "假设 onCancel 在 X 按钮/ESC/蒙层点击时也触发 → v5.x.next 新模式下传了 onDismiss 且不传 onClose 时，X/ESC/mask 仅调 onDismiss，不双触发 onCancel",
+                "不在 onCancel 内 setOpen(false) → Modal 是完全受控组件，不自动关闭",
+                "假设 onCancel 和 onClose 等价 → onClose 是 deprecated 的统一路径回调（v6 移除），onCancel 只绑取消按钮"
+            ]
+        },
+        "onDismiss": {
+            "signature": "(reason: 'esc' | 'mask' | 'x') => void",
+            "asyncSupported": false,
+            "examples": [
+                "推荐新写法（v5.x.next）：`onDismiss={(r) => { if (r !== 'esc') setOpen(false); }}` 区分关闭来源",
+                "仅传 onDismiss 不传 onClose → 新单触发行为：X/ESC/mask 只调 onDismiss，不再同时触发 onCancel",
+                "同时传 onClose（无论是否传 onDismiss）→ 旧兼容行为：维持 R6 双触发（onCancel + onClose）"
+            ],
+            "commonMistakes": [
+                "假设 onDismiss 的 reason 包含 'cancel' 或 'ok' → ModalDismissReason 只有 'esc' | 'mask' | 'x'，按钮路径不走这里",
+                "同时传 onClose + onDismiss 并期望单触发 → 同时传 onClose 时维持旧双触发行为，只有删 onClose 才能用新单触发",
+                "在 onDismiss 内不 setOpen(false) → Modal 完全受控，必须手动关闭"
+            ]
+        },
+        "onClose": {
+            "signature": "(reason: 'cancel' | 'ok' | 'esc' | 'mask' | 'x') => void",
+            "asyncSupported": false,
+            "examples": [
+                "（旧写法，已 @deprecated）统一处理所有关闭路径，reason 区分来源",
+                "迁移示例：删 onClose 改用 onDismiss + onOk + onCancel 三回调",
+                "如仍使用：`onClose={(r) => { setOpen(false); if (r==='ok') submit(); }}` 在 onClose 里统一 setOpen + 分支处理"
+            ],
+            "commonMistakes": [
+                "传了 onClose 后期望 onOk + onClose('ok') 不重复触发业务逻辑 → 两者叠加触发（src:230-237 实证），需在 onOk 只做提交，在 onClose 里判断 reason='ok' 再 setOpen(false)",
+                "在 v6 前就依赖 onClose 的确定/取消路径 → v6.0 移除 onClose，应迁移到新三回调模式",
+                "假设 onClose 在 Modal 组件 unmount 时触发 → onClose 仅在用户主动关闭时触发，不是生命周期回调"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "ModalCloseReason 和 ModalDismissReason 是不同的类型，不能混用",
+            "wrong": "onDismiss={(reason: 'cancel' | 'ok' | 'esc' | 'mask' | 'x') => ...}  // onDismiss 参数是 ModalDismissReason，无 'cancel'/'ok'",
+            "right": "import { ModalDismissReason } from '@para-ui/core'; onDismiss={(reason: ModalDismissReason) => ...}  // ModalDismissReason = 'esc' | 'mask' | 'x'"
+        },
+        {
+            "issue": "disableBackdropClick / disableEscapeKeyDown 默认值是 true（禁用），与多数库默认允许的直觉相反",
+            "wrong": "// 期望默认允许点击蒙层关闭 → 实际默认 disableBackdropClick=true 即禁用蒙层关闭",
+            "right": "<Modal closeOnBackdrop={true} closeOnEsc={true} />  // 正向命名，明确允许蒙层和ESC关闭（src/Modal/index.tsx:201-204 实证）"
+        },
+        {
+            "issue": "onSubmit 支持 async，onOk 的旧签名不明确支持 Promise",
+            "wrong": "onOk={async () => { await doSubmit(); setOpen(false); }}  // onOk 已 deprecated，且类型签名不含 Promise",
+            "right": "onSubmit={async (e) => { await doSubmit(); setOpen(false); }}  // onSubmit 签名: (e?) => void | Promise<void>"
+        },
+        {
+            "issue": "actions prop 接受函数形式时返回值类型是 ReactNode[] 不是 ReactNode",
+            "wrong": "actions={(btns) => <div>{btns}</div>}  // 返回 ReactNode，TS 报类型不匹配",
+            "right": "actions={(btns) => [...btns, <Button key='extra'>额外按钮</Button>]}  // 返回 ReactNode[] 数组"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Modal",
+        "adapter": null
+    }
+}

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