MyClub/DOCS/THUMBNAIL_PREVIEW_FEATURE.md

# Thumbnail Preview Feature - Admin Pages

## Overview
Added hover-to-preview functionality for thumbnail images in admin tables. Now when you hover over a small thumbnail in Articles, Activities, or Players admin pages, a larger preview pops up automatically.

## Component

### ThumbnailPreview
Location: `frontend/src/components/common/ThumbnailPreview.tsx`

A lightweight component that shows a small thumbnail with a popover preview on hover.

**Features:**
- 📸 Small thumbnail in table (default 48×48px)
- 🔍 Hover to see larger preview (default 300px wide, max 400px high)
- ⚡ Quick preview without clicking
- 🎨 Respects color mode (light/dark)
- 🚀 Lazy loading for performance
- ⏱️ 200ms delay before showing preview (prevents accidental popups)

## Usage

### Basic Example
```tsx
import ThumbnailPreview from '../../components/common/ThumbnailPreview';

<ThumbnailPreview 
  src="/uploads/2025/10/image.jpg"
  alt="Article cover"
  size="48px"
  previewSize="350px"
/>
```

### Props

```typescript
interface ThumbnailPreviewProps {
  src: string;              // Image URL (required)
  alt: string;              // Alt text (required)
  size?: string;            // Thumbnail size (default: '48px')
  previewSize?: string;     // Preview popup width (default: '300px')
  borderRadius?: string;    // Border radius (default: 'md')
  objectFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
                            // How to fit image (default: 'cover')
}
```

## Integrated Pages

### 1. Articles Admin Page
Location: `frontend/src/pages/admin/ArticlesAdminPage.tsx`

**Before:**
- Static 48×48px thumbnails
- No way to preview images without opening edit modal

**After:**
- Hover over thumbnail → See 350×400px preview
- Quick visual identification of articles
- No clicking required

**Implementation:**
```tsx
<ThumbnailPreview 
  src={assetUrl(article.image_url) || '/dist/img/logo-club-empty.svg'} 
  alt={article.title} 
  size="48px"
  previewSize="350px"
/>
```

### 2. Activities Admin Page
Location: `frontend/src/pages/admin/AdminActivitiesPage.tsx`

**New Feature:**
- Added "Náhled" (Preview) column to the table
- Shows event cover images
- Fallback to club logo if no image set (with 30% opacity)

**Before:**
- No image column in the table
- Couldn't see which events have images

**After:**
- Visual preview column
- Hover for larger view
- Easy to identify events with/without images

**Implementation:**
```tsx
{event.image_url ? (
  <ThumbnailPreview 
    src={assetUrl(event.image_url)} 
    alt={event.title} 
    size="48px"
    previewSize="350px"
  />
) : (
  <Image 
    src={clubLogo} 
    alt="No image" 
    boxSize="48px" 
    opacity={0.3}
  />
)}
```

### 3. Players Admin Page
Location: `frontend/src/pages/admin/PlayersAdminPage.tsx`

**Before:**
- Static 48×48px player photos
- No hover preview

**After:**
- Hover over photo → See 300×400px preview
- Better identification of players
- Rounded corners match player photo aesthetic

**Implementation:**
```tsx
<ThumbnailPreview 
  src={normalizeImageUrl(player.image_url)} 
  alt={`${player.first_name} ${player.last_name}`} 
  size="48px"
  previewSize="300px"
  borderRadius="md"
/>
```

## User Experience

### Interaction Flow
1. **Hover** over thumbnail (mouse over)
2. **Wait** 200ms (prevents accidental triggers)
3. **Preview** appears to the right of thumbnail
4. **Move away** → Preview closes after 100ms

### Visual Feedback
- Thumbnail scales up 5% on hover
- Box shadow appears on hover
- Smooth transitions (0.2s)
- Cursor changes to pointer

### Performance
- Lazy loading on thumbnails
- Preview image only loads when needed
- Minimal re-renders
- Portal-based rendering (no z-index issues)

## Benefits

### For Admins
✅ **Faster workflow** - No need to click to see images  
✅ **Visual identification** - Quickly spot articles/events by cover image  
✅ **Quality check** - Verify image quality without opening editor  
✅ **Better overview** - See which content has images  

### For Content Management
✅ **Image audit** - Easily see which articles need images  
✅ **Consistency check** - Spot images that don't match style  
✅ **Quick decisions** - Choose articles to feature based on visuals  

## Technical Details

### Popover Configuration
```tsx
<Popover 
  trigger="hover"           // Show on hover
  placement="right"         // Appears to the right
  openDelay={200}          // 200ms delay before showing
  closeDelay={100}         // 100ms delay before hiding
>
```

### Portal Rendering
The preview uses `<Portal>` to render at the root level, preventing:
- Z-index conflicts
- Overflow clipping
- Parent container constraints

### Responsive Behavior
- Preview max height: 400px
- Preview adapts to available space
- Falls back to browser default if no space to the right

## Browser Compatibility

| Feature | Chrome | Firefox | Safari | Edge |
|---------|--------|---------|--------|------|
| Hover trigger | ✅ | ✅ | ✅ | ✅ |
| Popover | ✅ | ✅ | ✅ | ✅ |
| Lazy loading | ✅ | ✅ | ✅ | ✅ |
| Portal | ✅ | ✅ | ✅ | ✅ |

## Mobile Behavior

On touch devices:
- Hover is triggered by tap
- Preview stays visible until user taps elsewhere
- First tap = preview
- Second tap = navigate/edit (if thumbnail is a link)

## Customization Examples

### Larger Preview
```tsx
<ThumbnailPreview 
  src={imageUrl}
  alt="Large preview"
  size="64px"
  previewSize="500px"
/>
```

### Square Fit (for logos)
```tsx
<ThumbnailPreview 
  src={logoUrl}
  alt="Logo"
  size="48px"
  objectFit="contain"
  borderRadius="none"
/>
```

### Circular Thumbnail
```tsx
<ThumbnailPreview 
  src={avatarUrl}
  alt="Avatar"
  size="40px"
  borderRadius="full"
/>
```

## Related Components

- **FilePreview** (`FilePreview.tsx`) - Full file preview with modal for attachments
- **Image Upload** - Various image upload components in admin pages
- **AlbumPhotoPicker** - Zonerama gallery picker

## Future Enhancements

Potential improvements:

1. **Zoom controls** - Add +/- buttons in preview
2. **Multiple images** - Show gallery of images if multiple
3. **Image info** - Display dimensions, file size
4. **Edit quick action** - Add "Edit" button in preview
5. **Keyboard navigation** - Arrow keys to navigate between previews
6. **Full-screen mode** - Click to open full-screen view
7. **Crop preview** - Show how image will be cropped
8. **Compare mode** - Side-by-side comparison of OG image

## Dependencies

- `@chakra-ui/react` - UI components (Popover, Portal, Image)
- React - Core functionality

## Files Modified

1. `frontend/src/components/common/ThumbnailPreview.tsx` (NEW)
2. `frontend/src/pages/admin/ArticlesAdminPage.tsx` (UPDATED)
3. `frontend/src/pages/admin/AdminActivitiesPage.tsx` (UPDATED)
4. `frontend/src/pages/admin/PlayersAdminPage.tsx` (UPDATED)

## Testing Checklist

- [ ] Hover over article thumbnail - preview appears
- [ ] Hover over activity thumbnail - preview appears
- [ ] Hover over player photo - preview appears
- [ ] Preview shows correct image
- [ ] Preview closes when mouse leaves
- [ ] Delay prevents accidental triggers
- [ ] Preview doesn't get cut off by container
- [ ] Dark mode colors look correct
- [ ] Fallback images work (no image set)
- [ ] Lazy loading works (check network tab)
- [ ] Mobile tap behavior works
- [ ] No console errors