@xbeeant/form-engine-react 0.0.1

package/README.md

@@ -0,0 +1,69 @@
+# 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...
+    },
+  },
+])
+```
+
+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...
+    },
+  },
+])
+```

package/dist/cjs/components/FormController.cjs

@@ -0,0 +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;

package/dist/cjs/components/NexusField.cjs

@@ -0,0 +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;

package/dist/cjs/components/NexusForm.cjs

@@ -0,0 +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;

package/dist/cjs/components/NexusFormProvider.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("react/jsx-runtime"),n=require("react"),i=require("../contexts/NexusContext.cjs");function x({engine:e,config:r,form:t,children:o}){const u=n.useMemo(()=>({engine:e,config:r,form:t}),[e,r,t]);return s.jsx(i.NexusContext.Provider,{value:u,children:o})}exports.NexusFormProvider=x;

package/dist/cjs/components/NexusLayout.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("react/jsx-runtime"),l=require("react"),y=require("../contexts/GridContext.cjs"),u=require("../contexts/LayoutConfigContext.cjs"),C=require("../contexts/NexusContext.cjs"),v=require("../utils/renderTreeNode.cjs"),h=require("../utils/resolveColSpan.cjs");function m({node:e}){const{engine:c}=C.useNexusContext(),r=c.getLayout(e.type),s=e.children.map((d,x)=>v.renderTreeNode(d,x)),a=l.useContext(y.GridContext),i=h.resolveColSpan(e.props.colSpan,a),o={...i?{gridColumn:`span ${i}`}:{},...e.props.width?{width:e.props.width,flexShrink:0}:{}},n=l.useMemo(()=>({removeHidden:e.props.removeHidden}),[e.props.removeHidden]);if(!r)return t.jsx(u.LayoutConfigContext.Provider,{value:n,children:t.jsxs("div",{"data-nexus-layout":e.type,className:"mb-4",style:Object.keys(o).length>0?o:void 0,children:[e.title&&t.jsx("div",{className:"mb-2 font-bold",children:e.title}),s]})});const{displayType:g,labelWidth:f,colSpan:j,width:S,...p}=e.props;return t.jsx(u.LayoutConfigContext.Provider,{value:n,children:t.jsx("div",{style:Object.keys(o).length>0?o:void 0,children:t.jsx(r,{...p,node:e,title:e.title,children:s})})})}exports.NexusLayout=m;

package/dist/cjs/components/NexusObject.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("react/jsx-runtime"),o=require("react"),h=require("../contexts/FieldInheritContext.cjs"),v=require("../contexts/NexusContext.cjs"),m=require("../utils/renderTreeNode.cjs");function f({node:e}){const{engine:s,config:a}=v.useNexusContext(),n=o.useContext(h.FieldInheritContext);o.useSyncExternalStore(i=>s.subscribeField(e.dataPath,i),()=>s.getFieldVersion(e.dataPath),()=>s.getFieldVersion(e.dataPath));const r=s.getFieldState(e.dataPath),[l,x]=o.useState(!1),d=(a.column??1)>1,c=d?{gridTemplateColumns:`repeat(${a.column}, 1fr)`}:{},u={disabled:n.disabled??(r?.disabled===!0?!0:void 0),readOnly:n.readOnly??(r?.readOnly===!0?!0:void 0),visible:n.visible===!1||r?.visible===!1?!1:void 0},b=u.visible===!1,g=()=>x(i=>!i);return t.jsx(h.FieldInheritContext.Provider,{value:u,children:t.jsxs("div",{"data-nexus-object":e.dataPath,className:`mb-4 ${b?"hidden":""}`,children:[e.title&&t.jsxs("div",{onClick:g,className:"flex gap-1 mb-2 cursor-pointer select-none border-none bg-transparent p-0 font-bold",children:[t.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 ${l?"rotate-0":"rotate-90"}`,"aria-hidden":"true",children:t.jsx("polyline",{points:"9 18 15 12 9 6"})}),e.title]}),t.jsx("div",{className:`${d?"grid gap-x-4":""} ${l?"hidden":""}`,style:Object.keys(c).length>0?c:void 0,children:e.children.map((i,p)=>m.renderTreeNode(i,p))})]})})}exports.NexusObject=f;

package/dist/cjs/contexts/FieldInheritContext.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("react"),t=e.createContext({});exports.FieldInheritContext=t;

package/dist/cjs/contexts/GridContext.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("react"),e=t.createContext(null);exports.GridContext=e;

package/dist/cjs/contexts/LayoutConfigContext.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("react"),e=t.createContext({});exports.LayoutConfigContext=e;

package/dist/cjs/contexts/NexusContext.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("react"),o=t.createContext(null);function u(){const e=t.useContext(o);if(!e)throw new Error("[NexusField] Must be used within <NexusFormProvider>");return e}exports.NexusContext=o;exports.useNexusContext=u;

package/dist/cjs/hooks/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./useEngine.cjs"),s=require("./useFieldState.cjs"),u=require("./useFieldValidator.cjs"),o=require("./useFieldValue.cjs"),t=require("./useForm.cjs"),r=require("./useFormConfig.cjs"),a=require("./useFormData.cjs"),i=require("./useWatch.cjs"),l=require("./useWatchAll.cjs"),c=require("./useWatchMultiple.cjs"),h=require("./useWatchState.cjs");exports.useEngine=e.useEngine;exports.useFieldState=s.useFieldState;exports.useFieldValidator=u.useFieldValidator;exports.useFieldValue=o.useFieldValue;exports.useForm=t.useForm;exports.useFormConfig=r.useFormConfig;exports.useFormData=a.useFormData;exports.useWatch=i.useWatch;exports.useWatchAll=l.useWatchAll;exports.useWatchMultiple=c.useWatchMultiple;exports.useWatchState=h.useWatchState;

package/dist/cjs/hooks/useEngine.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=require("../contexts/NexusContext.cjs");function t(){const{engine:e}=n.useNexusContext();return e}exports.useEngine=t;

package/dist/cjs/hooks/useFieldState.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const i=require("react"),r=require("../contexts/NexusContext.cjs");function s(e){const{engine:t}=r.useNexusContext();return i.useSyncExternalStore(n=>t.subscribeField(e,n),()=>t.getFieldVersion(e),()=>t.getFieldVersion(e)),t.getFieldState(e)}exports.useFieldState=s;

package/dist/cjs/hooks/useFieldValidator.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("react"),g=require("../contexts/NexusContext.cjs");function b(r,e,i,u){const{engine:d}=g.useNexusContext(),o=s.useRef(i);o.current=i;const t=s.useRef(u?.dependsOn);t.current=u?.dependsOn;const l=u?.deps;s.useEffect(()=>{if(!r||!e)return;const n=o.current;return r.registerValidator(e,n),()=>{r.unregisterValidator(e,n)}},[r,e,...l??[]]),s.useEffect(()=>{if(!e||!t.current||t.current.length===0)return;const n=d;if(!n)return;const f=e,a=t.current.map(c=>n.subscribeField(c,()=>{r?.revalidateField(f)}));return()=>{for(const c of a)c()}},[d,r,e])}exports.useFieldValidator=b;

package/dist/cjs/hooks/useFieldValue.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("react"),u=require("./useEngine.cjs");function s(e){const i=u.useEngine();return r.useSyncExternalStore(n=>i.subscribeField(e,n),()=>i.getFieldVersion(e),()=>i.getFieldVersion(e)),i.getFieldValue(e)}exports.useFieldValue=s;

package/dist/cjs/hooks/useForm.cjs

@@ -0,0 +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;

package/dist/cjs/hooks/useFormConfig.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("../contexts/NexusContext.cjs");function o(){const{config:e}=t.useNexusContext();return e}exports.useFormConfig=o;

package/dist/cjs/hooks/useFormData.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("react"),o=require("./useEngine.cjs");function r(){const e=o.useEngine(),n=t.useSyncExternalStore(e.subscribeStore,e.getSnapshot,e.getSnapshot);return t.useMemo(()=>e.getFormData(),[e,n])}exports.useFormData=r;

package/dist/cjs/hooks/useNexusContext.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("react"),o=t.createContext(null);function u(){const e=t.useContext(o);if(!e)throw new Error("[NexusField] Must be used within <NexusFormProvider>");return e}exports.NexusContext=o;exports.useNexusContext=u;

package/dist/cjs/hooks/useWatch.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=require("react");function d(t,c,i,l){const{deep:s=!1}=l||{},e=o.useRef(void 0),n=o.useRef(i);return n.current=i,o.useEffect(()=>{if(!t)return;const r=t.getFieldValue(c);e.current===void 0&&(e.current=r),(s?JSON.stringify(r)!==JSON.stringify(e.current):r!==e.current)&&(e.current=r,n.current(r));const f=t.subscribe(c,a=>{const u=a.value;(s?JSON.stringify(u)!==JSON.stringify(e.current):u!==e.current)&&(e.current=u,n.current(u))});return()=>{f()}},[t,c,s]),e.current}exports.useWatch=d;

package/dist/cjs/hooks/useWatchAll.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("react");function R(t,i,b){const{deep:l=!1}=b||{},e=s.useRef({}),c=s.useRef({}),u=s.useRef(i);return u.current=i,s.useEffect(()=>{if(!t)return;const f=t.getFormData();e.current=f,c.current=f,u.current(f);const d=t.subscribeAll(r=>{if(l)JSON.stringify(r)!==JSON.stringify(e.current)&&(e.current=r,c.current=r,u.current(r));else{let n=!1;for(const o in r)if(r[o]!==e.current[o]){n=!0;break}n&&(e.current=r,c.current=r,u.current(r))}});return()=>{d()}},[t,l]),c.current}exports.useWatchAll=R;

package/dist/cjs/hooks/useWatchMultiple.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("react");function h(r,n,a,d){const{deep:l=!1}=d||{},o=t.useRef({}),u=t.useRef({}),f=t.useRef(a);f.current=a;const i=t.useRef(n);i.current=n;const y=[...n].sort().join(",");return t.useEffect(()=>{if(!r)return;const R=i.current,c={};for(const e of R)c[e]=r.getFieldValue(e);o.current=c,u.current=c,f.current(c);const V=R.map(e=>r.subscribe(e,g=>{const s=g.value,b=o.current[e];(l?JSON.stringify(s)!==JSON.stringify(b):s!==b)&&(o.current[e]=s,u.current={[e]:s},f.current(u.current))}));return()=>{for(const e of V)e()}},[r,l,y]),u.current}exports.useWatchMultiple=h;

package/dist/cjs/hooks/useWatchState.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("react");function i(t,e,n){const r=s.useRef(void 0),u=s.useRef(n);return u.current=n,s.useEffect(()=>{if(!t)return;const c=t.getFieldState(e);r.current=c,c&&u.current(c);const f=t.subscribe(e,o=>{r.current=o,u.current(o)});return()=>{f()}},[t,e]),r.current||{}}exports.useWatchState=i;

package/dist/cjs/index.cjs

@@ -0,0 +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;

package/dist/cjs/utils/renderTreeNode.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const t=require("react/jsx-runtime"),r=require("../components/NexusField.cjs"),s=require("../components/NexusLayout.cjs"),a=require("../components/NexusObject.cjs");function o(e,u){return e.type==="field"?t.jsx(r.NexusField,{dataPath:e.dataPath,layoutKey:e.layoutKey},e.layoutKey||e.dataPath):e.type==="object"?t.jsx(a.NexusObject,{node:e},`object-${e.layoutKey}-${u}`):t.jsx(s.NexusLayout,{node:e},`layout-${e.type}-${u}`)}exports.renderTreeNode=o;

package/dist/cjs/utils/resolveColSpan.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function n(o,e){if(o!==void 0)return o;if(e&&e.column>0)return Math.max(1,Math.round(e.column/24))}exports.resolveColSpan=n;

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

@@ -0,0 +1,71 @@
+import { FieldState, NexusFormInstance, NexusSchema, NexusEngine } from '@xbeeant/form-engine';
+/**
+ * FormController — 包裹 Engine，暴露 Form 实例 API
+ */
+export declare class FormController implements NexusFormInstance {
+    private engine;
+    private formElementRef;
+    /** 稳定的 getter：每次 submit 执行时从外部 ref 读取最新的 onFinish/onFinishFailed 回调 */
+    private getOnFinish;
+    private getOnFinishFailed;
+    private removeHiddenData;
+    private watchers;
+    private globalWatcher;
+    constructor(engine?: NexusEngine);
+    /** 内部：首次绑定表单 DOM + 回调 getter（由 NexusForm 在挂载时调用一次） */
+    _bind(formEl: HTMLFormElement | null, getOnFinish: () => (data: Record<string, unknown>) => void | Promise<void>, getOnFinishFailed: () => (errors: Map<string, string[]>) => void): void;
+    /** 内部：同步 watch / removeHiddenData 配置（由 NexusForm 在它们变化时调用） */
+    _syncConfig(config: {
+        removeHiddenData?: boolean;
+        watch?: {
+            [path: string]: (value: unknown, allValues: Record<string, unknown>, changedPath?: string) => void;
+        };
+    }): void;
+    /** 内部：值变更时调用（由 Engine 通知） */
+    _onFieldValueChange(path: string, value: unknown): void;
+    /** 内部：获取 Engine 实例 */
+    _getEngine(): NexusEngine;
+    submit(): Promise<void>;
+    /**
+     * 定位到第一个校验失败的字段：按 DOM 渲染顺序查找（保证视觉上的"第一个"），
+     * 滚动入视并聚焦其内部可交互控件。
+     */
+    private focusFirstError;
+    resetFields(): void;
+    setErrorFields(errors: Array<{
+        path: string;
+        errors: string[];
+    }>): void;
+    setValues(values: Record<string, unknown>): void;
+    setValueByPath(path: string, value: unknown): void;
+    setSchemaByPath(path: string, patch: Record<string, unknown>): void;
+    setSchema(schema: NexusSchema): void;
+    getValues(paths?: string[]): Record<string, unknown>;
+    getHiddenValues(): Record<string, unknown>;
+    /** 获取所有字段值（含 hidden） */
+    getAllValues(): Record<string, unknown>;
+    getValueByPath(path: string): unknown;
+    /**
+     * 注册字段校验逻辑
+     * @param path 字段路径（如 'username'）
+     * @param validator 校验函数，返回错误消息数组（空数组表示通过）
+     */
+    registerValidator(path: string, validator: (value: unknown, formData: Record<string, unknown>) => string[] | Promise<string[]>): void;
+    /**
+     * 注销字段校验逻辑（按函数引用移除）
+     * 与 registerValidator 配对；widget 组件卸载时清理，避免校验器累积
+     */
+    unregisterValidator(path: string, validator: (value: unknown, formData: Record<string, unknown>) => string[] | Promise<string[]>): void;
+    /**
+     * 实时重校验指定字段（同步）
+     * 供 widget 组件内部状态变化（非字段值变化）时主动刷新错误态
+     */
+    revalidateField(path: string): void;
+    getSchema(): NexusSchema | null;
+    removeErrorField(path: string): void;
+    scrollToPath(path: string): void;
+    getFieldError(path: string): string[];
+    getFieldsError(): Map<string, string[]>;
+    validateFields(paths?: string[]): Promise<Map<string, string[]>>;
+    getFieldState(path: string): FieldState | undefined;
+}

package/dist/es/components/FormController.js

@@ -0,0 +1,153 @@
+import { NexusEngine as l, AsyncValidatorPlugin as o } from "@xbeeant/form-engine";
+class c {
+  engine;
+  formElementRef;
+  /** 稳定的 getter：每次 submit 执行时从外部 ref 读取最新的 onFinish/onFinishFailed 回调 */
+  getOnFinish;
+  getOnFinishFailed;
+  removeHiddenData = !0;
+  watchers = /* @__PURE__ */ new Map();
+  globalWatcher = null;
+  constructor(e) {
+    this.engine = e ?? new l(), this.engine.hasPlugin("async-validator") || this.engine.use(new o(this.engine)), this.formElementRef = {
+      current: null
+    }, this.getOnFinish = () => () => {
+    }, this.getOnFinishFailed = () => () => {
+    };
+  }
+  /** 内部：首次绑定表单 DOM + 回调 getter（由 NexusForm 在挂载时调用一次） */
+  _bind(e, t, i) {
+    this.formElementRef.current = e, this.getOnFinish = t, this.getOnFinishFailed = i, this.engine.registerOnFieldValueChange(
+      (n, r) => this._onFieldValueChange(n, r)
+    );
+  }
+  /** 内部：同步 watch / removeHiddenData 配置（由 NexusForm 在它们变化时调用） */
+  _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);
+    }
+  }
+  /** 内部：值变更时调用（由 Engine 通知） */
+  _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);
+  }
+  /** 内部：获取 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);
+  }
+  /**
+   * 定位到第一个校验失败的字段：按 DOM 渲染顺序查找（保证视觉上的"第一个"），
+   * 滚动入视并聚焦其内部可交互控件。
+   */
+  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();
+  }
+  /** 获取所有字段值（含 hidden） */
+  getAllValues() {
+    return this.engine.getAllFormData();
+  }
+  getValueByPath(e) {
+    return this.engine.getFieldValue(e);
+  }
+  /**
+   * 注册字段校验逻辑
+   * @param path 字段路径（如 'username'）
+   * @param validator 校验函数，返回错误消息数组（空数组表示通过）
+   */
+  registerValidator(e, t) {
+    this.engine.registerFieldValidator(e, t);
+  }
+  /**
+   * 注销字段校验逻辑（按函数引用移除）
+   * 与 registerValidator 配对；widget 组件卸载时清理，避免校验器累积
+   */
+  unregisterValidator(e, t) {
+    this.engine.unregisterFieldValidator(e, t);
+  }
+  /**
+   * 实时重校验指定字段（同步）
+   * 供 widget 组件内部状态变化（非字段值变化）时主动刷新错误态
+   */
+  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);
+  }
+}
+export {
+  c as FormController
+};

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

@@ -0,0 +1,9 @@
+interface NexusFieldProps {
+    dataPath: string;
+    layoutKey: string;
+}
+/**
+ * NexusField — 单个字段渲染器
+ */
+export declare function NexusField({ dataPath, layoutKey }: NexusFieldProps): import("react").JSX.Element | null;
+export {};

package/dist/es/components/NexusField.js

@@ -0,0 +1,98 @@
+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(
+    (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(
+    (n) => {
+      i.setFieldValue(t, n);
+    },
+    [i, t]
+  ), W = g(
+    (n) => {
+      n.currentTarget.contains(n.relatedTarget) || i.validateField(t, { trigger: "blur" });
+    },
+    [i, t]
+  ), h = x(
+    () => e?.meta.enum ? e.meta.enum.map((n, l) => ({
+      value: n,
+      label: e.meta.enumNames?.[l] ?? String(n)
+    })) : e?.props.options,
+    [e?.meta.enum, e?.meta.enumNames, e?.props.options]
+  ), w = x(() => {
+    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);
+    }
+    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: [
+      '⚠️ 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 = {
+    ...e.meta.width ? { width: e.meta.width, flexShrink: 0 } : {},
+    ...u ? { gridColumn: `span ${u}` } : {}
+  };
+  return /* @__PURE__ */ d(
+    "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
+      )
+    }
+  );
+}
+export {
+  A as NexusField
+};

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

@@ -0,0 +1,77 @@
+import { NexusSchema } from '@xbeeant/form-engine';
+import { CSSProperties, ReactNode } from 'react';
+import { FormController } from './FormController';
+export interface NexusFormConfig {
+    /** label 列配置（由 ui 层 Form.Item 消费） */
+    labelCol?: Record<string, unknown>;
+    /** label 宽度（px 或 %），快捷方式 — 映射到 labelCol.style.width */
+    labelWidth?: number | string;
+    /** 是否显示冒号 */
+    colon?: boolean | ReactNode;
+    /** 是否显示 label（默认 true） */
+    label?: boolean;
+    /** 表单布局方向 */
+    displayType?: 'row' | 'column' | 'inline';
+    /** 整个表单只读，所有字段以文本展示 */
+    readOnly?: boolean;
+    /** 表单每行显示多少列 */
+    column?: number;
+}
+export interface NexusFormProps {
+    /** Form 实例，由 useForm() 创建 */
+    form: FormController;
+    /** Schema 定义 */
+    schema?: NexusSchema;
+    /** 初始值 */
+    initialValues?: Record<string, unknown>;
+    /** 额外注册的 widget（与已注册的合并） */
+    widgets?: Record<string, (props: any) => ReactNode>;
+    /** 额外注册的 layout */
+    layouts?: Record<string, (props: any) => ReactNode>;
+    /** 提交成功回调 */
+    onFinish?: (formData: Record<string, unknown>) => void | Promise<void>;
+    /** 校验失败回调 */
+    onFinishFailed?: (errors: Map<string, string[]>) => void;
+    /** 是否显示默认 footer（提交/重置按钮），或自定义 footer */
+    footer?: boolean | ReactNode;
+    /** 自定义类名 */
+    className?: string;
+    /** 自定义样式 */
+    style?: CSSProperties;
+    /** 子节点 */
+    children?: ReactNode;
+    /**
+     * 表单值变化监听
+     * - key 为字段路径（如 'username'），值为回调函数
+     * - 使用 '#' 作为 key 可监听所有字段变化
+     * - 回调参数为 (value, allValues)；全局（'#'）监听额外提供第三参 changedPath，
+     *   即本次实际变更的字段路径（用于区分「未触碰的默认空值」与「用户主动清空」）
+     */
+    watch?: {
+        [path: string]: (value: unknown, allValues: Record<string, unknown>, changedPath?: string) => void;
+    };
+    /**
+     * 提交时是否移除 hidden 字段数据，默认 true
+     * - true: submit/getValues 不包含 hidden 字段
+     * - false: submit/getValues 包含所有字段（含 hidden）
+     */
+    removeHiddenData?: boolean;
+    /** label 列配置（由 ui 层 Form.Item 消费） */
+    labelCol?: Record<string, unknown>;
+    /** label 宽度（px 或 %），快捷方式 — 映射到 labelCol.style.width */
+    labelWidth?: number | string;
+    /** 是否显示冒号 */
+    colon?: boolean | ReactNode;
+    /** 是否显示 label（默认 true） */
+    label?: boolean;
+    /** 表单布局方向：'row' = horizontal, 'column' = vertical, 'inline' = inline */
+    displayType?: 'row' | 'column' | 'inline';
+    /** 整个表单只读，所有字段以文本展示 */
+    readOnly?: boolean;
+    /** 表单每行显示多少列 */
+    column?: number;
+}
+/**
+ * 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;