@xbeeant/form-engine-react 0.0.3 → 0.0.4

package/dist/es/components/form-controller.js

@@ -0,0 +1,310 @@
+import { NexusEngine as g, AsyncValidatorPlugin as h } from "@xbeeant/form-engine";
+import { omitNilDeep as c } from "../utils/omit-nil.js";
+const f = /* @__PURE__ */ new WeakSet();
+class V {
+  engine;
+  /** 提交中状态（校验 + 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 g(), this.engine.hasPlugin("async-validator") || this.engine.use(new h(this.engine));
+  }
+  /**
+   * 获取（或创建）指定实例的引擎视图
+   *
+   * 同一 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 / 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 通知，携带实例标识路由到对应实例的 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);
+  }
+  /** 内部：获取引擎宿主实例 */
+  _getEngine() {
+    return this.engine;
+  }
+  /**
+   * 获取底层引擎宿主实例（用于跨表单联动：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;
+    }
+    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, t) {
+    if (!t || e.size === 0)
+      return;
+    const s = new Set(e.keys());
+    requestAnimationFrame(() => {
+      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;
+        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;
+      }
+    });
+  }
+  resetFields() {
+    for (const e of this.resolveViews())
+      e.reset();
+  }
+  setErrorFields(e) {
+    for (const t of this.resolveViews())
+      t.setErrorFields(e);
+  }
+  setValues(e) {
+    for (const t of this.resolveViews())
+      t.setFieldValues(e);
+  }
+  setValueByPath(e, t) {
+    for (const s of this.resolveViews())
+      s.setFieldValue(e, t);
+  }
+  setSchemaByPath(e, t) {
+    for (const s of this.resolveViews())
+      s.setSchemaByPath(e, t);
+  }
+  setSchema(e) {
+    for (const t of this.resolveViews())
+      t.setSchema(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() {
+    const e = {};
+    for (const t of this.resolveViews())
+      Object.assign(e, t.getHiddenValues());
+    return e;
+  }
+  /** 获取所有字段值（含 hidden） */
+  getAllValues() {
+    const e = {};
+    for (const t of this.resolveViews())
+      Object.assign(e, t.getAllFormData());
+    return e;
+  }
+  getValueByPath(e) {
+    for (const t of this.resolveViews()) {
+      const s = t.getFieldValue(e);
+      if (s !== void 0)
+        return s;
+    }
+  }
+  /**
+   * 注册字段校验逻辑
+   * @param path 字段路径（如 'username'）
+   * @param validator 校验函数，返回错误消息数组（空数组表示通过）
+   */
+  registerValidator(e, t) {
+    for (const s of this.resolveViews())
+      s.registerFieldValidator(e, t);
+  }
+  /**
+   * 注销字段校验逻辑（按函数引用移除）
+   * 与 registerValidator 配对；widget 组件卸载时清理，避免校验器累积
+   */
+  unregisterValidator(e, t) {
+    for (const s of this.resolveViews())
+      s.unregisterFieldValidator(e, t);
+  }
+  /**
+   * 实时重校验指定字段（同步）
+   * 供 widget 组件内部状态变化（非字段值变化）时主动刷新错误态
+   */
+  revalidateField(e) {
+    for (const t of this.resolveViews())
+      t.validateField(e, { trigger: "change" });
+  }
+  getSchema() {
+    return this.resolveViews()[0]?.getSchema() ?? null;
+  }
+  removeErrorField(e) {
+    for (const t of this.resolveViews())
+      t.removeErrorField(e);
+  }
+  scrollToPath(e) {
+    this.getPrimaryFormEl()?.querySelector(`[data-nexus-field="${e}"]`)?.scrollIntoView({ behavior: "smooth", block: "center" });
+  }
+  getFieldError(e) {
+    for (const t of this.resolveViews()) {
+      const s = t.getFieldError(e);
+      if (s.length > 0)
+        return s;
+    }
+    return [];
+  }
+  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, 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) {
+    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 {
+  V as FormController
+};

package/dist/es/components/nexus-field.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/nexus-field.js

@@ -0,0 +1,131 @@
+import { jsx as m, jsxs as R } from "react/jsx-runtime";
+import { useSyncExternalStore as $, useContext as f, useCallback as C, useMemo as y } from "react";
+import { FieldInheritContext as E } from "../contexts/field-inherit-context.js";
+import { GridContext as G } from "../contexts/grid-context.js";
+import { LayoutConfigContext as H } from "../contexts/layout-config-context.js";
+import { useNexusContext as z } from "../contexts/nexus-context.js";
+import { resolveColSpan as A } from "../utils/resolve-col-span.js";
+function K({ dataPath: t, layoutKey: x }) {
+  const { engine: l, config: c, form: i } = z();
+  $(
+    (n) => l.subscribeField(t, n),
+    () => l.getFieldVersion(t),
+    () => l.getFieldVersion(t)
+  );
+  const e = l.getFieldState(t), S = f(G), w = f(H), u = f(E), W = C(
+    (n) => {
+      l.setFieldValue(t, n);
+    },
+    [l, t]
+  ), N = C(
+    (n) => {
+      n.currentTarget.contains(n.relatedTarget) || l.validateField(t, { trigger: "blur" });
+    },
+    [l, t]
+  ), O = y(
+    () => e?.meta.enum ? e.meta.enum.map((n, r) => ({
+      value: n,
+      label: e.meta.enumNames?.[r] ?? String(n)
+    })) : e?.props.options,
+    [e?.meta.enum, e?.meta.enumNames, e?.props.options]
+  ), B = y(() => {
+    const n = {};
+    if (e?.reactions) {
+      for (const r of e.reactions)
+        if (r.dependencies)
+          for (const a of r.dependencies)
+            n[a] = l.getFieldValue(a);
+    }
+    return n;
+  }, [e?.reactions, l]), T = y(() => {
+    const n = e?.meta.itemOf, a = !!n ? t.match(/\[(\d+)\]/) : void 0, M = a ? Number(a[1]) : void 0;
+    return {
+      get formData() {
+        return i.getValues();
+      },
+      get rootValue() {
+        return i.getValues();
+      },
+      value: e?.value,
+      dataPath: t,
+      path: t,
+      index: M,
+      parentValues: n ? i.getValueByPath(n) : void 0,
+      getValue: (s) => i.getValueByPath(s),
+      setValue: (s, d) => i.setValueByPath(s, d),
+      onItemChange: (s, d) => i.setValueByPath(s, d),
+      validate: async (s) => {
+        s ? await i.validateFields([s]) : await i.validateFields([t]);
+      },
+      validateFields: async (s) => {
+        await i.validateFields(s);
+      },
+      submit: () => i.submit(),
+      resetFields: () => i.resetFields(),
+      setSchema: (s) => i.setSchema(s),
+      setSchemaByPath: (s, d) => i.setSchemaByPath(s, d),
+      getSchema: () => i.getSchema()
+    };
+  }, [i, t, e?.value, e?.meta.itemOf]);
+  if (!e)
+    return l.getSnapshot() > 0 && console.warn(`[NexusField] Field not found: ${t}`), null;
+  if (u.visible === !1 || !e.visible)
+    return w.removeHidden === !0 ? null : /* @__PURE__ */ m("div", { className: "hidden", "data-nexus-hidden": t });
+  const p = c.readOnly || u.readOnly === !0 || e.readOnly, I = u.disabled === !0 || e.disabled, h = p && !!e.meta.readOnlyWidget, j = h ? e.meta.readOnlyWidget : e.meta.widget;
+  let o = l.getWidget(j);
+  if (!o && h && (o = l.getWidget(e.meta.widget)), !o)
+    return /* @__PURE__ */ R("div", { className: "text-xs text-red-500", "data-nexus-field": t, children: [
+      '⚠️ Widget "',
+      e.meta.widget,
+      '" 未注册 (path: ',
+      t,
+      ")"
+    ] });
+  const k = e.meta.displayType ?? c.displayType, D = e.meta.labelWidth ?? c.labelWidth, q = e.meta.column ?? c.column, v = A(e.meta.colSpan, S), F = {
+    ...e.meta.width ? { width: e.meta.width, flexShrink: 0 } : {},
+    ...v ? { gridColumn: `span ${v}` } : {}
+  }, b = l.getFieldWrapper(), L = {
+    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,
+    displayType: k,
+    labelWidth: D,
+    column: q
+  }, V = {
+    dataPath: t,
+    path: t,
+    value: e.value,
+    onChange: W,
+    disabled: I,
+    readOnly: p,
+    loading: e.loading,
+    placeholder: e.meta.placeholder,
+    options: O,
+    form: i,
+    addons: T,
+    dependValues: B,
+    items: e.meta.items,
+    schema: e.meta.schema,
+    // 远程选项数据版本：reloadRemoteData 后变化，widget 据此跳过缓存重新请求
+    remoteVersion: l.getRemoteDataVersion(t),
+    ...e.props
+  };
+  let g;
+  return b ? g = /* @__PURE__ */ m(b, { ...L, children: /* @__PURE__ */ m(o, { ...V }) }, x) : g = /* @__PURE__ */ m(o, { ...V }, x), /* @__PURE__ */ m(
+    "div",
+    {
+      "data-nexus-field": t,
+      className: p ? "nexus-field-readonly" : void 0,
+      onBlur: N,
+      style: Object.keys(F).length > 0 ? F : void 0,
+      children: g
+    }
+  );
+}
+export {
+  K as NexusField
+};

package/dist/es/components/nexus-form-provider.d.ts

@@ -0,0 +1,12 @@
+import { NexusEngine } from '@xbeeant/form-engine';
+import { ReactNode } from 'react';
+import { FormController } from './form-controller';
+import { NexusFormConfig } from './nexus-form';
+interface NexusFormProviderProps {
+    engine: NexusEngine;
+    config: NexusFormConfig;
+    form: FormController;
+    children: ReactNode;
+}
+export declare function NexusFormProvider({ engine, config, form, children, }: NexusFormProviderProps): import("react").JSX.Element;
+export {};

package/dist/es/components/nexus-form-provider.js

@@ -0,0 +1,18 @@
+import { jsx as u } from "react/jsx-runtime";
+import { useMemo as s } from "react";
+import { NexusContext as x } from "../contexts/nexus-context.js";
+function d({
+  engine: r,
+  config: o,
+  form: t,
+  children: e
+}) {
+  const m = s(
+    () => ({ engine: r, config: o, form: t }),
+    [r, o, t]
+  );
+  return /* @__PURE__ */ u(x.Provider, { value: m, children: e });
+}
+export {
+  d as NexusFormProvider
+};

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

@@ -0,0 +1,114 @@
+import { NexusComponent, NexusSchema } from '@xbeeant/form-engine';
+import { CSSProperties, ReactNode } from 'react';
+import { PersistOptions } from '../utils/persist';
+import { FormController } from './form-controller';
+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;
+    /** 表单语言标识（如 'zh-CN' / 'en-US'，ui 层消费：antd locale + 内置文案） */
+    locale?: string;
+}
+export interface NexusFormProps {
+    /**
+     * Form 实例，由 useForm() 创建。同一 form 引用 = 同一引擎宿主（组件/插件注册共享）；
+     * 每个 NexusForm 挂载自动获得独立实例（schema/值/订阅互不影响），
+     * form 的 API（getValues/setValues/submit...）聚合作用于全部实例。
+     */
+    form: FormController;
+    /** Schema 定义 */
+    schema?: NexusSchema;
+    /** 初始值 */
+    initialValues?: Record<string, unknown>;
+    /** 额外注册的 widget（与已注册的合并） */
+    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;
+    /** 自定义类名 */
+    className?: string;
+    /** 自定义样式 */
+    style?: CSSProperties;
+    /** 子节点 */
+    children?: ReactNode;
+    /**
+     * 表单值变化监听
+     * - key 为字段路径（如 'username'），值为回调函数
+     * - 使用 '#' 作为 key 可监听所有字段变化
+     * - 回调参数为 (value, allValues)；全局（'#'）监听额外提供第三参 changedPath，
+     *   即本次实际变更的字段路径（用于区分「未触碰的默认空值」与「用户主动清空」）
+     */
+    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 */
+    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, 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;