Grapher.ts

A TypeScript component for drawing graphs.

Provided Functionality (User Guide)

Project provides a UI component that allows users to draw directed weighted graphs.

Adding Vertices

To add a vertice user needs to select "Vertices tool" (circle in the toolbar) and click on graph drawing field wherever vertex needs to be added.

Adding vertices GIF

Adding Edges

To connect two vertices with an edge user needs to select "Edges tool", click and drag from source vertex to target vertex.

Adding edges GIF

Specifying Weights

To specify weights for edges user needs to select "Weights tool", select an edge and input the weight using keyboard. Weights can be deleted using backspace and delete keys. Only numeric values are allowed.

Specifying weights GIF

Repositioning Vertices

To reposition vertices user needs to select "Vertices tool" and drag a vertex to a new position.

Repositioning vertices GIF

Removing Graph Items

To remove individual items from the graph user needs to select "Removal tool" and click on items that needs to be removed. To remove all items in the graph user can click "Clear graph" button (thrash can in the toolbar).

Removing items GIF

Limitations and Issues

Tool cannot draw multigraphs or self-loop edges.

Weights inputed via GUI must be integer and cannot be negative or zero.

Selecting an edge for weight input on a device with soft keyboard (e.g. mobile devices) will not automatically open the keyboard.

Install

To use this component in Node.js project run:

npm install grapher-ts

Usage

Basic example

A very basic example of adding Grapher.ts component to an HTML document on load. This is sufficient to render the graph drawing tool.

import { Grapher } from 'grapher-ts';

window.onload = () => {
  const container = document.createElement('div');
  const grapher = new Grapher(container);
  document.body.appendChild(container);
};

Adding vertices and edges using API

const grapher = new Grapher(container);
const sourceVertex = grapher.addVertex(new Point(10, 20));
const targetVertex = grapher.addVertex(new Point(30, 30));
const weight = 3;
// This will create a directed edge going from source to target
// with specified weight.
grapher.addEdge(new Edge(sourceVertex, targetVertex, weight));

Exporting graph to a common format

const grapher = new Grapher(container);
// Converts graph to adjacency matrix where graph is represneted as V x V
// array where array elements are weights of edges (0 indicates no edge).
// Array is indexed using IDs of vertices.
grapher.graph.toAdjacencyMatrix();
// Coverts graph to adjacency list where graph is represented as a list
// of edges where each list element is an object of form
// {source, target, weight} where source is source vertex ID, target is
//  target vertex ID and weight is the weight of represented edge.
grapher.graph.toAdjacencyList();

Changing appearance of elements using CSS classes

Appearance of graph elements can be manipulated using CSS classes. This can be used to style graph to fit some design or to visualize algorithms.

const grapher = new Grapher(container);
const vertex = grapher.addVertex(new Point(10, 20));
// Add CSS class to vertex.
vertex.svgElement.classList.add('active');

const edge = grapher.svgEdges[0];
// Add CSS class to edge path element.
edge.edgeSvg.classList.add('active');
// Add CSS class to edge weight element.
edge.weightSvg.classList.add('active');

// Remove a CSS class from some item.
edge.weightSvg.classList.remove('hidden');

Component Architecture

Packages

Component consists of three packages:

Domain - package defines classes for modelling a graph. It defines edges, vertices, graph and basic operations of the graph.
Visual - package extends classes defined in domain by adding visual components to them. Deals with creating and manipulating DOM elements that represent the graph.
Interaction - package defines handlers for user input. Each handler defined in the package deals with one mode of operation that is controlled by the toolbar.

Classes

Below is a UML class diagram that covers all the classes of the component and shows relationships between them.

Description of each class can be found as comments in the source code or in generated TypeDoc documentation.

Class Diagram

TypeDoc Documentation

Documentation generated from the source using TypeDoc can be found here.

Changelog

0.0.5

Implemented graph export.
Updated readme.

0.0.4

Updated webpack output to correctly export library as module.
Updated readme with user guide, examples and documentation.

0.0.3

Reconfigured typings.

0.0.2

Added missing typings.

0.0.1

Initial version.

Compile

Builds use /lib as outpud directory. Builds will also generate documentation from source code using TypeDoc that will be placed under /docs.

Prod build

To compile the project run:

npm run-script build

This will output a Javascript file /lib/grapher.js that can be used to distribute this component.

Dev build

For local development purposes it is possible to build with:

npm run-script build-dev

Unlike regular build, this will output /lib/index.js that can be included in HTML file to load a demo of the component. To view the component, one can open src/index.html.