jedmund-svelte/PRD-media-library.md

Product Requirements Document: Media Library Modal System

Overview

Implement a comprehensive Media Library modal system that provides a unified interface for browsing, selecting, and managing media across all admin forms. The primary workflow is direct upload from computer within forms, with the Media Library serving as a secondary browsing interface and management tool for previously uploaded content.

📋 Updated Approach Summary

🎯 Primary Focus: Direct upload components that allow users to drag-and-drop or browse files directly within project/post/album forms, with immediate preview and alt text capture.

🎯 Secondary Feature: Media Library modal for selecting previously uploaded content when needed.

🎯 Key Addition: Alt text storage and editing capabilities for accessibility compliance and SEO.

Goals

Primary Goals (Direct Upload Workflow)

• Enable direct file upload within forms where content will be used (projects, posts, albums)
• Provide immediate upload and preview without requiring navigation to separate media management
• Store comprehensive metadata including alt text for accessibility and SEO
• Support drag-and-drop and click-to-browse for intuitive file selection

Secondary Goals (Media Library Browser)

• Create a reusable media browser for selecting previously uploaded content
• Provide media management interface showing where files are referenced
• Enable bulk operations and metadata editing (especially alt text)
• Support file organization and usage tracking

Technical Goals

• Maintain consistent UX across all media interactions
• Support different file type filtering based on context
• Integrate seamlessly with existing admin components

Current State Analysis

✅ What We Have

• Complete media API (/api/media, /api/media/upload, /api/media/bulk-upload)
• Media management page with grid/list views and search/filtering
• Modal base component (Modal.svelte)
• Complete admin UI component library (Button, Input, etc.)
• Media upload infrastructure with Cloudinary integration
• Pagination and search functionality

🎯 What We Need

High Priority (Direct Upload Focus)

• Enhanced upload components with immediate preview and metadata capture
• Alt text input fields for accessibility compliance
• Direct upload integration in form components (ImagePicker, GalleryManager)
• Metadata management during upload process

Medium Priority (Media Library Browser)

• Reusable MediaLibraryModal component for browsing existing content
• Selection state management for previously uploaded files
• Usage tracking and reference management

Database Updates Required

• Add alt_text field to Media table
• Add usage_references or similar tracking for where media is used

Workflow Priorities

🥇 Primary Workflow: Direct Upload in Forms

This is the main workflow that users will use 90% of the time:

1. User creates content (project, post, album)
2. User uploads files directly in the form where they'll be used
3. Files are immediately processed and previewed
4. Alt text and metadata are captured during upload
5. Content is saved with proper media references

Key Components:

• ImageUploader - Direct drag-and-drop/click upload with preview
• GalleryUploader - Multiple file upload with immediate gallery preview
• MediaMetadataForm - Alt text and description capture during upload

🥈 Secondary Workflow: Browse Existing Media

This workflow is for reusing previously uploaded content:

1. User needs to select existing media (rare case)
2. User clicks "Browse Library" (secondary button)
3. Media Library Modal opens showing all uploaded files
4. User selects from existing content
5. Media references are updated

Key Components:

• MediaLibraryModal - Browse and select existing media
• MediaSelector - Grid interface for selection
• MediaManager - Edit alt text and view usage

Technical Requirements

1. Enhanced Upload Components (Primary)

ImageUploader Component

Purpose: Direct image upload with immediate preview and metadata capture

interface ImageUploaderProps {
  label: string
  value?: Media | null
  onUpload: (media: Media) => void
  aspectRatio?: string
  required?: boolean
  error?: string
  allowAltText?: boolean  // Enable alt text input
  maxFileSize?: number    // MB limit
}

Features:

• Drag-and-drop upload zone with visual feedback
• Click to browse files from computer
• Immediate image preview with proper aspect ratio
• Alt text input field (when enabled)
• Upload progress indicator
• File validation with helpful error messages
• Replace/remove functionality

GalleryUploader Component

Purpose: Multiple file upload with gallery preview and reordering

interface GalleryUploaderProps {
  label: string
  value?: Media[]
  onUpload: (media: Media[]) => void
  onReorder?: (media: Media[]) => void
  maxItems?: number
  allowAltText?: boolean
  required?: boolean
  error?: string
}

Features:

• Multiple file drag-and-drop
• Immediate gallery preview grid
• Individual alt text inputs for each image
• Drag-and-drop reordering
• Individual remove buttons
• Bulk upload progress

2. MediaLibraryModal Component (Secondary)

Purpose: Main modal component that wraps the media browser functionality

Props Interface:

interface MediaLibraryModalProps {
  isOpen: boolean
  mode: 'single' | 'multiple'
  fileType?: 'image' | 'video' | 'all'
  onSelect: (media: Media | Media[]) => void
  onClose: () => void
  selectedIds?: number[]  // Pre-selected items
  title?: string          // Modal title
  confirmText?: string    // Confirm button text
}

Features:

• Modal overlay with proper focus management
• Header with title and close button
• Media browser grid with selection indicators
• Search and filter controls
• Upload area with drag-and-drop
• Footer with selection count and action buttons
• Responsive design (desktop and tablet)

2. MediaSelector Component

Purpose: The actual media browsing interface within the modal

Features:

• Grid layout with thumbnail previews
• Individual item selection with visual feedback
• Keyboard navigation support
• Loading states and error handling
• "Select All" / "Clear Selection" bulk actions (for multiple mode)

Item Display:

• Thumbnail image
• Filename (truncated)
• File size and dimensions
• Usage indicator (if used elsewhere)
• Selection checkbox/indicator

3. MediaUploader Component

Purpose: Handle file uploads within the modal

Features:

• Drag-and-drop upload zone
• Click to browse files
• Upload progress indicators
• Error handling and validation
• Multiple file upload support
• Automatic refresh of media grid after upload

Validation:

• File type restrictions based on context
• File size limits (10MB per file)
• Maximum number of files for bulk upload

4. Form Integration Components

MediaInput Component

Purpose: Generic input field that opens media library modal

interface MediaInputProps {
  label: string
  value?: Media | Media[] | null
  mode: 'single' | 'multiple'
  fileType?: 'image' | 'video' | 'all'
  onSelect: (media: Media | Media[] | null) => void
  placeholder?: string
  required?: boolean
  error?: string
}

Display:

• Label and optional required indicator
• Preview of selected media (thumbnail + filename)
• "Browse" button to open modal
• "Clear" button to remove selection
• Error state display

ImagePicker Component

Purpose: Specialized single image selector with enhanced preview

interface ImagePickerProps {
  label: string
  value?: Media | null
  onSelect: (media: Media | null) => void
  aspectRatio?: string    // e.g., "16:9", "1:1"
  placeholder?: string
  required?: boolean
  error?: string
}

Display:

• Large preview area with placeholder
• Image preview with proper aspect ratio
• Overlay with "Change" and "Remove" buttons on hover
• Upload progress indicator

GalleryManager Component

Purpose: Multiple image selection with drag-and-drop reordering

interface GalleryManagerProps {
  label: string
  value?: Media[]
  onSelect: (media: Media[]) => void
  onReorder?: (media: Media[]) => void
  maxItems?: number
  required?: boolean
  error?: string
}

Display:

• Grid of selected images with reorder handles
• "Add Images" button to open modal
• Individual remove buttons on each image
• Drag-and-drop reordering with visual feedback

User Experience Flows

🥇 Primary Flow: Direct Upload in Forms

1. Single Image Upload (Project Featured Image)

1. User creates/edits project and reaches featured image field
2. User drags image file directly onto ImageUploader component OR clicks to browse
3. File is immediately uploaded with progress indicator
4. Image preview appears with proper aspect ratio
5. Alt text input field appears below preview (if enabled)
6. User enters alt text for accessibility
7. Form can be saved with media reference and metadata

2. Multiple Image Upload (Project Gallery)

1. User reaches gallery section of project form
2. User drags multiple files onto GalleryUploader OR clicks to browse multiple
3. Upload progress shown for each file individually
4. Gallery grid appears with all uploaded images
5. Alt text inputs available for each image
6. User can reorder images with drag-and-drop
7. User can remove individual images with X button
8. Form saves with complete gallery and metadata

3. Media Management and Alt Text Editing

1. User visits Media Library page to manage uploaded content
2. User clicks on any media item to open details modal
3. User can edit alt text and other metadata
4. User can see usage references (which projects/posts use this media)
5. Changes are saved and reflected wherever media is used

🥈 Secondary Flow: Browse Existing Media

1. Selecting Previously Uploaded Image

1. User clicks "Browse Library" button (secondary option in forms)
2. MediaLibraryModal opens showing all previously uploaded media
3. User browses or searches existing content
4. User selects image and confirms selection
5. Modal closes and form shows selected media with existing alt text

2. Managing Media Library

1. User visits dedicated Media Library page
2. User can view all uploaded media in grid/list format
3. User can edit metadata including alt text for any media
4. User can see usage tracking - which content references each media
5. User can perform bulk operations like deleting unused media

Design Specifications

Modal Layout

• Width: 1200px max, responsive on smaller screens
• Height: 80vh max with scroll
• Grid: 4-6 columns depending on screen size
• Item Size: 180px × 140px thumbnails

Visual States

• Default: Border with subtle background
• Selected: Blue border and checkmark overlay
• Hover: Slight scale and shadow effect
• Loading: Skeleton loader animation
• Upload: Progress overlay with percentage

Colors (Using Existing Variables)

• Selection: $blue-60 for selected state
• Hover: $grey-10 background
• Upload Progress: $green-60 for success, $red-60 for error

API Integration

Endpoints Used

• GET /api/media - Browse media with search/filter/pagination
• POST /api/media/upload - Single file upload
• POST /api/media/bulk-upload - Multiple file upload

Search and Filtering

• Search: By filename (case-insensitive)
• Filter by Type: image/, video/, all
• Filter by Usage: unused only, all
• Sort: Most recent first

Pagination

• 24 items per page
• Infinite scroll or traditional pagination
• Loading states during page changes

Implementation Plan

Phase 1: Database Schema Updates (Required First)

1. Add Alt Text Support

   ALTER TABLE media ADD COLUMN alt_text TEXT;
   ALTER TABLE media ADD COLUMN description TEXT;
   

2. Add Usage Tracking (Optional)

   -- Track where media is referenced
   CREATE TABLE media_usage (
     id SERIAL PRIMARY KEY,
     media_id INTEGER REFERENCES media(id),
     content_type VARCHAR(50), -- 'project', 'post', 'album'
     content_id INTEGER,
     field_name VARCHAR(100), -- 'featured_image', 'gallery', etc.
     created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
   );
   

Phase 2: Direct Upload Components (High Priority)

1. ImageUploader Component

   • Drag-and-drop upload zone with visual feedback
   • Immediate upload and preview functionality
   • Alt text input integration
   • Replace existing ImagePicker with upload-first approach

2. GalleryUploader Component

   • Multiple file drag-and-drop
   • Individual alt text inputs per image
   • Drag-and-drop reordering
   • Remove individual images functionality

3. Upload API Enhancement

   • Accept alt text in upload request
   • Return complete media object with metadata
   • Handle batch uploads with individual alt text

Phase 3: Form Integration (High Priority)

1. Project Forms Enhancement

   • Replace logo field with ImageUploader
   • Add featured image with ImageUploader
   • Implement gallery section with GalleryUploader
   • Add secondary "Browse Library" buttons

2. Post Forms Enhancement

   • Photo post type with GalleryUploader
   • Album creation with GalleryUploader
   • Featured image selection for text posts

Phase 4: Media Library Management (Medium Priority)

1. Enhanced Media Library Page

   • Alt text editing for existing media
   • Usage tracking display (shows where media is used)
   • Bulk alt text editing
   • Search and filter by alt text

2. MediaLibraryModal for Selection

   • Browse existing media interface
   • Single and multiple selection modes
   • Integration as secondary option in forms

Phase 5: Polish and Advanced Features (Low Priority)

1. Advanced Upload Features

   • Image resizing/optimization options
   • Automatic alt text suggestions (AI integration)
   • Bulk upload with CSV metadata import

2. Usage Analytics

   • Dashboard showing media usage statistics
   • Unused media cleanup tools
   • Duplicate detection and management

Success Criteria

Functional Requirements

Primary Workflow (Direct Upload)

• Drag-and-drop upload works in all form components
• Click-to-browse file selection works reliably
• Immediate upload and preview happens without page navigation
• Alt text input appears and saves with uploaded media
• Upload progress is clearly indicated with percentage
• Error handling provides helpful feedback for failed uploads
• Multiple file upload works with individual progress tracking
• Gallery reordering works with drag-and-drop after upload

Secondary Workflow (Media Library)

• Media Library Modal opens and closes properly with smooth animations
• Single and multiple selection modes work correctly
• Search and filtering return accurate results
• Usage tracking shows where media is referenced
• Alt text editing works in Media Library management
• All components are keyboard accessible

Performance Requirements

• Modal opens in under 200ms
• Media grid loads in under 1 second
• Search results appear in under 500ms
• Upload progress updates in real-time
• No memory leaks when opening/closing modal multiple times

UX Requirements

• Interface is intuitive without instruction
• Visual feedback is clear for all interactions
• Error messages are helpful and actionable
• Mobile/tablet interface is fully functional
• Loading states prevent user confusion

Technical Considerations

State Management

• Use Svelte runes for reactive state
• Maintain selection state during modal lifecycle
• Handle API loading and error states properly

Accessibility

• Proper ARIA labels and roles
• Keyboard navigation support
• Focus management when modal opens/closes
• Screen reader announcements for state changes

Performance

• Lazy load thumbnails as they come into view
• Debounce search input to prevent excessive API calls
• Efficient reordering without full re-renders
• Memory cleanup when modal is closed

Error Handling

• Network failure recovery
• Upload failure feedback
• File validation error messages
• Graceful degradation for missing thumbnails

Future Enhancements

Nice-to-Have Features

• Bulk Operations: Delete multiple files, bulk tag editing
• Advanced Search: Search by tags, date range, file size
• Preview Mode: Full-size preview with navigation
• Folder Organization: Create folders/categories for organization
• Smart Suggestions: Recently used, similar images
• Crop Tool: Basic cropping interface within modal
• Alt Text Editor: Quick alt text editing for accessibility

Integration Opportunities

• CDN Optimization: Automatic image optimization settings
• AI Tagging: Automatic tag generation for uploaded images
• Duplicate Detection: Warn about similar/duplicate uploads
• Usage Analytics: Track which media is used most frequently

Development Checklist

Core Components

• MediaLibraryModal base structure
• MediaSelector with grid layout
• MediaUploader with drag-and-drop
• Search and filter interface
• Pagination implementation

Form Integration

• MediaInput generic component
• ImagePicker specialized component
• GalleryManager with reordering
• Integration with existing project forms
• Integration with post forms

Polish and Testing

• Responsive design implementation
• Accessibility testing and fixes
• Performance optimization
• Error state handling
• Cross-browser testing
• Mobile device testing

This Media Library system will serve as the foundation for all media-related functionality in the CMS, enabling rich content creation across projects, posts, and albums.