React Package

Package name: @graphora/react

Planned responsibility: a thin React binding over the graph engine, focused on lifecycle, props, refs, and ergonomic event callbacks.

V0.1 API

The first public component is <Graph />.

It:

• create a CanvasGraphRenderer by default
• create and mount a GraphEngine
• load raw graph input through engine APIs
• pass layouts, theme input, and interaction styles through public engine and renderer contracts
• apply a controlled highlight prop through a dedicated interaction update without remounting the engine or replacing hover and selection state
• wire React DOM events into public interaction helpers
• expose callback props for graph events, viewport changes, selection, hover, clicks, and node drag
• expose a small ref for engine-backed operations such as runLayout, fitToView, setViewport, render, and selection updates
• destroy the engine during unmount, including React Strict Mode cleanup paths

The detailed contract lives in product/specs/react-api-design.md.

Minimal usage:

import { Graph } from '@graphora/react'
import { createCircularLayout } from '@graphora/layouts'

export function BasicGraph() {
  return (
    <Graph
      graph={{
        nodes: [
          { id: 'a', label: 'Alpha' },
          { id: 'b', label: 'Beta' }
        ],
        edges: [{ source: 'a', target: 'b', directed: true }]
      }}
      layout={createCircularLayout()}
      fitToViewOnLayout
    />
  )
}
Copy

Real React examples and callback docs are tracked separately in TASK-062.

For filtered or otherwise derived graph props, opt into spatial-memory updates:

<Graph graph={visibleGraph} layout={layout} graphUpdatePolicy="preserve" />
Copy

With preserve, graph prop changes retain positions by normalized node ID and leave the viewport unchanged. Incoming finite node.position values remain authoritative. Newly seen nodes receive deterministic positions near known neighbors. The cache lives only for the mounted component instance and survives renderer recreation; call ref.current?.clearPositionMemory() to clear it. Changing the layout prop or calling runLayout() remains an explicit relayout, and controlled viewport props remain authoritative. Omitting the policy keeps the existing relayout behavior for graph prop changes.

Boundary Guardrails

React must stay an adapter over the engine. Do not implement graph normalization, layout algorithms, renderer drawing, style resolution, viewport math, or interaction algorithms in this package.

If wrapper implementation needs a missing runtime hook, prefer adding that hook to the owning package instead of hiding it in React.