FlowController

FlowController holds a diagram's nodes, edges, selection and viewport, and runs its gestures. Its public methods mirror the instance React Flow returns from useReactFlow().

Getting a controller

There are three ways to reach it:

• Pass your own as the controller prop. You create it, so you dispose it.
• Receive it in onInit(controller) after the first frame. The editor owns and disposes this one.
• Read it inside the tree with FlowProvider.of(context), from a custom node, edge or panel.

import { State, StatefulWidget, type Widget } from "flitter-core";
import { FlowController, FlowDiagram } from "flitter-diagram";
 
class Editor extends StatefulWidget {
  createState() {
    return new EditorState();
  }
}
 
class EditorState extends State<Editor> {
  controller = new FlowController();
 
  dispose() {
    this.controller.dispose();
    super.dispose();
  }
 
  build(): Widget {
    return FlowDiagram({ controller: this.controller, nodes, edges, fitView: true });
  }
}

new FlowController({ transformationController }) accepts an existing TransformationController if you want to share the viewport matrix with another widget.

FlowController is a ChangeNotifier. addListener(callback) runs callback after every change to nodes, edges, selection, viewport or interaction state, including every frame of a pan. Use it to sync a toolbar outside the diagram, and remove the listener when you are done. To follow one node or edge, use its signal instead, as described under Signals and rebuilds.

Nodes and edges

setNodes keeps the measured size of nodes whose id it already knows, so replacing the array does not cause a visible re-measure.

Selection

Selection changes emit select changes and onSelectionChange.

Viewport

A viewport is { x, y, zoom }: the pane-pixel offset of the flow origin and the scale. Every method clamps zoom to minZoom/maxZoom and the offset to translateExtent. Methods that take duration animate over that many milliseconds with an ease-in-out curve and return a promise that resolves when they finish.

Coordinates

screenToFlowPosition is what you need to drop a node where the user released the mouse:

const position = controller.screenToFlowPosition({ x: event.clientX, y: event.clientY });
controller.addNodes({ id: crypto.randomUUID(), position, data: { label: "Dropped" } });

Geometry

Sizes are known only after a node is measured, so these return null or empty results until then.

Layout

See Layout.

Interaction state

Custom nodes, edges, panels and toolbars can read these while building. A node builder only reruns when its own node changes, as described under Signals and rebuilds.

Signals and rebuilds

The editor does not rebuild the whole scene on every change. It creates one widget per node and per edge, keeps it across rebuilds, and rebuilds it only when that element's signal fires.

Each widget listens to the signals it depends on:

• A node widget listens to its node's signal.
• An edge widget listens to its edge's signal and to the signals of its source and target nodes, so moving a node redraws the edges attached to it.
• The connection line listens to connectionSignal.

In practice:

• Dragging a node rebuilds that node and its edges. No other node rebuilds.
• Panning and zooming rebuild no node and no edge. The pane around them rebuilds: the background, node toolbars and panels.
• setNodes and setEdges fire every node or edge signal.
• styleVersion increases every time the Flow or FlowDiagram widget receives props, and when setInteractive toggles the lock. The editor then drops its cached widgets and every node and edge rebuilds once. A parent that rebuilds the diagram widget on every change, for example by calling setState from onNodesChange, rebuilds the whole graph each time. Keep the widget stable and change the graph through the controller.

A node builder reruns only when its own node's signal fires. If a node's look depends on something else, such as another node or your app state, update that node with updateNode or updateNodeData so its signal fires.

Panels and toolbars are rebuilt with the pane, and a panel that reads FlowProvider.of(context) rebuilds on every change, including every frame of a pan. That is fine for light widgets such as a zoom label or a few buttons. Keep heavy work out of them.

Internal methods

configure, attachPane, setPaneSize, setNodeDimensions, setPointerInside, the handle… gesture methods (including handleReconnectStart and handleResizeStart/handleResizeMove/handleResizeEnd), hoverNode/unhoverNode, hoverEdge/unhoverEdge and resetPointerMovement are called by the Flow widget. They are public so custom renderers can reuse the engine, but application code should not call them.