@djangocfg/ui-tools 2.1.119 → 2.1.121

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

@@ -0,0 +1,237 @@
+import { defineStory, useBoolean, useSelect, useNumber } from '@djangocfg/playground';
+import { Gallery, GalleryCompact, type GalleryMediaItem, type GalleryAspectRatio } 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',
+  });
+
+  const [aspectRatio] = useSelect('aspectRatio', {
+    options: ['auto', '16/9', '4/3', '3/2', '1/1'] as const,
+    defaultValue: '4/3' as GalleryAspectRatio,
+    label: 'Aspect Ratio',
+    description: 'Image container aspect ratio',
+  });
+
+  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">
+            <GalleryCompact
+              images={SAMPLE_IMAGES}
+              aspectRatio={aspectRatio}
+              showDots={showDots}
+              showArrows={showArrows}
+              enableZoom={enableZoom}
+              showCounter={showCounter}
+              maxDots={maxDots}
+            />
+            <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/compact/GalleryCompact.tsx

@@ -12,9 +12,14 @@ import { ChevronLeft, ChevronRight, ImageOff } from 'lucide-react'
 import { GalleryMedia } from '../media'
 import type { GalleryMediaItem } from '../../types'
 
+/** Preset aspect ratios for common use cases */
+export type GalleryAspectRatio = '16/9' | '4/3' | '3/2' | '1/1' | 'auto'
+
 export interface GalleryCompactProps {
   /** Array of images to display */
   images: GalleryMediaItem[]
+  /** Aspect ratio preset or 'auto' to fill parent (default: 'auto') */
+  aspectRatio?: GalleryAspectRatio
   /** Show dots indicator (default: true) */
   showDots?: boolean
   /** Max dots to show (default: 5) */
@@ -43,8 +48,18 @@ export interface GalleryCompactProps {
  * - Fills parent container
  * - Stops event propagation on navigation
  */
+/** Map aspect ratio presets to CSS values */
+const aspectRatioMap: Record<GalleryAspectRatio, string | undefined> = {
+  '16/9': '16 / 9',
+  '4/3': '4 / 3',
+  '3/2': '3 / 2',
+  '1/1': '1 / 1',
+  'auto': undefined,
+}
+
 export const GalleryCompact = memo(function GalleryCompact({
   images,
+  aspectRatio = 'auto',
   showDots = true,
   maxDots = 5,
   showCounter = false,
@@ -56,9 +71,23 @@ export const GalleryCompact = memo(function GalleryCompact({
   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)
+
+  // Compute aspect ratio style - if set, we control height via aspect-ratio, otherwise fill parent
+  const aspectRatioStyle = aspectRatioMap[aspectRatio]
+  const containerStyle = aspectRatioStyle ? { aspectRatio: aspectRatioStyle } : undefined
+  const hasFixedAspect = aspectRatio !== 'auto'
+  const containerClass = hasFixedAspect ? 'relative w-full' : 'relative w-full h-full'
+
+  useEffect(() => {
+    setIsMounted(true)
+  }, [])
 
   const total = images.length
   const hasMultiple = total > 1
+  // Stable key for carousel reset on images change
+  const carouselKey = images[0]?.id ?? 'empty'
 
   // Determine which images should be loaded (current + neighbors for smooth transition)
   const loadedIndices = useMemo(() => {
@@ -90,23 +119,27 @@ export const GalleryCompact = memo(function GalleryCompact({
     }
   }, [api])
 
-  // Navigation handlers
+  // 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) => {
-      e.preventDefault()
-      e.stopPropagation()
+      stopEvent(e)
       api?.scrollPrev()
     },
-    [api]
+    [api, stopEvent]
   )
 
   const handleNext = useCallback(
     (e: React.MouseEvent) => {
-      e.preventDefault()
-      e.stopPropagation()
+      stopEvent(e)
       api?.scrollNext()
     },
-    [api]
+    [api, stopEvent]
   )
 
   // Dot click handler
@@ -134,7 +167,10 @@ export const GalleryCompact = memo(function GalleryCompact({
   // Empty state
   if (total === 0) {
     return (
-      <div className={cn('relative w-full h-full bg-muted flex items-center justify-center', className)}>
+      <div
+        className={cn(containerClass, 'bg-muted flex items-center justify-center', className)}
+        style={containerStyle}
+      >
         <ImageOff className="w-8 h-8 text-muted-foreground/50" />
       </div>
     )
@@ -144,7 +180,8 @@ export const GalleryCompact = memo(function GalleryCompact({
   if (!hasMultiple) {
     return (
       <div
-        className={cn('relative w-full h-full overflow-hidden group', className)}
+        className={cn(containerClass, 'overflow-hidden group', className)}
+        style={containerStyle}
         onClick={onClick}
       >
         <div className={cn(
@@ -165,14 +202,68 @@ export const GalleryCompact = memo(function GalleryCompact({
   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(containerClass, 'overflow-hidden', className)}
+        style={containerStyle}
+        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)}
+      className={cn(containerClass, 'group/gallery', className)}
+      style={containerStyle}
       onClick={handleClick}
       onMouseEnter={() => setIsHovered(true)}
       onMouseLeave={() => setIsHovered(false)}
     >
       <Carousel
+        key={carouselKey}
         setApi={setApi}
         opts={{
           loop: true,
@@ -226,6 +317,8 @@ export const GalleryCompact = memo(function GalleryCompact({
               '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" />
@@ -246,6 +339,8 @@ export const GalleryCompact = memo(function GalleryCompact({
               '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" />

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

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

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

@@ -2,7 +2,7 @@
 export { Gallery } from './Gallery'
 
 // Compact mode (for cards)
-export { GalleryCompact, type GalleryCompactProps } from './compact'
+export { GalleryCompact, type GalleryCompactProps, type GalleryAspectRatio } from './compact'
 
 // Preview modes
 export { GalleryCarousel } from './preview'

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

@@ -43,7 +43,7 @@ export const GalleryImage = memo(function GalleryImage({
 
   return (
     <div
-      className={cn('relative overflow-hidden', className)}
+      className={cn('relative w-full h-full overflow-hidden', className)}
       onClick={onClick}
     >
       {/* Loading skeleton */}
@@ -56,7 +56,7 @@ export const GalleryImage = memo(function GalleryImage({
         <img
           src={image.src}
           alt={image.alt || 'Gallery image'}
-          className="w-full h-full object-cover animate-in fade-in-0 duration-300"
+          className="absolute inset-0 w-full h-full object-cover animate-in fade-in-0 duration-300"
           loading={priority ? 'eager' : 'lazy'}
           decoding="async"
         />

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

@@ -1,7 +1,7 @@
 'use client'
 
 import * as React from 'react'
-import { memo, useCallback, useEffect, useMemo, useRef } from 'react'
+import { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import { cn } from '@djangocfg/ui-core/lib'
 import {
   Carousel,
@@ -65,6 +65,14 @@ export const GalleryCarousel = memo(function GalleryCarousel({
   className,
 }: GalleryCarouselProps) {
   const [api, setApi] = React.useState<CarouselApi>()
+  // Track if component is mounted (client-side) to avoid hydration mismatches
+  const [isMounted, setIsMounted] = useState(false)
+  // Stable key for carousel reset on images change
+  const carouselKey = images[0]?.id ?? 'empty'
+
+  useEffect(() => {
+    setIsMounted(true)
+  }, [])
 
   // Notify parent when API is ready
   useEffect(() => {
@@ -161,9 +169,86 @@ export const GalleryCarousel = memo(function GalleryCarousel({
     pointerStartRef.current = null
   }, [enableLightbox, onLightboxOpen])
 
+  // 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('space-y-3', className)}>
+        <div className="relative rounded-xl overflow-hidden">
+          <div
+            className="relative bg-muted"
+            style={{ aspectRatio }}
+          >
+            <GalleryMedia
+              media={images[0]}
+              className="w-full h-full"
+              priority
+            />
+            {/* Dark overlay */}
+            <div className="absolute inset-0 bg-gradient-to-t from-black/40 via-transparent to-black/20 pointer-events-none" />
+          </div>
+
+          {/* 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'
+              )}
+            >
+              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) => (
+                <div
+                  key={index}
+                  className={cn(
+                    'rounded-full',
+                    index === 0
+                      ? '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'
+                  )}
+                />
+              ))}
+              {remainingCount > 0 && (
+                <span className="text-white/70 text-xs ml-1">+{remainingCount}</span>
+              )}
+            </div>
+          )}
+        </div>
+
+        {/* Thumbnails placeholder */}
+        {showThumbnails && hasMultiple && (
+          <div className="hidden md:flex gap-2">
+            {images.slice(0, 8).map((image, index) => (
+              <div
+                key={image.id}
+                className={cn(
+                  'w-16 h-16 rounded-lg overflow-hidden bg-muted flex-shrink-0',
+                  index === 0 && 'ring-2 ring-primary'
+                )}
+              >
+                <GalleryMedia
+                  media={image}
+                  className="w-full h-full"
+                />
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+    )
+  }
+
   return (
     <div className={cn('space-y-3', className)}>
       <Carousel
+        key={carouselKey}
         setApi={setApi}
         opts={{
           loop: true,

package/src/tools/Gallery/index.ts

@@ -10,7 +10,7 @@ export {
   GalleryThumbnailsVirtual,
   GalleryLightbox,
 } from './components'
-export type { GalleryCompactProps, GalleryGridProps, GalleryGridLayout } from './components'
+export type { GalleryCompactProps, GalleryAspectRatio, GalleryGridProps, GalleryGridLayout } from './components'
 
 // Hooks
 export {