@graph-render/react 1.0.1

package/src/hooks/useStableConfig.ts

@@ -0,0 +1,108 @@
+import { useRef } from 'react';
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> => {
+  return Object.prototype.toString.call(value) === '[object Object]';
+};
+
+const areValuesEqual = (
+  left: unknown,
+  right: unknown,
+  seen: WeakMap<object, WeakSet<object>>
+): boolean => {
+  if (Object.is(left, right)) {
+    return true;
+  }
+
+  if (typeof left === 'function' || typeof right === 'function') {
+    return false;
+  }
+
+  if (!left || !right || typeof left !== 'object' || typeof right !== 'object') {
+    return false;
+  }
+
+  const existing = seen.get(left);
+  if (existing?.has(right)) {
+    return true;
+  }
+
+  if (Array.isArray(left) || Array.isArray(right)) {
+    if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length) {
+      return false;
+    }
+
+    if (!existing) {
+      seen.set(left, new WeakSet([right]));
+    } else {
+      existing.add(right);
+    }
+
+    for (let index = 0; index < left.length; index += 1) {
+      if (!areValuesEqual(left[index], right[index], seen)) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  if (!isPlainObject(left) || !isPlainObject(right)) {
+    return false;
+  }
+
+  if (!existing) {
+    seen.set(left, new WeakSet([right]));
+  } else {
+    existing.add(right);
+  }
+
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  if (leftKeys.length !== rightKeys.length) {
+    return false;
+  }
+
+  for (const key of leftKeys) {
+    if (!(key in right) || !areValuesEqual(left[key], right[key], seen)) {
+      return false;
+    }
+  }
+
+  return true;
+};
+
+/**
+ * Returns the same reference for a config-like object as long as its
+ * serialized form has not changed.
+ *
+ * This prevents a common foot-gun where consumers pass an inline object
+ * literal as the `config` prop:
+ *
+ *   <Graph config={{ layout: 'dag' }} ... />
+ *
+ * Without stabilization, every parent render creates a new object reference,
+ * which invalidates the normalizeGraphConfig memo and cascades through the
+ * entire graph model pipeline (layout, edge routing, etc.), causing full
+ * recomputes on every keystroke / scroll / hover in the parent tree.
+ *
+ * `GraphConfig` only contains JSON-serializable values (strings, numbers,
+ * booleans, string arrays, and theme objects with the same), so JSON.stringify
+ * is a reliable, cheap equality check here.
+ *
+ * Note: if `config` contains function-typed fields, those are intentionally
+ * excluded from the comparison (JSON.stringify omits them). Functions should
+ * be passed as separate, memoized props rather than embedded in the config
+ * object.
+ */
+export function useStableConfig<T>(config: T): T {
+  const ref = useRef<T | null>(null);
+
+  if (ref.current === null || !areValuesEqual(ref.current, config, new WeakMap())) {
+    // Writing to a ref during render is safe when the write is idempotent
+    // and deterministic for the same inputs (standard React ref-as-cache
+    // pattern).
+    ref.current = config;
+  }
+
+  return ref.current;
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+export { EdgeType, LayoutType, LayoutDirection, NodeSide } from '@graph-render/types';
+export type {
+  DragState,
+  EdgeComponent,
+  EdgeData,
+  EdgeId,
+  EdgePathProps,
+  EdgeRenderer,
+  EdgeRoutingContext,
+  GraphConfig,
+  GraphControlsPosition,
+  GraphHandle,
+  GraphHoverMeta,
+  GraphProps,
+  GraphRenderContext,
+  GraphSearchResults,
+  GraphSelection,
+  GraphTheme,
+  GraphTopology,
+  GraphViewport,
+  LayoutOptions,
+  NodeData,
+  NodeId,
+  NodeMeasurementHints,
+  NodeRenderer,
+  NodeSizingMode,
+  NxEdgeAttrs,
+  NxGraphInput,
+  NxNodeAttrs,
+  PathHoverOptions,
+  PathTraversalOptions,
+  PathTraversalResult,
+  Point,
+  PositionedEdge,
+  PositionedNode,
+  RenderConfig,
+  RenderGraphToSvgOptions,
+  RenderGraphToSvgResult,
+  RenderTheme,
+  RouteEdgesOptions,
+  Size,
+  TreeMetrics,
+  VertexComponent,
+  VertexComponentProps,
+} from '@graph-render/types';
+export { Graph } from './components/Graph';
+export { EdgePath } from './components/EdgePath';
+export { groupPositionedNodesByColumn } from './utils/columns';
+
+// Re-export core functionality
+export {
+  renderGraphToSvg,
+  layoutNodes,
+  routeEdges,
+  fromNxGraph,
+  buildEdgePath,
+} from '@graph-render/core';

package/src/utils/columns.ts

@@ -0,0 +1,51 @@
+import { PositionedNode } from '@graph-render/types';
+
+const DEFAULT_NODE_WIDTH = 180;
+const DEFAULT_COLUMN_TOLERANCE = 24;
+
+export interface NodeColumn<TNode extends PositionedNode = PositionedNode> {
+  centerX: number;
+  nodes: TNode[];
+}
+
+const getNodeWidth = (node: PositionedNode): number => node.size?.width ?? DEFAULT_NODE_WIDTH;
+
+const getNodeCenterX = (node: PositionedNode): number => node.position.x + getNodeWidth(node) / 2;
+
+export const groupPositionedNodesByColumn = <TNode extends PositionedNode = PositionedNode>(
+  nodes: TNode[],
+  tolerance: number = DEFAULT_COLUMN_TOLERANCE
+): NodeColumn<TNode>[] => {
+  const sortedNodes = [...nodes].sort((left, right) => getNodeCenterX(left) - getNodeCenterX(right));
+  const columns: Array<{ centerX: number; avgWidth: number; nodes: TNode[] }> = [];
+
+  sortedNodes.forEach((node) => {
+    const nodeCenterX = getNodeCenterX(node);
+    const nodeWidth = getNodeWidth(node);
+    const current = columns[columns.length - 1];
+
+    if (!current) {
+      columns.push({ centerX: nodeCenterX, avgWidth: nodeWidth, nodes: [node] });
+      return;
+    }
+
+    const threshold = Math.max(tolerance, Math.min(current.avgWidth, nodeWidth) * 0.35);
+    if (Math.abs(nodeCenterX - current.centerX) > threshold) {
+      columns.push({ centerX: nodeCenterX, avgWidth: nodeWidth, nodes: [node] });
+      return;
+    }
+
+    current.nodes.push(node);
+    // FIX: replaced O(k) reduce-based recompute with an O(1) incremental
+    // running average.  The previous approach re-summed the entire column on
+    // every push, making the full grouping O(n×k) for large graphs.
+    const newCount = current.nodes.length; // length after push
+    current.centerX = (current.centerX * (newCount - 1) + nodeCenterX) / newCount;
+    current.avgWidth = (current.avgWidth * (newCount - 1) + nodeWidth) / newCount;
+  });
+
+  return columns.map((column) => ({
+    centerX: column.centerX,
+    nodes: [...column.nodes].sort((left, right) => left.position.y - right.position.y),
+  }));
+};

package/src/utils/pathHighlight.ts

@@ -0,0 +1,160 @@
+import { EdgeId, PathTraversalResult, PositionedEdge } from '@graph-render/types';
+
+export interface FocusedPath {
+  nodeId: string;
+  sourceIndex: number | null;
+  pathKey?: string;
+}
+
+type NodeWithPathMeta = {
+  id: string;
+  meta?: Record<string, unknown>;
+};
+
+function normalizePathKey(value: string): string {
+  return value.trim().toLowerCase();
+}
+
+export function extractPathKeysFromNodes(nodes: NodeWithPathMeta[]): Map<string, string[]> {
+  const map = new Map<string, string[]>();
+
+  nodes.forEach((node) => {
+    const meta = node.meta;
+    if (!meta) {
+      return;
+    }
+
+    const rawPathKeys = meta.pathKeys;
+
+    // Only read the generic `pathKeys` field. Domain-specific metadata (e.g.
+    // tournament `players`) must be mapped to `pathKeys` by the consuming
+    // package before the graph is passed to Graph — see react-tournament-tree
+    // TournamentBracket for an example.
+    const pathKeys = Array.isArray(rawPathKeys) ? rawPathKeys : [];
+
+    const normalized = pathKeys
+      .map((entry) => {
+        if (typeof entry === 'string') {
+          return entry;
+        }
+
+        if (
+          typeof entry === 'object' &&
+          entry !== null &&
+          'name' in entry &&
+          typeof entry.name === 'string'
+        ) {
+          return entry.name;
+        }
+
+        return null;
+      })
+      .filter((value): value is string => typeof value === 'string')
+      .map((value) => value.trim())
+      .filter((value) => value.length > 0);
+
+    if (normalized.length) {
+      map.set(node.id, normalized);
+    }
+  });
+
+  return map;
+}
+
+export function traverseHighlightedPath(options: {
+  startNodeId: string;
+  sourceIndex?: number | null;
+  pathKey?: string;
+  incomingEdgesByTarget: Map<string, PositionedEdge[]>;
+  pathKeysByNode?: Map<string, string[]>;
+  /**
+   * Hard upper bound on the number of nodes visited. Prevents the traversal
+   * from freezing the UI on dense graphs when neither a pathKey nor a valid
+   * sourceIndex is supplied and the algorithm falls back to following all
+   * incoming edges.
+   *
+   * Defaults to 500.
+   */
+  maxNodes?: number;
+}): PathTraversalResult {
+  const {
+    startNodeId,
+    sourceIndex,
+    pathKey,
+    incomingEdgesByTarget,
+    pathKeysByNode,
+    maxNodes = 500,
+  } = options;
+
+  const nodes = new Set<string>([startNodeId]);
+  const edges = new Set<EdgeId>();
+  // Track which (nodeId, sourceIndex, pathKey) combinations have been pushed
+  // onto the stack so that a node reached via multiple paths is not processed
+  // more than once — preventing exponential fan-out on dense DAGs.
+  const visitedKeys = new Set<string>([`${startNodeId}|${sourceIndex ?? ''}|${pathKey ?? ''}`]);
+  const stack: Array<{ nodeId: string; sourceIndex: number | null; pathKey?: string }> = [
+    { nodeId: startNodeId, sourceIndex: sourceIndex ?? null, pathKey },
+  ];
+
+  while (stack.length) {
+    // Hard cap to prevent blocking the main thread on dense graphs where the
+    // fallback "follow all incoming edges" path would visit the entire graph.
+    if (nodes.size >= maxNodes) {
+      break;
+    }
+
+    const current = stack.pop();
+    if (!current) {
+      continue;
+    }
+
+    const incoming = incomingEdgesByTarget.get(current.nodeId) ?? [];
+    const normalizedKey = current.pathKey ? normalizePathKey(current.pathKey) : null;
+    let chosen: PositionedEdge[] = [];
+
+    if (normalizedKey && pathKeysByNode) {
+      chosen = incoming.filter((edge) => {
+        const keys = pathKeysByNode.get(edge.source) ?? [];
+        return keys.some((candidate) => normalizePathKey(candidate) === normalizedKey);
+      });
+    }
+
+    if (!chosen.length) {
+      if (current.sourceIndex == null) {
+        chosen = incoming;
+      } else if (incoming[current.sourceIndex]) {
+        chosen = [incoming[current.sourceIndex]];
+      }
+    }
+
+    chosen.forEach((edge) => {
+      if (edges.has(edge.id)) {
+        return;
+      }
+
+      edges.add(edge.id);
+      nodes.add(edge.source);
+
+      const sourceKeys = pathKeysByNode?.get(edge.source) ?? [];
+      const nextSourceIndex = normalizedKey
+        ? sourceKeys.findIndex((candidate) => normalizePathKey(candidate) === normalizedKey)
+        : current.sourceIndex;
+      const resolvedSourceIndex =
+        typeof nextSourceIndex === 'number' && nextSourceIndex >= 0
+          ? nextSourceIndex
+          : current.sourceIndex;
+
+      const visitKey = `${edge.source}|${resolvedSourceIndex ?? ''}|${current.pathKey ?? ''}`;
+      if (!visitedKeys.has(visitKey)) {
+        visitedKeys.add(visitKey);
+        stack.push({
+          nodeId: edge.source,
+          sourceIndex: resolvedSourceIndex,
+          pathKey: current.pathKey,
+        });
+      }
+    });
+  }
+
+  return { nodes, edges };
+}

package/src/utils/viewport.ts

@@ -0,0 +1,100 @@
+import { GraphViewport, PositionedNode } from '@graph-render/types';
+
+export interface GraphBounds {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+  width: number;
+  height: number;
+}
+
+const DEFAULT_NODE_WIDTH = 180;
+const DEFAULT_NODE_HEIGHT = 72;
+
+export const clampZoom = (zoom: number, minZoom: number, maxZoom: number): number => {
+  return Math.min(Math.max(zoom, minZoom), maxZoom);
+};
+
+export const getGraphBounds = (nodes: PositionedNode[]): GraphBounds | null => {
+  if (!nodes.length) {
+    return null;
+  }
+
+  const bounds = nodes.reduce<GraphBounds>(
+    (acc, node) => {
+      const width = node.size?.width ?? DEFAULT_NODE_WIDTH;
+      const height = node.size?.height ?? DEFAULT_NODE_HEIGHT;
+      const minX = Math.min(acc.minX, node.position.x);
+      const minY = Math.min(acc.minY, node.position.y);
+      const maxX = Math.max(acc.maxX, node.position.x + width);
+      const maxY = Math.max(acc.maxY, node.position.y + height);
+
+      return {
+        minX,
+        minY,
+        maxX,
+        maxY,
+        width: maxX - minX,
+        height: maxY - minY,
+      };
+    },
+    {
+      minX: Number.POSITIVE_INFINITY,
+      minY: Number.POSITIVE_INFINITY,
+      maxX: Number.NEGATIVE_INFINITY,
+      maxY: Number.NEGATIVE_INFINITY,
+      width: 0,
+      height: 0,
+    }
+  );
+
+  return bounds;
+};
+
+export const getFitViewport = (
+  bounds: GraphBounds | null,
+  width: number,
+  height: number,
+  padding: number,
+  minZoom: number,
+  maxZoom: number
+): GraphViewport => {
+  if (!bounds || width <= 0 || height <= 0) {
+    return { x: 0, y: 0, zoom: 1 };
+  }
+
+  const safeWidth = Math.max(bounds.width, 1);
+  const safeHeight = Math.max(bounds.height, 1);
+  const availableWidth = Math.max(width - padding * 2, 1);
+  const availableHeight = Math.max(height - padding * 2, 1);
+  const zoom = clampZoom(
+    Math.min(availableWidth / safeWidth, availableHeight / safeHeight),
+    minZoom,
+    maxZoom
+  );
+
+  return {
+    x: padding + (availableWidth - safeWidth * zoom) / 2 - bounds.minX * zoom,
+    y: padding + (availableHeight - safeHeight * zoom) / 2 - bounds.minY * zoom,
+    zoom,
+  };
+};
+
+export const centerViewportOnNode = (
+  node: PositionedNode,
+  width: number,
+  height: number,
+  currentZoom: number
+): GraphViewport => {
+  const nodeWidth = node.size?.width ?? DEFAULT_NODE_WIDTH;
+  const nodeHeight = node.size?.height ?? DEFAULT_NODE_HEIGHT;
+  const centerX = node.position.x + nodeWidth / 2;
+  const centerY = node.position.y + nodeHeight / 2;
+
+  return {
+    x: width / 2 - centerX * currentZoom,
+    y: height / 2 - centerY * currentZoom,
+    zoom: currentZoom,
+  };
+};

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.react.json",
+  "compilerOptions": {
+    "composite": true,
+    "outDir": "./dist",
+    "emitDeclarationOnly": false,
+    "allowImportingTsExtensions": false
+  },
+  "include": ["src"],
+  "exclude": ["dist", "node_modules"],
+  "references": [{ "path": "./tsconfig.node.json" }, { "path": "../types" }, { "path": "../core-graph-render" }]
+}

package/tsconfig.node.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "composite": true,
+    "allowSyntheticDefaultImports": true,
+    "types": []
+  },
+  "include": ["vite.config.ts"]
+}

package/vite.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    lib: {
+      entry: './src/index.ts',
+      name: 'ReactGraphRender',
+      formats: ['es'],
+      fileName: () => 'index.js',
+    },
+    rollupOptions: {
+      external: ['react', 'react-dom', '@graph-render/core', '@graph-render/types'],
+    },
+  },
+});