@html-graph/html-graph 3.1.0 → 3.3.0

package/README.md

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

package/dist/html-graph.d.ts

@@ -42,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;
@@ -79,13 +88,19 @@ 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 graphStore;
     private readonly viewportStore;
     private readonly htmlView;
     /**
-     * provides api for accessing graph model
+     * provides api for accessing model of rendered graph
      */
     readonly graph: Graph;
     /**
@@ -109,10 +124,17 @@ export declare class Canvas {
     private readonly onBeforeEdgeRemoved;
     private readonly onBeforeClear;
     private readonly onBeforeDestroyEmitter;
+    /**
+     * emits event just before destruction of canvas
+     */
     readonly onBeforeDestroy: EventHandler<void>;
-    constructor(element: HTMLElement, graphStore: GraphStore, viewportStore: ViewportStore, htmlView: HtmlView, options: CanvasDefaults);
+    constructor(
     /**
-     * adds node to graph
+     * @deprecated access element directly instead
+     */
+    element: HTMLElement, graphStore: GraphStore, viewportStore: ViewportStore, htmlView: HtmlView, defaults: CanvasDefaults);
+    /**
+     * adds new node
      */
     addNode(request: AddNodeRequest): Canvas;
     /**
@@ -120,42 +142,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;
     /**
@@ -170,16 +192,24 @@ 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 connectablePortsOptions;
     private virtualScrollOptions;
     private hasDraggableNode;
     private hasTransformableViewport;
     private hasResizeReactiveNodes;
+    private hasBackground;
+    private hasUserConnectablePorts;
     private boxRenderingTrigger;
+    private readonly window;
     setElement(element: HTMLElement): CanvasBuilder;
     /**
      * specifies default values for graph entities
@@ -201,11 +231,27 @@ export declare class CanvasBuilder {
      * sets emitter for rendering graph inside bounded area
      */
     enableBoxAreaRendering(trigger: EventSubject<RenderingBox>): CanvasBuilder;
+    /**
+     * enables built-in virtual scroll behavior, when only nodes and edges close
+     * to viewport are rendered
+     */
     enableVirtualScroll(options: VirtualScrollOptions): CanvasBuilder;
+    /**
+     * enables built-in background rendering
+     */
+    enableBackground(options?: BackgroundOptions): CanvasBuilder;
+    /**
+     * enables edge creation by dragging one port to another
+     */
+    enableUserConnectablePorts(options?: ConnectablePortsOptions): CanvasBuilder;
     /**
      * builds final canvas
      */
     build(): Canvas;
+    /**
+     * @deprecated
+     * CanvasBuilder should be single use object
+     */
     private reset;
 }
 
@@ -250,16 +296,34 @@ export declare interface CanvasDefaults {
 
 export declare type CenterFn = (width: number, height: number) => Point;
 
+export declare interface ConnectablePortsOptions {
+    readonly connectionTypeResolver?: ConnectionTypeResolver;
+    readonly connectionPreprocessor?: ConnectionPreprocessor;
+    readonly mouseDownEventVerifier?: MouseEventVerifier;
+    readonly events?: {
+        readonly onAfterEdgeCreated?: (edgeId: unknown) => void;
+    };
+}
+
+export declare type ConnectionPreprocessor = (request: AddEdgeRequest) => AddEdgeRequest | null;
+
+export declare type ConnectionTypeResolver = (portId: unknown) => "direct" | "reverse" | null;
+
 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?: {
         readonly dragCursor?: string | null;
-        readonly mouseDownEventVerifier?: (event: MouseEvent) => boolean;
-        readonly mouseUpEventVerifier?: (event: MouseEvent) => boolean;
+        readonly mouseDownEventVerifier?: MouseEventVerifier;
+        readonly mouseUpEventVerifier?: MouseEventVerifier;
     };
     readonly events?: {
         readonly onNodeDrag?: (payload: NodeDragPayload) => void;
@@ -290,6 +354,9 @@ export declare interface EdgeRenderPort {
     readonly nodeId: unknown;
 }
 
+/**
+ * Responsibility: Rendering edge via SVG
+ */
 export declare interface EdgeShape {
     readonly svg: SVGSVGElement;
     render(params: EdgeRenderParams): void;
@@ -299,15 +366,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;
@@ -316,7 +392,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;
@@ -372,14 +448,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>;
@@ -474,10 +550,17 @@ 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;
@@ -507,6 +590,8 @@ export declare interface MarkPortRequest {
     readonly direction?: number;
 }
 
+export declare type MouseEventVerifier = (event: MouseEvent) => boolean;
+
 export declare interface NodeDragPayload {
     readonly nodeId: unknown;
     readonly element: HTMLElement;
@@ -535,6 +620,9 @@ declare interface PatchTransformRequest {
     readonly y?: number;
 }
 
+/**
+ * Responsibility: Specifies point coordinates
+ */
 export declare interface Point {
     readonly x: number;
     readonly y: number;
@@ -548,6 +636,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 {
@@ -614,8 +705,8 @@ export declare interface TransformOptions {
     };
     readonly shift?: {
         readonly cursor?: string | null;
-        readonly mouseDownEventVerifier?: (event: MouseEvent) => boolean;
-        readonly mouseUpEventVerifier?: (event: MouseEvent) => boolean;
+        readonly mouseDownEventVerifier?: MouseEventVerifier;
+        readonly mouseUpEventVerifier?: MouseEventVerifier;
     };
     readonly transformPreprocessor?: TransformPreprocessorOption | TransformPreprocessorOption[];
     readonly events?: {
@@ -735,19 +826,19 @@ 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;
+    private readonly viewportStore;
     readonly onBeforeUpdated: EventHandler<void>;
     readonly onAfterUpdated: EventHandler<void>;
-    constructor(transformer: ViewportStore);
+    constructor(viewportStore: ViewportStore);
     getViewportMatrix(): TransformState;
     getContentMatrix(): TransformState;
 }
 
 /**
- * This entity is responsible for storing viewport transformation
+ * Responsibility: Stores viewport transformation state
  */
 declare class ViewportStore {
     private viewportMatrix;