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

package/es/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/es/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/es/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/es/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/es/AutoBox/index.js

@@ -19,7 +19,7 @@ const U = (s) => {
     style: L,
     trigger: y = "click",
     placement: R = "bottomLeft"
-  } = s, x = z(null), [t, f] = p(null), [j, h] = p(!1), [d] = p({}), S = z();
+  } = s, x = z(null), [t, f] = p(null), [j, h] = p(!1), [d] = p({}), S = z(null);
   a(() => {
     s.openMore !== void 0 && h(s.openMore);
   }, [s.openMore]), a(() => {

package/es/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/es/AutoBox/protal.js

@@ -1,54 +1,57 @@
-import { j as o } from "../_virtual/jsx-runtime.js";
-import { useState as v, useRef as i, useEffect as y } from "react";
+import { j as c } from "../_virtual/jsx-runtime.js";
+import { useState as v, useRef as a, useEffect as y } from "react";
 import { createPortal as E } from "react-dom";
 import { UUID as S } from "@snack-kit/lib";
 import { $prefixCls as h } from "../GlobalContext/constant.js";
 const M = (p) => {
-  const { children: w, className: a, anchorEl: l, onClose: m } = p, [g, x] = v({}), c = i({
+  const { children: w, className: u, anchorEl: m, onClose: f } = p, [g, x] = v({}), i = a({
     uuid: `${h}-protal-box-content-${S()}`
-  }), r = i(), s = i();
-  y(() => (R(), window.addEventListener("click", f), () => {
-    r && r.current && r.current.remove(), window.removeEventListener("click", f);
+  }), s = a(null), l = a(null);
+  y(() => (R(), window.addEventListener("click", d), () => {
+    s && s.current && s.current.remove(), window.removeEventListener("click", d);
   }), []);
-  const C = (t, n) => {
-    const e = t.matches || t.webkitMatchesSelector || t.mozMatchesSelector || t.msMatchesSelector;
-    for (; t && !e.call(t, n); )
-      t = t.parentElement;
-    return t;
-  }, f = (t) => {
-    if (!c.current) return;
-    C(t.target, `.${c.current.uuid}`) || m && m();
+  const C = (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;
+  }, d = (e) => {
+    if (!i.current) return;
+    C(e.target, `.${i.current.uuid}`) || f && f();
   }, R = () => {
-    if (!l || !s.current) return;
-    const t = l.getBoundingClientRect(), n = s.current.getBoundingClientRect(), e = {
+    if (!m || !l.current) return;
+    const e = m.getBoundingClientRect(), o = l.current.getBoundingClientRect(), t = {
       opacity: 1,
-      left: t.left,
-      top: t.top + t.height
-    }, u = window.innerHeight, d = window.innerWidth;
-    e.left + n.width > d && (e.left = d - n.width - 8, e.left < 0 && (e.left = 0)), e.top + n.height > u && (e.top = u - n.height - 8, e.top < 0 && (e.top = 0)), x(e);
+      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)), x(t);
   }, b = () => {
-    let t = `${h}-protal-box`;
-    return a && (t += ` ${a}`), t;
-  }, j = () => /* @__PURE__ */ o.jsxs(
+    let e = `${h}-protal-box`;
+    return u && (e += ` ${u}`), e;
+  }, j = () => /* @__PURE__ */ c.jsxs(
     "div",
     {
       className: b(),
-      ref: r,
+      ref: s,
       children: [
-        /* @__PURE__ */ o.jsx("div", { className: "protal-mask" }),
-        /* @__PURE__ */ o.jsx(
+        /* @__PURE__ */ c.jsx("div", { className: "protal-mask" }),
+        /* @__PURE__ */ c.jsx(
           "div",
           {
-            className: `protal-content ${c.current.uuid}`,
+            className: `protal-content ${i.current.uuid}`,
             style: g,
-            ref: s,
+            ref: l,
             children: w
           }
         )
       ]
     }
   );
-  return /* @__PURE__ */ o.jsx(o.Fragment, { children: E(j(), document.getElementsByTagName("body")[0]) });
+  return /* @__PURE__ */ c.jsx(c.Fragment, { children: E(j(), document.getElementsByTagName("body")[0]) });
 };
 export {
   M as Protal,

package/es/AutoButton/component.json

@@ -0,0 +1,109 @@
+{
+    "name": "AutoButton",
+    "category": "General",
+    "description": "自适应按钮组，根据容器宽度自动折叠超出的按钮到'更多'下拉弹层，list 每项支持 buttonType 切换图标/分割/普通三种形态",
+    "semantic": {
+        "intent": [
+            "按钮收纳",
+            "响应式操作"
+        ],
+        "useCases": [
+            "操作栏",
+            "批量操作",
+            "编辑器工具栏"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "expanded"
+    ],
+    "idealProps": {
+        "list": {
+            "type": "array",
+            "description": "按钮项数据数组,每项为 AutoButtonItemProps(union: ButtonProps | IconButtonProps | SplitButtonProps + 扩展 buttonType/popConfirmProps)"
+        },
+        "marginRight": {
+            "type": "string",
+            "default": "16px",
+            "description": "按钮间右间距"
+        },
+        "moreProps": {
+            "type": "object",
+            "objectShape": {
+                "buttonType": { "type": "'icon'", "description": "强制图标模式（不显示文字）" },
+                "icon": { "type": "ReactNode", "description": "自定义'更多'图标（默认 MoreVert）" },
+                "children": { "type": "ReactNode", "description": "自定义'更多'按钮文字内容" }
+            },
+            "description": "溢出折叠后'更多'按钮的展示形态({ buttonType?: 'icon'; icon?: ReactNode; children?: ReactNode })"
+        },
+        "morePlacement": {
+            "type": "string",
+            "default": "bottomLeft",
+            "description": "'更多'浮层弹出位置(透传 Dropdown placement)"
+        },
+        "moreMaxWidth": {
+            "type": "string",
+            "default": "500px",
+            "description": "'更多'浮层最大宽度,超出自动换行"
+        },
+        "trigger": {
+            "type": "array",
+            "default": "['hover']",
+            "description": "'更多'浮层触发方式数组('click' | 'hover' | 'contextMenu')[]"
+        }
+    },
+    "do": [
+        "在工具栏中使用收纳溢出按钮",
+        "保持主要操作可见，把低频操作放到 list 后面让其优先被折叠",
+        "每个 list 项用 buttonType 区分形态：不传=普通按钮 / 'icon'=图标按钮 / 'split'=分割按钮",
+        "需要二次确认时用 list 项的 popConfirmProps 属性透传 PopConfirm 参数"
+    ],
+    "dont": [
+        "主要操作被收纳进更多（应调整 list 顺序）",
+        "按钮过多时不分优先级",
+        "在 list 每项上传 buttonType='split' 时忘记提供 options 字段——split 按钮的子项来自 options"
+    ],
+    "events": {
+        "list[].onClick": {
+            "signature": "(event: React.MouseEvent<HTMLButtonElement>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "每项 onClick 挂在 AutoButtonItemProps 上：list={[{ children: '编辑', onClick: handleEdit }]}",
+                "溢出后在'更多'弹层中点击时，AutoButton 内部会代理调用该项的 onClick",
+                "需要区分是哪个按钮被点击：在每项的 onClick 闭包里引用各自的业务 id"
+            ],
+            "commonMistakes": [
+                "期望 AutoButton 暴露统一 onItemClick(index, item) 回调——AutoButton 无此 prop，onClick 挂在每项上",
+                "buttonType='split' 的子项点击时，src 会把 parentItem.onClick 也触发一次——注意避免重复处理",
+                "弹层中点击时 event.currentTarget 是弹层内 Button，不是原始按钮 DOM，不要依赖 currentTarget 做 DOM 查找"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "AutoButtonItemProps 是 ButtonProps | IconButtonProps | SplitButtonProps 的 union，TypeScript 需要用 buttonType 做类型守卫",
+            "wrong": "// 直接访问 split 专属字段\nconst item: AutoButtonItemProps = { buttonType: 'split', options: [...] };  // options 不在 ButtonProps 上，TS 报错",
+            "right": "// 断言为具体类型\nimport type { SplitButtonProps } from '@para-ui/core/Button';\nconst item: AutoButtonItemProps = { buttonType: 'split', ...(splitProps as SplitButtonProps) };"
+        },
+        {
+            "issue": "trigger prop 是数组类型，不是字符串，与部分其他组件的字符串 trigger 不同",
+            "wrong": "<AutoButton list={list} trigger='hover' />  // 期望字符串，实际是 string[] 类型报错",
+            "right": "<AutoButton list={list} trigger={['hover']} />  // 数组形式"
+        },
+        {
+            "issue": "list 的 popConfirmProps 是可选字段，传了但 items 没有此字段时 TypeScript 不报错（union 类型），但 runtime 才生效",
+            "wrong": "// 误以为所有 list 项都有 popConfirmProps 类型定义，直接访问\nconst confirm = item.popConfirmProps;  // 可能 undefined，需要 ?. 操作符",
+            "right": "const confirm = (item as AutoButtonItemProps).popConfirmProps;  // 先断言再访问，配合 ?. 操作符"
+        }
+    ],
+    "mapping": {
+        "realComponent": "AutoButton",
+        "adapter": null
+    }
+}