diff --git a/docs/frontend/gallery-view.md b/docs/frontend/gallery-view.md new file mode 100644 index 000000000..bbbcddd7a --- /dev/null +++ b/docs/frontend/gallery-view.md @@ -0,0 +1,245 @@ +# Gallery View + +The Gallery View is the heart of PictoPy, providing an intuitive and powerful interface for browsing, organizing, and managing your photo collection. Built with React and TypeScript, it offers a modern, responsive experience that adapts to different screen sizes and user preferences. + +## Overview + +The Gallery View presents photos in a chronological layout, automatically organizing images by date and providing smart navigation tools. It combines efficient rendering with rich metadata display and seamless integration with PictoPy's AI-powered features. + +## Core Components + +### ChronologicalGallery + +The main gallery component (`ChronologicalGallery.tsx`) provides the primary photo browsing experience: + +**Features:** +- **Chronological Organization**: Photos are automatically grouped by date (year/month) +- **Responsive Grid Layout**: Adapts to screen size with optimal thumbnail sizing +- **Virtual Scrolling**: Efficient rendering of large photo collections +- **Month Markers**: Visual separators between different time periods +- **Search Integration**: Seamlessly displays search results within the same interface + +**Key Props:** +```typescript +interface ChronologicalGalleryProps { + images: Image[]; + showTitle?: boolean; + title?: string; + onMonthOffsetsChange?: (markers: MonthMarker[]) => void; + scrollContainerRef?: RefObject; +} +``` + +### ImageCard + +Individual photo thumbnails (`ImageCard.tsx`) that display within the gallery: + +**Features:** +- **Smart Thumbnails**: Optimized image loading with lazy loading +- **Metadata Overlay**: Shows key information on hover/selection +- **Selection States**: Visual feedback for selected images +- **Favorite Indicators**: Heart icons for favorited photos +- **AI Tags**: Displays detected objects, faces, and scenes +- **Quick Actions**: Context menu for common operations + +**Interaction States:** +- **Default**: Clean thumbnail view +- **Hover**: Metadata overlay with quick actions +- **Selected**: Visual selection indicator +- **Loading**: Skeleton placeholder during image load + +### Timeline Navigation + +The Timeline Scrollbar (`TimelineScrollbar.tsx`) provides quick navigation through large photo collections: + +**Features:** +- **Month Markers**: Visual indicators for each month with photos +- **Quick Jump**: Click to instantly navigate to specific time periods +- **Scroll Sync**: Automatically updates based on current scroll position +- **Responsive Design**: Adapts to different screen sizes + +## Gallery Layouts + +### Grid View (Default) + +The primary gallery layout organizes photos in a responsive grid: + +- **Adaptive Columns**: Automatically adjusts column count based on screen width +- **Consistent Spacing**: Maintains visual rhythm across different image sizes +- **Aspect Ratio Preservation**: Images maintain their original proportions +- **Smooth Scrolling**: Optimized for performance with large collections + +### Chronological Grouping + +Photos are automatically organized into logical time-based groups: + +- **Year Sections**: Major separators for different years +- **Month Subsections**: Grouped by month within each year +- **Date Headers**: Clear visual indicators for time periods +- **Smart Spacing**: Appropriate gaps between different time periods + +## Image Viewing Experience + +### Full-Screen Viewer + +The ImageViewer component (`ImageViewer.tsx`) provides an immersive viewing experience: + +**Features:** +- **Full-Screen Display**: Maximizes image visibility +- **Zoom Controls**: Pinch-to-zoom and mouse wheel support +- **Pan Navigation**: Drag to explore zoomed images +- **Keyboard Shortcuts**: Arrow keys for navigation, ESC to close +- **Metadata Panel**: Detailed information sidebar +- **Navigation Controls**: Previous/next buttons with smooth transitions + +### Media Controls + +Comprehensive controls for image interaction (`MediaViewControls.tsx`): + +- **Zoom In/Out**: Precise zoom control with zoom levels +- **Fit to Screen**: Automatic sizing options (fit, fill, actual size) +- **Rotation**: 90-degree rotation controls +- **Slideshow**: Automatic progression through images +- **Favorite Toggle**: Quick favorite/unfavorite action +- **Share Options**: Export and sharing functionality + +## Search and Filtering + +### Face Search Integration + +The gallery seamlessly integrates with PictoPy's face recognition system: + +- **Face-Based Filtering**: Show only photos containing specific people +- **Search Results Display**: Clear indication when viewing search results +- **Result Count**: Shows number of matching photos +- **Search State Management**: Maintains search context across navigation + +### Smart Filtering + +Advanced filtering options for photo organization: + +- **Date Range**: Filter by specific time periods +- **AI Tags**: Filter by detected objects, scenes, or activities +- **Favorites**: Show only favorited photos +- **File Type**: Filter by image format (JPEG, PNG, RAW, etc.) +- **Folder Source**: Filter by source directory + +## Performance Optimizations + +### Efficient Rendering + +The gallery is optimized for handling large photo collections: + +- **Virtual Scrolling**: Only renders visible thumbnails +- **Lazy Loading**: Images load as they come into view +- **Progressive Enhancement**: Basic layout loads first, then enhancements +- **Memory Management**: Automatic cleanup of off-screen images + +### Image Loading Strategy + +Smart image loading for optimal performance: + +- **Thumbnail Generation**: Server-side thumbnail creation +- **Progressive JPEG**: Loads low-quality first, then high-quality +- **Caching**: Intelligent browser and application-level caching +- **Preloading**: Anticipates next images in sequence + +## Empty States + +User-friendly empty states for different scenarios: + +### EmptyGalleryState + +Displayed when no photos are available: + +- **Welcome Message**: Friendly introduction for new users +- **Action Buttons**: Direct links to add photos or configure folders +- **Visual Indicators**: Clear iconography and messaging +- **Onboarding Hints**: Guidance for getting started + +### No Search Results + +When search queries return no matches: + +- **Clear Messaging**: Explains why no results were found +- **Search Suggestions**: Tips for refining search terms +- **Alternative Actions**: Links to browse all photos or try different searches + +## Responsive Design + +### Mobile Experience + +Optimized for touch devices: + +- **Touch-Friendly Targets**: Appropriately sized tap areas +- **Swipe Navigation**: Gesture-based image navigation +- **Mobile Grid**: Optimized column layout for small screens +- **Pull-to-Refresh**: Intuitive refresh gesture + +### Desktop Experience + +Enhanced for mouse and keyboard interaction: + +- **Hover States**: Rich hover interactions with metadata +- **Keyboard Shortcuts**: Full keyboard navigation support +- **Context Menus**: Right-click actions for power users +- **Multi-Selection**: Shift+click and Ctrl+click selection + +## Accessibility Features + +### Screen Reader Support + +Full accessibility for visually impaired users: + +- **Alt Text**: Descriptive text for all images +- **ARIA Labels**: Proper labeling for interactive elements +- **Focus Management**: Logical tab order and focus indicators +- **Semantic HTML**: Proper heading structure and landmarks + +### Keyboard Navigation + +Complete keyboard accessibility: + +- **Tab Navigation**: All interactive elements are keyboard accessible +- **Arrow Key Navigation**: Navigate between images using arrow keys +- **Shortcut Keys**: Common actions available via keyboard shortcuts +- **Focus Indicators**: Clear visual focus indicators + +## Integration with AI Features + +### Object Detection + +Visual indicators for AI-detected content: + +- **Object Tags**: Overlay tags showing detected objects +- **Confidence Indicators**: Visual representation of detection confidence +- **Tag Filtering**: Click tags to filter similar images +- **Smart Grouping**: Automatic grouping by detected content + +### Face Recognition + +Seamless integration with face clustering: + +- **Face Thumbnails**: Small face previews on image cards +- **Person Filtering**: Filter gallery by specific people +- **Face Collections**: Navigate to dedicated person views +- **Recognition Confidence**: Visual indicators for face match confidence + +## Future Enhancements + +### Planned Features + +- **Map View**: Geographic organization of photos with location data +- **Timeline Scrubbing**: Smooth timeline navigation with preview thumbnails +- **Advanced Sorting**: Multiple sorting options (name, size, camera settings) +- **Batch Operations**: Multi-select actions for bulk photo management +- **Custom Albums**: User-created photo collections and albums + +### Performance Improvements + +- **WebGL Acceleration**: Hardware-accelerated image rendering +- **Service Worker Caching**: Offline gallery browsing capabilities +- **Predictive Loading**: AI-powered preloading based on user behavior +- **Compression Optimization**: Dynamic image quality based on network conditions + +The Gallery View represents the culmination of modern web technologies and thoughtful UX design, providing users with an intuitive, powerful, and enjoyable way to explore their photo collections while leveraging PictoPy's advanced AI capabilities. \ No newline at end of file diff --git a/docs/frontend/screenshots.md b/docs/frontend/screenshots.md index d4cf97d15..47a5c6020 100644 --- a/docs/frontend/screenshots.md +++ b/docs/frontend/screenshots.md @@ -16,6 +16,9 @@ The application includes AI-powered features for intelligent photo organization, ![AI Tagging](../assets/screenshots/ai-tagging.png) *AI Tagging interface showing face collections, object detection, and intelligent photo organization* +![AI Tagging Advanced](../assets/screenshots/ai-tagging2.png) +*Advanced AI tagging features with detailed face recognition and clustering capabilities* + ## Settings Panel The settings panel allows users to configure directories, preferences, and application behavior. @@ -23,5 +26,12 @@ The settings panel allows users to configure directories, preferences, and appli ![Settings](../assets/screenshots/settings.png) *Settings panel showing directory configuration and user preferences* +## Development Environment + +Screenshots showing the development setup and server configuration. +![Server Running](../assets/screenshots/serverRunning.png) +*Backend server running successfully with API endpoints active* +![Virtual Environment](../assets/screenshots/virtualEnv.png) +*Python virtual environment setup for development* \ No newline at end of file diff --git a/docs/frontend/ui-components.md b/docs/frontend/ui-components.md new file mode 100644 index 000000000..6c4056880 --- /dev/null +++ b/docs/frontend/ui-components.md @@ -0,0 +1,235 @@ +# UI Components + +PictoPy's frontend is built with React and TypeScript, featuring a comprehensive component library that provides a consistent and intuitive user interface. The application uses modern UI patterns with shadcn/ui components as the foundation. + +## Component Architecture + +The UI components are organized into several categories: + +### Core UI Components (`/components/ui/`) + +These are the foundational components based on shadcn/ui that provide consistent styling and behavior across the application. + +#### Form Components +- **Button** (`button.tsx`) - Primary, secondary, and variant buttons with loading states +- **Input** (`input.tsx`) - Text input fields with validation styling +- **Label** (`label.tsx`) - Form labels with proper accessibility +- **Textarea** (`textarea.tsx`) - Multi-line text input +- **Switch** (`switch.tsx`) - Toggle switches for boolean settings +- **Radio Group** (`radio-group.tsx`) - Radio button groups for single selection +- **Slider** (`Slider.tsx`) - Range sliders for numeric input + +#### Layout Components +- **Card** (`card.tsx`) - Container component for content sections +- **Dialog** (`dialog.tsx`) - Modal dialogs and popups +- **Sheet** (`sheet.tsx`) - Slide-out panels and drawers +- **Separator** (`separator.tsx`) - Visual dividers between content +- **Sidebar** (`sidebar.tsx`) - Navigation sidebar component +- **Scroll Area** (`scroll-area.tsx`) - Custom scrollable containers + +#### Display Components +- **Avatar** (`avatar.tsx`) - User profile pictures and placeholders +- **Badge** (`badge.tsx`) - Status indicators and labels +- **Alert** (`alert.tsx`) - Notification and warning messages +- **Progress** (`progress.tsx`) - Progress bars and loading indicators +- **Skeleton** (`skeleton.tsx`) - Loading placeholders +- **Tooltip** (`tooltip.tsx`) - Contextual help and information + +#### Navigation Components +- **Dropdown Menu** (`dropdown-menu.tsx`) - Context menus and action lists +- **Pagination** (`pagination.tsx`) - Page navigation controls +- **Pagination Controls** (`PaginationControls.tsx`) - Enhanced pagination with custom styling + +#### Specialized Components +- **Aspect Ratio** (`aspect-ratio.tsx`) - Maintains consistent image/video ratios +- **Loading Screen** (`LoadingScreen/`) - Full-screen loading states +- **Error Page** (`ErrorPage/`) - Error handling and 404 pages +- **Icons** (`Icons/`) - Custom icon components and SVG assets + +### Feature Components + +#### Media Components (`/components/Media/`) + +The media components handle the core photo viewing and management functionality: + +- **ChronologicalGallery** (`ChronologicalGallery.tsx`) - Main gallery view with chronological organization +- **ImageCard** (`ImageCard.tsx`) - Individual photo thumbnails with metadata +- **ImageViewer** (`ImageViewer.tsx`) - Full-screen image viewing experience +- **ImageTags** (`ImageTags.tsx`) - AI-generated tags and metadata display +- **MediaView** (`MediaView.tsx`) - Unified media viewing component +- **MediaViewControls** (`MediaViewControls.tsx`) - Playback and navigation controls +- **MediaThumbnails** (`MediaThumbnails.tsx`) - Thumbnail grid layouts +- **MediaInfoPanel** (`MediaInfoPanel.tsx`) - Detailed media information sidebar +- **NavigationButtons** (`NavigationButtons.tsx`) - Previous/next navigation +- **ZoomControls** (`ZoomControls.tsx`) - Image zoom and pan controls + +#### Navigation Components (`/components/Navigation/`) + +Handles application navigation and routing: + +- Main navigation sidebar +- Breadcrumb navigation +- Tab navigation for different views + +#### Dialog Components (`/components/Dialog/`) + +Modal dialogs for various interactions: + +- Confirmation dialogs +- Settings dialogs +- Information displays + +#### Specialized Feature Components + +- **FaceCollections** (`FaceCollections.tsx`) - Face recognition clustering interface +- **ThemeToggle** (`ThemeToggle.tsx`) - Dark/light mode switcher +- **Timeline** (`Timeline/TimelineScrollbar.tsx`) - Chronological navigation +- **FolderPicker** (`FolderPicker/`) - Directory selection interface +- **Loader** (`Loader/`) - Application-wide loading states +- **OnboardingSteps** (`OnboardingSteps/`) - User onboarding flow +- **VideoPlayer** (`VideoPlayer/`) - Video playback component +- **WebCam** (`WebCam/`) - Camera integration for photo capture +- **Updater** (`Updater/`) - Application update notifications + +### Empty States (`/components/EmptyStates/`) + +Provides user-friendly empty state components when no content is available: + +- Empty gallery states +- No search results +- Missing folder content + +## Component Design Principles + +### 1. Consistency +All components follow consistent design patterns using a shared design system based on shadcn/ui, ensuring visual harmony across the application. + +### 2. Accessibility +Components are built with accessibility in mind, including: +- Proper ARIA labels and roles +- Keyboard navigation support +- Screen reader compatibility +- Focus management + +### 3. Responsiveness +All components are designed to work across different screen sizes: +- Mobile-first approach +- Flexible layouts +- Touch-friendly interactions + +### 4. Performance +Components are optimized for performance: +- Lazy loading for images +- Virtual scrolling for large lists +- Memoization for expensive operations +- Efficient re-rendering patterns + +### 5. Type Safety +Full TypeScript integration provides: +- Compile-time error checking +- IntelliSense support +- Better developer experience +- Reduced runtime errors + +## Styling System + +### CSS Framework +The application uses Tailwind CSS for styling, providing: +- Utility-first approach +- Consistent spacing and colors +- Responsive design utilities +- Dark mode support + +### Theme System +PictoPy supports both light and dark themes: +- Automatic system preference detection +- Manual theme switching +- Consistent color schemes +- Smooth transitions between themes + +### Component Variants +Many components support multiple variants: +- **Buttons**: primary, secondary, outline, ghost, destructive +- **Alerts**: default, destructive, warning, success +- **Badges**: default, secondary, outline, destructive + +## Usage Examples + +### Basic Button Usage +```typescript +import { Button } from "@/components/ui/button"; + + +``` + +### Image Card in Gallery +```typescript +import { ImageCard } from "@/components/Media/ImageCard"; + + +``` + +### Dialog with Form +```typescript +import { Dialog, DialogContent, DialogHeader, DialogTitle } from "@/components/ui/dialog"; +import { Button } from "@/components/ui/button"; +import { Input } from "@/components/ui/input"; + + + + + Add New Album + +
+ + +
+ + +``` + +## Component Testing + +Components are tested using: +- **Jest** for unit testing +- **React Testing Library** for component testing +- **TypeScript** for type checking +- **ESLint** for code quality + +Test files are located in `__tests__` directories alongside components, ensuring comprehensive coverage of component functionality and user interactions. + +## Development Guidelines + +### Creating New Components +1. Use TypeScript for all components +2. Follow the existing naming conventions +3. Include proper prop types and interfaces +4. Add accessibility attributes +5. Write comprehensive tests +6. Document component props and usage + +### Component Structure +```typescript +interface ComponentProps { + // Define all props with proper types +} + +export const Component: React.FC = ({ + // Destructure props +}) => { + // Component logic + + return ( + // JSX with proper accessibility + ); +}; +``` + +This component architecture ensures PictoPy provides a smooth, accessible, and performant user experience while maintaining code quality and developer productivity. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index b3e000633..67454b0cf 100644 --- a/docs/index.md +++ b/docs/index.md @@ -76,6 +76,11 @@ This project was announced by [AOSSIE](https://aossie.org/), an umbrella organiz Gallery View +
  • + + Screenshots + +
    • diff --git a/mkdocs.yml b/mkdocs.yml index 70778130f..6f29e8e8a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -70,6 +70,8 @@ nav: - Python Backend Image Processing: backend/backend_python/image-processing.md - Rust Backend API: backend/backend_rust/api.md - Frontend: + - UI Components: frontend/ui-components.md + - Gallery View: frontend/gallery-view.md - State Management: frontend/state-management.md - Screenshots: frontend/screenshots.md