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

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}

package/lib/FieldForm/FieldFormItem/ItemHolder.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const t=require("../../_virtual/jsx-runtime.js"),n=require("react"),F=require("../../_virtual/index2.js"),H=require("rc-util/lib/Dom/isVisible"),N=require("rc-util/lib/hooks/useLayoutEffect"),h=require("../context.js"),O=require("../FormItemLabel.js"),T=require("../FormItemInput.js"),V=require("./StatusProvider.js");function W(a){const{className:p,style:b,helperText:o,errors:c,warnings:d,status:e,hidden:j,children:y,fieldId:r,required:q,onSubItemMetaChange:S,layout:m,hideLabel:v,hideError:E,noSpacing:I,label:R,labelProps:C,labelAlign:L,colon:M,labelWidth:P,labelWrap:_}=a,{prefixCls:i,layout:x}=n.useContext(h.FormContext),l=n.useMemo(()=>m??x,[m,x]),s=n.useRef(null),f=!!(o!=null||c.length||d.length),$=!!s.current&&H(s.current),[w,g]=n.useState(null);N(()=>{if(f&&s.current){const u=getComputedStyle(s.current);g(parseInt(u.marginBottom,10))}},[f,$]);const B=u=>{u||g(null)};return t.jsxRuntimeExports.jsx(V.default,{...a,prefixCls:i,children:t.jsxRuntimeExports.jsxs("div",{className:F.default(p,`${i}-item`,{[`${i}-item__${r}`]:r,"is-success":e==="success","is-warning":e==="warning","is-error":e==="error","is-validating":e==="validating","is-hidden":j,[`is-${l}`]:l}),style:b,children:[t.jsxRuntimeExports.jsx(O.default,{fieldId:r,label:R,labelWidth:P,labelWrap:_,labelAlign:L,colon:M,labelProps:{required:q,...C},hideLabel:v,layout:l}),t.jsxRuntimeExports.jsx(T.default,{fieldId:r,errors:c,warnings:d,status:e,helperText:o,marginBottom:w,onErrorVisibleChanged:B,hideError:E,noSpacing:I,children:t.jsxRuntimeExports.jsx(h.NoStyleItemContext.Provider,{value:S,children:y})})]})})}exports.default=W;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const t=require("../../_virtual/jsx-runtime.js"),n=require("react"),F=require("../../_virtual/index.js"),H=require("rc-util/lib/Dom/isVisible"),N=require("rc-util/lib/hooks/useLayoutEffect"),h=require("../context.js"),O=require("../FormItemLabel.js"),T=require("../FormItemInput.js"),V=require("./StatusProvider.js");function W(a){const{className:p,style:b,helperText:o,errors:c,warnings:d,status:e,hidden:j,children:y,fieldId:r,required:q,onSubItemMetaChange:S,layout:m,hideLabel:v,hideError:E,noSpacing:I,label:R,labelProps:C,labelAlign:L,colon:M,labelWidth:P,labelWrap:_}=a,{prefixCls:i,layout:x}=n.useContext(h.FormContext),l=n.useMemo(()=>m??x,[m,x]),s=n.useRef(null),f=!!(o!=null||c.length||d.length),$=!!s.current&&H(s.current),[w,g]=n.useState(null);N(()=>{if(f&&s.current){const u=getComputedStyle(s.current);g(parseInt(u.marginBottom,10))}},[f,$]);const B=u=>{u||g(null)};return t.jsxRuntimeExports.jsx(V.default,{...a,prefixCls:i,children:t.jsxRuntimeExports.jsxs("div",{className:F.default(p,`${i}-item`,{[`${i}-item__${r}`]:r,"is-success":e==="success","is-warning":e==="warning","is-error":e==="error","is-validating":e==="validating","is-hidden":j,[`is-${l}`]:l}),style:b,children:[t.jsxRuntimeExports.jsx(O.default,{fieldId:r,label:R,labelWidth:P,labelWrap:_,labelAlign:L,colon:M,labelProps:{required:q,...C},hideLabel:v,layout:l}),t.jsxRuntimeExports.jsx(T.default,{fieldId:r,errors:c,warnings:d,status:e,helperText:o,marginBottom:w,onErrorVisibleChanged:B,hideError:E,noSpacing:I,children:t.jsxRuntimeExports.jsx(h.NoStyleItemContext.Provider,{value:S,children:y})})]})})}exports.default=W;
 //# sourceMappingURL=ItemHolder.js.map

package/lib/FieldForm/FieldFormItem/MemoInput.d.ts

@@ -1,9 +1,9 @@
 import { default as React } from 'react';
 interface MemoInputProps {
     control: object;
-    update: any;
+    update: unknown;
     children: React.ReactNode;
-    childProps: any[];
+    childProps: unknown[];
 }
 declare const _default: React.MemoExoticComponent<({ children }: MemoInputProps) => JSX.Element>;
 export default _default;

package/lib/FieldForm/FieldFormItem/StatusProvider.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const o=require("../../_virtual/jsx-runtime.js"),l=require("react"),j=require("../../node_modules/@para-ui/icons/Loading/index.js"),C=require("../../node_modules/@para-ui/icons/CheckCircleF/index.js"),g=require("../../node_modules/@para-ui/icons/CloseCircleF/index.js"),k=require("../../node_modules/@para-ui/icons/WarningCircleF/index.js"),v=require("../../_virtual/index2.js"),x=require("../context.js"),$=require("../util.js"),S={success:C.CheckCircleF,warning:k.WarningCircleF,error:g.CloseCircleF,validating:j.Loading};function R({children:I,errors:r,warnings:s,hasFeedback:e,validateStatus:p,prefixCls:u,meta:f,noStyle:c}){const t=$.getStatus(r,s,f,null,!!e,p),{isFormItemInput:i,status:a,hasFeedback:q,feedbackIcon:F}=l.useContext(x.FormItemInputContext),b=l.useMemo(()=>{let d;if(e){const m=t&&S[t];d=m?o.jsxRuntimeExports.jsx("span",{className:v.default(`${u}-feedback-icon`,`${u}-feedback-icon-${t}`),children:o.jsxRuntimeExports.jsx(m,{})}):null}const n={status:t||"",errors:r,warnings:s,hasFeedback:!!e,feedbackIcon:d,isFormItemInput:!0};return c&&(n.status=(t??a)||"",n.isFormItemInput=i,n.hasFeedback=!!(e??q),n.feedbackIcon=e!==void 0?n.feedbackIcon:F),n},[t,e,c,i,a]);return o.jsxRuntimeExports.jsx(x.FormItemInputContext.Provider,{value:b,children:I})}exports.default=R;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const o=require("../../_virtual/jsx-runtime.js"),l=require("react"),j=require("../../node_modules/@para-ui/icons/Loading/index.js"),C=require("../../node_modules/@para-ui/icons/CheckCircleF/index.js"),g=require("../../node_modules/@para-ui/icons/CloseCircleF/index.js"),k=require("../../node_modules/@para-ui/icons/WarningCircleF/index.js"),v=require("../../_virtual/index.js"),x=require("../context.js"),$=require("../util.js"),S={success:C.CheckCircleF,warning:k.WarningCircleF,error:g.CloseCircleF,validating:j.Loading};function R({children:I,errors:r,warnings:s,hasFeedback:e,validateStatus:p,prefixCls:u,meta:f,noStyle:c}){const t=$.getStatus(r,s,f,null,!!e,p),{isFormItemInput:i,status:a,hasFeedback:q,feedbackIcon:F}=l.useContext(x.FormItemInputContext),b=l.useMemo(()=>{let d;if(e){const m=t&&S[t];d=m?o.jsxRuntimeExports.jsx("span",{className:v.default(`${u}-feedback-icon`,`${u}-feedback-icon-${t}`),children:o.jsxRuntimeExports.jsx(m,{})}):null}const n={status:t||"",errors:r,warnings:s,hasFeedback:!!e,feedbackIcon:d,isFormItemInput:!0};return c&&(n.status=(t??a)||"",n.isFormItemInput=i,n.hasFeedback=!!(e??q),n.feedbackIcon=e!==void 0?n.feedbackIcon:F),n},[t,e,c,i,a]);return o.jsxRuntimeExports.jsx(x.FormItemInputContext.Provider,{value:b,children:I})}exports.default=R;
 //# sourceMappingURL=StatusProvider.js.map

package/lib/FieldForm/FieldFormItem/index.d.ts

@@ -6,9 +6,9 @@ import { FormItemInputProps } from '../FormItemInput';
 import { FormItemLabelProps } from '../FormItemLabel';
 import { ReportMetaChange } from '../context';
 import { default as useFormItemStatus } from '../hooks/useFormItemStatus';
-type RenderChildren<Values = any> = (form: FormInstance<Values>) => ReactNode;
-type RcFieldProps<Values = any> = Omit<FieldProps<Values>, 'children'>;
-type ChildrenType<Values = any> = RenderChildren<Values> | ReactNode;
+type RenderChildren<Values = unknown> = (form: FormInstance<Values>) => ReactNode;
+type RcFieldProps<Values = unknown> = Omit<FieldProps<Values>, 'children'>;
+type ChildrenType<Values = unknown> = RenderChildren<Values> | ReactNode;
 declare const ValidateStatuses: readonly ["success", "warning", "error", "validating", ""];
 export type ValidateStatus = (typeof ValidateStatuses)[number];
 export type FeedbackIcons = (itemStatus: {
@@ -18,7 +18,7 @@ export type FeedbackIcons = (itemStatus: {
 }) => {
     [key in ValidateStatus]?: ReactNode;
 };
-export interface FormItemProps<Values = any> extends FormItemLabelProps, FormItemInputProps, RcFieldProps<Values> {
+export interface FormItemProps<Values = unknown> extends FormItemLabelProps, FormItemInputProps, RcFieldProps<Values> {
     noStyle?: boolean;
     style?: CSSProperties;
     className?: string;
@@ -28,7 +28,7 @@ export interface FormItemProps<Values = any> extends FormItemLabelProps, FormIte
     validateStatus?: ValidateStatus;
     required?: boolean;
     hidden?: boolean;
-    initialValue?: any;
+    initialValue?: unknown;
     messageVariables?: Record<string, string>;
     layout?: FormItemLayout;
     hideError?: boolean;
@@ -45,7 +45,7 @@ export interface ItemHolderProps extends FormItemProps {
     isRequired?: boolean;
     onSubItemMetaChange: ReportMetaChange;
 }
-declare function InternalFormItem<Values = any>(props: FormItemProps<Values>): ReactElement;
+declare function InternalFormItem<Values = unknown>(props: FormItemProps<Values>): ReactElement;
 type InternalFormItemType = typeof InternalFormItem;
 type CompoundedComponent = InternalFormItemType & {
     useStatus: typeof useFormItemStatus;

package/lib/FieldForm/Form.d.ts

@@ -10,7 +10,7 @@ export type RequiredMark = boolean | 'optional' | ((labelNode: ReactNode, info:
 }) => ReactNode);
 export type FormLayout = 'horizontal' | 'vertical';
 export type FormItemLayout = 'horizontal' | 'vertical';
-export interface FormProps<Values = any> extends Omit<RcFormProps<Values>, 'form'> {
+export interface FormProps<Values = unknown> extends Omit<RcFormProps<Values>, 'form'> {
     colon?: boolean;
     name?: string;
     layout?: FormLayout;
@@ -23,6 +23,6 @@ export interface FormProps<Values = any> extends Omit<RcFormProps<Values>, 'form
     requiredMark?: RequiredMark;
     size?: 'small' | 'medium' | 'large';
 }
-declare const FieldForm: (<Values = any>(props: PropsWithChildren<FormProps<Values>> & RefAttributes<FormRef<Values>>) => ReactElement) & Pick<FC, "displayName">;
+declare const FieldForm: (<Values = unknown>(props: PropsWithChildren<FormProps<Values>> & RefAttributes<FormRef<Values>>) => ReactElement) & Pick<FC, "displayName">;
 export { useForm, useWatch, type FormInstance };
 export default FieldForm;

package/lib/FieldForm/Form.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const i=require("../_virtual/jsx-runtime.js"),e=require("react"),A=require("../_virtual/index2.js"),v=require("rc-field-form"),w=require("../GlobalContext/constant.js"),R=require("./hooks/useForm.js"),p=require("./context.js"),z=require("./lang/index.js"),O=require("../GlobalContext/index.js"),u=`${w.$prefixCls}-field-form`,V=(W,q)=>{const{className:E,disabled:c,form:M,colon:m,labelAlign:d,labelWidth:n,labelWrap:g,layout:f="vertical",onFinishFailed:j,name:r,style:y,size:x,..._}=W,[l,C]=e.useState(0),{language:b}=e.useContext(O.default),L=e.useMemo(()=>z.defaultValidateMessages[b||"zh"],[b]),[s]=R.default(M),{__INTERNAL__:h}=s;h.name=r;const o=e.useRef(null);e.useImperativeHandle(q,()=>({...s,nativeElement:o.current?.nativeElement}));const I=t=>{j?.(t)},P=t=>{if(!t)return;const $=t.querySelectorAll(`.${u}-item`);let a=0;$?.forEach(N=>{const F=N.querySelector("label");if(F){const T=F.offsetWidth;a=Math.max(a,T)}}),C(a)};e.useEffect(()=>{const t=setTimeout(()=>{P(o.current?.nativeElement)},0);return()=>clearTimeout(t)},[]);const S=e.useMemo(()=>({name:r,labelAlign:d,labelWrap:n?g:!1,labelWidth:n||l,labelMaxWidth:l,layout:f,colon:m,itemRef:h.itemRef,form:s,prefixCls:u,disabled:c,size:x}),[r,d,f,m,s,c,l,n,x]);return i.jsxRuntimeExports.jsx(p.FormProvider,{validateMessages:L,children:i.jsxRuntimeExports.jsx(p.FormContext.Provider,{value:S,children:i.jsxRuntimeExports.jsx(v,{id:r,..._,name:r,onFinishFailed:I,form:s,ref:o,className:A.default(E,u),style:{...y}})})})},G=e.forwardRef(V);Object.defineProperty(exports,"useWatch",{enumerable:!0,get:()=>v.useWatch});exports.useForm=R.default;exports.default=G;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const i=require("../_virtual/jsx-runtime.js"),e=require("react"),A=require("../_virtual/index.js"),v=require("rc-field-form"),w=require("../GlobalContext/constant.js"),R=require("./hooks/useForm.js"),p=require("./context.js"),z=require("./lang/index.js"),O=require("../GlobalContext/index.js"),u=`${w.$prefixCls}-field-form`,V=(W,q)=>{const{className:E,disabled:c,form:M,colon:m,labelAlign:d,labelWidth:n,labelWrap:g,layout:f="vertical",onFinishFailed:j,name:r,style:y,size:x,..._}=W,[l,C]=e.useState(0),{language:b}=e.useContext(O.default),L=e.useMemo(()=>z.defaultValidateMessages[b||"zh"],[b]),[s]=R.default(M),{__INTERNAL__:h}=s;h.name=r;const o=e.useRef(null);e.useImperativeHandle(q,()=>({...s,nativeElement:o.current?.nativeElement}));const I=t=>{j?.(t)},P=t=>{if(!t)return;const $=t.querySelectorAll(`.${u}-item`);let a=0;$?.forEach(N=>{const F=N.querySelector("label");if(F){const T=F.offsetWidth;a=Math.max(a,T)}}),C(a)};e.useEffect(()=>{const t=setTimeout(()=>{P(o.current?.nativeElement)},0);return()=>clearTimeout(t)},[]);const S=e.useMemo(()=>({name:r,labelAlign:d,labelWrap:n?g:!1,labelWidth:n||l,labelMaxWidth:l,layout:f,colon:m,itemRef:h.itemRef,form:s,prefixCls:u,disabled:c,size:x}),[r,d,f,m,s,c,l,n,x]);return i.jsxRuntimeExports.jsx(p.FormProvider,{validateMessages:L,children:i.jsxRuntimeExports.jsx(p.FormContext.Provider,{value:S,children:i.jsxRuntimeExports.jsx(v,{id:r,..._,name:r,onFinishFailed:I,form:s,ref:o,className:A.default(E,u),style:{...y}})})})},G=e.forwardRef(V);Object.defineProperty(exports,"useWatch",{enumerable:!0,get:()=>v.useWatch});exports.useForm=R.default;exports.default=G;
 //# sourceMappingURL=Form.js.map

package/lib/FieldForm/FormItemInput.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const e=require("../_virtual/jsx-runtime.js"),h=require("react"),m=require("../_virtual/index2.js"),p=require("./ErrorList.js"),j=require("./context.js"),g=x=>{const{fieldId:l,children:a,errors:r,warnings:s,status:t,helperText:i,marginBottom:o,onErrorVisibleChanged:c,hideError:u,noSpacing:d=!1}=x,{prefixCls:n}=h.useContext(j.FormContext);return e.jsxRuntimeExports.jsxs("div",{className:m.default(`${n}-content`,{[`${n}-content__${l}`]:l,"has-spacing":!d,"has-helper-text":!u&&!!(r.length||s.length||i&&(t==="error"||t==="warning"))}),children:[e.jsxRuntimeExports.jsx("div",{className:`${n}-control-input`,children:e.jsxRuntimeExports.jsx("div",{className:`${n}-control-input-content`,children:a})}),e.jsxRuntimeExports.jsx("div",{className:`${n}-helper-text`,children:!u&&(o!==null||r.length||s.length||i&&(t==="error"||t==="warning"))?e.jsxRuntimeExports.jsxs(e.jsxRuntimeExports.Fragment,{children:[e.jsxRuntimeExports.jsx(p.default,{errors:r,warnings:s,helperText:i,helpStatus:t,onVisibleChanged:c}),!!o&&e.jsxRuntimeExports.jsx("div",{style:{width:0,height:o}})]}):null})]})};exports.default=g;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const e=require("../_virtual/jsx-runtime.js"),h=require("react"),m=require("../_virtual/index.js"),p=require("./ErrorList.js"),j=require("./context.js"),g=x=>{const{fieldId:l,children:a,errors:r,warnings:s,status:t,helperText:i,marginBottom:o,onErrorVisibleChanged:c,hideError:u,noSpacing:d=!1}=x,{prefixCls:n}=h.useContext(j.FormContext);return e.jsxRuntimeExports.jsxs("div",{className:m.default(`${n}-content`,{[`${n}-content__${l}`]:l,"has-spacing":!d,"has-helper-text":!u&&!!(r.length||s.length||i&&(t==="error"||t==="warning"))}),children:[e.jsxRuntimeExports.jsx("div",{className:`${n}-control-input`,children:e.jsxRuntimeExports.jsx("div",{className:`${n}-control-input-content`,children:a})}),e.jsxRuntimeExports.jsx("div",{className:`${n}-helper-text`,children:!u&&(o!==null||r.length||s.length||i&&(t==="error"||t==="warning"))?e.jsxRuntimeExports.jsxs(e.jsxRuntimeExports.Fragment,{children:[e.jsxRuntimeExports.jsx(p.default,{errors:r,warnings:s,helperText:i,helpStatus:t,onVisibleChanged:c}),!!o&&e.jsxRuntimeExports.jsx("div",{style:{width:0,height:o}})]}):null})]})};exports.default=g;
 //# sourceMappingURL=FormItemInput.js.map

package/lib/FieldForm/FormItemLabel.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const i=require("../_virtual/jsx-runtime.js"),n=require("react"),_=require("../_virtual/index2.js"),E=require("../GlobalContext/index.js"),y=require("./context.js"),M=require("../Label/index.js"),S=({fieldId:u,label:t,labelProps:d,hideLabel:p,colon:c,layout:r,labelAlign:b,labelWidth:a,labelWrap:g})=>{const{prefixCls:s,colon:m,labelWidth:f,labelAlign:h,labelWrap:C}=n.useContext(y.FormContext),$=b||h,{language:j,locale:L}=n.useContext(E.default),o=n.useRef(null),R=e=>typeof e=="number"?`${e}px`:typeof e=="string"?e.endsWith("px")?e:`${e}px`:e,q=n.useMemo(()=>{const e=a||f||0;return e&&r==="horizontal"?R(e):"auto"},[a,f,r]),W=n.useMemo(()=>{let e=t;return(c===!0||m!==!1&&c!==!1)&&r==="horizontal"&&typeof t=="string"&&t.trim()&&(e=t.replace(/[:|：]\s*$/,"")),i.jsxRuntimeExports.jsx(i.jsxRuntimeExports.Fragment,{children:e})},[j,L,t,c,m,r]);return n.useLayoutEffect(()=>{if(o.current){const l=o.current.querySelector(`.${s}-label-comp`)?.clientHeight;if(l&&l>32){const x=(l-32)/2;o.current.style.marginTop=`-${x}px`,o.current.classList.add("is-multiline")}}},[]),p||!t?null:i.jsxRuntimeExports.jsx("div",{ref:o,className:_.default(`${s}-label`,{[`${s}-label__${u}`]:u,"is-left":$==="left"&&r==="horizontal","is-wrap":g??C??!1}),style:{width:q},children:i.jsxRuntimeExports.jsx(M.default,{className:`${s}-label-comp`,label:W,...d})})};exports.default=S;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const i=require("../_virtual/jsx-runtime.js"),n=require("react"),_=require("../_virtual/index.js"),E=require("../GlobalContext/index.js"),y=require("./context.js"),M=require("../Label/index.js"),S=({fieldId:u,label:t,labelProps:d,hideLabel:p,colon:c,layout:r,labelAlign:b,labelWidth:a,labelWrap:g})=>{const{prefixCls:s,colon:m,labelWidth:f,labelAlign:h,labelWrap:C}=n.useContext(y.FormContext),$=b||h,{language:j,locale:L}=n.useContext(E.default),o=n.useRef(null),R=e=>typeof e=="number"?`${e}px`:typeof e=="string"?e.endsWith("px")?e:`${e}px`:e,q=n.useMemo(()=>{const e=a||f||0;return e&&r==="horizontal"?R(e):"auto"},[a,f,r]),W=n.useMemo(()=>{let e=t;return(c===!0||m!==!1&&c!==!1)&&r==="horizontal"&&typeof t=="string"&&t.trim()&&(e=t.replace(/[:|：]\s*$/,"")),i.jsxRuntimeExports.jsx(i.jsxRuntimeExports.Fragment,{children:e})},[j,L,t,c,m,r]);return n.useLayoutEffect(()=>{if(o.current){const l=o.current.querySelector(`.${s}-label-comp`)?.clientHeight;if(l&&l>32){const x=(l-32)/2;o.current.style.marginTop=`-${x}px`,o.current.classList.add("is-multiline")}}},[]),p||!t?null:i.jsxRuntimeExports.jsx("div",{ref:o,className:_.default(`${s}-label`,{[`${s}-label__${u}`]:u,"is-left":$==="left"&&r==="horizontal","is-wrap":g??C??!1}),style:{width:q},children:i.jsxRuntimeExports.jsx(M.default,{className:`${s}-label-comp`,label:W,...d})})};exports.default=S;
 //# sourceMappingURL=FormItemLabel.js.map

package/lib/FieldForm/FormList.d.ts

@@ -3,7 +3,7 @@ import { StoreValue, ValidatorRule } from 'rc-field-form/lib/interface';
 export interface FormListFieldData {
     name: number;
     key: number;
-    error?: any;
+    error?: unknown;
 }
 export interface FormListOperation {
     add: (defaultValue?: StoreValue, insertIndex?: number) => void;
@@ -13,7 +13,7 @@ export interface FormListOperation {
 export interface FormListProps {
     name: string | number | (string | number)[];
     rules?: ValidatorRule[];
-    initialValue?: any[];
+    initialValue?: unknown[];
     children: (fields: FormListFieldData[], operation: FormListOperation, meta: {
         errors: ReactNode[];
         warnings: ReactNode[];

package/lib/FieldForm/component.json

@@ -0,0 +1,196 @@
+{
+    "name": "FieldForm",
+    "category": "Data Entry",
+    "description": "表单组件，提供完整的表单解决方案(基于 rc-field-form;内部 cloneElement 注入 value/onChange/error 到 Item.children)",
+    "semantic": {
+        "intent": [
+            "表单管理",
+            "数据录入"
+        ],
+        "useCases": [
+            "用户注册",
+            "数据编辑",
+            "配置页面"
+        ],
+        "riskLevel": "normal"
+    },
+    "variants": {
+        "horizontal": {
+            "meaning": "水平布局"
+        },
+        "vertical": {
+            "meaning": "垂直布局"
+        }
+    },
+    "states": [
+        "default",
+        "disabled",
+        "validating",
+        "error"
+    ],
+    "idealProps": {
+        "form": {
+            "type": "FormInstance",
+            "description": "由 useForm() 创建的表单实例:`const [form] = FieldForm.useForm();` 仅在父组件需外部调用 submit/resetFields/setFieldsValue 时需要;**类型别名注意**:`FormInstance`(api.ts) ≡ `FieldFormInstance`(src/FieldForm 导出)两个名字指同一类型,推荐用 `FieldFormInstance`(更精确不与其他库混淆)"
+        },
+        "initialValues": {
+            "type": "object",
+            "objectShape": {
+                "[fieldName: string]": { "type": "any", "description": "字段名 → 初始值，例：{ username: '张三', age: 25 }" }
+            },
+            "completeExample": "{ username: '张三', email: 'zs@example.com' }",
+            "description": "表单初始默认值(仅 mount 时灌入;**后续动态变化需用 form.setFieldsValue,不能修改 initialValues prop**);典型用法 `<FieldForm initialValues={{ name: '张三', age: 25 }}>`"
+        },
+        "onFinish": {
+            "type": "(values: any) => void",
+            "description": "校验通过后触发:values 是表单全部字段的扁平对象(包含 FieldForm.Item.name 收集的所有字段);**触发时机**:点击 `<Button type=\"submit\">` 或调用 `form.submit()` 后,内部跑校验通过 → onFinish"
+        },
+        "onFinishFailed": {
+            "type": "({ values, errorFields, outOfDate }) => void",
+            "description": "校验失败后触发;errorFields 是失败字段数组"
+        },
+        "layout": {
+            "type": "enum",
+            "values": [
+                "horizontal",
+                "vertical"
+            ],
+            "default": "vertical",
+            "description": "vertical=label 在字段上方(默认,省略即生效);horizontal=label 在左侧"
+        },
+        "children": {
+            "type": "ReactNode",
+            "description": "FieldForm 接收任意 ReactNode(包括 FieldForm.Item / Button type=submit / 自定义包装);**但每个 Item 的 child 必须是支持 value/onChange/error/disabled 的自定义组件**(TextField / Select / Checkbox / Switch / DatePicker / InputNumber 等);**不可用原生 input/textarea/select/button — 会触发 React non-boolean-attribute warning**(因 cloneElement 注入 error={false} 给原生 DOM 元素时,React 视 error 为 DOM attr → 报错);见 childrenContract.FormItem"
+        }
+    },
+    "childrenContract": {
+        "FormItem": {
+            "rule": "FieldForm.Item 的 children 必须是支持 value/onChange/error/disabled prop 的自定义组件",
+            "recommended": [
+                "TextField",
+                "Select",
+                "Switch",
+                "Checkbox",
+                "InputNumber",
+                "DatePicker",
+                "TextEditor",
+                "RangeInput",
+                "RadioGroup",
+                "CheckboxGroup",
+                "Slider"
+            ],
+            "forbidden": [
+                "原生 <input>",
+                "原生 <textarea>",
+                "原生 <select>",
+                "包一层 <div>"
+            ],
+            "reason": "Item 用 cloneElement 注入 value/onChange/error/disabled/size 等 prop;原生 DOM 元素不消费 error: boolean,React 会报 non-boolean attribute warning(运行时 console error,demo 验证 fail)"
+        },
+        "submit": {
+            "rule": "提交用 <Button type=\"submit\"> 或 form.submit()",
+            "trigger": "<Button>(来自 @para-ui/core/Button)渲染为 <button type='submit'>,会触发 form 的 submit 事件 → 跑校验 → onFinish/onFinishFailed",
+            "wrapper": "提交按钮通常用 FieldForm.Item(不带 name)包裹做布局,如 `<FieldForm.Item><Button type='submit'>提交</Button></FieldForm.Item>`;Item 不带 name 时不会注入 value/onChange/error(纯布局容器),不会触发 non-boolean-attribute warning;**也可不包 Item 直接放 Button**(看布局需求)"
+        }
+    },
+    "interpretivePriority": {
+        "principle": "**当需求描述中的'范围约束'(如 '仅使用 FieldForm 本身' / '不引入其他组件')与 childrenContract 冲突时,优先服从 childrenContract**",
+        "reason": "childrenContract 决定 runtime 是否报 React warning;需求'仅使用 FieldForm 本身'通常指**目标包装组件**(如 EditDataForm / SearchHorizontalForm)的**实现层 import 限制**(不在该包装组件内部 import 其他组件),**不限制 Demo 入口层或 children 子组件**;若字面理解为'整个文件只能 import FieldForm',会导致 Item.children 只能用原生 <input> → 触发 non-boolean warning → 运行时 fail",
+        "resolution": "标准解读:'仅使用 FieldForm 本身' = '目标包装组件(EditDataForm 等)的实现 import 列表只有 FieldForm';**Demo 渲染入口 (`const Demo: FC = () => ...`) 可自由 import TextField / Button / Select 等推荐子组件作为 children 传入包装组件**;**包装组件接收 children: ReactNode 直接透传给 FieldForm 即可,不需要内部 import 字段组件**",
+        "antiPatterns": [
+            "❌ 整个 demo 文件只 import FieldForm,FieldForm.Item.children 用原生 <input>",
+            "❌ 整个 demo 文件只 import FieldForm,提交按钮用原生 <button type='submit'>",
+            "❌ 把'仅使用 FieldForm 本身'解读为'禁止 import TextField/Button'"
+        ],
+        "correctPatterns": [
+            "✅ 包装组件 (EditDataForm) 实现层只 import FieldForm,接收 children: ReactNode",
+            "✅ Demo 渲染入口 import TextField + Button,构造 <FieldForm.Item><TextField/></FieldForm.Item> 作为 children 传入",
+            "✅ 提交按钮:Demo 入口 import Button,<FieldForm.Item><Button type='submit'>提交</Button></FieldForm.Item>"
+        ]
+    },
+    "commonMisconceptions": {
+        "M1": {
+            "wrong": "FieldForm.Item.children 用原生 <input>",
+            "result": "React 报 `Received 'false' for a non-boolean attribute 'error'` warning → ai-test runtime fail",
+            "fix": "改用 TextField (或其他 recommended 组件)"
+        },
+        "M2": {
+            "wrong": "提交按钮用原生 `<button type='submit'>` 包在 FieldForm.Item 内",
+            "result": "Item cloneElement 注入 error={false} 到原生 button → React warning → ai-test fail",
+            "fix": "改用 `<Button type='submit'>` 或不包 FieldForm.Item 直接放原生 button(Item 在不包裹时不注入 error)"
+        },
+        "M3": {
+            "wrong": "需求 '仅使用 FieldForm 本身' 被解读为整个 demo 文件只 import FieldForm",
+            "result": "Item children 退化为原生 <input> → M1 warning",
+            "fix": "见 interpretivePriority.resolution(包装组件实现层 vs Demo 入口层的区分)"
+        }
+    },
+    "completeExample": "// R23 议题修补:R22 4/5 fail 根因 sub-agent 误解'仅使用 FieldForm 本身'\n// 标准完整示例(initialValues + useForm + onFinish + Item + TextField + Button submit):\n\nimport React, { FC } from 'react';\nimport FieldForm from '@para-ui/core/FieldForm';\nimport type { FieldFormInstance } from '@para-ui/core/FieldForm';\nimport TextField from '@para-ui/core/TextField';\nimport Button from '@para-ui/core/Button';\n\n// === 1. 目标包装组件(实现层只 import FieldForm + 类型) ===\ninterface EditDataFormProps {\n    initialData?: Record<string, any>;\n    children: React.ReactNode;\n    onSubmitSuccess: (values: any) => void;\n}\nconst EditDataForm: FC<EditDataFormProps> = ({ initialData, children, onSubmitSuccess }) => {\n    const [form] = FieldForm.useForm();\n    return (\n        <FieldForm\n            form={form}\n            initialValues={initialData}\n            onFinish={onSubmitSuccess}\n            layout='vertical'\n        >\n            {children}\n        </FieldForm>\n    );\n};\n\n// === 2. Demo 渲染入口(可自由 import TextField + Button 作为 children) ===\nconst Demo: FC = () => (\n    <EditDataForm\n        initialData={{ username: '张三', email: 'zs@example.com' }}\n        onSubmitSuccess={(values) => console.log('submitted', values)}\n    >\n        <FieldForm.Item name='username' label='用户名' rules={[{ required: true }]}>\n            <TextField placeholder='请输入用户名' />\n        </FieldForm.Item>\n        <FieldForm.Item name='email' label='邮箱' rules={[{ required: true, type: 'email' }]}>\n            <TextField placeholder='请输入邮箱' />\n        </FieldForm.Item>\n        <FieldForm.Item>\n            <Button type='submit'>保存修改</Button>\n        </FieldForm.Item>\n    </EditDataForm>\n);\nexport default Demo;",
+    "do": [
+        "**Demo 入口层**必须 import TextField / Button 等推荐组件给 Item.children(即使需求说'仅使用 FieldForm 本身',这是包装组件实现层约束,不是 Demo 入口约束)",
+        "使用 useForm() 管理表单实例;父组件需要外部调用 submit/resetFields/setFieldsValue 时通过 form prop 传入",
+        "完整 demo 模板见 completeExample(initialValues + onFinish + FieldForm.Item + TextField + Button)",
+        "提供完整的校验规则(rules: [{ required: true }, { type: 'email' }, { pattern: /.../ }])"
+    ],
+    "dont": [
+        "FieldForm.Item.children 用原生 <input> / <textarea> / <select> / <button>(触发 non-boolean-attribute warning,见 childrenContract.FormItem.reason)",
+        "把'仅使用 FieldForm 本身'解读为'整个文件不能 import TextField/Button'(见 interpretivePriority.resolution)",
+        "字段过多不分组",
+        "忽略异步校验",
+        "在 mount 后修改 initialValues prop(应用 form.setFieldsValue;initialValues 仅 mount 时灌入)"
+    ],
+    "events": {
+        "onFinish": {
+            "signature": "(values: any) => void",
+            "asyncSupported": false,
+            "examples": [
+                "校验全部通过后触发:values 是全部 FieldForm.Item.name 收集到的字段扁平对象",
+                "点击 <Button type='submit'> 或调用 form.submit() 后跑校验,通过才触发 onFinish",
+                "values 结构与 initialValues 形状一致,key = 每个 Item 的 name 字段值"
+            ],
+            "commonMistakes": [
+                "假设 onFinish 会在校验失败时也触发——只有全部通过才触发,失败时触发 onFinishFailed",
+                "假设 onFinish 签名是 (e: FormEvent) => void——实际只有 (values: any) 一个参数",
+                "假设 submit 时直接拿到 event.preventDefault()——FieldForm 内部已处理,不需要手动 preventDefault"
+            ]
+        },
+        "onFinishFailed": {
+            "signature": "({ values, errorFields, outOfDate }: ValidateErrorEntity) => void",
+            "asyncSupported": false,
+            "examples": [
+                "校验失败时触发:errorFields 是 { name: NamePath; errors: string[] }[] 数组",
+                "values 包含当前所有字段值(含未通过校验的字段)"
+            ],
+            "commonMistakes": [
+                "假设参数是 (errors: string[]) 而不是对象——实际是 { values, errorFields, outOfDate } 解构对象",
+                "假设只有 onFinish 就够了——校验失败场景必须处理 onFinishFailed 才能给用户提示"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "FieldFormInstance 与 FormInstance 是同一类型的两个别名,推荐用 FieldFormInstance 避免与其他库冲突",
+            "wrong": "import type { FormInstance } from 'rc-field-form';  // 直接用 rc-field-form 的类型",
+            "right": "import type { FieldFormInstance } from '@para-ui/core/FieldForm'; const [form] = FieldForm.useForm<FieldFormInstance>();"
+        },
+        {
+            "issue": "FieldForm.Item 的 children 必须是自定义组件(支持 value/onChange/error prop),不能是原生 DOM 元素",
+            "wrong": "<FieldForm.Item name='age'><input type='number' /></FieldForm.Item>  // error prop 会被注入到原生 input,React 报 non-boolean warning",
+            "right": "<FieldForm.Item name='age'><InputNumber /></FieldForm.Item>  // 使用支持 error: boolean 的自定义组件"
+        },
+        {
+            "issue": "initialValues 仅在 mount 时生效,mount 后动态修改 initialValues prop 不会刷新表单",
+            "wrong": "// 动态修改 initialValues 期望刷新表单\n<FieldForm initialValues={dynamicData} />  // 后续 dynamicData 变化不会更新表单",
+            "right": "// 需要动态回填时用 form.setFieldsValue(newData)\nconst [form] = FieldForm.useForm();\nuseEffect(() => { form.setFieldsValue(dynamicData); }, [dynamicData]);"
+        },
+        {
+            "issue": "rules 中的 validator 函数签名必须返回 Promise(rc-field-form 约定),不是同步返回",
+            "wrong": "rules={[{ validator: (_, val) => val > 0 ? true : false }]}  // 同步返回 boolean 不被识别",
+            "right": "rules={[{ validator: (_, val) => val > 0 ? Promise.resolve() : Promise.reject('必须大于 0') }]}"
+        }
+    ],
+    "mapping": {
+        "realComponent": "FieldForm",
+        "adapter": null
+    }
+}

package/lib/FieldForm/context.d.ts

@@ -20,7 +20,11 @@ export interface FormContextProps {
     size?: 'small' | 'medium' | 'large';
 }
 export declare const FormContext: React.Context<FormContextProps>;
-export type ReportMetaChange = (meta: Meta, uniqueKeys: Key[]) => void;
+/** rc-field-form 在销毁字段时会传入带 destroy 标记的 meta(官方 Meta 类型未声明此字段) */
+export type MetaWithDestroy = Meta & {
+    destroy?: boolean;
+};
+export type ReportMetaChange = (meta: MetaWithDestroy, uniqueKeys: Key[]) => void;
 export declare const NoStyleItemContext: React.Context<ReportMetaChange | null>;
 export interface FormItemStatusContextProps {
     isFormItemInput?: boolean;

package/lib/FieldForm/context.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("../_virtual/jsx-runtime.js"),t=require("react"),n=require("rc-field-form"),i=require("rc-util/lib/omit"),c=e=>{const o=i(e,["prefixCls"]);return r.jsxRuntimeExports.jsx(n.FormProvider,{...o})},m=t.createContext({labelAlign:"left",layout:"vertical",itemRef:(()=>{})}),s=t.createContext(null),l=t.createContext({});exports.FormContext=m;exports.FormItemInputContext=l;exports.FormProvider=c;exports.NoStyleItemContext=s;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("../_virtual/jsx-runtime.js"),t=require("react"),n=require("rc-field-form"),i=require("rc-util/lib/omit"),c=e=>{const o=i(e,["prefixCls"]);return r.jsxRuntimeExports.jsx(n.FormProvider,{...o})},m=t.createContext({labelAlign:"left",layout:"vertical",itemRef:()=>()=>{}}),s=t.createContext(null),l=t.createContext({});exports.FormContext=m;exports.FormItemInputContext=l;exports.FormProvider=c;exports.NoStyleItemContext=s;
 //# sourceMappingURL=context.js.map

package/lib/FieldForm/hooks/useForm.d.ts

@@ -1,6 +1,7 @@
+import { ReactElement } from 'react';
 import { FormInstance as RcFormInstance } from 'rc-field-form';
 import { NamePath } from '../interface';
-export interface FormInstance<Values = any> extends RcFormInstance<Values> {
-    getFieldInstance: (name: NamePath) => any;
+export interface FormInstance<Values = unknown> extends RcFormInstance<Values> {
+    getFieldInstance: (name: NamePath) => ReactElement | undefined;
 }
-export default function useForm<Values = any>(form?: FormInstance<Values>): [FormInstance<Values>];
+export default function useForm<Values = unknown>(form?: FormInstance<Values>): [FormInstance<Values>];

package/lib/FieldForm/hooks/useFormInstance.d.ts

@@ -1,2 +1,2 @@
 import { FormInstance } from './useForm';
-export default function useFormInstance<Value = any>(): FormInstance<Value>;
+export default function useFormInstance<Value = unknown>(): FormInstance<Value>;

package/lib/FieldForm/hooks/useFormItemStatus.d.ts

@@ -1,9 +1,13 @@
 import { ReactNode } from 'react';
 import { ValidateStatus } from '../FieldFormItem';
-type UseFormItemStatus = () => {
-    status?: ValidateStatus;
-    errors: ReactNode[];
-    warnings: ReactNode[];
-};
+import { FormItemInputContext } from '../context';
+interface UseFormItemStatus {
+    (): {
+        status?: ValidateStatus;
+        errors: ReactNode[];
+        warnings: ReactNode[];
+    };
+    Context: typeof FormItemInputContext;
+}
 declare const useFormItemStatus: UseFormItemStatus;
 export default useFormItemStatus;

package/lib/FieldForm/hooks/useFormItemStatus.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const u=require("react"),t=require("../context.js"),e=()=>{const{status:o,errors:r=[],warnings:n=[]}=u.useContext(t.FormItemInputContext);return{status:o,errors:r,warnings:n}};e.Context=t.FormItemInputContext;exports.default=e;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const u=require("react"),t=require("../context.js"),e=(()=>{const{status:o,errors:r=[],warnings:n=[]}=u.useContext(t.FormItemInputContext);return{status:o,errors:r,warnings:n}});e.Context=t.FormItemInputContext;exports.default=e;
 //# sourceMappingURL=useFormItemStatus.js.map

package/lib/FieldForm/hooks/useItemRef.d.ts

@@ -1,3 +1,3 @@
 import { default as React } from 'react';
 import { InternalNamePath } from '../interface';
-export default function useItemRef(): (name: InternalNamePath, children: any) => React.Ref<any> | undefined;
+export default function useItemRef(): (name: InternalNamePath, children: React.ReactNode) => React.Ref<unknown> | undefined;

package/lib/FieldForm/hooks/useItemRef.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const u=require("react"),i=require("rc-util/lib/ref"),s=require("../context.js");function R(){const{itemRef:c}=u.useContext(s.FormContext),e=u.useRef({});function f(n,t){const r=t&&typeof t=="object"&&t.ref,o=n.join("_");return(e.current.name!==o||e.current.originRef!==r)&&(e.current.name=o,e.current.originRef=r,e.current.ref=i.composeRef(c(n),r)),e.current.ref}return f}exports.default=R;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const c=require("react"),i=require("rc-util/lib/ref"),s=require("../context.js");function R(){const{itemRef:u}=c.useContext(s.FormContext),e=c.useRef({});function f(n,t){const r=t&&typeof t=="object"&&t.ref,o=n.join("_");return(e.current.name!==o||e.current.originRef!==r)&&(e.current.name=o,e.current.originRef=r,e.current.ref=i.composeRef(u(n),r)),e.current.ref}return f}exports.default=R;
 //# sourceMappingURL=useItemRef.js.map