@djangocfg/widget-visual 0.1.1

package/src/gallery/components/thumbnails/GalleryThumbnails.tsx

@@ -0,0 +1,198 @@
+'use client'
+
+import { memo, useRef, useEffect, useCallback, Suspense, lazy, useState, useMemo } from 'react'
+import { cn } from '@djangocfg/ui-core/lib'
+import type { GalleryThumbnailsProps } from '../../types'
+import { normalizeImageUrl } from '../../utils'
+import { ImageSpinner } from '../shared'
+
+// 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 [isLoaded, setIsLoaded] = useState(false)
+
+    // Reset loading state when image source changes
+    const imageSrc = useMemo(() => image?.thumbnail || image?.src, [image?.thumbnail, image?.src])
+    useEffect(() => {
+      setIsLoaded(false)
+    }, [imageSrc])
+
+    const handleClick = useCallback(() => {
+      onClick(index)
+    }, [onClick, index])
+
+    const handleLoad = useCallback(() => {
+      setIsLoaded(true)
+    }, [])
+
+    return (
+      <button
+        ref={ref}
+        type="button"
+        className={cn(
+          'relative flex-shrink-0 rounded-lg overflow-hidden bg-muted',
+          '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}
+      >
+        {/* Loading spinner */}
+        {!isLoaded && (
+          <div className="absolute inset-0 flex items-center justify-center">
+            <ImageSpinner size="sm" />
+          </div>
+        )}
+
+        <img
+          src={normalizeImageUrl(image.thumbnail || image.src)}
+          alt={image.alt || `Thumbnail ${index + 1}`}
+          className={cn(
+            'w-full h-full object-cover transition-opacity duration-200',
+            isLoaded ? 'opacity-100' : 'opacity-0'
+          )}
+          loading="lazy"
+          onLoad={handleLoad}
+        />
+
+        {/* Active overlay */}
+        {isActive && (
+          <div className="absolute inset-0 bg-primary/10" />
+        )}
+      </button>
+    )
+  }
+)

package/src/gallery/components/thumbnails/GalleryThumbnailsVirtual.tsx

@@ -0,0 +1,164 @@
+'use client'
+
+import { memo, useCallback, useEffect, useMemo, useState } from 'react'
+import { cn } from '@djangocfg/ui-core/lib'
+import { useVirtualList } from '../../hooks/useVirtualList'
+import type { GalleryThumbnailsProps } from '../../types'
+import { normalizeImageUrl } from '../../utils'
+import { ImageSpinner } from '../shared'
+
+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]
+          if (!image) return null
+          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 [isLoaded, setIsLoaded] = useState(false)
+
+  // Reset loading state when image source changes
+  const imageSrc = useMemo(() => image?.thumbnail || image?.src, [image?.thumbnail, image?.src])
+  useEffect(() => {
+    setIsLoaded(false)
+  }, [imageSrc])
+
+  const handleClick = useCallback(() => {
+    onClick(index)
+  }, [onClick, index])
+
+  const handleLoad = useCallback(() => {
+    setIsLoaded(true)
+  }, [])
+
+  return (
+    <button
+      type="button"
+      className={cn(
+        'absolute top-0 rounded-lg overflow-hidden bg-muted',
+        '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}
+    >
+      {/* Loading spinner */}
+      {!isLoaded && (
+        <div className="absolute inset-0 flex items-center justify-center">
+          <ImageSpinner size="sm" />
+        </div>
+      )}
+
+      <img
+        src={normalizeImageUrl(image.thumbnail || image.src)}
+        alt={image.alt || `Thumbnail ${index + 1}`}
+        className={cn(
+          'w-full h-full object-cover transition-opacity duration-200',
+          isLoaded ? 'opacity-100' : 'opacity-0'
+        )}
+        loading="lazy"
+        onLoad={handleLoad}
+      />
+
+      {/* Active overlay */}
+      {isActive && (
+        <div className="absolute inset-0 bg-primary/10" />
+      )}
+    </button>
+  )
+})

package/src/gallery/components/thumbnails/index.ts

@@ -0,0 +1,2 @@
+export { GalleryThumbnails } from './GalleryThumbnails'
+export { GalleryThumbnailsVirtual } from './GalleryThumbnailsVirtual'

package/src/gallery/gallery.stories.tsx

@@ -0,0 +1,182 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Gallery,
+  GalleryCompact,
+  GalleryGrid,
+  type GalleryMediaItem,
+} from '.';
+
+const CAT: GalleryMediaItem = { id: '1', src: 'https://images.unsplash.com/photo-1518791841217-8f162f1e1131?w=900', alt: 'Cat' };
+const DOG: GalleryMediaItem = { id: '2', src: 'https://images.unsplash.com/photo-1546182990-dffeafbe841d?w=900', alt: 'Dog' };
+const BIRDS: GalleryMediaItem = { id: '3', src: 'https://images.unsplash.com/photo-1444464666168-49d633b86797?w=900', alt: 'Birds' };
+const MOUNTAINS: GalleryMediaItem = { id: '4', src: 'https://images.unsplash.com/photo-1551279880-03041531948f?w=900', alt: 'Mountains' };
+const FOREST: GalleryMediaItem = { id: '5', src: 'https://images.unsplash.com/photo-1502082553048-f009c37129b9?w=900', alt: 'Forest' };
+const FIELD: GalleryMediaItem = { id: '6', src: 'https://images.unsplash.com/photo-1500382017468-9049fed747ef?w=900', alt: 'Field' };
+
+const IMAGES: GalleryMediaItem[] = [CAT, DOG, BIRDS, MOUNTAINS, FOREST, FIELD];
+
+const MIXED: GalleryMediaItem[] = [
+  CAT,
+  {
+    id: 'v1',
+    type: 'video',
+    src: 'https://images.unsplash.com/photo-1517694712202-14dd9538aa97?w=900',
+    videoSrc:
+      'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4',
+    videoType: 'video/mp4',
+    alt: 'Big Buck Bunny',
+  },
+  DOG,
+  BIRDS,
+  {
+    id: 'v2',
+    type: 'video',
+    src: 'https://images.unsplash.com/photo-1485846234645-a62644f84728?w=900',
+    videoSrc:
+      'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ElephantsDream.mp4',
+    videoType: 'video/mp4',
+    alt: 'Elephants Dream',
+  },
+  MOUNTAINS,
+];
+
+const meta = {
+  title: 'Widgets/Visual/Gallery',
+  component: GalleryCompact,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Gallery surface kit: `GalleryCompact` (card carousel), `GalleryGrid` (Airbnb-style mosaic), and `Gallery` (orchestrator with thumbnails + lightbox). Mix images and videos via `type: "video"` on items.',
+      },
+    },
+  },
+  args: { images: IMAGES },
+} satisfies Meta<typeof GalleryCompact>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Playground for `GalleryCompact` — tune the carousel surface used inside cards.
+ */
+export const Playground: Story = {
+  args: {
+    aspectRatio: '16/9',
+    showDots: true,
+    showArrows: true,
+    showCounter: true,
+    enableZoom: true,
+    maxDots: 5,
+  },
+  argTypes: {
+    aspectRatio: {
+      control: 'inline-radio',
+      options: ['16/9', '4/3', '3/2', '1/1', 'auto'],
+      table: { category: 'Layout' },
+    },
+    showDots: { control: 'boolean', table: { category: 'Chrome' } },
+    showArrows: { control: 'boolean', table: { category: 'Chrome' } },
+    showCounter: { control: 'boolean', table: { category: 'Chrome' } },
+    enableZoom: { control: 'boolean', table: { category: 'Behaviour' } },
+    maxDots: {
+      control: { type: 'number', min: 1, max: 10, step: 1 },
+      table: { category: 'Chrome' },
+    },
+  },
+  render: (args) => (
+    <div className="w-[640px]">
+      <GalleryCompact {...args} />
+    </div>
+  ),
+};
+
+/**
+ * Compact carousel inside a typical product card — the most common deployment.
+ */
+export const CompactCarousel: Story = {
+  render: () => (
+    <div className="grid grid-cols-1 md:grid-cols-2 gap-6 w-[720px]">
+      {[0, 1].map((i) => (
+        <div key={i} className="rounded-xl border border-border overflow-hidden bg-card">
+          <GalleryCompact
+            images={IMAGES}
+            aspectRatio="4/3"
+            showDots
+            showCounter
+            maxDots={5}
+          />
+          <div className="p-4">
+            <h3 className="font-medium text-sm">Listing {i + 1}</h3>
+            <p className="text-xs text-muted-foreground">$24,900 · 12k miles</p>
+          </div>
+        </div>
+      ))}
+    </div>
+  ),
+};
+
+/**
+ * Airbnb-style grid mosaic — layout auto-picks from image count, but you can pin one.
+ */
+export const GridMasonry: Story = {
+  render: () => (
+    <div className="space-y-8 w-[820px]">
+      <div>
+        <div className="text-xs font-medium text-muted-foreground mb-2">layout="mosaic-5"</div>
+        <GalleryGrid images={IMAGES} layout="mosaic-5" rounded="lg" gap={2} showMoreBadge />
+      </div>
+      <div>
+        <div className="text-xs font-medium text-muted-foreground mb-2">layout="hero-left"</div>
+        <GalleryGrid images={IMAGES.slice(0, 3)} layout="hero-left" rounded="lg" gap={2} />
+      </div>
+      <div>
+        <div className="text-xs font-medium text-muted-foreground mb-2">layout="grid-2x2"</div>
+        <GalleryGrid images={IMAGES.slice(0, 4)} layout="grid-2x2" rounded="lg" gap={2} />
+      </div>
+    </div>
+  ),
+};
+
+/**
+ * Full `Gallery` orchestrator — main image, thumbnail strip, click to open lightbox.
+ */
+export const Lightbox: Story = {
+  render: () => (
+    <div className="w-[820px]">
+      <Gallery
+        images={IMAGES}
+        previewMode="carousel"
+        showThumbnails
+        showControls
+        showCounter
+        enableLightbox
+        enableKeyboard
+        aspectRatio={16 / 9}
+      />
+    </div>
+  ),
+};
+
+/**
+ * Mixed media — `type: "video"` items render inline video players inside the gallery.
+ */
+export const MixedMedia: Story = {
+  render: () => (
+    <div className="w-[820px]">
+      <Gallery
+        images={MIXED}
+        previewMode="carousel"
+        showThumbnails
+        showControls
+        showCounter
+        enableLightbox
+        enableKeyboard
+        aspectRatio={16 / 9}
+      />
+    </div>
+  ),
+};

package/src/gallery/hooks/index.ts

@@ -0,0 +1,23 @@
+export { useGallery } from './useGallery'
+export type { UseGalleryOptions } from './useGallery'
+
+export { useSwipe } from './useSwipe'
+export type { UseSwipeOptions } from './useSwipe'
+
+export { usePreloadImages, preloadImage, preloadImages } from './usePreloadImages'
+
+export { useZoom } from './useZoom'
+export type { ZoomState, UseZoomOptions, UseZoomReturn } from './useZoom'
+
+export { usePinchZoom } from './usePinchZoom'
+export type { PinchZoomState, UsePinchZoomOptions, UsePinchZoomReturn } from './usePinchZoom'
+
+export { useVirtualList } from './useVirtualList'
+export type { VirtualListOptions, VirtualListReturn, VirtualItem } from './useVirtualList'
+
+export { useImageDimensions, clearDimensionsCache, getCachedDimensions } from './useImageDimensions'
+export type {
+  ImageWithDimensions,
+  UseImageDimensionsResult,
+  UseImageDimensionsOptions,
+} from './useImageDimensions'

package/src/gallery/hooks/useGallery.ts

@@ -0,0 +1,138 @@
+'use client'
+
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import type { GalleryMediaItem, GalleryContextValue } from '../types'
+
+export interface UseGalleryOptions {
+  /** Array of images */
+  images: GalleryMediaItem[]
+  /** Initial selected index */
+  initialIndex?: number
+  /** Loop navigation */
+  loop?: boolean
+  /** Callback when image changes */
+  onImageChange?: (index: number, image: GalleryMediaItem) => void
+}
+
+/**
+ * Hook for managing gallery state
+ */
+export function useGallery({
+  images,
+  initialIndex = 0,
+  loop = true,
+  onImageChange,
+}: UseGalleryOptions): GalleryContextValue {
+  const [currentIndex, setCurrentIndex] = useState(initialIndex)
+  const [isLightboxOpen, setIsLightboxOpen] = useState(false)
+  const [isZoomed, setIsZoomed] = useState(false)
+  const [isLoading, setIsLoading] = useState(false)
+
+  const total = images.length
+  const hasMultiple = total > 1
+  const currentImage = images[currentIndex] ?? null
+
+  // Reset state when images change
+  useEffect(() => {
+    if (currentIndex >= total) {
+      setCurrentIndex(Math.max(0, total - 1))
+    }
+  }, [total, currentIndex])
+
+  // Reset zoom when image changes
+  useEffect(() => {
+    setIsZoomed(false)
+    setIsLoading(true)
+  }, [currentIndex])
+
+  const goTo = useCallback(
+    (index: number) => {
+      if (index < 0 || index >= total) return
+      setCurrentIndex(index)
+      onImageChange?.(index, images[index]!)
+    },
+    [total, images, onImageChange]
+  )
+
+  const next = useCallback(() => {
+    if (!hasMultiple) return
+    const nextIndex = loop
+      ? (currentIndex + 1) % total
+      : Math.min(currentIndex + 1, total - 1)
+    if (nextIndex !== currentIndex) {
+      goTo(nextIndex)
+    }
+  }, [currentIndex, total, hasMultiple, loop, goTo])
+
+  const prev = useCallback(() => {
+    if (!hasMultiple) return
+    const prevIndex = loop
+      ? (currentIndex - 1 + total) % total
+      : Math.max(currentIndex - 1, 0)
+    if (prevIndex !== currentIndex) {
+      goTo(prevIndex)
+    }
+  }, [currentIndex, total, hasMultiple, loop, goTo])
+
+  const openLightbox = useCallback((index?: number) => {
+    if (index !== undefined) {
+      setCurrentIndex(index)
+    }
+    setIsLightboxOpen(true)
+    setIsZoomed(false)
+  }, [])
+
+  const closeLightbox = useCallback(() => {
+    setIsLightboxOpen(false)
+    setIsZoomed(false)
+  }, [])
+
+  const toggleZoom = useCallback(() => {
+    setIsZoomed((prev) => !prev)
+  }, [])
+
+  const setLoadingState = useCallback((loading: boolean) => {
+    setIsLoading(loading)
+  }, [])
+
+  return useMemo(
+    () => ({
+      // State
+      currentIndex,
+      isLightboxOpen,
+      isZoomed,
+      isLoading,
+      // Computed
+      images,
+      currentImage,
+      total,
+      hasMultiple,
+      // Actions
+      goTo,
+      next,
+      prev,
+      openLightbox,
+      closeLightbox,
+      toggleZoom,
+      setLoading: setLoadingState,
+    }),
+    [
+      currentIndex,
+      isLightboxOpen,
+      isZoomed,
+      isLoading,
+      images,
+      currentImage,
+      total,
+      hasMultiple,
+      goTo,
+      next,
+      prev,
+      openLightbox,
+      closeLightbox,
+      toggleZoom,
+      setLoadingState,
+    ]
+  )
+}