@flowgram-vue/form-core 0.2.0

package/src/form/services/form-path-service.ts

@@ -0,0 +1,88 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { injectable } from 'inversify';
+
+@injectable()
+export class FormPathService {
+  static readonly ROOT = '/';
+
+  static readonly DIVIDER = '/';
+
+  static readonly RELATIVE_PARENT = '..';
+
+  static readonly RELATIVE_CURRENT = '.';
+
+  static readonly ARRAY = '[]';
+
+  static normalize(path: string) {
+    if (path === FormPathService.ROOT) {
+      return path;
+    }
+    // 去掉末尾的斜杠
+    if (path.endsWith(FormPathService.DIVIDER)) {
+      path = path.slice(0, -1);
+    }
+    return path;
+  }
+
+  static join(paths: string[]): string {
+    if (paths[1].startsWith(FormPathService.ROOT)) {
+      throw new Error(
+        `FormPathService Error: join failed, invalid paths[1], paths[1]= ${paths[1]}`,
+      );
+    }
+    if (paths[0].endsWith(FormPathService.DIVIDER)) {
+      return `${paths[0]}${paths[1]}`;
+    }
+    return paths.join(FormPathService.DIVIDER);
+  }
+
+  static toArrayPath(path: string): string {
+    return FormPathService.join([path, FormPathService.ARRAY]);
+  }
+
+  static parseArrayItemPath(path: string) {
+    const names = path.split('/');
+
+    let i = 0;
+    while (i < names.length) {
+      const itemIndex = parseInt(names[i]);
+
+      if (!isNaN(itemIndex)) {
+        const arrayPath = FormPathService.toArrayPath(
+          names.slice(0, i).join(FormPathService.DIVIDER),
+        );
+        const restPath = names.slice(i + 1).join(FormPathService.DIVIDER);
+        const itemMetaPath = FormPathService.join([arrayPath, restPath]);
+        return { itemIndex, arrayPath, itemMetaPath };
+      }
+      i = i + 1;
+    }
+    return null;
+  }
+
+  simplify(path: string) {
+    const segments = path.split(FormPathService.DIVIDER);
+    const resSegments: string[] = [];
+
+    for (let i = 0; i < segments.length; i++) {
+      if (!segments[i]) {
+        throw new Error('FormPathService: join failed');
+      }
+
+      if (segments[i] === FormPathService.RELATIVE_CURRENT) {
+        // eslint-disable-next-line no-continue
+        continue;
+      }
+
+      if (segments[i] === FormPathService.RELATIVE_PARENT) {
+        resSegments.pop();
+      }
+      resSegments.push(segments[i]);
+    }
+    return resSegments.join(FormPathService.DIVIDER);
+  }
+}

package/src/form/services/index.ts

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

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

@@ -0,0 +1,65 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { FlowNodeEntity } from '@flowgram-vue/document';
+import { PlaygroundContext } from '@flowgram-vue/core';
+import { MaybePromise } from '@flowgram-vue/utils';
+
+import { type IFormItem } from './form-model.types';
+import { IFormItemMeta } from './form-meta.types';
+
+export interface FormItemAbilityMeta<Options = any> {
+  type: string;
+  options: Options;
+}
+
+/**
+ * @deprecated
+ */
+export interface FormItemContext {
+  /**
+   * @deprecated Use context.node instead
+   */
+  formItemMeta: IFormItemMeta;
+  /**
+   * @deprecated
+   */
+  formItem: IFormItem;
+  /**
+   * @deprecated Use context.node instead
+   */
+  flowNodeEntity: FlowNodeEntity;
+  /**
+   * @deprecated Use context.playgroundContext instead
+   */
+  playgroundContext: PlaygroundContext;
+}
+
+export interface FormItemHookParams extends FormItemContext {
+  formItem: IFormItem;
+}
+
+export interface FormItemHooks<T> {
+  /**
+   * FormItem初始化钩子
+   */
+  onInit?: (params: FormItemHookParams & T) => void;
+  /**
+   * FormItem提交时钩子
+   */
+  onSubmit?: (params: FormItemHookParams & T) => void;
+  /**
+   * FormItem克隆时钩子
+   */
+  onClone?: (params: FormItemHookParams & T) => MaybePromise<void>;
+  /**
+   * 克隆后执行的逻辑
+   */
+  afterClone?: (params: FormItemHookParams & T) => void;
+  /**
+   * FormItem全局校验时钩子
+   */
+  onValidate?: (params: FormItemHookParams & T) => void;
+}

package/src/form/types/form-meta.types.ts

@@ -0,0 +1,121 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { MaybePromise } from '@flowgram-vue/utils';
+import { FlowNodeEntity } from '@flowgram-vue/document';
+import { PlaygroundContext, PluginContext } from '@flowgram-vue/core';
+
+import { type FormItemAbilityMeta } from './form-ability.types';
+
+export type FormDataTypeName =
+  | 'string'
+  | 'number'
+  | 'integer'
+  | 'boolean'
+  | 'object'
+  | 'array'
+  | 'null';
+
+export type FormDataType =
+  | string //
+  | number
+  | boolean
+  | FormDataObject
+  | DataArray
+  | null;
+
+export interface FormDataObject {
+  [key: string]: FormDataType;
+}
+
+export type DataArray = Array<FormDataType>;
+
+export const FORM_VOID = 'form-void' as const;
+
+export interface TreeNode<T> {
+  name: string;
+  children?: TreeNode<T>[];
+}
+
+export interface IFormItemMeta extends TreeNode<IFormItemMeta> {
+  /**
+   * 表单项名称
+   */
+  name: string;
+  /**
+   * 数据类型
+   */
+  type: FormDataTypeName | typeof FORM_VOID;
+  /**
+   * 枚举值
+   */
+  enum?: FormDataType[];
+  /**
+   * 数组类型item的数据类型描述
+   */
+  items?: IFormItemMeta;
+  /**
+   * 表单项标题
+   */
+  title?: string;
+  /**
+   * 表单项描述
+   */
+  description?: string;
+  /**
+   * 表单项默认值
+   */
+  default?: FormDataType;
+  /**
+   * 是否必填
+   */
+  required?: boolean;
+  /**
+   * 扩展能力
+   */
+  abilities?: FormItemAbilityMeta[];
+
+  /**
+   * 子表单项
+   */
+  children?: IFormItemMeta[];
+}
+
+export interface IFormMeta {
+  /**
+   * 表单树结构root
+   */
+  root?: IFormItemMeta;
+  /**
+   * 表单全局配置
+   */
+  options?: IFormMetaOptions;
+}
+
+export interface NodeFormContext {
+  node: FlowNodeEntity;
+  playgroundContext: PlaygroundContext;
+  clientContext: PluginContext & Record<string, any>;
+}
+
+export interface IFormMetaOptions {
+  formatOnInit?: (value: any, context: NodeFormContext) => any;
+
+  formatOnSubmit?: (value: any, context: NodeFormContext) => any;
+
+  [key: string]: any;
+}
+
+export interface FormMetaGeneratorParams<PlaygroundContext, FormValue = any> {
+  node: FlowNodeEntity;
+  playgroundContext: PlaygroundContext;
+  initialValue?: FormValue;
+}
+
+export type FormMetaGenerator<PlaygroundContext = any, FormValue = any> = (
+  params: FormMetaGeneratorParams<FormValue, FormValue>
+) => MaybePromise<IFormMeta>;
+
+export type FormMetaOrFormMetaGenerator = FormMetaGenerator | IFormMeta;

package/src/form/types/form-model.types.ts

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export interface IFormItem<T = any> {
+  value: T;
+}
+
+export enum FormItemEventName {
+  onFormValueChange = 'onFormValueChange',
+  onFormItemInit = 'onFormItemInit',
+}
+
+export type FormModelValid = boolean | null;
+
+export type FeedbackStatus = 'error' | 'warning' | 'pending';
+export type FeedbackText = string;
+
+export interface FormItemFeedback {
+  feedbackStatus?: FeedbackStatus;
+  feedbackText?: FeedbackText;
+}
+
+export interface FormFeedback {
+  feedbackStatus?: FeedbackStatus;
+  feedbackText?: FeedbackText;
+  path: string;
+}
+
+export interface FormItemDomRef {
+  current: HTMLElement | null;
+}

package/src/form/types/index.ts

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

package/src/index.ts

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

package/src/node/core-materials.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export const MATERIAL_KEY = {
+  NODE_ERROR_RENDER: 'node_error_render',
+  NODE_PLACEHOLDER_RENDER: 'node_placeholder_render',
+};

package/src/node/core-plugins.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export const PLUGIN_KEY = {
+  FORM: 'Plugin_Form',
+  ERROR: 'Plugin_Error',
+};

package/src/node/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export { NodeContribution } from './node-contribution';
+export * from './node-container-module';
+export * from './node-manager';
+export * from './types';
+export * from './core-plugins';
+export * from './core-materials';
+export * from './node-engine';
+export * from './node-engine-context';

package/src/node/node-container-module.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { ContainerModule } from 'inversify';
+
+import { NodeManager } from './node-manager';
+import { NodeEngineContext } from './node-engine-context';
+import { NodeEngine } from './node-engine';
+
+export const NodeContainerModule = new ContainerModule((bind, unbind, isBound, rebind) => {
+  bind(NodeEngine).toSelf().inSingletonScope();
+  bind(NodeManager).toSelf().inSingletonScope();
+  bind(NodeEngineContext).toSelf().inSingletonScope();
+});

package/src/node/node-contribution.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { type NodeManager } from './node-manager';
+
+export const NodeContribution = Symbol('NodeContribution');
+
+export interface NodeContribution {
+  onRegister?(nodeManager: NodeManager): void;
+}

package/src/node/node-engine-context.ts

@@ -0,0 +1,54 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { injectable } from 'inversify';
+import { Emitter } from '@flowgram-vue/utils';
+
+export interface INodeEngineContext {
+  readonly: boolean;
+}
+
+/**
+ * NodeEngineContext 在 Node Engine 中为全局单例, 它的作用是让Node之间共享数据。
+ * context 分为内置context(如 readonly) 和 自定义context(业务可以按需注入)
+ */
+@injectable()
+export class NodeEngineContext {
+  static DEFAULT_READONLY = false;
+
+  static DEFAULT_JSON = { readonly: NodeEngineContext.DEFAULT_READONLY };
+
+  readonly onChangeEmitter = new Emitter<NodeEngineContext>();
+
+  readonly onChange = this.onChangeEmitter.event;
+
+  private _readonly: boolean = NodeEngineContext.DEFAULT_READONLY;
+
+  private _json: INodeEngineContext = NodeEngineContext.DEFAULT_JSON;
+
+  get json(): INodeEngineContext {
+    return this._json;
+  }
+
+  get readonly(): boolean {
+    return this._readonly;
+  }
+
+  set readonly(value: boolean) {
+    this._readonly = value;
+    this.fireChange();
+  }
+
+  private fireChange(): void {
+    this.updateJSON();
+    this.onChangeEmitter.fire(this);
+  }
+
+  private updateJSON(): void {
+    this._json = {
+      readonly: this._readonly,
+    };
+  }
+}

package/src/node/node-engine.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { injectable, inject } from 'inversify';
+
+import { NodeManager } from './node-manager';
+import { NodeEngineContext } from './node-engine-context';
+
+@injectable()
+export class NodeEngine {
+  @inject(NodeManager) nodeManager: NodeManager;
+
+  @inject(NodeEngineContext) context: NodeEngineContext;
+}

package/src/node/node-manager.ts

@@ -0,0 +1,63 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { flow } from 'lodash-es';
+import { injectable, multiInject, optional, postConstruct } from 'inversify';
+
+import { NodeErrorRenderProps } from '../error';
+import { NodePluginRender, NodeRenderHoc, Render } from './types';
+import { NodeContribution } from './node-contribution';
+
+export enum MaterialRenderKey {
+  CustomNodeError = 'Material_CustomNodeError',
+}
+
+@injectable()
+export class NodeManager {
+  readonly materialRenderRegistry: Map<string, Render> = new Map();
+
+  readonly pluginRenderRegistry: Map<string, Render> = new Map();
+
+  readonly nodeRenderHocs: NodeRenderHoc[] = [];
+
+  @multiInject(NodeContribution) @optional() protected nodeContributions: NodeContribution[] = [];
+
+  registerMaterialRender(key: string, render: Render) {
+    this.materialRenderRegistry.set(key, render);
+  }
+
+  getMaterialRender(key: string): Render | undefined {
+    return this.materialRenderRegistry.get(key);
+  }
+
+  registerPluginRender(key: string, render: NodePluginRender): void {
+    this.pluginRenderRegistry.set(key, render);
+  }
+
+  getPluginRender(key: string): NodePluginRender | undefined {
+    return this.pluginRenderRegistry.get(key);
+  }
+
+  registerNodeErrorRender(render: Render<NodeErrorRenderProps>) {
+    this.registerMaterialRender(MaterialRenderKey.CustomNodeError, render);
+  }
+
+  get nodeRenderHoc() {
+    return flow(this.nodeRenderHocs);
+  }
+
+  registerNodeRenderHoc(hoc: NodeRenderHoc) {
+    this.nodeRenderHocs.push(hoc);
+  }
+
+  get nodeErrorRender() {
+    return this.materialRenderRegistry.get(MaterialRenderKey.CustomNodeError);
+  }
+
+  @postConstruct()
+  protected init(): void {
+    this.nodeContributions.forEach((contrib) => contrib.onRegister?.(this));
+  }
+}

package/src/node/types.ts

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { Component } from 'vue';
+
+import { FlowNodeEntity } from '@flowgram-vue/document';
+
+import type { NodeFormContext } from '../form/types/form-meta.types';
+
+/**
+ * @deprecated
+ * use `NodeFormContext` instead
+ */
+export type NodeContext = NodeFormContext;
+
+export type Render<T = any> = (props: T) => any;
+
+export type NodePluginRender = Render<NodeFormContext>;
+
+export type NodePlaceholderRender = Render<NodeFormContext>;
+
+export interface NodeRenderProps {
+  node: FlowNodeEntity;
+}
+
+export type NodeRenderHoc = (
+  Component: Component<NodeRenderProps> | (() => any)
+) => Component<NodeRenderProps> | (() => any);

package/src/node-vue/composables/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './use-node-engine-context';
+export * from './use-form-item';

package/src/node-vue/composables/use-form-item.ts

@@ -0,0 +1,28 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { onBeforeUnmount } from 'vue';
+
+import { FlowNodeEntity } from '@flowgram-vue/document';
+import { useEntityFromContext, useRefresh } from '@flowgram-vue/core';
+
+import { FlowNodeFormData, FormModel, IFormItem } from '../../form';
+
+export function useFormItem(path: string): IFormItem | undefined {
+  const refresh = useRefresh();
+  const node = useEntityFromContext<FlowNodeEntity>();
+  const formData = node.getData<FlowNodeFormData>(FlowNodeFormData);
+  const formItem = formData.getFormModel<FormModel>().getFormItemByPath(path);
+
+  const disposable = formData.onDataChange(() => {
+    refresh();
+  });
+
+  onBeforeUnmount(() => {
+    disposable.dispose();
+  });
+
+  return formItem;
+}

package/src/node-vue/composables/use-node-engine-context.ts

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { onBeforeUnmount } from 'vue';
+
+import { useService, useRefresh } from '@flowgram-vue/core';
+
+import { NodeEngineContext } from '../../node';
+
+export function useNodeEngineContext(): NodeEngineContext {
+  const refresh = useRefresh();
+  const nodeEngineContext = useService<NodeEngineContext>(NodeEngineContext);
+
+  const disposable = nodeEngineContext.onChange(() => {
+    refresh();
+  });
+
+  onBeforeUnmount(() => {
+    disposable.dispose();
+  });
+
+  return nodeEngineContext;
+}

package/src/node-vue/context/index.ts

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

package/src/node-vue/context/node-engine-vue-context.ts

@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import type { InjectionKey } from 'vue';
+import { inject, provide } from 'vue';
+
+import { INodeEngineContext, NodeEngineContext } from '../../node';
+
+export const NodeEngineVueContextKey: InjectionKey<INodeEngineContext> = Symbol(
+  'NodeEngineVueContext'
+);
+
+export function provideNodeEngineContext(ctx: INodeEngineContext): void {
+  provide(NodeEngineVueContextKey, ctx);
+}
+
+export function useNodeEngineVueContext(): INodeEngineContext {
+  return inject(NodeEngineVueContextKey, NodeEngineContext.DEFAULT_JSON);
+}
+
+/** @deprecated use NodeEngineVueContextKey */
+export const NodeEngineVueContext = NodeEngineVueContextKey;

package/src/node-vue/hooks/index.ts

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

package/src/node-vue/index.ts

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