@djangocfg/ui-tools 2.1.120 → 2.1.121

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-tools",
-  "version": "2.1.120",
+  "version": "2.1.121",
   "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.121",
+    "@djangocfg/ui-core": "^2.1.121",
     "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.121",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.120",
-    "@djangocfg/ui-core": "^2.1.120",
+    "@djangocfg/typescript-config": "^2.1.121",
+    "@djangocfg/ui-core": "^2.1.121",
     "@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,6 +185,13 @@ 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 */}
@@ -192,16 +199,15 @@ export const Interactive = () => {
         <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>
+            <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' : '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(() => {
@@ -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,12 +256,14 @@ 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,

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

@@ -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 {