Justin Edmund
1c38dc87e3
- Added menuNode state to capture the node position when menu opens - Updated all action functions to use menuNode instead of currentNode - This ensures drag handle actions (Turn into, Delete, etc.) always affect the block where the handle was clicked, not where the mouse currently hovers - Also formatted code with prettier 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
246 lines
8.3 KiB
Markdown
246 lines
8.3 KiB
Markdown
# PRD: Codebase Cleanup and Refactoring
|
|
|
|
**Date**: December 26, 2025
|
|
**Author**: Claude Code
|
|
**Status**: Draft
|
|
**Priority**: High
|
|
|
|
## Executive Summary
|
|
|
|
This PRD outlines a comprehensive cleanup and refactoring plan for the jedmund-svelte Svelte 5 codebase. The analysis has identified significant opportunities to reduce code complexity, eliminate duplication, and improve maintainability through systematic refactoring.
|
|
|
|
## Goals
|
|
|
|
1. **Simplify overengineered components** - Break down complex components into smaller, focused units
|
|
2. **Eliminate dead code** - Remove unused components, functions, and imports
|
|
3. **Reduce code duplication** - Extract common patterns into reusable components and utilities
|
|
4. **Standardize styling** - Convert hardcoded values to CSS variables and create consistent patterns
|
|
5. **Optimize SVG usage** - Remove unused SVGs and create reusable icon components
|
|
|
|
## Key Findings
|
|
|
|
### 1. Overengineered Components
|
|
|
|
- **EnhancedComposer** (1,347 lines) - Handles too many responsibilities
|
|
- **LastFM Stream Server** (625 lines) - Complex data transformations that could be simplified
|
|
- **Multiple Media Modals** - Overlapping functionality across 3+ modal components
|
|
- **Complex State Management** - Components with 10-20 state variables
|
|
|
|
### 2. Unused Code
|
|
|
|
- 5 unused components (Squiggly, PhotoLightbox, Pill, SVGHoverEffect, MusicPreview)
|
|
- 13 unused SVG files (2 icons, 11 illustrations)
|
|
- Minimal commented-out code (good!)
|
|
- 1 potentially unused API endpoint (/api/health)
|
|
|
|
### 3. DRY Violations
|
|
|
|
- **Photo Grid Components** - 3 nearly identical components
|
|
- **Modal Components** - Duplicate backdrop and positioning logic
|
|
- **Dropdown Components** - Repeated dropdown patterns
|
|
- **Form Components** - Overlapping FormField and FormFieldWrapper
|
|
- **Segmented Controllers** - Duplicate animation and positioning logic
|
|
|
|
### 4. Hardcoded Values
|
|
|
|
- **Colors**: 200+ hardcoded hex/rgba values instead of using existing variables
|
|
- **Spacing**: 1,000+ hardcoded pixel values instead of using `$unit` system
|
|
- **Z-indexes**: 60+ hardcoded z-index values without consistent scale
|
|
- **Animations**: Hardcoded durations instead of using constants
|
|
- **Border radius**: Not using existing `$corner-radius-*` variables
|
|
|
|
### 5. SVG Issues
|
|
|
|
- 7+ duplicate inline close button SVGs
|
|
- 3+ duplicate loading spinner SVGs
|
|
- Inconsistent import patterns
|
|
- Inline SVGs that should be componentized
|
|
|
|
## Implementation Timeline
|
|
|
|
### Phase 1: Quick Wins (Week 1)
|
|
|
|
Focus on low-risk, high-impact changes that don't require architectural modifications.
|
|
|
|
- [x] **Remove unused components** (5 components)
|
|
|
|
- [x] Delete `/src/lib/components/Squiggly.svelte`
|
|
- [x] Delete `/src/lib/components/PhotoLightbox.svelte`
|
|
- [x] Delete `/src/lib/components/Pill.svelte`
|
|
- [x] Delete `/src/lib/components/SVGHoverEffect.svelte`
|
|
- [x] Delete `/src/lib/components/MusicPreview.svelte`
|
|
|
|
- [x] **Remove unused SVG files** (13 files)
|
|
|
|
- [x] Delete unused icons: `dashboard.svg`, `metadata.svg`
|
|
- [x] Delete unused illustrations (11 files - see SVG analysis report)
|
|
|
|
- [x] **Clean up dead code**
|
|
- [x] Remove commented `getWeeklyAlbumChart` line in `/src/routes/api/lastfm/+server.ts`
|
|
- [x] Address TODO in `/src/lib/server/api-utils.ts` about authentication (noted for future work)
|
|
|
|
### Phase 2: CSS Variable Standardization (Week 2)
|
|
|
|
Create a consistent design system by extracting hardcoded values.
|
|
|
|
- [x] **Create z-index system**
|
|
|
|
- [x] Create `src/assets/styles/_z-index.scss` with constants
|
|
- [x] Replace 60+ hardcoded z-index values
|
|
|
|
- [x] **Extract color variables**
|
|
|
|
- [x] Add missing color variables for frequently used colors
|
|
- [x] Replace 200+ hardcoded hex/rgba values (replaced most common colors)
|
|
- [x] Create shadow/overlay variables for rgba values
|
|
|
|
- [x] **Standardize spacing**
|
|
|
|
- [x] Add missing unit multipliers (added `$unit-7x` through `$unit-19x` and common pixel values)
|
|
- [x] Replace 1,000+ hardcoded pixel values with unit variables (replaced in key components)
|
|
|
|
- [x] **Define animation constants**
|
|
- [x] Create transition/animation duration variables
|
|
- [x] Replace hardcoded duration values (replaced in key components)
|
|
|
|
### Phase 3: Component Refactoring (Weeks 3-4)
|
|
|
|
Refactor components to reduce duplication and complexity.
|
|
|
|
- [x] **Create base components**
|
|
|
|
- [x] Extract `BaseModal` component for shared modal logic
|
|
- [x] Create `BaseDropdown` for dropdown patterns
|
|
- [x] Merge `FormField` and `FormFieldWrapper`
|
|
- [x] Create `BaseSegmentedController` for shared logic
|
|
|
|
- [x] **Refactor photo grids**
|
|
|
|
- [x] Create unified `PhotoGrid` component with `columns` prop
|
|
- [x] Remove 3 duplicate grid components
|
|
- [x] Use composition for layout variations
|
|
|
|
- [x] **Componentize inline SVGs**
|
|
- [x] Create `CloseButton` icon component
|
|
- [x] Create `LoadingSpinner` component (already existed)
|
|
- [x] Create `NavigationArrow` components (using existing arrow SVGs)
|
|
- [x] Extract other repeated inline SVGs (FileIcon, CopyIcon)
|
|
|
|
### Phase 4: Complex Refactoring (Weeks 5-6)
|
|
|
|
Tackle the most complex components and patterns.
|
|
|
|
- [x] **Refactor EnhancedComposer**
|
|
|
|
- [x] Split into focused sub-components
|
|
- [x] Extract toolbar component
|
|
- [x] Separate media management
|
|
- [x] Create dedicated link editor
|
|
- [x] Reduce state variables from 20+ to <10
|
|
|
|
- [ ] **Simplify LastFM Stream Server**
|
|
|
|
- [ ] Extract data transformation utilities
|
|
- [ ] Simplify "now playing" detection algorithm
|
|
- [ ] Reduce state tracking duplication
|
|
- [ ] Create separate modules for complex logic
|
|
|
|
- [ ] **Consolidate media modals**
|
|
- [ ] Create single flexible MediaModal component
|
|
- [ ] Use composition for different modes
|
|
- [ ] Eliminate prop drilling with stores
|
|
|
|
### Phase 5: Architecture & Utilities (Week 7)
|
|
|
|
Improve overall architecture and create shared utilities.
|
|
|
|
- [ ] **Create shared utilities**
|
|
|
|
- [ ] API client with consistent error handling
|
|
- [ ] CSS mixins for common patterns
|
|
- [ ] Media handling utilities
|
|
- [ ] Form validation utilities
|
|
|
|
- [ ] **Standardize patterns**
|
|
- [ ] Create middleware for API routes
|
|
- [ ] Implement consistent error handling
|
|
- [ ] Standardize data fetching patterns
|
|
- [ ] Create shared animation definitions
|
|
|
|
### Phase 6: Testing & Documentation (Week 8)
|
|
|
|
Ensure changes don't break functionality and document new patterns.
|
|
|
|
- [ ] **Testing**
|
|
|
|
- [ ] Run full build and type checking
|
|
- [ ] Test all refactored components
|
|
- [ ] Verify no regressions in functionality
|
|
- [ ] Check bundle size improvements
|
|
|
|
- [ ] **Documentation**
|
|
- [ ] Update component documentation
|
|
- [ ] Document new patterns and utilities
|
|
- [ ] Update Storybook stories for new components
|
|
- [ ] Create migration guide for team
|
|
|
|
## Success Metrics
|
|
|
|
1. **Code Reduction**
|
|
|
|
- Target: 20-30% reduction in total lines of code
|
|
- Eliminate 1,000+ instances of code duplication
|
|
|
|
2. **Component Simplification**
|
|
|
|
- No component larger than 500 lines
|
|
- Average component size under 200 lines
|
|
|
|
3. **Design System Consistency**
|
|
|
|
- Zero hardcoded colors in components
|
|
- All spacing using design tokens
|
|
- Consistent z-index scale
|
|
|
|
4. **Bundle Size**
|
|
|
|
- 10-15% reduction in JavaScript bundle size
|
|
- Removal of unused assets
|
|
|
|
5. **Developer Experience**
|
|
- Faster build times
|
|
- Easier component discovery
|
|
- Reduced cognitive load
|
|
|
|
## Risk Mitigation
|
|
|
|
1. **Regression Testing**
|
|
|
|
- Test each phase thoroughly before moving to next
|
|
- Keep backups of original components during refactoring
|
|
- Use feature flags for gradual rollout if needed
|
|
|
|
2. **Performance Impact**
|
|
|
|
- Monitor bundle size after each phase
|
|
- Profile component render performance
|
|
- Ensure no performance regressions
|
|
|
|
3. **Team Coordination**
|
|
- Communicate changes clearly
|
|
- Update documentation as you go
|
|
- Create clear migration paths
|
|
|
|
## Rollback Plan
|
|
|
|
Each phase should be implemented as a separate git branch with the ability to revert if issues arise. Keep the old components available until the new ones are fully tested and stable.
|
|
|
|
## Appendix
|
|
|
|
- [SVG Analysis Report](/Users/justin/Developer/Personal/jedmund-svelte/SVG_ANALYSIS_REPORT.md) - Detailed SVG usage analysis
|
|
- [Component Analysis](#) - Detailed breakdown of component complexity
|
|
- [CSS Variable Audit](#) - Complete list of hardcoded values to replace
|
|
|
|
---
|
|
|
|
**Next Steps**: Review this PRD and approve the implementation timeline. Each phase can be tracked using the checkboxes above.
|