@fpkit/acss 0.5.11 → 0.5.13

package/src/components/images/img.test.tsx

@@ -1,43 +1,372 @@
 import { Img } from './img'
 import React from 'react'
 import { fireEvent, render, screen } from '@testing-library/react'
-import jest from 'jest-mock'
+import { describe, it, expect, vi } from 'vitest'
+
 describe('Img', () => {
-  it('should render an img element with passed props', () => {
-    const src = 'test.jpg'
-    const alt = 'Test image'
-    const width = 100
+  describe('Basic Rendering', () => {
+    it('should render an img element with passed props', () => {
+      const src = 'test.jpg'
+      const alt = 'Test image'
+      const width = 100
+
+      render(<Img src={src} alt={alt} width={width} />)
+
+      const img = screen.getByRole('img')
+      expect(img).toBeInTheDocument()
+      expect(img).toHaveAttribute('src', src)
+      expect(img).toHaveAttribute('alt', alt)
+      expect(img).toHaveAttribute('width', width.toString())
+    })
+
+    it('should render with default props when none provided', () => {
+      render(<Img />)
+
+      const img = screen.getByRole('img')
+      expect(img).toBeInTheDocument()
+      expect(img).toHaveAttribute('src', '//')
+      expect(img).toHaveAttribute('width', '480')
+      expect(img).toHaveAttribute('loading', 'lazy')
+    })
+
+    it('should apply custom width and height', () => {
+      render(<Img src="test.jpg" alt="Test" width={200} height={150} />)
+
+      const img = screen.getByRole('img')
+      expect(img).toHaveAttribute('width', '200')
+      expect(img).toHaveAttribute('height', '150')
+    })
+  })
+
+  describe('Accessibility', () => {
+    it('should support decorative images with empty alt', () => {
+      render(<Img src="decorative.png" alt="" />)
+
+      const img = screen.getByRole('img', { hidden: true })
+      expect(img).toHaveAttribute('alt', '')
+    })
+
+    it('should support semantic images with descriptive alt text', () => {
+      const altText = 'Sales chart showing 30% growth in Q4'
+      render(<Img src="chart.png" alt={altText} />)
+
+      const img = screen.getByRole('img')
+      expect(img).toHaveAccessibleName(altText)
+    })
+
+    it('should allow missing alt attribute', () => {
+      render(<Img src="test.jpg" />)
+
+      const img = screen.getByRole('img')
+      expect(img).toBeInTheDocument()
+    })
+  })
+
+  describe('Responsive Images', () => {
+    it('should support srcSet attribute', () => {
+      const srcSet = 'image-320w.jpg 320w, image-640w.jpg 640w'
+      render(<Img src="image.jpg" srcSet={srcSet} alt="Responsive image" />)
+
+      const img = screen.getByRole('img')
+      expect(img).toHaveAttribute('srcset', srcSet)
+    })
+
+    it('should support sizes attribute', () => {
+      const sizes = '(max-width: 640px) 100vw, 640px'
+      render(
+        <Img
+          src="image.jpg"
+          srcSet="image-320w.jpg 320w, image-640w.jpg 640w"
+          sizes={sizes}
+          alt="Responsive image"
+        />,
+      )
+
+      const img = screen.getByRole('img')
+      expect(img).toHaveAttribute('sizes', sizes)
+    })
+
+    it('should work without srcSet and sizes', () => {
+      render(<Img src="image.jpg" alt="Regular image" />)
+
+      const img = screen.getByRole('img')
+      expect(img).not.toHaveAttribute('srcset')
+      expect(img).not.toHaveAttribute('sizes')
+    })
+  })
+
+  describe('Loading and Performance', () => {
+    it('should default to lazy loading', () => {
+      render(<Img src="test.jpg" alt="Test" />)
+
+      const img = screen.getByRole('img')
+      expect(img).toHaveAttribute('loading', 'lazy')
+    })
+
+    it('should support eager loading', () => {
+      render(<Img src="hero.jpg" alt="Hero" loading="eager" />)
+
+      const img = screen.getByRole('img')
+      expect(img).toHaveAttribute('loading', 'eager')
+    })
+
+    it('should support fetchpriority attribute', () => {
+      render(
+        <Img src="hero.jpg" alt="Hero" fetchpriority="high" loading="eager" />,
+      )
+
+      const img = screen.getByRole('img')
+      expect(img).toHaveAttribute('fetchpriority', 'high')
+    })
+
+    it('should support decoding attribute', () => {
+      render(<Img src="test.jpg" alt="Test" decoding="async" />)
+
+      const img = screen.getByRole('img')
+      expect(img).toHaveAttribute('decoding', 'async')
+    })
+  })
+
+  describe('Error Handling', () => {
+    it('should call onError callback and apply fallback placeholder', () => {
+      const onError = vi.fn()
+      render(<Img src="bad.jpg" alt="Test" onError={onError} />)
+
+      const img = screen.getByRole('img') as HTMLImageElement
+      fireEvent.error(img)
+
+      // Should call custom handler
+      expect(onError).toHaveBeenCalledTimes(1)
+      expect(onError).toHaveBeenCalledWith(expect.any(Object))
+
+      // Should still apply default fallback
+      expect(img.src).toContain('data:image/svg+xml')
+    })
+
+    it('should prevent default fallback when preventDefault is called', () => {
+      const customSrc = 'https://custom-fallback.jpg'
+      const onError = vi.fn((e) => {
+        e.preventDefault()
+        e.currentTarget.src = customSrc
+      })
+      render(<Img src="bad.jpg" alt="Test" onError={onError} />)
+
+      const img = screen.getByRole('img') as HTMLImageElement
+      fireEvent.error(img)
+
+      // Should call custom handler
+      expect(onError).toHaveBeenCalledTimes(1)
+
+      // Should use custom fallback, not default SVG
+      expect(img.src).toContain(customSrc)
+      expect(img.src).not.toContain('data:image/svg+xml')
+    })
+
+    it('should fallback to placeholder when error occurs and no onError handler', () => {
+      render(<Img src="bad.jpg" alt="Test" placeholder="/fallback.png" />)
+
+      const img = screen.getByRole('img') as HTMLImageElement
+      fireEvent.error(img)
 
-    const { container } = render(<Img src={src} alt={alt} width={width} />)
+      expect(img.src).toContain('fallback.png')
+    })
 
-    const img = screen.getByRole('img')
-    expect(img).toBeInTheDocument()
-    expect(img).toHaveAttribute('src', src)
-    expect(img).toHaveAttribute('alt', alt)
-    expect(img).toHaveAttribute('width', width.toString())
+    it('should use default SVG placeholder when none provided', () => {
+      render(<Img src="bad.jpg" alt="Test" width={300} />)
+
+      const img = screen.getByRole('img') as HTMLImageElement
+      fireEvent.error(img)
+
+      // Should use SVG data URI placeholder
+      expect(img.src).toContain('data:image/svg+xml')
+      expect(img.src).toContain('300') // Width in dimension text
+    })
+
+    it('should not enter infinite loop when placeholder also fails', () => {
+      render(<Img src="bad.jpg" alt="Test" placeholder="/also-bad.png" />)
+
+      const img = screen.getByRole('img') as HTMLImageElement
+
+      // First error: switches to placeholder
+      fireEvent.error(img)
+      const firstSrc = img.src
+
+      // Second error: should not change src again
+      fireEvent.error(img)
+      expect(img.src).toBe(firstSrc)
+    })
   })
 
-  it('should apply default styles when renderStyles is true', () => {
-    const { container } = render(<Img src="" alt="" />)
+  describe('Event Handlers', () => {
+    it('should call onLoad callback when image loads', () => {
+      const onLoad = vi.fn()
+      render(<Img src="good.jpg" alt="Test" onLoad={onLoad} />)
+
+      const img = screen.getByRole('img')
+      fireEvent.load(img)
+
+      expect(onLoad).toHaveBeenCalledTimes(1)
+      expect(onLoad).toHaveBeenCalledWith(expect.any(Object))
+    })
+
+    it('should work without onLoad callback', () => {
+      render(<Img src="test.jpg" alt="Test" />)
+
+      const img = screen.getByRole('img')
+      expect(() => fireEvent.load(img)).not.toThrow()
+    })
+
+    it('should work without onError callback', () => {
+      render(<Img src="test.jpg" alt="Test" />)
+
+      const img = screen.getByRole('img')
+      expect(() => fireEvent.error(img)).not.toThrow()
+    })
+  })
+
+  describe('Styling', () => {
+    it('should apply inline styles', () => {
+      const styles = { border: '1px solid red', borderRadius: '0.5rem' }
+      render(<Img src="test.jpg" alt="Test" styles={styles} />)
+
+      const img = screen.getByRole('img')
+      expect(img).toHaveStyle({ border: '1px solid red' })
+      expect(img).toHaveStyle({ borderRadius: '0.5rem' })
+    })
+
+    it('should forward additional props', () => {
+      render(
+        <Img
+          src="test.jpg"
+          alt="Test"
+          data-testid="custom-img"
+          className="custom-class"
+        />,
+      )
+
+      const img = screen.getByTestId('custom-img')
+      expect(img).toHaveClass('custom-class')
+    })
   })
 
-  it('should call imgError callback on error', () => {
-    const onError = jest.fn()
-    render(<Img src="bad.jpg" alt="" imgError={onError} />)
+  describe('Edge Cases', () => {
+    it('should handle string width values', () => {
+      render(<Img src="test.jpg" alt="Test" width="100%" />)
+
+      const img = screen.getByRole('img')
+      expect(img).toHaveAttribute('width', '100%')
+    })
+
+    it('should default height to auto when not provided', () => {
+      render(<Img src="test.jpg" alt="Test" />)
 
-    const img = screen.getByRole('img')
-    fireEvent.error(img)
+      const img = screen.getByRole('img')
+      expect(img).toHaveAttribute('height', 'auto')
+    })
 
-    expect(onError).toHaveBeenCalledTimes(1)
+    it('should accept custom height', () => {
+      render(<Img src="test.jpg" alt="Test" height={200} />)
+
+      const img = screen.getByRole('img')
+      expect(img).toHaveAttribute('height', '200')
+    })
   })
 
-  it('should call imgLoaded callback on load', () => {
-    const onLoad = jest.fn()
-    render(<Img src="good.jpg" alt="" imgLoaded={onLoad} />)
+  describe('SVG Placeholder', () => {
+    it('should generate SVG placeholder with correct dimensions', () => {
+      render(<Img src="bad.jpg" alt="Test" width={800} height={600} />)
+
+      const img = screen.getByRole('img') as HTMLImageElement
+      fireEvent.error(img)
+
+      // Should be SVG data URI
+      expect(img.src).toContain('data:image/svg+xml')
+      // Should contain both dimensions in the text
+      expect(img.src).toContain('800')
+      expect(img.src).toContain('600')
+    })
+
+    it('should generate SVG with 4:3 aspect ratio when height not provided', () => {
+      render(<Img src="bad.jpg" alt="Test" width={400} />)
+
+      const img = screen.getByRole('img') as HTMLImageElement
+      fireEvent.error(img)
+
+      expect(img.src).toContain('data:image/svg+xml')
+      // 400 * 0.75 = 300
+      expect(img.src).toContain('400')
+      expect(img.src).toContain('300')
+    })
+
+    it('should generate SVG with gradient elements', () => {
+      render(<Img src="bad.jpg" alt="Test" width={500} />)
+
+      const img = screen.getByRole('img') as HTMLImageElement
+      fireEvent.error(img)
+
+      const decodedSvg = decodeURIComponent(img.src.replace('data:image/svg+xml,', ''))
+
+      // Should contain gradient definition
+      expect(decodedSvg).toContain('linearGradient')
+      expect(decodedSvg).toContain('#6366f1') // Indigo
+      expect(decodedSvg).toContain('#8b5cf6') // Purple
+      expect(decodedSvg).toContain('#ec4899') // Pink
+
+      // Should contain decorative elements
+      expect(decodedSvg).toContain('circle') // Sun
+      expect(decodedSvg).toContain('path') // Mountain wave
+      expect(decodedSvg).toContain('text') // Dimension text
+    })
+
+    it('should generate unique gradient IDs for different dimensions', () => {
+      const { rerender } = render(<Img src="bad1.jpg" alt="Test" width={400} height={300} />)
+      const img1 = screen.getByRole('img') as HTMLImageElement
+      fireEvent.error(img1)
+      const svg1 = decodeURIComponent(img1.src.replace('data:image/svg+xml,', ''))
+
+      rerender(<Img src="bad2.jpg" alt="Test" width={800} height={600} />)
+      const img2 = screen.getByRole('img') as HTMLImageElement
+      fireEvent.error(img2)
+      const svg2 = decodeURIComponent(img2.src.replace('data:image/svg+xml,', ''))
+
+      // Different gradient IDs to prevent conflicts
+      expect(svg1).toContain('grad-400-300')
+      expect(svg2).toContain('grad-800-600')
+    })
+
+    it('should handle string width by defaulting to 480', () => {
+      render(<Img src="bad.jpg" alt="Test" width="100%" />)
+
+      const img = screen.getByRole('img') as HTMLImageElement
+      fireEvent.error(img)
+
+      expect(img.src).toContain('data:image/svg+xml')
+      // Should default to 480 when width is string
+      expect(img.src).toContain('480')
+    })
+
+    it('should be smaller than external placeholder', () => {
+      render(<Img src="bad.jpg" alt="Test" width={800} />)
+
+      const img = screen.getByRole('img') as HTMLImageElement
+      fireEvent.error(img)
+
+      // SVG data URI should be relatively small (< 2KB)
+      expect(img.src.length).toBeLessThan(2000)
+      // Should start with data URI scheme
+      expect(img.src).toMatch(/^data:image\/svg\+xml,/)
+    })
+
+    it('should contain viewBox for responsiveness', () => {
+      render(<Img src="bad.jpg" alt="Test" width={600} height={400} />)
+
+      const img = screen.getByRole('img') as HTMLImageElement
+      fireEvent.error(img)
 
-    const img = screen.getByRole('img')
-    fireEvent.load(img)
+      const decodedSvg = decodeURIComponent(img.src.replace('data:image/svg+xml,', ''))
 
-    expect(onLoad).toHaveBeenCalledTimes(1)
+      // Should have viewBox for perfect scaling
+      expect(decodedSvg).toContain('viewBox="0 0 600 400"')
+    })
   })
 })

package/src/components/images/img.tsx

@@ -1,75 +1,196 @@
-import UI from '../ui'
-import React from 'react'
-/*
- * ImageProps interface
- *
- * Extends ComponentProps and defines additional props for the Img component.
- *
- * @property {string} [src] - The image source URL
- * @property {string} alt - Required alt text for image accessibility
- * @property {number} width - Required width of image
- * @property {number} [height] - Optional height of image
- * @property {"eager" | "lazy"} [loading="lazy"] - Loading behavior
- * @property {string} [placeholder] - Fallback placeholder image
- * @property {"high" | "low"} [fetchpriority="low"] - Image fetch priority
- * @property {"sync" | "async" | "auto"} [decoding="auto"] - Decode setting
- * @property {function} [imgError] - Error callback
- * @property {function} [imgLoaded] - Loaded callback
- */
-export type ImageProps = React.ComponentProps<'img'> &
-  React.ComponentProps<typeof UI>
+import UI from "../ui";
+import React, { useMemo } from "react";
+import type { ImgProps } from "./img.types";
 
-/*
- * Img component
- *
- * Renders an <img> element with custom props.
- *
- * @param {string} src - The image source URL.
- * @param {string} alt - The alt text for the image.
- * @param {number} [width=480] - The width of the image.
- * @param {number} [height] - The height of the image.
- * @param {Object} [styles] - Additional CSS styles to apply.
- * @param {boolean} [renderStyles=true] - Whether to render the default styles.
- * @param {"eager" | "lazy"} [loading="lazy"] - The loading attribute.
- * @param {string} [placeholder] - A placeholder image URL.
- * @param {"high" | "low"} [fetchpriority="low"] - The fetchpriority attribute.
- * @param {"sync" | "async" | "auto"} [decoding="auto"] - The decoding attribute.
- * @param {function} [imgLoaded] - Callback when image loads successfully.
- * @param {function} [imgError] - Callback when image errors.
- *
- * @returns {JSX.Element} The Img component.
+/**
+ * Img - A semantic image component with accessibility and performance best practices.
+ *
+ * This component wraps the native `<img>` element with enhanced features:
+ * - **Responsive images** via optional srcset/sizes
+ * - **Lazy loading** by default for performance
+ * - **Error handling** with configurable fallback placeholders
+ * - **Type safety** with full TypeScript support
+ *
+ * ## Accessibility Patterns (WCAG 2.1 AA)
+ *
+ * ### Decorative Images
+ * Images that are purely visual decoration should use an empty alt attribute.
+ * These images are typically borders, patterns, or visual separators.
+ *
+ * @example
+ * ```tsx
+ * // ✅ GOOD: Decorative border image
+ * <Img src="/decorative-border.png" alt="" />
+ *
+ * // ✅ GOOD: Background pattern
+ * <Img src="/pattern.svg" alt="" loading="eager" />
+ * ```
+ *
+ * ### Semantic Images
+ * Images that convey information must have descriptive alt text that explains
+ * the content and purpose of the image.
+ *
+ * @example
+ * ```tsx
+ * // ✅ GOOD: Informative image with descriptive alt
+ * <Img
+ *   src="/sales-chart.png"
+ *   alt="Sales chart showing 30% revenue growth in Q4 2024"
+ * />
+ *
+ * // ✅ GOOD: Product photo with context
+ * <Img
+ *   src="/laptop.jpg"
+ *   alt="Silver MacBook Pro 14-inch on wooden desk"
+ * />
+ * ```
+ *
+ * ## Performance Optimization
+ *
+ * ### Lazy Loading
+ * By default, images use lazy loading to improve page load performance.
+ * Only use `loading="eager"` for above-the-fold images.
+ *
+ * @example
+ * ```tsx
+ * // ✅ GOOD: Lazy load below-the-fold image
+ * <Img src="/photo.jpg" alt="Photo" />
+ *
+ * // ✅ GOOD: Eager load hero image
+ * <Img
+ *   src="/hero.jpg"
+ *   alt="Hero banner"
+ *   loading="eager"
+ *   fetchpriority="high"
+ * />
+ * ```
+ *
+ * ### Responsive Images
+ * Use srcset and sizes for responsive images to serve appropriate image sizes
+ * based on viewport width, improving performance and bandwidth usage.
+ *
+ * @example
+ * ```tsx
+ * // ✅ GOOD: Responsive image with multiple sizes
+ * <Img
+ *   src="/photo.jpg"
+ *   srcSet="/photo-320w.jpg 320w, /photo-640w.jpg 640w, /photo-1024w.jpg 1024w"
+ *   sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 800px"
+ *   alt="Responsive image adapts to viewport"
+ * />
+ * ```
+ *
+ * ## Error Handling
+ *
+ * @example
+ * ```tsx
+ * // ✅ GOOD: Custom placeholder on error
+ * <Img
+ *   src="/photo.jpg"
+ *   placeholder="/fallback.png"
+ *   alt="User profile photo"
+ * />
+ *
+ * // ✅ GOOD: Custom error handler
+ * <Img
+ *   src="/photo.jpg"
+ *   onError={(e) => {
+ *     console.error('Image failed to load')
+ *     logToAnalytics('image_error', { src: e.currentTarget.src })
+ *   }}
+ *   alt="Photo"
+ * />
+ * ```
+ *
+ * @param {ImgProps} props - Component props extending native img attributes
+ * @returns {React.ReactElement} Image element with enhanced functionality
+ *
+ * @see {@link ImgProps} for complete prop documentation
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html
  */
 export const Img = ({
-  src = '//',
+  src = "//",
   alt,
   width = 480,
   height,
   styles,
-  loading = 'lazy',
-  placeholder = `https://via.placeholder.com/${width}?text=PLACEHOLDER`,
-  fetchpriority = 'low',
-  decoding = 'auto',
-  imgLoaded,
-  imgError,
+  loading = "lazy",
+  placeholder,
+  fetchpriority = "low",
+  decoding = "auto",
+  srcSet,
+  sizes,
+  onError,
+  onLoad,
   ...props
-}: ImageProps) => {
+}: ImgProps) => {
+  /**
+   * Generates a performant, responsive SVG gradient placeholder.
+   * Uses data URI to avoid network requests and memoizes based on dimensions.
+   * The SVG uses viewBox for perfect scaling at any size.
+   *
+   * Features:
+   * - Zero network requests (works offline)
+   * - ~900 bytes vs. 5-10KB external image
+   * - Responsive with viewBox
+   * - Attractive gradient (indigo → purple → pink)
+   * - Dimension text for debugging
+   */
+  const defaultPlaceholder = useMemo(() => {
+    const w = typeof width === "number" ? width : 480;
+    const h = typeof height === "number" ? height : Math.round(w * 0.75);
+
+    // Responsive SVG with attractive gradient and dimension text
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${w} ${h}">
+      <defs>
+        <linearGradient id="grad-${w}-${h}" x1="0%" y1="0%" x2="100%" y2="100%">
+          <stop offset="0%" style="stop-color:#6366f1;stop-opacity:1" />
+          <stop offset="50%" style="stop-color:#8b5cf6;stop-opacity:1" />
+          <stop offset="100%" style="stop-color:#ec4899;stop-opacity:1" />
+        </linearGradient>
+      </defs>
+      <rect width="${w}" height="${h}" fill="url(#grad-${w}-${h})"/>
+      <circle cx="${w * 0.15}" cy="${h * 0.2}" r="${Math.min(w, h) * 0.08}" fill="rgba(255,255,255,0.2)"/>
+      <path d="M0,${h * 0.75} Q${w * 0.25},${h * 0.65} ${w * 0.5},${h * 0.75} T${w},${h * 0.75} L${w},${h} L0,${h} Z" fill="rgba(0,0,0,0.15)"/>
+      <text x="50%" y="50%" dominant-baseline="middle" text-anchor="middle" font-family="system-ui,-apple-system,sans-serif" font-size="${Math.max(16, Math.min(w, h) * 0.05)}" font-weight="500" fill="rgba(255,255,255,0.9)">${w}×${h}</text>
+    </svg>`;
+
+    return `data:image/svg+xml,${encodeURIComponent(svg)}`;
+  }, [width, height]);
+
+  const fallbackPlaceholder = placeholder ?? defaultPlaceholder;
+
+  /**
+   * Handles image load errors.
+   * Calls custom error handler if provided, then applies fallback placeholder.
+   * The custom handler can prevent the default fallback by calling e.preventDefault().
+   */
   const handleImgError = (
-    e: React.SyntheticEvent<HTMLImageElement, Event>,
+    e: React.SyntheticEvent<HTMLImageElement, Event>
   ): void => {
-    if (imgError) {
-      imgError?.(e)
-      return
+    // Call custom error handler first (for logging, analytics, etc.)
+    if (onError) {
+      onError(e);
     }
-    if (e.currentTarget.src !== placeholder) {
-      e.currentTarget.src = placeholder
+
+    // Apply fallback unless preventDefault() was called
+    if (!e.defaultPrevented) {
+      // Avoid infinite error loop by checking if already showing placeholder
+      if (e.currentTarget.src !== fallbackPlaceholder) {
+        e.currentTarget.src = fallbackPlaceholder;
+      }
     }
-  }
+  };
 
+  /**
+   * Handles successful image load.
+   * Calls custom load handler if provided.
+   */
   const handleImgLoad = (
-    e: React.SyntheticEvent<HTMLImageElement, Event>,
+    e: React.SyntheticEvent<HTMLImageElement, Event>
   ): void => {
-    imgLoaded?.(e)
-  }
+    onLoad?.(e);
+  };
 
   return (
     <UI
@@ -77,17 +198,19 @@ export const Img = ({
       src={src}
       alt={alt}
       width={width}
-      height={height || 'auto'}
+      height={height || "auto"}
       loading={loading}
       style={styles}
+      srcSet={srcSet}
+      sizes={sizes}
       onError={handleImgError}
       onLoad={handleImgLoad}
-      fetchPriority={fetchpriority}
       decoding={decoding}
       {...props}
+      {...(fetchpriority && { fetchpriority })}
     />
-  )
-}
+  );
+};
 
-export default Img
-Img.displayName = 'Img'
+export default Img;
+Img.displayName = "Img";