@mgonza02/goal-image-gallery 1.2.5 → 1.2.6

package/CHANGELOG.md

@@ -5,6 +5,14 @@ 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.6] - 2026-10-13
+
+### 🚀 Enhancements & Responsive Layout
+- **Full-Width Hero / First Image (`featuredFirst`)**: Single-image galleries (`imageList.length === 1`) now automatically occupy full container width (`xs: 12, sm: 12, md: 12`) instead of being squished into a 25% narrow strip.
+- **Featured First Image Prop (`featuredFirst`)**: Added `featuredFirst?: boolean` prop to allow the primary/first image (`index === 0`) to span all 12 columns as a featured hero image, while subsequent images render in balanced responsive columns underneath.
+- **Balanced 2 & 3 Image Grids**: 2-image galleries split evenly (`50% / 50%`) and 3-image galleries split (`33% / 33% / 33%`) when `featuredFirst` is disabled, maximizing space usage.
+- **Customizable Image Heights**: Added `itemHeight` (default: 200px) and `featuredItemHeight` (default: 240px) props to `GoalImageGallery`, `ImageGalleryGrid`, and `ImageGalleryItem`.
+
 ## [1.2.5] - 2026-10-13
 
 ### 🐛 Bug Fixes

package/IMPLEMENTATION_GUIDE.md

@@ -262,6 +262,68 @@ const PermissionBasedGallery = ({ images, entityId, entityType }) => {
       allowDownload={hasPermission('DOWNLOAD_IMAGES')}
     />
   );
+### 3. Advanced Management, Limits & Lifecycle Callbacks (v1.2.2 - v1.2.5)
+
+In v1.2.2 – v1.2.5, `GoalImageGallery` introduces fine-grained operational controls, a floating action button for adding images, default image highlighting/selection, and reactive lifecycle hooks:
+
+```javascript
+import React, { useState, useCallback } from 'react';
+import { GoalImageGallery, validateImageFile } from '@mgonza02/goal-image-gallery';
+
+const ProductCatalogGallery = ({ product, onSave }) => {
+  const [imageCodes, setImageCodes] = useState(product.image_codes || []);
+  const [defaultImage, setDefaultImage] = useState(product.default_image || imageCodes[0]);
+
+  // Granular lifecycle callbacks
+  const handleAdd = useCallback((newCode) => {
+    console.log('Image added:', newCode);
+  }, []);
+
+  const handleUpdate = useCallback((oldCode, newCode) => {
+    console.log(`Replaced ${oldCode} with ${newCode}`);
+    if (defaultImage === oldCode) setDefaultImage(newCode);
+  }, [defaultImage]);
+
+  const handleDelete = useCallback((deletedCode) => {
+    console.log('Deleted image:', deletedCode);
+    if (defaultImage === deletedCode) {
+      setDefaultImage(imageCodes.filter(c => c !== deletedCode)[0]);
+    }
+  }, [defaultImage, imageCodes]);
+
+  const handleSetDefault = useCallback((image) => {
+    setDefaultImage(image.image_code);
+    onSave?.({ ...product, default_image: image.image_code });
+  }, [product, onSave]);
+
+  return (
+    <GoalImageGallery
+      imageCodes={imageCodes}
+      canEdit={true}
+      multiple={true}
+      ownerEntity={{ id: product.id, type: 'product' }}
+      imageHandlerApi={uploadApiHandler}
+      afterUpload={(res) => setImageCodes(res.data.image_codes)}
+
+      // Floating Add Button & Item Capping (v1.2.2 & v1.2.4)
+      maxItems={6}                   // Caps gallery at 6 images; hides floating add button
+      allowDelete={true}             // Delete enabled in single and multi modes
+      minItems={1}                   // Must keep at least 1 image; prevents deleting last photo
+
+      // Minimum Dimension Validation (v1.2.2)
+      minImageWidth={400}
+      minImageHeight={400}
+
+      // Default Image Badge & Selection (v1.2.3)
+      defaultImageCode={defaultImage}
+      onSetAsDefault={handleSetDefault} // Star icon appears on hover when >= 2 images
+
+      // Granular Lifecycle Hooks (v1.2.3)
+      onAdd={handleAdd}
+      onUpdate={handleUpdate}
+      onDelete={handleDelete}
+    />
+  );
 };
 ```
 

package/QUICK_REFERENCE.md

@@ -54,11 +54,53 @@ import { GoalImageGallery } from '@mgonza02/goal-image-gallery';
 | `imageHandlerApi` | `function` | - | Upload handler function |
 | `afterUpload` | `function` | - | Success callback |
 | `multiple` | `boolean` | `false` | Allow multiple images |
+| `maxItems` | `number` | - | Maximum items allowed (hides floating add button when reached) |
+| `allowDelete` | `boolean` | `true` | Enable deletion (available in both single and multi-mode) |
+| `minItems` | `number` | `0` | Minimum items required (disables delete at or below this count) |
+| `minImageWidth` | `number` | - | Minimum image width in pixels |
+| `minImageHeight` | `number` | - | Minimum image height in pixels |
+| `defaultImageCode` | `string` | - | Marks default image with a "Predeterminada" badge |
+| `onSetAsDefault` | `(image) => void` | - | Callback when set as default is clicked (multiple & >=2 images) |
+| `onDelete` | `(imageCode) => void` | - | Fired after successful image deletion |
+| `onUpdate` | `(oldCode, newCode) => void` | - | Fired after successful image replacement |
+| `onAdd` | `(imageCode) => void` | - | Fired after each newly added image |
 | `permission` | `string` | - | Required permission |
 | `emptyMessage` | `string` | `'No hay imágenes para mostrar'` | Empty state message |
 | `showImageInfo` | `boolean` | `false` | Show image info |
 | `allowDownload` | `boolean` | `true` | Enable downloads |
 
+## Floating Add Button (v1.2.4+)
+
+In editable multi-image galleries, the add button is rendered as a floating action button (`Fab`) over the gallery card container (`bottom: 16`, `right: 16`, `zIndex: 3`) instead of occupying a grid slot tile. The button automatically hides when `maxItems` is reached.
+
+## Validation & Utilities (v1.2.2 - v1.2.5)
+
+```javascript
+import {
+  validateImageFile,
+  validateImageFileSync,
+  countGalleryImages,
+  utils
+} from '@mgonza02/goal-image-gallery';
+
+// Async validation (size, MIME type, min dimensions)
+const result = await validateImageFile(file, {
+  maxSize: 10 * 1024 * 1024,
+  allowedTypes: ['image/jpeg', 'image/png', 'image/webp'],
+  minWidth: 400,
+  minHeight: 400
+});
+if (!result.isValid) {
+  console.error(result.errors);
+}
+
+// Synchronous validation (size & MIME type)
+const syncResult = validateImageFileSync(file, { maxSize: 5 * 1024 * 1024 });
+
+// Count actual images (excluding any '+' placeholders)
+const total = countGalleryImages(imageList);
+```
+
 ## Upload Methods
 
 ### 1. File Upload

package/README.md

@@ -45,6 +45,14 @@ import { GoalImageGallery } from '@mgonza02/goal-image-gallery';
 - **TypeScript Support**: Full type definitions included
 - **Hook-Based Architecture**: Reusable custom hooks for complex logic
 
+### ⚡ **Gallery Controls & Management (v1.2.2 - v1.2.5)**
+- **Floating Add Button**: Modern floating action button (`Fab`) over the gallery card rather than occupying a grid tile, automatically hidden when `maxItems` is reached.
+- **Default Image Highlighting**: Highlight primary/default image with a `Predeterminada` badge via `defaultImageCode`, and quick-set default star action via `onSetAsDefault` (for multi-image galleries with 2+ images).
+- **Item Limits & Delete Thresholds**: Enforce maximum images (`maxItems`), allow delete in both single and multi-image modes (`allowDelete`), and protect minimum remaining images (`minItems`).
+- **Image Dimension Validation**: Enforce minimum image width and height (`minImageWidth`, `minImageHeight`).
+- **Granular Lifecycle Callbacks**: Reactive hooks for individual lifecycle events: `onAdd`, `onUpdate`, and `onDelete`.
+- **Validation Utilities**: Exported `validateImageFile` (async with dimension check), `validateImageFileSync` (sync size & MIME check), and `countGalleryImages`.
+
 ### 📱 **Mobile-First Design**
 - **Touch Gestures**: Swipe, pinch-to-zoom, and tap interactions
 - **Responsive Breakpoints**: Optimized layouts for all devices

package/lib/GoalImageGallery.js

@@ -240,6 +240,9 @@ const GoalImageGallery = _ref => {
     minImageWidth,
     minImageHeight,
     defaultImageCode,
+    featuredFirst = false,
+    itemHeight = 200,
+    featuredItemHeight = 240,
     onSetAsDefault,
     onDelete,
     onUpdate,
@@ -417,7 +420,10 @@ const GoalImageGallery = _ref => {
       onDownloadImage: handleDownloadImage,
       canSetDefault: canSetDefault,
       canAdd: canAdd,
-      defaultImageCode: defaultImageCode
+      defaultImageCode: defaultImageCode,
+      featuredFirst: featuredFirst,
+      itemHeight: itemHeight,
+      featuredItemHeight: featuredItemHeight
     }), /*#__PURE__*/_jsx(ImageGalleryModal, {
       open: openImage !== null,
       imageUrl: openImage,
@@ -457,6 +463,9 @@ GoalImageGallery.propTypes = {
   minImageWidth: PropTypes.number,
   minImageHeight: PropTypes.number,
   defaultImageCode: PropTypes.string,
+  featuredFirst: PropTypes.bool,
+  itemHeight: PropTypes.number,
+  featuredItemHeight: PropTypes.number,
   onSetAsDefault: PropTypes.func,
   onDelete: PropTypes.func,
   onUpdate: PropTypes.func,

package/lib/components/ImageGalleryGrid.js

@@ -7,9 +7,41 @@ import ImageGalleryEmptyState from './ImageGalleryEmptyState';
 import { StyledImageGridContainer } from '../styles/styled-components';
 
 /**
- * Image grid component for displaying gallery images
+ * Helper to compute responsive grid column size for gallery items
  */
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const getItemGridSize = (index, totalCount, multiple, featuredFirst) => {
+  if (totalCount === 1 || featuredFirst && index === 0) {
+    return {
+      xs: 12,
+      sm: 12,
+      md: 12
+    };
+  }
+  if (totalCount === 2 && !featuredFirst) {
+    return {
+      xs: 12,
+      sm: 6,
+      md: 6
+    };
+  }
+  if (totalCount === 3 && !featuredFirst) {
+    return {
+      xs: 12,
+      sm: 4,
+      md: 4
+    };
+  }
+  return {
+    xs: 6,
+    sm: multiple ? 4 : 6,
+    md: multiple ? 3 : 4
+  };
+};
+
+/**
+ * Image grid component for displaying gallery images
+ */
 const ImageGalleryGrid = _ref => {
   let {
     imageList,
@@ -30,7 +62,10 @@ const ImageGalleryGrid = _ref => {
     onDownloadImage,
     canSetDefault = false,
     canAdd = false,
-    defaultImageCode
+    defaultImageCode,
+    featuredFirst = false,
+    itemHeight = 200,
+    featuredItemHeight = 240
   } = _ref;
   const theme = useTheme();
   if (imageList.length === 0) {
@@ -56,34 +91,35 @@ const ImageGalleryGrid = _ref => {
         children: /*#__PURE__*/_jsx(Grid, {
           container: true,
           spacing: 2,
-          children: imageList.map((image, index) => /*#__PURE__*/_jsx(Grid, {
-            size: {
-              xs: 6,
-              sm: multiple ? 4 : 6,
-              md: multiple ? 3 : 4
-            },
-            sx: {
-              position: 'relative'
-            },
-            children: /*#__PURE__*/_jsx(ImageGalleryItem, {
-              image: image,
-              index: index,
-              getImageUrl: getImageUrl,
-              noImageUrl: noImageUrl,
-              loading: loading,
-              updatable: updatable,
-              removable: removable,
-              allowDownload: allowDownload,
-              showImageInfo: showImageInfo,
-              onImageClick: onImageClick,
-              onImageSelect: onImageSelect,
-              onRemoveImage: onRemoveImage,
-              onSetAsDefault: onSetAsDefault,
-              onDownloadImage: onDownloadImage,
-              canSetDefault: canSetDefault,
-              isDefault: !!defaultImageCode && image.image_code === defaultImageCode
-            })
-          }, image.id))
+          children: imageList.map((image, index) => {
+            const isFeatured = imageList.length === 1 || featuredFirst && index === 0;
+            const height = isFeatured && featuredItemHeight ? featuredItemHeight : itemHeight;
+            return /*#__PURE__*/_jsx(Grid, {
+              size: getItemGridSize(index, imageList.length, multiple, featuredFirst),
+              sx: {
+                position: 'relative'
+              },
+              children: /*#__PURE__*/_jsx(ImageGalleryItem, {
+                image: image,
+                index: index,
+                getImageUrl: getImageUrl,
+                noImageUrl: noImageUrl,
+                loading: loading,
+                updatable: updatable,
+                removable: removable,
+                allowDownload: allowDownload,
+                showImageInfo: showImageInfo,
+                itemHeight: height,
+                onImageClick: onImageClick,
+                onImageSelect: onImageSelect,
+                onRemoveImage: onRemoveImage,
+                onSetAsDefault: onSetAsDefault,
+                onDownloadImage: onDownloadImage,
+                canSetDefault: canSetDefault,
+                isDefault: !!defaultImageCode && image.image_code === defaultImageCode
+              })
+            }, image.id);
+          })
         })
       })
     }), canAdd && /*#__PURE__*/_jsx(Tooltip, {
@@ -123,6 +159,9 @@ ImageGalleryGrid.propTypes = {
   onDownloadImage: PropTypes.func.isRequired,
   canSetDefault: PropTypes.bool,
   canAdd: PropTypes.bool,
-  defaultImageCode: PropTypes.string
+  defaultImageCode: PropTypes.string,
+  featuredFirst: PropTypes.bool,
+  itemHeight: PropTypes.number,
+  featuredItemHeight: PropTypes.number
 };
 export default ImageGalleryGrid;

package/lib/components/ImageGalleryItem.js

@@ -23,6 +23,7 @@ const ImageGalleryItem = _ref => {
     showImageInfo = false,
     canSetDefault = false,
     isDefault = false,
+    itemHeight = 200,
     onImageClick,
     onImageSelect,
     onRemoveImage,
@@ -36,7 +37,7 @@ const ImageGalleryItem = _ref => {
     return /*#__PURE__*/_jsx(Box, {
       sx: {
         ...getImageContainerStyles(theme),
-        height: 200,
+        height: itemHeight,
         display: 'flex',
         alignItems: 'center',
         justifyContent: 'center',
@@ -95,7 +96,7 @@ const ImageGalleryItem = _ref => {
     }), loading && /*#__PURE__*/_jsx(Skeleton, {
       variant: "rectangular",
       width: "100%",
-      height: 200,
+      height: itemHeight,
       animation: "wave"
     }), /*#__PURE__*/_jsx("img", {
       src: getImageUrl({
@@ -109,7 +110,7 @@ const ImageGalleryItem = _ref => {
       onError: e => handleImageError(e, noImageUrl),
       style: {
         width: '100%',
-        height: 200,
+        height: itemHeight,
         objectFit: 'cover',
         display: loading ? 'none' : 'block'
       }
@@ -203,6 +204,7 @@ ImageGalleryItem.propTypes = {
   showImageInfo: PropTypes.bool,
   canSetDefault: PropTypes.bool,
   isDefault: PropTypes.bool,
+  itemHeight: PropTypes.number,
   onImageClick: PropTypes.func.isRequired,
   onImageSelect: PropTypes.func.isRequired,
   onRemoveImage: PropTypes.func.isRequired,

package/lib/index.d.ts

@@ -35,6 +35,12 @@ export interface GoalImageGalleryProps {
   minImageHeight?: number;
   /** Image code marked as default (badge + star state) */
   defaultImageCode?: string;
+  /** When true, the first image uses all space (12 columns) as a featured hero image */
+  featuredFirst?: boolean;
+  /** Height in pixels of gallery image items (default: 200) */
+  itemHeight?: number;
+  /** Height in pixels of featured / single gallery image items (default: 240) */
+  featuredItemHeight?: number;
   /** Called when user sets an image as default (multi-image galleries with 2+ images) */
   onSetAsDefault?: (imageCode: string) => void;
   /** Called after a successful delete */

package/package.json

@@ -1,89 +1,92 @@
 {
-  "name": "@mgonza02/goal-image-gallery",
-  "version": "1.2.5",
-  "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",
-  "types": "lib/index.d.ts",
-  "keywords": [
-    "react",
-    "image-gallery",
-    "material-ui",
-    "component",
-    "upload",
-    "drag-drop",
-    "clipboard",
-    "modal",
-    "zoom",
-    "responsive"
-  ],
-  "author": "Goal Team",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/mgonza02/goal-image-gallery.git"
-  },
-  "homepage": "https://github.com/mgonza02/goal-image-gallery#readme",
-  "bugs": {
-    "url": "https://github.com/mgonza02/goal-image-gallery/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "files": [
-    "lib/",
-    "README.md",
-    "CHANGELOG.md",
-    "QUICK_REFERENCE.md",
-    "MIGRATION.md",
-    "IMPLEMENTATION_GUIDE.md",
-    "IMPLEMENTATION_SUMMARY.md",
-    "DOCUMENTATION_UPDATE_SUMMARY.md",
-    "PACKAGE_CLEANUP_SUMMARY.md",
-    "LICENSE"
-  ],
-  "peerDependencies": {
-    "@emotion/react": "^11.14.0",
-    "@emotion/styled": "^11.14.0",
-    "@mui/icons-material": "^9.0.0",
-    "@mui/material": "^9.0.0",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
-  },
-  "dependencies": {
-    "prop-types": "^15.8.0"
-  },
-  "devDependencies": {
-    "@babel/cli": "^7.20.0",
-    "@babel/core": "^7.20.0",
-    "@babel/preset-env": "^7.20.0",
-    "@babel/preset-react": "^7.18.0",
-    "prettier": "^3.4.2"
-  },
-  "browserslist": {
-    "production": [
-      ">0.2%",
-      "not dead",
-      "not op_mini all"
+    "name": "@mgonza02/goal-image-gallery",
+    "version": "1.2.6",
+    "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",
+    "types": "lib/index.d.ts",
+    "keywords": [
+        "react",
+        "image-gallery",
+        "material-ui",
+        "component",
+        "upload",
+        "drag-drop",
+        "clipboard",
+        "modal",
+        "zoom",
+        "responsive"
     ],
-    "development": [
-      "last 1 chrome version",
-      "last 1 firefox version",
-      "last 1 safari version"
-    ]
-  },
-  "engines": {
-    "node": ">=18.0.0",
-    "pnpm": ">=9.0.0"
-  },
-  "scripts": {
-    "build": "pnpm clean && pnpm build:js && pnpm build:types",
-    "build:js": "babel src --out-dir lib --copy-files --ignore '**/*.test.js'",
-    "build:types": "cp src/index.d.ts lib/index.d.ts",
-    "format": "prettier --write src/**/*.js",
-    "format:check": "prettier --check src/**/*.js",
-    "clean": "rm -rf lib",
-    "validate": "pnpm format:check",
-    "dev": "pnpm build -- --watch"
-  }
+    "author": "Goal Team",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/mgonza02/goal-image-gallery.git"
+    },
+    "homepage": "https://github.com/mgonza02/goal-image-gallery#readme",
+    "bugs": {
+        "url": "https://github.com/mgonza02/goal-image-gallery/issues"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "files": [
+        "lib/",
+        "README.md",
+        "CHANGELOG.md",
+        "QUICK_REFERENCE.md",
+        "MIGRATION.md",
+        "IMPLEMENTATION_GUIDE.md",
+        "IMPLEMENTATION_SUMMARY.md",
+        "DOCUMENTATION_UPDATE_SUMMARY.md",
+        "PACKAGE_CLEANUP_SUMMARY.md",
+        "LICENSE"
+    ],
+    "peerDependencies": {
+        "@emotion/react": "^11.14.0",
+        "@emotion/styled": "^11.14.0",
+        "@mui/icons-material": "^9.0.0",
+        "@mui/material": "^9.0.0",
+        "react": "^18.0.0",
+        "react-dom": "^18.0.0"
+    },
+    "dependencies": {
+        "prop-types": "^15.8.0"
+    },
+    "packageManager": "pnpm@10.33.2",
+    "scripts": {
+        "build": "pnpm clean && pnpm build:js && pnpm build:types",
+        "build:js": "babel src --out-dir lib --copy-files --ignore '**/*.test.js'",
+        "build:types": "cp src/index.d.ts lib/index.d.ts",
+        "prepublishOnly": "pnpm build",
+        "format": "prettier --write src/**/*.js",
+        "format:check": "prettier --check src/**/*.js",
+        "clean": "rm -rf lib",
+        "validate": "pnpm format:check",
+        "dev": "pnpm build -- --watch",
+        "prepack": "pnpm validate && pnpm build"
+    },
+    "devDependencies": {
+        "@babel/cli": "^7.20.0",
+        "@babel/core": "^7.20.0",
+        "@babel/preset-env": "^7.20.0",
+        "@babel/preset-react": "^7.18.0",
+        "prettier": "^3.4.2"
+    },
+    "browserslist": {
+        "production": [
+            ">0.2%",
+            "not dead",
+            "not op_mini all"
+        ],
+        "development": [
+            "last 1 chrome version",
+            "last 1 firefox version",
+            "last 1 safari version"
+        ]
+    },
+    "engines": {
+        "node": ">=18.0.0",
+        "pnpm": ">=9.0.0"
+    }
 }