@petrarca/sonnet-graph

Renderer-agnostic property graph visualization, exploration, and enrichment for the Petrarca Sonnet component library.

What's included

GraphVisualizer — Main visualization component. Renders a property graph using the active renderer (Cytoscape or Reagraph). Supports node/edge selection, focus mode, hide/show, and graph expansion.

ActionPanel — Side panel showing selected node/edge details and graph exploration actions.

GraphA11yList — Accessible DOM mirror of the graph's selectable elements. Cytoscape (canvas) and Reagraph (WebGL) draw nodes/edges outside the DOM, so they are invisible to screen readers, keyboard users, and DOM automation; this renders a virtualized list of node/edge <button>s that drive the same selection store the canvas reads. sr-only by default (real apps); pass visible for an on-screen outline panel.

GraphRendererProvider — Context provider that selects the active renderer ("cytoscape" or "reagraph").

Store factories — Create the Zustand stores the graph components need: createGraphDataStore, createGraphFilterStore, createGraphExplorationStore, createSelectionStore, createGraphFocusStore.

Graph utilities — enrichNodes, enrichEdges, buildColorPalette for preparing raw graph data before passing it to stores.

Install

pnpm add @petrarca/sonnet-graph

Required peer dependencies

pnpm add react@">=19" react-dom@">=19"

Renderer peer dependencies

Install only the renderers you use:

pnpm add cytoscape          # Cytoscape.js renderer
pnpm add reagraph           # Reagraph (3D/WebGL) renderer

If you use @petrarca/sonnet-playground (which includes the graph demo page), both cytoscape and reagraph are required even if your app only uses one renderer.

Cytoscape layout plugins (optional)

Install the layout algorithms you need. All are optional — the graph works without them but with fewer layout options:

pnpm add cytoscape-fcose    # Force-directed, compound graph
pnpm add cytoscape-cola     # Constraint-based
pnpm add cytoscape-dagre    # DAG / hierarchical
pnpm add cytoscape-elk      # Eclipse Layout Kernel
pnpm add cytoscape-cise     # Circular layout
pnpm add cytoscape-klay     # KLay hierarchical
pnpm add cytoscape-cxtmenu  # Context menu extension

Local development with SONNET_UI_LOCAL=1

When resolving @petrarca/sonnet-graph from the local dist (via Vite aliases), the Cytoscape plugins must also be aliased to the consumer's node_modules — Vite cannot find them relative to the dist file. Add to your sonnet-aliases.ts:

const nm = path.resolve(baseDir, "node_modules");
// ...
"cytoscape-fcose": path.resolve(nm, "cytoscape-fcose"),
"cytoscape-cola":  path.resolve(nm, "cytoscape-cola"),
"cytoscape-dagre": path.resolve(nm, "cytoscape-dagre"),
"cytoscape-elk":   path.resolve(nm, "cytoscape-elk"),
"cytoscape-cise":  path.resolve(nm, "cytoscape-cise"),
"cytoscape-klay":  path.resolve(nm, "cytoscape-klay"),
"cytoscape-cxtmenu": path.resolve(nm, "cytoscape-cxtmenu"),

See sonnet-ui-starter/sonnet-aliases.ts for a complete reference implementation.

Basic usage

import {
  GraphVisualizer,
  ActionPanel,
  GraphRendererProvider,
  GraphStoresContext,
  createGraphDataStore,
  createGraphFilterStore,
  createGraphExplorationStore,
  createSelectionStore,
  createGraphFocusStore,
  enrichNodes,
  enrichEdges,
  buildColorPalette,
  type RawGraphNode,
  type RawGraphEdge,
  type WorkspaceStores,
} from "@petrarca/sonnet-graph";

// Create stores once (e.g. in a context provider)
const stores: WorkspaceStores = {
  graphData:        createGraphDataStore(),
  graphFilter:      createGraphFilterStore(),
  graphExploration: createGraphExplorationStore(),
  selection:        createSelectionStore(),
  graphFocus:       createGraphFocusStore(),
};

// Render
function MyGraph() {
  return (
    <GraphStoresContext.Provider value={stores}>
      <GraphRendererProvider defaultRenderer="cytoscape">
        <div style={{ display: "flex", height: 600 }}>
          <GraphVisualizer />
          <ActionPanel />
        </div>
      </GraphRendererProvider>
    </GraphStoresContext.Provider>
  );
}

License

See LICENSE.md.