@kushagradhawan/kookie-ui 0.1.14 → 0.1.16

package/src/components/image.tsx

@@ -8,6 +8,7 @@ import { extractProps } from '../helpers/extract-props.js';
 import { marginPropDefs } from '../props/margin.props.js';
 import { widthPropDefs } from '../props/width.props.js';
 import { heightPropDefs } from '../props/height.props.js';
+import { Skeleton } from './skeleton.js';
 
 import type { ComponentPropsWithout, RemovedProps } from '../helpers/component-props.js';
 import type { MarginProps } from '../props/margin.props.js';
@@ -18,6 +19,27 @@ import type { GetPropDefTypes } from '../props/prop-def.js';
 type ImageElement = React.ElementRef<'img'>;
 type ImageOwnProps = GetPropDefTypes<typeof imagePropDefs> & {
   loading?: 'eager' | 'lazy';
+  /**
+   * Placeholder image URL to show while the main image is loading.
+   * Can be a low-quality/blurred version of the main image.
+   */
+  placeholder?: string;
+  /**
+   * Shows a skeleton placeholder while loading instead of a blank space.
+   */
+  showSkeleton?: boolean;
+  /**
+   * Whether the image should fade in when loaded. Set to false for background images or when you want immediate visibility.
+   */
+  fadeIn?: boolean;
+  /**
+   * Callback fired when the image successfully loads.
+   */
+  onLoad?: (event: React.SyntheticEvent<HTMLImageElement>) => void;
+  /**
+   * Callback fired when the image fails to load.
+   */
+  onError?: (event: React.SyntheticEvent<HTMLImageElement>) => void;
 };
 
 interface ImageProps
@@ -28,13 +50,13 @@ interface ImageProps
     ImageOwnProps {
   /**
    * The alt attribute provides alternative information for an image if a user for some reason cannot view it.
-   * Required for accessibility when not using asChild.
+   * Required for accessibility when not using asChild. Use empty string for decorative images.
    */
-  alt?: string;
+  alt: string;
 }
 
 const Image = React.forwardRef<ImageElement, ImageProps>((props, forwardedRef) => {
-  const { variant = 'surface', fit: _fit = 'cover', children } = props;
+  const { variant = 'surface', children } = props;
   const {
     asChild,
     className,
@@ -43,16 +65,108 @@ const Image = React.forwardRef<ImageElement, ImageProps>((props, forwardedRef) =
     loading = 'lazy',
     alt,
     src,
+    placeholder,
+    showSkeleton = false,
+    fadeIn = true,
+    onLoad: userOnLoad,
+    onError: userOnError,
     children: _children, // Extract children to exclude from imgProps
     ...imgProps
   } = extractProps(props, imagePropDefs, marginPropDefs, widthPropDefs, heightPropDefs);
 
+  // Loading state management
+  const [imageLoaded, setImageLoaded] = React.useState(false);
+  const [imageError, setImageError] = React.useState(false);
+  const [showPlaceholder, setShowPlaceholder] = React.useState(!!placeholder);
+  
+  // Ref to check if image is already loaded (for cached images)
+  const imgRef = React.useRef<HTMLImageElement>(null);
+
+  // Handle image load - moved to top to avoid conditional hook call
+  const handleLoad = React.useCallback((event: React.SyntheticEvent<HTMLImageElement>) => {
+    setImageLoaded(true);
+    setImageError(false);
+    setShowPlaceholder(false);
+    userOnLoad?.(event);
+  }, [userOnLoad]);
+
+  // Handle image error - moved to top to avoid conditional hook call
+  const handleError = React.useCallback((event: React.SyntheticEvent<HTMLImageElement>) => {
+    setImageLoaded(false);
+    setImageError(true);
+    setShowPlaceholder(false);
+    userOnError?.(event);
+  }, [userOnError]);
+
+  // Check if image is already loaded (for cached images)
+  React.useEffect(() => {
+    const img = imgRef.current;
+    if (img && img.complete && img.naturalWidth > 0) {
+      setImageLoaded(true);
+      setImageError(false);
+      setShowPlaceholder(false);
+    }
+  }, [src]);
+
+  // Validate required props
+  if (!src) {
+    console.warn('Image component: src prop is required');
+    return null;
+  }
+
+  if (!asChild && alt === undefined) {
+    console.warn('Image component: alt prop is required for accessibility when not using asChild');
+  }
+
+  // Create skeleton placeholder
+  const skeletonElement = showSkeleton && !imageLoaded && !imageError ? (
+    <Skeleton
+      style={{
+        ...style,
+        width: '100%',
+        height: '100px', // Default height, can be overridden by style
+        borderRadius: radius ? `var(--radius-${radius})` : undefined,
+      }}
+      className={className}
+    />
+  ) : null;
+
+  // Create placeholder image element
+  const placeholderElement = placeholder && showPlaceholder ? (
+    <img
+      data-radius={radius}
+      style={{
+        ...style,
+        position: 'absolute',
+        top: 0,
+        left: 0,
+        width: '100%',
+        height: '100%',
+        filter: 'blur(4px)',
+        opacity: 0.7,
+        transition: 'opacity 0.3s ease-out',
+      }}
+      className={classNames(
+        'rt-reset',
+        'rt-Image',
+        'rt-Image--placeholder',
+        className,
+      )}
+      alt=""
+      src={placeholder}
+    />
+  ) : null;
+
   // Create the standard img element
   const imgElement = (
     <img
       data-radius={radius}
       loading={loading}
-      style={style}
+      style={{
+        ...style,
+        opacity: fadeIn ? (imageLoaded ? 1 : 0) : 1,
+        transition: fadeIn ? 'opacity 0.3s ease-out' : 'none',
+      }}
       className={classNames(
         'rt-reset',
         'rt-Image',
@@ -61,11 +175,29 @@ const Image = React.forwardRef<ImageElement, ImageProps>((props, forwardedRef) =
       )}
       alt={alt}
       src={src}
+      onLoad={handleLoad}
+      onError={handleError}
       {...imgProps}
-      ref={forwardedRef}
+      ref={(node) => {
+        imgRef.current = node;
+        if (typeof forwardedRef === 'function') {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          forwardedRef.current = node;
+        }
+      }}
     />
   );
 
+  // Wrapper for images with placeholders
+  const imageWithPlaceholder = (placeholder || showSkeleton) ? (
+    <div style={{ position: 'relative', display: 'inline-block' }}>
+      {skeletonElement}
+      {placeholderElement}
+      {imgElement}
+    </div>
+  ) : imgElement;
+
   // Handle asChild - inject img into the child element
   if (asChild && children) {
     const child = React.Children.only(children) as React.ReactElement<any>;
@@ -113,12 +245,27 @@ const Image = React.forwardRef<ImageElement, ImageProps>((props, forwardedRef) =
             <img
               data-radius={radius}
               loading={loading}
-              style={{ ...style, position: 'relative', zIndex: 1 }}
+              style={{ 
+                ...style, 
+                position: 'relative', 
+                zIndex: 1,
+                opacity: fadeIn ? (imageLoaded ? 1 : 0) : 1,
+                transition: fadeIn ? 'opacity 0.3s ease-out' : 'none',
+              }}
               className={classNames('rt-reset', 'rt-Image', 'rt-Image--blur', className)}
               alt={alt}
               src={src}
+              onLoad={handleLoad}
+              onError={handleError}
               {...imgProps}
-              ref={forwardedRef}
+              ref={(node) => {
+                imgRef.current = node;
+                if (typeof forwardedRef === 'function') {
+                  forwardedRef(node);
+                } else if (forwardedRef) {
+                  forwardedRef.current = node;
+                }
+              }}
             />
           </>
         ),
@@ -137,7 +284,7 @@ const Image = React.forwardRef<ImageElement, ImageProps>((props, forwardedRef) =
           cursor: 'pointer', // Ensure interactive cursor
           ...child.props?.style, // Allow user overrides
         },
-        children: imgElement,
+        children: imageWithPlaceholder,
       });
     }
   }
@@ -171,18 +318,33 @@ const Image = React.forwardRef<ImageElement, ImageProps>((props, forwardedRef) =
         <img
           data-radius={radius}
           loading={loading}
-          style={{ ...style, position: 'relative', zIndex: 1 }}
+          style={{ 
+            ...style, 
+            position: 'relative', 
+            zIndex: 1,
+            opacity: fadeIn ? (imageLoaded ? 1 : 0) : 1,
+            transition: fadeIn ? 'opacity 0.3s ease-out' : 'none',
+          }}
           className={classNames('rt-reset', 'rt-Image', 'rt-Image--blur', className)}
           alt={alt}
           src={src}
+          onLoad={handleLoad}
+          onError={handleError}
           {...imgProps}
-          ref={forwardedRef}
+          ref={(node) => {
+            imgRef.current = node;
+            if (typeof forwardedRef === 'function') {
+              forwardedRef(node);
+            } else if (forwardedRef) {
+              forwardedRef.current = node;
+            }
+          }}
         />
       </div>
     );
   }
 
-  return imgElement;
+  return imageWithPlaceholder;
 });
 
 Image.displayName = 'Image';