@flowgram-vue/form 0.2.0

package/src/core/form-model.ts

@@ -0,0 +1,362 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { flatten, get } from 'lodash-es';
+import { deepEqual } from 'fast-equals';
+import { Disposable, Emitter } from '@flowgram-vue/utils';
+import { ReactiveState } from '@flowgram-vue/reactive';
+
+import { feedbackToFieldErrorsOrWarnings, hasError, toFeedback } from '../utils/validate';
+import { Glob } from '../utils/glob';
+import { keepValidKeys } from '../utils';
+import {
+  FormModelState,
+  FormOptions,
+  FormState,
+  OnFormValuesChangePayload,
+  OnFormValuesInitPayload,
+  OnFormValuesUpdatedPayload,
+} from '../types/form';
+import { FieldName, FieldValue } from '../types/field';
+import { Errors, FeedbackLevel, FormValidateReturn, Validate, Warnings } from '../types';
+import { createFormModelState } from '../constants';
+import { getValidByErrors, mergeFeedbacks } from './utils';
+import { Store } from './store';
+import { Path } from './path';
+import { FieldModel } from './field-model';
+import { FieldArrayModel } from './field-array-model';
+
+export class FormModel<TValues = any> implements Disposable {
+  protected _fieldMap: Map<string, FieldModel> = new Map();
+
+  readonly store = new Store();
+
+  protected _options: FormOptions = {};
+
+  protected onFieldModelCreateEmitter = new Emitter<FieldModel>();
+
+  readonly onFieldModelCreate = this.onFieldModelCreateEmitter.event;
+
+  readonly onFormValuesChangeEmitter = new Emitter<OnFormValuesChangePayload>();
+
+  readonly onFormValuesChange = this.onFormValuesChangeEmitter.event;
+
+  readonly onFormValuesInitEmitter = new Emitter<OnFormValuesInitPayload>();
+
+  readonly onFormValuesInit = this.onFormValuesInitEmitter.event;
+
+  readonly onFormValuesUpdatedEmitter = new Emitter<OnFormValuesUpdatedPayload>();
+
+  readonly onFormValuesUpdated = this.onFormValuesUpdatedEmitter.event;
+
+  readonly onValidateEmitter = new Emitter<FormModelState>();
+
+  readonly onValidate = this.onValidateEmitter.event;
+
+  protected _state: ReactiveState<FormModelState> = new ReactiveState<FormModelState>(
+    createFormModelState()
+  );
+
+  protected _initialized = false;
+
+  set fieldMap(map) {
+    this._fieldMap = map;
+  }
+
+  /**
+   * 表单初始值，初始化设置后不可修改
+   * @protected
+   */
+  // protected _initialValues?: TValues;
+
+  get fieldMap() {
+    return this._fieldMap;
+  }
+
+  get context() {
+    return this._options.context;
+  }
+
+  get initialValues() {
+    return this._options.initialValues;
+  }
+
+  get values() {
+    return this.store.values;
+  }
+
+  set values(v) {
+    const prevValues = this.values;
+    if (deepEqual(prevValues, v)) {
+      return;
+    }
+    this.store.values = v;
+    this.fireOnFormValuesChange({
+      values: this.values,
+      prevValues,
+      name: '',
+    });
+  }
+
+  get validationTrigger() {
+    return this._options.validateTrigger;
+  }
+
+  get state() {
+    return this._state.value;
+  }
+
+  get reactiveState() {
+    return this._state;
+  }
+
+  get fields(): FieldModel[] {
+    return Array.from(this.fieldMap.values());
+  }
+
+  updateState(state: Partial<FormState>) {
+    // todo
+  }
+
+  get initialized() {
+    return this._initialized;
+  }
+
+  fireOnFormValuesChange(payload: OnFormValuesChangePayload) {
+    this.onFormValuesChangeEmitter.fire(payload);
+    this.onFormValuesUpdatedEmitter.fire(payload);
+  }
+
+  fireOnFormValuesInit(payload: OnFormValuesInitPayload) {
+    this.onFormValuesInitEmitter.fire(payload);
+    this.onFormValuesUpdatedEmitter.fire(payload);
+  }
+
+  init(options: FormOptions<TValues>) {
+    this._options = options;
+    if (options.initialValues) {
+      const prevValues = this.store.values;
+      this.store.values = options.initialValues;
+      this.fireOnFormValuesInit({
+        values: options.initialValues,
+        prevValues,
+        name: '',
+      });
+    }
+    this._initialized = true;
+  }
+
+  createField<TValue = FieldValue>(name: FieldName, isArray?: boolean): FieldModel<TValue> {
+    const path = new Path(name);
+    const pathString = path.toString();
+
+    if (this.fieldMap.get(pathString)) {
+      return this.fieldMap.get(pathString)!;
+    }
+
+    // const fieldValue = value || get(this.initialValues, pathString);
+
+    const field: FieldModel = isArray
+      ? new FieldArrayModel(path, this)
+      : new FieldModel(path, this);
+
+    this.fieldMap.set(pathString, field);
+    field.onDispose(() => {
+      this.fieldMap.delete(pathString);
+    });
+    this.onFieldModelCreateEmitter.fire(field);
+
+    return field;
+  }
+
+  createFieldArray<TValue = FieldValue>(
+    name: FieldName,
+    value?: Array<TValue>
+  ): FieldArrayModel<TValue> {
+    return this.createField<Array<TValue>>(name, true) as FieldArrayModel<TValue>;
+  }
+
+  /**
+   * 销毁Field 模型和子模型,但不会删除field的值
+   * @param name
+   */
+  disposeField(name: string) {
+    const field = this.fieldMap.get(name);
+    if (field) {
+      field.dispose();
+    }
+  }
+
+  /**
+   * 删除field, 会删除值和 Field 模型， 以及对应的子模型
+   * @param name
+   */
+  deleteField(name: string) {
+    const field = this.fieldMap.get(name);
+    if (field) {
+      // 销毁值
+      field.clear();
+      // 销毁模型
+      field.dispose();
+    }
+  }
+
+  getField<TFieldModel extends FieldModel | FieldArrayModel = FieldModel>(
+    name: FieldName
+  ): TFieldModel | undefined {
+    return this.fieldMap.get(new Path(name).toString()) as TFieldModel | undefined;
+  }
+
+  getValueIn<TValue>(name: FieldName): TValue {
+    return this.store.getIn<TValue>(new Path(name));
+  }
+
+  setValueIn<TValue>(name: FieldName, value: TValue): void {
+    const prevValues = this.values;
+
+    this.store.setIn(new Path(name), value);
+
+    this.fireOnFormValuesChange({
+      values: this.values,
+      prevValues,
+      name,
+    });
+  }
+
+  setInitValueIn<TValue = any>(name: FieldName, value: TValue): void {
+    const path = new Path(name);
+    const prevValue = this.store.getIn(path);
+    if (prevValue === undefined) {
+      const prevValues = this.values;
+      this.store.setIn(new Path(name), value);
+      this.fireOnFormValuesInit({
+        values: this.values,
+        prevValues,
+        name,
+      });
+    }
+  }
+
+  validateDisabled = false;
+
+  clearValueIn(name: FieldName) {
+    this.setValueIn(name, undefined);
+  }
+
+  async validateIn(name: FieldName) {
+    if (this.validateDisabled) return [];
+    const validateOptions = this.getValidateOptions();
+    if (!validateOptions) {
+      return;
+    }
+
+    const validateKeys = Object.keys(validateOptions).filter((pattern) =>
+      Glob.isMatch(pattern, name)
+    );
+
+    const validatePromises = validateKeys.map(async (validateKey) => {
+      const validate = validateOptions![validateKey];
+
+      return validate({
+        value: this.getValueIn(name),
+        formValues: this.values,
+        context: this.context,
+        name,
+      });
+    });
+
+    return Promise.all(validatePromises);
+  }
+
+  protected getValidateOptions(): Record<string, Validate> | undefined {
+    const validate = this._options.validate;
+    if (typeof validate === 'function') {
+      return validate(this.values, this.context);
+    }
+    return validate;
+  }
+
+  async validate(): Promise<FormValidateReturn> {
+    if (this.validateDisabled) return [];
+    const validateOptions = this.getValidateOptions();
+    if (!validateOptions) {
+      return [];
+    }
+
+    const feedbacksArrPromises = Object.keys(validateOptions).map(async (nameRule) => {
+      const validate = validateOptions![nameRule];
+      const values = this.values;
+      const paths = Glob.findMatchPathsWithEmptyValue(values, nameRule);
+      return Promise.all(
+        paths.map(async (path) => {
+          const result = await validate({
+            value: get(values, path),
+            formValues: values,
+            context: this.context,
+            name: path,
+          });
+
+          const feedback = toFeedback(result, path);
+          const field = this.getField(path);
+
+          const errors = feedbackToFieldErrorsOrWarnings<Errors>(
+            path,
+            feedback?.level === FeedbackLevel.Error ? feedback : undefined
+          );
+          const warnings = feedbackToFieldErrorsOrWarnings<Warnings>(
+            path,
+            feedback?.level === FeedbackLevel.Warning ? feedback : undefined
+          );
+
+          if (field) {
+            field.state.errors = errors;
+            field.state.warnings = warnings;
+            field.state.invalid = hasError(errors);
+            field.bubbleState();
+          }
+
+          // 无论是否存在 field 都要保证 form 的state 被更新
+          this.state.errors = mergeFeedbacks(this.state.errors, errors);
+          this.state.warnings = mergeFeedbacks(this.state.warnings, warnings);
+
+          this.state.invalid = !getValidByErrors(this.state.errors);
+          return feedback;
+        })
+      );
+    });
+
+    this.state.isValidating = true;
+    const feedbacksArr = await Promise.all(feedbacksArrPromises);
+    this.state.isValidating = false;
+    this.onValidateEmitter.fire(this.state);
+
+    return flatten(feedbacksArr).filter(Boolean) as FormValidateReturn;
+  }
+
+  alignStateWithFieldMap() {
+    const keys = Array.from(this.fieldMap.keys());
+
+    if (this.state.errors) {
+      this.state.errors = keepValidKeys(this.state.errors, keys);
+    }
+    if (this.state.warnings) {
+      this.state.warnings = keepValidKeys(this.state.warnings, keys);
+    }
+    this.fieldMap.forEach((f) => {
+      if (f.state.errors) {
+        f.state.errors = keepValidKeys(f.state.errors, keys);
+      }
+      if (f.state.warnings) {
+        f.state.warnings = keepValidKeys(f.state.warnings, keys);
+      }
+    });
+  }
+
+  dispose() {
+    this.fieldMap.forEach((f) => f.dispose());
+    this.store.dispose();
+    this._initialized = false;
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export { FormModel } from './form-model';
+export { createForm, type CreateFormOptions } from './create-form';
+export { FieldModel } from './field-model';
+export { FieldArrayModel } from './field-array-model';
+
+export { toField, toFieldState } from './to-field';
+export { toFieldArray } from './to-field-array';
+export { toForm, toFormState } from './to-form';
+export { Path } from './path';

package/src/core/path.ts

@@ -0,0 +1,125 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { toPath } from 'lodash-es';
+
+export class Path {
+  protected _path: string[] = [];
+
+  constructor(path: string | string[]) {
+    this._path = toPath(path);
+  }
+
+  get parent(): Path | undefined {
+    if (this._path.length < 2) {
+      return undefined;
+    }
+    return new Path(this._path.slice(0, -1));
+  }
+
+  toString(): string {
+    return this._path.join('.');
+  }
+
+  get value(): string[] {
+    return this._path;
+  }
+
+  /**
+   * 仅计直系child
+   * @param path
+   */
+  isChild(path: string) {
+    const target = new Path(path).value;
+    const self = this.value;
+
+    if (target.length - self.length !== 1) {
+      return false;
+    }
+
+    for (let i = 0; i < self.length; i++) {
+      if (target[i] !== self[i]) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * 比较两个数组path大小
+   * 返回小于0则path1<path2, 大于0 则path1>path2, 等于0则相等
+   * @param path1
+   * @param path2
+   */
+  static compareArrayPath(path1: Path, path2: Path): number | void {
+    let i = 0;
+    while (path1.value[i] && path2.value[i]) {
+      const index1 = parseInt(path1.value[i]);
+      const index2 = parseInt(path2.value[i]);
+
+      if (!isNaN(index1) && !isNaN(index2)) {
+        return index1 - index2;
+      } else if (path1.value[i] !== path2.value[i]) {
+        throw new Error(
+          `[Form] Path.compareArrayPath invalid input Error: two path should refers to the same array, but got path1: ${path1.toString()}, path2: ${path2.toString()}`
+        );
+      }
+      i++;
+    }
+    throw new Error(
+      `[Form] Path.compareArrayPath invalid input Error: got path1: ${path1.toString()}, path2: ${path2.toString()}`
+    );
+  }
+
+  isChildOrGrandChild(path: string) {
+    const target = new Path(path).value;
+    const self = this.value;
+
+    if (target.length - self.length < 1) {
+      return false;
+    }
+
+    for (let i = 0; i < self.length; i++) {
+      if (target[i] !== self[i]) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  getArrayIndex(parent: Path) {
+    return parseInt(this._path[parent.value.length]);
+  }
+
+  concat(name: number | string) {
+    if (typeof name === 'string' || typeof name === 'number') {
+      return new Path(this._path.concat(new Path(name.toString())._path));
+    }
+    throw new Error(
+      `[Form] Error in Path.concat: invalid param type, require number or string, but got ${typeof name}`
+    );
+  }
+
+  replaceParent(parent: Path, newParent: Path) {
+    if (parent.value.length > this.value.length) {
+      throw new Error(
+        `[Form] Error in Path.replaceParent: invalid parent param: ${parent}, parent length should not greater than current length.`
+      );
+    }
+    const rest = [];
+    for (let i = 0; i < this.value.length; i++) {
+      if (i < parent.value.length && parent.value[i] !== this.value[i]) {
+        throw new Error(
+          `[Form] Error in Path.replaceParent: invalid parent param: '${parent}' is not a parent of '${this.toString()}'`
+        );
+      }
+      if (i >= parent.value.length) {
+        rest.push(this.value[i]);
+      }
+    }
+
+    return new Path(newParent.value.concat(rest));
+  }
+}

package/src/core/store.ts

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { get, clone, cloneDeep } from 'lodash-es';
+
+import { shallowSetIn } from '../utils';
+import { FieldValue } from '../types/field';
+import { Path } from './path';
+
+export class Store<TValues = FieldValue> {
+  protected _values: TValues;
+
+  get values(): TValues {
+    return clone(this._values);
+  }
+
+  set values(v) {
+    this._values = cloneDeep(v);
+  }
+
+  setIn<TValue = FieldValue>(path: Path, value: TValue): void {
+    // shallow clone set
+    this._values = shallowSetIn(this._values || {}, path.toString(), value);
+  }
+
+  getIn<TValue = FieldValue>(path: Path): TValue {
+    return get(this.values, path.value);
+  }
+
+  dispose() {}
+}

package/src/core/to-field-array.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Field, FieldArray } from '../types/field';
+import { toField } from './to-field';
+import { FieldArrayModel } from './field-array-model';
+
+export function toFieldArray<TValue>(model: FieldArrayModel<TValue>): FieldArray<TValue> {
+  const res: FieldArray<TValue> = {
+    get key() {
+      return model.id;
+    },
+    get name() {
+      return model.path.toString();
+    },
+    get value() {
+      return model.value;
+    },
+    onChange: (value) => {
+      model.value = value;
+    },
+    map: <T = any>(cb: (f: Field<TValue>, index: number) => T) =>
+      model.map<T>((f, index) => cb(toField(f), index)),
+    append: (value) => toField<TValue>(model.append(value)),
+    /**
+     * @deprecated: use remove instead
+     * @param index
+     */
+    delete: (index: number) => model.delete(index),
+    remove: (index: number) => model.delete(index),
+    swap: (from: number, to: number) => model.swap(from, to),
+    move: (from: number, to: number) => model.move(from, to),
+  } as FieldArray<TValue>;
+
+  // Object.defineProperty(res, 'validate', {
+  //   enumerable: false,
+  //   get() {
+  //     return model.validate.bind(model);
+  //   },
+  // });
+
+  // 隐藏属性
+  Object.defineProperty(res, '_fieldModel', {
+    enumerable: false,
+    get() {
+      return model;
+    },
+  });
+  return res;
+}

package/src/core/to-field.ts

@@ -0,0 +1,80 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { isNativeChangeEvent } from '../utils';
+import { Field, FieldModelState } from '../types/field';
+import { ValidateTrigger } from '../types';
+import { shouldValidate } from './utils';
+import { FieldModel } from './field-model';
+
+export function toField<TValue>(model: FieldModel): Field<TValue> {
+  const res: Field<TValue> = {
+    get name() {
+      return model.name;
+    },
+    get value() {
+      return model.value;
+    },
+    onChange: (e: unknown) => {
+      if (isNativeChangeEvent(e)) {
+        model.value = e.target.type === 'checkbox' ? e.target.checked : e.target.value;
+      } else {
+        model.value = e;
+      }
+    },
+    onBlur() {
+      if (shouldValidate(ValidateTrigger.onBlur, model.form.validationTrigger)) {
+        model.validate();
+      }
+    },
+    onFocus() {
+      model.state.isTouched = true;
+    },
+  } as Field<TValue>;
+
+  Object.defineProperty(res, 'key', {
+    enumerable: false,
+    get() {
+      return model.id;
+    },
+  });
+
+  Object.defineProperty(res, '_fieldModel', {
+    enumerable: false,
+    get() {
+      return model;
+    },
+  });
+  return res;
+}
+
+export function toFieldState(modelState: FieldModelState) {
+  return {
+    get isTouched() {
+      return modelState.isTouched;
+    },
+    get invalid() {
+      return modelState.invalid;
+    },
+    get isDirty() {
+      return modelState.isDirty;
+    },
+    get isValidating() {
+      return modelState.isValidating;
+    },
+    get errors() {
+      if (modelState.errors) {
+        return Object.values(modelState.errors).reduce((acc, arr) => acc.concat(arr), []);
+      }
+      return;
+    },
+    get warnings() {
+      if (modelState.warnings) {
+        return Object.values(modelState.warnings).reduce((acc, arr) => acc.concat(arr), []);
+      }
+      return;
+    },
+  };
+}