@djangocfg/widget-visual 0.1.1

package/src/gallery/hooks/useImageDimensions.ts

@@ -0,0 +1,224 @@
+'use client'
+
+import { useEffect, useMemo, useRef, useState } from 'react';
+
+import type { GalleryMediaItem } from '../types'
+
+/**
+ * Image with loaded dimensions
+ */
+export interface ImageWithDimensions extends GalleryMediaItem {
+  width: number
+  height: number
+  loaded: boolean
+}
+
+/**
+ * Result of useImageDimensions hook
+ */
+export interface UseImageDimensionsResult {
+  /** Images with dimensions (loaded or from props) */
+  images: ImageWithDimensions[]
+  /** Whether all images have dimensions */
+  isReady: boolean
+  /** Whether currently loading */
+  isLoading: boolean
+  /** Number of images loaded */
+  loadedCount: number
+}
+
+/**
+ * Options for useImageDimensions
+ */
+export interface UseImageDimensionsOptions {
+  /** Only load dimensions for first N images */
+  maxToLoad?: number
+  /** Skip loading if dimensions already present */
+  skipIfPresent?: boolean
+  /** Timeout per image in ms */
+  timeout?: number
+}
+
+// Cache for loaded dimensions
+const dimensionsCache = new Map<string, { width: number; height: number }>()
+
+/**
+ * Load image dimensions
+ */
+function loadImageDimensions(
+  src: string,
+  timeout: number = 5000
+): Promise<{ width: number; height: number }> {
+  // Check cache
+  const cached = dimensionsCache.get(src)
+  if (cached) return Promise.resolve(cached)
+
+  return new Promise((resolve, reject) => {
+    const img = new Image()
+    const timeoutId = setTimeout(() => {
+      reject(new Error('Timeout loading image'))
+    }, timeout)
+
+    img.onload = () => {
+      clearTimeout(timeoutId)
+      const dims = { width: img.naturalWidth, height: img.naturalHeight }
+      dimensionsCache.set(src, dims)
+      resolve(dims)
+    }
+
+    img.onerror = () => {
+      clearTimeout(timeoutId)
+      reject(new Error('Failed to load image'))
+    }
+
+    img.src = src
+  })
+}
+
+/**
+ * Hook to load image dimensions for gallery images
+ *
+ * Uses thumbnail URL when available (faster to load)
+ * Caches results to avoid reloading
+ */
+export function useImageDimensions(
+  images: GalleryMediaItem[],
+  options: UseImageDimensionsOptions = {}
+): UseImageDimensionsResult {
+  const {
+    maxToLoad = 5,
+    skipIfPresent = true,
+    timeout = 5000,
+  } = options
+
+  // Create stable key from image IDs
+  const imageIds = useMemo(() => {
+    return images.slice(0, maxToLoad).map(img => img.id).join(',')
+  }, [images, maxToLoad])
+
+  // Track dimensions in a map by ID (stable across re-renders)
+  const dimensionsRef = useRef(new Map<string, { width: number; height: number; loaded: boolean }>())
+  const [version, setVersion] = useState(0) // Force re-render when dimensions load
+  const [isLoading, setIsLoading] = useState(true)
+  const loadingRef = useRef(false)
+  const prevImageIdsRef = useRef('')
+
+  // Initialize dimensions from props or cache
+  useEffect(() => {
+    const targetImages = images.slice(0, maxToLoad)
+    const idsChanged = prevImageIdsRef.current !== imageIds
+    prevImageIdsRef.current = imageIds
+
+    // Update dimensions map with any new images
+    for (const img of targetImages) {
+      if (!dimensionsRef.current.has(img.id)) {
+        // Check cache first
+        const src = img.thumbnail || img.src
+        const cached = dimensionsCache.get(src)
+
+        if (cached) {
+          dimensionsRef.current.set(img.id, { ...cached, loaded: true })
+        } else if (img.width && img.height && skipIfPresent) {
+          dimensionsRef.current.set(img.id, { width: img.width, height: img.height, loaded: true })
+        } else {
+          dimensionsRef.current.set(img.id, { width: 0, height: 0, loaded: false })
+        }
+      }
+    }
+
+    // Find images that need loading
+    const toLoad = targetImages.filter(img => {
+      const dims = dimensionsRef.current.get(img.id)
+      return !dims?.loaded
+    })
+
+    // Nothing to load
+    if (toLoad.length === 0) {
+      setIsLoading(false)
+      if (idsChanged) setVersion(v => v + 1)
+      return
+    }
+
+    // Already loading
+    if (loadingRef.current) return
+
+    loadingRef.current = true
+    setIsLoading(true)
+
+    // Load dimensions
+    Promise.all(
+      toLoad.map(async (img) => {
+        try {
+          const src = img.thumbnail || img.src
+          const dims = await loadImageDimensions(src, timeout)
+          dimensionsRef.current.set(img.id, { ...dims, loaded: true })
+          return { id: img.id, success: true }
+        } catch {
+          // Use default dimensions on error
+          dimensionsRef.current.set(img.id, { width: 1600, height: 900, loaded: true })
+          return { id: img.id, success: false }
+        }
+      })
+    ).then(() => {
+      loadingRef.current = false
+      setIsLoading(false)
+      setVersion(v => v + 1)
+    })
+  }, [imageIds, images, maxToLoad, skipIfPresent, timeout])
+
+  // Build result array
+  const result = useMemo((): ImageWithDimensions[] => {
+    return images.slice(0, maxToLoad).map(img => {
+      const dims = dimensionsRef.current.get(img.id)
+      return {
+        ...img,
+        width: dims?.width || img.width || 0,
+        height: dims?.height || img.height || 0,
+        loaded: dims?.loaded || false,
+      }
+    })
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [imageIds, version])
+
+  // Also return all images (not just maxToLoad) with available dimensions
+  const allImages = useMemo((): ImageWithDimensions[] => {
+    return images.map(img => {
+      const dims = dimensionsRef.current.get(img.id)
+      return {
+        ...img,
+        width: dims?.width || img.width || 0,
+        height: dims?.height || img.height || 0,
+        loaded: dims?.loaded || Boolean(img.width && img.height),
+      }
+    })
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [images, version])
+
+  const loadedCount = result.filter(img => img.loaded).length
+  const targetCount = Math.min(images.length, maxToLoad)
+
+  const isReady = !isLoading && loadedCount >= targetCount
+
+  return {
+    images: allImages,
+    isReady,
+    isLoading,
+    loadedCount,
+  }
+}
+
+/**
+ * Clear dimensions cache
+ */
+export function clearDimensionsCache(): void {
+  dimensionsCache.clear()
+}
+
+/**
+ * Get cached dimensions for an image
+ */
+export function getCachedDimensions(
+  src: string
+): { width: number; height: number } | null {
+  return dimensionsCache.get(src) || null
+}

package/src/gallery/hooks/usePinchZoom.ts

@@ -0,0 +1,239 @@
+'use client'
+
+import { useCallback, useRef, useState } from 'react';
+
+export interface PinchZoomState {
+  scale: number
+  x: number
+  y: number
+}
+
+export interface UsePinchZoomOptions {
+  minScale?: number
+  maxScale?: number
+  onZoomChange?: (zoomed: boolean) => void
+}
+
+export interface UsePinchZoomReturn {
+  state: PinchZoomState
+  isZoomed: boolean
+  handlers: {
+    onTouchStart: (e: React.TouchEvent) => void
+    onTouchMove: (e: React.TouchEvent) => void
+    onTouchEnd: (e: React.TouchEvent) => void
+  }
+  reset: () => void
+  zoomTo: (scale: number, x?: number, y?: number) => void
+}
+
+const INITIAL_STATE: PinchZoomState = { scale: 1, x: 0, y: 0 }
+
+/**
+ * Hook for pinch-to-zoom functionality on touch devices
+ */
+export function usePinchZoom(options: UsePinchZoomOptions = {}): UsePinchZoomReturn {
+  const { minScale = 1, maxScale = 3, onZoomChange } = options
+
+  const [state, setState] = useState<PinchZoomState>(INITIAL_STATE)
+
+  // Track touch state and container size
+  const touchRef = useRef<{
+    initialDistance: number
+    initialScale: number
+    initialX: number
+    initialY: number
+    centerX: number
+    centerY: number
+    isPinching: boolean
+    lastTap: number
+    containerWidth: number
+    containerHeight: number
+  }>({
+    initialDistance: 0,
+    initialScale: 1,
+    initialX: 0,
+    initialY: 0,
+    centerX: 0,
+    centerY: 0,
+    isPinching: false,
+    lastTap: 0,
+    containerWidth: 0,
+    containerHeight: 0,
+  })
+
+  const isZoomed = state.scale > 1.05
+
+  // Calculate distance between two touch points
+  const getDistance = useCallback((touches: React.TouchList): number => {
+    const a = touches[0]
+    const b = touches[1]
+    if (!a || !b) return 0
+    const dx = a.clientX - b.clientX
+    const dy = a.clientY - b.clientY
+    return Math.sqrt(dx * dx + dy * dy)
+  }, [])
+
+  // Get center point between two touches
+  const getCenter = useCallback((touches: React.TouchList): { x: number; y: number } => {
+    const a = touches[0]
+    const b = touches[1]
+    if (!a) return { x: 0, y: 0 }
+    if (!b) return { x: a.clientX, y: a.clientY }
+    return {
+      x: (a.clientX + b.clientX) / 2,
+      y: (a.clientY + b.clientY) / 2,
+    }
+  }, [])
+
+  // Calculate max pan based on container size and scale
+  const getMaxPan = useCallback((scale: number) => {
+    const { containerWidth, containerHeight } = touchRef.current
+    // When zoomed, allow panning up to half the "extra" size
+    // At 2x zoom on 400px container: can pan 200px in each direction
+    return {
+      x: (containerWidth * (scale - 1)) / 2,
+      y: (containerHeight * (scale - 1)) / 2,
+    }
+  }, [])
+
+  const handleTouchStart = useCallback((e: React.TouchEvent) => {
+    const touches = e.touches
+
+    // Store container dimensions from the element
+    const rect = e.currentTarget.getBoundingClientRect()
+    touchRef.current.containerWidth = rect.width
+    touchRef.current.containerHeight = rect.height
+
+    // Double tap to zoom
+    const touch0 = touches[0]
+    if (touches.length === 1 && touch0) {
+      const now = Date.now()
+      const timeSinceLastTap = now - touchRef.current.lastTap
+
+      if (timeSinceLastTap < 300) {
+        // Double tap detected
+        e.preventDefault()
+        if (isZoomed) {
+          setState(INITIAL_STATE)
+          onZoomChange?.(false)
+        } else {
+          const x = touch0.clientX - rect.left - rect.width / 2
+          const y = touch0.clientY - rect.top - rect.height / 2
+          setState({ scale: 2, x: -x * 0.5, y: -y * 0.5 })
+          onZoomChange?.(true)
+        }
+        touchRef.current.lastTap = 0
+        return
+      }
+
+      touchRef.current.lastTap = now
+
+      // Single finger - start pan (if zoomed)
+      if (isZoomed) {
+        touchRef.current.initialX = touch0.clientX - state.x
+        touchRef.current.initialY = touch0.clientY - state.y
+      }
+    }
+
+    // Two finger pinch
+    if (touches.length === 2) {
+      e.preventDefault()
+      touchRef.current.isPinching = true
+      touchRef.current.initialDistance = getDistance(touches)
+      touchRef.current.initialScale = state.scale
+
+      const center = getCenter(touches)
+      touchRef.current.centerX = center.x
+      touchRef.current.centerY = center.y
+      touchRef.current.initialX = state.x
+      touchRef.current.initialY = state.y
+    }
+  }, [isZoomed, state, getDistance, getCenter, onZoomChange])
+
+  const handleTouchMove = useCallback((e: React.TouchEvent) => {
+    const touches = e.touches
+
+    // Pinch zoom
+    if (touches.length === 2 && touchRef.current.isPinching) {
+      e.preventDefault()
+
+      const currentDistance = getDistance(touches)
+      const scaleDelta = currentDistance / touchRef.current.initialDistance
+      let newScale = touchRef.current.initialScale * scaleDelta
+
+      // Clamp scale
+      newScale = Math.max(minScale, Math.min(maxScale, newScale))
+
+      // Calculate new position to zoom toward center
+      const center = getCenter(touches)
+      const dx = center.x - touchRef.current.centerX
+      const dy = center.y - touchRef.current.centerY
+
+      // Apply pan limits
+      const maxPan = getMaxPan(newScale)
+      const newX = Math.max(-maxPan.x, Math.min(maxPan.x, touchRef.current.initialX + dx))
+      const newY = Math.max(-maxPan.y, Math.min(maxPan.y, touchRef.current.initialY + dy))
+
+      setState({
+        scale: newScale,
+        x: newX,
+        y: newY,
+      })
+
+      if (newScale > 1.05 !== isZoomed) {
+        onZoomChange?.(newScale > 1.05)
+      }
+    }
+
+    // Pan when zoomed (single finger)
+    const panTouch = touches[0]
+    if (touches.length === 1 && panTouch && isZoomed && !touchRef.current.isPinching) {
+      e.preventDefault()
+
+      const maxPan = getMaxPan(state.scale)
+      const newX = panTouch.clientX - touchRef.current.initialX
+      const newY = panTouch.clientY - touchRef.current.initialY
+
+      setState((prev) => ({
+        ...prev,
+        x: Math.max(-maxPan.x, Math.min(maxPan.x, newX)),
+        y: Math.max(-maxPan.y, Math.min(maxPan.y, newY)),
+      }))
+    }
+  }, [isZoomed, state.scale, minScale, maxScale, getDistance, getCenter, getMaxPan, onZoomChange])
+
+  const handleTouchEnd = useCallback((e: React.TouchEvent) => {
+    if (e.touches.length < 2) {
+      touchRef.current.isPinching = false
+    }
+
+    // Snap to 1 if close
+    if (state.scale < 1.1 && state.scale > 0.9) {
+      setState(INITIAL_STATE)
+      onZoomChange?.(false)
+    }
+  }, [state.scale, onZoomChange])
+
+  const reset = useCallback(() => {
+    setState(INITIAL_STATE)
+    onZoomChange?.(false)
+  }, [onZoomChange])
+
+  const zoomTo = useCallback((scale: number, x = 0, y = 0) => {
+    const clampedScale = Math.max(minScale, Math.min(maxScale, scale))
+    setState({ scale: clampedScale, x, y })
+    onZoomChange?.(clampedScale > 1.05)
+  }, [minScale, maxScale, onZoomChange])
+
+  return {
+    state,
+    isZoomed,
+    handlers: {
+      onTouchStart: handleTouchStart,
+      onTouchMove: handleTouchMove,
+      onTouchEnd: handleTouchEnd,
+    },
+    reset,
+    zoomTo,
+  }
+}

package/src/gallery/hooks/usePreloadImages.ts

@@ -0,0 +1,119 @@
+'use client'
+
+import { useEffect, useRef } from 'react';
+
+import type { GalleryMediaItem } from '../types'
+import { normalizeImageUrl } from '../utils'
+
+/** Max number of URLs to remember as "already preloaded" before evicting oldest */
+const MAX_PRELOAD_MEMORY = 200
+
+/**
+ * Preload adjacent images for smoother navigation
+ * Preloads prev and next images when current index changes
+ */
+export function usePreloadImages(
+  images: GalleryMediaItem[],
+  currentIndex: number,
+  preloadCount: number = 1
+): void {
+  // Insertion-ordered Set, used as a bounded LRU to avoid unbounded growth
+  const preloadedRef = useRef<Set<string>>(new Set())
+
+  useEffect(() => {
+    if (images.length === 0) return
+
+    const toPreload: string[] = []
+
+    // Collect indices to preload (current + adjacent)
+    for (let offset = -preloadCount; offset <= preloadCount; offset++) {
+      if (offset === 0) continue // Skip current, it's already loading
+
+      const index = (currentIndex + offset + images.length) % images.length
+      const image = images[index]
+      if (!image) continue
+
+      // Videos are not preloadable via Image(); skip them
+      if (image.type === 'video') continue
+
+      const src = normalizeImageUrl(image.src)
+      if (src && !preloadedRef.current.has(src)) {
+        toPreload.push(src)
+      }
+    }
+
+    if (toPreload.length === 0) return
+
+    const memory = preloadedRef.current
+    const loaders: HTMLImageElement[] = []
+
+    toPreload.forEach((src) => {
+      const img = new Image()
+      // Release the loader once finished so it can be GC'd
+      const cleanup = () => {
+        img.onload = null
+        img.onerror = null
+      }
+      img.onload = cleanup
+      img.onerror = cleanup
+      img.src = src
+      loaders.push(img)
+
+      memory.add(src)
+      // Evict oldest entries to keep the Set bounded
+      if (memory.size > MAX_PRELOAD_MEMORY) {
+        const oldest = memory.values().next().value
+        if (oldest !== undefined) memory.delete(oldest)
+      }
+    })
+
+    // Cancel in-flight loaders if the effect re-runs before they settle
+    return () => {
+      loaders.forEach((img) => {
+        img.onload = null
+        img.onerror = null
+        img.src = ''
+      })
+    }
+  }, [images, currentIndex, preloadCount])
+}
+
+/**
+ * Preload specific image URLs
+ */
+export function preloadImage(src: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const img = new Image()
+    const cleanup = () => {
+      img.onload = null
+      img.onerror = null
+    }
+    img.onload = () => {
+      cleanup()
+      resolve()
+    }
+    img.onerror = () => {
+      cleanup()
+      reject(new Error(`Failed to preload image: ${src}`))
+    }
+    img.src = normalizeImageUrl(src)
+  })
+}
+
+/**
+ * Preload multiple images with optional concurrency limit
+ */
+export async function preloadImages(
+  urls: string[],
+  concurrency: number = 3
+): Promise<void> {
+  const chunks: string[][] = []
+
+  for (let i = 0; i < urls.length; i += concurrency) {
+    chunks.push(urls.slice(i, i + concurrency))
+  }
+
+  for (const chunk of chunks) {
+    await Promise.allSettled(chunk.map(preloadImage))
+  }
+}

package/src/gallery/hooks/useSwipe.ts

@@ -0,0 +1,87 @@
+'use client'
+
+import { useCallback, useState } from 'react';
+
+import type { TouchEvent } from 'react'
+
+export interface UseSwipeOptions {
+  /** Minimum swipe distance in pixels */
+  minDistance?: number
+  /** Callback when swiped left */
+  onSwipeLeft?: () => void
+  /** Callback when swiped right */
+  onSwipeRight?: () => void
+  /** Callback when swiped up */
+  onSwipeUp?: () => void
+  /** Callback when swiped down */
+  onSwipeDown?: () => void
+}
+
+interface TouchPosition {
+  x: number
+  y: number
+}
+
+/**
+ * Hook for handling swipe gestures
+ */
+export function useSwipe({
+  minDistance = 50,
+  onSwipeLeft,
+  onSwipeRight,
+  onSwipeUp,
+  onSwipeDown,
+}: UseSwipeOptions = {}) {
+  const [touchStart, setTouchStart] = useState<TouchPosition | null>(null)
+  const [touchEnd, setTouchEnd] = useState<TouchPosition | null>(null)
+
+  const handleTouchStart = useCallback((e: TouchEvent) => {
+    setTouchEnd(null)
+    const touch = e.targetTouches[0]
+    if (touch) {
+      setTouchStart({ x: touch.clientX, y: touch.clientY })
+    }
+  }, [])
+
+  const handleTouchMove = useCallback((e: TouchEvent) => {
+    const touch = e.targetTouches[0]
+    if (touch) {
+      setTouchEnd({ x: touch.clientX, y: touch.clientY })
+    }
+  }, [])
+
+  const handleTouchEnd = useCallback(() => {
+    if (!touchStart || !touchEnd) return
+
+    const deltaX = touchStart.x - touchEnd.x
+    const deltaY = touchStart.y - touchEnd.y
+    const absX = Math.abs(deltaX)
+    const absY = Math.abs(deltaY)
+
+    // Determine if horizontal or vertical swipe
+    if (absX > absY && absX > minDistance) {
+      // Horizontal swipe
+      if (deltaX > 0) {
+        onSwipeLeft?.()
+      } else {
+        onSwipeRight?.()
+      }
+    } else if (absY > absX && absY > minDistance) {
+      // Vertical swipe
+      if (deltaY > 0) {
+        onSwipeUp?.()
+      } else {
+        onSwipeDown?.()
+      }
+    }
+
+    setTouchStart(null)
+    setTouchEnd(null)
+  }, [touchStart, touchEnd, minDistance, onSwipeLeft, onSwipeRight, onSwipeUp, onSwipeDown])
+
+  return {
+    onTouchStart: handleTouchStart,
+    onTouchMove: handleTouchMove,
+    onTouchEnd: handleTouchEnd,
+  }
+}