@html-graph/html-graph 3.6.0 → 3.8.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,8 +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;
+    readonly group: SVGGElement;
+    readonly line: SVGPathElement;
+    readonly sourceArrow: SVGPathElement | null;
+    readonly targetArrow: SVGPathElement | null;
     private readonly arrowLength;
     private readonly arrowWidth;
     private readonly curvature;
@@ -76,7 +83,7 @@ export declare class BezierEdgeShape implements EdgeShape {
     private readonly detourDistance;
     private readonly hasSourceArrow;
     private readonly hasTargetArrow;
-    private readonly genericShape;
+    private readonly lineShape;
     private readonly createCyclePath;
     private readonly createDetourPath;
     private readonly createLinePath;
@@ -99,6 +106,7 @@ export declare class Canvas {
     private readonly graphStore;
     private readonly viewportStore;
     private readonly htmlView;
+    private readonly defaults;
     /**
      * provides api for accessing model of rendered graph
      */
@@ -107,7 +115,6 @@ export declare class Canvas {
      * provides api for accessing viewport state
      */
     readonly viewport: Viewport;
-    private readonly defaults;
     private readonly nodeIdGenerator;
     private readonly portIdGenerator;
     private readonly edgeIdGenerator;
@@ -132,7 +139,7 @@ export declare class Canvas {
     /**
      * @deprecated access element directly instead
      */
-    element: HTMLElement, graphStore: GraphStore, viewportStore: ViewportStore, htmlView: HtmlView, defaults: CanvasDefaults);
+    element: HTMLElement, graphStore: GraphStore, viewportStore: ViewportStore, htmlView: HtmlView, defaults: Defaults);
     /**
      * adds new node
      */
@@ -322,8 +329,24 @@ 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 Defaults {
+    readonly nodes: {
+        readonly centerFn: CenterFn;
+        readonly priorityFn: PriorityFn;
+    };
+    readonly ports: {
+        readonly direction: number;
+    };
+    readonly edges: {
+        readonly shapeFactory: EdgeShapeFactory;
+        readonly priorityFn: PriorityFn;
+    };
+}
+
 declare interface DotsRenderer {
     readonly radius?: number;
     readonly color?: string;
@@ -377,7 +400,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
@@ -424,10 +447,12 @@ export declare class Graph {
     readonly onBeforeClear: EventHandler<void>;
     constructor(graphStore: GraphStore);
     getNode(nodeId: unknown): GraphNode | null;
+    getElementNodeId(element: HTMLElement): unknown | null;
     getAllNodeIds(): readonly unknown[];
     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;
@@ -461,15 +486,17 @@ export declare interface GraphPort {
 }
 
 /**
- * Responsibility: Stores stae of graph
+ * Responsibility: Store state of graph
  */
 declare class GraphStore {
     private readonly nodes;
     private readonly ports;
     private readonly edges;
+    private readonly nodesElementsMap;
     private readonly incomingEdges;
     private readonly outcomingEdges;
     private readonly cycleEdges;
+    private readonly elementPorts;
     private readonly afterNodeAddedEmitter;
     readonly onAfterNodeAdded: EventHandler<unknown>;
     private readonly afterNodeUpdatedEmitter;
@@ -500,12 +527,14 @@ declare class GraphStore {
     addNode(request: AddNodeRequest_2): void;
     getAllNodeIds(): readonly unknown[];
     getNode(nodeId: unknown): NodePayload | undefined;
+    getElementNodeId(element: HTMLElement): unknown | undefined;
     updateNode(nodeId: unknown, request: UpdateNodeRequest_2): void;
     removeNode(nodeId: unknown): void;
     addPort(request: AddPortRequest): void;
     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;
@@ -540,8 +569,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;
+    readonly group: SVGGElement;
+    readonly line: SVGPathElement;
+    readonly sourceArrow: SVGPathElement | null;
+    readonly targetArrow: SVGPathElement | null;
     private readonly arrowLength;
     private readonly arrowWidth;
     private readonly arrowOffset;
@@ -551,7 +588,7 @@ export declare class HorizontalEdgeShape implements EdgeShape {
     private readonly detourDistance;
     private readonly hasSourceArrow;
     private readonly hasTargetArrow;
-    private readonly genericShape;
+    private readonly lineShape;
     private readonly createCyclePath;
     private readonly createDetourPath;
     private readonly createLinePath;
@@ -590,6 +627,62 @@ declare interface HtmlView {
 
 declare type IncrementalPriority = "incremental";
 
+export declare class InteractiveEdgeError extends Error {
+    constructor(message: string);
+}
+
+export declare interface InteractiveEdgeParams {
+    /**
+     * TODO: rename to 'radius'
+     */
+    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;
@@ -687,8 +780,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;
+    readonly group: SVGGElement;
+    readonly line: SVGPathElement;
+    readonly sourceArrow: SVGPathElement | null;
+    readonly targetArrow: SVGPathElement | null;
     private readonly arrowLength;
     private readonly arrowWidth;
     private readonly arrowOffset;
@@ -698,7 +798,7 @@ export declare class StraightEdgeShape implements EdgeShape {
     private readonly detourDistance;
     private readonly hasSourceArrow;
     private readonly hasTargetArrow;
-    private readonly genericShape;
+    private readonly lineShape;
     private readonly createCyclePath;
     private readonly createDetourPath;
     private readonly createLinePath;
@@ -710,6 +810,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;
@@ -793,8 +903,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;
+    readonly group: SVGGElement;
+    readonly line: SVGPathElement;
+    readonly sourceArrow: SVGPathElement | null;
+    readonly targetArrow: SVGPathElement | null;
     private readonly arrowLength;
     private readonly arrowWidth;
     private readonly arrowOffset;
@@ -804,7 +922,7 @@ export declare class VerticalEdgeShape implements EdgeShape {
     private readonly detourDistance;
     private readonly hasSourceArrow;
     private readonly hasTargetArrow;
-    private readonly genericShape;
+    private readonly lineShape;
     private readonly createCyclePath;
     private readonly createDetourPath;
     private readonly createLinePath;