OpenParable
Skip to content
← Back to skills

reactflow-workflow

Development

Build and harden React Flow diagram surfaces in VeloxDB using @xyflow/react patterns (nodes, edges, viewport, controls, interactions, performance). Use when working on schema diagram canvas behavior, replacing legacy canvas code, or improving diagram UX and scale.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/veloxbase/veloxdb/blob/HEAD/.cursor/skills/reactflow-workflow/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/reactflow-workflow, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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