@undefine-ui/design-system 2.12.0 → 2.14.0

package/README.md

@@ -113,6 +113,123 @@ import { Icon } from '@undefine-ui/design-system';
 
 The Icon component renders SVG icons with full theme integration and accepts any MUI Box props for flexible styling.
 
+### Image
+
+A high-performance lazy-loading image component with responsive image support, fallback handling, and smooth loading transitions. Perfect for optimizing image delivery across different devices and screen sizes.
+
+**Usage:**
+
+```tsx
+import { Image } from '@undefine-ui/design-system';
+
+// Basic usage with lazy loading
+<Image
+  src="/path/to/image.jpg"
+  alt="Description"
+  aspectRatio="16 / 9"
+/>
+
+// Responsive images with srcSet
+<Image
+  src="/image-1280w.jpg"
+  srcSet="/image-320w.jpg 320w, /image-640w.jpg 640w, /image-1280w.jpg 1280w"
+  sizes="(max-width: 600px) 100vw, (max-width: 1200px) 50vw, 33vw"
+  alt="Responsive image"
+  aspectRatio="16 / 9"
+/>
+
+// Retina display support
+<Image
+  src="/image.jpg"
+  srcSet="/image.jpg 1x, /image@2x.jpg 2x, /image@3x.jpg 3x"
+  alt="High DPI image"
+/>
+
+// With fallback for error handling
+<Image
+  src="/primary-image.jpg"
+  fallbackSrc="/fallback-image.jpg"
+  alt="Image with fallback"
+  aspectRatio="4 / 3"
+/>
+
+// Disable lazy loading for above-the-fold images
+<Image
+  src="/hero-image.jpg"
+  alt="Hero image"
+  lazy={false}
+  aspectRatio="21 / 9"
+/>
+
+// Custom loading indicator
+<Image
+  src="/image.jpg"
+  alt="Custom loading"
+  loadingIndicator={<CircularProgress />}
+/>
+
+// With overlay content
+<Image
+  src="/image.jpg"
+  alt="Image with overlay"
+  overlay={
+    <Box sx={{ p: 2, color: 'white' }}>
+      <Typography variant="h5">Overlay Text</Typography>
+    </Box>
+  }
+/>
+
+// Custom object-fit and position
+<Image
+  src="/portrait.jpg"
+  alt="Portrait"
+  aspectRatio="1"
+  fit="contain"
+  position="top center"
+/>
+```
+
+**Props:**
+
+- `src` - Image source URL (required)
+- `alt` - Alternative text for accessibility (required)
+- `lazy` - Enable lazy loading with Intersection Observer (default: `true`)
+- `srcSet` - Responsive image sources for different screen sizes/resolutions
+- `sizes` - Defines which image size to use at different viewport widths
+- `fallbackSrc` - Fallback URL when the main source fails to load
+- `aspectRatio` - Aspect ratio to prevent layout shift (e.g., `"16 / 9"`, `1.5`)
+- `fit` - Controls `object-fit` CSS property (default: `"cover"`)
+- `position` - Controls `object-position` CSS property (default: `"center"`)
+- `overlay` - Optional overlay content rendered above the image
+- `withOverlay` - Enables overlay even without content
+- `loadingIndicator` - Custom loading indicator component
+- `renderError` - Custom error fallback UI
+- `observerMargin` - Intersection Observer root margin (default: `"200px"`)
+- `imgSx` - Additional styles for the image element
+- `imgProps` - Additional props for the underlying image element
+- `onLoad` - Callback fired when the image loads
+- `onError` - Callback fired when the image fails to load
+
+**Features:**
+
+- **Lazy loading:** Uses Intersection Observer for efficient viewport detection
+- **Responsive images:** Full support for `srcSet` and `sizes` attributes
+- **Fallback handling:** Automatic retry with fallback source on error
+- **Layout stability:** Prevents layout shift with aspect ratio control
+- **Smooth transitions:** Fade-in animation when image loads
+- **Custom loading states:** Skeleton loader by default, customizable
+- **Error handling:** Graceful error UI with customization options
+- **Overlay support:** Render content on top of images
+- **Browser fallback:** Uses native `loading="lazy"` when IntersectionObserver unavailable
+- **Flexible styling:** Supports all MUI Box props for container and image
+
+**Performance Tips:**
+
+- Use `lazy={false}` for above-the-fold images to avoid lazy loading delay
+- Always specify `aspectRatio` to prevent layout shift during loading
+- Use `srcSet` with appropriate sizes for optimal image delivery
+- Set `observerMargin="400px"` to preload images slightly before viewport
+
 ### OTP Input
 
 A one-time password input component with keyboard navigation, paste support, and validation. Perfect for email/SMS verification, PIN codes, and security codes.
@@ -234,7 +351,7 @@ Everything is re-exported from `src/index.ts`. Key groups:
 
 | Group      | Exports                                                                                                                                                                      |
 | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Components | `CopyButton`, `HookForm` helpers (`Form`, `Field`, `RHFSwitch`, etc.), `Icon`, `Logo`, `LoadingScreen`, `Table`, `Upload`                                                    |
+| Components | `CopyButton`, `HookForm` helpers (`Form`, `Field`, `RHFSwitch`, etc.), `Icon`, `Image`, `Logo`, `LoadingScreen`, `OTPInput`, `Table`, `Upload`                               |
 | Hooks      | `useBoolean`, `useCopyToClipboard`, `useEventListener`, `useLocalStorage`, `useResponsive`, `useSettings`, `useSetState`, `useScrollOffsetTop`, `usePopover`, `useCountdown` |
 | Contexts   | `SettingsProvider`, `SettingsContext`, `defaultSettings`, `SettingsValueProps`                                                                                               |
 | Theme      | `ThemeProvider`, `createTheme`, `colorSchemes`, `components`, `palette`, `radius`, `shadows`, `customSpacing`, utilities such as `varAlpha`, `bgGradient`, `hideScrollX/Y`   |