@djangocfg/ui-tools 2.1.118 → 2.1.120

package/src/tools/Gallery/Gallery.story.tsx

@@ -0,0 +1,231 @@
+import { defineStory, useBoolean, useSelect, useNumber } from '@djangocfg/playground';
+import { Gallery, GalleryCompact, type GalleryMediaItem } from './index';
+
+// Sample images for testing
+const SAMPLE_IMAGES: GalleryMediaItem[] = [
+  {
+    id: '1',
+    src: 'https://images.unsplash.com/photo-1494976388531-d1058494cdd8?w=800',
+    thumbnail: 'https://images.unsplash.com/photo-1494976388531-d1058494cdd8?w=200',
+    alt: 'Classic car',
+  },
+  {
+    id: '2',
+    src: 'https://images.unsplash.com/photo-1503376780353-7e6692767b70?w=800',
+    thumbnail: 'https://images.unsplash.com/photo-1503376780353-7e6692767b70?w=200',
+    alt: 'Porsche',
+  },
+  {
+    id: '3',
+    src: 'https://images.unsplash.com/photo-1542362567-b07e54358753?w=800',
+    thumbnail: 'https://images.unsplash.com/photo-1542362567-b07e54358753?w=200',
+    alt: 'BMW',
+  },
+  {
+    id: '4',
+    src: 'https://images.unsplash.com/photo-1555215695-3004980ad54e?w=800',
+    thumbnail: 'https://images.unsplash.com/photo-1555215695-3004980ad54e?w=200',
+    alt: 'Mercedes',
+  },
+  {
+    id: '5',
+    src: 'https://images.unsplash.com/photo-1617531653332-bd46c24f2068?w=800',
+    thumbnail: 'https://images.unsplash.com/photo-1617531653332-bd46c24f2068?w=200',
+    alt: 'Tesla',
+  },
+];
+
+export default defineStory({
+  title: 'Tools/Gallery',
+  component: Gallery,
+  description: 'Full-featured gallery with lightbox, thumbnails, and keyboard navigation.',
+});
+
+export const CarouselMode = () => (
+  <div className="max-w-4xl">
+    <Gallery
+      images={SAMPLE_IMAGES}
+      previewMode="carousel"
+      showThumbnails
+      showControls
+      showCounter
+      enableLightbox
+      enableKeyboard
+      aspectRatio={16 / 9}
+    />
+  </div>
+);
+
+export const GridMode = () => (
+  <div className="max-w-4xl">
+    <Gallery
+      images={SAMPLE_IMAGES}
+      previewMode="grid"
+      previewCount={5}
+      enableLightbox
+      aspectRatio={16 / 9}
+    />
+  </div>
+);
+
+export const WithoutThumbnails = () => (
+  <div className="max-w-4xl">
+    <Gallery
+      images={SAMPLE_IMAGES}
+      previewMode="carousel"
+      showThumbnails={false}
+      showControls
+      enableLightbox
+      aspectRatio={16 / 9}
+    />
+  </div>
+);
+
+export const Compact = {
+  render: (args: {
+    showDots: boolean;
+    showArrows: boolean;
+    enableZoom: boolean;
+    showCounter: boolean;
+  }) => (
+    <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
+      <div className="rounded-xl border border-border overflow-hidden">
+        <div className="aspect-[4/3]">
+          <GalleryCompact
+            images={SAMPLE_IMAGES}
+            showDots={args.showDots}
+            showArrows={args.showArrows}
+            enableZoom={args.enableZoom}
+            showCounter={args.showCounter}
+          />
+        </div>
+        <div className="p-4">
+          <h3 className="font-medium">Vehicle Title</h3>
+          <p className="text-sm text-muted-foreground">$25,000</p>
+        </div>
+      </div>
+    </div>
+  ),
+  args: {
+    showDots: true,
+    showArrows: true,
+    enableZoom: true,
+    showCounter: false,
+  },
+  argTypes: {
+    showDots: { control: 'boolean', description: 'Show navigation dots' },
+    showArrows: { control: 'boolean', description: 'Show arrow buttons' },
+    enableZoom: { control: 'boolean', description: 'Enable zoom on hover' },
+    showCounter: { control: 'boolean', description: 'Show image counter' },
+  },
+};
+
+export const SingleImage = () => (
+  <div className="w-64">
+    <div className="rounded-xl border border-border overflow-hidden">
+      <div className="aspect-[4/3]">
+        <GalleryCompact images={SAMPLE_IMAGES.slice(0, 1)} enableZoom />
+      </div>
+    </div>
+  </div>
+);
+
+export const EmptyState = () => (
+  <div className="w-64">
+    <div className="rounded-xl border border-border overflow-hidden">
+      <div className="aspect-[4/3]">
+        <GalleryCompact images={[]} />
+      </div>
+    </div>
+  </div>
+);
+
+/**
+ * Interactive story using fixture hooks
+ * Controls appear automatically in the right sidebar
+ */
+export const Interactive = () => {
+  // These hooks auto-register controls in the Properties panel
+  const [showDots] = useBoolean('showDots', {
+    defaultValue: true,
+    label: 'Show Dots',
+    description: 'Display navigation dots at the bottom',
+  });
+
+  const [showArrows] = useBoolean('showArrows', {
+    defaultValue: true,
+    label: 'Show Arrows',
+    description: 'Display navigation arrows on hover',
+  });
+
+  const [enableZoom] = useBoolean('enableZoom', {
+    defaultValue: true,
+    label: 'Enable Zoom',
+    description: 'Zoom effect on image hover',
+  });
+
+  const [showCounter] = useBoolean('showCounter', {
+    defaultValue: false,
+    label: 'Show Counter',
+    description: 'Display image counter badge',
+  });
+
+  const [maxDots] = useNumber('maxDots', {
+    defaultValue: 5,
+    min: 1,
+    max: 10,
+    label: 'Max Dots',
+    description: 'Maximum number of dots to display',
+  });
+
+  const [previewMode] = useSelect('previewMode', {
+    options: ['carousel', 'grid'] as const,
+    defaultValue: 'carousel',
+    label: 'Preview Mode',
+    description: 'Gallery preview display mode',
+  });
+
+  return (
+    <div className="space-y-8">
+      {/* GalleryCompact */}
+      <div>
+        <h3 className="text-lg font-semibold mb-4">GalleryCompact</h3>
+        <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
+          <div className="rounded-xl border border-border overflow-hidden">
+            <div className="aspect-[4/3]">
+              <GalleryCompact
+                images={SAMPLE_IMAGES}
+                showDots={showDots}
+                showArrows={showArrows}
+                enableZoom={enableZoom}
+                showCounter={showCounter}
+                maxDots={maxDots}
+              />
+            </div>
+            <div className="p-4">
+              <h3 className="font-medium">Interactive Card</h3>
+              <p className="text-sm text-muted-foreground">Use controls on the right →</p>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      {/* Full Gallery */}
+      <div>
+        <h3 className="text-lg font-semibold mb-4">Full Gallery ({previewMode})</h3>
+        <div className="max-w-4xl">
+          <Gallery
+            images={SAMPLE_IMAGES}
+            previewMode={previewMode}
+            showThumbnails
+            showControls
+            showCounter={showCounter}
+            enableLightbox
+            enableKeyboard
+            aspectRatio={16 / 9}
+          />
+        </div>
+      </div>
+    </div>
+  );
+};

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

@@ -5,13 +5,13 @@ 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 { GalleryGrid } from './preview'
+import { GalleryCarousel } from './preview'
 import type { GalleryProps } from '../types'
 
 // Lazy load lightbox - only loaded when user opens it
 const GalleryLightbox = lazy(() =>
-  import('./GalleryLightbox').then((mod) => ({ default: mod.GalleryLightbox }))
+  import('./lightbox').then((mod) => ({ default: mod.GalleryLightbox }))
 )
 
 /**

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

@@ -0,0 +1,363 @@
+'use client'
+
+import { memo, useCallback, useEffect, useState, useMemo } from 'react'
+import { cn } from '@djangocfg/ui-core/lib'
+import {
+  Carousel,
+  CarouselContent,
+  CarouselItem,
+  type CarouselApi,
+} from '@djangocfg/ui-core/components'
+import { ChevronLeft, ChevronRight, ImageOff } from 'lucide-react'
+import { GalleryMedia } from '../media'
+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
+  /** Show navigation arrows on hover (default: true) */
+  showArrows?: boolean
+  /** Enable zoom effect on hover (default: true) */
+  enableZoom?: boolean
+  /** On image click callback */
+  onClick?: () => void
+  /** Additional CSS class */
+  className?: string
+}
+
+/**
+ * GalleryCompact - Minimal carousel for property/vehicle cards
+ *
+ * Features:
+ * - Simple swipe carousel
+ * - Dots indicator (mobile-style)
+ * - Navigation arrows on hover (desktop)
+ * - Hover zoom effect on images
+ * - Lazy loading - only loads active image + neighbors
+ * - Fills parent container
+ * - Stops event propagation on navigation
+ */
+export const GalleryCompact = memo(function GalleryCompact({
+  images,
+  showDots = true,
+  maxDots = 5,
+  showCounter = false,
+  showArrows = true,
+  enableZoom = true,
+  onClick,
+  className,
+}: GalleryCompactProps) {
+  const [api, setApi] = useState<CarouselApi>()
+  const [currentIndex, setCurrentIndex] = useState(0)
+  const [isHovered, setIsHovered] = useState(false)
+  // Track if component is mounted (client-side) to avoid hydration mismatches
+  const [isMounted, setIsMounted] = useState(false)
+
+  useEffect(() => {
+    setIsMounted(true)
+  }, [])
+
+  const total = images.length
+  const hasMultiple = total > 1
+
+  // Determine which images should be loaded (current + neighbors for smooth transition)
+  const loadedIndices = useMemo(() => {
+    if (total === 0) return new Set<number>()
+    const indices = new Set<number>()
+    // Always load first image
+    indices.add(0)
+    // Load current
+    indices.add(currentIndex)
+    // Load neighbors for smooth transitions
+    if (hasMultiple) {
+      indices.add((currentIndex - 1 + total) % total)
+      indices.add((currentIndex + 1) % total)
+    }
+    return indices
+  }, [currentIndex, total, hasMultiple])
+
+  // Listen to carousel changes
+  useEffect(() => {
+    if (!api) return
+
+    const onSelect = () => {
+      setCurrentIndex(api.selectedScrollSnap())
+    }
+
+    api.on('select', onSelect)
+    return () => {
+      api.off('select', onSelect)
+    }
+  }, [api])
+
+  // Navigation handlers - stop all propagation to parent Link
+  const stopEvent = useCallback((e: React.MouseEvent | React.PointerEvent) => {
+    e.preventDefault()
+    e.stopPropagation()
+    e.nativeEvent.stopImmediatePropagation()
+  }, [])
+
+  const handlePrev = useCallback(
+    (e: React.MouseEvent) => {
+      stopEvent(e)
+      api?.scrollPrev()
+    },
+    [api, stopEvent]
+  )
+
+  const handleNext = useCallback(
+    (e: React.MouseEvent) => {
+      stopEvent(e)
+      api?.scrollNext()
+    },
+    [api, stopEvent]
+  )
+
+  // Dot click handler
+  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 navigation elements
+      if ((e.target as HTMLElement).closest('[data-nav]')) {
+        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 overflow-hidden group', className)}
+        onClick={onClick}
+      >
+        <div className={cn(
+          'w-full h-full transition-transform duration-500 ease-out',
+          enableZoom && 'group-hover:scale-110'
+        )}>
+          <GalleryMedia
+            media={images[0]}
+            className="w-full h-full"
+            priority
+          />
+        </div>
+      </div>
+    )
+  }
+
+  // Calculate visible dots
+  const visibleDots = images.slice(0, maxDots).map((_, i) => i)
+  const remainingCount = total > maxDots ? total - maxDots : 0
+
+  // SSR fallback - render first image only to avoid hydration mismatch
+  // The carousel requires DOM access and will cause issues during SSR
+  if (!isMounted) {
+    return (
+      <div
+        className={cn('relative w-full h-full overflow-hidden', className)}
+        onClick={onClick}
+      >
+        <GalleryMedia
+          media={images[0]}
+          className="w-full h-full"
+          priority
+        />
+        {/* Show dots indicator placeholder for consistent layout */}
+        {showDots && (
+          <div
+            className={cn(
+              'absolute bottom-3 left-1/2 -translate-x-1/2 z-10',
+              'flex items-center gap-1.5',
+              'px-2 py-1 rounded-full',
+              'bg-black/30 backdrop-blur-sm'
+            )}
+          >
+            {visibleDots.map((index) => (
+              <div
+                key={index}
+                className={cn(
+                  'rounded-full',
+                  index === 0
+                    ? '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'
+                )}
+              />
+            ))}
+            {remainingCount > 0 && (
+              <span className="text-white/80 text-[10px] font-medium ml-0.5">
+                +{remainingCount}
+              </span>
+            )}
+          </div>
+        )}
+        {/* Counter badge placeholder */}
+        {showCounter && (
+          <div className="absolute bottom-3 right-3 z-10 bg-black/50 backdrop-blur-sm text-white text-xs px-2 py-1 rounded-full font-medium">
+            1 / {total}
+          </div>
+        )}
+      </div>
+    )
+  }
+
+  return (
+    <div
+      className={cn('relative w-full h-full group/gallery', className)}
+      onClick={handleClick}
+      onMouseEnter={() => setIsHovered(true)}
+      onMouseLeave={() => setIsHovered(false)}
+    >
+      <Carousel
+        setApi={setApi}
+        opts={{
+          loop: true,
+        }}
+        className="w-full h-full"
+      >
+        <CarouselContent className="-ml-0 h-full">
+          {images.map((image, index) => {
+            const shouldLoad = loadedIndices.has(index)
+            const isActive = index === currentIndex
+
+            return (
+              <CarouselItem key={image.id} className="pl-0 h-full overflow-hidden">
+                <div className={cn(
+                  'w-full h-full transition-transform duration-500 ease-out',
+                  enableZoom && isActive && isHovered && 'scale-110'
+                )}>
+                  {shouldLoad ? (
+                    <GalleryMedia
+                      media={image}
+                      className="w-full h-full"
+                      priority={index === 0}
+                    />
+                  ) : (
+                    // Placeholder for unloaded images
+                    <div className="w-full h-full bg-muted animate-pulse" />
+                  )}
+                </div>
+              </CarouselItem>
+            )
+          })}
+        </CarouselContent>
+      </Carousel>
+
+      {/* Navigation arrows - always visible but subtle, more prominent on hover */}
+      {showArrows && (
+        <>
+          <button
+            data-nav
+            type="button"
+            className={cn(
+              'absolute left-2 top-1/2 -translate-y-1/2 z-10',
+              'w-7 h-7 rounded-full',
+              'bg-black/30 backdrop-blur-sm text-white/80',
+              'flex items-center justify-center',
+              'transition-all duration-200',
+              // Always visible but subtle, more prominent on hover
+              'opacity-60 group-hover/gallery:opacity-100',
+              'hover:bg-black/60 hover:text-white hover:scale-110',
+              'active:scale-95',
+              'focus:outline-none focus:ring-2 focus:ring-white/50'
+            )}
+            onClick={handlePrev}
+            onMouseDown={stopEvent}
+            onPointerDown={stopEvent}
+            aria-label="Previous image"
+          >
+            <ChevronLeft className="w-4 h-4" />
+          </button>
+          <button
+            data-nav
+            type="button"
+            className={cn(
+              'absolute right-2 top-1/2 -translate-y-1/2 z-10',
+              'w-7 h-7 rounded-full',
+              'bg-black/30 backdrop-blur-sm text-white/80',
+              'flex items-center justify-center',
+              'transition-all duration-200',
+              // Always visible but subtle, more prominent on hover
+              'opacity-60 group-hover/gallery:opacity-100',
+              'hover:bg-black/60 hover:text-white hover:scale-110',
+              'active:scale-95',
+              'focus:outline-none focus:ring-2 focus:ring-white/50'
+            )}
+            onClick={handleNext}
+            onMouseDown={stopEvent}
+            onPointerDown={stopEvent}
+            aria-label="Next image"
+          >
+            <ChevronRight className="w-4 h-4" />
+          </button>
+        </>
+      )}
+
+      {/* Dots indicator */}
+      {showDots && (
+        <div
+          data-nav
+          className={cn(
+            'absolute bottom-3 left-1/2 -translate-x-1/2 z-10',
+            'flex items-center gap-1.5',
+            'px-2 py-1 rounded-full',
+            'bg-black/30 backdrop-blur-sm'
+          )}
+          onClick={(e) => e.stopPropagation()}
+        >
+          {visibleDots.map((index) => (
+            <button
+              key={index}
+              type="button"
+              className={cn(
+                'rounded-full transition-all duration-200',
+                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/80'
+              )}
+              onClick={(e) => handleDotClick(e, index)}
+              aria-label={`Go to image ${index + 1}`}
+            />
+          ))}
+          {remainingCount > 0 && (
+            <span className="text-white/80 text-[10px] font-medium ml-0.5">
+              +{remainingCount}
+            </span>
+          )}
+        </div>
+      )}
+
+      {/* Counter badge */}
+      {showCounter && (
+        <div className="absolute bottom-3 right-3 z-10 bg-black/50 backdrop-blur-sm text-white text-xs px-2 py-1 rounded-full font-medium">
+          {currentIndex + 1} / {total}
+        </div>
+      )}
+    </div>
+  )
+})

package/src/tools/Gallery/components/compact/index.ts

@@ -0,0 +1 @@
+export { GalleryCompact, type GalleryCompactProps } from './GalleryCompact'

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

@@ -1,13 +1,18 @@
+// Main Gallery component
 export { Gallery } from './Gallery'
-export { GalleryCarousel } from './GalleryCarousel'
-export type { GalleryCarouselProps } from './GalleryCarousel'
-export { GalleryCompact } from './GalleryCompact'
-export type { GalleryCompactProps } from './GalleryCompact'
-export { GalleryGrid } from './GalleryGrid'
-export type { GalleryGridProps, GalleryGridLayout } from './GalleryGrid'
-export { GalleryImage } from './GalleryImage'
-export { GalleryVideo } from './GalleryVideo'
-export { GalleryMedia } from './GalleryMedia'
-export { GalleryThumbnails } from './GalleryThumbnails'
-export { GalleryThumbnailsVirtual } from './GalleryThumbnailsVirtual'
-export { GalleryLightbox } from './GalleryLightbox'
+
+// Compact mode (for cards)
+export { GalleryCompact, type GalleryCompactProps } from './compact'
+
+// Preview modes
+export { GalleryCarousel } from './preview'
+export { GalleryGrid, type GalleryGridProps, type GalleryGridLayout } from './preview'
+
+// Lightbox
+export { GalleryLightbox } from './lightbox'
+
+// Media components
+export { GalleryImage, GalleryVideo, GalleryMedia, type GalleryMediaProps } from './media'
+
+// Thumbnails
+export { GalleryThumbnails, GalleryThumbnailsVirtual } from './thumbnails'

package/src/tools/Gallery/components/{GalleryLightbox.tsx → lightbox/GalleryLightbox.tsx}

@@ -5,12 +5,12 @@ import { createPortal } from 'react-dom'
 import { cn } from '@djangocfg/ui-core/lib'
 import { useTypedT, type I18nTranslations } from '@djangocfg/i18n'
 import { X, ChevronLeft, ChevronRight, Download, Share2, ZoomIn, ZoomOut } from 'lucide-react'
-import { useSwipe } from '../hooks/useSwipe'
-import { usePreloadImages } from '../hooks/usePreloadImages'
-import { useZoom } from '../hooks/useZoom'
-import { GalleryMedia } from './GalleryMedia'
-import { GalleryThumbnails } from './GalleryThumbnails'
-import type { GalleryLightboxProps } from '../types'
+import { useSwipe } from '../../hooks/useSwipe'
+import { usePreloadImages } from '../../hooks/usePreloadImages'
+import { useZoom } from '../../hooks/useZoom'
+import { GalleryMedia } from '../media'
+import { GalleryThumbnails } from '../thumbnails'
+import type { GalleryLightboxProps } from '../../types'
 
 /**
  * GalleryLightbox - Fullscreen image viewer with zoom and navigation

package/src/tools/Gallery/components/lightbox/index.ts

@@ -0,0 +1 @@
+export { GalleryLightbox } from './GalleryLightbox'

package/src/tools/Gallery/components/{GalleryImage.tsx → media/GalleryImage.tsx}

@@ -5,7 +5,7 @@ import { cn } from '@djangocfg/ui-core/lib'
 import { useTypedT, type I18nTranslations } from '@djangocfg/i18n'
 import { useImageLoader } from '@djangocfg/ui-core/hooks'
 import { ImageOff } from 'lucide-react'
-import type { GalleryImageProps } from '../types'
+import type { GalleryImageProps } from '../../types'
 
 /**
  * GalleryImage - Single image with loading state and error handling

package/src/tools/Gallery/components/{GalleryMedia.tsx → media/GalleryMedia.tsx}

@@ -3,7 +3,7 @@
 import { memo } from 'react'
 import { GalleryImage as GalleryImageComponent } from './GalleryImage'
 import { GalleryVideo } from './GalleryVideo'
-import type { GalleryMediaItem } from '../types'
+import type { GalleryMediaItem } from '../../types'
 
 export interface GalleryMediaProps {
   /** Media data */