@flowgram-vue/form 0.2.0

package/src/core/to-form.ts

@@ -0,0 +1,64 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { Form, FormModelState, FormState } from '../types/form';
+import { FieldName, FieldValue } from '../types/field';
+import { FormModel } from './form-model';
+
+export function toForm<TValue>(model: FormModel): Form<TValue> {
+  const res = {
+    initialValues: model.initialValues,
+    get values() {
+      return model.values;
+    },
+    set values(v) {
+      model.values = v;
+    },
+    state: toFormState(model.state),
+    getValueIn: <TValue = FieldValue>(name: FieldName) => model.getValueIn(name),
+    setValueIn: <TValue>(name: FieldName, value: TValue) => model.setValueIn(name, value),
+    validate: model.validate.bind(model),
+  };
+
+  Object.defineProperty(res, '_formModel', {
+    enumerable: false,
+    get() {
+      return model;
+    },
+  });
+  return res as Form<TValue>;
+}
+
+export function toFormState(modelState: FormModelState): FormState {
+  return {
+    get isTouched() {
+      return modelState.isTouched;
+    },
+    get invalid() {
+      return modelState.invalid;
+    },
+    get isDirty() {
+      return modelState.isDirty;
+    },
+    get isValidating() {
+      return modelState.isValidating;
+    },
+    // get dirtyFields() {
+    //   return modelState.dirtyFields;
+    // },
+    // get isLoading() {
+    //   return modelState.isLoading;
+    // },
+    // get touchedFields() {
+    //   return modelState.touchedFields;
+    // },
+    get errors() {
+      return modelState.errors;
+    },
+    get warnings() {
+      return modelState.warnings;
+    },
+  };
+}

package/src/core/utils.ts

@@ -0,0 +1,123 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { isEmpty, isEqual } from 'lodash-es';
+
+import { Glob } from '../utils';
+import { Errors, Feedback, OnFormValuesChangePayload, ValidateTrigger, Warnings } from '../types';
+import { Path } from './path';
+
+export function updateFeedbacksName(feedbacks: Feedback<any>[], name: string) {
+  return (feedbacks || []).map((f) => ({
+    ...f,
+    name,
+  }));
+}
+
+export function mergeFeedbacks<T extends Errors | Warnings>(origin?: T, source?: T) {
+  if (!source) {
+    return origin;
+  }
+  if (!origin) {
+    return { ...source };
+  }
+  const changed = Object.keys(source).some(
+    (sourceKey) => !isEqual(origin[sourceKey], source[sourceKey])
+  );
+
+  if (changed) {
+    return {
+      ...origin,
+      ...source,
+    };
+  }
+  return origin;
+}
+
+export function clearFeedbacks<T extends Errors | Warnings>(name: string, origin?: T) {
+  if (!origin) {
+    return origin;
+  }
+  if (name in origin) {
+    delete origin[name];
+  }
+  return origin;
+}
+
+export function shouldValidate(currentTrigger: ValidateTrigger, formTrigger?: ValidateTrigger) {
+  return currentTrigger === formTrigger;
+}
+
+export function getValidByErrors(errors: Errors | undefined) {
+  return errors ? Object.keys(errors).every((name) => isEmpty(errors[name])) : true;
+}
+
+export namespace FieldEventUtils {
+  export function shouldTriggerFieldChangeEvent(
+    payload: OnFormValuesChangePayload,
+    fieldName: string
+  ) {
+    const { name: changedName, options } = payload;
+
+    // 如果 Field 是 变更path 的 ancestor 则触发
+    if (Glob.isMatchOrParent(fieldName, changedName)) {
+      return true;
+    }
+
+    // 如果 Field 是 变更path 的 child 或 grandchild 有条件触发
+    if (new Path(changedName).isChildOrGrandChild(fieldName)) {
+      // 数组情况下部分子项不触发变更
+
+      // 1. 数组 append 触发的FormValuesChange 不需要触发其子 Field 的 onValueChange
+      if (options?.action === 'array-append') {
+        return !new Path(changedName).isChildOrGrandChild(fieldName);
+      }
+      // 2. 数组 splice 触发的FormValuesChange 无需触发第一个删除项前的所有子  Field 的 onValueChange
+      else if (options?.action === 'array-splice' && options?.indexes?.length) {
+        return (
+          (Path.compareArrayPath(
+            new Path(fieldName),
+            new Path(changedName).concat(options.indexes[0])
+          ) as number) >= 0
+        );
+      }
+
+      // 其余情况都需要触发
+      return true;
+    }
+    return false;
+  }
+
+  export function shouldTriggerFieldValidateWhenChange(
+    payload: OnFormValuesChangePayload,
+    fieldName: string
+  ) {
+    const { name: changedName, options } = payload;
+
+    if (options?.action === 'array-splice' || options?.action === 'array-swap') {
+      // const splicedIndexes = options?.indexes || [];
+      //
+      // const splicedPaths = splicedIndexes.map(index => new Path(changedName).concat(index));
+      // const removedPaths = Array.from({ length: splicedIndexes.length }, (_, i) =>
+      //   new Path(changedName).concat(prevValues[changedName].length - i - 1),
+      // );
+      //
+      // const ignoredPathOrParentPaths = [...splicedPaths, ...removedPaths];
+      // // const ignoredPathOrParentPaths = splicedPaths;
+      // if (
+      //   ignoredPathOrParentPaths.some(
+      //     path => path.toString() === fieldName || path.isChildOrGrandChild(fieldName),
+      //   )
+      // ) {
+      //   return false;
+      // }
+
+      // splice 和 swap 都属于数组跟级别的变更，仅需触发数组field的校验, 无需校验子项
+      return fieldName === changedName;
+    }
+
+    return FieldEventUtils.shouldTriggerFieldChangeEvent(payload, fieldName);
+  }
+}

package/src/env.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue';
+  const component: DefineComponent<object, object, unknown>;
+  export default component;
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './vue';
+export type {
+  FormRenderProps,
+  FieldRenderProps,
+  FieldArrayRenderProps,
+  FieldState,
+  FormState,
+  Validate,
+  FormControl,
+  FieldName,
+  FieldError,
+  FieldWarning,
+  FormValidateReturn,
+  FieldValue,
+  FieldArray as IFieldArray,
+  Field as IField,
+  Form as IForm,
+  Errors,
+  Warnings,
+} from './types';
+
+export { ValidateTrigger, FeedbackLevel } from './types';
+export { createForm, type CreateFormOptions } from './core/create-form';
+export { Glob } from './utils';
+export * from './core';

package/src/types/common.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export type Context = any;

package/src/types/field.ts

@@ -0,0 +1,193 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { VNode } from 'vue';
+
+import { Errors, FieldError, FieldWarning, Warnings } from './validate';
+import { FormState } from './form';
+
+export type NativeFieldValue = string | number | boolean | null | undefined | unknown[];
+
+export type FieldValue = any;
+export type FieldArrayValue = Array<any> | undefined;
+export type FieldName = string;
+
+export type CustomElement = Partial<HTMLElement> & {
+  name: FieldName;
+  type?: string;
+  value?: any;
+  disabled?: boolean;
+  checked?: boolean;
+  options?: HTMLOptionsCollection;
+  files?: FileList | null;
+  focus?: () => void;
+};
+
+export type FieldElement =
+  | HTMLInputElement
+  | HTMLSelectElement
+  | HTMLTextAreaElement
+  | CustomElement;
+
+export type Ref = FieldElement;
+
+/**
+ * Field render model, it's only available when Field is rendered
+ */
+export interface Field<
+  TFieldValue extends FieldValue = FieldValue,
+  E = Event | TFieldValue
+> {
+  /**
+   * Uniq key for the Field, you can use it for the child Vue component's uniq key.
+   */
+  key: string;
+  /**
+   * A function which sends the input's value to Field.
+   * It should be assigned to the onChange prop of the input component
+   * @param e It can be the new value of the field or the event sent by original dom input or checkbox component.
+   */
+  onChange: (e: E) => void;
+  /**
+   * The current value of Field
+   */
+  value: TFieldValue;
+  /**
+   * Field's name (path)
+   */
+  name: FieldName;
+  /**
+   * A function which sends the input's onFocus event to Field. It should be assigned to the input's onFocus prop.
+   */
+  onFocus?: () => void;
+  /**
+   * A function which sends the input's onBlur event to Field. It should be assigned to the input's onBlur prop.
+   */
+  onBlur?: () => void;
+}
+
+/**
+ * FieldArray render model, it's only available when FieldArray is rendered
+ */
+export interface FieldArray<TFieldValue extends FieldValue = FieldValue>
+  extends Field<Array<TFieldValue> | undefined, Array<TFieldValue> | undefined> {
+  /**
+   * Same as native Array.map, the first param of the callback function is the child field of this FieldArray.
+   * @param cb callback function
+   */
+  map: <T = any>(cb: (f: Field<TFieldValue>, index: number) => T) => T[];
+  /**
+   * Append a value at the end of the array, it will create a new Field for this value as well.
+   * @param value the value to append
+   */
+  append: (value: TFieldValue) => Field<TFieldValue>;
+  /**
+   * @deprecated use remove instead
+   * Delete the value and the related field at certain index of the array.
+   * @param index the index of the element to delete
+   */
+  delete: (index: number) => void;
+  /**
+   * Delete the value and the related field at certain index of the array.
+   * @param index the index of the element to delete
+   */
+  remove: (index: number) => void;
+  /**
+   * Move an array element from one position to another.
+   * @param from from position
+   * @param to to position
+   */
+  move: (from: number, to: number) => void;
+  /**
+   * Swap the position of two elements of the array.
+   * @param from
+   * @param to
+   */
+  swap: (from: number, to: number) => void;
+}
+
+export interface FieldOptions<TValue, TFormValues = any> {
+  /**
+   * Field's name(path), it should be uniq within a form instance.
+   * Two Fields Rendered with the same name will link to the same part of data and field status such as errors is shared.
+   */
+  name: FieldName;
+  /**
+   * Default value of the field. Please notice that Field is a render model, so this default value will only be set when
+   * the field is rendered. If you want to give a default value before field rendering, please set it in the Form's defaultValue.
+   */
+  defaultValue?: TValue;
+  /**
+   * This is a render prop. A function that returns a Vue VNode and provides the ability to attach events and value into the component.
+   * This simplifies integrating with external controlled components with non-standard prop names. Provides field、fieldState and formState, to the child component.
+   * @param props
+   */
+  render?: (props: FieldRenderProps<TValue>) => VNode;
+}
+
+export interface FieldRenderProps<TValue> {
+  field: Field<TValue>;
+  fieldState: Readonly<FieldState>;
+  formState: Readonly<FormState>;
+}
+
+export interface FieldArrayOptions<TValue> {
+  /**
+   * Field's name(path), it should be uniq within a form instance.
+   * Two Fields Rendered with the same name will link to the same part of data and field status such as errors is shared.
+   */
+  name: FieldName;
+  /**
+   * Default value of the field. Please notice that Field is a render model, so this default value will only be set when
+   * the field is rendered. If you want to give a default value before field rendering, please set it in the Form's initialValues.
+   */
+  defaultValue?: TValue[];
+  /**
+   * This is a render prop. A function that returns a Vue VNode and provides the ability to attach events and value into the component.
+   * This simplifies integrating with external controlled components with non-standard prop names. Provides field、fieldState and formState, to the child component.
+   * @param props
+   */
+  render?: (props: FieldArrayRenderProps<TValue>) => VNode;
+}
+
+export interface FieldArrayRenderProps<TValue> {
+  field: FieldArray<TValue>;
+  fieldState: Readonly<FieldState>;
+  formState: Readonly<FormState>;
+}
+
+export interface UseFieldReturn {}
+
+export interface FieldState {
+  /**
+   * If field value is invalid
+   */
+  invalid: boolean;
+  /**
+   * If field input component is touched by user
+   */
+  isTouched: boolean;
+  /**
+   * If field current value is different from the initialValue.
+   */
+  isDirty: boolean;
+  /**
+   * If field is validating.
+   */
+  isValidating: boolean;
+  /**
+   * Field errors, empty array means there is no errors.
+   */
+  errors?: FieldError[];
+  /**
+   * Field warnings, empty array means there is no warnings.
+   */
+  warnings?: FieldWarning[];
+}
+
+export interface FieldModelState extends Omit<FieldState, 'errors' | 'warnings'> {
+  errors?: Errors;
+  warnings?: Warnings;
+}

package/src/types/form.ts

@@ -0,0 +1,145 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { FormModel } from '../core/form-model';
+import { Errors, FormValidateReturn, Validate, ValidateTrigger, Warnings } from './validate';
+import { Field, FieldArray, FieldName, FieldValue } from './field';
+import { Context } from './common';
+
+export interface FormState {
+  // isLoading: boolean;
+  /**
+   * If the form data is valid
+   */
+  invalid: boolean;
+  /**
+   * If the form data is different from the intialValues
+   */
+  isDirty: boolean;
+  /**
+   * If the form fields have been touched
+   */
+  isTouched: boolean;
+  /**
+   * If the form is during validation
+   */
+  isValidating: boolean;
+  /**
+   * Form errors
+   */
+  errors?: Errors;
+  /**
+   * Form warnings
+   */
+  warnings?: Warnings;
+}
+
+export interface FormModelState extends Omit<FormState, 'errors' | 'warnings'> {
+  errors?: Errors;
+  warnings?: Warnings;
+}
+
+export interface FormOptions<TValues = any> {
+  /**
+   * InitialValues of the form.
+   */
+  initialValues?: TValues;
+  /**
+   * When should the validation trigger, for example onChange or onBlur.
+   */
+  validateTrigger?: ValidateTrigger;
+  /**
+   * Form data's validation rules. It's a key value map, where the key is a pattern of data's path (or field name), the value is a validate function.
+   */
+  validate?:
+    | Record<string, Validate>
+    | ((value: TValues, ctx: Context) => Record<string, Validate>);
+  /**
+   * Custom context. It will be accessible via form instance or in validate function.
+   */
+  context?: Context;
+}
+
+export interface Form<TValues = any> {
+  /**
+   * The initialValues of the form.
+   */
+  initialValues: TValues;
+  /**
+   * Form values. Returns a deep copy of the data in the store.
+   */
+  values: TValues;
+  /**
+   * Form state
+   */
+  state: FormState;
+
+  /**
+   * Get value in certain path
+   * @param name path
+   */
+  getValueIn<TValue = FieldValue>(name: FieldName): TValue;
+
+  /**
+   * Set value in certain path.
+   * It will trigger the re-rendering of the Field Component if a Field is related to this path
+   * @param name path
+   */
+  setValueIn<TValue>(name: FieldName, value: TValue): void;
+
+  /**
+   * Trigger validate for the whole form.
+   */
+  validate: () => Promise<FormValidateReturn>;
+}
+
+export interface FormRenderProps<TValues> {
+  /**
+   * Form instance.
+   */
+  form: Form<TValues>;
+}
+
+export interface FormControl<TValues> {
+  _formModel: FormModel<TValues>;
+  getField: <
+    TValue = FieldValue,
+    TField extends Field<TValue> | FieldArray<TValue> = Field<TValue>
+  >(
+    name: FieldName
+  ) => Field<TValue> | FieldArray<TValue> | undefined;
+  /** 手动初始化form */
+  init: () => void;
+}
+
+export interface CreateFormReturn<TValues> {
+  form: Form<TValues>;
+  control: FormControl<TValues>;
+}
+
+export interface OnFormValuesChangeOptions {
+  action?: 'array-append' | 'array-splice' | 'array-swap';
+  indexes?: number[];
+}
+
+export interface OnFormValuesChangePayload {
+  values: FieldValue;
+  prevValues: FieldValue;
+  name: FieldName;
+  options?: OnFormValuesChangeOptions;
+}
+
+export interface OnFormValuesInitPayload {
+  values: FieldValue;
+  prevValues: FieldValue;
+  name: FieldName;
+}
+
+export interface OnFormValuesUpdatedPayload {
+  values: FieldValue;
+  prevValues: FieldValue;
+  name: FieldName;
+  options?: OnFormValuesChangeOptions;
+}

package/src/types/index.ts

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

package/src/types/validate.ts

@@ -0,0 +1,88 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { VNode } from 'vue';
+import { MaybePromise } from '@flowgram-vue/utils';
+
+import { FieldName } from './field';
+import { Context } from './common';
+
+export enum FeedbackLevel {
+  Error = 'error',
+  Warning = 'warning',
+}
+
+export interface Feedback<FeedbackLevel> {
+  /**
+   * The data path (or field path) that generate this feedback
+   */
+  name: string;
+  /**
+   * The type of the feedback
+   */
+  type?: string;
+  /**
+   * Feedback level
+   */
+  level: FeedbackLevel;
+  /**
+   * Feedback message
+   */
+  message: string | VNode;
+}
+
+export type FieldError = Feedback<FeedbackLevel.Error>;
+export type FieldWarning = Feedback<FeedbackLevel.Warning>;
+
+export type FormErrorOptions = Omit<FieldError, 'name'>;
+export type FormWarningOptions = Omit<FieldWarning, 'name'>;
+export type FeedbackOptions<FeedbackLevel> = Omit<Feedback<FeedbackLevel>, 'name'>;
+
+export type Validate<TFieldValue = any, TFormValues = any> = (props: {
+  /**
+   * Value of the data to validate
+   */
+  value: TFieldValue;
+  /**
+   * Complete form values
+   */
+  formValues: TFormValues;
+  /**
+   * The path of the data we are validating
+   */
+  name: FieldName;
+  /**
+   * The custom context set when init form
+   */
+  context: Context;
+}) =>
+  | MaybePromise<string>
+  | MaybePromise<FormErrorOptions>
+  | MaybePromise<FormWarningOptions>
+  | MaybePromise<undefined>;
+
+export function isFieldError(f: Feedback<any>): f is FieldError {
+  if (f.level === FeedbackLevel.Error) {
+    return true;
+  }
+  return false;
+}
+
+export function isFieldWarning(f: Feedback<any>): f is FieldWarning {
+  if (f.level === FeedbackLevel.Warning) {
+    return true;
+  }
+  return false;
+}
+
+export type Errors = Record<FieldName, FieldError[]>;
+export type Warnings = Record<FieldName, FieldWarning[]>;
+
+export enum ValidateTrigger {
+  onChange = 'onChange',
+  onBlur = 'onBlur',
+}
+
+export type FormValidateReturn = (FieldError | FieldWarning)[];

package/src/utils/dom.ts

@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export interface NativeChangeEvent {
+  target: EventTarget & {
+    value?: any;
+    type?: string;
+    checked?: boolean;
+  };
+}
+
+export function isNativeChangeEvent(e: unknown): e is NativeChangeEvent {
+  return (
+    typeof e === 'object' &&
+    e !== null &&
+    'target' in e &&
+    typeof (e as NativeChangeEvent).target === 'object'
+  );
+}
+
+export function isCheckBoxEvent(e: unknown): e is NativeChangeEvent {
+  return (
+    typeof e === 'object' &&
+    e !== null &&
+    'target' in e &&
+    typeof (e as NativeChangeEvent).target === 'object' &&
+    (e as NativeChangeEvent).target.type === 'checkbox'
+  );
+}