murnanedaniel ResearchPlanner .cursorrules file for TypeScript

# ResearchGraph Project Overview

!!!
Very important: Document all work in the .logs folder. For example, these files are already in the .logs folder:
- .logs/PROGRESS.md: Any new features should be documented here, with a short description and date
- .logs/REFACTOR.md: Any refactoring should be documented here, with a short description and date
- .logs/ISSUES.md: When working on any issues, always check if they are listed here already. If they are, add a comment to the issue with the date and your progress. If they are not, add the issue to the list.
!!!

## Project Structure

```
research-planner/
├── app/                      # Next.js app directory
│   ├── api/                  # API routes
│   │   └── autocomplete/     # AI feature endpoints
│   ├── page.tsx             # Main app page
│   └── layout.tsx           # Root layout
├── components/              
│   ├── ui/                  # Shared UI components
│   └── ResearchPlanner/     # Main application components
│       ├── components/      # Feature-specific components
│       │   ├── NodeGraph/   # Graph visualization
│       │   ├── SidePanel/   # Node/Edge editing
│       │   ├── Toolbar/     # Control buttons
│       │   └── shared/      # Shared components
│       ├── context/         # React Context providers
│       ├── hooks/           # Custom React hooks
│       ├── utils/           # Utility functions
│       └── types/           # TypeScript definitions
├── .logs/                   # Development documentation
└── __tests__/              # Integration tests
    └── components/
        └── ResearchPlanner/
            └── NodeGraph.test.tsx  # Main graph tests
```

## Core Components

### 1. ResearchPlanner (components/ResearchPlanner/ResearchPlanner.tsx)
Main orchestrator component that:
- Manages application state through hooks and context
- Handles user interactions and events
- Controls layout and rendering
- Manages feature integration

Key responsibilities:
- Node/Edge state management
- Selection handling
- Graph persistence
- Layout control
- Feature coordination

### 2. NodeGraph (components/ResearchPlanner/components/NodeGraph/)
Graph visualization system:
- Node.tsx: Individual node rendering and interactions
- Edge.tsx: Edge visualization and routing (TODO: implement)
- TimelineGrid.tsx: Timeline visualization
- Node.test.tsx: Co-located node tests

Features:
- Interactive node dragging
- Edge creation/editing
- Multi-select operations
- Timeline integration
- Zoom/pan controls

### 3. SidePanel (components/ResearchPlanner/components/SidePanel/)
Node and edge editing interface:
- SidePanel.tsx: Main component containing node/edge editing
  - Node editing functionality
  - Edge editing functionality
  - MDX integration for rich text
  - Property controls
- SidePanel.test.tsx: Component tests

### 4. Toolbar (components/ResearchPlanner/components/Toolbar/)
Control interface:
- Toolbar.tsx: Main component containing:
  - Node creation controls
  - Edge creation toggle
  - Timeline controls
  - AI feature controls
  - Graph operation buttons
- Toolbar.test.tsx: Component tests

## State Management

### 1. Context Providers (components/ResearchPlanner/context/)
- GraphContext.tsx: Core graph state
  - Nodes and edges
  - Timeline configuration
  - File operations
  - GraphContext.test.tsx: Context tests
- SelectionContext.tsx: Selection state
  - Single/multi selection
  - Start/goal nodes
  - Selection operations

### 2. Custom Hooks (components/ResearchPlanner/hooks/)
Active hooks:
- useNodeOperations.ts: Node manipulation (with tests)
- useEdgeOperations.ts: Edge handling (with tests)
- useGraphPersistence.ts: Storage operations (with tests)
- useLayoutManager.ts: Layout calculations
- useIdGenerator.ts: Unique ID management
- useColorGenerator.ts: Visual styling
- useTextFit.ts: Text sizing utilities

Placeholder hooks (to be implemented):
- useNodeSelection.ts: Node selection management
- useProjectStorage.ts: Project persistence

## Core Features

### 1. Node System
Data Structure:
```typescript
interface GraphNode {
    id: number;
    title: string;
    description: string;
    x: number;
    y: number;
    isObsolete: boolean;
    parentId?: number;
    childNodes?: number[];
    isExpanded?: boolean;
    hullPoints?: Point[];
    hullColor?: { fill: string; stroke: string };
}
```

Operations:
- Creation/deletion
- Position management
- Content editing
- Obsolescence marking
- Parent-child relationships
- Subgraph management

### 2. Edge System
Data Structure:
```typescript
interface Edge {
    id: number;
    source: number;
    target: number;
    title: string;
    description: string;
    isPlanned: boolean;
    isObsolete: boolean;
}
```

Operations:
- Interactive creation
- Direction management
- Content editing
- Status tracking
- Visibility control

### 3. Timeline System
Configuration:
```typescript
interface TimelineConfig {
        isActive: boolean;
        startDate: Date;
    pixelsPerUnit: number;
    scale: 'daily' | 'weekly' | 'monthly';
}
```

Features:
- Date-based grid
- Node snapping
- Scale adaptation
- Visual indicators
- Date management

### 4. Subgraph System
Features:
- Hierarchical nodes
- Expand/collapse
- Hull visualization
- Drag-drop organization
- Multi-level management

## Utility Functions (components/ResearchPlanner/utils/)

### 1. hull.ts
- Convex hull calculations for subgraphs
- Point padding and smoothing
- Visual boundary management

### 2. timeline.ts
- Date-grid calculations
- Snapping logic
- Scale management
- Position mapping

### 3. textFit.ts
- Text scaling calculations
- Responsive text fitting
- Size optimization

### 4. Placeholder Utils (to be implemented)
- storage.ts: Storage utilities
- layout.ts: Layout calculations

## Testing

### 1. Test-Driven Development (TDD)
Core principles:
- Write a simple test that describes the desired behavior
- Run the test and see it fail (Red phase)
- Write the minimum code to make the test pass (Green phase)
- Refactor if needed, keeping tests green (Refactor phase)

Guidelines:
- Keep tests focused on behavior, not implementation
- Start with the simplest possible test case
- Add complexity incrementally
- Avoid over-engineering test infrastructure
- If a test is hard to write, the design might be too complex

Example workflow:
```typescript
// 1. Write a simple test describing the behavior
it('should make node B a child of node A when ctrl-dropped', () => {
    // Arrange: Set up the minimum needed nodes
    // Act: Simulate ctrl-drop
    // Assert: Verify parent-child relationship
});

// 2. Run test, see it fail
// 3. Write minimum code to make it pass
// 4. Refactor if needed
```

### 2. Test Structure
Tests are organized in two ways:
- Integration tests in `__tests__/`
  - Focus on user-facing behavior
  - Test complete features
- Co-located component tests
  - Focus on component-specific behavior
  - Keep close to the implementation

### 3. Testing Strategy
- Start with behavior, not implementation
- Write tests before code
- Keep tests simple and focused
- Test one thing at a time
- Use meaningful test names that describe behavior

### 4. Test Coverage
Key behaviors to test:
- User interactions (clicks, drags, etc.)
- State changes
- Visual feedback
- Error cases

## Development Workflow

### 1. Documentation
All development work is documented in .logs/:
- PROGRESS.md: Feature implementation
- REFACTOR.md: Code improvements
- SUBGRAPH.md: Subgraph feature
- ISSUES.md: Known issues

### 2. Feature Development
1. Document design in .logs
2. Implement core functionality
3. Add tests
4. Update documentation

### 3. Code Style
- TypeScript for type safety
- React hooks for state
- Context for global state
- Tailwind for styling
- Jest for testing

## Performance Considerations

### 1. Rendering Optimization
- Selective re-renders
- Memoization
- Virtual scrolling
- Efficient updates

### 2. State Management
- Atomic updates
- Batch operations
- Context splitting
- State normalization

### 3. Layout Performance
- Efficient calculations
- Cached positions
- Optimized algorithms
- Lazy evaluation