@pyreon/flow

@pyreon/flow

Reactive flow diagrams — signal-native nodes, edges, pan/zoom, auto-layout.

Build node/edge diagrams (workflow editors, mind maps, BPMN, story graphs, infra topology) with Pyreon's fine-grained reactivity. Each node and edge has its own per-property signal — a 60fps drag in a 1000-node graph is O(1) per frame, not O(N). Custom node and edge renderers receive REACTIVE ACCESSORS (data() / selected() / dragging() / source/target coordinates), so a custom node mounts EXACTLY ONCE across the lifetime of the graph and patches in place on every change. Pan/zoom via pointer events + CSS transforms (no D3). Auto-layout via elkjs, lazy-loaded on first use.

Install

bun add @pyreon/flow @pyreon/core @pyreon/reactivity @pyreon/runtime-dom
# elkjs is bundled as a runtime dependency, lazy-loaded

@pyreon/runtime-dom is a peer because the JSX templates emit _tpl() calls — declare it in your app's deps.

Quick start

import { createFlow, Flow, Background, MiniMap, Controls } from '@pyreon/flow'

const flow = createFlow({
  nodes: [
    { id: '1', position: { x: 0, y: 0 }, data: { label: 'Start' } },
    { id: '2', position: { x: 200, y: 100 }, data: { label: 'End' } },
  ],
  edges: [{ source: '1', target: '2' }],
})

const App = () => (
  <Flow instance={flow}>
    <Background />
    <MiniMap />
    <Controls />
  </Flow>
)

createFlow<TData>(config) vs useFlow<TData>(config)

• createFlow — bare constructor. Use for flows owned outside the component tree (app stores, singletons that outlive any view).
• useFlow — component-scoped wrapper. Auto-disposes on unmount. Prefer this inside component bodies.

const Diagram = () => {
  const flow = useFlow<{ label: string }>({
    nodes: [{ id: '1', position: { x: 0, y: 0 }, data: { label: 'Start' } }],
    edges: [],
  })
  return (
    <Flow instance={flow}>
      <Background />
    </Flow>
  )
}

The TData generic flows through to FlowNode<TData> and NodeComponentProps<TData> so custom node renderers stay typed end-to-end.

Instance API

FlowInstance<TData>:

Surface	Methods
Reactive state	nodes / edges / viewport / selection (signals)
Node CRUD	addNode / removeNode / updateNode / updateNodePosition / setNodes
Edge CRUD	addEdge / removeEdge / setEdges
Edge waypoints	addEdgeWaypoint / removeEdgeWaypoint
Selection	selectNode(id, additive?) / selectEdge(id, additive?) / clearSelection / deleteSelected
Clipboard	copySelected / paste(offset?)
Viewport	zoomIn / zoomOut / zoomTo / panTo / fitView(ids?, padding?)
Auto-layout	layout(algorithm?, options?) — Promise, elkjs lazy-loaded
Graph queries	getConnectedEdges / getIncomers / getOutgoers / isValidConnection
Listeners	onConnect / onNodesChange / onNodeClick / onEdgeClick
Serialization	toJSON() / fromJSON(data)
Lifecycle	dispose()

Components

Component	Notes
<Flow instance={flow} nodeTypes={...} edgeTypes={...}>	Main container — pan/zoom, mounts nodes/edges
<Background variant?="dots" | "lines">	Grid background
<MiniMap>	Overview minimap with viewport indicator
<Controls>	Zoom in/out + fit-view buttons
<Handle type="source" | "target" position={Position.Top}>	Connection handle on nodes
<Panel position="top-left" | ...>	Overlay panel relative to the flow viewport
<NodeResizer>	Resize handles for the selected node
<NodeToolbar>	Toolbar attached to a node

JSX components are NOT generic at the call site (<Flow<MyData> /> isn't valid JSX). FlowProps.instance is typed as FlowInstance<any> so typed consumers pass FlowInstance<MyData> without casting.

Custom node renderers

NodeComponentProps<TData> exposes accessors — NOT plain values:

type MyData = { label: string; status: 'pending' | 'done' }

const MyNode: ComponentFn<NodeComponentProps<MyData>> = (props) => (
  <div class={props.selected() ? 'selected' : ''}>
    {props.data().label}
    {() => props.dragging() && <span>(dragging)</span>}
  </div>
)

const flow = useFlow<MyData>({ nodes: [...], edges: [...] })

<Flow instance={flow} nodeTypes={{ task: MyNode }} />
// Use type="task" on nodes to render via MyNode

Each node mounts ONCE per graph lifetime. Drags, selection clicks, and updateNode(id, { data: ... }) patches read through the same reactive accessors — no remount, no diff.

Custom edge renderers

Same accessor contract — EdgeComponentProps exposes sourceX() / sourceY() / targetX() / targetY() / selected() as reactive accessors. Use the path helpers (getBezierPath, getSmoothStepPath, getStraightPath, getStepPath, getWaypointPath) inside the render to compute d.

Auto-layout via elkjs

await flow.layout('layered', { direction: 'RIGHT', nodeSpacing: 50, layerSpacing: 100 })

Available algorithms: layered (default), force, stress, tree, radial, box, rectpacking.

LayoutOptions applicability:

Option	Applies to
nodeSpacing	Every algorithm
direction	layered, tree
layerSpacing	layered only
edgeRouting	layered only

Other algorithms accept the option in the type (it typechecks) but silently ignore it at layout time. The framework emits a console.warn in dev mode when an option is set on an algorithm that ignores it.

Serialization

const snapshot = flow.toJSON() // { nodes, edges, viewport }
localStorage.setItem('flow', JSON.stringify(snapshot))

// Later:
flow.fromJSON(JSON.parse(localStorage.getItem('flow')!))

Edge path helpers

For custom edge renderers — pure functions returning SVG d-string + label coordinates:

• getBezierPath({ sourceX, sourceY, targetX, targetY, sourcePosition, targetPosition })
• getSmoothStepPath(...)
• getStraightPath(...)
• getStepPath(...)
• getWaypointPath(...) — with mid-edge waypoints

Plus getEdgePath, getHandlePosition, getSmartHandlePositions for handle math.

Position enum

import { Position } from '@pyreon/flow'

Position.Top // 'top'
Position.Right // 'right'
Position.Bottom // 'bottom'
Position.Left // 'left'

Gotchas

• @pyreon/runtime-dom is a required peer — JSX templates emit _tpl() calls.
• Custom node / edge renderers must read props as accessors (props.data(), not props.data). Reading the bare property captures a snapshot and your node won't react to updateNode writes.
• JSX components aren't generic at the call site — write useFlow<MyData>(...) then pass the instance to <Flow instance={flow}>. <Flow<MyData> /> is a TypeScript syntax error.
• LayoutOptions.direction / layerSpacing / edgeRouting apply to layered/tree only — silently ignored by force / stress / radial / box / rectpacking. Dev mode logs a warning.
• elkjs is lazy-loaded on first flow.layout() call — the first layout takes longer than subsequent ones.
• flow.dispose() is final — listeners detach, signals stop updating. Don't reuse a disposed instance. useFlow wires this up for you on unmount.

Documentation

Full docs: pyreon.dev/docs/flow (or docs/src/content/docs/flow.md in this repo).

License

MIT