@shohojdhara/atomix 0.1.16 → 0.1.17

package/src/components/PhotoViewer/README.md

@@ -1,358 +0,0 @@
-# PhotoViewer Component - Refactoring Documentation
-
-## Overview
-
-The PhotoViewer component has been comprehensively refactored to follow Atomix design system guidelines. This document outlines the changes made, the new structure, and how to use the component.
-
-## What Was Refactored
-
-### 1. Component Structure
-- **Before**: Single large file with inline sub-components
-- **After**: Modular structure with separate files for each sub-component
-
-### 2. File Organization
-```
-src/components/PhotoViewer/
-├── PhotoViewer.tsx              # Main component
-├── PhotoViewerHeader.tsx        # Header with controls
-├── PhotoViewerNavigation.tsx    # Navigation buttons
-├── PhotoViewerImage.tsx         # Image display with gestures
-├── PhotoViewerThumbnails.tsx    # Thumbnail navigation
-├── PhotoViewerInfo.tsx          # Image metadata panel
-├── PhotoViewer.stories.tsx      # Storybook examples
-├── index.ts                     # Component exports
-├── examples/                    # Usage examples
-│   ├── ImageGallery.tsx
-│   └── SimpleGallery.tsx
-└── scripts/                     # Vanilla JS implementation
-    ├── index.ts                 # Main PhotoViewer class
-    ├── PhotoViewerInteractions.ts # Event handlers & utilities
-    └── bundle.ts                # Global registration
-```
-
-### 3. New Features
-- **Body Class Toggle**: Adds `is-open-photoviewer` class to body element when PhotoViewer is open
-- **Per-Image State Management**: Each image maintains its own zoom, rotation, and position state
-- **Smart Dragging Limits**: Dragging is constrained to image boundaries based on zoom level and rotation
-- **Enhanced Touch Gestures**: Improved pinch-to-zoom and pan gestures for mobile devices
-- **Smooth Transitions**: Enhanced animations for image navigation and state changes
-- **Smart Zoom Levels**: Intelligent zoom presets (1x, 2x, 4x) with double-click support
-
-### 4. Type Definitions
-- **ImageType** interface moved to `src/lib/types/components.ts`
-- All component props properly documented with JSDoc
-- Comprehensive TypeScript support
-
-### 4. Vanilla JS Implementation
-- Complete rewrite of the vanilla JS version
-- Full feature parity with React component
-- Proper event handling and lifecycle management
-- Global API registration under `window.Atomix.PhotoViewer`
-
-### 5. Hook Improvements
-- Added missing `imageRef` to `usePhotoViewer` hook
-- Better TypeScript types
-- Enhanced gesture handling
-- Fixed infinite re-render issues
-- Added comprehensive null safety checks
-- Improved performance with optimized dependencies
-
-### 6. Error Handling & Stability
-- **Null Safety**: Comprehensive checks for DOM element availability
-- **Mount State Tracking**: Prevents premature calculations
-- **Graceful Degradation**: Fallbacks for missing image dimensions
-- **Error Boundaries**: Try-catch blocks for critical operations
-- **Performance Guards**: Prevents unnecessary re-renders
-
-## Component Features
-
-## Core Features
-- ✅ Image navigation with keyboard support
-- ✅ Zoom and pan functionality with edge constraints
-- ✅ Touch gestures for mobile devices
-- ✅ Fullscreen mode
-- ✅ Image rotation
-- ✅ Download and share capabilities
-- ✅ Thumbnail navigation
-- ✅ Image metadata display
-- ✅ Responsive design
-- ✅ Accessibility support (ARIA, keyboard navigation)
-- ✅ Body class toggle for styling (`is-open-photoviewer` class)
-- ✅ Per-image state persistence (zoom, pan, rotation)
-- ✅ Smart boundary detection and constraint enforcement
-- ✅ Smooth transitions and animations
-- ✅ Error handling and null safety
-- ✅ Per-image state persistence (zoom, rotation, position)
-- ✅ Smart dragging boundaries
-- ✅ Enhanced gesture recognition
-- ✅ Smooth image transitions
-- ✅ Intelligent zoom controls
-
-### New Capabilities
-- **Enhanced Type Safety**: All components properly typed
-- **Modular Architecture**: Each sub-component can be used independently
-- **Vanilla JS API**: Complete JavaScript implementation for non-React projects
-- **Improved Performance**: Better event handling and optimizations
-- **Better Error Handling**: Graceful handling of edge cases and null safety
-- **Per-Image State Management**: Individual zoom, pan, and rotation states preserved
-- **Advanced Boundary System**: Dynamic edge constraints based on zoom/rotation
-- **Smooth UX**: Professional-grade animations and transitions
-- **Mobile Excellence**: Native-like touch interactions and gestures
-- **Per-Image State Management**: Each image remembers its zoom, rotation, and position
-- **Smart Boundary Detection**: Dragging is intelligently constrained to image edges
-- **Enhanced Mobile Experience**: Improved touch gestures and responsive design
-- **Smooth Animations**: Fluid transitions between images and states
-- **Advanced UX Features**: Per-image state, smart boundaries, enhanced gestures
-- **Mobile-First Design**: Optimized touch interactions and responsive behavior
-
-## Usage Examples
-
-### React Component
-
-```tsx
-import { PhotoViewer } from '@/components/PhotoViewer';
-
-const images = [
-  {
-    src: 'https://example.com/image1.jpg',
-    alt: 'Image 1',
-    title: 'Beautiful Landscape',
-    description: 'A stunning mountain landscape',
-    tags: ['nature', 'mountains']
-  },
-  'https://example.com/image2.jpg' // Simple string format also supported
-];
-
-function MyComponent() {
-  return (
-    <PhotoViewer
-      images={images}
-      startIndex={0}
-      enableKeyboardNavigation={true}
-      enableGestures={true}
-      enableFullscreen={true}
-      thumbnailPosition="bottom"
-      onImageChange={(index) => console.log('Changed to image:', index)}
-      onClose={() => console.log('Viewer closed')}
-    />
-  );
-}
-
-// Note: When PhotoViewer is open, an 'is-open-photoviewer' class
-// is automatically added to the body element for styling purposes
-```
-
-### Vanilla JavaScript
-
-```javascript
-// Initialize from data attributes
-const viewers = Atomix.PhotoViewer.init();
-
-// Create programmatically
-const viewer = new Atomix.PhotoViewer.create(document.getElementById('viewer'), {
-  images: [
-    { src: 'image1.jpg', title: 'Image 1' },
-    { src: 'image2.jpg', title: 'Image 2' }
-  ],
-  startIndex: 0,
-  enableKeyboardNavigation: true
-});
-
-// Open viewer programmatically
-Atomix.PhotoViewer.open([
-  'image1.jpg',
-  'image2.jpg'
-], { startIndex: 1 });
-
-// Setup gallery
-Atomix.PhotoViewer.setupGallery('.gallery', 'img');
-```
-
-### HTML Data Attributes
-
-```html
-<div data-photoviewer 
-     data-images='[{"src":"image1.jpg","title":"Image 1"},{"src":"image2.jpg","title":"Image 2"}]'
-     data-start-index="0"
-     data-enable-keyboard-navigation="true">
-  <!-- Content will be replaced by PhotoViewer -->
-</div>
-```
-
-## API Reference
-
-### React Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `images` | `(string \| ImageType)[]` | `[]` | Array of image URLs or objects |
-| `startIndex` | `number` | `0` | Initial image index |
-| `className` | `string` | `''` | Additional CSS classes |
-| `disabled` | `boolean` | `false` | Disable all interactions |
-| `enableKeyboardNavigation` | `boolean` | `true` | Enable arrow key navigation |
-| `enableGestures` | `boolean` | `true` | Enable touch gestures |
-| `enableFullscreen` | `boolean` | `true` | Enable fullscreen mode |
-| `thumbnailPosition` | `'bottom' \| 'top' \| 'left' \| 'right' \| 'none'` | `'bottom'` | Thumbnail position |
-| `onImageChange` | `(index: number) => void` | - | Image change callback |
-| `onClose` | `() => void` | - | Close callback |
-
-### Vanilla JS API
-
-| Method | Description |
-|--------|-------------|
-| `Atomix.PhotoViewer.create(element, options)` | Create new instance |
-| `Atomix.PhotoViewer.init()` | Initialize from data attributes |
-| `Atomix.PhotoViewer.get(element)` | Get existing instance |
-| `Atomix.PhotoViewer.open(images, options)` | Open viewer programmatically |
-| `Atomix.PhotoViewer.setupGallery(selector)` | Setup gallery click handlers |
-| `Atomix.PhotoViewer.disposeAll()` | Dispose all instances |
-
-### ImageType Interface
-
-```typescript
-interface ImageType {
-  src: string;
-  alt?: string;
-  thumbnail?: string;
-  title?: string;
-  description?: string;
-  date?: string;
-  author?: string;
-  tags?: string[];
-}
-```
-
-### Accessibility Features
-
-- **ARIA Support**: Proper roles and labels
-- **Keyboard Navigation**: Arrow keys, Escape, Tab navigation
-- **Screen Reader**: Descriptive alt text and announcements
-- **Focus Management**: Proper focus handling in modal state
-- **High Contrast**: Works with high contrast modes
-- **Reduced Motion**: Respects `prefers-reduced-motion`
-
-## Browser Support
-
-- **Modern Browsers**: Chrome 80+, Firefox 74+, Safari 13+, Edge 80+
-- **Mobile**: iOS Safari 13+, Chrome Mobile 80+
-- **Touch Gestures**: Full support on touch devices
-- **Fullscreen API**: Where supported by browser
-
-## Performance Optimizations
-
-- **Lazy Loading**: Thumbnails loaded on demand
-- **Event Delegation**: Efficient event handling
-- **Memory Management**: Proper cleanup on destroy
-- **Image Preloading**: Smart preloading of adjacent images
-- **CSS Optimizations**: Hardware acceleration for smooth animations
-
-## Migration Guide
-
-### From Previous Version
-
-1. **Import Changes**:
-   ```tsx
-   // Old
-   import { PhotoViewer, ImageType } from './PhotoViewer';
-   
-   // New
-   import { PhotoViewer, ImageType } from './PhotoViewer';
-   // ImageType now imported from types
-   import { ImageType } from '../../lib/types/components';
-   ```
-
-2. **No Breaking Changes**: All existing props and functionality preserved
-
-3. **New Features**: Additional capabilities available without migration
-
-### Vanilla JS Migration
-
-If migrating from a custom implementation:
-
-1. Replace custom initialization with `Atomix.PhotoViewer.init()`
-2. Use data attributes for configuration
-3. Leverage built-in gallery setup with `setupGallery()`
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Navigator.share not available**: Gracefully handled, button hidden when unsupported
-2. **Touch events**: Properly handles passive/active listeners
-3. **Fullscreen API**: Falls back gracefully when not supported
-4. **Image loading errors**: Shows placeholder and continues to work
-5. **Body styling**: Uses `is-open-photoviewer` class on body element for additional styling
-6. **getBoundingClientRect errors**: Fixed with comprehensive null checks and mount state tracking
-7. **Infinite re-renders**: Resolved with optimized useEffect dependencies
-8. **Performance issues**: Mitigated with proper state management and bounds calculation
-
-### Fixed Issues (v1.1.0)
-
-- ✅ **Fixed**: `Cannot read properties of null (reading 'getBoundingClientRect')` error
-- ✅ **Fixed**: Maximum update depth exceeded warnings
-- ✅ **Fixed**: Infinite re-render loops in usePhotoViewer hook
-- ✅ **Fixed**: Memory leaks from improper cleanup
-- ✅ **Fixed**: Race conditions with DOM element initialization
-- ✅ **Fixed**: Touch gesture conflicts with browser behaviors
-
-### CSS Styling Hook
-
-```css
-/* Example of using the body class to style other elements when PhotoViewer is open */
-body.is-open-photoviewer .site-header {
-  z-index: 0; /* Lower z-index when PhotoViewer is open */
-}
-
-body.is-open-photoviewer {
-  overflow: hidden; /* Prevent background scrolling */
-}
-```
-
-### Debug Mode
-
-```javascript
-// Enable debug logging
-window.Atomix.PhotoViewer.debug = true;
-```
-
-## Recent Updates (v1.1.0)
-
-### 🐛 Bug Fixes
-- Fixed critical `getBoundingClientRect` null reference errors
-- Resolved infinite re-render issues in React hook
-- Added comprehensive null safety checks throughout
-- Improved DOM element initialization handling
-- Fixed memory leaks and performance issues
-
-### 🚀 Performance Improvements
-- Optimized useEffect dependencies to prevent unnecessary re-renders
-- Added mount state tracking for better initialization
-- Improved bounds calculation efficiency
-- Enhanced error handling with try-catch blocks
-- Better state management for per-image persistence
-
-### ✨ UX Enhancements
-- Smoother image transitions with loading states
-- Enhanced touch gesture recognition
-- Better boundary constraint system
-- Improved mobile experience
-- Professional-grade animations and easing
-
-## Future Enhancements
-
-- **Virtual Scrolling**: For large image sets
-- **Image Comparison**: Side-by-side comparison mode
-- **Video Support**: Extend to support video files
-- **Advanced Filters**: Built-in image filters
-- **Cloud Integration**: Direct integration with cloud storage APIs
-- **AI Features**: Smart cropping and enhancement suggestions
-
-## Contributing
-
-When contributing to PhotoViewer:
-
-1. Follow Atomix component guidelines
-2. Maintain feature parity between React and Vanilla JS versions
-3. Add comprehensive tests for new features
-4. Update documentation and examples
-5. Ensure accessibility compliance

package/src/components/PhotoViewer/examples/ImageGallery.tsx

@@ -1,200 +0,0 @@
-import React, { useState } from 'react';
-import { fn } from '@storybook/test';
-import { MasonryGridItem } from '../../../layouts/MasonryGrid/MasonryGridItem';
-import { MasonryGrid } from '../../../layouts/MasonryGrid/MasonryGrid';
-import { PhotoViewer } from '../PhotoViewer';
-import { Card } from '../../Card/Card';
-
-// Define the image gallery item type
-export interface GalleryImage {
-  id: number;
-  title: string;
-  description: string;
-  url: string;
-  width: number;
-  height: number;
-}
-
-// Create sample gallery data with different aspect ratios
-const galleryImages: GalleryImage[] = [
-  {
-    id: 1,
-    title: 'Mountain Landscape',
-    description: 'Beautiful mountain landscape with a lake view',
-    url: 'https://picsum.photos/id/10/800/600',
-    width: 800,
-    height: 600
-  },
-  {
-    id: 2,
-    title: 'Beach Sunset',
-    description: 'Stunning sunset over the ocean',
-    url: 'https://picsum.photos/id/11/800/1000',
-    width: 800,
-    height: 1000
-  },
-  {
-    id: 3,
-    title: 'Forest Path',
-    description: 'A serene path through a dense forest',
-    url: 'https://picsum.photos/id/12/800/500',
-    width: 800,
-    height: 500
-  },
-  {
-    id: 4,
-    title: 'City Skyline',
-    description: 'Urban skyline with modern architecture',
-    url: 'https://picsum.photos/id/13/800/800',
-    width: 800,
-    height: 800
-  },
-  {
-    id: 5,
-    title: 'Abstract Art',
-    description: 'Colorful abstract painting with geometric shapes',
-    url: 'https://picsum.photos/id/14/800/600',
-    width: 800,
-    height: 600
-  },
-  {
-    id: 6,
-    title: 'Wildlife',
-    description: 'Wild animals in their natural habitat',
-    url: 'https://picsum.photos/id/15/800/1200',
-    width: 800,
-    height: 1200
-  },
-  {
-    id: 7,
-    title: 'Architecture',
-    description: 'Impressive architectural details of a historic building',
-    url: 'https://picsum.photos/id/16/800/600',
-    width: 800,
-    height: 600
-  },
-  {
-    id: 8,
-    title: 'Food Photography',
-    description: 'Delicious culinary creation beautifully presented',
-    url: 'https://picsum.photos/id/17/800/700',
-    width: 800,
-    height: 700
-  },
-  {
-    id: 9,
-    title: 'Portrait',
-    description: 'Expressive portrait capturing human emotion',
-    url: 'https://picsum.photos/id/18/800/1000',
-    width: 800,
-    height: 1000
-  },
-  {
-    id: 10,
-    title: 'Nature Closeup',
-    description: 'Macro photography revealing intricate natural details',
-    url: 'https://picsum.photos/id/19/800/600',
-    width: 800,
-    height: 600
-  },
-  {
-    id: 11,
-    title: 'Travel Destination',
-    description: 'Iconic landmark from a popular travel destination',
-    url: 'https://picsum.photos/id/20/800/900',
-    width: 800,
-    height: 900
-  },
-  {
-    id: 12,
-    title: 'Minimalist Scene',
-    description: 'Clean, minimalist composition with simple elements',
-    url: 'https://picsum.photos/id/21/800/600',
-    width: 800,
-    height: 600
-  }
-];
-
-export const ImageGallery: React.FC = () => {
-  // State to track which images are selected for the PhotoViewer
-  const [selectedImageIndex, setSelectedImageIndex] = useState(0);
-  const [showPhotoViewer, setShowPhotoViewer] = useState(false);
-  
-  // Create enhanced image objects for the PhotoViewer
-  const enhancedImages = galleryImages.map(image => ({
-    src: image.url,
-    alt: image.title,
-    title: image.title,
-    description: image.description,
-    tags: [`${image.width}x${image.height}`]
-  }));
-  
-  // Handle clicking on a gallery item
-  const handleImageClick = (index: number) => {
-    setSelectedImageIndex(index);
-    setShowPhotoViewer(true);
-  };
-  
-  // Handle closing the PhotoViewer
-  const handlePhotoViewerClose = () => {
-    setShowPhotoViewer(false);
-  };
-  
-  // Create spy function for image change handler
-  const handleImageChange = fn((index: number) => {
-    setSelectedImageIndex(index);
-  });
-  
-  return (
-    <div className="c-image-gallery">
-      <h2 className="c-image-gallery__title">Image Gallery</h2>
-      <p className="c-image-gallery__description">
-        Click on any image to view it in the PhotoViewer. Navigate through the gallery using the arrow buttons or thumbnails.
-      </p>
-      
-      {/* MasonryGrid for the image gallery */}
-      <MasonryGrid 
-        xs={1} 
-        sm={2} 
-        md={3} 
-        lg={4} 
-        gap={16}
-        animate={true}
-        imagesLoaded={true}
-      >
-        {galleryImages.map((image, index) => (
-          <MasonryGridItem key={image.id}>
-            <div 
-              className="c-image-gallery__item"
-              onClick={() => handleImageClick(index)}
-            >
-              <Card
-                image={image.url}
-                imageAlt={image.title}
-                title={image.title}
-                text={image.description}
-                className="c-image-gallery__card"
-              />
-            </div>
-          </MasonryGridItem>
-        ))}
-      </MasonryGrid>
-      
-      {/* PhotoViewer component */}
-      {showPhotoViewer && (
-        <PhotoViewer 
-          images={enhancedImages}
-          startIndex={selectedImageIndex}
-          onClose={handlePhotoViewerClose}
-          thumbnailPosition="bottom"
-          enableFullscreen={true}
-          enableGestures={true}
-          enableKeyboardNavigation={true}
-          onImageChange={handleImageChange}
-        />
-      )}
-    </div>
-  );
-};
-
-export default ImageGallery;

package/src/components/PhotoViewer/examples/SimpleGallery.tsx

@@ -1,71 +0,0 @@
-import React, { useState } from 'react';
-import { fn } from '@storybook/test';
-import { PhotoViewer } from '../PhotoViewer';
-
-const images = [
-  'https://picsum.photos/id/10/800/600',
-  'https://picsum.photos/id/11/800/1000',
-  'https://picsum.photos/id/12/800/500',
-  'https://picsum.photos/id/13/800/800',
-];
-
-export const SimpleGallery: React.FC = () => {
-  const [selectedIndex, setSelectedIndex] = useState(0);
-  const [showViewer, setShowViewer] = useState(false);
-  
-  const handleOpen = (index: number) => {
-    setSelectedIndex(index);
-    setShowViewer(true);
-  };
-  
-  const handleClose = () => {
-    setShowViewer(false);
-  };
-  
-  // Create spy functions for event handlers
-  const handleImageChange = fn((index: number) => {
-    setSelectedIndex(index);
-  });
-  
-  return (
-    <div style={{ padding: '20px' }}>
-      <h2 style={{ marginBottom: '20px' }}>Simple Gallery Example</h2>
-      <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fill, minmax(200px, 1fr))', gap: '16px' }}>
-        {images.map((src, index) => (
-          <div 
-            key={index}
-            onClick={() => handleOpen(index)}
-            style={{ 
-              cursor: 'pointer',
-              borderRadius: '8px',
-              overflow: 'hidden',
-              boxShadow: '0 4px 6px rgba(0,0,0,0.1)',
-              transition: 'transform 0.3s ease'
-            }}
-          >
-            <img 
-              src={src} 
-              alt={`Gallery image ${index + 1}`} 
-              style={{ width: '100%', height: 'auto', display: 'block' }}
-            />
-          </div>
-        ))}
-      </div>
-      
-      {showViewer && (
-        <PhotoViewer
-          images={images}
-          startIndex={selectedIndex}
-          onClose={handleClose}
-          thumbnailPosition="bottom"
-          enableFullscreen={true}
-          enableGestures={true}
-          enableKeyboardNavigation={true}
-          onImageChange={handleImageChange}
-        />
-      )}
-    </div>
-  );
-};
-
-export default SimpleGallery;

package/src/components/PhotoViewer/examples/index.ts

@@ -1,2 +0,0 @@
-export { ImageGallery } from './ImageGallery';
-export type { GalleryImage } from './ImageGallery';

package/src/components/PhotoViewer/index.ts

@@ -1,14 +0,0 @@
-export { PhotoViewer } from './PhotoViewer';
-export { default } from './PhotoViewer';
-export { PhotoViewerHeader } from './PhotoViewerHeader';
-export { PhotoViewerNavigation } from './PhotoViewerNavigation';
-export { PhotoViewerImage } from './PhotoViewerImage';
-export { PhotoViewerThumbnails } from './PhotoViewerThumbnails';
-export { PhotoViewerInfo } from './PhotoViewerInfo';
-
-export type { PhotoViewerProps, ImageType } from '../../lib/types/components';
-export type { PhotoViewerHeaderProps } from './PhotoViewerHeader';
-export type { PhotoViewerNavigationProps } from './PhotoViewerNavigation';
-export type { PhotoViewerImageProps } from './PhotoViewerImage';
-export type { PhotoViewerThumbnailsProps } from './PhotoViewerThumbnails';
-export type { PhotoViewerInfoProps } from './PhotoViewerInfo';