@djangocfg/ui-tools 2.1.110 → 2.1.112

package/src/tools/Gallery/components/GalleryLightbox.tsx

@@ -0,0 +1,331 @@
+'use client'
+
+import { memo, useEffect, useCallback, useState, useMemo } from 'react'
+import { createPortal } from 'react-dom'
+import { cn } from '@djangocfg/ui-core/lib'
+import { useTypedT, type I18nTranslations } from '@djangocfg/i18n'
+import { X, ChevronLeft, ChevronRight, Download, Share2, ZoomIn, ZoomOut } from 'lucide-react'
+import { useSwipe } from '../hooks/useSwipe'
+import { usePreloadImages } from '../hooks/usePreloadImages'
+import { useZoom } from '../hooks/useZoom'
+import { GalleryMedia } from './GalleryMedia'
+import { GalleryThumbnails } from './GalleryThumbnails'
+import type { GalleryLightboxProps } from '../types'
+
+/**
+ * GalleryLightbox - Fullscreen image viewer with zoom and navigation
+ *
+ * Features:
+ * - Preloads adjacent images for smooth navigation
+ * - Loading skeleton while image loads
+ * - Zoom with pan/drag support
+ * - Keyboard and swipe navigation
+ */
+export const GalleryLightbox = memo(function GalleryLightbox({
+  open,
+  onClose,
+  images,
+  currentIndex,
+  onIndexChange,
+  showThumbnails = true,
+  enableZoom = true,
+  enableDownload = true,
+  enableShare = true,
+  title,
+}: GalleryLightboxProps) {
+  const t = useTypedT<I18nTranslations>()
+  const [mounted, setMounted] = useState(false)
+
+  // Translations
+  const labels = useMemo(() => ({
+    lightbox: t('tools.gallery.lightbox'),
+    previous: t('tools.gallery.previous'),
+    next: t('tools.gallery.next'),
+    close: t('tools.gallery.close'),
+    download: t('tools.gallery.download'),
+    share: t('tools.gallery.share'),
+    zoomIn: t('tools.image.zoomIn'),
+    zoomOut: t('tools.image.zoomOut'),
+  }), [t])
+
+  // Unified zoom (handles both desktop click/drag and mobile pinch/tap)
+  const zoom = useZoom({
+    minScale: 1,
+    maxScale: 3,
+    desktopScale: 2,
+  })
+
+  // Prepare data
+  const currentImage = useMemo(() => images[currentIndex], [images, currentIndex])
+  const hasMultiple = useMemo(() => images.length > 1, [images.length])
+  const { isZoomed, isDragging } = zoom
+
+  // Preload adjacent images when lightbox is open
+  usePreloadImages(open ? images : [], currentIndex, 2)
+
+  // Handle client-side mounting for portal
+  useEffect(() => {
+    setMounted(true)
+  }, [])
+
+  // Reset zoom when image changes
+  useEffect(() => {
+    zoom.reset()
+  }, [currentIndex])
+
+  // Prevent body scroll when open
+  useEffect(() => {
+    if (open) {
+      const originalStyle = window.getComputedStyle(document.body).overflow
+      document.body.style.overflow = 'hidden'
+      return () => {
+        document.body.style.overflow = originalStyle
+      }
+    }
+  }, [open])
+
+  // Navigation handlers
+  const goToPrev = useCallback(() => {
+    if (hasMultiple) {
+      onIndexChange((currentIndex - 1 + images.length) % images.length)
+    }
+  }, [hasMultiple, currentIndex, images.length, onIndexChange])
+
+  const goToNext = useCallback(() => {
+    if (hasMultiple) {
+      onIndexChange((currentIndex + 1) % images.length)
+    }
+  }, [hasMultiple, currentIndex, images.length, onIndexChange])
+
+  // Keyboard navigation
+  useEffect(() => {
+    if (!open) return
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      switch (e.key) {
+        case 'Escape':
+          if (isZoomed) {
+            zoom.reset()
+          } else {
+            onClose()
+          }
+          break
+        case 'ArrowLeft':
+          if (!isZoomed) goToPrev()
+          break
+        case 'ArrowRight':
+          if (!isZoomed) goToNext()
+          break
+      }
+    }
+
+    window.addEventListener('keydown', handleKeyDown)
+    return () => window.removeEventListener('keydown', handleKeyDown)
+  }, [open, isZoomed, goToPrev, goToNext, onClose, zoom])
+
+  // Swipe handlers (disabled when zoomed)
+  const swipeHandlers = useSwipe({
+    onSwipeLeft: isZoomed ? undefined : goToNext,
+    onSwipeRight: isZoomed ? undefined : goToPrev,
+  })
+
+  // Action handlers
+  const handleDownload = useCallback(() => {
+    if (!currentImage) return
+    const link = document.createElement('a')
+    link.href = currentImage.src
+    link.download = currentImage.alt || `image-${currentIndex + 1}.jpg`
+    document.body.appendChild(link)
+    link.click()
+    document.body.removeChild(link)
+  }, [currentImage, currentIndex])
+
+  const handleShare = useCallback(async () => {
+    if (!currentImage) return
+    if (navigator.share) {
+      try {
+        await navigator.share({
+          title: title || 'Image',
+          url: currentImage.src,
+        })
+      } catch {
+        // User cancelled or error
+      }
+    } else {
+      await navigator.clipboard.writeText(currentImage.src)
+    }
+  }, [currentImage, title])
+
+  const handleToggleZoom = useCallback(() => {
+    zoom.toggleZoom()
+  }, [zoom])
+
+  const handleContentClick = useCallback((e: React.MouseEvent) => {
+    e.stopPropagation()
+  }, [])
+
+  if (!open || !mounted) return null
+
+  const lightbox = (
+    <div
+      className={cn(
+        'fixed inset-0 z-50',
+        'backdrop-blur-sm',
+        'animate-in fade-in-0 duration-200'
+      )}
+      style={{ backgroundColor: 'rgba(0, 0, 0, 0.85)' }}
+      onClick={onClose}
+      role="dialog"
+      aria-modal="true"
+      aria-label={labels.lightbox}
+    >
+      {/* Content */}
+      <div
+        className="relative w-full h-full flex flex-col"
+        onClick={handleContentClick}
+        {...swipeHandlers}
+      >
+        {/* Header */}
+        <div className="absolute top-0 left-0 right-0 z-10 flex items-center justify-between p-4">
+          {/* Title & Counter */}
+          <div className="text-white">
+            {title && <div className="font-medium">{title}</div>}
+            {hasMultiple && (
+              <div className="text-sm text-white/70">
+                {currentIndex + 1} / {images.length}
+              </div>
+            )}
+          </div>
+
+          {/* Actions */}
+          <div className="flex items-center gap-2">
+            {enableZoom && (
+              <button
+                type="button"
+                className="p-2 rounded-full bg-white/10 hover:bg-white/20 text-white transition-colors"
+                onClick={handleToggleZoom}
+                aria-label={isZoomed ? labels.zoomOut : labels.zoomIn}
+              >
+                {isZoomed ? (
+                  <ZoomOut className="w-5 h-5" />
+                ) : (
+                  <ZoomIn className="w-5 h-5" />
+                )}
+              </button>
+            )}
+
+            {enableDownload && (
+              <button
+                type="button"
+                className="p-2 rounded-full bg-white/10 hover:bg-white/20 text-white transition-colors"
+                onClick={handleDownload}
+                aria-label={labels.download}
+              >
+                <Download className="w-5 h-5" />
+              </button>
+            )}
+
+            {enableShare && (
+              <button
+                type="button"
+                className="p-2 rounded-full bg-white/10 hover:bg-white/20 text-white transition-colors"
+                onClick={handleShare}
+                aria-label={labels.share}
+              >
+                <Share2 className="w-5 h-5" />
+              </button>
+            )}
+
+            <button
+              type="button"
+              className="p-2 rounded-full bg-white/10 hover:bg-white/20 text-white transition-colors"
+              onClick={onClose}
+              aria-label={labels.close}
+            >
+              <X className="w-5 h-5" />
+            </button>
+          </div>
+        </div>
+
+        {/* Main Image */}
+        <div className="flex-1 flex items-center justify-center p-4 pt-16 pb-24 overflow-hidden">
+          {currentImage && (
+            <div
+              className={cn(
+                'relative max-w-full max-h-full select-none',
+                isZoomed ? 'cursor-grab' : enableZoom ? 'cursor-zoom-in' : 'cursor-default',
+                isDragging && 'cursor-grabbing'
+              )}
+              {...(enableZoom ? zoom.handlers : {})}
+              style={{
+                transform: isZoomed
+                  ? `scale(${zoom.state.scale}) translate(${zoom.state.x}px, ${zoom.state.y}px)`
+                  : 'scale(1)',
+                transition: isDragging ? 'none' : 'transform 0.3s ease-out',
+                touchAction: 'none',
+              }}
+            >
+              <GalleryMedia
+                media={currentImage}
+                className="max-w-full max-h-[calc(100vh-10rem)] object-contain pointer-events-none"
+                showLoading
+                priority
+                autoPlay
+              />
+            </div>
+          )}
+        </div>
+
+        {/* Navigation Arrows */}
+        {hasMultiple && !isZoomed && (
+          <>
+            <button
+              type="button"
+              className={cn(
+                'absolute left-4 top-1/2 -translate-y-1/2 z-10',
+                'w-12 h-12 rounded-full',
+                'bg-white/10 hover:bg-white/20 text-white',
+                'flex items-center justify-center transition-colors',
+                'focus:outline-none focus-visible:ring-2 focus-visible:ring-white'
+              )}
+              onClick={goToPrev}
+              aria-label={labels.previous}
+            >
+              <ChevronLeft className="w-6 h-6" />
+            </button>
+
+            <button
+              type="button"
+              className={cn(
+                'absolute right-4 top-1/2 -translate-y-1/2 z-10',
+                'w-12 h-12 rounded-full',
+                'bg-white/10 hover:bg-white/20 text-white',
+                'flex items-center justify-center transition-colors',
+                'focus:outline-none focus-visible:ring-2 focus-visible:ring-white'
+              )}
+              onClick={goToNext}
+              aria-label={labels.next}
+            >
+              <ChevronRight className="w-6 h-6" />
+            </button>
+          </>
+        )}
+
+        {/* Thumbnails */}
+        {showThumbnails && hasMultiple && !isZoomed && (
+          <div className="absolute bottom-0 left-0 right-0 p-4 bg-gradient-to-t from-black/50 to-transparent">
+            <GalleryThumbnails
+              images={images}
+              currentIndex={currentIndex}
+              onSelect={onIndexChange}
+              size="sm"
+              className="justify-center"
+            />
+          </div>
+        )}
+      </div>
+    </div>
+  )
+
+  return createPortal(lightbox, document.body)
+})

package/src/tools/Gallery/components/GalleryMedia.tsx

@@ -0,0 +1,66 @@
+'use client'
+
+import { memo } from 'react'
+import { GalleryImage as GalleryImageComponent } from './GalleryImage'
+import { GalleryVideo } from './GalleryVideo'
+import type { GalleryMediaItem } from '../types'
+
+export interface GalleryMediaProps {
+  /** Media data */
+  media: GalleryMediaItem
+  /** Whether to show loading skeleton */
+  showLoading?: boolean
+  /** On load callback */
+  onLoad?: () => void
+  /** On error callback */
+  onError?: () => void
+  /** On click callback */
+  onClick?: () => void
+  /** Priority loading (images only) */
+  priority?: boolean
+  /** Autoplay video */
+  autoPlay?: boolean
+  /** Additional CSS class */
+  className?: string
+}
+
+/**
+ * GalleryMedia - Renders image or video based on media type
+ */
+export const GalleryMedia = memo(function GalleryMedia({
+  media,
+  showLoading = true,
+  onLoad,
+  onError,
+  onClick,
+  priority = false,
+  autoPlay = false,
+  className,
+}: GalleryMediaProps) {
+  const isVideo = media.type === 'video' && media.videoSrc
+
+  if (isVideo) {
+    return (
+      <GalleryVideo
+        media={media}
+        autoPlay={autoPlay}
+        muted
+        loop
+        showControls
+        className={className}
+      />
+    )
+  }
+
+  return (
+    <GalleryImageComponent
+      image={media}
+      showLoading={showLoading}
+      onLoad={onLoad}
+      onError={onError}
+      onClick={onClick}
+      priority={priority}
+      className={className}
+    />
+  )
+})

package/src/tools/Gallery/components/GalleryThumbnails.tsx

@@ -0,0 +1,173 @@
+'use client'
+
+import { memo, useRef, useEffect, useCallback, Suspense, lazy } from 'react'
+import { cn } from '@djangocfg/ui-core/lib'
+import type { GalleryThumbnailsProps } from '../types'
+
+// Lazy load virtualized thumbnails - only for 50+ images
+const GalleryThumbnailsVirtual = lazy(() =>
+  import('./GalleryThumbnailsVirtual').then((mod) => ({ default: mod.GalleryThumbnailsVirtual }))
+)
+
+const SIZES = {
+  sm: 'w-14 h-10',
+  md: 'w-20 h-14',
+  lg: 'w-24 h-18',
+} as const
+
+/** Threshold for switching to virtualized rendering */
+const VIRTUALIZATION_THRESHOLD = 50
+
+/**
+ * GalleryThumbnails - Horizontal scrollable thumbnail strip
+ * Automatically switches to virtualized rendering for 50+ images
+ */
+export const GalleryThumbnails = memo(function GalleryThumbnails(props: GalleryThumbnailsProps) {
+  const { images } = props
+
+  // Use virtualized version for large galleries (lazy loaded)
+  if (images.length >= VIRTUALIZATION_THRESHOLD) {
+    return (
+      <Suspense fallback={<ThumbnailsSkeleton className={props.className} />}>
+        <GalleryThumbnailsVirtual {...props} />
+      </Suspense>
+    )
+  }
+
+  return <GalleryThumbnailsRegular {...props} />
+})
+
+// Simple skeleton for loading state
+const ThumbnailsSkeleton = memo(function ThumbnailsSkeleton({ className }: { className?: string }) {
+  return (
+    <div className={cn('flex gap-2 overflow-hidden p-1', className)}>
+      {Array.from({ length: 5 }).map((_, i) => (
+        <div key={i} className="w-20 h-14 rounded-lg bg-muted animate-pulse flex-shrink-0" />
+      ))}
+    </div>
+  )
+})
+
+/**
+ * Regular (non-virtualized) thumbnails for smaller galleries
+ */
+const GalleryThumbnailsRegular = memo(function GalleryThumbnailsRegular({
+  images,
+  currentIndex,
+  onSelect,
+  size = 'md',
+  className,
+}: GalleryThumbnailsProps) {
+  const containerRef = useRef<HTMLDivElement>(null)
+  const itemRefs = useRef<(HTMLButtonElement | null)[]>([])
+
+  // Scroll active thumbnail into view
+  useEffect(() => {
+    const activeItem = itemRefs.current[currentIndex]
+    if (activeItem && containerRef.current) {
+      const container = containerRef.current
+      const itemLeft = activeItem.offsetLeft
+      const itemWidth = activeItem.offsetWidth
+      const containerWidth = container.offsetWidth
+      const scrollLeft = container.scrollLeft
+
+      // Check if item is not fully visible
+      if (itemLeft < scrollLeft || itemLeft + itemWidth > scrollLeft + containerWidth) {
+        activeItem.scrollIntoView({
+          behavior: 'smooth',
+          block: 'nearest',
+          inline: 'center',
+        })
+      }
+    }
+  }, [currentIndex])
+
+  // Handle thumbnail click
+  const handleClick = useCallback(
+    (index: number) => {
+      onSelect(index)
+    },
+    [onSelect]
+  )
+
+  if (images.length <= 1) return null
+
+  return (
+    <div
+      ref={containerRef}
+      className={cn(
+        'flex gap-2 overflow-x-auto scrollbar-hide p-1',
+        className
+      )}
+    >
+      {images.map((image, index) => (
+        <ThumbnailButton
+          key={image.id}
+          ref={(el) => {
+            itemRefs.current[index] = el
+          }}
+          image={image}
+          index={index}
+          isActive={index === currentIndex}
+          size={size}
+          onClick={handleClick}
+        />
+      ))}
+    </div>
+  )
+})
+
+// Extracted thumbnail button component
+interface ThumbnailButtonProps {
+  image: { id: string; src: string; thumbnail?: string; alt?: string }
+  index: number
+  isActive: boolean
+  size: 'sm' | 'md' | 'lg'
+  onClick: (index: number) => void
+}
+
+const ThumbnailButton = memo(
+  function ThumbnailButton({
+    image,
+    index,
+    isActive,
+    size,
+    onClick,
+    ref,
+  }: ThumbnailButtonProps & { ref?: React.Ref<HTMLButtonElement> }) {
+    const handleClick = useCallback(() => {
+      onClick(index)
+    }, [onClick, index])
+
+    return (
+      <button
+        ref={ref}
+        type="button"
+        className={cn(
+          'relative flex-shrink-0 rounded-lg overflow-hidden',
+          'border-2 transition-all duration-200',
+          'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary',
+          SIZES[size],
+          isActive
+            ? 'border-primary ring-1 ring-primary/30'
+            : 'border-transparent hover:border-muted-foreground/30'
+        )}
+        onClick={handleClick}
+        aria-label={`View image ${index + 1}`}
+        aria-current={isActive ? 'true' : undefined}
+      >
+        <img
+          src={image.thumbnail || image.src}
+          alt={image.alt || `Thumbnail ${index + 1}`}
+          className="w-full h-full object-cover"
+          loading="lazy"
+        />
+
+        {/* Active overlay */}
+        {isActive && (
+          <div className="absolute inset-0 bg-primary/10" />
+        )}
+      </button>
+    )
+  }
+)

package/src/tools/Gallery/components/GalleryThumbnailsVirtual.tsx

@@ -0,0 +1,138 @@
+'use client'
+
+import { memo, useCallback, useEffect } from 'react'
+import { cn } from '@djangocfg/ui-core/lib'
+import { useVirtualList } from '../hooks/useVirtualList'
+import type { GalleryThumbnailsProps } from '../types'
+
+const SIZES = {
+  sm: { width: 56, height: 40 },
+  md: { width: 80, height: 56 },
+  lg: { width: 96, height: 72 },
+} as const
+
+/**
+ * GalleryThumbnailsVirtual - Virtualized thumbnail strip for large galleries
+ * Only renders visible thumbnails + buffer for optimal performance
+ */
+export const GalleryThumbnailsVirtual = memo(function GalleryThumbnailsVirtual({
+  images,
+  currentIndex,
+  onSelect,
+  size = 'md',
+  className,
+}: GalleryThumbnailsProps) {
+  const dimensions = SIZES[size]
+
+  const { containerRef, totalWidth, virtualItems, scrollToIndex } = useVirtualList({
+    itemCount: images.length,
+    itemWidth: dimensions.width,
+    gap: 8,
+    overscan: 3,
+  })
+
+  // Scroll active thumbnail into view
+  useEffect(() => {
+    scrollToIndex(currentIndex)
+  }, [currentIndex, scrollToIndex])
+
+  // Handle thumbnail click
+  const handleClick = useCallback(
+    (index: number) => {
+      onSelect(index)
+    },
+    [onSelect]
+  )
+
+  if (images.length <= 1) return null
+
+  return (
+    <div
+      ref={containerRef}
+      className={cn(
+        'relative overflow-x-auto scrollbar-hide p-1',
+        className
+      )}
+    >
+      {/* Spacer for total scroll width */}
+      <div style={{ width: totalWidth, height: dimensions.height }} className="relative">
+        {virtualItems.map((virtualItem) => {
+          const image = images[virtualItem.index]
+          const isActive = virtualItem.index === currentIndex
+
+          return (
+            <VirtualThumbnail
+              key={image.id}
+              image={image}
+              index={virtualItem.index}
+              isActive={isActive}
+              left={virtualItem.start}
+              width={dimensions.width}
+              height={dimensions.height}
+              onClick={handleClick}
+            />
+          )
+        })}
+      </div>
+    </div>
+  )
+})
+
+// Extracted virtual thumbnail component
+interface VirtualThumbnailProps {
+  image: { id: string; src: string; thumbnail?: string; alt?: string }
+  index: number
+  isActive: boolean
+  left: number
+  width: number
+  height: number
+  onClick: (index: number) => void
+}
+
+const VirtualThumbnail = memo(function VirtualThumbnail({
+  image,
+  index,
+  isActive,
+  left,
+  width,
+  height,
+  onClick,
+}: VirtualThumbnailProps) {
+  const handleClick = useCallback(() => {
+    onClick(index)
+  }, [onClick, index])
+
+  return (
+    <button
+      type="button"
+      className={cn(
+        'absolute top-0 rounded-lg overflow-hidden',
+        'border-2 transition-all duration-200',
+        'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary',
+        isActive
+          ? 'border-primary ring-1 ring-primary/30'
+          : 'border-transparent hover:border-muted-foreground/30'
+      )}
+      style={{
+        left,
+        width,
+        height,
+      }}
+      onClick={handleClick}
+      aria-label={`View image ${index + 1}`}
+      aria-current={isActive ? 'true' : undefined}
+    >
+      <img
+        src={image.thumbnail || image.src}
+        alt={image.alt || `Thumbnail ${index + 1}`}
+        className="w-full h-full object-cover"
+        loading="lazy"
+      />
+
+      {/* Active overlay */}
+      {isActive && (
+        <div className="absolute inset-0 bg-primary/10" />
+      )}
+    </button>
+  )
+})