Reactflow Workflow

React Flow Workflow

Use this skill when implementing or improving the schema diagram surface in VeloxDB.

Quick Start

1. Keep @xyflow/react styles imported once in the React Flow canvas module.
2. Ensure the canvas parent has explicit width and height.
3. Keep model state ownership in ModelWorkspace; keep ReactFlowCanvas mostly presentational and interaction-focused.
4. Use DiagramSurfaceProps as the boundary contract between workspace state and rendering.

VeloxDB Diagram Architecture

• src/features/model/components/ModelWorkspace.tsx:
  • owns diagram state (viewport, selection, on-canvas tables, pending FKs, groups)
  • computes display props and passes them into DiagramSurfaceAdapter
• src/features/model/components/DiagramSurfaceAdapter.tsx:
  • forwards DiagramSurfaceProps to ReactFlowCanvas
• src/features/model/components/ReactFlowCanvas.tsx:
  • renders React Flow nodes/edges, connects events to workspace callbacks, and exposes export handle

Keep this separation intact; avoid pushing workspace orchestration logic into the canvas.

React Flow Implementation Patterns

• Nodes:

  • Use memoized custom node components for table rendering.
  • Keep node data minimal and serializable.
  • Derive draggable, selected, and connectability from current tool mode.

• Edges:

  • Use routed edge points from buildRoutedDiagramEdges.
  • Keep pending edges visually distinct (dash + stronger color).
  • Prefer custom edge component only when built-in edges cannot represent routed geometry.

• Connections:

  • Gate with isValidConnection to block invalid or duplicate FK links.
  • Parse handles with stable prefixes (in: / out:) to identify columns.

• Viewport & controls:

  • Persist viewport to workspace via callback.
  • Throttle high-frequency viewport updates to avoid rerender storms.
  • Provide explicit fit actions (all and selection) in controls.

• Tool modes:

  • Select mode: selection + table dragging.
  • Pan mode: canvas drag panning.
  • Connect mode: handle-to-handle links; no accidental pan.
  • Space key temporarily enables panning in any mode.

UX and Styling Guidance

• Use design tokens (--diagram-table-header, --border, --muted-foreground) for node and edge visuals.
• Keep minimap/background enabled; they improve navigation on medium/large models.
• Show concise mode hints in-canvas when interaction mode changes.
• Keep selected state and focus state obvious for keyboard + mouse users.

Performance Guardrails

• Memoize mapped nodes/edges from workspace props.
• Avoid rebuilding heavy arrays on unrelated state changes.
• Throttle viewport persistence callbacks.
• Keep columns bounded for node rendering (MAX_ROWS style cap).
• Avoid unnecessary useEffect; prefer derived state and event callbacks.

Change Checklist

• Confirm no renderer fallback code is reintroduced.
• Verify interactions: select, pan, connect, marquee, drag, delete/clear.
• Verify controls: zoom, fit all, fit selection, reset behavior.
• Verify exports (PNG/PDF) still work from current viewport/container.
• Run lint/type checks after editing diagram components.

Reference

• React Flow Learn: https://reactflow.dev/learn