MyClub/DOCS/FILE_PREVIEW_COMPONENT.md

# File Preview Component

## Overview
A comprehensive file preview component that provides inline viewing and downloading capabilities for various file types including images, PDFs, videos, audio files, and Office documents (PPTX, DOCX, XLSX).

## Component Location
`frontend/src/components/common/FilePreview.tsx`

## Features

### 1. **Supported File Types**

#### Full Preview Support (in modal)
- **Images**: JPG, JPEG, PNG, GIF, SVG, WebP, BMP
  - Direct inline display
  - Click to zoom in modal
  - Error handling for failed loads

- **PDFs**: 
  - Embedded iframe viewer
  - Native browser PDF viewer
  - Maintains aspect ratio

- **Videos**: MP4, AVI, MOV, WebM
  - HTML5 video player with controls
  - 16:9 aspect ratio
  - Support for multiple formats

- **Audio**: MP3, WAV, OGG
  - HTML5 audio player with controls
  - Icon display with player below

#### Online Preview Support
- **PowerPoint**: PPTX, PPT
  - "Zobrazit online" button using Microsoft Office Online Viewer
  - Download option
  - File info display

- **Word**: DOCX, DOC
  - Same online viewer support
  - Icon and file metadata

- **Excel**: XLSX, XLS
  - Online spreadsheet viewer
  - Download and preview options

### 2. **Display Modes**

#### Compact Mode (default)
```tsx
<FilePreview 
  url="/uploads/document.pdf"
  name="Document.pdf"
  mimeType="application/pdf"
  size={1024000}
/>
```
- Shows file icon, name, and size
- Preview and Download buttons
- Responsive layout

#### Inline Mode (for images)
```tsx
<FilePreview 
  url="/uploads/photo.jpg"
  name="Photo.jpg"
  mimeType="image/jpeg"
  size={512000}
  showInline={true}
/>
```
- Displays image directly in the page
- Click to open full-size modal
- Max height: 400px

### 3. **User Interface Elements**

#### File Information
- Icon based on file type (color-coded)
- File name (truncated if too long)
- File size (displayed in KB or MB)
- MIME type indicator

#### Action Buttons
- **Náhled** (Preview): Opens modal with file preview
- **Stáhnout** (Download): Direct download link
- **Zobrazit online** (View Online): For Office documents

#### Modal Preview
- Full-screen modal (90vw × 90vh)
- Dark overlay background
- Close button
- Download button in footer
- Responsive content area

## Props

```typescript
interface FilePreviewProps {
  url: string;           // File URL (relative or absolute)
  name?: string;         // Display name (defaults to filename from URL)
  mimeType?: string;     // MIME type (e.g., 'image/jpeg', 'application/pdf')
  size?: number;         // File size in bytes
  showInline?: boolean;  // Show inline preview for images (default: false)
}
```

## Usage Examples

### Basic Usage (Event Attachments)
```tsx
import FilePreview from '../components/common/FilePreview';

// In your component
{attachments.map((att, idx) => (
  <FilePreview
    key={idx}
    url={att.url}
    name={att.name}
    mimeType={att.mime_type}
    size={att.size}
  />
))}
```

### Inline Image Gallery
```tsx
{images.map((img, idx) => (
  <FilePreview
    key={idx}
    url={img.url}
    name={img.name}
    mimeType="image/jpeg"
    size={img.size}
    showInline={true}
  />
))}
```

### PDF Document
```tsx
<FilePreview
  url="/uploads/report.pdf"
  name="Monthly Report.pdf"
  mimeType="application/pdf"
  size={2048000}
/>
```

### PowerPoint Presentation
```tsx
<FilePreview
  url="/uploads/presentation.pptx"
  name="Company Presentation.pptx"
  mimeType="application/vnd.openxmlformats-officedocument.presentationml.presentation"
  size={3145728}
/>
```

## File Type Detection

The component automatically detects file types based on MIME type:

| MIME Type Pattern | Icon | Color | Preview Available |
|------------------|------|-------|-------------------|
| `image/*` | FiImage | Purple | ✅ Yes (inline) |
| `application/pdf` | FiFileText | Red | ✅ Yes (iframe) |
| `video/*` | FiVideo | Pink | ✅ Yes (player) |
| `audio/*` | FiMusic | Green | ✅ Yes (player) |
| `*word*`, `*document*` | FiFileText | Blue | ⚠️ Online only |
| `*sheet*`, `*excel*` | FiFile | Green | ⚠️ Online only |
| `*presentation*`, `*powerpoint*` | FiFile | Orange | ⚠️ Online only |
| Other | FiFile | Gray | ❌ Download only |

## Microsoft Office Online Viewer

For Office documents (PPTX, DOCX, XLSX), the component offers a "Zobrazit online" button that opens the file in Microsoft Office Online Viewer:

```
https://view.officeapps.live.com/op/view.aspx?src=[ENCODED_FILE_URL]
```

**Requirements:**
- File must be publicly accessible
- Supported formats: DOCX, XLSX, PPTX
- Internet connection required

## Integration with ActivityDetailPage

The FilePreview component has been integrated into `ActivityDetailPage.tsx`:

**Before:**
- Simple download button
- No preview functionality
- Minimal file information

**After:**
- Full preview support for all file types
- Inline image display
- Modal viewer for PDFs, videos, audio
- Office document online viewer
- Better file metadata display

## Styling & Theming

The component uses Chakra UI's color mode values:

```tsx
const borderColor = useColorModeValue('gray.200', 'gray.700');
const cardBg = useColorModeValue('white', 'gray.800');
const mutedText = useColorModeValue('gray.600', 'gray.300');
const linkColor = useColorModeValue('blue.600', 'blue.300');
```

This ensures proper display in both light and dark modes.

## Error Handling

### Image Loading Errors
- Catches `onError` event
- Displays fallback message
- Provides download option

### Video/Audio Playback Errors
- Shows browser's native error message
- Falls back to download option

### PDF Loading Issues
- Browser's native PDF viewer handles errors
- Users can download if preview fails

## Accessibility

- Proper ARIA labels
- Keyboard navigation support (modal)
- Screen reader friendly
- High contrast icons
- Responsive design

## Browser Compatibility

| Browser | Images | PDFs | Video | Audio | Office Docs |
|---------|--------|------|-------|-------|-------------|
| Chrome 90+ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Firefox 88+ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Safari 14+ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Edge 90+ | ✅ | ✅ | ✅ | ✅ | ✅ |

**Note:** Office document online viewing requires an internet connection and works on all modern browsers.

## Performance Considerations

1. **Lazy Loading**: Images are loaded only when visible
2. **Modal Loading**: Preview content loads only when modal opens
3. **External Links**: Downloads don't trigger component re-renders
4. **Error Boundaries**: Failed loads don't crash the component

## Future Enhancements

Potential improvements:

1. **Caching**: Cache preview content
2. **Thumbnails**: Generate thumbnails for large files
3. **Full-screen mode**: Add full-screen toggle for videos
4. **Download progress**: Show progress bar for large files
5. **Zoom controls**: Add zoom in/out for images and PDFs
6. **Print option**: Add print button for documents
7. **Share functionality**: Social sharing buttons
8. **Multi-page PDF navigation**: Add page controls for PDFs

## Dependencies

- `@chakra-ui/react`: UI components
- `react-icons/fi`: Feather icons
- `assetUrl` utility: URL resolution helper

## Testing Checklist

- [ ] Image preview opens in modal
- [ ] PDF displays in iframe
- [ ] Video plays with controls
- [ ] Audio plays correctly
- [ ] Office docs show "View Online" button
- [ ] Download button works
- [ ] Error states display properly
- [ ] Responsive on mobile
- [ ] Dark mode looks correct
- [ ] File sizes format correctly (KB/MB)
- [ ] Modal closes properly
- [ ] External links open in new tab