@xbeeant/form-engine-react 0.0.2 → 0.0.4

package/dist/es/components/NexusForm.js

@@ -1,120 +1,174 @@
-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";
-function s() {
+import { jsx as S, jsxs as A } from "react/jsx-runtime";
+import { useId as de, useMemo as f, useRef as i, useEffect as u, useSyncExternalStore as fe, useCallback as B } from "react";
+import "../contexts/NexusContext.js";
+import "@xbeeant/form-engine";
+import { useFormSubmitting as pe } from "../hooks/useFormSubmitting.js";
+import { loadPersisted as be, savePersisted as ge, clearPersisted as ye } from "../utils/persist.js";
+import { renderTreeNode as me } from "../utils/renderTreeNode.js";
+import { NexusFormProvider as Re } from "./NexusFormProvider.js";
+function T() {
 }
-function ne({
-  form: n,
-  schema: t,
-  initialValues: _,
-  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,
-  watch: m,
-  removeHiddenData: R = !0
+function je({
+  form: o,
+  schema: n,
+  initialValues: G,
+  widgets: p,
+  layouts: b,
+  fieldWrapper: g,
+  onFinish: J,
+  onFinishFailed: Q,
+  onMount: x,
+  footer: y = !1,
+  className: U,
+  style: X,
+  children: Y,
+  labelCol: m,
+  labelWidth: Z,
+  colon: H,
+  label: ee,
+  displayType: te,
+  readOnly: C,
+  column: ne,
+  watch: v,
+  onValuesChange: L,
+  removeHiddenData: h = !0,
+  omitNil: j = !1,
+  locale: re,
+  persist: c
 }) {
-  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(
-      x.current,
-      () => N.current,
-      () => v.current
+  const l = de(), e = f(
+    () => o._useInstance(l),
+    [o, l]
+  ), k = i(null), a = i(c);
+  a.current = c;
+  const E = te ?? n?.displayType ?? "row", I = ee ?? n?.label ?? !0, N = H ?? n?.colon, s = Z ?? n?.labelWidth, O = C ?? n?.readOnly ?? !1, d = ne ?? n?.column, P = re ?? n?.locale ?? e.getLocale();
+  u(() => {
+    p && e.registerWidgets(p), g && e.registerFieldWrapper(g), b && e.registerLayouts(b);
+  }, [e, p, b, g]);
+  const _ = i(!0), oe = i(G);
+  u(() => {
+    if (n)
+      if (_.current) {
+        const t = a.current ? be(a.current) : void 0;
+        e.init(n, t ?? oe.current), _.current = !1;
+      } else
+        e.init(n, e.getFormData());
+  }, [e, n]);
+  const $ = c ? `${c.storage ?? "localStorage"}:${c.key}` : null;
+  u(() => {
+    const t = $ ? a.current : void 0;
+    if (!t)
+      return;
+    let r = null;
+    const F = t.debounce ?? 300, ae = e.subscribeStore(() => {
+      r && clearTimeout(r), r = setTimeout(() => {
+        ge(t, e.getFormData());
+      }, F);
+    });
+    return () => {
+      r && clearTimeout(r), ae();
+    };
+  }, [e, $]);
+  const D = i(x);
+  D.current = x;
+  const V = i(!1), W = !n || typeof n == "object" && Object.keys(n).length === 0;
+  u(() => {
+    V.current || W || (V.current = !0, D.current?.());
+  }, [W]);
+  const M = i(T), K = i(T);
+  M.current = (t) => {
+    const r = a.current;
+    return r && r.clearOnSubmit !== !1 && ye(r), J?.(t);
+  }, K.current = Q ?? T, u(() => {
+    o._bind(
+      l,
+      k.current,
+      () => M.current,
+      () => K.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(
-    async (p) => {
-      p.preventDefault(), await n.submit();
+  }, [o, l]);
+  const q = i(L);
+  q.current = L, u(() => {
+    o._syncConfig(l, {
+      removeHiddenData: h,
+      omitNil: j,
+      watch: v,
+      onValuesChange: (t, r, F) => q.current?.(t, r, F)
+    });
+  }, [o, l, h, j, v]);
+  const ie = fe(
+    (t) => e.subscribeRender(t),
+    () => e.getRenderSnapshot(),
+    () => e.getRenderSnapshot()
+  ), se = f(() => e.getRenderTree(), [e, ie]), le = B(
+    async (t) => {
+      t.preventDefault(), await o.submit();
     },
-    [n]
-  ), G = W(() => {
-    n.resetFields();
-  }, [n]);
-  let d = null;
-  a === !0 ? d = /* @__PURE__ */ L("div", { className: "mt-4", children: [
-    /* @__PURE__ */ b("button", { type: "submit", children: "提交" }),
+    [o]
+  ), ue = B(() => {
+    o.resetFields();
+  }, [o]), w = pe(o);
+  let R = null;
+  y === !0 ? R = /* @__PURE__ */ A("div", { className: "mt-4", children: [
+    /* @__PURE__ */ S("button", { type: "submit", disabled: w, children: w ? "提交中..." : "提交" }),
     " ",
-    /* @__PURE__ */ b("button", { type: "button", onClick: G, children: "重置" })
-  ] }) : a && (d = a);
-  const E = y(() => {
-    if (f)
-      return f;
-    if (r)
+    /* @__PURE__ */ S("button", { type: "button", onClick: ue, children: "重置" })
+  ] }) : y && (R = y);
+  const z = f(() => {
+    if (m)
+      return m;
+    if (s)
       return {
         style: {
-          width: typeof r == "number" ? `${r}px` : r
+          width: typeof s == "number" ? `${s}px` : s
         }
       };
-  }, [f, r]), J = y(
+  }, [m, s]), ce = f(
     () => ({
-      labelCol: E,
-      labelWidth: r,
-      colon: S,
-      label: C,
-      displayType: F,
-      readOnly: T,
-      column: i
+      labelCol: z,
+      labelWidth: s,
+      colon: N,
+      label: I,
+      displayType: E,
+      readOnly: O,
+      column: d,
+      locale: P
     }),
     [
+      z,
+      s,
+      N,
+      I,
       E,
-      r,
-      S,
-      C,
-      F,
-      T,
-      i
+      O,
+      d,
+      P
     ]
   );
-  return /* @__PURE__ */ b(X, { engine: e, config: J, form: n, children: /* @__PURE__ */ L(
+  return /* @__PURE__ */ S(Re, { engine: e, config: ce, form: o, children: /* @__PURE__ */ A(
     "form",
     {
-      ref: x,
-      onSubmit: B,
-      className: D,
+      ref: k,
+      onSubmit: le,
+      className: U,
       style: {
-        ...O,
+        ...X,
         // 当配置了 column 时，使用 CSS Grid 布局
-        ...i && i > 1 ? {
+        ...d && d > 1 ? {
           display: "grid",
-          gridTemplateColumns: `repeat(${i}, 1fr)`,
+          gridTemplateColumns: `repeat(${d}, 1fr)`,
           gap: "0 16px"
         } : {}
       },
       noValidate: !0,
       children: [
-        A.map((p, K) => U(p, K)),
-        !g && d,
-        V
+        se.map((t, r) => me(t, r)),
+        !C && R,
+        Y
       ]
     }
   ) });
 }
 export {
-  ne as NexusForm
+  je as NexusForm
 };

package/dist/es/components/form-controller.d.ts

@@ -0,0 +1,129 @@
+import { FieldState, NexusFormInstance, NexusSchema, NexusEngine } from '@xbeeant/form-engine';
+/**
+ * FormController — 包裹引擎宿主，暴露 Form 实例 API
+ *
+ * 一个 form 可承载多个 NexusForm 挂载（每个挂载一份 schema，schema 与状态互相独立）。
+ * 实例标识由 NexusForm 内部生成（React useId），用户侧不感知任何 instanceId：
+ * - 同一 form 引用 = 同一引擎宿主：插件/组件注册/跨表单联动等引擎级能力共享
+ * - 每个 NexusForm 挂载自动获得独立实例：schema/值/校验/订阅互不影响
+ * - form 的 API（getValues/setValues/submit/resetFields...）聚合作用于全部实例
+ * - 引擎本身是独立实体，可单独创建或跨 form 复用（useForm(formId, engine)）
+ */
+export declare class FormController implements NexusFormInstance {
+    private engine;
+    /** 提交中状态（校验 + onFinish 全流程，formily submitting 对齐） */
+    private submitting;
+    /** 提交状态监听器（供 useSyncExternalStore 消费） */
+    private submittingListeners;
+    /** 实例标识（内部）→ 实例视图引擎（同一 form 挂载的多个 NexusForm 各自独立） */
+    private views;
+    /** 实例标识 → 该实例的 DOM / 回调绑定（onFinish/onFinishFailed 按实例独立） */
+    private instanceBindings;
+    /** 实例标识 → watch / removeHiddenData / onValuesChange / omitNil 配置（按实例独立） */
+    private instanceConfigs;
+    constructor(engine?: NexusEngine);
+    /**
+     * 获取（或创建）指定实例的引擎视图
+     *
+     * 同一 form 挂载多个 NexusForm 时各自独立：schema/值/订阅互不影响。
+     * 实例标识由 NexusForm 内部分配（React useId），用户不感知。
+     *
+     * @param instanceId - 实例标识（内部）
+     * @returns 定向到该实例的引擎视图
+     */
+    _useInstance(instanceId: string): NexusEngine;
+    /**
+     * 内部：解析方法作用的目标实例视图（聚合全部实例，无实例时回退宿主引擎）
+     */
+    private resolveViews;
+    /** 内部：首次绑定的实例 DOM（兼容既有 scrollToPath/focusFirstError 单实例行为） */
+    private getPrimaryFormEl;
+    /**
+     * 内部：绑定实例 DOM + 回调 getter（由 NexusForm 在挂载时按实例调用）
+     * 回调以 getter 传入：submit 时读取最新闭包，而非绑定时刻的快照
+     */
+    _bind(instanceId: string, formEl: HTMLFormElement | null, getOnFinish: () => (data: Record<string, unknown>) => void | Promise<void>, getOnFinishFailed: () => (errors: Map<string, string[]>) => void): void;
+    /** 内部：同步 watch / removeHiddenData / onValuesChange 配置（由 NexusForm 在它们变化时按实例调用） */
+    _syncConfig(instanceId: string, config: {
+        removeHiddenData?: boolean;
+        /** 提交/取值时递归移除空值（undefined/null/''，ProForm omitNil 对齐） */
+        omitNil?: boolean;
+        watch?: {
+            [path: string]: (value: unknown, allValues: Record<string, unknown>, changedPath?: string) => void;
+        };
+        onValuesChange?: (changedValue: unknown, allValues: Record<string, unknown>, changedPath: string) => void;
+    }): void;
+    /** 内部：值变更时调用（由 Engine 通知，携带实例标识路由到对应实例的 watcher） */
+    _onFieldValueChange(instanceId: string, path: string, value: unknown): void;
+    /** 内部：获取引擎宿主实例 */
+    _getEngine(): NexusEngine;
+    /**
+     * 获取底层引擎宿主实例（用于跨表单联动：linkForm / setFormId / registerAntdUI 等；
+     * 宿主上的组件/插件注册对全部实例生效）
+     */
+    getEngine(): NexusEngine;
+    submit(options?: {
+        validateFirst?: boolean;
+        omitNil?: boolean;
+    }): Promise<void>;
+    /** 提交中状态（formily submitting 对齐，供提交按钮 loading） */
+    getSubmitting(): boolean;
+    /** 订阅提交状态变化（返回取消订阅函数，供 useSyncExternalStore 使用） */
+    onSubmittingChange(callback: () => void): () => void;
+    private setSubmitting;
+    private runSubmit;
+    /** 内部：反查实例视图对应的实例标识 */
+    private findInstanceId;
+    /**
+     * 定位到第一个校验失败的字段：按 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[], options?: {
+        omitNil?: boolean;
+    }): 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[], options?: {
+        validateFirst?: boolean;
+    }): Promise<Map<string, string[]>>;
+    getFieldState(path: string): FieldState | undefined;
+    /**
+     * 重载远程选项数据（x-render reloadRemoteData 对齐）
+     * 传入 path 仅重载该字段的远程数据；缺省时重载全部远程数据字段。
+     * 作用于全部实例视图。
+     */
+    reloadRemoteData(path?: string): void;
+}