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

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/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/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

package/lib/Form/component.json

@@ -0,0 +1,161 @@
+{
+    "name": "Form",
+    "category": "Data Entry",
+    "description": "基于配置的高性能表单组件",
+    "semantic": {
+        "intent": [
+            "数据录入",
+            "数据编辑",
+            "数据校验"
+        ],
+        "useCases": [
+            "登录注册",
+            "配置设置",
+            "信息填写"
+        ],
+        "riskLevel": "high"
+    },
+    "variants": {
+        "horizontal": {
+            "meaning": "水平布局表单"
+        },
+        "vertical": {
+            "meaning": "垂直布局表单"
+        }
+    },
+    "states": [
+        "loading",
+        "submitting",
+        "error"
+    ],
+    "idealProps": {
+        "configList": {
+            "type": "configListProps",
+            "description": "表单项配置数组（`type configListProps = Array<FormItemProps>`，src/Form/index.tsx:20 已 export）。**FormItemProps 核心字段（完整见 docs/view/form/api.ts apiDataFormItemProps）**：\n• `name: string`（必填，唯一标识；onChange / backData 的 key 都对应该值）\n• `label: string | ((props: FormItemProps) => ReactNode)`（显示文案）\n• `InputType: 'default' | 'number' | 'textarea' | 'select' | 'radioGroup' | 'checkGroup' | 'switch' | 'file' | FC<ItemTypeProps>`（⚠️ 控件类型用 **InputType**，不是 type；type 是布局覆盖）\n• `defaultValue: any`（字段初始值；backData[name] 优先级更高）\n• `rules: { validate: { required?, maxlength?, minLength?, pattern?, [customKey]? }, message: { [key]: string } }`（⚠️ **注意大小写**：`maxlength` 小写 l；`minLength` 驼峰 L——src 命名不一致，写错会导致校验规则被忽略）\n• `list: Array<{label, name?|value?}>`（radioGroup/checkGroup 子项用 `name`；select 子项用 `value`）\n• `disabled: boolean`（单项禁用）\n• `hide: boolean`（隐藏该项）\n• `hideError: boolean`（隐藏该项内置 error UI）\n• `type: 'vertical' | 'horizontal'`（单项布局覆盖；与顶层 type 同名，仅控制布局，不影响控件类型）"
+        },
+        "backData": {
+            "type": "{ [name: string]: any }",
+            "description": "整表回填数据。比 configList 中每项的 defaultValue 优先级更高；切换到该新对象会刷新表单。常配合 form.refreshForm(undefined, newBackData) 实现『换数据源』场景"
+        },
+        "type": {
+            "type": "enum",
+            "values": [
+                "vertical",
+                "horizontal"
+            ],
+            "default": "horizontal",
+            "description": "**布局类型**（vertical=竖 / horizontal=横）；configList 中每项的 `type` 字段可覆盖顶层布局。⚠️ **此处 type 仅控制布局，与控件类型无关**——控件类型用 FormItemProps.`InputType`（default/select/radioGroup 等）"
+        },
+        "disabled": {
+            "type": "boolean",
+            "default": false,
+            "description": "是否全局禁用所有 FormItem 输入控件——对所有 InputType（default/textarea/number/file/switch/select/radioGroup/checkGroup/自定义函数）都生效，FormItem 内部把顶层 disabled 透传给每项。disabled 期间用户交互被屏蔽，onChange 不触发；不影响 form.current.check / reset / clear 等命令式调用"
+        },
+        "onChange": {
+            "type": "function",
+            "signature": "(name: string, value: any) => void",
+            "description": "表单值改变回调——任意字段（任意 InputType）变化都触发。**name 参数 = 对应 configList 该项的 `name` 字段值**；value 为该字段当前值。**触发时机**：input 类等价 onInput 实时（非 onBlur）；select/radioGroup/checkGroup 在用户选中瞬时；switch 在 toggle 瞬时。**初始 backData 注入不触发 onChange**（仅用户交互或 form.current.refreshForm 才触发）。该回调不携带校验状态，需校验请用 form.current.check?.()"
+        },
+        "form": {
+            "type": "React.MutableRefObject<FormRefObject>",
+            "description": "**命令式 ref**——通过 form.current 调用 check / reset / clear / refreshForm / getValidValues 等方法。**FormRefObject 字段完整列表**（DEFECT-001/002）：check（校验，**返回 false | { [name]: any }**——失败返 false 不抛错；**成功返回的对象 key = configList 每项的 `name` 字段值**，扁平结构非嵌套）/ reset（重置到初始 backData/defaultValue）/ clear（清空全部或指定字段，签名 `(name?: string | string[]) => void`）/ items（{ [name]: ItemTypeProps }）/ values / refreshForm / refData / getValidValues（过滤 hide=true 与未通过校验的字段）。docs/view/form/api.ts 末尾 RefObject 表列出全部字段。**5.x 仅整表 check，无 checkField(name) 单字段校验 API**——逐字段实时校验需在父组件用 onChange 桥接 + 业务方复刻 validate 逻辑。**FormRefObject 已公开 export**（Form-DEFECT-001 起），通过 `import { FormRefObject } from '@para-ui/core'` 或 `import { FormRefObject } from '@para-ui/core/Form'` 获取精确类型；推荐声明：`const formRef = useRef<FormRefObject>({} as FormRefObject)`"
+        },
+        "getCheckForm": {
+            "type": "function",
+            "signature": "(checkFrom: Function) => void",
+            "description": "**与 form ref 是同一能力的双通路（DEFECT-005）**。回调式：组件挂载后调用 getCheckForm(check) 把 check 函数交给父组件。**推荐统一用 form ref**——getCheckForm 是历史回调式 API"
+        },
+        "getForcedRefresh": {
+            "type": "function",
+            "signature": "(setConfigHook: (configList: configListProps, bData?: { [name: string]: any }) => void) => void",
+            "description": "强制刷新配置回调（src/Form/index.tsx:96-102 interface 实证）：组件挂载后将内部 setConfig 方法交给父组件；父组件可通过 setConfigHook(newConfigList, newBackData) 命令式刷新整个表单结构和回填数据。⚠️ **推荐改用 form ref.refreshForm**——getForcedRefresh 是历史 API，与 form ref 功能重叠"
+        },
+        "disOnlySpace": {
+            "type": "boolean",
+            "description": "是否禁止纯空格提交（src/Form/index.tsx:111 interface 实证）：true 时 rules.validate.required + 纯空格内容也会校验失败"
+        },
+        "className": {
+            "type": "string",
+            "description": "表单容器自定义类名（src/Form/index.tsx:122 interface 实证）"
+        },
+        "labelWidth": {
+            "type": "number",
+            "description": "Label 区块宽度，仅在顶层 type='vertical' 时生效（src/Form/index.tsx:131 interface 实证）"
+        }
+    },
+    "do": [
+        "使用 configList 进行配置化开发以减少模版代码",
+        "利用 form ref 进行手动校验和数据获取（推荐 form 单一通路而非 getCheckForm 双通路）",
+        "提交场景：`const values = formRef.current.check?.(); if (!values) return; submit(values);`——check 校验失败返 false，不抛错",
+        "重置场景：调用 form.current.reset?.() 而非 refreshForm(schema, {})（DEFECT-002 reset 是真实存在的 API）",
+        "FormItem 字段默认值用 FormItemProps.defaultValue（DEFECT-003 已实现，docs api.ts apiDataFormItemProps 已补）",
+        "**FormItemProps.list 子项 key 命名按 InputType 选用**（DEFECT-008 + src 实证）：radioGroup / checkGroup 用 `{ label, name }`（用户选中产生的值 = name）；select 用 `{ label, value }`（用户选中产生的值 = value）",
+        "**rules.validate 合法 key**（src/FormItem/index.tsx:54-60 实证）：`required` / **`maxlength`**（小写 L）/ **`minLength`**（驼峰 L，与 maxlength 命名不一致是 src 现状）/ `pattern` / `disOnlySpace` / 任意自定义 key（值为 `(item, val) => boolean | string`）。message 中 key 与 validate key 一一对应",
+        "需要把同步 `check()` 包成 Promise 时：`async () => { const v = formRef.current.check?.(); return v || null; }`——失败返 null 而非 reject，避免业务方两套错误处理（参见 codeString.ts asyncCheckDemo）",
+        "需要逐字段实时校验：用顶层 onChange 桥接（任意字段变化都触发）+ 业务方在父组件复刻一份 validate 逻辑——5.x 没有 checkField(name) 单字段校验 API",
+        "需要父组件接管错误显示（服务端 / 异步校验）：更新 configList 对应项的 `errorMessage` 字段注入自定义错误文案（FormItem 优先展示此值，check() 内部错误被覆盖）；清除时传 `errorMessage: ''` 或 `undefined`。若需彻底隐藏内置 error UI 改用外部渲染，则配合 `hideError: true` + 父组件自定义 UI（议题 discussions/Form-error-takeover.md）"
+    ],
+    "dont": [
+        "在 render 中动态改变 configList 结构（应保持引用稳定）",
+        "混用受控和非受控模式",
+        "不要假设 check() 失败抛异常或返回 undefined——失败时返回 false（DEFECT-006）",
+        "不要既传 form 又传 getCheckForm 混用双通路（DEFECT-005）——选 form 即可",
+        "**不要在 select 子项里用 `{ label, name }`**——select 内部读 `value` 字段，用 name 会导致选中后 onChange 不传值；checkGroup/radioGroup 反过来要用 name 不能用 value（DEFECT-008 + src 实证）",
+        "**不要在 rules.validate 中把 maxlength 写成 maxLength（驼峰 L）或把 minLength 写成 minlength（小写 L）**——src 字段名严格匹配，写错会导致校验规则被忽略；不一致是 src 现状",
+        "不要假设 onChange 触发时携带校验状态——onChange 仅传 (name, value)，校验状态需主动调 form.current.check?.()",
+        "不要假设初始 backData 注入触发 onChange——src 实证仅用户交互或 form.current.refreshForm 触发"
+    ],
+    "events": {
+        "onChange": {
+            "signature": "(name: string, value: any) => void",
+            "asyncSupported": false,
+            "examples": [
+                "任意 FormItem 字段值变化时触发，name 是 configList 该项的 name 字段值",
+                "input 类等价 onInput 实时触发，select/radioGroup 在选中瞬时，switch 在 toggle 瞬时",
+                "桥接逐字段实时校验：拿到 (name, value) 后调 formRef.current.check?.() 触发整表校验"
+            ],
+            "commonMistakes": [
+                "假设回调签名是 (e, value) 类似 antd → 实际只有 (name, value) 两个参数",
+                "在 onChange 里直接做副作用而不通过 setState（破坏受控模式）",
+                "假设初始 backData 注入会触发 onChange → 不会，仅用户交互或 refreshForm 触发",
+                "假设 onChange 携带校验状态 → 不携带，需主动调 check?.()"
+            ]
+        }
+    },
+    "typescriptPitfalls": [
+        {
+            "issue": "FormRefObject 必须显式声明类型，否则 ref.current 推断为 unknown",
+            "wrong": "const formRef = useRef(null); formRef.current.check();  // 报 unknown 类型错",
+            "right": "import { FormRefObject } from '@para-ui/core'; const formRef = useRef<FormRefObject>({} as FormRefObject);"
+        },
+        {
+            "issue": "FormItem 控件类型字段叫 InputType 不是 type（type 是布局覆盖）",
+            "wrong": "configList: [{ name: 'age', label: '年龄', type: 'number' }]  // type 在这里是布局,不是控件",
+            "right": "configList: [{ name: 'age', label: '年龄', InputType: 'number' }]"
+        },
+        {
+            "issue": "rules.validate 字段名大小写不一致（src 现状）",
+            "wrong": "rules: { validate: { maxLength: 10, minlength: 2 } }  // 写错被忽略",
+            "right": "rules: { validate: { maxlength: 10, minLength: 2 } }  // 注意：maxlength 小写 L，minLength 驼峰 L"
+        },
+        {
+            "issue": "list 子项的 key 名称按 InputType 选用",
+            "wrong": "InputType: 'select', list: [{ label: 'A', name: 'a' }]  // select 读 value,name 被忽略",
+            "right": "InputType: 'select' → list: [{ label: 'A', value: 'a' }] // radioGroup/checkGroup 反过来用 name"
+        },
+        {
+            "issue": "check() 返回类型是 false | object,不是 boolean 也不抛异常",
+            "wrong": "const ok = formRef.current.check?.(); if (!ok) throw new Error('fail');  // ok 是 false | object",
+            "right": "const values = formRef.current.check?.(); if (!values) return; submit(values);  // false 表失败,object 表成功并含字段值"
+        },
+        {
+            "issue": "configList 不接受 undefined (TS2345),空状态用 '' 或 []",
+            "wrong": "<Form configList={someUndefined} />  // 触发 TS2345: Argument of type 'undefined' is not assignable to '\"\" | FormItemProps[]'",
+            "right": "<Form configList={someValue || []} />  // 或 configList=''"
+        }
+    ],
+    "mapping": {
+        "realComponent": "Form",
+        "adapter": null
+    }
+}