@skyramp/skyramp 1.3.15 → 1.3.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyramp/skyramp",
-  "version": "1.3.15",
+  "version": "1.3.16",
   "description": "module for leveraging skyramp cli functionality",
   "scripts": {
     "lint": "eslint 'src/**/*.js' 'src/**/*.ts' --fix",

package/src/classes/GoJSDiagram.d.ts

@@ -0,0 +1,66 @@
+import { Page } from '@playwright/test';
+
+export interface AddNodeOptions {
+  /** Key to assign to the new node in the GoJS model. */
+  key: string;
+  /** GoJS node category — used to look up the palette template. */
+  category: string;
+  /** CSS selector for the div that hosts the target GoJS diagram. */
+  diagramSelector: string;
+  /** CSS selector for the palette div to copy app-specific properties from. Optional. */
+  paletteSelector?: string;
+  /** Key of the pre-existing diagram node to use as placement anchor. */
+  anchorKey?: string;
+  /** X offset from the anchor node's document-space location. */
+  anchorOffsetX?: number;
+  /** Y offset from the anchor node's document-space location. */
+  anchorOffsetY?: number;
+}
+
+export interface NodeRef {
+  panelSelector: string;
+  key: string | number;
+  port?: string;
+}
+
+export interface PaletteSource {
+  panelSelector: string;
+  category: string;
+}
+
+export interface DocTarget {
+  panelSelector: string;
+  docX: number;
+  docY: number;
+}
+
+export interface NodeSource {
+  panelSelector: string;
+  key: string | number;
+}
+
+export declare class GoJSDiagram {
+  constructor(page: Page, framePath?: string[]);
+
+  /**
+   * Add a new node to a GoJS diagram at a position relative to an anchor node.
+   * App-specific properties are copied from the palette template for the given
+   * category, skipping GoJS internals and loc to avoid palette mutation.
+   */
+  addNode(opts: AddNodeOptions): Promise<void>;
+
+  /**
+   * Create a directed link between two GoJS nodes via the model API.
+   */
+  linkNodes(source: NodeRef, target: NodeRef): Promise<void>;
+
+  /**
+   * Drag a node from a GoJS Palette into a GoJS Diagram.
+   */
+  dragFromPalette(source: PaletteSource, target: DocTarget): Promise<void>;
+
+  /**
+   * Move an existing node within a GoJS Diagram.
+   */
+  moveNode(source: NodeSource, target: DocTarget): Promise<void>;
+}

package/src/classes/GoJSDiagram.js

@@ -0,0 +1,368 @@
+/**
+ * Copyright (c) Skyramp Corporation.
+ *
+ * GoJSDiagram — a Playwright helper for driving GoJS canvases.
+ *
+ * GoJS renders entirely into a <canvas> element so there are no DOM nodes for
+ * individual diagram items.  This class handles the three-step coordinate
+ * resolution that is required for any reliable interaction:
+ *
+ *   1. Ask the GoJS model for the viewport-space offset of the element
+ *      (via go.Diagram.fromDiv().transformDocToView() or findNodeForKey()).
+ *   2. Ask Playwright for the page-level bounding box of the <canvas> element
+ *      (via locator.boundingBox() which correctly traverses the iframe chain).
+ *   3. Add the two together → final page coordinate for page.mouse.*.
+ *
+ * The class is generic: it locates GoJS containers via the standard
+ * go.Diagram.fromDiv() API and does NOT rely on application-specific CSS IDs.
+ *
+ * Usage (TypeScript):
+ *
+ *   import { GoJSDiagram } from '@skyramp/skyramp';
+ *
+ *   const gojs = new GoJSDiagram(page, ['iframe[title="main menu"]', 'iframe[title="iframe process"]']);
+ *
+ *   // Drag a node from a palette to a diagram
+ *   await gojs.dragFromPalette(
+ *     { panelSelector: '#myPalette', category: 'Task' },
+ *     { panelSelector: '#myDiagram', docX: 350, docY: 285 },
+ *   );
+ *
+ *   // Move an existing node within a diagram
+ *   await gojs.moveNode(
+ *     { panelSelector: '#myDiagram', key: '3' },
+ *     { panelSelector: '#myDiagram', docX: 250, docY: 300 },
+ *   );
+ */
+
+/* global document, window */
+
+const GOJS_DRAG_STEPS = 50; // Minimum steps for GoJS to register a drag
+
+class GoJSDiagram {
+  /**
+   * @param {import('@playwright/test').Page} page  The Playwright Page object.
+   * @param {string[]} framePath  Ordered list of iframe selectors to reach the
+   *   frame that contains the GoJS diagram (e.g. ['iframe[title="menu"]',
+   *   'iframe[title="process"]']).  Empty array means the diagram is in the
+   *   top-level page.
+   */
+  constructor(page, framePath = []) {
+    this._page = page;
+    this._framePath = framePath;
+  }
+
+  /**
+   * Returns a FrameLocator scoped to the innermost frame in framePath,
+   * or the page itself when framePath is empty.
+   *
+   * @returns {import('@playwright/test').Page | import('@playwright/test').FrameLocator}
+   */
+  _frameLocator() {
+    let scope = this._page;
+    for (const sel of this._framePath) {
+      scope = scope.frameLocator(sel);
+    }
+    return scope;
+  }
+
+  /**
+   * Resolve the page-level {x, y} of a point expressed in GoJS document
+   * coordinates within the specified panel container.
+   *
+   * @param {string} panelSelector  CSS selector for the div that hosts the GoJS
+   *   diagram or palette (e.g. '#myPalette', '[data-testid="diagram"]').
+   * @param {number} docX  X coordinate in GoJS document space.
+   * @param {number} docY  Y coordinate in GoJS document space.
+   * @returns {Promise<{x: number, y: number}>}
+   */
+  async _resolveDocPoint(panelSelector, docX, docY) {
+    const fl = this._frameLocator();
+    const canvasLocator = fl.locator(`${panelSelector} canvas`).first();
+
+    // Page-level bounding box of the canvas element
+    const box = await canvasLocator.boundingBox();
+    if (!box) {
+      throw new Error(`GoJSDiagram: canvas not found for panel "${panelSelector}"`);
+    }
+
+    // Viewport-space point inside the canvas, obtained via GoJS API in the frame
+    const vpPt = await this._evaluateInFrame(([sel, dx, dy]) => {
+      const container = document.querySelector(sel);
+      if (!container) return null;
+      const diagram = window.go?.Diagram?.fromDiv?.(container);
+      if (!diagram) return null;
+      const vp = diagram.transformDocToView(new window.go.Point(dx, dy));
+      return { x: vp.x, y: vp.y };
+    }, [panelSelector, docX, docY]);
+
+    if (!vpPt) {
+      throw new Error(`GoJSDiagram: could not resolve document point via GoJS for panel "${panelSelector}"`);
+    }
+
+    return { x: box.x + vpPt.x, y: box.y + vpPt.y };
+  }
+
+  /**
+   * Resolve the page-level {x, y} of a palette node identified by category.
+   * Picks the first node in the palette whose data.category matches.
+   *
+   * @param {string} panelSelector  CSS selector for the palette container div.
+   * @param {string} category  The GoJS node category to look for.
+   * @returns {Promise<{x: number, y: number}>}
+   */
+  async _resolvePaletteNode(panelSelector, category) {
+    const fl = this._frameLocator();
+    const canvasLocator = fl.locator(`${panelSelector} canvas`).first();
+
+    const box = await canvasLocator.boundingBox();
+    if (!box) {
+      throw new Error(`GoJSDiagram: palette canvas not found for panel "${panelSelector}"`);
+    }
+
+    const vpPt = await this._evaluateInFrame(([sel, cat]) => {
+      const container = document.querySelector(sel);
+      if (!container) return null;
+      const diagram = window.go?.Diagram?.fromDiv?.(container);
+      if (!diagram) return null;
+      let found = null;
+      diagram.nodes.each(n => {
+        if (!found && n.data?.category === cat) found = n;
+      });
+      if (!found) return null;
+      const center = found.getDocumentPoint(window.go.Spot.Center);
+      const vp = diagram.transformDocToView(center);
+      return { x: vp.x, y: vp.y };
+    }, [panelSelector, category]);
+
+    if (!vpPt) {
+      throw new Error(`GoJSDiagram: no node with category "${category}" found in palette "${panelSelector}"`);
+    }
+
+    return { x: box.x + vpPt.x, y: box.y + vpPt.y };
+  }
+
+  /**
+   * Resolve the page-level {x, y} of a diagram node identified by key.
+   *
+   * @param {string} panelSelector  CSS selector for the diagram container div.
+   * @param {string|number} key  The GoJS node key.
+   * @returns {Promise<{x: number, y: number}>}
+   */
+  async _resolveDiagramNode(panelSelector, key) {
+    const fl = this._frameLocator();
+    const canvasLocator = fl.locator(`${panelSelector} canvas`).first();
+
+    const box = await canvasLocator.boundingBox();
+    if (!box) {
+      throw new Error(`GoJSDiagram: diagram canvas not found for panel "${panelSelector}"`);
+    }
+
+    const vpPt = await this._evaluateInFrame(([sel, k]) => {
+      const container = document.querySelector(sel);
+      if (!container) return null;
+      const diagram = window.go?.Diagram?.fromDiv?.(container);
+      if (!diagram) return null;
+      const node = diagram.findNodeForKey(k);
+      if (!node) return null;
+      const center = node.getDocumentPoint(window.go.Spot.Center);
+      const vp = diagram.transformDocToView(center);
+      return { x: vp.x, y: vp.y };
+    }, [panelSelector, key]);
+
+    if (!vpPt) {
+      throw new Error(`GoJSDiagram: no node with key "${key}" found in diagram "${panelSelector}"`);
+    }
+
+    return { x: box.x + vpPt.x, y: box.y + vpPt.y };
+  }
+
+  /**
+   * Execute a function inside the correct frame context.
+   * Uses page.evaluate() when there are no iframes, otherwise uses
+   * page.frames().find() to reach the correct nested frame.
+   *
+   * @param {Function} fn  Function to evaluate in the frame.
+   * @param {...any} args  Arguments forwarded to fn.
+   * @returns {Promise<any>}
+   */
+  async _evaluateInFrame(fn, ...args) {
+    if (this._framePath.length === 0) {
+      return this._page.evaluate(fn, ...args);
+    }
+
+    // Locate the target frame by walking the frame tree
+    const targetUrl = await this._frameLocator()
+      .locator('html')
+      .evaluate(el => el.ownerDocument.defaultView?.location?.href ?? '');
+
+    const frame = this._page.frames().find(f => f.url() === targetUrl);
+    if (!frame) {
+      throw new Error(`GoJSDiagram: could not find frame for path [${this._framePath.join(', ')}]`);
+    }
+
+    return frame.evaluate(fn, args[0]);
+  }
+
+  /**
+   * Execute the mouse drag sequence that GoJS responds to.
+   * Requires ≥50 intermediate mousemove steps.
+   *
+   * @param {{x: number, y: number}} src  Page-level source coordinates.
+   * @param {{x: number, y: number}} dest  Page-level destination coordinates.
+   */
+  async _drag(src, dest) {
+    // Move to source first (hover to let GoJS know where we start)
+    await this._page.mouse.move(src.x, src.y);
+    await this._page.waitForTimeout(200);
+    await this._page.mouse.down();
+    await this._page.waitForTimeout(600);
+    await this._page.mouse.move(dest.x, dest.y, { steps: GOJS_DRAG_STEPS });
+    await this._page.waitForTimeout(800);
+    await this._page.mouse.up();
+    await this._page.waitForTimeout(500);
+  }
+
+  /**
+   * Drag a node from a GoJS Palette into a GoJS Diagram.
+   *
+   * @param {{ panelSelector: string, category: string }} source
+   * @param {{ panelSelector: string, docX: number, docY: number }} target
+   */
+  async dragFromPalette(source, target) {
+    const src = await this._resolvePaletteNode(source.panelSelector, source.category);
+    const dest = await this._resolveDocPoint(target.panelSelector, target.docX, target.docY);
+    await this._drag(src, dest);
+  }
+
+  /**
+   * Move an existing node within a GoJS Diagram.
+   *
+   * @param {{ panelSelector: string, key: string|number }} source
+   * @param {{ panelSelector: string, docX: number, docY: number }} target
+   */
+  async moveNode(source, target) {
+    const src = await this._resolveDiagramNode(source.panelSelector, source.key);
+    const dest = await this._resolveDocPoint(target.panelSelector, target.docX, target.docY);
+    await this._drag(src, dest);
+  }
+
+  /**
+   * Create a directed link between two GoJS nodes via the model API.
+   *
+   * This method uses diagram.model.addLinkData() which bypasses the invisible
+   * overlay div that intercepts all coordinate-based pointer events on the GoJS
+   * canvas.  Raw mouse drag approaches (including _drag()) are unreliable for
+   * link creation because the port hit areas are small and position-dependent.
+   *
+   * Usage (TypeScript):
+   *
+   *   await gojs.linkNodes(
+   *     { panelSelector: '#myDiagram', key: 'TaskA' },
+   *     { panelSelector: '#myDiagram', key: 'TaskB' },
+   *   );
+   *
+   * @param {{ panelSelector: string, key: string|number, port?: string }} source
+   * @param {{ panelSelector: string, key: string|number, port?: string }} target
+   */
+  async linkNodes(source, target) {
+    await this._evaluateInFrame(([sel, fromKey, toKey, fromPort, toPort]) => {
+      const container = document.querySelector(sel);
+      if (!container) return;
+      const diagram = window.go?.Diagram?.fromDiv?.(container);
+      if (!diagram) return;
+      const linkData = { from: fromKey, to: toKey };
+      if (fromPort) linkData.fromPort = fromPort;
+      if (toPort) linkData.toPort = toPort;
+      const txName = `link ${fromKey} -> ${toKey}`;
+      diagram.startTransaction(txName);
+      diagram.model.addLinkData(linkData);
+      diagram.commitTransaction(txName);
+    }, [source.panelSelector, source.key, target.key, source.port ?? '', target.port ?? '']);
+  }
+
+  /**
+   * Add a new node to a GoJS diagram, placing it at a position relative to an
+   * existing anchor node.  App-specific properties are copied from the palette
+   * template for the given category, skipping GoJS internal fields and the loc
+   * property to prevent palette mutation from corrupting subsequent placements.
+   *
+   * Usage (TypeScript):
+   *
+   *   await _canvas.addNode({
+   *     key: 'Conditional-0001',
+   *     category: 'Conditional',
+   *     diagramSelector: '#divCenter',
+   *     paletteSelector: '#divLeft',
+   *     anchorKey: 'InputTask-0001',
+   *     anchorOffsetX: -9,
+   *     anchorOffsetY: 137,
+   *   });
+   *
+   * @param {{
+   *   key: string,
+   *   category: string,
+   *   diagramSelector: string,
+   *   paletteSelector?: string,
+   *   anchorKey?: string,
+   *   anchorOffsetX?: number,
+   *   anchorOffsetY?: number,
+   * }} opts
+   */
+  async addNode(opts) {
+    const {
+      key,
+      category,
+      diagramSelector,
+      paletteSelector,
+      anchorKey,
+      anchorOffsetX = 0,
+      anchorOffsetY = 0,
+    } = opts;
+
+    await this._evaluateInFrame(([diagSel, palSel, nodeKey, nodeCat, anKey, offX, offY]) => {
+      const go = window.go;
+      if (!go) throw new Error('GoJSDiagram: GoJS not found on window');
+      const diagramDiv = document.querySelector(diagSel);
+      if (!diagramDiv) throw new Error(`GoJSDiagram: panel not found for "${diagSel}"`);
+      const diagram = go.Diagram.fromDiv(diagramDiv);
+      if (!diagram) throw new Error(`GoJSDiagram: no GoJS diagram found for "${diagSel}"`);
+
+      const nodeData = { key: nodeKey, category: nodeCat };
+
+      // Copy app-specific properties from the palette template, skipping GoJS
+      // internals and loc to prevent palette mutation across multiple addNode calls.
+      if (palSel) {
+        const paletteDiv = document.querySelector(palSel);
+        const palette = paletteDiv ? go.Diagram.fromDiv(paletteDiv) : null;
+        if (palette) {
+          const skip = new Set(['__gohashid', '__gohash', 'loc', 'key']);
+          palette.nodes.each((n) => {
+            if (n.data?.category === nodeCat) {
+              for (const prop in n.data) {
+                if (!skip.has(prop)) nodeData[prop] = n.data[prop];
+              }
+            }
+          });
+        }
+      }
+
+      const txName = `add ${nodeCat} node`;
+      diagram.startTransaction(txName);
+      try {
+        diagram.model.addNodeData(nodeData);
+        const node = diagram.findNodeForKey(nodeKey);
+        if (node && anKey) {
+          const anchor = diagram.findNodeForKey(anKey);
+          if (!anchor) throw new Error(`GoJSDiagram: anchor node "${anKey}" not found`);
+          node.location = new go.Point(anchor.location.x + offX, anchor.location.y + offY);
+        }
+      } finally {
+        diagram.commitTransaction(txName);
+      }
+    }, [diagramSelector, paletteSelector ?? '', key, category, anchorKey ?? '', anchorOffsetX, anchorOffsetY]);
+  }
+}
+
+module.exports = GoJSDiagram;
+

package/src/index.d.ts

@@ -19,4 +19,5 @@ export * from "./classes/AsyncTestStatus";
 export * from "./utils";
 export * from "./function";
 export * from "./classes/SmartPlaywright";
+export * from "./classes/GoJSDiagram";
 export * from "./workspace";

package/src/index.js

@@ -20,6 +20,7 @@ const MockV2 = require('./classes/MockV2');
 const { getValue, getResponseValue, checkSchema, iterate, pushToolEvent, getBaseUrl } = require('./utils');
 const { checkStatusCode, checkRequestPayload } = require('./function');
 const { newSkyrampPlaywrightPage, expect } = require('./classes/SmartPlaywright');
+const GoJSDiagram = require('./classes/GoJSDiagram');
 const {
   workspaceConfigSchema,
   serviceSchema,
@@ -60,6 +61,7 @@ module.exports = {
   pushToolEvent,
   getBaseUrl,
   newSkyrampPlaywrightPage,
+  GoJSDiagram,
   expect,
   workspaceConfigSchema,
   serviceSchema,