@djangocfg/ui-tools 2.1.110 → 2.1.112

package/src/tools/Gallery/hooks/usePinchZoom.ts

@@ -0,0 +1,234 @@
+'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 => {
+    if (touches.length < 2) return 0
+    const dx = touches[0].clientX - touches[1].clientX
+    const dy = touches[0].clientY - touches[1].clientY
+    return Math.sqrt(dx * dx + dy * dy)
+  }, [])
+
+  // Get center point between two touches
+  const getCenter = useCallback((touches: React.TouchList): { x: number; y: number } => {
+    if (touches.length < 2) {
+      return { x: touches[0].clientX, y: touches[0].clientY }
+    }
+    return {
+      x: (touches[0].clientX + touches[1].clientX) / 2,
+      y: (touches[0].clientY + touches[1].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
+    if (touches.length === 1) {
+      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 = touches[0].clientX - rect.left - rect.width / 2
+          const y = touches[0].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 = touches[0].clientX - state.x
+        touchRef.current.initialY = touches[0].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)
+    if (touches.length === 1 && isZoomed && !touchRef.current.isPinching) {
+      e.preventDefault()
+
+      const maxPan = getMaxPan(state.scale)
+      const newX = touches[0].clientX - touchRef.current.initialX
+      const newY = touches[0].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/tools/Gallery/hooks/usePreloadImages.ts

@@ -0,0 +1,71 @@
+'use client'
+
+import { useEffect, useRef } from 'react'
+import type { GalleryMediaItem } from '../types'
+
+/**
+ * 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 {
+  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 && !preloadedRef.current.has(image.src)) {
+        toPreload.push(image.src)
+      }
+    }
+
+    // Preload images
+    toPreload.forEach((src) => {
+      const img = new Image()
+      img.src = src
+      preloadedRef.current.add(src)
+    })
+  }, [images, currentIndex, preloadCount])
+}
+
+/**
+ * Preload specific image URLs
+ */
+export function preloadImage(src: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const img = new Image()
+    img.onload = () => resolve()
+    img.onerror = reject
+    img.src = 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/tools/Gallery/hooks/useSwipe.ts

@@ -0,0 +1,86 @@
+'use client'
+
+import { useState, useCallback } 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,
+  }
+}

package/src/tools/Gallery/hooks/useVirtualList.ts

@@ -0,0 +1,129 @@
+'use client'
+
+import { useState, useEffect, useCallback, useMemo, useRef } from 'react'
+
+export interface VirtualListOptions {
+  /** Total number of items */
+  itemCount: number
+  /** Width of each item in pixels */
+  itemWidth: number
+  /** Gap between items in pixels */
+  gap?: number
+  /** Number of items to render outside visible area */
+  overscan?: number
+}
+
+export interface VirtualListReturn {
+  /** Container ref to attach to scrollable element */
+  containerRef: React.RefObject<HTMLDivElement | null>
+  /** Total width of all items (for spacer) */
+  totalWidth: number
+  /** Visible items with their positions */
+  virtualItems: VirtualItem[]
+  /** Scroll to specific index */
+  scrollToIndex: (index: number, behavior?: ScrollBehavior) => void
+}
+
+export interface VirtualItem {
+  index: number
+  start: number
+  size: number
+}
+
+/**
+ * Hook for virtualizing horizontal list items
+ * Only renders items that are visible + overscan buffer
+ */
+export function useVirtualList({
+  itemCount,
+  itemWidth,
+  gap = 8,
+  overscan = 3,
+}: VirtualListOptions): VirtualListReturn {
+  const containerRef = useRef<HTMLDivElement>(null)
+  const [scrollLeft, setScrollLeft] = useState(0)
+  const [containerWidth, setContainerWidth] = useState(0)
+
+  // Calculate total width
+  const totalWidth = useMemo(() => {
+    if (itemCount === 0) return 0
+    return itemCount * itemWidth + (itemCount - 1) * gap
+  }, [itemCount, itemWidth, gap])
+
+  // Handle scroll
+  useEffect(() => {
+    const container = containerRef.current
+    if (!container) return
+
+    const handleScroll = () => {
+      setScrollLeft(container.scrollLeft)
+    }
+
+    const handleResize = () => {
+      setContainerWidth(container.clientWidth)
+    }
+
+    // Initial measurements
+    handleResize()
+    handleScroll()
+
+    container.addEventListener('scroll', handleScroll, { passive: true })
+
+    const resizeObserver = new ResizeObserver(handleResize)
+    resizeObserver.observe(container)
+
+    return () => {
+      container.removeEventListener('scroll', handleScroll)
+      resizeObserver.disconnect()
+    }
+  }, [])
+
+  // Calculate visible items
+  const virtualItems = useMemo((): VirtualItem[] => {
+    if (itemCount === 0 || containerWidth === 0) return []
+
+    const itemWithGap = itemWidth + gap
+
+    // Find start and end indices
+    const startIndex = Math.max(0, Math.floor(scrollLeft / itemWithGap) - overscan)
+    const endIndex = Math.min(
+      itemCount - 1,
+      Math.ceil((scrollLeft + containerWidth) / itemWithGap) + overscan
+    )
+
+    const items: VirtualItem[] = []
+    for (let i = startIndex; i <= endIndex; i++) {
+      items.push({
+        index: i,
+        start: i * itemWithGap,
+        size: itemWidth,
+      })
+    }
+
+    return items
+  }, [itemCount, itemWidth, gap, scrollLeft, containerWidth, overscan])
+
+  // Scroll to index
+  const scrollToIndex = useCallback(
+    (index: number, behavior: ScrollBehavior = 'smooth') => {
+      const container = containerRef.current
+      if (!container) return
+
+      const itemWithGap = itemWidth + gap
+      const targetScroll = index * itemWithGap - containerWidth / 2 + itemWidth / 2
+
+      container.scrollTo({
+        left: Math.max(0, targetScroll),
+        behavior,
+      })
+    },
+    [itemWidth, gap, containerWidth]
+  )
+
+  return {
+    containerRef,
+    totalWidth,
+    virtualItems,
+    scrollToIndex,
+  }
+}