@etus/ui 0.1.0

package/src/components/data-display/ImageGallery/ImageGallery.tsx

@@ -0,0 +1,733 @@
+"use client"
+
+import type {
+  ImageGalleryGap,
+  ImageGalleryItemProps,
+  ImageGalleryLayout,
+  ImageGalleryProps,
+  ImageItem,
+  ResponsiveColumns,
+} from "./ImageGallery.types"
+
+import { cva } from "class-variance-authority"
+import useEmblaCarousel from "embla-carousel-react"
+import { Check } from "lucide-react"
+import * as React from "react"
+
+import { cn } from "../../../lib/utils"
+import { AspectRatio } from "../../primitives/AspectRatio"
+
+// Gap size mapping
+const gapClasses: Record<ImageGalleryGap, string> = {
+  lg: "gap-6",
+  md: "gap-4",
+  sm: "gap-2",
+}
+
+// Static column class mappings for Tailwind v4 detection
+const columnClasses: Record<number, string> = {
+  1: "grid-cols-1",
+  2: "grid-cols-2",
+  3: "grid-cols-3",
+  4: "grid-cols-4",
+  5: "grid-cols-5",
+  6: "grid-cols-6",
+}
+
+const smColumnClasses: Record<number, string> = {
+  1: "sm:grid-cols-1",
+  2: "sm:grid-cols-2",
+  3: "sm:grid-cols-3",
+  4: "sm:grid-cols-4",
+  5: "sm:grid-cols-5",
+  6: "sm:grid-cols-6",
+}
+
+const mdColumnClasses: Record<number, string> = {
+  1: "md:grid-cols-1",
+  2: "md:grid-cols-2",
+  3: "md:grid-cols-3",
+  4: "md:grid-cols-4",
+  5: "md:grid-cols-5",
+  6: "md:grid-cols-6",
+}
+
+const lgColumnClasses: Record<number, string> = {
+  1: "lg:grid-cols-1",
+  2: "lg:grid-cols-2",
+  3: "lg:grid-cols-3",
+  4: "lg:grid-cols-4",
+  5: "lg:grid-cols-5",
+  6: "lg:grid-cols-6",
+}
+
+const xlColumnClasses: Record<number, string> = {
+  1: "xl:grid-cols-1",
+  2: "xl:grid-cols-2",
+  3: "xl:grid-cols-3",
+  4: "xl:grid-cols-4",
+  5: "xl:grid-cols-5",
+  6: "xl:grid-cols-6",
+}
+
+// Get the number of columns for inline style fallback
+function getColumnCount(columns: number | ResponsiveColumns | undefined): number {
+  if (columns === undefined) return 4
+  if (typeof columns === "number") return columns
+  return columns.lg ?? columns.md ?? columns.sm ?? 4
+}
+
+// Generate responsive column classes using static mappings
+function getColumnClasses(
+  columns: number | ResponsiveColumns | undefined
+): string {
+  if (columns === undefined) {
+    return "grid-cols-2 sm:grid-cols-2 md:grid-cols-3 lg:grid-cols-4"
+  }
+
+  if (typeof columns === "number") {
+    return columnClasses[columns] ?? "grid-cols-4"
+  }
+
+  const classes: string[] = []
+  if (columns.sm) classes.push(smColumnClasses[columns.sm] ?? "sm:grid-cols-2")
+  if (columns.md) classes.push(mdColumnClasses[columns.md] ?? "md:grid-cols-3")
+  if (columns.lg) classes.push(lgColumnClasses[columns.lg] ?? "lg:grid-cols-4")
+  if (columns.xl) classes.push(xlColumnClasses[columns.xl] ?? "xl:grid-cols-4")
+
+  return classes.join(" ") || "grid-cols-2 md:grid-cols-3 lg:grid-cols-4"
+}
+
+// Item variants for consistent styling
+const imageGalleryItemVariants = cva(
+  [
+    "relative overflow-hidden rounded-md",
+    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2",
+    "transition-transform duration-200",
+    "cursor-pointer",
+  ],
+  {
+    variants: {
+      selected: {
+        true: "ring-2 ring-primary ring-offset-2",
+        false: "",
+      },
+      interactive: {
+        true: "hover:scale-[1.02]",
+        false: "",
+      },
+    },
+    defaultVariants: {
+      selected: false,
+      interactive: true,
+    },
+  }
+)
+
+/**
+ * Individual gallery item component
+ */
+function ImageGalleryItem({
+  aspectRatio = 1,
+  className,
+  enableLightbox = true,
+  enableSelection = false,
+  image,
+  index: _index,
+  isSelected = false,
+  onClick,
+  onImageError,
+  onImageLoad,
+  ...props
+}: ImageGalleryItemProps) {
+  const [imageState, setImageState] = React.useState<
+    "error" | "loaded" | "loading"
+  >("loading")
+
+  const handleLoad = React.useCallback(() => {
+    setImageState("loaded")
+    onImageLoad?.()
+  }, [onImageLoad])
+
+  const handleError = React.useCallback(() => {
+    setImageState("error")
+    onImageError?.(new Error(`Failed to load image: ${image.src}`))
+  }, [image.src, onImageError])
+
+  const handleKeyDown = React.useCallback(
+    (event: React.KeyboardEvent) => {
+      if (event.key === "Enter" || event.key === " ") {
+        event.preventDefault()
+        onClick?.()
+      }
+    },
+    [onClick]
+  )
+
+  return (
+    <button
+      aria-label={
+        enableSelection && isSelected
+          ? `${image.alt} (selected)`
+          : image.alt
+      }
+      className={cn(
+        imageGalleryItemVariants({
+          selected: isSelected,
+          interactive: enableLightbox || enableSelection,
+        }),
+        className
+      )}
+      aria-pressed={enableSelection ? isSelected : undefined}
+      data-error={imageState === "error" || undefined}
+      data-loading={imageState === "loading" || undefined}
+      data-selected={isSelected || undefined}
+      data-slot="image-gallery-item"
+      type="button"
+      onClick={onClick}
+      onKeyDown={handleKeyDown}
+      {...props}
+    >
+      <AspectRatio ratio={aspectRatio}>
+        {imageState === "loading" && (
+          <div className="absolute inset-0 animate-pulse bg-muted" />
+        )}
+        {imageState === "error" ? (
+          <div className="flex h-full w-full items-center justify-center bg-muted text-muted-foreground">
+            <span className="text-sm">Failed to load</span>
+          </div>
+        ) : (
+          <img
+            className={cn(
+              "h-full w-full object-cover transition-opacity duration-200",
+              imageState === "loading" ? "opacity-0" : "opacity-100"
+            )}
+            alt={image.alt}
+            data-slot="image-gallery-image"
+            loading="lazy"
+            src={image.thumbnail ?? image.src}
+            onError={handleError}
+            onLoad={handleLoad}
+          />
+        )}
+      </AspectRatio>
+
+      {/* Selection indicator */}
+      {enableSelection && isSelected && (
+        <div className="absolute right-2 top-2 flex h-6 w-6 items-center justify-center rounded-full bg-primary text-primary-foreground">
+          <Check className="h-4 w-4" />
+        </div>
+      )}
+    </button>
+  )
+}
+
+/**
+ * Grid layout component
+ */
+function GridLayout({
+  aspectRatio = 1,
+  columns,
+  enableLightbox = true,
+  enableSelection = false,
+  gap = "md",
+  images,
+  onImageError,
+  onImageLoad,
+  onItemClick,
+  selectedIds = [],
+}: {
+  aspectRatio?: number
+  columns?: number | ResponsiveColumns
+  enableLightbox?: boolean
+  enableSelection?: boolean
+  gap?: ImageGalleryGap
+  images: ImageItem[]
+  onImageError?: (image: ImageItem, error: Error) => void
+  onImageLoad?: (image: ImageItem) => void
+  onItemClick: (image: ImageItem, index: number) => void
+  selectedIds?: string[]
+}) {
+  const columnCount = getColumnCount(columns)
+
+  return (
+    <div
+      style={{
+        // Inline style fallback for grid-template-columns (Tailwind v4 compatibility)
+        gridTemplateColumns: `repeat(${String(columnCount)}, minmax(0, 1fr))`,
+      }}
+      className={cn("grid", getColumnClasses(columns), gapClasses[gap])}
+      data-layout="grid"
+    >
+      {images.map((image, index) => (
+        <ImageGalleryItem
+          key={image.id}
+          aspectRatio={aspectRatio}
+          enableLightbox={enableLightbox}
+          enableSelection={enableSelection}
+          image={image}
+          index={index}
+          isSelected={selectedIds.includes(image.id)}
+          onClick={() => {
+            onItemClick(image, index)
+          }}
+          onImageError={(error) => {
+            onImageError?.(image, error)
+          }}
+          onImageLoad={() => {
+            onImageLoad?.(image)
+          }}
+        />
+      ))}
+    </div>
+  )
+}
+
+/**
+ * Masonry layout component
+ * Uses CSS columns for a Pinterest-style layout
+ */
+function MasonryLayout({
+  columns,
+  enableLightbox = true,
+  enableSelection = false,
+  gap = "md",
+  images,
+  onImageError,
+  onImageLoad,
+  onItemClick,
+  selectedIds = [],
+}: {
+  columns?: number | ResponsiveColumns
+  enableLightbox?: boolean
+  enableSelection?: boolean
+  gap?: ImageGalleryGap
+  images: ImageItem[]
+  onImageError?: (image: ImageItem, error: Error) => void
+  onImageLoad?: (image: ImageItem) => void
+  onItemClick: (image: ImageItem, index: number) => void
+  selectedIds?: string[]
+}) {
+  const columnCount =
+    typeof columns === "number" ? columns : columns?.lg ?? columns?.md ?? 3
+
+  const gapValue = gap === "sm" ? "0.5rem" : gap === "lg" ? "1.5rem" : "1rem"
+
+  return (
+    <div
+      style={{
+        columnCount,
+        columnGap: gapValue,
+      }}
+      className="[column-fill:balance]"
+      data-layout="masonry"
+    >
+      {images.map((image, index) => {
+        const aspectRatio =
+          image.width && image.height ? image.width / image.height : 1
+
+        return (
+          <div
+            key={image.id}
+            style={{
+              marginBottom: gapValue,
+            }}
+            className="mb-2 break-inside-avoid md:mb-4 lg:mb-6"
+          >
+            <ImageGalleryItem
+              aspectRatio={aspectRatio}
+              enableLightbox={enableLightbox}
+              enableSelection={enableSelection}
+              image={image}
+              index={index}
+              isSelected={selectedIds.includes(image.id)}
+              onClick={() => {
+                onItemClick(image, index)
+              }}
+              onImageError={(error) => {
+                onImageError?.(image, error)
+              }}
+              onImageLoad={() => {
+                onImageLoad?.(image)
+              }}
+            />
+          </div>
+        )
+      })}
+    </div>
+  )
+}
+
+/**
+ * Featured layout component
+ * Shows first image large with thumbnails on the side
+ */
+function FeaturedLayout({
+  aspectRatio = 1,
+  enableLightbox = true,
+  enableSelection = false,
+  gap = "md",
+  images,
+  onImageError,
+  onImageLoad,
+  onItemClick,
+  selectedIds = [],
+}: {
+  aspectRatio?: number
+  enableLightbox?: boolean
+  enableSelection?: boolean
+  gap?: ImageGalleryGap
+  images: ImageItem[]
+  onImageError?: (image: ImageItem, error: Error) => void
+  onImageLoad?: (image: ImageItem) => void
+  onItemClick: (image: ImageItem, index: number) => void
+  selectedIds?: string[]
+}) {
+  const [featuredIndex, setFeaturedIndex] = React.useState(0)
+
+  const handleThumbnailClick = React.useCallback(
+    (image: ImageItem, originalIndex: number) => {
+      setFeaturedIndex(originalIndex)
+      onItemClick(image, originalIndex)
+    },
+    [onItemClick]
+  )
+
+  if (images.length === 0) return null
+
+  const featuredImage = images[featuredIndex]
+  if (!featuredImage) return null
+
+  const thumbnails = images.filter((_, i) => i !== featuredIndex)
+
+  return (
+    <div
+      className={cn("flex flex-col gap-4 md:flex-row", gapClasses[gap])}
+      data-layout="featured"
+    >
+      {/* Main featured image */}
+      <div className="flex-1">
+        <ImageGalleryItem
+          aspectRatio={aspectRatio}
+          className="h-full"
+          enableLightbox={enableLightbox}
+          enableSelection={enableSelection}
+          image={featuredImage}
+          index={featuredIndex}
+          isSelected={selectedIds.includes(featuredImage.id)}
+          onClick={() => {
+            onItemClick(featuredImage, featuredIndex)
+          }}
+          onImageError={(error) => {
+            onImageError?.(featuredImage, error)
+          }}
+          onImageLoad={() => {
+            onImageLoad?.(featuredImage)
+          }}
+        />
+      </div>
+
+      {/* Thumbnails sidebar */}
+      {thumbnails.length > 0 && (
+        <div
+          className={cn(
+            "flex w-full flex-row md:w-24 md:flex-col lg:w-32",
+            gapClasses[gap]
+          )}
+        >
+          {thumbnails.map((image) => {
+            const originalIndex = images.findIndex((img) => img.id === image.id)
+            return (
+              <ImageGalleryItem
+                key={image.id}
+                aspectRatio={1}
+                className="flex-1 md:flex-none"
+                enableLightbox={false}
+                enableSelection={enableSelection}
+                image={image}
+                index={originalIndex}
+                isSelected={selectedIds.includes(image.id)}
+                onClick={() => {
+                  handleThumbnailClick(image, originalIndex)
+                }}
+                onImageError={(error) => {
+                  onImageError?.(image, error)
+                }}
+                onImageLoad={() => {
+                  onImageLoad?.(image)
+                }}
+              />
+            )
+          })}
+        </div>
+      )}
+    </div>
+  )
+}
+
+/**
+ * Carousel layout component
+ * Horizontal slider using Embla Carousel
+ */
+function CarouselLayout({
+  aspectRatio = 1,
+  enableLightbox = true,
+  enableSelection = false,
+  gap = "md",
+  images,
+  onImageError,
+  onImageLoad,
+  onItemClick,
+  selectedIds = [],
+}: {
+  aspectRatio?: number
+  enableLightbox?: boolean
+  enableSelection?: boolean
+  gap?: ImageGalleryGap
+  images: ImageItem[]
+  onImageError?: (image: ImageItem, error: Error) => void
+  onImageLoad?: (image: ImageItem) => void
+  onItemClick: (image: ImageItem, index: number) => void
+  selectedIds?: string[]
+}) {
+  const [emblaRef] = useEmblaCarousel({
+    align: "start",
+    loop: false,
+    slidesToScroll: 1,
+  })
+
+  const gapValue = gap === "sm" ? "0.5rem" : gap === "lg" ? "1.5rem" : "1rem"
+
+  return (
+    <div
+      ref={emblaRef}
+      aria-roledescription="carousel"
+      className="overflow-hidden"
+      data-layout="carousel"
+    >
+      <div
+        style={{
+          gap: gapValue,
+        }}
+        className="flex"
+      >
+        {images.map((image, index) => (
+          <div
+            key={image.id}
+            aria-roledescription="slide"
+            className="min-w-0 shrink-0 basis-full sm:basis-1/2 md:basis-1/3 lg:basis-1/4"
+            role="group"
+          >
+            <ImageGalleryItem
+              aspectRatio={aspectRatio}
+              enableLightbox={enableLightbox}
+              enableSelection={enableSelection}
+              image={image}
+              index={index}
+              isSelected={selectedIds.includes(image.id)}
+              onClick={() => {
+                onItemClick(image, index)
+              }}
+              onImageError={(error) => {
+                onImageError?.(image, error)
+              }}
+              onImageLoad={() => {
+                onImageLoad?.(image)
+              }}
+            />
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+/**
+ * Loading skeleton for the gallery
+ */
+function LoadingSkeleton({
+  aspectRatio = 1,
+  columns,
+  count = 8,
+  gap = "md",
+}: {
+  aspectRatio?: number
+  columns?: number | ResponsiveColumns
+  count?: number
+  gap?: ImageGalleryGap
+}) {
+  // Generate stable keys for skeleton items
+  const skeletonKeys = React.useMemo(
+    () => Array.from({ length: count }, (_, i) => `skeleton-${String(i)}`),
+    [count]
+  )
+
+  const columnCount = getColumnCount(columns)
+
+  return (
+    <div
+      style={{
+        // Inline style fallback for grid-template-columns (Tailwind v4 compatibility)
+        gridTemplateColumns: `repeat(${String(columnCount)}, minmax(0, 1fr))`,
+      }}
+      className={cn("grid", getColumnClasses(columns), gapClasses[gap])}
+      data-loading="true"
+    >
+      {skeletonKeys.map((key) => (
+        <AspectRatio key={key} ratio={aspectRatio}>
+          <div className="h-full w-full animate-pulse rounded-md bg-muted" />
+        </AspectRatio>
+      ))}
+    </div>
+  )
+}
+
+/**
+ * ImageGallery - A component for displaying collections of images in various layouts
+ *
+ * @example
+ * ```tsx
+ * <ImageGallery
+ *   images={[
+ *     { id: "1", src: "/photo.jpg", alt: "Beach sunset" },
+ *     { id: "2", src: "/mountain.jpg", alt: "Mountain view" },
+ *   ]}
+ *   layout="grid"
+ *   columns={{ sm: 2, md: 3, lg: 4 }}
+ *   gap="md"
+ * />
+ * ```
+ */
+function ImageGallery({
+  aspectRatio = 1,
+  className,
+  columns,
+  enableLightbox = true,
+  enableSelection = false,
+  gap = "md",
+  images,
+  layout = "grid",
+  loading = false,
+  maxSelection,
+  onImageClick,
+  onImageError,
+  onImageLoad,
+  _onLoadMore,
+  onSelectionChange,
+  ref,
+  selectedIds: controlledSelectedIds,
+  ...props
+}: ImageGalleryProps & { _onLoadMore?: () => void }) {
+  // Internal selection state when uncontrolled
+  const [internalSelectedIds, setInternalSelectedIds] = React.useState<
+    string[]
+  >([])
+  const selectedIds = controlledSelectedIds ?? internalSelectedIds
+
+  const handleItemClick = React.useCallback(
+    (image: ImageItem, index: number) => {
+      // Handle selection mode
+      if (enableSelection) {
+        const newSelectedIds = selectedIds.includes(image.id)
+          ? selectedIds.filter((id) => id !== image.id)
+          : maxSelection && selectedIds.length >= maxSelection
+            ? selectedIds // Don't add if at max
+            : [...selectedIds, image.id]
+
+        if (controlledSelectedIds === undefined) {
+          setInternalSelectedIds(newSelectedIds)
+        }
+        onSelectionChange?.(newSelectedIds)
+      }
+
+      // Always call onImageClick callback
+      onImageClick?.(image, index)
+    },
+    [
+      enableSelection,
+      selectedIds,
+      maxSelection,
+      controlledSelectedIds,
+      onSelectionChange,
+      onImageClick,
+    ]
+  )
+
+  // Render loading skeleton
+  if (loading) {
+    return (
+      <div
+        ref={ref}
+        aria-busy="true"
+        aria-label="Image gallery loading"
+        className={cn("relative w-full", className)}
+        data-slot="image-gallery"
+        role="group"
+        {...props}
+      >
+        <LoadingSkeleton
+          aspectRatio={aspectRatio}
+          columns={columns}
+          count={8}
+          gap={gap}
+        />
+      </div>
+    )
+  }
+
+  // Empty state
+  if (images.length === 0) {
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "flex min-h-[200px] items-center justify-center rounded-lg border-2 border-dashed border-muted",
+          className
+        )}
+        aria-label="Empty image gallery"
+        data-slot="image-gallery"
+        role="group"
+        {...props}
+      >
+        <p className="text-muted-foreground">No images to display</p>
+      </div>
+    )
+  }
+
+  const layoutProps = {
+    aspectRatio,
+    columns,
+    enableLightbox,
+    enableSelection,
+    gap,
+    images,
+    onImageError,
+    onImageLoad,
+    onItemClick: handleItemClick,
+    selectedIds,
+  }
+
+  const layoutComponents: Record<ImageGalleryLayout, React.ReactNode> = {
+    carousel: <CarouselLayout {...layoutProps} />,
+    featured: <FeaturedLayout {...layoutProps} />,
+    grid: <GridLayout {...layoutProps} />,
+    masonry: <MasonryLayout {...layoutProps} />,
+  }
+
+  return (
+    <div
+      ref={ref}
+      aria-label={`Image gallery with ${String(images.length)} images`}
+      aria-roledescription="gallery"
+      className={cn("relative w-full", className)}
+      data-layout={layout}
+      data-slot="image-gallery"
+      role="group"
+      {...props}
+    >
+      {layoutComponents[layout]}
+    </div>
+  )
+}
+
+export { ImageGallery, ImageGalleryItem }