Merge pull request #154 from KNowledgeOnWebScale/development

v1.1.0

Author: TiboStr

.github/workflows/continuous-integration-workflow.yml

@@ -1,5 +1,8 @@
 name: GitHub Pages CI
-on: push
+on:
+  push:
+    branches:
+      - main
 
 jobs:
   build-test-deploy:
@@ -11,8 +14,9 @@ jobs:
         uses: actions/setup-node@v1
         with:
           node-version: "18.x"
-      - run: npm ci
+      - run: npm ci --legacy-peer-deps
       - run: npm run build
+      - run: npm test
       - name: Deploy
         uses: crazy-max/ghaction-github-pages@v1
         with:

.husky/pre-commit

@@ -0,0 +1,4 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npm test -- --watchAll=false

CHANGELOG.md

@@ -1,12 +1,45 @@
 # Changelog
 
-Dates are DD-MM-YYYY
+All notable changes to this project will be documented in this file.
 
-## [0.1.0] - 04-08-2022
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-First ever release. You can make flows from JSON or YAML.
+## Unreleased
+
+/
 
-## [1.0.0] - 12-08-2022
+## [1.1.0] - 2022-09-02
+
+### Added
+
+- Details custom React component
+- Support to embed a link to an online JSON file in a permalink.
+- Input field to enter a permalink
+- You can set spacing for autoLayout, hgroup and vgroups.
+- The shape of a node can be anything defined in [react-icons](https://react-icons.github.io/react-icons).
+- Added FAQ section to README
+- You can make 'simulations' (= flow in multiple steps)
+- Navigation bar, so you can quickly navigate a large network of nodes.
+- You can use an ellipse as shape for a node.
+- You can refer to multiple presets.
+- Make fontsize smaller of title and label, if it does not fit its node.
+- Undo/redo buttons
+
+### Changed
+
+- Controls and MiniMaps everywhere
+- updates schemas and docs via test script
+- Clicking on the button to get the permalink, will always return the link where the custom data is encoded. Never a
+  link with raw data.
+
+### Fixed
+
+- Changelog formatting
+- Auto layout with horizontal layout was broken.
+- Some shapes showed unexpected behaviour when height and width were not the same.
+
+## [1.0.0] - 2022-08-12
 
 ### Added
 
@@ -45,17 +78,12 @@ First ever release. You can make flows from JSON or YAML.
 
 - Issue #40: If you changed the color of an edge, all the markers with no color specified, changed to that color.
 - Issue #69: Title and label in a node that was no parent, did not work.
+- Kept [README.md] en [DEVELOPMENT.md] up to date with all the new changes and additions.
 
-Kept [README] en [DEVELOPMENT] up to date with all the new changes and additions.
-
-## Unreleased
+## [0.1.0] - 2022-08-04
 
-* /
+First ever release. You can make flows from JSON or YAML.
 
 [DEVELOPMENT.md]: DEVELOPMENT.md
 
-[DEVELOPMENT]: DEVELOPMENT.md
-
 [README.md]: README.md
-
-[README]: README.md

DEVELOPMENT.md

@@ -4,46 +4,71 @@ This document is aimed at developers.
 
 ### How to autogenerate the documentation
 
-In [index.js](src/index.js) set the variable `download` to `true`. Rerun the application and set the variable to `false`
-again. You will notice there were three JSON files downloaded. Paste the contents of these files in the accompanying
-files in the directory [schemas/schemas](schemas/schemas). Open your terminal, `cd` to `/schemas` and
-run `node JSONSchemaMarkdown.js`. The new markdowns will be generated, [README.md](README.md) already links to these
+Run `npm run build:docs`. This uses the Jest runner to re-create the schemas and their documentation,
+and stores them in the accompanying
+files in the directory [schemas/schemas](schemas/schemas).
+The new markdowns will be generated, [README.md](README.md) already links to these
 files.
 
-You might ask why not introduce a command, e.g. `npm build docs` that launches a separate script. The reason is that
-React can't write to files and the separate script would need the schemas being built
-in [schemaValidation.js](src/lib/schemaValidation.js). In order for that script to import a JavaScript file used in 
-React, someone should mess with webpack. To the person who will do this, good luck!
+Note that there is a pre-commit hook (see [.husky](.husky)) that regenerates the docs.
 
 ### How to add shapes/images
 
 As mentioned in the documentation, the value of `image` can be a predefined value or a URL. If you want to add your own
 predefined
-image, edit the hashmap `SHAPES` in the file [nodeUtil.js](./src/components/node/nodeUtil.js). Pull requests are always
+image, edit the hashmap `SHAPES` in the file [nodeUtil.js](./src/components/node/nodeUtil.js). Then add the name of your
+shape to the array `shapes` in [configParsing.js](src/lib/configParsing.js). Pull requests are always
 welcome.
 
+Note that there are already thousands of shapes supported. In your node config, you can set `shape` to `icon`. Then you
+can set the key `iconName` to anything defined in the [react-icons](https://react-icons.github.io/react-icons) library.
+
+### How to add a custom React component as a node
+
+Add your custom React component under the [custom](./src/components/custom/) folder and add an entry
+to [index.js](./src/components/custom/index.js).
+See the `Details` component for an example.
+
 ### How to add examples
 
+#### Single-config flow
+
 When using this application, you'll notice there are buttons to load examples. These buttons load in the
-files [exampleData1.js](./src/data/examples/exampleData1.js), [exampleData2.js](./src/data/examples/exampleData2.js) ...
+files [exampleData1.js](src/data/single-flow/examples/exampleData1.js)
+, [exampleData2.js](src/data/single-flow/examples/exampleData2.js) ...
 So if you want to
 add
 an example, just create another file. In this file, you should have a JSON object for the global defaults, an array of
 nodes
 and an array of edges. Optionally, you can set a title as well. This will be the text inside the button (so the contents
 of the buttons don't have to be `example x`). If your file is ready, import everything
-in [examples.js](./src/data/examples.js) and add your imports to the array `examples`. A button to load in
+in [examples.js](src/data/single-flow/examples.js) and add your imports to the array `examples`. A button to load in
 your example will automatically show up if you restart the application.
 
+#### Multi-config flow
+
+The buttons to load in multi-config flows are shown on the page where you build your simulation.
+There is already an example provided. See e.g., [example1/](src/data/simulation-flow/examples). To make your own
+example,
+make a new folder where you put every step in a different file. As with the single-config examples, you should have a
+JSON object for the global defaults, an array for the nodes, and an array for the edges. When you have created your
+configs, import them in [examples.js](src/data/simulation-flow/examples.js). Next, add your imports to the
+hashmap `examples` the same way
+this is done by the other examples. The keys of the hashmap (e.g. `example 1`) will be the text on the buttons (that
+once again will show up automatically). However, you can't deviate from the keys `step0`, `step1`, `...` .
+
 ### Permalink
 
-There is a button to get a link to your flow. There are two formats for a link.
+There is a button to get a link to your flow. There are three formats for a link.
 
 1) `https://knowledgeonwebscale.github.io/dataflow-visualization/#/customdata?globaldefaults=...&nodes=...&edges=...`
     * The query parameters are the URI-encoded values of what's inside the editors.
 2) `https://knowledgeonwebscale.github.io/dataflow-visualization/#/rawdata?nodes=...&edges=...`
     * The query parameters are the URI-encoded values of the raw data of the flow. Remember, there is a button to export
       the raw data.
+3) `https://knowledgeonwebscale.github.io/dataflow-visualization/#/online?location=...`
+    * The query parameter is a URL to an online JSON file. The structure of that file should be the same as the
+      structure when you export your config.
 
-If you press the button to copy the permalink to your clipboard, you get whichever link is shortest. 
+If you press the button to copy the permalink to your clipboard, you get the first link (`customdata`). 
 

README.md

@@ -1,3 +1,5 @@
+<!-- omit in toc -->
+
 # Flow Visualization
 
 This is a [React] application to generate flow graphs from [JSON] or [YAML].
@@ -8,7 +10,8 @@ It is built on top of [ReactFlow].
     - [Global defaults](#global-defaults)
     - [Nodes](#nodes)
     - [Edges](#edges)
-    - [Buttons](#buttons)
+    - [Buttons](#controls)
+- [FAQ](#faq)
 - [License](#license)
 
 ## How to run
@@ -20,13 +23,13 @@ and open http://localhost:3000/.
 ## Documentation
 
 If you [run the application](#how-to-run), you'll see that there are three editors. One to
-set [global defaults](#global-defaults), one to describe the [nodes](#nodes) and one for the [connections](#edges)
+set [global defaults](#global-defaults), one to describe the [nodes](#nodes), and one for the [connections](#edges)
 between these nodes (edges). The editors you see are the same editors used
-by [Visual Studio Code](https://code.visualstudio.com/),
-this means that you can use shortcuts like `ctrl+shift+i` for indentation or `ctrl+z` to undo your last change. You can
+by [Visual Studio Code](https://code.visualstudio.com/).
+This means that you can use shortcuts like `ctrl+shift+i` for indentation or `ctrl+z` to undo your last change. You can
 also open the command palette by hitting the `F1`-key.
 
-Note when reading this documentation: this is a [React] application, so all ID's/properties are
+Note when reading this documentation: this is a [React] application, so all ID's and properties are
 written in [camelCase](https://en.wikipedia.org/wiki/Camel_case).
 
 ### Global defaults
@@ -42,6 +45,16 @@ nodes or edges.
 
 * More info: [nodes](schemas/docs/nodes-doc.md)
 
+#### ID
+
+IDs are used by the edges to refer to a node. But IDs are not mandatory. If no ID is specified:
+
+* If the node has a unique `title`, the title becomes the ID.
+* If the node has a unique `label`, that label becomes the ID.
+* If the node has a unique `shape`, that shape becomes the ID.
+* If the node has a unique `image`, that image becomes the ID.
+* Otherwise, there is no way (as the end user) to refer to that node.
+
 #### Node positioning
 
 [As seen before](#nodes), you can set the positions of all nodes individually with the `position` key. But it is not
@@ -62,36 +75,25 @@ very efficient to set all nodes manually. There are three mechanisms to make the
 - Use the `autoLayout` key:
     - If set to `true`, [dagre](https://github.com/dagrejs/dagre) is used to position all the nodes. The keys `position`
       , `vgroup` and `hgroup` are ignored. This method works for very simple flows (e.g. example 1). If your flows start
-      to get a little more complex, this method is not recommended, because dagre does not always work very well in
+      to get a little more complex, this method is not recommended because dagre does not always work very well in
       combination with this project.
 
 ### Edges
 
 * More info: [edges](schemas/docs/edges-doc.md)
 
-#### Animations
-
-There is a key `animated`, which you can set to `true`. But if you want custom animations, you should use
-the `animation` property. An example of the standard `animated` key can be found
-in [example 2](/src/data/examples/exampleData2.js). Custom animations can be
-found in [example 6](/src/data/examples/exampleData6.js). For more information about the `animation` property, please
-check out
-the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/CSS/animation). If you use `animated` with
-no `strokeDasharray`, `strokeDasharray` is set to a value of `5`. If you use a custom `animation`, the `animated` key
-has no effect anymore.
-
-### Buttons
+### Controls
 
 When running this application, you'll see that there are a few buttons visible.
 
 #### Example buttons
 
-These buttons on are for loading in examples.
+These buttons are for loading examples.
 
 #### Import/export buttons
 
 These buttons are to import and export entire configs (format is JSON). This feature is useful if you want to save
-configs for later.
+configurations for later.
 
 There is also a button to export the raw data. This is the data needed for [ReactFlow] to draw up a flow.
 
@@ -125,13 +127,74 @@ See [DEVELOPMENT.md](DEVELOPMENT.md#permalink) for more information about the st
 
 #### Autosync button
 
-If this switch is toggled on, the flow will render automatically if the config has been changed and is valid.
+If this switch is toggled on, the flow will render automatically if the configuration has been changed and is valid.
 
 #### Snap to grid button
 
 If this switch is toggled, the nodes will be snapped to the grid. If this switch is not toggled, you can move the nodes
 more freely.
 
+#### Enter permalink input field
+
+If you have a link `https://knowledgeonwebscale.github.io/dataflow-visualization/#/customdata?...`, you can enter that
+link in the text input field. The configs encoded in that URL will be filled in into the editors, so you can edit and
+create a new permalink.
+
+#### Undo/redo buttons
+
+With undo, you can go to a previous (valid) configuration, and with redo, you can move forward.
+
+*Autosync enabled*  
+The state of the configs is saved if there has been more than two seconds elapsed since the last change in one of
+the editors.
+
+If you click on e.g. redo you load in the previous config. That configuration will, of course, not be saved again (
+unless you make a change).
+
+*Autsync disabled*  
+The state of the configs will be saved every time you press 'convert' and your configs are valid.
+
+#### Create simulation button
+
+When clicking on this button, you'll be redirected to a new page. On that page, you can create multiple configs. When
+clicking 'convert', you'll be able to animate the flow by visualizing one config after the other.
+
+#### Navigation bar
+
+Next to the window where your flow is shown, you see a gray bar. This is some sort of "jump bar". Depending on where
+you click on the bar, you'll jump to the height of a different node. If you click somewhere at the very top of the bar,
+you'll jump to the height of the most upper node. The lower you click, the lower the node that will be picked as the
+reference height. If you click somewhere at the bottom of the bar, you'll jump to the y position of the lowest node.
+
+This navigation bar is very useful when you want to quickly navigate through a very large network of (vertically
+oriented)
+nodes.
+
+## FAQ
+
+#### I have an animated edge. How do I change the direction of this animation without messing up my layout?
+
+You could, of course, switch `source` and `target`. But when using `autoLayout`, this may mess up your layout a bit. A
+solution could be to use the `animation` key. If you have `animation` set to e.g. `dashdraw .6s linear infinite`, you
+can just change this to `dashdraw .6s linear infinite reverse` and your problem is solved. If you're satisfied with the
+default animations, there is also an option to set `animation` to `reverse`.
+
+#### The sizing of some nodes doesn't seem to work. Why?
+
+Some shapes are only defined by an aspect ratio. So changing that ratio simply makes it another shape. For example,
+setting a
+different width and height for the shapes `square`
+, `cirle` ... does not make sense.
+
+If you do set, e.g., a `square` to a width of, e.g., 50 and a height of, e.g., 100. Then the largest possible square
+will be
+drawn inside a box of 50 by 100 (so in this case, you can expect a height of 50).
+
+#### In the simulation creation page, when loading example 1 and clicking convert, I just see a button 'Step 0'. Shouldn't I see more buttons (one per configuration)?
+
+Yes, you should see more buttons (you should see a button for step 0 to step 4). Some people reported this bug, this
+is an unresolved issue ([#138](https://github.com/KNowledgeOnWebScale/dataflow-visualization/issues/138)).
+
 ## License
 
 This project is licensed under the terms of the MIT License. See [LICENSE.md](LICENSE.md) for details.