f319f29d4c
- Add functionality to create new collections via API - Implement copy and move operations between collections - Improve image rendering in markdown preview with relative path resolution - Add support for previewing binary files (images, PDFs) - Refactor modal styling to use flat buttons and improve accessibility
427 lines
9.1 KiB
Markdown
427 lines
9.1 KiB
Markdown
# UI Code Refactoring Plan
|
|
|
|
**Project:** Markdown Editor
|
|
**Date:** 2025-10-26
|
|
**Status:** In Progress
|
|
|
|
---
|
|
|
|
## Executive Summary
|
|
|
|
This document outlines a comprehensive refactoring plan for the UI codebase to improve maintainability, remove dead code, extract utilities, and standardize patterns. The refactoring is organized into 6 phases with 14 tasks, prioritized by risk and impact.
|
|
|
|
**Key Metrics:**
|
|
|
|
- Total Lines of Code: ~3,587
|
|
- Dead Code to Remove: 213 lines (6%)
|
|
- Estimated Effort: 5-8 days
|
|
- Risk Level: Mostly LOW to MEDIUM
|
|
|
|
---
|
|
|
|
## Phase 1: Analysis Summary
|
|
|
|
### Files Reviewed
|
|
|
|
**JavaScript Files (10):**
|
|
|
|
- `/static/js/app.js` (484 lines)
|
|
- `/static/js/column-resizer.js` (100 lines)
|
|
- `/static/js/confirmation.js` (170 lines)
|
|
- `/static/js/editor.js` (420 lines)
|
|
- `/static/js/file-tree-actions.js` (482 lines)
|
|
- `/static/js/file-tree.js` (865 lines)
|
|
- `/static/js/macro-parser.js` (103 lines)
|
|
- `/static/js/macro-processor.js` (157 lines)
|
|
- `/static/js/ui-utils.js` (305 lines)
|
|
- `/static/js/webdav-client.js` (266 lines)
|
|
|
|
**CSS Files (6):**
|
|
|
|
- `/static/css/variables.css` (32 lines)
|
|
- `/static/css/layout.css`
|
|
- `/static/css/file-tree.css`
|
|
- `/static/css/editor.css`
|
|
- `/static/css/components.css`
|
|
- `/static/css/modal.css`
|
|
|
|
**HTML Templates (1):**
|
|
|
|
- `/templates/index.html` (203 lines)
|
|
|
|
---
|
|
|
|
## Issues Found
|
|
|
|
### 🔴 HIGH PRIORITY
|
|
|
|
1. **Deprecated Modal Code (Dead Code)**
|
|
- Location: `/static/js/file-tree-actions.js` lines 262-474
|
|
- Impact: 213 lines of unused code (44% of file)
|
|
- Risk: LOW to remove
|
|
|
|
2. **Duplicated Event Bus Implementation**
|
|
- Location: `/static/js/app.js` lines 16-30
|
|
- Should be extracted to reusable module
|
|
|
|
3. **Duplicated Debounce Function**
|
|
- Location: `/static/js/editor.js` lines 404-414
|
|
- Should be shared utility
|
|
|
|
4. **Inconsistent Notification Usage**
|
|
- Mixed usage of `window.showNotification` vs `showNotification`
|
|
|
|
5. **Duplicated File Download Logic**
|
|
- Location: `/static/js/file-tree.js` lines 829-839
|
|
- Should be shared utility
|
|
|
|
6. **Hard-coded Values**
|
|
- Long-press threshold: 400ms
|
|
- Debounce delay: 300ms
|
|
- Drag preview width: 200px
|
|
- Toast delay: 3000ms
|
|
|
|
### 🟡 MEDIUM PRIORITY
|
|
|
|
7. **Global State Management**
|
|
- Location: `/static/js/app.js` lines 6-13
|
|
- Makes testing difficult
|
|
|
|
8. **Duplicated Path Manipulation**
|
|
- `path.split('/').pop()` appears 10+ times
|
|
- `path.substring(0, path.lastIndexOf('/'))` appears 5+ times
|
|
|
|
9. **Mixed Responsibility in ui-utils.js**
|
|
- Contains 6 different classes/utilities
|
|
- Should be split into separate modules
|
|
|
|
10. **Deprecated Event Handler**
|
|
- Location: `/static/js/file-tree-actions.js` line 329
|
|
- Uses deprecated `onkeypress`
|
|
|
|
### 🟢 LOW PRIORITY
|
|
|
|
11. **Unused Function Parameters**
|
|
12. **Magic Numbers in Styling**
|
|
13. **Inconsistent Comment Styles**
|
|
14. **Console.log Statements**
|
|
|
|
---
|
|
|
|
## Phase 2: Proposed Reusable Components
|
|
|
|
### 1. Config Module (`/static/js/config.js`)
|
|
|
|
Centralize all configuration values:
|
|
|
|
```javascript
|
|
export const Config = {
|
|
// Timing
|
|
LONG_PRESS_THRESHOLD: 400,
|
|
DEBOUNCE_DELAY: 300,
|
|
TOAST_DURATION: 3000,
|
|
|
|
// UI
|
|
DRAG_PREVIEW_WIDTH: 200,
|
|
TREE_INDENT_PX: 12,
|
|
MOUSE_MOVE_THRESHOLD: 5,
|
|
|
|
// Validation
|
|
FILENAME_PATTERN: /^[a-z0-9_]+(\.[a-z0-9_]+)*$/,
|
|
|
|
// Storage Keys
|
|
STORAGE_KEYS: {
|
|
DARK_MODE: 'darkMode',
|
|
SELECTED_COLLECTION: 'selectedCollection',
|
|
LAST_VIEWED_PAGE: 'lastViewedPage',
|
|
COLUMN_DIMENSIONS: 'columnDimensions'
|
|
}
|
|
};
|
|
```
|
|
|
|
### 2. Logger Module (`/static/js/logger.js`)
|
|
|
|
Structured logging with levels:
|
|
|
|
```javascript
|
|
export class Logger {
|
|
static debug(message, ...args)
|
|
static info(message, ...args)
|
|
static warn(message, ...args)
|
|
static error(message, ...args)
|
|
static setLevel(level)
|
|
}
|
|
```
|
|
|
|
### 3. Event Bus Module (`/static/js/event-bus.js`)
|
|
|
|
Centralized event system:
|
|
|
|
```javascript
|
|
export class EventBus {
|
|
on(event, callback)
|
|
off(event, callback)
|
|
once(event, callback)
|
|
dispatch(event, data)
|
|
clear(event)
|
|
}
|
|
```
|
|
|
|
### 4. Utilities Module (`/static/js/utils.js`)
|
|
|
|
Common utility functions:
|
|
|
|
```javascript
|
|
export const PathUtils = {
|
|
getFileName(path),
|
|
getParentPath(path),
|
|
normalizePath(path),
|
|
joinPaths(...paths),
|
|
getExtension(path)
|
|
};
|
|
|
|
export const TimingUtils = {
|
|
debounce(func, wait),
|
|
throttle(func, wait)
|
|
};
|
|
|
|
export const DownloadUtils = {
|
|
triggerDownload(content, filename),
|
|
downloadAsBlob(blob, filename)
|
|
};
|
|
|
|
export const ValidationUtils = {
|
|
validateFileName(name, isFolder),
|
|
sanitizeFileName(name)
|
|
};
|
|
```
|
|
|
|
### 5. Notification Service (`/static/js/notification-service.js`)
|
|
|
|
Standardized notifications:
|
|
|
|
```javascript
|
|
export class NotificationService {
|
|
static success(message)
|
|
static error(message)
|
|
static warning(message)
|
|
static info(message)
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Phase 3: Refactoring Tasks
|
|
|
|
### 🔴 HIGH PRIORITY
|
|
|
|
**Task 1: Remove Dead Code**
|
|
|
|
- Files: `/static/js/file-tree-actions.js`
|
|
- Lines: 262-474 (213 lines)
|
|
- Risk: LOW
|
|
- Dependencies: None
|
|
|
|
**Task 2: Extract Event Bus**
|
|
|
|
- Files: NEW `/static/js/event-bus.js`, MODIFY `app.js`, `editor.js`
|
|
- Risk: MEDIUM
|
|
- Dependencies: None
|
|
|
|
**Task 3: Create Utilities Module**
|
|
|
|
- Files: NEW `/static/js/utils.js`, MODIFY multiple files
|
|
- Risk: MEDIUM
|
|
- Dependencies: None
|
|
|
|
**Task 4: Create Config Module**
|
|
|
|
- Files: NEW `/static/js/config.js`, MODIFY multiple files
|
|
- Risk: LOW
|
|
- Dependencies: None
|
|
|
|
**Task 5: Standardize Notification Usage**
|
|
|
|
- Files: NEW `/static/js/notification-service.js`, MODIFY multiple files
|
|
- Risk: LOW
|
|
- Dependencies: None
|
|
|
|
### 🟡 MEDIUM PRIORITY
|
|
|
|
**Task 6: Fix Deprecated Event Handler**
|
|
|
|
- Files: `/static/js/file-tree-actions.js` line 329
|
|
- Risk: LOW
|
|
- Dependencies: None
|
|
|
|
**Task 7: Refactor ui-utils.js**
|
|
|
|
- Files: DELETE `ui-utils.js`, CREATE 5 new modules
|
|
- Risk: HIGH
|
|
- Dependencies: Task 5
|
|
|
|
**Task 8: Standardize Class Export Pattern**
|
|
|
|
- Files: All class files
|
|
- Risk: MEDIUM
|
|
- Dependencies: None
|
|
|
|
**Task 9: Create Logger Module**
|
|
|
|
- Files: NEW `/static/js/logger.js`, MODIFY multiple files
|
|
- Risk: LOW
|
|
- Dependencies: None
|
|
|
|
**Task 10: Implement Download Action**
|
|
|
|
- Files: `/static/js/file-tree-actions.js`
|
|
- Risk: LOW
|
|
- Dependencies: Task 3
|
|
|
|
### 🟢 LOW PRIORITY
|
|
|
|
**Task 11: Standardize JSDoc Comments**
|
|
**Task 12: Extract Magic Numbers to CSS**
|
|
**Task 13: Add Error Boundaries**
|
|
**Task 14: Cache DOM Elements**
|
|
|
|
---
|
|
|
|
## Phase 4: Implementation Order
|
|
|
|
### Step 1: Foundation (Do First)
|
|
|
|
1. Create Config Module (Task 4)
|
|
2. Create Logger Module (Task 9)
|
|
3. Create Event Bus Module (Task 2)
|
|
|
|
### Step 2: Utilities (Do Second)
|
|
|
|
4. Create Utilities Module (Task 3)
|
|
5. Create Notification Service (Task 5)
|
|
|
|
### Step 3: Cleanup (Do Third)
|
|
|
|
6. Remove Dead Code (Task 1)
|
|
7. Fix Deprecated Event Handler (Task 6)
|
|
|
|
### Step 4: Restructuring (Do Fourth)
|
|
|
|
8. Refactor ui-utils.js (Task 7)
|
|
9. Standardize Class Export Pattern (Task 8)
|
|
|
|
### Step 5: Enhancements (Do Fifth)
|
|
|
|
10. Implement Download Action (Task 10)
|
|
11. Add Error Boundaries (Task 13)
|
|
|
|
### Step 6: Polish (Do Last)
|
|
|
|
12. Standardize JSDoc Comments (Task 11)
|
|
13. Extract Magic Numbers to CSS (Task 12)
|
|
14. Cache DOM Elements (Task 14)
|
|
|
|
---
|
|
|
|
## Phase 5: Testing Checklist
|
|
|
|
### Core Functionality
|
|
|
|
- [ ] File tree loads and displays correctly
|
|
- [ ] Files can be selected and opened
|
|
- [ ] Folders can be expanded/collapsed
|
|
- [ ] Editor loads file content
|
|
- [ ] Preview renders markdown correctly
|
|
- [ ] Save button saves files
|
|
- [ ] Delete button deletes files
|
|
- [ ] New button creates new files
|
|
|
|
### Context Menu Actions
|
|
|
|
- [ ] Right-click shows context menu
|
|
- [ ] New file action works
|
|
- [ ] New folder action works
|
|
- [ ] Rename action works
|
|
- [ ] Delete action works
|
|
- [ ] Copy/Cut/Paste actions work
|
|
- [ ] Upload action works
|
|
|
|
### Drag and Drop
|
|
|
|
- [ ] Long-press detection works
|
|
- [ ] Drag preview appears correctly
|
|
- [ ] Drop targets highlight properly
|
|
- [ ] Files can be moved
|
|
- [ ] Undo (Ctrl+Z) works
|
|
|
|
### Modals
|
|
|
|
- [ ] Confirmation modals appear
|
|
- [ ] Prompt modals appear
|
|
- [ ] Modals don't double-open
|
|
- [ ] Enter/Escape keys work
|
|
|
|
### UI Features
|
|
|
|
- [ ] Dark mode toggle works
|
|
- [ ] Collection selector works
|
|
- [ ] Column resizers work
|
|
- [ ] Notifications appear
|
|
- [ ] URL routing works
|
|
- [ ] View/Edit modes work
|
|
|
|
---
|
|
|
|
## Recommendations
|
|
|
|
### Immediate Actions (Before Production)
|
|
|
|
1. Remove dead code (Task 1)
|
|
2. Fix deprecated event handler (Task 6)
|
|
3. Create config module (Task 4)
|
|
|
|
### Short-term Actions (Next Sprint)
|
|
|
|
4. Extract utilities (Task 3)
|
|
5. Standardize notifications (Task 5)
|
|
6. Create event bus (Task 2)
|
|
|
|
### Medium-term Actions (Future Sprints)
|
|
|
|
7. Refactor ui-utils.js (Task 7)
|
|
8. Add logger (Task 9)
|
|
9. Standardize exports (Task 8)
|
|
|
|
---
|
|
|
|
## Success Metrics
|
|
|
|
**Before Refactoring:**
|
|
|
|
- Total Lines: ~3,587
|
|
- Dead Code: 213 lines (6%)
|
|
- Duplicated Code: ~50 lines
|
|
- Hard-coded Values: 15+
|
|
|
|
**After Refactoring:**
|
|
|
|
- Total Lines: ~3,400 (-5%)
|
|
- Dead Code: 0 lines
|
|
- Duplicated Code: 0 lines
|
|
- Hard-coded Values: 0
|
|
|
|
**Estimated Effort:** 5-8 days
|
|
|
|
---
|
|
|
|
## Conclusion
|
|
|
|
The UI codebase is generally well-structured. Main improvements needed:
|
|
|
|
1. Remove dead code
|
|
2. Extract duplicated utilities
|
|
3. Centralize configuration
|
|
4. Standardize patterns
|
|
|
|
Start with high-impact, low-risk changes first to ensure production readiness.
|