@djangocfg/ui-tools 2.1.109 → 2.1.111

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

@@ -0,0 +1,316 @@
+'use client'
+
+import { useCallback, useRef, useState } from 'react'
+
+export interface ZoomState {
+  scale: number
+  x: number
+  y: number
+}
+
+export interface UseZoomOptions {
+  minScale?: number
+  maxScale?: number
+  desktopScale?: number
+  onZoomChange?: (zoomed: boolean) => void
+}
+
+export interface UseZoomReturn {
+  state: ZoomState
+  isZoomed: boolean
+  isDragging: boolean
+  handlers: {
+    onTouchStart: (e: React.TouchEvent) => void
+    onTouchMove: (e: React.TouchEvent) => void
+    onTouchEnd: (e: React.TouchEvent) => void
+    onClick: (e: React.MouseEvent) => void
+    onMouseDown: (e: React.MouseEvent) => void
+    onMouseMove: (e: React.MouseEvent) => void
+    onMouseUp: () => void
+    onMouseLeave: () => void
+  }
+  reset: () => void
+  zoomTo: (scale: number, x?: number, y?: number) => void
+  toggleZoom: () => void
+}
+
+const INITIAL_STATE: ZoomState = { scale: 1, x: 0, y: 0 }
+const ZOOM_THRESHOLD = 1.05
+
+/**
+ * Unified zoom hook for both desktop (click/drag) and mobile (pinch/tap)
+ */
+export function useZoom(options: UseZoomOptions = {}): UseZoomReturn {
+  const { minScale = 1, maxScale = 3, desktopScale = 2, onZoomChange } = options
+
+  const [state, setState] = useState<ZoomState>(INITIAL_STATE)
+  const [isDragging, setIsDragging] = useState(false)
+
+  const touchRef = useRef<{
+    // Touch tracking
+    initialDistance: number
+    initialScale: number
+    initialX: number
+    initialY: number
+    centerX: number
+    centerY: number
+    isPinching: boolean
+    lastTap: number
+    // Container dimensions
+    containerWidth: number
+    containerHeight: number
+    // Mouse drag tracking
+    dragStartX: number
+    dragStartY: number
+  }>({
+    initialDistance: 0,
+    initialScale: 1,
+    initialX: 0,
+    initialY: 0,
+    centerX: 0,
+    centerY: 0,
+    isPinching: false,
+    lastTap: 0,
+    containerWidth: 0,
+    containerHeight: 0,
+    dragStartX: 0,
+    dragStartY: 0,
+  })
+
+  const isZoomed = state.scale > ZOOM_THRESHOLD
+
+  // 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
+    return {
+      x: (containerWidth * (scale - 1)) / 2,
+      y: (containerHeight * (scale - 1)) / 2,
+    }
+  }, [])
+
+  // Clamp pan position within bounds
+  const clampPan = useCallback((x: number, y: number, scale: number) => {
+    const maxPan = getMaxPan(scale)
+    return {
+      x: Math.max(-maxPan.x, Math.min(maxPan.x, x)),
+      y: Math.max(-maxPan.y, Math.min(maxPan.y, y)),
+    }
+  }, [getMaxPan])
+
+  // ========== TOUCH HANDLERS (MOBILE) ==========
+
+  const handleTouchStart = useCallback((e: React.TouchEvent) => {
+    const touches = e.touches
+    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) {
+        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: desktopScale, 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, desktopScale, 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
+      newScale = Math.max(minScale, Math.min(maxScale, newScale))
+
+      const center = getCenter(touches)
+      const dx = center.x - touchRef.current.centerX
+      const dy = center.y - touchRef.current.centerY
+
+      const { x: clampedX, y: clampedY } = clampPan(
+        touchRef.current.initialX + dx,
+        touchRef.current.initialY + dy,
+        newScale
+      )
+
+      setState({ scale: newScale, x: clampedX, y: clampedY })
+
+      if (newScale > ZOOM_THRESHOLD !== isZoomed) {
+        onZoomChange?.(newScale > ZOOM_THRESHOLD)
+      }
+    }
+
+    // Pan when zoomed (single finger)
+    if (touches.length === 1 && isZoomed && !touchRef.current.isPinching) {
+      e.preventDefault()
+
+      const newX = touches[0].clientX - touchRef.current.initialX
+      const newY = touches[0].clientY - touchRef.current.initialY
+      const { x: clampedX, y: clampedY } = clampPan(newX, newY, state.scale)
+
+      setState((prev) => ({ ...prev, x: clampedX, y: clampedY }))
+    }
+  }, [isZoomed, state.scale, minScale, maxScale, getDistance, getCenter, clampPan, 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])
+
+  // ========== MOUSE HANDLERS (DESKTOP) ==========
+
+  const handleClick = useCallback((e: React.MouseEvent) => {
+    // Skip if we were dragging
+    if (isDragging) return
+
+    const rect = e.currentTarget.getBoundingClientRect()
+    touchRef.current.containerWidth = rect.width
+    touchRef.current.containerHeight = rect.height
+
+    if (isZoomed) {
+      setState(INITIAL_STATE)
+      onZoomChange?.(false)
+    } else {
+      // Zoom to click position
+      const x = ((e.clientX - rect.left) / rect.width - 0.5) * -100
+      const y = ((e.clientY - rect.top) / rect.height - 0.5) * -100
+      setState({ scale: desktopScale, x, y })
+      onZoomChange?.(true)
+    }
+  }, [isZoomed, isDragging, desktopScale, onZoomChange])
+
+  const handleMouseDown = useCallback((e: React.MouseEvent) => {
+    if (!isZoomed) return
+    e.preventDefault()
+    setIsDragging(true)
+    touchRef.current.dragStartX = e.clientX - state.x
+    touchRef.current.dragStartY = e.clientY - state.y
+
+    const rect = e.currentTarget.getBoundingClientRect()
+    touchRef.current.containerWidth = rect.width
+    touchRef.current.containerHeight = rect.height
+  }, [isZoomed, state.x, state.y])
+
+  const handleMouseMove = useCallback((e: React.MouseEvent) => {
+    if (!isDragging) return
+
+    const newX = e.clientX - touchRef.current.dragStartX
+    const newY = e.clientY - touchRef.current.dragStartY
+    const { x: clampedX, y: clampedY } = clampPan(newX, newY, state.scale)
+
+    setState((prev) => ({ ...prev, x: clampedX, y: clampedY }))
+  }, [isDragging, state.scale, clampPan])
+
+  const handleMouseUp = useCallback(() => {
+    // Small delay to prevent click from triggering after drag
+    setTimeout(() => setIsDragging(false), 10)
+  }, [])
+
+  // ========== COMMON ACTIONS ==========
+
+  const reset = useCallback(() => {
+    setState(INITIAL_STATE)
+    setIsDragging(false)
+    onZoomChange?.(false)
+  }, [onZoomChange])
+
+  const zoomTo = useCallback((scale: number, x = 0, y = 0) => {
+    const clampedScale = Math.max(minScale, Math.min(maxScale, scale))
+    const { x: clampedX, y: clampedY } = clampPan(x, y, clampedScale)
+    setState({ scale: clampedScale, x: clampedX, y: clampedY })
+    onZoomChange?.(clampedScale > ZOOM_THRESHOLD)
+  }, [minScale, maxScale, clampPan, onZoomChange])
+
+  const toggleZoom = useCallback(() => {
+    if (isZoomed) {
+      setState(INITIAL_STATE)
+      onZoomChange?.(false)
+    } else {
+      setState({ scale: desktopScale, x: 0, y: 0 })
+      onZoomChange?.(true)
+    }
+  }, [isZoomed, desktopScale, onZoomChange])
+
+  return {
+    state,
+    isZoomed,
+    isDragging,
+    handlers: {
+      onTouchStart: handleTouchStart,
+      onTouchMove: handleTouchMove,
+      onTouchEnd: handleTouchEnd,
+      onClick: handleClick,
+      onMouseDown: handleMouseDown,
+      onMouseMove: handleMouseMove,
+      onMouseUp: handleMouseUp,
+      onMouseLeave: handleMouseUp,
+    },
+    reset,
+    zoomTo,
+    toggleZoom,
+  }
+}

package/src/tools/Gallery/index.ts

@@ -0,0 +1,66 @@
+// Components
+export {
+  Gallery,
+  GalleryCompact,
+  GalleryGrid,
+  GalleryImage,
+  GalleryVideo,
+  GalleryMedia,
+  GalleryThumbnails,
+  GalleryThumbnailsVirtual,
+  GalleryLightbox,
+} from './components'
+export type { GalleryCompactProps, GalleryGridProps, GalleryGridLayout } from './components'
+
+// Hooks
+export {
+  useGallery,
+  useSwipe,
+  usePreloadImages,
+  preloadImage,
+  preloadImages,
+  usePinchZoom,
+  useVirtualList,
+  useImageDimensions,
+  clearDimensionsCache,
+  getCachedDimensions,
+} from './hooks'
+export type {
+  UseGalleryOptions,
+  UseSwipeOptions,
+  PinchZoomState,
+  UsePinchZoomOptions,
+  UsePinchZoomReturn,
+  VirtualListOptions,
+  VirtualListReturn,
+  VirtualItem,
+  ImageWithDimensions,
+  UseImageDimensionsResult,
+  UseImageDimensionsOptions,
+} from './hooks'
+
+// Utils
+export {
+  getOrientation,
+  getAspectRatio,
+  analyzeImage,
+  analyzeImages,
+} from './utils'
+export type {
+  ImageOrientation,
+  AnalyzedImage,
+} from './utils'
+
+// Types
+export type {
+  GalleryMediaType,
+  GalleryPreviewMode,
+  GalleryMediaItem,
+  GalleryState,
+  GalleryActions,
+  GalleryContextValue,
+  GalleryProps,
+  GalleryImageProps,
+  GalleryThumbnailsProps,
+  GalleryLightboxProps,
+} from './types'

package/src/tools/Gallery/types.ts

@@ -0,0 +1,183 @@
+import type { ReactNode } from 'react'
+
+/**
+ * Media type for gallery items
+ */
+export type GalleryMediaType = 'image' | 'video'
+
+/**
+ * Single item in the gallery (image or video)
+ */
+export interface GalleryMediaItem {
+  /** Unique identifier */
+  id: string
+  /** Full-size image/poster URL */
+  src: string
+  /** Thumbnail URL (optional, falls back to src) */
+  thumbnail?: string
+  /** Alt text for accessibility */
+  alt?: string
+  /** Image width (optional, for aspect ratio) */
+  width?: number
+  /** Image height (optional, for aspect ratio) */
+  height?: number
+  /** Media type (default: 'image') */
+  type?: GalleryMediaType
+  /** Video URL (required if type is 'video') */
+  videoSrc?: string
+  /** Video MIME type */
+  videoType?: string
+}
+
+/**
+ * Gallery state
+ */
+export interface GalleryState {
+  /** Currently selected image index */
+  currentIndex: number
+  /** Whether lightbox is open */
+  isLightboxOpen: boolean
+  /** Whether image is zoomed in lightbox */
+  isZoomed: boolean
+  /** Whether current image is loading */
+  isLoading: boolean
+}
+
+/**
+ * Gallery actions
+ */
+export interface GalleryActions {
+  /** Go to specific image by index */
+  goTo: (index: number) => void
+  /** Go to next image */
+  next: () => void
+  /** Go to previous image */
+  prev: () => void
+  /** Open lightbox at specific index */
+  openLightbox: (index?: number) => void
+  /** Close lightbox */
+  closeLightbox: () => void
+  /** Toggle zoom in lightbox */
+  toggleZoom: () => void
+  /** Set loading state */
+  setLoading: (loading: boolean) => void
+}
+
+/**
+ * Gallery context value
+ */
+export interface GalleryContextValue extends GalleryState, GalleryActions {
+  /** All images in gallery */
+  images: GalleryMediaItem[]
+  /** Current image */
+  currentImage: GalleryMediaItem | null
+  /** Total number of images */
+  total: number
+  /** Whether there are multiple images */
+  hasMultiple: boolean
+}
+
+/**
+ * Preview mode for gallery
+ */
+export type GalleryPreviewMode = 'carousel' | 'grid'
+
+/**
+ * Props for Gallery component
+ */
+export interface GalleryProps {
+  /** Array of images to display */
+  images: GalleryMediaItem[]
+  /** Initial image index */
+  initialIndex?: number
+  /** Preview mode: carousel (default) or grid */
+  previewMode?: GalleryPreviewMode
+  /** Number of images to show in grid preview (default: 5) */
+  previewCount?: number
+  /** Show thumbnail strip (carousel mode only) */
+  showThumbnails?: boolean
+  /** Show navigation controls (carousel mode only) */
+  showControls?: boolean
+  /** Show image counter */
+  showCounter?: boolean
+  /** Aspect ratio for main image (e.g., 16/9, 4/3) */
+  aspectRatio?: number
+  /** Enable lightbox on click */
+  enableLightbox?: boolean
+  /** Enable keyboard navigation */
+  enableKeyboard?: boolean
+  /** Callback when image changes */
+  onImageChange?: (index: number, image: GalleryMediaItem) => void
+  /** Callback when lightbox opens */
+  onLightboxOpen?: () => void
+  /** Callback when lightbox closes */
+  onLightboxClose?: () => void
+  /** Custom empty state */
+  emptyState?: ReactNode
+  /** Custom loading placeholder */
+  loadingPlaceholder?: ReactNode
+  /** Additional CSS class */
+  className?: string
+}
+
+/**
+ * Props for GalleryImage component
+ */
+export interface GalleryImageProps {
+  /** Image data */
+  image: GalleryMediaItem
+  /** Whether to show loading skeleton */
+  showLoading?: boolean
+  /** On image load callback */
+  onLoad?: () => void
+  /** On image error callback */
+  onError?: () => void
+  /** On click callback */
+  onClick?: () => void
+  /** Priority loading */
+  priority?: boolean
+  /** Additional CSS class */
+  className?: string
+}
+
+/**
+ * Props for GalleryThumbnails component
+ */
+export interface GalleryThumbnailsProps {
+  /** All images */
+  images: GalleryMediaItem[]
+  /** Currently selected index */
+  currentIndex: number
+  /** On thumbnail click */
+  onSelect: (index: number) => void
+  /** Thumbnail size */
+  size?: 'sm' | 'md' | 'lg'
+  /** Additional CSS class */
+  className?: string
+}
+
+/**
+ * Props for GalleryLightbox component
+ */
+export interface GalleryLightboxProps {
+  /** Whether lightbox is open */
+  open: boolean
+  /** On close callback */
+  onClose: () => void
+  /** All images */
+  images: GalleryMediaItem[]
+  /** Current image index */
+  currentIndex: number
+  /** On index change */
+  onIndexChange: (index: number) => void
+  /** Show thumbnails in lightbox */
+  showThumbnails?: boolean
+  /** Enable zoom */
+  enableZoom?: boolean
+  /** Enable download button */
+  enableDownload?: boolean
+  /** Enable share button */
+  enableShare?: boolean
+  /** Title to display */
+  title?: string
+}

package/src/tools/Gallery/utils/imageAnalysis.ts

@@ -0,0 +1,52 @@
+import type { GalleryMediaItem } from '../types'
+
+/**
+ * Image orientation types
+ */
+export type ImageOrientation = 'landscape' | 'portrait' | 'square'
+
+/**
+ * Analyzed image with orientation info
+ */
+export interface AnalyzedImage extends GalleryMediaItem {
+  orientation: ImageOrientation
+  aspectRatio: number
+}
+
+/**
+ * Get orientation from width/height
+ */
+export function getOrientation(width?: number, height?: number): ImageOrientation {
+  if (!width || !height) return 'landscape' // default assumption
+
+  const ratio = width / height
+  if (ratio > 1.2) return 'landscape'
+  if (ratio < 0.8) return 'portrait'
+  return 'square'
+}
+
+/**
+ * Calculate aspect ratio from width/height
+ */
+export function getAspectRatio(width?: number, height?: number): number {
+  if (!width || !height) return 16 / 9 // default
+  return width / height
+}
+
+/**
+ * Analyze single image
+ */
+export function analyzeImage(image: GalleryMediaItem): AnalyzedImage {
+  return {
+    ...image,
+    orientation: getOrientation(image.width, image.height),
+    aspectRatio: getAspectRatio(image.width, image.height),
+  }
+}
+
+/**
+ * Analyze array of images
+ */
+export function analyzeImages(images: GalleryMediaItem[]): AnalyzedImage[] {
+  return images.map(analyzeImage)
+}

package/src/tools/Gallery/utils/index.ts

@@ -0,0 +1,11 @@
+export {
+  getOrientation,
+  getAspectRatio,
+  analyzeImage,
+  analyzeImages,
+} from './imageAnalysis'
+
+export type {
+  ImageOrientation,
+  AnalyzedImage,
+} from './imageAnalysis'