@mgonza02/goal-image-gallery 1.2.1 → 1.2.4

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to the GoalImageGallery project will be documented in this f
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.4] - 2026-10-12
+
+### Added
+- **Floating Add Button**: Replaced the static '+' grid item with a floating action button (Fab) over the image gallery when `canAdd` is active.
+
+## [1.2.3] - 2026-10-12
+
+### Added
+- **`defaultImageCode`**: Highlights the default image in the grid.
+- **`onSetAsDefault(imageCode)`**: Star action when `multiple` and at least two images (requires handler).
+- **`onDelete(imageCode)`**, **`onUpdate(oldCode, newCode)`**, **`onAdd(imageCode)`**: Fired after successful gallery operations.
+
+## [1.2.2] - 2026-10-12
+
+### Added
+- **`maxItems`**: Cap gallery size; hides the add tile and blocks uploads beyond the limit.
+- **`allowDelete` / `minItems`**: Configurable delete in single- and multi-image mode (delete was previously limited to multi with 2+ images).
+- **`minImageWidth` / `minImageHeight`**: Minimum dimension constraints, passed to custom selectors and `validateImageFile`.
+- **`validateImageFile`**, **`validateImageFileSync`**, **`countGalleryImages`** exported from `image-utils`.
+
+### Changed
+- Delete API payload includes `action: 'delete'`, `image_codes`, and `deletedImageCode` for backends that branch on operation type.
+
 ## [1.2.1] - 2026-05-22
 
 ### 🐛 Bug Fixes

package/README.md

@@ -312,6 +312,16 @@ const CustomImageSelector = ({
 | `imageHandlerApi` | `function` | `undefined` | No | API function for image operations (required for editing) |
 | `afterUpload` | `function` | `undefined` | No | Callback function called after successful upload |
 | `multiple` | `boolean` | `false` | No | Allow multiple image selection and upload |
+| `maxItems` | `number` | `undefined` | No | Maximum number of images in the gallery (hides add control when reached) |
+| `allowDelete` | `boolean` | `true` | No | Show delete action when `canEdit` is enabled |
+| `minItems` | `number` | `0` | No | Minimum images that must remain (disables delete at this count) |
+| `minImageWidth` | `number` | `undefined` | No | Minimum image width in pixels (forwarded to selector / `validateImageFile`) |
+| `minImageHeight` | `number` | `undefined` | No | Minimum image height in pixels (forwarded to selector / `validateImageFile`) |
+| `defaultImageCode` | `string` | `undefined` | No | Marks which image is the default in the grid |
+| `onSetAsDefault` | `(imageCode) => void` | `undefined` | No | User chose default (only when `multiple` and 2+ images) |
+| `onDelete` | `(imageCode) => void` | `undefined` | No | After successful delete |
+| `onUpdate` | `(oldImageCode, newImageCode) => void` | `undefined` | No | After successful replace |
+| `onAdd` | `(imageCode) => void` | `undefined` | No | After each new image is added |
 
 ### Display Props
 

package/lib/GoalImageGallery.js

@@ -5,7 +5,7 @@ import { useMediaQuery } from "@mui/material";
 import ImageGalleryGrid from "./components/ImageGalleryGrid";
 import ImageGalleryModal from "./components/ImageGalleryModal";
 import { useImageGallery, useImageZoom, useClipboard, useKeyboardNavigation } from "./hooks/use-image-gallery";
-import { downloadImage } from "./utils/image-utils";
+import { countGalleryImages, downloadImage } from "./utils/image-utils";
 
 /**
  * GoalImageGallery - Advanced React Image Gallery Component
@@ -233,7 +233,17 @@ const GoalImageGallery = _ref => {
     hasPermission = () => true,
     currentCompany = 0,
     slot = {},
-    slotProps = {}
+    slotProps = {},
+    maxItems,
+    allowDelete = true,
+    minItems = 0,
+    minImageWidth,
+    minImageHeight,
+    defaultImageCode,
+    onSetAsDefault,
+    onDelete,
+    onUpdate,
+    onAdd
   } = _ref;
   const theme = useTheme();
   const [updatable, setUpdatable] = useState(false);
@@ -241,8 +251,21 @@ const GoalImageGallery = _ref => {
     selector: ImageSelector
   } = slot;
   const {
-    selector: imageSelectorProps
+    selector: imageSelectorProps = {}
   } = slotProps;
+  const currentImageCount = countGalleryImages((Array.isArray(imageCodes) ? imageCodes : (imageCodes || "").split(/[\s,]+/).filter(Boolean)).map((code, index) => ({
+    id: index,
+    image_code: code
+  })));
+  const mergedSelectorProps = {
+    ...imageSelectorProps,
+    maxItems,
+    currentImageCount,
+    minImageWidth,
+    minImageHeight,
+    minWidth: imageSelectorProps.minWidth ?? minImageWidth,
+    minHeight: imageSelectorProps.minHeight ?? minImageHeight
+  };
 
   // Initialize permissions
   useEffect(() => {
@@ -259,12 +282,15 @@ const GoalImageGallery = _ref => {
     zoomLevel,
     loading,
     removable,
+    canSetDefault,
+    canAdd,
     setZoomLevel,
     handleOpenImage,
     handleCloseImage,
     handleImageSelect,
     handleCancel,
     handleRemoveImage,
+    handleSetAsDefault,
     handleAfterUpload
   } = useImageGallery({
     imageCodes,
@@ -275,7 +301,14 @@ const GoalImageGallery = _ref => {
     ownerEntity,
     currentCompany,
     onRefresh,
-    showError
+    showError,
+    maxItems,
+    allowDelete,
+    minItems,
+    onSetAsDefault,
+    onDelete,
+    onUpdate,
+    onAdd
   });
 
   // Zoom and navigation handlers
@@ -338,7 +371,7 @@ const GoalImageGallery = _ref => {
       multiple: multiple,
       title: multiple ? "Seleccionar Imágenes" : "Seleccionar Imagen",
       uploadMessage: multiple ? "Arrastra imágenes aquí o haz clic para seleccionar" : "Arrastra una imagen aquí o haz clic para seleccionar",
-      ...imageSelectorProps
+      ...mergedSelectorProps
     }) : /*#__PURE__*/_jsxs("div", {
       style: {
         padding: "20px",
@@ -380,7 +413,11 @@ const GoalImageGallery = _ref => {
       onImageClick: handleOpenImage,
       onImageSelect: handleImageSelect,
       onRemoveImage: handleRemoveImage,
-      onDownloadImage: handleDownloadImage
+      onSetAsDefault: handleSetAsDefault,
+      onDownloadImage: handleDownloadImage,
+      canSetDefault: canSetDefault,
+      canAdd: canAdd,
+      defaultImageCode: defaultImageCode
     }), /*#__PURE__*/_jsx(ImageGalleryModal, {
       open: openImage !== null,
       imageUrl: openImage,
@@ -413,6 +450,16 @@ GoalImageGallery.propTypes = {
   hasPermission: PropTypes.func,
   currentCompany: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
   slot: PropTypes.object,
-  slotProps: PropTypes.object
+  slotProps: PropTypes.object,
+  maxItems: PropTypes.number,
+  allowDelete: PropTypes.bool,
+  minItems: PropTypes.number,
+  minImageWidth: PropTypes.number,
+  minImageHeight: PropTypes.number,
+  defaultImageCode: PropTypes.string,
+  onSetAsDefault: PropTypes.func,
+  onDelete: PropTypes.func,
+  onUpdate: PropTypes.func,
+  onAdd: PropTypes.func
 };
 export default GoalImageGallery;

package/lib/components/ImageGalleryGrid.js

@@ -1,5 +1,6 @@
 import PropTypes from 'prop-types';
-import { Grid, Card, CardContent } from '@mui/material';
+import { Grid, Card, CardContent, Fab, Tooltip } from '@mui/material';
+import { Add as AddIcon } from '@mui/icons-material';
 import { useTheme } from '@mui/material/styles';
 import ImageGalleryItem from './ImageGalleryItem';
 import ImageGalleryEmptyState from './ImageGalleryEmptyState';
@@ -8,7 +9,7 @@ import { StyledImageGridContainer } from '../styles/styled-components';
 /**
  * Image grid component for displaying gallery images
  */
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const ImageGalleryGrid = _ref => {
   let {
     imageList,
@@ -25,7 +26,11 @@ const ImageGalleryGrid = _ref => {
     onImageClick,
     onImageSelect,
     onRemoveImage,
-    onDownloadImage
+    onSetAsDefault,
+    onDownloadImage,
+    canSetDefault = false,
+    canAdd = false,
+    defaultImageCode
   } = _ref;
   const theme = useTheme();
   if (imageList.length === 0) {
@@ -41,9 +46,12 @@ const ImageGalleryGrid = _ref => {
       })
     });
   }
-  return /*#__PURE__*/_jsx(Card, {
+  return /*#__PURE__*/_jsxs(Card, {
     elevation: 2,
-    children: /*#__PURE__*/_jsx(CardContent, {
+    sx: {
+      position: 'relative'
+    },
+    children: [/*#__PURE__*/_jsx(CardContent, {
       children: /*#__PURE__*/_jsx(StyledImageGridContainer, {
         children: /*#__PURE__*/_jsx(Grid, {
           container: true,
@@ -70,12 +78,30 @@ const ImageGalleryGrid = _ref => {
               onImageClick: onImageClick,
               onImageSelect: onImageSelect,
               onRemoveImage: onRemoveImage,
-              onDownloadImage: onDownloadImage
+              onSetAsDefault: onSetAsDefault,
+              onDownloadImage: onDownloadImage,
+              canSetDefault: canSetDefault,
+              isDefault: !!defaultImageCode && image.image_code === defaultImageCode
             })
           }, image.id))
         })
       })
-    })
+    }), canAdd && /*#__PURE__*/_jsx(Tooltip, {
+      title: "Agregar imagen",
+      children: /*#__PURE__*/_jsx(Fab, {
+        color: "primary",
+        size: "small",
+        "aria-label": "Agregar imagen",
+        onClick: () => onImageSelect(null),
+        sx: {
+          position: 'absolute',
+          bottom: 16,
+          right: 16,
+          zIndex: 3
+        },
+        children: /*#__PURE__*/_jsx(AddIcon, {})
+      })
+    })]
   });
 };
 ImageGalleryGrid.propTypes = {
@@ -93,6 +119,10 @@ ImageGalleryGrid.propTypes = {
   onImageClick: PropTypes.func.isRequired,
   onImageSelect: PropTypes.func.isRequired,
   onRemoveImage: PropTypes.func.isRequired,
-  onDownloadImage: PropTypes.func.isRequired
+  onSetAsDefault: PropTypes.func,
+  onDownloadImage: PropTypes.func.isRequired,
+  canSetDefault: PropTypes.bool,
+  canAdd: PropTypes.bool,
+  defaultImageCode: PropTypes.string
 };
 export default ImageGalleryGrid;

package/lib/components/ImageGalleryItem.js

@@ -2,7 +2,7 @@ import React from 'react';
 import PropTypes from 'prop-types';
 import { Box, IconButton, Skeleton, Tooltip, Typography, Button } from '@mui/material';
 import { alpha, useTheme } from '@mui/material/styles';
-import { ChangeCircle as ChangeIcon, Download as DownloadIcon, Visibility as ViewIcon, Add as AddIcon, Delete as DeleteIcon } from '@mui/icons-material';
+import { ChangeCircle as ChangeIcon, Download as DownloadIcon, Visibility as ViewIcon, Add as AddIcon, Delete as DeleteIcon, Star as StarIcon, StarBorder as StarBorderIcon } from '@mui/icons-material';
 import { getImageContainerStyles, getImageOverlayStyles } from '../styles/styled-components';
 import { handleImageError } from '../utils/image-utils';
 
@@ -21,9 +21,12 @@ const ImageGalleryItem = _ref => {
     removable = false,
     allowDownload = false,
     showImageInfo = false,
+    canSetDefault = false,
+    isDefault = false,
     onImageClick,
     onImageSelect,
     onRemoveImage,
+    onSetAsDefault,
     onDownloadImage
   } = _ref;
   const theme = useTheme();
@@ -65,7 +68,31 @@ const ImageGalleryItem = _ref => {
   }
   return /*#__PURE__*/_jsxs(Box, {
     sx: getImageContainerStyles(theme),
-    children: [loading && /*#__PURE__*/_jsx(Skeleton, {
+    children: [isDefault && /*#__PURE__*/_jsxs(Box, {
+      sx: {
+        position: 'absolute',
+        top: 8,
+        left: 8,
+        zIndex: 2,
+        display: 'flex',
+        alignItems: 'center',
+        gap: 0.5,
+        px: 1,
+        py: 0.25,
+        borderRadius: 1,
+        backgroundColor: alpha(theme.palette.warning.main, 0.92),
+        color: theme.palette.warning.contrastText
+      },
+      children: [/*#__PURE__*/_jsx(StarIcon, {
+        sx: {
+          fontSize: 16
+        }
+      }), /*#__PURE__*/_jsx(Typography, {
+        variant: "caption",
+        fontWeight: 600,
+        children: "Predeterminada"
+      })]
+    }), loading && /*#__PURE__*/_jsx(Skeleton, {
       variant: "rectangular",
       width: "100%",
       height: 200,
@@ -111,6 +138,17 @@ const ImageGalleryItem = _ref => {
           },
           children: /*#__PURE__*/_jsx(DownloadIcon, {})
         })
+      }), canSetDefault && !isDefault && /*#__PURE__*/_jsx(Tooltip, {
+        title: "Usar como predeterminada",
+        children: /*#__PURE__*/_jsx(IconButton, {
+          size: "small",
+          onClick: e => {
+            e.stopPropagation();
+            onSetAsDefault?.(image);
+          },
+          color: "warning",
+          children: /*#__PURE__*/_jsx(StarBorderIcon, {})
+        })
       }), updatable && /*#__PURE__*/_jsx(Tooltip, {
         title: "Cambiar imagen",
         children: /*#__PURE__*/_jsx(IconButton, {
@@ -163,9 +201,12 @@ ImageGalleryItem.propTypes = {
   removable: PropTypes.bool,
   allowDownload: PropTypes.bool,
   showImageInfo: PropTypes.bool,
+  canSetDefault: PropTypes.bool,
+  isDefault: PropTypes.bool,
   onImageClick: PropTypes.func.isRequired,
   onImageSelect: PropTypes.func.isRequired,
   onRemoveImage: PropTypes.func.isRequired,
+  onSetAsDefault: PropTypes.func,
   onDownloadImage: PropTypes.func.isRequired
 };
 export default ImageGalleryItem;

package/lib/hooks/use-image-gallery.js

@@ -1,4 +1,5 @@
 import { useEffect, useState, useCallback } from 'react';
+import { countGalleryImages } from '../utils/image-utils';
 
 /**
  * Custom hook for managing image gallery state
@@ -13,7 +14,14 @@ export const useImageGallery = _ref => {
     ownerEntity,
     currentCompany,
     onRefresh,
-    showError
+    showError,
+    maxItems,
+    allowDelete = true,
+    minItems = 0,
+    onSetAsDefault,
+    onDelete,
+    onUpdate,
+    onAdd
   } = _ref;
   const [openImage, setOpenImage] = useState(null);
   const [selectedImageIndex, setSelectedImageIndex] = useState(0);
@@ -23,6 +31,8 @@ export const useImageGallery = _ref => {
   const [zoomLevel, setZoomLevel] = useState(1);
   const [loading, setLoading] = useState(false);
   const [removable, setRemovable] = useState(false);
+  const [canSetDefault, setCanSetDefault] = useState(false);
+  const [canAdd, setCanAdd] = useState(false);
 
   // Process image codes into image list
   useEffect(() => {
@@ -40,17 +50,14 @@ export const useImageGallery = _ref => {
     } else {
       newList = [];
     }
-    setRemovable(multiple && newList.length > 1);
-
-    // Add plus button for multiple mode
-    if (updatable && multiple) {
-      newList.push({
-        image_code: '+',
-        id: newList.length
-      });
-    }
+    const imageCount = newList.length;
+    const canRemoveMore = imageCount > minItems;
+    setRemovable(!!(updatable && allowDelete && imageCount > 0 && canRemoveMore));
+    const atMaxItems = maxItems != null && imageCount >= maxItems;
+    setCanAdd(!!(updatable && multiple && !atMaxItems));
+    setCanSetDefault(!!(multiple && imageCount >= 2 && onSetAsDefault));
     setImageList(newList);
-  }, [imageCodes, canEdit, multiple, updatable]);
+  }, [imageCodes, canEdit, multiple, updatable, maxItems, allowDelete, minItems, onSetAsDefault]);
 
   // Image handlers
   const handleOpenImage = useCallback(function (imageUrl) {
@@ -64,9 +71,16 @@ export const useImageGallery = _ref => {
     setZoomLevel(1);
   }, []);
   const handleImageSelect = useCallback(image => {
+    if (image === null && maxItems != null) {
+      const currentCount = countGalleryImages(imageList);
+      if (currentCount >= maxItems) {
+        showError?.(`Máximo ${maxItems} imágenes permitidas`);
+        return;
+      }
+    }
     setSelectedImage(image);
     setSelectingImage(true);
-  }, []);
+  }, [imageList, maxItems, showError]);
   const handleCancel = useCallback(() => {
     setSelectingImage(false);
   }, []);
@@ -83,9 +97,13 @@ export const useImageGallery = _ref => {
         ...ownerEntity,
         companyId: currentCompany,
         image_code: imagesToSave,
-        company_id: currentCompany
+        image_codes: imagesToSave,
+        company_id: currentCompany,
+        action: 'delete',
+        deletedImageCode: image.image_code
       });
       if (result.success) {
+        onDelete?.(image.image_code);
         onRefresh?.(result);
       } else {
         showError(result.message);
@@ -95,7 +113,13 @@ export const useImageGallery = _ref => {
     } finally {
       setLoading(false);
     }
-  }, [ownerEntity, currentCompany, imageList, onRefresh, showError, imageHandlerApi]);
+  }, [ownerEntity, currentCompany, imageList, onRefresh, onDelete, showError, imageHandlerApi]);
+  const handleSetAsDefault = useCallback(image => {
+    if (!image?.image_code || image.image_code === '+') {
+      return;
+    }
+    onSetAsDefault?.(image.image_code);
+  }, [onSetAsDefault]);
 
   /**
    * Handles the upload completion for single or multiple images
@@ -149,19 +173,47 @@ export const useImageGallery = _ref => {
         }
       });
     }
+    if (maxItems != null && imagesToSave.length > maxItems) {
+      showError?.(`Máximo ${maxItems} imágenes permitidas (se intentaron guardar ${imagesToSave.length})`);
+      return;
+    }
+    const existingCodes = imageList.reduce((acc, img) => {
+      if (img.image_code !== '+') {
+        acc.push(img.image_code);
+      }
+      return acc;
+    }, []);
     const result = await imageHandlerApi({
       ...ownerEntity,
       companyId: currentCompany,
       company_id: currentCompany,
-      image_code: imagesToSave
+      image_code: imagesToSave,
+      image_codes: imagesToSave
     });
     if (result.success) {
+      if (currentImageCode) {
+        const newPrimaryCode = imagesArray[0]?.code;
+        if (newPrimaryCode && newPrimaryCode !== currentImageCode) {
+          onUpdate?.(currentImageCode, newPrimaryCode);
+        }
+        imagesArray.slice(1).forEach(image => {
+          if (image?.code) {
+            onAdd?.(image.code);
+          }
+        });
+      } else {
+        imagesArray.forEach(image => {
+          if (image?.code && !existingCodes.includes(image.code)) {
+            onAdd?.(image.code);
+          }
+        });
+      }
       setSelectingImage(false);
       onRefresh?.(result);
     } else {
       showError(result.message);
     }
-  }, [ownerEntity, currentCompany, imageList, selectedImage, imageHandlerApi, onRefresh, showError]);
+  }, [ownerEntity, currentCompany, imageList, selectedImage, imageHandlerApi, onRefresh, onAdd, onUpdate, showError, maxItems]);
   return {
     openImage,
     selectedImageIndex,
@@ -171,12 +223,15 @@ export const useImageGallery = _ref => {
     zoomLevel,
     loading,
     removable,
+    canSetDefault,
+    canAdd,
     setZoomLevel,
     handleOpenImage,
     handleCloseImage,
     handleImageSelect,
     handleCancel,
     handleRemoveImage,
+    handleSetAsDefault,
     handleAfterUpload
   };
 };

package/lib/index.d.ts

@@ -23,6 +23,26 @@ export interface GoalImageGalleryProps {
   slotProps?: {
     selector?: object;
   };
+  /** Maximum number of images allowed in the gallery */
+  maxItems?: number;
+  /** When false, hides delete actions */
+  allowDelete?: boolean;
+  /** Minimum images that must remain (delete disabled at or below this count) */
+  minItems?: number;
+  /** Minimum image width in pixels (passed to selector and validateImageFile) */
+  minImageWidth?: number;
+  /** Minimum image height in pixels (passed to selector and validateImageFile) */
+  minImageHeight?: number;
+  /** Image code marked as default (badge + star state) */
+  defaultImageCode?: string;
+  /** Called when user sets an image as default (multi-image galleries with 2+ images) */
+  onSetAsDefault?: (imageCode: string) => void;
+  /** Called after a successful delete */
+  onDelete?: (imageCode: string) => void;
+  /** Called after a successful replace upload */
+  onUpdate?: (oldImageCode: string, newImageCode: string) => void;
+  /** Called after each new image is added */
+  onAdd?: (imageCode: string) => void;
 }
 
 // Image item interface
@@ -54,6 +74,13 @@ export interface UseImageGalleryOptions {
   currentCompany?: string;
   onRefresh?: (result: any) => void;
   showError?: (message: string) => void;
+  maxItems?: number;
+  allowDelete?: boolean;
+  minItems?: number;
+  onSetAsDefault?: (imageCode: string) => void;
+  onDelete?: (imageCode: string) => void;
+  onUpdate?: (oldImageCode: string, newImageCode: string) => void;
+  onAdd?: (imageCode: string) => void;
 }
 
 export interface UseImageGalleryReturn {
@@ -65,12 +92,15 @@ export interface UseImageGalleryReturn {
   zoomLevel: number;
   loading: boolean;
   removable: boolean;
+  canSetDefault: boolean;
+  canAdd: boolean;
   setZoomLevel: (level: number) => void;
   handleOpenImage: (imageUrl: string, index?: number) => void;
   handleCloseImage: () => void;
   handleImageSelect: (image: ImageItem | null) => void;
   handleCancel: () => void;
   handleRemoveImage: (image: ImageItem) => Promise<void>;
+  handleSetAsDefault: (image: ImageItem) => void;
   handleAfterUpload: (images: UploadedImage | UploadedImage[]) => Promise<void>;
 }
 
@@ -105,7 +135,11 @@ export interface ImageGalleryGridProps {
   onImageClick: (imageUrl: string, index: number) => void;
   onImageSelect: (image: ImageItem | null) => void;
   onRemoveImage: (image: ImageItem) => void;
+  onSetAsDefault?: (image: ImageItem) => void;
   onDownloadImage: (imageCode: string) => void;
+  canSetDefault?: boolean;
+  canAdd?: boolean;
+  defaultImageCode?: string;
 }
 
 export interface ImageGalleryModalProps {
@@ -135,7 +169,10 @@ export interface ImageGalleryItemProps {
   onImageClick: (imageUrl: string, index: number) => void;
   onImageSelect: (image: ImageItem) => void;
   onRemoveImage: (image: ImageItem) => void;
+  onSetAsDefault?: (image: ImageItem) => void;
   onDownloadImage: (imageCode: string) => void;
+  canSetDefault?: boolean;
+  isDefault?: boolean;
 }
 
 export interface ImageGalleryEmptyStateProps {
@@ -200,3 +237,20 @@ export declare const debounce: Debounce;
 export declare const isTouchDevice: IsTouchDevice;
 export declare const getImageDimensions: GetImageDimensions;
 export declare const createImagePreview: CreateImagePreview;
+export declare const countGalleryImages: (imageList: ImageItem[]) => number;
+export declare const validateImageFileSync: (
+  file: File,
+  options?: {
+    maxSize?: number;
+    allowedTypes?: string[];
+  }
+) => { isValid: boolean; errors: string[] };
+export declare const validateImageFile: (
+  file: File,
+  options?: {
+    maxSize?: number;
+    allowedTypes?: string[];
+    minWidth?: number;
+    minHeight?: number;
+  }
+) => Promise<{ isValid: boolean; errors: string[]; width?: number; height?: number }>;

package/lib/index.js

@@ -20,7 +20,7 @@ export { useImageGallery, useImageZoom, useClipboard, useKeyboardNavigation } fr
 export { StyledImageContainer, ImageOverlay, StyledModalContainer, StyledModalHeader, StyledModalBody, StyledModalFooter, StyledEmptyStateContainer, StyledImageGridContainer } from './styles/styled-components';
 
 // Utility exports
-export { handleImageError, downloadImage, processImageCodes, getGridColumns, isValidImageFile, formatFileSize, generateId, debounce, isTouchDevice, getImageDimensions, createImagePreview } from './utils/image-utils';
+export { handleImageError, downloadImage, processImageCodes, getGridColumns, isValidImageFile, formatFileSize, generateId, debounce, isTouchDevice, getImageDimensions, createImagePreview, countGalleryImages, validateImageFile, validateImageFileSync } from './utils/image-utils';
 
 // Examples and documentation
 export { default as GoalImageGalleryExamples } from './examples';
@@ -66,25 +66,9 @@ export const utils = {
    * @param {Object} options - Validation options
    * @returns {Object} - Validation result
    */
-  validateImageFile: function (file) {
-    let options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
-    const {
-      maxSize = 5 * 1024 * 1024,
-      // 5MB
-      allowedTypes = FEATURES.SUPPORTED_FORMATS
-    } = options;
-    const errors = [];
-    if (file.size > maxSize) {
-      errors.push(`File size exceeds ${maxSize / 1024 / 1024}MB limit`);
-    }
-    if (!allowedTypes.includes(file.type)) {
-      errors.push(`File type ${file.type} is not supported`);
-    }
-    return {
-      isValid: errors.length === 0,
-      errors
-    };
-  },
+  validateImageFile,
+  validateImageFileSync,
+  countGalleryImages,
   /**
    * Create image handler API wrapper
    * @param {Function} uploadFunction - Upload function
@@ -136,8 +120,20 @@ export const CONFIG = {
 };
 
 // Export version info
-export const VERSION = '1.2.1';
+export const VERSION = '1.2.4';
 export const CHANGELOG = [{
+  version: '1.2.4',
+  date: '2026-10-12',
+  changes: ['Replaced grid add placeholder tile with a floating action button over the image gallery when canAdd is true']
+}, {
+  version: '1.2.3',
+  date: '2026-10-12',
+  changes: ['Added defaultImageCode, onSetAsDefault, onDelete, onUpdate, and onAdd lifecycle callbacks', 'Set-as-default control shown only when multiple is true and there are at least two images']
+}, {
+  version: '1.2.2',
+  date: '2026-10-12',
+  changes: ['Added allowDelete, maxItems, minItems, minImageWidth, and minImageHeight props', 'Delete is available for single and multiple galleries when editing (respects minItems)', 'Exported validateImageFile async helper with minimum dimension checks']
+}, {
   version: '1.2.1',
   date: '2026-05-22',
   changes: ['Fixed warning about invalid alignItems prop being passed to DOM elements by Stack components']

package/lib/utils/image-utils.js

@@ -47,13 +47,94 @@ export const getGridColumns = (isMobile, isTablet, multiple) => {
   if (isTablet) return multiple ? 4 : 6; // 3 or 2 columns on tablet
   return multiple ? 3 : 4; // 4 or 3 columns on desktop
 };
+const DEFAULT_IMAGE_TYPES = ['image/jpeg', 'image/jpg', 'image/png', 'image/gif', 'image/webp'];
 
 /**
  * Validate image file type
  */
 export const isValidImageFile = file => {
-  const validTypes = ['image/jpeg', 'image/jpg', 'image/png', 'image/gif', 'image/webp'];
-  return validTypes.includes(file.type);
+  return DEFAULT_IMAGE_TYPES.includes(file.type);
+};
+
+/**
+ * Count gallery images (excludes the "+" add placeholder).
+ */
+export const countGalleryImages = function () {
+  let imageList = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : [];
+  return imageList.filter(img => img?.image_code && img.image_code !== '+').length;
+};
+
+/**
+ * Validate image file size and type (sync). Use validateImageFile for dimension checks.
+ */
+export const validateImageFileSync = function (file) {
+  let options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  const {
+    maxSize = 25 * 1024 * 1024,
+    allowedTypes = DEFAULT_IMAGE_TYPES
+  } = options;
+  const errors = [];
+  if (!file) {
+    errors.push('No se ha seleccionado ningún archivo');
+  } else {
+    if (maxSize && file.size > maxSize) {
+      errors.push(`El tamaño del archivo supera el límite de ${formatFileSize(maxSize)}`);
+    }
+    if (allowedTypes.length && !allowedTypes.includes(file.type)) {
+      errors.push(`El tipo de archivo ${file.type || 'desconocido'} no está permitido`);
+    }
+  }
+  return {
+    isValid: errors.length === 0,
+    errors
+  };
+};
+
+/**
+ * Validate image file including optional minimum width and height (async).
+ */
+export const validateImageFile = async function (file) {
+  let options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  const {
+    minWidth,
+    minHeight,
+    minImageWidth,
+    minImageHeight,
+    ...syncOptions
+  } = options;
+  const resolvedMinWidth = minWidth ?? minImageWidth;
+  const resolvedMinHeight = minHeight ?? minImageHeight;
+  const syncResult = validateImageFileSync(file, syncOptions);
+  if (!syncResult.isValid || !resolvedMinWidth && !resolvedMinHeight) {
+    return syncResult;
+  }
+  const objectUrl = URL.createObjectURL(file);
+  try {
+    const {
+      width,
+      height
+    } = await getImageDimensions(objectUrl);
+    const errors = [...syncResult.errors];
+    if (resolvedMinWidth && width < resolvedMinWidth) {
+      errors.push(`El ancho mínimo es ${resolvedMinWidth}px (la imagen tiene ${width}px)`);
+    }
+    if (resolvedMinHeight && height < resolvedMinHeight) {
+      errors.push(`El alto mínimo es ${resolvedMinHeight}px (la imagen tiene ${height}px)`);
+    }
+    return {
+      isValid: errors.length === 0,
+      errors,
+      width,
+      height
+    };
+  } catch {
+    return {
+      isValid: false,
+      errors: [...syncResult.errors, 'No se pudieron leer las dimensiones de la imagen']
+    };
+  } finally {
+    URL.revokeObjectURL(objectUrl);
+  }
 };
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mgonza02/goal-image-gallery",
-  "version": "1.2.1",
+  "version": "1.2.4",
   "description": "Advanced, accessible, and highly customizable React image gallery component with multi-method upload, responsive design, and extensive TypeScript support",
   "main": "lib/index.js",
   "module": "lib/index.js",