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

package/es/Modal/index.js

@@ -1,70 +1,107 @@
 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 s from "react";
+import Me from "rc-dialog";
+import { Button as C } from "../Button/index.js";
+import { Close as Ae } from "../node_modules/@para-ui/icons/Close/index.js";
+import $e from "../GlobalContext/useFormatMessage.js";
+import Re from "./lang/index.js";
+import { Confirm as qe } from "./Confirm/index.js";
+import H from "clsx";
+import { $prefixCls as F } from "../GlobalContext/constant.js";
+import je from "../AutoTips/index.js";
 import './index.css';/* empty css           */
-let u;
-const ue = (o) => {
-  u = {
-    x: o.pageX,
-    y: o.pageY
+let h;
+const ze = (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", ze, !0);
+const Le = (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: u,
+    visible: f,
+    defaultOpen: k,
+    closeIcon: G,
+    centered: I = !0,
+    focusTriggerAfterClose: T = !0,
+    title: _,
+    footer: V,
+    showActions: K = !0,
+    actions: P,
+    header: p,
+    hideHeader: W = !1,
+    showCancel: X = !0,
+    maskClosable: L = !1,
+    disableBackdropClick: J = !0,
+    closeOnBackdrop: x,
+    keyboard: Y = !1,
+    disableEscapeKeyDown: q = !0,
+    closeOnEsc: v,
+    restoreFocusOnClose: g,
+    fullScreen: Q,
+    customizeSize: U,
+    style: Z,
+    bodyStyle: ee,
+    contentWidth: oe,
+    contentHeight: E,
+    contentStyle: N,
+    size: r = "md",
+    children: ne,
+    closable: te = !0,
+    mask: O = !0,
+    ...se
+  } = e, w = $e("Modal", Re), S = e.onClose !== void 0, b = s.useRef(!1);
+  s.useEffect(() => {
+    process.env.NODE_ENV !== "production" && S && !b.current && (b.current = !0, console.warn(
+      "[Modal] onClose 已在 v5.x.next 标记为 @deprecated，将在 v6.0 移除。请迁移到 onDismiss（处理 X/ESC/mask 关闭）+ onOk（确定按钮）+ onCancel（取消按钮）三回调模式。详见 BREAKING-CHANGES §B-Modal-props-rework。"
+    ));
+  }, [S]);
+  const y = f !== void 0, B = s.useRef(!1);
+  s.useEffect(() => {
+    process.env.NODE_ENV !== "production" && y && !B.current && (B.current = !0, console.warn(
+      "[Modal] visible 已在 v5.x.next 标记为 @deprecated，将在 v6.0 移除。请改用 open prop。详见 BREAKING-CHANGES §B-Modal-props-rework 子条 #3-A"
+    ));
+  }, [y]);
+  const M = e.onOk !== void 0, A = e.onSubmit !== void 0, $ = s.useRef(!1);
+  s.useEffect(() => {
+    process.env.NODE_ENV !== "production" && M && !A && !$.current && ($.current = !0, console.warn(
+      "[Modal] onOk 已在 v5.x.next 标记为 @deprecated，将在 v6.0 移除。请改用 onSubmit prop（语义更清晰）。详见 BREAKING-CHANGES §B-Modal-props-rework"
+    ));
+  }, [M, A]);
+  const l = u !== void 0 || f !== void 0, [le, i] = s.useState(k ?? !1), re = l ? u ?? f ?? !1 : le, R = k !== void 0, j = u !== void 0;
+  s.useEffect(() => {
+    process.env.NODE_ENV !== "production" && j && R && console.warn(
+      "[Modal] 同时传 open + defaultOpen，defaultOpen 被忽略（open 优先，受控模式）。详见 BREAKING-CHANGES §B-Modal-props-rework 子条 #2"
+    );
+  }, [j, R]);
+  const z = s.useRef(l);
+  s.useEffect(() => {
+    z.current !== l && (process.env.NODE_ENV !== "production" && console.warn("[Modal] open 受控/非受控状态运行时切换，React 不支持此模式，请保持一致。"), z.current = l);
+  }, [l]);
+  const ae = Q || r === "fullScreen", n = `${F}-modal`, ce = v !== void 0 ? v : !q, ie = x !== void 0 ? x : !J, de = g !== void 0 ? g : T, ue = (o) => {
+    e.onCancel?.(o), e.onClose?.("cancel"), l || i(!1);
+  }, fe = (o) => {
+    e.onClose !== void 0 ? (e.onCancel?.(o), e.onClose("x")) : e.onDismiss?.("x"), l || i(!1);
+  }, me = (o) => {
+    const a = o && o.type === "keydown" ? "esc" : "mask";
+    e.onClose !== void 0 ? (e.onCancel?.(o), e.onClose(a)) : e.onDismiss?.(a), l || i(!1);
+  }, Ce = (o) => {
+    e.onSubmit ? e.onSubmit(o) : e.onOk?.(o), e.onClose?.("ok"), l || i(!1);
+  }, he = () => {
+    const o = {
+      sm: `${n}-sm`,
+      md: `${n}-md`,
+      lg: `${n}-lg`,
+      auto: `${n}-auto`,
+      fullScreen: `${n}-fullscreen`
     };
-    if (!h)
-      return J ? n.fullScreen : n[s];
-  }, Y = () => !s || s === "fullScreen" || s === "auto" ? void 0 : {
+    if (!N)
+      return ae ? o.fullScreen : o[r];
+  }, ke = () => !r || r === "fullScreen" || r === "auto" ? void 0 : {
     sm: {
       width: 430,
       maxHeight: 118
@@ -77,94 +114,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() || {};
+  }[r], pe = () => O ? `${n}-with-mask` : `${n}-without-mask`, xe = () => ({ ...U, ...Z }), ve = () => {
+    const { maxHeight: o, width: a } = ke() || {};
     return {
       // contentWidth 和 contentHeight 优先级总是最高
-      maxHeight: f || n || "calc(100vh - 142px)",
-      width: O || i,
-      height: f,
+      maxHeight: E || o || "calc(100vh - 142px)",
+      width: oe || a,
+      height: E,
       // minHeight: contentHeight || 118,
-      ...L,
-      ...h
+      ...ee,
+      ...N
     };
-  }, U = () => {
-    if (H) return null;
-    if (d) return d;
-    const n = W && /* @__PURE__ */ t.jsx(
-      m.IconButton,
+  }, ge = () => {
+    if (W) return null;
+    if (p) return p;
+    const o = te && /* @__PURE__ */ t.jsx(
+      C.IconButton,
       {
-        onClick: a,
-        className: `${e}-close`,
+        onClick: fe,
+        className: `${n}-close`,
         variant: "outlined",
         size: "small",
-        children: S || /* @__PURE__ */ t.jsx(ae, { className: `${e}-close-icon` })
+        children: G || /* @__PURE__ */ t.jsx(Ae, { className: `${n}-close-icon` })
       }
     );
     return /* @__PURE__ */ t.jsxs(t.Fragment, { children: [
-      /* @__PURE__ */ t.jsx(me, { className: `${e}-title-text`, children: z }),
-      n
+      /* @__PURE__ */ t.jsx(je, { className: `${n}-title-text`, children: _ }),
+      o
     ] });
-  }, V = () => {
-    if (!B) return null;
-    const { okText: n, cancelText: i, okButtonProps: te, cancelButtonProps: ne, confirmLoading: oe = !1 } = o, se = /* @__PURE__ */ t.jsx(
-      m,
+  }, Ee = () => {
+    if (!K) return null;
+    const { okText: o, cancelText: a, okButtonProps: we, cancelButtonProps: Se, confirmLoading: be = !1 } = e, ye = /* @__PURE__ */ t.jsx(
+      C,
       {
         variant: "contained",
         size: "large",
-        loading: oe,
-        onClick: K,
-        ...te,
-        children: n ?? x({ id: "ok" })
+        loading: be,
+        onClick: Ce,
+        ...we,
+        children: o ?? w({ id: "ok" })
       }
-    ), k = [M && /* @__PURE__ */ t.jsx(
-      m,
+    ), D = [X && /* @__PURE__ */ t.jsx(
+      C,
       {
         variant: "outlined",
         size: "large",
-        onClick: a,
-        ...ne,
-        children: i ?? x({ id: "cancel" })
+        onClick: ue,
+        ...Se,
+        children: a ?? w({ 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());
+    ), ye], d = P ?? V;
+    if (typeof d == "function") {
+      const c = d(D);
+      return /* @__PURE__ */ t.jsx(t.Fragment, { children: Array.isArray(c) ? c.map((m, Be) => /* @__PURE__ */ t.jsx(s.Fragment, { children: m }, Be)) : c });
+    } else if (d)
+      return d;
+    return /* @__PURE__ */ t.jsx(t.Fragment, { children: D.map((c, m) => /* @__PURE__ */ t.jsx(s.Fragment, { children: c }, m)) });
+  }, Ne = H(e.wrapClassName, {
+    [`${n}-centered`]: I
+  }), Oe = H(e.className, `${F}-scrollbar-small`, he(), pe());
   return /* @__PURE__ */ t.jsx(
-    le,
+    Me,
     {
-      ..._,
-      mask: g,
-      visible: $ ?? b,
-      title: U(),
-      footer: V(),
-      style: G(),
-      bodyStyle: Q(),
-      prefixCls: e,
-      className: ee,
-      wrapClassName: Z,
-      mousePosition: u,
-      onClose: a,
+      ...se,
+      mask: O,
+      visible: re,
+      title: ge(),
+      footer: Ee(),
+      style: xe(),
+      bodyStyle: ve(),
+      prefixCls: n,
+      className: Oe,
+      wrapClassName: Ne,
+      mousePosition: h,
+      onClose: me,
       closable: !1,
       closeIcon: null,
-      maskClosable: !A || v,
-      keyboard: !E || T,
-      focusTriggerAfterClose: j,
-      transitionName: `${e}-zoom`,
-      maskTransitionName: `${e}-fade`,
-      children: R
+      maskClosable: ie || L,
+      keyboard: ce || Y,
+      focusTriggerAfterClose: de,
+      transitionName: `${n}-zoom`,
+      maskTransitionName: `${n}-fade`,
+      children: ne
     }
   );
 };
 export {
-  Ne as Confirm,
-  we as Modal,
-  we as default
+  qe as Confirm,
+  Le as Modal,
+  Le 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
+    }
+}

package/es/MultiBox/index.js

@@ -10,7 +10,7 @@ import ae from "../GlobalContext/useFormatMessage.js";
 import ie from "./lang/index.js";
 import { Tooltip as ne } from "../Tooltip/index.js";
 import './index.css';/* empty css           */
-const ye = (n) => {
+const ye = (u) => {
   const {
     className: C,
     style: D,
@@ -29,14 +29,14 @@ const ye = (n) => {
     helperText: d = "",
     value: x,
     replaceFields: v,
-    onChange: i,
+    onChange: n,
     fetchSuggestionsKey: j,
     fetchSuggestionsValue: g,
     keyOtherProps: k,
     valueOtherProps: T
-  } = n, S = !!(d && typeof d == "string"), J = d instanceof Array, w = ae("MultiBox", ie), [o, c] = M([]), [a, G] = M({ key: "label", value: "value" });
+  } = u, S = !!(d && typeof d == "string"), J = d instanceof Array, w = ae("MultiBox", ie), [o, c] = M([]), [a, G] = M({ key: "label", value: "value" });
   y(() => {
-    n.defaultValue !== void 0 && c([...n.defaultValue]);
+    u.defaultValue !== void 0 && c([...u.defaultValue]);
   }, []), y(() => {
     x !== void 0 && c([...x]);
   }, [x]), y(() => {
@@ -48,19 +48,19 @@ const ye = (n) => {
   const $ = (t, e) => {
     let l = { error: !1, helperText: "" };
     if (J) {
-      const u = d[t];
-      u && u[e] && (l = {
+      const i = d[t];
+      i && i[e] && (l = {
         error: !0,
-        helperText: u[e]
+        helperText: i[e]
       });
     }
     return l;
   }, Q = () => {
-    s !== !0 && (o.push({}), n.value === void 0 && c([...o]), i && i(o));
+    s !== !0 && (o.push({}), u.value === void 0 && c([...o]), n && n(o));
   }, U = (t) => () => {
-    s !== !0 && (o.splice(t, 1), n.value === void 0 && c([...o]), i && i(o));
+    s !== !0 && (o.splice(t, 1), u.value === void 0 && c([...o]), n && n(o));
   }, A = (t, e) => (l) => {
-    o[e][t] = l.target.value, n.value === void 0 && c([...o]), i && i(o);
+    o[e][t] = l.target.value, u.value === void 0 && c([...o]), n && n(o);
   }, W = () => {
     if (!N && !V) return null;
     const t = () => {
@@ -78,7 +78,7 @@ const ye = (n) => {
       }
     );
   }, X = (t, e) => {
-    const l = t[a.key || ""] || "", u = t[a.value || ""] || "", ee = s instanceof Array ? s[e]?.[l] : s, te = s instanceof Array ? s[e]?.[u] : s, K = $(e, a.key || ""), O = $(e, a.value || "");
+    const l = t[a.key || ""] || "", i = t[a.value || ""] || "", ee = s instanceof Array ? s[e]?.[l] : s, te = s instanceof Array ? s[e]?.[i] : s, K = $(e, a.key || ""), O = $(e, a.value || "");
     let L = "multi-box-content-item-input";
     return (K.error || O.error) && (L += " multi-box-content-item-input-error"), /* @__PURE__ */ r.jsxs("div", { className: L, children: [
       /* @__PURE__ */ r.jsx(
@@ -104,12 +104,12 @@ const ye = (n) => {
           size: f,
           disabled: te,
           placeholder: R,
-          value: u,
+          value: i,
           ...O,
           onChange: A(a.value || "", e),
           fetchSuggestions: g ? E("value") : void 0,
           onSelect: F(a.value || "", e),
-          ...T && T(e, u)
+          ...T && T(e, i)
         }
       )
     ] });
@@ -133,7 +133,12 @@ const ye = (n) => {
   )) }), E = (t) => (e, l) => {
     t === "key" ? j && j(e, l) : g && g(e, l);
   }, F = (t, e) => (l) => {
-    typeof l == "object" && l !== null ? o[e][t] = l.value : o[e][t] = l, n.value === void 0 && c([...o]), i && i(o);
+    if (typeof l == "object" && l !== null) {
+      const i = l.value;
+      o[e][t] = i;
+    } else
+      o[e][t] = l;
+    u.value === void 0 && c([...o]), n && n(o);
   }, Z = () => {
     let t = `${m}-multi-box multi-box`;
     return C && (t += ` ${C}`), f && (t += ` ${m}-multi-box-${f}`), z && (t += ` ${m}-multi-box-error`), s === !0 && (t += ` ${m}-multi-box-disabled`), b && (t += ` ${m}-multi-box-separator`), t;