@flowgram-vue/form 0.2.0

package/src/utils/event.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Emitter } from '@flowgram-vue/utils';
+
+interface Payload<T> {
+  origin?: T;
+  current?: T;
+}
+
+export class EmitterChain<T> {
+  protected emitter: Emitter<Payload<T>>;
+
+  constructor() {
+    this.emitter = new Emitter<Payload<T>>();
+  }
+
+  get event() {
+    return this.emitter.event;
+  }
+
+  _fire(current?: T, origin?: T) {
+    this.emitter.fire({ current, origin });
+  }
+
+  fire(current: T, next?: EmitterChain<T>) {
+    this._fire(current);
+    next?._fire(undefined, current);
+  }
+}

package/src/utils/glob.ts

@@ -0,0 +1,279 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { flatten, get, isArray, isObject } from 'lodash-es';
+
+export namespace Glob {
+  export const DIVIDER = '.';
+  export const ALL = '*';
+
+  // 仅支持一个通配符
+  export function isMatch(pattern: string, path: string) {
+    const patternArr = pattern.split(DIVIDER);
+    const pathArr = path.split(DIVIDER);
+    if (patternArr.length !== pathArr.length) {
+      return false;
+    }
+    return patternArr.every((pattern, index) => {
+      if (pattern === ALL) {
+        return true;
+      }
+      return pattern === pathArr[index];
+    });
+  }
+
+  /**
+   * 判断pattern 是否match pattern 或其parent
+   * @param pattern
+   * @param path
+   */
+  export function isMatchOrParent(pattern: string, path: string) {
+    if (pattern === '') {
+      return true;
+    }
+    const patternArr = pattern.split(DIVIDER);
+    const pathArr = path.split(DIVIDER);
+
+    if (patternArr.length > pathArr.length) {
+      return false;
+    }
+
+    for (let i = 0; i < patternArr.length; i++) {
+      if (patternArr[i] !== ALL && patternArr[i] !== pathArr[i]) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * 从 path 中提取出匹配pattern 的 parent path，包括是 path 自身
+   * 该方法默认 isMatchOrParent(pattern, path) 为 true, 不做为false 的错误处理。
+   * @param pattern
+   * @param path
+   */
+  export function getParentPathByPattern(pattern: string, path: string) {
+    const patternArr = pattern.split(DIVIDER);
+    const pathArr = path.split(DIVIDER);
+
+    return pathArr.slice(0, patternArr.length).join(DIVIDER);
+  }
+
+  function concatPath(p1: string | number, ...pathArr: (string | number)[]): string {
+    const p2 = pathArr.shift();
+    if (p2 === undefined) return p1.toString();
+    let resultPath = '';
+    if (p1 === '' && p2 === '') {
+      resultPath = '';
+    } else if (p1 !== '' && p2 === '') {
+      resultPath = p1.toString();
+    } else if (p1 === '' && p2 !== '') {
+      resultPath = p2.toString();
+    } else {
+      resultPath = `${p1}${DIVIDER}${p2}`;
+    }
+    if (pathArr.length > 0) {
+      return concatPath(resultPath, ...pathArr);
+    }
+    return resultPath;
+  }
+
+  /**
+   * 找到 obj 在给与 paths 下所有子path
+   * @param paths
+   * @param obj
+   * @private
+   */
+  export function getSubPaths(paths: string[], obj: any): string[] {
+    if (!obj || typeof obj !== 'object') {
+      return [];
+    }
+
+    return flatten(
+      paths.map((path) => {
+        const value = path === '' ? obj : get(obj, path);
+        if (isArray(value)) {
+          return value.map((_: any, index: number) => concatPath(path, index));
+        } else if (isObject(value)) {
+          return Object.keys(value).map((key) => concatPath(path, key));
+        }
+        return [];
+      })
+    );
+  }
+
+  /**
+   * 将带有通配符的 path pattern 分割。如 a.b.*.c.*.d, 会被分割成['a.b','*','c','*','d']
+   * @param pattern
+   * @private
+   */
+  export function splitPattern(pattern: string): string[] {
+    const parts = pattern.split(DIVIDER);
+    const res: string[] = [];
+
+    let i = 0;
+    let curPath: string[] = [];
+
+    while (i < parts.length) {
+      if (parts[i] === ALL) {
+        if (curPath.length) {
+          res.push(curPath.join(DIVIDER));
+        }
+        res.push(ALL);
+        curPath = [];
+      } else {
+        curPath.push(parts[i]);
+      }
+      i += 1;
+    }
+    if (curPath.length) {
+      res.push(curPath.join(DIVIDER));
+    }
+    return res;
+  }
+
+  /**
+   * Find all paths matched pattern in object. If withEmptyValue is true, it will include
+   * paths  whoes value is undefined.
+   * @param obj
+   * @param pattern
+   * @param withEmptyValue
+   */
+
+  export function findMatchPaths(obj: any, pattern: string, withEmptyValue?: boolean): string[] {
+    if (!obj || !pattern) {
+      return [];
+    }
+    const nextPaths: string[] = pattern.split(DIVIDER);
+    let curKey: string | undefined = nextPaths.shift();
+    let curPaths: string[] = [];
+    let curValue = obj;
+    while (curKey) {
+      let isObject = typeof curValue === 'object' && curValue !== null;
+      if (!isObject) return [];
+      // 匹配 *
+      if (curKey === ALL) {
+        const parentPath = curPaths.join(DIVIDER);
+        return flatten(
+          Object.keys(curValue).map((key) => {
+            if (nextPaths.length === 0) {
+              return concatPath(parentPath, key);
+            }
+            return findMatchPaths(curValue[key], `${nextPaths.join(DIVIDER)}`, withEmptyValue).map(
+              (p) => concatPath(parentPath, key, p)
+            );
+          })
+        );
+      }
+      // 找不到对应 key 则不匹配
+      if (!(curKey in curValue) && !withEmptyValue) {
+        return [];
+      }
+      curValue = curValue[curKey!];
+      curPaths.push(curKey);
+      curKey = nextPaths.shift();
+    }
+
+    return [pattern];
+
+    // const parts = splitPattern(pattern);
+    //
+    // let prePaths: string[] = [''];
+    // let curPath: string = '';
+    //
+    // for (let i in parts) {
+    //   const part = parts[i];
+    //   if (part === ALL) {
+    //     prePaths = getSubPaths(
+    //       prePaths.map(p => concatPath(p, curPath)),
+    //       obj,
+    //     );
+    //     curPath = '';
+    //   } else {
+    //     curPath = part;
+    //
+    //     /**
+    //      * 过滤掉后续path 值不存在的prePath
+    //      * 为什么： prePaths 是返回前一个通配符下所有的路径，但每个路径下的数据的field 可能不同
+    //      * 这会导致一些prePath 不存在后面所需的路径。如以下场景
+    //      * const obj = {
+    //      *   a: { b: { c: 1 } },
+    //      *   x: { y: { z: 2 } },
+    //      * };
+    //      * expect(Glob.findMatchPaths(obj, '*.y')).toEqual(['x.y']);
+    //      */
+    //
+    //     prePaths = prePaths.filter(p => {
+    //       const preValue = p ? get(obj, p) : obj;
+    //       if (typeof preValue === 'object') {
+    //         return curPath in preValue;
+    //       }
+    //       return true;
+    //     });
+    //   }
+    // }
+    //
+    // if (curPath) {
+    //   return prePaths.map(p => [p, curPath].join(DIVIDER));
+    // }
+    // return prePaths;
+  }
+
+  /**
+   * Find all paths matched pattern in object, including paths  whoes value is undefined.
+   * @param obj
+   * @param pattern
+   */
+  export function findMatchPathsWithEmptyValue(obj: any, pattern: string): string[] {
+    if (!pattern.includes('*')) {
+      return [pattern];
+    }
+    return findMatchPaths(obj, pattern, true);
+  }
+
+  // export function findMatchPathsWithEmptyValue(obj: any, pattern: string) {
+  //   const parts = splitPattern(pattern);
+  //
+  //   let prePaths: string[] = [''];
+  //   let curPath: string = '';
+  //
+  //   for (let i in parts) {
+  //     const part = parts[i];
+  //     if (part === ALL) {
+  //       prePaths = getSubPaths(
+  //         prePaths.map(p => concatPath(p, curPath)),
+  //         obj,
+  //       );
+  //       curPath = '';
+  //     } else {
+  //       curPath = part;
+  //
+  //       /**
+  //        * 过滤掉后续path 值不存在的prePath
+  //        * 为什么： prePaths 是返回前一个通配符下所有的路径，但每个路径下的数据的field 可能不同
+  //        * 这会导致一些prePath 不存在后面所需的路径。如以下场景
+  //        * const obj = {
+  //        *   a: { b: { c: 1 } },
+  //        *   x: { y: { z: 2 } },
+  //        * };
+  //        * expect(Glob.findMatchPaths(obj, '*.y')).toEqual(['x.y']);
+  //        */
+  //
+  //       // prePaths = prePaths.filter(p => {
+  //       //   const preValue = p ? get(obj, p) : obj;
+  //       //   if (typeof preValue === 'object') {
+  //       //     return curPath in preValue;
+  //       //   }
+  //       //   return true;
+  //       // });
+  //     }
+  //   }
+  //
+  //   if (curPath) {
+  //     return prePaths.map(p => [p, curPath].join(DIVIDER));
+  //   }
+  //   return prePaths;
+  // }
+}

package/src/utils/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './object';
+export * from './dom';
+export * from './glob';

package/src/utils/object.ts

@@ -0,0 +1,107 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { clone, toPath } from 'lodash-es';
+
+/**
+ * These functions are copied from Formik.
+ * @see https://github.com/jaredpalmer/formik
+ */
+
+export const isEmptyArray = (value?: any) => Array.isArray(value) && value.length === 0;
+
+/** @private is the given object a Function? */
+export const isFunction = (obj: any): obj is Function => typeof obj === 'function';
+
+/** @private is the given object an Object? */
+export const isObject = (obj: any): obj is Object => obj !== null && typeof obj === 'object';
+
+/** @private is the given object an integer? */
+export const isInteger = (obj: any): boolean => String(Math.floor(Number(obj))) === obj;
+
+/** @private is the given object a string? */
+export const isString = (obj: any): obj is string =>
+  Object.prototype.toString.call(obj) === '[object String]';
+
+/** @private is the given object a NaN? */
+// eslint-disable-next-line no-self-compare
+export const isNaN = (obj: any): boolean => obj !== obj;
+
+/** @private is the given object/value a promise? */
+export const isPromise = (value: any): value is PromiseLike<any> =>
+  isObject(value) && isFunction(value.then);
+
+/**
+ * Deeply get a value from an object via its path.
+ */
+export function getIn(obj: any, key: string | string[], def?: any, p: number = 0) {
+  const path = toPath(key);
+  while (obj && p < path.length) {
+    obj = obj[path[p++]];
+  }
+
+  // check if path is not in the end
+  if (p !== path.length && !obj) {
+    return def;
+  }
+
+  return obj === undefined ? def : obj;
+}
+
+/**
+ * Deeply set a value from in object via its path. If the value at `path`
+ * has changed, return a shallow copy of obj with `value` set at `path`.
+ * If `value` has not changed, return the original `obj`.
+ *
+ * Existing objects / arrays along `path` are also shallow copied. Sibling
+ * objects along path retain the same internal js reference. Since new
+ * objects / arrays are only created along `path`, we can test if anything
+ * changed in a nested structure by comparing the object's reference in
+ * the old and new object, similar to how russian doll cache invalidation
+ * works.
+ */
+export function shallowSetIn(obj: any, path: string, value: any): any {
+  let res: any = clone(obj); // this keeps inheritance when obj is a class
+  let resVal: any = res;
+  let i = 0;
+  let pathArray = toPath(path);
+
+  for (; i < pathArray.length - 1; i++) {
+    const currentPath: string = pathArray[i];
+    let currentObj: any = getIn(obj, pathArray.slice(0, i + 1));
+
+    if (currentObj && (isObject(currentObj) || Array.isArray(currentObj))) {
+      resVal = resVal[currentPath] = clone(currentObj);
+    } else {
+      const nextPath: string = pathArray[i + 1];
+      resVal = resVal[currentPath] = isInteger(nextPath) && Number(nextPath) >= 0 ? [] : {};
+    }
+  }
+
+  // Return original object if new value is the same as current
+  //  `pathArray[i] in obj` is to supoort set undefined value with unknown key
+  if ((i === 0 ? obj : resVal)[pathArray[i]] === value && pathArray[i] in obj) {
+    return obj;
+  }
+
+  /**
+   * In Formik, they delete the key if the value is undefined. but here we keep the key with the undefined value.
+   * The reason that Formik tackle in this way is to fix the issue https://github.com/jaredpalmer/formik/issues/727
+   * Their fix is https://github.com/jaredpalmer/formik/issues/727, and we roll back to the code before this PR.
+   */
+  resVal[pathArray[i]] = value;
+  return res;
+}
+
+export function keepValidKeys(obj: Record<string, any>, validKeys: string[]) {
+  const validKeysSet = new Set(validKeys);
+  const newObj: Record<string, any> = {};
+  Object.keys(obj).forEach((key) => {
+    if (validKeysSet.has(key)) {
+      newObj[key] = obj[key];
+    }
+  });
+  return newObj;
+}

package/src/utils/validate.ts

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import {
+  Errors,
+  Feedback,
+  FeedbackLevel,
+  FieldError,
+  FieldName,
+  FieldWarning,
+  FormErrorOptions,
+  FormWarningOptions,
+} from '../types';
+
+export function toFeedback(
+  result: string | FormErrorOptions | FormWarningOptions | undefined,
+  name: FieldName
+): FieldError | FieldWarning | undefined {
+  if (typeof result === 'string') {
+    return {
+      name,
+      message: result,
+      level: FeedbackLevel.Error,
+    };
+  } else if (result?.message) {
+    return {
+      ...result,
+      name,
+    };
+  }
+}
+
+export function feedbackToFieldErrorsOrWarnings<T>(name: string, feedback?: Feedback<any>) {
+  return {
+    [name]: feedback ? [feedback] : [],
+  } as T;
+}
+
+export const hasError = (errors: Errors) =>
+  Object.keys(errors).some((key) => errors[key]?.length > 0);

package/src/vue/context.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { InjectionKey } from 'vue';
+
+import type { FieldModel } from '../core/field-model';
+import type { FormModel } from '../core/form-model';
+
+export const FormModelKey: InjectionKey<FormModel> = Symbol('FormModel');
+export const FieldModelKey: InjectionKey<FieldModel> = Symbol('FieldModel');

package/src/vue/field-array.vue

@@ -0,0 +1,117 @@
+<script lang="ts">
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+import { defineComponent, h, onBeforeUnmount, provide, type PropType, type VNode } from 'vue';
+import { isFunction } from 'lodash-es';
+import { DisposableCollection, useRefresh } from '@flowgram-vue/utils';
+import { useReadonlyReactiveState } from '@flowgram-vue/reactive';
+
+import {
+  FieldArrayRenderProps,
+  FieldModelState,
+  FieldName,
+  FieldValue,
+} from '../types/field';
+import { FormModelState } from '../types';
+import { toFieldArray } from '../core/to-field-array';
+import { FieldArrayModel } from '../core/field-array-model';
+import { toFieldState, toFormState } from '../core';
+import { useFormModel } from '../composables/use-form-model';
+import { FieldModelKey } from './context';
+
+export default defineComponent({
+  name: 'FieldArray',
+  props: {
+    name: { type: String, required: true },
+    defaultValue: { type: Array, default: undefined },
+    render: {
+      type: Function as PropType<(props: FieldArrayRenderProps<any>) => VNode>,
+      default: undefined,
+    },
+    deps: { type: Array as PropType<FieldName[]>, default: undefined },
+  },
+  setup(props, { slots }) {
+    const formModel = useFormModel();
+    const fieldModel =
+      formModel.getField<FieldArrayModel<FieldValue>>(props.name) ||
+      (formModel.createFieldArray(props.name) as FieldArrayModel<any>);
+
+    const field = toFieldArray(fieldModel);
+    const refresh = useRefresh();
+
+    const fieldModelState = useReadonlyReactiveState<FieldModelState>(fieldModel.reactiveState);
+    const formModelState = useReadonlyReactiveState<FormModelState>(formModel.reactiveState);
+    const fieldState = toFieldState(fieldModelState);
+    const formState = toFormState(formModelState);
+
+    const bind = () => {
+      if (fieldModel.disposed) {
+        refresh();
+        return () => {};
+      }
+      fieldModel.renderCount = fieldModel.renderCount + 1;
+
+      if (!formModel.getValueIn(props.name) !== undefined && props.defaultValue !== undefined) {
+        formModel.setInitValueIn(props.name, props.defaultValue);
+        refresh();
+      }
+
+      const disposableCollection = new DisposableCollection();
+
+      disposableCollection.push(
+        fieldModel.onValueChange(() => {
+          refresh();
+        })
+      );
+
+      if (props.deps) {
+        props.deps.forEach((dep) => {
+          const disposable = formModel.getField(dep)?.onValueChange(() => {
+            refresh();
+          });
+          if (disposable) {
+            disposableCollection.push(disposable);
+          }
+        });
+      }
+
+      return () => {
+        disposableCollection.dispose();
+
+        if (fieldModel.renderCount > 1) {
+          fieldModel.renderCount = fieldModel.renderCount - 1;
+        } else {
+          const newFieldModel = formModel.getField(fieldModel.name);
+          if (newFieldModel === fieldModel) fieldModel.dispose();
+        }
+      };
+    };
+
+    const unbind = bind();
+    onBeforeUnmount(unbind);
+
+    provide(FieldModelKey, fieldModel);
+
+    return () => {
+      if (fieldModel.disposed) {
+        return null;
+      }
+
+      const slotProps: FieldArrayRenderProps<any> = { field, fieldState, formState };
+
+      if (props.render && isFunction(props.render)) {
+        return props.render(slotProps);
+      }
+
+      const slot = slots.default;
+      if (isFunction(slot)) {
+        return slot(slotProps);
+      }
+
+      return h('span', 'Invalid Array render');
+    };
+  },
+});
+</script>