more docs

README.md

@@ -5,6 +5,22 @@
 # (WIP) fa-diagrams
 ## SVG diagrams built from Font-Awesome icons
 
+## RoadMap to v1
+
+* [x] Font-Awesome paths scrapping in build
+* [x] Node placing with links
+* [x] SVG output
+* [x] Node's icon rendering
+* [x] Simple links rendering
+* [ ] Dashed links rendering
+* [ ] Colors
+* [ ] Sub-elements
+* [ ] More options
+* [ ] PNG output
+* [ ] Unit testing
+
+## Summary
+
 * [Install](#install)
   * [CDN](#cdn)
   * [Static scripts](#static-scripts)
@@ -13,8 +29,18 @@
 * [Usage](#usage)
   * [Node module](#node-module)
   * [Html script](#html-script)
+* [API](#api)
+  * [`options`](#options)
+  * [`nodes`](#nodes)
+  * [`links`](#links)
+  * [Sub-elements](#sub-elements)
+* [More info](#more-info)
+  * [Icon names](#icon-names)
+  * [Link types](#link-types)
+* [Examples](#examples)
   
 ## Install  
+*[back to top](#top)*
 
 ### Static scripts
 
@@ -58,6 +84,7 @@ node build.sh
 ```
 
 ## Usage
+*[back to top](#top)*
 
 ### Node module
 
@@ -83,7 +110,6 @@ const data = {
     ],
     links: [
         {
-            type: 'arrow',
             from: 'node1',
             to: 'node2',
             bottom: {text: 'Hello World!'}
@@ -119,4 +145,99 @@ Will produce the following diagram :
 </html>
 ```
 
+## API
+*[back to top](#top)*
 
+**You must pass as argument an object containing 3 keys:**
+  * [`options`](#options)
+  * [`nodes`](#nodes)
+  * [`links`](#links)
+
+### `options`
+
+| Key (`/subkey`) | Default value | Info |
+| --- | --- |  --- |
+| `placing/max-link-length` | 3 | maximum stretching of links between nodes |
+| `placing/diagonals` | `true` | allow diagonal links to be made |
+| `rendering/beautify` | `false` | output a readable SVG file |
+| `rendering/scale` | 128 | (in pixels) final icons size |
+| `rendering/color` | `black` | color of all elements |
+| `rendering/h-spacing` | 1.3 | how width is stretched comparing to height |
+| `rendering/icons/scale` | 1 | default scaling of icons (might be redefined in node definition) |
+| `rendering/links/scale` | 1 | default scaling of links (might be redefined in link definition) |
+| `rendering/links/size` | 0 | forced size/length of the links (0 means it will be computed from the distance between the nodes) (might be redefined in link definition) |
+| `rendering/texts/font` | `'Arial'` | font family of the texts (might be redefined in sub-elements definition) |
+| `rendering/texts/font-size` | 20 | font size of the texts (might be redefined in sub-elements definition) |
+| `rendering/texts/font-style` | `'normal'` | font style of the texts (see [Font styles](#font-styles)) (might be redefined in sub-elements definition) |
+
+### `nodes`
+
+Array of object as following:
+
+| Key | Type | Required | Info |
+| --- | --- | --- |  --- |
+| **`name`** | string | **yes** | used in links to reference nodes |
+| **`icon`** | string | **yes** | name of the Font-Awesome icon of the node (see [Icon names](#icon-names)) |
+| `top`, `bottom`, `left`, `right` | string or object | no | see [Sub-elements](#sub-elements) |
+| `color` | string | no | redefined the color |
+| `scale` | number | no | redefine this node icon scale |
+| `x`, `y` | number | no | force the position of this node |
+
+### `links`
+
+Array of object as following:
+
+| Key | Type | Required | Info |
+| --- | --- | --- |  --- |
+| **`from`** | string | **yes** | source node name  |
+| **`to`** | string | **yes** | destination node name |
+| `type` | string | no | link's appearance (see [Link types](#link-types)) |
+| `top`, `bottom` | string or object | no | see [Sub-elements](#sub-elements) |
+| `color` | string | no | redefined the color |
+| `scale` | number | no | redefine this link scale |
+| `size` | number | no | forced size/length of the link |
+
+### Sub-elements
+
+Elements meant to be drawn along-side a node/link.  
+There are two types: text and icons
+
+### Texts
+
+You can **just enter a string** to be considered a text but you can define a text with more options as following:
+
+| Key | Type | Required | Info |
+| --- | --- | --- |  --- |
+| **`text`** | string | **yes** | value of your text  |
+| `color` | string | no | redefined the color |
+| `font` | string | no | redefine the font family |
+| `font-size` | number | no | redefine the font size |
+| `font-style` | string | no | redefine the font style (see [Font styles](#font-styles)) |
+
+### Icons
+
+You can define a relative icon with the following:
+
+| Key (`/subkey`) | Type | Required | Info |
+| --- | --- | --- |  --- |
+| **`icon`** | string | **yes** | name of the Font-Awesome icon of the sub-element (see [Icon names](#icon-names)) |
+| `color` | string | no | redefined the color |
+
+## More info
+*[back to top](#top)*
+
+### Icon names
+
+(soon)
+
+### Link types
+
+(soon)
+
+### Font styles
+
+(soon)
+
+## Examples
+*[back to top](#top)*
+(soon)

localtests.js

@@ -1,112 +0,0 @@
-const faDiagrams = require('./src/index');
-const fs = require('fs');
-
-/*const data = {
-  options: {
-    font: 'Courier New'
-  },
-  nodes: [
-    {
-      name: 'node1',
-      icon: 'server',
-      bottom: {text: 'myserver' },
-      top: {icon: 'node'}
-    },
-    {
-      name: 'node2',
-      icon: 'globe',
-      bottom: {text: 'world'}
-    }
-  ],
-  links: [
-    {
-      type: 'arrow',
-      from: 'node1',
-      to: 'node2',
-      direction: 'right',
-      bottom: {text: 'Hello World!'}
-    }
-  ]
-};*/
-
-const data = {
-  options: {
-    rendering: {
-      beautify: true
-    },
-    placing: {
-      diagonals: true
-    }
-  },
-  nodes: [
-    {
-      name: '1',
-      icon: 'circle',
-    },
-    {
-      name: '2',
-      icon: 'circle'
-    },
-    {
-      name: '3',
-      icon: 'circle'
-    },
-    {
-      name: '4',
-      icon: 'circle'
-    },
-    {
-      name: '5',
-      icon: 'circle'
-    },
-    {
-      name: '6',
-      icon: 'circle'
-    },
-  ],
-  links: [
-    {from: '1', to: '2', direction: 'right', type: ''},
-    {from: '1', to: '3', direction: 'down', type: ''},
-    {from: '3', to: '4', direction: 'right', type: ''},
-    {from: '4', to: '5', direction: 'up', type: 'double'},
-    {from: '3', to: '6', direction: 'left', type: ''}
-  ]
-};
-
-fs.writeFileSync('out.svg', faDiagrams.compute(data), {encoding: 'utf-8'});
-
-const rendering = require('./src/rendering')({
-  'beautify': false,
-  'scale': 1,
-  'h-spacing': 1,
-  'icons': {
-    'scale': 0.1
-  },
-  'links': {
-    'scale': 1
-  },
-});
-
-const g = [];
-
-let y = 0;
-
-for (let i = 0; i < 20; i++) {
-  if (i % 5 === 0)
-    y = 0;
-  ['', 'double', 'line'].forEach(type => {
-    g.push({
-      '_attributes': {
-        'transform': `translate(${Math.pow(Math.floor(i / 5), 1.6) * 720} ${256 * (y++)})`
-      },
-      'path': {
-        '_attributes': {
-          'd': rendering.getLinkPath(type, (i + 1) / 5)
-        }
-      }
-    });
-  });
-
-}
-
-fs.writeFileSync('out2.svg', rendering.toXML({g: g}, {w: 7000, h: 256 * 16}), {encoding: 'utf-8'});

src/rendering.js

@@ -30,8 +30,10 @@ const DEFAULT_OPTIONS = {
     'scale': 1
   },
   'links': {
-    'scale': 1
+    'scale': 1,
+    'size': 0
   },
+  'font': 'Arial' // https://websitesetup.org/web-safe-fonts-html-css/
 };
 
 const DEFAULT_SCALE = 0.4;
@@ -78,8 +80,16 @@ module.exports = (options = DEFAULT_OPTIONS) => {
       return null;
     },
 
+    /**
+     * Create the correct path from the type and width
+     * @param {string} type
+     * @param {number} width
+     * @return {string|null}
+     */
     getLinkPath: (type, width) => {
       switch (type) {
+        case 'none':
+          return null;
         case 'line':
           return `M12 216c-6.627 0-12 5.373-12 12v56c0 6.627 5.373 12 12 12h${width * 512 - 24}c6.627 0 12 -5.373 12 -12v-56c0 -6.627 -5.373 -12 -12 -12z`;
         case 'double':
@@ -154,7 +164,10 @@ module.exports = (options = DEFAULT_OPTIONS) => {
 
         const size = Math.sqrt(Math.pow((dst.x - src.x) * options['h-spacing'], 2) + Math.pow(dst.y - src.y, 2));
 
-        const path = self.getLinkPath(link.type, link['size'] || size);
+        const path = self.getLinkPath(link.type, link['size'] || options['links']['size'] || size);
+
+        if (!path)
+          return;
 
         const scale = (link['scale'] || options['links']['scale']) * DEFAULT_SCALE;
         const group = {
@@ -188,8 +201,8 @@ module.exports = (options = DEFAULT_OPTIONS) => {
           '_attributes': {
             'xmlns': 'http://www.w3.org/2000/svg',
             'viewBox': `0 0 ${bounds.w * options['h-spacing']} ${bounds.h}`,
-            'width': bounds.w * options['h-spacing'] * options['scale'],
+            'width': bounds.w * options['h-spacing'] * options['scale'] / DEFAULT_SCALE,
-            'height': bounds.h * options['scale'],
+            'height': bounds.h * options['scale'] / DEFAULT_SCALE,
           }
         }
       };