@mgonza02/goal-image-gallery 1.0.0

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

@@ -0,0 +1,252 @@
+import { useEffect, useState, useCallback } from 'react';
+
+/**
+ * Custom hook for managing image gallery state
+ */
+export const useImageGallery = _ref => {
+  let {
+    imageCodes,
+    multiple,
+    canEdit,
+    updatable,
+    imageHandlerApi,
+    ownerEntity,
+    currentCompany,
+    onRefresh,
+    showError
+  } = _ref;
+  const [openImage, setOpenImage] = useState(null);
+  const [selectedImageIndex, setSelectedImageIndex] = useState(0);
+  const [selectingImage, setSelectingImage] = useState(false);
+  const [imageList, setImageList] = useState([]);
+  const [selectedImage, setSelectedImage] = useState(null);
+  const [zoomLevel, setZoomLevel] = useState(1);
+  const [loading, setLoading] = useState(false);
+  const [removable, setRemovable] = useState(false);
+
+  // Process image codes into image list
+  useEffect(() => {
+    const splitedImages = Array.isArray(imageCodes) ? imageCodes : imageCodes?.split(/[\s,]+/);
+    let newList = [];
+    if (splitedImages) {
+      const list = splitedImages.map((image_code, index) => ({
+        id: index,
+        width: 1,
+        height: 1,
+        title: 'Goal Image',
+        image_code
+      }));
+      newList = [...list];
+    } else {
+      newList = [];
+    }
+    setRemovable(multiple && newList.length > 1);
+
+    // Add plus button for multiple mode
+    if (updatable && multiple) {
+      newList.push({
+        image_code: '+',
+        id: newList.length
+      });
+    }
+    setImageList(newList);
+  }, [imageCodes, canEdit, multiple, updatable]);
+
+  // Image handlers
+  const handleOpenImage = useCallback(function (imageUrl) {
+    let index = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 0;
+    setOpenImage(imageUrl);
+    setSelectedImageIndex(index);
+    setZoomLevel(1);
+  }, []);
+  const handleCloseImage = useCallback(() => {
+    setOpenImage(null);
+    setZoomLevel(1);
+  }, []);
+  const handleImageSelect = useCallback(image => {
+    setSelectedImage(image);
+    setSelectingImage(true);
+  }, []);
+  const handleCancel = useCallback(() => {
+    setSelectingImage(false);
+  }, []);
+  const handleRemoveImage = useCallback(async image => {
+    setLoading(true);
+    try {
+      const imagesToSave = imageList.reduce((acc, img) => {
+        if (img.image_code !== '+' && img.image_code !== image.image_code) {
+          acc.push(img.image_code);
+        }
+        return acc;
+      }, []);
+      const result = await imageHandlerApi({
+        ...ownerEntity,
+        companyId: currentCompany,
+        image_code: imagesToSave,
+        company_id: currentCompany
+      });
+      if (result.success) {
+        onRefresh?.(result);
+      } else {
+        showError(result.message);
+      }
+    } catch (error) {
+      showError(error.message || 'Error al eliminar la imagen');
+    } finally {
+      setLoading(false);
+    }
+  }, [ownerEntity, currentCompany, imageList, onRefresh, showError, imageHandlerApi]);
+  const handleAfterUpload = useCallback(async image => {
+    const currentImageCode = selectedImage?.image_code || '';
+    const imagesToSave = imageList.reduce((acc, img) => {
+      if (img.image_code !== '+') {
+        acc.push(img.image_code === currentImageCode ? image.code : img.image_code);
+      }
+      return acc;
+    }, []);
+    if (!currentImageCode) {
+      imagesToSave.push(image.code);
+    }
+    const result = await imageHandlerApi({
+      ...ownerEntity,
+      companyId: currentCompany,
+      image_code: imagesToSave,
+      company_id: currentCompany
+    });
+    if (result.success) {
+      setSelectingImage(false);
+      onRefresh?.(result);
+    } else {
+      showError(result.message);
+    }
+  }, [ownerEntity, currentCompany, imageList, selectedImage, imageHandlerApi, onRefresh, showError]);
+  return {
+    openImage,
+    selectedImageIndex,
+    selectingImage,
+    imageList,
+    selectedImage,
+    zoomLevel,
+    loading,
+    removable,
+    setZoomLevel,
+    handleOpenImage,
+    handleCloseImage,
+    handleImageSelect,
+    handleCancel,
+    handleRemoveImage,
+    handleAfterUpload
+  };
+};
+
+/**
+ * Custom hook for managing image zoom functionality
+ */
+export const useImageZoom = (getImageUrl, imageList) => {
+  const [zoomLevel, setZoomLevel] = useState(1);
+  const [selectedImageIndex, setSelectedImageIndex] = useState(0);
+  const handleZoomIn = useCallback(() => {
+    setZoomLevel(prev => Math.min(prev + 0.5, 3));
+  }, []);
+  const handleZoomOut = useCallback(() => {
+    setZoomLevel(prev => Math.max(prev - 0.5, 0.5));
+  }, []);
+  const handlePreviousImage = useCallback(() => {
+    const newIndex = selectedImageIndex > 0 ? selectedImageIndex - 1 : imageList.length - 1;
+    setSelectedImageIndex(newIndex);
+    setZoomLevel(1);
+    return getImageUrl({
+      imageCode: imageList[newIndex].image_code
+    });
+  }, [selectedImageIndex, imageList, getImageUrl]);
+  const handleNextImage = useCallback(() => {
+    const newIndex = selectedImageIndex < imageList.length - 1 ? selectedImageIndex + 1 : 0;
+    setSelectedImageIndex(newIndex);
+    setZoomLevel(1);
+    return getImageUrl({
+      imageCode: imageList[newIndex].image_code
+    });
+  }, [selectedImageIndex, imageList, getImageUrl]);
+  return {
+    zoomLevel,
+    selectedImageIndex,
+    setZoomLevel,
+    setSelectedImageIndex,
+    handleZoomIn,
+    handleZoomOut,
+    handlePreviousImage,
+    handleNextImage
+  };
+};
+
+/**
+ * Custom hook for clipboard functionality
+ */
+export const useClipboard = (updatable, selectingImage, onPasteImage) => {
+  const [clipboardSupported, setClipboardSupported] = useState(false);
+  useEffect(() => {
+    setClipboardSupported(navigator.clipboard);
+  }, []);
+  useEffect(() => {
+    const handlePaste = async event => {
+      if (!clipboardSupported || !updatable || selectingImage) return;
+      const items = event.clipboardData?.items;
+      if (!items) return;
+      for (let i = 0; i < items.length; i++) {
+        const item = items[i];
+        if (item.type.indexOf('image') !== -1) {
+          const file = item.getAsFile();
+          if (file) {
+            onPasteImage?.(file);
+          }
+        }
+      }
+    };
+    if (clipboardSupported && updatable) {
+      document.addEventListener('paste', handlePaste);
+      return () => document.removeEventListener('paste', handlePaste);
+    }
+  }, [clipboardSupported, updatable, selectingImage, onPasteImage]);
+  return {
+    clipboardSupported
+  };
+};
+
+/**
+ * Custom hook for keyboard navigation
+ */
+export const useKeyboardNavigation = (openImage, onPreviousImage, onNextImage, onCloseImage, onZoomIn, onZoomOut) => {
+  useEffect(() => {
+    const handleKeyDown = event => {
+      if (openImage !== null) {
+        switch (event.key) {
+          case 'ArrowLeft':
+            event.preventDefault();
+            onPreviousImage();
+            break;
+          case 'ArrowRight':
+            event.preventDefault();
+            onNextImage();
+            break;
+          case 'Escape':
+            event.preventDefault();
+            onCloseImage();
+            break;
+          case '+':
+          case '=':
+            event.preventDefault();
+            onZoomIn();
+            break;
+          case '-':
+            event.preventDefault();
+            onZoomOut();
+            break;
+          default:
+            break;
+        }
+      }
+    };
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [openImage, onPreviousImage, onNextImage, onCloseImage, onZoomIn, onZoomOut]);
+};

package/lib/index.d.ts

@@ -0,0 +1,187 @@
+import { ReactNode } from 'react';
+
+// Main component props
+export interface GoalImageGalleryProps {
+  canEdit?: boolean;
+  ownerEntity?: object;
+  imageHandlerApi?: (data: any) => Promise<any>;
+  afterUpload?: (result: any) => void;
+  imageCodes?: string | string[];
+  multiple?: boolean;
+  permission?: string;
+  emptyMessage?: string;
+  showImageInfo?: boolean;
+  allowDownload?: boolean;
+  getImageUrl?: (params: { imageCode: string; thumbMail?: boolean }) => string;
+  noImageUrl?: string;
+  showError?: (message: string) => void;
+  hasPermission?: (permission: string) => boolean;
+  currentCompany?: string;
+}
+
+// Image item interface
+export interface ImageItem {
+  id: number;
+  width: number;
+  height: number;
+  title: string;
+  image_code: string;
+}
+
+// Hook interfaces
+export interface UseImageGalleryOptions {
+  imageCodes?: string | string[];
+  multiple?: boolean;
+  canEdit?: boolean;
+  updatable?: boolean;
+  imageHandlerApi?: (data: any) => Promise<any>;
+  ownerEntity?: object;
+  currentCompany?: string;
+  onRefresh?: (result: any) => void;
+  showError?: (message: string) => void;
+}
+
+export interface UseImageGalleryReturn {
+  openImage: string | null;
+  selectedImageIndex: number;
+  selectingImage: boolean;
+  imageList: ImageItem[];
+  selectedImage: ImageItem | null;
+  zoomLevel: number;
+  loading: boolean;
+  removable: 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>;
+  handleAfterUpload: (image: any) => Promise<void>;
+}
+
+export interface UseImageZoomReturn {
+  zoomLevel: number;
+  selectedImageIndex: number;
+  setZoomLevel: (level: number) => void;
+  setSelectedImageIndex: (index: number) => void;
+  handleZoomIn: () => void;
+  handleZoomOut: () => void;
+  handlePreviousImage: () => string;
+  handleNextImage: () => string;
+}
+
+export interface UseClipboardReturn {
+  clipboardSupported: boolean;
+}
+
+// Component props interfaces
+export interface ImageGalleryGridProps {
+  imageList: ImageItem[];
+  emptyMessage: string;
+  multiple?: boolean;
+  updatable?: boolean;
+  removable?: boolean;
+  allowDownload?: boolean;
+  showImageInfo?: boolean;
+  loading?: boolean;
+  clipboardSupported?: boolean;
+  getImageUrl: (params: { imageCode: string; thumbMail?: boolean }) => string;
+  noImageUrl: string;
+  onImageClick: (imageUrl: string, index: number) => void;
+  onImageSelect: (image: ImageItem | null) => void;
+  onRemoveImage: (image: ImageItem) => void;
+  onDownloadImage: (imageCode: string) => void;
+}
+
+export interface ImageGalleryModalProps {
+  open: boolean;
+  imageUrl?: string | null;
+  imageList: ImageItem[];
+  selectedImageIndex: number;
+  zoomLevel: number;
+  noImageUrl: string;
+  onClose: () => void;
+  onZoomIn: () => void;
+  onZoomOut: () => void;
+  onPreviousImage: () => void;
+  onNextImage: () => void;
+}
+
+export interface ImageGalleryItemProps {
+  image: ImageItem;
+  index: number;
+  getImageUrl: (params: { imageCode: string; thumbMail?: boolean }) => string;
+  noImageUrl: string;
+  loading?: boolean;
+  updatable?: boolean;
+  removable?: boolean;
+  allowDownload?: boolean;
+  showImageInfo?: boolean;
+  onImageClick: (imageUrl: string, index: number) => void;
+  onImageSelect: (image: ImageItem) => void;
+  onRemoveImage: (image: ImageItem) => void;
+  onDownloadImage: (imageCode: string) => void;
+}
+
+export interface ImageGalleryEmptyStateProps {
+  emptyMessage: string;
+  updatable?: boolean;
+  clipboardSupported?: boolean;
+  onAddImage?: () => void;
+}
+
+// Utility function types
+export type HandleImageError = (e: Event, noImageUrl: string) => void;
+export type DownloadImage = (imageUrl: string, imageCode: string) => void;
+export type ProcessImageCodes = (imageCodes: string | string[]) => ImageItem[];
+export type GetGridColumns = (isMobile: boolean, isTablet: boolean, multiple: boolean) => number;
+export type IsValidImageFile = (file: File) => boolean;
+export type FormatFileSize = (bytes: number) => string;
+export type GenerateId = () => string;
+export type Debounce = (func: Function, wait: number) => Function;
+export type IsTouchDevice = () => boolean;
+export type GetImageDimensions = (url: string) => Promise<{ width: number; height: number }>;
+export type CreateImagePreview = (file: File) => Promise<string>;
+
+// Hook functions
+export declare function useImageGallery(options: UseImageGalleryOptions): UseImageGalleryReturn;
+export declare function useImageZoom(
+  getImageUrl: (params: { imageCode: string }) => string,
+  imageList: ImageItem[]
+): UseImageZoomReturn;
+export declare function useClipboard(
+  updatable: boolean,
+  selectingImage: boolean,
+  onPasteImage?: (file: File) => void
+): UseClipboardReturn;
+export declare function useKeyboardNavigation(
+  openImage: string | null,
+  onPreviousImage: () => void,
+  onNextImage: () => void,
+  onCloseImage: () => void,
+  onZoomIn: () => void,
+  onZoomOut: () => void
+): void;
+
+// Main component
+declare const GoalImageGallery: React.FC<GoalImageGalleryProps>;
+export default GoalImageGallery;
+
+// Sub-components
+export declare const ImageGalleryGrid: React.FC<ImageGalleryGridProps>;
+export declare const ImageGalleryModal: React.FC<ImageGalleryModalProps>;
+export declare const ImageGalleryItem: React.FC<ImageGalleryItemProps>;
+export declare const ImageGalleryEmptyState: React.FC<ImageGalleryEmptyStateProps>;
+
+// Utility functions
+export declare const handleImageError: HandleImageError;
+export declare const downloadImage: DownloadImage;
+export declare const processImageCodes: ProcessImageCodes;
+export declare const getGridColumns: GetGridColumns;
+export declare const isValidImageFile: IsValidImageFile;
+export declare const formatFileSize: FormatFileSize;
+export declare const generateId: GenerateId;
+export declare const debounce: Debounce;
+export declare const isTouchDevice: IsTouchDevice;
+export declare const getImageDimensions: GetImageDimensions;
+export declare const createImagePreview: CreateImagePreview;

package/lib/index.js

@@ -0,0 +1,148 @@
+// GoalImageGallery - Enhanced Image Gallery Component
+//
+// This is the main entry point for the GoalImageGallery component
+// and its related utilities and documentation.
+
+// Main component exports
+export { default as GoalImageGallery } from './GoalImageGallery';
+export { default } from './GoalImageGallery';
+
+// Subcomponent exports
+export { default as ImageGalleryGrid } from './components/ImageGalleryGrid';
+export { default as ImageGalleryModal } from './components/ImageGalleryModal';
+export { default as ImageGalleryItem } from './components/ImageGalleryItem';
+export { default as ImageGalleryEmptyState } from './components/ImageGalleryEmptyState';
+
+// Hook exports
+export { useImageGallery, useImageZoom, useClipboard, useKeyboardNavigation } from './hooks/use-image-gallery';
+
+// Style exports
+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';
+
+// Examples and documentation
+export { default as GoalImageGalleryExamples } from './examples';
+
+// Component features and capabilities
+export const FEATURES = {
+  UPLOAD_METHODS: {
+    FILE_UPLOAD: 'file',
+    CLIPBOARD_PASTE: 'clipboard',
+    URL_LOADING: 'url'
+  },
+  KEYBOARD_SHORTCUTS: {
+    NAVIGATE_LEFT: 'ArrowLeft',
+    NAVIGATE_RIGHT: 'ArrowRight',
+    ZOOM_IN: ['+', '='],
+    ZOOM_OUT: '-',
+    CLOSE: 'Escape',
+    PASTE: 'Ctrl+V'
+  },
+  SUPPORTED_FORMATS: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'],
+  BROWSER_SUPPORT: {
+    CHROME: 'full',
+    FIREFOX: 'full',
+    SAFARI: 'full',
+    EDGE: 'full',
+    IE11: 'limited'
+  }
+};
+
+// Utility functions
+export const utils = {
+  /**
+   * Convert image URLs to image codes
+   * @param {string} url - Image URL
+   * @returns {string} - Image code
+   */
+  getImageCodeFromUrl: url => {
+    return url.split('/').pop().split('.')[0];
+  },
+  /**
+   * Validate image file
+   * @param {File} file - Image file
+   * @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
+    };
+  },
+  /**
+   * Create image handler API wrapper
+   * @param {Function} uploadFunction - Upload function
+   * @returns {Function} - Wrapped handler
+   */
+  createImageHandler: uploadFunction => {
+    return async imageData => {
+      try {
+        const result = await uploadFunction(imageData);
+        return {
+          success: true,
+          data: result,
+          message: 'Upload successful'
+        };
+      } catch (error) {
+        return {
+          success: false,
+          message: error.message
+        };
+      }
+    };
+  },
+  /**
+   * Convert legacy photo format to image codes
+   * @param {Array} photos - Legacy photo array
+   * @returns {Array} - Image codes
+   */
+  convertPhotosToImageCodes: photos => {
+    return photos.map(photo => photo.image_code || photo.id || photo.src);
+  }
+};
+
+// Configuration constants
+export const CONFIG = {
+  DEFAULT_MAX_FILES: 10,
+  DEFAULT_MAX_FILE_SIZE: 5 * 1024 * 1024,
+  // 5MB
+  DEFAULT_UPLOAD_FOLDER: 'gallery',
+  DEFAULT_ZOOM_LEVELS: {
+    MIN: 0.5,
+    MAX: 3.0,
+    STEP: 0.5
+  },
+  DEFAULT_BREAKPOINTS: {
+    MOBILE: 'md',
+    TABLET: 'lg',
+    DESKTOP: 'xl'
+  }
+};
+
+// Export version info
+export const VERSION = '2.0.0';
+export const CHANGELOG = [{
+  version: '2.0.0',
+  date: '2024-01-01',
+  changes: ['Added multi-method upload support', 'Enhanced UI/UX with Material Design 3', 'Improved accessibility features', 'Added keyboard navigation', 'Mobile optimization', 'Comprehensive documentation']
+}, {
+  version: '1.0.0',
+  date: '2023-12-01',
+  changes: ['Initial release', 'Basic image gallery functionality', 'File upload support', 'Image viewer modal']
+}];