@xbeeant/form-engine-react 0.0.1

package/src/components/FormController.ts

@@ -0,0 +1,271 @@
+import type {
+  FieldState,
+  NexusFormInstance,
+  NexusSchema,
+} from '@xbeeant/form-engine';
+import { AsyncValidatorPlugin, NexusEngine } from '@xbeeant/form-engine';
+import type { RefObject } from 'react';
+
+/**
+ * FormController — 包裹 Engine，暴露 Form 实例 API
+ */
+export class FormController implements NexusFormInstance {
+  private engine: NexusEngine;
+  private formElementRef: RefObject<HTMLFormElement | null>;
+  /** 稳定的 getter：每次 submit 执行时从外部 ref 读取最新的 onFinish/onFinishFailed 回调 */
+  private getOnFinish: () => (
+    data: Record<string, unknown>,
+  ) => void | Promise<void>;
+  private getOnFinishFailed: () => (errors: Map<string, string[]>) => void;
+  private removeHiddenData: boolean = true;
+  private watchers: Map<
+    string,
+    (value: unknown, allValues: Record<string, unknown>) => void
+  > = new Map();
+  private globalWatcher:
+    | ((
+        value: Record<string, unknown>,
+        allValues: Record<string, unknown>,
+        changedPath?: string,
+      ) => void)
+    | null = null;
+
+  constructor(engine?: NexusEngine) {
+    this.engine = engine ?? new NexusEngine();
+    // 默认注入异步校验器插件：useFieldValidator / registerFieldValidator
+    // 注册的异步校验器即可在字段值变化时被触发（防抖调度，与默认 'change' trigger 对齐）。
+    // 外部已注入同名插件时不重复注入（hasPlugin 幂等）。
+    if (!this.engine.hasPlugin('async-validator')) {
+      this.engine.use(new AsyncValidatorPlugin(this.engine));
+    }
+    this.formElementRef = {
+      current: null,
+    } as RefObject<HTMLFormElement | null>;
+    this.getOnFinish = () => () => {};
+    this.getOnFinishFailed = () => () => {};
+  }
+
+  /** 内部：首次绑定表单 DOM + 回调 getter（由 NexusForm 在挂载时调用一次） */
+  _bind(
+    formEl: HTMLFormElement | null,
+    getOnFinish: () => (data: Record<string, unknown>) => void | Promise<void>,
+    getOnFinishFailed: () => (errors: Map<string, string[]>) => void,
+  ): void {
+    (this.formElementRef as { current: HTMLFormElement | null }).current =
+      formEl;
+    this.getOnFinish = getOnFinish;
+    this.getOnFinishFailed = getOnFinishFailed;
+    // 注册值变更回调到 Engine，只需一次（回调闭包引用了稳定的实例）
+    this.engine.registerOnFieldValueChange((path, value) =>
+      this._onFieldValueChange(path, value),
+    );
+  }
+
+  /** 内部：同步 watch / removeHiddenData 配置（由 NexusForm 在它们变化时调用） */
+  _syncConfig(config: {
+    removeHiddenData?: boolean;
+    watch?: {
+      [path: string]: (
+        value: unknown,
+        allValues: Record<string, unknown>,
+        changedPath?: string,
+      ) => void;
+    };
+  }): void {
+    if (config.removeHiddenData !== undefined) {
+      this.removeHiddenData = config.removeHiddenData;
+    }
+    if (config.watch) {
+      this.watchers.clear();
+      this.globalWatcher = null;
+      for (const [path, fn] of Object.entries(config.watch)) {
+        if (path === '#') {
+          this.globalWatcher = fn;
+        } else {
+          this.watchers.set(path, fn);
+        }
+      }
+    }
+  }
+
+  /** 内部：值变更时调用（由 Engine 通知） */
+  _onFieldValueChange(path: string, value: unknown): void {
+    const allValues = this.engine.getFormData();
+    const globalData = this.removeHiddenData
+      ? allValues
+      : this.engine.getAllFormData();
+
+    // 全局 watcher（# 监听所有字段变化，value 即为全部表单值；
+    // 第三参携带本次实际变更的字段路径，供清空值场景区分「未赋值默认值」与「用户主动清空」）
+    if (this.globalWatcher) {
+      this.globalWatcher(globalData, globalData, path);
+    }
+    // 路径匹配的 watcher
+    const fn = this.watchers.get(path);
+    if (fn) {
+      fn(value, globalData);
+    }
+  }
+
+  /** 内部：获取 Engine 实例 */
+  _getEngine(): NexusEngine {
+    return this.engine;
+  }
+
+  async submit(): Promise<void> {
+    const errors = await this.engine.validate();
+    if (errors.size > 0) {
+      this.focusFirstError(errors);
+      this.getOnFinishFailed()?.(errors);
+      return;
+    }
+    const formData = this.removeHiddenData
+      ? this.engine.getFormData()
+      : this.engine.getAllFormData();
+    await this.getOnFinish()?.(formData);
+  }
+
+  /**
+   * 定位到第一个校验失败的字段：按 DOM 渲染顺序查找（保证视觉上的"第一个"），
+   * 滚动入视并聚焦其内部可交互控件。
+   */
+  private focusFirstError(errors: Map<string, string[]>): void {
+    const formEl = this.formElementRef.current;
+    if (!formEl || errors.size === 0) {
+      return;
+    }
+
+    const errorPaths = new Set(errors.keys());
+
+    const focus = () => {
+      const fieldEls =
+        formEl.querySelectorAll<HTMLElement>('[data-nexus-field]');
+      for (const el of Array.from(fieldEls)) {
+        const path = el.getAttribute('data-nexus-field');
+        if (!path || !errorPaths.has(path)) {
+          continue;
+        }
+
+        el.scrollIntoView({ behavior: 'smooth', block: 'center' });
+        const focusable = el.querySelector<HTMLElement>(
+          'input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])',
+        );
+        focusable?.focus();
+        return;
+      }
+    };
+
+    // 等待 React 将错误态刷到 DOM 后再定位，保证错误提示已可见
+    requestAnimationFrame(focus);
+  }
+
+  resetFields(): void {
+    this.engine.reset();
+  }
+
+  setErrorFields(errors: Array<{ path: string; errors: string[] }>): void {
+    this.engine.setErrorFields(errors);
+  }
+
+  setValues(values: Record<string, unknown>): void {
+    this.engine.setFieldValues(values);
+  }
+
+  setValueByPath(path: string, value: unknown): void {
+    this.engine.setFieldValue(path, value);
+  }
+
+  setSchemaByPath(path: string, patch: Record<string, unknown>): void {
+    this.engine.setSchemaByPath(path, patch);
+  }
+
+  setSchema(schema: NexusSchema): void {
+    this.engine.setSchema(schema);
+  }
+
+  getValues(paths?: string[]): Record<string, unknown> {
+    return this.engine.getFormData(paths);
+  }
+
+  getHiddenValues(): Record<string, unknown> {
+    return this.engine.getHiddenValues();
+  }
+
+  /** 获取所有字段值（含 hidden） */
+  getAllValues(): Record<string, unknown> {
+    return this.engine.getAllFormData();
+  }
+
+  getValueByPath(path: string): unknown {
+    return this.engine.getFieldValue(path);
+  }
+
+  /**
+   * 注册字段校验逻辑
+   * @param path 字段路径（如 'username'）
+   * @param validator 校验函数，返回错误消息数组（空数组表示通过）
+   */
+  registerValidator(
+    path: string,
+    validator: (
+      value: unknown,
+      formData: Record<string, unknown>,
+    ) => string[] | Promise<string[]>,
+  ): void {
+    // 注册到 Engine（validate 与 实时校验 统一由 Engine 执行）
+    this.engine.registerFieldValidator(path, validator);
+  }
+
+  /**
+   * 注销字段校验逻辑（按函数引用移除）
+   * 与 registerValidator 配对；widget 组件卸载时清理，避免校验器累积
+   */
+  unregisterValidator(
+    path: string,
+    validator: (
+      value: unknown,
+      formData: Record<string, unknown>,
+    ) => string[] | Promise<string[]>,
+  ): void {
+    this.engine.unregisterFieldValidator(path, validator);
+  }
+
+  /**
+   * 实时重校验指定字段（同步）
+   * 供 widget 组件内部状态变化（非字段值变化）时主动刷新错误态
+   */
+  revalidateField(path: string): void {
+    this.engine.validateField(path, { trigger: 'change' });
+  }
+
+  getSchema(): NexusSchema | null {
+    return this.engine.getSchema();
+  }
+
+  removeErrorField(path: string): void {
+    this.engine.removeErrorField(path);
+  }
+
+  scrollToPath(path: string): void {
+    const el = this.formElementRef.current?.querySelector(
+      `[data-nexus-field="${path}"]`,
+    );
+    el?.scrollIntoView({ behavior: 'smooth', block: 'center' });
+  }
+
+  getFieldError(path: string): string[] {
+    return this.engine.getFieldError(path);
+  }
+
+  getFieldsError(): Map<string, string[]> {
+    return this.engine.getFieldsError();
+  }
+
+  validateFields(paths?: string[]): Promise<Map<string, string[]>> {
+    return this.engine.validate(paths);
+  }
+
+  getFieldState(path: string): FieldState | undefined {
+    return this.engine.getFieldState(path);
+  }
+}

package/src/components/NexusField.tsx

@@ -0,0 +1,182 @@
+import type { CSSProperties, FocusEvent } from 'react';
+import { useCallback, useContext, useMemo, useSyncExternalStore } from 'react';
+import { FieldInheritContext } from '../contexts/FieldInheritContext';
+import { GridContext } from '../contexts/GridContext';
+import { LayoutConfigContext } from '../contexts/LayoutConfigContext';
+import { useNexusContext } from '../contexts/NexusContext';
+import { resolveColSpan } from '../utils/resolveColSpan';
+
+interface NexusFieldProps {
+  dataPath: string;
+  layoutKey: string;
+}
+
+/**
+ * NexusField — 单个字段渲染器
+ */
+export function NexusField({ dataPath, layoutKey }: NexusFieldProps) {
+  const { engine, config, form } = useNexusContext();
+  // 按路径精准订阅：仅该字段版本变化时重渲染（reaction 影响其他字段不会触发本组件）
+  // 第三个参数 getServerSnapshot 与 getSnapshot 一致（引擎状态同步，SSR 必需）
+  useSyncExternalStore(
+    (onStoreChange) => engine.subscribeField(dataPath, onStoreChange),
+    () => engine.getFieldVersion(dataPath),
+    () => engine.getFieldVersion(dataPath),
+  );
+  const state = engine.getFieldState(dataPath);
+  // GridContext 必须在所有 early return 之前调用，否则会破坏 Hooks 调用顺序
+  const gridCtx = useContext(GridContext);
+  const layoutConfig = useContext(LayoutConfigContext);
+  // 祖先对象容器（NexusObject）下发的继承属性：visible=false 时子树整体隐藏
+  const inherit = useContext(FieldInheritContext);
+
+  const handleChange = useCallback(
+    (value: unknown) => {
+      engine.setFieldValue(dataPath, value);
+    },
+    [engine, dataPath],
+  );
+
+  // 失焦触发 blur 规则校验（trigger: 'blur'）：
+  // React onBlur 冒泡（focusout 语义），包裹层统一处理内部控件失焦；
+  // 焦点仍在字段内部（如 dateRange 双输入框间切换）时跳过。
+  const handleBlur = useCallback(
+    (e: FocusEvent<HTMLDivElement>) => {
+      if (e.currentTarget.contains(e.relatedTarget as Node)) {
+        return;
+      }
+      engine.validateField(dataPath, { trigger: 'blur' });
+    },
+    [engine, dataPath],
+  );
+
+  // 从 enum + enumNames 构建选项（x-render 对齐）。
+  // meta/props 引用在状态更新时保持稳定，useMemo 避免每次渲染重建数组（破坏子组件 memo）。
+  // 必须在所有 early return 之前调用（Hooks 顺序规则），state 未定义时安全降级
+  const options = useMemo(
+    () =>
+      state?.meta.enum
+        ? state.meta.enum.map((value: any, index: number) => ({
+            value,
+            label: state.meta.enumNames?.[index] ?? String(value),
+          }))
+        : (state?.props.options as
+            | Array<{ label: string; value: unknown } | string | number>
+            | undefined),
+    [state?.meta.enum, state?.meta.enumNames, state?.props.options],
+  );
+
+  // 从 reactions 依赖构建 dependValues，供 widget 获取关联字段值。
+  // reactions 引用稳定，值在 memo 执行时读取；避免每次渲染新建对象
+  const dependValues = useMemo(() => {
+    const values: Record<string, unknown> = {};
+    if (state?.reactions) {
+      for (const reaction of state.reactions) {
+        if (reaction.dependencies) {
+          for (const dep of reaction.dependencies) {
+            values[dep] = engine.getFieldValue(dep);
+          }
+        }
+      }
+    }
+    return values;
+  }, [state?.reactions, engine]);
+
+  if (!state) {
+    // 仅当引擎已初始化（version > 0）但字段仍未找到时才发出警告
+    // 初始化过程中的短暂空状态不应报警
+    if (engine.getSnapshot() > 0) {
+      console.warn(`[NexusField] Field not found: ${dataPath}`);
+    }
+    return null;
+  }
+
+  // 祖先对象容器隐藏 → 子树整体不可见（与字段自身 visible 合并判断）
+  if (inherit.visible === false || !state.visible) {
+    // 如果父布局节点配置了 removeHidden，则不渲染占位符（移除以防止栅格塌陷）
+    if (layoutConfig.removeHidden === true) {
+      return null;
+    }
+    // 默认行为：渲染 display:none 占位符以保持布局
+    return <div className='hidden' data-nexus-hidden={dataPath} />;
+  }
+
+  // 从 enum + enumNames 构建选项（x-render 对齐）
+  const readOnly =
+    config.readOnly || inherit.readOnly === true || state.readOnly;
+  // 对象容器继承 disabled（父级激活时优先），与字段级 disabled 合并
+  const disabled = inherit.disabled === true || state.disabled;
+
+  // readOnlyWidget：指定 readOnly 生效时切换使用的渲染 widget（x-render readOnlyWidget 对齐）。
+  // - 配置了 readOnlyWidget 且字段为只读时，切换渲染该 widget（readOnly 一并透传，
+  //   widget 按自身逻辑决定只读展示形态，如 treeSelect 的 readOnly 回显）；
+  // - 未配置时 readOnly 原样透传给 widget，由 widget 自身决定只读形态
+  //   （antd 原生 readOnly，或内置 widget 的 ReadOnlyDisplay 文本回退）。
+  const wantReadOnlyWidget = readOnly && !!state.meta.readOnlyWidget;
+  const widgetName = wantReadOnlyWidget
+    ? state.meta.readOnlyWidget!
+    : state.meta.widget;
+  /** 获取UI组件库 进行渲染 **/
+  let Widget = engine.getWidget(widgetName);
+  // readOnlyWidget 未注册时优雅降级：退回原 widget，沿用现有只读渲染方式
+  if (!Widget && wantReadOnlyWidget) {
+    Widget = engine.getWidget(state.meta.widget);
+  }
+
+  if (!Widget) {
+    return (
+      <div className='text-xs text-red-500' data-nexus-field={dataPath}>
+        ⚠️ Widget "{state.meta.widget}" 未注册 (path: {dataPath})
+      </div>
+    );
+  }
+
+  // 字段级配置优先于表单级配置
+  const fieldDisplayType = state.meta.displayType ?? config.displayType;
+  const fieldLabelWidth = state.meta.labelWidth ?? config.labelWidth;
+  const fieldColumn = state.meta.column ?? config.column;
+
+  // 布局属性作用于 NexusField 包装层而非 DOM 控件
+  // - column（fieldColumn）：字段内部子元素分列数（如 checkboxes/radio），传给 Widget
+  // - colSpan：在父 Grid 中横跨多少列（tailwind 风格：gridColumn: span N）
+  // - width：在父 Flex 布局中自身宽度（百分比或固定值），flexShrink:0 防压缩
+  const effectiveColSpan = resolveColSpan(state.meta.colSpan, gridCtx);
+  const wrapperStyle: CSSProperties = {
+    ...(state.meta.width ? { width: state.meta.width, flexShrink: 0 } : {}),
+    ...(effectiveColSpan ? { gridColumn: `span ${effectiveColSpan}` } : {}),
+  };
+
+  return (
+    <div
+      data-nexus-field={dataPath}
+      onBlur={handleBlur}
+      style={Object.keys(wrapperStyle).length > 0 ? wrapperStyle : undefined}
+    >
+      <Widget
+        key={layoutKey}
+        dataPath={dataPath}
+        path={dataPath}
+        value={state.value}
+        onChange={handleChange}
+        disabled={disabled}
+        readOnly={readOnly}
+        loading={state.loading}
+        required={state.required}
+        title={state.meta.title}
+        description={state.meta.description}
+        placeholder={state.meta.placeholder}
+        label={state.meta.label}
+        options={options}
+        errors={state.errors}
+        extra={state.meta.extra}
+        displayType={fieldDisplayType}
+        labelWidth={fieldLabelWidth}
+        column={fieldColumn}
+        form={form}
+        dependValues={dependValues}
+        items={state.meta.items}
+        {...state.props}
+      />
+    </div>
+  );
+}