@aiready/components 0.1.3 → 0.1.4

package/src/charts/LinkItem.tsx

@@ -0,0 +1,74 @@
+import React from 'react';
+import type { GraphLink, GraphNode } from './ForceDirectedGraph';
+
+export interface LinkItemProps {
+  link: GraphLink;
+  onClick?: (l: GraphLink) => void;
+  defaultWidth?: number;
+  showLabel?: boolean;
+  nodes?: GraphNode[]; // Optional nodes array to resolve string IDs to node objects
+}
+
+export const LinkItem: React.FC<LinkItemProps> = ({ link, onClick, defaultWidth, showLabel = true, nodes = [] }) => {
+  const src = (link.source as any)?.id ?? (typeof link.source === 'string' ? link.source : undefined);
+  const tgt = (link.target as any)?.id ?? (typeof link.target === 'string' ? link.target : undefined);
+
+  // Helper to get node position from source/target (which could be node object or string ID)
+  const getNodePosition = (nodeOrId: string | GraphNode): { x: number; y: number } | null => {
+    if (typeof nodeOrId === 'object' && nodeOrId !== null) {
+      // It's a node object
+      const node = nodeOrId as GraphNode;
+      return { x: node.x ?? 0, y: node.y ?? 0 };
+    } else if (typeof nodeOrId === 'string') {
+      // It's a string ID, try to find in nodes array
+      const found = nodes.find(n => n.id === nodeOrId);
+      if (found) return { x: found.x ?? 0, y: found.y ?? 0 };
+    }
+    return null;
+  };
+
+  const sourcePos = getNodePosition(link.source);
+  const targetPos = getNodePosition(link.target);
+
+  // If we can't get positions, render nothing (or a placeholder)
+  if (!sourcePos || !targetPos) {
+    return null;
+  }
+
+  // Calculate midpoint for label positioning
+  const midX = (sourcePos.x + targetPos.x) / 2;
+  const midY = (sourcePos.y + targetPos.y) / 2;
+
+  return (
+    <g>
+      <line
+        x1={sourcePos.x}
+        y1={sourcePos.y}
+        x2={targetPos.x}
+        y2={targetPos.y}
+        data-source={src}
+        data-target={tgt}
+        stroke={link.color}
+        strokeWidth={link.width ?? defaultWidth ?? 1}
+        opacity={0.6}
+        className="cursor-pointer transition-opacity hover:opacity-100"
+        onClick={() => onClick?.(link)}
+      />
+      {showLabel && link.label && (
+        <text
+          x={midX}
+          y={midY}
+          fill="#666"
+          fontSize="10"
+          textAnchor="middle"
+          dominantBaseline="middle"
+          pointerEvents="none"
+        >
+          {link.label}
+        </text>
+      )}
+    </g>
+  );
+};
+
+export default LinkItem;

package/src/charts/NodeItem.tsx

@@ -0,0 +1,70 @@
+import React from 'react';
+import type { GraphNode } from './ForceDirectedGraph';
+
+export interface NodeItemProps {
+  node: GraphNode;
+  isSelected: boolean;
+  isHovered: boolean;
+  pinned: boolean;
+  defaultNodeSize: number;
+  defaultNodeColor: string;
+  showLabel?: boolean;
+  onClick?: (n: GraphNode) => void;
+  onDoubleClick?: (e: React.MouseEvent, n: GraphNode) => void;
+  onMouseEnter?: (n: GraphNode) => void;
+  onMouseLeave?: () => void;
+  onMouseDown?: (e: React.MouseEvent, n: GraphNode) => void;
+}
+
+export const NodeItem: React.FC<NodeItemProps> = ({
+  node,
+  isSelected,
+  isHovered,
+  pinned,
+  defaultNodeSize,
+  defaultNodeColor,
+  showLabel = true,
+  onClick,
+  onDoubleClick,
+  onMouseEnter,
+  onMouseLeave,
+  onMouseDown,
+}) => {
+  const nodeSize = node.size || defaultNodeSize;
+  const nodeColor = node.color || defaultNodeColor;
+
+  const x = node.x ?? 0;
+  const y = node.y ?? 0;
+
+  return (
+    <g
+      key={node.id}
+      className="cursor-pointer node"
+      data-id={node.id}
+      transform={`translate(${x},${y})`}
+      onClick={() => onClick?.(node)}
+      onDoubleClick={(e) => onDoubleClick?.(e, node)}
+      onMouseEnter={() => onMouseEnter?.(node)}
+      onMouseLeave={() => onMouseLeave?.()}
+      onMouseDown={(e) => onMouseDown?.(e, node)}
+    >
+      <circle
+        r={nodeSize}
+        fill={nodeColor}
+        stroke={isSelected ? '#000' : isHovered ? '#666' : 'none'}
+        strokeWidth={pinned ? 3 : isSelected ? 2.5 : isHovered ? 2 : 1.5}
+        opacity={isHovered || isSelected ? 1 : 0.9}
+      />
+      {pinned && (
+        <circle r={nodeSize + 4} fill="none" stroke="#ff6b6b" strokeWidth={1} opacity={0.5} className="pointer-events-none" />
+      )}
+      {showLabel && node.label && (
+        <text y={nodeSize + 15} fill="#333" fontSize="12" textAnchor="middle" dominantBaseline="middle" pointerEvents="none" className="select-none">
+          {node.label}
+        </text>
+      )}
+    </g>
+  );
+};
+
+export default NodeItem;

package/src/hooks/useForceSimulation.ts

@@ -65,6 +65,44 @@ export interface ForceSimulationOptions {
    */
   alphaDecay?: number;
 
+  /**
+   * Alpha target controls the resting energy of the simulation. When set to 0
+   * the simulation will cool and stop moving once forces settle. Increase to
+   * keep the graph more dynamic.
+   * @default 0
+   */
+  alphaTarget?: number;
+
+  /**
+   * Warm alpha used when (re)starting the simulation to give it a small amount
+   * of energy. This mirrors the Observable example which sets a modest
+   * alphaTarget when dragging instead of forcing alpha to 1.
+   * @default 0.3
+   */
+  warmAlpha?: number;
+
+  /**
+   * Minimum alpha threshold below which the simulation is considered cooled
+   * and will stop. Increasing this makes the simulation stop earlier.
+   * @default 0.01
+   */
+  alphaMin?: number;
+
+  /**
+   * When true, zero node velocities and snap positions when the simulation
+   * stops to reduce residual jitter.
+   * @default true
+   */
+  stabilizeOnStop?: boolean;
+
+  /**
+   * Maximum time (ms) to allow the simulation to run after creation/restart.
+   * If the simulation hasn't cooled by this time, it will be force-stopped
+   * to prevent indefinite animation. Set to 0 to disable.
+   * @default 3000
+   */
+  maxSimulationTimeMs?: number;
+
   /**
    * Velocity decay (friction)
    * @default 0.4
@@ -185,7 +223,18 @@ export function useForceSimulation(
     height,
     alphaDecay = 0.0228,
     velocityDecay = 0.4,
+    alphaTarget = 0,
+    warmAlpha = 0.3,
+    alphaMin = 0.01,
+    // @ts-ignore allow extra option
+    stabilizeOnStop = true,
     onTick,
+    // Optional throttle in milliseconds for tick updates (reduce React re-renders)
+    // Lower values = smoother but more CPU; default ~30ms (~33fps)
+    // @ts-ignore allow extra option
+    tickThrottleMs = 33,
+    // @ts-ignore allow extra option
+    maxSimulationTimeMs = 3000,
   } = options;
 
   const [nodes, setNodes] = useState<SimulationNode[]>(initialNodes);
@@ -194,53 +243,160 @@ export function useForceSimulation(
   const [alpha, setAlpha] = useState(1);
 
   const simulationRef = useRef<d3.Simulation<SimulationNode, SimulationLink> | null>(null);
+  const stopTimeoutRef = useRef<number | null>(null);
+
+  // Create lightweight keys for nodes/links so we only recreate the simulation
+  // when the actual identity/content of inputs change (not when parent passes
+  // new array references on each render).
+  const nodesKey = initialNodes.map((n) => n.id).join('|');
+  const linksKey = (initialLinks || []).map((l) => {
+    const s = typeof l.source === 'string' ? l.source : (l.source as any)?.id;
+    const t = typeof l.target === 'string' ? l.target : (l.target as any)?.id;
+    return `${s}->${t}:${(l as any).type || ''}`;
+  }).join('|');
 
   useEffect(() => {
     // Create a copy of nodes and links to avoid mutating the original data
     const nodesCopy = initialNodes.map((node) => ({ ...node }));
     const linksCopy = initialLinks.map((link) => ({ ...link }));
 
+    // ALWAYS seed initial positions to ensure nodes don't stack at origin
+    // This is critical for force-directed graphs to work properly
+    try {
+      // Always seed positions for all nodes when simulation is created
+      // This ensures nodes start spread out even if they have coordinates
+      nodesCopy.forEach((n, i) => {
+        // Use deterministic but more widely spread positions based on index
+        const angle = (i * 2 * Math.PI) / nodesCopy.length;
+        // Larger seed radius to encourage an initial spread
+        const radius = Math.min(width, height) * 0.45;
+        n.x = width / 2 + radius * Math.cos(angle);
+        n.y = height / 2 + radius * Math.sin(angle);
+        // Add very small random velocity to avoid large initial motion
+        (n as any).vx = (Math.random() - 0.5) * 2;
+        (n as any).vy = (Math.random() - 0.5) * 2;
+      });
+    } catch (e) {
+      // If error, fall back to random positions
+      nodesCopy.forEach((n) => {
+        n.x = Math.random() * width;
+        n.y = Math.random() * height;
+        (n as any).vx = (Math.random() - 0.5) * 10;
+        (n as any).vy = (Math.random() - 0.5) * 10;
+      });
+    }
+
     // Create the simulation
-    const simulation = d3
-      .forceSimulation<SimulationNode>(nodesCopy)
-      .force(
-        'link',
-        d3
-          .forceLink<SimulationNode, SimulationLink>(linksCopy)
-          .id((d) => d.id)
-          .distance((d: any) => (d && d.distance != null ? d.distance : linkDistance))
-          .strength(linkStrength)
-      )
-      .force('charge', d3.forceManyBody().strength(chargeStrength))
-      .force('center', d3.forceCenter(width / 2, height / 2).strength(centerStrength))
-      .force(
-        'collision',
-        d3
-          .forceCollide<SimulationNode>()
-          .radius((d: any) => {
-            // Use node-specific size when available and add configured padding to ensure minimum spacing
-            const nodeSize = (d && d.size) ? d.size : 10;
-            return nodeSize + collisionRadius;
-          })
-          .strength(collisionStrength)
-      )
-      .alphaDecay(alphaDecay)
-      .velocityDecay(velocityDecay);
+    const simulation = (d3.forceSimulation(nodesCopy as any) as unknown) as d3.Simulation<SimulationNode, SimulationLink>;
+
+    // Configure link force separately to avoid using generic type args on d3 helpers
+    try {
+      const linkForce = (d3.forceLink(linksCopy as any) as unknown) as d3.ForceLink<SimulationNode, SimulationLink>;
+      linkForce.id((d: any) => d.id).distance((d: any) => (d && d.distance != null ? d.distance : linkDistance)).strength(linkStrength);
+      simulation.force('link', linkForce as any);
+    } catch (e) {
+      // fallback: attach a plain link force
+      try { simulation.force('link', d3.forceLink(linksCopy as any) as any); } catch (e) {}
+    }
+      ;
+
+    try {
+      simulation.force('charge', d3.forceManyBody().strength(chargeStrength) as any);
+      simulation.force('center', d3.forceCenter(width / 2, height / 2).strength(centerStrength) as any);
+      const collide = d3.forceCollide().radius((d: any) => {
+        const nodeSize = (d && d.size) ? d.size : 10;
+        return nodeSize + collisionRadius;
+      }).strength(collisionStrength as any) as any;
+      simulation.force('collision', collide);
+      simulation.force('x', d3.forceX(width / 2).strength(Math.max(0.02, centerStrength * 0.5)) as any);
+      simulation.force('y', d3.forceY(height / 2).strength(Math.max(0.02, centerStrength * 0.5)) as any);
+      simulation.alphaDecay(alphaDecay);
+      simulation.velocityDecay(velocityDecay);
+      simulation.alphaMin(alphaMin);
+      try { simulation.alphaTarget(alphaTarget); } catch (e) {}
+      try { simulation.alpha(warmAlpha); } catch (e) {}
+    } catch (e) {
+      // ignore force configuration errors
+    }
 
     simulationRef.current = simulation;
 
-    // Update state on each tick
-    simulation.on('tick', () => {
+    // Force-stop timeout to ensure simulation doesn't run forever.
+    if (stopTimeoutRef.current != null) {
+      try { (globalThis.clearTimeout as any)(stopTimeoutRef.current); } catch (e) {}
+      stopTimeoutRef.current = null;
+    }
+    if (maxSimulationTimeMs && maxSimulationTimeMs > 0) {
+      stopTimeoutRef.current = (globalThis.setTimeout as any)(() => {
+        try {
+          if (stabilizeOnStop) {
+            nodesCopy.forEach((n) => {
+              (n as any).vx = 0;
+              (n as any).vy = 0;
+              if (typeof n.x === 'number') n.x = Number(n.x.toFixed(3));
+              if (typeof n.y === 'number') n.y = Number(n.y.toFixed(3));
+            });
+          }
+          simulation.alpha(0);
+          simulation.stop();
+        } catch (e) {}
+        setIsRunning(false);
+        setNodes([...nodesCopy]);
+        setLinks([...linksCopy]);
+      }, maxSimulationTimeMs) as unknown as number;
+    }
+
+    // Update state on each tick. Batch updates via requestAnimationFrame to avoid
+    // excessive React re-renders which can cause visual flicker.
+    let rafId: number | null = null;
+    let lastUpdate = 0;
+    const tickHandler = () => {
       try {
         if (typeof onTick === 'function') onTick(nodesCopy, linksCopy, simulation);
       } catch (e) {
         // ignore user tick errors
       }
-      setNodes([...nodesCopy]);
-      setLinks([...linksCopy]);
-      setAlpha(simulation.alpha());
-      setIsRunning(simulation.alpha() > simulation.alphaMin());
-    });
+
+      // If simulation alpha has cooled below the configured minimum, stop it to
+      // ensure nodes don't drift indefinitely (acts as a hard-stop safeguard).
+      try {
+        if (simulation.alpha() <= (alphaMin as number)) {
+          try {
+            if (stabilizeOnStop) {
+              nodesCopy.forEach((n) => {
+                (n as any).vx = 0;
+                (n as any).vy = 0;
+                if (typeof n.x === 'number') n.x = Number(n.x.toFixed(3));
+                if (typeof n.y === 'number') n.y = Number(n.y.toFixed(3));
+              });
+            }
+            simulation.stop();
+          } catch (e) {}
+          setAlpha(simulation.alpha());
+          setIsRunning(false);
+          setNodes([...nodesCopy]);
+          setLinks([...linksCopy]);
+          return;
+        }
+      } catch (e) {
+        // ignore
+      }
+
+      const now = Date.now();
+      const shouldUpdate = now - lastUpdate >= (tickThrottleMs as number);
+      if (rafId == null && shouldUpdate) {
+        rafId = (globalThis.requestAnimationFrame || ((cb: FrameRequestCallback) => setTimeout(cb, 16)))(() => {
+          rafId = null;
+          lastUpdate = Date.now();
+          setNodes([...nodesCopy]);
+          setLinks([...linksCopy]);
+          setAlpha(simulation.alpha());
+          setIsRunning(simulation.alpha() > simulation.alphaMin());
+        }) as unknown as number;
+      }
+    };
+
+    simulation.on('tick', tickHandler);
 
     simulation.on('end', () => {
       setIsRunning(false);
@@ -248,11 +404,22 @@ export function useForceSimulation(
 
     // Cleanup on unmount
     return () => {
+      try {
+        simulation.on('tick', null as any);
+      } catch (e) {}
+      if (stopTimeoutRef.current != null) {
+        try { (globalThis.clearTimeout as any)(stopTimeoutRef.current); } catch (e) {}
+        stopTimeoutRef.current = null;
+      }
+      if (rafId != null) {
+        try { (globalThis.cancelAnimationFrame || ((id: number) => clearTimeout(id)))(rafId); } catch (e) {}
+        rafId = null;
+      }
       simulation.stop();
     };
   }, [
-    initialNodes,
-    initialLinks,
+    nodesKey,
+    linksKey,
     chargeStrength,
     linkDistance,
     linkStrength,
@@ -263,13 +430,30 @@ export function useForceSimulation(
     height,
     alphaDecay,
     velocityDecay,
-    onTick,
+    alphaTarget,
+    alphaMin,
+    stabilizeOnStop,
+    tickThrottleMs,
+    maxSimulationTimeMs,
   ]);
 
   const restart = () => {
     if (simulationRef.current) {
-      simulationRef.current.alpha(1).restart();
+      // Reheat the simulation to a modest alpha target rather than forcing
+      // full heat; this matches the Observable pattern and helps stability.
+      try { simulationRef.current.alphaTarget(warmAlpha).restart(); } catch (e) { simulationRef.current.restart(); }
       setIsRunning(true);
+      // Reset safety timeout when simulation is manually restarted
+      if (stopTimeoutRef.current != null) {
+        try { (globalThis.clearTimeout as any)(stopTimeoutRef.current); } catch (e) {}
+        stopTimeoutRef.current = null;
+      }
+      if (maxSimulationTimeMs && maxSimulationTimeMs > 0) {
+        stopTimeoutRef.current = (globalThis.setTimeout as any)(() => {
+          try { simulationRef.current?.alpha(0); simulationRef.current?.stop(); } catch (e) {}
+          setIsRunning(false);
+        }, maxSimulationTimeMs) as unknown as number;
+      }
     }
   };