@html-graph/html-graph 3.0.0 → 3.2.0

package/README.md

@@ -62,6 +62,7 @@ const canvas = new CanvasBuilder()
   })
   .enableUserDraggableNodes()
   .enableUserTransformableViewport()
+  .enableBackground()
   .build();
 
 canvas

package/dist/html-graph.d.ts

@@ -14,14 +14,6 @@ declare interface AddEdgeRequest_2 {
     readonly priority: number;
 }
 
-declare interface AddEdgeRequest_3 {
-    readonly id: unknown;
-    readonly from: unknown;
-    readonly to: unknown;
-    readonly shape: EdgeShape;
-    readonly priority: number;
-}
-
 export declare type AddNodePorts = Iterable<MarkNodePortRequest>;
 
 export declare interface AddNodeRequest {
@@ -43,15 +35,6 @@ declare interface AddNodeRequest_2 {
     readonly priority: number;
 }
 
-declare interface AddNodeRequest_3 {
-    readonly id: unknown;
-    readonly element: HTMLElement;
-    readonly x: number;
-    readonly y: number;
-    readonly centerFn: CenterFn;
-    readonly priority: number;
-}
-
 declare interface AddPortRequest {
     readonly id: unknown;
     readonly nodeId: unknown;
@@ -59,6 +42,15 @@ declare interface AddPortRequest {
     readonly direction: number;
 }
 
+declare interface BackgroundOptions {
+    readonly tileDimensions?: {
+        readonly width?: number;
+        readonly height?: number;
+    };
+    readonly renderer?: DotsRenderer | SVGElement;
+    readonly maxViewportScale?: number;
+}
+
 export declare interface BezierEdgeParams {
     readonly color?: string | undefined;
     readonly width?: number | undefined;
@@ -96,24 +88,50 @@ declare type BezierEdgeShapeConfig = {
     readonly type?: "bezier" | undefined;
 } & BezierEdgeParams;
 
+/**
+ * Responsibility: provides graph rendering API for end user
+ */
 export declare class Canvas {
+    /**
+     * @deprecated access element directly instead
+     */
     readonly element: HTMLElement;
-    private readonly controller;
-    private readonly nodeIdGenerator;
-    private readonly portIdGenerator;
-    private readonly edgeIdGenerator;
-    private readonly defaults;
+    private readonly graphStore;
+    private readonly viewportStore;
+    private readonly htmlView;
     /**
-     * provides api for accessing graph model
+     * provides api for accessing model of rendered graph
      */
     readonly graph: Graph;
     /**
      * provides api for accessing viewport state
      */
     readonly viewport: Viewport;
-    constructor(element: HTMLElement, controller: CanvasController, options: CanvasDefaults);
+    private readonly defaults;
+    private readonly nodeIdGenerator;
+    private readonly portIdGenerator;
+    private readonly edgeIdGenerator;
+    private readonly onAfterNodeAdded;
+    private readonly onAfterNodeUpdated;
+    private readonly onAfterNodePriorityUpdated;
+    private readonly onBeforeNodeRemoved;
+    private readonly onAfterPortUpdated;
+    private readonly onBeforePortUnmarked;
+    private readonly onAfterEdgeAdded;
+    private readonly onAfterEdgeShapeUpdated;
+    private readonly onAfterEdgeUpdated;
+    private readonly onAfterEdgePriorityUpdated;
+    private readonly onBeforeEdgeRemoved;
+    private readonly onBeforeClear;
+    private readonly onBeforeDestroyEmitter;
+    readonly onBeforeDestroy: EventHandler<void>;
+    constructor(
+    /**
+     * @deprecated access element directly instead
+     */
+    element: HTMLElement, graphStore: GraphStore, viewportStore: ViewportStore, htmlView: HtmlView, options: CanvasDefaults);
     /**
-     * adds node to graph
+     * adds new node
      */
     addNode(request: AddNodeRequest): Canvas;
     /**
@@ -121,42 +139,42 @@ export declare class Canvas {
      */
     updateNode(nodeId: unknown, request?: UpdateNodeRequest): Canvas;
     /**
-     * removes node from graph
+     * removes specified node
      * all the ports of node get unmarked
      * all the edges adjacent to node get removed
      */
     removeNode(nodeId: unknown): Canvas;
     /**
-     * marks element as port of node
+     * marks specified element as a port for specified node
      */
     markPort(request: MarkPortRequest): Canvas;
     /**
-     * updates port and attached edges
+     * updates port and edges attached to it
      */
     updatePort(portId: unknown, request?: UpdatePortRequest): Canvas;
     /**
-     * ummarks element as port of node
-     * all the edges adjacent to port get removed
+     * unmarks specified port
+     * all the edges adjacent to the port get removed
      */
     unmarkPort(portId: unknown): Canvas;
     /**
-     * adds edge to graph
+     * adds new edge
      */
     addEdge(request: AddEdgeRequest): Canvas;
     /**
-     * updates edge
+     * updates specified edge
      */
     updateEdge(edgeId: unknown, request?: UpdateEdgeRequest): Canvas;
     /**
-     * removes edge from graph
+     * removes specified edge
      */
     removeEdge(edgeId: unknown): Canvas;
     /**
-     * applies transformation for viewport
+     * applies transformation for viewport matrix
      */
     patchViewportMatrix(request: PatchMatrixRequest): Canvas;
     /**
-     * applies transformation for content
+     * applies transformation for content matrix
      */
     patchContentMatrix(request: PatchMatrixRequest): Canvas;
     /**
@@ -171,15 +189,20 @@ export declare class Canvas {
     destroy(): void;
 }
 
+/**
+ * Responsibility: Constructs canvas based on specified configuration
+ */
 export declare class CanvasBuilder {
     private element;
     private canvasDefaults;
     private dragOptions;
     private transformOptions;
+    private backgroundOptions;
     private virtualScrollOptions;
     private hasDraggableNode;
     private hasTransformableViewport;
     private hasResizeReactiveNodes;
+    private hasBackground;
     private boxRenderingTrigger;
     setElement(element: HTMLElement): CanvasBuilder;
     /**
@@ -203,31 +226,18 @@ export declare class CanvasBuilder {
      */
     enableBoxAreaRendering(trigger: EventSubject<RenderingBox>): CanvasBuilder;
     enableVirtualScroll(options: VirtualScrollOptions): CanvasBuilder;
+    enableBackground(options?: BackgroundOptions): CanvasBuilder;
     /**
      * builds final canvas
      */
     build(): Canvas;
+    /**
+     * @deprecated
+     * CanvasBuilder should be single use object
+     */
     private reset;
 }
 
-declare interface CanvasController {
-    readonly graph: Graph;
-    readonly viewport: Viewport;
-    addNode(node: AddNodeRequest_3): void;
-    updateNode(nodeId: unknown, request: UpdateNodeRequest_3): void;
-    removeNode(nodeId: unknown): void;
-    markPort(port: MarkPortRequest_2): void;
-    updatePort(portId: unknown, request: UpdatePortRequest_3): void;
-    unmarkPort(portId: unknown): void;
-    addEdge(edge: AddEdgeRequest_3): void;
-    updateEdge(edgeId: unknown, request: UpdateEdgeRequest_3): void;
-    removeEdge(edgeId: unknown): void;
-    patchViewportMatrix(request: PatchMatrixRequest_2): void;
-    patchContentMatrix(request: PatchMatrixRequest_2): void;
-    clear(): void;
-    destroy(): void;
-}
-
 export declare interface CanvasDefaults {
     /**
      * nodes related behavior
@@ -273,6 +283,11 @@ declare type ConstantPriority = number;
 
 declare type CustomPriority = PriorityFn;
 
+declare interface DotsRenderer {
+    readonly radius?: number;
+    readonly color?: string;
+}
+
 export declare interface DragOptions {
     readonly moveOnTop?: boolean;
     readonly mouse?: {
@@ -309,6 +324,9 @@ export declare interface EdgeRenderPort {
     readonly nodeId: unknown;
 }
 
+/**
+ * Responsibility: Rendering edge via SVG
+ */
 export declare interface EdgeShape {
     readonly svg: SVGSVGElement;
     render(params: EdgeRenderParams): void;
@@ -318,15 +336,24 @@ declare type EdgeShapeConfig = BezierEdgeShapeConfig | StraightEdgeShapeConfig |
 
 declare type EdgeShapeFactory = () => EdgeShape;
 
+/**
+ * Responsibility: Provides a way to trigger events
+ */
 export declare interface EventEmitter<T> {
     emit(payload: T): void;
 }
 
+/**
+ * Responsibility: Provides a way to handle events
+ */
 export declare interface EventHandler<T> {
     subscribe(callback: (payload: T) => void): void;
     unsubscribe(callback: (payload: T) => void): void;
 }
 
+/**
+ * Responsibility: Connects events and event handlers
+ */
 export declare class EventSubject<T> implements EventEmitter<T>, EventHandler<T> {
     private readonly callbacks;
     subscribe(callback: (payload: T) => void): void;
@@ -335,7 +362,7 @@ export declare class EventSubject<T> implements EventEmitter<T>, EventHandler<T>
 }
 
 /**
- * This entity is responsible for providing access to end user in a safe way
+ * Responsibility: Provides access to graph model for end user
  */
 export declare class Graph {
     private readonly graphStore;
@@ -391,14 +418,14 @@ export declare interface GraphPort {
 }
 
 /**
- * This entity is responsible for storing state of graph
+ * Responsibility: Stores stae of graph
  */
 declare class GraphStore {
     private readonly nodes;
     private readonly ports;
     private readonly edges;
-    private readonly incommingEdges;
-    private readonly outcommingEdges;
+    private readonly incomingEdges;
+    private readonly outcomingEdges;
     private readonly cycleEdges;
     private readonly afterNodeAddedEmitter;
     readonly onAfterNodeAdded: EventHandler<unknown>;
@@ -493,10 +520,31 @@ declare type HorizontalEdgeShapeConfig = {
     readonly type: "horizontal";
 } & HorizontalEdgeParams;
 
+/**
+ * Responsibility: Library specific error to throw when unexpected action
+ * occured
+ */
 export declare class HtmlGraphError extends Error {
     readonly name = "HtmlGraphError";
 }
 
+/**
+ * Responsibility: Provides access to DOM modifications
+ */
+declare interface HtmlView {
+    attachNode(nodeId: unknown): void;
+    detachNode(nodeId: unknown): void;
+    attachEdge(edgeId: unknown): void;
+    detachEdge(edgeId: unknown): void;
+    clear(): void;
+    destroy(): void;
+    updateNodePosition(nodeId: unknown): void;
+    updateNodePriority(nodeId: unknown): void;
+    updateEdgeShape(edgeId: unknown): void;
+    renderEdge(edgeId: unknown): void;
+    updateEdgePriority(edgeId: unknown): void;
+}
+
 declare type IncrementalPriority = "incremental";
 
 export declare type MarkNodePortRequest = {
@@ -512,13 +560,6 @@ export declare interface MarkPortRequest {
     readonly direction?: number;
 }
 
-declare interface MarkPortRequest_2 {
-    readonly id: unknown;
-    readonly element: HTMLElement;
-    readonly nodeId: unknown;
-    readonly direction: number;
-}
-
 export declare interface NodeDragPayload {
     readonly nodeId: unknown;
     readonly element: HTMLElement;
@@ -541,18 +582,15 @@ export declare interface PatchMatrixRequest {
     readonly y?: number | undefined;
 }
 
-declare interface PatchMatrixRequest_2 {
-    readonly scale?: number | undefined;
-    readonly x?: number | undefined;
-    readonly y?: number | undefined;
-}
-
 declare interface PatchTransformRequest {
     readonly scale?: number;
     readonly x?: number;
     readonly y?: number;
 }
 
+/**
+ * Responsibility: Specifies point coordinates
+ */
 export declare interface Point {
     readonly x: number;
     readonly y: number;
@@ -566,6 +604,9 @@ declare interface PortPayload {
 
 declare type Priority = ConstantPriority | IncrementalPriority | CustomPriority;
 
+/**
+ * Responsibility: Specifies how to determine Z-index of an entity in DOM
+ */
 export declare type PriorityFn = () => number;
 
 export declare interface RenderingBox {
@@ -693,13 +734,6 @@ declare interface UpdateEdgeRequest_2 {
     readonly priority?: number;
 }
 
-declare interface UpdateEdgeRequest_3 {
-    readonly from?: unknown | undefined;
-    readonly to?: unknown | undefined;
-    readonly shape?: EdgeShape | undefined;
-    readonly priority?: number | undefined;
-}
-
 export declare interface UpdateNodeRequest {
     readonly x?: number | undefined;
     readonly y?: number | undefined;
@@ -714,13 +748,6 @@ declare interface UpdateNodeRequest_2 {
     readonly priority?: number;
 }
 
-declare interface UpdateNodeRequest_3 {
-    readonly x?: number | undefined;
-    readonly y?: number | undefined;
-    readonly priority?: number | undefined;
-    readonly centerFn?: CenterFn | undefined;
-}
-
 export declare interface UpdatePortRequest {
     readonly direction?: number;
 }
@@ -729,10 +756,6 @@ declare interface UpdatePortRequest_2 {
     readonly direction?: number;
 }
 
-declare interface UpdatePortRequest_3 {
-    readonly direction?: number;
-}
-
 export declare interface VerticalEdgeParams {
     readonly color?: string | undefined;
     readonly width?: number | undefined;
@@ -771,7 +794,7 @@ declare type VerticalEdgeShapeConfig = {
 } & VerticalEdgeParams;
 
 /**
- * This entity is responsible for providing viewport API
+ * Responsibility: Provides access to viewport state for end user
  */
 export declare class Viewport {
     private readonly transformer;
@@ -783,7 +806,7 @@ export declare class Viewport {
 }
 
 /**
- * This entity is responsible for storing viewport transformation
+ * Responsibility: Stores viewport transformation state
  */
 declare class ViewportStore {
     private viewportMatrix;