do-community/diagram-tool

🚧 A tool to design infrastructure diagrams.

Diagram Tool

This tool is a infrastructure diagram tool. The goal of the Diagram Tool is to be able to clearly lay out diagrams for infrastructure which you want to create, allowing you to be able to visualise your plans.

Development/Building

To setup the build/develop environment, you will need to run npm i with Node 12+ installed (you can use nvm to do this). This will install the dependencies to allow you to build the project.

To develop for this tool run npm start. This will start a development server that will automatically reload the codebase when changes occur.

If you wish to host this tool on a service, simply run npm run build. This will run all the necessary build scripts automatically to build the tool. You can then take the dist folder and put it on your web server/bucket.

GitHub Actions is setup to do this automatically for this repository to deploy to gh-pages. It is also configured to deploy each PR commit to DigitalOcean Spaces for PR previews.

Contributing

If you are contributing, please read the contributing file before submitting your pull requests.

Source Structure

src

src/styles

Any stylesheets which are required. Right now, this folder only contains 1 file, but this can be expanded over time.

src/data

This defines the data which is used within the application. When new data is created which the application should use, it should be added there. If you wish to create a new node, you should run mk_node.py.

src/components

This defines the React components that are used within the application. All components which are used should, therefore, be within this folder.

src/actions

This is used to handle the actions within the application.

diagram-tool's Issues

Improve initial state

Currently, the initial state for the tool always provides three buttons:

If a user is new to the tool (no saved tool state), these buttons don't really make much sense. Instead, we should simply show a single button New Diagram which takes them through to the diagram creator in a blank state.

For a user who already has a saved state, the New Diagram button seems a bit odd -- pressing it reloads the page and appears to do nothing else. Instead, this should wipe the saved state and immediately take them through to the tool, providing a far more intuitive experience.

For a user who already has a saved state, Go To Tool might not be the best text to describe what that button does, instead, we should consider using text like Continue Diagram to explain that this button will go to the diagram creator with their existing saved diagram state.

In all cases, we could consider making the initial state (start screen) more interesting by adding some buttons/images below these primary buttons that act as pre-created diagrams. These might be under a small 'Example Diagrams' header, where we provide a set of images (showing the examples), where clicking on one would load the diagram creator with that example as the new state.

Move new/save diagram buttons top right, grow name

On the diagram editor view, move the new/save buttons to the top right and then flex-grow the diagram name to fill the remaining width.

Further, we can then shorten the height of the editor to be below this set of items, so that diagrams can't end up stuck underneath.

Support click to edit on new diagram view

On the new diagram view, instead of the small play button, allow clicking anywhere on the image to open the diagram in the editor.

Sometimes "Remove from all categories" will not time out

Information

Chrome 83 on macOS (Catalina)

Details

Description

For some reason, removing from all categories doesn't hide as expected.

Steps to reproduce

Unknown. It sometimes seems to happen.

Expected behavior

Hides after 10 seconds.

Screenshots

If tool state empty, go to new diagram view

If the tool state is empty (no nodes etc.), it currently shows the blank diagram editor view. Instead, we should show the new diagram view.

Replace menu button with new + save

In the diagram editor view, we should replace the current Menu button with two buttons in the top right of the screen that provide direct access to the New and Save views/functionality in the tool.

These should be two small buttons (similar style to current menu button) in the top right of the screen so that they are out of the way and pose less potential for intruding on a diagram.

Provide more complex new diagram examples

With the new diagram view now providing an example diagram, we should expand this to provide some more complex diagrams based on potential real-world infra layouts.

It might be worth looking at https://do.co/diagram-kit for inspiration here.

Remove 'Currently Shown Diagram' text

Allow deletion of nodes/links

It seems this functionality might have been lost along the way somewhere, but it seems you can't currently delete nodes.

To make this more intuitive, I think we should actually bring back node selection & the properties panel, but completely change the contents of the panel.

In the panel, I think we should have two simple actions:

1. Remove from all categories
2. Remove node

Moving these to a panel should hopefully provide a cleaner experience in the main diagram creator, not clogging the view with 'Remove from all categories', as well as providing a definite button to remove a node from the diagram.

---

To extend this, a third option I'd love to see in the panel is a toggle for if a node should sit on the 'edge' of a category boundary.

Some node types do this by default, and I think for some users this might be confusing and an unwanted feature, so when a node is selected and this panel shows, we could provide a simple toggle for the node to control if it sits on the edge, or fully within the category.

Escape button dismisses "New Node" panel and crosshairs

Feature request

Feature description

When the "Category Selection" panel and new node crosshairs are open, pressing the escape key should dismiss it.

How the feature is useful

Sometimes users will click the background just to deselect nodes, we need a way of letting them do this without bringing up the "new node" panel.

Provide input for save diagram link

Improve panel design

The current panels used in the diagram tool are functional, but not following the normal design standard seen throughout DigitalOcean and our other tools.

Some improvements that can be made:

• Use the standard do-bulma panel styling, which has a much cleaner box-shadow, as well as background color & different border-radius
  

• Show the 'pointer' cursor for items that can be clicked on, such as the different node icons & the back arrow.

• Provide a hover state for items that can be clicked on, to further visually confirm they are items that can be clicked.

• Replace the back arrow with a proper icon, either chevron-left from Feather which we can bring in as an SVG directly, or angle-left from FontAwesome if we already have FA in the tool

Allow customisation of connectors

Currently, the connectors in the app are automatically given a specific style based on the determined connection type.

Whilst this is technically accurate and is great default behaviour, we should allow the user to change the style of the connector line if that is what they want to do. We should offer all the current connector styles currently in the app, as well as any others featured in the diagram kit that we don't currently have.

Further to this, we should also allow the user to optionally enable arrow heads at either end of a connector line.

Using arrows to move nodes should snap to grid

Now that we have removed the grid snapping when dragging nodes, it is very hard to align multiple nodes together.

To counter this, we should update the arrow keys controls to snap to a grid. When a node is selected and the arrows keys are used to move it, the movements should snap to a 16x16 grid.

This will allow for a user to drag a node wherever they want and align it to a grid with arrows keys if needed.

Remove labels from connectors

Currently, connectors have labels that show when you hover over them.

For now, we should remove these labels to avoid confusion.

At a later date, in a separate issue, we can reevaluate labels for both connectors and nodes.

Allow dragging & zooming of canvas

We should allow the user to build a diagram as big and as complex as they'd like.

To support this, we should allow the user to drag the canvas around (using middle mouse button) so that they can add nodes in places that would be default be off-screen.

This also acts as a great solution for if nodes end up stuck under the new/save controls, the user can just drag the canvas so they aren't under the controls.

Further, we should also allow the user to zoom the canvas in/out so if they have a large, complex diagram they could view the whole thing on the screen at once.

This should be done with cmd/ctrl + scroll -- we will need to hijack this from the browser's default zoom behaviour when in the diagram editor view.

Arrow keys should snap to global grid

Currently the arrow keys shift by 8px, but not everything is aligned the same. The arrow keys should shift by one cell on an imaginary global 8px grid, snapping the node to that grid if it is misaligned.

Save diagram should not automatically save to clipboard

Using the save diagram button shouldn't automatically save the URL to the clipboard. This is likely very unexpected for the user and may result in them losing important information currently in their clipboard.

Instead, the save diagram button should show a view (or a modal) that has a read-only textbox with the share URL that has a copy icon next to it. When the copy icon is clicked it will then write to the clipboard and indicate to the user that this has happened.

Demo diagrams generate under diagram name

When using the new diagram option with a demo diagram, the diagram generates in the top left of the screen, partially under the diagram title bar.

When the user chooses a demo diagram, we should generate it centred on the screen.

Play button support

Feature request

Feature description

Some items have play buttons. These should be implemented.

How the feature is useful

This will clearly show how the traffic is routed.

Fix drag/drop jumping

Sometimes, when you drag a node and then drop it, it jumps slightly to a different position than where you'd expect it to drop.

This seems to be happening as whenever a node is dropped, the middle left point of the node aligns itself with the cursor position.

To fix this, I believe we need to store the position of the cursor on the node when then drag begins, and then apply this offset when the node is dropped.

Save Diagram dialog should format the URL

Information

Chrome 83 on macOS (Catalina)

Details

Description

the save diagram URL goes outside of the screen

Steps to reproduce

Go to the save diagram screen from the menu

Expected behavior

it is formatted properly

Screenshots

Initial state may not be new diagram view

In Firefox, if I remove the diagramTool local storage values and reload the tool I am presented with the To start, simply click anywhere... diagram editor view.

The initial state for the tool (if no existing diagram) should always be the new diagram view, not the main menu or diagram editor.

Add hover states to all menus

Currently, the menus used in the app (the component selector & node menu) do not have an indication on which bits are clickable.

The items I noticed that don't indicate you can click them:

• Components, categories & back arrows in the component selector menu
• 'Remove ...' options in the node menu

For these, we should add a basic cursor: pointer to them and consider also adding a proper :hover state to them.

[Security] Workflow gh-pages-workflow.yml is using vulnerable action JamesIves/github-pages-deploy-action

The workflow gh-pages-workflow.yml is referencing action JamesIves/github-pages-deploy-action using references 2.0.0. However this reference is missing the commit 661e33871bce8107c9af083f7415176608dce40e which may contain fix to the some vulnerability.
The vulnerability fix that is missing by actions version could be related to:
(1) CVE fix
(2) upgrade of vulnerable dependency
(3) fix to secret leak and others.
Please consider to update the reference to the action.

Rename main menu button to diagram, only show if state present

On the new diagram view, there is a return to main menu button that goes to the diagram editor. Let's rename this to Return to diagram, and we should only show it if there is contents in the diagram to show.

End user components + third party components crash the app

Selecting any component from the end-user components section or from the third party section crashes the app.

Further, if you have one of these components already in a diagram, selecting it crashes the app also.

Import icon packs

Feature request

Feature description

The ability to import icon packs would make this useful for the end user to easily expand as they needed.

How the feature is useful

Allows user specific items to be imported without having to PR it (which may not be possible for niche items).

Select node when dropped

[Security] Workflow gh-pages-workflow.yml is using vulnerable action actions/checkout

The workflow gh-pages-workflow.yml is referencing action actions/checkout using references v1. However this reference is missing the commit a6747255bd19d7a757dbdda8c654a9f84db19839 which may contain fix to the some vulnerability.
The vulnerability fix that is missing by actions version could be related to:
(1) CVE fix
(2) upgrade of vulnerable dependency
(3) fix to secret leak and others.
Please consider to update the reference to the action.

when all items in category are copied, we should create a new category of the same name

Right now they persist the same category they were in before. We should instead clone this.

Round of small UI Feedback

When the add node "Category Selection" pane is open, any clicks outside the pane should close it (like a modal)

Connectors should look different when "selected" (similar to how nodes have a blue focus glow ring when selected)

Dragging some nodes is bugged

Certain nodes behave differently from the others, where dragging them causes them to jump all over the screen and not drag/align how you might expect them to.

This can be seen with the 'Application Server' node, where dragging it will cause the 'ghost' version to appear in a completely different location to the actual node, leading to it being dragged to an unexpected position:

This can also be seen to a lesser degree with the 'MySQL Server' node:

Selection doesn't work

Details

Description

Selection does not work if you try and drag. I believe this is relating to the Z positioning.

Steps to reproduce

Try dragging around items.

Expected behavior

The nodes get selected.

Screenshots

N/A

If multiple nodes are selected, allow dragging together

If you have multiple nodes selected, using arrow keys allows them to be moved together but dragging doesn't work. Support dragging of multiple nodes.

Removing a node from categories doesn't work

The option to remove a node from categories (shown top right when a node is selected) doesn't seem to work. Pressing it doesn't appear to remove a node.

This should be fixed so that pressing the option removes the node from categories -- this should be shown visually with the node no longer being in a category and also with the option disappearing from the menu when the node is in no categories.

Whilst we're fixing this, we should also update the copy used from Remove all categories to Remove from all categories.

Allow deletion of connectors

Currently, connectors can be created and can be auto-generated.

However, there is no way to select and connector and delete it.

Similar to how you can select a node, we should allow the selection of connectors which then allows them to be removed.

New diagram view is misleading and unintuitive

The new diagram view on the tool is somewhat misleading and unintuitive in a couple of ways:

1. The preview for the blank diagram is the To start, simply click anywhere... text, which is misleading as you cannot just click anywhere to start

2. The demo diagram previews are very low down on the page, almost below the fold on small screens. Further, selecting one to use is very unintuitive with a small play icon as the only way -- we should improve this.

Add labels to nodes & connectors

Currently, a user cannot add a label to a node to describe what its purpose is. Further, a user cannot add labels to connectors, to describe the data flow etc.

We should allow the user to add a label to a node. We should provide an option for the position of the label: below the node, above the node, to the right of the node, to the left of the node.

Similar to the node, we should also allow the user to add a label to a connector. For positioning of this, we should provide two dropdowns that combine to define a position. The first should be an option to put the label either above or below the line. The second dropdown will then offer three options for where along the line the label should be: start, middle, end.

(I am unsure how to handle vertical lines, the above is written for horizontal lines. I assume we should have the text always be horizontal, so maybe we need logic to switch top/bottom to left/right if the line fits certain criteria making it "vertical" instead of "horizontal"?)

These label options for both the nodes & connectors can likely be offered in the panel that is shown when a node is selected. If not already implemented, we should add similar selecting & UI panels for connectors, which can then contain the label options.

Whilst we are adding new labelling, we should also consider improving the label options for a category. We can likely do a similar thing to the above, where we add the ability for a category to be selected, and then show the UI panel where the user can edit the label text and positioning. When we get to this point we can discuss further the positioning options that we offer (top/left/right/bottom + corners, all inside & outside the category boundary?).