@html-graph/html-graph 0.0.43

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Dmitry Marov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+<h1>
+  <img src="/media/favicon.png" alt="HTMLGraph" width="25" height="25"/> HTMLGraph
+</h1>
+
+## Graph visualization library that enables to customize nodes using HTML
+
+![CI](https://github.com/html-graph/html-graph/actions/workflows/ci.yml/badge.svg?branch=master)
+
+Visit <a target="_blank" href="https://html-graph.github.io">live demo</a>
+
+<a target="_blank" href="https://html-graph.github.io/">
+    <img width="100%" src="https://raw.githubusercontent.com/html-graph/html-graph/master/media/full-demo.gif"/>
+</a>
+
+Instead of connecting nodes dirrectly this library uses concept of ports, which provide greater fexibility at managing connections.
+Port is an entity of the node to which connection can be attached to.
+
+This library fits for tasks where easy nodes customization and interactiveness are required.
+
+## Features:
+
+- easy nodes customization using HTML
+- wide configuration options out of the box
+- draggable and scalable canvas with draggable nodes
+- exhaustive set of examples
+- typescript support
+- mobile devices support
+
+## Getting started:
+
+```
+npm i @html-graph/core
+```
+
+```typescript
+import { ApiPortPayload, CanvasBuilder } from "@html-graph/html-graph";
+
+const canvas = new CanvasBuilder()
+  .options({
+    background: { type: "dots" },
+    connections: { hasTargetArrow: true },
+  })
+  .draggableNodes()
+  .transformableCanvas()
+  .build();
+
+function createNode(
+  name: string,
+  frontPortId: string,
+  backPortId: string,
+): [HTMLElement, Record<string, ApiPortPayload>] {
+  const node = document.createElement("div");
+  node.classList.add("node");
+
+  const frontPort = document.createElement("div");
+  frontPort.classList.add("port");
+  node.appendChild(frontPort);
+
+  const text = document.createElement("div");
+  text.innerText = name;
+  node.appendChild(text);
+
+  const backPort = document.createElement("div");
+  backPort.classList.add("port");
+  node.appendChild(backPort);
+
+  return [node, { [frontPortId]: frontPort, [backPortId]: backPort }];
+}
+
+const [node1, ports1] = createNode("Node 1", "port-1-1", "port-1-2");
+const [node2, ports2] = createNode("Node 2", "port-2-1", "port-2-2");
+
+const canvasElement = document.getElementById("canvas")!;
+
+canvas
+  .attach(canvasElement)
+  .addNode({ element: node1, x: 200, y: 400, ports: ports1 })
+  .addNode({ element: node2, x: 600, y: 500, ports: ports2 })
+  .addConnection({ from: "port-1-2", to: "port-2-1" });
+```
+
+Refer to [Examples](examples) for more.
+
+## Run examples locally
+
+Use node version >= 20
+
+```
+npm install
+
+npm run start
+```
+
+or
+
+```
+docker compose up
+```
+
+Open `http://localhost:3100`

package/dist/main.d.ts

@@ -0,0 +1,569 @@
+export declare interface ApiConnection {
+    id?: string;
+    from: string;
+    to: string;
+    options?: ConnectionOptions;
+}
+
+export declare interface ApiContentMoveTransform {
+    x?: number;
+    y?: number;
+}
+
+export declare interface ApiContentScaleTransform {
+    scale: number;
+    x?: number;
+    y?: number;
+}
+
+export declare interface ApiNode {
+    id?: string;
+    element: HTMLElement;
+    x: number;
+    y: number;
+    ports?: Record<string, ApiPortsPayload>;
+    centerFn?: CenterFn;
+}
+
+export declare interface ApiPort {
+    readonly id?: string;
+    readonly element: HTMLElement;
+    readonly nodeId: string;
+    readonly centerFn?: CenterFn;
+    readonly direction?: number | null;
+}
+
+export declare type ApiPortsPayload = HTMLElement | {
+    readonly element: HTMLElement;
+    readonly centerFn?: CenterFn;
+    readonly direction?: number | null;
+};
+
+declare interface ApiTransform {
+    scale?: number;
+    x?: number;
+    y?: number;
+}
+
+declare interface ApiUpdateConnection {
+    readonly controller?: ConnectionController;
+}
+
+export declare type BackgroundDrawingFn = (ctx: CanvasRenderingContext2D, transformer: PublicViewportTransformer) => void;
+
+declare type BackgroundOptions = {
+    readonly type: "none";
+} | {
+    readonly type: "color";
+    readonly color?: string;
+} | {
+    readonly type: "dots";
+    readonly dotColor?: string;
+    readonly dotGap?: number;
+    readonly dotRadius?: number;
+    readonly color?: string;
+} | {
+    readonly type: "custom";
+    readonly drawingFn: BackgroundDrawingFn;
+};
+
+export declare class BezierConnectionController implements ConnectionController {
+    private readonly color;
+    private readonly width;
+    private readonly curvature;
+    private readonly arrowLength;
+    private readonly arrowWidth;
+    private readonly hasSourceArrow;
+    private readonly hasTargetArrow;
+    readonly svg: SVGSVGElement;
+    private readonly group;
+    private readonly line;
+    private readonly sourceArrow;
+    private readonly targetArrow;
+    constructor(color: string, width: number, curvature: number, arrowLength: number, arrowWidth: number, hasSourceArrow: boolean, hasTargetArrow: boolean);
+    update(x: number, y: number, width: number, height: number, from: PortPayload, to: PortPayload): void;
+}
+
+declare interface BezierConnectionOptions {
+    readonly type?: "bezier";
+    readonly color?: string;
+    readonly width?: number;
+    readonly curvature?: number;
+    readonly arrowLength?: number;
+    readonly arrowWidth?: number;
+    readonly hasSourceArrow?: boolean;
+    readonly hasTargetArrow?: boolean;
+}
+
+export declare interface Canvas {
+    /**
+     * provides api for canvas transformation
+     */
+    readonly transformation: PublicViewportTransformer;
+    /**
+     * provides api for graph structure access
+     */
+    readonly model: PublicGraphStore;
+    /**
+     * adds node to graph
+     */
+    addNode(node: ApiNode): Canvas;
+    /**
+     * removes node from graph
+     * all the ports of node get unmarked
+     * all the connections adjacent to node get removed
+     */
+    removeNode(nodeId: string): Canvas;
+    /**
+     * marks element as port of node
+     */
+    markPort(port: ApiPort): Canvas;
+    /**
+     * updates connections attached to port
+     */
+    updatePortConnections(portId: string): Canvas;
+    /**
+     * ummarks element as port of node
+     * all the connections adjacent to port get removed
+     */
+    unmarkPort(portId: string): Canvas;
+    /**
+     * adds connection to graph
+     */
+    addConnection(connection: ApiConnection): Canvas;
+    /**
+     * removes connection from graph
+     */
+    removeConnection(connectionId: string): Canvas;
+    /**
+     * applies transformation for viewport
+     */
+    patchViewportTransform(apiTransform: ApiTransform): Canvas;
+    /**
+     * applies move transformation for content
+     */
+    moveContent(apiTransform: ApiContentMoveTransform): Canvas;
+    /**
+     * applies scale transformation for content
+     */
+    scaleContent(apiTransform: ApiContentScaleTransform): Canvas;
+    /**
+     * applies shift transformation for content
+     */
+    moveToNodes(nodeIds: readonly string[]): Canvas;
+    /**
+     * updates node absolute coordinates
+     */
+    updateNodeCoords(nodeId: string, x: number, y: number): Canvas;
+    /**
+     * updates connection
+     */
+    updateConnectionOptions(connectionId: string, options: ApiUpdateConnection): Canvas;
+    /**
+     * drags node in viewport
+     */
+    dragNode(nodeId: string, dx: number, dy: number): Canvas;
+    /**
+     * moves specified node on top
+     */
+    moveNodeOnTop(nodeId: string): Canvas;
+    /**
+     * attaches canvas to given element
+     */
+    attach(element: HTMLElement): Canvas;
+    /**
+     * detaches canvas from element
+     */
+    detach(): Canvas;
+    /**
+     * clears graph
+     * graph gets rolled back to initial state
+     * canvas can be reused
+     */
+    clear(): Canvas;
+    /**
+     * destroys canvas
+     * canvas element gets rolled back to initial state
+     * canvas requires reinitialization in order to be used again
+     */
+    destroy(): void;
+}
+
+export declare class CanvasBuilder {
+    private coreOptions;
+    private transformOptions;
+    private isDraggable;
+    private isTransformable;
+    options(options: CoreOptions): CanvasBuilder;
+    draggableNodes(): CanvasBuilder;
+    transformableCanvas(options?: TransformOptions): CanvasBuilder;
+    build(): Canvas;
+}
+
+/**
+ * Provides core API for acting on graph
+ */
+export declare class CanvasCore implements Canvas {
+    private readonly apiOptions?;
+    readonly transformation: PublicViewportTransformer;
+    readonly model: PublicGraphStore;
+    private readonly options;
+    private readonly di;
+    constructor(apiOptions?: CoreOptions | undefined);
+    addNode(node: ApiNode): CanvasCore;
+    moveNodeOnTop(nodeId: string): CanvasCore;
+    removeNode(nodeId: string): CanvasCore;
+    markPort(port: ApiPort): CanvasCore;
+    updatePortConnections(portId: string): CanvasCore;
+    unmarkPort(portId: string): CanvasCore;
+    addConnection(connection: ApiConnection): CanvasCore;
+    removeConnection(connectionId: string): CanvasCore;
+    patchViewportTransform(apiTransform: ApiTransform): CanvasCore;
+    moveContent(apiTransform: ApiContentMoveTransform): CanvasCore;
+    scaleContent(apiTransform: ApiContentScaleTransform): CanvasCore;
+    moveToNodes(nodeIds: readonly string[]): CanvasCore;
+    updateNodeCoords(nodeId: string, x: number, y: number): CanvasCore;
+    updateConnectionOptions(connectionId: string, options: ApiUpdateConnection): CanvasCore;
+    dragNode(nodeId: string, dx: number, dy: number): CanvasCore;
+    clear(): CanvasCore;
+    attach(element: HTMLElement): CanvasCore;
+    detach(): CanvasCore;
+    destroy(): void;
+}
+
+declare type CenterFn = (width: number, height: number) => [number, number];
+
+declare interface ConnectionController {
+    readonly svg: SVGSVGElement;
+    update(x: number, y: number, width: number, height: number, from: PortPayload, to: PortPayload): void;
+}
+
+declare type ConnectionControllerFactory = () => ConnectionController;
+
+declare type ConnectionOptions = BezierConnectionOptions | StraightConnectionOptions | CustomConnectionOptions;
+
+declare interface ConnectionPayload {
+    from: string;
+    to: string;
+    controller: ConnectionController;
+}
+
+export declare class ConnectionUtils {
+    static getPortCenter(port: PortPayload): Point;
+    static rotate(point: Point, vector: Point, center: Point): Point;
+    static getDirectionVector(direction: number | null, flipX: number, flipY: number): Point;
+    static getArrowPath(vect: Point, shiftX: number, shiftY: number, arrowLength: number, arrowWidth: number): string;
+    static getArrowOffsetPath(vect: Point, shiftX: number, shiftY: number, arrowLength: number, arrowOffset: number): string;
+}
+
+export declare interface CoreOptions {
+    /**
+     * canvas background settings
+     */
+    readonly background?: BackgroundOptions;
+    /**
+     * nodes related behavior
+     */
+    readonly nodes?: {
+        /**
+         * specifies how to determine center of node
+         * center of nodes specified in addNode method by x and y
+         */
+        readonly centerFn?: CenterFn;
+    };
+    /**
+     * ports related behavior
+     */
+    readonly ports?: {
+        /**
+         * specifies how to determine center of port
+         * center of port determines point to which connection attaches
+         */
+        readonly centerFn?: CenterFn;
+    };
+    /**
+     *connections related behavior
+     */
+    readonly connections?: ConnectionOptions;
+    /**
+     * layers related behavior
+     */
+    readonly layers?: {
+        /**
+         * sets layers order
+         */
+        readonly mode?: LayersMode;
+    };
+}
+
+declare interface CustomConnectionOptions {
+    readonly type: "custom";
+    readonly controllerFactory: ConnectionControllerFactory;
+}
+
+export declare class DraggableNodesCanvas implements Canvas {
+    private readonly canvas;
+    readonly transformation: PublicViewportTransformer;
+    readonly model: PublicGraphStore;
+    private readonly nodes;
+    private grabbedNodeId;
+    private readonly nodeIdGenerator;
+    private element;
+    private readonly onCanvasMouseUp;
+    private readonly onCanvasMouseMove;
+    private readonly onCanvasTouchStart;
+    private readonly onCanvasTouchMove;
+    private readonly onCanvasTouchEnd;
+    private previousTouchCoords;
+    constructor(canvas: Canvas);
+    addNode(node: ApiNode): DraggableNodesCanvas;
+    removeNode(nodeId: string): DraggableNodesCanvas;
+    markPort(port: ApiPort): DraggableNodesCanvas;
+    updatePortConnections(portId: string): DraggableNodesCanvas;
+    unmarkPort(portId: string): DraggableNodesCanvas;
+    addConnection(connection: ApiConnection): DraggableNodesCanvas;
+    removeConnection(connectionId: string): DraggableNodesCanvas;
+    patchViewportTransform(apiTransform: ApiTransform): DraggableNodesCanvas;
+    moveContent(apiTransform: ApiContentMoveTransform): DraggableNodesCanvas;
+    scaleContent(apiTransform: ApiContentScaleTransform): DraggableNodesCanvas;
+    moveToNodes(nodeIds: readonly string[]): DraggableNodesCanvas;
+    updateNodeCoords(nodeId: string, x: number, y: number): DraggableNodesCanvas;
+    updateConnectionOptions(connectionId: string, options: ApiUpdateConnection): DraggableNodesCanvas;
+    dragNode(nodeId: string, dx: number, dy: number): DraggableNodesCanvas;
+    moveNodeOnTop(nodeId: string): DraggableNodesCanvas;
+    clear(): DraggableNodesCanvas;
+    attach(element: HTMLElement): DraggableNodesCanvas;
+    detach(): DraggableNodesCanvas;
+    destroy(): void;
+    private setCursor;
+}
+
+declare class GraphStore {
+    private nodes;
+    private ports;
+    private nodePorts;
+    private portNodeId;
+    private connections;
+    private incommingConnections;
+    private outcommingConnections;
+    private cycleConnections;
+    getAllNodes(): readonly string[];
+    getAllPorts(): readonly string[];
+    getAllConnections(): readonly string[];
+    addNode(nodeId: string, element: HTMLElement, x: number, y: number, centerFn: CenterFn): void;
+    hasNode(nodeId: string): boolean;
+    getNode(nodeId: string): NodePayload;
+    updateNodeCoords(nodeId: string, x: number, y: number): void;
+    updateConnectionController(connectionId: string, controller: ConnectionController): void;
+    removeNode(nodeId: string): void;
+    addPort(portId: string, element: HTMLElement, nodeId: string, centerFn: CenterFn, dir: number | null): void;
+    getPort(portId: string): PortPayload;
+    getPortNode(portId: string): string;
+    hasPort(portId: string): boolean;
+    removePort(portId: string): void;
+    addConnection(connectionId: string, fromPortId: string, toPortId: string, svgController: ConnectionController): void;
+    getConnection(connectionId: string): ConnectionPayload;
+    hasConnection(connectionId: string): boolean;
+    removeConnection(connectionId: string): void;
+    getPortIncomingConnections(portId: string): readonly string[];
+    getPortOutcomingConnections(portId: string): readonly string[];
+    getPortCycleConnections(portId: string): readonly string[];
+    getPortAdjacentConnections(portId: string): readonly string[];
+    getNodeIncomingConnections(nodeId: string): readonly string[];
+    getNodeOutcomingConnections(nodeId: string): readonly string[];
+    getNodeCycleConnections(nodeId: string): readonly string[];
+    getNodeAdjacentConnections(nodeId: string): readonly string[];
+    clear(): void;
+}
+
+declare type LayersMode = "connections-on-top" | "nodes-on-top" | "connections-follow-node";
+
+declare interface NodePayload {
+    element: HTMLElement;
+    x: number;
+    y: number;
+    centerFn: CenterFn;
+}
+
+declare type Point = [number, number];
+
+export declare interface PortPayload {
+    element: HTMLElement;
+    centerFn: CenterFn;
+    direction: number | null;
+}
+
+declare class PublicGraphStore {
+    private readonly graphStore;
+    constructor(graphStore: GraphStore);
+    getNode(nodeId: string): {
+        x: number;
+        y: number;
+    } | null;
+    getPort(portId: string): {
+        nodeId: string;
+    } | null;
+    getConnection(connectionId: string): {
+        from: string;
+        to: string;
+    } | null;
+    getAllNodes(): readonly string[];
+    getAllPorts(): readonly string[];
+    getAllConnections(): readonly string[];
+    hasNode(nodeId: string): boolean;
+    hasPort(portId: string): boolean;
+    hasConnection(connectionId: string): boolean;
+    getPortIncomingConnections(portId: string): readonly string[];
+    getPortOutcomingConnections(portId: string): readonly string[];
+    getPortCycleConnections(portId: string): readonly string[];
+    getPortAdjacentConnections(portId: string): readonly string[];
+    getNodeIncomingConnections(nodeId: string): readonly string[];
+    getNodeOutcomingConnections(nodeId: string): readonly string[];
+    getNodeCycleConnections(nodeId: string): readonly string[];
+    getNodeAdjacentConnections(nodeId: string): readonly string[];
+}
+
+export declare class PublicViewportTransformer {
+    private readonly transformer;
+    constructor(transformer: ViewportTransformer);
+    /**
+     * for given absolute coordinates returns viewport coordinates
+     * viewport coordinated represent actual coordinates on screen for given absolute coordinates
+     */
+    getViewCoords(xa: number, ya: number): [number, number];
+    /**
+     * returns viewport scale
+     * it represents scale at which entities on canvas should be scaled to fit current scale
+     */
+    getViewScale(): number;
+    /**
+     * for given viewport coordinates returns absolute coordinates
+     * absolute coordinates represent actual coordinates, which stay constant even for transformed canvas
+     */
+    getAbsCoords(xv: number, yv: number): [number, number];
+    /**
+     * returns absolute scale
+     * it represents scale at which current viewport was scaled compared to initial state
+     */
+    getAbsScale(): number;
+}
+
+export declare class StraightConnectionController implements ConnectionController {
+    private readonly color;
+    private readonly width;
+    private readonly arrowLength;
+    private readonly arrowWidth;
+    private readonly minPortOffset;
+    private readonly hasSourceArrow;
+    private readonly hasTargetArrow;
+    readonly svg: SVGSVGElement;
+    private readonly group;
+    private readonly line;
+    private readonly sourceArrow;
+    private readonly targetArrow;
+    constructor(color: string, width: number, arrowLength: number, arrowWidth: number, minPortOffset: number, hasSourceArrow: boolean, hasTargetArrow: boolean);
+    update(x: number, y: number, width: number, height: number, from: PortPayload, to: PortPayload): void;
+}
+
+declare interface StraightConnectionOptions {
+    readonly type: "straight";
+    readonly color?: string;
+    readonly width?: number;
+    readonly arrowLength?: number;
+    readonly arrowWidth?: number;
+    readonly minPortOffset?: number;
+    readonly hasSourceArrow?: boolean;
+    readonly hasTargetArrow?: boolean;
+}
+
+export declare class TransformableCanvas implements Canvas {
+    private readonly canvas;
+    private readonly options?;
+    readonly transformation: PublicViewportTransformer;
+    readonly model: PublicGraphStore;
+    private element;
+    private isMoving;
+    private prevTouches;
+    private readonly isScalable;
+    private readonly isShiftable;
+    private readonly minContentScale;
+    private readonly maxContentScale;
+    private readonly wheelSensitivity;
+    private readonly onMouseDown;
+    private readonly onMouseMove;
+    private readonly onMouseUp;
+    private readonly onWheelScroll;
+    private readonly onTouchStart;
+    private readonly onTouchMove;
+    private readonly onTouchEnd;
+    constructor(canvas: Canvas, options?: TransformOptions | undefined);
+    addNode(node: ApiNode): TransformableCanvas;
+    removeNode(nodeId: string): TransformableCanvas;
+    markPort(port: ApiPort): TransformableCanvas;
+    updatePortConnections(portId: string): TransformableCanvas;
+    unmarkPort(portId: string): TransformableCanvas;
+    addConnection(connection: ApiConnection): TransformableCanvas;
+    removeConnection(connectionId: string): TransformableCanvas;
+    patchViewportTransform(apiTransform: ApiTransform): TransformableCanvas;
+    moveContent(apiTransform: ApiContentMoveTransform): TransformableCanvas;
+    scaleContent(apiTransform: ApiContentScaleTransform): TransformableCanvas;
+    moveToNodes(nodeIds: readonly string[]): TransformableCanvas;
+    updateNodeCoords(nodeId: string, x: number, y: number): TransformableCanvas;
+    updateConnectionOptions(connectionId: string, options: ApiUpdateConnection): TransformableCanvas;
+    dragNode(nodeId: string, dx: number, dy: number): TransformableCanvas;
+    moveNodeOnTop(nodeId: string): TransformableCanvas;
+    clear(): TransformableCanvas;
+    attach(element: HTMLElement): TransformableCanvas;
+    detach(): TransformableCanvas;
+    destroy(): void;
+    private getAverageTouch;
+    private checkNextScaleValid;
+    private setCursor;
+}
+
+export declare interface TransformOptions {
+    scale?: {
+        enabled?: boolean;
+        minContent?: number;
+        maxContent?: number;
+        wheelSensitivity?: number;
+    };
+    shift?: {
+        enabled?: boolean;
+    };
+}
+
+declare class ViewportTransformer {
+    private state;
+    /**
+     * dx2 - traslate x
+     * dy2 - traslate y
+     *
+     * direct transform
+     *  s1  0   dx1     1   0   dx2
+     *  0   s1  dy1     0   1   dy2
+     *  0   0   1       0   0   1
+     *
+     * [s, dx, dy] = [s1, s * dx2 + dx1, s * dy2 + dy1]
+     */
+    applyShift(dx: number, dy: number): void;
+    /**
+     * s2 - scale
+     * cx - scale pivot x
+     * cy - scale pivot y
+     *
+     *  s1  0   dx1     s2  0   (1 - s2) * cx
+     *  0   s1  dy1     0   s2  (1 - s2) * cy
+     *  0   0   1       0   0   1
+     *
+     * [s, dx, dy] = [s1 * s2, s1 * (1 - s2) * cx + dx1, s1 * (1 - s2) * cy + dy1]
+     */
+    applyScale(s2: number, cx: number, cy: number): void;
+    getViewCoords(xa: number, ya: number): [number, number];
+    getViewScale(): number;
+    getAbsCoords(xv: number, yv: number): [number, number];
+    getAbsScale(): number;
+    patchState(scale: number | null, x: number | null, y: number | null): void;
+}
+
+export { }