@graph-render/core 1.0.1

package/src/layouts/tree.ts

@@ -0,0 +1,35 @@
+import { NodeData, EdgeData, PositionedNode, LayoutDirection } from '@graph-render/types';
+import { DEFAULT_PADDING, DEFAULT_NODE_GAP } from '../utils';
+import {
+  assertHierarchicalGraph,
+  buildGraphTopology,
+  findRootNodes,
+  assignNodesToLevels,
+  groupNodesByLevel,
+} from './treeTopology';
+import { calculateTreeMetrics } from './treePositioning';
+import { positionNodesInLevels, alignNodesToParents } from './treeAlignment';
+
+/**
+ * Layout nodes in a tree/hierarchical structure
+ */
+export const treeLayout = (
+  nodes: NodeData[],
+  edges: EdgeData[],
+  pad: number = DEFAULT_PADDING,
+  gap: number = DEFAULT_NODE_GAP,
+  direction: LayoutDirection = LayoutDirection.LTR,
+  containerHeight?: number
+): PositionedNode[] => {
+  assertHierarchicalGraph(nodes, edges);
+
+  const { incoming, outgoing } = buildGraphTopology(edges);
+  const rootIds = findRootNodes(nodes, incoming);
+  const levelMap = assignNodesToLevels(nodes, rootIds, outgoing);
+  const levels = groupNodesByLevel(nodes, levelMap);
+  const metrics = calculateTreeMetrics(nodes, levels, gap, pad, containerHeight);
+
+  const positioned = positionNodesInLevels(nodes, levels, levelMap, metrics, gap, pad, direction);
+
+  return alignNodesToParents(positioned, edges, levels, metrics.maxLevel);
+};

package/src/layouts/treeAlignment.ts

@@ -0,0 +1,107 @@
+import {
+  NodeData,
+  EdgeData,
+  PositionedNode,
+  TreeMetrics,
+  LayoutDirection,
+} from '@graph-render/types';
+import { DEFAULT_NODE_SIZE } from '../utils';
+import { calculateXPosition, calculateYPosition } from './treePositioning';
+
+/**
+ * Position all nodes initially based on their level
+ */
+export const positionNodesInLevels = (
+  nodes: NodeData[],
+  levels: string[][],
+  levelMap: Map<string, number>,
+  metrics: TreeMetrics,
+  gap: number,
+  padding: number,
+  direction: LayoutDirection
+): PositionedNode[] => {
+  return nodes.map((node) => {
+    if (node.position) return node as PositionedNode;
+
+    const level = levelMap.get(node.id) ?? 0;
+    const levelNodes = levels[level] ?? [];
+    const idx = levelNodes.indexOf(node.id);
+    const nodeWidth = node.size?.width ?? DEFAULT_NODE_SIZE.width;
+
+    const x = calculateXPosition(level, metrics.maxLevel, nodeWidth, gap, padding, direction);
+    const y = calculateYPosition(
+      idx,
+      levelNodes,
+      metrics.maxNodeHeight,
+      gap,
+      metrics.totalHeight,
+      metrics.baseY
+    );
+
+    return { ...node, position: { x, y } } as PositionedNode;
+  });
+};
+
+// FIX: deleted the file-private `getParentNodes` helper.  It was replaced by
+// the `incomingByTarget` Map built inside `alignNodesToParents` (O(n+e) vs the
+// previous O(n×e)) and was never exported, so no external callers exist.
+
+/**
+ * Calculate average Y center of parent nodes
+ */
+const calculateParentCentersAverage = (
+  parentIds: string[],
+  posMap: Map<string, PositionedNode>
+): number | null => {
+  const centers = parentIds
+    .map((src) => posMap.get(src))
+    .filter((n): n is PositionedNode => !!n)
+    .map((n) => n.position.y + (n.size?.height ?? DEFAULT_NODE_SIZE.height) / 2);
+
+  if (!centers.length) return null;
+  return centers.reduce((a, b) => a + b, 0) / centers.length;
+};
+
+/**
+ * Align nodes with multiple parents to their parent's average position
+ */
+export const alignNodesToParents = (
+  positioned: PositionedNode[],
+  edges: EdgeData[],
+  levels: string[][],
+  maxLevel: number
+): PositionedNode[] => {
+  const posMap = new Map<string, PositionedNode>();
+  positioned.forEach((n) => posMap.set(n.id, n));
+
+  // FIX: build a target→sources index once instead of calling
+  // edges.filter(e => e.target === id) for every node (was O(nodes × edges)).
+  const incomingByTarget = new Map<string, string[]>();
+  edges.forEach((e) => {
+    incomingByTarget.set(e.target, [...(incomingByTarget.get(e.target) ?? []), e.source]);
+  });
+
+  for (let level = 1; level <= maxLevel; level += 1) {
+    const ids = levels[level] ?? [];
+    ids.forEach((id) => {
+      const node = posMap.get(id);
+      if (!node) return;
+
+      const parentIds = incomingByTarget.get(id) ?? [];
+      if (parentIds.length < 2) return;
+
+      const avgCenterY = calculateParentCentersAverage(parentIds, posMap);
+      if (avgCenterY === null) return;
+
+      const h = node.size?.height ?? DEFAULT_NODE_SIZE.height;
+      const newY = avgCenterY - h / 2;
+      const updated = {
+        ...node,
+        position: { ...node.position, y: newY },
+      } as PositionedNode;
+      posMap.set(id, updated);
+    });
+  }
+
+  return Array.from(posMap.values());
+};

package/src/layouts/treePositioning.ts

@@ -0,0 +1,55 @@
+import { NodeData, TreeMetrics, LayoutDirection } from '@graph-render/types';
+import { getMaxNodeHeight } from '../utils';
+
+/**
+ * Calculate tree layout metrics
+ */
+export const calculateTreeMetrics = (
+  nodes: NodeData[],
+  levels: string[][],
+  gap: number,
+  padding: number,
+  containerHeight?: number
+): TreeMetrics => {
+  const maxLevel = levels.length ? levels.length - 1 : 0;
+  const maxNodeHeight = getMaxNodeHeight(nodes);
+  const maxLevelCount = Math.max(1, ...levels.map((l) => l?.length ?? 0));
+  const totalHeight = maxLevelCount * maxNodeHeight + (maxLevelCount - 1) * gap;
+  const baseY =
+    containerHeight != null ? Math.max(padding, (containerHeight - totalHeight) / 2) : padding;
+
+  return { maxLevel, maxNodeHeight, maxLevelCount, totalHeight, baseY };
+};
+
+/**
+ * Calculate X position based on level and direction
+ */
+export const calculateXPosition = (
+  level: number,
+  maxLevel: number,
+  nodeWidth: number,
+  gap: number,
+  padding: number,
+  direction: LayoutDirection
+): number => {
+  const ltrX = padding + level * (nodeWidth + gap);
+  const rtlX = padding + (maxLevel - level) * (nodeWidth + gap);
+  return direction === LayoutDirection.RTL ? rtlX : ltrX;
+};
+
+/**
+ * Calculate Y position for a node in a level
+ */
+export const calculateYPosition = (
+  nodeIndex: number,
+  levelNodes: string[],
+  maxNodeHeight: number,
+  gap: number,
+  totalHeight: number,
+  baseY: number
+): number => {
+  const levelHeight =
+    (levelNodes.length || 1) * maxNodeHeight + Math.max(0, (levelNodes.length || 1) - 1) * gap;
+  const levelStartY = baseY + (totalHeight - levelHeight) / 2;
+  return levelStartY + nodeIndex * (maxNodeHeight + gap);
+};

package/src/layouts/treeTopology.ts

@@ -0,0 +1,184 @@
+import { NodeData, EdgeData, GraphTopology } from '@graph-render/types';
+
+export const assertHierarchicalGraph = (nodes: NodeData[], edges: EdgeData[]): void => {
+  if (!nodes.length) {
+    return;
+  }
+
+  const inDegree = new Map(nodes.map((node) => [node.id, 0]));
+  const outgoing = new Map<string, string[]>();
+
+  for (const edge of edges) {
+    if (!inDegree.has(edge.source) || !inDegree.has(edge.target)) {
+      throw new Error(
+        `Tree layout requires every edge to reference existing nodes. Invalid edge: ${edge.source} -> ${edge.target}.`
+      );
+    }
+
+    inDegree.set(edge.target, (inDegree.get(edge.target) ?? 0) + 1);
+    outgoing.set(edge.source, [...(outgoing.get(edge.source) ?? []), edge.target]);
+  }
+
+  const queue = Array.from(inDegree.entries())
+    .filter(([, degree]) => degree === 0)
+    .map(([nodeId]) => nodeId);
+
+  if (!queue.length) {
+    throw new Error(
+      'Tree layout requires at least one root node and does not support cyclic graphs.'
+    );
+  }
+
+  let processed = 0;
+  for (let index = 0; index < queue.length; index += 1) {
+    const current = queue[index];
+    processed += 1;
+
+    for (const child of outgoing.get(current) ?? []) {
+      const nextDegree = (inDegree.get(child) ?? 0) - 1;
+      inDegree.set(child, nextDegree);
+      if (nextDegree === 0) {
+        queue.push(child);
+      }
+    }
+  }
+
+  if (processed !== nodes.length) {
+    throw new Error(
+      'Tree layout requires an acyclic graph. Cycles were detected in the input graph.'
+    );
+  }
+};
+
+/**
+ * Build graph topology from edges
+ */
+export const buildGraphTopology = (edges: EdgeData[]): GraphTopology => {
+  const incoming = new Map<string, number>();
+  const outgoing = new Map<string, string[]>();
+
+  edges.forEach((e) => {
+    incoming.set(e.target, (incoming.get(e.target) ?? 0) + 1);
+    outgoing.set(e.source, [...(outgoing.get(e.source) ?? []), e.target]);
+  });
+
+  return { incoming, outgoing };
+};
+
+/**
+ * Find root nodes (nodes with no incoming edges)
+ */
+export const findRootNodes = (nodes: NodeData[], incoming: Map<string, number>): string[] => {
+  const roots = nodes.filter((n) => (incoming.get(n.id) ?? 0) === 0);
+  return roots.map((r) => r.id);
+};
+
+/**
+ * Assign nodes to levels using BFS
+ */
+export const assignNodesToLevels = (
+  nodes: NodeData[],
+  rootIds: string[],
+  outgoing: Map<string, string[]>
+): Map<string, number> => {
+  const levelMap = new Map<string, number>();
+  const queue = [...rootIds];
+  rootIds.forEach((id) => levelMap.set(id, 0));
+
+  for (let index = 0; index < queue.length; index += 1) {
+    const current = queue[index];
+    const level = levelMap.get(current) ?? 0;
+    for (const child of outgoing.get(current) ?? []) {
+      if (!levelMap.has(child)) {
+        levelMap.set(child, level + 1);
+        queue.push(child);
+      }
+    }
+  }
+
+  return levelMap;
+};
+
+/**
+ * Assign DAG-style max-depth levels using a single Kahn's BFS pass.
+ * Validates edge references and detects cycles in the same traversal,
+ * replacing the three-pass pattern of assertHierarchicalGraph +
+ * buildGraphTopology + an inline BFS.
+ */
+export const assignDagLevels = (
+  nodes: NodeData[],
+  edges: EdgeData[]
+): { levels: Map<string, number>; outgoing: Map<string, string[]> } => {
+  if (!nodes.length) {
+    return { levels: new Map(), outgoing: new Map() };
+  }
+
+  const nodeSet = new Set(nodes.map((n) => n.id));
+  const inDegree = new Map<string, number>(nodes.map((n) => [n.id, 0]));
+  const outgoing = new Map<string, string[]>();
+
+  for (const edge of edges) {
+    if (!nodeSet.has(edge.source) || !nodeSet.has(edge.target)) {
+      throw new Error(
+        `DAG layout requires every edge to reference existing nodes. Invalid edge: ${edge.source} -> ${edge.target}.`
+      );
+    }
+    inDegree.set(edge.target, (inDegree.get(edge.target) ?? 0) + 1);
+    const children = outgoing.get(edge.source) ?? [];
+    children.push(edge.target);
+    outgoing.set(edge.source, children);
+  }
+
+  const levels = new Map<string, number>();
+  const queue = nodes.filter((n) => inDegree.get(n.id) === 0).map((n) => n.id);
+
+  if (!queue.length) {
+    throw new Error(
+      'DAG layout requires at least one root node and does not support cyclic graphs.'
+    );
+  }
+
+  queue.forEach((id) => levels.set(id, 0));
+  let processed = 0;
+
+  for (let index = 0; index < queue.length; index += 1) {
+    const current = queue[index];
+    processed += 1;
+    const currentLevel = levels.get(current) ?? 0;
+
+    for (const child of outgoing.get(current) ?? []) {
+      levels.set(child, Math.max(levels.get(child) ?? 0, currentLevel + 1));
+      const nextInDegree = (inDegree.get(child) ?? 0) - 1;
+      inDegree.set(child, nextInDegree);
+      if (nextInDegree === 0) {
+        queue.push(child);
+      }
+    }
+  }
+
+  if (processed !== nodes.length) {
+    throw new Error(
+      'DAG layout requires an acyclic graph. Cycles were detected in the input graph.'
+    );
+  }
+
+  return { levels, outgoing };
+};
+
+/**
+ * Group nodes by their level
+ */
+export const groupNodesByLevel = (nodes: NodeData[], levelMap: Map<string, number>): string[][] => {
+  const levels: string[][] = [];
+  nodes.forEach((n) => {
+    const l = levelMap.get(n.id);
+    if (l == null) {
+      throw new Error(
+        `Tree layout could not assign a level to node "${n.id}". Ensure the graph is connected from at least one root and acyclic.`
+      );
+    }
+    if (!levels[l]) levels[l] = [];
+    levels[l].push(n.id);
+  });
+  return levels;
+};

package/src/rendering/defaultRenderers.ts

@@ -0,0 +1,110 @@
+import { PositionedNode, EdgeType } from '@graph-render/types';
+import type { NodeRenderer, EdgeRenderer } from '@graph-render/types';
+import { escapeXml } from './utils';
+import {
+  DEFAULT_NODE_WIDTH,
+  DEFAULT_NODE_HEIGHT,
+  DEFAULT_NODE_RADIUS,
+  DEFAULT_NODE_FILL,
+  DEFAULT_NODE_STROKE,
+  DEFAULT_TEXT_FILL,
+  DEFAULT_TEXT_SIZE,
+} from '../utils';
+
+const MAX_RENDER_LABEL_LENGTH = 2_000;
+const MAX_RENDER_LABEL_LINES = 8;
+
+/**
+ * Extract label from node data
+ */
+const getNodeLabel = (node: PositionedNode): string => {
+  if (typeof node.label === 'string' || typeof node.label === 'number') {
+    return String(node.label);
+  }
+  return node.id;
+};
+
+const getRenderableLabelLines = (label: string): string[] => {
+  const truncated = label.slice(0, MAX_RENDER_LABEL_LENGTH);
+  const lines = truncated
+    .split(/\r?\n/)
+    .slice(0, MAX_RENDER_LABEL_LINES)
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+
+  return lines.length ? lines : [''];
+};
+
+/**
+ * Get node dimensions
+ */
+const getNodeDimensions = (node: PositionedNode): { width: number; height: number } => {
+  return {
+    width: node.size?.width ?? DEFAULT_NODE_WIDTH,
+    height: node.size?.height ?? DEFAULT_NODE_HEIGHT,
+  };
+};
+
+/**
+ * Create SVG rectangle element for node
+ */
+const createNodeRect = (width: number, height: number, radius: number): string => {
+  return `<rect x="0" y="0" width="${width}" height="${height}" rx="${radius}" ry="${radius}" fill="${DEFAULT_NODE_FILL}" stroke="${DEFAULT_NODE_STROKE}" stroke-width="1" />`;
+};
+
+/**
+ * Create SVG text element for node label
+ */
+const createNodeText = (label: string, width: number, height: number): string => {
+  const lines = getRenderableLabelLines(label);
+  const x = width / 2;
+  const lineHeight = DEFAULT_TEXT_SIZE + 4;
+  const firstLineY = height / 2 - ((lines.length - 1) * lineHeight) / 2 + 4;
+  const tspans = lines
+    .map(
+      (line, index) =>
+        `<tspan x="${x}" y="${firstLineY + index * lineHeight}">${escapeXml(line)}</tspan>`
+    )
+    .join('');
+
+  return `<text x="${x}" fill="${DEFAULT_TEXT_FILL}" font-size="${DEFAULT_TEXT_SIZE}" font-weight="600" text-anchor="middle">${tspans}</text>`;
+};
+
+/**
+ * Default node renderer - creates a rounded rectangle with centered text
+ */
+export const defaultNodeRenderer: NodeRenderer = (node) => {
+  const { width, height } = getNodeDimensions(node);
+  const label = getNodeLabel(node);
+  const rect = createNodeRect(width, height, DEFAULT_NODE_RADIUS);
+  const text = createNodeText(label, width, height);
+  return [rect, text].join('');
+};
+
+/**
+ * Determine if edge should have an arrow marker
+ */
+const shouldShowArrow = (edgeType?: EdgeType): boolean => {
+  return edgeType === EdgeType.Directed;
+};
+
+/**
+ * Create marker-end attribute for directed edges
+ */
+const createMarkerAttribute = (markerId: string): string => {
+  return ` marker-end="url(#${markerId})"`;
+};
+
+/**
+ * Default edge renderer - creates an SVG path with optional arrow marker
+ */
+export const defaultEdgeRenderer: EdgeRenderer = (edge, pathD, theme) => {
+  const marker =
+    shouldShowArrow(edge.type) && theme.markerId ? createMarkerAttribute(theme.markerId) : '';
+  const path = `<path d="${pathD}" stroke="${theme.edgeColor}" stroke-width="${theme.edgeWidth}" fill="none"${marker}/>`;
+  const label =
+    edge.label != null && edge.labelPosition
+      ? `<text x="${edge.labelPosition.x}" y="${edge.labelPosition.y - 6}" fill="${theme.edgeLabelColor}" font-size="12" font-weight="600" text-anchor="middle">${escapeXml(String(edge.label))}</text>`
+      : '';
+  return `${path}${label}`;
+};

package/src/rendering/index.ts

@@ -0,0 +1,3 @@
+export { renderGraphToSvg } from './svg';
+export { defaultNodeRenderer, defaultEdgeRenderer } from './defaultRenderers';
+export { escapeXml } from './utils';