feat(fixed-layout): slotPort -> slotBlock (#523)

* feat(fixed-layout): slotPort -> slotBlock

* feat(docs): add slote demo and docs

* feat(documnet): add isTypeOrtExtendType api

* feat(fixed-layout): change SLOT_LABEL_RENDER -> SLOT_ADDER

* feat(demo): add slot adder

apps/demo-fixed-layout-simple/src/components/slot-adder.tsx

@@ -0,0 +1,56 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { nanoid } from 'nanoid';
+import {
+  type FlowNodeEntity,
+  FlowNodeRenderData,
+  FlowDocument,
+  useService,
+} from '@flowgram.ai/fixed-layout-editor';
+import { Button } from '@douyinfe/semi-ui';
+import { IconPlus } from '@douyinfe/semi-icons';
+
+interface PropsType {
+  node: FlowNodeEntity;
+}
+
+export function SlotAdder(props: PropsType) {
+  const { node } = props;
+
+  const nodeData = node.firstChild?.getData<FlowNodeRenderData>(FlowNodeRenderData);
+  const document = useService(FlowDocument) as FlowDocument;
+
+  async function addPort() {
+    document.addNode({
+      id: nanoid(5),
+      type: 'custom',
+      parent: node,
+      data: {
+        title: 'Custom',
+        content: 'custom content',
+      },
+    });
+  }
+
+  return (
+    <div
+      style={{
+        display: 'flex',
+        background: 'var(--semi-color-bg-0)',
+      }}
+      onMouseEnter={() => nodeData?.toggleMouseEnter()}
+      onMouseLeave={() => nodeData?.toggleMouseLeave()}
+    >
+      <Button
+        onClick={() => {
+          addPort();
+        }}
+        size="small"
+        icon={<IconPlus />}
+      />
+    </div>
+  );
+}

apps/demo-fixed-layout-simple/src/data/index.ts

@@ -6,6 +6,7 @@
 import { FlowDocumentJSON, FlowLayoutDefault } from '@flowgram.ai/fixed-layout-editor';
 
 import { tryCatch } from './tryCatch';
+import { slot } from './slot';
 import { multiOutputs } from './multiOutputs';
 import { multiInputs } from './multiInputs';
 import { mindmap } from './mindmap';
@@ -21,4 +22,5 @@ export const FLOW_LIST: Record<string, FlowDocumentJSON & { defaultLayout?: Flow
   loop,
   multiInputs,
   multiOutputs,
+  slot,
 };

apps/demo-fixed-layout-simple/src/data/slot.ts

@@ -0,0 +1,102 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { FlowDocumentJSON } from '@flowgram.ai/fixed-layout-editor';
+
+export const slot: FlowDocumentJSON = {
+  nodes: [
+    // 开始节点
+    {
+      id: 'start_0',
+      type: 'start',
+      data: {
+        title: 'Start',
+        content: 'start content',
+      },
+      blocks: [],
+    },
+    {
+      id: 'slot_0',
+      type: 'slot',
+      data: {
+        title: 'Slot',
+        content: 'Slot content',
+      },
+      blocks: [
+        {
+          id: 'slot_port_1',
+          type: 'slotBlock',
+          data: {
+            title: 'Slot 1',
+            content: 'slot 1 content',
+          },
+          blocks: [
+            {
+              id: 'custom_1',
+              type: 'custom',
+              data: {
+                title: 'Custom',
+                content: 'custom content',
+              },
+            },
+          ],
+        },
+        {
+          id: 'slot_port_2',
+          type: 'slotBlock',
+          data: {
+            title: 'Slot 2',
+            content: 'slot 2 content',
+          },
+          blocks: [
+            {
+              id: 'custom_2',
+              type: 'custom',
+              data: {
+                title: 'Custom',
+                content: 'custom content',
+              },
+            },
+          ],
+        },
+        {
+          id: 'slot_port_3',
+          type: 'slotBlock',
+          data: {
+            title: 'Slot 3',
+            content: 'slot 3 content',
+          },
+          blocks: [
+            {
+              id: 'custom_3',
+              type: 'custom',
+              data: {
+                title: 'Custom',
+                content: 'custom content',
+              },
+            },
+            {
+              id: 'custom_4',
+              type: 'custom',
+              data: {
+                title: 'Custom',
+                content: 'custom content',
+              },
+            },
+          ],
+        },
+      ],
+    },
+    // 结束节点
+    {
+      id: 'end_0',
+      type: 'end',
+      data: {
+        title: 'End',
+        content: 'end content',
+      },
+    },
+  ],
+};

apps/demo-fixed-layout-simple/src/data/slots.ts

@@ -1,5 +0,0 @@
-/**
- * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
- * SPDX-License-Identifier: MIT
- */
-

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

@@ -16,6 +16,7 @@ import {
   FlowTextKey,
 } from '@flowgram.ai/fixed-layout-editor';
 
+import { SlotAdder } from '../components/slot-adder';
 import { NodeAdder } from '../components/node-adder';
 import { BranchAdder } from '../components/branch-adder';
 import { BaseNode } from '../components/base-node';
@@ -88,6 +89,7 @@ export function useEditorProps(
            */
           [FlowRendererKey.ADDER]: NodeAdder,
           [FlowRendererKey.BRANCH_ADDER]: BranchAdder,
+          [FlowRendererKey.SLOT_ADDER]: SlotAdder,
           // [FlowRendererKey.DRAG_NODE]: DragNode,
         },
         renderDefaultNode: BaseNode, // 节点渲染

apps/demo-fixed-layout/src/components/agent-label/index.tsx → apps/demo-fixed-layout/src/components/agent-adder/index.tsx

@@ -20,7 +20,7 @@ interface PropsType {
   node: FlowNodeEntity;
 }
 
-export function AgentLabel(props: PropsType) {
+export function AgentAdder(props: PropsType) {
   const { node } = props;
 
   const nodeData = node.firstChild?.getData<FlowNodeRenderData>(FlowNodeRenderData);

apps/demo-fixed-layout/src/components/index.ts

@@ -5,4 +5,4 @@
 
 export { DemoTools } from './tools';
 export { DragNode } from './drag-node';
-export { AgentLabel } from './agent-label';
+export { AgentAdder } from './agent-adder';

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

@@ -27,7 +27,7 @@ import { SelectorBoxPopover } from '../components/selector-box-popover';
 import NodeAdder from '../components/node-adder';
 import BranchAdder from '../components/branch-adder';
 import { BaseNode } from '../components/base-node';
-import { DragNode, AgentLabel } from '../components';
+import { DragNode, AgentAdder } from '../components';
 
 export function useEditorProps(
   initialData: FlowDocumentJSON,
@@ -174,7 +174,7 @@ export function useEditorProps(
           [FlowRendererKey.ADDER]: NodeAdder, // Node Add Button
           [FlowRendererKey.BRANCH_ADDER]: BranchAdder, // Branch Add Button
           [FlowRendererKey.DRAG_NODE]: DragNode, // Component in node dragging
-          [FlowRendererKey.SLOT_LABEL_RENDER]: AgentLabel, // Agent Label
+          [FlowRendererKey.SLOT_ADDER]: AgentAdder, // Agent adder
         },
         renderDefaultNode: BaseNode, // node render
         renderTexts: {

apps/demo-fixed-layout/src/nodes/agent/agent-llm.ts

@@ -9,7 +9,7 @@ import { FlowNodeRegistry } from '../../typings';
 
 export const AgentLLMNodeRegistry: FlowNodeRegistry = {
   type: 'agentLLM',
-  extend: FlowNodeBaseType.SLOT_PORT,
+  extend: FlowNodeBaseType.SLOT_BLOCK,
   meta: {
     addDisable: true,
     sidebarDisable: true,

apps/demo-fixed-layout/src/nodes/agent/agent-memory.ts

@@ -9,7 +9,7 @@ import { FlowNodeRegistry } from '../../typings';
 
 export const AgentMemoryNodeRegistry: FlowNodeRegistry = {
   type: 'agentMemory',
-  extend: FlowNodeBaseType.SLOT_PORT,
+  extend: FlowNodeBaseType.SLOT_BLOCK,
   meta: {
     addDisable: true,
     sidebarDisable: true,

apps/demo-fixed-layout/src/nodes/agent/agent-tools.ts

@@ -11,7 +11,7 @@ import { FlowNodeRegistry } from '../../typings';
 let index = 0;
 export const AgentToolsNodeRegistry: FlowNodeRegistry = {
   type: 'agentTools',
-  extend: FlowNodeBaseType.SLOT_PORT,
+  extend: FlowNodeBaseType.SLOT_BLOCK,
   info: {
     icon: '',
     description: 'Agent Tools.',

apps/docs/components/fixed-layout-simple/composite-nodes-preview.tsx

@@ -8,6 +8,7 @@ import { FixedLayoutSimple } from './fixed-layout-simple.tsx';
 import { PreviewEditor } from '../preview-editor.tsx';
 
 import tryCatch from '!!raw-loader!@flowgram.ai/demo-fixed-layout-simple/src/data/tryCatch.ts';
+import slot from '!!raw-loader!@flowgram.ai/demo-fixed-layout-simple/src/data/slot.ts';
 import multiOutputs from '!!raw-loader!@flowgram.ai/demo-fixed-layout-simple/src/data/multiOutputs.ts';
 import multiInputs from '!!raw-loader!@flowgram.ai/demo-fixed-layout-simple/src/data/multiInputs.ts';
 import loop from '!!raw-loader!@flowgram.ai/demo-fixed-layout-simple/src/data/loop.ts';
@@ -144,6 +145,31 @@ export function CompositeNodesPreview(props: { cellHeight?: number }) {
           </PreviewEditor>
         </td>
       </tr>
+      <tr>
+        <td style={{ textAlign: 'center' }}>slot</td>
+        <td>
+          <PreviewEditor
+            codeInRight
+            files={{
+              'index.tsx': {
+                code: slot,
+                active: true,
+              },
+            }}
+            previewStyle={{
+              width: previewWidth,
+              height: cellHeight,
+              position: 'relative',
+            }}
+            editorStyle={{
+              height: cellHeight,
+              width: editorWidth,
+            }}
+          >
+            <FixedLayoutSimple hideTools demo="slot" />
+          </PreviewEditor>
+        </td>
+      </tr>
     </table>
   );
 }

packages/canvas-engine/document/__tests__/flow-node-registry.spec.ts

@@ -80,6 +80,8 @@ describe('flow-node-registry', () => {
     expect(doc.isExtend('c', 'dynamicSplit')).toBeTruthy();
     expect(doc.isExtend('c', 'b')).toBeTruthy();
     expect(doc.isExtend('c', 'a')).toBeTruthy();
+    expect(doc.isTypeOrExtendType('dynamicSplit', 'dynamicSplit')).toBeTruthy();
+    expect(doc.isTypeOrExtendType('c', 'a')).toBeTruthy();
   });
   it('base extend', () => {
     expect(doc.getNodeRegistry('a').onAdd).toBeTypeOf('function');

packages/canvas-engine/document/src/entities/flow-node-entity.ts

@@ -390,11 +390,19 @@ export class FlowNodeEntity extends Entity<FlowNodeEntityConfig> {
   }
 
   /**
-   * Check node extend
+   * Check node extend type
    */
-  isExtend(parentType: string): boolean {
+  isExtend(parentType: FlowNodeType): boolean {
     return this.document.isExtend(this.flowNodeType, parentType);
   }
+
+  /**
+   * Check node type
+   * @param parentType
+   */
+  isTypeOrExtendType(parentType: FlowNodeType): boolean {
+    return this.document.isTypeOrExtendType(this.flowNodeType, parentType);
+  }
 }
 
 export namespace FlowNodeEntity {

packages/canvas-engine/document/src/flow-document.ts

@@ -443,10 +443,19 @@ export class FlowDocument<T = FlowDocumentJSON> implements Disposable {
   /**
    * Check node extend
    * @param currentType
-   * @param parentType
+   * @param extendType
    */
-  isExtend(currentType: FlowNodeType, parentType: FlowNodeType): boolean {
-    return (this.getNodeRegistry(currentType).__extends__ || []).includes(parentType);
+  isExtend(currentType: FlowNodeType, extendType: FlowNodeType): boolean {
+    return (this.getNodeRegistry(currentType).__extends__ || []).includes(extendType);
+  }
+
+  /**
+   * Check node type
+   * @param currentType
+   * @param extendType
+   */
+  isTypeOrExtendType(currentType: FlowNodeType, extendType: FlowNodeType): boolean {
+    return currentType === extendType || this.isExtend(currentType, extendType);
   }
 
   /**

packages/canvas-engine/document/src/typings/flow.ts

@@ -42,7 +42,7 @@ export enum FlowNodeBaseType {
   INPUT = 'input', // 输入节点
   OUTPUT = 'output', // 输出节点
   SLOT = 'slot', // 插槽节点
-  SLOT_PORT = 'slotPort', // 插槽端口节点
+  SLOT_BLOCK = 'slotBlock', // 插槽子节点
 }
 
 export enum FlowNodeSplitType {

packages/canvas-engine/fixed-layout-core/src/activities/slot/constants.ts

@@ -5,13 +5,13 @@
 
 import { FlowRendererKey } from '@flowgram.ai/renderer';
 
-export const RENDER_SLOT_LABEL_KEY = FlowRendererKey.SLOT_LABEL_RENDER;
-export const RENDER_SLOT_COLLAPSE_KEY = FlowRendererKey.SLOT_COLLPASE_RENDER;
+export const RENDER_SLOT_ADDER_KEY = FlowRendererKey.SLOT_ADDER;
+export const RENDER_SLOT_COLLAPSE_KEY = FlowRendererKey.SLOT_COLLPASE;
 
-export const SLOT_PORT_DISTANCE = 60;
+export const SLOT_BLOCK_DISTANCE = 60;
 export const SLOT_COLLAPSE_MARGIN = 20;
 export const SLOT_SPACING = 32;
 
 export const SLOT_NODE_LAST_SPACING = 10;
 
-export const SLOT_INLINE_BLOCKS_DELTA = SLOT_COLLAPSE_MARGIN + SLOT_PORT_DISTANCE * 2;
+export const SLOT_INLINE_BLOCKS_DELTA = SLOT_COLLAPSE_MARGIN + SLOT_BLOCK_DISTANCE * 2;

packages/canvas-engine/fixed-layout-core/src/activities/slot/extends/index.ts

@@ -5,4 +5,4 @@
 
 export { SlotIconRegistry } from './slot-icon';
 export { SlotInlineBlocksRegistry } from './slot-inline-blocks';
-export { SlotPortRegistry } from './slot-port';
+export { SlotBlockRegistry } from './slot-block';

packages/canvas-engine/fixed-layout-core/src/activities/slot/extends/slot-port.ts → packages/canvas-engine/fixed-layout-core/src/activities/slot/extends/slot-block.ts

@@ -14,10 +14,10 @@ import { FlowNodeTransformData } from '@flowgram.ai/document';
 
 import { getPortChildInput, getSlotChildLineStartPoint } from '../utils/transition';
 import { SlotNodeType } from '../typings';
-import { SLOT_PORT_DISTANCE, RENDER_SLOT_LABEL_KEY } from '../constants';
+import { SLOT_BLOCK_DISTANCE, RENDER_SLOT_ADDER_KEY } from '../constants';
 
-export const SlotPortRegistry: FlowNodeRegistry = {
-  type: SlotNodeType.SlotPort,
+export const SlotBlockRegistry: FlowNodeRegistry = {
+  type: SlotNodeType.SlotBlock,
   extend: FlowNodeBaseType.BLOCK,
   meta: {
     inlineSpacingAfter: 0,
@@ -69,7 +69,7 @@ export const SlotPortRegistry: FlowNodeRegistry = {
     return [
       {
         type: FlowTransitionLabelEnum.CUSTOM_LABEL,
-        renderKey: RENDER_SLOT_LABEL_KEY,
+        renderKey: RENDER_SLOT_ADDER_KEY,
         props: {
           node: transition.entity,
         },
@@ -90,7 +90,7 @@ export const SlotPortRegistry: FlowNodeRegistry = {
     }
 
     return {
-      x: start.x + SLOT_PORT_DISTANCE,
+      x: start.x + SLOT_BLOCK_DISTANCE,
       y: inputY,
     };
   },

packages/canvas-engine/fixed-layout-core/src/activities/slot/extends/slot-inline-blocks.ts

@@ -7,7 +7,7 @@ import { FlowNodeRegistry, FlowNodeBaseType } from '@flowgram.ai/document';
 import { FlowNodeTransformData } from '@flowgram.ai/document';
 
 import { SlotNodeType } from '../typings';
-import { SLOT_COLLAPSE_MARGIN, SLOT_INLINE_BLOCKS_DELTA, SLOT_PORT_DISTANCE } from '../constants';
+import { SLOT_COLLAPSE_MARGIN, SLOT_INLINE_BLOCKS_DELTA, SLOT_BLOCK_DISTANCE } from '../constants';
 
 export const SlotInlineBlocksRegistry: FlowNodeRegistry = {
   type: SlotNodeType.SlotInlineBlocks,
@@ -60,12 +60,12 @@ export const SlotInlineBlocksRegistry: FlowNodeRegistry = {
        */
       if (noChildren) {
         return {
-          x: SLOT_PORT_DISTANCE - icon.localBounds.width / 2,
+          x: SLOT_BLOCK_DISTANCE - icon.localBounds.width / 2,
           y: icon.localBounds.bottom + SLOT_COLLAPSE_MARGIN,
         };
       }
       return {
-        x: 2 * SLOT_PORT_DISTANCE - icon.localBounds.width / 2,
+        x: 2 * SLOT_BLOCK_DISTANCE - icon.localBounds.width / 2,
         y: icon.localBounds.bottom + SLOT_COLLAPSE_MARGIN,
       };
     }

packages/canvas-engine/fixed-layout-core/src/activities/slot/index.ts

@@ -4,4 +4,4 @@
  */
 
 export { SlotRegistry } from './slot';
-export { SlotPortRegistry } from './extends';
+export { SlotBlockRegistry } from './extends';

packages/canvas-engine/fixed-layout-core/src/activities/slot/typings.ts

@@ -7,7 +7,7 @@ import { FlowNodeBaseType } from '@flowgram.ai/document';
 
 export enum SlotNodeType {
   Slot = FlowNodeBaseType.SLOT,
-  SlotPort = FlowNodeBaseType.SLOT_PORT,
+  SlotBlock = FlowNodeBaseType.SLOT_BLOCK,
   SlotInlineBlocks = 'slotInlineBlocks',
-  SlotPortInlineBlocks = 'slotPortInlineBlocks',
+  SlotBlockInlineBlocks = 'slotBlockInlineBlocks',
 }

packages/canvas-engine/fixed-layout-core/src/activities/slot/utils/create.ts

@@ -35,11 +35,11 @@ import { SlotNodeType } from '../typings';
  * - Slot
  *  - SlotBlockIcon
  *  - SlotInlineBlocks
- *    - SlotPort 1
- *        - SlotPortIcon 1
+ *    - SlotBlock 1
+ *        - SlotBlockIcon 1
  *          - ChildSlot 1
  *          - ChildSlot 2
- *    - SlotPort 2
+ *    - SlotBlock 2
  *
  * 范例数据：
  * {
@@ -82,7 +82,7 @@ export const createSlotFromJSON = (node: FlowNodeEntity, json: FlowNodeJSON): Fl
 
   portJSONList.forEach((_portJSON) => {
     const port = document.addNode({
-      type: SlotNodeType.SlotPort,
+      type: SlotNodeType.SlotBlock,
       ..._portJSON,
       originParent: node,
       parent: inlineBlocksNode,

packages/canvas-engine/fixed-layout-core/src/activities/slot/utils/node.ts

@@ -21,7 +21,7 @@ export const canSlotDrilldown = (Slot: FlowNodeEntity): boolean =>
  * @returns
  */
 export const insideSlot = (entity?: FlowNodeEntity): boolean =>
-  !!entity?.parent?.isExtend(SlotNodeType.SlotPort);
+  !!entity?.parent?.isTypeOrExtendType(SlotNodeType.SlotBlock);
 
 /**
  * 获取在页面上实际渲染的第一个 Child 节点

packages/canvas-engine/fixed-layout-core/src/flow-registers.ts

@@ -41,7 +41,7 @@ import {
   InputRegistry,
   OuputRegistry,
   SlotRegistry,
-  SlotPortRegistry,
+  SlotBlockRegistry,
 } from './activities';
 
 @injectable()
@@ -76,7 +76,7 @@ export class FlowRegisters
       InputRegistry,
       OuputRegistry,
       SlotRegistry,
-      SlotPortRegistry
+      SlotBlockRegistry
     );
     /**
      * 注册节点数据 (ECS - Component)

packages/canvas-engine/renderer/src/flow-renderer-registry.ts

@@ -29,8 +29,8 @@ export enum FlowRendererKey {
   CONTEXT_MENU_POPOVER = 'context-menu-popover', // 右键菜单
   SUB_CANVAS = 'sub-canvas', // 子画布渲染
 
-  SLOT_LABEL_RENDER = 'slot-label-render', // 插槽端口渲染
-  SLOT_COLLPASE_RENDER = 'slot-collapse-render', // 插槽收起按钮渲染
+  SLOT_ADDER = 'slot-adder', // 插槽添加按钮
+  SLOT_COLLPASE = 'slot-collapse', // 插槽收起按钮渲染
 
   // 工作流线条箭头自定义渲染
   ARROW_RENDERER = 'arrow-renderer', // 工作流线条箭头渲染器

packages/materials/fixed-semi-materials/src/components/index.tsx

@@ -7,8 +7,8 @@ import { FlowRendererKey } from '@flowgram.ai/fixed-layout-editor';
 
 import { Ellipse } from '../assets';
 import TryCatchCollapse from './try-catch-collapse';
-import { SlotLabel } from './slot-label';
 import { SlotCollapse } from './slot-collapse';
+import { SlotAdder } from './slot-adder';
 import DraggingAdder from './dragging-adder';
 import DragNode from './drag-node';
 import DragHighlightAdder from './drag-highlight-adder';
@@ -25,6 +25,6 @@ export const defaultFixedSemiMaterials = {
   [FlowRendererKey.DRAGGABLE_ADDER]: DraggingAdder,
   [FlowRendererKey.DRAG_HIGHLIGHT_ADDER]: DragHighlightAdder,
   [FlowRendererKey.DRAG_BRANCH_HIGHLIGHT_ADDER]: Ellipse,
-  [FlowRendererKey.SLOT_COLLPASE_RENDER]: SlotCollapse,
-  [FlowRendererKey.SLOT_LABEL_RENDER]: SlotLabel,
+  [FlowRendererKey.SLOT_COLLPASE]: SlotCollapse,
+  [FlowRendererKey.SLOT_ADDER]: SlotAdder,
 };

packages/materials/fixed-semi-materials/src/components/slot-label.tsx → packages/materials/fixed-semi-materials/src/components/slot-adder.tsx

@@ -19,7 +19,7 @@ interface PropsType {
   node: FlowNodeEntity;
 }
 
-export function SlotLabel(props: PropsType) {
+export function SlotAdder(props: PropsType) {
   const { node } = props;
 
   const nodeData = node.firstChild?.getData<FlowNodeRenderData>(FlowNodeRenderData);