feat(docs): composite nodes docs (#265)

* feat(docs): add composite nodes docs

* feat(docs): source code link

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

@@ -0,0 +1,45 @@
+import { FlowDocumentJSON } from '@flowgram.ai/fixed-layout-editor';
+
+export const dynamicSplit: FlowDocumentJSON = {
+  nodes: [
+    {
+      id: 'start_0',
+      type: 'start',
+      data: {
+        title: 'Start',
+      },
+      blocks: [],
+    },
+    {
+      id: 'dynamicSplit_0',
+      type: 'dynamicSplit',
+      data: {
+        title: 'DynamicSplit',
+      },
+      blocks: [
+        {
+          id: 'branch_0',
+          type: 'block',
+          data: {
+            title: 'Branch 0',
+          },
+        },
+        {
+          id: 'branch_1',
+          type: 'block',
+          data: {
+            title: 'Branch 1',
+          },
+          blocks: [],
+        },
+      ],
+    },
+    {
+      id: 'end_0',
+      type: 'end',
+      data: {
+        title: 'End',
+      },
+    },
+  ],
+};

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

@@ -1,11 +1,19 @@
 import { FlowDocumentJSON, FlowLayoutDefault } from '@flowgram.ai/fixed-layout-editor';
 
-import { tryCatch } from './trycatch';
+import { tryCatch } from './tryCatch';
+import { multiOutputs } from './multiOutputs';
+import { multiInputs } from './multiInputs';
 import { mindmap } from './mindmap';
+import { loop } from './loop';
+import { dynamicSplit } from './dynamicSplit';
 import { condition } from './condition';
 
 export const FLOW_LIST: Record<string, FlowDocumentJSON & { defaultLayout?: FlowLayoutDefault }> = {
   condition,
   mindmap: { ...mindmap, defaultLayout: FlowLayoutDefault.HORIZONTAL_FIXED_LAYOUT },
   tryCatch,
+  dynamicSplit,
+  loop,
+  multiInputs,
+  multiOutputs,
 };

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

@@ -0,0 +1,46 @@
+import { FlowDocumentJSON } from '@flowgram.ai/fixed-layout-editor';
+
+export const loop: FlowDocumentJSON = {
+  nodes: [
+    {
+      id: 'start_0',
+      type: 'start',
+      data: {
+        title: 'Start',
+      },
+      blocks: [],
+    },
+    {
+      id: 'loop_0',
+      type: 'loop',
+      data: {
+        title: 'Loop',
+      },
+      blocks: [
+        {
+          id: 'branch_0',
+          type: 'block',
+          data: {
+            title: 'Branch 0',
+          },
+          blocks: [
+            {
+              id: 'custom',
+              type: 'custom',
+              data: {
+                title: 'Custom',
+              },
+            },
+          ],
+        },
+      ],
+    },
+    {
+      id: 'end_0',
+      type: 'end',
+      data: {
+        title: 'End',
+      },
+    },
+  ],
+};

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

@@ -27,26 +27,6 @@ export const mindmap: FlowDocumentJSON = {
             title: 'input_3',
           },
         },
-        // {
-        //   id: 'multiInputs_2',
-        //   type: 'multiInputs',
-        //   blocks: [
-        //     {
-        //       id: 'input_2',
-        //       type: 'input',
-        //       data: {
-        //         title: 'input_2'
-        //       },
-        //     },
-        //     {
-        //       id: 'input',
-        //       type: 'input_3',
-        //       data: {
-        //         title: 'input_3'
-        //       },
-        //     }
-        //   ],
-        // },
       ],
     },
     {

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

@@ -0,0 +1,40 @@
+import { FlowDocumentJSON } from '@flowgram.ai/fixed-layout-editor';
+
+export const multiInputs: FlowDocumentJSON = {
+  nodes: [
+    {
+      id: 'multiInputs_0',
+      type: 'multiInputs',
+      blocks: [
+        {
+          id: 'input_0',
+          type: 'input',
+          data: {
+            title: 'input_0',
+          },
+        },
+        {
+          id: 'input_1',
+          type: 'input',
+          data: {
+            title: 'input_1',
+          },
+        },
+        {
+          id: 'input_3',
+          type: 'input',
+          data: {
+            title: 'input_3',
+          },
+        },
+      ],
+    },
+    {
+      id: 'end_0',
+      type: 'end',
+      data: {
+        title: 'End',
+      },
+    },
+  ],
+};

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

@@ -0,0 +1,44 @@
+import { FlowDocumentJSON } from '@flowgram.ai/fixed-layout-editor';
+
+export const multiOutputs: FlowDocumentJSON = {
+  nodes: [
+    {
+      id: 'start_0',
+      type: 'start',
+      data: {
+        title: 'Start',
+      },
+      blocks: [],
+    },
+    {
+      id: 'multiOutputs_0',
+      type: 'multiOutputs',
+      data: {
+        title: 'MultiOutputs',
+      },
+      blocks: [
+        {
+          id: 'output_0',
+          type: 'output',
+          data: {
+            title: 'output_0',
+          },
+        },
+        {
+          id: 'output_1',
+          type: 'output',
+          data: {
+            title: 'output_1',
+          },
+        },
+        {
+          id: 'output_2',
+          type: 'output',
+          data: {
+            title: 'output_2',
+          },
+        },
+      ],
+    },
+  ],
+};

apps/demo-fixed-layout-simple/src/data/trycatch.ts → apps/demo-fixed-layout-simple/src/data/tryCatch.ts

@@ -2,17 +2,14 @@ import { FlowDocumentJSON } from '@flowgram.ai/fixed-layout-editor';
 
 export const tryCatch: FlowDocumentJSON = {
   nodes: [
-    // 开始节点
     {
       id: 'start_0',
       type: 'start',
       data: {
         title: 'Start',
-        content: 'start content',
       },
       blocks: [],
     },
-    // 分支节点
     {
       id: 'tryCatch_0',
       type: 'tryCatch',
@@ -43,13 +40,11 @@ export const tryCatch: FlowDocumentJSON = {
         },
       ],
     },
-    // 结束节点
     {
       id: 'end_0',
       type: 'end',
       data: {
         title: 'End',
-        content: 'end content',
       },
     },
   ],

apps/demo-fixed-layout-simple/src/editor.tsx

@@ -11,9 +11,9 @@ import { Tools } from './components/tools';
 import { Minimap } from './components/minimap';
 import { FlowSelect } from './components/flow-select';
 
-export const Editor = (props: { demoKey?: string }) => {
+export const Editor = (props: { demo?: string; hideTools?: boolean }) => {
   const editorProps = useEditorProps(
-    props.demoKey ? FLOW_LIST[props.demoKey] : initialData,
+    props.demo ? FLOW_LIST[props.demo] : initialData,
     nodeRegistries
   );
   return (
@@ -21,9 +21,13 @@ export const Editor = (props: { demoKey?: string }) => {
       <div className="demo-fixed-container">
         <EditorRenderer>{/* add child panel here */}</EditorRenderer>
       </div>
-      <Tools />
-      <FlowSelect />
-      <Minimap />
+      {!props.hideTools ? (
+        <>
+          <Tools />
+          <FlowSelect />
+          <Minimap />
+        </>
+      ) : null}
     </FixedLayoutEditorProvider>
   );
 };

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

@@ -117,6 +117,14 @@ export function useEditorProps(
         // ctx.document.fromJSON(initialData)
         console.log('---- Playground Init ----');
       },
+      /**
+       * Playground render
+       */
+      onAllLayersRendered: (ctx) => {
+        setTimeout(() => {
+          ctx.playground.config.fitView(ctx.document.root.bounds.pad(30));
+        }, 10);
+      },
       /**
        * Playground dispose
        * 画布销毁

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

@@ -0,0 +1,143 @@
+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 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';
+import dynamicSplit from '!!raw-loader!@flowgram.ai/demo-fixed-layout-simple/src/data/dynamicSplit.ts';
+
+export function CompositeNodesPreview(props: { cellHeight?: number }) {
+  const previewWidth = '50%';
+  const editorWidth = '50%';
+  const cellHeight = props.cellHeight || 300;
+  return (
+    <table className="" style={{ width: '100%', border: '1px solid var(--rp-c-divider-light)' }}>
+      <tr>
+        <td style={{ textAlign: 'center' }}>dynamicSplit</td>
+        <td>
+          <PreviewEditor
+            codeInRight
+            files={{
+              'index.tsx': {
+                code: dynamicSplit,
+                active: true,
+              },
+            }}
+            previewStyle={{
+              width: previewWidth,
+              height: cellHeight,
+              position: 'relative',
+            }}
+            editorStyle={{
+              width: editorWidth,
+              height: cellHeight,
+            }}
+          >
+            <FixedLayoutSimple hideTools demo="dynamicSplit" />
+          </PreviewEditor>
+        </td>
+      </tr>
+      <tr>
+        <td style={{ textAlign: 'center' }}>loop</td>
+        <td>
+          <PreviewEditor
+            codeInRight
+            files={{
+              'index.tsx': {
+                code: loop,
+                active: true,
+              },
+            }}
+            previewStyle={{
+              width: previewWidth,
+              height: cellHeight,
+              position: 'relative',
+            }}
+            editorStyle={{
+              height: cellHeight,
+              width: editorWidth,
+            }}
+          >
+            <FixedLayoutSimple hideTools demo="loop" />
+          </PreviewEditor>
+        </td>
+      </tr>
+      <tr>
+        <td style={{ textAlign: 'center' }}>tryCatch</td>
+        <td>
+          <PreviewEditor
+            codeInRight
+            files={{
+              'index.tsx': {
+                code: tryCatch,
+                active: true,
+              },
+            }}
+            previewStyle={{
+              width: previewWidth,
+              height: cellHeight,
+              position: 'relative',
+            }}
+            editorStyle={{
+              height: cellHeight,
+              width: editorWidth,
+            }}
+          >
+            <FixedLayoutSimple hideTools demo="tryCatch" />
+          </PreviewEditor>
+        </td>
+      </tr>
+      <tr>
+        <td style={{ textAlign: 'center' }}>multiInputs</td>
+        <td>
+          <PreviewEditor
+            codeInRight
+            files={{
+              'index.tsx': {
+                code: multiInputs,
+                active: true,
+              },
+            }}
+            previewStyle={{
+              width: previewWidth,
+              height: cellHeight,
+              position: 'relative',
+            }}
+            editorStyle={{
+              height: cellHeight,
+              width: editorWidth,
+            }}
+          >
+            <FixedLayoutSimple hideTools demo="multiInputs" />
+          </PreviewEditor>
+        </td>
+      </tr>
+      <tr>
+        <td style={{ textAlign: 'center' }}>multiOutputs</td>
+        <td>
+          <PreviewEditor
+            codeInRight
+            files={{
+              'index.tsx': {
+                code: multiOutputs,
+                active: true,
+              },
+            }}
+            previewStyle={{
+              width: previewWidth,
+              height: cellHeight,
+              position: 'relative',
+            }}
+            editorStyle={{
+              height: cellHeight,
+              width: editorWidth,
+            }}
+          >
+            <FixedLayoutSimple hideTools demo="multiOutputs" />
+          </PreviewEditor>
+        </td>
+      </tr>
+    </table>
+  );
+}

apps/docs/components/fixed-layout-simple/fixed-layout-simple.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+
+// https://github.com/web-infra-dev/rspress/issues/553
+const FixedLayoutSimple = React.lazy(() =>
+  import('@flowgram.ai/demo-fixed-layout-simple').then((module) => ({
+    default: module.DemoFixedLayout,
+  }))
+);
+
+export { FixedLayoutSimple };

apps/docs/components/fixed-layout-simple/index.tsx

@@ -1,10 +1,2 @@
-import React from 'react';
-
-// https://github.com/web-infra-dev/rspress/issues/553
-const FixedLayoutSimple = React.lazy(() =>
-  import('@flowgram.ai/demo-fixed-layout-simple').then((module) => ({
-    default: module.DemoFixedLayout,
-  }))
-);
-
-export { FixedLayoutSimple };
+export { FixedLayoutSimple } from './fixed-layout-simple.tsx';
+export { CompositeNodesPreview } from './composite-nodes-preview.tsx';

apps/docs/components/free-layout-simple/preview.tsx

@@ -11,7 +11,10 @@ import minimapCode from '!!raw-loader!@flowgram.ai/demo-free-layout-simple/src/c
 
 export const FreeLayoutSimplePreview = () => {
   const files = {
-    'editor.tsx': editorCode,
+    'editor.tsx': {
+      active: true,
+      code: editorCode,
+    },
     'use-editor-props.tsx': useEditorPropsCode,
     'initial-data.ts': dataCode,
     'node-registries.ts': nodeRegistriesCode,

apps/docs/components/index.ts

@@ -3,6 +3,6 @@ export { FixedFeatureOverview } from './fixed-feature-overview';
 export { FreeFeatureOverview } from './free-feature-overview';
 export { FreeLayoutSimple } from './free-layout-simple';
 export { FreeLayoutSimplePreview } from './free-layout-simple/preview';
-export { FixedLayoutSimple } from './fixed-layout-simple';
+export { FixedLayoutSimple, CompositeNodesPreview } from './fixed-layout-simple';
 export { FixedLayoutSimplePreview } from './fixed-layout-simple/preview';
 export { NodeFormBasicPreview, NodeFormEffectPreview, NodeFormDynamicPreview } from './node-form';

apps/docs/components/preview-editor.tsx

@@ -15,15 +15,37 @@ export const PreviewEditor = ({
   previewStyle,
   dependencies,
   editorStyle,
+  codeInRight,
 }: {
   files: SandpackFiles;
   children: JSX.Element;
   previewStyle?: React.CSSProperties;
   dependencies?: Record<string, string>;
   editorStyle?: React.CSSProperties;
+  codeInRight?: boolean;
 }) => {
   const dark = useDark();
   const theme = useMemo(() => (dark ? 'dark' : 'light'), [dark]);
+  const content = codeInRight ? (
+    <>
+      <SandpackLayout style={{ width: '100%', display: 'flex' }}>
+        <div className="light-mode" style={previewStyle}>
+          {children}
+        </div>
+        <SandpackCodeEditor style={editorStyle} readOnly />
+      </SandpackLayout>
+    </>
+  ) : (
+    <>
+      <SandpackLayout style={previewStyle}>
+        <div className="light-mode">{children}</div>
+        {/* <SandpackPreview /> */}
+      </SandpackLayout>
+      <SandpackLayout>
+        <SandpackCodeEditor style={editorStyle} readOnly />
+      </SandpackLayout>
+    </>
+  );
 
   return (
     <SandpackProvider
@@ -32,18 +54,18 @@ export const PreviewEditor = ({
       customSetup={{
         dependencies,
       }}
-      files={files}
+      files={{
+        ...files,
+        '/App.js': {
+          code: '',
+          hidden: true,
+        },
+      }}
       onChange={(v) => {
         console.log('debugger', v);
       }}
     >
-      <SandpackLayout style={previewStyle}>
-        <div className="light-mode">{children}</div>
-        {/* <SandpackPreview /> */}
-      </SandpackLayout>
-      <SandpackLayout>
-        <SandpackCodeEditor style={editorStyle} readOnly />
-      </SandpackLayout>
+      {content}
     </SandpackProvider>
   );
 };

apps/docs/src/en/examples/fixed-layout/_meta.json

@@ -1,4 +1,5 @@
 [
   "fixed-layout-simple",
+  "fixed-composite-nodes",
   "fixed-feature-overview"
 ]

apps/docs/src/en/examples/fixed-layout/fixed-composite-nodes.mdx

@@ -0,0 +1,21 @@
+---
+outline: false
+---
+
+
+# Composite Nodes
+
+import { CompositeNodesPreview } from '../../../../components';
+
+<CompositeNodesPreview cellHeight={500}/>
+
+## Installation
+
+```bash
+npx @flowgram.ai/create-app@latest fixed-layout-simple
+```
+
+## Source Code
+
+- jsonData: https://github.com/bytedance/flowgram.ai/tree/main/apps/demo-fixed-layout-simple/src/data
+- nodeRegistries: https://github.com/bytedance/flowgram.ai/tree/main/packages/canvas-engine/fixed-layout-core/src/activities

apps/docs/src/en/guide/advanced/fixed-layout/_meta.json

@@ -1,4 +1,5 @@
 [
   "load",
-  "node"
+  "node",
+  "composite-nodes"
 ]

apps/docs/src/en/guide/advanced/fixed-layout/composite-nodes.mdx

@@ -0,0 +1,33 @@
+# Composite nodes
+
+Composite nodes are composed of multiple nodes and support custom lines, such as condition, loop, and TryCatch.
+
+## Usage
+
+```ts pure title="node-registries.ts"
+
+import { FlowNodeRegistry  } from '@flowgram.ai/fixed-layout-editor';
+
+/**
+ * Node registration
+ */
+export const nodeRegistries: FlowNodeRegistry[] = [
+  {
+    type: 'yourCustomNodeType',
+    extend: 'dynamicSplit',
+  },
+];
+
+```
+
+## Built-in composite nodes
+
+<div className="rs-tip">
+  <a className="rs-link" target="_blank" href="https://github.com/bytedance/flowgram.ai/tree/main/packages/canvas-engine/fixed-layout-core/src/activities">
+    Source Code
+  </a>
+</div>
+
+import { CompositeNodesPreview } from '../../../../../components';
+
+<CompositeNodesPreview />

apps/docs/src/zh/examples/fixed-layout/_meta.json

@@ -1,4 +1,5 @@
 [
   "fixed-layout-simple",
+  "fixed-composite-nodes",
   "fixed-feature-overview"
 ]

apps/docs/src/zh/examples/fixed-layout/fixed-composite-nodes.mdx

@@ -0,0 +1,21 @@
+---
+outline: false
+---
+
+
+# 复合节点
+
+import { CompositeNodesPreview } from '../../../../components';
+
+<CompositeNodesPreview cellHeight={500}/>
+
+## 安装
+
+```bash
+npx @flowgram.ai/create-app@latest fixed-layout-simple
+```
+
+## 源码
+
+- jsonData: https://github.com/bytedance/flowgram.ai/tree/main/apps/demo-fixed-layout-simple/src/data
+- nodeRegistries: https://github.com/bytedance/flowgram.ai/tree/main/packages/canvas-engine/fixed-layout-core/src/activities

apps/docs/src/zh/guide/advanced/fixed-layout/_meta.json

@@ -1,4 +1,5 @@
 [
   "load",
-  "node"
+  "node",
+  "composite-nodes"
 ]

apps/docs/src/zh/guide/advanced/fixed-layout/composite-nodes.mdx

@@ -0,0 +1,35 @@
+# 复合节点
+
+复合节点由多个节点组合，并支持自定义线条，如 分支节点、Loop 节点、TryCatch 节点:
+
+
+## 使用
+
+```ts pure title="node-registries.ts"
+
+import { FlowNodeRegistry  } from '@flowgram.ai/fixed-layout-editor';
+
+/**
+ * 节点注册
+ */
+export const nodeRegistries: FlowNodeRegistry[] = [
+  {
+    type: 'yourCustomNodeType',
+    extend: 'dynamicSplit',
+  },
+];
+
+```
+
+## 内置的复合节点
+
+<div className="rs-tip">
+  <a className="rs-link" target="_blank" href="https://github.com/bytedance/flowgram.ai/tree/main/packages/canvas-engine/fixed-layout-core/src/activities">
+    Source Code
+  </a>
+</div>
+
+import { CompositeNodesPreview } from '../../../../../components';
+
+<CompositeNodesPreview />
+