@aiready/components 0.13.18 → 0.13.20

package/src/charts/force-directed/ForceDirectedGraph.tsx

@@ -0,0 +1,250 @@
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  forwardRef,
+  useImperativeHandle,
+} from 'react';
+import * as d3 from 'd3';
+import {
+  GraphNode,
+  LayoutType,
+  ForceDirectedGraphHandle,
+  ForceDirectedGraphProps,
+} from './types';
+import {
+  useGraphZoom,
+  useWindowDrag,
+  useNodeInteractions,
+} from './useGraphInteractions';
+import { useGraphLayout, useSimulationControls } from './useGraphLayout';
+import { useImperativeHandleMethods } from './useImperativeHandle';
+import { GraphCanvas } from './GraphCanvas';
+
+export const ForceDirectedGraph = forwardRef<
+  ForceDirectedGraphHandle,
+  ForceDirectedGraphProps
+>(
+  (
+    {
+      nodes: initialNodes,
+      links: initialLinks,
+      width,
+      height,
+      enableZoom = true,
+      enableDrag = true,
+      onNodeClick,
+      onNodeHover,
+      onLinkClick,
+      selectedNodeId,
+      hoveredNodeId,
+      defaultNodeColor,
+      defaultNodeSize,
+      defaultLinkColor,
+      defaultLinkWidth,
+      showNodeLabels,
+      showLinkLabels,
+      className,
+      manualLayout = false,
+      onManualLayoutChange,
+      packageBounds,
+      layout: externalLayout,
+      onLayoutChange,
+    },
+    ref
+  ) => {
+    const svgRef = useRef<SVGSVGElement>(null);
+    const gRef = useRef<SVGGElement>(null);
+    const [transform, setTransform] = useState({ k: 1, x: 0, y: 0 });
+    const transformRef = useRef(transform);
+    const dragNodeRef = useRef<GraphNode | null>(null);
+    const dragActiveRef = useRef(false);
+    const [pinnedNodes, setPinnedNodes] = useState<Set<string>>(new Set());
+    const internalDragEnabledRef = useRef(enableDrag);
+    const [layout, setLayout] = useState<LayoutType>(externalLayout || 'force');
+
+    useEffect(() => {
+      if (externalLayout && externalLayout !== layout)
+        setLayout(externalLayout);
+    }, [externalLayout, layout]);
+
+    const handleLayoutChange = useCallback(
+      (newLayout: LayoutType) => {
+        setLayout(newLayout);
+        onLayoutChange?.(newLayout);
+      },
+      [onLayoutChange]
+    );
+
+    useEffect(() => {
+      internalDragEnabledRef.current = enableDrag;
+    }, [enableDrag]);
+
+    const { restart, stop, setForcesEnabled } = useSimulationControls();
+    const { nodes } = useGraphLayout(
+      initialNodes,
+      width,
+      height,
+      layout,
+      restart
+    );
+
+    useEffect(() => {
+      setForcesEnabled(!(manualLayout || pinnedNodes.size > 0));
+    }, [manualLayout, pinnedNodes, setForcesEnabled]);
+
+    useImperativeHandle(
+      ref,
+      () =>
+        useImperativeHandleMethods({
+          nodes,
+          pinnedNodes,
+          setPinnedNodes,
+          restart,
+          width,
+          height,
+          layout,
+          handleLayoutChange,
+          setForcesEnabled,
+          svgRef,
+          gRef,
+          setTransform,
+          internalDragEnabledRef,
+        }),
+      [
+        nodes,
+        pinnedNodes,
+        restart,
+        width,
+        height,
+        layout,
+        handleLayoutChange,
+        setForcesEnabled,
+      ]
+    );
+
+    useEffect(() => {
+      onManualLayoutChange?.(manualLayout);
+    }, [manualLayout, onManualLayoutChange]);
+
+    useGraphZoom(svgRef, gRef, enableZoom, setTransform, transformRef);
+    useWindowDrag(
+      enableDrag,
+      svgRef,
+      transformRef,
+      dragActiveRef,
+      dragNodeRef,
+      () => {
+        setForcesEnabled(true);
+        restart();
+      }
+    );
+
+    useEffect(() => {
+      if (!gRef.current) return;
+      const g = d3.select(gRef.current);
+      g.selectAll('g.node').each(function (this: any) {
+        const d = d3.select(this).datum() as any;
+        if (d)
+          d3.select(this).attr(
+            'transform',
+            `translate(${d.x || 0},${d.y || 0})`
+          );
+      });
+      g.selectAll('line').each(function (this: any) {
+        const l = d3.select(this).datum() as any;
+        if (!l) return;
+        const s =
+          typeof l.source === 'object'
+            ? l.source
+            : nodes.find((n) => n.id === l.source);
+        const t =
+          typeof l.target === 'object'
+            ? l.target
+            : nodes.find((n) => n.id === l.target);
+        if (s && t)
+          d3.select(this)
+            .attr('x1', s.x)
+            .attr('y1', s.y)
+            .attr('x2', t.x)
+            .attr('y2', t.y);
+      });
+    }, [nodes, initialLinks]);
+
+    const { handleDragStart, handleNodeDoubleClick } = useNodeInteractions(
+      enableDrag,
+      nodes,
+      pinnedNodes,
+      setPinnedNodes,
+      restart,
+      stop
+    );
+
+    useEffect(() => {
+      if (!gRef.current || !enableDrag) return;
+      const g = d3.select(gRef.current);
+      const dragBehavior = (d3 as any)
+        .drag()
+        .on('start', (event: any) => {
+          const target = (event.sourceEvent?.target || event.target) as Element;
+          const id = target.closest?.('g.node')?.getAttribute('data-id');
+          if (!id || !internalDragEnabledRef.current) return;
+          const node = nodes.find((n) => n.id === id);
+          if (!node) return;
+          if (!event.active) restart();
+          dragActiveRef.current = true;
+          dragNodeRef.current = node;
+        })
+        .on('drag', (event: any) => {
+          if (!dragActiveRef.current || !dragNodeRef.current || !svgRef.current)
+            return;
+          const rect = svgRef.current.getBoundingClientRect();
+          dragNodeRef.current.fx =
+            (event.sourceEvent.clientX - rect.left - transform.x) / transform.k;
+          dragNodeRef.current.fy =
+            (event.sourceEvent.clientY - rect.top - transform.y) / transform.k;
+        })
+        .on('end', () => {
+          setForcesEnabled(true);
+          restart();
+        });
+
+      g.selectAll('g.node').call(dragBehavior);
+      return () => {
+        g.selectAll('g.node').on('.drag', null);
+      };
+    }, [gRef, enableDrag, nodes, transform, restart, setForcesEnabled]);
+
+    return (
+      <GraphCanvas
+        svgRef={svgRef}
+        gRef={gRef}
+        width={width}
+        height={height}
+        className={className}
+        nodes={nodes}
+        links={initialLinks}
+        pinnedNodes={pinnedNodes}
+        selectedNodeId={selectedNodeId}
+        hoveredNodeId={hoveredNodeId}
+        defaultNodeColor={defaultNodeColor}
+        defaultNodeSize={defaultNodeSize}
+        defaultLinkColor={defaultLinkColor}
+        defaultLinkWidth={defaultLinkWidth}
+        showNodeLabels={showNodeLabels}
+        showLinkLabels={showLinkLabels}
+        onNodeClick={onNodeClick}
+        onNodeHover={onNodeHover}
+        onLinkClick={onLinkClick}
+        packageBounds={packageBounds}
+        handleNodeDoubleClick={handleNodeDoubleClick}
+        handleDragStart={handleDragStart}
+        restart={restart}
+        setPinnedNodes={setPinnedNodes}
+      />
+    );
+  }
+);
+
+ForceDirectedGraph.displayName = 'ForceDirectedGraph';

package/src/charts/force-directed/GraphCanvas.tsx

@@ -0,0 +1,129 @@
+import React from 'react';
+import { cn } from '../../utils/cn';
+import NodeItem from '../NodeItem';
+import LinkItem from '../LinkItem';
+import { PackageBoundaries } from '../PackageBoundaries';
+import {
+  DEFAULT_NODE_COLOR,
+  DEFAULT_NODE_SIZE,
+  DEFAULT_LINK_COLOR,
+  DEFAULT_LINK_WIDTH,
+} from '../constants';
+import { GraphNode, GraphLink, ForceDirectedGraphProps } from './types';
+import { unpinAllNodes } from './useGraphInteractions';
+
+interface GraphCanvasProps extends Pick<
+  ForceDirectedGraphProps,
+  | 'width'
+  | 'height'
+  | 'className'
+  | 'selectedNodeId'
+  | 'hoveredNodeId'
+  | 'defaultNodeColor'
+  | 'defaultNodeSize'
+  | 'defaultLinkColor'
+  | 'defaultLinkWidth'
+  | 'showNodeLabels'
+  | 'showLinkLabels'
+  | 'onNodeClick'
+  | 'onNodeHover'
+  | 'onLinkClick'
+  | 'packageBounds'
+> {
+  svgRef: React.RefObject<SVGSVGElement | null>;
+  gRef: React.RefObject<SVGGElement | null>;
+  nodes: GraphNode[];
+  links: GraphLink[];
+  pinnedNodes: Set<string>;
+  handleNodeDoubleClick: (e: React.MouseEvent, node: GraphNode) => void;
+  handleDragStart: (e: React.MouseEvent, node: GraphNode) => void;
+  restart: () => void;
+  setPinnedNodes: React.Dispatch<React.SetStateAction<Set<string>>>;
+}
+
+export const GraphCanvas: React.FC<GraphCanvasProps> = ({
+  svgRef,
+  gRef,
+  width,
+  height,
+  className,
+  nodes,
+  links,
+  pinnedNodes,
+  selectedNodeId,
+  hoveredNodeId,
+  defaultNodeColor = DEFAULT_NODE_COLOR,
+  defaultNodeSize = DEFAULT_NODE_SIZE,
+  defaultLinkColor = DEFAULT_LINK_COLOR,
+  defaultLinkWidth = DEFAULT_LINK_WIDTH,
+  showNodeLabels = true,
+  showLinkLabels = false,
+  onNodeClick,
+  onNodeHover,
+  onLinkClick,
+  packageBounds,
+  handleNodeDoubleClick,
+  handleDragStart,
+  restart,
+  setPinnedNodes,
+}) => {
+  return (
+    <svg
+      ref={svgRef}
+      width={width}
+      height={height}
+      className={cn('bg-white dark:bg-gray-900', className)}
+      onDoubleClick={() => {
+        unpinAllNodes(nodes);
+        setPinnedNodes(new Set());
+        restart();
+      }}
+    >
+      <defs>
+        <marker
+          id="arrow"
+          viewBox="0 0 10 10"
+          refX="20"
+          refY="5"
+          markerWidth="6"
+          markerHeight="6"
+          orient="auto"
+        >
+          <path d="M 0 0 L 10 5 L 0 10 z" fill={defaultLinkColor} />
+        </marker>
+      </defs>
+
+      <g ref={gRef}>
+        {links.map((link, i) => (
+          <LinkItem
+            key={`link-${i}`}
+            link={link as GraphLink}
+            onClick={onLinkClick}
+            defaultWidth={defaultLinkWidth}
+            showLabel={showLinkLabels}
+            nodes={nodes}
+          />
+        ))}
+
+        {nodes.map((node) => (
+          <NodeItem
+            key={node.id}
+            node={node}
+            isSelected={selectedNodeId === node.id}
+            isHovered={hoveredNodeId === node.id}
+            pinned={pinnedNodes.has(node.id)}
+            defaultNodeSize={defaultNodeSize}
+            defaultNodeColor={defaultNodeColor}
+            showLabel={showNodeLabels}
+            onClick={onNodeClick}
+            onDoubleClick={handleNodeDoubleClick}
+            onMouseEnter={(n) => onNodeHover?.(n)}
+            onMouseLeave={() => onNodeHover?.(null)}
+            onMouseDown={handleDragStart}
+          />
+        ))}
+        <PackageBoundaries packageBounds={packageBounds || {}} />
+      </g>
+    </svg>
+  );
+};

package/src/charts/{GraphControls.tsx → force-directed/GraphControls.tsx}

@@ -1,81 +1,23 @@
 import React from 'react';
-import { cn } from '../utils/cn';
+import { cn } from '../../utils/cn';
+import { ControlButton } from './ControlButton';
 
 export interface GraphControlsProps {
-  /**
-   * Whether dragging is enabled
-   */
   dragEnabled?: boolean;
-
-  /**
-   * Callback to toggle drag mode
-   * @param enabled - True when drag mode should be enabled, false when disabled
-   */
   onDragToggle?: (enabled: boolean) => void;
-
-  /**
-   * Whether manual layout mode is enabled
-   */
   manualLayout?: boolean;
-
-  /**
-   * Callback to toggle manual layout mode
-   * @param enabled - True when manual layout should be enabled, false when disabled
-   */
   onManualLayoutToggle?: (enabled: boolean) => void;
-
-  /**
-   * Callback to pin all nodes
-   */
   onPinAll?: () => void;
-
-  /**
-   * Callback to unpin all nodes
-   */
   onUnpinAll?: () => void;
-
-  /**
-   * Callback to center/reset the view
-   */
   onReset?: () => void;
-
-  /**
-   * Callback to fit all nodes in view
-   */
   onFitView?: () => void;
-
-  /**
-   * Number of pinned nodes
-   */
   pinnedCount?: number;
-
-  /**
-   * Total number of nodes
-   */
   totalNodes?: number;
-
-  /**
-   * Whether to show the controls
-   * @default true
-   */
   visible?: boolean;
-
-  /**
-   * Position of the controls
-   * @default "top-left"
-   */
   position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
-
-  /**
-   * Additional CSS classes
-   */
   className?: string;
 }
 
-/**
- * GraphControls: Floating toolbar for manipulating graph layout and dragging
- * Provides controls for toggling drag mode, manual layout, pinning nodes, and resetting the view
- */
 export const GraphControls: React.FC<GraphControlsProps> = ({
   dragEnabled = true,
   onDragToggle,
@@ -100,35 +42,6 @@ export const GraphControls: React.FC<GraphControlsProps> = ({
     'bottom-right': 'bottom-4 right-4',
   };
 
-  const ControlButton: React.FC<{
-    onClick: () => void;
-    active?: boolean;
-    icon: string;
-    label: string;
-    disabled?: boolean;
-  }> = ({ onClick, active = false, icon, label, disabled = false }) => (
-    <div className="relative group">
-      <button
-        onClick={onClick}
-        disabled={disabled}
-        className={cn(
-          'p-2 rounded-lg transition-all duration-200',
-          active
-            ? 'bg-blue-500 text-white shadow-md hover:bg-blue-600'
-            : 'bg-gray-100 text-gray-700 hover:bg-gray-200',
-          disabled && 'opacity-50 cursor-not-allowed hover:bg-gray-100',
-          'dark:bg-gray-700 dark:text-gray-200 dark:hover:bg-gray-600 dark:active:bg-blue-600'
-        )}
-        title={label}
-      >
-        <span className="text-lg">{icon}</span>
-      </button>
-      <div className="absolute left-full ml-2 px-2 py-1 bg-gray-900 text-white text-xs rounded whitespace-nowrap opacity-0 group-hover:opacity-100 transition-opacity duration-200 pointer-events-none z-50">
-        {label}
-      </div>
-    </div>
-  );
-
   return (
     <div
       className={cn(
@@ -138,7 +51,6 @@ export const GraphControls: React.FC<GraphControlsProps> = ({
       )}
     >
       <div className="flex flex-col gap-2">
-        {/* Drag Mode Toggle */}
         <ControlButton
           onClick={() => onDragToggle?.(!dragEnabled)}
           active={dragEnabled}
@@ -146,22 +58,15 @@ export const GraphControls: React.FC<GraphControlsProps> = ({
           label={dragEnabled ? 'Drag enabled' : 'Drag disabled'}
         />
 
-        {/* Manual Layout Toggle */}
         <ControlButton
           onClick={() => onManualLayoutToggle?.(!manualLayout)}
           active={manualLayout}
           icon="🔧"
-          label={
-            manualLayout
-              ? 'Manual layout: ON (drag freely)'
-              : 'Manual layout: OFF (forces active)'
-          }
+          label={manualLayout ? 'Manual layout: ON' : 'Manual layout: OFF'}
         />
 
-        {/* Divider */}
         <div className="w-8 h-px bg-gray-300 dark:bg-gray-600 mx-auto my-1" />
 
-        {/* Pin/Unpin Controls */}
         <div className="flex gap-1">
           <ControlButton
             onClick={() => onPinAll?.()}
@@ -177,10 +82,8 @@ export const GraphControls: React.FC<GraphControlsProps> = ({
           />
         </div>
 
-        {/* Divider */}
         <div className="w-8 h-px bg-gray-300 dark:bg-gray-600 mx-auto my-1" />
 
-        {/* View Controls */}
         <ControlButton
           onClick={() => onFitView?.()}
           disabled={totalNodes === 0}
@@ -196,7 +99,6 @@ export const GraphControls: React.FC<GraphControlsProps> = ({
         />
       </div>
 
-      {/* Info Panel */}
       <div className="mt-3 pt-3 border-t border-gray-200 dark:border-gray-700 text-xs text-gray-600 dark:text-gray-400">
         <div className="whitespace-nowrap">
           <strong>Nodes:</strong> {totalNodes}
@@ -206,15 +108,6 @@ export const GraphControls: React.FC<GraphControlsProps> = ({
             <strong>Pinned:</strong> {pinnedCount}
           </div>
         )}
-        <div className="mt-2 text-gray-500 dark:text-gray-500 leading-snug">
-          <strong>Tips:</strong>
-          <ul className="mt-1 ml-1 space-y-0.5">
-            <li>• Drag nodes to reposition</li>
-            <li>• Double-click to pin/unpin</li>
-            <li>• Double-click canvas to unpin all</li>
-            <li>• Scroll to zoom</li>
-          </ul>
-        </div>
       </div>
     </div>
   );

package/src/charts/force-directed/index.ts

@@ -0,0 +1,31 @@
+// Re-export types
+export type {
+  GraphNode,
+  GraphLink,
+  LayoutType,
+  ForceDirectedGraphHandle,
+  ForceDirectedGraphProps,
+} from './types';
+
+// Re-export hooks
+export {
+  pinNode,
+  unpinNode,
+  unpinAllNodes,
+  useGraphZoom,
+  useWindowDrag,
+  useNodeInteractions,
+} from './useGraphInteractions';
+
+export { useGraphLayout, useSimulationControls } from './useGraphLayout';
+export { useImperativeHandleMethods } from './useImperativeHandle';
+
+// Re-export components
+export { GraphControls } from './GraphControls';
+export type { GraphControlsProps } from './GraphControls';
+export { ControlButton } from './ControlButton';
+export type { ControlButtonProps } from './ControlButton';
+export { GraphCanvas } from './GraphCanvas';
+
+// Re-export the main component
+export { ForceDirectedGraph } from './ForceDirectedGraph';

package/src/charts/force-directed/types.ts

@@ -0,0 +1,102 @@
+import type { BaseGraphNode, BaseGraphLink } from '@aiready/core/client';
+
+/**
+ * Graph node extending core BaseGraphNode with component-specific properties
+ */
+export interface GraphNode extends BaseGraphNode {
+  label?: string;
+  color?: string;
+  size?: number;
+  group?: string;
+  kind?: 'file' | 'package';
+  packageGroup?: string;
+}
+
+/**
+ * Graph link extending core BaseGraphLink with component-specific properties
+ */
+export interface GraphLink extends BaseGraphLink {
+  color?: string;
+  width?: number;
+  label?: string;
+  type?: string;
+}
+
+export type LayoutType = 'force' | 'hierarchical' | 'circular';
+
+/**
+ * Handle for imperative actions on the ForceDirectedGraph.
+ */
+export interface ForceDirectedGraphHandle {
+  /** Pins all nodes to their current positions. */
+  pinAll: () => void;
+  /** Unpins all nodes, allowing them to move freely in the simulation. */
+  unpinAll: () => void;
+  /** Resets the layout by unpinning all nodes and restarting the simulation. */
+  resetLayout: () => void;
+  /** Rescales and re-centers the view to fit all nodes. */
+  fitView: () => void;
+  /** Returns the IDs of all currently pinned nodes. */
+  getPinnedNodes: () => string[];
+  /**
+   * Enable or disable drag mode for nodes.
+   * @param enabled - When true, nodes can be dragged; when false, dragging is disabled
+   */
+  setDragMode: (enabled: boolean) => void;
+  /** Sets the current layout type. */
+  setLayout: (layout: LayoutType) => void;
+  /** Gets the current layout type. */
+  getLayout: () => LayoutType;
+}
+
+/**
+ * Props for the ForceDirectedGraph component.
+ */
+export interface ForceDirectedGraphProps {
+  /** Array of node objects to render. */
+  nodes: GraphNode[];
+  /** Array of link objects to render. */
+  links: GraphLink[];
+  /** Width of the SVG canvas. */
+  width: number;
+  /** Height of the SVG canvas. */
+  height: number;
+  /** Whether to enable zoom and pan interactions. */
+  enableZoom?: boolean;
+  /** Whether to enable node dragging. */
+  enableDrag?: boolean;
+  /** Callback fired when a node is clicked. */
+  onNodeClick?: (node: GraphNode) => void;
+  /** Callback fired when a node is hovered. */
+  onNodeHover?: (node: GraphNode | null) => void;
+  /** Callback fired when a link is clicked. */
+  onLinkClick?: (link: GraphLink) => void;
+  /** ID of the currently selected node. */
+  selectedNodeId?: string;
+  /** ID of the currently hovered node. */
+  hoveredNodeId?: string;
+  /** Default fallback color for nodes. */
+  defaultNodeColor?: string;
+  /** Default fallback size for nodes. */
+  defaultNodeSize?: number;
+  /** Default fallback color for links. */
+  defaultLinkColor?: string;
+  /** Default fallback width for links. */
+  defaultLinkWidth?: number;
+  /** Whether to show labels on nodes. */
+  showNodeLabels?: boolean;
+  /** Whether to show labels on links. */
+  showLinkLabels?: boolean;
+  /** Additional CSS classes for the SVG element. */
+  className?: string;
+  /** Whether manual layout mode is active. */
+  manualLayout?: boolean;
+  /** Callback fired when manual layout mode changes. */
+  onManualLayoutChange?: (enabled: boolean) => void;
+  /** Optional bounds for package groups. */
+  packageBounds?: Record<string, { x: number; y: number; r: number }>;
+  /** Current layout algorithm. */
+  layout?: LayoutType;
+  /** Callback fired when layout changes. */
+  onLayoutChange?: (layout: LayoutType) => void;
+}