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

package/lib/Modal/index.d.ts

@@ -1,12 +1,33 @@
 import { default as React, ReactNode } from 'react';
 import { ButtonProps } from '../Button';
 import { Confirm, ConfirmObject } from './Confirm';
+import { ModalDismissReason } from './interface';
 type ModalSize = 'sm' | 'md' | 'lg' | 'auto' | 'fullScreen';
+/**
+ * Modal onClose 关闭路径标识(R6 §B3 阶段 1 引入,见 BREAKING-CHANGES §B3 + discussions/Modal-unified-onClose.md)
+ * - 'cancel' = 取消按钮
+ * - 'ok' = 确定按钮
+ * - 'esc' = 键盘 Escape 关闭(若 keyboard 启用)
+ * - 'mask' = 蒙层点击关闭(若 maskClosable 启用)
+ * - 'x' = 右上角 X 按钮
+ */
+export type ModalCloseReason = 'cancel' | 'ok' | 'esc' | 'mask' | 'x';
 export interface ModalProps {
-    /** 对话框是否可见 */
+    /**
+     * @deprecated v5.x.next 改用 `open`（命名对齐业界 antd5/Chakra/Radix/MUI）；v6.0 移除 visible prop + fallback。详见 BREAKING-CHANGES §B-Modal-props-rework 子条 #3-A
+     * `open` 的旧别名；与 open 二选一即可，新代码推荐用 open
+     */
     visible?: boolean;
     /** 打开 */
     open?: boolean;
+    /**
+     * **(v5.x.next 议题 #2 引入)** 非受控模式初始 open 值。
+     * 未传 `open`（且未传 `visible`）时启用非受控 — Modal 内部维护 open state，
+     * 关闭路径自动 setOpen(false)，业务方不需要手动管理 open state。
+     * 与 React `<input defaultValue>` 惯例一致。
+     * 同时传 open + defaultOpen → open 优先（受控模式），dev warn 提示。
+     */
+    defaultOpen?: boolean;
     /** 确定按钮 loading */
     confirmLoading?: boolean;
     /** 标题 */
@@ -27,10 +48,59 @@ export interface ModalProps {
     showCancel?: boolean;
     /** 是否显示右上角的关闭按钮 */
     closable?: boolean;
-    /** 点击确定回调 */
+    /**
+     * @deprecated v5.x.next 改用 `onSubmit`（语义更清晰:submit 比 ok 更准确表达"确认提交"行为，对齐表单语义）；v6.0 移除 onOk。详见 BREAKING-CHANGES §B-Modal-props-rework
+     * 点击确定回调（旧名）
+     */
     onOk?: (e?: React.MouseEvent<HTMLElement>) => void;
-    /** 点击模态框右上角叉、取消按钮,return false 不关闭 */
+    /**
+     * **(v5.x.next 议题 #M1 引入)** 点击确定回调（推荐新 API,语义清晰）。
+     * 与 `onOk` 同义但 submit 比 ok 更准确表达"确认提交"行为。同时传 `onOk + onSubmit` → `onSubmit` 优先调用,`onOk` 跳过(避免业务函数重复触发)；
+     * 仅传 `onOk` → 旧行为不变(onOk 仍触发)。dev 环境若检测到只传 `onOk` 会 console.warn 1 次提示迁移。
+     */
+    onSubmit?: (e?: React.MouseEvent<HTMLElement>) => void | Promise<void>;
+    /**
+     * 取消按钮回调(v5.x.next 起为主职责)。
+     *
+     * **v5.0.0-beta.14(v5.x.next-fix)起兼容性约定**:
+     * - 显式传 `onDismiss` → 仅取消按钮触发 onCancel,X / ESC / mask 走 onDismiss(γ 单触发)
+     * - 显式传 `onClose` → R6 双触发:onCancel + onClose(legacy)
+     * - **未传 onDismiss / onClose**(v4 写法) → onCancel 仍 fallback 兜底 X / ESC / mask 三路;
+     *   **dev 环境抛 Error 强制业务方迁移到 onDismiss(prod 仍 fallback 不影响线上)**。
+     *
+     * v6.0(2026 Q3)起 fallback 兜底移除 — 只用 onCancel 接 X / ESC / mask 的写法运行时静默失效。
+     * 详见 BREAKING-CHANGES §B-Modal-props-rework 子条 #5。
+     */
     onCancel?: (e?: React.MouseEvent<HTMLElement>) => boolean | void;
+    /**
+     * @deprecated v5.x.next 改用 onDismiss（X/ESC/mask）+ onOk（确定）+ onCancel（取消）三回调职责互斥；v6.0 移除 onClose。详见 BREAKING-CHANGES §B-Modal-props-rework
+     *
+     * **(R6 §B3 阶段 1 引入)** 任意路径关闭都触发的统一回调,reason 区分关闭来源(`'cancel' | 'ok' | 'esc' | 'mask' | 'x'`)。
+     *
+     * 与 onCancel/onOk 共存(阶段 3 v6 移除单独 onCancel/onOk → BREAKING):
+     * - 取消按钮关闭 → 同时调 onCancel + onClose('cancel')
+     * - 确定按钮关闭 → 同时调 onOk + onClose('ok')
+     * - ESC 关闭 → 同时调 onCancel + onClose('esc')
+     * - 蒙层关闭 → 同时调 onCancel + onClose('mask')
+     * - X 按钮关闭 → 同时调 onCancel + onClose('x')
+     *
+     * 推荐写法 — 业务方在 onClose 里统一 setOpen(false) + reason 分支(埋点 / 重置 state 等),不再写双绑 `onCancel={fn} onOk={fn}` 兜底。
+     * 详见 BREAKING-CHANGES §B3 + discussions/Modal-unified-onClose.md
+     */
+    onClose?: (reason: ModalCloseReason) => void;
+    /**
+     * **(v5.x.next γ 方案 议题 #1 引入)** 非按钮关闭路径（X / ESC / 蒙层）的专用回调。
+     * 职责显式互斥：
+     * - onOk = 仅确定按钮
+     * - onCancel = 仅取消按钮
+     * - onDismiss = 仅 X / ESC / mask 三种"非按钮关闭"
+     *
+     * 仅传 onDismiss（不传 onClose）→ 新单触发行为：3 个非按钮路径仅调 onDismiss，不双触发。
+     * 同时传 onClose（无论是否也传 onDismiss）→ 旧兼容行为：维持 R6 双触发（onCancel + onClose）。
+     * 迁移时推荐：删 onClose，改用 onDismiss（理由见 discussions/Modal-props-rework.md §3.1）。
+     * 详见 BREAKING-CHANGES §B-Modal-props-rework。
+     */
+    onDismiss?: (reason: ModalDismissReason) => void;
     afterClose?: () => void;
     /** 大小 */
     size?: ModalSize;
@@ -40,13 +110,20 @@ export interface ModalProps {
     width?: string | number;
     /** 确认按钮文字 */
     okText?: ReactNode;
-    /** 确认按钮类型 */
-    okType?: string;
     /** 取消按钮文字 */
     cancelText?: ReactNode;
     /** 点击蒙层是否允许关闭 */
     maskClosable?: boolean;
+    /**
+     * @deprecated v5.x.next 改用 `closeOnBackdrop`(正向命名,业界对齐 antd `maskClosable` / chakra `closeOnOverlayClick`);v6 移除。
+     * 默认 `true`(即默认禁用蒙层关闭),与多数 Modal 库默认开放的直觉相反。详见 BREAKING-CHANGES §B6。
+     */
     disableBackdropClick?: boolean;
+    /**
+     * **(R6 §B6 阶段 1 引入)** 是否允许蒙层点击关闭(正向命名,业界对齐)。显式传值优先 — 未传时 fallback 旧 `disableBackdropClick`(默认 true 即禁用)。
+     * 阶段 3 v6 移除 `disableBackdropClick` 后默认 `true`(允许蒙层关闭)。详见 BREAKING-CHANGES §B6
+     */
+    closeOnBackdrop?: boolean;
     /** 强制渲染 Modal */
     forceRender?: boolean;
     /** 确定按钮属性 */
@@ -73,7 +150,21 @@ export interface ModalProps {
     mask?: boolean;
     /** 是否支持键盘esc关闭 */
     keyboard?: boolean;
+    /**
+     * @deprecated v5.x.next 改用 `closeOnEsc`(正向命名,业界对齐 antd `keyboard` / chakra `closeOnEsc`);v6 移除。
+     * 默认 `true`(即默认禁用 ESC 关闭),与多数 Modal 库默认开放的直觉相反。详见 BREAKING-CHANGES §B6。
+     */
     disableEscapeKeyDown?: boolean;
+    /**
+     * **(R6 §B6 阶段 1 引入)** 是否允许 Escape 键关闭(正向命名,业界对齐)。显式传值优先 — 未传时 fallback 旧 `disableEscapeKeyDown`(默认 true 即禁用)。
+     * 阶段 3 v6 移除 `disableEscapeKeyDown` 后默认 `true`(允许 ESC 关闭)。详见 BREAKING-CHANGES §B6
+     */
+    closeOnEsc?: boolean;
+    /**
+     * **(R6 §B6 阶段 1 引入)** 关闭后是否将焦点恢复到原触发元素(正向命名,业界对齐 mui `restoreFocus`)。等价 `focusTriggerAfterClose` 的正向 alias — 显式传值优先,未传时 fallback `focusTriggerAfterClose`(默认 true)。
+     * 注:`disableEnforceFocus` 仅 component.json/api.ts 文档层警示词,src 实际控制由 `focusTriggerAfterClose` 反向承担;v6 路径只保留 `restoreFocusOnClose`。详见 BREAKING-CHANGES §B6
+     */
+    restoreFocusOnClose?: boolean;
     /** 右上角关闭图标 */
     closeIcon?: ReactNode;
     /** 自定义渲染对话框 */
@@ -90,7 +181,7 @@ export interface ModalProps {
     contentHeight?: number | string;
     /** 内容样式 */
     contentStyle?: React.CSSProperties;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export declare const Modal: React.FC<ModalProps>;
 export { Confirm };

package/lib/Modal/index.js

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

package/lib/Modal/interface.d.ts

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

package/lib/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/lib/MultiBox/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const r=require("../_virtual/jsx-runtime.js"),x=require("react"),B=require("../TextField/index.js"),se=require("../Label/index.js"),re=require("../HelperText/index.js"),le=require("../node_modules/@para-ui/icons/Delete/index.js"),oe=require("../node_modules/@para-ui/icons/PlusCircleF/index.js"),f=require("../GlobalContext/constant.js"),ie=require("../GlobalContext/useFormatMessage.js"),ae=require("./lang/index.js"),ne=require("../Tooltip/index.js");;/* empty css            */const O=n=>{const{className:y,style:K,size:m="large",placeholderKey:P="",placeholderValue:L="",label:C="",labelTooltip:p,labelSign:R,disabled:o=!1,disabledTooltip:b,required:D=!1,error:I=!1,hideErrorDom:z,separator:h=":",helperText:d="",value:j,replaceFields:v,onChange:a,fetchSuggestionsKey:E,fetchSuggestionsValue:g,keyOtherProps:N,valueOtherProps:$}=n,T=!!(d&&typeof d=="string"),H=d instanceof Array,w=ie.default("MultiBox",ae.default),[l,c]=x.useState([]),[i,G]=x.useState({key:"label",value:"value"});x.useEffect(()=>{n.defaultValue!==void 0&&c([...n.defaultValue])},[]),x.useEffect(()=>{j!==void 0&&c([...j])},[j]),x.useEffect(()=>{if(v){const t={...i,...v};G(t)}},[v]);const q=(t,e)=>{let s={error:!1,helperText:""};if(H){const u=d[t];u&&u[e]&&(s={error:!0,helperText:u[e]})}return s},J=()=>{o!==!0&&(l.push({}),n.value===void 0&&c([...l]),a&&a(l))},Q=t=>()=>{o!==!0&&(l.splice(t,1),n.value===void 0&&c([...l]),a&&a(l))},S=(t,e)=>s=>{l[e][t]=s.target.value,n.value===void 0&&c([...l]),a&&a(l)},U=()=>{if(!C&&!R)return null;const t=()=>{let e="multi-box-label";return p&&p.className&&(e+=` ${p.className}`),e};return r.jsxRuntimeExports.jsx(se.default,{label:C,required:D,labelSign:R,...p,className:t()})},W=(t,e)=>{const s=t[i.key||""]||"",u=t[i.value||""]||"",ee=o instanceof Array?o[e]?.[s]:o,te=o instanceof Array?o[e]?.[u]:o,A=q(e,i.key||""),M=q(e,i.value||"");let _="multi-box-content-item-input";return(A.error||M.error)&&(_+=" multi-box-content-item-input-error"),r.jsxRuntimeExports.jsxs("div",{className:_,children:[r.jsxRuntimeExports.jsx(B.TextField,{className:"multi-box-text-field",size:m,disabled:ee,placeholder:P,value:s,...A,onChange:S(i.key||"",e),fetchSuggestions:E?V("key"):void 0,onSelect:k(i.key||"",e),...N&&N(e,s)}),h&&r.jsxRuntimeExports.jsx("span",{className:"multi-box-separator",children:h}),r.jsxRuntimeExports.jsx(B.TextField,{className:"multi-box-text-field",size:m,disabled:te,placeholder:L,value:u,...M,onChange:S(i.value||"",e),fetchSuggestions:g?V("value"):void 0,onSelect:k(i.value||"",e),...$&&$(e,u)})]})},X=()=>r.jsxRuntimeExports.jsx("div",{className:"multi-box-content",children:l.map((t,e)=>r.jsxRuntimeExports.jsxs("div",{className:"multi-box-content-item",children:[W(t,e),o!==!0&&r.jsxRuntimeExports.jsx("div",{className:"opera-box",children:r.jsxRuntimeExports.jsx("span",{className:"del-box",onClick:Q(e),children:r.jsxRuntimeExports.jsx(le.Delete,{})})})]},e))}),V=t=>(e,s)=>{t==="key"?E&&E(e,s):g&&g(e,s)},k=(t,e)=>s=>{typeof s=="object"&&s!==null?l[e][t]=s.value:l[e][t]=s,n.value===void 0&&c([...l]),a&&a(l)},Y=()=>{let t=`${f.$prefixCls}-multi-box multi-box`;return y&&(t+=` ${y}`),m&&(t+=` ${f.$prefixCls}-multi-box-${m}`),I&&(t+=` ${f.$prefixCls}-multi-box-error`),o===!0&&(t+=` ${f.$prefixCls}-multi-box-disabled`),h&&(t+=` ${f.$prefixCls}-multi-box-separator`),t},F=()=>r.jsxRuntimeExports.jsxs("div",{className:"multi-box-add",onClick:J,children:[r.jsxRuntimeExports.jsx(oe.PlusCircleF,{}),r.jsxRuntimeExports.jsx("span",{children:w({id:"add"})})]}),Z=()=>b?r.jsxRuntimeExports.jsx(ne.Tooltip,{disabled:!0,placement:b.placement||"top",...b,children:F()}):F();return r.jsxRuntimeExports.jsxs("div",{className:Y(),style:K,children:[U(),X(),Z(),r.jsxRuntimeExports.jsx(re.default,{className:"multi-box-error-text",error:T,helperText:T?d:void 0,hideErrorDom:z})]})};exports.MultiBox=O;exports.default=O;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const r=require("../_virtual/jsx-runtime.js"),x=require("react"),B=require("../TextField/index.js"),se=require("../Label/index.js"),re=require("../HelperText/index.js"),le=require("../node_modules/@para-ui/icons/Delete/index.js"),oe=require("../node_modules/@para-ui/icons/PlusCircleF/index.js"),m=require("../GlobalContext/constant.js"),ie=require("../GlobalContext/useFormatMessage.js"),ae=require("./lang/index.js"),ne=require("../Tooltip/index.js");;/* empty css            */const O=u=>{const{className:y,style:K,size:f="large",placeholderKey:P="",placeholderValue:L="",label:C="",labelTooltip:p,labelSign:R,disabled:o=!1,disabledTooltip:b,required:D=!1,error:I=!1,hideErrorDom:z,separator:h=":",helperText:d="",value:j,replaceFields:v,onChange:n,fetchSuggestionsKey:E,fetchSuggestionsValue:g,keyOtherProps:N,valueOtherProps:$}=u,T=!!(d&&typeof d=="string"),H=d instanceof Array,w=ie.default("MultiBox",ae.default),[l,c]=x.useState([]),[i,G]=x.useState({key:"label",value:"value"});x.useEffect(()=>{u.defaultValue!==void 0&&c([...u.defaultValue])},[]),x.useEffect(()=>{j!==void 0&&c([...j])},[j]),x.useEffect(()=>{if(v){const t={...i,...v};G(t)}},[v]);const q=(t,e)=>{let s={error:!1,helperText:""};if(H){const a=d[t];a&&a[e]&&(s={error:!0,helperText:a[e]})}return s},J=()=>{o!==!0&&(l.push({}),u.value===void 0&&c([...l]),n&&n(l))},Q=t=>()=>{o!==!0&&(l.splice(t,1),u.value===void 0&&c([...l]),n&&n(l))},S=(t,e)=>s=>{l[e][t]=s.target.value,u.value===void 0&&c([...l]),n&&n(l)},U=()=>{if(!C&&!R)return null;const t=()=>{let e="multi-box-label";return p&&p.className&&(e+=` ${p.className}`),e};return r.jsxRuntimeExports.jsx(se.default,{label:C,required:D,labelSign:R,...p,className:t()})},W=(t,e)=>{const s=t[i.key||""]||"",a=t[i.value||""]||"",ee=o instanceof Array?o[e]?.[s]:o,te=o instanceof Array?o[e]?.[a]:o,A=q(e,i.key||""),M=q(e,i.value||"");let _="multi-box-content-item-input";return(A.error||M.error)&&(_+=" multi-box-content-item-input-error"),r.jsxRuntimeExports.jsxs("div",{className:_,children:[r.jsxRuntimeExports.jsx(B.TextField,{className:"multi-box-text-field",size:f,disabled:ee,placeholder:P,value:s,...A,onChange:S(i.key||"",e),fetchSuggestions:E?V("key"):void 0,onSelect:k(i.key||"",e),...N&&N(e,s)}),h&&r.jsxRuntimeExports.jsx("span",{className:"multi-box-separator",children:h}),r.jsxRuntimeExports.jsx(B.TextField,{className:"multi-box-text-field",size:f,disabled:te,placeholder:L,value:a,...M,onChange:S(i.value||"",e),fetchSuggestions:g?V("value"):void 0,onSelect:k(i.value||"",e),...$&&$(e,a)})]})},X=()=>r.jsxRuntimeExports.jsx("div",{className:"multi-box-content",children:l.map((t,e)=>r.jsxRuntimeExports.jsxs("div",{className:"multi-box-content-item",children:[W(t,e),o!==!0&&r.jsxRuntimeExports.jsx("div",{className:"opera-box",children:r.jsxRuntimeExports.jsx("span",{className:"del-box",onClick:Q(e),children:r.jsxRuntimeExports.jsx(le.Delete,{})})})]},e))}),V=t=>(e,s)=>{t==="key"?E&&E(e,s):g&&g(e,s)},k=(t,e)=>s=>{if(typeof s=="object"&&s!==null){const a=s.value;l[e][t]=a}else l[e][t]=s;u.value===void 0&&c([...l]),n&&n(l)},Y=()=>{let t=`${m.$prefixCls}-multi-box multi-box`;return y&&(t+=` ${y}`),f&&(t+=` ${m.$prefixCls}-multi-box-${f}`),I&&(t+=` ${m.$prefixCls}-multi-box-error`),o===!0&&(t+=` ${m.$prefixCls}-multi-box-disabled`),h&&(t+=` ${m.$prefixCls}-multi-box-separator`),t},F=()=>r.jsxRuntimeExports.jsxs("div",{className:"multi-box-add",onClick:J,children:[r.jsxRuntimeExports.jsx(oe.PlusCircleF,{}),r.jsxRuntimeExports.jsx("span",{children:w({id:"add"})})]}),Z=()=>b?r.jsxRuntimeExports.jsx(ne.Tooltip,{disabled:!0,placement:b.placement||"top",...b,children:F()}):F();return r.jsxRuntimeExports.jsxs("div",{className:Y(),style:K,children:[U(),X(),Z(),r.jsxRuntimeExports.jsx(re.default,{className:"multi-box-error-text",error:T,helperText:T?d:void 0,hideErrorDom:z})]})};exports.MultiBox=O;exports.default=O;
 //# sourceMappingURL=index.js.map

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