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

package/lib/Dropdown/component.json

@@ -0,0 +1,147 @@
+{
+    "name": "Dropdown",
+    "category": "Navigation",
+    "description": "下拉菜单浮层。children 必须是**单一 React 元素**(rc-dropdown 内部需挂 ref);overlay 必须是**单一 ReactElement**(不接受 ReactNode/字符串/数组/Fragment),不传则不渲染浮层。",
+    "semantic": {
+        "intent": [
+            "下拉选择",
+            "菜单展示"
+        ],
+        "useCases": [
+            "用户操作菜单",
+            "导航下拉",
+            "右键上下文菜单",
+            "快捷操作"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "open",
+        "closed"
+    ],
+    "idealProps": {
+        "overlay": {
+            "type": "React.ReactElement | (() => React.ReactElement)",
+            "description": "下拉浮层内容。**必须是单个 JSX 元素或返回单个 JSX 元素的函数**——不接受字符串/数字/数组/Fragment/ReactNode(否则 TS2322)。要传多个节点请用单一容器(如 `<div>` / `<ul>`)包裹。**如封装组件以 `ReactNode` 类型 prop 接收浮层内容，推荐封装写法：`overlay={<div>{contentProp}</div>}`**——额外的 div 容器不影响 rc-dropdown 内部定位。"
+        },
+        "children": {
+            "type": "React.ReactElement",
+            "description": "触发浮层的目标节点(必填，**单一可接收 ref 的 React 元素**)。传 string / Fragment / 数组会触发 TS2322；如需多节点触发器，外层包一层 `<span>` 或具体组件即可。**如封装组件以 `ReactNode` 类型 prop 接收触发器内容，推荐封装写法：`<Dropdown ...><span>{triggerNodeProp}</span></Dropdown>`**——`<span>` 容器可正常挂 ref，不影响触发行为。"
+        },
+        "trigger": {
+            "type": "('click' | 'hover' | 'contextMenu')[]",
+            "values": ["click", "hover", "contextMenu"],
+            "default": ["hover"],
+            "description": "触发下拉的行为列表;数组形式可同时启用多种触发(如 ['click','hover'])。'contextMenu' 用于右键上下文菜单场景。"
+        },
+        "placement": {
+            "type": "'top' | 'topLeft' | 'topRight' | 'bottom' | 'bottomLeft' | 'bottomRight'",
+            "values": ["top", "topLeft", "topRight", "bottom", "bottomLeft", "bottomRight"],
+            "default": "bottomLeft",
+            "description": "菜单弹出位置；6 枚举值已展开。默认 'bottomLeft'（左对齐从下方弹出）；'bottom' 为居中对齐，'bottomRight' 为右对齐。"
+        },
+        "visible": {
+            "type": "boolean",
+            "description": "受控显示状态;传值则交由外部控制开合,不传走非受控由 trigger 触发。"
+        },
+        "onVisibleChange": {
+            "type": "(visible: boolean) => void",
+            "description": "菜单显隐切换回调;受控/非受控均会触发,可用作 visible 同步源。"
+        },
+        "destroyPopupOnHide": {
+            "type": "boolean",
+            "default": false,
+            "description": "关闭时是否销毁浮层 DOM(避免后台仍渲染)。"
+        },
+        "overlayClassName": {
+            "type": "string",
+            "description": "浮层最外层 class 名"
+        },
+        "overlayStyle": {
+            "type": "React.CSSProperties",
+            "description": "浮层最外层样式"
+        },
+        "mouseEnterDelay": {
+            "type": "number",
+            "description": "trigger='hover' 鼠标进入延迟(秒)"
+        },
+        "mouseLeaveDelay": {
+            "type": "number",
+            "description": "trigger='hover' 鼠标移出延迟(秒)"
+        },
+        "getPopupContainer": {
+            "type": "(triggerNode: HTMLElement) => HTMLElement",
+            "description": "浮层渲染容器;默认 body,可指定挂载到自定义 DOM 节点(滚动容器场景常用)"
+        },
+        "forceRender": {
+            "type": "boolean",
+            "default": false,
+            "description": "首次渲染前强制创建浮层 DOM(SSR / 首次过渡动画场景)"
+        },
+        "isolationPopupOnHide": {
+            "type": "boolean",
+            "default": false,
+            "description": "关闭时把浮层定位至屏幕之外,隔离 DOM 污染(默认 false)"
+        }
+    },
+    "do": [
+        "overlay 包成单一 JSX 元素(<div>/<ul>/自定义浮层组件),不要传字符串或多节点数组",
+        "children 必须是单一可挂 ref 的元素;非组件节点用 <span> 包裹",
+        "封装 Dropdown 时，外部 prop 类型为 ReactNode → children 传 `<span>{prop}</span>`，overlay 传 `<div>{prop}</div>`——这是官方推荐封装模式，不影响定位和 ref 挂载",
+        "右键上下文菜单场景用 trigger={['contextMenu']}",
+        "需要受控开合时同时传 visible + onVisibleChange,保证状态来源唯一"
+    ],
+    "dont": [
+        "不要给 overlay 传 ReactNode/字符串/数组/Fragment——overlay 必须是单个 ReactElement(JSX 元素)",
+        "不要给 children 传字符串/Fragment/数组——会因无法挂 ref 导致触发不生效",
+        "不要在 overlay 里依赖 children 的 onClick——点击事件需在 overlay 内部自行处理",
+        "不要嵌套过深的 Dropdown(下拉里再下拉),交互复杂且不利于键盘可达性"
+    ],
+    "events": {
+        "onVisibleChange": {
+            "signature": "(visible: boolean) => void",
+            "asyncSupported": false,
+            "examples": [
+                "受控模式:onVisibleChange={v => setOpen(v)},配合 visible={open} 实现完全受控",
+                "非受控模式:onVisibleChange={v => console.log('dropdown', v ? '打开' : '关闭')},不传 visible 由 trigger 控制",
+                "点击外部关闭时 onVisibleChange(false) 也会触发"
+            ],
+            "commonMistakes": [
+                "只传 visible 不传 onVisibleChange → 受控模式下下拉无法关闭(visible 永远不更新)",
+                "假设 onVisibleChange 接受 (visible, event) 两个参数 → 实际只有一个 boolean 参数",
+                "在 onVisibleChange 里直接修改 overlay 内容期望触发重渲染 → overlay 变化不会重触发 onVisibleChange"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "overlay 类型是 React.ReactElement | (() => React.ReactElement),不是 ReactNode",
+            "wrong": "overlay={<><div>A</div><div>B</div></>}  // Fragment 作为 overlay 会触发 TS2322 类型错",
+            "right": "overlay={<div><div>A</div><div>B</div></div>}  // 用单一容器元素包裹多节点"
+        },
+        {
+            "issue": "children 类型是 React.ReactElement,不是 ReactNode,传字符串或 Fragment 会 TS 报错",
+            "wrong": "<Dropdown overlay={menu}>触发文字</Dropdown>  // 字符串不是 ReactElement,TS2322",
+            "right": "<Dropdown overlay={menu}><span>触发文字</span></Dropdown>  // 用 span 包裹字符串"
+        },
+        {
+            "issue": "trigger prop 是数组类型,不是字符串",
+            "wrong": "trigger='click'  // TS2322: Type 'string' is not assignable to type '...'",
+            "right": "trigger={['click']}  // 数组形式,支持 ['click'] / ['hover'] / ['click', 'hover']"
+        },
+        {
+            "issue": "Placement 枚举只有 6 个有效值,不包含 'left' / 'right'",
+            "wrong": "placement='left'  // TS 报错:不在 Placement 枚举中",
+            "right": "placement='bottomLeft'  // 合法值: 'top'|'topLeft'|'topRight'|'bottom'|'bottomLeft'|'bottomRight'"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Dropdown",
+        "adapter": null
+    }
+}

package/lib/DynamicMultiBox/component.json

@@ -0,0 +1,278 @@
+{
+    "name": "DynamicMultiBox",
+    "category": "Data Entry",
+    "description": "动态多行表单,支持动态增删行 + 拖拽排序 + 字段级错误反馈。**封装协议:外部以业务对象数组传入,内部维护 valueList + errors 双 state(必须双 state,见 commonPatterns.wrapperPattern)**",
+    "semantic": {
+        "intent": [
+            "动态表单",
+            "多行录入",
+            "支持拖拽 + 行级错误反馈"
+        ],
+        "useCases": [
+            "批量参数 / 联系人录入",
+            "规则配置(条件 → 动作)",
+            "可排序步骤配置(工作流)",
+            "动态字段表单(字段配置由父组件传入)"
+        ],
+        "riskLevel": "normal"
+    },
+    "r23FailingScenarios": {
+        "scenario_003_TS2538_undefined_index": {
+            "failedRequirement": "DynamicMultiBox-003 可拖拽排序的步骤配置",
+            "wrongCode": "const errRow: IErrors = { id: s.id };\nfieldConfig.forEach((cfg: IConfig) => {\n    errRow[cfg.name] = '';  // ❌ TS2538 'Type undefined cannot be used as an index type'\n});",
+            "rootCause": "**IConfig.name 在 v5.x 类型严格化后是 `string | undefined`**(非必填字段)。直接用 cfg.name 做对象索引时 TS 拒绝(undefined 不能作为索引)",
+            "fixedCode": "const errRow: IErrors = { id: s.id };\nfieldConfig.forEach((cfg: IConfig) => {\n    if (cfg.name) errRow[cfg.name] = '';  // ✅ narrow 后再索引\n});",
+            "alternativeFix": "// 或用 ! 非空断言(已知 config 项必有 name):\nfieldConfig.forEach((cfg: IConfig) => {\n    errRow[cfg.name!] = '';\n});"
+        },
+        "scenario_006_TS2352_rest_spread_unknown": {
+            "failedRequirement": "DynamicMultiBox-006 标准联系人录入",
+            "wrongCode": "interface Contact { name: string; phone: string; email: string; }\nconst valueListToContacts = (valueList: IValueList[]): Contact[] =>\n    valueList.map(({ id, ...rest }) => rest as Contact);  // ❌ TS2352",
+            "rootCause": "对 IValueList 做 `{id, ...rest}` 解构后,TS 把 rest 推断为 `{[x: string]: unknown}`(索引签名)。**unknown 索引签名 → 具体业务类型** 直接 `as Contact` 被 TS 5.x 拒绝(类型不充分重叠)",
+            "fixedCode": "const valueListToContacts = (valueList: IValueList[]): Contact[] =>\n    valueList.map(({ id, ...rest }) => rest as unknown as Contact);  // ✅ unknown 中转",
+            "alternativeFix": "// 或显式字段映射(更类型安全):\nconst valueListToContacts = (valueList: IValueList[]): Contact[] =>\n    valueList.map(({ name, phone, email }) => ({ name, phone, email } as Contact));"
+        }
+    },
+    "titleModeBehavior": {
+        "all": "**默认值**。每列在表格顶部独立显示 IConfig.label —— '第一数据行上方有列标题'就是 all。典型表格效果",
+        "none": "完全隐藏所有标题。所有列单元格直接从表顶开始,无任何 label",
+        "single": "**整张表只有 1 个合并标题行**(跨所有列居中显示 singleTitle.label),不是'只在第一行显示列标题'。配合 singleTitle prop = `{ label: ReactNode, required: boolean }` 配置文案。**误解警告**:需求描述'只在第一行显示标题'通常想要的是 all(每列独立标题),不是 single(整表 1 个合并标题)",
+        "domStructure": "// all:\n//   <thead>列1 label | 列2 label | 列3 label</thead>\n//   <tbody>行 1 数据 | 行 2 数据 | ...</tbody>\n//\n// single:\n//   <thead>singleTitle.label (跨列居中)</thead>\n//   <tbody>行 1 数据 | 行 2 数据 | ...</tbody>\n//\n// none:\n//   <tbody>行 1 数据 | 行 2 数据 | ...</tbody>(无 thead)"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "default",
+        "error"
+    ],
+    "idealProps": {
+        "config": {
+            "type": "IConfig[]",
+            "description": "每列配置数组:[{ name, label, inputType, isFixed, required, list?, customRender? }];**name 必须等于 valueList[*][name] —— 否则该列读不到值**。注意 IConfig.name 类型签名是 `string | undefined`(R23 003 fail 根因 —— 见 r23FailingScenarios)。**inputType 是 IInputType 严格 union(必须 PascalCase · 不是 HTML lowercase)**:`'TextField' | 'Select' | 'Switch' | 'InputNumber' | 'InputLang' | 'ComboSelect' | 'DatePicker' | 'custom'`。⚠️ **不要写 inputType: 'text' / 'date' / 'select'(HTML 风格 · TS 编译报错 · runtime 不渲染)**。完整 schema 签名见 `dist/es/DynamicMultiBox/interface.d.ts`(发布产物)",
+            "required": true
+        },
+        "valueList": {
+            "type": "IValueList[]",
+            "description": "受控值集合 [{ id: string, [name]: any }];初始 id 由调用方维护;点击新增时组件 UUID 自动生成新行 id 并通过 onAdd 回填",
+            "required": true
+        },
+        "errors": {
+            "type": "IErrors[]",
+            "description": "每行错误集合,结构同 valueList,**按 id 一一对应**;无错误字段留空字符串占位。**调用方必须维护 errors state**,在 onAdd/onDelete 回调里用第二参数同步(见 wrapperPattern)"
+        },
+        "onChange": {
+            "type": "(valueList, currentItem) => void",
+            "description": "单元格值变化回调(不在新增/删除/拖拽时触发);currentItem 含 id/name/value/rowIndex 用于行内校验"
+        },
+        "onAdd": {
+            "type": "(valueList, errors) => void",
+            "description": "点击新增按钮触发;valueList 已含新行(id 由组件生成);**回调第二参数已是同步后的新 errors(含新行空占位),不要忽略**"
+        },
+        "onDelete": {
+            "type": "(valueList, errors) => void",
+            "description": "点击删除按钮触发;valueList 已剔除该行;errors 同步剔除对应行"
+        },
+        "titleMode": {
+            "type": "enum",
+            "values": [
+                "none",
+                "single",
+                "all"
+            ],
+            "default": "all",
+            "description": "见 titleModeBehavior:all=每列独立 label(常见表格效果);none=隐藏所有标题;**single=整表 1 个合并标题**(不是'只在第一行显示列标题',此处常被误解)"
+        },
+        "singleTitle": {
+            "type": "{ label: ReactNode, required: boolean }",
+            "description": "titleMode='single' 时的合并标题配置(必须传)"
+        },
+        "isSort": {
+            "type": "boolean",
+            "default": false,
+            "description": "true 启用拖拽排序;需配合 onSort 接收新顺序;拖拽时不触发 onChange"
+        },
+        "onSort": {
+            "type": "(newValueList, swapIds) => void",
+            "description": "排序回调;swapIds 是位置变动行的下标集合,非 [from,to] 对"
+        },
+        "initValue": {
+            "type": "Record<string, any>",
+            "description": "新增行字段默认值(不含 id)"
+        },
+        "isFilter": {
+            "type": "boolean",
+            "default": false,
+            "description": "true 启用列筛选下拉(用户可在 UI 中切换显示哪些列)"
+        },
+        "checkedValue": {
+            "type": "string[]",
+            "description": "配合 isFilter=true 使用 —— 当前筛选下拉中'已勾选展示'的列 key 数组。`isFilter=false`(默认)时无需传"
+        },
+        "filterConfig": {
+            "type": "IConfig[]",
+            "description": "筛选下拉中可勾选的可选列(结构同 IConfig),配合 isFilter=true + checkedValue 使用"
+        }
+    },
+    "commonMisconceptions": {
+        "M1": {
+            "wrong": "对 IConfig.name 直接做对象索引: `errRow[cfg.name] = ''`",
+            "result": "**TS2538 'Type undefined cannot be used as an index type'** —— IConfig.name 类型 `string | undefined`(R23 DynamicMultiBox-003 fail 根因)",
+            "fix": "narrow 后再索引: `if (cfg.name) errRow[cfg.name] = ''` 或 `errRow[cfg.name!] = ''`(非空断言)"
+        },
+        "M2": {
+            "wrong": "用 `{id, ...rest} = item; rest as Contact` 把 IValueList 转业务类型",
+            "result": "**TS2352 'Conversion may be a mistake because neither type sufficiently overlaps'** —— rest 是 unknown 索引签名,直接 as 业务类型被 TS 5.x 拒绝(R23 DynamicMultiBox-006 fail 根因)",
+            "fix": "用 `as unknown as Contact` 中转,或显式字段映射 `({ name, phone, email })`"
+        },
+        "M3": {
+            "wrong": "onAdd / onDelete 只接受单参数 valueList: `onAdd={(valueList) => setValueList(valueList)}`",
+            "result": "**errors state 与 valueList 不同步** —— 新行没有对应 errors 占位,该行渲染时查 errors 失败显示异常",
+            "fix": "双参数 + 双 setState: `onAdd={(valueList, errors) => { setValueList(valueList); setErrors(errors); }}`"
+        },
+        "M4": {
+            "wrong": "把 titleMode='single' 当成'只在第一行显示列标题',期望第 1 行上方有列标题、其余行无",
+            "result": "**single 实际是'整表 1 个合并标题'**(跨所有列居中),不是按行/列粒度的控制",
+            "fix": "需要'每列独立标题'(常见表格):用默认的 titleMode='all'(或不传)。需要'整表 1 合并标题':用 single + singleTitle prop"
+        },
+        "M5": {
+            "wrong": "在 fieldConfig 变化时不重置 errors state,继续用旧 errors",
+            "result": "字段集合变化后,errors 旧 key 残留,新 key 缺占位 → 渲染异常",
+            "fix": "用 useMemo 或 useEffect 监听 fieldConfig 变化,重新调用 buildEmptyErrors(valueList, fieldConfig) 重建 errors"
+        }
+    },
+    "do": [
+        "封装包装组件时,valueList + errors 都必须维护 state(双 state 联动 — 见 commonPatterns.wrapperPattern)",
+        "**onAdd / onDelete 必须接受双参数**(valueList, errors)并同时 setValueList + setErrors(M3)",
+        "**初始化 errors** 时用 narrow 写法: `if (cfg.name) errRow[cfg.name] = ''`(M1,R23 003 fail 修复)",
+        "**业务类型转换** rest 解构后用 `as unknown as Contact` 中转(M2,R23 006 fail 修复)",
+        "fieldConfig 动态变化时:重新计算 errors,避免 key 不对齐(M5)",
+        "需要每列独立标题用 titleMode='all',需要整表合并 1 个标题用 'single' + singleTitle(M4)"
+    ],
+    "dont": [
+        "行数过多时不分页",
+        "每行字段过多导致布局拥挤",
+        "**onAdd / onDelete 只接受 valueList 一个参数**(M3,errors 不同步)",
+        "**直接 `errRow[cfg.name] = ''` 不做 narrow**(M1,TS2538)",
+        "**`valueList.map(({ id, ...rest }) => rest as Contact)`** 缺 unknown 中转(M2,TS2352)",
+        "**把 titleMode='single' 当作'只第一行有标题'**(M4)"
+    ],
+    "commonPatterns": {
+        "wrapperPattern": {
+            "scenario": "封装 DynamicMultiBox 为业务组件(如 SortableStepsForm / ContactsEntryForm),外部以业务对象数组传入,内部维护 valueList + errors 双 state",
+            "code": "import React, { FC, useState, useMemo } from 'react';\nimport DynamicMultiBox from '@para-ui/core/DynamicMultiBox';\nimport type { IConfig, IErrors, IValueList } from '@para-ui/core/DynamicMultiBox/interface';\n\ninterface SortableStepsFormProps {\n    fieldConfig: IConfig[];\n    steps: Array<Record<string, any>>;\n    onStepsChange: (next: Array<Record<string, any>>) => void;\n}\n\n// 工具:把 fieldConfig 转为 errors 空占位行(M1 narrow 修法)\nconst buildEmptyErrors = (valueList: IValueList[], fieldConfig: IConfig[]): IErrors[] =>\n    valueList.map(row => {\n        const errRow: IErrors = { id: row.id };\n        fieldConfig.forEach(cfg => {\n            if (cfg.name) errRow[cfg.name] = '';  // ⚠️ narrow:cfg.name 是 string | undefined\n        });\n        return errRow;\n    });\n\nconst SortableStepsForm: FC<SortableStepsFormProps> = ({ fieldConfig, steps, onStepsChange }) => {\n    const [valueList, setValueList] = useState<IValueList[]>(steps as IValueList[]);\n    const [errors, setErrors] = useState<IErrors[]>(\n        () => buildEmptyErrors(steps as IValueList[], fieldConfig)\n    );\n\n    return (\n        <DynamicMultiBox\n            config={fieldConfig}\n            valueList={valueList}\n            errors={errors}\n            isSort\n            onChange={(next) => { setValueList(next); onStepsChange(next); }}\n            onAdd={(next, nextErrors) => {       // ✅ 必须接受双参数\n                setValueList(next);\n                setErrors(nextErrors);            // ✅ errors 同步\n                onStepsChange(next);\n            }}\n            onDelete={(next, nextErrors) => {     // ✅ 必须接受双参数\n                setValueList(next);\n                setErrors(nextErrors);\n                onStepsChange(next);\n            }}\n            onSort={(newList) => { setValueList(newList); onStepsChange(newList); }}\n        />\n    );\n};\n"
+        },
+        "businessTypeMappingPattern": {
+            "scenario": "外部以业务 Contact[] 类型受控,IValueList[] 与 Contact[] 双向映射(R23 DynamicMultiBox-006 fail 修复版本)",
+            "code": "interface Contact { name: string; phone: string; email: string; }\n\n// IN: Contact[] → IValueList[](补 id)\nconst contactsToValueList = (contacts: Contact[]): IValueList[] =>\n    contacts.map((c, i) => ({ id: String(i + 1), ...c }));\n\n// OUT: IValueList[] → Contact[](剔除 id,业务类型转换)\n// ⚠️ 关键:rest 解构后 TS 推断为 { [x: string]: unknown },要 as unknown 中转\nconst valueListToContacts = (valueList: IValueList[]): Contact[] =>\n    valueList.map(({ id, ...rest }) => rest as unknown as Contact);\n\n// 替代:显式字段映射(更类型安全,IDE 跳转友好)\nconst valueListToContactsExplicit = (valueList: IValueList[]): Contact[] =>\n    valueList.map(({ name, phone, email }) => ({ name, phone, email } as Contact));\n"
+        }
+    },
+    "events": {
+        "onChange": {
+            "signature": "(valueList: IValueList<T>[], currentItem?: ICurrentItem<T>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "同步整表值：onChange={(list) => setValueList(list)}",
+                "利用 currentItem 做行内校验：onChange={(list, cur) => { setValueList(list); validateRow(cur.rowIndex, cur.name, cur.value); }}",
+                "currentItem 包含 { name, value, rowIndex, id }——可精确定位是哪行哪字段发生了变化"
+            ],
+            "commonMistakes": [
+                "在 onChange 里同时 setErrors——onChange 只在单元格值变化时触发，不涉及 errors；errors 同步在 onAdd/onDelete 完成",
+                "假设 onChange 在新增/删除/拖拽时也触发——这三种操作分别走 onAdd/onDelete/onSort 回调",
+                "onChange 第二参数 currentItem 的 name 是 keyof T & string——与 IConfig.name 类型一致，可直接做对象索引"
+            ]
+        },
+        "onAdd": {
+            "signature": "(valueList: IValueList<T>[], errors: IErrors<T>[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "双 state 同步（必须）：onAdd={(list, errs) => { setValueList(list); setErrors(errs); }}",
+                "同时通知父组件：onAdd={(list, errs) => { setValueList(list); setErrors(errs); onStepsChange(list); }}"
+            ],
+            "commonMistakes": [
+                "只接受一个参数 valueList，忽略 errors——errors 不同步导致新行渲染异常（TS 签名有第二参数）",
+                "在 onAdd 里手动构造 errors 新行——组件已帮你构造好新行空占位 errors，直接 setErrors(errs) 即可",
+                "期望 onAdd 触发后 valueList 还是旧数据加上新行——onAdd 第一参数已是含新行的新数组"
+            ]
+        },
+        "onDelete": {
+            "signature": "(valueList: IValueList<T>[], errors: IErrors<T>[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "双 state 同步：onDelete={(list, errs) => { setValueList(list); setErrors(errs); }}",
+                "配合业务通知：onDelete={(list, errs) => { setValueList(list); setErrors(errs); onStepsChange(list); }}"
+            ],
+            "commonMistakes": [
+                "只接受 valueList 忽略 errors 第二参数——errors 不同步，行对应关系错位（id 对不上）",
+                "期望 keepLastItem=true 时最后一行也能删——keepLastItem=true（默认）时只剩 1 行时删除图标隐藏，onDelete 不触发"
+            ]
+        },
+        "onSort": {
+            "signature": "(newValueList: IValueList<T>[], swapIds?: number[]) => void",
+            "asyncSupported": false,
+            "examples": [
+                "同步排序后的顺序：onSort={(newList) => setValueList(newList)}",
+                "swapIds 是位置变动行的下标集合，不是 [from, to] 对：onSort={(newList, swapIds) => console.log(swapIds)}"
+            ],
+            "commonMistakes": [
+                "把 swapIds 当作 [fromIndex, toIndex] 对使用——实际是所有位置变动行的下标集合",
+                "onSort 里同时重建 errors——拖拽排序不改变行数，errors 的行数不变；只需按 newList 顺序重排 errors（用 rowKey 映射）",
+                "期望 isSort=true 自动维护排序——isSort 只开启 UI 拖拽，newList 必须通过 onSort 回调同步到父组件 state"
+            ]
+        },
+        "onFilter": {
+            "signature": "(data: IFilterParams<T>) => void",
+            "asyncSupported": false,
+            "examples": [
+                "监听筛选变化：onFilter={(data) => console.log(data.checkedVal, data.valueList)}",
+                "data 包含 { name, checkedVal, valueList, errors }——列筛选变化时的完整快照"
+            ],
+            "commonMistakes": [
+                "期望 isFilter=false 时 onFilter 也触发——isFilter 必须为 true 才显示筛选 UI",
+                "假设 onFilter 替代 onChange——onFilter 只在列筛选器操作时触发，单元格值变化走 onChange"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "IConfig.name 类型是 keyof T & string（可能含 undefined），直接用作对象索引报 TS2538",
+            "wrong": "const errRow: IErrors = { id: s.id };\nfieldConfig.forEach((cfg: IConfig) => {\n    errRow[cfg.name] = '';  // TS2538: 'undefined' cannot be used as an index type\n});",
+            "right": "fieldConfig.forEach((cfg: IConfig) => {\n    if (cfg.name) errRow[cfg.name] = '';  // narrow 后再索引\n    // 或：errRow[cfg.name!] = '';  // 非空断言（已知 name 必有值时）\n});"
+        },
+        {
+            "issue": "IValueList 解构后 rest 是 unknown 索引签名，直接 as 具体类型被 TS 5.x 拒绝",
+            "wrong": "const toContact = (item: IValueList): Contact =>\n    (({ id, ...rest }) => rest as Contact)(item);  // TS2352: not sufficiently overlapping",
+            "right": "const toContact = (item: IValueList): Contact =>\n    (({ id, ...rest }) => rest as unknown as Contact)(item);  // 先转 unknown 再转目标类型"
+        },
+        {
+            "issue": "IConfig.inputType 只接受 PascalCase 严格枚举，不接受 HTML 小写风格",
+            "wrong": "{ inputType: 'text' }  // 或 'date'、'select'——TS 报错，runtime 不渲染",
+            "right": "{ inputType: 'TextField' }  // 或 'Select'、'DatePicker'、'Switch'、'InputNumber'——PascalCase"
+        },
+        {
+            "issue": "onAdd/onDelete 是双参数签名，只声明单参数会导致 errors 不同步（TS 不会报错但逻辑错误）",
+            "wrong": "onAdd={(valueList) => setValueList(valueList)}  // errors 参数丢失，新行无占位",
+            "right": "onAdd={(valueList, errors) => { setValueList(valueList); setErrors(errors); }}  // 两个 state 同时同步"
+        },
+        {
+            "issue": "IMultiValueProps 是泛型 <T extends Record<string, unknown>>，使用具体业务类型时需传泛型参数",
+            "wrong": "// 不传泛型，render/onChange 里 row/currentItem 的字段是 unknown\n<DynamicMultiBox config={config} valueList={valueList} />",
+            "right": "// 传泛型，类型推断正确\nconst config: IConfig<Contact>[] = [...];\nconst valueList: IValueList<Contact>[] = [...];\n<DynamicMultiBox<Contact> config={config} valueList={valueList} />"
+        },
+        {
+            "issue": "泛型 T 必须满足 Record<string, unknown> 约束，普通 interface 没有 index signature 会报 TS2344",
+            "wrong": "interface Param { foo: string }  // 没有 index signature\n<DynamicMultiBox<Param> ... />  // TS2344: Type 'Param' does not satisfy the constraint 'Record<string, unknown>'. Index signature for type 'string' is missing in type 'Param'.",
+            "right": "interface Param { foo: string; [key: string]: unknown }  // 加 index signature\n// 或用 type 别名: type Param = { foo: string } & Record<string, unknown>\n<DynamicMultiBox<Param> ... />  // 编译通过"
+        },
+        {
+            "issue": "IConfig / IValueList 等类型必须从 @para-ui/core/DynamicMultiBox 导入,不是子路径 /interface",
+            "wrong": "import type { IConfig } from '@para-ui/core/DynamicMultiBox/interface';  // TS2307: Cannot find module",
+            "right": "import type { IConfig, IValueList } from '@para-ui/core/DynamicMultiBox';"
+        }
+    ],
+    "mapping": {
+        "realComponent": "DynamicMultiBox",
+        "adapter": null
+    }
+}

package/lib/DynamicMultiBox/formItem.d.ts

@@ -5,7 +5,7 @@ export type IFormItem = {
     /** 错误集合*/
     errors?: IErrors[];
     /**回调 */
-    onChange?: (id: string, value: any) => void;
+    onChange?: (id: string, value: unknown) => void;
     /** 渲染数据*/
     formItemProps?: IConfig;
 };

package/lib/DynamicMultiBox/rowForm.d.ts

@@ -18,9 +18,9 @@ export interface IRowForm {
      * @param value 当前组件value值
      * @param name 当前组件name
      * */
-    onFormItemChange?: (name: string, id: string, value: any) => void;
+    onFormItemChange?: (name: string, id: string, value: unknown) => void;
     /**其他*/
-    [name: string]: any;
+    [name: string]: unknown;
 }
 declare const RowForm: (props: IRowForm) => import("react/jsx-runtime").JSX.Element;
 export default RowForm;

package/lib/Empty/component.json

@@ -0,0 +1,123 @@
+{
+    "name": "Empty",
+    "category": "Data Display",
+    "description": "空状态时的展示占位符，用于无数据、无搜索结果、无权限等场景，支持自定义图片、描述文案、刷新按钮及整体替换",
+    "semantic": {
+        "intent": [
+            "展示空状态",
+            "引导操作",
+            "占位"
+        ],
+        "useCases": [
+            "无数据",
+            "无搜索结果",
+            "无权限"
+        ],
+        "riskLevel": "low"
+    },
+    "variants": {
+        "default": {
+            "meaning": "默认样式"
+        }
+    },
+    "states": [
+        "visible"
+    ],
+    "idealProps": {
+        "size": {
+            "type": "enum",
+            "values": [
+                "small",
+                "medium",
+                "large"
+            ],
+            "default": "large",
+            "description": "尺寸。三档统一为 small / medium / large(2026-05-08 跨组件命名 epic §3.1 选项 B 实施,medium 为新增视觉档,默认 large 不变,既有 small/large 调用零回归)"
+        },
+        "image": {
+            "type": "ReactNode | string",
+            "description": "自定义图片节点。传字符串时渲染为 <img src={image}>,传 ReactNode 时直接渲染。**不传时按 size 自动选内置图：small=SmallNull, medium/large=LargeNull**"
+        },
+        "description": {
+            "type": "ReactNode | string",
+            "description": "自定义描述内容；不传时显示国际化默认文案（zh_CN='暂无内容'）"
+        },
+        "imageStyle": {
+            "type": "object",
+            "objectShape": {
+                "height": { "type": "string | number", "description": "图片高度" },
+                "width": { "type": "string | number", "description": "图片宽度" }
+            },
+            "completeExample": "{ height: 60 }",
+            "description": "图片区域内联样式（React.CSSProperties 子集）"
+        },
+        "showRefresh": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否显示刷新按钮；配合 onRefresh 使用"
+        },
+        "onRefresh": {
+            "type": "(event: React.MouseEvent) => void",
+            "description": "点击刷新按钮回调；仅 showRefresh=true 时展示触发"
+        },
+        "customEmpty": {
+            "type": "ReactNode",
+            "description": "**完整替换**整个空状态内容（包括图片 + 描述），传入后 image / description / showRefresh 全部不渲染（src/Empty/index.tsx 90 行 if(customEmpty) 分支实证）"
+        },
+        "className": {
+            "type": "string",
+            "description": "外层容器自定义类名"
+        },
+        "style": {
+            "type": "React.CSSProperties",
+            "description": "外层容器 style"
+        }
+    },
+    "do": [
+        "在无数据时提供 Empty 状态",
+        "提供引导操作：配合 showRefresh + onRefresh 增加刷新入口",
+        "需要完整自定义布局时使用 customEmpty 整体替换",
+        "size 默认 large，需要紧凑展示（如表格内嵌）时用 small"
+    ],
+    "dont": [
+        "在 Loading 时显示 Empty——应先消除 Loading 遮罩再渲染 Empty",
+        "同时传 customEmpty 和 description/image——customEmpty 会覆盖后者，造成困惑"
+    ],
+    "events": {
+        "onRefresh": {
+            "signature": "(event: React.MouseEvent) => void",
+            "asyncSupported": false,
+            "examples": [
+                "showRefresh={true} onRefresh={() => fetchData()} — 点击刷新文字触发重新请求",
+                "onRefresh={(e) => { e.stopPropagation(); reload(); }} — 阻止冒泡后重载",
+                "配合 loading state：onRefresh={() => { setLoading(true); fetch().finally(() => setLoading(false)); }}"
+            ],
+            "commonMistakes": [
+                "不传 showRefresh={true} 只传 onRefresh — 刷新按钮不会渲染，回调永不触发",
+                "期望点击图片触发 onRefresh — 只有文字区域的刷新链接触发，图片无点击事件",
+                "异步刷新后没有给用户反馈（Loading 状态）— 应结合父组件 loading 状态"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "image prop 类型是 ReactNode | string，传 null 会触发 TS2322",
+            "wrong": "const img: React.ReactNode | null = getImg(); <Empty image={img} /> // 可能 null，TS 报错",
+            "right": "const img = getImg(); <Empty image={img ?? undefined} /> // 用 undefined 替代 null"
+        },
+        {
+            "issue": "description 类型是 ReactNode，不支持 false/null 显式传递",
+            "wrong": "<Empty description={null} /> // 期望显示默认文案，但 null 在 ReactNode 中合法，结果不渲染描述区域",
+            "right": "<Empty /> // 不传 description 时自动用国际化默认文案（'暂无内容'）"
+        },
+        {
+            "issue": "customEmpty 传入后 image/description/showRefresh 均不生效——源码 if(customEmpty) 分支直接 return customEmpty",
+            "wrong": "<Empty customEmpty={<CustomUI />} description='还有数据哦' /> // description 被 customEmpty 覆盖",
+            "right": "// 要自定义描述同时用 customEmpty：把描述塞进 customEmpty 里\n<Empty customEmpty={<><CustomUI /><p>还有数据哦</p></>} />"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Empty",
+        "adapter": null
+    }
+}

package/lib/Empty/index.css

@@ -1 +1 @@
-@charset "UTF-8";.paraui-v4-empty{display:inline-flex;flex-direction:column;align-items:center}.paraui-v4-empty>.empty-image{line-height:0;overflow:hidden}.paraui-v4-empty>.empty-image img{width:100%}.paraui-v4-empty .empty-image-large{width:334px;height:238px}.paraui-v4-empty .empty-image-small{width:120px;height:120px}.paraui-v4-empty>.empty-description{line-height:17px;font-size:14px;font-weight:400;color:#5c6573}.paraui-v4-empty>.empty-description>.empty-description-refresh{display:inline-block}.paraui-v4-empty>.empty-description>.empty-description-refresh span{color:#2e65e6;cursor:pointer}.paraui-v4-empty>.empty-description>.empty-description-refresh span:hover{color:#5783eb}.paraui-v4-empty.paraui-v4-empty-large>.empty-description{margin-top:20px}.paraui-v4-empty.paraui-v4-empty-small>.empty-description{margin-top:10px;font-size:14px}
+@charset "UTF-8";.paraui-v4-empty{display:inline-flex;flex-direction:column;align-items:center}.paraui-v4-empty>.empty-image{overflow:hidden;line-height:0}.paraui-v4-empty>.empty-image img{width:100%}.paraui-v4-empty .empty-image-large{width:334px;height:238px}.paraui-v4-empty .empty-image-medium{width:220px;height:180px}.paraui-v4-empty .empty-image-small{width:120px;height:120px}.paraui-v4-empty>.empty-description{font-size:14px;font-weight:400;line-height:17px;color:#5c6573}.paraui-v4-empty>.empty-description>.empty-description-refresh{display:inline-block}.paraui-v4-empty>.empty-description>.empty-description-refresh span{color:#2e65e6;cursor:pointer}.paraui-v4-empty>.empty-description>.empty-description-refresh span:hover{color:#5783eb}.paraui-v4-empty.paraui-v4-empty-large>.empty-description{margin-top:20px}.paraui-v4-empty.paraui-v4-empty-medium>.empty-description{margin-top:15px;font-size:14px}.paraui-v4-empty.paraui-v4-empty-small>.empty-description{margin-top:10px;font-size:14px}

package/lib/Empty/index.d.ts

@@ -5,7 +5,7 @@ export interface EmptyProps {
     /** style */
     style?: React.CSSProperties;
     /** 尺寸 */
-    size?: 'large' | 'small';
+    size?: 'small' | 'medium' | 'large';
     /** 图片样式 */
     imageStyle?: React.CSSProperties;
     /** 图片 */
@@ -18,7 +18,7 @@ export interface EmptyProps {
     onRefresh?: (event: React.MouseEvent) => void;
     /** 自定义空节点 */
     customEmpty?: React.ReactNode;
-    [name: string]: any;
+    [name: string]: unknown;
 }
 declare const Empty: FC<EmptyProps>;
 export default Empty;

package/lib/Empty/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"),R=require("clsx"),a=require("./images/index.js"),h=require("../GlobalContext/useFormatMessage.js"),N=require("./lang/index.js"),q=require("../Hooks/useGlobalProps.js"),c=require("../GlobalContext/constant.js");;/* empty css            */const $={large:e.jsxRuntimeExports.jsx(a.LargeNull,{}),small:e.jsxRuntimeExports.jsx(a.SmallNull,{})},v=l=>{const{className:u,style:x,size:t="large",imageStyle:p,image:i=$[t],description:o,showRefresh:d=!1,onRefresh:j,customEmpty:m}=q.default(l,"Empty"),r=h.default("Empty",N.default),f=E=>{j?.(E)},s=typeof o<"u"?o:r({id:"noData"}),g=typeof s=="string"?s:"empty";let n=null;const y=d?e.jsxRuntimeExports.jsxs("span",{className:"empty-description-refresh",children:[r({id:"click"}),e.jsxRuntimeExports.jsx("span",{onClick:f,children:r({id:"refresh"})})]}):null;return typeof i=="string"?n=e.jsxRuntimeExports.jsx("img",{src:i,alt:g}):n=i,e.jsxRuntimeExports.jsx("div",{className:R(`${c.$prefixCls}-empty`,u,`${c.$prefixCls}-empty-${t}`),style:x,children:m||e.jsxRuntimeExports.jsxs(e.jsxRuntimeExports.Fragment,{children:[e.jsxRuntimeExports.jsx("div",{className:`empty-image ${l?.image?"":`empty-image-${t}`}`,style:p,children:n}),s&&e.jsxRuntimeExports.jsxs("div",{className:"empty-description",children:[e.jsxRuntimeExports.jsx(e.jsxRuntimeExports.Fragment,{children:s}),y]})]})})};exports.default=v;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});require('./index.css');const e=require("../_virtual/jsx-runtime.js"),R=require("clsx"),l=require("./images/index.js"),h=require("../GlobalContext/useFormatMessage.js"),N=require("./lang/index.js"),q=require("../Hooks/useGlobalProps.js"),u=require("../GlobalContext/constant.js");;/* empty css            */const $={large:e.jsxRuntimeExports.jsx(l.LargeNull,{}),medium:e.jsxRuntimeExports.jsx(l.LargeNull,{}),small:e.jsxRuntimeExports.jsx(l.SmallNull,{})},v=o=>{const{className:x,style:c,size:t="large",imageStyle:p,image:i=$[t],description:m,showRefresh:d=!1,onRefresh:j,customEmpty:a}=q.default(o,"Empty"),r=h.default("Empty",N.default),g=E=>{j?.(E)},s=typeof m<"u"?m:r({id:"noData"}),f=typeof s=="string"?s:"empty";let n=null;const y=d?e.jsxRuntimeExports.jsxs("span",{className:"empty-description-refresh",children:[r({id:"click"}),e.jsxRuntimeExports.jsx("span",{onClick:g,children:r({id:"refresh"})})]}):null;return typeof i=="string"?n=e.jsxRuntimeExports.jsx("img",{src:i,alt:f}):n=i,e.jsxRuntimeExports.jsx("div",{className:R(`${u.$prefixCls}-empty`,x,`${u.$prefixCls}-empty-${t}`),style:c,children:a||e.jsxRuntimeExports.jsxs(e.jsxRuntimeExports.Fragment,{children:[e.jsxRuntimeExports.jsx("div",{className:`empty-image ${o?.image?"":`empty-image-${t}`}`,style:p,children:n}),s&&e.jsxRuntimeExports.jsxs("div",{className:"empty-description",children:[e.jsxRuntimeExports.jsx(e.jsxRuntimeExports.Fragment,{children:s}),y]})]})})};exports.default=v;
 //# sourceMappingURL=index.js.map

package/lib/Empty/style/index.css

@@ -1 +1 @@
-.paraui-v4-empty{display:inline-flex;flex-direction:column;align-items:center}.paraui-v4-empty>.empty-image{line-height:0;overflow:hidden}.paraui-v4-empty>.empty-image img{width:100%}.paraui-v4-empty .empty-image-large{width:334px;height:238px}.paraui-v4-empty .empty-image-small{width:120px;height:120px}.paraui-v4-empty>.empty-description{line-height:17px;font-size:14px;font-weight:400;color:#5c6573}.paraui-v4-empty>.empty-description>.empty-description-refresh{display:inline-block}.paraui-v4-empty>.empty-description>.empty-description-refresh span{color:#2e65e6;cursor:pointer}.paraui-v4-empty>.empty-description>.empty-description-refresh span:hover{color:#5783eb}.paraui-v4-empty.paraui-v4-empty-large>.empty-description{margin-top:20px}.paraui-v4-empty.paraui-v4-empty-small>.empty-description{margin-top:10px;font-size:14px}
+.paraui-v4-empty{display:inline-flex;flex-direction:column;align-items:center}.paraui-v4-empty>.empty-image{overflow:hidden;line-height:0}.paraui-v4-empty>.empty-image img{width:100%}.paraui-v4-empty .empty-image-large{width:334px;height:238px}.paraui-v4-empty .empty-image-medium{width:220px;height:180px}.paraui-v4-empty .empty-image-small{width:120px;height:120px}.paraui-v4-empty>.empty-description{font-size:14px;font-weight:400;line-height:17px;color:#5c6573}.paraui-v4-empty>.empty-description>.empty-description-refresh{display:inline-block}.paraui-v4-empty>.empty-description>.empty-description-refresh span{color:#2e65e6;cursor:pointer}.paraui-v4-empty>.empty-description>.empty-description-refresh span:hover{color:#5783eb}.paraui-v4-empty.paraui-v4-empty-large>.empty-description{margin-top:20px}.paraui-v4-empty.paraui-v4-empty-medium>.empty-description{margin-top:15px;font-size:14px}.paraui-v4-empty.paraui-v4-empty-small>.empty-description{margin-top:10px;font-size:14px}