System Design #14: Design an Image Carousel / Gallery

// Let the browser handle scroll physics — it's smoother than JS
function CSSSnapCarousel({ items }: { items: CarouselItem[] }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const [activeIndex, setActiveIndex] = useState(0);
  
  // Track which slide is snapped
  useEffect(() => {
    const container = containerRef.current;
    if (!container) return;
    
    const observer = new IntersectionObserver(
      (entries) => {
        entries.forEach(entry => {
          if (entry.isIntersecting && entry.intersectionRatio > 0.5) {
            const index = Number(entry.target.getAttribute('data-index'));
            setActiveIndex(index);
          }
        });
      },
      { root: container, threshold: 0.5 }
    );
    
    container.querySelectorAll('[data-index]').forEach(el => observer.observe(el));
    return () => observer.disconnect();
  }, [items.length]);
  
  return (
    <div
      ref={containerRef}
      className="flex overflow-x-auto snap-x snap-mandatory scrollbar-hide"
      style={{ scrollBehavior: 'smooth' }}
      role="region"
      aria-roledescription="carousel"
      aria-label="Image gallery"
    >
      {items.map((item, i) => (
        <div
          key={item.id}
          data-index={i}
          className="flex-none w-full snap-center"
          role="group"
          aria-roledescription="slide"
          aria-label={`Slide ${i + 1} of ${items.length}`}
        >
          <CarouselSlide item={item} isActive={i === activeIndex} />
        </div>
      ))}
    </div>
  );
}

// For custom physics or complex animations
function TransformCarousel({ items }: { items: CarouselItem[] }) {
  const [offset, setOffset] = useState(0);
  const [isDragging, setIsDragging] = useState(false);
  const dragStart = useRef(0);
  const dragOffset = useRef(0);
  
  const goTo = (index: number) => {
    setOffset(-index * 100); // Percentage-based
  };
  
  return (
    <div className="overflow-hidden">
      <div
        className={cn("flex", !isDragging && "transition-transform duration-300")}
        style={{ transform: `translateX(${offset}%)` }}
        onPointerDown={handleDragStart}
        onPointerMove={handleDragMove}
        onPointerUp={handleDragEnd}
      >
        {items.map((item, i) => (
          <div key={item.id} className="flex-none w-full">
            <CarouselSlide item={item} />
          </div>
        ))}
      </div>
    </div>
  );
}

ImageGallery
├── CarouselContainer           // Main slide area
│   ├── CarouselSlide[]         // Individual slides
│   │   └── LazyImage           // Intersection-based loading
│   ├── PrevButton / NextButton // Arrow navigation
│   └── SwipeHandler            // Touch gesture detection
├── Indicators                  // Dots or thumbnail strip
│   └── ThumbnailStrip          // Scrollable thumbnails
├── Lightbox (Portal)           // Fullscreen overlay
│   ├── ZoomableImage           // Pinch-zoom + pan
│   ├── LightboxControls
│   └── LightboxThumbnails
└── AutoplayController          // Timer + pause logic

interface CarouselItem {
  id: string;
  type: 'image' | 'video';
  src: string;
  srcSet?: string;              // Responsive sources
  thumbnail?: string;           // Low-res placeholder
  blurHash?: string;            // BlurHash for skeleton
  alt: string;
  width: number;
  height: number;               // For aspect ratio (prevents CLS)
  caption?: string;
}

interface CarouselState {
  activeIndex: number;
  totalSlides: number;
  isAutoPlaying: boolean;
  isLightboxOpen: boolean;
  lightboxIndex: number;
  loadedIndices: Set<number>;   // Track which images are loaded
  direction: 'left' | 'right';  // For animation direction
}

// Only load: current slide, previous slide, next slide
function useAdjacentPreload(activeIndex: number, total: number) {
  const [loaded, setLoaded] = useState<Set<number>>(new Set([0]));
  
  useEffect(() => {
    const toLoad = new Set(loaded);
    toLoad.add(activeIndex);
    if (activeIndex > 0) toLoad.add(activeIndex - 1);
    if (activeIndex < total - 1) toLoad.add(activeIndex + 1);
    setLoaded(toLoad);
  }, [activeIndex, total]);
  
  return loaded;
}

function LazyImage({ item, shouldLoad }: { item: CarouselItem; shouldLoad: boolean }) {
  if (!shouldLoad) {
    // Show blurHash placeholder or aspect-ratio skeleton
    return (
      <div
        className="bg-muted animate-pulse"
        style={{ aspectRatio: `${item.width}/${item.height}` }}
      />
    );
  }
  
  return (
    <img
      src={item.src}
      srcSet={item.srcSet}
      alt={item.alt}
      loading="lazy"
      decoding="async"
      className="w-full h-full object-cover"
      style={{ aspectRatio: `${item.width}/${item.height}` }}
    />
  );
}

function useSwipeGesture(onSwipe: (dir: 'left' | 'right') => void) {
  const startX = useRef(0);
  const startY = useRef(0);
  const isDragging = useRef(false);
  
  const handlers = {
    onTouchStart: (e: React.TouchEvent) => {
      startX.current = e.touches[0].clientX;
      startY.current = e.touches[0].clientY;
      isDragging.current = true;
    },
    
    onTouchEnd: (e: React.TouchEvent) => {
      if (!isDragging.current) return;
      isDragging.current = false;
      
      const endX = e.changedTouches[0].clientX;
      const endY = e.changedTouches[0].clientY;
      const deltaX = endX - startX.current;
      const deltaY = endY - startY.current;
      
      // Only trigger if horizontal swipe is dominant
      if (Math.abs(deltaX) > Math.abs(deltaY) && Math.abs(deltaX) > 50) {
        onSwipe(deltaX > 0 ? 'right' : 'left');
      }
    },
  };
  
  return handlers;
}

function ZoomableImage({ src, alt }: { src: string; alt: string }) {
  const [scale, setScale] = useState(1);
  const [position, setPosition] = useState({ x: 0, y: 0 });
  const isDragging = useRef(false);
  const lastPos = useRef({ x: 0, y: 0 });
  
  const handleWheel = (e: React.WheelEvent) => {
    e.preventDefault();
    const newScale = Math.max(1, Math.min(5, scale - e.deltaY * 0.01));
    setScale(newScale);
    if (newScale === 1) setPosition({ x: 0, y: 0 }); // Reset pan
  };
  
  const handleDoubleClick = () => {
    if (scale > 1) {
      setScale(1);
      setPosition({ x: 0, y: 0 });
    } else {
      setScale(2.5);
    }
  };
  
  return (
    <div
      className="overflow-hidden cursor-grab active:cursor-grabbing"
      onWheel={handleWheel}
      onDoubleClick={handleDoubleClick}
      onPointerDown={startDrag}
      onPointerMove={drag}
      onPointerUp={endDrag}
    >
      <img
        src={src}
        alt={alt}
        className="max-h-[90vh] object-contain transition-transform duration-200"
        style={{
          transform: `scale(${scale}) translate(${position.x}px, ${position.y}px)`,
        }}
        draggable={false}
      />
    </div>
  );
}

// ALWAYS set aspect ratio to prevent CLS
function CarouselSlide({ item }: { item: CarouselItem }) {
  return (
    <div
      className="relative w-full"
      style={{ aspectRatio: `${item.width}/${item.height}` }}
    >
      <img
        src={item.src}
        alt={item.alt}
        className="absolute inset-0 w-full h-full object-cover"
      />
    </div>
  );
}

function useAutoplay(goNext: () => void, interval: number = 5000) {
  const [isPlaying, setIsPlaying] = useState(true);
  const timerRef = useRef<ReturnType<typeof setInterval>>();
  
  useEffect(() => {
    if (!isPlaying) return;
    timerRef.current = setInterval(goNext, interval);
    return () => clearInterval(timerRef.current);
  }, [isPlaying, interval]);
  
  // Pause on hover, focus, or reduced-motion preference
  const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
  
  useEffect(() => {
    if (prefersReducedMotion) setIsPlaying(false);
  }, [prefersReducedMotion]);
  
  return {
    isPlaying,
    pause: () => setIsPlaying(false),
    play: () => setIsPlaying(true),
    toggle: () => setIsPlaying(p => !p),
  };
}

// For massive galleries, only render slides near the viewport
function VirtualizedCarousel({ items }: { items: CarouselItem[] }) {
  const [activeIndex, setActiveIndex] = useState(0);
  
  // Only render 5 slides: [active-2, active-1, active, active+1, active+2]
  const windowSize = 5;
  const startIndex = Math.max(0, activeIndex - 2);
  const endIndex = Math.min(items.length - 1, activeIndex + 2);
  
  const visibleSlides = items.slice(startIndex, endIndex + 1).map((item, i) => ({
    ...item,
    virtualIndex: startIndex + i,
  }));
  
  return (
    <div className="relative overflow-hidden">
      {visibleSlides.map(slide => (
        <div
          key={slide.id}
          className="absolute inset-0 transition-transform duration-300"
          style={{
            transform: `translateX(${(slide.virtualIndex - activeIndex) * 100}%)`,
          }}
        >
          <CarouselSlide item={slide} />
        </div>
      ))}
    </div>
  );
}