@carlonicora/nextjs-jsonapi 1.97.2 → 1.99.0

package/src/hooks/useCustomD3Graph.tsx

@@ -5,6 +5,7 @@ import { Loader2 } from "lucide-react";
 import { useCallback, useEffect, useMemo, useRef } from "react";
 import { renderToStaticMarkup } from "react-dom/server";
 import { D3Link, D3Node } from "../interfaces";
+import { computeLayeredLayout, type LayeredRankDir } from "./computeLayeredLayout";
 
 /**
  * Custom hook for D3 graph visualization with larger circles and more interactive features
@@ -14,6 +15,15 @@ export function useCustomD3Graph(
   links: D3Link[],
   onNodeClick: (nodeId: string) => void,
   visibleNodeIds?: Set<string>,
+  options?: {
+    directed?: boolean;
+    layout?: "radial" | "layered";
+    layered?: {
+      rankdir?: LayeredRankDir;
+      nodesep?: number;
+      ranksep?: number;
+    };
+  },
   loadingNodeIds?: Set<string>,
   containerKey?: string | number,
 ) {
@@ -154,6 +164,9 @@ export function useCustomD3Graph(
 
   const getNodeColor = useCallback(
     (node: D3Node) => {
+      if (node.color) {
+        return node.washedOut ? washOutColor(node.color) : node.color;
+      }
       const baseColor = colorScale.get(node.instanceType) || "gray";
       if (node.washedOut) {
         return washOutColor(baseColor);
@@ -190,6 +203,26 @@ export function useCustomD3Graph(
 
     const graphGroup = svg.append("g").attr("class", "graph-content");
 
+    const nodeRadius = 40;
+    const directed = options?.directed === true;
+
+    if (directed) {
+      const defs = svg.append("defs");
+      defs
+        .append("marker")
+        .attr("id", "narr8-arrow")
+        .attr("viewBox", "-10 -10 20 20")
+        .attr("markerWidth", 14)
+        .attr("markerHeight", 14)
+        .attr("markerUnits", "userSpaceOnUse")
+        .attr("orient", "auto")
+        .attr("refX", 0)
+        .attr("refY", 0)
+        .append("path")
+        .attr("d", "M-10,-10 L0,0 L-10,10 z")
+        .attr("fill", "#999");
+    }
+
     const zoom = d3
       .zoom<SVGSVGElement, unknown>()
       .scaleExtent([0.1, 4])
@@ -206,170 +239,245 @@ export function useCustomD3Graph(
       .on("wheel.zoom", null)
       .on("dblclick.zoom", null);
 
-    const nodeRadius = 40;
-
-    const childDistanceFromRoot = Math.min(width, height) * 0.4;
-    const grandchildDistanceFromChild = nodeRadius * 10;
-
-    const centralNodeId = nodes[0].id;
+    const layoutMode = options?.layout ?? "radial";
+    let layeredPositionsApplied = false;
+
+    if (layoutMode === "layered") {
+      const layeredOpts = options?.layered ?? {};
+      const positions = computeLayeredLayout(visibleNodes, visibleLinks, {
+        rankdir: layeredOpts.rankdir ?? "LR",
+        nodesep: layeredOpts.nodesep,
+        ranksep: layeredOpts.ranksep,
+        minNodeWidth: nodeRadius * 2,
+        minNodeHeight: nodeRadius * 2,
+      });
 
-    const nodeHierarchy = new Map<
-      string,
-      {
-        depth: number;
-        parent: string | null;
-        children: string[];
-        angle?: number;
-        x?: number;
-        y?: number;
+      if (positions) {
+        visibleNodes.forEach((node) => {
+          const saved = nodePositionsRef.current.get(node.id);
+          if (saved) {
+            node.fx = saved.x;
+            node.fy = saved.y;
+            node.x = saved.x;
+            node.y = saved.y;
+            return;
+          }
+          const pos = positions.get(node.id);
+          if (pos) {
+            node.fx = pos.x;
+            node.fy = pos.y;
+            node.x = pos.x;
+            node.y = pos.y;
+            nodePositionsRef.current.set(node.id, { x: pos.x, y: pos.y });
+          }
+        });
+        // d3.forceLink normally mutates link.source/link.target from string
+        // IDs to D3Node references when the simulation initializes. The
+        // layered branch skips the simulation, so we resolve those refs
+        // ourselves — otherwise the downstream link rendering reads
+        // `(d.source as D3Node).x` against a string and draws every line
+        // at (0,0)→(0,0).
+        const nodeById = new Map<string, D3Node>();
+        visibleNodes.forEach((n) => nodeById.set(n.id, n));
+        visibleLinks.forEach((link) => {
+          if (typeof link.source === "string") {
+            const src = nodeById.get(link.source);
+            if (src) link.source = src;
+          }
+          if (typeof link.target === "string") {
+            const tgt = nodeById.get(link.target);
+            if (tgt) link.target = tgt;
+          }
+        });
+        layeredPositionsApplied = true;
+      } else {
+        console.warn("[useCustomD3Graph] Layered layout failed; falling back to radial.");
       }
-    >();
+    }
 
-    nodeHierarchy.set(centralNodeId, {
-      depth: 0,
-      parent: null,
-      children: [],
-    });
+    let simulation: d3.Simulation<D3Node, D3Link> | null = null;
 
-    visibleLinks.forEach((link) => {
-      const sourceId = typeof link.source === "string" ? link.source : link.source.id;
-      const targetId = typeof link.target === "string" ? link.target : link.target.id;
+    if (!layeredPositionsApplied) {
+      const childDistanceFromRoot = Math.min(width, height) * 0.4;
+      const grandchildDistanceFromChild = nodeRadius * 10;
+
+      const centralNodeId = nodes[0].id;
 
-      if (sourceId === centralNodeId) {
-        nodeHierarchy.set(targetId, { depth: 1, parent: centralNodeId, children: [] });
-        const rootNode = nodeHierarchy.get(centralNodeId);
-        if (rootNode) {
-          rootNode.children.push(targetId);
+      const nodeHierarchy = new Map<
+        string,
+        {
+          depth: number;
+          parent: string | null;
+          children: string[];
+          angle?: number;
+          x?: number;
+          y?: number;
         }
-      }
-    });
+      >();
 
-    visibleLinks.forEach((link) => {
-      const sourceId = typeof link.source === "string" ? link.source : link.source.id;
-      const targetId = typeof link.target === "string" ? link.target : link.target.id;
+      nodeHierarchy.set(centralNodeId, {
+        depth: 0,
+        parent: null,
+        children: [],
+      });
 
-      const sourceNode = nodeHierarchy.get(sourceId);
-      if (sourceNode && sourceNode.depth === 1 && !nodeHierarchy.has(targetId)) {
-        nodeHierarchy.set(targetId, { depth: 2, parent: sourceId, children: [] });
-        sourceNode.children.push(targetId);
-      }
-    });
+      visibleLinks.forEach((link) => {
+        const sourceId = typeof link.source === "string" ? link.source : link.source.id;
+        const targetId = typeof link.target === "string" ? link.target : link.target.id;
 
-    const rootChildren = nodeHierarchy.get(centralNodeId)?.children || [];
+        if (sourceId === centralNodeId) {
+          nodeHierarchy.set(targetId, { depth: 1, parent: centralNodeId, children: [] });
+          const rootNode = nodeHierarchy.get(centralNodeId);
+          if (rootNode) {
+            rootNode.children.push(targetId);
+          }
+        }
+      });
 
-    const childAngleStep = (2 * Math.PI) / Math.max(rootChildren.length, 1);
+      visibleLinks.forEach((link) => {
+        const sourceId = typeof link.source === "string" ? link.source : link.source.id;
+        const targetId = typeof link.target === "string" ? link.target : link.target.id;
 
-    rootChildren.forEach((childId, index) => {
-      const childNode = nodeHierarchy.get(childId);
-      if (childNode) {
-        const angle = index * childAngleStep;
-        childNode.angle = angle;
-        childNode.x = width / 2 + childDistanceFromRoot * Math.cos(angle);
-        childNode.y = height / 2 + childDistanceFromRoot * Math.sin(angle);
-      }
-    });
+        const sourceNode = nodeHierarchy.get(sourceId);
+        if (sourceNode && sourceNode.depth === 1 && !nodeHierarchy.has(targetId)) {
+          nodeHierarchy.set(targetId, { depth: 2, parent: sourceId, children: [] });
+          sourceNode.children.push(targetId);
+        }
+      });
 
-    for (const [_nodeId, node] of nodeHierarchy.entries()) {
-      if (node.depth === 1 && node.angle !== undefined && node.x !== undefined && node.y !== undefined) {
-        const childAngle = node.angle;
-        const childX = node.x;
-        const childY = node.y;
-        const grandchildren = node.children;
-
-        if (grandchildren.length === 0) continue;
-
-        const dirX = childX - width / 2;
-        const dirY = childY - height / 2;
-        const dirLength = Math.sqrt(dirX * dirX + dirY * dirY);
-
-        const normDirX = dirX / dirLength;
-        const normDirY = dirY / dirLength;
-
-        if (grandchildren.length === 1) {
-          const grandchildId = grandchildren[0];
-          const grandchildNode = nodeHierarchy.get(grandchildId);
-          if (grandchildNode) {
-            grandchildNode.x = childX + normDirX * grandchildDistanceFromChild;
-            grandchildNode.y = childY + normDirY * grandchildDistanceFromChild;
-            grandchildNode.angle = childAngle;
-          }
-        } else {
-          // Multiple grandchildren - arrange in semicircular arc
-          const numChildren = grandchildren.length;
+      const rootChildren = nodeHierarchy.get(centralNodeId)?.children || [];
 
-          // Dynamic arc span: scale from 60° (2 children) to 180° (7+ children)
-          const minArc = Math.PI / 3; // 60 degrees
-          const maxArc = Math.PI; // 180 degrees
-          const arcProgress = Math.min(1, (numChildren - 2) / 5);
-          const arcSpan = minArc + arcProgress * (maxArc - minArc);
+      const childAngleStep = (2 * Math.PI) / Math.max(rootChildren.length, 1);
 
-          // Calculate starting angle (center the arc around the radial direction)
-          const startAngle = childAngle - arcSpan / 2;
+      rootChildren.forEach((childId, index) => {
+        const childNode = nodeHierarchy.get(childId);
+        if (childNode) {
+          const angle = index * childAngleStep;
+          childNode.angle = angle;
+          childNode.x = width / 2 + childDistanceFromRoot * Math.cos(angle);
+          childNode.y = height / 2 + childDistanceFromRoot * Math.sin(angle);
+        }
+      });
 
-          grandchildren.forEach((grandchildId, index) => {
-            const grandchildNode = nodeHierarchy.get(grandchildId);
-            if (!grandchildNode) return;
+      for (const [_nodeId, node] of nodeHierarchy.entries()) {
+        if (node.depth === 1 && node.angle !== undefined && node.x !== undefined && node.y !== undefined) {
+          const childAngle = node.angle;
+          const childX = node.x;
+          const childY = node.y;
+          const grandchildren = node.children;
 
-            // Calculate angle for this child
-            const angleOffset = numChildren > 1 ? (index / (numChildren - 1)) * arcSpan : 0;
-            const angle = startAngle + angleOffset;
+          if (grandchildren.length === 0) continue;
 
-            // Position at constant radius from parent
-            grandchildNode.x = childX + grandchildDistanceFromChild * Math.cos(angle);
-            grandchildNode.y = childY + grandchildDistanceFromChild * Math.sin(angle);
-            grandchildNode.angle = angle;
-          });
-        }
-      }
-    }
+          const dirX = childX - width / 2;
+          const dirY = childY - height / 2;
+          const dirLength = Math.sqrt(dirX * dirX + dirY * dirY);
 
-    visibleNodes.forEach((node) => {
-      const savedPosition = nodePositionsRef.current.get(node.id);
+          const normDirX = dirX / dirLength;
+          const normDirY = dirY / dirLength;
 
-      if (savedPosition) {
-        node.fx = savedPosition.x;
-        node.fy = savedPosition.y;
-      } else {
-        const hierarchyNode = nodeHierarchy.get(node.id);
-        if (hierarchyNode && hierarchyNode.x !== undefined && hierarchyNode.y !== undefined) {
-          node.fx = hierarchyNode.x;
-          node.fy = hierarchyNode.y;
-          // Save the calculated position so it persists across re-renders
-          nodePositionsRef.current.set(node.id, { x: hierarchyNode.x, y: hierarchyNode.y });
-        } else if (node.id === centralNodeId) {
-          node.fx = width / 2;
-          node.fy = height / 2;
-          // Save the center position
-          nodePositionsRef.current.set(node.id, { x: width / 2, y: height / 2 });
+          if (grandchildren.length === 1) {
+            const grandchildId = grandchildren[0];
+            const grandchildNode = nodeHierarchy.get(grandchildId);
+            if (grandchildNode) {
+              grandchildNode.x = childX + normDirX * grandchildDistanceFromChild;
+              grandchildNode.y = childY + normDirY * grandchildDistanceFromChild;
+              grandchildNode.angle = childAngle;
+            }
+          } else {
+            // Multiple grandchildren - arrange in semicircular arc
+            const numChildren = grandchildren.length;
+
+            // Dynamic arc span: scale from 60° (2 children) to 180° (7+ children)
+            const minArc = Math.PI / 3; // 60 degrees
+            const maxArc = Math.PI; // 180 degrees
+            const arcProgress = Math.min(1, (numChildren - 2) / 5);
+            const arcSpan = minArc + arcProgress * (maxArc - minArc);
+
+            // Calculate starting angle (center the arc around the radial direction)
+            const startAngle = childAngle - arcSpan / 2;
+
+            grandchildren.forEach((grandchildId, index) => {
+              const grandchildNode = nodeHierarchy.get(grandchildId);
+              if (!grandchildNode) return;
+
+              // Calculate angle for this child
+              const angleOffset = numChildren > 1 ? (index / (numChildren - 1)) * arcSpan : 0;
+              const angle = startAngle + angleOffset;
+
+              // Position at constant radius from parent
+              grandchildNode.x = childX + grandchildDistanceFromChild * Math.cos(angle);
+              grandchildNode.y = childY + grandchildDistanceFromChild * Math.sin(angle);
+              grandchildNode.angle = angle;
+            });
+          }
         }
       }
-    });
 
-    const simulation = d3
-      .forceSimulation<D3Node>(visibleNodes)
-      .force(
-        "link",
-        d3
-          .forceLink<D3Node, D3Link>(visibleLinks)
-          .id((d) => d.id)
-          .distance(nodeRadius * 3)
-          .strength(0.1),
-      )
-      .force("charge", d3.forceManyBody().strength(-500).distanceMax(300))
-      .force("collision", d3.forceCollide().radius(nodeRadius * 1.2))
-      .force("center", d3.forceCenter(width / 2, height / 2).strength(0.1));
+      visibleNodes.forEach((node) => {
+        const savedPosition = nodePositionsRef.current.get(node.id);
 
-    simulation.stop();
-    for (let i = 0; i < 100; i++) {
-      simulation.tick();
-    }
+        if (savedPosition) {
+          node.fx = savedPosition.x;
+          node.fy = savedPosition.y;
+        } else {
+          const hierarchyNode = nodeHierarchy.get(node.id);
+          if (hierarchyNode && hierarchyNode.x !== undefined && hierarchyNode.y !== undefined) {
+            node.fx = hierarchyNode.x;
+            node.fy = hierarchyNode.y;
+            // Save the calculated position so it persists across re-renders
+            nodePositionsRef.current.set(node.id, { x: hierarchyNode.x, y: hierarchyNode.y });
+          } else if (node.id === centralNodeId) {
+            node.fx = width / 2;
+            node.fy = height / 2;
+            // Save the center position
+            nodePositionsRef.current.set(node.id, { x: width / 2, y: height / 2 });
+          }
+        }
+      });
 
-    visibleNodes.forEach((node) => {
-      if (node.fx === undefined) {
-        node.fx = node.x;
-        node.fy = node.y;
+      simulation = d3
+        .forceSimulation<D3Node>(visibleNodes)
+        .force(
+          "link",
+          d3
+            .forceLink<D3Node, D3Link>(visibleLinks)
+            .id((d) => d.id)
+            .distance(nodeRadius * 3)
+            .strength(0.1),
+        )
+        .force("charge", d3.forceManyBody().strength(-500).distanceMax(300))
+        .force("collision", d3.forceCollide().radius(nodeRadius * 1.2))
+        .force("center", d3.forceCenter(width / 2, height / 2).strength(0.1));
+
+      simulation.stop();
+      for (let i = 0; i < 100; i++) {
+        simulation.tick();
       }
-    });
+
+      visibleNodes.forEach((node) => {
+        if (node.fx === undefined) {
+          node.fx = node.x;
+          node.fy = node.y;
+        }
+      });
+    } // end if (!layeredPositionsApplied)
+
+    // When directed, stop the line at the target node boundary so the
+    // arrowhead tip sits just outside the circle rather than inside it.
+    const linkX2 = (sx: number, sy: number, tx: number, ty: number): number => {
+      if (!directed) return tx;
+      const dx = tx - sx;
+      const dy = ty - sy;
+      const dist = Math.sqrt(dx * dx + dy * dy) || 1;
+      return tx - (dx / dist) * nodeRadius;
+    };
+    const linkY2 = (sx: number, sy: number, tx: number, ty: number): number => {
+      if (!directed) return ty;
+      const dx = tx - sx;
+      const dy = ty - sy;
+      const dist = Math.sqrt(dx * dx + dy * dy) || 1;
+      return ty - (dy / dist) * nodeRadius;
+    };
 
     const link = graphGroup
       .append("g")
@@ -380,9 +488,18 @@ export function useCustomD3Graph(
       .join("line")
       .attr("x1", (d) => (d.source as D3Node).x || 0)
       .attr("y1", (d) => (d.source as D3Node).y || 0)
-      .attr("x2", (d) => (d.target as D3Node).x || 0)
-      .attr("y2", (d) => (d.target as D3Node).y || 0)
-      .attr("stroke-width", 1.5);
+      .attr("x2", (d) => {
+        const s = d.source as D3Node;
+        const t = d.target as D3Node;
+        return linkX2(s.x || 0, s.y || 0, t.x || 0, t.y || 0);
+      })
+      .attr("y2", (d) => {
+        const s = d.source as D3Node;
+        const t = d.target as D3Node;
+        return linkY2(s.x || 0, s.y || 0, t.x || 0, t.y || 0);
+      })
+      .attr("stroke-width", 1.5)
+      .attr("marker-end", directed ? "url(#narr8-arrow)" : null);
 
     const node = graphGroup
       .append("g")
@@ -423,12 +540,22 @@ export function useCustomD3Graph(
                 return source.fy || source.y || 0;
               })
               .attr("x2", (l) => {
+                const source = l.source as D3Node;
                 const target = l.target as D3Node;
-                return target.fx || target.x || 0;
+                const sx = source.fx || source.x || 0;
+                const sy = source.fy || source.y || 0;
+                const tx = target.fx || target.x || 0;
+                const ty = target.fy || target.y || 0;
+                return linkX2(sx, sy, tx, ty);
               })
               .attr("y2", (l) => {
+                const source = l.source as D3Node;
                 const target = l.target as D3Node;
-                return target.fy || target.y || 0;
+                const sx = source.fx || source.x || 0;
+                const sy = source.fy || source.y || 0;
+                const tx = target.fx || target.x || 0;
+                const ty = target.fy || target.y || 0;
+                return linkY2(sx, sy, tx, ty);
               });
           })
           .on("end", function (event, d) {
@@ -489,8 +616,13 @@ export function useCustomD3Graph(
           .attr("r", nodeRadius)
           .attr("filter", null);
 
-        // Return text to normal size with smooth transform
-        const normalOffset = nodeRadius + 5;
+        // Return text to normal size with smooth transform. Two-line labels
+        // (when `d.subtitle` is set) sit one line-gap higher than the single
+        // line case — restoring to the bare `nodeRadius + 5` offset would
+        // shift the title down by that gap (visibly jumping after the first
+        // hover). The 16 here matches the `lineGap` used when the two-line
+        // text is first rendered (see the `d.subtitle` branch below).
+        const normalOffset = nodeRadius + 5 + (d.subtitle ? 16 : 0);
         currentNode
           .select("text")
           .transition()
@@ -607,6 +739,24 @@ export function useCustomD3Graph(
             .attr("dy", index === 0 ? `${startY}em` : `${lineHeight}em`)
             .text(word);
         });
+      } else if (d.subtitle) {
+        // Two-line label: name (bigger, bolder) on line 1, subtitle
+        // (smaller, dimmed) on line 2. Used by the scene graph to show
+        // the HAPPENS_AT location name beneath the scene title. The
+        // whole text block is lifted above the circle so the lower line
+        // sits at the same baseline the single-line case uses.
+        const titleSize = 16;
+        const subtitleSize = 11;
+        const lineGap = titleSize; // px between baselines
+        textElement.attr("dy", -nodeRadius - 5 - lineGap).attr("fill", "currentColor");
+        textElement.append("tspan").attr("x", 0).attr("font-size", titleSize).attr("font-weight", 700).text(d.name);
+        textElement
+          .append("tspan")
+          .attr("x", 0)
+          .attr("dy", lineGap)
+          .attr("font-size", subtitleSize)
+          .attr("fill-opacity", 0.7)
+          .text(d.subtitle);
       } else {
         // Non-root nodes: single line text above the circle. The
         // optional `bold` flag lets the consumer highlight a focal
@@ -623,9 +773,21 @@ export function useCustomD3Graph(
     });
 
     return () => {
-      simulation.stop();
+      simulation?.stop();
     };
-  }, [nodes, links, colorScale, visibleNodeIds, loadingNodeIds, onNodeClick]);
+  }, [
+    nodes,
+    links,
+    colorScale,
+    visibleNodeIds,
+    options?.directed,
+    options?.layout,
+    options?.layered?.rankdir,
+    options?.layered?.nodesep,
+    options?.layered?.ranksep,
+    loadingNodeIds,
+    onNodeClick,
+  ]);
 
   const zoomIn = useCallback(() => {
     if (!svgRef.current || !zoomBehaviorRef.current) return;

package/src/interfaces/d3.node.interface.ts

@@ -11,4 +11,6 @@ export interface D3Node extends d3.SimulationNodeDatum {
   visible?: boolean;
   washedOut?: boolean;
   bold?: boolean;
+  color?: string;
+  subtitle?: string;
 }