@fpkit/acss 0.5.12 → 0.6.0

package/src/components/images/img.types.ts

@@ -0,0 +1,211 @@
+import React from 'react'
+
+/**
+ * Props for the Img component.
+ *
+ * Extends native HTML img element attributes with additional functionality
+ * for responsive images, loading states, and error handling.
+ *
+ * ## Accessibility Guidelines (WCAG 2.1 AA)
+ *
+ * **Decorative Images:**
+ * Images that are purely visual decoration should have an empty alt attribute.
+ *
+ * @example
+ * ```tsx
+ * // ✅ Decorative image (border, background pattern, visual separator)
+ * <Img src="/decorative-border.png" alt="" />
+ * ```
+ *
+ * **Semantic Images:**
+ * Images that convey information or meaning must have descriptive alt text.
+ *
+ * @example
+ * ```tsx
+ * // ✅ Semantic image (charts, diagrams, photos with meaning)
+ * <Img
+ *   src="/sales-chart.png"
+ *   alt="Sales chart showing 30% growth in Q4 2024"
+ * />
+ * ```
+ *
+ * **Responsive Images:**
+ * Use srcset and sizes for responsive images to optimize performance.
+ *
+ * @example
+ * ```tsx
+ * // ✅ Responsive image with srcset
+ * <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, 33vw"
+ *   alt="Team photo from annual conference"
+ * />
+ * ```
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html
+ */
+export interface ImgProps
+  extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, 'placeholder'> {
+  /**
+   * The image source URL.
+   * @default '//'
+   */
+  src?: string
+
+  /**
+   * Alternative text for the image.
+   * - **Empty string (`""`)** for decorative images
+   * - **Descriptive text** for semantic images that convey meaning
+   *
+   * @example
+   * ```tsx
+   * // Decorative
+   * <Img src="/border.png" alt="" />
+   *
+   * // Semantic
+   * <Img src="/logo.png" alt="Company logo" />
+   * ```
+   */
+  alt?: string
+
+  /**
+   * Width of the image in pixels.
+   * @default 480
+   */
+  width?: number | string
+
+  /**
+   * Height of the image in pixels.
+   * When not provided, defaults to 'auto'.
+   */
+  height?: number | string
+
+  /**
+   * Inline styles to apply to the image.
+   */
+  styles?: React.CSSProperties
+
+  /**
+   * Loading behavior for the image.
+   * - `"lazy"` (default): Defers loading until near viewport
+   * - `"eager"`: Loads immediately
+   *
+   * @default "lazy"
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading
+   */
+  loading?: 'eager' | 'lazy'
+
+  /**
+   * Fallback placeholder image URL to display on error.
+   * If not provided and image fails to load, a default placeholder is used.
+   *
+   * @example
+   * ```tsx
+   * <Img
+   *   src="/photo.jpg"
+   *   placeholder="/fallback.png"
+   *   alt="User profile photo"
+   * />
+   * ```
+   */
+  placeholder?: string
+
+  /**
+   * Hint for the browser to prioritize image fetching.
+   * - `"high"`: High priority (above-the-fold images)
+   * - `"low"` (default): Low priority
+   * - `"auto"`: Browser decides
+   *
+   * @default "low"
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#fetchpriority
+   */
+  fetchpriority?: 'high' | 'low' | 'auto'
+
+  /**
+   * Decoding hint for the browser.
+   * - `"async"`: Decode asynchronously (don't block rendering)
+   * - `"sync"`: Decode synchronously
+   * - `"auto"` (default): Browser decides
+   *
+   * @default "auto"
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#decoding
+   */
+  decoding?: 'sync' | 'async' | 'auto'
+
+  /**
+   * Responsive image sources with width descriptors.
+   * Allows browser to choose appropriate image based on viewport.
+   *
+   * @example
+   * ```tsx
+   * <Img
+   *   src="/photo.jpg"
+   *   srcSet="/photo-320w.jpg 320w, /photo-640w.jpg 640w"
+   *   sizes="(max-width: 640px) 100vw, 640px"
+   *   alt="Responsive image"
+   * />
+   * ```
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#srcset
+   */
+  srcSet?: string
+
+  /**
+   * Media conditions for responsive image sizing.
+   * Works with srcSet to determine which image to load.
+   *
+   * @example
+   * ```tsx
+   * sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 800px"
+   * ```
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes
+   */
+  sizes?: string
+
+  /**
+   * Callback fired when the image fails to load.
+   * The default SVG placeholder is still applied after calling this handler.
+   * Call `event.preventDefault()` to prevent the default fallback behavior.
+   *
+   * @param event - The error event
+   *
+   * @example
+   * ```tsx
+   * // Log error and show default placeholder
+   * <Img
+   *   src="/photo.jpg"
+   *   onError={(e) => console.error('Image failed to load', e)}
+   *   alt="Photo"
+   * />
+   *
+   * // Prevent default and use custom fallback
+   * <Img
+   *   src="/photo.jpg"
+   *   onError={(e) => {
+   *     e.preventDefault()
+   *     e.currentTarget.src = '/custom-fallback.jpg'
+   *   }}
+   *   alt="Photo"
+   * />
+   * ```
+   */
+  onError?: (event: React.SyntheticEvent<HTMLImageElement, Event>) => void
+
+  /**
+   * Callback fired when the image successfully loads.
+   *
+   * @param event - The load event
+   *
+   * @example
+   * ```tsx
+   * <Img
+   *   src="/photo.jpg"
+   *   onLoad={(e) => console.log('Image loaded successfully')}
+   *   alt="Photo"
+   * />
+   * ```
+   */
+  onLoad?: (event: React.SyntheticEvent<HTMLImageElement, Event>) => void
+}