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

package/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/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/ExpressionInput/component.json

@@ -0,0 +1,79 @@
+{
+  "name": "ExpressionInput",
+  "category": "数据录入",
+  "description": "单行表达式变量自动补全输入框,默认要求 {{ }} 包裹触发,候选数据完全由业务方通过 resolveCandidates 注入。",
+  "semantic": {
+    "intent": ["在文本中输入引用变量的表达式", "按命名空间层级下钻选择变量"],
+    "useCases": ["脚本/配置里引用运行时变量", "低代码画布属性面板里的表达式绑定"],
+    "riskLevel": "low"
+  },
+  "variants": {
+    "braces": { "meaning": "默认触发模式,要求光标位于 {{ }} 区间内才弹出候选" },
+    "bare": { "meaning": "不要求大括号包裹,任意位置匹配 triggerPrefix 即弹出候选" }
+  },
+  "states": ["default", "focus", "disabled", "readOnly", "popup-open"],
+  "idealProps": {
+    "value": { "type": "string", "description": "受控值", "required": false },
+    "onChange": { "type": "function", "description": "值变化回调", "signature": "(value: string) => void" },
+    "resolveCandidates": {
+      "type": "function",
+      "description": "按命名空间路径返回该层级的完整候选列表,组件内部按 parts 缓存",
+      "signature": "(parts: string[]) => ExprCandidate[]",
+      "required": true
+    },
+    "triggerMode": {
+      "type": "string",
+      "description": "触发匹配机制",
+      "values": ["braces", "bare"],
+      "default": "braces"
+    },
+    "triggerPrefix": { "type": "string", "description": "触发前缀符号", "default": "$" },
+    "virtualizeThreshold": { "type": "number", "description": "候选数超过该阈值启用虚拟滚动", "default": "50" },
+    "renderPopupHeader": {
+      "type": "function",
+      "description": "自定义浮层 header 文案",
+      "signature": "(ctx: ExprChainCtx, count: number) => React.ReactNode",
+      "required": false
+    },
+    "expressionTooltip": {
+      "type": "ReactNode",
+      "description": "表达式说明 tooltip 文案,不传则不展示;仅当 value 命中表达式格式(braces/bare)时 hover/focus 才弹出",
+      "required": false
+    }
+  },
+  "commonMisconceptions": [
+    "以为 resolveCandidates 每次按键都会被调用——实际只有下钻/回退到新的命名空间层级时才调用,同层级内逐字过滤是客户端完成的",
+    "以为默认触发不需要 {{ }} 包裹——默认 triggerMode 是 'braces',裸写 $.xxx 不会触发,需要显式传 triggerMode='bare' 才对齐 Ditto 原始行为",
+    "以为传入的 candidate.value 可以是任意字符串——实际必须是合法标识符字符([A-Za-z0-9_$]),否则插入后再次解析会被截断",
+    "以为 expressionTooltip 会随打字实时弹出/消失——实际是否命中只在 hover/focus 触发那一刻判定,光标停留期间继续输入使 value 从未命中变为命中不会自动弹出,需要重新 hover/focus",
+    "以为花括号着色和 expressionTooltip 用同一套判定标准——实际着色只看 {{ }} 是否配对闭合,不校验内容合法性,门槛比 expressionTooltip 低,{{$.}} 这类值会着色但不会弹出 tooltip,两者可能不一致,这是预期行为"
+  ],
+  "do": [
+    "为需要继续下钻子级的候选项设置 chain: true,让选中后自动追加 . 方便连续输入",
+    "为敏感字段设置 sensitive: true,组件会自动展示锁图标",
+    "在 Modal/Drawer 中使用时无需额外处理,组件内部已对接 usePopupContainer 自动寻找最近可滚动祖先容器"
+  ],
+  "dont": [
+    "不要在 resolveCandidates 内部做未做缓存的重量级计算并假设组件会防抖——组件只在 parts 变化时调用一次,但单次调用本身仍需业务方保证足够快",
+    "不要给多个实例传相同的 DOM id 或手动操作 document.body 上的浮层 — 组件已经用 UUID 做了实例隔离"
+  ],
+  "events": {
+    "onChange": {
+      "signature": "(value: string) => void",
+      "asyncSupported": false,
+      "examples": ["受控更新 value 状态"],
+      "commonMistakes": ["忘记把新 value 传回 props.value,导致组件表现为不可编辑"]
+    }
+  },
+  "typescriptPitfalls": [
+    {
+      "issue": "resolveCandidates 类型签名从 ChainCtx 变成了 parts: string[]",
+      "wrong": "resolveCandidates={(ctx) => ctx.partial ? [] : rootCandidates}",
+      "right": "resolveCandidates={(parts) => parts.length === 0 ? rootCandidates : []}"
+    }
+  ],
+  "mapping": {
+    "realComponent": "ExpressionInput",
+    "adapter": "无,直接使用"
+  }
+}