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

package/lib/Anchor/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const s=require("../_virtual/jsx-runtime.js"),n=require("react"),y=require("clsx"),S=require("../GlobalContext/constant.js"),Q=require("./anchorMenu/index.js"),B=require("../node_modules/@para-ui/icons/ToRight/index.js"),F=require("../node_modules/@para-ui/icons/ToLeft/index.js"),U=require("../node_modules/@para-ui/icons/PreviewOpen/index.js"),X=require("../Search/index.js"),Y=require("../GlobalContext/useFormatMessage.js"),Z=require("./lang/index.js"),_=require("@paraview/lib");;/* empty css            */const ee=q=>{const{style:W,className:z,title:E="",scrollId:R=`${S.$prefixCls}-anchor-scroll-id`,list:d=[],listClassName:I,scrollClassName:D,placement:i="right",allExpanded:G=!0,search:H=!1,customPrefixIcon:$,listWidth:p}=q,J=Y.default("Anchor",Z.default),[C,L]=n.useState(""),[m,K]=n.useState(!1),[h,g]=n.useState({}),[T,M]=n.useState(!1),[N,O]=n.useState(""),[f,v]=n.useState(null),o=n.useRef({currentAnchorId:"",anchorList:d,anchorMap:{},searchValue:"",scrolling:!1}),V=T?"50px":p?`${p+20}px`:"160px";n.useEffect(()=>{o.current.anchorList=d;const e={};let r=!1;const c=(x,a="")=>{x.forEach(t=>{(t?.expanded===void 0||t?.expanded===null)&&(t.expanded=!1),a&&(t.parentId=a),e[t.id]=t,t.children&&(r=!0,c(t.children,t.id))})};c(d),K(r),o.current.anchorMap=e,g(e)},[d]),n.useEffect(()=>{const e=document.getElementById(R),r=_.throttle(async()=>{if(o.current.scrolling)return;const c=e?.querySelectorAll("[id]")||[],a=Array.from(c).map(l=>({id:l.id,offsetTop:l.offsetTop-(e?.offsetTop||0)}));let t=0,u="";const A=a.find(l=>(t<l.offsetTop&&(t=l.offsetTop,u=l.id),l.offsetTop>=(e?.scrollTop||0)));if(A?.id!==o.current.currentAnchorId){let l=A?.id||"";e?.scrollTop&&!A?.id&&(l=u),L(l)}},300);return r(),e?.addEventListener("scroll",r,{passive:!0}),()=>{e?.addEventListener("scroll",r)}},[]);const k=e=>{const r=document.getElementById(R),c=r?.querySelectorAll("[id]")||[],x=Array.from(c).findIndex(t=>String(t.id)===String(e)),a=c[x];a&&(L(e),o.current.currentAnchorId=e,o.current.scrolling=!0,setTimeout(()=>{o.current.scrolling=!1},1e3),r?.scrollTo({top:a?.offsetTop||0-(r?.offsetTop||0),behavior:"smooth"}))},b=()=>{Object.keys(h).forEach(e=>{h[e].expanded=!0}),g({...h})},j=n.useMemo(()=>_.debounce(async()=>{const e=o.current.searchValue;if(!e){v(null);return}const r=o.current.anchorList||[],c=[],x=(a,t="")=>{a.forEach(u=>{u?.name?.indexOf(e)>-1&&c.push(u),u.children&&x(u.children,u.id)})};x(r),v(c)},200),[]),w=n.useMemo(()=>E?s.jsxRuntimeExports.jsxs(s.jsxRuntimeExports.Fragment,{children:[s.jsxRuntimeExports.jsxs("div",{className:"anchor-menu-title",children:[s.jsxRuntimeExports.jsx("div",{className:"title",children:E}),s.jsxRuntimeExports.jsxs("div",{className:"opera-area",children:[m&&G&&s.jsxRuntimeExports.jsxs(s.jsxRuntimeExports.Fragment,{children:[s.jsxRuntimeExports.jsx(U.PreviewOpen,{onClick:b}),s.jsxRuntimeExports.jsx("div",{className:"split-line"})]}),s.jsxRuntimeExports.jsx("div",{onClick:()=>M(!0),children:i==="left"?s.jsxRuntimeExports.jsx(F.ToLeft,{}):s.jsxRuntimeExports.jsx(B.ToRight,{})})]})]}),H&&s.jsxRuntimeExports.jsx(X.Search,{size:"small",value:N,onChange:e=>{O(e),o.current.searchValue=e,j()},onClickRightIcon:j,onEnter:j,onClear:()=>{O(""),o.current.searchValue="",v(null)},placeholder:J("pleaseEnter"),style:{padding:"0 4px",marginBottom:"6px"}})]}):null,[E,m,N,b,j]),P=n.useMemo(()=>{if(!d?.length)return null;if(T)return s.jsxRuntimeExports.jsx("div",{className:"collapse-icon-area",onClick:()=>M(!1),children:i==="left"?s.jsxRuntimeExports.jsx(B.ToRight,{}):s.jsxRuntimeExports.jsx(F.ToLeft,{})});const e=f||d;return s.jsxRuntimeExports.jsxs("div",{className:y("anchor-menu-list",I),style:{width:p?`${p}px`:"140px"},children:[w,e.map((r,c)=>s.jsxRuntimeExports.jsx(Q.default,{data:r,currentAnchorId:C,handleClick:k,isTree:f?!1:m,anchorMap:h,setAnchorMap:g,customPrefixIcon:$,onlyOneLevel:!!f},r?.id))]})},[d,C,I,k,m,w,h,$,T,f]);return s.jsxRuntimeExports.jsxs("div",{className:y(`${S.$prefixCls}-anchor`,z,{[`${S.$prefixCls}-anchor-${i}`]:i}),style:W,children:[i==="left"&&P,s.jsxRuntimeExports.jsx("div",{id:R,className:y("anchor-scroll",D),style:{paddingLeft:i==="left"?V:"0",paddingRight:i==="right"?V:"0"},children:q.children}),i==="right"&&P]})};exports.default=ee;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const s=require("../_virtual/jsx-runtime.js"),n=require("react"),y=require("clsx"),S=require("../GlobalContext/constant.js"),U=require("./anchorMenu/index.js"),F=require("../node_modules/@para-ui/icons/ToRight/index.js"),_=require("../node_modules/@para-ui/icons/ToLeft/index.js"),X=require("../node_modules/@para-ui/icons/PreviewOpen/index.js"),Y=require("../Search/index.js"),Z=require("../GlobalContext/useFormatMessage.js"),ee=require("./lang/index.js"),D=require("@snack-kit/lib");;/* empty css            */const se=q=>{const{style:W,className:z,title:E="",scrollId:R=`${S.$prefixCls}-anchor-scroll-id`,list:d=[],listClassName:I,scrollClassName:G,placement:i="right",allExpanded:H=!0,search:J=!1,customPrefixIcon:C,listWidth:p}=q,K=Z.default("Anchor",ee.default),[L,M]=n.useState(""),[m,Q]=n.useState(!1),[h,g]=n.useState({}),[T,$]=n.useState(!1),[N,O]=n.useState(""),[f,v]=n.useState(null),o=n.useRef({currentAnchorId:"",anchorList:d,anchorMap:{},searchValue:"",scrolling:!1}),V=T?"50px":p?`${p+20}px`:"160px";n.useEffect(()=>{o.current.anchorList=d;const e={};let r=!1;const c=(x,l="")=>{x.forEach(t=>{(t?.expanded===void 0||t?.expanded===null)&&(t.expanded=!1),l&&(t.parentId=l),e[t.id]=t,t.children&&(r=!0,c(t.children,t.id))})};c(d),Q(r),o.current.anchorMap=e,g(e)},[d]),n.useEffect(()=>{const e=document.getElementById(R),r=D.Throttle(async()=>{if(o.current.scrolling)return;const c=e?.querySelectorAll("[id]")||[],l=Array.from(c).map(a=>{const B=a;return{id:B.id,offsetTop:B.offsetTop-(e?.offsetTop||0)}});let t=0,u="";const A=l.find(a=>(t<a.offsetTop&&(t=a.offsetTop,u=a.id),a.offsetTop>=(e?.scrollTop||0)));if(A?.id!==o.current.currentAnchorId){let a=A?.id||"";e?.scrollTop&&!A?.id&&(a=u),M(a)}},300);return r(),e?.addEventListener("scroll",r,{passive:!0}),()=>{e?.addEventListener("scroll",r)}},[]);const b=e=>{const r=document.getElementById(R),c=r?.querySelectorAll("[id]")||[],x=Array.from(c).findIndex(t=>String(t.id)===String(e)),l=c[x];l&&(M(e),o.current.currentAnchorId=e,o.current.scrolling=!0,setTimeout(()=>{o.current.scrolling=!1},1e3),r?.scrollTo({top:l?.offsetTop||0-(r?.offsetTop||0),behavior:"smooth"}))},k=()=>{Object.keys(h).forEach(e=>{h[e].expanded=!0}),g({...h})},j=n.useMemo(()=>D.Debounce(async()=>{const e=o.current.searchValue;if(!e){v(null);return}const r=o.current.anchorList||[],c=[],x=(l,t="")=>{l.forEach(u=>{u?.name?.indexOf(e)>-1&&c.push(u),u.children&&x(u.children,u.id)})};x(r),v(c)},200),[]),w=n.useMemo(()=>E?s.jsxRuntimeExports.jsxs(s.jsxRuntimeExports.Fragment,{children:[s.jsxRuntimeExports.jsxs("div",{className:"anchor-menu-title",children:[s.jsxRuntimeExports.jsx("div",{className:"title",children:E}),s.jsxRuntimeExports.jsxs("div",{className:"opera-area",children:[m&&H&&s.jsxRuntimeExports.jsxs(s.jsxRuntimeExports.Fragment,{children:[s.jsxRuntimeExports.jsx(X.PreviewOpen,{onClick:k}),s.jsxRuntimeExports.jsx("div",{className:"split-line"})]}),s.jsxRuntimeExports.jsx("div",{onClick:()=>$(!0),children:i==="left"?s.jsxRuntimeExports.jsx(_.ToLeft,{}):s.jsxRuntimeExports.jsx(F.ToRight,{})})]})]}),J&&s.jsxRuntimeExports.jsx(Y.Search,{size:"small",value:N,onChange:e=>{O(e),o.current.searchValue=e,j()},onClickRightIcon:j,onEnter:j,onClear:()=>{O(""),o.current.searchValue="",v(null)},placeholder:K("pleaseEnter"),style:{padding:"0 4px",marginBottom:"6px"}})]}):null,[E,m,N,k,j]),P=n.useMemo(()=>{if(!d?.length)return null;if(T)return s.jsxRuntimeExports.jsx("div",{className:"collapse-icon-area",onClick:()=>$(!1),children:i==="left"?s.jsxRuntimeExports.jsx(F.ToRight,{}):s.jsxRuntimeExports.jsx(_.ToLeft,{})});const e=f||d;return s.jsxRuntimeExports.jsxs("div",{className:y("anchor-menu-list",I),style:{width:p?`${p}px`:"140px"},children:[w,e.map((r,c)=>s.jsxRuntimeExports.jsx(U.default,{data:r,currentAnchorId:L,handleClick:b,isTree:f?!1:m,anchorMap:h,setAnchorMap:g,customPrefixIcon:C,onlyOneLevel:!!f},r?.id))]})},[d,L,I,b,m,w,h,C,T,f]);return s.jsxRuntimeExports.jsxs("div",{className:y(`${S.$prefixCls}-anchor`,z,{[`${S.$prefixCls}-anchor-${i}`]:i}),style:W,children:[i==="left"&&P,s.jsxRuntimeExports.jsx("div",{id:R,className:y("anchor-scroll",G),style:{paddingLeft:i==="left"?V:"0",paddingRight:i==="right"?V:"0"},children:q.children}),i==="right"&&P]})};exports.default=se;
 //# sourceMappingURL=index.js.map

package/lib/Anchor/type.d.ts

@@ -18,8 +18,8 @@ export interface AnchorProps {
     style?: React.CSSProperties;
     /** 类名 */
     className?: string;
-    /** 标题 */
-    title?: string;
+    /** 标题(R6 §6 类型放宽:string → ReactNode,支持嵌入徽标/计数/动态状态文本;string 是 ReactNode 子集,完全向后兼容) */
+    title?: ReactNode;
     /** 滚动盒子Id */
     scrollId?: string;
     /** 子元素 */
@@ -31,8 +31,12 @@ export interface AnchorProps {
     /** 位置 */
     placement?: 'left' | 'right';
     /** 默认展示的锚点 */
-    /** 自定义前缀符号 */
-    customPrefixIcon?: ReactNode;
+    /**
+     * 自定义前缀符号(R6 §6 类型放宽):
+     * - 静态 ReactNode — 所有目录项共用同一前缀图标(原行为)
+     * - 函数形式 `(item, isActive) => ReactNode` — 按当前激活态返回不同 ReactNode(墨水点指示器等激活态联动场景);函数版本每次激活变化触发 list 重渲染,内部 AnchorListMemo 已优化
+     */
+    customPrefixIcon?: ReactNode | ((item: AnchorItem, isActive: boolean) => ReactNode);
     /** 全部展开功能是否开启 */
     allExpanded?: boolean;
     /** 是否带目录搜索 */

package/lib/Argv/component.json

@@ -0,0 +1,216 @@
+{
+    "name": "Argv",
+    "category": "Data Entry",
+    "description": "动态参数键值对编辑器。用户可以增删行、编辑每行的 key/value,value 支持多类型(string/number/boolean/object)。典型场景:命令行参数配置、环境变量编辑、动态配置项。**重要:这是一个'对象 ⇄ 列表'双形态组件,内部数据形态是 IArgvItem[],外部数据形态可以是对象(Record<string,any>)或列表(IArgvItem[]),通过两套不同的 prop 通道分别接入(见 controlledChannels)**",
+    "semantic": {
+        "intent": [
+            "动态键值对编辑",
+            "参数配置",
+            "可增删行的表单"
+        ],
+        "useCases": [
+            "命令行参数配置面板(CLI argv 编辑)",
+            "环境变量编辑器(KEY=VALUE 列表)",
+            "HTTP Header / Query 参数编辑",
+            "动态配置项编辑(配置中心场景)",
+            "脚本变量定义"
+        ],
+        "riskLevel": "normal"
+    },
+    "protocolSummary": "**双形态受控对**:外部可用 **对象形态**(defaultValue: Record<string,any> + onChange: (val: Record<string,any>) => void,**onChange 防抖 200ms**)或 **列表形态**(list: IArgvItem[] + onListChange: (val: IArgvItem[]) => void,**无防抖**)接入数据。defaultValue 仅 mount + 引用变化时灌入(不受控);list 是受控通道(每次变化都会被同步)。两套通道可同时存在(各自独立 fire)。**无 value/values prop,无 schema/argSchema prop——这是常见误解**",
+    "controlledChannels": {
+        "objectMode": {
+            "in": "defaultValue: Record<string, any>",
+            "out": "onChange: (val: Record<string, any>) => void",
+            "behavior": "**非受控**:defaultValue 引用变化时(useEffect 依赖)重置内部 state,父层 setState 后再传入相同引用不会重置。onChange 内部 200ms 防抖,返回值已经 formatDataToObject 转成普通对象(丢弃空 key 项)",
+            "whenToUse": "外部数据天然是对象(API 返回的 config 对象、env vars 对象),且不需要严格受控(用户编辑过程中父层不需要插队覆盖)"
+        },
+        "listMode": {
+            "in": "list: IArgvItem[]",
+            "out": "onListChange: (val: IArgvItem[]) => void",
+            "behavior": "**受控**:list 每次变化都会被同步进内部 state(useEffect 依赖 list 引用)。onListChange 无防抖,每次按键 / 增删行立即 fire,返回原始 IArgvItem[](保留空 key 项,保留类型元数据)",
+            "whenToUse": "需要保留输入过程中间态(空 key 行、未填值)、需要保留类型元数据(dataType=string/number/boolean/object)、或父层做严格受控(每次输入都过父层 reducer)"
+        },
+        "bothModes": "list 和 defaultValue 可以同时传(list 会覆盖 defaultValue 的初始化效果);onChange 和 onListChange 可同时监听,两个回调都会触发,**但 onChange 因防抖会延迟 200ms 且只回传对象形态**"
+    },
+    "dataFlow": {
+        "objectToList": "**formatObjectToData(obj: Record<string,any>): IArgvItem[]** — Object.keys 遍历, 每个 [k,v] 转换成 IArgvItem(自动推断 dataType: typeof v)。导出函数,可在父层提前调用",
+        "listToObject": "**formatDataToObject(list: IArgvItem[]): Record<string,any>** — 遍历 list, 跳过 item.key 为空的项, 用 item.key 作为对象 key, formatGeneratorToData 还原 value。导出函数",
+        "validate": "**checkArgvData(list: IArgvItem[], intl: Function): { error: boolean, detail: Record<string,string>[] }** — 校验每行 key 非空 + value 格式正确,返回的 detail 可以直接喂给 errors prop"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式(无 variant 切换,样式由 size/disabled 等控制)"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "error"
+    ],
+    "idealProps": {
+        "list": {
+            "type": "IArgvItem[]",
+            "description": "**受控形态的数据通道**。每项结构: `{ key: string, data: IDataGeneratorValue }`,其中 `IDataGeneratorValue = { dataType: 'string' | 'number' | 'boolean' | 'object', data: any }`。**与 onListChange 配对使用,无防抖**。如果同时传了 defaultValue,list 优先级更高(list 引用变化会覆盖)",
+            "shape": {
+                "key": "string — 参数名(显示在左侧 TextField)。允许空字符串,但 formatDataToObject 转对象时会被跳过",
+                "data": "IDataGeneratorValue — 参数值容器,含 dataType (类型选择器) + data (实际值,类型与 dataType 联动)"
+            }
+        },
+        "onListChange": {
+            "type": "(val: IArgvItem[]) => void",
+            "description": "**列表形态变化回调,无防抖**。每次按键 / 增删行 / 类型切换都立即触发。返回完整 IArgvItem[](保留空 key 项)。如果只想拿对象形态结果,用 onChange",
+            "pairsWith": "list"
+        },
+        "defaultValue": {
+            "type": "Record<string, any>",
+            "description": "**对象形态的初始值,非受控**。组件 mount 时 + 引用变化时(useEffect 依赖)灌入,父层用 setState 重新传相同引用不会重置(常见坑:误以为 defaultValue 是受控,见 commonMisconceptions.M1)。内部用 formatObjectToData 自动推断每个 value 的 dataType",
+            "controlled": false
+        },
+        "onChange": {
+            "type": "(val: Record<string, any>) => void",
+            "description": "**对象形态变化回调,内部 200ms 防抖**。返回值已经 formatDataToObject 转成普通对象(item.key 空的行被跳过, item.data 还原成对应 dataType 的原始值)。**适合保存到 state 但不适合做严格受控**(防抖期间输入和 state 不同步)",
+            "pairsWith": "defaultValue"
+        },
+        "errors": {
+            "type": "Record<string, string>[]",
+            "description": "**按 list 行索引对齐**(errors[0] 对应 list[0],以此类推)。**不是按 key 名映射**(常见误解,见 commonMisconceptions.M3)。每项结构 `{ key?: string, value?: string }`: `key` 字段填非空字符串时,该行左侧 TextField 红框 + 显示该字符串作为 helperText;`value` 字段填非空字符串时,该行右侧 DataGenerator 红框 + 显示该字符串。如不需要某行/某列显示错误就不填或填空字符串",
+            "shape": {
+                "[index].key": "string | undefined — 该行 key 列的错误文案(空字符串/undefined = 无错误)",
+                "[index].value": "string | undefined — 该行 value 列的错误文案"
+            },
+            "tip": "直接消费 checkArgvData(list, intl).detail 即可,无需手工拼装"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "**整体禁用**:禁用所有 TextField + DataGenerator,屏蔽新增按钮(点击 add 时 early return)、屏蔽删除按钮(点击 del 时 early return)。不存在子字段单独禁用——若需更细颗粒度,改用底层 TextField + DataGenerator 自行编排"
+        },
+        "label": {
+            "type": "LabelProps['label']",
+            "description": "顶部标题文本(string 或 ReactNode)。不传时显示 i18n 默认值('环境变量' / 'Environment Variable')。注意这是顶层 label,**不是每行的 label**(每行只有 key/value 两个 TextField,无独立 label 位)"
+        },
+        "labelProps": {
+            "type": "LabelProps",
+            "description": "传给顶部 Label 组件的完整 props(覆盖默认 label),用于调整 required / tooltip / labelWidth 等。`label` 字段会被外层 label prop 覆盖(外层优先)"
+        },
+        "className": {
+            "type": "string",
+            "description": "外层 div 的 className"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "外层 div 的 style"
+        }
+    },
+    "commonMisconceptions": {
+        "M1": {
+            "wrong": "把 defaultValue 当受控 prop 用: `<Argv defaultValue={state} onChange={setState} />` 期望父层 setState 后 Argv 内部跟着更新",
+            "result": "defaultValue 只在引用变化时灌入,父层 setState 后 React 重渲传入新引用确实会重置——但**正在编辑的行会被清空**(useEffect 重跑 formatObjectToData),导致用户输入丢失",
+            "fix": "需要严格受控就用 **list + onListChange**(列表形态、受控、无防抖);只需保存最终结果用 defaultValue + onChange(对象形态、非受控、防抖)。**不要混用**"
+        },
+        "M2": {
+            "wrong": "想给 Argv 传 schema / argSchema 限制可选 key 列表或字段类型: `<Argv schema={...} />`",
+            "result": "Argv **不存在 schema / argSchema prop**——传入会被 TypeScript 直接报错。Argv 是自由键值对编辑器,没有内置 schema 约束",
+            "fix": "需要约束 key 白名单:在父层 onListChange 里过滤;需要约束 value 类型:Argv 内部已有 DataGenerator 让用户选 dataType(string/number/boolean/object);需要强 schema(必填 + 正则等):换用 FieldForm + FieldForm.Item rules"
+        },
+        "M3": {
+            "wrong": "errors 按 key 名映射: `errors={{ username: '必填', email: '格式错' }}` (Record<string,string>)",
+            "result": "类型不匹配——errors 是 `Record<string, string>[]` 数组,**按 list 行索引对齐**,不是按字段名映射。传错形态会导致 errors[index] 取值为 undefined,所有行都不显示错误",
+            "fix": "用 `errors={[{key: '', value: '必填'}, {key: '重复', value: ''}]}` 或直接 `errors={checkArgvData(list, intl).detail}`(detail 已经是正确形态)"
+        },
+        "M4": {
+            "wrong": "想用 `value` / `values` prop 做受控: `<Argv value={data} onChange={setData} />`",
+            "result": "Argv **无 value 也无 values prop**——TypeScript 报错。常见的受控套路在 Argv 上不直接成立",
+            "fix": "Argv 的受控通道叫 **list + onListChange**(命名上 list 替代了 value 角色,IArgvItem[] 替代了 普通对象)。如果父层数据是普通对象,可以在父层用 formatObjectToData / formatDataToObject 工具函数转换"
+        },
+        "M5": {
+            "wrong": "同时监听 onChange 和 onListChange 并期望它们的回调时机一致",
+            "result": "**onListChange 立即触发,onChange 防抖 200ms**——按键过程中两个 callback 看到的数据可能短暂不一致,且 onChange 收到的是对象形态(过滤了空 key 项),onListChange 收到的是列表形态(保留全部)",
+            "fix": "通常只监听一个:严格受控用 onListChange,只关心最终对象结果用 onChange。如必须两个都监听,理解 200ms 时差是预期行为"
+        }
+    },
+    "completeExample": "// 标准用法:list 受控模式 + errors 校验\nimport React, { useState, useMemo } from 'react';\nimport Argv, { IArgvItem, checkArgvData } from '@para-ui/core/Argv';\nimport useFormatMessage from '@para-ui/core/GlobalContext/useFormatMessage';\n\nconst Demo: React.FC = () => {\n    const [list, setList] = useState<IArgvItem[]>([\n        { key: 'NODE_ENV', data: { dataType: 'string', data: 'production' } },\n        { key: 'PORT', data: { dataType: 'number', data: 3000 } },\n        { key: 'DEBUG', data: { dataType: 'boolean', data: false } }\n    ]);\n    const intl = useFormatMessage('Argv');\n    // 校验:返回 { error: boolean, detail: errors 形态 }\n    const validation = useMemo(() => checkArgvData(list, intl), [list, intl]);\n    return (\n        <div>\n            <Argv\n                label='环境变量配置'\n                list={list}\n                onListChange={setList}\n                errors={validation.detail}\n            />\n            <button disabled={validation.error}>保存</button>\n        </div>\n    );\n};\nexport default Demo;",
+    "utilities": {
+        "formatObjectToData": {
+            "import": "import { formatObjectToData } from '@para-ui/core/Argv';",
+            "signature": "(data: Record<string, any>) => IArgvItem[]",
+            "purpose": "把普通对象转成 IArgvItem[](自动推断 dataType)。父层有对象形态数据但想用 list 受控通道时用"
+        },
+        "formatDataToObject": {
+            "import": "import { formatDataToObject } from '@para-ui/core/Argv';",
+            "signature": "(data: IArgvItem[]) => Record<string, any>",
+            "purpose": "把 IArgvItem[] 转回普通对象(跳过空 key,还原 dataType)。保存到后端时用"
+        },
+        "checkArgvData": {
+            "import": "import { checkArgvData } from '@para-ui/core/Argv';",
+            "signature": "(data: IArgvItem[], intl: Function) => { error: boolean, detail: Record<string,string>[] }",
+            "purpose": "内置校验:每行 key 非空 + value 格式正确。detail 可以直接喂给 errors prop"
+        }
+    },
+    "do": [
+        "需要严格受控(中途插队 / 实时同步):用 **list + onListChange**(列表形态、无防抖)",
+        "只需保存最终结果到父层 state:用 **defaultValue + onChange**(对象形态、200ms 防抖)",
+        "errors 直接消费 **checkArgvData(list, intl).detail**,无需手工拼装",
+        "保存到后端前用 **formatDataToObject(list)** 转成对象形态",
+        "理解'对象 ⇄ 列表'两套通道是平级且独立的,不要混用"
+    ],
+    "dont": [
+        "**不要**给 Argv 传 schema / argSchema / value / values prop——这些都不存在(见 commonMisconceptions M2/M4)",
+        "**不要**把 defaultValue 当受控 prop 用——会导致编辑过程中数据被清空(M1)",
+        "**不要**按 key 名映射 errors——errors 按行索引对齐(M3)",
+        "**不要**期望 onChange 和 onListChange 时机一致——前者有 200ms 防抖(M5)",
+        "参数过多(>10 行)不分组用同一个 Argv——考虑分多个 Argv 或换 FieldForm"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(val: Record<string, any>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "对象形态回调，内部 200ms 防抖，适合保存到 state 但不适合严格受控",
+                "返回值已经 formatDataToObject 转换，跳过空 key 项，还原 dataType 原始值",
+                "async 场景可直接 await 包裹：const save = async (val) => { await api.save(val); setDirty(false); }"
+            ],
+            "commonMistakes": [
+                "期望 onChange 和 onListChange 在同一帧触发——onChange 有 200ms 防抖，onListChange 立即触发，两者不同步",
+                "期望 onChange 回传 IArgvItem[] 列表形态——onChange 返回普通对象 Record<string,any>，要列表形态用 onListChange",
+                "把 onChange 当受控 prop 配合 defaultValue 用——defaultValue 非受控，引用不变不触发重置，严格受控用 list+onListChange"
+            ]
+        },
+        "onListChange": {
+            "signature": "(val: IArgvItem[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "每次按键 / 增删行 / 类型切换立即触发，无防抖，适合严格受控场景",
+                "返回完整 IArgvItem[]（保留空 key 行），可直接回传给 list prop 实现受控循环",
+                "结合 checkArgvData 做实时校验：onListChange={val => { setList(val); setErrors(checkArgvData(val, intl).detail); }}"
+            ],
+            "commonMistakes": [
+                "期望 onListChange 返回对象形态——它返回 IArgvItem[]，要对象形态用 onChange 或 formatDataToObject",
+                "onListChange 频率比 onChange 高，如果 handler 有重计算逻辑应加 useMemo/useCallback 避免性能问题",
+                "同时传 list 和 defaultValue 但期望 onListChange 只触发一次——list 引用变化会触发，defaultValue 也会灌入，两套通道独立"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "errors prop 是按行索引对齐的数组，不是按 key 名映射的对象",
+            "wrong": "// 错误：按字段名映射\n<Argv errors={{ NODE_ENV: '必填', PORT: '格式错' }} />  // TS 类型报错：期望数组",
+            "right": "// 正确：按 list 行索引对齐\n<Argv errors={[{ key: '', value: '必填' }, { key: '重复', value: '' }]} />\n// 或直接消费 checkArgvData 结果\n<Argv errors={checkArgvData(list, intl).detail} />"
+        },
+        {
+            "issue": "Argv 无 value / values prop，受控通道叫 list + onListChange",
+            "wrong": "// antd/MUI 风格受控写法\n<Argv value={data} onChange={setData} />  // TS 报错：value 不在 ArgvProps",
+            "right": "// para-ui Argv 受控写法\n<Argv list={list} onListChange={setList} />"
+        },
+        {
+            "issue": "IArgvItem.data.dataType 是字符串联合类型，不能传任意字符串",
+            "wrong": "const item: IArgvItem = { key: 'PORT', data: { dataType: 'int', data: 3000 } };  // 'int' 不在联合类型",
+            "right": "const item: IArgvItem = { key: 'PORT', data: { dataType: 'number', data: 3000 } };  // 只有 'string'|'number'|'boolean'|'object'"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Argv",
+        "adapter": null
+    }
+}

package/lib/Argv/dataGenerator/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const n=require("../../_virtual/jsx-runtime.js"),u=require("react"),N=require("../../TextField/index.js"),M=require("../../Select/index.js"),y=require("./config.js"),D=require("../../node_modules/@para-ui/icons/ExpandPart/index.js"),w=require("../../InputNumber/index.js"),G=require("../../Modal/index.js"),I=require("../../Message/index.js"),_=require("../../GlobalContext/useFormatMessage.js"),O=require("../lang/index.js"),F=require("@paraview/lib");;/* empty css            */const J=e=>{const{defaultValue:i,value:t,disabled:o,onChange:d,error:p,helperText:f,placeholderTextField:T}=e,E=_.default("Argv",O.default),[s,x]=u.useState({dataType:"string",data:""}),[S,m]=u.useState(!1),[g,j]=u.useState(""),v=u.useRef({dataMapping:{...y.defaultInputValueMapping},uuid:F.UUID()});u.useEffect(()=>{i!==void 0&&x(i)},[]),u.useEffect(()=>{t!==void 0&&x(t)},[t]);const q=a=>{const r=a;if(r!==s.dataType){const h=v.current.dataMapping[r]??"",b={...s,dataType:r,data:h};x(b),d&&d(b)}},c=a=>{const r={...s,data:a};x(r),d&&d(r);const l=s.dataType,h=v.current.dataMapping;h[l]=a},C=u.useMemo(()=>{const{dataType:a,data:r}=s;if(a==="number"){const l=Number(r);return n.jsxRuntimeExports.jsx(w.InputNumber,{placeholder:T,disabled:o,className:"data-input",value:l,onChange:c,error:p,helperText:f})}return a==="boolean"?n.jsxRuntimeExports.jsx(M.default,{disabled:o,className:"data-input",list:y.booleanSelectList,value:r,onChange:c,error:p,helperText:f}):n.jsxRuntimeExports.jsx(N.TextField,{placeholder:T,className:"data-input",multiline:!0,value:r,rightIcon:n.jsxRuntimeExports.jsx(D.ExpandPart,{}),onClickIcon:()=>{m(!0),j(r)},onChange:l=>c(l.target.value),rows:1,resize:!1,error:p,helperText:f})},[s,c,p,f]),R=()=>{if(s.dataType==="string"&&(c(g),m(!1)),s.dataType==="object")try{const a=JSON.parse(g);c(g),m(!1)}catch{I.Message.warn(E("formatErrorJson"))}};return n.jsxRuntimeExports.jsxs("div",{className:"argv-data-generator",children:[n.jsxRuntimeExports.jsxs("div",{className:"data-generator-content",children:[n.jsxRuntimeExports.jsx(M.default,{disabled:o,className:"datatype-select",list:y.dataTypeSelectList,value:s?.dataType,onChange:q}),C]}),n.jsxRuntimeExports.jsx(G.Modal,{open:S,hideHeader:!0,size:"auto",onCancel:()=>m(!1),onOk:R,children:n.jsxRuntimeExports.jsx("div",{style:{width:"600px",height:"auto",paddingTop:"20px"},children:n.jsxRuntimeExports.jsx(N.TextField,{disabled:o,multiline:!0,rows:12,value:g||"",onChange:a=>j(a.target.value)})})})]})},V=e=>{const{dataType:i,data:t}=e;switch(i){case"number":return!isNaN(Number(t));case"boolean":return!0;case"string":return!0;case"object":try{return JSON.parse(t),!0}catch{return!1}default:return!1}},k=e=>{if(!e)return"";const{dataType:i,data:t}=e;switch(i){case"number":return Number(t);case"boolean":return!!t;case"string":return t;case"object":try{return JSON.parse(t)}catch{return{}}default:return t}},$=e=>typeof e=="number"?{dataType:"number",data:e}:typeof e=="boolean"?{dataType:"boolean",data:e}:typeof e=="string"?{dataType:"string",data:e}:typeof e=="object"?{dataType:"object",data:JSON.stringify(e)}:{dataType:"string",data:""};exports.checkGeneratorData=V;exports.default=J;exports.formatDataToGenerator=$;exports.formatGeneratorToData=k;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const n=require("../../_virtual/jsx-runtime.js"),u=require("react"),N=require("../../TextField/index.js"),M=require("../../Select/index.js"),y=require("./config.js"),D=require("../../node_modules/@para-ui/icons/ExpandPart/index.js"),w=require("../../InputNumber/index.js"),G=require("../../Modal/index.js"),I=require("../../Message/index.js"),_=require("../../GlobalContext/useFormatMessage.js"),O=require("../lang/index.js"),F=require("@snack-kit/lib");;/* empty css            */const J=e=>{const{defaultValue:i,value:t,disabled:o,onChange:d,error:p,helperText:f,placeholderTextField:T}=e,E=_.default("Argv",O.default),[s,x]=u.useState({dataType:"string",data:""}),[S,m]=u.useState(!1),[g,j]=u.useState(""),b=u.useRef({dataMapping:{...y.defaultInputValueMapping},uuid:F.UUID()});u.useEffect(()=>{i!==void 0&&x(i)},[]),u.useEffect(()=>{t!==void 0&&x(t)},[t]);const q=a=>{const r=a;if(r!==s.dataType){const h=b.current.dataMapping[r]??"",v={...s,dataType:r,data:h};x(v),d&&d(v)}},c=a=>{const r={...s,data:a};x(r),d&&d(r);const l=s.dataType,h=b.current.dataMapping;h[l]=a},C=u.useMemo(()=>{const{dataType:a,data:r}=s;if(a==="number"){const l=Number(r);return n.jsxRuntimeExports.jsx(w.InputNumber,{placeholder:T,disabled:o,className:"data-input",value:l,onChange:c,error:p,helperText:f})}return a==="boolean"?n.jsxRuntimeExports.jsx(M.default,{disabled:o,className:"data-input",list:y.booleanSelectList,value:r,onChange:c,error:p,helperText:f}):n.jsxRuntimeExports.jsx(N.TextField,{placeholder:T,className:"data-input",multiline:!0,value:r,rightIcon:n.jsxRuntimeExports.jsx(D.ExpandPart,{}),onClickIcon:()=>{m(!0),j(r)},onChange:l=>c(l.target.value),rows:1,resize:!1,error:p,helperText:f})},[s,c,p,f]),R=()=>{if(s.dataType==="string"&&(c(g),m(!1)),s.dataType==="object")try{const a=JSON.parse(g);c(g),m(!1)}catch{I.Message.warn(E("formatErrorJson"))}};return n.jsxRuntimeExports.jsxs("div",{className:"argv-data-generator",children:[n.jsxRuntimeExports.jsxs("div",{className:"data-generator-content",children:[n.jsxRuntimeExports.jsx(M.default,{disabled:o,className:"datatype-select",list:y.dataTypeSelectList,value:s?.dataType,onChange:q}),C]}),n.jsxRuntimeExports.jsx(G.Modal,{open:S,hideHeader:!0,size:"auto",onCancel:()=>m(!1),onOk:R,children:n.jsxRuntimeExports.jsx("div",{style:{width:"600px",height:"auto",paddingTop:"20px"},children:n.jsxRuntimeExports.jsx(N.TextField,{disabled:o,multiline:!0,rows:12,value:g||"",onChange:a=>j(a.target.value)})})})]})},V=e=>{const{dataType:i,data:t}=e;switch(i){case"number":return!isNaN(Number(t));case"boolean":return!0;case"string":return!0;case"object":try{return JSON.parse(t),!0}catch{return!1}default:return!1}},k=e=>{if(!e)return"";const{dataType:i,data:t}=e;switch(i){case"number":return Number(t);case"boolean":return!!t;case"string":return t;case"object":try{return JSON.parse(t)}catch{return{}}default:return t}},z=e=>typeof e=="number"?{dataType:"number",data:e}:typeof e=="boolean"?{dataType:"boolean",data:e}:typeof e=="string"?{dataType:"string",data:e}:typeof e=="object"?{dataType:"object",data:JSON.stringify(e)}:{dataType:"string",data:""};exports.checkGeneratorData=V;exports.default=J;exports.formatDataToGenerator=z;exports.formatGeneratorToData=k;
 //# sourceMappingURL=index.js.map

package/lib/Argv/index.d.ts

@@ -1,7 +1,6 @@
 import { default as React } from 'react';
 import { IDataGeneratorValue } from './dataGenerator';
 import { LabelProps } from '../Label';
-import { IObject } from '../Utils/type';
 export interface IArgvItem {
     key: string;
     data: IDataGeneratorValue;
@@ -14,11 +13,11 @@ export interface ArgvProps {
     /** 禁用 */
     disabled?: boolean;
     /** 默认值 不受控 */
-    defaultValue?: IObject;
+    defaultValue?: Record<string, unknown>;
     /** label */
     label?: LabelProps['label'];
     /** 改变值 */
-    onChange?: (val: IObject) => void;
+    onChange?: (val: Record<string, unknown>) => void;
     /** 格式化的列表 */
     list?: IArgvItem[];
     /** 改变值 */
@@ -30,6 +29,6 @@ export interface ArgvProps {
 }
 declare const Argv: (props: ArgvProps) => import("react/jsx-runtime").JSX.Element;
 export default Argv;
-export declare const formatObjectToData: (data: IObject) => IArgvItem[];
-export declare const formatDataToObject: (data: IArgvItem[]) => IObject;
-export declare const checkArgvData: (data: IArgvItem[], intl: Function) => Record<string, any>;
+export declare const formatObjectToData: (data: Record<string, unknown>) => IArgvItem[];
+export declare const formatDataToObject: (data: IArgvItem[]) => Record<string, unknown>;
+export declare const checkArgvData: (data: IArgvItem[], intl: Function) => Record<string, unknown>;

package/lib/Argv/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const e=require("../_virtual/jsx-runtime.js"),x=require("react"),S=require("clsx"),_=require("../GlobalContext/constant.js"),K=require("../GlobalContext/useFormatMessage.js"),J=require("@paraview/lib"),L=require("./lang/index.js"),P=require("./batchEdit/index.js"),j=require("./dataGenerator/index.js"),I=require("../Label/index.js"),B=require("../TextField/index.js"),U=require("../node_modules/@para-ui/icons/Delete/index.js"),w=require("../node_modules/@para-ui/icons/PlusCircleF/index.js"),N=require("../Utils/index.js");;/* empty css            */const z=i=>{const{style:u,className:n,defaultValue:a,disabled:c,label:f,labelProps:h,errors:g,onChange:m,list:l,onListChange:k}=i,p=K.default("Argv",L.default),[s,v]=x.useState([]),T={key:"",data:{dataType:"string",data:""}};x.useEffect(()=>{if(!a||!N.isObject(a)){v([]);return}v(C(a))},[a]),x.useEffect(()=>{l!==void 0&&v(l)},[l]);const $=x.useMemo(()=>J.debounce(async r=>{const t=O(r);m&&m(t)},200),[]),E=r=>{v(r),k&&k(r),$(r)},A=()=>{c||(s.push({...T}),E([...s]))},q=r=>{c||(s.splice(r,1),E([...s]))},b=(r,t,o)=>{s[t]||(s[t]={...T}),s[t]={...s[t],[o]:r},E([...s])},M=x.useMemo(()=>e.jsxRuntimeExports.jsx("div",{className:"argv-label",children:e.jsxRuntimeExports.jsx(I.default,{label:f||p("environmentVariable"),...h})}),[f,h]),F=x.useMemo(()=>s.map((t,o)=>{const d=g?.[o]??{},y=d?.key||"",D=d?.value||"";return e.jsxRuntimeExports.jsx("div",{children:e.jsxRuntimeExports.jsxs("div",{className:"argv-item",children:[e.jsxRuntimeExports.jsx("div",{className:"argv-key",children:e.jsxRuntimeExports.jsx(B.TextField,{value:t?.key||"",placeholder:p("pleaseEnterKey"),onChange:R=>b(R.target.value,o,"key"),disabled:c,error:!!y,helperText:y})}),e.jsxRuntimeExports.jsx("div",{className:"middle-icon",children:":"}),e.jsxRuntimeExports.jsx("div",{className:"argv-value",children:e.jsxRuntimeExports.jsx(j.default,{value:t?.data,onChange:R=>b(R,o,"data"),disabled:c,error:!!D,helperText:D,placeholderTextField:p("pleaseEnterValue")})}),e.jsxRuntimeExports.jsx("div",{className:`argv-btn-del ${c?"disabled":""}`,children:e.jsxRuntimeExports.jsx(U.Delete,{onClick:()=>q(o)})})]},o)},o)}),[s,b,q]),V=()=>{if(!Array.isArray(s))return"";const r=s.map(t=>{const o=j.formatGeneratorToData(t.data);return{key:t.key||"",value:o}});try{return JSON.stringify(r,null,4)}catch{return""}},G=r=>{let t=[];try{t=JSON.parse(r)}catch{return[]}return Array.isArray(t)?t.map(d=>{const y=j.formatDataToGenerator(d?.value);return{key:d.key,data:y}}):[]};return e.jsxRuntimeExports.jsxs("div",{className:S(`${_.$prefixCls}-argv`,n,{}),style:u,children:[e.jsxRuntimeExports.jsx("div",{className:"btn-batch-edit",children:e.jsxRuntimeExports.jsx(P.default,{sourceData:s,dataToJson:V,jsonToData:G,onFinish:r=>{console.log(r,"BatchEdit===>"),E([...r])}})}),M,e.jsxRuntimeExports.jsx("div",{className:"argv-list",children:F}),e.jsxRuntimeExports.jsxs("div",{className:`argv-btn-add ${c?"disabled":""}`,onClick:A,children:[e.jsxRuntimeExports.jsx(w.PlusCircleF,{}),e.jsxRuntimeExports.jsx("span",{children:p("add")})]})]})},C=i=>{if(!N.isObject(i))return[];const u=Object.keys(i),n=[];return u.forEach(a=>{const c=j.formatDataToGenerator(i?.[a]);n.push({key:a,data:c})}),n},O=i=>{const u={};return i.forEach(n=>{if(n.key){const a=j.formatGeneratorToData(n.data);u[n.key]=a}}),u},H=(i,u)=>{const n=[];let a=!1;return i.forEach((c,f)=>{const{key:h,data:g}=c,m=!h,l=!j.checkGeneratorData(g);(m||l)&&(a=!0,n[f]={key:m?u("required"):"",value:l?u("formatError"):""})}),{error:a,detail:n}};exports.checkArgvData=H;exports.default=z;exports.formatDataToObject=O;exports.formatObjectToData=C;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const e=require("../_virtual/jsx-runtime.js"),x=require("react"),S=require("clsx"),_=require("../GlobalContext/constant.js"),K=require("../GlobalContext/useFormatMessage.js"),J=require("@snack-kit/lib"),L=require("./lang/index.js"),P=require("./batchEdit/index.js"),j=require("./dataGenerator/index.js"),I=require("../Label/index.js"),B=require("../TextField/index.js"),U=require("../node_modules/@para-ui/icons/Delete/index.js"),w=require("../node_modules/@para-ui/icons/PlusCircleF/index.js"),N=require("../Utils/index.js");;/* empty css            */const z=i=>{const{style:l,className:n,defaultValue:a,disabled:c,label:f,labelProps:h,errors:g,onChange:m,list:u,onListChange:k}=i,p=K.default("Argv",L.default),[s,v]=x.useState([]),D={key:"",data:{dataType:"string",data:""}};x.useEffect(()=>{if(!a||!N.isObject(a)){v([]);return}v(C(a))},[a]),x.useEffect(()=>{u!==void 0&&v(u)},[u]);const A=x.useMemo(()=>J.Debounce(async r=>{const t=O(r);m&&m(t)},200),[]),E=r=>{v(r),k&&k(r),A(r)},M=()=>{c||(s.push({...D}),E([...s]))},T=r=>{c||(s.splice(r,1),E([...s]))},b=(r,t,o)=>{s[t]||(s[t]={...D}),s[t]={...s[t],[o]:r},E([...s])},$=x.useMemo(()=>e.jsxRuntimeExports.jsx("div",{className:"argv-label",children:e.jsxRuntimeExports.jsx(I.default,{label:f||p("environmentVariable"),...h})}),[f,h]),F=x.useMemo(()=>s.map((t,o)=>{const d=g?.[o]??{},y=d?.key||"",q=d?.value||"";return e.jsxRuntimeExports.jsx("div",{children:e.jsxRuntimeExports.jsxs("div",{className:"argv-item",children:[e.jsxRuntimeExports.jsx("div",{className:"argv-key",children:e.jsxRuntimeExports.jsx(B.TextField,{value:t?.key||"",placeholder:p("pleaseEnterKey"),onChange:R=>b(R.target.value,o,"key"),disabled:c,error:!!y,helperText:y})}),e.jsxRuntimeExports.jsx("div",{className:"middle-icon",children:":"}),e.jsxRuntimeExports.jsx("div",{className:"argv-value",children:e.jsxRuntimeExports.jsx(j.default,{value:t?.data,onChange:R=>b(R,o,"data"),disabled:c,error:!!q,helperText:q,placeholderTextField:p("pleaseEnterValue")})}),e.jsxRuntimeExports.jsx("div",{className:`argv-btn-del ${c?"disabled":""}`,children:e.jsxRuntimeExports.jsx(U.Delete,{onClick:()=>T(o)})})]},o)},o)}),[s,b,T]),V=()=>{if(!Array.isArray(s))return"";const r=s.map(t=>{const o=j.formatGeneratorToData(t.data);return{key:t.key||"",value:o}});try{return JSON.stringify(r,null,4)}catch{return""}},G=r=>{let t=[];try{t=JSON.parse(r)}catch{return[]}return Array.isArray(t)?t.map(d=>{const y=j.formatDataToGenerator(d?.value);return{key:d.key,data:y}}):[]};return e.jsxRuntimeExports.jsxs("div",{className:S(`${_.$prefixCls}-argv`,n,{}),style:l,children:[e.jsxRuntimeExports.jsx("div",{className:"btn-batch-edit",children:e.jsxRuntimeExports.jsx(P.default,{sourceData:s,dataToJson:V,jsonToData:G,onFinish:r=>{console.log(r,"BatchEdit===>"),E([...r])}})}),$,e.jsxRuntimeExports.jsx("div",{className:"argv-list",children:F}),e.jsxRuntimeExports.jsxs("div",{className:`argv-btn-add ${c?"disabled":""}`,onClick:M,children:[e.jsxRuntimeExports.jsx(w.PlusCircleF,{}),e.jsxRuntimeExports.jsx("span",{children:p("add")})]})]})},C=i=>{if(!N.isObject(i))return[];const l=Object.keys(i),n=[];return l.forEach(a=>{const c=j.formatDataToGenerator(i?.[a]);n.push({key:a,data:c})}),n},O=i=>{const l={};return i.forEach(n=>{if(n.key){const a=j.formatGeneratorToData(n.data);l[n.key]=a}}),l},H=(i,l)=>{const n=[];let a=!1;return i.forEach((c,f)=>{const{key:h,data:g}=c,m=!h,u=!j.checkGeneratorData(g);(m||u)&&(a=!0,n[f]={key:m?l("required"):"",value:u?l("formatError"):""})}),{error:a,detail:n}};exports.checkArgvData=H;exports.default=z;exports.formatDataToObject=O;exports.formatObjectToData=C;
 //# sourceMappingURL=index.js.map

package/lib/AutoBox/component.json

@@ -0,0 +1,133 @@
+{
+    "name": "AutoBox",
+    "category": "Layout",
+    "description": "自适应容器，根据容器宽度自动计算可见项数量，超出部分折叠到'更多'下拉弹层中展示",
+    "semantic": {
+        "intent": [
+            "响应式布局",
+            "内容收纳"
+        ],
+        "useCases": [
+            "工具栏",
+            "标签组",
+            "操作区"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "expanded"
+    ],
+    "idealProps": {
+        "list": {
+            "type": "array",
+            "description": "需要自适应容纳的子节点数组(ReactNode[]);事件挂在节点自身,AutoBox 不暴露 item-level onClick"
+        },
+        "showNum": {
+            "type": "number",
+            "description": "强制显示前 N 项(跳过自适应计算),溢出全部进'更多'"
+        },
+        "trigger": {
+            "type": "enum",
+            "values": [
+                "click",
+                "hover"
+            ],
+            "default": "click",
+            "description": "'更多'弹层触发方式"
+        },
+        "placement": {
+            "type": "string",
+            "default": "bottomLeft",
+            "description": "'更多'弹层位置(透传 Popover placement)"
+        },
+        "hideMore": {
+            "type": "boolean",
+            "default": false,
+            "description": "隐藏内置'更多'按钮(配 anchorEl + openMore 自管理外置触发器)"
+        },
+        "moreCustomize": {
+            "type": "ReactNode",
+            "description": "自定义'更多'触发节点,替换默认 More 图标按钮"
+        },
+        "openMore": {
+            "type": "boolean",
+            "default": false,
+            "description": "外部受控弹层显隐"
+        },
+        "onShowMore": {
+            "type": "function",
+            "description": "(bol: boolean) => void 是否有溢出项的状态回调"
+        },
+        "onCloseMore": {
+            "type": "function",
+            "description": "() => void 受控弹层关闭回调"
+        }
+    },
+    "do": [
+        "用于空间有限需要收纳溢出内容的场景",
+        "配合 Popover 展示更多",
+        "list 中每个 ReactNode 自行绑定点击事件——AutoBox 只做布局计算和'更多'收纳"
+    ],
+    "dont": [
+        "在固定宽度布局中滥用",
+        "列表项过多时不做分页",
+        "期望 AutoBox 暴露单项 onClick——事件需要挂在 list 元素自身上"
+    ],
+    "events": {
+        "onShowMore": {
+            "signature": "(bol: boolean) => void",
+            "asyncSupported": false,
+            "examples": [
+                "bol=true 表示当前有溢出项（list.length > morePos），可用于显示/隐藏外部操作按钮",
+                "bol=false 表示所有项都可见，无需显示外部'更多'入口",
+                "配合 hideMore + openMore 实现外置触发器：onShowMore={setHasMore}，只在 hasMore 时渲染自定义按钮"
+            ],
+            "commonMistakes": [
+                "期望 onShowMore 返回具体溢出项数量——它只返回 boolean，溢出项数量需自行计算(list.length - morePos)",
+                "在 onShowMore 里 setState 引发重渲染后，AutoBox 内部 resize 可能再次触发 onShowMore，注意避免循环",
+                "onShowMore 在 list prop 变化或 window resize 后都会重新触发，不要依赖它的调用次数做副作用"
+            ]
+        },
+        "onCloseMore": {
+            "signature": "() => void",
+            "asyncSupported": false,
+            "examples": [
+                "弹层关闭时同步外部受控状态：onCloseMore={() => setOpenMore(false)}",
+                "关闭时记录日志：onCloseMore={() => analytics.track('more_closed')}",
+                "配合 openMore 实现受控弹层：<AutoBox openMore={open} onCloseMore={() => setOpen(false)} />"
+            ],
+            "commonMistakes": [
+                "传了 onCloseMore 但忘记传 openMore——二者需配合使用才能实现受控弹层",
+                "期望 onCloseMore 在用户点击弹层内容后也触发——只有弹层关闭时触发，内容点击需在 list 节点自身处理",
+                "期望 onCloseMore 携带关闭原因——回调无参数，无法区分是点击外部还是 ESC 关闭"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "list 类型是 any[]，但传入非 ReactNode 元素会导致 runtime 渲染异常",
+            "wrong": "// list 传了原始数据对象，忘记 map 成 ReactNode\n<AutoBox list={[{ id: 1, name: '标签' }]} />  // 对象不是合法 ReactNode，渲染报错",
+            "right": "// 先 map 成 ReactNode\n<AutoBox list={data.map(d => <Tag key={d.id}>{d.name}</Tag>)} />"
+        },
+        {
+            "issue": "moreCustomize 声明为 ReactNode，但 src 内部也处理了函数形式（typeof moreCustomize === 'function'），类型声明不完整",
+            "wrong": "// 传函数期望接收 morePos 参数，但 TypeScript 按 ReactNode 检查会报类型错误\nmoreCustomize={(morePos) => <span>+{morePos}</span>}",
+            "right": "// 如需传函数绕过类型检查需显式 as any，或直接传静态 ReactNode\nmoreCustomize={<span>更多</span>}"
+        },
+        {
+            "issue": "AutoBoxProps 有索引签名 [name: string]: any，传错误 prop 名不会报 TS 错误",
+            "wrong": "// 拼写错误不会被 TS 捕获\n<AutoBox list={list} closeMore={() => {}} />  // closeMore 应为 onCloseMore，静默失效",
+            "right": "// 注意使用正确 prop 名\n<AutoBox list={list} onCloseMore={() => {}} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "AutoBox",
+        "adapter": null
+    }
+}

package/lib/AutoBox/index.d.ts

@@ -6,7 +6,7 @@ export interface AutoBoxProps {
     /** style */
     style?: React.CSSProperties;
     /** list选项 */
-    list?: any[];
+    list?: React.ReactNode[];
     /** 指定渲染几项,存在这个参数,则不自适应 */
     showNum?: number;
     /** 下拉框样式 */
@@ -18,7 +18,7 @@ export interface AutoBoxProps {
     /** 打开下拉框 */
     openMore?: boolean;
     /** 定位元素 */
-    anchorEl?: any;
+    anchorEl?: HTMLElement | null;
     /** 关闭弹窗 */
     onCloseMore?: () => void;
     /** 显示更多 */
@@ -27,7 +27,7 @@ export interface AutoBoxProps {
     trigger?: 'click' | 'hover';
     /** 位置 */
     placement?: TooltipPlacement;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export declare const AutoBox: FunctionComponent<AutoBoxProps>;
 export default AutoBox;

package/lib/AutoBox/index.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const s=require("../_virtual/jsx-runtime.js"),t=require("react"),_=require("../Popover/index.js"),A=require("./protal.js"),F=require("../node_modules/@para-ui/icons/More/index.js"),N=require("../GlobalContext/constant.js");;/* empty css            */const w=i=>{const{className:x,list:o=[],popoverClassName:p,moreCustomize:l,anchorEl:v,hideMore:q=!1,showNum:m,onCloseMore:j,onShowMore:u,style:P,trigger:S="click",placement:$="bottomLeft"}=i,M=t.useRef(null),[r,f]=t.useState(null),[E,d]=t.useState(!1),[h]=t.useState({}),z=t.useRef();t.useEffect(()=>{i.openMore!==void 0&&d(i.openMore)},[i.openMore]),t.useEffect(()=>{if(i.showNum===void 0)return a(),window.addEventListener("resize",a),()=>{window.removeEventListener("resize",a),clearTimeout(h.timer)}},[o]),t.useEffect(()=>{m!==void 0&&(f(m),window.removeEventListener("resize",a))},[m]),t.useEffect(()=>{r!==null&&o.length>r?u&&u(!0):u&&u(!1)},[o,r,u]);const y=e=>{if(e)return d(!0);c()},c=()=>{d(!1),j&&j()},D=()=>{c()},C=e=>{if(e===null||e===0)return;e===void 0&&(e=o.length);const n=M.current;if(n)if(n.scrollWidth>n.clientWidth){const b=Number(e)-1;f(b),C(b)}else o.length<=e&&D()},a=()=>{clearTimeout(h.timer),c(),h.timer=setTimeout(()=>{f(o.length),C()},100)},L=()=>{let e=`${N.$prefixCls}-auto-box`;return x&&(e+=` ${x}`),e},g=()=>{let e=`${N.$prefixCls}-auto-box-popover`;return p&&(e+=` ${p}`),e},R=()=>s.jsxRuntimeExports.jsx("div",{className:"auto-box-popover-content",children:o&&o.map((e,n)=>r!==null&&r>n?null:s.jsxRuntimeExports.jsx(t.Fragment,{children:e},n))}),T=()=>{if(r!==null&&o.length>r&&!q){const e=()=>l?typeof l=="function"?l(r):l:s.jsxRuntimeExports.jsx(F.More,{});return s.jsxRuntimeExports.jsx(_.Popover,{open:E,content:R(),overlayClassName:g(),placement:$,trigger:S,onVisibleChange:y,children:s.jsxRuntimeExports.jsx("div",{className:"auto-box-more",ref:z,children:e()})})}},B=()=>{if(v&&E)return s.jsxRuntimeExports.jsx(A.Protal,{className:g(),anchorEl:v,onClose:c,children:R()})};return s.jsxRuntimeExports.jsxs("div",{className:L(),style:P,ref:M,children:[o.map((e,n)=>r!==null&&r<=n?null:s.jsxRuntimeExports.jsx(t.Fragment,{children:e},n)),T(),B()]})};exports.AutoBox=w;exports.default=w;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const s=require("../_virtual/jsx-runtime.js"),t=require("react"),_=require("../Popover/index.js"),A=require("./protal.js"),F=require("../node_modules/@para-ui/icons/More/index.js"),N=require("../GlobalContext/constant.js");;/* empty css            */const w=i=>{const{className:x,list:o=[],popoverClassName:p,moreCustomize:l,anchorEl:v,hideMore:q=!1,showNum:m,onCloseMore:j,onShowMore:u,style:P,trigger:S="click",placement:$="bottomLeft"}=i,M=t.useRef(null),[r,f]=t.useState(null),[E,d]=t.useState(!1),[h]=t.useState({}),z=t.useRef(null);t.useEffect(()=>{i.openMore!==void 0&&d(i.openMore)},[i.openMore]),t.useEffect(()=>{if(i.showNum===void 0)return a(),window.addEventListener("resize",a),()=>{window.removeEventListener("resize",a),clearTimeout(h.timer)}},[o]),t.useEffect(()=>{m!==void 0&&(f(m),window.removeEventListener("resize",a))},[m]),t.useEffect(()=>{r!==null&&o.length>r?u&&u(!0):u&&u(!1)},[o,r,u]);const y=e=>{if(e)return d(!0);c()},c=()=>{d(!1),j&&j()},D=()=>{c()},C=e=>{if(e===null||e===0)return;e===void 0&&(e=o.length);const n=M.current;if(n)if(n.scrollWidth>n.clientWidth){const b=Number(e)-1;f(b),C(b)}else o.length<=e&&D()},a=()=>{clearTimeout(h.timer),c(),h.timer=setTimeout(()=>{f(o.length),C()},100)},L=()=>{let e=`${N.$prefixCls}-auto-box`;return x&&(e+=` ${x}`),e},g=()=>{let e=`${N.$prefixCls}-auto-box-popover`;return p&&(e+=` ${p}`),e},R=()=>s.jsxRuntimeExports.jsx("div",{className:"auto-box-popover-content",children:o&&o.map((e,n)=>r!==null&&r>n?null:s.jsxRuntimeExports.jsx(t.Fragment,{children:e},n))}),T=()=>{if(r!==null&&o.length>r&&!q){const e=()=>l?typeof l=="function"?l(r):l:s.jsxRuntimeExports.jsx(F.More,{});return s.jsxRuntimeExports.jsx(_.Popover,{open:E,content:R(),overlayClassName:g(),placement:$,trigger:S,onVisibleChange:y,children:s.jsxRuntimeExports.jsx("div",{className:"auto-box-more",ref:z,children:e()})})}},B=()=>{if(v&&E)return s.jsxRuntimeExports.jsx(A.Protal,{className:g(),anchorEl:v,onClose:c,children:R()})};return s.jsxRuntimeExports.jsxs("div",{className:L(),style:P,ref:M,children:[o.map((e,n)=>r!==null&&r<=n?null:s.jsxRuntimeExports.jsx(t.Fragment,{children:e},n)),T(),B()]})};exports.AutoBox=w;exports.default=w;
 //# sourceMappingURL=index.js.map

package/lib/AutoBox/protal.d.ts

@@ -2,11 +2,11 @@ import { FunctionComponent, ReactNode } from 'react';
 export interface ProtalBoxProps {
     className?: string;
     /** 定位元素 */
-    anchorEl?: any;
+    anchorEl?: HTMLElement | null;
     /** 关闭事件 */
     onClose?: () => void;
     children?: ReactNode;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 export declare const Protal: FunctionComponent<ProtalBoxProps>;
 export default Protal;

package/lib/AutoBox/protal.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const o=require("../_virtual/jsx-runtime.js"),r=require("react"),v=require("react-dom"),C=require("@paraview/lib"),h=require("../GlobalContext/constant.js"),p=x=>{const{children:R,className:u,anchorEl:a,onClose:l}=x,[g,w]=r.useState({}),c=r.useRef({uuid:`${h.$prefixCls}-protal-box-content-${C.UUID()}`}),s=r.useRef(),i=r.useRef();r.useEffect(()=>(E(),window.addEventListener("click",d),()=>{s&&s.current&&s.current.remove(),window.removeEventListener("click",d)}),[]);const j=(t,n)=>{const e=t.matches||t.webkitMatchesSelector||t.mozMatchesSelector||t.msMatchesSelector;for(;t&&!e.call(t,n);)t=t.parentElement;return t},d=t=>{if(!c.current)return;j(t.target,`.${c.current.uuid}`)||l&&l()},E=()=>{if(!a||!i.current)return;const t=a.getBoundingClientRect(),n=i.current.getBoundingClientRect(),e={opacity:1,left:t.left,top:t.top+t.height},f=window.innerHeight,m=window.innerWidth;e.left+n.width>m&&(e.left=m-n.width-8,e.left<0&&(e.left=0)),e.top+n.height>f&&(e.top=f-n.height-8,e.top<0&&(e.top=0)),w(e)},$=()=>{let t=`${h.$prefixCls}-protal-box`;return u&&(t+=` ${u}`),t},b=()=>o.jsxRuntimeExports.jsxs("div",{className:$(),ref:s,children:[o.jsxRuntimeExports.jsx("div",{className:"protal-mask"}),o.jsxRuntimeExports.jsx("div",{className:`protal-content ${c.current.uuid}`,style:g,ref:i,children:R})]});return o.jsxRuntimeExports.jsx(o.jsxRuntimeExports.Fragment,{children:v.createPortal(b(),document.getElementsByTagName("body")[0])})};exports.Protal=p;exports.default=p;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const s=require("../_virtual/jsx-runtime.js"),c=require("react"),C=require("react-dom"),S=require("@snack-kit/lib"),h=require("../GlobalContext/constant.js"),p=x=>{const{children:R,className:a,anchorEl:d,onClose:f}=x,[g,w]=c.useState({}),l=c.useRef({uuid:`${h.$prefixCls}-protal-box-content-${S.UUID()}`}),i=c.useRef(null),u=c.useRef(null);c.useEffect(()=>(E(),window.addEventListener("click",m),()=>{i&&i.current&&i.current.remove(),window.removeEventListener("click",m)}),[]);const j=(e,o)=>{if(!e)return null;const t=e,r=t.matches||t.webkitMatchesSelector||t.mozMatchesSelector||t.msMatchesSelector;if(!r)return null;let n=e;for(;n&&!r.call(n,o);)n=n.parentElement;return n},m=e=>{if(!l.current)return;j(e.target,`.${l.current.uuid}`)||f&&f()},E=()=>{if(!d||!u.current)return;const e=d.getBoundingClientRect(),o=u.current.getBoundingClientRect(),t={opacity:1,left:e.left,top:e.top+e.height},r=window.innerHeight,n=window.innerWidth;t.left+o.width>n&&(t.left=n-o.width-8,t.left<0&&(t.left=0)),t.top+o.height>r&&(t.top=r-o.height-8,t.top<0&&(t.top=0)),w(t)},b=()=>{let e=`${h.$prefixCls}-protal-box`;return a&&(e+=` ${a}`),e},v=()=>s.jsxRuntimeExports.jsxs("div",{className:b(),ref:i,children:[s.jsxRuntimeExports.jsx("div",{className:"protal-mask"}),s.jsxRuntimeExports.jsx("div",{className:`protal-content ${l.current.uuid}`,style:g,ref:u,children:R})]});return s.jsxRuntimeExports.jsx(s.jsxRuntimeExports.Fragment,{children:C.createPortal(v(),document.getElementsByTagName("body")[0])})};exports.Protal=p;exports.default=p;
 //# sourceMappingURL=protal.js.map