web-digraph

A library to create a simple directed graph editor. See the demo at https://web-digraph.netlify.app/.

Overview

Initially, this library was basically a copy of react-digraph, but with less features, less polished, and less everything. but using canvas instead of svg for rendering, and also not using react, because we love imperative things. React is for the weak.

Features

• Built with Typescript.
• Small size (~8KB minified and gzipped, compared to react-digraph ~100KB minified and gzipped).
• Imperative API and class-based (yes, this is a feature).
• Touch input support.

Installation

npm install --save web-digraph

Usage

• Import the GraphView class and needed types.

import {
  createGraphView,
  GraphEdge,
  GraphMode,
  GraphNode,
  GraphView,
  createEdgeShape,
  createNodeShape,
  defaultEdgeShape,
  defaultNodeShape
} from "web-digraph";

• Define the node and edge types. I suggest putting this node and edge types definition in its own file because it may get long.

const rectNodeShape = createNodeShape({
  width: 160,
  height: 120,
  createPath: (x, y, w, h) => {
    const p = new Path2D();

    p.rect(x - w * 0.5, y - h * 0.5, w, h);
    p.closePath();

    return p;
  }
});

const starNodeShape = createNodeShape({
  width: 218,
  height: 205,
  createPath: (x, y, w, h) => {
    const p = new Path2D();

    const l = x - w * 0.5;
    const t = y - h * 0.5;

    p.moveTo(l + 108, t + 0.0);
    p.lineTo(l + 141, t + 70);
    p.lineTo(l + 218, t + 78.3);
    p.lineTo(l + 162, t + 131);
    p.lineTo(l + 175, t + 205);
    p.lineTo(l + 108, t + 170);
    p.lineTo(l + 41.2, t + 205);
    p.lineTo(l + 55, t + 131);
    p.lineTo(l + 0, t + 78);
    p.lineTo(l + 75, t + 68);
    p.lineTo(l + 108, t + 0);
    p.closePath();

    return p;
  }
});

const circleEdgeShape = createEdgeShape({
  width: 48,
  height: 48,
  createPath: (x, y, w) => {
    const p = new Path2D();

    p.arc(x, y, w * 0.5, 0, 2 * Math.PI);
    p.closePath();

    return p;
  }
});

const nodeShapes = [
  defaultNodeShape,
  rectNodeShape,
  starNodeShape,
  wowNodeShape
];

const edgeShapes = [defaultEdgeShape, circleEdgeShape];

• Create a new instance of GraphView class. The first parameter is the container, and second parameter is the options. Please see the example for the options' detail.

const graphDiv = document.getElementById("graph-div");
const graphView = new GraphView<GraphNode, GraphEdge>(graphDiv, {
  width: 100000,
  height: 100000,
  minScale: 0.2,
  maxScale: 3.0,
  onViewZoom: handleViewZoom,
  onCreateNode: handleCreateNode,
  onCreateEdge: handleCreateEdge
});

• Do some operations. See the example for more detail.

graphView.addNode(
  {
    id: 1,
    x: 0
    y: 0
  },
  nodeShapes[getRandomInt(0, nodeShapes.length)]
);

Options

width: number;
height: number;
bgColor: string;
bgDotColor: string;
bgLineWidth: number;
bgLineGap: number;
bgShowDots: boolean;
bgBorderWidth: number;
bgBorderColor: string;
bgOutboundColor: string;
minScale: number;
maxScale: number;
edgeLineWidth: number;
edgeLineColor: string;
edgeArrowHeight: number;
edgeArrowWidth: number;
edgeShapeColor: string;
edgeContentColor: string;
edgeTextAlign: CanvasTextAlign;
edgeTextBaseline: CanvasTextBaseline;
edgeFont: string;
edgeHoveredLineColor: string;
edgeSelectedLineColor: string;
edgeSelectedShapeColor: string;
edgeSelectedContentColor: string;
nodeLineWidth: number;
nodeLineColor: string;
nodeColor: string;
nodeContentColor: string;
nodeTextAlign: CanvasTextAlign;
nodeTextBaseline: CanvasTextBaseline;
nodeFont: string;
nodeHoveredLineColor: string;
nodeSelectedLineColor: string;
nodeSelectedColor: string;
nodeSelectedContentColor: string;
onViewZoom: () => void;
onCreateNode: (x: number, y: number) => void;
onCreateEdge: (sourceId: number, targetId: number) => void;

GraphNode

If you want to use your own Node data type, you can. Just make sure that your custom type have all the properties of GraphNode. The same also apply to GraphEdge.

| Prop | Type | Required | Notes | | ---- | :------: | :------: | :-------------------------: | | id | number | true | A unique identifier number. | | x | number | true | X coordinate of the node. | | y | number | true | Y coordinate of the node. |

GraphEdge

| Prop | Type | Required | Notes | | ---------- | :------: | :------: | :-------------------------: | | id | number | true | A unique identifier number. | | sourceId | number | true | The source node id | | targetId | number | true | The target node id. |

Notes

• Nodes' and edges' ids must be unique or there will be unexpected behaviors.
• Nodes' and edges' ids must be greater than 0.

Limitations

• No swap edge (react-digraph has it, but i don't think it is needed).

FAQ

Q: Why not just use react-digraph if this is basically an inferior version of react-digraph?
A: Size and performance are the main reasons. react-digraph depends on D3 and other dependencies, which make it heavy. Also they use react and svg, which is not performant when the nodes and edges count are really big. Try 1000 nodes on react-digraph's example and then try 999999 (i am not joking) nodes on web-digraph's example and you will see the difference.

Q: Why no react?
A: There are some reasons for this:

• First, react-digraph already use React, so why should we do the same?
• I am not a fan nor an expert of React. I just use React because of job's requirements xD
• Well, actually I tried to use React at first xD But it is not performing as well as I wanted and the code becomes ugly very quick (maybe i am just not good with React). And I didn't even know about react-digraph at first. So after knowing about react-digraph, I immediately redo from scratch without React and copies react-digraph. xD

Q: Is it production ready?
A: Not sure, maybe not. xD If you find any bugs, please let me know or create a PR. xD

Q: There are some missing event that I need, like onViewMoved, onHoverChange, etc. A: Well, please let me know or create a PR. xD