@djangocfg/ui-tools 2.1.120 → 2.1.123

package/package.json

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

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

@@ -1,5 +1,5 @@
 import { defineStory, useBoolean, useSelect, useNumber } from '@djangocfg/playground';
-import { Gallery, GalleryCompact, type GalleryMediaItem } from './index';
+import { Gallery, GalleryCompact, type GalleryMediaItem, type GalleryAspectRatio } from './index';
 
 // Sample images for testing
 const SAMPLE_IMAGES: GalleryMediaItem[] = [
@@ -185,23 +185,29 @@ export const Interactive = () => {
     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">
-            <div className="aspect-[4/3]">
-              <GalleryCompact
-                images={SAMPLE_IMAGES}
-                showDots={showDots}
-                showArrows={showArrows}
-                enableZoom={enableZoom}
-                showCounter={showCounter}
-                maxDots={maxDots}
-              />
-            </div>
+          <div className="rounded-xl border border-border overflow-hidden bg-black">
+            <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>

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,
@@ -59,12 +74,20 @@ export const GalleryCompact = memo(function GalleryCompact({
   // 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 overflow-hidden' : 'relative w-full h-full overflow-hidden'
+
   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(() => {
@@ -144,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>
     )
@@ -154,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(
@@ -180,7 +207,8 @@ export const GalleryCompact = memo(function GalleryCompact({
   if (!isMounted) {
     return (
       <div
-        className={cn('relative w-full h-full overflow-hidden', className)}
+        className={cn(containerClass, 'overflow-hidden', className)}
+        style={containerStyle}
         onClick={onClick}
       >
         <GalleryMedia
@@ -228,17 +256,19 @@ export const GalleryCompact = memo(function GalleryCompact({
 
   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,
         }}
-        className="w-full h-full"
+        className="absolute inset-0"
       >
         <CarouselContent className="-ml-0 h-full">
           {images.map((image, index) => {

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

@@ -9,7 +9,7 @@ import type { GalleryImageProps } from '../../types'
 
 /**
  * GalleryImage - Single image with loading state and error handling
- * Uses useImageLoader for preloading images before displaying
+ * Uses CSS background-image for reliable cover behavior
  */
 export const GalleryImage = memo(function GalleryImage({
   image,
@@ -25,6 +25,10 @@ export const GalleryImage = memo(function GalleryImage({
   const callbacks = useMemo(() => ({ onLoad, onError }), [onLoad, onError])
   const { isLoading, isLoaded, hasError } = useImageLoader(image.src, callbacks)
 
+  const backgroundStyle = useMemo(() =>
+    isLoaded ? { backgroundImage: `url(${image.src})` } : undefined
+  , [isLoaded, image.src])
+
   if (hasError) {
     return (
       <div
@@ -43,24 +47,16 @@ export const GalleryImage = memo(function GalleryImage({
 
   return (
     <div
-      className={cn('relative overflow-hidden', className)}
-      onClick={onClick}
-    >
-      {/* Loading skeleton */}
-      {showLoading && isLoading && (
-        <div className="absolute inset-0 bg-muted animate-pulse" />
+      className={cn(
+        'w-full h-full bg-cover bg-center bg-no-repeat',
+        isLoading && 'bg-muted animate-pulse',
+        isLoaded && 'animate-in fade-in-0 duration-300',
+        className
       )}
-
-      {/* Image - only render when preloaded */}
-      {isLoaded && (
-        <img
-          src={image.src}
-          alt={image.alt || 'Gallery image'}
-          className="w-full h-full object-cover animate-in fade-in-0 duration-300"
-          loading={priority ? 'eager' : 'lazy'}
-          decoding="async"
-        />
-      )}
-    </div>
+      style={backgroundStyle}
+      onClick={onClick}
+      role="img"
+      aria-label={image.alt || 'Gallery image'}
+    />
   )
 })

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

@@ -67,6 +67,8 @@ export const GalleryCarousel = memo(function GalleryCarousel({
   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)
@@ -246,6 +248,7 @@ export const GalleryCarousel = memo(function GalleryCarousel({
   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 {