@flowgram-vue/document 0.2.0

package/src/flow-render-tree.ts

@@ -0,0 +1,236 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { FlowDocumentConfigEnum, FlowNodeBaseType, FlowNodeSplitType } from './typings';
+import { FlowVirtualTree } from './flow-virtual-tree';
+import type { FlowDocument } from './flow-document';
+import type { FlowNodeEntity } from './entities';
+
+/**
+ * Render Tree 会只读模式，不具备操作 tree 结构元素
+ */
+export class FlowRenderTree<T extends FlowNodeEntity> extends FlowVirtualTree<T> {
+  protected originTree: FlowVirtualTree<T>;
+
+  protected document: FlowDocument;
+
+  /**
+   * 折叠的节点
+   * @protected
+   */
+  protected nodesCollapsed = new Set<T>();
+
+  constructor(readonly root: T, originTree: FlowVirtualTree<T>, document: FlowDocument) {
+    super(root);
+    this.originTree = originTree;
+    this.onTreeChange = this.originTree.onTreeChange;
+    this.document = document;
+  }
+
+  isCollapsed(node: T): boolean {
+    return this.nodesCollapsed.has(node);
+  }
+
+  get collapsedNodeList(): T[] {
+    return Array.from(this.nodesCollapsed);
+  }
+
+  /**
+   * 折叠元素
+   * @param node
+   * @param collapsed
+   */
+  setCollapsed(node: T, collapsed: boolean): void {
+    if (collapsed) {
+      this.nodesCollapsed.add(node);
+    } else {
+      this.nodesCollapsed.delete(node);
+    }
+    this.originTree.fireTreeChange();
+  }
+
+  /**
+   *
+   */
+  openNodeInsideCollapsed(node: T) {
+    // 找到所有的originTree上的parent
+    let curr: T | undefined = this.originTree.getInfo(node)?.parent;
+
+    while (curr) {
+      if (this.nodesCollapsed.has(curr)) {
+        this.nodesCollapsed.delete(curr);
+      }
+      const { parent } = this.originTree.getInfo(curr) || {};
+      curr = parent;
+    }
+    this.originTree.fireTreeChange();
+  }
+
+  /**
+   * 更新结束节点等位置信息，分支里如果全是结束节点则要做相应的偏移
+   */
+  updateRenderStruct(): void {
+    this.map = this.originTree.cloneMap();
+
+    // 结束节点位置更新逻辑开关
+    if (this.document.config.get(FlowDocumentConfigEnum.END_NODES_REFINE_BRANCH)) {
+      this.refineBranch(this.root);
+    }
+
+    // 节点展开收起
+    this.hideCollapsed();
+  }
+
+  /**
+   * 隐藏收起节点
+   */
+  protected hideCollapsed() {
+    this.nodesCollapsed.forEach(collapsedNode => {
+      const collapsedNodeInfo = this.getInfo(collapsedNode);
+      if (!collapsedNodeInfo) {
+        // 自动回收节点数据
+        this.nodesCollapsed.delete(collapsedNode);
+        return;
+      }
+
+      const iconChild = collapsedNodeInfo.children.find(
+        _child =>
+          _child.flowNodeType === FlowNodeBaseType.BLOCK_ICON ||
+          _child.flowNodeType === FlowNodeBaseType.BLOCK_ORDER_ICON,
+      );
+
+      // ⚠️注意：BLOCK_ICON 和 BLOCK_ORDER_ICON 作为一个 block 的标识节点，收起时需要保留
+      if (iconChild) {
+        const iconInfo = this.getInfo(iconChild);
+        iconInfo.next = undefined;
+        iconInfo.pre = undefined;
+        collapsedNodeInfo.children = [iconChild];
+
+        return;
+      }
+
+      // 收起节点children置为空
+      collapsedNodeInfo.children = [];
+    });
+  }
+
+  // 节点是否为结束节点
+  isNodeEnd(node: T): boolean {
+    if (node.getNodeMeta().isNodeEnd) {
+      return true;
+    }
+    const { children } = this.getInfo(node);
+
+    if (children.length > 0 && node.isInlineBlocks) {
+      return children.every(child => this.isNodeEnd(child));
+    }
+
+    if (node.isInlineBlock) {
+      return this.isNodeEnd(children[children.length - 1]);
+    }
+
+    return false;
+  }
+
+  /**
+   * 优化精简分支线
+   * - 结束节点拉直分支线
+   */
+  protected refineBranch(block: T) {
+    let curr: T | undefined = this.getInfo(block).children[0];
+
+    while (curr) {
+      if (
+        curr.flowNodeType === FlowNodeSplitType.DYNAMIC_SPLIT ||
+        curr.flowNodeType === FlowNodeSplitType.STATIC_SPLIT
+      ) {
+        const { next, children: branchChildren } = this.getInfo(curr);
+        const { children } = this.getInfo(branchChildren[1]);
+
+        const passBlocks = (children || []).filter(child => !this.isNodeEnd(child));
+
+        const shouldDragAllNextNodes = passBlocks.length === 1;
+        if (shouldDragAllNextNodes && next) {
+          this.dragNextNodesToBlock(passBlocks[0], next);
+        }
+
+        // 对每一个分支再进行refineBranch
+        children?.forEach(child => {
+          this.refineBranch(child);
+        });
+
+        if (shouldDragAllNextNodes) {
+          break;
+        }
+      }
+
+      curr = curr.next as T;
+    }
+  }
+
+  // 结束节点拽分支，将后续节点拽到对应分支内
+  protected dragNextNodesToBlock(toBlock: T, next: T) {
+    const toBlockInfo = this.getInfo(toBlock);
+    const nextInfo = this.getInfo(next);
+    const toBlockLastChild = toBlockInfo.children[toBlock.children.length - 1];
+
+    if (nextInfo.parent) {
+      const nextParentInfo = this.getInfo(nextInfo.parent);
+
+      // 1. next的节点和之前的节点断连
+      if (nextInfo.pre) {
+        this.getInfo(nextInfo.pre).next = undefined;
+      }
+
+      // 2. next连接到before上
+      if (toBlockLastChild) {
+        const lastChildInfo = this.getInfo(toBlockLastChild);
+        lastChildInfo.next = next;
+        nextInfo.pre = toBlockLastChild;
+      }
+
+      // 3. 获取所有后续节点, 将所有后续节点重新设置parent
+      const nextNodeIndex = nextParentInfo.children.indexOf(next);
+      const allNextNodes = nextParentInfo.children.slice(nextNodeIndex);
+      nextParentInfo.children = nextParentInfo.children.slice(0, nextNodeIndex);
+      for (const node of allNextNodes) {
+        const nodeInfo = this.getInfo(node);
+        toBlockInfo.children.push(node);
+        nodeInfo.parent = toBlock;
+      }
+    }
+  }
+
+  getInfo(node: T): FlowVirtualTree.NodeInfo<T> {
+    const info = this.map.get(node) || this.originTree.getInfo(node);
+    return info;
+  }
+
+  // 或者originTree节点的信息
+  getOriginInfo(node: T): FlowVirtualTree.NodeInfo<T> {
+    return this.originTree.getInfo(node);
+  }
+
+  // 获取收起的隐藏节点
+  getCollapsedChildren(node: T): T[] {
+    return this.getOriginInfo(node).children || [];
+  }
+
+  remove(): void {
+    throw new Error('Render Tree cannot use remove node');
+  }
+
+  addChild(): T {
+    throw new Error('Render tree cannot use add child');
+  }
+
+  insertAfter(): void {
+    throw new Error('Render tree cannot use insert after');
+  }
+
+  removeParent(): void {
+    throw new Error('Render tree cannot use remove parent');
+  }
+}

package/src/flow-virtual-tree.ts

@@ -0,0 +1,244 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { type Disposable, Emitter } from '@flowgram-vue/utils';
+
+import { type FlowNodeType } from './typings';
+
+/**
+ * 存储节点的 tree 结构信息
+ * 策略是 "重修改轻查询"，即修改时候做的事情更多，查询都通过指针来操作
+ */
+export class FlowVirtualTree<T extends { id: string; flowNodeType?: FlowNodeType }>
+  implements Disposable
+{
+  protected onTreeChangeEmitter = new Emitter<void>();
+
+  /**
+   * tree 结构变化时候触发
+   */
+  onTreeChange = this.onTreeChangeEmitter.event;
+
+  protected map: Map<T, FlowVirtualTree.NodeInfo<T>> = new Map();
+
+  constructor(readonly root: T) {}
+
+  dispose() {
+    this.map.clear();
+    this.onTreeChangeEmitter.dispose();
+  }
+
+  getInfo(node: T): FlowVirtualTree.NodeInfo<T> {
+    let res: FlowVirtualTree.NodeInfo<T> | undefined = this.map.get(node);
+    if (!res) {
+      res = { children: [] };
+      this.map.set(node, res);
+    }
+    return res;
+  }
+
+  clear(): void {
+    this.map.clear();
+  }
+
+  cloneMap(): Map<T, FlowVirtualTree.NodeInfo<T>> {
+    const newMap: Map<T, FlowVirtualTree.NodeInfo<T>> = new Map();
+    for (const [key, value] of this.map) {
+      newMap.set(key, {
+        ...value,
+        children: value.children.slice(),
+      });
+    }
+
+    return newMap;
+  }
+
+  clone(): FlowVirtualTree<T> {
+    const newTree = new FlowVirtualTree<T>(this.root);
+    newTree.map = this.cloneMap();
+    return newTree;
+  }
+
+  remove(node: T, withChildren = true): void {
+    this.removeParent(node);
+    if (withChildren) {
+      this._removeChildren(node);
+    }
+    this.map.delete(node);
+    this.fireTreeChange();
+  }
+
+  addChild(parent: T, child: T, index?: number): T {
+    const parentInfo = this.getInfo(parent);
+    const childInfo = this.getInfo(child);
+    if (childInfo.parent) {
+      if (childInfo.parent === parent) return child;
+      if (childInfo.parent !== parent) {
+        this.removeParent(child);
+      }
+    }
+
+    const len = parentInfo.children.length;
+    const idx = typeof index === 'undefined' ? len - 1 : index - 1;
+    const lastChild = parentInfo.children[idx];
+    const nextChild = parentInfo.children[idx + 1];
+    if (lastChild) this.getInfo(lastChild).next = child;
+    if (nextChild) this.getInfo(nextChild).pre = child;
+    childInfo.pre = lastChild;
+    childInfo.next = nextChild;
+    parentInfo.children.splice(idx + 1, 0, child);
+    childInfo.parent = parent;
+    this.fireTreeChange();
+    return child;
+  }
+
+  moveChilds(parent: T, childs: T[], index?: number): T[] {
+    const parentInfo = this.getInfo(parent);
+    const len = parentInfo.children.length;
+    let childIndex: number = index ?? len;
+
+    childs.forEach((child) => {
+      const childInfo = this.getInfo(child);
+      if (childInfo.parent) {
+        this.removeParent(child);
+      }
+    });
+
+    childs.forEach((child) => {
+      const childInfo = this.getInfo(child);
+      let lastChild: T | undefined = parentInfo.children[childIndex - 1];
+      let nextChild: T | undefined = parentInfo.children[childIndex];
+
+      if (lastChild) this.getInfo(lastChild).next = child;
+      if (nextChild) this.getInfo(nextChild).pre = child;
+      childInfo.pre = lastChild;
+      childInfo.next = nextChild;
+      parentInfo.children.splice(childIndex, 0, child);
+      childInfo.parent = parent;
+      childIndex++;
+    });
+
+    this.fireTreeChange();
+    return childs;
+  }
+
+  getById(id: string): T | undefined {
+    for (const node of this.map.keys()) {
+      if (node.id === id) return node;
+    }
+  }
+
+  /**
+   * 插入节点到后边
+   * @param before
+   * @param after
+   */
+  insertAfter(before: T, after: T) {
+    const beforeInfo = this.getInfo(before);
+    const afterInfo = this.getInfo(after);
+    this.removeParent(after);
+    if (beforeInfo.parent) {
+      const parentInfo = this.getInfo(beforeInfo.parent);
+      parentInfo.children.splice(parentInfo.children.indexOf(before) + 1, 0, after);
+      const { next } = beforeInfo;
+      if (next) {
+        this.getInfo(next).pre = after;
+      }
+      afterInfo.next = next;
+      beforeInfo.next = after;
+      afterInfo.pre = before;
+      afterInfo.parent = beforeInfo.parent;
+    }
+    this.fireTreeChange();
+  }
+
+  removeParent(node: T): void {
+    const info = this.getInfo(node);
+    if (!info.parent) return;
+    const parentInfo = this.getInfo(info.parent);
+    const index = parentInfo.children.indexOf(node);
+    parentInfo.children.splice(index, 1);
+    const { pre, next } = info;
+    if (pre) this.getInfo(pre).next = next;
+    if (next) this.getInfo(next).pre = pre;
+    this.fireTreeChange();
+  }
+
+  private _removeChildren(node: T): void {
+    // 删除子节点
+    const children = this.getChildren(node);
+    if (children.length > 0) {
+      children.forEach((child) => {
+        this._removeChildren(child);
+        this.map.delete(child);
+      });
+    }
+  }
+
+  getParent(node: T): T | undefined {
+    return this.getInfo(node).parent;
+  }
+
+  getPre(node: T): T | undefined {
+    return this.getInfo(node).pre;
+  }
+
+  getNext(node: T): T | undefined {
+    return this.getInfo(node).next;
+  }
+
+  getChildren(node: T): T[] {
+    return this.getInfo(node).children;
+  }
+
+  traverse(
+    fn: (node: T, depth: number, index: number) => boolean | void,
+    node = this.root,
+    depth = 0,
+    index = 0
+  ): boolean | void {
+    const breaked = fn(node, depth, index);
+    if (breaked) return true;
+    const info = this.getInfo(node);
+    const shouldBreak = info.children.find((child, i) => this.traverse(fn, child, depth + 1, i));
+    if (shouldBreak) return true;
+  }
+
+  /**
+   * 通知文档树结构更新
+   */
+  fireTreeChange(): void {
+    this.onTreeChangeEmitter.fire();
+  }
+
+  get size(): number {
+    return this.map.size;
+  }
+
+  toString(showType?: boolean): string {
+    const ret: string[] = [];
+    this.traverse((node, depth) => {
+      if (depth === 0) {
+        ret.push(node.id);
+      } else {
+        ret.push(
+          `|${new Array(depth).fill('--').join('')} ${
+            showType ? `${node.flowNodeType}(${node.id})` : node.id
+          }`
+        );
+      }
+    });
+    return `${ret.join('\n')}`;
+  }
+}
+
+export namespace FlowVirtualTree {
+  export interface NodeInfo<T> {
+    parent?: T;
+    next?: T;
+    pre?: T;
+    children: T[];
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+export * from './typings';
+export * from './entities';
+export * from './datas';
+export * from './flow-document';
+export * from './flow-virtual-tree';
+export * from './flow-document-contribution';
+export * from './flow-document-container-module';
+export * from './flow-document-config';
+export * from './flow-document-options';
+export * from './services';
+export * from './utils';

package/src/layout/horizontal-fixed-layout.ts

@@ -0,0 +1,198 @@
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+import { injectable, inject, multiInject, optional } from 'inversify';
+import { IPoint, OriginSchema, PaddingSchema, ScrollSchema, SizeSchema } from '@flowgram-vue/utils';
+
+import { type FlowLayout, FlowLayoutDefault, FlowLayoutContribution } from '../typings';
+import { type FlowDocument, FlowDocumentProvider } from '../flow-document';
+import { FlowNodeEntity } from '../entities';
+import { FlowNodeTransformData } from '../datas';
+
+// 开始节点距离上边 36 像素
+const DEFAULT_SCROLL = -36;
+
+/**
+ * 用于描述节点的结构特征
+ */
+interface FlowNodeTransformStructData {
+  childrenLength: number;
+  index: number;
+}
+/**
+ * 用于描述节点的结构特征
+ */
+interface FlowNodeTransformStructData {
+  childrenLength: number;
+  index: number;
+}
+
+function isStructDataEqual(
+  struct1: FlowNodeTransformStructData,
+  struct2: FlowNodeTransformStructData
+): boolean {
+  return struct1.childrenLength === struct2.childrenLength && struct1.index === struct2.index;
+}
+
+@injectable()
+export class HorizontalFixedLayout implements FlowLayout {
+  name = FlowLayoutDefault.HORIZONTAL_FIXED_LAYOUT;
+
+  protected structDataMap = new WeakMap<FlowNodeEntity, FlowNodeTransformStructData>();
+
+  @inject(FlowDocumentProvider) protected documentProvider: FlowDocumentProvider;
+
+  @multiInject(FlowLayoutContribution)
+  @optional()
+  contribs?: FlowLayoutContribution[];
+
+  get document(): FlowDocument {
+    return this.documentProvider();
+  }
+
+  reload() {
+    this.structDataMap = new WeakMap();
+  }
+
+  /**
+   * 更新布局
+   */
+  update(): void {
+    this.updateLocalTransform(this.document.root);
+  }
+
+  /**
+   * 更新节点的偏移
+   * @param node
+   * @param forceChange
+   */
+  updateLocalTransform(node: FlowNodeEntity, forceChange = false): boolean {
+    const { children, parent, isInlineBlock } = node;
+
+    const transform = node.getData<FlowNodeTransformData>(FlowNodeTransformData);
+    const { getDelta, getOrigin } = node.getNodeRegistry();
+    const lastStructData = this.structDataMap.get(node) || {
+      childrenLength: 0,
+      index: -1,
+    };
+    // 重新计算都要清空 bounds 缓存，因为 bounds 依赖所有
+    node.clearMemoGlobal();
+    let localDirty = transform.localDirty || forceChange;
+    const newStructData: FlowNodeTransformStructData = {
+      index: node.index,
+      childrenLength: node.children.length,
+    };
+    // index 变化也要重新计算
+    if (!isStructDataEqual(lastStructData, newStructData)) {
+      localDirty = true;
+      this.structDataMap.set(node, newStructData);
+    }
+    // Step1: 计算子节点
+    let siblingDirty = false;
+    if (children.length > 0) {
+      for (const child of children) {
+        const childDirty = this.updateLocalTransform(child, siblingDirty);
+        // 子节点变更则父节点跟着变更
+        if (childDirty) {
+          siblingDirty = true;
+          localDirty = true;
+        }
+      }
+    }
+    // 如果没有变更则不执行
+    if (!localDirty) return false;
+    // Step2: 计算节点的 position 偏移量
+    node.clearMemoLocal();
+    transform.transform.update({
+      origin: getOrigin ? getOrigin(transform, this) : this.getDefaultNodeOrigin(),
+    });
+    const preTransform = transform.pre;
+    const delta = getDelta?.(transform, this) || { x: 0, y: 0 };
+    const inlineSpacingPre =
+      isInlineBlock && transform.parent?.inlineSpacingPre ? transform.parent?.inlineSpacingPre : 0;
+    const fromParentDelta = parent?.getNodeRegistry().getChildDelta?.(transform, this) || {
+      x: 0,
+      y: 0,
+    };
+    delta.x += fromParentDelta.x;
+    delta.y += fromParentDelta.y;
+
+    // Step3：根据上一个节点的相对偏移算当前偏移
+    const position = { x: delta.x, y: delta.y };
+    // 水平布局
+    if (isInlineBlock) {
+      position.x += inlineSpacingPre;
+    } else {
+      position.x += preTransform?.localBounds.right || 0;
+      position.x += preTransform?.spacing || 0;
+    }
+
+    transform.transform.update({
+      size: transform.data.size,
+      position,
+    });
+
+    // 布局结束后可执行额外逻辑
+    this.onAfterUpdateLocalTransform(transform);
+
+    transform.localDirty = false;
+
+    return true;
+  }
+
+  onAfterUpdateLocalTransform(transform: FlowNodeTransformData) {
+    // 执行 register 上的 onAfterUpdateLocalTransform
+    const { onAfterUpdateLocalTransform } = transform.entity.getNodeRegistry();
+    onAfterUpdateLocalTransform?.(transform, this);
+
+    // 执行 contribution 上的 onAfterUpdateLocalTransform
+    this.contribs?.forEach((_contrib) => {
+      _contrib?.onAfterUpdateLocalTransform?.(transform, this);
+    });
+  }
+
+  getNodeTransform(node: FlowNodeEntity): FlowNodeTransformData {
+    return node.getData(FlowNodeTransformData)!;
+  }
+
+  getPadding(node: FlowNodeEntity): PaddingSchema {
+    const { inlineSpacingPre, inlineSpacingAfter, padding } = node.getNodeMeta();
+    const transform = this.getNodeTransform(node);
+    if (padding) {
+      return typeof padding === 'function' ? padding(transform) : padding;
+    }
+
+    const paddingPre =
+      typeof inlineSpacingPre === 'function' ? inlineSpacingPre(transform) : inlineSpacingPre;
+    const paddingAfter =
+      typeof inlineSpacingAfter === 'function' ? inlineSpacingAfter(transform) : inlineSpacingAfter;
+
+    return {
+      left: paddingPre,
+      top: 0,
+      right: paddingAfter,
+      bottom: 0,
+    };
+  }
+
+  getInitScroll(contentSize: SizeSchema): ScrollSchema {
+    return {
+      scrollX: DEFAULT_SCROLL,
+      scrollY: -contentSize.height / 2,
+    };
+  }
+
+  getDefaultInputPoint(node: FlowNodeEntity): IPoint {
+    return this.getNodeTransform(node).bounds.leftCenter;
+  }
+
+  getDefaultOutputPoint(node: FlowNodeEntity): IPoint {
+    return this.getNodeTransform(node).bounds.rightCenter;
+  }
+
+  getDefaultNodeOrigin(): OriginSchema {
+    return { x: 0, y: 0.5 };
+  }
+}

package/src/layout/index.ts

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