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

package/es/Modal/index.js

@@ -1,70 +1,122 @@
 import { j as t } from "../_virtual/jsx-runtime.js";
-import p from "react";
-import le from "rc-dialog";
-import { Button as m } from "../Button/index.js";
-import { Close as ae } from "../node_modules/@para-ui/icons/Close/index.js";
-import ie from "../GlobalContext/useFormatMessage.js";
-import ce from "./lang/index.js";
-import { Confirm as Ne } from "./Confirm/index.js";
-import C from "clsx";
-import { $prefixCls as y } from "../GlobalContext/constant.js";
-import me from "../AutoTips/index.js";
+import n from "react";
+import _e from "rc-dialog";
+import { Button as k } from "../Button/index.js";
+import { Close as ze } from "../node_modules/@para-ui/icons/Close/index.js";
+import Fe from "../GlobalContext/useFormatMessage.js";
+import Te from "./lang/index.js";
+import { Confirm as to } from "./Confirm/index.js";
+import P from "clsx";
+import { $prefixCls as W } from "../GlobalContext/constant.js";
+import Ie from "../AutoTips/index.js";
 import './index.css';/* empty css           */
-let u;
-const ue = (o) => {
-  u = {
-    x: o.pageX,
-    y: o.pageY
+let h;
+const Ke = (e) => {
+  h = {
+    x: e.pageX,
+    y: e.pageY
   }, setTimeout(() => {
-    u = null;
+    h = null;
   }, 100);
 };
-window.document.documentElement && document.documentElement.addEventListener("click", ue, !0);
-const we = (o) => {
+window.document.documentElement && document.documentElement.addEventListener("click", Ke, !0);
+const oo = (e) => {
   const {
-    open: $,
-    visible: b = !1,
-    closeIcon: S,
-    centered: w = !0,
-    focusTriggerAfterClose: j = !0,
-    title: z,
-    footer: N,
-    showActions: B = !0,
-    actions: F,
-    header: d,
-    hideHeader: H = !1,
-    showCancel: M = !0,
-    maskClosable: v = !1,
-    disableBackdropClick: A = !0,
-    keyboard: T = !1,
-    disableEscapeKeyDown: E = !0,
-    fullScreen: P,
-    customizeSize: I,
-    style: D,
-    bodyStyle: L,
-    contentWidth: O,
-    contentHeight: f,
-    contentStyle: h,
-    size: s = "md",
-    children: R,
-    closable: W = !0,
-    mask: g = !0,
-    ..._
-  } = o, J = P || s === "fullScreen", x = ie("Modal", ce), e = `${y}-modal`, a = (n) => {
-    o.onCancel?.(n);
-  }, K = (n) => {
-    o.onOk?.(n);
-  }, X = () => {
-    const n = {
-      sm: `${e}-sm`,
-      md: `${e}-md`,
-      lg: `${e}-lg`,
-      auto: `${e}-auto`,
-      fullScreen: `${e}-fullscreen`
+    open: f,
+    visible: m,
+    defaultOpen: v,
+    closeIcon: X,
+    centered: L = !0,
+    focusTriggerAfterClose: J = !0,
+    title: Q,
+    footer: U,
+    showActions: Y = !0,
+    actions: q,
+    header: E,
+    hideHeader: Z = !1,
+    showCancel: ee = !0,
+    maskClosable: oe = !1,
+    disableBackdropClick: ne = !0,
+    closeOnBackdrop: p,
+    keyboard: se = !1,
+    disableEscapeKeyDown: te = !0,
+    closeOnEsc: x,
+    restoreFocusOnClose: g,
+    fullScreen: le,
+    customizeSize: ae,
+    style: re,
+    bodyStyle: ce,
+    contentWidth: ie,
+    contentHeight: N,
+    contentStyle: b,
+    size: a = "md",
+    children: de,
+    closable: ue = !0,
+    mask: w = !0,
+    ...fe
+  } = e, O = Fe("Modal", Te), i = e.onClose !== void 0, S = n.useRef(!1);
+  n.useEffect(() => {
+    process.env.NODE_ENV !== "production" && i && !S.current && (S.current = !0, console.warn(
+      "[Modal] onClose 已在 v5.x.next 标记为 @deprecated，将在 v6.0 移除。请迁移到 onDismiss（处理 X/ESC/mask 关闭）+ onOk（确定按钮）+ onCancel（取消按钮）三回调模式。详见 BREAKING-CHANGES §B-Modal-props-rework。"
+    ));
+  }, [i]);
+  const B = m !== void 0, D = n.useRef(!1);
+  n.useEffect(() => {
+    process.env.NODE_ENV !== "production" && B && !D.current && (D.current = !0, console.warn(
+      "[Modal] visible 已在 v5.x.next 标记为 @deprecated，将在 v6.0 移除。请改用 open prop。详见 BREAKING-CHANGES §B-Modal-props-rework 子条 #3-A"
+    ));
+  }, [B]);
+  const A = e.onOk !== void 0, M = e.onSubmit !== void 0, y = n.useRef(!1);
+  n.useEffect(() => {
+    process.env.NODE_ENV !== "production" && A && !M && !y.current && (y.current = !0, console.warn(
+      "[Modal] onOk 已在 v5.x.next 标记为 @deprecated，将在 v6.0 移除。请改用 onSubmit prop（语义更清晰）。详见 BREAKING-CHANGES §B-Modal-props-rework"
+    ));
+  }, [A, M]);
+  const R = e.onCancel !== void 0, $ = e.onDismiss !== void 0, j = n.useRef(!1);
+  n.useEffect(() => {
+    if (process.env.NODE_ENV !== "production" && R && !$ && !i && !j.current)
+      throw j.current = !0, new Error(
+        "[Modal] v5.0.0-beta.14 起 X / ESC / 蒙层关闭路径主职责已交给 onDismiss(γ 互斥语义)。当前仅传 onCancel 而未传 onDismiss/onClose,prod 走 fallback 兼容,dev 抛 Error 强制迁移。一键迁移:`npx jscodeshift -t node_modules/@para-ui/core/codemods/modal-onCancel-to-onDismiss.js --parser=tsx src/`。v6.0(2026 Q3)起 fallback 删除,届时 X/ESC/mask 静默失效。详见 docs/UPGRADE_v4_to_v5.md §3.D.0 + BREAKING-CHANGES §B-Modal-props-rework 子条 #5。"
+      );
+  }, [R, $, i]);
+  const H = e.maskClosable !== void 0, G = e.disableBackdropClick !== void 0, _ = e.disableEscapeKeyDown !== void 0, z = e.focusTriggerAfterClose !== void 0, F = n.useRef(!1);
+  n.useEffect(() => {
+    if (process.env.NODE_ENV === "production" || F.current) return;
+    const o = [];
+    H && o.push("maskClosable → closeOnBackdrop"), G && o.push("disableBackdropClick → closeOnBackdrop"), _ && o.push("disableEscapeKeyDown → closeOnEsc"), z && o.push("focusTriggerAfterClose → restoreFocusOnClose"), o.length !== 0 && (F.current = !0, console.warn(
+      `[Modal] 检测到 v5.x.next 已 @deprecated 的反向命名 prop:${o.join("、")}。v5.x 仍 fallback 兼容,v6.0 移除。请按箭头右侧迁移到正向命名(对齐业界 antd/chakra/mui)。详见 BREAKING-CHANGES §B-Modal-props-rework + §B6。`
+    ));
+  }, [H, G, _, z]);
+  const l = f !== void 0 || m !== void 0, [me, d] = n.useState(v ?? !1), Ce = l ? f ?? m ?? !1 : me, T = v !== void 0, I = f !== void 0;
+  n.useEffect(() => {
+    process.env.NODE_ENV !== "production" && I && T && console.warn(
+      "[Modal] 同时传 open + defaultOpen，defaultOpen 被忽略（open 优先，受控模式）。详见 BREAKING-CHANGES §B-Modal-props-rework 子条 #2"
+    );
+  }, [I, T]);
+  const K = n.useRef(l);
+  n.useEffect(() => {
+    K.current !== l && (process.env.NODE_ENV !== "production" && console.warn("[Modal] open 受控/非受控状态运行时切换，React 不支持此模式，请保持一致。"), K.current = l);
+  }, [l]);
+  const ke = le || a === "fullScreen", s = `${W}-modal`, he = x !== void 0 ? x : !te, ve = p !== void 0 ? p : !ne, Ee = g !== void 0 ? g : J, pe = (o) => {
+    e.onCancel?.(o), e.onClose?.("cancel"), l || d(!1);
+  }, xe = (o) => {
+    e.onClose !== void 0 ? (e.onCancel?.(o), e.onClose("x")) : e.onDismiss !== void 0 ? e.onDismiss("x") : e.onCancel?.(o), l || d(!1);
+  }, ge = (o) => {
+    const r = o && o.type === "keydown" ? "esc" : "mask";
+    e.onClose !== void 0 ? (e.onCancel?.(o), e.onClose(r)) : e.onDismiss !== void 0 ? e.onDismiss(r) : e.onCancel?.(o), l || d(!1);
+  }, Ne = (o) => {
+    e.onSubmit ? e.onSubmit(o) : e.onOk?.(o), e.onClose?.("ok"), l || d(!1);
+  }, be = () => {
+    const o = {
+      sm: `${s}-sm`,
+      md: `${s}-md`,
+      lg: `${s}-lg`,
+      auto: `${s}-auto`,
+      fullScreen: `${s}-fullscreen`
     };
-    if (!h)
-      return J ? n.fullScreen : n[s];
-  }, Y = () => !s || s === "fullScreen" || s === "auto" ? void 0 : {
+    if (!b)
+      return ke ? o.fullScreen : o[a];
+  }, we = () => !a || a === "fullScreen" || a === "auto" ? void 0 : {
     sm: {
       width: 430,
       maxHeight: 118
@@ -77,94 +129,94 @@ const we = (o) => {
       width: 948,
       maxHeight: 478
     }
-  }[s], q = () => g ? `${e}-with-mask` : `${e}-without-mask`, G = () => ({ ...I, ...D }), Q = () => {
-    const { maxHeight: n, width: i } = Y() || {};
+  }[a], Oe = () => w ? `${s}-with-mask` : `${s}-without-mask`, Se = () => ({ ...ae, ...re }), Be = () => {
+    const { maxHeight: o, width: r } = we() || {};
     return {
       // contentWidth 和 contentHeight 优先级总是最高
-      maxHeight: f || n || "calc(100vh - 142px)",
-      width: O || i,
-      height: f,
+      maxHeight: N || o || "calc(100vh - 142px)",
+      width: ie || r,
+      height: N,
       // minHeight: contentHeight || 118,
-      ...L,
-      ...h
+      ...ce,
+      ...b
     };
-  }, U = () => {
-    if (H) return null;
-    if (d) return d;
-    const n = W && /* @__PURE__ */ t.jsx(
-      m.IconButton,
+  }, De = () => {
+    if (Z) return null;
+    if (E) return E;
+    const o = ue && /* @__PURE__ */ t.jsx(
+      k.IconButton,
       {
-        onClick: a,
-        className: `${e}-close`,
+        onClick: xe,
+        className: `${s}-close`,
         variant: "outlined",
         size: "small",
-        children: S || /* @__PURE__ */ t.jsx(ae, { className: `${e}-close-icon` })
+        children: X || /* @__PURE__ */ t.jsx(ze, { className: `${s}-close-icon` })
       }
     );
     return /* @__PURE__ */ t.jsxs(t.Fragment, { children: [
-      /* @__PURE__ */ t.jsx(me, { className: `${e}-title-text`, children: z }),
-      n
+      /* @__PURE__ */ t.jsx(Ie, { className: `${s}-title-text`, children: Q }),
+      o
     ] });
-  }, V = () => {
-    if (!B) return null;
-    const { okText: n, cancelText: i, okButtonProps: te, cancelButtonProps: ne, confirmLoading: oe = !1 } = o, se = /* @__PURE__ */ t.jsx(
-      m,
+  }, Ae = () => {
+    if (!Y) return null;
+    const { okText: o, cancelText: r, okButtonProps: Re, cancelButtonProps: $e, confirmLoading: je = !1 } = e, He = /* @__PURE__ */ t.jsx(
+      k,
       {
         variant: "contained",
         size: "large",
-        loading: oe,
-        onClick: K,
-        ...te,
-        children: n ?? x({ id: "ok" })
+        loading: je,
+        onClick: Ne,
+        ...Re,
+        children: o ?? O({ id: "ok" })
       }
-    ), k = [M && /* @__PURE__ */ t.jsx(
-      m,
+    ), V = [ee && /* @__PURE__ */ t.jsx(
+      k,
       {
         variant: "outlined",
         size: "large",
-        onClick: a,
-        ...ne,
-        children: i ?? x({ id: "cancel" })
+        onClick: pe,
+        ...$e,
+        children: r ?? O({ id: "cancel" })
       }
-    ), se], l = F ?? N;
-    if (typeof l == "function") {
-      const r = l(k);
-      return /* @__PURE__ */ t.jsx(t.Fragment, { children: Array.isArray(r) ? r.map((c, re) => /* @__PURE__ */ t.jsx(p.Fragment, { children: c }, re)) : r });
-    } else if (l)
-      return l;
-    return /* @__PURE__ */ t.jsx(t.Fragment, { children: k.map((r, c) => /* @__PURE__ */ t.jsx(p.Fragment, { children: r }, c)) });
-  }, Z = C(o.wrapClassName, {
-    [`${e}-centered`]: w
-  }), ee = C(o.className, `${y}-scrollbar-small`, X(), q());
+    ), He], u = q ?? U;
+    if (typeof u == "function") {
+      const c = u(V);
+      return /* @__PURE__ */ t.jsx(t.Fragment, { children: Array.isArray(c) ? c.map((C, Ge) => /* @__PURE__ */ t.jsx(n.Fragment, { children: C }, Ge)) : c });
+    } else if (u)
+      return u;
+    return /* @__PURE__ */ t.jsx(t.Fragment, { children: V.map((c, C) => /* @__PURE__ */ t.jsx(n.Fragment, { children: c }, C)) });
+  }, Me = P(e.wrapClassName, {
+    [`${s}-centered`]: L
+  }), ye = P(e.className, `${W}-scrollbar-small`, be(), Oe());
   return /* @__PURE__ */ t.jsx(
-    le,
+    _e,
     {
-      ..._,
-      mask: g,
-      visible: $ ?? b,
-      title: U(),
-      footer: V(),
-      style: G(),
-      bodyStyle: Q(),
-      prefixCls: e,
-      className: ee,
-      wrapClassName: Z,
-      mousePosition: u,
-      onClose: a,
+      ...fe,
+      mask: w,
+      visible: Ce,
+      title: De(),
+      footer: Ae(),
+      style: Se(),
+      bodyStyle: Be(),
+      prefixCls: s,
+      className: ye,
+      wrapClassName: Me,
+      mousePosition: h,
+      onClose: ge,
       closable: !1,
       closeIcon: null,
-      maskClosable: !A || v,
-      keyboard: !E || T,
-      focusTriggerAfterClose: j,
-      transitionName: `${e}-zoom`,
-      maskTransitionName: `${e}-fade`,
-      children: R
+      maskClosable: ve || oe,
+      keyboard: he || se,
+      focusTriggerAfterClose: Ee,
+      transitionName: `${s}-zoom`,
+      maskTransitionName: `${s}-fade`,
+      children: de
     }
   );
 };
 export {
-  Ne as Confirm,
-  we as Modal,
-  we as default
+  to as Confirm,
+  oo as Modal,
+  oo as default
 };
 //# sourceMappingURL=index.js.map

package/es/Modal/interface.d.ts

@@ -0,0 +1 @@
+export type ModalDismissReason = 'esc' | 'mask' | 'x';

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