@usefragments/ui 1.0.0

package/src/components/Image/Image.contract.json

@@ -0,0 +1,209 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Image",
+  "description": "Responsive image component with aspect ratio control, loading states, and error fallbacks. Handles image display with consistent styling.",
+  "category": "display",
+  "tags": [
+    "image",
+    "media",
+    "photo",
+    "picture",
+    "visual"
+  ],
+  "status": "stable",
+  "sourcePath": "src/components/Image/index.tsx",
+  "exportName": "Image",
+  "propsSummary": [
+    "src: string (required)",
+    "alt: string (required)",
+    "aspectRatio: 1:1|4:3|16:9|21:9|auto (default: auto)",
+    "objectFit: cover|contain|fill|none (default: cover)",
+    "width: union",
+    "height: union",
+    "rounded: none|sm|md|lg|full (default: none)",
+    "fallback: node",
+    "className: string",
+    "style: object",
+    "imgProps: object",
+    "onImageLoad: function",
+    "onImageError: function"
+  ],
+  "props": {
+    "src": {
+      "type": "string",
+      "description": "Image source URL",
+      "required": true
+    },
+    "alt": {
+      "type": "string",
+      "description": "Alt text for accessibility (required)",
+      "required": true
+    },
+    "aspectRatio": {
+      "type": "enum",
+      "description": "Aspect ratio of the image container",
+      "default": "auto",
+      "required": false,
+      "values": [
+        "1:1",
+        "4:3",
+        "16:9",
+        "21:9",
+        "auto"
+      ]
+    },
+    "objectFit": {
+      "type": "enum",
+      "description": "How the image fits within its container",
+      "default": "cover",
+      "required": false,
+      "values": [
+        "cover",
+        "contain",
+        "fill",
+        "none"
+      ]
+    },
+    "width": {
+      "type": "union",
+      "description": "Width of the image container",
+      "required": false
+    },
+    "height": {
+      "type": "union",
+      "description": "Height of the image container",
+      "required": false
+    },
+    "rounded": {
+      "type": "enum",
+      "description": "Border radius",
+      "default": "none",
+      "required": false,
+      "values": [
+        "none",
+        "sm",
+        "md",
+        "lg",
+        "full"
+      ]
+    },
+    "fallback": {
+      "type": "node",
+      "description": "Content to show while loading or on error",
+      "required": false
+    },
+    "className": {
+      "type": "string",
+      "description": "Additional class name",
+      "required": false
+    },
+    "style": {
+      "type": "object",
+      "description": "Inline styles",
+      "required": false
+    },
+    "imgProps": {
+      "type": "object",
+      "description": "Additional props for the underlying img element (except src/alt/size/style/events)",
+      "required": false
+    },
+    "onImageLoad": {
+      "type": "function",
+      "description": "Called when the underlying img element loads",
+      "required": false
+    },
+    "onImageError": {
+      "type": "function",
+      "description": "Called when the underlying img element fails to load",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Displaying product images in cards or grids",
+      "Hero images with specific aspect ratios",
+      "User-uploaded content that may fail to load",
+      "Thumbnails in lists or galleries"
+    ],
+    "whenNot": [
+      "User avatars (use Avatar component)",
+      "Icons or symbols (use Icon component)",
+      "Background images (use CSS background-image)",
+      "SVG illustrations (use inline SVG or Image component)"
+    ],
+    "guidelines": [
+      "Always provide meaningful alt text for accessibility",
+      "Use appropriate aspect ratios for consistent layouts",
+      "Provide fallback content for failed loads",
+      "Use objectFit=\"contain\" for logos to preserve aspect ratio",
+      "Use imgProps / onImageLoad / onImageError when you need lower-level img control"
+    ],
+    "accessibility": [
+      "Alt text is required and must describe the image content",
+      "Decorative images should have empty alt=\"\"",
+      "Avoid text in images; if necessary, describe the text in alt",
+      "Ensure sufficient contrast between image and surrounding content"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Default",
+      "description": "Basic image display",
+      "code": "<Image\n  src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=400&h=300&fit=crop\"\n  alt=\"Code on a screen\"\n  width={300}\n/>"
+    },
+    {
+      "name": "Aspect Ratios",
+      "description": "Different aspect ratio options",
+      "code": "<div style={{ display: 'flex', gap: '16px', flexWrap: 'wrap' }}>\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=200&h=200&fit=crop\"\n    alt=\"Square image\"\n    aspectRatio=\"1:1\"\n    width={100}\n  />\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=200&h=150&fit=crop\"\n    alt=\"4:3 image\"\n    aspectRatio=\"4:3\"\n    width={120}\n  />\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=320&h=180&fit=crop\"\n    alt=\"16:9 image\"\n    aspectRatio=\"16:9\"\n    width={160}\n  />\n</div>"
+    },
+    {
+      "name": "Rounded Corners",
+      "description": "Border radius options",
+      "code": "<div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=100&h=100&fit=crop\"\n    alt=\"No rounding\"\n    rounded=\"none\"\n    width={80}\n    height={80}\n  />\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=100&h=100&fit=crop\"\n    alt=\"Medium rounding\"\n    rounded=\"md\"\n    width={80}\n    height={80}\n  />\n  <Image\n    src=\"https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=100&h=100&fit=crop\"\n    alt=\"Full rounding\"\n    rounded=\"full\"\n    width={80}\n    height={80}\n  />\n</div>"
+    },
+    {
+      "name": "With Fallback",
+      "description": "Fallback content for loading/error states",
+      "code": "<Image\n  src=\"https://invalid-url.example/image.jpg\"\n  alt=\"Image that will fail\"\n  width={200}\n  height={150}\n  rounded=\"md\"\n  fallback={\n    <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'center', height: '100%', background: 'var(--fui-color-surface-secondary)' }}>\n      <span style={{ color: 'var(--fui-color-text-tertiary)' }}>No image</span>\n    </div>\n  }\n/>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Card",
+      "relationship": "child",
+      "note": "Common pattern to use Image at top of product cards"
+    },
+    {
+      "component": "Avatar",
+      "relationship": "alternative",
+      "note": "Use Avatar for user profile pictures"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "src: string - image URL (required)",
+      "alt: string - accessibility text (required)",
+      "aspectRatio: 1:1|4:3|16:9|21:9|auto - container ratio",
+      "objectFit: cover|contain|fill|none - image fitting",
+      "rounded: none|sm|md|lg|full - border radius",
+      "fallback: ReactNode - loading/error content",
+      "imgProps/onImageLoad/onImageError - low-level img customization and events"
+    ],
+    "a11yRules": [
+      "A11Y_IMG_ALT",
+      "A11Y_IMG_DECORATIVE"
+    ]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": [
+      "Root"
+    ]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-03-13T23:18:59.379Z"
+  }
+}

package/src/components/Image/Image.module.scss

@@ -0,0 +1,77 @@
+@use '../../tokens/variables' as *;
+
+.imageContainer {
+  position: relative;
+  display: block;
+  overflow: hidden;
+  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+}
+
+.image {
+  display: block;
+  width: 100%;
+  height: 100%;
+  transition: opacity var(--fui-transition-normal, $fui-transition-normal);
+}
+
+// Object fit variants
+.fit-cover {
+  object-fit: cover;
+}
+
+.fit-contain {
+  object-fit: contain;
+}
+
+.fit-fill {
+  object-fit: fill;
+}
+
+.fit-none {
+  object-fit: none;
+}
+
+// Aspect ratio variants
+.aspect-1-1 {
+  aspect-ratio: 1 / 1;
+}
+
+.aspect-4-3 {
+  aspect-ratio: 4 / 3;
+}
+
+.aspect-16-9 {
+  aspect-ratio: 16 / 9;
+}
+
+.aspect-21-9 {
+  aspect-ratio: 21 / 9;
+}
+
+// Border radius variants
+.rounded-sm {
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+}
+
+.rounded-md {
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+}
+
+.rounded-lg {
+  border-radius: var(--fui-radius-lg, $fui-radius-lg);
+}
+
+.rounded-full {
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+}
+
+// Fallback
+.fallback {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+}

package/src/components/Image/Image.stories.tsx

@@ -0,0 +1,109 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Image } from '.';
+
+/**
+ * Image is a responsive image component with aspect-ratio control, loading
+ * states, and error fallbacks. The src and alt props are required; alt must
+ * describe the image content for accessibility.
+ */
+const SAMPLE_SRC =
+  'https://images.unsplash.com/photo-1555066931-4365d14bab8c?w=400&h=300&fit=crop';
+
+const meta = {
+  title: 'Display/Image',
+  component: Image,
+  tags: ['autodocs', 'canonical'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'Responsive image with aspect-ratio control, loading states, and error fallbacks.',
+      },
+    },
+  },
+  argTypes: {
+    aspectRatio: {
+      control: 'select',
+      options: ['1:1', '4:3', '16:9', '21:9', 'auto'],
+      description: 'Aspect ratio of the image container',
+    },
+    objectFit: {
+      control: 'select',
+      options: ['cover', 'contain', 'fill', 'none'],
+      description: 'How the image fits within its container',
+    },
+    rounded: {
+      control: 'select',
+      options: ['none', 'sm', 'md', 'lg', 'full'],
+      description: 'Border radius',
+    },
+  },
+  args: {
+    src: SAMPLE_SRC,
+    alt: 'Code on a screen',
+    width: 300,
+  },
+} satisfies Meta<typeof Image>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: { src: SAMPLE_SRC, alt: 'Code on a screen', width: 300 },
+};
+
+export const Square: Story = {
+  args: {
+    src: SAMPLE_SRC,
+    alt: 'Square crop',
+    aspectRatio: '1:1',
+    width: 200,
+  },
+};
+
+export const Widescreen: Story = {
+  args: {
+    src: SAMPLE_SRC,
+    alt: 'Widescreen crop',
+    aspectRatio: '16:9',
+    width: 320,
+    rounded: 'md',
+  },
+};
+
+export const Rounded: Story = {
+  args: {
+    src: SAMPLE_SRC,
+    alt: 'Rounded image',
+    aspectRatio: '1:1',
+    rounded: 'full',
+    width: 120,
+    height: 120,
+  },
+};
+
+export const WithFallback: Story = {
+  args: {
+    src: 'https://invalid-url.example/image.jpg',
+    alt: 'Image that will fail to load',
+    width: 200,
+    height: 150,
+    rounded: 'md',
+    fallback: (
+      <div
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          height: '100%',
+          background: 'var(--fui-color-surface-secondary, #f4f4f5)',
+        }}
+      >
+        <span style={{ color: 'var(--fui-color-text-tertiary, #71717a)' }}>
+          No image
+        </span>
+      </div>
+    ),
+  },
+};

package/src/components/Image/index.tsx

@@ -0,0 +1,128 @@
+'use client';
+
+import * as React from 'react';
+import styles from './Image.module.scss';
+
+export interface ImageProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+  /** Image source URL */
+  src: string;
+  /** Alt text for accessibility */
+  alt: string;
+  /** Aspect ratio of the image container */
+  aspectRatio?: '1:1' | '4:3' | '16:9' | '21:9' | 'auto';
+  /** How the image should fit within its container */
+  objectFit?: 'cover' | 'contain' | 'fill' | 'none';
+  /** Width of the image */
+  width?: string | number;
+  /** Height of the image */
+  height?: string | number;
+  /** Border radius */
+  rounded?: 'none' | 'sm' | 'md' | 'lg' | 'full';
+  /** Fallback content to show while loading or on error */
+  fallback?: React.ReactNode;
+  /** Additional class name */
+  className?: string;
+  /** Inline styles */
+  style?: React.CSSProperties;
+  /** Additional props for the underlying img element */
+  imgProps?: Omit<
+    React.ImgHTMLAttributes<HTMLImageElement>,
+    'src' | 'alt' | 'width' | 'height' | 'className' | 'style' | 'onLoad' | 'onError'
+  >;
+  /** Called when the image finishes loading */
+  onImageLoad?: React.ReactEventHandler<HTMLImageElement>;
+  /** Called when the image fails to load */
+  onImageError?: React.ReactEventHandler<HTMLImageElement>;
+}
+
+const ImageRoot = React.forwardRef<HTMLDivElement, ImageProps>(
+  function Image(
+    {
+      src,
+      alt,
+      aspectRatio = 'auto',
+      objectFit = 'cover',
+      width,
+      height,
+      rounded = 'none',
+      fallback,
+      className,
+      style,
+      imgProps,
+      onImageLoad,
+      onImageError,
+      ...htmlProps
+    },
+    ref
+  ) {
+    const imgRef = React.useRef<HTMLImageElement>(null);
+    const [status, setStatus] = React.useState<'loading' | 'loaded' | 'error'>('loading');
+
+    // Handle images that are already cached/loaded before hydration
+    React.useEffect(() => {
+      const img = imgRef.current;
+      if (img && img.complete) {
+        setStatus(img.naturalWidth > 0 ? 'loaded' : 'error');
+      }
+    }, [src]);
+
+    const handleLoad: React.ReactEventHandler<HTMLImageElement> = (event) => {
+      setStatus('loaded');
+      onImageLoad?.(event);
+    };
+    const handleError: React.ReactEventHandler<HTMLImageElement> = (event) => {
+      setStatus('error');
+      onImageError?.(event);
+    };
+
+    const classes = [
+      styles.imageContainer,
+      aspectRatio !== 'auto' && styles[`aspect-${aspectRatio.replace(':', '-')}`],
+      rounded !== 'none' && styles[`rounded-${rounded}`],
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    const imgClasses = [
+      styles.image,
+      styles[`fit-${objectFit}`],
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    const containerStyle: React.CSSProperties = {
+      ...style,
+      ...(width !== undefined && { width: typeof width === 'number' ? `${width}px` : width }),
+      ...(height !== undefined && { height: typeof height === 'number' ? `${height}px` : height }),
+    };
+
+    return (
+      <div ref={ref} {...htmlProps} className={classes} style={containerStyle}>
+        {status === 'error' && fallback ? (
+          <div className={styles.fallback}>{fallback}</div>
+        ) : (
+          <>
+            {status === 'loading' && fallback && (
+              <div className={styles.fallback}>{fallback}</div>
+            )}
+            <img
+              ref={imgRef}
+              {...imgProps}
+              src={src}
+              alt={alt}
+              className={imgClasses}
+              onLoad={handleLoad}
+              onError={handleError}
+              style={{ opacity: status === 'loaded' ? 1 : 0 }}
+            />
+          </>
+        )}
+      </div>
+    );
+  }
+);
+
+export const Image = Object.assign(ImageRoot, {
+  Root: ImageRoot,
+});