gitbook y

.gitbook.yaml

@@ -0,0 +1 @@
+root: ./docs/

docs/README.md

@@ -1,2 +0,0 @@
-# Introduction
-

docs/SUMMARY.md

@@ -2,9 +2,9 @@
 
 * [Introduction](README.md)
 * [Interacting with diagrams](interactive-usage.md)
-* [Getting Started](getting-started/README.md)
-  * [Using the library](getting-started/using-the-library.md)
-* [About the project](about-the-project/README.md)
-  * [Testing](about-the-project/testing.md)
-  * [Architecture Questions](about-the-project/architecture-questions.md)
+* [Getting Started](docs/getting-started/README.md)
+  * [Using the library](docs/getting-started/using-the-library.md)
+* [About the project](docs/about-the-project/README.md)
+  * [Testing](docs/about-the-project/testing.md)
+  * [Architecture Questions](docs/about-the-project/architecture-questions.md)
 

docs/about-the-project/architecture-questions.md

@@ -1,2 +1,52 @@
 # Architecture Questions
 
+Here I will try to answer any questions relating to the design of the system
+
+## What was the inspiration for this library?
+
+Joint JS \(a fantastic library\) + my need for rich HTML nodes + LabView + Blender Composite sub system
+
+## Why render the nodes as HTML Elements and not SVG's?
+
+My original requirement for this library stemmed from the requirement of wanting HTML nodes that would allow me to embed rich controls such as input fields, drop downs and have the system treat such nodes as first class citizens. I originally tried to make this work in JointJS, but ran into a number of problems of which this was a relatively big one.
+
+JointJS does allow you to do this, but at the time of writing this library originally, I was having a lot of trouble to make it work exactly like I needed it, and therefore decided from the very beginning that I would attempt this with an HTML first mindset.
+
+## Why Typescript?
+
+Firstly, because it can transpile into any level of ECMAScript. This means that I don't need to break our the refactor tractor every time ECMAScript decides it wants to add features which it should have done years ago.
+
+I also ported it to Typescript to accommodate the heavy architectural changes I was starting to make. Since porting the library to typescript, and seeing the project explode in size and complexity, I consider this the best decision made with regards to this library so far.
+
+Porting to typescript also afforded us a set of powerful features such as generics and static analysis that all the project contributors have made exclusive use of.
+
+Typescript is <3 typescript is life.
+
+## Why not Flow instead of Typescript?
+
+At the time when I first started evaluating languages that could transpile to ECMAScript, I was not so sold on the supporting environment surrounding flow, and and found that there was better tooling to support typescript, they are ultimately trying to do the same thing though, and I guess in the end, typescript just made more sense.
+
+## Why React ?
+
+React is really efficient at rendering and managing HTML in a declarative manner. React has also become one of the bigger industry standards and has a rich eco system that plays really well with typescript. Apart from these notable points, I am really fond of React and wanted a diagramming library that takes full advantage of it, and makes it easy for engineers to use its power as well, when extending this library.
+
+## Why cant the Default models and widgets do this or that ?
+
+They are intended to illustrate **how** to use this library and act as a good starting point to extend and show the capability. Ultimately I designed this library to be completely pluggable in a way that you can use it as a library and not a framework. If the default widgets are not good enough, then a good place to start is with creating your own models/factories/widgets.
+
+## Model vs Widget
+
+For those that are new to [Scene Graphs](https://en.wikipedia.org/wiki/Scene_graph) or are not familiar with concepts such as [MVC](https://en.wikipedia.org/wiki/Model–view–controller), this library represents your entire graph as a model. The model is a traversable graph that represents the nodes and links between them in a virtual manner. Your program \(aka the business logic/layer\) can mutate this model imperatively or store snapshots decoratively of the complete model \(via serialization\) and then the engine and react widgets will take care of the rendering. For this reason every model in the library is represented by a widget, and the factories glue it all together.
+
+## How do I make my own elements?
+
+Take a look at the **demos** directory, with specific attention to the **DefaultNodeWidget**
+
+That being said, the demos directory is an _example_ of how you can create your own elements. A number of people want to use the defaults as is, which is cool, but is recommended to create your own models/factories/widgets.
+
+## How do I use the library?
+
+Take a look at the demo folders, they have simple and complex examples of the complete usage.
+
+A good example of a real-world example is Demo 5
+

docs/about-the-project/testing.md

@@ -1,2 +1,20 @@
 # Testing
 
+STORM React diagrams is tested two main ways.
+
+## JEST Snapshot testing
+
+With Jest snapshots, we render all the demos in the demo folder by automatically looking into each `demo-*` folder and searching for an **index.tsx** file.
+
+For each file we find, we dynamically include it as a storybook story and assemble one big test. This test then renders each demo in a deterministic way and compares it to the snapshot file situated in **snapshots**. If the snapshots don't match, then something has changed and either the snapshot needs to be updated, or the test is failing in which case we need to fix the code.
+
+Snapshot testing does not test the functionality of the program but it is a first important step to make sure that changes aren't having a drastic effect on the overall system.
+
+In the event that the snapshot needs to be updated, please run `yarn run test -u` to overwrite the snapshot file, and then make sure to your branch.
+
+## End to end testing
+
+To test the functionality of the library, we make use of e2e tests \(end to end tests\). In this library, we spin up a headless chrome using pupeteer and interactively and programmatically tell the mouse pointer to click and drag on various elements while making assertions along the way.
+
+We use Jest for the assertions and the interactivity is handled by puppeteer. Due to the laborious nature of writing e2e tests, there is a helper method that is provided in each test that makes interacting with the diagrams a lot easier. Using this helper, you can easily tell the mouse to drag links between nodes, select them and also easily assert information about them. The important thing here, is that this helper does not touch the model in any way, but is purely a helper for writing the tests themselves. Please make use of this helper when writing tests, as it ensure that the tests are defensive in nature, and also reduces the overhead of physically writing them.
+

docs/getting-started/README.md

@@ -1,2 +1,34 @@
+---
+description: 'How to install, and render two nodes with a Hello World link.'
+---
+
 # Getting Started
 
+## Installation
+
+The first thing you need to do, is grab the distribution files on NPM. You can do this either using **yarn** or **npm.**
+
+**Via yarn:**
+
+```text
+yarn add @projectstorm/react-diagrams@next
+```
+
+**Via npm:**
+
+```text
+npm install @projectstorm/react-diagrams@next
+```
+
+When you run this in your project directory, this will install the library into `./node_modules/@projectstorm/react-diagrams`. You will then find a **dist** folder that contains all the minified and production ready code.
+
+### Install the peer dependencies
+
+The library includes it's dependencies as peer-dependencies, so yarn will output warnings letting you know which ones are missing. Simple install them, specifically these ones:
+
+```text
+yarn add closest lodash react mathjs dagre pathfinding paths-js
+```
+
+We do this, so that you can better control the versions of these libraries yourself since you might make use of `Lodash` in other parts of your software. 
+

docs/getting-started/using-the-library.md

@@ -1,2 +1,65 @@
 # Using the library
 
+## Using Typescript
+
+If you are using typescript, then you are in luck! The library is built in typescript, and includes advanced types for everything you need right out of the box. 
+
+Lets start by including the things we are going to need:
+
+```typescript
+import createEngine, { 
+    DefaultLinkModel, 
+    DefaultNodeModel,
+    DiagramModel 
+} from '@projectstorm/react-diagrams';
+```
+
+Now we call `createEngine` which will bootstrap a **DiagramEngine** for us that contains all the defaults setup.
+
+```typescript
+// create an instance of the engine with all the defaults
+const engine = createEngine();
+```
+
+Next, we create two nodes:
+
+```typescript
+// node 1
+const node1 = new DefaultNodeModel({
+	name: 'Node 1',
+	color: 'rgb(0,192,255)',
+});
+node1.setPosition(100, 100);
+let port1 = node1.addOutPort('Out');
+
+// node 2
+const node2 = new DefaultNodeModel({
+	name: 'Node 1',
+	color: 'rgb(0,192,255)',
+});
+node2.setPosition(100, 100);
+let port2 = node2.addOutPort('Out');
+```
+
+Now we link the two ports of both of the nodes:
+
+```typescript
+// link them and add a label to the link
+const link = port1.link<DefaultLinkModel>(port2);
+link.addLabel('Hello World!');
+```
+
+Great! Now we have setup a simple diagram. All thats left to do, is create a **DiagramModel** to contain everything, add all the elements to it, and then add it to the engine.
+
+```typescript
+const model = new DiagramModel();
+model.addAll(node1, node2, link);
+engine.setModel(model);
+```
+
+And then we render with **React**!
+
+```jsx
+<CanvasWidget engine={engine} />
+```
+

packages/diagrams-demo-gallery/demos/demo-simple/index.tsx

@@ -11,9 +11,12 @@ export default () => {
 	var model = new DiagramModel();
 
 	//3-A) create a default node
-	var node1 = new DefaultNodeModel('Node 1', 'rgb(0,192,255)');
-	let port1 = node1.addOutPort('Out');
+	var node1 = new DefaultNodeModel({
+		name: 'Node 1',
+		color: 'rgb(0,192,255)',
+	});
 	node1.setPosition(100, 100);
+	let port1 = node1.addOutPort('Out');
 
 	//3-B) create another default node
 	var node2 = new DefaultNodeModel('Node 2', 'rgb(192,255,0)');