refactor(Graph): enhance zoomTo method to support various target types and improve documentation

Author: draedful

src/api/PublicGraphApi.ts

@@ -10,7 +10,7 @@ import { selectBlockById } from "../store/block/selectors";
 import { TConnection, TConnectionId } from "../store/connection/ConnectionState";
 import { selectConnectionById } from "../store/connection/selectors";
 import { TGraphSettingsConfig } from "../store/settings";
-import { getBlocksRect, getElementsRect, startAnimation } from "../utils/functions";
+import { getElementsRect, startAnimation } from "../utils/functions";
 import { TRect } from "../utils/types/shapes";
 
 export type ZoomConfig = {
@@ -23,18 +23,44 @@ export class PublicGraphApi {
     // noop
   }
 
+  /**
+   * Zooms to blocks
+   * @param blockIds - block ids to zoom to
+   * @param zoomConfig - {@link ZoomConfig} zoom config
+   * @returns {boolean} true if zoom is successful, false otherwise
+   *
+   * @example
+   * ```typescript
+   * graph.zoomToBlocks([block1.id, block2.id]);
+   * graph.zoomToBlocks([block1.id, block2.id], { transition: 1000, padding: 50 });
+   * ```
+   */
   public zoomToBlocks(blockIds: TBlockId[], zoomConfig?: ZoomConfig) {
-    const blocks = blockIds.map((id) => this.graph.rootStore.blocksList.$blocksMap.value.get(id)).filter(Boolean);
-    if (blocks.length === 0) {
-      return;
-    }
-    const blocksRect = getBlocksRect(blocks.map((block) => block.asTBlock()));
-    this.zoomToRect(blocksRect, zoomConfig);
+    return this.zoomToElements(
+      this.graph.rootStore.blocksList.getBlockStates(blockIds).map((blockState) => blockState.getViewComponent()),
+      zoomConfig
+    );
   }
 
+  /**
+   * Zooms to GraphComponent instances
+   * @param instances -  {@link GraphComponent} instances to zoom to
+   * @param zoomConfig - {@link ZoomConfig} zoom config
+   * @returns {boolean} true if zoom is successful, false otherwise
+   *
+   * @example
+   * ```typescript
+   * graph.zoomToElements([component1, component2]);
+   * graph.zoomToElements([component1, component2], { transition: 1000, padding: 50 });
+   * ```
+   */
   public zoomToElements<T extends GraphComponent = GraphComponent>(elements: T[], zoomConfig?: ZoomConfig) {
+    if (elements.length === 0) {
+      return false;
+    }
     const elementsRect = getElementsRect(elements);
     this.zoomToRect(elementsRect, zoomConfig);
+    return true;
   }
 
   /**
@@ -61,6 +87,21 @@ export class PublicGraphApi {
     });
   }
 
+  /**
+   * Zooms to the specified rectangle in camera coordinates
+   *
+   * Zooms the camera to fit the specified rectangle in the viewport. The rectangle will be scaled
+   * to fill the visible area (respecting camera insets) and centered in the viewport.
+   *
+   * @param rect - {@link TRect} rectangle to zoom to in camera coordinates
+   * @param zoomConfig - {@link ZoomConfig} zoom config
+   * @returns {undefined}
+   *
+   * @example
+   * ```typescript
+   * graph.zoomToRect({ x: 0, y: 0, width: 100, height: 100 });
+   * graph.zoomToRect({ x: 0, y: 0, width: 100, height: 100 }, { transition: 1000, padding: 50 });
+   */
   public zoomToRect(rect: TRect, zoomConfig?: ZoomConfig) {
     const transition = zoomConfig?.transition || 0;
     const padding = zoomConfig?.padding || 0;

src/graph.ts

@@ -170,20 +170,42 @@ export class Graph {
     this.cameraService.zoom(zoomConfig.x || width / 2, zoomConfig.y || height / 2, zoomConfig.scale);
   }
 
-  public zoomTo(target: TGraphZoomTarget, config?: ZoomConfig) {
-    if (target === "center") {
-      this.api.zoomToViewPort(config);
-      return;
-    }
+  /**
+   * Zooms to the target
+   *
+   * - If target is rectangle, it will be zoomed({@link PublicGraphApi.zoomToRect}) to the rectangle and returns true.
+   * - If target is array of block ids, it will be zoomed({@link PublicGraphApi.zoomToBlocks}) to the blocks, if at least one block is found, returns true, otherwise returns false.
+   * - If target is array of {@link GraphComponent} instances, it will be zoomed({@link PublicGraphApi.zoomToElements}) to the rect containing all components and returns true.
+   * - If target is center, it will be zoomed({@link PublicGraphApi.zoomToViewPort}) to the center and returns true.
+   *
+   * @example
+   * ```typescript
+   * graph.zoomTo("center");
+   * graph.zoomTo([block1.id, block2.id]);
+   * graph.zoomTo([block1, block2]);
+   * graph.zoomTo({x: 100, y: 100, width: 100, height: 100 });
+   * ```
+   * @param target - target to zoom to
+   * @param config - zoom config, optional, optional
+   * @returns {boolean} true if zoom is successful, false otherwise
+   *
+   * */
+  public zoomTo(target: TGraphZoomTarget, config?: ZoomConfig): boolean {
     if (isTRect(target)) {
       this.api.zoomToRect(target, config);
-      return;
+      return true;
     }
-    if (Array.isArray(target) && target.every((item) => item instanceof GraphComponent)) {
-      this.api.zoomToElements(target, config);
-      return;
+    if (Array.isArray(target)) {
+      if (target.every((item) => item instanceof GraphComponent)) {
+        return this.api.zoomToElements(target, config);
+      }
+      if (target.every((item) => typeof item === "string")) {
+        return this.api.zoomToBlocks(target, config);
+      }
     }
-    this.api.zoomToBlocks(target, config);
+
+    this.api.zoomToViewPort(config);
+    return true;
   }
 
   public getElementsOverPoint<T extends Constructor<GraphComponent>>(point: IPoint, filter?: T[]): InstanceType<T>[] {