@aiready/components 0.1.0

package/src/hooks/useForceSimulation.ts

@@ -0,0 +1,328 @@
+import { useEffect, useRef, useState } from 'react';
+import * as d3 from 'd3';
+
+export interface SimulationNode extends d3.SimulationNodeDatum {
+  id: string;
+  [key: string]: any;
+}
+
+export interface SimulationLink extends d3.SimulationLinkDatum<SimulationNode> {
+  source: string | SimulationNode;
+  target: string | SimulationNode;
+  [key: string]: any;
+}
+
+export interface ForceSimulationOptions {
+  /**
+   * Strength of the charge force (repulsion between nodes)
+   * @default -300
+   */
+  chargeStrength?: number;
+
+  /**
+   * Distance for links between nodes
+   * @default 100
+   */
+  linkDistance?: number;
+
+  /**
+   * Strength of the link force
+   * @default 1
+   */
+  linkStrength?: number;
+
+  /**
+   * Strength of collision detection
+   * @default 1
+   */
+  collisionStrength?: number;
+
+  /**
+   * Radius for collision detection (node size)
+   * @default 10
+   */
+  collisionRadius?: number;
+
+  /**
+   * Strength of centering force
+   * @default 0.1
+   */
+  centerStrength?: number;
+
+  /**
+   * Width of the simulation space
+   */
+  width: number;
+
+  /**
+   * Height of the simulation space
+   */
+  height: number;
+
+  /**
+   * Alpha decay rate (how quickly the simulation cools down)
+   * @default 0.0228
+   */
+  alphaDecay?: number;
+
+  /**
+   * Velocity decay (friction)
+   * @default 0.4
+   */
+  velocityDecay?: number;
+}
+
+export interface UseForceSimulationReturn {
+  /**
+   * Current nodes with positions
+   */
+  nodes: SimulationNode[];
+
+  /**
+   * Current links
+   */
+  links: SimulationLink[];
+
+  /**
+   * Restart the simulation
+   */
+  restart: () => void;
+
+  /**
+   * Stop the simulation
+   */
+  stop: () => void;
+
+  /**
+   * Whether the simulation is currently running
+   */
+  isRunning: boolean;
+
+  /**
+   * Current alpha value (simulation heat)
+   */
+  alpha: number;
+}
+
+/**
+ * Hook for managing d3-force simulations
+ * Automatically handles simulation lifecycle, tick updates, and cleanup
+ *
+ * @param initialNodes - Initial nodes for the simulation
+ * @param initialLinks - Initial links for the simulation
+ * @param options - Configuration options for the force simulation
+ * @returns Simulation state and control functions
+ *
+ * @example
+ * ```tsx
+ * function NetworkGraph() {
+ *   const nodes = [
+ *     { id: 'node1', name: 'Node 1' },
+ *     { id: 'node2', name: 'Node 2' },
+ *     { id: 'node3', name: 'Node 3' },
+ *   ];
+ *
+ *   const links = [
+ *     { source: 'node1', target: 'node2' },
+ *     { source: 'node2', target: 'node3' },
+ *   ];
+ *
+ *   const { nodes: simulatedNodes, links: simulatedLinks, restart } = useForceSimulation(
+ *     nodes,
+ *     links,
+ *     {
+ *       width: 800,
+ *       height: 600,
+ *       chargeStrength: -500,
+ *       linkDistance: 150,
+ *     }
+ *   );
+ *
+ *   return (
+ *     <svg width={800} height={600}>
+ *       {simulatedLinks.map((link, i) => (
+ *         <line
+ *           key={i}
+ *           x1={(link.source as SimulationNode).x}
+ *           y1={(link.source as SimulationNode).y}
+ *           x2={(link.target as SimulationNode).x}
+ *           y2={(link.target as SimulationNode).y}
+ *           stroke="#999"
+ *         />
+ *       ))}
+ *       {simulatedNodes.map((node) => (
+ *         <circle
+ *           key={node.id}
+ *           cx={node.x}
+ *           cy={node.y}
+ *           r={10}
+ *           fill="#69b3a2"
+ *         />
+ *       ))}
+ *     </svg>
+ *   );
+ * }
+ * ```
+ */
+export function useForceSimulation(
+  initialNodes: SimulationNode[],
+  initialLinks: SimulationLink[],
+  options: ForceSimulationOptions
+): UseForceSimulationReturn {
+  const {
+    chargeStrength = -300,
+    linkDistance = 100,
+    linkStrength = 1,
+    collisionStrength = 1,
+    collisionRadius = 10,
+    centerStrength = 0.1,
+    width,
+    height,
+    alphaDecay = 0.0228,
+    velocityDecay = 0.4,
+  } = options;
+
+  const [nodes, setNodes] = useState<SimulationNode[]>(initialNodes);
+  const [links, setLinks] = useState<SimulationLink[]>(initialLinks);
+  const [isRunning, setIsRunning] = useState(false);
+  const [alpha, setAlpha] = useState(1);
+
+  const simulationRef = useRef<d3.Simulation<SimulationNode, SimulationLink> | null>(null);
+
+  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 }));
+
+    // Create the simulation
+    const simulation = d3
+      .forceSimulation<SimulationNode>(nodesCopy)
+      .force(
+        'link',
+        d3
+          .forceLink<SimulationNode, SimulationLink>(linksCopy)
+          .id((d) => d.id)
+          .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(collisionRadius).strength(collisionStrength)
+      )
+      .alphaDecay(alphaDecay)
+      .velocityDecay(velocityDecay);
+
+    simulationRef.current = simulation;
+
+    // Update state on each tick
+    simulation.on('tick', () => {
+      setNodes([...nodesCopy]);
+      setLinks([...linksCopy]);
+      setAlpha(simulation.alpha());
+      setIsRunning(simulation.alpha() > simulation.alphaMin());
+    });
+
+    simulation.on('end', () => {
+      setIsRunning(false);
+    });
+
+    // Cleanup on unmount
+    return () => {
+      simulation.stop();
+    };
+  }, [
+    initialNodes,
+    initialLinks,
+    chargeStrength,
+    linkDistance,
+    linkStrength,
+    collisionStrength,
+    collisionRadius,
+    centerStrength,
+    width,
+    height,
+    alphaDecay,
+    velocityDecay,
+  ]);
+
+  const restart = () => {
+    if (simulationRef.current) {
+      simulationRef.current.alpha(1).restart();
+      setIsRunning(true);
+    }
+  };
+
+  const stop = () => {
+    if (simulationRef.current) {
+      simulationRef.current.stop();
+      setIsRunning(false);
+    }
+  };
+
+  return {
+    nodes,
+    links,
+    restart,
+    stop,
+    isRunning,
+    alpha,
+  };
+}
+
+/**
+ * Hook for creating a draggable force simulation
+ * Provides drag handlers that can be attached to node elements
+ *
+ * @param simulation - The d3 force simulation instance
+ * @returns Drag behavior that can be applied to nodes
+ *
+ * @example
+ * ```tsx
+ * function DraggableNetworkGraph() {
+ *   const simulation = useRef<d3.Simulation<SimulationNode, SimulationLink>>();
+ *   const drag = useDrag(simulation.current);
+ *
+ *   return (
+ *     <svg>
+ *       {nodes.map((node) => (
+ *         <circle
+ *           key={node.id}
+ *           {...drag}
+ *           cx={node.x}
+ *           cy={node.y}
+ *           r={10}
+ *         />
+ *       ))}
+ *     </svg>
+ *   );
+ * }
+ * ```
+ */
+export function useDrag(simulation: d3.Simulation<SimulationNode, any> | null | undefined) {
+  const dragStarted = (event: any, node: SimulationNode) => {
+    if (!simulation) return;
+    if (!event.active) simulation.alphaTarget(0.3).restart();
+    node.fx = node.x;
+    node.fy = node.y;
+  };
+
+  const dragged = (event: any, node: SimulationNode) => {
+    node.fx = event.x;
+    node.fy = event.y;
+  };
+
+  const dragEnded = (event: any, node: SimulationNode) => {
+    if (!simulation) return;
+    if (!event.active) simulation.alphaTarget(0);
+    node.fx = null;
+    node.fy = null;
+  };
+
+  return {
+    onDragStart: dragStarted,
+    onDrag: dragged,
+    onDragEnd: dragEnded,
+  };
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+// Components
+export { Button, buttonVariants, type ButtonProps } from './components/button';
+export {
+  Card,
+  CardHeader,
+  CardFooter,
+  CardTitle,
+  CardDescription,
+  CardContent,
+} from './components/card';
+export { Input, type InputProps } from './components/input';
+export { Label, type LabelProps } from './components/label';
+export { Badge, badgeVariants, type BadgeProps } from './components/badge';
+
+// Layout Components
+export { Container, type ContainerProps } from './components/container';
+export { Grid, type GridProps } from './components/grid';
+export { Stack, type StackProps } from './components/stack';
+export { Separator, type SeparatorProps } from './components/separator';
+
+// Form Components
+export { Checkbox, type CheckboxProps } from './components/checkbox';
+export { RadioGroup, type RadioGroupProps, type RadioOption } from './components/radio-group';
+export { Switch, type SwitchProps } from './components/switch';
+export { Textarea, type TextareaProps } from './components/textarea';
+export { Select, type SelectProps, type SelectOption } from './components/select';
+
+// Utils
+export { cn } from './utils/cn';
+export * from './utils/colors';
+export * from './utils/formatters';
+
+// Hooks
+export { useDebounce } from './hooks/useDebounce';
+export { useD3, useD3WithResize } from './hooks/useD3';
+export {
+  useForceSimulation,
+  useDrag,
+  type SimulationNode,
+  type SimulationLink,
+  type ForceSimulationOptions,
+  type UseForceSimulationReturn,
+} from './hooks/useForceSimulation';
+
+// Charts
+export {
+  ForceDirectedGraph,
+  type GraphNode,
+  type GraphLink,
+  type ForceDirectedGraphProps,
+} from './charts/ForceDirectedGraph';

package/src/utils/cn.ts

@@ -0,0 +1,11 @@
+import { type ClassValue, clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+/**
+ * Merges class names using clsx and tailwind-merge
+ * @param inputs - Class values to merge
+ * @returns Merged class names
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/utils/colors.ts

@@ -0,0 +1,58 @@
+/**
+ * Color utilities for charts and visualizations
+ */
+
+// Severity colors for issue highlighting
+export const severityColors = {
+  critical: '#ef4444', // red-500
+  major: '#f59e0b', // amber-500
+  minor: '#eab308', // yellow-500
+  info: '#60a5fa', // blue-400
+} as const;
+
+// Domain colors for clustering and categorization
+export const domainColors = [
+  '#3b82f6', // blue-500
+  '#8b5cf6', // violet-500
+  '#ec4899', // pink-500
+  '#10b981', // green-500
+  '#f59e0b', // amber-500
+  '#06b6d4', // cyan-500
+  '#f97316', // orange-500
+  '#a855f7', // purple-500
+] as const;
+
+// Chart colors
+export const chartColors = {
+  primary: '#3b82f6',
+  success: '#10b981',
+  warning: '#f59e0b',
+  danger: '#ef4444',
+  info: '#06b6d4',
+} as const;
+
+/**
+ * Get a color for a domain/category by index
+ */
+export function getDomainColor(index: number): string {
+  return domainColors[index % domainColors.length];
+}
+
+/**
+ * Get severity color by level
+ */
+export function getSeverityColor(
+  severity: keyof typeof severityColors
+): string {
+  return severityColors[severity];
+}
+
+/**
+ * Convert hex color to RGBA
+ */
+export function hexToRgba(hex: string, alpha: number): string {
+  const r = parseInt(hex.slice(1, 3), 16);
+  const g = parseInt(hex.slice(3, 5), 16);
+  const b = parseInt(hex.slice(5, 7), 16);
+  return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+}

package/src/utils/formatters.ts

@@ -0,0 +1,161 @@
+/**
+ * Number formatting utilities for data visualization
+ */
+
+/**
+ * Format a number with commas for thousands
+ * @example formatNumber(1234567) => "1,234,567"
+ */
+export function formatNumber(value: number): string {
+  return new Intl.NumberFormat('en-US').format(value);
+}
+
+/**
+ * Format a number with K/M/B abbreviations
+ * @example formatCompactNumber(1234) => "1.2K"
+ * @example formatCompactNumber(1234567) => "1.2M"
+ */
+export function formatCompactNumber(value: number): string {
+  return new Intl.NumberFormat('en-US', {
+    notation: 'compact',
+    maximumFractionDigits: 1,
+  }).format(value);
+}
+
+/**
+ * Format a percentage with optional decimal places
+ * @example formatPercentage(0.1234) => "12.3%"
+ * @example formatPercentage(0.1234, 0) => "12%"
+ */
+export function formatPercentage(value: number, decimals: number = 1): string {
+  return `${(value * 100).toFixed(decimals)}%`;
+}
+
+/**
+ * Format file size in bytes to human-readable format
+ * @example formatFileSize(1024) => "1.0 KB"
+ * @example formatFileSize(1048576) => "1.0 MB"
+ */
+export function formatFileSize(bytes: number): string {
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let size = bytes;
+  let unitIndex = 0;
+
+  while (size >= 1024 && unitIndex < units.length - 1) {
+    size /= 1024;
+    unitIndex++;
+  }
+
+  return `${size.toFixed(1)} ${units[unitIndex]}`;
+}
+
+/**
+ * Format a date as relative time (e.g., "2 hours ago")
+ * @example formatRelativeTime(new Date(Date.now() - 3600000)) => "1 hour ago"
+ */
+export function formatRelativeTime(date: Date): string {
+  const now = new Date();
+  const diffMs = now.getTime() - date.getTime();
+  const diffSec = Math.floor(diffMs / 1000);
+  const diffMin = Math.floor(diffSec / 60);
+  const diffHour = Math.floor(diffMin / 60);
+  const diffDay = Math.floor(diffHour / 24);
+  const diffMonth = Math.floor(diffDay / 30);
+  const diffYear = Math.floor(diffDay / 365);
+
+  if (diffYear > 0) {
+    return `${diffYear} year${diffYear > 1 ? 's' : ''} ago`;
+  }
+  if (diffMonth > 0) {
+    return `${diffMonth} month${diffMonth > 1 ? 's' : ''} ago`;
+  }
+  if (diffDay > 0) {
+    return `${diffDay} day${diffDay > 1 ? 's' : ''} ago`;
+  }
+  if (diffHour > 0) {
+    return `${diffHour} hour${diffHour > 1 ? 's' : ''} ago`;
+  }
+  if (diffMin > 0) {
+    return `${diffMin} minute${diffMin > 1 ? 's' : ''} ago`;
+  }
+  return 'just now';
+}
+
+/**
+ * Format a date in short format (e.g., "Jan 15, 2024")
+ */
+export function formatDate(date: Date): string {
+  return new Intl.DateTimeFormat('en-US', {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+  }).format(date);
+}
+
+/**
+ * Format a date with time (e.g., "Jan 15, 2024 at 3:45 PM")
+ */
+export function formatDateTime(date: Date): string {
+  return new Intl.DateTimeFormat('en-US', {
+    year: 'numeric',
+    month: 'short',
+    day: 'numeric',
+    hour: 'numeric',
+    minute: '2-digit',
+    hour12: true,
+  }).format(date);
+}
+
+/**
+ * Format duration in milliseconds to human-readable format
+ * @example formatDuration(3661000) => "1h 1m 1s"
+ */
+export function formatDuration(ms: number): string {
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+
+  if (hours > 0) {
+    return `${hours}h ${minutes % 60}m ${seconds % 60}s`;
+  }
+  if (minutes > 0) {
+    return `${minutes}m ${seconds % 60}s`;
+  }
+  return `${seconds}s`;
+}
+
+/**
+ * Format a metric value with appropriate unit and precision
+ * Useful for displaying various metrics in charts
+ */
+export function formatMetric(
+  value: number,
+  unit: 'number' | 'bytes' | 'percentage' | 'duration' = 'number'
+): string {
+  switch (unit) {
+    case 'bytes':
+      return formatFileSize(value);
+    case 'percentage':
+      return formatPercentage(value);
+    case 'duration':
+      return formatDuration(value);
+    default:
+      return formatCompactNumber(value);
+  }
+}
+
+/**
+ * Format a range of values
+ * @example formatRange(100, 200) => "100 - 200"
+ */
+export function formatRange(min: number, max: number): string {
+  return `${formatCompactNumber(min)} - ${formatCompactNumber(max)}`;
+}
+
+/**
+ * Format a number with a specific number of decimal places
+ * @example formatDecimal(3.14159, 2) => "3.14"
+ */
+export function formatDecimal(value: number, decimals: number = 2): string {
+  return value.toFixed(decimals);
+}

package/tailwind.config.js

@@ -0,0 +1,46 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+  darkMode: ['class'],
+  content: ['./src/**/*.{ts,tsx}'],
+  theme: {
+    extend: {
+      colors: {
+        border: 'hsl(var(--border))',
+        input: 'hsl(var(--input))',
+        ring: 'hsl(var(--ring))',
+        background: 'hsl(var(--background))',
+        foreground: 'hsl(var(--foreground))',
+        primary: {
+          DEFAULT: 'hsl(var(--primary))',
+          foreground: 'hsl(var(--primary-foreground))',
+        },
+        secondary: {
+          DEFAULT: 'hsl(var(--secondary))',
+          foreground: 'hsl(var(--secondary-foreground))',
+        },
+        destructive: {
+          DEFAULT: 'hsl(var(--destructive))',
+          foreground: 'hsl(var(--destructive-foreground))',
+        },
+        muted: {
+          DEFAULT: 'hsl(var(--muted))',
+          foreground: 'hsl(var(--muted-foreground))',
+        },
+        accent: {
+          DEFAULT: 'hsl(var(--accent))',
+          foreground: 'hsl(var(--accent-foreground))',
+        },
+        card: {
+          DEFAULT: 'hsl(var(--card))',
+          foreground: 'hsl(var(--card-foreground))',
+        },
+      },
+      borderRadius: {
+        lg: 'var(--radius)',
+        md: 'calc(var(--radius) - 2px)',
+        sm: 'calc(var(--radius) - 4px)',
+      },
+    },
+  },
+  plugins: [],
+};