@flowgram-vue/node 0.2.0

package/src/get-node-form.ts

@@ -0,0 +1,109 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { h, type VNode } from 'vue';
+
+import { Disposable, Event } from '@flowgram-vue/utils';
+import { FlowNodeFormData, NodeRender, OnFormValuesChangePayload } from '@flowgram-vue/form-core';
+import { FieldName, FieldValue, FormState } from '@flowgram-vue/form';
+import { FlowNodeEntity } from '@flowgram-vue/document';
+
+import { onFormValueChangeInPayload } from './types';
+import { FormModelV2 } from './form-model-v2';
+
+export interface NodeFormProps<TValues> {
+  /**
+   * 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;
+  /**
+   * set form values
+   */
+  updateFormValues(values: any): void;
+  /**
+   * Render form
+   */
+  render: () => VNode;
+  /**
+   * Form value change event
+   */
+  onFormValuesChange: Event<OnFormValuesChangePayload>;
+  /**
+   * Trigger form validate
+   */
+  validate: () => Promise<boolean>;
+  /**
+   * Form validate event
+   */
+  onValidate: Event<FormState>;
+  /**
+   * Form field value change event
+   */
+  onFormValueChangeIn<TValue = FieldValue, TFormValue = FieldValue>(
+    name: FieldName,
+    callback: (payload: onFormValueChangeInPayload<TValue, TFormValue>) => void
+  ): Disposable;
+}
+
+/**
+ * Use `node.form` instead
+ * @deprecated
+ * @param node
+ */
+export function getNodeForm<TValues = FieldValue>(
+  node: FlowNodeEntity
+): NodeFormProps<TValues> | undefined {
+  const formModel = node.getData<FlowNodeFormData>(FlowNodeFormData)?.getFormModel<FormModelV2>();
+  const nativeFormModel = formModel?.nativeFormModel;
+
+  if (!formModel || !nativeFormModel) return undefined;
+
+  const result: NodeFormProps<TValues> = {
+    initialValues: nativeFormModel.initialValues,
+    get values() {
+      return nativeFormModel.values;
+    },
+
+    state: nativeFormModel.state,
+    getValueIn: (name: FieldName) => nativeFormModel.getValueIn(name),
+    setValueIn: (name: FieldName, value: any) => nativeFormModel.setValueIn(name, value),
+    updateFormValues: (values: any) => {
+      formModel.updateFormValues(values);
+    },
+    render: () => h(NodeRender, { node }),
+    onFormValuesChange: formModel.onFormValuesChange.bind(formModel),
+    onFormValueChangeIn: formModel.onFormValueChangeIn.bind(formModel),
+    onValidate: formModel.nativeFormModel.onValidate,
+    validate: formModel.validate.bind(formModel),
+  };
+
+  Object.defineProperty(result, '_formModel', {
+    enumerable: false,
+    get() {
+      return formModel;
+    },
+  });
+  return result;
+}

package/src/helpers.ts

@@ -0,0 +1,29 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { FlowNodeFormData } from '@flowgram-vue/form-core';
+import { FlowNodeEntity } from '@flowgram-vue/document';
+
+import { DataEvent } from './types';
+import { FormModelV2 } from './form-model-v2';
+
+export function getFormModel(node: FlowNodeEntity) {
+  // @ts-ignore
+  return node.getData<FlowNodeFormData>(FlowNodeFormData)?.formModel as FormModelV2;
+}
+
+export function isFormV2(node: FlowNodeEntity) {
+  return !!node.getNodeRegistry().formMeta?.render;
+}
+
+export function createEffectOptions<T>(
+  event: DataEvent,
+  effect: T
+): { effect: T; event: DataEvent } {
+  return {
+    event,
+    effect,
+  };
+}

package/src/hooks.ts

@@ -0,0 +1,98 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { onBeforeUnmount } from 'vue';
+
+import { useRefresh } from '@flowgram-vue/utils';
+import { FlowNodeFormData } from '@flowgram-vue/form-core';
+import { Errors, Warnings } from '@flowgram-vue/form';
+import { FormState, useFormErrors, useFormState, useFormWarnings } from '@flowgram-vue/form';
+import { FlowNodeEntity } from '@flowgram-vue/document';
+
+import { FormModelV2 } from './form-model-v2';
+
+/**
+ * Listen to Form's values and refresh the Vue component.
+ * By providing related node, you can use this hook outside the Form Component.
+ * @param node
+ */
+export function useWatchFormValues<T = any>(node: FlowNodeEntity): T | undefined {
+  const formModel = node.getData(FlowNodeFormData).getFormModel<FormModelV2>();
+  const refresh = useRefresh();
+
+  const disposable = formModel.nativeFormModel?.onFormValuesChange(() => {
+    refresh();
+  });
+  onBeforeUnmount(() => disposable?.dispose());
+
+  return formModel.getValues<T>();
+}
+
+/**
+ * Listen to Form's value in a certain path and refresh the Vue component.
+ * By providing related node, you can use this hook outside the Form Component.
+ * @param node
+ */
+export function useWatchFormValueIn<T = any>(node: FlowNodeEntity, name: string): T | undefined {
+  const formModel = node.getData(FlowNodeFormData).getFormModel<FormModelV2>();
+  const refresh = useRefresh();
+
+  const disposable = formModel.nativeFormModel?.onFormValuesChange(({ name: changedName }) => {
+    if (name === changedName) {
+      refresh();
+    }
+  });
+
+  onBeforeUnmount(() => disposable?.dispose());
+
+  return formModel.getValueIn<T>(name);
+}
+
+/**
+ * Listen to FormModel's initialization and refresh Vue component.
+ * By providing related node, you can use this hook outside the Form Component.
+ * @param node
+ */
+export function useInitializedFormModel(node: FlowNodeEntity) {
+  const formModel = node.getData(FlowNodeFormData).getFormModel<FormModelV2>();
+  const refresh = useRefresh();
+
+  const disposable = formModel.onInitialized(() => {
+    refresh();
+  });
+  onBeforeUnmount(() => disposable.dispose());
+
+  return formModel;
+}
+
+/**
+ * Get Form's state, Form State is a proxy, it will refresh the Vue component when the value you accessed changed
+ * By providing related node, you can use this hook outside the Form Component.
+ * @param node
+ */
+export function useWatchFormState(node: FlowNodeEntity): FormState | undefined {
+  const formModel = useInitializedFormModel(node);
+  return useFormState(formModel.formControl);
+}
+
+/**
+ * Get Form's errors, Form errors is a proxy, it will refresh the Vue component when the value you accessed changed
+ * By providing related node, you can use this hook outside the Form Component.
+ * @param node
+ */
+export function useWatchFormErrors(node: FlowNodeEntity): Errors | undefined {
+  const formModel = useInitializedFormModel(node);
+  return useFormErrors(formModel.formControl);
+}
+
+/**
+ * Get Form's warnings, Form warnings is a proxy, it will refresh the Vue component when the value you accessed changed
+ * By providing related node, you can use this hook outside the Form Component.
+ * @param node
+ */
+export function useWatchFormWarnings(node: FlowNodeEntity): Warnings | undefined {
+  const formModel = useInitializedFormModel(node);
+  return useFormWarnings(formModel.formControl);
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './types';
+export * from './form-model-v2';
+export { isFormV2, createEffectOptions } from './helpers';
+export * from './hooks';
+export * from './form-plugin';
+export { type NodeFormProps, getNodeForm } from './get-node-form';

package/src/types.ts

@@ -0,0 +1,153 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { VNode } from 'vue';
+
+import { FormModel, IFormMeta, NodeContext } from '@flowgram-vue/form-core';
+import { FieldName, FieldValue } from '@flowgram-vue/form';
+import {
+  FormRenderProps,
+  IForm,
+  Validate as FormValidate,
+  ValidateTrigger,
+} from '@flowgram-vue/form';
+
+import { FormPlugin } from './form-plugin';
+import { FormModelV2 } from './form-model-v2';
+
+export interface Node {}
+
+export interface Flow {}
+
+export type Validate<TFieldValue = any, TFormValues = any> = (props: {
+  value: TFieldValue;
+  formValues: TFormValues;
+  context: NodeContext;
+  name: FieldName;
+}) => ReturnType<FormValidate<TFieldValue, TFormValues>>;
+
+export enum DataEvent {
+  /* When value change */
+  onValueChange = 'onValueChange',
+  /**
+   * When value Init，it triggers when
+   * - defaultValue is configured in formMeta, it will trigger when form is initializing.
+   * - defaultValue is configured in Field, it will trigger when this Field is initializing if no initial value is set to this field.
+   */
+  onValueInit = 'onValueInit',
+  /**
+   * When Value Init or change
+   */
+  onValueInitOrChange = 'onValueInitOrChange',
+  /* It will trigger when ArrayField.append is called. It relies on ArrayField's rendering. If ArrayField is possibly not rendered in your case, please avoid using this event */
+  onArrayAppend = 'onArrayAppend',
+  /* It will trigger when ArrayField.delete is called. It relies on ArrayField's rendering. If ArrayField is possibly not rendered in your case, please avoid using this event */
+  onArrayDelete = 'onArrayDelete',
+}
+
+export type EffectReturn = () => void;
+
+export interface EffectFuncProps<TFieldValue = any, TFormValues = any> {
+  name: FieldName;
+  value: TFieldValue;
+  prevValue?: TFieldValue;
+  formValues: TFormValues;
+  form: IForm;
+  context: NodeContext;
+}
+
+export type Effect<TFieldValue = any, TFormValues = any> = (
+  props: EffectFuncProps<TFieldValue, TFormValues>
+) => void | EffectReturn;
+
+export type ArrayAppendEffect<TFieldValue = any, TFormValues = any> = (props: {
+  index: number;
+  value: TFieldValue;
+  arrayValues: Array<TFieldValue>;
+  formValues: TFormValues;
+  form: IForm;
+  context: NodeContext;
+}) => void | EffectReturn;
+
+export type ArrayDeleteEffect<TFieldValue = any, TFormValues = any> = (props: {
+  index: number;
+  arrayValue: Array<TFieldValue>;
+  formValues: TFormValues;
+  form: IForm;
+  context: NodeContext;
+}) => void | EffectReturn;
+
+export type EffectOptions =
+  | { effect: Effect; event: DataEvent }
+  | { effect: ArrayAppendEffect; event: DataEvent }
+  | { effect: ArrayDeleteEffect; event: DataEvent };
+
+export interface FormMeta<TValues = any> {
+  /**
+   * The render method of the node form content. <Form /> is already integrated, so you don't need to wrap your components with <Form />
+   * @param props
+   */
+  render: (props: FormRenderProps<any>) => VNode;
+  /**
+   * When to trigger the validation.
+   */
+  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<FieldName, Validate>
+    | ((values: TValues, ctx: NodeContext) => Record<FieldName, Validate>);
+  /**
+   * Form data's effects. It's a key value map, where the key is a pattern of data's path (or field name), the value is an array of effect configuration.
+   */
+  effect?: Record<FieldName, EffectOptions[]>;
+  /**
+   * Form data's complete default value. it will not be sent to formatOnInit, but used directly as form's value when needed.
+   */
+  defaultValues?: TValues | ((context: NodeContext) => TValues);
+  /**
+   * This function is to format the value when initiate the form, the returned value will be used as the initial value of the form.
+   * @param value value input to node as initialValue.
+   * @param context
+   */
+  formatOnInit?: (value: any, context: NodeContext) => any;
+  /**
+   * This function is to format the value when FormModel.toJSON is called, the returned value will be used as the final value to be saved .
+   * @param value value sent by form before format.
+   * @param context
+   */
+  formatOnSubmit?: (value: any, context: NodeContext) => any;
+  /**
+   * Form's plugins
+   */
+  plugins?: FormPlugin[];
+}
+
+export function isFormModelV2(fm: FormModel | FormModelV2): fm is FormModelV2 {
+  return 'onFormValuesChange' in fm;
+}
+
+export function isFormMetaV2(formMeta: IFormMeta | FormMeta) {
+  return 'render' in formMeta;
+}
+
+export type FormPluginCtx = {
+  formModel: FormModelV2;
+} & NodeContext;
+
+export type FormPluginSetupMetaCtx = {
+  mergeEffect: (effect: Record<string, EffectOptions[]>) => void;
+  mergeValidate: (validate: Record<FieldName, Validate>) => void;
+  addFormatOnInit: (formatOnInit: FormMeta['formatOnInit']) => void;
+  addFormatOnSubmit: (formatOnSubmit: FormMeta['formatOnSubmit']) => void;
+} & NodeContext;
+
+export interface onFormValueChangeInPayload<TValue = FieldValue, TFormValues = FieldValue> {
+  value: TValue;
+  prevValue: TValue;
+  formValues: TFormValues;
+  prevFormValues: TFormValues;
+}

package/src/utils.ts

@@ -0,0 +1,86 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { find, mergeWith } from 'lodash-es';
+import { FormFeedback, FormPathService } from '@flowgram-vue/form-core';
+import type { FieldError, FieldWarning, FormValidateReturn } from '@flowgram-vue/form';
+import { type FieldModel, FieldName } from '@flowgram-vue/form';
+
+import { DataEvent, EffectOptions, EffectReturn } from './types';
+
+export function findMatchedInMap<T = any>(
+  field: FieldModel<any>,
+  validateMap: Record<FieldName, T> | undefined
+): T | undefined {
+  if (!validateMap) {
+    return;
+  }
+  if (validateMap[field.name]) {
+    return validateMap[field.name];
+  }
+
+  const found = find(Object.keys(validateMap), (key) => {
+    if (key.startsWith('regex:')) {
+      const regex = RegExp(key.split(':')[1]);
+      return regex.test(field.name);
+    }
+    return false;
+  });
+
+  if (found) {
+    return validateMap[found];
+  }
+}
+
+export function formFeedbacksToNodeCoreFormFeedbacks(
+  formFeedbacks: FormValidateReturn
+): FormFeedback[] {
+  return formFeedbacks.map(
+    (f: FieldError | FieldWarning) =>
+      ({
+        feedbackStatus: f.level,
+        feedbackText: f.message,
+        path: f.name,
+      } as FormFeedback)
+  );
+}
+
+export function convertGlobPath(path: string) {
+  if (path.startsWith('/')) {
+    const parts = FormPathService.normalize(path).slice(1).split('/');
+    return parts.join('.');
+  }
+  return path;
+}
+
+export function mergeEffectMap(
+  origin: Record<string, EffectOptions[]>,
+  source: Record<string, EffectOptions[]>
+) {
+  return mergeWith(origin, source, function (objValue: EffectOptions[], srcValue: EffectOptions[]) {
+    return (objValue || []).concat(srcValue);
+  });
+}
+
+export function mergeEffectReturn(origin?: EffectReturn, source?: EffectReturn): EffectReturn {
+  return () => {
+    origin?.();
+    source?.();
+  };
+}
+
+export function runAndDeleteEffectReturn(
+  effectReturnMap: Map<DataEvent, Record<string, EffectReturn>>,
+  name: string,
+  events: DataEvent[]
+) {
+  events.forEach((event) => {
+    const eventMap = effectReturnMap.get(event);
+    if (eventMap?.[name]) {
+      eventMap[name]();
+      delete eventMap[name];
+    }
+  });
+}