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;
}