flowhub / the-graph

SVG custom elements for FBP graph editing and visualization. Used in noflo/noflo-ui

The Graph Editor

This project provides a set React components for viewing and editing node-based graphs. The focus is on graphs used for dataflow and Flow-based programming.

The graph structure is stored by fbp-graph, which supports extendable metadata and undo/redo.

You can optionally use klayjs-noflo for automatic layout of graphs.

the-graph is used as the editor in the Flowhub IDE.

Examples

• Basic demo. code | Run
• Stresstest. code | Run
• Thumbnail. code | Run

Using

Install via NPM

npm install the-graph

See the examples for how to include the .js and .css files, and API usage.

License

The MIT License

Support

Please refer to https://noflojs.org/support/.

Developing

Clone the repo

git clone https://github.com/flowhub/the-graph.git # or your own fork on Github
cd the-graph

Install dependencies and build

npm install
npm run build

Run the demo server

npm start

or http://localhost:3000/examples/demo-full.html for interactive demo.

Send pull requests on Github!

the-graph's Issues

center process label

<the-graph-process>
  <h1 class="the-graph-process-label">makeMinuteRotation</h1>
</the-graph-process>

Pretty basic, but impossible with css unless they all have a certain width.

Ensure touch targets stay reasonable also when zoomed out

This means the absolute minimum size should be 22 pixels for the following things:

• Node
• Port on a highlighted node

dragging node crosshair

It can be tough to know where you'll release the node when your finger covers it. A simple solution could be a crosshair in the background:

start panning when dragged to edge

edge and node

Workaround until this is fixed: two-finger/mouse-wheel scroll works while dragging a node.

drag node from gesture start point

Would be nice to drag the node from where the gesture started (or middle) instead of top-left. In forresto/dataflow-prototyping#1 it snapped to the middle while dragging and that seemed ok.

bring process to top

when highlighted or dragging

Nodes should not snap to grid when dragging

Nodes should snap to grid on release, otherwise feels too jittery

Port side choosing: go with the side matching most edges

Currently the port side (E, S, W, N) is determined by the last edge added. Instead, this should happen by looking at all the connected edges and choosing the direction matching most of them.

Snap newly loaded graph to grid, keep node x, y as absolute

The snap-to-grid feature from #8 should be entirely a visual aid for making graphs look cleaner with less fiddling. However, the grid should not affect the actual x, y coordinates of nodes:

• When loading nodes from an initial graph, apply the grid to their positions
• When moving nodes, store their real x, y value, but show them with the grid applied

This way we can even make the grid configurable, as it might be that the desirable grid size for a graph is anything between 1 pixel and [node-width].

prevent flash on panning

Panning -x -y direction fires a bumped event, which process and edges listen for to compensate. We should ensure that this happens within a single redraw, not the next event loop.

grid is getting out of whack

related to #24 (rounding to whole pixels), the grid is getting off with rounding background size and node positions.

same edge might want to come from both right and bottom

depending on the nodes that it is connected to

re #1
noflo/noflo-ui#14
noflo/noflo#90

panDebounce is causing graph to pan off screen

pan a bit, then pause, then move again... the pan skips. need to reset something else when panned is hit.

pointer event performance

I'm noticing that moving nodes is pretty slow, and I think the timeline is saying it is the pointer event polyfill's fault.

Found another polyfill that could be worth trying: https://github.com/Rich-Harris/Points

Since that one intercepts events at the window level, it could maybe allow gmaps-like panning while dragged outside of the window.

this.$.graph broken

Maybe we shouldn't change ids: 9e9546e#commitcomment-4605161

Edges should get removed when node is removed

When the node in either end of an edge is removed, the edge should get removed as well.

Possibly needs MutationObservers.

port positioning is a bit wobbly

on load:

Show port names when zoomed in

When user zooms in, we should at some threshold start showing the port names.

Limit canvas panning

Even though we need to have an infinite canvas (#10), we still should not users get lost in the dot grid jungle.

So, limit panning so that at least one node from the graph is always visible on screen.

mouse wheel: pan or zoom?

mouse wheel and 2-finger move on trackpads. i went with pan in dataflow. gmaps zooms.

Implement a minimap for the graph

When parts of the graph are outside the current view, we should display a minimap showing the whole graph, with the current viewport highlighted.

It doesn't have to be an exact reproduction of the big graph, it is probably enough to just show the nodes as "blips"

(This could also be useful to preview a subgraph or collapsed group.)

Architectural questions

Think we should iron these out sooner than later:

• When does it make sense to use lightdom vs shadowdom
• Attributes vs properties: seems like attributes are always strings, which is annoying to have to parse them back and forth.
• Positional attributes as vectors pos="x y" pan="x y" since we need to react to both when one or both change. (Or properties? node.pos = {x:100, y:100})
• the-behavior with a scale attribute. That way moving nodes and panning can be done in graph-relative units. The gestures can stay in screen-relative pixels.

show all port names at some zoom level

We have a lot of empty space in the boxes, especially after zooming in. At some zoom level we should show all port labels.

mouse wheel for firefox

https://developer.mozilla.org/en-US/docs/DOM/DOM_event_reference/DOMMouseScroll (?)

avoid dubstep effect, round values to pixel

translate on the-graph
translate on the-process
size of the-process
left of the-process h1 (gss/gss#5)

(see difference in node on left and right)

the-pointer-trail stealing pointer events

this breaks

• process snap-to-grid
• minimap drag tracking
• zoom button click

select first inport or outport on highlight gesture

So, dragging directly from one node to another (e||w) will result in the first (compatible) ports being ready to connect.

Make Port calculatePosition faster

Currently position calculations seem kind of heavy. On a graph with 45 nodes that contain 105 ports, the calculation can take around 500-700ms.

A big part of this might be the fact that each port queries its siblings to find its relative position. It might be better to put the-graph-inports and the-graph-outports into the driver's seat to make this more coordinated.

See gss/gss#6

Correlate zoom centering and level to finger positions

With #14 zooming is now centered, which is perfect for non-touchscreen devices that use the zoom controls on the map screen.

However, this still isn't exactly how zooming should behave on the pinch gesture. Essentially what you want is tracking the position of the fingers, and changing map zooming and panning so that the fingers constantly stay on the same "absolute" graph coordinates regardless of how you pinch.

Make wires touchable

Now the wires are so narrow that it is pretty much impossible to touch and manipulate them. We need to make the thicker without affecting how they look.

Different edge drawing algorithm for different edge directions

Instead of having a single edge drawing algorithm, we should look at the heading of the edge (from source node to target node), and pick the right algorithm:

• E, NE, SE: from right side to left side, possibly with a curve
• S: from bottom to top, possibly with a curve
• N, NW, W: from bottom to left with a curve passing both nodes
• SW: from bottom to top, with a curve passing both nodes

make edges with clicks/taps instead of dnd

Another way to make edges:

• click node to show ports
• click port
• compatible ports expand (might require another tap to open that node)
• click port

We should see if this is better than the directional gestures to move vs connect.

consider modes

graph: select, pan, zoom

node: move, connect

We've been avoiding modes as a design constraint, but I think eventually we'll have to break down and use them (+ keyboard shortcuts).

Center zoom

Currently we zoom at an edge. Instead, zooming should center at:

• center of the screen when using the on-screen buttons
• based on the touches when pinching

This should affect pan state accordingly

Swipe across a wire to remove it

For touchscreen devices, it would be nice to have a gesture where by swiping across a wire (or a set of them) they get removed.

label legibility when zoomed out

make some zoom breakpoint classes to make the font smaller / closer to node

drag pan outside of window

if the listener is attached to window is will also fire when dragging and releasing outside of the window, like gmaps

tested and working with

    var graph = this;
    window.addEventListener('track', function(event) {
      graph.panning({
        x: graph._pan.x + event.dx,
        y: graph._pan.y + event.dy
      });
    });
    window.addEventListener('trackend', function(event) {
      graph.panned({
        x: graph._pan.x + event.dx,
        y: graph._pan.y + event.dy
      });
    });

Nodes disappearing on state changes

Side effect of the work on #10 , currently we have nodes disappearing on several situations, like:

• changing zoom level
• highlighting a node

They reappear on pan, so this is probably a bumped value problem.

Momentum panning

A fast swipe should pan all the way across the graph (but not further, #15).

Should feel the same as the browser's momentum scrolling. Is there an accepted equation for that?

Show graph exports

the-graph-export nodes should be visualized as "pseudo-nodes" that can be moved around, removed, etc.

Basically the same look as regular the-graph-process instances but without highlighting.

gpu scaling looks like vector?

transform: scale(2)

ff

chrome

any idea why ff looks like vector scaling, and chrome a scaled texture (expected)?... seems like it must not be accelerating the css transform, though it feels just as fast.

grid alignment

nodes should snap #8 centered in the css grid

and the grid is getting off on zoom, fixing itself on pan

rotated ports in highlighted nodes

I'm voting to not rotate the ports to match the wires. I think it is more important that they match the direction of the gesture.

Background heat map

Currently the graph background is a passive dot grid. In the sketches however it had some additional features:

1. Red guide line every third grid unit
2. "Heatmap" showing the impact of currently selected node(s)

The heatmap should react to selection/highlighting state of nodes and show a brighter background for the grid under selected nodes, fading towards the regular dark background along the connections of that node

port order match order specified in component

I think this is important for muscle memory. After the initial ports are loaded based on the connections present in the graph, we will need to correct the order once the info is loaded from the library.

Otherwise...

Node groups/layers

For a better way of explaining the structure of a graph, we need to support something like node grouping/layering with some textual information added.

The groups could be possible to either hide completely ('show only the templating part of this graph'), or maybe showable as a single node, sort of as 'inline subgraphs'.

Originally opened as meemoo/dataflow#56, see that for older discussion. The NoFlo side of this ticket is noflo/noflo#62

UI mockups

Grouped nodes in a graph:

Group navigator card (which would be in noflo/noflo-ui):

Clarify roles of the-graph and the-graph-editor

The graph component is responsible for displaying a graph. It may allow things like panning and zooming, but it shouldn't make any modifications to the graph (though it can of course react to modifications that happen anyway).

The graph editor component uses the graph component and adds the editing features.

This way we can use the-graph for static graph visualization, and the-graph-editor as the actual editing UI.

edge sometimes on wrong side after zooming

Zoom all the way out, let render, then zoom all the way in.

Strange. I thought that making the redraw synchronous would fix this, but it hasn't.

Snap-to-grid

Currently node dragging is 100% accurate, following your pointer (though, see #5). This makes graphs fiddly and easily messy-looking. We should instead implement a snap-to-grid feature. The sizing of that grid is another question... even a 10 pixel grid could be helpful, but on the bigger end we could even impose a grid of the same size as the nodes are.

infinite canvas

for real this time 😉