@flowgram-vue/form-core 0.2.0

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

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { injectable } from 'inversify';
+
+import { NodeContribution } from '../node';
+import { NodeManager, PLUGIN_KEY } from '../node';
+import { errorPluginRender } from './renders';
+
+@injectable()
+export class ErrorNodeContribution implements NodeContribution {
+  onRegister(nodeManager: NodeManager) {
+    nodeManager.registerPluginRender(PLUGIN_KEY.ERROR, errorPluginRender);
+  }
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { EntityData } from '@flowgram-vue/core';
+
+export interface ErrorData {
+  error: Error | null;
+}
+
+export class FlowNodeErrorData extends EntityData {
+  static type = 'FlowNodeErrorData';
+
+  getDefaultData(): ErrorData {
+    return { error: null };
+  }
+
+  setError(e: ErrorData['error']) {
+    this.update({ error: e });
+  }
+
+  getError(): Error {
+    return this.data.error;
+  }
+}

package/src/error/index.ts

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

package/src/error/renders/ErrorRender.vue

@@ -0,0 +1,61 @@
+<script lang="ts">
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+import { defineComponent, onBeforeUnmount, type PropType } from 'vue';
+
+import { FlowNodeEntity } from '@flowgram-vue/document';
+import { PlaygroundContext, useRefresh, useService, PluginContext } from '@flowgram-vue/core';
+
+import { FlowNodeErrorData } from '../flow-node-error-data';
+import { MATERIAL_KEY, NodeManager } from '../../node';
+import { defaultErrorRender } from './default-error-render';
+
+export default defineComponent({
+  name: 'ErrorRender',
+  props: {
+    node: { type: Object as PropType<FlowNodeEntity>, required: true },
+    playgroundContext: { type: Object as PropType<PlaygroundContext>, required: true },
+    clientContext: { type: Object as PropType<PluginContext>, required: true },
+  },
+  setup(props) {
+    const refresh = useRefresh();
+    const nodeErrorData = props.node.getData<FlowNodeErrorData>(FlowNodeErrorData);
+    const nodeManager = useService<NodeManager>(NodeManager);
+    const nodeErrorRender = nodeManager.getMaterialRender(MATERIAL_KEY.NODE_ERROR_RENDER);
+
+    const disposable = nodeErrorData.onDataChange(() => {
+      refresh();
+    });
+    onBeforeUnmount(() => {
+      disposable.dispose();
+    });
+
+    return () => {
+      const nodeError = nodeErrorData.getError();
+      if (!nodeError) {
+        return null;
+      }
+      if (!nodeErrorRender) {
+        return defaultErrorRender({
+          error: nodeError,
+          context: {
+            node: props.node,
+            playgroundContext: props.playgroundContext,
+            clientContext: props.clientContext,
+          },
+        });
+      }
+      return nodeErrorRender({
+        error: nodeError,
+        context: {
+          node: props.node,
+          playgroundContext: props.playgroundContext,
+          clientContext: props.clientContext,
+        },
+      });
+    };
+  },
+});
+</script>

package/src/error/renders/default-error-render.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { h } from 'vue';
+
+import { NodeErrorRenderProps } from '../types';
+
+const ERROR_STYLE = {
+  color: '#f54a45',
+};
+
+export const defaultErrorRender = ({ error }: NodeErrorRenderProps) =>
+  h('div', { style: ERROR_STYLE }, error.message);

package/src/error/renders/error-render.ts

@@ -0,0 +1,19 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { h } from 'vue';
+
+import { NodePluginRender } from '../../node';
+import ErrorRender from './ErrorRender.vue';
+
+export { default as ErrorRender } from './ErrorRender.vue';
+export { defaultErrorRender } from './default-error-render';
+
+export const errorPluginRender: NodePluginRender = (props) =>
+  h(ErrorRender, {
+    node: props.node,
+    playgroundContext: props.playgroundContext,
+    clientContext: props.clientContext,
+  });

package/src/error/renders/index.ts

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

package/src/error/types.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { NodeContext, Render } from '../node';
+
+export interface NodeErrorRenderProps {
+  error: Error;
+  context: NodeContext;
+}
+
+export type NodeErrorRender = Render<NodeErrorRenderProps>;

package/src/form/FormRender.vue

@@ -0,0 +1,39 @@
+<script lang="ts">
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+import { defineComponent, onBeforeUnmount, type PropType } from 'vue';
+
+import { useRefresh } from '@flowgram-vue/utils';
+import { FlowNodeEntity } from '@flowgram-vue/document';
+
+import { FormModel } from './models';
+import { FlowNodeFormData } from './flow-node-form-data';
+
+function getFormModelFromNode(node: FlowNodeEntity) {
+  return node.getData(FlowNodeFormData)?.getFormModel<FormModel>();
+}
+
+export default defineComponent({
+  name: 'FormRender',
+  props: {
+    node: { type: Object as PropType<FlowNodeEntity>, required: true },
+  },
+  setup(props) {
+    const refresh = useRefresh();
+    const formModel = getFormModelFromNode(props.node);
+
+    if (formModel) {
+      const disposable = formModel.onInitialized(() => {
+        refresh();
+      });
+      onBeforeUnmount(() => {
+        disposable.dispose();
+      });
+    }
+
+    return () => (formModel?.initialized ? formModel.render() : null);
+  },
+});
+</script>

package/src/form/abilities/decorator-ability/decorator-ability.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { FormItemAbility } from '../../models/form-item-ability';
+
+export class DecoratorAbility implements FormItemAbility {
+  static readonly type = 'decorator';
+
+  get type(): string {
+    return DecoratorAbility.type;
+  }
+}

package/src/form/abilities/decorator-ability/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './decorator-ability';
+export * from './types';

package/src/form/abilities/decorator-ability/types.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { FormItemContext, FormItemFeedback } from '../../types';
+import { SetterOrDecoratorContext } from '../../abilities/setter-ability';
+
+export interface DecoratorAbilityOptions {
+  /**
+   * 已注册的decorator的唯一标识
+   */
+  key: string;
+}
+
+export interface DecoratorComponentProps<CustomOptions = any>
+  extends FormItemFeedback,
+    FormItemContext {
+  readonly: boolean;
+  children?: any;
+  options: DecoratorAbilityOptions & CustomOptions;
+  context: SetterOrDecoratorContext;
+}
+
+export interface DecoratorExtension {
+  key: string;
+  component: (props: DecoratorComponentProps) => any;
+}

package/src/form/abilities/default-ability/default-ability.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { FormItemAbility } from '../../models/form-item-ability';
+
+export class DefaultAbility implements FormItemAbility {
+  static readonly type = 'default';
+
+  get type(): string {
+    return DefaultAbility.type;
+  }
+}

package/src/form/abilities/default-ability/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './default-ability';
+export * from './types';

package/src/form/abilities/default-ability/types.ts

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { FormItemContext, FormItemMaterialContext } from '../..';
+
+export interface GetDefaultValueProps extends FormItemContext {
+  options: DefaultAbilityOptions;
+  context: FormItemMaterialContext;
+}
+
+export interface DefaultAbilityOptions<T = any> {
+  getDefaultValue: (params: GetDefaultValueProps) => T;
+}

package/src/form/abilities/effect-ability/effect-ability.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { FormItemAbility } from '../../models/form-item-ability';
+
+export class EffectAbility implements FormItemAbility {
+  static readonly type = 'effect';
+
+  get type(): string {
+    return EffectAbility.type;
+  }
+}

package/src/form/abilities/effect-ability/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './effect-ability';
+export * from './types';

package/src/form/abilities/effect-ability/types.ts

@@ -0,0 +1,41 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { FormItemContext, FormItemEventName } from '../../types';
+import { type FormItemMaterialContext } from '../../models/form-item-material-context';
+
+export interface EffectAbilityOptions {
+  /**
+   * 已注册的effect 唯一标识
+   */
+  key?: string;
+  /**
+   * 触发 effect 的事件
+   */
+  event?: FormItemEventName;
+  /**
+   * 如果不使用已经注册的effect, 也支持直接写effect函数
+   */
+  effect?: EffectFunction;
+}
+
+export interface EffectEvent {
+  target: any & { value: any };
+  currentTarget: any;
+  type: FormItemEventName;
+}
+
+export interface EffectProps<CustomOptions = any, Event = EffectEvent> extends FormItemContext {
+  event: Event;
+  options: EffectAbilityOptions & CustomOptions;
+  context: FormItemMaterialContext;
+}
+
+export type EffectFunction = (props: EffectProps) => void;
+
+export interface EffectExtension {
+  key: string;
+  effect: EffectFunction;
+}

package/src/form/abilities/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './setter-ability';
+export * from './decorator-ability';
+export * from './visibility-ability';
+export * from './effect-ability';
+export * from './default-ability';
+export * from './validation-ability';

package/src/form/abilities/setter-ability/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './setter-ability';
+export * from './types';

package/src/form/abilities/setter-ability/setter-ability.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { FormItemAbility } from '../../models/form-item-ability';
+
+export class SetterAbility implements FormItemAbility {
+  static readonly type = 'setter';
+
+  get type(): string {
+    return SetterAbility.type;
+  }
+}

package/src/form/abilities/setter-ability/types.ts

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { Component } from 'vue';
+
+import { FormItemContext, FormItemFeedback } from '../../types';
+import { type FormItemMaterialContext } from '../../models/form-item-material-context';
+import { ValidatorFunction } from '../../abilities/validation-ability';
+
+export interface SetterAbilityOptions {
+  /**
+   * 已注册的setter的唯一标识
+   */
+  key: string;
+}
+
+/**
+ * Setter context 是 FormItemMaterialContext 的外观
+ * 基于外观设计模式设计，屏蔽了FormItemMaterialContext中一些setter不可见的接口
+ * readonly: 对于setter 已经放在props 根级别，所以在这里屏蔽，防止干扰
+ * getFormItemValueByPath: setter需通过表单联动方式获取其他表单项的值，不推荐是用这个方法，所以屏蔽
+ */
+export type SetterOrDecoratorContext = Omit<
+  FormItemMaterialContext,
+  'getFormItemValueByPath' | 'readonly'
+>;
+
+export interface SetterComponentProps<T = any, CustomOptions = any>
+  extends FormItemFeedback,
+    FormItemContext {
+  value: T;
+  onChange: (v: T) => void;
+  /**
+   * 节点引擎全局readonly
+   */
+  readonly: boolean;
+  children?: any;
+  options: SetterAbilityOptions & CustomOptions;
+  context: SetterOrDecoratorContext;
+}
+
+export interface SetterExtension {
+  key: string;
+  component: (props: SetterComponentProps) => any;
+  validator?: ValidatorFunction;
+}
+
+export type SetterHoc = (
+  Component: Component<SetterComponentProps>
+) => Component<SetterComponentProps>;

package/src/form/abilities/validation-ability/form-validate.types.ts

@@ -0,0 +1,74 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+// export type ValidatorFormats =
+//   | 'url'
+//   | 'email'
+//   | 'ipv6'
+//   | 'ipv4'
+//   | 'number'
+//   | 'integer'
+//   | 'idcard'
+//   | 'qq'
+//   | 'phone'
+//   | 'money'
+//   | 'zh'
+//   | 'date'
+//   | 'zip'
+//   | (string & {});
+//
+// export interface IValidatorRules<Context = any> {
+//   format?: ValidatorFormats;
+//   validator?: ValidatorFunction<Context>;
+//   required?: boolean;
+//   pattern?: RegExp | string;
+//   max?: number;
+//   maximum?: number;
+//   maxItems?: number;
+//   minItems?: number;
+//   maxLength?: number;
+//   minLength?: number;
+//   exclusiveMaximum?: number;
+//   exclusiveMinimum?: number;
+//   minimum?: number;
+//   min?: number;
+//   len?: number;
+//   whitespace?: boolean;
+//   enum?: any[];
+//   const?: any;
+//   multipleOf?: number;
+//   uniqueItems?: boolean;
+//   maxProperties?: number;
+//   minProperties?: number;
+//   message?: string;
+//
+//   [key: string]: any;
+// }
+//
+// export interface IValidateResult {
+//   type: 'error' | 'warning';
+//   message: string;
+// }
+//
+// export const isValidateResult = (obj: any): obj is IValidateResult =>
+//   Boolean(obj.type) && Boolean(obj.message);
+//
+// export type ValidatorFunctionResponse =
+//   | null
+//   | void
+//   | undefined
+//   | string
+//   | boolean
+//   | IValidateResult;
+//
+// export type ValidatorFunction<Context = any> = (
+//   value: any,
+//   ctx: Context,
+// ) => ValidatorFunctionResponse | Promise<ValidatorFunctionResponse>;
+//
+// export type Validator<Context = any> =
+//   | ValidatorFormats
+//   | ValidatorFunction<Context>
+//   | IValidatorRules;

package/src/form/abilities/validation-ability/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './validation-ability';
+export * from './types';

package/src/form/abilities/validation-ability/types.ts

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { FormItemMaterialContext } from '../../models';
+
+// 这里参照了rehaje 的validator function 返回格式
+export interface IValidateResult {
+  type: 'error' | 'warning';
+  message: string;
+}
+
+export type ValidatorFunctionResponse =
+  | null
+  | void
+  | undefined
+  | string
+  | boolean
+  | IValidateResult;
+
+export interface ValidationAbilityOptions {
+  /**
+   * 已注册的validator唯一标识
+   */
+  key?: string;
+  /**
+   * 不使用已注册的validator 也支持在options中直接写validator
+   */
+  validator?: ValidatorFunction;
+}
+
+export interface ValidatorProps<T = any, CustomOptions = any> {
+  value: T;
+  options: ValidationAbilityOptions & CustomOptions;
+  context: FormItemMaterialContext;
+}
+
+export type ValidatorFunction = (props: ValidatorProps) => ValidatorFunctionResponse;
+
+export interface ValidationExtension {
+  key: string;
+  validator: ValidatorFunction;
+}

package/src/form/abilities/validation-ability/validation-ability.ts

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { FormItemAbility } from '../../models/form-item-ability';
+
+export class ValidationAbility implements FormItemAbility {
+  static readonly type = 'validation';
+
+  get type(): string {
+    return ValidationAbility.type;
+  }
+}

package/src/form/abilities/visibility-ability/index.ts

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

package/src/form/abilities/visibility-ability/visibility-ability.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { FormItemAbility } from '../../models/form-item-ability';
+
+export interface VisibilityAbilityOptions {
+  /**
+   * 是否隐藏
+   */
+  hidden: string | boolean;
+  /**
+   * 隐藏是否要清空表单值, 默认为false
+   */
+  clearWhenHidden?: boolean;
+}
+
+export class VisibilityAbility implements FormItemAbility {
+  static readonly type = 'visibility';
+
+  get type(): string {
+    return VisibilityAbility.type;
+  }
+}

package/src/form/client/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { FlowNodeEntity } from '@flowgram-vue/document';
+
+import { FlowNodeFormData } from '../flow-node-form-data';
+import { FormModel } from '../models';
+
+export function isNodeFormReady(node: FlowNodeEntity) {
+  return node.getData<FlowNodeFormData>(FlowNodeFormData).getFormModel<FormModel>().initialized;
+}
+
+export function getFormModel(node: FlowNodeEntity) {
+  return node.getData<FlowNodeFormData>(FlowNodeFormData).formModel;
+}