refactor: move formatNodeLines and formatNodeLabels to fixed-layout-props, demo-free-layout loop node cannot nest loop node (#672)

* feat(demo-free-layout): loop node cannot nest loop node

* refactor(editor): move formatNodeLines and formatNodeLabels to fixed-layout-prest, add editor props comments

* fix: ts-check

apps/demo-fixed-layout/src/hooks/use-editor-props.ts

@@ -39,6 +39,10 @@ export function useEditorProps(
        * Whether to enable the background
        */
       background: true,
+      /**
+       * 画布相关配置
+       * Canvas-related configurations
+       */
       playground: {
         /**
          * Prevent Mac browser gestures from turning pages

apps/demo-free-layout/src/hooks/use-editor-props.tsx

@@ -44,6 +44,10 @@ export function useEditorProps(
        * Whether to enable the background
        */
       background: true,
+      /**
+       * 画布相关配置
+       * Canvas-related configurations
+       */
       playground: {
         /**
          * Prevent Mac browser gestures from turning pages
@@ -143,6 +147,10 @@ export function useEditorProps(
       canDeleteNode(ctx, node) {
         return true;
       },
+      /**
+       * 是否允许拖入子画布 (loop or group)
+       * Whether to allow dragging into the sub-canvas (loop or group)
+       */
       canDropToNode: (ctx, params) => {
         const { dragNodeType, dropNodeType } = params;
         /**
@@ -171,11 +179,19 @@ export function useEditorProps(
         ) {
           return false;
         }
+        /**
+         * 循环节点无法嵌套循环节点
+         * Loop node cannot nest loop node
+         */
+        if (dragNodeType === WorkflowNodeType.Loop && dropNodeType === WorkflowNodeType.Loop) {
+          return false;
+        }
         return true;
       },
       /**
        * Drag the end of the line to create an add panel (feature optional)
        * 拖拽线条结束需要创建一个添加面板 （功能可选）
+       * 希望提供控制线条粗细的配置项
        */
       onDragLineEnd,
       /**
@@ -231,7 +247,6 @@ export function useEditorProps(
        * Running line
        */
       isFlowingLine: (ctx, line) => ctx.get(WorkflowRuntimeService).isFlowingLine(line),
-
       /**
        * Shortcuts
        */
@@ -339,6 +354,9 @@ export function useEditorProps(
          * ContextMenu plugin
          */
         createContextMenuPlugin({}),
+        /**
+         * Runtime plugin
+         */
         createRuntimePlugin({
           mode: 'browser',
           // mode: 'server',

packages/canvas-engine/document/src/datas/flow-node-transform-data.ts

@@ -102,6 +102,12 @@ export class FlowNodeTransformData extends EntityData<FlowNodeTransformSchema> {
     };
   }
 
+  set position(position: PositionSchema) {
+    this.transform.update({
+      position,
+    });
+  }
+
   set size(size: SizeSchema) {
     const { width, height } = this.data.size;
     // Container size 由子节点决定

packages/client/editor/src/preset/editor-default-preset.ts

@@ -14,7 +14,6 @@ import { createHistoryNodePlugin } from '@flowgram.ai/history-node-plugin';
 import { FlowDocumentContainerModule } from '@flowgram.ai/document';
 import { createPlaygroundPlugin, Plugin, PluginsProvider } from '@flowgram.ai/core';
 
-import { compose } from '../utils/compose';
 import { createFlowEditorClientPlugins } from '../clients/flow-editor-client-plugins';
 import { EditorPluginContext, EditorProps } from './editor-props';
 
@@ -81,20 +80,6 @@ export function createDefaultPreset<CTX extends EditorPluginContext = EditorPlug
           if (opts.constants) {
             ctx.document.options.constants = opts.constants;
           }
-          // 劫持节点线条
-          if (opts.formatNodeLines) {
-            ctx.document.options.formatNodeLines = compose([
-              ctx.document.options.formatNodeLines,
-              opts.formatNodeLines,
-            ]);
-          }
-          // 劫持节点 label
-          if (opts.formatNodeLabels) {
-            ctx.document.options.formatNodeLabels = compose([
-              ctx.document.options.formatNodeLabels,
-              opts.formatNodeLabels,
-            ]);
-          }
           if (opts.getNodeDefaultRegistry) {
             ctx.document.options.getNodeDefaultRegistry = opts.getNodeDefaultRegistry;
           }

packages/client/editor/src/preset/editor-props.ts

@@ -18,8 +18,6 @@ import {
   type FlowNodeJSON,
   FlowNodeRegistry,
   FlowNodeType,
-  FlowTransitionLabel,
-  FlowTransitionLine,
 } from '@flowgram.ai/document';
 import { PluginContext } from '@flowgram.ai/core';
 
@@ -28,48 +26,51 @@ export interface EditorPluginContext extends PluginContext {
   selection: SelectionService;
 }
 
-/**
- * 固定布局配置
- */
 export interface EditorProps<
   CTX extends EditorPluginContext = EditorPluginContext,
   JSON = FlowDocumentJSON
 > extends PlaygroundReactProps<CTX> {
   /**
+   * Initialize data
    * 初始化数据
    */
   initialData?: JSON;
   /**
+   * whether it is readonly
    * 是否为 readonly
    */
   readonly?: boolean;
   /**
+   * node registries
    * 节点定义
    */
   nodeRegistries?: FlowNodeRegistry[];
   /**
-   * 获取默认的节点配置
+   * Get the default node registry, which will be merged with the 'nodeRegistries'
+   * 提供默认的节点注册，这个会和 nodeRegistries 做合并
    */
   getNodeDefaultRegistry?: (type: FlowNodeType) => FlowNodeRegistry;
   /**
-   * 节点引擎配置
+   * Node engine configuration
    */
   nodeEngine?: NodeCorePluginOptions & {
     /**
-     * 默认FormMeta
+     * Default formMeta
      */
     createDefaultFormMeta?: (node: FlowNodeEntity) => FormMetaOrFormMetaGenerator;
     /**
-     * 开启
+     * Enable node engine
      */
     enable?: boolean;
   };
   /**
+   * By default, all nodes are expanded
    * 默认是否展开所有节点
    */
   allNodesDefaultExpanded?: boolean;
   /**
-   * 画布物料
+   * Canvas material, Used to customize react components
+   * 画布物料, 用于自定义 react 组件
    */
   materials?: MaterialsPluginOptions;
   /**
@@ -79,18 +80,23 @@ export interface EditorProps<
   onLoad?: (ctx: CTX) => void;
   /**
    * 是否开启变量引擎
+   * Variable engine enable
    */
   variableEngine?: VariablePluginOptions;
   /**
-   * 是否开启历史
+   * Redo/Undo enable
    */
   history?: HistoryPluginOptions<CTX> & { disableShortcuts?: boolean };
 
   /**
-   * redux 开发者工具配置
+   * redux devtool configuration
    */
   reduxDevTool?: ReduxDevToolPluginOptions;
 
+  /**
+   * Scroll configuration
+   * 滚动配置
+   */
   scroll?: {
     enableScrollLimit?: boolean; // 开启滚动限制
     disableScrollBar?: boolean; //  关闭滚动条
@@ -98,31 +104,27 @@ export interface EditorProps<
   };
 
   /**
-   * 节点数据导出
-   * - node 当前节点
-   * - json 当前节点数据
+   * Node data transformation, called by ctx.document.fromJSON
+   * 节点数据转换, 由 ctx.document.fromJSON 调用
+   * @param node - current node
+   * @param json - Current node json data
    */
   toNodeJSON?(node: FlowNodeEntity, json: FlowNodeJSON): FlowNodeJSON;
   /**
-   * 节点数据导入
-   * - node 当前节点
-   * - json 当前节点数据
-   * - isFirstCreate 是否是第一次创建
+   * Node data transformation, called by ctx.document.toJSON
+   * 节点数据转换, 由 ctx.document.toJSON 调用
+   * @param node - current node
+   * @param json - Current node json data
+   * @param isFirstCreate - Whether it is created for the first time, If document.fromJSON is recalled, but the node already exists, isFirstCreate is false
    */
   fromNodeJSON?(node: FlowNodeEntity, json: FlowNodeJSON, isFirstCreate: boolean): FlowNodeJSON;
   /**
+   * Canvas internal constant customization
    * 画布内部常量自定义
    */
   constants?: Record<string, any>;
   /**
-   * 自定义节点线条
-   */
-  formatNodeLines?: (node: FlowNodeEntity, lines: FlowTransitionLine[]) => FlowTransitionLine[];
-  /**
-   * 自定义节点 label
-   */
-  formatNodeLabels?: (node: FlowNodeEntity, lines: FlowTransitionLabel[]) => FlowTransitionLabel[];
-  /**
+   * i18n
    * 国际化
    */
   i18n?: I18nPluginOptions;

packages/client/fixed-layout-editor/src/preset/fixed-layout-preset.ts

@@ -27,6 +27,7 @@ import {
   createPlaygroundReactPreset,
 } from '@flowgram.ai/editor';
 
+import { compose } from '../utils/compose';
 import { FlowOperationService } from '../types';
 import { createOperationPlugin } from '../plugins/create-operation-plugin';
 import { fromNodeJSON, toNodeJSON } from './node-serialize';
@@ -146,6 +147,20 @@ export function createFixedLayoutPreset(
             FlowNodesContentLayer, // 节点内容渲染
             FlowNodesTransformLayer // 节点位置偏移计算
           );
+          // 劫持节点线条
+          if (opts.formatNodeLines) {
+            ctx.document.options.formatNodeLines = compose([
+              ctx.document.options.formatNodeLines,
+              opts.formatNodeLines,
+            ]);
+          }
+          // 劫持节点 label
+          if (opts.formatNodeLabels) {
+            ctx.document.options.formatNodeLabels = compose([
+              ctx.document.options.formatNodeLabels,
+              opts.formatNodeLabels,
+            ]);
+          }
           if (opts.scroll?.enableScrollLimit) {
             // 控制滚动范围
             ctx.playground.registerLayer(FlowScrollLimitLayer);

packages/client/fixed-layout-editor/src/preset/fixed-layout-props.ts

@@ -15,6 +15,9 @@ import {
   FlowLayoutDefault,
   SelectionService,
   PluginContext,
+  FlowNodeEntity,
+  FlowTransitionLine,
+  FlowTransitionLabel,
 } from '@flowgram.ai/editor';
 
 import { FlowOperationService } from '../types';
@@ -36,10 +39,32 @@ export interface FixedLayoutPluginContext extends EditorPluginContext {
  * 固定布局配置
  */
 export interface FixedLayoutProps extends EditorProps<FixedLayoutPluginContext, FlowDocumentJSON> {
+  /**
+   * SelectBox config
+   */
   selectBox?: SelectBoxPluginOptions;
+  /**
+   * Drag/Drop config
+   */
   dragdrop?: FixDragPluginOptions<FixedLayoutPluginContext>;
+  /**
+   * Redo/Undo enable
+   */
   history?: FixedHistoryPluginOptions<FixedLayoutPluginContext> & { disableShortcuts?: boolean };
+  /**
+   * vertical or horizontal layout
+   */
   defaultLayout?: FlowLayoutDefault | string; // 默认布局
+  /**
+   * Customize the node line
+   * 自定义节点线条
+   */
+  formatNodeLines?: (node: FlowNodeEntity, lines: FlowTransitionLine[]) => FlowTransitionLine[];
+  /**
+   * Custom node label
+   * 自定义节点 label
+   */
+  formatNodeLabels?: (node: FlowNodeEntity, lines: FlowTransitionLabel[]) => FlowTransitionLabel[];
 }
 
 export namespace FixedLayoutProps {

packages/client/editor/src/utils/compose.ts → packages/client/fixed-layout-editor/src/utils/compose.ts

@@ -3,7 +3,7 @@
  * SPDX-License-Identifier: MIT
  */
 
-import { FlowNodeEntity } from '@flowgram.ai/document';
+import { FlowNodeEntity } from '@flowgram.ai/editor';
 
 export type ComposeListItem<T> = (node: FlowNodeEntity, data: T[]) => T[];
 

packages/client/free-layout-editor/src/preset/free-layout-props.ts

@@ -49,35 +49,49 @@ export interface FreeLayoutPluginContext extends EditorPluginContext {
 }
 
 /**
+ * Free layout configuration
  * 自由布局配置
  */
 export interface FreeLayoutProps extends EditorProps<FreeLayoutPluginContext, WorkflowJSON> {
+  /**
+   * SelectBox config
+   * 选择框定义
+   */
   selectBox?: SelectBoxPluginOptions;
   /**
-   * 节点定义
+   * Node registries
+   * 节点注册
    */
   nodeRegistries?: WorkflowNodeRegistry[];
   /**
+   * By default, all nodes are expanded
    * 默认是否展开所有节点
    */
   allNodesDefaultExpanded?: boolean;
   /*
-   * 光标图片
+   * Cursor configuration, support svg
+   * 光标图片, 支持 svg
    */
   cursors?: {
     grab?: string;
     grabbing?: string;
   };
+  /**
+   * History configuration
+   */
   history?: FreeHistoryPluginOptions<FreeLayoutPluginContext> & { disableShortcuts?: boolean };
   /**
+   * Line color configuration
    * 线条颜色
    */
   lineColor?: LineColor;
   /**
-   * 画布内容更新
+   * Listen for content change
+   * 监听画布内容更新
    */
   onContentChange?: (ctx: FreeLayoutPluginContext, event: WorkflowContentChangeEvent) => void;
   /**
+   * Determine whether the line is marked as error
    * 判断线条是否标红
    * @param ctx
    * @param fromPort
@@ -91,54 +105,63 @@ export interface FreeLayoutProps extends EditorProps<FreeLayoutPluginContext, Wo
     lines: WorkflowLinesManager
   ) => boolean;
   /**
+   * Determine whether the port is marked as error
    * 判断端口是否标红
    * @param ctx
    * @param port
    */
   isErrorPort?: (ctx: FreeLayoutPluginContext, port: WorkflowPortEntity) => boolean;
   /**
+   * Determine if the port is disabled
    * 判断端口是否禁用
    * @param ctx
    * @param port
    */
   isDisabledPort?: (ctx: FreeLayoutPluginContext, port: WorkflowPortEntity) => boolean;
   /**
+   * Determine whether the line arrow is reversed
    * 判断线条箭头是否反转
    * @param ctx
    * @param line
    */
   isReverseLine?: (ctx: FreeLayoutPluginContext, line: WorkflowLineEntity) => boolean;
   /**
+   * Determine if the line hides the arrow
    * 判断线条是否隐藏箭头
    * @param ctx
    * @param line
    */
   isHideArrowLine?: (ctx: FreeLayoutPluginContext, line: WorkflowLineEntity) => boolean;
   /**
+   * Determine whether the line shows a flow effect
    * 判断线条是否展示流动效果
    * @param ctx
    * @param line
    */
   isFlowingLine?: (ctx: FreeLayoutPluginContext, line: WorkflowLineEntity) => boolean;
   /**
+   * Determine if a line is disabled
    * 判断线条是否禁用
    * @param ctx
    * @param line
    */
   isDisabledLine?: (ctx: FreeLayoutPluginContext, line: WorkflowLineEntity) => boolean;
   /**
+   * Judge whether the line is vertical
    * 判断线条是否竖向
    * @param ctx
    * @param line
    */
   isVerticalLine?: (ctx: FreeLayoutPluginContext, line: WorkflowLineEntity) => boolean;
   /**
+   * Listen for dragging the line to end
    * 拖拽线条结束
    * @param ctx
    * @param params
    */
   onDragLineEnd?: (ctx: FreeLayoutPluginContext, params: onDragLineEndParams) => Promise<void>;
   /**
+   * Set the line renderer type
    * 设置线条渲染器类型
    * @param ctx
    * @param line
@@ -148,16 +171,18 @@ export interface FreeLayoutProps extends EditorProps<FreeLayoutPluginContext, Wo
     line: WorkflowLineEntity
   ) => LineRenderType | undefined;
   /**
+   * Set the line className
    * 设置线条样式
    * @param ctx
    * @param line
    */
   setLineClassName?: (ctx: FreeLayoutPluginContext, line: WorkflowLineEntity) => string | undefined;
   /**
+   * Whether to create lines or not
    * 是否允许创建线条
    * @param ctx
-   * @param fromPort - 开始点
-   * @param toPort - 目标点
+   * @param fromPort - Source port
+   * @param toPort - Target port
    */
   canAddLine?: (
     ctx: FreeLayoutPluginContext,
@@ -167,6 +192,7 @@ export interface FreeLayoutProps extends EditorProps<FreeLayoutPluginContext, Wo
     silent?: boolean
   ) => boolean;
   /**
+   * Whether to allow the deletion of nodes
    * 是否允许删除节点
    * @param ctx
    * @param node - 目标节点
@@ -179,11 +205,12 @@ export interface FreeLayoutProps extends EditorProps<FreeLayoutPluginContext, Wo
   ) => boolean;
   /**
    *
+   * Whether to delete lines or not
    * 是否允许删除线条
    * @param ctx
-   * @param line - 目标线条
-   * @param newLineInfo - 新的线条信息
-   * @param silent - 如果为false，可以加 toast 弹窗
+   * @param line - target line
+   * @param newLineInfo - new line info
+   * @param silent - If false, you can add a toast pop-up
    */
   canDeleteLine?: (
     ctx: FreeLayoutPluginContext,
@@ -192,11 +219,12 @@ export interface FreeLayoutProps extends EditorProps<FreeLayoutPluginContext, Wo
     silent?: boolean
   ) => boolean;
   /**
+   * Whether to allow lines to be reset
    * 是否允许重置线条
-   * @param fromPort - 开始点
-   * @param oldToPort - 旧的连接点
-   * @param newToPort - 新的连接点
-   * @param lines - 线条管理器
+   * @param fromPort - source port
+   * @param oldToPort - old target port
+   * @param newToPort - new target port
+   * @param lines - lines manager
    */
   canResetLine?: (
     ctx: FreeLayoutPluginContext,
@@ -206,8 +234,8 @@ export interface FreeLayoutProps extends EditorProps<FreeLayoutPluginContext, Wo
     lines: WorkflowLinesManager
   ) => boolean;
   /**
-   * 是否允许拖入子画布 (loop or group)
    * Whether to allow dragging into the sub-canvas (loop or group)
+   * 是否允许拖入子画布 (loop or group)
    * @param params
    */
   canDropToNode?: (

packages/plugins/fixed-drag-plugin/src/create-fixed-drag-plugin.ts

@@ -11,10 +11,18 @@ import { definePluginCreator, PluginContext } from '@flowgram.ai/core';
 
 export interface FixDragPluginOptions<CTX extends PluginContext = PluginContext> {
   enable?: boolean;
+  /**
+   * Callback when drag drop
+   */
   onDrop?: (ctx: CTX, dropData: { dragNodes: FlowNodeEntity[]; dropNode: FlowNodeEntity }) => void;
+  /**
+   * Check can drop
+   * @param ctx
+   * @param dropData
+   */
   canDrop?: (
     ctx: CTX,
-    dropData: { dragNodes: FlowNodeEntity[]; dropNode: FlowNodeEntity; isBranch?: boolean },
+    dropData: { dragNodes: FlowNodeEntity[]; dropNode: FlowNodeEntity; isBranch?: boolean }
   ) => boolean;
 }