@djangocfg/ui-tools 2.1.137 → 2.1.138

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.137",
+  "version": "2.1.138",
   "description": "Heavy React tools with lazy loading - for Electron, Vite, CRA, Next.js apps",
   "keywords": [
     "ui-tools",
@@ -63,8 +63,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.137",
-    "@djangocfg/ui-core": "^2.1.137",
+    "@djangocfg/i18n": "^2.1.138",
+    "@djangocfg/ui-core": "^2.1.138",
     "lucide-react": "^0.545.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -96,10 +96,10 @@
     "@maplibre/maplibre-gl-geocoder": "^1.7.0"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.137",
+    "@djangocfg/i18n": "^2.1.138",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.137",
-    "@djangocfg/ui-core": "^2.1.137",
+    "@djangocfg/typescript-config": "^2.1.138",
+    "@djangocfg/ui-core": "^2.1.138",
     "@types/mapbox__mapbox-gl-draw": "^1.4.8",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",

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

@@ -16,3 +16,6 @@ export { GalleryImage, GalleryVideo, GalleryMedia, type GalleryMediaProps } from
 
 // Thumbnails
 export { GalleryThumbnails, GalleryThumbnailsVirtual } from './thumbnails'
+
+// Shared components
+export { ImageSpinner, type ImageSpinnerProps } from './shared'

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

@@ -7,6 +7,7 @@ import { useImageLoader } from '@djangocfg/ui-core/hooks'
 import { ImageOff } from 'lucide-react'
 import type { GalleryImageProps } from '../../types'
 import { normalizeImageUrl } from '../../utils'
+import { ImageSpinner } from '../shared'
 
 /**
  * GalleryImage - Single image with loading state and error handling
@@ -24,17 +25,18 @@ export const GalleryImage = memo(function GalleryImage({
 }: GalleryImageProps) {
   const t = useTypedT<I18nTranslations>()
   const failedToLoadText = useMemo(() => t('tools.image.failedToLoad'), [t])
+  const normalizedSrc = useMemo(() => normalizeImageUrl(image.src), [image.src])
   const callbacks = useMemo(() => ({ onLoad, onError }), [onLoad, onError])
-  const { isLoading, isLoaded, hasError } = useImageLoader(image.src, callbacks)
+  const { isLoading, isLoaded, hasError } = useImageLoader(normalizedSrc, callbacks)
 
   const backgroundStyle = useMemo(() =>
     isLoaded && objectFit === 'cover' ? {
-      backgroundImage: `url(${image.src})`,
+      backgroundImage: `url(${normalizedSrc})`,
       backgroundSize: 'cover',
       backgroundPosition: 'center',
       backgroundRepeat: 'no-repeat',
     } : undefined
-  , [isLoaded, image.src, objectFit])
+  , [isLoaded, normalizedSrc, objectFit])
 
   if (hasError) {
     return (
@@ -57,15 +59,20 @@ export const GalleryImage = memo(function GalleryImage({
     return (
       <div
         className={cn(
-          'w-full h-full flex items-center justify-center',
-          isLoading && 'bg-muted animate-pulse',
+          'relative w-full h-full flex items-center justify-center bg-muted',
           className
         )}
         onClick={onClick}
       >
+        {/* Loading spinner */}
+        {isLoading && showLoading && (
+          <div className="absolute inset-0 flex items-center justify-center">
+            <ImageSpinner size="lg" />
+          </div>
+        )}
         {isLoaded && (
           <img
-            src={image.src}
+            src={normalizedSrc}
             alt={image.alt || 'Gallery image'}
             className="max-w-full max-h-full object-contain animate-in fade-in-0 duration-300"
           />
@@ -78,8 +85,7 @@ export const GalleryImage = memo(function GalleryImage({
   return (
     <div
       className={cn(
-        'w-full h-full',
-        isLoading && 'bg-muted animate-pulse',
+        'relative w-full h-full bg-muted',
         isLoaded && 'animate-in fade-in-0 duration-300',
         className
       )}
@@ -87,6 +93,13 @@ export const GalleryImage = memo(function GalleryImage({
       onClick={onClick}
       role="img"
       aria-label={image.alt || 'Gallery image'}
-    />
+    >
+      {/* Loading spinner */}
+      {isLoading && showLoading && (
+        <div className="absolute inset-0 flex items-center justify-center">
+          <ImageSpinner size="md" />
+        </div>
+      )}
+    </div>
   )
 })

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

@@ -1,10 +1,11 @@
 'use client'
 
-import { memo, useCallback, useMemo } from 'react'
+import { memo, useCallback, useMemo, useState } from 'react'
 import { cn } from '@djangocfg/ui-core/lib'
 import { Play } from 'lucide-react'
 import type { GalleryMediaItem } from '../../types'
 import { normalizeImageUrl } from '../../utils'
+import { ImageSpinner } from '../shared'
 
 export type GalleryGridLayout =
   | 'auto'
@@ -348,10 +349,21 @@ const GridItem = memo(function GridItem({
   showBadge = false,
   badgeCount = 0,
 }: GridItemProps) {
+  const [isLoaded, setIsLoaded] = useState(false)
+  const [hasError, setHasError] = useState(false)
+
   const handleClick = useCallback(() => {
     onClick(index)
   }, [onClick, index])
 
+  const handleLoad = useCallback(() => {
+    setIsLoaded(true)
+  }, [])
+
+  const handleError = useCallback(() => {
+    setHasError(true)
+  }, [])
+
   if (!image) return null
 
   const isVideo = image.type === 'video'
@@ -370,16 +382,26 @@ const GridItem = memo(function GridItem({
       onClick={handleClick}
       aria-label={`View image ${index + 1}`}
     >
+      {/* Loading spinner - shows until image loads */}
+      {!isLoaded && !hasError && (
+        <div className="absolute inset-0 flex items-center justify-center z-10">
+          <ImageSpinner size="md" />
+        </div>
+      )}
+
       <img
         src={normalizeImageUrl(image.thumbnail || image.src)}
         alt={image.alt || `Image ${index + 1}`}
         className={cn(
-          'w-full h-full object-cover transition-transform duration-300 group-hover:scale-105',
-          // Staggered reveal animation with CSS only (no JS state needed)
-          staggerDelay > 0 && 'animate-in fade-in zoom-in-95 duration-300 fill-mode-both'
+          'w-full h-full object-cover transition-all duration-300 group-hover:scale-105',
+          // Hide until loaded, then fade in
+          !isLoaded && 'opacity-0',
+          isLoaded && 'opacity-100'
         )}
-        style={staggerDelay > 0 ? { animationDelay } : undefined}
+        style={staggerDelay > 0 && isLoaded ? { animationDelay } : undefined}
         loading={index === 0 ? 'eager' : 'lazy'}
+        onLoad={handleLoad}
+        onError={handleError}
       />
 
       {/* Hover overlay */}

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

@@ -0,0 +1,37 @@
+'use client'
+
+import { memo } from 'react'
+import { cn } from '@djangocfg/ui-core/lib'
+
+export interface ImageSpinnerProps {
+  /** Size variant */
+  size?: 'sm' | 'md' | 'lg'
+  /** Additional class */
+  className?: string
+}
+
+const SIZE_CLASSES = {
+  sm: 'w-4 h-4 border-[1.5px]',
+  md: 'w-6 h-6 border-2',
+  lg: 'w-8 h-8 border-2',
+} as const
+
+/**
+ * Minimal loading spinner for images
+ * Adapts to dark/light theme via muted-foreground
+ */
+export const ImageSpinner = memo(function ImageSpinner({
+  size = 'md',
+  className,
+}: ImageSpinnerProps) {
+  return (
+    <div
+      className={cn(
+        'rounded-full animate-spin',
+        'border-muted-foreground/20 border-t-muted-foreground/60',
+        SIZE_CLASSES[size],
+        className
+      )}
+    />
+  )
+})

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

@@ -0,0 +1 @@
+export { ImageSpinner, type ImageSpinnerProps } from './ImageSpinner'

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

@@ -1,8 +1,10 @@
 'use client'
 
-import { memo, useRef, useEffect, useCallback, Suspense, lazy } from 'react'
+import { memo, useRef, useEffect, useCallback, Suspense, lazy, useState } from 'react'
 import { cn } from '@djangocfg/ui-core/lib'
 import type { GalleryThumbnailsProps } from '../../types'
+import { normalizeImageUrl } from '../../utils'
+import { ImageSpinner } from '../shared'
 
 // Lazy load virtualized thumbnails - only for 50+ images
 const GalleryThumbnailsVirtual = lazy(() =>
@@ -135,16 +137,22 @@ const ThumbnailButton = memo(
     onClick,
     ref,
   }: ThumbnailButtonProps & { ref?: React.Ref<HTMLButtonElement> }) {
+    const [isLoaded, setIsLoaded] = useState(false)
+
     const handleClick = useCallback(() => {
       onClick(index)
     }, [onClick, index])
 
+    const handleLoad = useCallback(() => {
+      setIsLoaded(true)
+    }, [])
+
     return (
       <button
         ref={ref}
         type="button"
         className={cn(
-          'relative flex-shrink-0 rounded-lg overflow-hidden',
+          'relative flex-shrink-0 rounded-lg overflow-hidden bg-muted',
           'border-2 transition-all duration-200',
           'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary',
           SIZES[size],
@@ -156,11 +164,22 @@ const ThumbnailButton = memo(
         aria-label={`View image ${index + 1}`}
         aria-current={isActive ? 'true' : undefined}
       >
+        {/* Loading spinner */}
+        {!isLoaded && (
+          <div className="absolute inset-0 flex items-center justify-center">
+            <ImageSpinner size="sm" />
+          </div>
+        )}
+
         <img
-          src={image.thumbnail || image.src}
+          src={normalizeImageUrl(image.thumbnail || image.src)}
           alt={image.alt || `Thumbnail ${index + 1}`}
-          className="w-full h-full object-cover"
+          className={cn(
+            'w-full h-full object-cover transition-opacity duration-200',
+            isLoaded ? 'opacity-100' : 'opacity-0'
+          )}
           loading="lazy"
+          onLoad={handleLoad}
         />
 
         {/* Active overlay */}

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

@@ -1,9 +1,11 @@
 'use client'
 
-import { memo, useCallback, useEffect } from 'react'
+import { memo, useCallback, useEffect, useState } from 'react'
 import { cn } from '@djangocfg/ui-core/lib'
 import { useVirtualList } from '../../hooks/useVirtualList'
 import type { GalleryThumbnailsProps } from '../../types'
+import { normalizeImageUrl } from '../../utils'
+import { ImageSpinner } from '../shared'
 
 const SIZES = {
   sm: { width: 56, height: 40 },
@@ -98,15 +100,21 @@ const VirtualThumbnail = memo(function VirtualThumbnail({
   height,
   onClick,
 }: VirtualThumbnailProps) {
+  const [isLoaded, setIsLoaded] = useState(false)
+
   const handleClick = useCallback(() => {
     onClick(index)
   }, [onClick, index])
 
+  const handleLoad = useCallback(() => {
+    setIsLoaded(true)
+  }, [])
+
   return (
     <button
       type="button"
       className={cn(
-        'absolute top-0 rounded-lg overflow-hidden',
+        'absolute top-0 rounded-lg overflow-hidden bg-muted',
         'border-2 transition-all duration-200',
         'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary',
         isActive
@@ -122,11 +130,22 @@ const VirtualThumbnail = memo(function VirtualThumbnail({
       aria-label={`View image ${index + 1}`}
       aria-current={isActive ? 'true' : undefined}
     >
+      {/* Loading spinner */}
+      {!isLoaded && (
+        <div className="absolute inset-0 flex items-center justify-center">
+          <ImageSpinner size="sm" />
+        </div>
+      )}
+
       <img
-        src={image.thumbnail || image.src}
+        src={normalizeImageUrl(image.thumbnail || image.src)}
         alt={image.alt || `Thumbnail ${index + 1}`}
-        className="w-full h-full object-cover"
+        className={cn(
+          'w-full h-full object-cover transition-opacity duration-200',
+          isLoaded ? 'opacity-100' : 'opacity-0'
+        )}
         loading="lazy"
+        onLoad={handleLoad}
       />
 
       {/* Active overlay */}