@graph-render/react 1.0.1

package/src/components/GraphLabels.tsx

@@ -0,0 +1,141 @@
+import React from 'react';
+import { PositionedNode, LayoutType, LayoutDirection } from '@graph-render/types';
+import { groupPositionedNodesByColumn } from '../utils/columns';
+
+/**
+ * Canonical dimensions for column-label pills. Exported so that the parent
+ * Graph component can compute label bounds using the same values for fit-view
+ * calculations, eliminating the two-source-of-truth problem.
+ */
+export const LABEL_PILL_MIN_WIDTH = 64;
+export const LABEL_PILL_HEIGHT = 20;
+export const LABEL_PILL_RADIUS = 8;
+const LABEL_PILL_PADDING_X = 12;
+const LABEL_PILL_CHAR_WIDTH = 7;
+const MAX_LABEL_PILL_CHARS = 48;
+
+const LABEL_PILL_FONT_SIZE = 12;
+const LABEL_PILL_FONT_WEIGHT = 700;
+
+export function getLabelPillWidth(label: string): number {
+  const charCount = Math.min(Array.from(label).length, MAX_LABEL_PILL_CHARS);
+  return Math.max(
+    LABEL_PILL_MIN_WIDTH,
+    charCount * LABEL_PILL_CHAR_WIDTH + LABEL_PILL_PADDING_X * 2
+  );
+}
+
+export function getEffectiveGraphLabels(
+  positionedNodes: PositionedNode[],
+  layout: LayoutType,
+  layoutDirection: LayoutDirection,
+  labels?: string[],
+  autoLabels = false
+): { orderedXs: number[]; orderedLabels: string[] } {
+  const columns = groupPositionedNodesByColumn(positionedNodes);
+  const xs = columns.map((column) => column.centerX);
+
+  if (!xs.length) {
+    return { orderedXs: [], orderedLabels: [] };
+  }
+
+  const levelCounts = columns.map((column) => column.nodes.length);
+
+  const inferred = levelCounts.map((count) => {
+    const denom = count * 2;
+    if (denom <= 2) return 'Final';
+    return `1/${denom}`;
+  });
+
+  const effectiveLabels = labels && labels.length ? labels : autoLabels ? inferred : [];
+  const orderedXs =
+    layout === LayoutType.Tree && layoutDirection === LayoutDirection.RTL ? [...xs].reverse() : xs;
+  const orderedLabels =
+    layout === LayoutType.Tree && layoutDirection === LayoutDirection.RTL
+      ? [...effectiveLabels].reverse()
+      : effectiveLabels;
+
+  return { orderedXs, orderedLabels };
+}
+
+export interface GraphLabelsProps {
+  positionedNodes: PositionedNode[];
+  layout: LayoutType;
+  layoutDirection: LayoutDirection;
+  labels?: string[];
+  autoLabels: boolean;
+  labelOffset: number;
+  /** Background fill of the label pill. Defaults to `#eef1f6`. */
+  pillBackground?: string;
+  /** Border stroke of the label pill. Defaults to `#d7dbe3`. */
+  pillBorderColor?: string;
+  /** Text color inside the label pill. Defaults to `#3f434b`. */
+  pillTextColor?: string;
+}
+
+export function GraphLabels({
+  positionedNodes,
+  layout,
+  layoutDirection,
+  labels,
+  autoLabels,
+  labelOffset,
+  pillBackground = '#eef1f6',
+  pillBorderColor = '#d7dbe3',
+  pillTextColor = '#3f434b',
+}: GraphLabelsProps) {
+  const { orderedXs, orderedLabels } = getEffectiveGraphLabels(
+    positionedNodes,
+    layout,
+    layoutDirection,
+    labels,
+    autoLabels
+  );
+
+  if (!orderedXs.length || !orderedLabels.length) return null;
+
+  // FIX: avoid spreading a potentially large array into Math.min, which can
+  // throw a RangeError when the argument count exceeds the JS engine limit.
+  const minY = positionedNodes.reduce(
+    (min, n) => Math.min(min, n.position.y),
+    Number.POSITIVE_INFINITY
+  );
+  const y = minY - labelOffset;
+
+  return (
+    <g aria-label="labels">
+      {orderedXs.map((x, idx) => {
+        const label = orderedLabels[idx] ?? '';
+        const pillWidth = getLabelPillWidth(label);
+        const cx = x;
+
+        return (
+          <g
+            key={`col-${x}`}
+            transform={`translate(${cx - pillWidth / 2}, ${y - LABEL_PILL_HEIGHT + 6})`}
+          >
+            <rect
+              width={pillWidth}
+              height={LABEL_PILL_HEIGHT}
+              rx={LABEL_PILL_RADIUS}
+              ry={LABEL_PILL_RADIUS}
+              fill={pillBackground}
+              stroke={pillBorderColor}
+              strokeWidth={1}
+            />
+            <text
+              x={pillWidth / 2}
+              y={LABEL_PILL_HEIGHT / 2 + 4}
+              fill={pillTextColor}
+              fontSize={LABEL_PILL_FONT_SIZE}
+              fontWeight={LABEL_PILL_FONT_WEIGHT}
+              textAnchor="middle"
+            >
+              {label}
+            </text>
+          </g>
+        );
+      })}
+    </g>
+  );
+}

package/src/components/GraphNode.tsx

@@ -0,0 +1,214 @@
+import React, { useEffect, useLayoutEffect, useRef } from 'react';
+import { PositionedNode, Size, VertexComponent } from '@graph-render/types';
+
+const useIsomorphicLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect;
+
+interface GraphNodeProps {
+  node: PositionedNode;
+  Vertex: VertexComponent;
+  isSelected: boolean;
+  isFocused: boolean;
+  isHighlighted: boolean;
+  activePathKey?: string;
+  activePathNodeIds?: Set<string>;
+  highlightColor: string;
+  selectionColor: string;
+  nodeBorderColor?: string;
+  nodeBorderWidth: number;
+  hoverNodeBorderColor: string;
+  hoverNodeBothColor: string;
+  hoverNodeInColor: string;
+  hoverNodeOutColor: string;
+  hoverNodeHighlight: boolean;
+  hoveredNodeStates: Map<string, { in?: boolean; out?: boolean }> | undefined;
+  onNodeMeasure?: (nodeId: string, size: Size) => void;
+  onNodeFocus?: (nodeId: string) => void;
+  onNodeClick?: (node: PositionedNode) => void;
+  onNodeDoubleClick?: (node: PositionedNode) => void;
+  onNodeMouseEnter: (nodeId: string) => void;
+  onNodeMouseLeave: () => void;
+  onPathHover: (nodeId: string, sourceIndex: number, playerKey?: string) => void;
+  onPathLeave: () => void;
+}
+
+export const GraphNode = React.memo<GraphNodeProps>(
+  ({
+    node,
+    Vertex,
+    isSelected,
+    isFocused,
+    selectionColor,
+    isHighlighted,
+    activePathKey,
+    activePathNodeIds,
+    highlightColor,
+    nodeBorderColor,
+    nodeBorderWidth,
+    hoverNodeBorderColor,
+    hoverNodeBothColor,
+    hoverNodeInColor,
+    hoverNodeOutColor,
+    hoverNodeHighlight,
+    hoveredNodeStates,
+    onNodeMeasure,
+    onNodeFocus,
+    onNodeClick,
+    onNodeDoubleClick,
+    onNodeMouseEnter,
+    onNodeMouseLeave,
+    onPathHover,
+    onPathLeave,
+  }) => {
+    const groupRef = useRef<SVGGElement>(null);
+    const width = node.size?.width ?? 180;
+    const height = node.size?.height ?? 72;
+    const radius = 8;
+    const hoverState = hoveredNodeStates?.get(node.id);
+    const isHoveredIn = hoverState?.in ?? false;
+    const isHoveredOut = hoverState?.out ?? false;
+    const isHoveredBoth = isHoveredIn && isHoveredOut;
+    const isHoveredNode = isHoveredIn || isHoveredOut;
+    const hasBorder = (!!nodeBorderColor && nodeBorderWidth > 0) || isSelected;
+
+    let borderStroke = nodeBorderColor;
+    if (isSelected) {
+      borderStroke = selectionColor;
+    } else if (isHighlighted) {
+      borderStroke = highlightColor;
+    } else if (!hasBorder) {
+      borderStroke = 'none';
+    } else if (hoverNodeHighlight) {
+      if (isHoveredBoth) {
+        borderStroke = hoverNodeBothColor;
+      } else if (isHoveredOut) {
+        borderStroke = hoverNodeOutColor;
+      } else if (isHoveredIn) {
+        borderStroke = hoverNodeInColor;
+      } else if (isHoveredNode) {
+        borderStroke = hoverNodeBorderColor;
+      }
+    }
+
+    let borderOpacity = 0;
+    if (isSelected || isHighlighted) {
+      borderOpacity = 1;
+    } else if (hasBorder) {
+      borderOpacity = hoverNodeHighlight && isHoveredNode ? 1 : 0.4;
+    }
+
+    useIsomorphicLayoutEffect(() => {
+      if (!groupRef.current || !onNodeMeasure) {
+        return;
+      }
+
+      const reportFallbackSize = () => {
+        if (width > 0 && height > 0) {
+          onNodeMeasure(node.id, { width: Math.ceil(width), height: Math.ceil(height) });
+        }
+      };
+
+      const frame = requestAnimationFrame(() => {
+        try {
+          if (typeof groupRef.current?.getBBox !== 'function') {
+            reportFallbackSize();
+            return;
+          }
+
+          const bounds = groupRef.current?.getBBox();
+          if (bounds && bounds.width > 0 && bounds.height > 0) {
+            onNodeMeasure(node.id, {
+              width: Math.ceil(bounds.width),
+              height: Math.ceil(bounds.height),
+            });
+            return;
+          }
+        } catch {
+          reportFallbackSize();
+        }
+
+        reportFallbackSize();
+      });
+
+      return () => cancelAnimationFrame(frame);
+    }, [node.id, node.label, node.meta, onNodeMeasure, width, height]);
+
+    const borderWidth =
+      isSelected || isHighlighted ? Math.max(2, nodeBorderWidth) : hasBorder ? nodeBorderWidth : 0;
+    const focusStrokeWidth = isFocused ? Math.max(2, borderWidth || 2) : 0;
+
+    return (
+      <g
+        ref={groupRef}
+        transform={`translate(${node.position.x}, ${node.position.y})`}
+        data-graph-node-interactive="true"
+        role="button"
+        tabIndex={0}
+        aria-selected={isSelected}
+        onMouseDown={(event) => {
+          event.preventDefault();
+        }}
+        onFocus={() => onNodeFocus?.(node.id)}
+        onClick={() => onNodeClick?.(node)}
+        onDoubleClick={() => onNodeDoubleClick?.(node)}
+        onMouseEnter={() => onNodeMouseEnter(node.id)}
+        onMouseLeave={onNodeMouseLeave}
+        onKeyDown={(event) => {
+          if (event.key === 'Enter' || event.key === ' ') {
+            event.preventDefault();
+            onNodeClick?.(node);
+          }
+        }}
+      >
+        <rect
+          x={0}
+          y={0}
+          width={width}
+          height={height}
+          rx={radius}
+          ry={radius}
+          fill="none"
+          stroke={borderStroke}
+          strokeOpacity={borderOpacity}
+          strokeWidth={borderWidth}
+          pointerEvents="none"
+        />
+        {isFocused ? (
+          <rect
+            x={-3}
+            y={-3}
+            width={width + 6}
+            height={height + 6}
+            rx={radius + 2}
+            ry={radius + 2}
+            fill="none"
+            stroke={selectionColor}
+            strokeOpacity={0.7}
+            strokeWidth={focusStrokeWidth}
+            strokeDasharray="4 3"
+            pointerEvents="none"
+          />
+        ) : null}
+        <Vertex
+          node={node}
+          isSelected={isSelected}
+          isHovered={isHoveredNode}
+          isHoveredIn={isHoveredIn}
+          isHoveredOut={isHoveredOut}
+          isHoveredBoth={isHoveredBoth}
+          activePathKey={activePathKey}
+          activePathNodeIds={activePathNodeIds}
+          hoverInColor={hoverNodeInColor}
+          hoverOutColor={hoverNodeOutColor}
+          hoverBothColor={hoverNodeBothColor}
+          onPathHover={(sourceIndex, opts) =>
+            sourceIndex !== null &&
+            onPathHover(node.id, sourceIndex, opts?.pathKey ?? opts?.playerKey)
+          }
+          onPathLeave={onPathLeave}
+        />
+      </g>
+    );
+  }
+);
+
+GraphNode.displayName = 'GraphNode';

package/src/constants/defaults.ts

@@ -0,0 +1,62 @@
+import { EdgeType, GraphConfig, LayoutDirection, LayoutType } from '@graph-render/types';
+
+// These three fields are intentionally absent from the default object
+// (their undefined values let consumers override them selectively).
+// Using Partial<Pick<...>> makes that intent explicit: the type says
+// "these may or may not be set" so TypeScript won't complain about them
+// being missing from the object literal below.
+export const DEFAULT_CONFIG: Required<
+  Pick<
+    GraphConfig,
+    | 'width'
+    | 'height'
+    | 'defaultEdgeType'
+    | 'curveEdges'
+    | 'curveStrength'
+    | 'arrowPadding'
+    | 'routingStyle'
+    | 'edgeSeparation'
+    | 'selfLoopRadius'
+    | 'layout'
+    | 'layoutDirection'
+    | 'autoLabels'
+    | 'labelOffset'
+    | 'nodeSizing'
+    | 'labelMeasurementPaddingX'
+    | 'labelMeasurementPaddingY'
+    | 'labelMeasurementCharWidth'
+    | 'labelMeasurementLineHeight'
+    | 'hoverHighlight'
+    | 'hoverEdgeColor'
+    | 'hoverNodeInColor'
+    | 'hoverNodeOutColor'
+    | 'hoverNodeHighlight'
+    | 'edgeLabelColor'
+  >
+> &
+  Partial<Pick<GraphConfig, 'hoverNodeBorderColor' | 'hoverNodeBothColor' | 'forceRightToLeft'>> = {
+  width: 960,
+  height: 720,
+  defaultEdgeType: EdgeType.Directed,
+  curveEdges: true,
+  curveStrength: 0.3,
+  arrowPadding: 6,
+  routingStyle: 'smart',
+  edgeSeparation: 18,
+  selfLoopRadius: 32,
+  layout: LayoutType.Centered,
+  layoutDirection: LayoutDirection.LTR,
+  autoLabels: false,
+  labelOffset: 32,
+  nodeSizing: 'fixed',
+  labelMeasurementPaddingX: 18,
+  labelMeasurementPaddingY: 12,
+  labelMeasurementCharWidth: 8,
+  labelMeasurementLineHeight: 18,
+  hoverHighlight: true,
+  hoverEdgeColor: '#4da3ff',
+  edgeLabelColor: '#334155',
+  hoverNodeInColor: '#2ecc71',
+  hoverNodeOutColor: '#ff5b5b',
+  hoverNodeHighlight: true,
+};

package/src/hooks/useGraphCollapse.ts

@@ -0,0 +1,53 @@
+import { useCallback, useMemo, useState } from 'react';
+
+interface UseGraphCollapseOptions {
+  collapsedNodeIds?: string[];
+  defaultCollapsedNodeIds?: string[];
+  onCollapsedNodeIdsChange?: (nodeIds: string[]) => void;
+}
+
+interface UseGraphCollapseResult {
+  collapsedIds: string[];
+  collapsedNodeSet: Set<string>;
+  pendingExpansionNodeSet: Set<string>;
+  updateCollapsedNodeIds: (next: string[] | ((current: string[]) => string[])) => void;
+  setPendingExpansionNodeIds: React.Dispatch<React.SetStateAction<string[]>>;
+}
+
+export const useGraphCollapse = ({
+  collapsedNodeIds,
+  defaultCollapsedNodeIds,
+  onCollapsedNodeIdsChange,
+}: UseGraphCollapseOptions): UseGraphCollapseResult => {
+  const [internalCollapsedNodeIds, setInternalCollapsedNodeIds] = useState<string[]>(
+    defaultCollapsedNodeIds ?? []
+  );
+  const [pendingExpansionNodeIds, setPendingExpansionNodeIds] = useState<string[]>([]);
+
+  const collapsedIds = collapsedNodeIds ?? internalCollapsedNodeIds;
+  const collapsedNodeSet = useMemo(() => new Set(collapsedIds), [collapsedIds]);
+  const pendingExpansionNodeSet = useMemo(
+    () => new Set(pendingExpansionNodeIds),
+    [pendingExpansionNodeIds]
+  );
+
+  const updateCollapsedNodeIds = useCallback(
+    (next: string[] | ((current: string[]) => string[])) => {
+      const current = collapsedIds;
+      const resolved = typeof next === 'function' ? next(current) : next;
+      if (collapsedNodeIds == null) {
+        setInternalCollapsedNodeIds(resolved);
+      }
+      onCollapsedNodeIdsChange?.(resolved);
+    },
+    [collapsedIds, collapsedNodeIds, onCollapsedNodeIdsChange]
+  );
+
+  return {
+    collapsedIds,
+    collapsedNodeSet,
+    pendingExpansionNodeSet,
+    updateCollapsedNodeIds,
+    setPendingExpansionNodeIds,
+  };
+};

package/src/hooks/useGraphHover.ts

@@ -0,0 +1,206 @@
+import { useMemo, useState } from 'react';
+import { PositionedEdge, EdgeId } from '@graph-render/types';
+import { groupEdgesByTarget, sortEdgesBySourcePosition } from '@graph-render/core';
+import {
+  extractPathKeysFromNodes,
+  FocusedPath,
+  traverseHighlightedPath,
+} from '../utils/pathHighlight';
+
+export function useGraphHover(
+  positionedNodes: Array<{
+    id: string;
+    position: { x: number; y: number };
+    meta?: Record<string, unknown>;
+  }>,
+  positionedEdges: PositionedEdge[],
+  hoverHighlight: boolean
+) {
+  const [hoveredEdgeId, setHoveredEdgeId] = useState<EdgeId | null>(null);
+  const [hoveredNodeId, setHoveredNodeId] = useState<string | null>(null);
+  const [focusedPath, setFocusedPath] = useState<FocusedPath | null>(null);
+  const edgeById = useMemo(
+    () => new Map(positionedEdges.map((edge) => [edge.id, edge])),
+    [positionedEdges]
+  );
+  const edgesByNodeId = useMemo(() => {
+    const map = new Map<string, PositionedEdge[]>();
+
+    positionedEdges.forEach((edge) => {
+      map.set(edge.source, [...(map.get(edge.source) ?? []), edge]);
+      if (edge.target !== edge.source) {
+        map.set(edge.target, [...(map.get(edge.target) ?? []), edge]);
+      }
+    });
+
+    return map;
+  }, [positionedEdges]);
+
+  const nodePos = useMemo(() => {
+    const m = new Map<string, { x: number; y: number }>();
+    positionedNodes.forEach((n) => m.set(n.id, n.position));
+    return m;
+  }, [positionedNodes]);
+
+  const pathKeysByNode = useMemo(
+    () => extractPathKeysFromNodes(positionedNodes),
+    [positionedNodes]
+  );
+
+  const incomingEdgesByTarget = useMemo(() => {
+    const map = groupEdgesByTarget(positionedEdges);
+    map.forEach((edges, targetId) => {
+      map.set(targetId, sortEdgesBySourcePosition(edges, nodePos));
+    });
+    return map;
+  }, [positionedEdges, nodePos]);
+
+  const pathHighlight = useMemo(() => {
+    if (!focusedPath) return null;
+
+    return traverseHighlightedPath({
+      startNodeId: focusedPath.nodeId,
+      sourceIndex: focusedPath.sourceIndex,
+      pathKey: focusedPath.pathKey,
+      incomingEdgesByTarget,
+      pathKeysByNode,
+    });
+  }, [focusedPath, incomingEdgesByTarget, pathKeysByNode]);
+
+  const hoveredNodeStates = useMemo(() => {
+    if (!hoverHighlight && !pathHighlight) return null;
+
+    const map = new Map<string, { in: boolean; out: boolean }>();
+
+    const applyPath = () => {
+      if (pathHighlight) {
+        pathHighlight.nodes.forEach((id) => {
+          const curr = map.get(id) ?? { in: false, out: false };
+          map.set(id, { ...curr, in: true, out: true });
+        });
+      }
+    };
+
+    if (focusedPath) {
+      applyPath();
+    } else {
+      if (hoverHighlight) {
+        if (hoveredEdgeId) {
+          const match = edgeById.get(hoveredEdgeId);
+          if (match) {
+            const add = (id: string, dir: 'in' | 'out') => {
+              const curr = map.get(id) ?? { in: false, out: false };
+              map.set(id, { ...curr, [dir]: true });
+            };
+            if (match.type === 'undirected') {
+              add(match.source, 'in');
+              add(match.source, 'out');
+              add(match.target, 'in');
+              add(match.target, 'out');
+            } else {
+              // For a directed edge A→B the source is the origin (out only)
+              // and the target is the destination (in only).
+              add(match.source, 'out');
+              add(match.target, 'in');
+            }
+          }
+        } else if (hoveredNodeId) {
+          const add = (id: string, dir: 'in' | 'out') => {
+            const curr = map.get(id) ?? { in: false, out: false };
+            map.set(id, { ...curr, [dir]: true });
+          };
+          (edgesByNodeId.get(hoveredNodeId) ?? []).forEach((e) => {
+            const isUndir = e.type === 'undirected';
+            if (e.source === hoveredNodeId) {
+              if (isUndir) {
+                add(e.source, 'in');
+                add(e.source, 'out');
+                add(e.target, 'in');
+                add(e.target, 'out');
+              } else {
+                add(e.source, 'out');
+                add(e.target, 'in');
+              }
+            } else if (e.target === hoveredNodeId) {
+              if (isUndir) {
+                add(e.source, 'in');
+                add(e.source, 'out');
+                add(e.target, 'in');
+                add(e.target, 'out');
+              } else {
+                add(e.source, 'out');
+                add(e.target, 'in');
+              }
+            }
+          });
+          add(hoveredNodeId, 'in');
+          add(hoveredNodeId, 'out');
+        }
+      }
+      applyPath();
+    }
+
+    return map.size ? map : null;
+  }, [
+    edgeById,
+    edgesByNodeId,
+    hoverHighlight,
+    hoveredEdgeId,
+    hoveredNodeId,
+    pathHighlight,
+    focusedPath,
+  ]);
+
+  const edgesForRender = useMemo(() => {
+    const highlightIds = new Set<string>();
+
+    if (focusedPath && pathHighlight) {
+      pathHighlight.edges.forEach((id) => highlightIds.add(id));
+    } else {
+      if (hoverHighlight) {
+        if (hoveredEdgeId) {
+          highlightIds.add(hoveredEdgeId);
+        } else if (hoveredNodeId) {
+          (edgesByNodeId.get(hoveredNodeId) ?? []).forEach((e) => {
+            if (e.source === hoveredNodeId || e.target === hoveredNodeId) {
+              highlightIds.add(e.id);
+            }
+          });
+        }
+      }
+      if (pathHighlight) {
+        pathHighlight.edges.forEach((id) => highlightIds.add(id));
+      }
+    }
+
+    if (!highlightIds.size) return positionedEdges;
+
+    const front: PositionedEdge[] = [];
+    const back: PositionedEdge[] = [];
+    positionedEdges.forEach((e) => {
+      if (highlightIds.has(e.id)) front.push(e);
+      else back.push(e);
+    });
+    return [...back, ...front];
+  }, [
+    edgesByNodeId,
+    hoverHighlight,
+    hoveredEdgeId,
+    hoveredNodeId,
+    positionedEdges,
+    pathHighlight,
+    focusedPath,
+  ]);
+
+  return {
+    hoveredEdgeId,
+    setHoveredEdgeId,
+    hoveredNodeId,
+    setHoveredNodeId,
+    focusedPath,
+    setFocusedPath,
+    pathHighlight,
+    hoveredNodeStates,
+    edgesForRender,
+  };
+}