Refactor: Make v002 codebase more composable and modular

[ebowwa]

Overview

The current /workspaces/app-preview-generator/v002/app/page.tsx file is a monolithic component with 1779 lines of code. This issue proposes refactoring the codebase to be more composable and modular without breaking any existing functionality or making assumptions about implementation details.

Current State Analysis

File Statistics

• Lines of Code: 1779 lines
• Single Component: Everything is in one Home component
• Mixed Concerns: UI components, business logic, state management, event handlers, and utility functions are all combined

Identified Areas for Modularization

1. State Management (Lines 21-90)

   • Screen state
   • Drag states (device, text, asset, screenshot)
   • UI state (currentScreen, deviceType, showGrid)

2. Event Handlers & Drag Logic (Lines 136-395)

   • Mouse event handlers for dragging
   • Separate drag systems for screenshots, text, assets
   • Complex useEffect hooks for managing drag behavior

3. File Operations (Lines 399-464, 578-620)

   • Image upload handling
   • Asset upload handling
   • Project save/load functionality

4. Utility Functions (Lines 515-670)

   • Export functions
   • Transform calculations
   • Style generation

5. UI Components (Lines 673-1778)

   • Preview canvas
   • Device mockup
   • Screen selector with thumbnails
   • Control panels (4 tabs: Content, Style, Position, Export)
   • Form controls and inputs

Proposed Modular Structure

Components to Extract

1. components/preview/DeviceMockup.tsx

   • Device frame rendering
   • Background styles
   • Transform calculations

2. components/preview/ScreenshotLayer.tsx

   • Screenshot rendering
   • Multiple screenshot support
   • Legacy single screenshot fallback

3. components/preview/TextOverlay.tsx

   • Text overlay rendering
   • Overlay styles
   • Text positioning

4. components/preview/ImageAssets.tsx

   • Additional image asset rendering
   • Asset positioning and styling

5. components/screens/ScreenSelector.tsx

   • Screen thumbnails
   • Screen navigation
   • Add/remove screen functionality

6. components/controls/ContentTab.tsx

   • Screenshot management
   • Image asset management
   • Text content controls

7. components/controls/StyleTab.tsx

   • Background style controls
   • Color pickers
   • Device position controls
   • Layer order controls

8. components/controls/PositionTab.tsx

   • Screenshot position controls
   • Text position controls
   • Quick positioning buttons

9. components/controls/ExportTab.tsx

   • Device type selection
   • Export controls
   • Save/load project functionality

Hooks to Create

1. hooks/useDragAndDrop.ts

   • Generic drag handling logic
   • Mouse event management
   • Cursor and selection management

2. hooks/useScreenManagement.ts

   • Screen CRUD operations
   • Current screen state
   • Screen navigation

3. hooks/useFileOperations.ts

   • Image upload handling
   • Project save/load
   • Export functionality

4. hooks/useScreenshotManagement.ts

   • Screenshot CRUD operations
   • Multiple screenshot handling
   • Legacy compatibility

Utilities to Extract

1. utils/deviceTransforms.ts

   • Device position transforms
   • Device sizing calculations

2. utils/backgroundStyles.ts

   • Background style generation
   • Pattern generation
   • Gradient calculations

3. utils/export.ts

   • Canvas export logic
   • Image sizing and formatting
   • Batch export functionality

State Management Considerations

1. Context or State Management Library
   • Consider using React Context for shared state
   • Or implement a state management solution (Zustand, Jotai)
   • Keep local state where appropriate

Benefits of Modularization

1. Maintainability: Easier to locate and fix bugs
2. Reusability: Components can be reused in other parts of the application
3. Testing: Smaller units are easier to test
4. Performance: Potential for better React rendering optimization
5. Collaboration: Multiple developers can work on different components
6. Code Organization: Clear separation of concerns
7. Type Safety: Better TypeScript inference with smaller components

Implementation Guidelines

Requirements

• ✅ No functionality should be broken
• ✅ All existing features must continue to work
• ✅ No assumptions about implementation details
• ✅ Preserve all existing state management logic
• ✅ Maintain backward compatibility with saved projects
• ✅ Keep all drag-and-drop functionality intact

Best Practices to Follow

1. Start with extracting pure presentation components
2. Move to extracting hooks for logic reuse
3. Create utilities for pure functions
4. Test each extraction thoroughly
5. Maintain proper TypeScript types throughout
6. Document component interfaces clearly

Testing Strategy

1. Unit Tests: For individual components and utilities
2. Integration Tests: For hook interactions
3. E2E Tests: Ensure full functionality remains intact
4. Visual Regression: Ensure UI remains pixel-perfect

Migration Path

Phase 1: Extract Utilities

• Move pure functions to utility files
• No component changes needed

Phase 2: Extract Simple Components

• Start with leaf components (no children)
• Move presentation-only components

Phase 3: Extract Complex Components

• Extract components with local state
• Maintain prop drilling initially

Phase 4: Implement Hooks

• Extract reusable logic into hooks
• Reduce code duplication

Phase 5: Optimize State Management

• Consider state management solution
• Reduce prop drilling if needed

Acceptance Criteria

• File is split into logical, reusable components
• Each component/hook/utility has a single responsibility
• No functionality is lost or broken
• Code is well-organized and easy to navigate
• TypeScript types are properly maintained
• Performance is not negatively impacted
• All existing projects can still be loaded
• Documentation is updated to reflect new structure

Additional Notes

The current implementation works well but the monolithic structure makes it challenging to:

• Add new features without increasing complexity
• Debug specific functionality
• Onboard new developers
• Optimize performance for specific parts

This refactoring should be done incrementally to minimize risk and ensure stability throughout the process.

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com