@aiready/components 0.14.2 → 0.14.3

package/dist/{useForceSimulation-BNhxX4gH.d.ts → useForceSimulation-CjLhYevG.d.ts}

@@ -37,13 +37,14 @@ interface UseForceSimulationReturn {
     alpha: number;
 }
 
-declare function useForceSimulation(initialNodes: SimulationNode[], initialLinks: SimulationLink[], options: ForceSimulationOptions): UseForceSimulationReturn & {
+interface UseForceSimulationReturnExt extends UseForceSimulationReturn {
     setForcesEnabled: (enabled: boolean) => void;
-};
+}
+declare function useForceSimulation(initialNodes: SimulationNode[], initialLinks: SimulationLink[], options: ForceSimulationOptions): UseForceSimulationReturnExt;
 declare function useDrag(simulation: d3.Simulation<SimulationNode, any> | null | undefined): {
     onDragStart: (event: any, node: SimulationNode) => void;
     onDrag: (event: any, node: SimulationNode) => void;
     onDragEnd: (event: any, node: SimulationNode) => void;
 };
 
-export { type ForceSimulationOptions as F, type SimulationLink as S, type UseForceSimulationReturn as U, type SimulationNode as a, useForceSimulation as b, useDrag as u };
+export { type ForceSimulationOptions as F, type SimulationLink as S, type UseForceSimulationReturn as U, type SimulationNode as a, useForceSimulation as b, type UseForceSimulationReturnExt as c, useDrag as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiready/components",
-  "version": "0.14.2",
+  "version": "0.14.3",
   "description": "Unified shared components library (UI, charts, hooks, utilities) for AIReady",
   "type": "module",
   "main": "./dist/index.js",
@@ -128,7 +128,7 @@
     "framer-motion": "^12.35.0",
     "lucide-react": "^0.577.0",
     "tailwind-merge": "^3.0.0",
-    "@aiready/core": "0.24.3"
+    "@aiready/core": "0.24.4"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.5",

package/src/hooks/simulation-constants.ts

@@ -0,0 +1,39 @@
+/**
+ * Constants for force simulation defaults and configuration
+ */
+export const SIMULATION_DEFAULTS = {
+  CHARGE_STRENGTH: -300,
+  LINK_DISTANCE: 100,
+  LINK_STRENGTH: 1,
+  COLLISION_STRENGTH: 1,
+  COLLISION_RADIUS: 10,
+  CENTER_STRENGTH: 0.1,
+  ALPHA_DECAY: 0.0228,
+  VELOCITY_DECAY: 0.4,
+  ALPHA_TARGET: 0,
+  WARM_ALPHA: 0.3,
+  ALPHA_MIN: 0.01,
+  TICK_THROTTLE_MS: 33, // ~30 fps
+  MAX_SIMULATION_TIME_MS: 3000,
+  STABILIZE_ON_STOP: true,
+} as const;
+
+/**
+ * Force names used in d3-force
+ */
+export const FORCE_NAMES = {
+  LINK: 'link',
+  CHARGE: 'charge',
+  CENTER: 'center',
+  COLLISION: 'collision',
+  X: 'x',
+  Y: 'y',
+} as const;
+
+/**
+ * Event names used in d3-force
+ */
+export const EVENT_NAMES = {
+  TICK: 'tick',
+  END: 'end',
+} as const;

package/src/hooks/simulation-helpers.ts

@@ -6,13 +6,33 @@ import { SimulationNode } from './simulation-types';
  */
 export function stabilizeNodes(nodes: SimulationNode[]): void {
   nodes.forEach((n) => {
-    (n as any).vx = 0;
-    (n as any).vy = 0;
+    n.vx = 0;
+    n.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));
   });
 }
 
+/**
+ * Seeds nodes with initial positions in a spread circle.
+ * This ensures nodes don't stack at origin and have some initial velocity.
+ */
+export function seedCircularPositions(
+  nodes: SimulationNode[],
+  width: number,
+  height: number
+): void {
+  const radius = Math.min(width, height) * 0.45;
+  nodes.forEach((n, i) => {
+    const angle = (i * 2 * Math.PI) / nodes.length;
+    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.vx = (Math.random() - 0.5) * 2;
+    n.vy = (Math.random() - 0.5) * 2;
+  });
+}
+
 /**
  * Seeds nodes with random positions within bounds.
  * Used as fallback when initial positioning fails.
@@ -25,7 +45,25 @@ export function seedRandomPositions(
   nodes.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;
+    n.vx = (Math.random() - 0.5) * 10;
+    n.vy = (Math.random() - 0.5) * 10;
   });
 }
+
+/**
+ * Safely stops a d3 simulation and performs cleanup tasks.
+ */
+export function safelyStopSimulation(
+  simulation: d3.Simulation<SimulationNode, any>,
+  nodes: SimulationNode[],
+  options: { stabilize?: boolean } = {}
+): void {
+  try {
+    if (options.stabilize) {
+      stabilizeNodes(nodes);
+    }
+    simulation.stop();
+  } catch (error) {
+    console.warn('AIReady: Failed to stop simulation safely:', error);
+  }
+}