@djangocfg/ui-tools 2.1.110 → 2.1.112

package/src/tools/Gallery/components/Gallery.tsx

@@ -0,0 +1,182 @@
+'use client'
+
+import { memo, useCallback, useMemo, Suspense, lazy } from 'react'
+import { cn } from '@djangocfg/ui-core/lib'
+import { useTypedT, type I18nTranslations } from '@djangocfg/i18n'
+import { ImageOff } from 'lucide-react'
+import { useGallery } from '../hooks/useGallery'
+import { GalleryGrid } from './GalleryGrid'
+import { GalleryCarousel } from './GalleryCarousel'
+import type { GalleryProps } from '../types'
+
+// Lazy load lightbox - only loaded when user opens it
+const GalleryLightbox = lazy(() =>
+  import('./GalleryLightbox').then((mod) => ({ default: mod.GalleryLightbox }))
+)
+
+/**
+ * Gallery - Complete image gallery with carousel/grid preview and lightbox
+ *
+ * Features:
+ * - Two preview modes: carousel (default) or grid
+ * - Smooth slide transitions (embla-carousel)
+ * - Touch/swipe support
+ * - Keyboard navigation
+ * - Fullscreen lightbox
+ * - Dark overlay for controls
+ */
+export const Gallery = memo(function Gallery({
+  images,
+  initialIndex = 0,
+  previewMode = 'carousel',
+  previewCount = 5,
+  showThumbnails = true,
+  showControls = true,
+  showCounter = true,
+  aspectRatio = 16 / 9,
+  enableLightbox = true,
+  enableKeyboard = true,
+  onImageChange,
+  onLightboxOpen,
+  onLightboxClose,
+  emptyState,
+  className,
+}: GalleryProps) {
+  const t = useTypedT<I18nTranslations>()
+  const noImagesText = useMemo(() => t('tools.gallery.noImages'), [t])
+
+  const gallery = useGallery({
+    images,
+    initialIndex,
+    loop: true,
+    onImageChange,
+  })
+
+  const {
+    currentIndex,
+    total,
+    hasMultiple,
+    isLightboxOpen,
+    goTo,
+    openLightbox,
+    closeLightbox,
+    setLoading,
+  } = gallery
+
+  // Lightbox callbacks
+  const handleLightboxOpen = useCallback(() => {
+    openLightbox()
+    onLightboxOpen?.()
+  }, [openLightbox, onLightboxOpen])
+
+  const handleLightboxClose = useCallback(() => {
+    closeLightbox()
+    onLightboxClose?.()
+  }, [closeLightbox, onLightboxClose])
+
+  // Open lightbox at specific index (for grid mode)
+  const handleGridImageClick = useCallback(
+    (index: number) => {
+      goTo(index)
+      openLightbox()
+      onLightboxOpen?.()
+    },
+    [goTo, openLightbox, onLightboxOpen]
+  )
+
+  // Current image load handler
+  const handleCurrentImageLoad = useCallback(() => {
+    setLoading(false)
+  }, [setLoading])
+
+  // Empty state
+  if (images.length === 0) {
+    if (emptyState) {
+      return <>{emptyState}</>
+    }
+
+    return (
+      <div
+        className={cn(
+          'bg-muted rounded-xl flex items-center justify-center',
+          className
+        )}
+        style={{ aspectRatio }}
+      >
+        <div className="text-center text-muted-foreground p-8">
+          <ImageOff className="w-12 h-12 mx-auto mb-3 opacity-50" />
+          <p>{noImagesText}</p>
+        </div>
+      </div>
+    )
+  }
+
+  // Grid mode
+  if (previewMode === 'grid') {
+    return (
+      <div className={className}>
+        <GalleryGrid
+          images={images}
+          maxVisible={previewCount}
+          aspectRatio={aspectRatio}
+          gap={2}
+          rounded="xl"
+          onImageClick={enableLightbox ? handleGridImageClick : undefined}
+          showMoreBadge
+        />
+
+        {/* Lightbox - lazy loaded */}
+        {enableLightbox && isLightboxOpen && (
+          <Suspense fallback={null}>
+            <GalleryLightbox
+              open={isLightboxOpen}
+              onClose={handleLightboxClose}
+              images={images}
+              currentIndex={currentIndex}
+              onIndexChange={goTo}
+              showThumbnails={showThumbnails}
+            />
+          </Suspense>
+        )}
+      </div>
+    )
+  }
+
+  // Carousel mode (default)
+  return (
+    <>
+      <GalleryCarousel
+        images={images}
+        currentIndex={currentIndex}
+        total={total}
+        hasMultiple={hasMultiple}
+        initialIndex={initialIndex}
+        aspectRatio={aspectRatio}
+        showControls={showControls}
+        showCounter={showCounter}
+        showThumbnails={showThumbnails}
+        enableLightbox={enableLightbox}
+        enableKeyboard={enableKeyboard}
+        isLightboxOpen={isLightboxOpen}
+        onIndexChange={goTo}
+        onLightboxOpen={handleLightboxOpen}
+        onImageLoad={handleCurrentImageLoad}
+        className={className}
+      />
+
+      {/* Lightbox - lazy loaded */}
+      {enableLightbox && isLightboxOpen && (
+        <Suspense fallback={null}>
+          <GalleryLightbox
+            open={isLightboxOpen}
+            onClose={handleLightboxClose}
+            images={images}
+            currentIndex={currentIndex}
+            onIndexChange={goTo}
+            showThumbnails={showThumbnails}
+          />
+        </Suspense>
+      )}
+    </>
+  )
+})

package/src/tools/Gallery/components/GalleryCarousel.tsx

@@ -0,0 +1,251 @@
+'use client'
+
+import * as React from 'react'
+import { memo, useCallback, useEffect, useMemo } from 'react'
+import { cn } from '@djangocfg/ui-core/lib'
+import {
+  Carousel,
+  CarouselContent,
+  CarouselItem,
+  CarouselPrevious,
+  CarouselNext,
+  type CarouselApi,
+} from '@djangocfg/ui-core/components'
+import { ZoomIn } from 'lucide-react'
+import { GalleryMedia } from './GalleryMedia'
+import { GalleryThumbnails } from './GalleryThumbnails'
+import type { GalleryMediaItem } from '../types'
+
+export interface GalleryCarouselProps {
+  images: GalleryMediaItem[]
+  currentIndex: number
+  total: number
+  hasMultiple: boolean
+  initialIndex?: number
+  aspectRatio?: number
+  showControls?: boolean
+  showCounter?: boolean
+  showThumbnails?: boolean
+  enableLightbox?: boolean
+  enableKeyboard?: boolean
+  isLightboxOpen?: boolean
+  onApiChange?: (api: CarouselApi | undefined) => void
+  onIndexChange: (index: number) => void
+  onLightboxOpen?: () => void
+  onImageLoad?: () => void
+  className?: string
+}
+
+/**
+ * GalleryCarousel - Embla-based carousel for gallery images
+ *
+ * Features:
+ * - Smooth slide transitions
+ * - Touch/swipe support
+ * - Keyboard navigation
+ * - Mobile dots + desktop thumbnails
+ */
+export const GalleryCarousel = memo(function GalleryCarousel({
+  images,
+  currentIndex,
+  total,
+  hasMultiple,
+  initialIndex = 0,
+  aspectRatio = 16 / 9,
+  showControls = true,
+  showCounter = true,
+  showThumbnails = true,
+  enableLightbox = true,
+  enableKeyboard = true,
+  isLightboxOpen = false,
+  onApiChange,
+  onIndexChange,
+  onLightboxOpen,
+  onImageLoad,
+  className,
+}: GalleryCarouselProps) {
+  const [api, setApi] = React.useState<CarouselApi>()
+
+  // Notify parent when API is ready
+  useEffect(() => {
+    onApiChange?.(api)
+  }, [api, onApiChange])
+
+  // Mobile dots (max 5)
+  const mobileDots = useMemo(() => {
+    return images.slice(0, 5).map((_, index) => index)
+  }, [images])
+
+  const remainingCount = useMemo(() => {
+    return images.length > 5 ? images.length - 5 : 0
+  }, [images.length])
+
+  // Sync carousel with external state
+  useEffect(() => {
+    if (!api) return
+    api.scrollTo(currentIndex)
+  }, [api, currentIndex])
+
+  // Listen to carousel changes
+  useEffect(() => {
+    if (!api) return
+
+    const onSelect = () => {
+      const index = api.selectedScrollSnap()
+      if (index !== currentIndex) {
+        onIndexChange(index)
+      }
+    }
+
+    api.on('select', onSelect)
+    return () => {
+      api.off('select', onSelect)
+    }
+  }, [api, currentIndex, onIndexChange])
+
+  // Keyboard navigation
+  useEffect(() => {
+    if (!enableKeyboard || isLightboxOpen || !api) return
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (e.key === 'ArrowLeft' && hasMultiple) {
+        api.scrollPrev()
+      } else if (e.key === 'ArrowRight' && hasMultiple) {
+        api.scrollNext()
+      }
+    }
+
+    window.addEventListener('keydown', handleKeyDown)
+    return () => window.removeEventListener('keydown', handleKeyDown)
+  }, [enableKeyboard, isLightboxOpen, hasMultiple, api])
+
+  // Dot click handler
+  const handleDotClick = useCallback(
+    (e: React.MouseEvent, index: number) => {
+      e.stopPropagation()
+      api?.scrollTo(index)
+    },
+    [api]
+  )
+
+  // Scroll to index
+  const handleScrollTo = useCallback(
+    (index: number) => {
+      api?.scrollTo(index)
+    },
+    [api]
+  )
+
+  return (
+    <div className={cn('space-y-3', className)}>
+      <Carousel
+        setApi={setApi}
+        opts={{
+          loop: true,
+          startIndex: initialIndex,
+        }}
+        className="relative rounded-xl overflow-hidden"
+      >
+        <CarouselContent className="-ml-0">
+          {images.map((image, index) => (
+            <CarouselItem key={image.id} className="pl-0">
+              <div
+                className="relative bg-muted cursor-pointer"
+                style={{ aspectRatio }}
+                onClick={enableLightbox ? onLightboxOpen : undefined}
+              >
+                <GalleryMedia
+                  media={image}
+                  className="w-full h-full"
+                  onLoad={index === currentIndex ? onImageLoad : undefined}
+                  priority={index === 0}
+                />
+
+                {/* Dark overlay */}
+                <div className="absolute inset-0 bg-gradient-to-t from-black/40 via-transparent to-black/20 pointer-events-none" />
+
+                {/* Lightbox indicator */}
+                {enableLightbox && (
+                  <div className="absolute inset-0 flex items-center justify-center opacity-0 hover:opacity-100 transition-opacity">
+                    <div className="bg-black/60 backdrop-blur-sm rounded-full p-3 shadow-lg border border-white/20">
+                      <ZoomIn className="w-6 h-6 text-white" />
+                    </div>
+                  </div>
+                )}
+              </div>
+            </CarouselItem>
+          ))}
+        </CarouselContent>
+
+        {/* Navigation Controls */}
+        {showControls && hasMultiple && (
+          <>
+            <CarouselPrevious
+              className={cn(
+                'absolute left-3 top-1/2 -translate-y-1/2',
+                'w-10 h-10 rounded-full',
+                'bg-black/50 hover:bg-black/70 text-white backdrop-blur-sm border-white/20',
+                'disabled:opacity-30'
+              )}
+            />
+            <CarouselNext
+              className={cn(
+                'absolute right-3 top-1/2 -translate-y-1/2',
+                'w-10 h-10 rounded-full',
+                'bg-black/50 hover:bg-black/70 text-white backdrop-blur-sm border-white/20',
+                'disabled:opacity-30'
+              )}
+            />
+          </>
+        )}
+
+        {/* Counter */}
+        {showCounter && hasMultiple && (
+          <div
+            className={cn(
+              'absolute bottom-3 right-3 z-10',
+              'bg-black/60 backdrop-blur-sm text-white px-3 py-1.5 rounded-full',
+              'text-sm font-medium'
+            )}
+          >
+            {currentIndex + 1} / {total}
+          </div>
+        )}
+
+        {/* Mobile dots */}
+        {hasMultiple && (
+          <div className="absolute bottom-3 left-1/2 -translate-x-1/2 flex gap-2 md:hidden z-10">
+            {mobileDots.map((index) => (
+              <button
+                key={index}
+                type="button"
+                className={cn(
+                  'rounded-full transition-all',
+                  index === currentIndex
+                    ? 'w-2.5 h-2.5 bg-white shadow-[0_0_4px_rgba(255,255,255,0.8)]'
+                    : 'w-2 h-2 bg-white/40'
+                )}
+                onClick={(e) => handleDotClick(e, index)}
+                aria-label={`Go to image ${index + 1}`}
+              />
+            ))}
+            {remainingCount > 0 && (
+              <span className="text-white/70 text-xs ml-1">+{remainingCount}</span>
+            )}
+          </div>
+        )}
+      </Carousel>
+
+      {/* Thumbnails */}
+      {showThumbnails && hasMultiple && (
+        <GalleryThumbnails
+          images={images}
+          currentIndex={currentIndex}
+          onSelect={handleScrollTo}
+          size="md"
+          className="hidden md:flex"
+        />
+      )}
+    </div>
+  )
+})

package/src/tools/Gallery/components/GalleryCompact.tsx

@@ -0,0 +1,173 @@
+'use client'
+
+import { memo, useCallback, useEffect, useState } from 'react'
+import { cn } from '@djangocfg/ui-core/lib'
+import {
+  Carousel,
+  CarouselContent,
+  CarouselItem,
+  type CarouselApi,
+} from '@djangocfg/ui-core/components'
+import { ImageOff } from 'lucide-react'
+import { GalleryMedia } from './GalleryMedia'
+import type { GalleryMediaItem } from '../types'
+
+export interface GalleryCompactProps {
+  /** Array of images to display */
+  images: GalleryMediaItem[]
+  /** Show dots indicator (default: true) */
+  showDots?: boolean
+  /** Max dots to show (default: 5) */
+  maxDots?: number
+  /** Show counter badge (default: false) */
+  showCounter?: boolean
+  /** On image click callback */
+  onClick?: () => void
+  /** Additional CSS class */
+  className?: string
+}
+
+/**
+ * GalleryCompact - Minimal carousel for property cards
+ *
+ * Features:
+ * - Simple swipe carousel
+ * - Dots indicator (mobile-style)
+ * - No arrows, thumbnails, or lightbox
+ * - Fills parent container
+ * - Stops event propagation on navigation
+ */
+export const GalleryCompact = memo(function GalleryCompact({
+  images,
+  showDots = true,
+  maxDots = 5,
+  showCounter = false,
+  onClick,
+  className,
+}: GalleryCompactProps) {
+  const [api, setApi] = useState<CarouselApi>()
+  const [currentIndex, setCurrentIndex] = useState(0)
+
+  const total = images.length
+  const hasMultiple = total > 1
+
+  // Listen to carousel changes
+  useEffect(() => {
+    if (!api) return
+
+    const onSelect = () => {
+      setCurrentIndex(api.selectedScrollSnap())
+    }
+
+    api.on('select', onSelect)
+    return () => {
+      api.off('select', onSelect)
+    }
+  }, [api])
+
+  // Dot click handler - stops propagation to prevent card click
+  const handleDotClick = useCallback(
+    (e: React.MouseEvent, index: number) => {
+      e.preventDefault()
+      e.stopPropagation()
+      api?.scrollTo(index)
+    },
+    [api]
+  )
+
+  // Handle container click
+  const handleClick = useCallback(
+    (e: React.MouseEvent) => {
+      // Don't trigger if clicking on dots
+      if ((e.target as HTMLElement).closest('[data-dots]')) {
+        return
+      }
+      onClick?.()
+    },
+    [onClick]
+  )
+
+  // Empty state
+  if (total === 0) {
+    return (
+      <div className={cn('relative w-full h-full bg-muted flex items-center justify-center', className)}>
+        <ImageOff className="w-8 h-8 text-muted-foreground/50" />
+      </div>
+    )
+  }
+
+  // Single image - no carousel needed
+  if (!hasMultiple) {
+    return (
+      <div className={cn('relative w-full h-full', className)} onClick={onClick}>
+        <GalleryMedia
+          media={images[0]}
+          className="w-full h-full"
+          priority
+        />
+      </div>
+    )
+  }
+
+  // Calculate visible dots
+  const visibleDots = images.slice(0, maxDots).map((_, i) => i)
+  const remainingCount = total > maxDots ? total - maxDots : 0
+
+  return (
+    <div className={cn('relative w-full h-full', className)} onClick={handleClick}>
+      <Carousel
+        setApi={setApi}
+        opts={{
+          loop: true,
+        }}
+        className="w-full h-full"
+      >
+        <CarouselContent className="-ml-0 h-full">
+          {images.map((image, index) => (
+            <CarouselItem key={image.id} className="pl-0 h-full">
+              <GalleryMedia
+                media={image}
+                className="w-full h-full"
+                priority={index === 0}
+              />
+            </CarouselItem>
+          ))}
+        </CarouselContent>
+      </Carousel>
+
+      {/* Dots indicator */}
+      {showDots && (
+        <div
+          data-dots
+          className="absolute bottom-3 left-1/2 -translate-x-1/2 flex items-center gap-1.5 z-10"
+          onClick={(e) => e.stopPropagation()}
+        >
+          {visibleDots.map((index) => (
+            <button
+              key={index}
+              type="button"
+              className={cn(
+                'rounded-full transition-all',
+                index === currentIndex
+                  ? 'w-2 h-2 bg-white shadow-[0_0_4px_rgba(255,255,255,0.8)]'
+                  : 'w-1.5 h-1.5 bg-white/50 hover:bg-white/70'
+              )}
+              onClick={(e) => handleDotClick(e, index)}
+              aria-label={`Go to image ${index + 1}`}
+            />
+          ))}
+          {remainingCount > 0 && (
+            <span className="text-white/70 text-[10px] ml-0.5">+{remainingCount}</span>
+          )}
+        </div>
+      )}
+
+      {/* Counter badge */}
+      {showCounter && (
+        <div className="absolute bottom-3 right-3 z-10 bg-black/60 backdrop-blur-sm text-white text-xs px-2 py-1 rounded-full">
+          {currentIndex + 1} / {total}
+        </div>
+      )}
+    </div>
+  )
+})