feat(stack): support custom stack index (bytedance#892)

* fix(demo): comment node placeholder

* feat(stack): support custom stack index

* fix: test error

Author: louisyoungx

apps/demo-free-layout/package.json

@@ -45,6 +45,7 @@
     "@flowgram.ai/free-group-plugin": "workspace:*",
     "@flowgram.ai/form-materials": "workspace:*",
     "@flowgram.ai/panel-manager-plugin": "workspace:*",
+    "@flowgram.ai/free-stack-plugin": "workspace:*",
     "@flowgram.ai/runtime-js": "workspace:*",
     "lodash-es": "^4.17.21",
     "nanoid": "^5.0.9",

apps/demo-free-layout/src/components/comment/components/editor.tsx

@@ -8,6 +8,7 @@ import { type FC, type CSSProperties, useEffect, useRef } from 'react';
 import { usePlayground } from '@flowgram.ai/free-layout-editor';
 
 import { CommentEditorModel } from '../model';
+import { usePlaceholder } from '../hooks';
 import { CommentEditorEvent } from '../constant';
 
 interface ICommentEditor {
@@ -20,8 +21,8 @@ interface ICommentEditor {
 export const CommentEditor: FC<ICommentEditor> = (props) => {
   const { model, style, onChange } = props;
   const playground = usePlayground();
+  const placeholder = usePlaceholder({ model });
   const editorRef = useRef<HTMLTextAreaElement | null>(null);
-  const placeholder = model.value || model.focused ? undefined : 'Enter a comment...';
 
   // 同步编辑器内部值变化
   useEffect(() => {

apps/demo-free-layout/src/components/comment/hooks/index.ts

@@ -4,3 +4,4 @@
  */
 
 export { useSize } from './use-size';
+export { usePlaceholder } from './use-placeholder';

apps/demo-free-layout/src/components/comment/hooks/use-placeholder.ts

@@ -0,0 +1,34 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { useState, useEffect } from 'react';
+
+import { CommentEditorModel } from '../model';
+import { CommentEditorEvent } from '../constant';
+
+export const usePlaceholder = (params: { model: CommentEditorModel }): string | undefined => {
+  const { model } = params;
+
+  const [placeholder, setPlaceholder] = useState<string | undefined>('Enter a comment...');
+
+  // 监听 change 事件
+  useEffect(() => {
+    const changeDisposer = model.on((params) => {
+      if (params.type !== CommentEditorEvent.Change && params.type !== CommentEditorEvent.Init) {
+        return;
+      }
+      if (params.value) {
+        setPlaceholder(undefined);
+      } else {
+        setPlaceholder('Enter a comment...');
+      }
+    });
+    return () => {
+      changeDisposer.dispose();
+    };
+  }, [model]);
+
+  return placeholder;
+};

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

@@ -9,13 +9,15 @@ import { useMemo } from 'react';
 import { debounce } from 'lodash-es';
 import { createPanelManagerPlugin } from '@flowgram.ai/panel-manager-plugin';
 import { createMinimapPlugin } from '@flowgram.ai/minimap-plugin';
+import { createFreeStackPlugin } from '@flowgram.ai/free-stack-plugin';
 import { createFreeSnapPlugin } from '@flowgram.ai/free-snap-plugin';
 import { createFreeNodePanelPlugin } from '@flowgram.ai/free-node-panel-plugin';
 import { createFreeLinesPlugin } from '@flowgram.ai/free-lines-plugin';
 import {
   FlowNodeBaseType,
   FreeLayoutPluginContext,
   FreeLayoutProps,
+  WorkflowNodeEntity,
 } from '@flowgram.ai/free-layout-editor';
 import { createFreeGroupPlugin } from '@flowgram.ai/free-group-plugin';
 import { createContainerNodePlugin } from '@flowgram.ai/free-container-plugin';
@@ -274,6 +276,20 @@ export function useEditorProps(
         },
       },
       plugins: () => [
+        createFreeStackPlugin({
+          sortNodes: (nodes) => {
+            const commentNodes: WorkflowNodeEntity[] = [];
+            const otherNodes: WorkflowNodeEntity[] = [];
+            nodes.forEach((node) => {
+              if (node.flowNodeType === WorkflowNodeType.Comment) {
+                commentNodes.push(node);
+              } else {
+                otherNodes.push(node);
+              }
+            });
+            return [...commentNodes, ...otherNodes];
+          },
+        }),
         /**
          * Line render plugin
          * 连线渲染插件

common/config/rush/pnpm-lock.yaml

@@ -125,6 +125,7 @@ describe('StackingContextManager private methods', () => {
       hoveredEntityID: undefined,
       selectedIDs: new Set(),
       selectedNodes: [],
+      sortNodes: stackingContextManager.options.sortNodes,
     });
     hoverService.updateHoveredKey('start_0');
     const breakNode = document.getNode('break_0')!;

packages/plugins/free-stack-plugin/__tests__/manager.test.ts

@@ -13,7 +13,7 @@ import type {
 } from '@flowgram.ai/free-layout-core';
 import type { EntityManager, PipelineRegistry, PipelineRenderer } from '@flowgram.ai/core';
 
-import type { StackingContext } from '../src/type';
+import type { StackContextManagerOptions, StackingContext } from '../src/type';
 
 /** mock类型便于测试内部方法 */
 export interface IStackingContextManager {
@@ -25,6 +25,7 @@ export interface IStackingContextManager {
   selectService: WorkflowSelectService;
   node: HTMLDivElement;
   disposers: Disposable[];
+  options: StackContextManagerOptions;
   init(): void;
   ready(): void;
   dispose(): void;

packages/plugins/free-stack-plugin/__tests__/type.mock.ts

@@ -5,15 +5,17 @@
 
 import { definePluginCreator } from '@flowgram.ai/core';
 
+import { FreeStackPluginOptions } from './type';
 import { StackingContextManager } from './manager';
 
-export const createFreeStackPlugin = definePluginCreator({
+export const createFreeStackPlugin = definePluginCreator<FreeStackPluginOptions>({
+  singleton: true,
   onBind({ bind }) {
     bind(StackingContextManager).toSelf().inSingletonScope();
   },
-  onInit(ctx) {
+  onInit(ctx, options) {
     const stackingContextManager = ctx.get<StackingContextManager>(StackingContextManager);
-    stackingContextManager.init();
+    stackingContextManager.init(options);
   },
   onReady(ctx) {
     const stackingContextManager = ctx.get<StackingContextManager>(StackingContextManager);

packages/plugins/free-stack-plugin/src/create-free-stack-plugin.ts

@@ -17,7 +17,7 @@ import { WorkflowDocument } from '@flowgram.ai/free-layout-core';
 import { FlowNodeRenderData } from '@flowgram.ai/document';
 import { EntityManager, PipelineRegistry, PipelineRenderer } from '@flowgram.ai/core';
 
-import type { StackingContext } from './type';
+import type { StackContextManagerOptions, StackingContext } from './type';
 import { StackingComputing } from './stacking-computing';
 import { BASE_Z_INDEX } from './constant';
 
@@ -43,11 +43,16 @@ export class StackingContextManager {
     'gedit-playground-layer gedit-flow-render-layer'
   );
 
+  private options: StackContextManagerOptions = {
+    sortNodes: (nodes: WorkflowNodeEntity[]) => nodes,
+  };
+
   private disposers: Disposable[] = [];
 
   constructor() {}
 
-  public init(): void {
+  public init(options: Partial<StackContextManagerOptions> = {}): void {
+    this.options = { ...this.options, ...options };
     this.pipelineRenderer.node.appendChild(this.node);
     this.mountListener();
   }
@@ -116,6 +121,7 @@ export class StackingContextManager {
       hoveredEntityID: this.hoverService.someHovered?.id,
       selectedNodes: this.selectService.selectedNodes,
       selectedIDs: new Set(this.selectService.selection.map((entity) => entity.id)),
+      sortNodes: this.options.sortNodes,
     };
   }