@flowgram-vue/form-core 0.2.0

package/src/form/flow-node-form-data.ts

@@ -0,0 +1,109 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Disposable, Emitter } from '@flowgram-vue/utils';
+import { FlowNodeEntity } from '@flowgram-vue/document';
+import { EntityData } from '@flowgram-vue/core';
+
+import { FlowNodeErrorData } from '../error';
+import { FormMetaOrFormMetaGenerator } from './types';
+import { FormModel, type FormModelFactory } from './models';
+
+interface Options {
+  formModelFactory: FormModelFactory;
+}
+
+export interface DetailChangeEvent {
+  path: string;
+  oldValue: any;
+  value: any;
+  initialized: boolean;
+}
+
+export interface OnFormValuesChangePayload {
+  values: any;
+  prevValues: any;
+  name: string;
+}
+
+export class FlowNodeFormData extends EntityData {
+  static type = 'FlowNodeEntityFormData';
+
+  readonly formModel: FormModel;
+
+  protected flowNodeEntity: FlowNodeEntity;
+
+  /**
+   * @deprecated rehaje 版表单form Values change 事件
+   * @protected
+   */
+  protected onDetailChangeEmitter = new Emitter<DetailChangeEvent>();
+
+  /**
+   * @deprecated 该方法为旧版引擎（rehaje）表单数据变更事件, 新版节点引擎请使用
+   * this.getFormModel<FormModelV2>().onFormValuesChange.
+   * @protected
+   */
+  readonly onDetailChange = this.onDetailChangeEmitter.event;
+
+  constructor(entity: FlowNodeEntity, opts: Options) {
+    super(entity);
+
+    this.flowNodeEntity = entity;
+    this.formModel = opts.formModelFactory(entity);
+
+    this.toDispose.push(this.onDetailChangeEmitter);
+
+    this.toDispose.push(
+      Disposable.create(() => {
+        this.formModel.dispose();
+      })
+    );
+  }
+
+  getFormModel<TFormModel>(): TFormModel {
+    // @ts-ignore
+    return this.formModel as TFormModel;
+  }
+
+  getDefaultData(): any {
+    return {};
+  }
+
+  createForm(formMetaOrFormMetaGenerator: any, initialValue?: any): void {
+    const errorData = this.flowNodeEntity.getData<FlowNodeErrorData>(FlowNodeErrorData);
+
+    errorData.setError(null);
+    try {
+      this.formModel.init(formMetaOrFormMetaGenerator, initialValue);
+    } catch (e) {
+      errorData.setError(e as Error);
+    }
+  }
+
+  updateFormValues(value: any) {
+    this.formModel.updateFormValues(value);
+  }
+
+  recreateForm(formMetaOrFormMetaGenerator: FormMetaOrFormMetaGenerator, initialValue?: any): void {
+    this.createForm(formMetaOrFormMetaGenerator, initialValue);
+  }
+
+  toJSON(): any {
+    return this.formModel.toJSON();
+  }
+
+  dispose(): void {
+    super.dispose();
+  }
+
+  /**
+   * @deprecated rehaje 版表单form Values change 事件触发函数
+   * @protected
+   */
+  fireDetaiChange(detailChangeEvent: DetailChangeEvent) {
+    this.onDetailChangeEmitter.fire(detailChangeEvent);
+  }
+}

package/src/form/form-contribution.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { type FormManager } from './services/form-manager';
+
+export const FormContribution = Symbol('FormContribution');
+
+export interface FormContribution {
+  onRegister?(formManager: FormManager): void;
+}

package/src/form/form-core-container-module.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { ContainerModule } from 'inversify';
+import { bindContributions } from '@flowgram-vue/utils';
+
+import { FormContextMaker } from './services/form-context-maker';
+import { NodeContribution } from '../node';
+import { FormManager, FormPathService } from './services';
+import { FormNodeContribution } from './form-node-contribution';
+
+export const FormCoreContainerModule = new ContainerModule((bind) => {
+  bind(FormManager).toSelf().inSingletonScope();
+  bind(FormPathService).toSelf().inSingletonScope();
+  bind(FormContextMaker).toSelf().inSingletonScope();
+  bindContributions(bind, FormNodeContribution, [NodeContribution]);
+});

package/src/form/form-node-contribution.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { injectable } from 'inversify';
+
+import { NodeContribution, NodeManager, PLUGIN_KEY } from '../node';
+import { formPluginRender } from './form-render';
+
+@injectable()
+export class FormNodeContribution implements NodeContribution {
+  onRegister(nodeManager: NodeManager) {
+    nodeManager.registerPluginRender(PLUGIN_KEY.FORM, formPluginRender);
+  }
+}

package/src/form/form-render.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { h } from 'vue';
+
+import { NodeContext } from '../node';
+import FormRender from './FormRender.vue';
+
+export { default as FormRender } from './FormRender.vue';
+
+export const formPluginRender = (props: NodeContext) => h(FormRender, { node: props.node });

package/src/form/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './form-core-container-module';
+export * from './form-contribution';
+export * from './services';
+export * from './models';
+export * from './types';
+export * from './abilities';
+export * from './flow-node-form-data';
+export * from './client';

package/src/form/models/form-ability-extension-registry.ts

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { injectable } from 'inversify';
+
+export interface Extension {
+  key: string;
+}
+@injectable()
+export class FormAbilityExtensionRegistry {
+  protected registry = new Map<string, Extension>();
+
+  register(extension: Extension): void {
+    this.registry.set(extension.key, extension);
+  }
+
+  get<T extends Extension>(key: string): T | undefined {
+    return this.registry.get(key) as T | undefined;
+  }
+
+  get objectMap(): Record<string, Extension> {
+    return Object.fromEntries(this.registry);
+  }
+
+  get collection(): Extension[] {
+    return Array.from(this.registry.values());
+  }
+}

package/src/form/models/form-item-ability.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export interface FormItemAbility {
+  type: string;
+  /**
+   * 注册到formManager时钩子时调用
+   */
+  onAbilityRegister?: () => void;
+}
+
+export interface AbilityClass {
+  type: string;
+
+  new (): FormItemAbility;
+}

package/src/form/models/form-item-material-context.ts

@@ -0,0 +1,50 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { type FlowNodeEntity } from '@flowgram-vue/document';
+import { PlaygroundContext } from '@flowgram-vue/core';
+
+import { type IFormItemMeta } from '../types';
+import { type FormModel } from './form-model';
+
+export interface FormItemMaterialContext {
+  /**
+   * 当前表单项的meta
+   */
+  meta: IFormItemMeta;
+  /**
+   * 当前表单项的路径
+   */
+  path: string;
+  /**
+   * 节点引擎全局readonly
+   */
+  readonly: boolean;
+  /**
+   * 通过路径获取表单项的值
+   * @param path 表单项在当前表单中的绝对路径，路径协议遵循glob
+   */
+  getFormItemValueByPath: <T>(path: string) => T;
+  /**
+   * 节点表单校验回调函数注册
+   */
+  onFormValidate: FormModel['onValidate'];
+  /**
+   * 获取Node模型
+   */
+  node: FlowNodeEntity;
+  /**
+   * 获取FormModel原始模型
+   */
+  form: FormModel;
+  /**
+   * 业务注入的全局context
+   */
+  playgroundContext: PlaygroundContext;
+  /**
+   * 数组场景下当前项的index
+   */
+  index?: number | undefined;
+}

package/src/form/models/form-item.ts

@@ -0,0 +1,53 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { DisposableCollection, Emitter } from '@flowgram-vue/utils';
+
+import { type FormItemDomRef, type IFormItemMeta } from '../types';
+import { type FormModel } from './form-model';
+
+export abstract class FormItem {
+  readonly meta: IFormItemMeta;
+
+  readonly path: string;
+
+  readonly formModel: FormModel;
+
+  readonly onInitEventEmitter = new Emitter<FormItem>();
+
+  readonly onInit = this.onInitEventEmitter.event;
+
+  protected toDispose: DisposableCollection = new DisposableCollection();
+
+  readonly onDispose = this.toDispose.onDispose;
+
+  // todo(heyuan): 将dom 相关逻辑拆到form item插件里
+  private _domRef: FormItemDomRef;
+
+  protected constructor(meta: IFormItemMeta, path: string, formModel: FormModel) {
+    this.meta = meta;
+    this.path = path;
+    this.formModel = formModel;
+    this.toDispose.push(this.onInitEventEmitter);
+  }
+
+  abstract get value(): any;
+
+  abstract set value(value: any);
+
+  abstract validate(): void;
+
+  set domRef(domRef: FormItemDomRef) {
+    this._domRef = domRef;
+  }
+
+  get domRef() {
+    return this._domRef;
+  }
+
+  dispose(): void {
+    this.toDispose.dispose();
+  }
+}

package/src/form/models/form-meta.ts

@@ -0,0 +1,62 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { type IFormItemMeta, type IFormMeta, type IFormMetaOptions } from '../types';
+import { FormPathService } from '../services';
+
+export interface FormMetaTraverseParams {
+  formItemMeta: IFormItemMeta;
+  parentPath?: string;
+  handle: (params: { formItemMeta: IFormItemMeta; path: string }) => any;
+}
+
+export class FormMeta implements IFormMeta {
+  constructor(root: IFormItemMeta, options: IFormMetaOptions) {
+    this._root = root;
+    this._options = options;
+  }
+
+  protected _root: IFormItemMeta;
+
+  get root(): IFormItemMeta {
+    return this._root;
+  }
+
+  protected _options: IFormMetaOptions;
+
+  get options(): IFormMetaOptions {
+    return this._options;
+  }
+
+  static traverse({ formItemMeta, parentPath = '', handle }: FormMetaTraverseParams): void {
+    if (!formItemMeta) {
+      return;
+    }
+
+    const isRoot = !parentPath;
+
+    const path = isRoot
+      ? FormPathService.ROOT
+      : formItemMeta.name
+      ? FormPathService.join([parentPath, formItemMeta.name])
+      : parentPath;
+
+    handle({ formItemMeta, path });
+
+    if (formItemMeta.items) {
+      this.traverse({
+        formItemMeta: formItemMeta.items,
+        handle,
+        parentPath: FormPathService.toArrayPath(path),
+      });
+    }
+
+    if (formItemMeta.children && formItemMeta.children.length) {
+      formItemMeta.children.forEach((child) => {
+        this.traverse({ formItemMeta: child, handle, parentPath: path });
+      });
+    }
+  }
+}

package/src/form/models/form-model.ts

@@ -0,0 +1,84 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { injectable } from 'inversify';
+import { DisposableCollection, Event, MaybePromise } from '@flowgram-vue/utils';
+import { type FlowNodeEntity } from '@flowgram-vue/document';
+
+import { FormFeedback, FormModelValid, IFormItem } from '../types';
+import { type FormManager } from '../services/form-manager';
+import { type FormItem } from './form-item';
+
+export type FormModelFactory = (entity: FlowNodeEntity) => FormModel;
+export const FormModelFactory = Symbol('FormModelFactory');
+export const FormModelEntity = Symbol('FormModelEntity');
+
+@injectable()
+export abstract class FormModel {
+  readonly onValidate: Event<FormModel>;
+
+  readonly onValidChange: Event<FormModelValid>;
+
+  readonly onFeedbacksChange: Event<FormFeedback[]>;
+
+  readonly onInitialized: Event<FormModel>;
+
+  protected toDispose: DisposableCollection = new DisposableCollection();
+
+  /**
+   * @deprecated
+   * use `formModel.node` instead in FormModelV2
+   */
+  abstract get flowNodeEntity(): FlowNodeEntity;
+
+  /**
+   * @deprecated
+   */
+  abstract get formManager(): FormManager;
+
+  abstract get formMeta(): any;
+
+  abstract get initialized(): boolean;
+
+  abstract get valid(): FormModelValid;
+
+  abstract updateFormValues(value: any): void;
+
+  /**
+   * @deprecated
+   * use `formModel.getFieldIn` instead in FormModelV2 to get the model of a form field
+   * do not use this in FormModelV2 since  it only return an empty Map.
+   */
+  abstract get formItemPathMap(): Map<string, IFormItem>;
+
+  /**
+   * @deprecated
+   */
+  abstract clearValid(): void;
+
+  abstract validate(): Promise<boolean>;
+
+  abstract validateWithFeedbacks(): Promise<FormFeedback[]>;
+
+  abstract init(formMetaOrFormMetaGenerator: any, initialValue?: any): MaybePromise<void>;
+
+  abstract toJSON(): any;
+
+  /**
+   * @deprecated
+   * use `formModel.getField` instead in FormModelV2
+   */
+  abstract getFormItemByPath(path: string): FormItem | undefined;
+
+  /**
+   * @deprecated
+   * use `formModel.getFieldValue` instead in FormModelV2 to get the model of a form field by path
+   */
+  abstract getFormItemValueByPath<T = any>(path: string): any | undefined;
+
+  abstract render(): any;
+
+  abstract dispose(): void;
+}

package/src/form/models/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './form-model';
+export * from './form-item';
+export * from './form-meta';
+export * from './form-ability-extension-registry';
+export * from './form-item-ability';
+export * from './form-item-material-context';

package/src/form/services/form-context-maker.ts

@@ -0,0 +1,35 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { inject, injectable } from 'inversify';
+import { injectPlaygroundContext, PlaygroundContext } from '@flowgram-vue/core';
+
+import { NodeEngineContext } from '../../node/node-engine-context';
+import { FormItem } from '../models/form-item';
+import { type FormItemMaterialContext } from '../models/form-item-material-context';
+
+@injectable()
+export class FormContextMaker {
+  @inject(NodeEngineContext) readonly nodeEngineContext: NodeEngineContext;
+
+  @injectPlaygroundContext() readonly playgroundContext: PlaygroundContext;
+
+  makeFormItemMaterialContext(
+    formItem: FormItem,
+    options?: { getIndex: () => number | undefined }
+  ): FormItemMaterialContext {
+    return {
+      meta: formItem.meta,
+      path: formItem.path,
+      readonly: this.nodeEngineContext.readonly,
+      getFormItemValueByPath: formItem.formModel.getFormItemValueByPath.bind(formItem.formModel),
+      onFormValidate: formItem.formModel.onValidate.bind(formItem.formModel),
+      form: formItem.formModel,
+      node: formItem.formModel.flowNodeEntity,
+      playgroundContext: this.playgroundContext,
+      index: options?.getIndex(),
+    };
+  }
+}

package/src/form/services/form-manager.ts

@@ -0,0 +1,113 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { mapValues } from 'lodash-es';
+import { inject, injectable, multiInject, optional, postConstruct } from 'inversify';
+import { Emitter } from '@flowgram-vue/utils';
+import { injectPlaygroundContext, PlaygroundContext } from '@flowgram-vue/core';
+
+import { AbilityClass, FormItemAbility } from '../models/form-item-ability';
+import { FormAbilityExtensionRegistry, FormModel } from '../models';
+import { FormContribution } from '../form-contribution';
+import {
+  DecoratorAbility,
+  DecoratorExtension,
+  SetterAbility,
+  SetterExtension,
+  SetterHoc,
+} from '../abilities';
+import { FormContextMaker } from './form-context-maker';
+import { FormPathService } from './form-path-service';
+
+@injectable()
+export class FormManager {
+  readonly abilityRegistry: Map<string, FormItemAbility> = new Map();
+
+  readonly setterHocs: SetterHoc[] = [];
+
+  readonly extensionRegistryMap: Map<string, FormAbilityExtensionRegistry> = new Map();
+
+  @inject(FormPathService) readonly pathManager: FormPathService;
+
+  @inject(FormContextMaker) readonly formContextMaker: FormContextMaker;
+
+  @injectPlaygroundContext() readonly playgroundContext: PlaygroundContext;
+
+  @multiInject(FormContribution) @optional() protected formContributions: FormContribution[] = [];
+
+  private readonly onFormModelWillInitEmitter = new Emitter<{
+    model: FormModel;
+    data: any;
+  }>();
+
+  readonly onFormModelWillInit = this.onFormModelWillInitEmitter.event;
+
+  get components(): Record<string, any> {
+    return mapValues(
+      this.extensionRegistryMap.get(SetterAbility.type)?.objectMap || {},
+      (setter: SetterExtension) => setter.component
+    );
+  }
+
+  get decorators(): Record<string, any> {
+    return mapValues(
+      this.extensionRegistryMap.get(DecoratorAbility.type)?.objectMap || {},
+      (decorator: DecoratorExtension) => decorator.component
+    );
+  }
+
+  registerAbilityExtension(type: string, extension: any): void {
+    if (!this.extensionRegistryMap.get(type)) {
+      this.extensionRegistryMap.set(type, new FormAbilityExtensionRegistry());
+    }
+    const registry = this.extensionRegistryMap.get(type);
+    if (!registry) {
+      return;
+    }
+    registry.register(extension);
+  }
+
+  getAbilityExtension(abilityType: string, extensionKey: string): any {
+    return this.extensionRegistryMap.get(abilityType)?.get(extensionKey);
+  }
+
+  registerAbility(Ability: AbilityClass): void {
+    const ability = new Ability();
+    this.abilityRegistry.set(ability.type, ability);
+  }
+
+  registerAbilities(Abilities: AbilityClass[]): void {
+    Abilities.forEach(this.registerAbility.bind(this));
+  }
+
+  getAbility<ExtendAbility>(type: string): (FormItemAbility & ExtendAbility) | undefined {
+    return this.abilityRegistry.get(type) as FormItemAbility & ExtendAbility;
+  }
+
+  /**
+   * @deprecated
+   * Setter Hoc and setter are no longer supported in NodeEngineV2
+   * @param hoc
+   */
+  registerSetterHoc(hoc: SetterHoc): void {
+    this.setterHocs.push(hoc);
+  }
+
+  fireFormModelWillInit(model: FormModel, data: any) {
+    this.onFormModelWillInitEmitter.fire({
+      model,
+      data,
+    });
+  }
+
+  dispose() {
+    this.onFormModelWillInitEmitter.dispose();
+  }
+
+  @postConstruct()
+  protected init(): void {
+    this.formContributions.forEach((contrib) => contrib.onRegister?.(this));
+  }
+}