From semi controlled elements to controlled nodes and edges

[moklick]

From elements to nodes and edges

At the moment there is a lot of uncertainty about handling elements (nodes and edges). The problem is that React Flow stores and updates some values like the position, width, height and handles internally that are not changed in the elements array that you pass to React Flow. It would be much clearer if we would use a controlled elements prop in combination with an onElementsChange handler to pass the changes (dragging, selecting, removing) to your elements array.

Now that we are speaking about breaking changes I thought that it would be a good time to separate nodes and edges and don't use the elements array anymore but nodes and edges with onNodesChange and onEdgesChange handlers.

That's the idea for now. We will think about it and discuss pros, cons and the specific api changes here.

[mikebarkmin]

I think that it is a good idea to have separate props for nodes and edges. At least for my use-case I am storing nodes and edges separatly and combine them to one array for passing it to the props of the flow.

[ambroseus]

+1 my case too

[computebender]

This would be amazing for my use case. I'm using React Flow as a part of a larger app where nodes mean something beyond just on the canvas. In our use case clicking a node lets you configure that node somewhere else. To manage that, I'm attempting to store the source of truth of all nodes outside React Flow's state. This means when a node is added to the external state, a new node is added to React Flow and when a node in React Flow gets removed, moved, updated, the external state must be updated to match.

The "syncing" of states I'm trying to do would be much easier with callbacks just representing element changes. An example of where the current implementation falters is having multiple nodes selected and moved, I'm relying on the onNodeDragStop callback to update external state when a node is moved, but this doesn't work for multiple selected nodes (as the callback is only called on one), or probably for "Auto-Aligning" nodes (haven't tried, but don't see why the drag callback would be called in that case).

[meatflavourdev]

From elements to nodes and edges

At the moment there is a lot of uncertainty about handling elements (nodes and edges). The problem is that React Flow stores and updates some values like the position, width, height and handles internally that are not changed in the elements array that you pass to React Flow. It would be much clearer if we would use a controlled elements prop in combination with an onElementsChange handler to pass the changes (dragging, selecting, removing) to your elements array.

+1 for this for sure-- This is the main limitation I've had to contending with-- that there is internal data hidden away inside redux stores and the elements props isn't controlled so there is no 1:1 relationship between the exposed elements state array and the state of the elements as React Flow sees them. Furthermore, when integrating with 3rd party libraries that need to synchronize state with React Flow, it's a headache that there isn't an easy solution to:

a) Give me an easy way to prevent React Flow from updating position on node drag (getting weird race conditions when I attempt to update the position myself on node drag)
b) Give me an easy way to observe React Flow's state changes without subscribing to every redux update and filtering through each update frame myself (is there a better way to do this? 🤷‍♂️)

Your proposal would increase the interoperability of the library and I think that's good for the library in the long run-- even if the change is not backwards compatible.

As for an API.. something like this I would assume-- forgive any glaring errors, I'm quite tired.

export type elementChange<T = any> = {
  before: FlowElement, // Before element state
  after: FlowElement, // After element state
  changedKeys: Map<string, any> // A map from each changed key to its new value, for ease of access
};

ReactFlowProps.onElementsChange?: (changedElements: elementChange[]) => void;

[meatflavourdev]

Thoughts on considerations re: upcoming changes

It seems to me, this would be an ideal time to also think of grouping and rafting--
check out this great example of a raft composite
and a more common group composite
Both would be excellent additions-- but my point is more that they're worth keeping in mind when considering modification to the data structure, as potential futures that present decisions might be aware of.

In addition to that-- the concept of visual ordering might also be kept in mind? Consider a scene graph where layers can be rearranged. Just throwin' all that out there as something to consider 🤷‍♂️😅

[bentron2000]

I imagine that one of the newer state libs like recoil/jotai/hookstate will make it fairly straightforward for you to provide hooks to subscribe to / update internal state more easily.

[lostfictions]

Would love to help make the transition to controlled nodes and edges happen! Maybe it could be opt-in and shipped experimentally for now, so that it's not a huge breaking change and can be iterated on? (ie. the same way React form elements can be controlled or uncontrolled)

[meatflavourdev]

+1 hookstate
ActiveJS is also just great as it implements the Observable contract for Rxjs inoperability-- a boon for anyone like me who loves functional reactive programming; any updates can be subscribed to implicitly taking care of notifying whoever and whatever wants to be notified.

yJS would fit right in by design as a Custom AsyncSystem Whoops wrong thread... but my comment stands, yJS whips the Llamas a**.

[moklick]

I am currently refactoring the node and edge handling and the internal/external state handling. The current API looks like this:

const [nodes, setNodes] = useState<Node[]>(initialNodes);
const [edges, setEdges] = useState<Edge[]>(initialEdges);

const onNodesChange = useCallback((changes: ElementChange[]) => {
  setNodes((prevNodes) => applyNodeChanges(changes, prevNodes));
}, []);

const onEdgesChange = useCallback((changes: ElementChange[]) => {
  setEdges((prevEdges) => applyEdgeChanges(changes, prevEdges));
}, []);

return (
  <ReactFlow
    nodes={nodes}
    edges={edges}
    onNodesChange={onNodesChange}
    onEdgesChange={onEdgesChange}
  />
);

With this change you get notified when a node (or multiple nodes) get dragged, selected or removed. The applyNodeChanges and applyEdgeChanges functions get exported from the library. What do you think about this API?

[moklick]

Hey @lostfictions @datoslabs @mikebarkmin @meatflavourdev

If you find the time it would be super helpful if you could check out the current v10 and let me know what you think about the current API. You can read about the changes here: #1555

[datoslabs]

THANK YOU @moklick and team for all the amazing work! I briefly read through the changelog and am impressed with the amount of work that went into this major release! I will find time this weekend to check out the updates and share my findings/thoughts.

[lostfictions]

Thanks for the ping and for all the work on this release @moklick! At a glance it looks great to me -- I'll try to give it a shot in a project this week.

[moklick]

Now that we did these changes I am thinking about doing the same for the viewport (x,y,zoom). This would make it easier to fit bounds and doing animated pans/zooms for example.

This would also mean that we can't have interactive (panning/zooming) flows without defining something like this anymore:

const [viewport, setViewport, onViewportChange] = useViewportState(initialViewport);

🧐

[mikebarkmin]

@moklick I am also very impressed. Great explanation of the changes in the upcoming release. These changes will improve the DX of React Flow immensely IMHO. Thank you very much for your afford.

[datoslabs]

Hi @moklick,

I didn't get a chance to try out the development version this week; hopefully, I will be able to spend more time next week to gain some hands-on experience on V10 branch. Based on reviewing the changes, I have a few questions/observations:

A. Using the useNodeState and useEdgeState hooks can avoid the need for boilerplate code like:

  const onNodesChange = useCallback((changes) => setNodes((ns) => applyNodeChanges(changes, ns)), []);
  const onEdgesChange = useCallback((changes) => setEdges((es) => applyEdgeChanges(changes, es)), []);

The hooks are very convenient, especially for new users, and should be included as the default example. I am wondering if the hooks can further "store" the default onNodesChange and onEdgesChange callbacks in the ReactFlowProvider context so that if users did not specify/override with custom onNodesChange and/or onEdgesChange callbacks to the ReactFlow component (like the following example), it will use these defaults. This will further simplify the starting code for new users.

...
const BasicFlow = () => {
  const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
  const [edges, setEdges, onEdgesChange] = useEdgesState(initialEdges);

  return (
    <ReactFlow
      nodes={nodes} 
      edges={edges}
    />
  );
};

...

B. The applyChanges method (in utils/changes.ts) requires the NodeChange[] | EdgeChange[] array as input; however, the case statements only handle 'select', 'dimensions', and 'remove'. I may have missed it due to my limited time to look through all the code; how would the user specify other types of changes such as "add" or other updates, are NodeChange[] | EdgeChange[]` arrays optional (ie just apply the nodes/edges arrays as provided)?

C. With the overhaul of internal states API, how would the user be able to obtain the node.__rf.handleBounds (which is often needed with advanced styling) for auto layout under the new API?

[moklick]

Hey @datoslabs

thanks for your input here :)

A: The helpers are just meant for handling the local state. We now added defaultNodes and defaultEdges which might lead to the decision to remove the useNodesState and useEdgesState hooks again ;) There is no real benefit for these hooks anymore. If you want to get started quickly you can use the new uncontrolled behaviour with defaultNodes and defaultEdges and if you want to have the full control you can use the nodes, edges, onNodesChange and onEdgesChange props.

B: The applyChanges handlers are only for updating changes that are triggered internally by React Flow. If you want to add or alter a node you can just update the node object in your nodes array.

C: For now the only way is to get the nodeInternals from the store. We already added a new hook useNodeBounds. We might add the handles there or create another one that returns the handles.

[moklick]

@datoslabs @mikebarkmin @lostfictions @ambroseus @meatflavourdev (I hope it's ok when I ping you here, if not just let me know).

Besides the new way of having an controlled React Flow component we might also add the possibility to create a uncontrolled component by passing defaultNodes, defaultEdges and defaultEdgeOptions . An uncontrolled React Flow component doesn't require any other handlers and everything (drag, remove, connect) gets managed internally. For updating the nodes and edges we created the hooks useUpdateNodes and useUpdateEdges.

Update: For updating the nodes and edges we will add a useReactFlow hook that exports helper functions like setNodes, setEdges, addNodes, addEdges etc.

You can find an example that uses all the new features here: https://github.com/wbkd/react-flow/blob/v10/example/src/DefaultNodes/index.tsx

What do you think about this?

[ambroseus]

@moklick looks good :)

[moklick]

We will not add separate useUpdateNodes, useUpdateEdges hooks etc. but add a useReactFlow hook that exports functions like setNodes, setEdges, addNodes, addEdges etc.

[lostfictions]

@moklick that link seems to be broken now -- is it this file here? https://github.com/wbkd/react-flow/blob/2a4dfce61c99f436ed3c4fc5e6fd086995ed2c55/example/src/DefaultNodes/index.tsx

I might be a little confused but it seems like you're dropping the idea of having a controlled component then? This very much looks like an API where you have to call imperative updater functions if your data changes (from an external source, for example). It definitely seems like it would be clunkier, less interoperable, and less useful than the previous proposed API in the case of data being updated from an external source.

Is it possible you accidentally swapped the terms "uncontrolled" and "controlled" in your post? I'm not sure what the "uncontrolled" API is, if it's not this.

[moklick]

Thanks! I just corrected the things you mentioned (I always mix up controlled and uncontrolled 🙃) The new uncontrolled API is an extension to the existing one. You can have your controlled flow or you can create an uncontrolled one. The uncontrolled one is easier to setup and good enough for most simpler use cases. If you need the full control you can create a controlled flow with the onNodesChange and onEdgesChange handlers.

[datoslabs]

Thank you @moklick and team for lots of great work and improvements in V10! The uncontrolled example answered my previous comments about removing the boilerplate code to simplify coding for straight forward use cases as well as users/developers new to React Flow.

After a quick glance, I noticed the get* hooks return shallow copies (instead of deep clone) of the internal store objects, is this by design? Developers may be able to make changes to these objects (e.g. node.data) outside of the set* hooks and potentially cause unintended changes in future renderings. I wonder if we can make these hooks behave much like React useState hook with a one-way update after each rendering cycle.