@xbeeant/form-engine-react 0.0.1 → 0.0.3

package/README.md

@@ -1,69 +1,97 @@
-# React + TypeScript + Vite
-
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
-
-Currently, two official plugins are available:
-
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
-
-## Expanding the ESLint configuration
-
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
-
-```js
-export default tseslint.config([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-
-      // Remove tseslint.configs.recommended and replace with this
-      ...tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      ...tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      ...tseslint.configs.stylisticTypeChecked,
-
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+# @xbeeant/form-engine-react
+
+`@xbeeant/form-engine` 的 React 渲染适配层。
+
+通过 `useSyncExternalStore` + 按路径精准版本订阅渲染字段，联动更新只重渲染受影响的组件；Schema 解析与路径计算全部在 Core 完成，本包直接消费渲染树。
+
+## 安装
+
+```bash
+npm install @xbeeant/form-engine-react @xbeeant/form-engine
 ```
 
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default tseslint.config([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
+peerDependencies：`react >= 18`、`react-dom >= 18`。
+
+## 快速开始
+
+```tsx
+import { useForm, NexusForm } from '@xbeeant/form-engine-react';
+import { registerAntdUI } from '@xbeeant/form-engine-ui';
+
+const schema = {
+  type: 'object',
+  displayType: 'row',
+  properties: {
+    username: {
+      type: 'string',
+      widget: 'input',
+      title: '用户名',
+      required: true,
     },
+    age: { type: 'integer', widget: 'number', title: '年龄' },
   },
-])
+};
+
+function App() {
+  const [form] = useForm();
+  return (
+    <NexusForm
+      form={form}
+      schema={schema}
+      initialValues={{ username: 'alice' }}
+      onFinish={(values) => console.log(values)}
+      onFinishFailed={(errors) => console.log(errors)}
+      footer
+    />
+  );
+}
+```
+
+> 需要先注册 UI 组件：`registerAntdUI(engine)`（engine 由 `useForm()` 内部创建）或 `engine.use(antdPreset)` 注入 `@xbeeant/form-engine-ui`。未注册 widget 的字段会优雅降级渲染。
+
+## API
+
+### NexusForm
+
+| Prop | 类型 | 说明 |
+| :--- | :--- | :--- |
+| `form` | `FormController` | 由 `useForm()` 创建的表单实例 |
+| `schema` | `NexusSchema` | Schema 定义（缺省则渲染 children） |
+| `initialValues` | `Record<string, unknown>` | 初始值 |
+| `widgets` / `layouts` | `Record<string, (props) => ReactNode>` | 额外注册的组件 |
+| `onFinish` | `(formData) => void \| Promise` | 提交成功回调 |
+| `onFinishFailed` | `(errors: Map<string, string[]>) => void` | 校验失败回调 |
+| `footer` | `boolean \| ReactNode` | 是否显示默认提交/重置按钮，或自定义 |
+| `displayType` / `labelWidth` / `label` / `colon` / `column` / `readOnly` | — | 表单布局配置，优先级：组件 props > Schema 顶层 > 默认值 |
+| `className` / `style` / `children` | — | 常规属性 |
+
+### useForm
+
+```ts
+const [form] = useForm(); // 返回 [FormController]，可选 useForm(engine) 复用已有实例
 ```
+
+`FormController` 常用方法：`submit()`、`resetFields()`、`setValues(values)`、`setValueByPath(path, value)`、`getValues(paths?)`、`getAllValues()`、`getHiddenValues()`、`validateFields(paths?)`、`getFieldError(path)`、`setSchema(schema)`、`setSchemaByPath(path, patch)`、`registerValidator(path, fn)`、`scrollToPath(path)` 等。`submit` 失败时自动滚动聚焦第一个错误字段。
+
+### Hooks
+
+| Hook | 说明 |
+| :--- | :--- |
+| `useFormData()` | 订阅完整 formData（全局快照） |
+| `useFieldValue(path)` | 订阅单字段值（精准版本订阅，仅该字段重渲染） |
+| `useFieldState(path)` | 订阅单字段完整状态（value / errors / visible / required ...） |
+| `useWatch(path)` | 监听字段值变化（`(value, oldValue) => void`） |
+| `useWatchState(path)` | 监听字段状态变化 |
+| `useWatchMultiple(paths)` | 同时监听多个字段 |
+| `useWatchAll()` | 监听所有字段值变化 |
+| `useEngine()` | 获取当前引擎实例 |
+| `useFieldValidator(path, validator)` | 为字段注册校验器 |
+| `useFormConfig()` | 获取表单布局配置（displayType / labelWidth / column ...） |
+
+## 关联包
+
+| 包 | 说明 |
+| :--- | :--- |
+| `@xbeeant/form-engine` | 表单引擎核心（纯 TypeScript） |
+| `@xbeeant/form-engine-ui` | Ant Design 控件与布局库 |
+| `@xbeeant/form-engine-designer` | Schema 可视化设计器 |

package/dist/cjs/components/FormController.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const l=require("@xbeeant/form-engine");class o{engine;formElementRef;getOnFinish;getOnFinishFailed;removeHiddenData=!0;watchers=new Map;globalWatcher=null;constructor(e){this.engine=e??new l.NexusEngine,this.engine.hasPlugin("async-validator")||this.engine.use(new l.AsyncValidatorPlugin(this.engine)),this.formElementRef={current:null},this.getOnFinish=()=>()=>{},this.getOnFinishFailed=()=>()=>{}}_bind(e,t,i){this.formElementRef.current=e,this.getOnFinish=t,this.getOnFinishFailed=i,this.engine.registerOnFieldValueChange((n,r)=>this._onFieldValueChange(n,r))}_syncConfig(e){if(e.removeHiddenData!==void 0&&(this.removeHiddenData=e.removeHiddenData),e.watch){this.watchers.clear(),this.globalWatcher=null;for(const[t,i]of Object.entries(e.watch))t==="#"?this.globalWatcher=i:this.watchers.set(t,i)}}_onFieldValueChange(e,t){const i=this.engine.getFormData(),n=this.removeHiddenData?i:this.engine.getAllFormData();this.globalWatcher&&this.globalWatcher(n,n,e);const r=this.watchers.get(e);r&&r(t,n)}_getEngine(){return this.engine}async submit(){const e=await this.engine.validate();if(e.size>0){this.focusFirstError(e),this.getOnFinishFailed()?.(e);return}const t=this.removeHiddenData?this.engine.getFormData():this.engine.getAllFormData();await this.getOnFinish()?.(t)}focusFirstError(e){const t=this.formElementRef.current;if(!t||e.size===0)return;const i=new Set(e.keys());requestAnimationFrame(()=>{const r=t.querySelectorAll("[data-nexus-field]");for(const s of Array.from(r)){const a=s.getAttribute("data-nexus-field");if(!a||!i.has(a))continue;s.scrollIntoView({behavior:"smooth",block:"center"}),s.querySelector('input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])')?.focus();return}})}resetFields(){this.engine.reset()}setErrorFields(e){this.engine.setErrorFields(e)}setValues(e){this.engine.setFieldValues(e)}setValueByPath(e,t){this.engine.setFieldValue(e,t)}setSchemaByPath(e,t){this.engine.setSchemaByPath(e,t)}setSchema(e){this.engine.setSchema(e)}getValues(e){return this.engine.getFormData(e)}getHiddenValues(){return this.engine.getHiddenValues()}getAllValues(){return this.engine.getAllFormData()}getValueByPath(e){return this.engine.getFieldValue(e)}registerValidator(e,t){this.engine.registerFieldValidator(e,t)}unregisterValidator(e,t){this.engine.unregisterFieldValidator(e,t)}revalidateField(e){this.engine.validateField(e,{trigger:"change"})}getSchema(){return this.engine.getSchema()}removeErrorField(e){this.engine.removeErrorField(e)}scrollToPath(e){this.formElementRef.current?.querySelector(`[data-nexus-field="${e}"]`)?.scrollIntoView({behavior:"smooth",block:"center"})}getFieldError(e){return this.engine.getFieldError(e)}getFieldsError(){return this.engine.getFieldsError()}validateFields(e){return this.engine.validate(e)}getFieldState(e){return this.engine.getFieldState(e)}}exports.FormController=o;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const l=require("@xbeeant/form-engine");class o{engine;formElementRef;getOnFinish;getOnFinishFailed;removeHiddenData=!0;watchers=new Map;globalWatcher=null;constructor(e){this.engine=e??new l.NexusEngine,this.engine.hasPlugin("async-validator")||this.engine.use(new l.AsyncValidatorPlugin(this.engine)),this.formElementRef={current:null},this.getOnFinish=()=>()=>{},this.getOnFinishFailed=()=>()=>{}}_bind(e,t,i){this.formElementRef.current=e,this.getOnFinish=t,this.getOnFinishFailed=i,this.engine.registerOnFieldValueChange((n,r)=>this._onFieldValueChange(n,r))}_syncConfig(e){if(e.removeHiddenData!==void 0&&(this.removeHiddenData=e.removeHiddenData),e.watch){this.watchers.clear(),this.globalWatcher=null;for(const[t,i]of Object.entries(e.watch))t==="#"?this.globalWatcher=i:this.watchers.set(t,i)}}_onFieldValueChange(e,t){const i=this.engine.getFormData(),n=this.removeHiddenData?i:this.engine.getAllFormData();this.globalWatcher&&this.globalWatcher(n,n,e);const r=this.watchers.get(e);r&&r(t,n)}_getEngine(){return this.engine}getEngine(){return this.engine}async submit(){const e=await this.engine.validate();if(e.size>0){this.focusFirstError(e),this.getOnFinishFailed()?.(e);return}const t=this.removeHiddenData?this.engine.getFormData():this.engine.getAllFormData();await this.getOnFinish()?.(t)}focusFirstError(e){const t=this.formElementRef.current;if(!t||e.size===0)return;const i=new Set(e.keys());requestAnimationFrame(()=>{const r=t.querySelectorAll("[data-nexus-field]");for(const s of Array.from(r)){const a=s.getAttribute("data-nexus-field");if(!a||!i.has(a))continue;s.scrollIntoView({behavior:"smooth",block:"center"}),s.querySelector('input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])')?.focus();return}})}resetFields(){this.engine.reset()}setErrorFields(e){this.engine.setErrorFields(e)}setValues(e){this.engine.setFieldValues(e)}setValueByPath(e,t){this.engine.setFieldValue(e,t)}setSchemaByPath(e,t){this.engine.setSchemaByPath(e,t)}setSchema(e){this.engine.setSchema(e)}getValues(e){return this.engine.getFormData(e)}getHiddenValues(){return this.engine.getHiddenValues()}getAllValues(){return this.engine.getAllFormData()}getValueByPath(e){return this.engine.getFieldValue(e)}registerValidator(e,t){this.engine.registerFieldValidator(e,t)}unregisterValidator(e,t){this.engine.unregisterFieldValidator(e,t)}revalidateField(e){this.engine.validateField(e,{trigger:"change"})}getSchema(){return this.engine.getSchema()}removeErrorField(e){this.engine.removeErrorField(e)}scrollToPath(e){this.formElementRef.current?.querySelector(`[data-nexus-field="${e}"]`)?.scrollIntoView({behavior:"smooth",block:"center"})}getFieldError(e){return this.engine.getFieldError(e)}getFieldsError(){return this.engine.getFieldsError()}validateFields(e){return this.engine.validate(e)}getFieldState(e){return this.engine.getFieldState(e)}}exports.FormController=o;

package/dist/cjs/components/NexusField.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const d=require("react/jsx-runtime"),s=require("react"),O=require("../contexts/FieldInheritContext.cjs"),j=require("../contexts/GridContext.cjs"),T=require("../contexts/LayoutConfigContext.cjs"),V=require("../contexts/NexusContext.cjs"),_=require("../utils/resolveColSpan.cjs");function k({dataPath:t,layoutKey:x}){const{engine:n,config:o,form:f}=V.useNexusContext();s.useSyncExternalStore(i=>n.subscribeField(t,i),()=>n.getFieldVersion(t),()=>n.getFieldVersion(t));const e=n.getFieldState(t),y=s.useContext(j.GridContext),C=s.useContext(T.LayoutConfigContext),u=s.useContext(O.FieldInheritContext),b=s.useCallback(i=>{n.setFieldValue(t,i)},[n,t]),v=s.useCallback(i=>{i.currentTarget.contains(i.relatedTarget)||n.validateField(t,{trigger:"blur"})},[n,t]),F=s.useMemo(()=>e?.meta.enum?e.meta.enum.map((i,r)=>({value:i,label:e.meta.enumNames?.[r]??String(i)})):e?.props.options,[e?.meta.enum,e?.meta.enumNames,e?.props.options]),S=s.useMemo(()=>{const i={};if(e?.reactions){for(const r of e.reactions)if(r.dependencies)for(const p of r.dependencies)i[p]=n.getFieldValue(p)}return i},[e?.reactions,n]);if(!e)return n.getSnapshot()>0&&console.warn(`[NexusField] Field not found: ${t}`),null;if(u.visible===!1||!e.visible)return C.removeHidden===!0?null:d.jsx("div",{className:"hidden","data-nexus-hidden":t});const a=o.readOnly||u.readOnly===!0||e.readOnly,h=u.disabled===!0||e.disabled,c=a&&!!e.meta.readOnlyWidget,W=c?e.meta.readOnlyWidget:e.meta.widget;let l=n.getWidget(W);if(!l&&c&&(l=n.getWidget(e.meta.widget)),!l)return d.jsxs("div",{className:"text-xs text-red-500","data-nexus-field":t,children:['⚠️ Widget "',e.meta.widget,'" 未注册 (path: ',t,")"]});const w=e.meta.displayType??o.displayType,N=e.meta.labelWidth??o.labelWidth,q=e.meta.column??o.column,m=_.resolveColSpan(e.meta.colSpan,y),g={...e.meta.width?{width:e.meta.width,flexShrink:0}:{},...m?{gridColumn:`span ${m}`}:{}};return d.jsx("div",{"data-nexus-field":t,onBlur:v,style:Object.keys(g).length>0?g:void 0,children:d.jsx(l,{dataPath:t,path:t,value:e.value,onChange:b,disabled:h,readOnly:a,loading:e.loading,required:e.required,title:e.meta.title,description:e.meta.description,placeholder:e.meta.placeholder,label:e.meta.label,options:F,errors:e.errors,extra:e.meta.extra,displayType:w,labelWidth:N,column:q,form:f,dependValues:S,items:e.meta.items,...e.props},x)})}exports.NexusField=k;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("react/jsx-runtime"),s=require("react"),_=require("../contexts/FieldInheritContext.cjs"),k=require("../contexts/GridContext.cjs"),L=require("../contexts/LayoutConfigContext.cjs"),M=require("../contexts/NexusContext.cjs"),B=require("../utils/resolveColSpan.cjs");function G({dataPath:t,layoutKey:u}){const{engine:n,config:l,form:b}=M.useNexusContext();s.useSyncExternalStore(i=>n.subscribeField(t,i),()=>n.getFieldVersion(t),()=>n.getFieldVersion(t));const e=n.getFieldState(t),F=s.useContext(k.GridContext),h=s.useContext(L.LayoutConfigContext),c=s.useContext(_.FieldInheritContext),v=s.useCallback(i=>{n.setFieldValue(t,i)},[n,t]),W=s.useCallback(i=>{i.currentTarget.contains(i.relatedTarget)||n.validateField(t,{trigger:"blur"})},[n,t]),w=s.useMemo(()=>e?.meta.enum?e.meta.enum.map((i,d)=>({value:i,label:e.meta.enumNames?.[d]??String(i)})):e?.props.options,[e?.meta.enum,e?.meta.enumNames,e?.props.options]),S=s.useMemo(()=>{const i={};if(e?.reactions){for(const d of e.reactions)if(d.dependencies)for(const y of d.dependencies)i[y]=n.getFieldValue(y)}return i},[e?.reactions,n]);if(!e)return n.getSnapshot()>0&&console.warn(`[NexusField] Field not found: ${t}`),null;if(c.visible===!1||!e.visible)return h.removeHidden===!0?null:o.jsx("div",{className:"hidden","data-nexus-hidden":t});const m=l.readOnly||c.readOnly===!0||e.readOnly,N=c.disabled===!0||e.disabled,p=m&&!!e.meta.readOnlyWidget,j=p?e.meta.readOnlyWidget:e.meta.widget;let r=n.getWidget(j);if(!r&&p&&(r=n.getWidget(e.meta.widget)),!r)return o.jsxs("div",{className:"text-xs text-red-500","data-nexus-field":t,children:['⚠️ Widget "',e.meta.widget,'" 未注册 (path: ',t,")"]});const q=e.meta.displayType??l.displayType,O=e.meta.labelWidth??l.labelWidth,T=e.meta.column??l.column,g=B.resolveColSpan(e.meta.colSpan,F),x={...e.meta.width?{width:e.meta.width,flexShrink:0}:{},...g?{gridColumn:`span ${g}`}:{}},f=n.getFieldWrapper(),V={label:e.meta.label,title:e.meta.title,description:e.meta.description,errors:e.errors,required:e.required,extra:e.meta.extra,width:e.meta.width,displayType:q,labelWidth:O,column:T},C={dataPath:t,path:t,value:e.value,onChange:v,disabled:N,readOnly:m,loading:e.loading,placeholder:e.meta.placeholder,options:w,form:b,dependValues:S,items:e.meta.items,...e.props};let a;return f?a=o.jsx(f,{...V,children:o.jsx(r,{...C})},u):a=o.jsx(r,{...C},u),o.jsx("div",{"data-nexus-field":t,onBlur:W,style:Object.keys(x).length>0?x:void 0,children:a})}exports.NexusField=G;

package/dist/cjs/components/NexusForm.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const l=require("react/jsx-runtime"),e=require("react"),B=require("../utils/renderTreeNode.cjs"),G=require("./NexusFormProvider.cjs");function o(){}function J({form:t,schema:r,initialValues:E,widgets:u,layouts:c,onFinish:v,onFinishFailed:_,footer:f=!1,className:h,style:q,children:L,labelCol:a,labelWidth:M,colon:W,label:k,displayType:O,readOnly:b,column:P,watch:y,removeHiddenData:g=!0}){const n=t._getEngine(),R=e.useRef(null),x=O??r?.displayType??"row",F=k??r?.label??!0,m=W??r?.colon,i=M??r?.labelWidth,S=b??r?.readOnly??!1,s=P??r?.column;e.useEffect(()=>{u&&n.registerWidgets(u),c&&n.registerLayouts(c)},[n,u,c]);const T=e.useRef(!0),D=e.useRef(E);e.useEffect(()=>{r&&(T.current?(n.init(r,D.current),T.current=!1):n.init(r,n.getFormData()))},[n,r]);const C=e.useRef(o),N=e.useRef(o);C.current=v??o,N.current=_??o,e.useEffect(()=>{t._bind(R.current,()=>C.current,()=>N.current)},[t]),e.useEffect(()=>{t._syncConfig({removeHiddenData:g,watch:y})},[t,g,y]);const V=e.useSyncExternalStore(n.subscribeStore,n.getSnapshot,n.getSnapshot),$=e.useMemo(()=>n.getRenderTree(),[n,V]),I=e.useCallback(async p=>{p.preventDefault(),await t.submit()},[t]),w=e.useCallback(()=>{t.resetFields()},[t]);let d=null;f===!0?d=l.jsxs("div",{className:"mt-4",children:[l.jsx("button",{type:"submit",children:"提交"})," ",l.jsx("button",{type:"button",onClick:w,children:"重置"})]}):f&&(d=f);const j=e.useMemo(()=>{if(a)return a;if(i)return{style:{width:typeof i=="number"?`${i}px`:i}}},[a,i]),z=e.useMemo(()=>({labelCol:j,labelWidth:i,colon:m,label:F,displayType:x,readOnly:S,column:s}),[j,i,m,F,x,S,s]);return l.jsx(G.NexusFormProvider,{engine:n,config:z,form:t,children:l.jsxs("form",{ref:R,onSubmit:I,className:h,style:{...q,...s&&s>1?{display:"grid",gridTemplateColumns:`repeat(${s}, 1fr)`,gap:"0 16px"}:{}},noValidate:!0,children:[$.map((p,A)=>B.renderTreeNode(p,A)),!b&&d,L]})})}exports.NexusForm=J;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const u=require("react/jsx-runtime"),e=require("react"),Q=require("../utils/renderTreeNode.cjs"),U=require("./NexusFormProvider.cjs");function o(){}function X({form:r,schema:n,initialValues:h,widgets:l,layouts:c,onFinish:k,onFinishFailed:q,onMount:b,footer:f=!1,className:L,style:O,children:W,labelCol:a,labelWidth:P,colon:D,label:V,displayType:$,readOnly:y,column:I,watch:g,removeHiddenData:R=!0}){const t=r._getEngine(),x=e.useRef(null),F=$??n?.displayType??"row",S=V??n?.label??!0,j=D??n?.colon,s=P??n?.labelWidth,E=y??n?.readOnly??!1,i=I??n?.column;e.useEffect(()=>{l&&t.registerWidgets(l),c&&t.registerLayouts(c)},[t,l,c]);const T=e.useRef(!0),w=e.useRef(h);e.useEffect(()=>{n&&(T.current?(t.init(n,w.current),T.current=!1):t.init(n,t.getFormData()))},[t,n]);const m=e.useRef(b);m.current=b;const C=e.useRef(!1),N=!n||typeof n=="object"&&Object.keys(n).length===0;e.useEffect(()=>{C.current||N||(C.current=!0,m.current?.())},[N]);const v=e.useRef(o),_=e.useRef(o);v.current=k??o,_.current=q??o,e.useEffect(()=>{r._bind(x.current,()=>v.current,()=>_.current)},[r]),e.useEffect(()=>{r._syncConfig({removeHiddenData:R,watch:g})},[r,R,g]);const z=e.useSyncExternalStore(t.subscribeStore,t.getSnapshot,t.getSnapshot),A=e.useMemo(()=>t.getRenderTree(),[t,z]),B=e.useCallback(async p=>{p.preventDefault(),await r.submit()},[r]),G=e.useCallback(()=>{r.resetFields()},[r]);let d=null;f===!0?d=u.jsxs("div",{className:"mt-4",children:[u.jsx("button",{type:"submit",children:"提交"})," ",u.jsx("button",{type:"button",onClick:G,children:"重置"})]}):f&&(d=f);const M=e.useMemo(()=>{if(a)return a;if(s)return{style:{width:typeof s=="number"?`${s}px`:s}}},[a,s]),J=e.useMemo(()=>({labelCol:M,labelWidth:s,colon:j,label:S,displayType:F,readOnly:E,column:i}),[M,s,j,S,F,E,i]);return u.jsx(U.NexusFormProvider,{engine:t,config:J,form:r,children:u.jsxs("form",{ref:x,onSubmit:B,className:L,style:{...O,...i&&i>1?{display:"grid",gridTemplateColumns:`repeat(${i}, 1fr)`,gap:"0 16px"}:{}},noValidate:!0,children:[A.map((p,K)=>Q.renderTreeNode(p,K)),!y&&d,W]})})}exports.NexusForm=X;

package/dist/cjs/hooks/useForm.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("react"),t=require("../components/FormController.cjs");function n(e){const r=o.useRef(null);return r.current||(r.current=new t.FormController(e)),[r.current]}exports.useForm=n;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("@xbeeant/form-engine"),t=require("react"),u=require("../components/FormController.cjs");function c(r,n){const e=t.useRef(null);return e.current||(e.current=new u.FormController(n??(r?new o.NexusEngine({formId:r}):void 0))),[e.current]}exports.useForm=c;

package/dist/cjs/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./components/FormController.cjs"),o=require("./components/NexusField.cjs"),t=require("./components/NexusForm.cjs"),s=require("./components/NexusFormProvider.cjs"),r=require("./components/NexusLayout.cjs"),u=require("./components/NexusObject.cjs"),n=require("./contexts/FieldInheritContext.cjs"),i=require("./contexts/GridContext.cjs"),c=require("./contexts/LayoutConfigContext.cjs"),l=require("./hooks/useEngine.cjs"),a=require("./hooks/useFieldState.cjs"),F=require("./hooks/useFieldValidator.cjs"),x=require("./hooks/useFieldValue.cjs"),d=require("./hooks/useForm.cjs"),h=require("./hooks/useFormConfig.cjs"),m=require("./hooks/useFormData.cjs"),q=require("./hooks/useWatch.cjs"),_=require("./hooks/useWatchAll.cjs"),C=require("./hooks/useWatchMultiple.cjs"),N=require("./hooks/useWatchState.cjs");exports.FormController=e.FormController;exports.NexusField=o.NexusField;exports.NexusForm=t.NexusForm;exports.NexusFormProvider=s.NexusFormProvider;exports.NexusLayout=r.NexusLayout;exports.NexusObject=u.NexusObject;exports.FieldInheritContext=n.FieldInheritContext;exports.GridContext=i.GridContext;exports.LayoutConfigContext=c.LayoutConfigContext;exports.useEngine=l.useEngine;exports.useFieldState=a.useFieldState;exports.useFieldValidator=F.useFieldValidator;exports.useFieldValue=x.useFieldValue;exports.useForm=d.useForm;exports.useFormConfig=h.useFormConfig;exports.useFormData=m.useFormData;exports.useWatch=q.useWatch;exports.useWatchAll=_.useWatchAll;exports.useWatchMultiple=C.useWatchMultiple;exports.useWatchState=N.useWatchState;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});require('./styles.css');;/* empty css             */const e=require("./components/FormController.cjs"),o=require("./components/NexusField.cjs"),t=require("./components/NexusForm.cjs"),s=require("./components/NexusFormProvider.cjs"),r=require("./components/NexusLayout.cjs"),u=require("./components/NexusObject.cjs"),n=require("./contexts/FieldInheritContext.cjs"),i=require("./contexts/GridContext.cjs"),c=require("./contexts/LayoutConfigContext.cjs"),l=require("./hooks/useEngine.cjs"),a=require("./hooks/useFieldState.cjs"),F=require("./hooks/useFieldValidator.cjs"),x=require("./hooks/useFieldValue.cjs"),d=require("./hooks/useForm.cjs"),h=require("./hooks/useFormConfig.cjs"),m=require("./hooks/useFormData.cjs"),q=require("./hooks/useWatch.cjs"),_=require("./hooks/useWatchAll.cjs"),C=require("./hooks/useWatchMultiple.cjs"),N=require("./hooks/useWatchState.cjs");exports.FormController=e.FormController;exports.NexusField=o.NexusField;exports.NexusForm=t.NexusForm;exports.NexusFormProvider=s.NexusFormProvider;exports.NexusLayout=r.NexusLayout;exports.NexusObject=u.NexusObject;exports.FieldInheritContext=n.FieldInheritContext;exports.GridContext=i.GridContext;exports.LayoutConfigContext=c.LayoutConfigContext;exports.useEngine=l.useEngine;exports.useFieldState=a.useFieldState;exports.useFieldValidator=F.useFieldValidator;exports.useFieldValue=x.useFieldValue;exports.useForm=d.useForm;exports.useFormConfig=h.useFormConfig;exports.useFormData=m.useFormData;exports.useWatch=q.useWatch;exports.useWatchAll=_.useWatchAll;exports.useWatchMultiple=C.useWatchMultiple;exports.useWatchState=N.useWatchState;

package/dist/cjs/styles.css

@@ -0,0 +1 @@
+@layer properties{@supports (((-webkit-hyphens:none)) and (not (margin-trim:inline))) or ((-moz-orient:inline) and (not (color:rgb(from red r g b)))){*,:before,:after,::backdrop{--tw-font-weight:initial;--tw-blur:initial;--tw-brightness:initial;--tw-contrast:initial;--tw-grayscale:initial;--tw-hue-rotate:initial;--tw-invert:initial;--tw-opacity:initial;--tw-saturate:initial;--tw-sepia:initial;--tw-drop-shadow:initial;--tw-drop-shadow-color:initial;--tw-drop-shadow-alpha:100%;--tw-drop-shadow-size:initial;--tw-duration:initial;--tw-ease:initial}}}:root,:host{--color-red-500:oklch(63.7% .237 25.331);--spacing:.25rem;--text-xs:.75rem;--text-xs--line-height:calc(1 / .75);--font-weight-bold:700;--ease-in-out:cubic-bezier(.4, 0, .2, 1);--default-transition-duration:.15s;--default-transition-timing-function:cubic-bezier(.4, 0, .2, 1)}.visible{visibility:visible}.mt-4{margin-top:calc(var(--spacing) * 4)}.mb-2{margin-bottom:calc(var(--spacing) * 2)}.mb-4{margin-bottom:calc(var(--spacing) * 4)}.block{display:block}.flex{display:flex}.grid{display:grid}.hidden{display:none}.inline{display:inline}.rotate-0{rotate:0deg}.rotate-90{rotate:90deg}.cursor-pointer{cursor:pointer}.gap-1{gap:var(--spacing)}.gap-x-4{column-gap:calc(var(--spacing) * 4)}.border-none{--tw-border-style:none;border-style:none}.bg-transparent{background-color:#0000}.p-0{padding:0}.align-middle{vertical-align:middle}.text-xs{font-size:var(--text-xs);line-height:var(--tw-leading,var(--text-xs--line-height))}.font-bold{--tw-font-weight:var(--font-weight-bold);font-weight:var(--font-weight-bold)}.text-red-500{color:var(--color-red-500)}.blur{--tw-blur:blur(8px);filter:var(--tw-blur,) var(--tw-brightness,) var(--tw-contrast,) var(--tw-grayscale,) var(--tw-hue-rotate,) var(--tw-invert,) var(--tw-saturate,) var(--tw-sepia,) var(--tw-drop-shadow,)}.transition-transform{transition-property:transform,translate,scale,rotate;transition-timing-function:var(--tw-ease,var(--default-transition-timing-function));transition-duration:var(--tw-duration,var(--default-transition-duration))}.duration-200{--tw-duration:.2s;transition-duration:.2s}.ease-in-out{--tw-ease:var(--ease-in-out);transition-timing-function:var(--ease-in-out)}.select-none{-webkit-user-select:none;user-select:none}@property --tw-font-weight{syntax:"*";inherits:false}@property --tw-blur{syntax:"*";inherits:false}@property --tw-brightness{syntax:"*";inherits:false}@property --tw-contrast{syntax:"*";inherits:false}@property --tw-grayscale{syntax:"*";inherits:false}@property --tw-hue-rotate{syntax:"*";inherits:false}@property --tw-invert{syntax:"*";inherits:false}@property --tw-opacity{syntax:"*";inherits:false}@property --tw-saturate{syntax:"*";inherits:false}@property --tw-sepia{syntax:"*";inherits:false}@property --tw-drop-shadow{syntax:"*";inherits:false}@property --tw-drop-shadow-color{syntax:"*";inherits:false}@property --tw-drop-shadow-alpha{syntax:"<percentage>";inherits:false;initial-value:100%}@property --tw-drop-shadow-size{syntax:"*";inherits:false}@property --tw-duration{syntax:"*";inherits:false}@property --tw-ease{syntax:"*";inherits:false}

package/dist/cjs/tailwind.css

@@ -0,0 +1 @@
+@layer properties{@supports (((-webkit-hyphens:none)) and (not (margin-trim:inline))) or ((-moz-orient:inline) and (not (color:rgb(from red r g b)))){*,:before,:after,::backdrop{--tw-font-weight:initial;--tw-blur:initial;--tw-brightness:initial;--tw-contrast:initial;--tw-grayscale:initial;--tw-hue-rotate:initial;--tw-invert:initial;--tw-opacity:initial;--tw-saturate:initial;--tw-sepia:initial;--tw-drop-shadow:initial;--tw-drop-shadow-color:initial;--tw-drop-shadow-alpha:100%;--tw-drop-shadow-size:initial;--tw-duration:initial;--tw-ease:initial}}}:root,:host{--color-red-500:oklch(63.7% .237 25.331);--spacing:.25rem;--text-xs:.75rem;--text-xs--line-height:calc(1 / .75);--font-weight-bold:700;--ease-in-out:cubic-bezier(.4, 0, .2, 1);--default-transition-duration:.15s;--default-transition-timing-function:cubic-bezier(.4, 0, .2, 1)}.visible{visibility:visible}.mt-4{margin-top:calc(var(--spacing) * 4)}.mb-2{margin-bottom:calc(var(--spacing) * 2)}.mb-4{margin-bottom:calc(var(--spacing) * 4)}.block{display:block}.flex{display:flex}.grid{display:grid}.hidden{display:none}.inline{display:inline}.rotate-0{rotate:0deg}.rotate-90{rotate:90deg}.cursor-pointer{cursor:pointer}.gap-1{gap:var(--spacing)}.gap-x-4{column-gap:calc(var(--spacing) * 4)}.border-none{--tw-border-style:none;border-style:none}.bg-transparent{background-color:#0000}.p-0{padding:0}.align-middle{vertical-align:middle}.text-xs{font-size:var(--text-xs);line-height:var(--tw-leading,var(--text-xs--line-height))}.font-bold{--tw-font-weight:var(--font-weight-bold);font-weight:var(--font-weight-bold)}.text-red-500{color:var(--color-red-500)}.blur{--tw-blur:blur(8px);filter:var(--tw-blur,) var(--tw-brightness,) var(--tw-contrast,) var(--tw-grayscale,) var(--tw-hue-rotate,) var(--tw-invert,) var(--tw-saturate,) var(--tw-sepia,) var(--tw-drop-shadow,)}.transition-transform{transition-property:transform,translate,scale,rotate;transition-timing-function:var(--tw-ease,var(--default-transition-timing-function));transition-duration:var(--tw-duration,var(--default-transition-duration))}.duration-200{--tw-duration:.2s;transition-duration:.2s}.ease-in-out{--tw-ease:var(--ease-in-out);transition-timing-function:var(--ease-in-out)}.select-none{-webkit-user-select:none;user-select:none}@property --tw-font-weight{syntax:"*";inherits:false}@property --tw-blur{syntax:"*";inherits:false}@property --tw-brightness{syntax:"*";inherits:false}@property --tw-contrast{syntax:"*";inherits:false}@property --tw-grayscale{syntax:"*";inherits:false}@property --tw-hue-rotate{syntax:"*";inherits:false}@property --tw-invert{syntax:"*";inherits:false}@property --tw-opacity{syntax:"*";inherits:false}@property --tw-saturate{syntax:"*";inherits:false}@property --tw-sepia{syntax:"*";inherits:false}@property --tw-drop-shadow{syntax:"*";inherits:false}@property --tw-drop-shadow-color{syntax:"*";inherits:false}@property --tw-drop-shadow-alpha{syntax:"<percentage>";inherits:false;initial-value:100%}@property --tw-drop-shadow-size{syntax:"*";inherits:false}@property --tw-duration{syntax:"*";inherits:false}@property --tw-ease{syntax:"*";inherits:false}

package/dist/es/components/FormController.d.ts

@@ -25,6 +25,10 @@ export declare class FormController implements NexusFormInstance {
     _onFieldValueChange(path: string, value: unknown): void;
     /** 内部：获取 Engine 实例 */
     _getEngine(): NexusEngine;
+    /**
+     * 获取底层 Engine 实例（用于跨表单联动：linkForm / setFormId 等）
+     */
+    getEngine(): NexusEngine;
     submit(): Promise<void>;
     /**
      * 定位到第一个校验失败的字段：按 DOM 渲染顺序查找（保证视觉上的"第一个"），

package/dist/es/components/FormController.js

@@ -40,6 +40,12 @@ class c {
   _getEngine() {
     return this.engine;
   }
+  /**
+   * 获取底层 Engine 实例（用于跨表单联动：linkForm / setFormId 等）
+   */
+  getEngine() {
+    return this.engine;
+  }
   async submit() {
     const e = await this.engine.validate();
     if (e.size > 0) {

package/dist/es/components/NexusField.js

@@ -1,98 +1,97 @@
-import { jsx as d, jsxs as j } from "react/jsx-runtime";
-import { useSyncExternalStore as k, useContext as a, useCallback as g, useMemo as x } from "react";
-import { FieldInheritContext as q } from "../contexts/FieldInheritContext.js";
-import { GridContext as B } from "../contexts/GridContext.js";
-import { LayoutConfigContext as L } from "../contexts/LayoutConfigContext.js";
-import { useNexusContext as $ } from "../contexts/NexusContext.js";
-import { resolveColSpan as D } from "../utils/resolveColSpan.js";
-function A({ dataPath: t, layoutKey: y }) {
-  const { engine: i, config: o, form: b } = $();
-  k(
+import { jsx as o, jsxs as L } from "react/jsx-runtime";
+import { useSyncExternalStore as $, useContext as m, useCallback as C, useMemo as W } from "react";
+import { FieldInheritContext as D } from "../contexts/FieldInheritContext.js";
+import { GridContext as E } from "../contexts/GridContext.js";
+import { LayoutConfigContext as G } from "../contexts/LayoutConfigContext.js";
+import { useNexusContext as H } from "../contexts/NexusContext.js";
+import { resolveColSpan as I } from "../utils/resolveColSpan.js";
+function X({ dataPath: t, layoutKey: c }) {
+  const { engine: i, config: l, form: h } = H();
+  $(
     (n) => i.subscribeField(t, n),
     () => i.getFieldVersion(t),
     () => i.getFieldVersion(t)
   );
-  const e = i.getFieldState(t), C = a(B), v = a(L), s = a(q), F = g(
+  const e = i.getFieldState(t), w = m(E), F = m(G), d = m(D), v = C(
     (n) => {
       i.setFieldValue(t, n);
     },
     [i, t]
-  ), W = g(
+  ), S = C(
     (n) => {
       n.currentTarget.contains(n.relatedTarget) || i.validateField(t, { trigger: "blur" });
     },
     [i, t]
-  ), h = x(
-    () => e?.meta.enum ? e.meta.enum.map((n, l) => ({
+  ), N = W(
+    () => e?.meta.enum ? e.meta.enum.map((n, s) => ({
       value: n,
-      label: e.meta.enumNames?.[l] ?? String(n)
+      label: e.meta.enumNames?.[s] ?? String(n)
     })) : e?.props.options,
     [e?.meta.enum, e?.meta.enumNames, e?.props.options]
-  ), w = x(() => {
+  ), O = W(() => {
     const n = {};
     if (e?.reactions) {
-      for (const l of e.reactions)
-        if (l.dependencies)
-          for (const f of l.dependencies)
-            n[f] = i.getFieldValue(f);
+      for (const s of e.reactions)
+        if (s.dependencies)
+          for (const b of s.dependencies)
+            n[b] = i.getFieldValue(b);
     }
     return n;
   }, [e?.reactions, i]);
   if (!e)
     return i.getSnapshot() > 0 && console.warn(`[NexusField] Field not found: ${t}`), null;
-  if (s.visible === !1 || !e.visible)
-    return v.removeHidden === !0 ? null : /* @__PURE__ */ d("div", { className: "hidden", "data-nexus-hidden": t });
-  const m = o.readOnly || s.readOnly === !0 || e.readOnly, S = s.disabled === !0 || e.disabled, c = m && !!e.meta.readOnlyWidget, N = c ? e.meta.readOnlyWidget : e.meta.widget;
-  let r = i.getWidget(N);
-  if (!r && c && (r = i.getWidget(e.meta.widget)), !r)
-    return /* @__PURE__ */ j("div", { className: "text-xs text-red-500", "data-nexus-field": t, children: [
+  if (d.visible === !1 || !e.visible)
+    return F.removeHidden === !0 ? null : /* @__PURE__ */ o("div", { className: "hidden", "data-nexus-hidden": t });
+  const p = l.readOnly || d.readOnly === !0 || e.readOnly, T = d.disabled === !0 || e.disabled, u = p && !!e.meta.readOnlyWidget, V = u ? e.meta.readOnlyWidget : e.meta.widget;
+  let r = i.getWidget(V);
+  if (!r && u && (r = i.getWidget(e.meta.widget)), !r)
+    return /* @__PURE__ */ L("div", { className: "text-xs text-red-500", "data-nexus-field": t, children: [
       '⚠️ Widget "',
       e.meta.widget,
       '" 未注册 (path: ',
       t,
       ")"
     ] });
-  const O = e.meta.displayType ?? o.displayType, T = e.meta.labelWidth ?? o.labelWidth, V = e.meta.column ?? o.column, u = D(e.meta.colSpan, C), p = {
+  const j = e.meta.displayType ?? l.displayType, k = e.meta.labelWidth ?? l.labelWidth, q = e.meta.column ?? l.column, f = I(e.meta.colSpan, w), g = {
     ...e.meta.width ? { width: e.meta.width, flexShrink: 0 } : {},
-    ...u ? { gridColumn: `span ${u}` } : {}
+    ...f ? { gridColumn: `span ${f}` } : {}
+  }, x = i.getFieldWrapper(), B = {
+    label: e.meta.label,
+    title: e.meta.title,
+    description: e.meta.description,
+    errors: e.errors,
+    required: e.required,
+    extra: e.meta.extra,
+    width: e.meta.width,
+    displayType: j,
+    labelWidth: k,
+    column: q
+  }, y = {
+    dataPath: t,
+    path: t,
+    value: e.value,
+    onChange: v,
+    disabled: T,
+    readOnly: p,
+    loading: e.loading,
+    placeholder: e.meta.placeholder,
+    options: N,
+    form: h,
+    dependValues: O,
+    items: e.meta.items,
+    ...e.props
   };
-  return /* @__PURE__ */ d(
+  let a;
+  return x ? a = /* @__PURE__ */ o(x, { ...B, children: /* @__PURE__ */ o(r, { ...y }) }, c) : a = /* @__PURE__ */ o(r, { ...y }, c), /* @__PURE__ */ o(
     "div",
     {
       "data-nexus-field": t,
-      onBlur: W,
-      style: Object.keys(p).length > 0 ? p : void 0,
-      children: /* @__PURE__ */ d(
-        r,
-        {
-          dataPath: t,
-          path: t,
-          value: e.value,
-          onChange: F,
-          disabled: S,
-          readOnly: m,
-          loading: e.loading,
-          required: e.required,
-          title: e.meta.title,
-          description: e.meta.description,
-          placeholder: e.meta.placeholder,
-          label: e.meta.label,
-          options: h,
-          errors: e.errors,
-          extra: e.meta.extra,
-          displayType: O,
-          labelWidth: T,
-          column: V,
-          form: b,
-          dependValues: w,
-          items: e.meta.items,
-          ...e.props
-        },
-        y
-      )
+      onBlur: S,
+      style: Object.keys(g).length > 0 ? g : void 0,
+      children: a
     }
   );
 }
 export {
-  A as NexusField
+  X as NexusField
 };

package/dist/es/components/NexusForm.d.ts

@@ -32,6 +32,13 @@ export interface NexusFormProps {
     onFinish?: (formData: Record<string, unknown>) => void | Promise<void>;
     /** 校验失败回调 */
     onFinishFailed?: (errors: Map<string, string[]>) => void;
+    /**
+     * 表单首次加载回调：非空 schema 首次传入并完成渲染后执行一次
+     * - undefined / null / {}（无 properties）均视为「空」schema，不触发
+     * - schema 由空变为非空时，于首个非空渲染提交后触发
+     * - 后续 schema 变更不重复触发
+     */
+    onMount?: () => void;
     /** 是否显示默认 footer（提交/重置按钮），或自定义 footer */
     footer?: boolean | ReactNode;
     /** 自定义类名 */
@@ -74,4 +81,4 @@ export interface NexusFormProps {
 /**
  * NexusForm — 顶层表单组件
  */
-export declare function NexusForm({ form, schema, initialValues, widgets, layouts, onFinish, onFinishFailed, footer, className, style, children, labelCol, labelWidth, colon, label, displayType, readOnly, column, watch, removeHiddenData, }: NexusFormProps): import("react").JSX.Element;
+export declare function NexusForm({ form, schema, initialValues, widgets, layouts, onFinish, onFinishFailed, onMount, footer, className, style, children, labelCol, labelWidth, colon, label, displayType, readOnly, column, watch, removeHiddenData, }: NexusFormProps): import("react").JSX.Element;

package/dist/es/components/NexusForm.js

@@ -1,120 +1,127 @@
-import { jsx as b, jsxs as L } from "react/jsx-runtime";
-import { useRef as l, useEffect as o, useSyncExternalStore as Q, useMemo as y, useCallback as W } from "react";
-import { renderTreeNode as U } from "../utils/renderTreeNode.js";
-import { NexusFormProvider as X } from "./NexusFormProvider.js";
+import { jsx as b, jsxs as k } from "react/jsx-runtime";
+import { useRef as i, useEffect as l, useSyncExternalStore as Z, useMemo as y, useCallback as O } from "react";
+import { renderTreeNode as H } from "../utils/renderTreeNode.js";
+import { NexusFormProvider as ee } from "./NexusFormProvider.js";
 function s() {
 }
-function ne({
-  form: n,
-  schema: t,
-  initialValues: _,
+function oe({
+  form: t,
+  schema: e,
+  initialValues: D,
   widgets: u,
   layouts: c,
-  onFinish: j,
-  onFinishFailed: k,
-  footer: a = !1,
-  className: D,
-  style: O,
-  children: V,
-  labelCol: f,
-  labelWidth: $,
-  colon: I,
-  label: M,
-  displayType: P,
-  readOnly: g,
-  column: q,
+  onFinish: M,
+  onFinishFailed: V,
+  onMount: g,
+  footer: f = !1,
+  className: $,
+  style: I,
+  children: P,
+  labelCol: a,
+  labelWidth: q,
+  colon: w,
+  label: z,
+  displayType: A,
+  readOnly: R,
+  column: B,
   watch: m,
-  removeHiddenData: R = !0
+  removeHiddenData: F = !0
 }) {
-  const e = n._getEngine(), x = l(null), F = P ?? t?.displayType ?? "row", C = M ?? t?.label ?? !0, S = I ?? t?.colon, r = $ ?? t?.labelWidth, T = g ?? t?.readOnly ?? !1, i = q ?? t?.column;
-  o(() => {
-    u && e.registerWidgets(u), c && e.registerLayouts(c);
-  }, [e, u, c]);
-  const h = l(!0), w = l(_);
-  o(() => {
-    t && (h.current ? (e.init(t, w.current), h.current = !1) : e.init(t, e.getFormData()));
-  }, [e, t]);
-  const N = l(s), v = l(s);
-  N.current = j ?? s, v.current = k ?? s, o(() => {
-    n._bind(
+  const n = t._getEngine(), x = i(null), S = A ?? e?.displayType ?? "row", C = z ?? e?.label ?? !0, T = w ?? e?.colon, r = q ?? e?.labelWidth, E = R ?? e?.readOnly ?? !1, o = B ?? e?.column;
+  l(() => {
+    u && n.registerWidgets(u), c && n.registerLayouts(c);
+  }, [n, u, c]);
+  const N = i(!0), G = i(D);
+  l(() => {
+    e && (N.current ? (n.init(e, G.current), N.current = !1) : n.init(e, n.getFormData()));
+  }, [n, e]);
+  const h = i(g);
+  h.current = g;
+  const j = i(!1), v = !e || typeof e == "object" && Object.keys(e).length === 0;
+  l(() => {
+    j.current || v || (j.current = !0, h.current?.());
+  }, [v]);
+  const L = i(s), W = i(s);
+  L.current = M ?? s, W.current = V ?? s, l(() => {
+    t._bind(
       x.current,
-      () => N.current,
-      () => v.current
+      () => L.current,
+      () => W.current
     );
-  }, [n]), o(() => {
-    n._syncConfig({ removeHiddenData: R, watch: m });
-  }, [n, R, m]);
-  const z = Q(
-    e.subscribeStore,
-    e.getSnapshot,
-    e.getSnapshot
-  ), A = y(() => e.getRenderTree(), [e, z]), B = W(
+  }, [t]), l(() => {
+    t._syncConfig({ removeHiddenData: F, watch: m });
+  }, [t, F, m]);
+  const J = Z(
+    n.subscribeStore,
+    n.getSnapshot,
+    n.getSnapshot
+  ), K = y(() => n.getRenderTree(), [n, J]), Q = O(
     async (p) => {
-      p.preventDefault(), await n.submit();
+      p.preventDefault(), await t.submit();
     },
-    [n]
-  ), G = W(() => {
-    n.resetFields();
-  }, [n]);
+    [t]
+  ), U = O(() => {
+    t.resetFields();
+  }, [t]);
   let d = null;
-  a === !0 ? d = /* @__PURE__ */ L("div", { className: "mt-4", children: [
+  f === !0 ? d = /* @__PURE__ */ k("div", { className: "mt-4", children: [
     /* @__PURE__ */ b("button", { type: "submit", children: "提交" }),
     " ",
-    /* @__PURE__ */ b("button", { type: "button", onClick: G, children: "重置" })
-  ] }) : a && (d = a);
-  const E = y(() => {
-    if (f)
-      return f;
+    /* @__PURE__ */ b("button", { type: "button", onClick: U, children: "重置" })
+  ] }) : f && (d = f);
+  const _ = y(() => {
+    if (a)
+      return a;
     if (r)
       return {
         style: {
           width: typeof r == "number" ? `${r}px` : r
         }
       };
-  }, [f, r]), J = y(
+  }, [a, r]), X = y(
     () => ({
-      labelCol: E,
+      labelCol: _,
       labelWidth: r,
-      colon: S,
+      colon: T,
       label: C,
-      displayType: F,
-      readOnly: T,
-      column: i
+      displayType: S,
+      readOnly: E,
+      column: o
     }),
     [
-      E,
+      _,
       r,
-      S,
-      C,
-      F,
       T,
-      i
+      C,
+      S,
+      E,
+      o
     ]
   );
-  return /* @__PURE__ */ b(X, { engine: e, config: J, form: n, children: /* @__PURE__ */ L(
+  return /* @__PURE__ */ b(ee, { engine: n, config: X, form: t, children: /* @__PURE__ */ k(
     "form",
     {
       ref: x,
-      onSubmit: B,
-      className: D,
+      onSubmit: Q,
+      className: $,
       style: {
-        ...O,
+        ...I,
         // 当配置了 column 时，使用 CSS Grid 布局
-        ...i && i > 1 ? {
+        ...o && o > 1 ? {
           display: "grid",
-          gridTemplateColumns: `repeat(${i}, 1fr)`,
+          gridTemplateColumns: `repeat(${o}, 1fr)`,
           gap: "0 16px"
         } : {}
       },
       noValidate: !0,
       children: [
-        A.map((p, K) => U(p, K)),
-        !g && d,
-        V
+        K.map((p, Y) => H(p, Y)),
+        !R && d,
+        P
       ]
     }
   ) });
 }
 export {
-  ne as NexusForm
+  oe as NexusForm
 };

package/dist/es/hooks/useForm.d.ts

@@ -2,5 +2,14 @@ import { NexusEngine } from '@xbeeant/form-engine';
 import { FormController } from '../components/FormController';
 /**
  * useForm — 创建 Form 实例
+ *
+ * 支持一个页面挂载多个表单实例：
+ * - `useForm()`：独立实例（未注册，不参与跨表单联动）
+ * - `useForm(formId)`：创建带 formId 的实例，自动注册到默认表单注册表，
+ *   可通过 schema `crossForm` reaction / `engine.linkForm` 与其他表单联动
+ * - `useForm(formId, engine)`：复用外部创建的引擎（如 `new NexusEngine({ formId })`）
+ *
+ * @param formId - 可选，表单实例唯一标识（跨表单联动寻址）
+ * @param engine - 可选，外部引擎实例（缺省内部创建）
  */
-export declare function useForm(engine?: NexusEngine): [FormController];
+export declare function useForm(formId?: string, engine?: NexusEngine): [FormController];

package/dist/es/hooks/useForm.js

@@ -1,9 +1,12 @@
-import { useRef as e } from "react";
-import { FormController as n } from "../components/FormController.js";
-function f(o) {
-  const r = e(null);
-  return r.current || (r.current = new n(o)), [r.current];
+import { NexusEngine as n } from "@xbeeant/form-engine";
+import { useRef as t } from "react";
+import { FormController as u } from "../components/FormController.js";
+function c(e, o) {
+  const r = t(null);
+  return r.current || (r.current = new u(
+    o ?? (e ? new n({ formId: e }) : void 0)
+  )), [r.current];
 }
 export {
-  f as useForm
+  c as useForm
 };

package/dist/es/index.js

@@ -1,42 +1,43 @@
-import { FormController as r } from "./components/FormController.js";
-import { NexusField as x } from "./components/NexusField.js";
-import { NexusForm as f } from "./components/NexusForm.js";
-import { NexusFormProvider as u } from "./components/NexusFormProvider.js";
+import './styles.css';/* empty css           */
+import { FormController as t } from "./components/FormController.js";
+import { NexusField as m } from "./components/NexusField.js";
+import { NexusForm as p } from "./components/NexusForm.js";
+import { NexusFormProvider as s } from "./components/NexusFormProvider.js";
 import { NexusLayout as a } from "./components/NexusLayout.js";
-import { NexusObject as l } from "./components/NexusObject.js";
-import { FieldInheritContext as n } from "./contexts/FieldInheritContext.js";
-import { GridContext as C } from "./contexts/GridContext.js";
-import { LayoutConfigContext as h } from "./contexts/LayoutConfigContext.js";
-import { useEngine as W } from "./hooks/useEngine.js";
-import { useFieldState as y } from "./hooks/useFieldState.js";
-import { useFieldValidator as S } from "./hooks/useFieldValidator.js";
-import { useFieldValue as b } from "./hooks/useFieldValue.js";
-import { useForm as v } from "./hooks/useForm.js";
-import { useFormConfig as D } from "./hooks/useFormConfig.js";
-import { useFormData as G } from "./hooks/useFormData.js";
-import { useWatch as M } from "./hooks/useWatch.js";
-import { useWatchAll as P } from "./hooks/useWatchAll.js";
-import { useWatchMultiple as q } from "./hooks/useWatchMultiple.js";
-import { useWatchState as z } from "./hooks/useWatchState.js";
+import { NexusObject as F } from "./components/NexusObject.js";
+import { FieldInheritContext as d } from "./contexts/FieldInheritContext.js";
+import { GridContext as c } from "./contexts/GridContext.js";
+import { LayoutConfigContext as N } from "./contexts/LayoutConfigContext.js";
+import { useEngine as g } from "./hooks/useEngine.js";
+import { useFieldState as L } from "./hooks/useFieldState.js";
+import { useFieldValidator as V } from "./hooks/useFieldValidator.js";
+import { useFieldValue as j } from "./hooks/useFieldValue.js";
+import { useForm as A } from "./hooks/useForm.js";
+import { useFormConfig as E } from "./hooks/useFormConfig.js";
+import { useFormData as I } from "./hooks/useFormData.js";
+import { useWatch as O } from "./hooks/useWatch.js";
+import { useWatchAll as k } from "./hooks/useWatchAll.js";
+import { useWatchMultiple as w } from "./hooks/useWatchMultiple.js";
+import { useWatchState as B } from "./hooks/useWatchState.js";
 export {
-  n as FieldInheritContext,
-  r as FormController,
-  C as GridContext,
-  h as LayoutConfigContext,
-  x as NexusField,
-  f as NexusForm,
-  u as NexusFormProvider,
+  d as FieldInheritContext,
+  t as FormController,
+  c as GridContext,
+  N as LayoutConfigContext,
+  m as NexusField,
+  p as NexusForm,
+  s as NexusFormProvider,
   a as NexusLayout,
-  l as NexusObject,
-  W as useEngine,
-  y as useFieldState,
-  S as useFieldValidator,
-  b as useFieldValue,
-  v as useForm,
-  D as useFormConfig,
-  G as useFormData,
-  M as useWatch,
-  P as useWatchAll,
-  q as useWatchMultiple,
-  z as useWatchState
+  F as NexusObject,
+  g as useEngine,
+  L as useFieldState,
+  V as useFieldValidator,
+  j as useFieldValue,
+  A as useForm,
+  E as useFormConfig,
+  I as useFormData,
+  O as useWatch,
+  k as useWatchAll,
+  w as useWatchMultiple,
+  B as useWatchState
 };

package/dist/es/styles.css

@@ -0,0 +1 @@
+@layer properties{@supports (((-webkit-hyphens:none)) and (not (margin-trim:inline))) or ((-moz-orient:inline) and (not (color:rgb(from red r g b)))){*,:before,:after,::backdrop{--tw-font-weight:initial;--tw-blur:initial;--tw-brightness:initial;--tw-contrast:initial;--tw-grayscale:initial;--tw-hue-rotate:initial;--tw-invert:initial;--tw-opacity:initial;--tw-saturate:initial;--tw-sepia:initial;--tw-drop-shadow:initial;--tw-drop-shadow-color:initial;--tw-drop-shadow-alpha:100%;--tw-drop-shadow-size:initial;--tw-duration:initial;--tw-ease:initial}}}:root,:host{--color-red-500:oklch(63.7% .237 25.331);--spacing:.25rem;--text-xs:.75rem;--text-xs--line-height:calc(1 / .75);--font-weight-bold:700;--ease-in-out:cubic-bezier(.4, 0, .2, 1);--default-transition-duration:.15s;--default-transition-timing-function:cubic-bezier(.4, 0, .2, 1)}.visible{visibility:visible}.mt-4{margin-top:calc(var(--spacing) * 4)}.mb-2{margin-bottom:calc(var(--spacing) * 2)}.mb-4{margin-bottom:calc(var(--spacing) * 4)}.block{display:block}.flex{display:flex}.grid{display:grid}.hidden{display:none}.inline{display:inline}.rotate-0{rotate:0deg}.rotate-90{rotate:90deg}.cursor-pointer{cursor:pointer}.gap-1{gap:var(--spacing)}.gap-x-4{column-gap:calc(var(--spacing) * 4)}.border-none{--tw-border-style:none;border-style:none}.bg-transparent{background-color:#0000}.p-0{padding:0}.align-middle{vertical-align:middle}.text-xs{font-size:var(--text-xs);line-height:var(--tw-leading,var(--text-xs--line-height))}.font-bold{--tw-font-weight:var(--font-weight-bold);font-weight:var(--font-weight-bold)}.text-red-500{color:var(--color-red-500)}.blur{--tw-blur:blur(8px);filter:var(--tw-blur,) var(--tw-brightness,) var(--tw-contrast,) var(--tw-grayscale,) var(--tw-hue-rotate,) var(--tw-invert,) var(--tw-saturate,) var(--tw-sepia,) var(--tw-drop-shadow,)}.transition-transform{transition-property:transform,translate,scale,rotate;transition-timing-function:var(--tw-ease,var(--default-transition-timing-function));transition-duration:var(--tw-duration,var(--default-transition-duration))}.duration-200{--tw-duration:.2s;transition-duration:.2s}.ease-in-out{--tw-ease:var(--ease-in-out);transition-timing-function:var(--ease-in-out)}.select-none{-webkit-user-select:none;user-select:none}@property --tw-font-weight{syntax:"*";inherits:false}@property --tw-blur{syntax:"*";inherits:false}@property --tw-brightness{syntax:"*";inherits:false}@property --tw-contrast{syntax:"*";inherits:false}@property --tw-grayscale{syntax:"*";inherits:false}@property --tw-hue-rotate{syntax:"*";inherits:false}@property --tw-invert{syntax:"*";inherits:false}@property --tw-opacity{syntax:"*";inherits:false}@property --tw-saturate{syntax:"*";inherits:false}@property --tw-sepia{syntax:"*";inherits:false}@property --tw-drop-shadow{syntax:"*";inherits:false}@property --tw-drop-shadow-color{syntax:"*";inherits:false}@property --tw-drop-shadow-alpha{syntax:"<percentage>";inherits:false;initial-value:100%}@property --tw-drop-shadow-size{syntax:"*";inherits:false}@property --tw-duration{syntax:"*";inherits:false}@property --tw-ease{syntax:"*";inherits:false}

package/dist/es/tailwind.css

@@ -0,0 +1 @@
+@layer properties{@supports (((-webkit-hyphens:none)) and (not (margin-trim:inline))) or ((-moz-orient:inline) and (not (color:rgb(from red r g b)))){*,:before,:after,::backdrop{--tw-font-weight:initial;--tw-blur:initial;--tw-brightness:initial;--tw-contrast:initial;--tw-grayscale:initial;--tw-hue-rotate:initial;--tw-invert:initial;--tw-opacity:initial;--tw-saturate:initial;--tw-sepia:initial;--tw-drop-shadow:initial;--tw-drop-shadow-color:initial;--tw-drop-shadow-alpha:100%;--tw-drop-shadow-size:initial;--tw-duration:initial;--tw-ease:initial}}}:root,:host{--color-red-500:oklch(63.7% .237 25.331);--spacing:.25rem;--text-xs:.75rem;--text-xs--line-height:calc(1 / .75);--font-weight-bold:700;--ease-in-out:cubic-bezier(.4, 0, .2, 1);--default-transition-duration:.15s;--default-transition-timing-function:cubic-bezier(.4, 0, .2, 1)}.visible{visibility:visible}.mt-4{margin-top:calc(var(--spacing) * 4)}.mb-2{margin-bottom:calc(var(--spacing) * 2)}.mb-4{margin-bottom:calc(var(--spacing) * 4)}.block{display:block}.flex{display:flex}.grid{display:grid}.hidden{display:none}.inline{display:inline}.rotate-0{rotate:0deg}.rotate-90{rotate:90deg}.cursor-pointer{cursor:pointer}.gap-1{gap:var(--spacing)}.gap-x-4{column-gap:calc(var(--spacing) * 4)}.border-none{--tw-border-style:none;border-style:none}.bg-transparent{background-color:#0000}.p-0{padding:0}.align-middle{vertical-align:middle}.text-xs{font-size:var(--text-xs);line-height:var(--tw-leading,var(--text-xs--line-height))}.font-bold{--tw-font-weight:var(--font-weight-bold);font-weight:var(--font-weight-bold)}.text-red-500{color:var(--color-red-500)}.blur{--tw-blur:blur(8px);filter:var(--tw-blur,) var(--tw-brightness,) var(--tw-contrast,) var(--tw-grayscale,) var(--tw-hue-rotate,) var(--tw-invert,) var(--tw-saturate,) var(--tw-sepia,) var(--tw-drop-shadow,)}.transition-transform{transition-property:transform,translate,scale,rotate;transition-timing-function:var(--tw-ease,var(--default-transition-timing-function));transition-duration:var(--tw-duration,var(--default-transition-duration))}.duration-200{--tw-duration:.2s;transition-duration:.2s}.ease-in-out{--tw-ease:var(--ease-in-out);transition-timing-function:var(--ease-in-out)}.select-none{-webkit-user-select:none;user-select:none}@property --tw-font-weight{syntax:"*";inherits:false}@property --tw-blur{syntax:"*";inherits:false}@property --tw-brightness{syntax:"*";inherits:false}@property --tw-contrast{syntax:"*";inherits:false}@property --tw-grayscale{syntax:"*";inherits:false}@property --tw-hue-rotate{syntax:"*";inherits:false}@property --tw-invert{syntax:"*";inherits:false}@property --tw-opacity{syntax:"*";inherits:false}@property --tw-saturate{syntax:"*";inherits:false}@property --tw-sepia{syntax:"*";inherits:false}@property --tw-drop-shadow{syntax:"*";inherits:false}@property --tw-drop-shadow-color{syntax:"*";inherits:false}@property --tw-drop-shadow-alpha{syntax:"<percentage>";inherits:false;initial-value:100%}@property --tw-drop-shadow-size{syntax:"*";inherits:false}@property --tw-duration{syntax:"*";inherits:false}@property --tw-ease{syntax:"*";inherits:false}

package/dist/umd/index.css

@@ -0,0 +1 @@
+@layer properties{@supports (((-webkit-hyphens:none)) and (not (margin-trim:inline))) or ((-moz-orient:inline) and (not (color:rgb(from red r g b)))){*,:before,:after,::backdrop{--tw-font-weight:initial;--tw-blur:initial;--tw-brightness:initial;--tw-contrast:initial;--tw-grayscale:initial;--tw-hue-rotate:initial;--tw-invert:initial;--tw-opacity:initial;--tw-saturate:initial;--tw-sepia:initial;--tw-drop-shadow:initial;--tw-drop-shadow-color:initial;--tw-drop-shadow-alpha:100%;--tw-drop-shadow-size:initial;--tw-duration:initial;--tw-ease:initial}}}:root,:host{--color-red-500:oklch(63.7% .237 25.331);--spacing:.25rem;--text-xs:.75rem;--text-xs--line-height:calc(1 / .75);--font-weight-bold:700;--ease-in-out:cubic-bezier(.4, 0, .2, 1);--default-transition-duration:.15s;--default-transition-timing-function:cubic-bezier(.4, 0, .2, 1)}.visible{visibility:visible}.mt-4{margin-top:calc(var(--spacing) * 4)}.mb-2{margin-bottom:calc(var(--spacing) * 2)}.mb-4{margin-bottom:calc(var(--spacing) * 4)}.block{display:block}.flex{display:flex}.grid{display:grid}.hidden{display:none}.inline{display:inline}.rotate-0{rotate:0deg}.rotate-90{rotate:90deg}.cursor-pointer{cursor:pointer}.gap-1{gap:var(--spacing)}.gap-x-4{column-gap:calc(var(--spacing) * 4)}.border-none{--tw-border-style:none;border-style:none}.bg-transparent{background-color:#0000}.p-0{padding:0}.align-middle{vertical-align:middle}.text-xs{font-size:var(--text-xs);line-height:var(--tw-leading,var(--text-xs--line-height))}.font-bold{--tw-font-weight:var(--font-weight-bold);font-weight:var(--font-weight-bold)}.text-red-500{color:var(--color-red-500)}.blur{--tw-blur:blur(8px);filter:var(--tw-blur,) var(--tw-brightness,) var(--tw-contrast,) var(--tw-grayscale,) var(--tw-hue-rotate,) var(--tw-invert,) var(--tw-saturate,) var(--tw-sepia,) var(--tw-drop-shadow,)}.transition-transform{transition-property:transform,translate,scale,rotate;transition-timing-function:var(--tw-ease,var(--default-transition-timing-function));transition-duration:var(--tw-duration,var(--default-transition-duration))}.duration-200{--tw-duration:.2s;transition-duration:.2s}.ease-in-out{--tw-ease:var(--ease-in-out);transition-timing-function:var(--ease-in-out)}.select-none{-webkit-user-select:none;user-select:none}@property --tw-font-weight{syntax:"*";inherits:false}@property --tw-blur{syntax:"*";inherits:false}@property --tw-brightness{syntax:"*";inherits:false}@property --tw-contrast{syntax:"*";inherits:false}@property --tw-grayscale{syntax:"*";inherits:false}@property --tw-hue-rotate{syntax:"*";inherits:false}@property --tw-invert{syntax:"*";inherits:false}@property --tw-opacity{syntax:"*";inherits:false}@property --tw-saturate{syntax:"*";inherits:false}@property --tw-sepia{syntax:"*";inherits:false}@property --tw-drop-shadow{syntax:"*";inherits:false}@property --tw-drop-shadow-color{syntax:"*";inherits:false}@property --tw-drop-shadow-alpha{syntax:"<percentage>";inherits:false;initial-value:100%}@property --tw-drop-shadow-size{syntax:"*";inherits:false}@property --tw-duration{syntax:"*";inherits:false}@property --tw-ease{syntax:"*";inherits:false}

package/dist/umd/index.umd.cjs

@@ -1 +1 @@
-(function(a,N){typeof exports=="object"&&typeof module<"u"?N(exports,require("@xbeeant/form-engine"),require("react/jsx-runtime"),require("react")):typeof define=="function"&&define.amd?define(["exports","@xbeeant/form-engine","react/jsx-runtime","react"],N):(a=typeof globalThis<"u"?globalThis:a||self,N(a.NexusFormEngineReact={},a.formEngine,a.jsxRuntime,a.react))})(this,(function(a,N,c,s){"use strict";class P{engine;formElementRef;getOnFinish;getOnFinishFailed;removeHiddenData=!0;watchers=new Map;globalWatcher=null;constructor(t){this.engine=t??new N.NexusEngine,this.engine.hasPlugin("async-validator")||this.engine.use(new N.AsyncValidatorPlugin(this.engine)),this.formElementRef={current:null},this.getOnFinish=()=>()=>{},this.getOnFinishFailed=()=>()=>{}}_bind(t,i,r){this.formElementRef.current=t,this.getOnFinish=i,this.getOnFinishFailed=r,this.engine.registerOnFieldValueChange((l,n)=>this._onFieldValueChange(l,n))}_syncConfig(t){if(t.removeHiddenData!==void 0&&(this.removeHiddenData=t.removeHiddenData),t.watch){this.watchers.clear(),this.globalWatcher=null;for(const[i,r]of Object.entries(t.watch))i==="#"?this.globalWatcher=r:this.watchers.set(i,r)}}_onFieldValueChange(t,i){const r=this.engine.getFormData(),l=this.removeHiddenData?r:this.engine.getAllFormData();this.globalWatcher&&this.globalWatcher(l,l,t);const n=this.watchers.get(t);n&&n(i,l)}_getEngine(){return this.engine}async submit(){const t=await this.engine.validate();if(t.size>0){this.focusFirstError(t),this.getOnFinishFailed()?.(t);return}const i=this.removeHiddenData?this.engine.getFormData():this.engine.getAllFormData();await this.getOnFinish()?.(i)}focusFirstError(t){const i=this.formElementRef.current;if(!i||t.size===0)return;const r=new Set(t.keys());requestAnimationFrame(()=>{const n=i.querySelectorAll("[data-nexus-field]");for(const o of Array.from(n)){const u=o.getAttribute("data-nexus-field");if(!u||!r.has(u))continue;o.scrollIntoView({behavior:"smooth",block:"center"}),o.querySelector('input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])')?.focus();return}})}resetFields(){this.engine.reset()}setErrorFields(t){this.engine.setErrorFields(t)}setValues(t){this.engine.setFieldValues(t)}setValueByPath(t,i){this.engine.setFieldValue(t,i)}setSchemaByPath(t,i){this.engine.setSchemaByPath(t,i)}setSchema(t){this.engine.setSchema(t)}getValues(t){return this.engine.getFormData(t)}getHiddenValues(){return this.engine.getHiddenValues()}getAllValues(){return this.engine.getAllFormData()}getValueByPath(t){return this.engine.getFieldValue(t)}registerValidator(t,i){this.engine.registerFieldValidator(t,i)}unregisterValidator(t,i){this.engine.unregisterFieldValidator(t,i)}revalidateField(t){this.engine.validateField(t,{trigger:"change"})}getSchema(){return this.engine.getSchema()}removeErrorField(t){this.engine.removeErrorField(t)}scrollToPath(t){this.formElementRef.current?.querySelector(`[data-nexus-field="${t}"]`)?.scrollIntoView({behavior:"smooth",block:"center"})}getFieldError(t){return this.engine.getFieldError(t)}getFieldsError(){return this.engine.getFieldsError()}validateFields(t){return this.engine.validate(t)}getFieldState(t){return this.engine.getFieldState(t)}}const R=s.createContext({}),M=s.createContext(null),k=s.createContext({}),H=s.createContext(null);function S(){const e=s.useContext(H);if(!e)throw new Error("[NexusField] Must be used within <NexusFormProvider>");return e}function q(e,t){if(e!==void 0)return e;if(t&&t.column>0)return Math.max(1,Math.round(t.column/24))}function J({dataPath:e,layoutKey:t}){const{engine:i,config:r,form:l}=S();s.useSyncExternalStore(y=>i.subscribeField(e,y),()=>i.getFieldVersion(e),()=>i.getFieldVersion(e));const n=i.getFieldState(e),o=s.useContext(M),u=s.useContext(k),g=s.useContext(R),f=s.useCallback(y=>{i.setFieldValue(e,y)},[i,e]),b=s.useCallback(y=>{y.currentTarget.contains(y.relatedTarget)||i.validateField(e,{trigger:"blur"})},[i,e]),d=s.useMemo(()=>n?.meta.enum?n.meta.enum.map((y,E)=>({value:y,label:n.meta.enumNames?.[E]??String(y)})):n?.props.options,[n?.meta.enum,n?.meta.enumNames,n?.props.options]),F=s.useMemo(()=>{const y={};if(n?.reactions){for(const E of n.reactions)if(E.dependencies)for(const p of E.dependencies)y[p]=i.getFieldValue(p)}return y},[n?.reactions,i]);if(!n)return i.getSnapshot()>0&&console.warn(`[NexusField] Field not found: ${e}`),null;if(g.visible===!1||!n.visible)return u.removeHidden===!0?null:c.jsx("div",{className:"hidden","data-nexus-hidden":e});const h=r.readOnly||g.readOnly===!0||n.readOnly,C=g.disabled===!0||n.disabled,v=h&&!!n.meta.readOnlyWidget,x=v?n.meta.readOnlyWidget:n.meta.widget;let V=i.getWidget(x);if(!V&&v&&(V=i.getWidget(n.meta.widget)),!V)return c.jsxs("div",{className:"text-xs text-red-500","data-nexus-field":e,children:['⚠️ Widget "',n.meta.widget,'" 未注册 (path: ',e,")"]});const j=n.meta.displayType??r.displayType,D=n.meta.labelWidth??r.labelWidth,m=n.meta.column??r.column,O=q(n.meta.colSpan,o),w={...n.meta.width?{width:n.meta.width,flexShrink:0}:{},...O?{gridColumn:`span ${O}`}:{}};return c.jsx("div",{"data-nexus-field":e,onBlur:b,style:Object.keys(w).length>0?w:void 0,children:c.jsx(V,{dataPath:e,path:e,value:n.value,onChange:f,disabled:C,readOnly:h,loading:n.loading,required:n.required,title:n.meta.title,description:n.meta.description,placeholder:n.meta.placeholder,label:n.meta.label,options:d,errors:n.errors,extra:n.meta.extra,displayType:j,labelWidth:D,column:m,form:l,dependValues:F,items:n.meta.items,...n.props},t)})}function B({node:e}){const{engine:t}=S(),i=t.getLayout(e.type),r=e.children.map((h,C)=>$(h,C)),l=s.useContext(M),n=q(e.props.colSpan,l),o={...n?{gridColumn:`span ${n}`}:{},...e.props.width?{width:e.props.width,flexShrink:0}:{}},u=s.useMemo(()=>({removeHidden:e.props.removeHidden}),[e.props.removeHidden]);if(!i)return c.jsx(k.Provider,{value:u,children:c.jsxs("div",{"data-nexus-layout":e.type,className:"mb-4",style:Object.keys(o).length>0?o:void 0,children:[e.title&&c.jsx("div",{className:"mb-2 font-bold",children:e.title}),r]})});const{displayType:g,labelWidth:f,colSpan:b,width:d,...F}=e.props;return c.jsx(k.Provider,{value:u,children:c.jsx("div",{style:Object.keys(o).length>0?o:void 0,children:c.jsx(i,{...F,node:e,title:e.title,children:r})})})}function I({node:e}){const{engine:t,config:i}=S(),r=s.useContext(R);s.useSyncExternalStore(F=>t.subscribeField(e.dataPath,F),()=>t.getFieldVersion(e.dataPath),()=>t.getFieldVersion(e.dataPath));const l=t.getFieldState(e.dataPath),[n,o]=s.useState(!1),u=(i.column??1)>1,g=u?{gridTemplateColumns:`repeat(${i.column}, 1fr)`}:{},f={disabled:r.disabled??(l?.disabled===!0?!0:void 0),readOnly:r.readOnly??(l?.readOnly===!0?!0:void 0),visible:r.visible===!1||l?.visible===!1?!1:void 0},b=f.visible===!1,d=()=>o(F=>!F);return c.jsx(R.Provider,{value:f,children:c.jsxs("div",{"data-nexus-object":e.dataPath,className:`mb-4 ${b?"hidden":""}`,children:[e.title&&c.jsxs("div",{onClick:d,className:"flex gap-1 mb-2 cursor-pointer select-none border-none bg-transparent p-0 font-bold",children:[c.jsx("svg",{width:"12",height:"12",viewBox:"0 0 24 24",fill:"none",stroke:"currentColor",strokeWidth:"2",strokeLinecap:"round",strokeLinejoin:"round",className:`align-middle transition-transform duration-200 ease-in-out ${n?"rotate-0":"rotate-90"}`,"aria-hidden":"true",children:c.jsx("polyline",{points:"9 18 15 12 9 6"})}),e.title]}),c.jsx("div",{className:`${u?"grid gap-x-4":""} ${n?"hidden":""}`,style:Object.keys(g).length>0?g:void 0,children:e.children.map((F,h)=>$(F,h))})]})})}function $(e,t){return e.type==="field"?c.jsx(J,{dataPath:e.dataPath,layoutKey:e.layoutKey},e.layoutKey||e.dataPath):e.type==="object"?c.jsx(I,{node:e},`object-${e.layoutKey}-${t}`):c.jsx(B,{node:e},`layout-${e.type}-${t}`)}function K({engine:e,config:t,form:i,children:r}){const l=s.useMemo(()=>({engine:e,config:t,form:i}),[e,t,i]);return c.jsx(H.Provider,{value:l,children:r})}function T(){}function Y({form:e,schema:t,initialValues:i,widgets:r,layouts:l,onFinish:n,onFinishFailed:o,footer:u=!1,className:g,style:f,children:b,labelCol:d,labelWidth:F,colon:h,label:C,displayType:v,readOnly:x,column:V,watch:j,removeHiddenData:D=!0}){const m=e._getEngine(),O=s.useRef(null),w=v??t?.displayType??"row",y=C??t?.label??!0,E=h??t?.colon,p=F??t?.labelWidth,G=x??t?.readOnly??!1,W=V??t?.column;s.useEffect(()=>{r&&m.registerWidgets(r),l&&m.registerLayouts(l)},[m,r,l]);const z=s.useRef(!0),ae=s.useRef(i);s.useEffect(()=>{t&&(z.current?(m.init(t,ae.current),z.current=!1):m.init(t,m.getFormData()))},[m,t]);const U=s.useRef(T),Q=s.useRef(T);U.current=n??T,Q.current=o??T,s.useEffect(()=>{e._bind(O.current,()=>U.current,()=>Q.current)},[e]),s.useEffect(()=>{e._syncConfig({removeHiddenData:D,watch:j})},[e,D,j]);const ce=s.useSyncExternalStore(m.subscribeStore,m.getSnapshot,m.getSnapshot),de=s.useMemo(()=>m.getRenderTree(),[m,ce]),fe=s.useCallback(async A=>{A.preventDefault(),await e.submit()},[e]),ge=s.useCallback(()=>{e.resetFields()},[e]);let L=null;u===!0?L=c.jsxs("div",{className:"mt-4",children:[c.jsx("button",{type:"submit",children:"提交"})," ",c.jsx("button",{type:"button",onClick:ge,children:"重置"})]}):u&&(L=u);const X=s.useMemo(()=>{if(d)return d;if(p)return{style:{width:typeof p=="number"?`${p}px`:p}}},[d,p]),he=s.useMemo(()=>({labelCol:X,labelWidth:p,colon:E,label:y,displayType:w,readOnly:G,column:W}),[X,p,E,y,w,G,W]);return c.jsx(K,{engine:m,config:he,form:e,children:c.jsxs("form",{ref:O,onSubmit:fe,className:g,style:{...f,...W&&W>1?{display:"grid",gridTemplateColumns:`repeat(${W}, 1fr)`,gap:"0 16px"}:{}},noValidate:!0,children:[de.map((A,be)=>$(A,be)),!x&&L,b]})})}function _(){const{engine:e}=S();return e}function Z(e){const{engine:t}=S();return s.useSyncExternalStore(i=>t.subscribeField(e,i),()=>t.getFieldVersion(e),()=>t.getFieldVersion(e)),t.getFieldState(e)}function ee(e,t,i,r){const{engine:l}=S(),n=s.useRef(i);n.current=i;const o=s.useRef(r?.dependsOn);o.current=r?.dependsOn;const u=r?.deps;s.useEffect(()=>{if(!e||!t)return;const g=n.current;return e.registerValidator(t,g),()=>{e.unregisterValidator(t,g)}},[e,t,...u??[]]),s.useEffect(()=>{if(!t||!o.current||o.current.length===0)return;const g=l;if(!g)return;const f=t,b=o.current.map(d=>g.subscribeField(d,()=>{e?.revalidateField(f)}));return()=>{for(const d of b)d()}},[l,e,t])}function te(e){const t=_();return s.useSyncExternalStore(i=>t.subscribeField(e,i),()=>t.getFieldVersion(e),()=>t.getFieldVersion(e)),t.getFieldValue(e)}function ne(e){const t=s.useRef(null);return t.current||(t.current=new P(e)),[t.current]}function ie(){const{config:e}=S();return e}function se(){const e=_(),t=s.useSyncExternalStore(e.subscribeStore,e.getSnapshot,e.getSnapshot);return s.useMemo(()=>e.getFormData(),[e,t])}function re(e,t,i,r){const{deep:l=!1}=r||{},n=s.useRef(void 0),o=s.useRef(i);return o.current=i,s.useEffect(()=>{if(!e)return;const u=e.getFieldValue(t);n.current===void 0&&(n.current=u),(l?JSON.stringify(u)!==JSON.stringify(n.current):u!==n.current)&&(n.current=u,o.current(u));const f=e.subscribe(t,b=>{const d=b.value;(l?JSON.stringify(d)!==JSON.stringify(n.current):d!==n.current)&&(n.current=d,o.current(d))});return()=>{f()}},[e,t,l]),n.current}function le(e,t,i){const{deep:r=!1}=i||{},l=s.useRef({}),n=s.useRef({}),o=s.useRef(t);return o.current=t,s.useEffect(()=>{if(!e)return;const u=e.getFormData();l.current=u,n.current=u,o.current(u);const g=e.subscribeAll(f=>{if(r)JSON.stringify(f)!==JSON.stringify(l.current)&&(l.current=f,n.current=f,o.current(f));else{let b=!1;for(const d in f)if(f[d]!==l.current[d]){b=!0;break}b&&(l.current=f,n.current=f,o.current(f))}});return()=>{g()}},[e,r]),n.current}function oe(e,t,i,r){const{deep:l=!1}=r||{},n=s.useRef({}),o=s.useRef({}),u=s.useRef(i);u.current=i;const g=s.useRef(t);g.current=t;const f=[...t].sort().join(",");return s.useEffect(()=>{if(!e)return;const b=g.current,d={};for(const h of b)d[h]=e.getFieldValue(h);n.current=d,o.current=d,u.current(d);const F=b.map(h=>e.subscribe(h,C=>{const v=C.value,x=n.current[h];(l?JSON.stringify(v)!==JSON.stringify(x):v!==x)&&(n.current[h]=v,o.current={[h]:v},u.current(o.current))}));return()=>{for(const h of F)h()}},[e,l,f]),o.current}function ue(e,t,i){const r=s.useRef(void 0),l=s.useRef(i);return l.current=i,s.useEffect(()=>{if(!e)return;const n=e.getFieldState(t);r.current=n,n&&l.current(n);const o=e.subscribe(t,u=>{r.current=u,l.current(u)});return()=>{o()}},[e,t]),r.current||{}}a.FieldInheritContext=R,a.FormController=P,a.GridContext=M,a.LayoutConfigContext=k,a.NexusField=J,a.NexusForm=Y,a.NexusFormProvider=K,a.NexusLayout=B,a.NexusObject=I,a.useEngine=_,a.useFieldState=Z,a.useFieldValidator=ee,a.useFieldValue=te,a.useForm=ne,a.useFormConfig=ie,a.useFormData=se,a.useWatch=re,a.useWatchAll=le,a.useWatchMultiple=oe,a.useWatchState=ue,Object.defineProperty(a,Symbol.toStringTag,{value:"Module"})}));
+(function(c,x){typeof exports=="object"&&typeof module<"u"?x(exports,require("@xbeeant/form-engine"),require("react/jsx-runtime"),require("react")):typeof define=="function"&&define.amd?define(["exports","@xbeeant/form-engine","react/jsx-runtime","react"],x):(c=typeof globalThis<"u"?globalThis:c||self,x(c.NexusFormEngineReact={},c.formEngine,c.jsxRuntime,c.react))})(this,(function(c,x,a,s){"use strict";class J{engine;formElementRef;getOnFinish;getOnFinishFailed;removeHiddenData=!0;watchers=new Map;globalWatcher=null;constructor(t){this.engine=t??new x.NexusEngine,this.engine.hasPlugin("async-validator")||this.engine.use(new x.AsyncValidatorPlugin(this.engine)),this.formElementRef={current:null},this.getOnFinish=()=>()=>{},this.getOnFinishFailed=()=>()=>{}}_bind(t,i,r){this.formElementRef.current=t,this.getOnFinish=i,this.getOnFinishFailed=r,this.engine.registerOnFieldValueChange((l,n)=>this._onFieldValueChange(l,n))}_syncConfig(t){if(t.removeHiddenData!==void 0&&(this.removeHiddenData=t.removeHiddenData),t.watch){this.watchers.clear(),this.globalWatcher=null;for(const[i,r]of Object.entries(t.watch))i==="#"?this.globalWatcher=r:this.watchers.set(i,r)}}_onFieldValueChange(t,i){const r=this.engine.getFormData(),l=this.removeHiddenData?r:this.engine.getAllFormData();this.globalWatcher&&this.globalWatcher(l,l,t);const n=this.watchers.get(t);n&&n(i,l)}_getEngine(){return this.engine}getEngine(){return this.engine}async submit(){const t=await this.engine.validate();if(t.size>0){this.focusFirstError(t),this.getOnFinishFailed()?.(t);return}const i=this.removeHiddenData?this.engine.getFormData():this.engine.getAllFormData();await this.getOnFinish()?.(i)}focusFirstError(t){const i=this.formElementRef.current;if(!i||t.size===0)return;const r=new Set(t.keys());requestAnimationFrame(()=>{const n=i.querySelectorAll("[data-nexus-field]");for(const o of Array.from(n)){const u=o.getAttribute("data-nexus-field");if(!u||!r.has(u))continue;o.scrollIntoView({behavior:"smooth",block:"center"}),o.querySelector('input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])')?.focus();return}})}resetFields(){this.engine.reset()}setErrorFields(t){this.engine.setErrorFields(t)}setValues(t){this.engine.setFieldValues(t)}setValueByPath(t,i){this.engine.setFieldValue(t,i)}setSchemaByPath(t,i){this.engine.setSchemaByPath(t,i)}setSchema(t){this.engine.setSchema(t)}getValues(t){return this.engine.getFormData(t)}getHiddenValues(){return this.engine.getHiddenValues()}getAllValues(){return this.engine.getAllFormData()}getValueByPath(t){return this.engine.getFieldValue(t)}registerValidator(t,i){this.engine.registerFieldValidator(t,i)}unregisterValidator(t,i){this.engine.unregisterFieldValidator(t,i)}revalidateField(t){this.engine.validateField(t,{trigger:"change"})}getSchema(){return this.engine.getSchema()}removeErrorField(t){this.engine.removeErrorField(t)}scrollToPath(t){this.formElementRef.current?.querySelector(`[data-nexus-field="${t}"]`)?.scrollIntoView({behavior:"smooth",block:"center"})}getFieldError(t){return this.engine.getFieldError(t)}getFieldsError(){return this.engine.getFieldsError()}validateFields(t){return this.engine.validate(t)}getFieldState(t){return this.engine.getFieldState(t)}}const k=s.createContext({}),P=s.createContext(null),j=s.createContext({}),B=s.createContext(null);function V(){const e=s.useContext(B);if(!e)throw new Error("[NexusField] Must be used within <NexusFormProvider>");return e}function I(e,t){if(e!==void 0)return e;if(t&&t.column>0)return Math.max(1,Math.round(t.column/24))}function K({dataPath:e,layoutKey:t}){const{engine:i,config:r,form:l}=V();s.useSyncExternalStore(F=>i.subscribeField(e,F),()=>i.getFieldVersion(e),()=>i.getFieldVersion(e));const n=i.getFieldState(e),o=s.useContext(P),u=s.useContext(j),d=s.useContext(k),f=s.useCallback(F=>{i.setFieldValue(e,F)},[i,e]),b=s.useCallback(F=>{F.currentTarget.contains(F.relatedTarget)||i.validateField(e,{trigger:"blur"})},[i,e]),g=s.useMemo(()=>n?.meta.enum?n.meta.enum.map((F,v)=>({value:F,label:n.meta.enumNames?.[v]??String(F)})):n?.props.options,[n?.meta.enum,n?.meta.enumNames,n?.props.options]),y=s.useMemo(()=>{const F={};if(n?.reactions){for(const v of n.reactions)if(v.dependencies)for(const R of v.dependencies)F[R]=i.getFieldValue(R)}return F},[n?.reactions,i]);if(!n)return i.getSnapshot()>0&&console.warn(`[NexusField] Field not found: ${e}`),null;if(d.visible===!1||!n.visible)return u.removeHidden===!0?null:a.jsx("div",{className:"hidden","data-nexus-hidden":e});const h=r.readOnly||d.readOnly===!0||n.readOnly,E=d.disabled===!0||n.disabled,S=h&&!!n.meta.readOnlyWidget,N=S?n.meta.readOnlyWidget:n.meta.widget;let C=i.getWidget(N);if(!C&&S&&(C=i.getWidget(n.meta.widget)),!C)return a.jsxs("div",{className:"text-xs text-red-500","data-nexus-field":e,children:['⚠️ Widget "',n.meta.widget,'" 未注册 (path: ',e,")"]});const A=n.meta.displayType??r.displayType,D=n.meta.labelWidth??r.labelWidth,M=n.meta.column??r.column,m=I(n.meta.colSpan,o),O={...n.meta.width?{width:n.meta.width,flexShrink:0}:{},...m?{gridColumn:`span ${m}`}:{}},w=i.getFieldWrapper(),$={label:n.meta.label,title:n.meta.title,description:n.meta.description,errors:n.errors,required:n.required,extra:n.meta.extra,width:n.meta.width,displayType:A,labelWidth:D,column:M},W={dataPath:e,path:e,value:n.value,onChange:f,disabled:E,readOnly:h,loading:n.loading,placeholder:n.meta.placeholder,options:g,form:l,dependValues:y,items:n.meta.items,...n.props};let p;return w?p=a.jsx(w,{...$,children:a.jsx(C,{...W})},t):p=a.jsx(C,{...W},t),a.jsx("div",{"data-nexus-field":e,onBlur:b,style:Object.keys(O).length>0?O:void 0,children:p})}function G({node:e}){const{engine:t}=V(),i=t.getLayout(e.type),r=e.children.map((h,E)=>_(h,E)),l=s.useContext(P),n=I(e.props.colSpan,l),o={...n?{gridColumn:`span ${n}`}:{},...e.props.width?{width:e.props.width,flexShrink:0}:{}},u=s.useMemo(()=>({removeHidden:e.props.removeHidden}),[e.props.removeHidden]);if(!i)return a.jsx(j.Provider,{value:u,children:a.jsxs("div",{"data-nexus-layout":e.type,className:"mb-4",style:Object.keys(o).length>0?o:void 0,children:[e.title&&a.jsx("div",{className:"mb-2 font-bold",children:e.title}),r]})});const{displayType:d,labelWidth:f,colSpan:b,width:g,...y}=e.props;return a.jsx(j.Provider,{value:u,children:a.jsx("div",{style:Object.keys(o).length>0?o:void 0,children:a.jsx(i,{...y,node:e,title:e.title,children:r})})})}function z({node:e}){const{engine:t,config:i}=V(),r=s.useContext(k);s.useSyncExternalStore(y=>t.subscribeField(e.dataPath,y),()=>t.getFieldVersion(e.dataPath),()=>t.getFieldVersion(e.dataPath));const l=t.getFieldState(e.dataPath),[n,o]=s.useState(!1),u=(i.column??1)>1,d=u?{gridTemplateColumns:`repeat(${i.column}, 1fr)`}:{},f={disabled:r.disabled??(l?.disabled===!0?!0:void 0),readOnly:r.readOnly??(l?.readOnly===!0?!0:void 0),visible:r.visible===!1||l?.visible===!1?!1:void 0},b=f.visible===!1,g=()=>o(y=>!y);return a.jsx(k.Provider,{value:f,children:a.jsxs("div",{"data-nexus-object":e.dataPath,className:`mb-4 ${b?"hidden":""}`,children:[e.title&&a.jsxs("div",{onClick:g,className:"flex gap-1 mb-2 cursor-pointer select-none border-none bg-transparent p-0 font-bold",children:[a.jsx("svg",{width:"12",height:"12",viewBox:"0 0 24 24",fill:"none",stroke:"currentColor",strokeWidth:"2",strokeLinecap:"round",strokeLinejoin:"round",className:`align-middle transition-transform duration-200 ease-in-out ${n?"rotate-0":"rotate-90"}`,"aria-hidden":"true",children:a.jsx("polyline",{points:"9 18 15 12 9 6"})}),e.title]}),a.jsx("div",{className:`${u?"grid gap-x-4":""} ${n?"hidden":""}`,style:Object.keys(d).length>0?d:void 0,children:e.children.map((y,h)=>_(y,h))})]})})}function _(e,t){return e.type==="field"?a.jsx(K,{dataPath:e.dataPath,layoutKey:e.layoutKey},e.layoutKey||e.dataPath):e.type==="object"?a.jsx(z,{node:e},`object-${e.layoutKey}-${t}`):a.jsx(G,{node:e},`layout-${e.type}-${t}`)}function U({engine:e,config:t,form:i,children:r}){const l=s.useMemo(()=>({engine:e,config:t,form:i}),[e,t,i]);return a.jsx(B.Provider,{value:l,children:r})}function T(){}function ne({form:e,schema:t,initialValues:i,widgets:r,layouts:l,onFinish:n,onFinishFailed:o,onMount:u,footer:d=!1,className:f,style:b,children:g,labelCol:y,labelWidth:h,colon:E,label:S,displayType:N,readOnly:C,column:A,watch:D,removeHiddenData:M=!0}){const m=e._getEngine(),O=s.useRef(null),w=N??t?.displayType??"row",$=S??t?.label??!0,W=E??t?.colon,p=h??t?.labelWidth,F=C??t?.readOnly??!1,v=A??t?.column;s.useEffect(()=>{r&&m.registerWidgets(r),l&&m.registerLayouts(l)},[m,r,l]);const R=s.useRef(!0),ge=s.useRef(i);s.useEffect(()=>{t&&(R.current?(m.init(t,ge.current),R.current=!1):m.init(t,m.getFormData()))},[m,t]);const Q=s.useRef(u);Q.current=u;const X=s.useRef(!1),Y=!t||typeof t=="object"&&Object.keys(t).length===0;s.useEffect(()=>{X.current||Y||(X.current=!0,Q.current?.())},[Y]);const Z=s.useRef(T),ee=s.useRef(T);Z.current=n??T,ee.current=o??T,s.useEffect(()=>{e._bind(O.current,()=>Z.current,()=>ee.current)},[e]),s.useEffect(()=>{e._syncConfig({removeHiddenData:M,watch:D})},[e,M,D]);const he=s.useSyncExternalStore(m.subscribeStore,m.getSnapshot,m.getSnapshot),be=s.useMemo(()=>m.getRenderTree(),[m,he]),ye=s.useCallback(async q=>{q.preventDefault(),await e.submit()},[e]),me=s.useCallback(()=>{e.resetFields()},[e]);let H=null;d===!0?H=a.jsxs("div",{className:"mt-4",children:[a.jsx("button",{type:"submit",children:"提交"})," ",a.jsx("button",{type:"button",onClick:me,children:"重置"})]}):d&&(H=d);const te=s.useMemo(()=>{if(y)return y;if(p)return{style:{width:typeof p=="number"?`${p}px`:p}}},[y,p]),Fe=s.useMemo(()=>({labelCol:te,labelWidth:p,colon:W,label:$,displayType:w,readOnly:F,column:v}),[te,p,W,$,w,F,v]);return a.jsx(U,{engine:m,config:Fe,form:e,children:a.jsxs("form",{ref:O,onSubmit:ye,className:f,style:{...b,...v&&v>1?{display:"grid",gridTemplateColumns:`repeat(${v}, 1fr)`,gap:"0 16px"}:{}},noValidate:!0,children:[be.map((q,pe)=>_(q,pe)),!C&&H,g]})})}function L(){const{engine:e}=V();return e}function ie(e){const{engine:t}=V();return s.useSyncExternalStore(i=>t.subscribeField(e,i),()=>t.getFieldVersion(e),()=>t.getFieldVersion(e)),t.getFieldState(e)}function se(e,t,i,r){const{engine:l}=V(),n=s.useRef(i);n.current=i;const o=s.useRef(r?.dependsOn);o.current=r?.dependsOn;const u=r?.deps;s.useEffect(()=>{if(!e||!t)return;const d=n.current;return e.registerValidator(t,d),()=>{e.unregisterValidator(t,d)}},[e,t,...u??[]]),s.useEffect(()=>{if(!t||!o.current||o.current.length===0)return;const d=l;if(!d)return;const f=t,b=o.current.map(g=>d.subscribeField(g,()=>{e?.revalidateField(f)}));return()=>{for(const g of b)g()}},[l,e,t])}function re(e){const t=L();return s.useSyncExternalStore(i=>t.subscribeField(e,i),()=>t.getFieldVersion(e),()=>t.getFieldVersion(e)),t.getFieldValue(e)}function le(e,t){const i=s.useRef(null);return i.current||(i.current=new J(t??(e?new x.NexusEngine({formId:e}):void 0))),[i.current]}function oe(){const{config:e}=V();return e}function ue(){const e=L(),t=s.useSyncExternalStore(e.subscribeStore,e.getSnapshot,e.getSnapshot);return s.useMemo(()=>e.getFormData(),[e,t])}function ce(e,t,i,r){const{deep:l=!1}=r||{},n=s.useRef(void 0),o=s.useRef(i);return o.current=i,s.useEffect(()=>{if(!e)return;const u=e.getFieldValue(t);n.current===void 0&&(n.current=u),(l?JSON.stringify(u)!==JSON.stringify(n.current):u!==n.current)&&(n.current=u,o.current(u));const f=e.subscribe(t,b=>{const g=b.value;(l?JSON.stringify(g)!==JSON.stringify(n.current):g!==n.current)&&(n.current=g,o.current(g))});return()=>{f()}},[e,t,l]),n.current}function ae(e,t,i){const{deep:r=!1}=i||{},l=s.useRef({}),n=s.useRef({}),o=s.useRef(t);return o.current=t,s.useEffect(()=>{if(!e)return;const u=e.getFormData();l.current=u,n.current=u,o.current(u);const d=e.subscribeAll(f=>{if(r)JSON.stringify(f)!==JSON.stringify(l.current)&&(l.current=f,n.current=f,o.current(f));else{let b=!1;for(const g in f)if(f[g]!==l.current[g]){b=!0;break}b&&(l.current=f,n.current=f,o.current(f))}});return()=>{d()}},[e,r]),n.current}function de(e,t,i,r){const{deep:l=!1}=r||{},n=s.useRef({}),o=s.useRef({}),u=s.useRef(i);u.current=i;const d=s.useRef(t);d.current=t;const f=[...t].sort().join(",");return s.useEffect(()=>{if(!e)return;const b=d.current,g={};for(const h of b)g[h]=e.getFieldValue(h);n.current=g,o.current=g,u.current(g);const y=b.map(h=>e.subscribe(h,E=>{const S=E.value,N=n.current[h];(l?JSON.stringify(S)!==JSON.stringify(N):S!==N)&&(n.current[h]=S,o.current={[h]:S},u.current(o.current))}));return()=>{for(const h of y)h()}},[e,l,f]),o.current}function fe(e,t,i){const r=s.useRef(void 0),l=s.useRef(i);return l.current=i,s.useEffect(()=>{if(!e)return;const n=e.getFieldState(t);r.current=n,n&&l.current(n);const o=e.subscribe(t,u=>{r.current=u,l.current(u)});return()=>{o()}},[e,t]),r.current||{}}c.FieldInheritContext=k,c.FormController=J,c.GridContext=P,c.LayoutConfigContext=j,c.NexusField=K,c.NexusForm=ne,c.NexusFormProvider=U,c.NexusLayout=G,c.NexusObject=z,c.useEngine=L,c.useFieldState=ie,c.useFieldValidator=se,c.useFieldValue=re,c.useForm=le,c.useFormConfig=oe,c.useFormData=ue,c.useWatch=ce,c.useWatchAll=ae,c.useWatchMultiple=de,c.useWatchState=fe,Object.defineProperty(c,Symbol.toStringTag,{value:"Module"})}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xbeeant/form-engine-react",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
@@ -70,6 +70,7 @@
     }
   },
   "dependencies": {
-    "@xbeeant/form-engine": "^0.0.1"
-  }
+    "@xbeeant/form-engine": "^0.0.3"
+  },
+  "gitHead": "32282a81ac6acd1c5b26ccf081504b9da53e07de"
 }

package/src/components/FormController.ts

@@ -112,6 +112,13 @@ export class FormController implements NexusFormInstance {
     return this.engine;
   }
 
+  /**
+   * 获取底层 Engine 实例（用于跨表单联动：linkForm / setFormId 等）
+   */
+  getEngine(): NexusEngine {
+    return this.engine;
+  }
+
   async submit(): Promise<void> {
     const errors = await this.engine.validate();
     if (errors.size > 0) {

package/src/components/NexusField.tsx

@@ -1,4 +1,4 @@
-import type { CSSProperties, FocusEvent } from 'react';
+import type { CSSProperties, FocusEvent, ReactElement } from 'react';
 import { useCallback, useContext, useMemo, useSyncExternalStore } from 'react';
 import { FieldInheritContext } from '../contexts/FieldInheritContext';
 import { GridContext } from '../contexts/GridContext';
@@ -146,37 +146,63 @@ export function NexusField({ dataPath, layoutKey }: NexusFieldProps) {
     ...(effectiveColSpan ? { gridColumn: `span ${effectiveColSpan}` } : {}),
   };
 
+  // 默认包裹：所有 widget 统一由 FieldWrapper 包裹（引擎注册，UI 层提供），
+  // 仅当 label === false（字段级或表单级）时 FieldWrapper 不包裹 Form.Item。
+  // 未注册 FieldWrapper（纯 react 无 ui 层）时直接渲染裸 widget。
+  const FieldWrapper = engine.getFieldWrapper();
+
+  // Form.Item 消费的元数据 props 剥离给 FieldWrapper，避免透传到底层 antd 控件：
+  // - required: 会让 <input required> 触发浏览器原生校验
+  // - errors/title/description/label/extra/width/displayType/labelWidth/column:
+  //   作为未知属性透传到 DOM 会产生 React 警告
+  const fieldWrapperProps = {
+    label: state.meta.label,
+    title: state.meta.title,
+    description: state.meta.description,
+    errors: state.errors,
+    required: state.required,
+    extra: state.meta.extra,
+    width: state.meta.width,
+    displayType: fieldDisplayType,
+    labelWidth: fieldLabelWidth,
+    column: fieldColumn,
+  };
+
+  // widget 仅接收控件相关 props（value/onChange/状态/选项/表单引用/自有 props）
+  const widgetProps = {
+    dataPath,
+    path: dataPath,
+    value: state.value,
+    onChange: handleChange,
+    disabled,
+    readOnly,
+    loading: state.loading,
+    placeholder: state.meta.placeholder,
+    options,
+    form,
+    dependValues,
+    items: state.meta.items,
+    ...state.props,
+  };
+
+  let control: ReactElement;
+  if (FieldWrapper) {
+    control = (
+      <FieldWrapper key={layoutKey} {...fieldWrapperProps}>
+        <Widget {...widgetProps} />
+      </FieldWrapper>
+    );
+  } else {
+    control = <Widget key={layoutKey} {...widgetProps} />;
+  }
+
   return (
     <div
       data-nexus-field={dataPath}
       onBlur={handleBlur}
       style={Object.keys(wrapperStyle).length > 0 ? wrapperStyle : undefined}
     >
-      <Widget
-        key={layoutKey}
-        dataPath={dataPath}
-        path={dataPath}
-        value={state.value}
-        onChange={handleChange}
-        disabled={disabled}
-        readOnly={readOnly}
-        loading={state.loading}
-        required={state.required}
-        title={state.meta.title}
-        description={state.meta.description}
-        placeholder={state.meta.placeholder}
-        label={state.meta.label}
-        options={options}
-        errors={state.errors}
-        extra={state.meta.extra}
-        displayType={fieldDisplayType}
-        labelWidth={fieldLabelWidth}
-        column={fieldColumn}
-        form={form}
-        dependValues={dependValues}
-        items={state.meta.items}
-        {...state.props}
-      />
+      {control}
     </div>
   );
 }

package/src/components/NexusForm.tsx

@@ -48,6 +48,13 @@ export interface NexusFormProps {
   onFinish?: (formData: Record<string, unknown>) => void | Promise<void>;
   /** 校验失败回调 */
   onFinishFailed?: (errors: Map<string, string[]>) => void;
+  /**
+   * 表单首次加载回调：非空 schema 首次传入并完成渲染后执行一次
+   * - undefined / null / {}（无 properties）均视为「空」schema，不触发
+   * - schema 由空变为非空时，于首个非空渲染提交后触发
+   * - 后续 schema 变更不重复触发
+   */
+  onMount?: () => void;
   /** 是否显示默认 footer（提交/重置按钮），或自定义 footer */
   footer?: boolean | ReactNode;
   /** 自定义类名 */
@@ -107,6 +114,7 @@ export function NexusForm({
   layouts,
   onFinish,
   onFinishFailed,
+  onMount,
   footer = false,
   className,
   style,
@@ -161,6 +169,22 @@ export function NexusForm({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [engine, schema]);
 
+  // onMount：首次传入「非空」schema 并完成渲染后执行一次
+  // undefined / null / {}（无任何键）均视为空 schema，不触发；
+  // schema 由空变为非空时，于首个非空渲染提交（useEffect）后触发。
+  const onMountRef = useRef(onMount);
+  onMountRef.current = onMount;
+  const onMountFiredRef = useRef(false);
+  const isSchemaEmpty =
+    !schema || (typeof schema === 'object' && Object.keys(schema).length === 0);
+  useEffect(() => {
+    if (onMountFiredRef.current || isSchemaEmpty) {
+      return;
+    }
+    onMountFiredRef.current = true;
+    onMountRef.current?.();
+  }, [isSchemaEmpty]);
+
   // 绑定 form controller
   // 使用 ref 持有 onFinish / onFinishFailed，避免每次 re-render 都造成绑定逻辑重复执行
   const onFinishRef =

package/src/hooks/useForm.ts

@@ -1,15 +1,29 @@
-import type { NexusEngine } from '@xbeeant/form-engine';
+import { NexusEngine } from '@xbeeant/form-engine';
 import { useRef } from 'react';
 
 import { FormController } from '../components/FormController';
 
 /**
  * useForm — 创建 Form 实例
+ *
+ * 支持一个页面挂载多个表单实例：
+ * - `useForm()`：独立实例（未注册，不参与跨表单联动）
+ * - `useForm(formId)`：创建带 formId 的实例，自动注册到默认表单注册表，
+ *   可通过 schema `crossForm` reaction / `engine.linkForm` 与其他表单联动
+ * - `useForm(formId, engine)`：复用外部创建的引擎（如 `new NexusEngine({ formId })`）
+ *
+ * @param formId - 可选，表单实例唯一标识（跨表单联动寻址）
+ * @param engine - 可选，外部引擎实例（缺省内部创建）
  */
-export function useForm(engine?: NexusEngine): [FormController] {
+export function useForm(
+  formId?: string,
+  engine?: NexusEngine,
+): [FormController] {
   const formRef = useRef<FormController | null>(null);
   if (!formRef.current) {
-    formRef.current = new FormController(engine);
+    formRef.current = new FormController(
+      engine ?? (formId ? new NexusEngine({ formId }) : undefined),
+    );
   }
   return [formRef.current];
 }

package/src/index.ts

@@ -3,6 +3,8 @@
 // 导出所有React组件、Hooks和类型定义，供上层应用使用
 // ============================================================================
 
+import './styles.css';
+
 export { FormController } from './components/FormController';
 export { NexusField } from './components/NexusField';
 export type { NexusFormConfig } from './components/NexusForm';

package/src/styles.css

@@ -0,0 +1,6 @@
+/* Renderer 样式入口（Tailwind CSS v4）
+ * 仅引入 theme + utilities（不引入 preflight），随构建产物输出为 index.css，
+ * 供未接入 Tailwind 的宿主应用使用；已接入 Tailwind 的应用可忽略该文件
+ */
+@import "tailwindcss/theme";
+@import "tailwindcss/utilities";

package/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />