@html-graph/html-graph 3.5.1 → 3.7.0

package/README.md

@@ -23,65 +23,74 @@ npm i @html-graph/html-graph
 ```javascript
 import { CanvasBuilder } from "@html-graph/html-graph";
 
-function createNode({ name, x, y, frontPortId, backPortId }) {
-  const node = document.createElement("div");
-  const text = document.createElement("div");
-  const frontPort = document.createElement("div");
-  const backPort = document.createElement("div");
+class Application {
+  constructor(element) {
+    this.canvas = new CanvasBuilder(element)
+      .setDefaults({
+        edges: {
+          shape: {
+            hasTargetArrow: true,
+          },
+        },
+      })
+      .enableUserDraggableNodes()
+      .enableUserTransformableViewport()
+      .enableBackground()
+      .build();
+  }
 
-  node.classList.add("node");
-  frontPort.classList.add("port");
-  backPort.classList.add("port");
-  text.innerText = name;
+  initGraph() {
+    this.canvas
+      .addNode(
+        this.createNode({
+          name: "Node 1",
+          x: 200,
+          y: 400,
+          frontPortId: "node-1-in",
+          backPortId: "node-1-out",
+        }),
+      )
+      .addNode(
+        this.createNode({
+          name: "Node 2",
+          x: 600,
+          y: 500,
+          frontPortId: "node-2-in",
+          backPortId: "node-2-out",
+        }),
+      )
+      .addEdge({ from: "node-1-out", to: "node-2-in" });
+  }
 
-  node.appendChild(frontPort);
-  node.appendChild(text);
-  node.appendChild(backPort);
+  createNode({ name, x, y, frontPortId, backPortId }) {
+    const node = document.createElement("div");
+    const text = document.createElement("div");
+    const frontPort = document.createElement("div");
+    const backPort = document.createElement("div");
 
-  return {
-    element: node,
-    x: x,
-    y: y,
-    ports: [
-      { id: frontPortId, element: frontPort },
-      { id: backPortId, element: backPort },
-    ],
-  };
+    node.classList.add("node");
+    frontPort.classList.add("port");
+    backPort.classList.add("port");
+    text.innerText = name;
+
+    node.appendChild(frontPort);
+    node.appendChild(text);
+    node.appendChild(backPort);
+
+    return {
+      element: node,
+      x: x,
+      y: y,
+      ports: [
+        { id: frontPortId, element: frontPort },
+        { id: backPortId, element: backPort },
+      ],
+    };
+  }
 }
 
 const element = document.getElementById("canvas");
+const app = new Application(element);
 
-const canvas = new CanvasBuilder(element)
-  .setDefaults({
-    edges: {
-      shape: {
-        hasTargetArrow: true,
-      },
-    },
-  })
-  .enableUserDraggableNodes()
-  .enableUserTransformableViewport()
-  .enableBackground()
-  .build();
-
-canvas
-  .addNode(
-    createNode({
-      name: "Node 1",
-      x: 200,
-      y: 400,
-      frontPortId: "node-1-in",
-      backPortId: "node-1-out",
-    }),
-  )
-  .addNode(
-    createNode({
-      name: "Node 2",
-      x: 600,
-      y: 500,
-      frontPortId: "node-2-in",
-      backPortId: "node-2-out",
-    }),
-  )
-  .addEdge({ from: "node-1-out", to: "node-2-in" });
+app.initGraph();
 ```

package/dist/html-graph.d.ts

@@ -65,12 +65,15 @@ export declare interface BezierEdgeParams {
     readonly detourDirection?: number | undefined;
 }
 
-export declare class BezierEdgeShape implements EdgeShape {
+/**
+ * Responsibility: Providing edge shape connecting ports with bezier line
+ */
+export declare class BezierEdgeShape implements StructuredEdgeShape {
     readonly svg: SVGSVGElement;
-    private readonly group;
-    private readonly line;
-    private readonly sourceArrow;
-    private readonly targetArrow;
+    readonly group: SVGGElement;
+    readonly line: SVGPathElement;
+    readonly sourceArrow: SVGPathElement | null;
+    readonly targetArrow: SVGPathElement | null;
     private readonly arrowLength;
     private readonly arrowWidth;
     private readonly curvature;
@@ -80,6 +83,10 @@ export declare class BezierEdgeShape implements EdgeShape {
     private readonly detourDistance;
     private readonly hasSourceArrow;
     private readonly hasTargetArrow;
+    private readonly lineShape;
+    private readonly createCyclePath;
+    private readonly createDetourPath;
+    private readonly createLinePath;
     constructor(params?: BezierEdgeParams);
     render(params: EdgeRenderParams): void;
 }
@@ -306,8 +313,11 @@ declare interface ConnectablePortsConfig {
     readonly connectionPreprocessor?: ConnectionPreprocessor;
     readonly mouseDownEventVerifier?: MouseEventVerifier;
     readonly mouseUpEventVerifier?: MouseEventVerifier;
+    readonly dragPortDirection?: number | undefined;
     readonly events?: {
         readonly onAfterEdgeCreated?: (edgeId: unknown) => void;
+        readonly onEdgeCreationInterrupted?: (staticPortId: unknown, isDirect: boolean) => void;
+        readonly onEdgeCreationPrevented?: (request: AddEdgeRequest) => void;
     };
 }
 export { ConnectablePortsConfig }
@@ -319,6 +329,8 @@ export declare type ConnectionTypeResolver = (portId: unknown) => "direct" | "re
 
 declare type ConstantPriority = number;
 
+export declare type CreatePathFn = (sourceDirection: Point, targetDirection: Point, to: Point, flipX: number, flipY: number) => string;
+
 declare type CustomPriority = PriorityFn;
 
 declare interface DotsRenderer {
@@ -374,7 +386,7 @@ export declare interface EdgeShape {
 
 declare type EdgeShapeConfig = BezierEdgeShapeConfig | StraightEdgeShapeConfig | HorizontalEdgeShapeConfig | VerticalEdgeShapeConfig | EdgeShapeFactory;
 
-declare type EdgeShapeFactory = () => EdgeShape;
+declare type EdgeShapeFactory = (edgeId: unknown) => EdgeShape;
 
 /**
  * Responsibility: Provides a way to trigger events
@@ -425,6 +437,7 @@ export declare class Graph {
     getPort(portId: unknown): GraphPort | null;
     getAllPortIds(): readonly unknown[];
     getNodePortIds(nodeId: unknown): readonly unknown[] | null;
+    getElementPortsIds(element: HTMLElement): readonly unknown[];
     getAllEdgeIds(): readonly unknown[];
     getEdge(edgeId: unknown): GraphEdge | null;
     getPortIncomingEdgeIds(portId: unknown): readonly unknown[] | null;
@@ -458,7 +471,7 @@ export declare interface GraphPort {
 }
 
 /**
- * Responsibility: Stores stae of graph
+ * Responsibility: Store state of graph
  */
 declare class GraphStore {
     private readonly nodes;
@@ -467,6 +480,7 @@ declare class GraphStore {
     private readonly incomingEdges;
     private readonly outcomingEdges;
     private readonly cycleEdges;
+    private readonly elementPorts;
     private readonly afterNodeAddedEmitter;
     readonly onAfterNodeAdded: EventHandler<unknown>;
     private readonly afterNodeUpdatedEmitter;
@@ -503,6 +517,7 @@ declare class GraphStore {
     getPort(portId: unknown): PortPayload | undefined;
     updatePort(portId: unknown, request: UpdatePortRequest_2): void;
     getAllPortIds(): readonly unknown[];
+    getElementPortsIds(element: HTMLElement): readonly unknown[];
     getNodePortIds(nodeId: unknown): readonly unknown[] | undefined;
     removePort(portId: unknown): void;
     addEdge(request: AddEdgeRequest_2): void;
@@ -537,12 +552,16 @@ export declare interface HorizontalEdgeParams {
     readonly detourDirection?: number | undefined;
 }
 
-export declare class HorizontalEdgeShape implements EdgeShape {
+/**
+ * Responsibility: Providing edge shape connecting ports with horizontal angled
+ * line
+ */
+export declare class HorizontalEdgeShape implements StructuredEdgeShape {
     readonly svg: SVGSVGElement;
-    private readonly group;
-    private readonly line;
-    private readonly sourceArrow;
-    private readonly targetArrow;
+    readonly group: SVGGElement;
+    readonly line: SVGPathElement;
+    readonly sourceArrow: SVGPathElement | null;
+    readonly targetArrow: SVGPathElement | null;
     private readonly arrowLength;
     private readonly arrowWidth;
     private readonly arrowOffset;
@@ -552,6 +571,10 @@ export declare class HorizontalEdgeShape implements EdgeShape {
     private readonly detourDistance;
     private readonly hasSourceArrow;
     private readonly hasTargetArrow;
+    private readonly lineShape;
+    private readonly createCyclePath;
+    private readonly createDetourPath;
+    private readonly createLinePath;
     constructor(params?: HorizontalEdgeParams);
     render(params: EdgeRenderParams): void;
 }
@@ -587,6 +610,59 @@ declare interface HtmlView {
 
 declare type IncrementalPriority = "incremental";
 
+export declare class InteractiveEdgeError extends Error {
+    constructor(message: string);
+}
+
+export declare interface InteractiveEdgeParams {
+    readonly width?: number;
+}
+
+/**
+ * Responsibility: Providing handle for attaching interactive behavior to an
+ * edge
+ */
+export declare class InteractiveEdgeShape implements StructuredEdgeShape {
+    private readonly structuredEdge;
+    readonly svg: SVGSVGElement;
+    readonly group: SVGGElement;
+    readonly line: SVGPathElement;
+    readonly sourceArrow: SVGPathElement | null;
+    readonly targetArrow: SVGPathElement | null;
+    readonly handle: SVGGElement;
+    private readonly interactiveLine;
+    private readonly interactiveSourceArrow;
+    private readonly interactiveTargetArrow;
+    constructor(structuredEdge: StructuredEdgeShape, params?: InteractiveEdgeParams);
+    render(params: EdgeRenderParams): void;
+}
+
+export declare interface LineEdgeParams {
+    readonly width: number;
+    readonly color: string;
+    readonly arrowLength: number;
+    readonly arrowWidth: number;
+    readonly hasSourceArrow: boolean;
+    readonly hasTargetArrow: boolean;
+    readonly createCyclePath: CreatePathFn;
+    readonly createDetourPath: CreatePathFn;
+    readonly createLinePath: CreatePathFn;
+}
+
+/**
+ * Responsibility: Providing low level core for single line structured edges
+ */
+export declare class LineEdgeShape implements StructuredEdgeShape {
+    private readonly params;
+    readonly svg: SVGSVGElement;
+    readonly group: SVGGElement;
+    readonly line: SVGPathElement;
+    readonly sourceArrow: SVGPathElement | null;
+    readonly targetArrow: SVGPathElement | null;
+    constructor(params: LineEdgeParams);
+    render(params: EdgeRenderParams): void;
+}
+
 export declare type MarkNodePortRequest = {
     readonly id?: unknown | undefined;
     readonly element: HTMLElement;
@@ -684,12 +760,15 @@ export declare interface StraightEdgeParams {
     readonly detourDirection?: number | undefined;
 }
 
-export declare class StraightEdgeShape implements EdgeShape {
+/**
+ * Responsibility: Providing edge shape connecting ports with straight line
+ */
+export declare class StraightEdgeShape implements StructuredEdgeShape {
     readonly svg: SVGSVGElement;
-    private readonly group;
-    private readonly line;
-    private readonly sourceArrow;
-    private readonly targetArrow;
+    readonly group: SVGGElement;
+    readonly line: SVGPathElement;
+    readonly sourceArrow: SVGPathElement | null;
+    readonly targetArrow: SVGPathElement | null;
     private readonly arrowLength;
     private readonly arrowWidth;
     private readonly arrowOffset;
@@ -699,6 +778,10 @@ export declare class StraightEdgeShape implements EdgeShape {
     private readonly detourDistance;
     private readonly hasSourceArrow;
     private readonly hasTargetArrow;
+    private readonly lineShape;
+    private readonly createCyclePath;
+    private readonly createDetourPath;
+    private readonly createLinePath;
     constructor(params?: StraightEdgeParams);
     render(params: EdgeRenderParams): void;
 }
@@ -707,6 +790,16 @@ declare type StraightEdgeShapeConfig = {
     readonly type: "straight";
 } & StraightEdgeParams;
 
+/**
+ * Responsibility: Specifying EdgeShape with a standard visual structure
+ */
+export declare interface StructuredEdgeShape extends EdgeShape {
+    readonly group: SVGGElement;
+    readonly line: SVGPathElement;
+    readonly sourceArrow: SVGPathElement | null;
+    readonly targetArrow: SVGPathElement | null;
+}
+
 export declare interface TransformPayload {
     readonly scale: number;
     readonly x: number;
@@ -790,12 +883,16 @@ export declare interface VerticalEdgeParams {
     readonly detourDirection?: number | undefined;
 }
 
-export declare class VerticalEdgeShape implements EdgeShape {
+/**
+ * Responsibility: Providing edge shape connecting ports with vertical angled
+ * line
+ */
+export declare class VerticalEdgeShape implements StructuredEdgeShape {
     readonly svg: SVGSVGElement;
-    private readonly group;
-    private readonly line;
-    private readonly sourceArrow;
-    private readonly targetArrow;
+    readonly group: SVGGElement;
+    readonly line: SVGPathElement;
+    readonly sourceArrow: SVGPathElement | null;
+    readonly targetArrow: SVGPathElement | null;
     private readonly arrowLength;
     private readonly arrowWidth;
     private readonly arrowOffset;
@@ -805,6 +902,10 @@ export declare class VerticalEdgeShape implements EdgeShape {
     private readonly detourDistance;
     private readonly hasSourceArrow;
     private readonly hasTargetArrow;
+    private readonly lineShape;
+    private readonly createCyclePath;
+    private readonly createDetourPath;
+    private readonly createLinePath;
     constructor(params?: VerticalEdgeParams);
     render(params: EdgeRenderParams): void;
 }