@xbeeant/form-engine-react 0.0.2 → 0.0.4

package/dist/es/components/FormController.js

@@ -1,70 +1,173 @@
-import { NexusEngine as l, AsyncValidatorPlugin as o } from "@xbeeant/form-engine";
-class c {
+import { NexusEngine as g, AsyncValidatorPlugin as h } from "@xbeeant/form-engine";
+import { omitNilDeep as c } from "../utils/omitNil.js";
+const f = /* @__PURE__ */ new WeakSet();
+class V {
   engine;
-  formElementRef;
-  /** 稳定的 getter：每次 submit 执行时从外部 ref 读取最新的 onFinish/onFinishFailed 回调 */
-  getOnFinish;
-  getOnFinishFailed;
-  removeHiddenData = !0;
-  watchers = /* @__PURE__ */ new Map();
-  globalWatcher = null;
+  /** 提交中状态（校验 + onFinish 全流程，formily submitting 对齐） */
+  submitting = !1;
+  /** 提交状态监听器（供 useSyncExternalStore 消费） */
+  submittingListeners = /* @__PURE__ */ new Set();
+  /** 实例标识（内部）→ 实例视图引擎（同一 form 挂载的多个 NexusForm 各自独立） */
+  views = /* @__PURE__ */ new Map();
+  /** 实例标识 → 该实例的 DOM / 回调绑定（onFinish/onFinishFailed 按实例独立） */
+  instanceBindings = /* @__PURE__ */ new Map();
+  /** 实例标识 → watch / removeHiddenData / onValuesChange / omitNil 配置（按实例独立） */
+  instanceConfigs = /* @__PURE__ */ new Map();
   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 = () => () => {
-    };
+    this.engine = e ?? new g(), this.engine.hasPlugin("async-validator") || this.engine.use(new h(this.engine));
   }
-  /** 内部：首次绑定表单 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)
+  /**
+   * 获取（或创建）指定实例的引擎视图
+   *
+   * 同一 form 挂载多个 NexusForm 时各自独立：schema/值/订阅互不影响。
+   * 实例标识由 NexusForm 内部分配（React useId），用户不感知。
+   *
+   * @param instanceId - 实例标识（内部）
+   * @returns 定向到该实例的引擎视图
+   */
+  _useInstance(e) {
+    let t = this.views.get(e);
+    return t || (this.views.size === 0 && !f.has(this.engine) ? (f.add(this.engine), t = this.engine) : t = this.engine.instance(e), this.views.set(e, t), this.instanceConfigs.set(e, {
+      removeHiddenData: !0,
+      omitNil: !1,
+      watchers: /* @__PURE__ */ new Map(),
+      globalWatcher: null,
+      onValuesChange: null
+    })), t;
+  }
+  /**
+   * 内部：解析方法作用的目标实例视图（聚合全部实例，无实例时回退宿主引擎）
+   */
+  resolveViews() {
+    const e = Array.from(this.views.values());
+    return e.length > 0 ? e : [this.engine];
+  }
+  /** 内部：首次绑定的实例 DOM（兼容既有 scrollToPath/focusFirstError 单实例行为） */
+  getPrimaryFormEl() {
+    return this.instanceBindings.values().next().value?.formEl ?? null;
+  }
+  /**
+   * 内部：绑定实例 DOM + 回调 getter（由 NexusForm 在挂载时按实例调用）
+   * 回调以 getter 传入：submit 时读取最新闭包，而非绑定时刻的快照
+   */
+  _bind(e, t, s, n) {
+    this.instanceBindings.set(e, {
+      formEl: t,
+      getOnFinish: s,
+      getOnFinishFailed: n
+    }), this._useInstance(e).registerOnFieldValueChange(
+      (o, r) => this._onFieldValueChange(e, o, 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);
+  /** 内部：同步 watch / removeHiddenData / onValuesChange 配置（由 NexusForm 在它们变化时按实例调用） */
+  _syncConfig(e, t) {
+    const s = this.instanceConfigs.get(e) ?? {
+      removeHiddenData: !0,
+      omitNil: !1,
+      watchers: /* @__PURE__ */ new Map(),
+      globalWatcher: null,
+      onValuesChange: null
+    };
+    if (t.removeHiddenData !== void 0 && (s.removeHiddenData = t.removeHiddenData), t.omitNil !== void 0 && (s.omitNil = t.omitNil), t.onValuesChange !== void 0 && (s.onValuesChange = t.onValuesChange), t.watch) {
+      s.watchers.clear(), s.globalWatcher = null;
+      for (const [n, i] of Object.entries(t.watch))
+        n === "#" ? s.globalWatcher = i : s.watchers.set(n, i);
     }
+    this.instanceConfigs.set(e, s);
   }
-  /** 内部：值变更时调用（由 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 通知，携带实例标识路由到对应实例的 watcher） */
+  _onFieldValueChange(e, t, s) {
+    const n = this.views.get(e), i = this.instanceConfigs.get(e);
+    if (!n || !i)
+      return;
+    const o = n.getFormData(), r = i.removeHiddenData ? o : n.getAllFormData();
+    i.globalWatcher && i.globalWatcher(r, r, t), i.onValuesChange && i.onValuesChange(s, r, t);
+    const a = i.watchers.get(t);
+    a && a(s, r);
   }
-  /** 内部：获取 Engine 实例 */
+  /** 内部：获取引擎宿主实例 */
   _getEngine() {
     return this.engine;
   }
-  async submit() {
-    const e = await this.engine.validate();
-    if (e.size > 0) {
-      this.focusFirstError(e), this.getOnFinishFailed()?.(e);
+  /**
+   * 获取底层引擎宿主实例（用于跨表单联动：linkForm / setFormId / registerAntdUI 等；
+   * 宿主上的组件/插件注册对全部实例生效）
+   */
+  getEngine() {
+    return this.engine;
+  }
+  async submit(e) {
+    this.setSubmitting(!0);
+    try {
+      await this.runSubmit(e);
+    } finally {
+      this.setSubmitting(!1);
+    }
+  }
+  /** 提交中状态（formily submitting 对齐，供提交按钮 loading） */
+  getSubmitting() {
+    return this.submitting;
+  }
+  /** 订阅提交状态变化（返回取消订阅函数，供 useSyncExternalStore 使用） */
+  onSubmittingChange(e) {
+    return this.submittingListeners.add(e), () => {
+      this.submittingListeners.delete(e);
+    };
+  }
+  setSubmitting(e) {
+    if (this.submitting !== e) {
+      this.submitting = e;
+      for (const t of this.submittingListeners)
+        t();
+    }
+  }
+  async runSubmit(e) {
+    const t = this.resolveViews(), s = /* @__PURE__ */ new Map();
+    let n;
+    for (const i of t) {
+      const o = await i.validate(void 0, {
+        validateFirst: e?.validateFirst
+      });
+      if (o.size > 0) {
+        for (const [r, a] of o)
+          s.set(r, a);
+        n ??= this.instanceBindings.get(this.findInstanceId(i));
+      }
+    }
+    if (s.size > 0) {
+      this.focusFirstError(s, n?.formEl ?? null), n?.getOnFinishFailed()?.(s);
       return;
     }
-    const t = this.removeHiddenData ? this.engine.getFormData() : this.engine.getAllFormData();
-    await this.getOnFinish()?.(t);
+    for (const i of t) {
+      const o = this.findInstanceId(i), r = this.instanceConfigs.get(o) ?? {
+        removeHiddenData: !0,
+        omitNil: !1
+      }, a = r.removeHiddenData ? i.getFormData() : i.getAllFormData(), l = e?.omitNil ?? r.omitNil ?? !1 ? c(a) : a;
+      await i.submit(l) && await this.instanceBindings.get(o)?.getOnFinish()?.(l);
+    }
+  }
+  /** 内部：反查实例视图对应的实例标识 */
+  findInstanceId(e) {
+    for (const [t, s] of this.views)
+      if (s === e)
+        return t;
+    return "default";
   }
   /**
    * 定位到第一个校验失败的字段：按 DOM 渲染顺序查找（保证视觉上的"第一个"），
    * 滚动入视并聚焦其内部可交互控件。
    */
-  focusFirstError(e) {
-    const t = this.formElementRef.current;
+  focusFirstError(e, t) {
     if (!t || e.size === 0)
       return;
-    const i = new Set(e.keys());
+    const s = 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))
+      const i = t.querySelectorAll("[data-nexus-field]");
+      for (const o of Array.from(i)) {
+        const r = o.getAttribute("data-nexus-field");
+        if (!r || !s.has(r))
           continue;
-        s.scrollIntoView({ behavior: "smooth", block: "center" }), s.querySelector(
+        typeof o.scrollIntoView == "function" && o.scrollIntoView({ behavior: "smooth", block: "center" }), o.querySelector(
           'input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
         )?.focus();
         return;
@@ -72,35 +175,56 @@ class c {
     });
   }
   resetFields() {
-    this.engine.reset();
+    for (const e of this.resolveViews())
+      e.reset();
   }
   setErrorFields(e) {
-    this.engine.setErrorFields(e);
+    for (const t of this.resolveViews())
+      t.setErrorFields(e);
   }
   setValues(e) {
-    this.engine.setFieldValues(e);
+    for (const t of this.resolveViews())
+      t.setFieldValues(e);
   }
   setValueByPath(e, t) {
-    this.engine.setFieldValue(e, t);
+    for (const s of this.resolveViews())
+      s.setFieldValue(e, t);
   }
   setSchemaByPath(e, t) {
-    this.engine.setSchemaByPath(e, t);
+    for (const s of this.resolveViews())
+      s.setSchemaByPath(e, t);
   }
   setSchema(e) {
-    this.engine.setSchema(e);
+    for (const t of this.resolveViews())
+      t.setSchema(e);
   }
-  getValues(e) {
-    return this.engine.getFormData(e);
+  getValues(e, t) {
+    const s = {};
+    for (const n of this.resolveViews()) {
+      const i = n.getFormData(e);
+      t?.omitNil ? Object.assign(s, c(i)) : Object.assign(s, i);
+    }
+    return s;
   }
   getHiddenValues() {
-    return this.engine.getHiddenValues();
+    const e = {};
+    for (const t of this.resolveViews())
+      Object.assign(e, t.getHiddenValues());
+    return e;
   }
   /** 获取所有字段值（含 hidden） */
   getAllValues() {
-    return this.engine.getAllFormData();
+    const e = {};
+    for (const t of this.resolveViews())
+      Object.assign(e, t.getAllFormData());
+    return e;
   }
   getValueByPath(e) {
-    return this.engine.getFieldValue(e);
+    for (const t of this.resolveViews()) {
+      const s = t.getFieldValue(e);
+      if (s !== void 0)
+        return s;
+    }
   }
   /**
    * 注册字段校验逻辑
@@ -108,46 +232,79 @@ class c {
    * @param validator 校验函数，返回错误消息数组（空数组表示通过）
    */
   registerValidator(e, t) {
-    this.engine.registerFieldValidator(e, t);
+    for (const s of this.resolveViews())
+      s.registerFieldValidator(e, t);
   }
   /**
    * 注销字段校验逻辑（按函数引用移除）
    * 与 registerValidator 配对；widget 组件卸载时清理，避免校验器累积
    */
   unregisterValidator(e, t) {
-    this.engine.unregisterFieldValidator(e, t);
+    for (const s of this.resolveViews())
+      s.unregisterFieldValidator(e, t);
   }
   /**
    * 实时重校验指定字段（同步）
    * 供 widget 组件内部状态变化（非字段值变化）时主动刷新错误态
    */
   revalidateField(e) {
-    this.engine.validateField(e, { trigger: "change" });
+    for (const t of this.resolveViews())
+      t.validateField(e, { trigger: "change" });
   }
   getSchema() {
-    return this.engine.getSchema();
+    return this.resolveViews()[0]?.getSchema() ?? null;
   }
   removeErrorField(e) {
-    this.engine.removeErrorField(e);
+    for (const t of this.resolveViews())
+      t.removeErrorField(e);
   }
   scrollToPath(e) {
-    this.formElementRef.current?.querySelector(
-      `[data-nexus-field="${e}"]`
-    )?.scrollIntoView({ behavior: "smooth", block: "center" });
+    this.getPrimaryFormEl()?.querySelector(`[data-nexus-field="${e}"]`)?.scrollIntoView({ behavior: "smooth", block: "center" });
   }
   getFieldError(e) {
-    return this.engine.getFieldError(e);
+    for (const t of this.resolveViews()) {
+      const s = t.getFieldError(e);
+      if (s.length > 0)
+        return s;
+    }
+    return [];
   }
   getFieldsError() {
-    return this.engine.getFieldsError();
+    const e = /* @__PURE__ */ new Map();
+    for (const t of this.resolveViews())
+      for (const [s, n] of t.getFieldsError())
+        e.set(s, n);
+    return e;
   }
-  validateFields(e) {
-    return this.engine.validate(e);
+  validateFields(e, t) {
+    const s = this.resolveViews();
+    return s.length === 1 ? s[0].validate(e, t) : Promise.all(s.map((n) => n.validate(e, t))).then(
+      (n) => {
+        const i = /* @__PURE__ */ new Map();
+        for (const o of n)
+          for (const [r, a] of o)
+            i.set(r, a);
+        return i;
+      }
+    );
   }
   getFieldState(e) {
-    return this.engine.getFieldState(e);
+    for (const t of this.resolveViews()) {
+      const s = t.getFieldState(e);
+      if (s)
+        return s;
+    }
+  }
+  /**
+   * 重载远程选项数据（x-render reloadRemoteData 对齐）
+   * 传入 path 仅重载该字段的远程数据；缺省时重载全部远程数据字段。
+   * 作用于全部实例视图。
+   */
+  reloadRemoteData(e) {
+    for (const t of this.resolveViews())
+      t.reloadRemoteData(e);
   }
 }
 export {
-  c as FormController
+  V as FormController
 };

package/dist/es/components/NexusField.js

@@ -1,98 +1,101 @@
-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 r, jsxs as D } from "react/jsx-runtime";
+import { useSyncExternalStore as L, useContext as m, useCallback as C, useMemo as h } from "react";
+import { FieldInheritContext as R } from "../contexts/FieldInheritContext.js";
+import { GridContext as $ } from "../contexts/GridContext.js";
+import { LayoutConfigContext as E } from "../contexts/LayoutConfigContext.js";
+import { useNexusContext as G } from "../contexts/NexusContext.js";
+import { resolveColSpan as H } from "../utils/resolveColSpan.js";
+function X({ dataPath: t, layoutKey: c }) {
+  const { engine: i, config: l, form: W } = G();
+  L(
     (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($), F = m(E), d = m(R), 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 = h(
+    () => 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 = h(() => {
     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__ */ r("div", { className: "hidden", "data-nexus-hidden": t });
+  const p = l.readOnly || d.readOnly === !0 || e.readOnly, V = d.disabled === !0 || e.disabled, u = p && !!e.meta.readOnlyWidget, T = u ? e.meta.readOnlyWidget : e.meta.widget;
+  let o = i.getWidget(T);
+  if (!o && u && (o = i.getWidget(e.meta.widget)), !o)
+    return /* @__PURE__ */ D("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 = H(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,
+    tooltip: e.meta.tooltip,
+    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: V,
+    readOnly: p,
+    loading: e.loading,
+    placeholder: e.meta.placeholder,
+    options: N,
+    form: W,
+    dependValues: O,
+    items: e.meta.items,
+    schema: e.meta.schema,
+    // 远程选项数据版本：reloadRemoteData 后变化，widget 据此跳过缓存重新请求
+    remoteVersion: i.getRemoteDataVersion(t),
+    ...e.props
   };
-  return /* @__PURE__ */ d(
+  let a;
+  return x ? a = /* @__PURE__ */ r(x, { ...B, children: /* @__PURE__ */ r(o, { ...y }) }, c) : a = /* @__PURE__ */ r(o, { ...y }, c), /* @__PURE__ */ r(
     "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

@@ -1,5 +1,6 @@
-import { NexusSchema } from '@xbeeant/form-engine';
+import { NexusComponent, NexusSchema } from '@xbeeant/form-engine';
 import { CSSProperties, ReactNode } from 'react';
+import { PersistOptions } from '../utils/persist';
 import { FormController } from './FormController';
 export interface NexusFormConfig {
     /** label 列配置（由 ui 层 Form.Item 消费） */
@@ -16,9 +17,15 @@ export interface NexusFormConfig {
     readOnly?: boolean;
     /** 表单每行显示多少列 */
     column?: number;
+    /** 表单语言标识（如 'zh-CN' / 'en-US'，ui 层消费：antd locale + 内置文案） */
+    locale?: string;
 }
 export interface NexusFormProps {
-    /** Form 实例，由 useForm() 创建 */
+    /**
+     * Form 实例，由 useForm() 创建。同一 form 引用 = 同一引擎宿主（组件/插件注册共享）；
+     * 每个 NexusForm 挂载自动获得独立实例（schema/值/订阅互不影响），
+     * form 的 API（getValues/setValues/submit...）聚合作用于全部实例。
+     */
     form: FormController;
     /** Schema 定义 */
     schema?: NexusSchema;
@@ -28,10 +35,19 @@ export interface NexusFormProps {
     widgets?: Record<string, (props: any) => ReactNode>;
     /** 额外注册的 layout */
     layouts?: Record<string, (props: any) => ReactNode>;
+    /** 字段包裹组件（UI 无关，Renderer 层注入；渲染层默认包裹所有 widget，label=false 时跳过） */
+    fieldWrapper?: NexusComponent;
     /** 提交成功回调 */
     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;
     /** 自定义类名 */
@@ -50,12 +66,33 @@ export interface NexusFormProps {
     watch?: {
         [path: string]: (value: unknown, allValues: Record<string, unknown>, changedPath?: string) => void;
     };
+    /**
+     * 表单值变化回调（x-render onValuesChange 对齐）
+     * 任意字段值变化时触发，参数为 (changedValue, allValues, changedPath)
+     * 与 watch: { '#': fn } 语义等价，但作为标准回调 API 提供
+     */
+    onValuesChange?: (changedValue: unknown, allValues: Record<string, unknown>, changedPath: string) => void;
     /**
      * 提交时是否移除 hidden 字段数据，默认 true
      * - true: submit/getValues 不包含 hidden 字段
      * - false: submit/getValues 包含所有字段（含 hidden）
      */
     removeHiddenData?: boolean;
+    /**
+     * 提交时递归移除空值（undefined/null/''，ProForm omitNil 对齐）
+     * 与 form.submit({ omitNil: true }) / form.getValues(paths, { omitNil: true }) 等价
+     */
+    omitNil?: boolean;
+    /** 表单语言标识（如 'zh-CN' / 'en-US'，ui 层消费：antd locale + 内置文案） */
+    locale?: string;
+    /**
+     * 表单草稿持久化：值变化时自动保存到 Web Storage，下次挂载自动恢复
+     * @example
+     * ```tsx
+     * <NexusForm persist={{ key: 'apply-form', storage: 'localStorage' }} />
+     * ```
+     */
+    persist?: PersistOptions;
     /** label 列配置（由 ui 层 Form.Item 消费） */
     labelCol?: Record<string, unknown>;
     /** label 宽度（px 或 %），快捷方式 — 映射到 labelCol.style.width */
@@ -74,4 +111,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, fieldWrapper, onFinish, onFinishFailed, onMount, footer, className, style, children, labelCol, labelWidth, colon, label, displayType, readOnly, column, watch, onValuesChange, removeHiddenData, omitNil, locale, persist, }: NexusFormProps): import("react").JSX.Element;