@delightui/components 0.1.105 → 0.1.107

package/docs/components/atoms/Image.md

@@ -0,0 +1,448 @@
+# Image
+
+A versatile image component that extends the standard HTML img element with enhanced features including fallback support, different fit options, loading states, and aspect ratio control. This component provides a robust solution for displaying images with proper error handling and responsive behavior.
+
+## Aliases
+
+- Image
+- Img
+- Picture
+
+## Props Breakdown
+
+**Extends:** `ImgHTMLAttributes<HTMLImageElement>`
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `src` | `string` | `undefined` | Yes | The URL of the image to display |
+| `alt` | `string` | `undefined` | Yes | Alternative text for accessibility |
+| `fallback` | `string` | `undefined` | No | The URL of the image to display if the image fails to load |
+| `fit` | `'Fit' \| 'Fill' \| 'Crop'` | `'Fit'` | No | The fit option for the image |
+| `onLoad` | `() => void` | `undefined` | No | Callback function when the image has loaded |
+| `onError` | `(error: SyntheticEvent<HTMLImageElement>) => void` | `undefined` | No | Callback function when an error occurs while loading the image |
+| `showLoading` | `boolean` | `false` | No | Flag to show a loading indicator for the image |
+| `className` | `string` | `undefined` | No | Additional class for styling |
+| `aspectRatio` | `string` | `natural aspect ratio` | No | The aspect ratio of the image |
+| `width` | `string \| number` | `undefined` | No | Width of the image |
+| `height` | `string \| number` | `undefined` | No | Height of the image |
+| `loading` | `'eager' \| 'lazy'` | `undefined` | No | Loading behavior of the image |
+| `decoding` | `'sync' \| 'async' \| 'auto'` | `undefined` | No | Decoding behavior of the image |
+
+Plus all standard HTML img attributes (crossOrigin, referrerPolicy, sizes, srcSet, useMap, etc.).
+
+## Examples
+
+### Basic Image
+
+```tsx
+import { Image } from '@delightui/components';
+
+function BasicImageExample() {
+  return (
+    <Image
+      src="https://via.placeholder.com/300x200"
+      alt="Placeholder image"
+    />
+  );
+}
+```
+
+### Image with Fallback
+
+```tsx
+import { Image } from '@delightui/components';
+
+function FallbackImageExample() {
+  return (
+    <Image
+      src="https://invalid-url.com/image.jpg"
+      alt="Failed image"
+      fallback="https://via.placeholder.com/300x200?text=Fallback"
+      onError={(error) => console.log('Image failed to load:', error)}
+    />
+  );
+}
+```
+
+### Different Fit Options
+
+```tsx
+import { Image } from '@delightui/components';
+
+function FitOptionsExample() {
+  const imageUrl = "https://via.placeholder.com/400x300";
+
+  return (
+    <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap' }}>
+      <div>
+        <h4>Fit (Default)</h4>
+        <div style={{ width: '200px', height: '150px', border: '1px solid #ccc' }}>
+          <Image
+            src={imageUrl}
+            alt="Fit example"
+            fit="Fit"
+          />
+        </div>
+      </div>
+
+      <div>
+        <h4>Fill</h4>
+        <div style={{ width: '200px', height: '150px', border: '1px solid #ccc' }}>
+          <Image
+            src={imageUrl}
+            alt="Fill example"
+            fit="Fill"
+          />
+        </div>
+      </div>
+
+      <div>
+        <h4>Crop</h4>
+        <div style={{ width: '200px', height: '150px', border: '1px solid #ccc' }}>
+          <Image
+            src={imageUrl}
+            alt="Crop example"
+            fit="Crop"
+          />
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### Aspect Ratio Control
+
+```tsx
+import { Image } from '@delightui/components';
+
+function AspectRatioExample() {
+  const imageUrl = "https://via.placeholder.com/400x300";
+
+  return (
+    <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap' }}>
+      <div>
+        <h4>16:9 Aspect Ratio</h4>
+        <Image
+          src={imageUrl}
+          alt="16:9 aspect ratio"
+          aspectRatio="16/9"
+          style={{ width: '300px' }}
+        />
+      </div>
+
+      <div>
+        <h4>1:1 Aspect Ratio</h4>
+        <Image
+          src={imageUrl}
+          alt="1:1 aspect ratio"
+          aspectRatio="1/1"
+          style={{ width: '200px' }}
+        />
+      </div>
+
+      <div>
+        <h4>4:3 Aspect Ratio</h4>
+        <Image
+          src={imageUrl}
+          alt="4:3 aspect ratio"
+          aspectRatio="4/3"
+          style={{ width: '240px' }}
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+### Loading States
+
+```tsx
+import { Image, Spinner } from '@delightui/components';
+
+function LoadingImageExample() {
+  const [isLoading, setIsLoading] = useState(true);
+
+  const handleLoad = () => {
+    setIsLoading(false);
+    console.log('Image loaded successfully');
+  };
+
+  const handleError = (error: any) => {
+    setIsLoading(false);
+    console.error('Image failed to load:', error);
+  };
+
+  return (
+    <div style={{ position: 'relative', width: '300px', height: '200px' }}>
+      {isLoading && (
+        <div style={{
+          position: 'absolute',
+          top: 0,
+          left: 0,
+          right: 0,
+          bottom: 0,
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          backgroundColor: '#f5f5f5'
+        }}>
+          <Spinner size="Medium" />
+        </div>
+      )}
+      
+      <Image
+        src="https://via.placeholder.com/300x200"
+        alt="Loading example"
+        onLoad={handleLoad}
+        onError={handleError}
+        showLoading={true}
+        style={{ opacity: isLoading ? 0 : 1, transition: 'opacity 0.3s' }}
+      />
+    </div>
+  );
+}
+```
+
+### Lazy Loading
+
+```tsx
+import { Image } from '@delightui/components';
+
+function LazyLoadingExample() {
+  const images = [
+    { id: 1, url: 'https://via.placeholder.com/300x200/FF0000/FFFFFF?text=Image+1' },
+    { id: 2, url: 'https://via.placeholder.com/300x200/00FF00/FFFFFF?text=Image+2' },
+    { id: 3, url: 'https://via.placeholder.com/300x200/0000FF/FFFFFF?text=Image+3' },
+    { id: 4, url: 'https://via.placeholder.com/300x200/FFFF00/000000?text=Image+4' },
+    { id: 5, url: 'https://via.placeholder.com/300x200/FF00FF/FFFFFF?text=Image+5' }
+  ];
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '100vh' }}>
+      {images.map((image) => (
+        <div key={image.id}>
+          <h3>Image {image.id}</h3>
+          <Image
+            src={image.url}
+            alt={`Lazy loaded image ${image.id}`}
+            loading="lazy"
+            onLoad={() => console.log(`Image ${image.id} loaded`)}
+          />
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Gallery Example
+
+```tsx
+import { Image } from '@delightui/components';
+
+function GalleryExample() {
+  const [selectedImage, setSelectedImage] = useState<string | null>(null);
+  
+  const images = [
+    'https://via.placeholder.com/300x200/FF6B6B/FFFFFF?text=Photo+1',
+    'https://via.placeholder.com/300x200/4ECDC4/FFFFFF?text=Photo+2',
+    'https://via.placeholder.com/300x200/45B7D1/FFFFFF?text=Photo+3',
+    'https://via.placeholder.com/300x200/96CEB4/FFFFFF?text=Photo+4',
+    'https://via.placeholder.com/300x200/FFEAA7/000000?text=Photo+5',
+    'https://via.placeholder.com/300x200/DDA0DD/FFFFFF?text=Photo+6'
+  ];
+
+  return (
+    <div>
+      <div style={{ 
+        display: 'grid', 
+        gridTemplateColumns: 'repeat(auto-fit, minmax(150px, 1fr))', 
+        gap: '16px',
+        marginBottom: '24px'
+      }}>
+        {images.map((src, index) => (
+          <Image
+            key={index}
+            src={src}
+            alt={`Gallery image ${index + 1}`}
+            fit="Crop"
+            aspectRatio="1/1"
+            style={{ cursor: 'pointer' }}
+            onClick={() => setSelectedImage(src)}
+          />
+        ))}
+      </div>
+
+      {selectedImage && (
+        <div style={{
+          position: 'fixed',
+          top: 0,
+          left: 0,
+          right: 0,
+          bottom: 0,
+          backgroundColor: 'rgba(0, 0, 0, 0.8)',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          zIndex: 1000
+        }} onClick={() => setSelectedImage(null)}>
+          <Image
+            src={selectedImage}
+            alt="Selected image"
+            style={{ maxWidth: '90%', maxHeight: '90%' }}
+          />
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Responsive Images
+
+```tsx
+import { Image } from '@delightui/components';
+
+function ResponsiveImageExample() {
+  return (
+    <div style={{ maxWidth: '800px' }}>
+      <h3>Responsive Image</h3>
+      <Image
+        src="https://via.placeholder.com/800x400"
+        alt="Responsive image"
+        style={{
+          width: '100%',
+          height: 'auto',
+          maxWidth: '100%'
+        }}
+      />
+
+      <h3>Fixed Aspect Ratio Responsive</h3>
+      <Image
+        src="https://via.placeholder.com/800x400"
+        alt="Fixed aspect ratio responsive"
+        aspectRatio="16/9"
+        fit="Crop"
+        style={{ width: '100%' }}
+      />
+    </div>
+  );
+}
+```
+
+### Error Handling
+
+```tsx
+import { Image, Text } from '@delightui/components';
+
+function ErrorHandlingExample() {
+  const [imageError, setImageError] = useState<string | null>(null);
+  const [imageLoaded, setImageLoaded] = useState(false);
+
+  const handleError = (error: any) => {
+    setImageError('Failed to load image');
+    console.error('Image error:', error);
+  };
+
+  const handleLoad = () => {
+    setImageLoaded(true);
+    setImageError(null);
+  };
+
+  return (
+    <div>
+      <Image
+        src="https://invalid-image-url.com/nonexistent.jpg"
+        alt="This will fail to load"
+        fallback="https://via.placeholder.com/300x200/FF0000/FFFFFF?text=Error+Fallback"
+        onError={handleError}
+        onLoad={handleLoad}
+      />
+      
+      {imageError && (
+        <Text color="error" style={{ marginTop: '8px' }}>
+          {imageError}
+        </Text>
+      )}
+      
+      {imageLoaded && (
+        <Text color="success" style={{ marginTop: '8px' }}>
+          Image loaded successfully!
+        </Text>
+      )}
+    </div>
+  );
+}
+```
+
+### Image with Custom Styling
+
+```tsx
+import { Image } from '@delightui/components';
+
+function CustomStyledImageExample() {
+  return (
+    <div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap' }}>
+      <Image
+        src="https://via.placeholder.com/200x200"
+        alt="Rounded image"
+        className="rounded-image"
+        style={{ borderRadius: '50%' }}
+      />
+
+      <Image
+        src="https://via.placeholder.com/200x200"
+        alt="Border image"
+        style={{ 
+          border: '4px solid #007bff',
+          borderRadius: '8px',
+          boxShadow: '0 4px 8px rgba(0,0,0,0.1)'
+        }}
+      />
+
+      <Image
+        src="https://via.placeholder.com/200x200"
+        alt="Grayscale image"
+        style={{ 
+          filter: 'grayscale(100%)',
+          transition: 'filter 0.3s ease'
+        }}
+        onMouseEnter={(e) => {
+          e.currentTarget.style.filter = 'grayscale(0%)';
+        }}
+        onMouseLeave={(e) => {
+          e.currentTarget.style.filter = 'grayscale(100%)';
+        }}
+      />
+    </div>
+  );
+}
+```
+
+### Performance Optimized
+
+```tsx
+import { Image } from '@delightui/components';
+
+function PerformanceOptimizedExample() {
+  return (
+    <div>
+      <h3>Optimized Image Loading</h3>
+      <Image
+        src="https://via.placeholder.com/800x600"
+        alt="High resolution image"
+        loading="lazy"
+        decoding="async"
+        width={400}
+        height={300}
+        style={{
+          objectFit: 'cover',
+          transition: 'transform 0.3s ease'
+        }}
+        onLoad={() => console.log('Image loaded and decoded')}
+      />
+    </div>
+  );
+}
+```