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

import ThumbnailPreview from '../../components/common/ThumbnailPreview';

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

Props

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:

<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:

{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:

<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

<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

<ThumbnailPreview 
  src={imageUrl}
  alt="Large preview"
  size="64px"
  previewSize="500px"
/>

Square Fit (for logos)

<ThumbnailPreview 
  src={logoUrl}
  alt="Logo"
  size="48px"
  objectFit="contain"
  borderRadius="none"
/>

Circular Thumbnail

<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