Custom Folder System for Documents

[adriandarian]

Description

Implement a custom folder/directory system for organizing documents, allowing users to create nested folders with custom names and colors, drag-and-drop files, and manage their document library hierarchically.

---

Requirements

• Create folder data structure
• Build folder tree UI component
• Implement folder CRUD operations
• Add drag-and-drop for folders
• Add drag-and-drop for files to folders
• Support nested folders (unlimited depth)
• Add folder colors and icons
• Implement folder breadcrumb navigation
• Add folder search
• Show document count per folder
• Add folder sorting options
• Implement folder sharing/export

---

User Stories

As a user, I want to:

1. Create custom folders for my documents
2. Organize folders hierarchically (nested folders)
3. Choose colors and icons for folders
4. Drag files into folders easily
5. Move folders within the hierarchy
6. Search for folders by name
7. See document count in each folder
8. Navigate folders with breadcrumbs
9. Sort folders by name, date, or count
10. Delete folders (with safety confirmation)

---

Folder Features

Folder Properties

• Name: Custom name (required)
• Color: From predefined palette
• Icon: From icon library (optional)
• Description: Optional text
• Parent: Parent folder ID (null for root)
• Created: Timestamp
• Modified: Timestamp

Folder Actions

• Create new folder
• Rename folder
• Change folder color
• Change folder icon
• Move folder to different parent
• Delete folder (move contents to parent or delete all)
• Duplicate folder structure

Folder Views

• Tree view (collapsible)
• Grid view (with icons)
• List view (with details)

---

Acceptance Criteria

• Can create folders with custom names
• Can nest folders to any depth
• Can assign colors to folders
• Can assign icons to folders
• Can drag files into folders
• Can drag folders to reorganize
• Breadcrumb navigation works
• Folder search finds correct folders
• Document count displays correctly
• Can sort folders by multiple criteria
• Delete folder shows confirmation
• Folder operations persist to storage
• UI is intuitive and responsive

---

Technical Details

Data Structure

interface Folder {
  id: string;
  name: string;
  color: string;
  icon?: string;
  description?: string;
  parentId: string | null;
  documentIds: string[];
  createdAt: Date;
  updatedAt: Date;
  order: number;
}

interface FolderTree {
  folder: Folder;
  children: FolderTree[];
  documentCount: number;
}

Files to Create

• src/types/folder.ts
• src/stores/folderStore.ts
• src/components/documents/FolderTree.tsx
• src/components/documents/FolderItem.tsx
• src/components/documents/FolderDialog.tsx
• src/components/documents/FolderBreadcrumb.tsx
• src/hooks/useFolders.ts
• src/lib/folderOperations.ts

Dependencies

• @dnd-kit (for drag-and-drop)
• lucide-react (for icons)

---

UI Mockup

┌─ Documents ────────────────────────────────────┐
│  🔍 Search folders...              [+ New Folder]│
├────────────────────────────────────────────────┤
│  📁 Resumes (15)                               │
│    ├─ 📄 Software Engineering (8)             │
│    ├─ 📄 Data Science (5)                     │
│    └─ 📄 Archive (2)                          │
│  📁 Cover Letters (23)                         │
│    ├─ 📄 Tech Companies (15)                  │
│    └─ 📄 Startups (8)                         │
│  📁 Certifications (7)                         │
│  📁 Portfolio (12)                             │
└────────────────────────────────────────────────┘

---

Testing Plan

• Unit tests for folder operations
• Test nested folder creation
• Test folder drag-and-drop
• Test file drag into folders
• Test folder deletion (with/without contents)
• Test folder search
• Test breadcrumb navigation
• E2E test for complete workflow
• Performance test with 100+ folders

---

Related Tasks

• TASK-201: Tag System for Documents - 📋 Planned
• TASK-202: Smart Document Organization - 📋 Planned
• TASK-203: Folder Templates - 💡 Backlog

---

Notes

• Consider max nesting depth (e.g., 10 levels)
• Add folder templates (e.g., "Standard Resume Folder")
• Future: Add folder sharing/collaboration
• Future: Add folder automation rules