@appforgeapps/uiforge 0.5.5 → 0.5.6

package/README.md

@@ -1711,8 +1711,25 @@ UIForge components support comprehensive theming through CSS variables. See [THE
 - CSS variable reference
 - System preference detection
 - Advanced customization techniques
+- **Example app themes** - Learn from real-world examples like the NexaLive music streaming app theme
 
-Quick example:
+### Example App Themes
+
+UIForge provides concrete example themes in `examples/themes/` to demonstrate how to create custom themes for real applications:
+
+- **NexaLive Theme** (`examples/themes/nexalive-theme.css`) - A purple/pink themed music streaming app example based on the [chriscase/nexalive](https://github.com/chriscase/nexalive) project
+
+**Important:** Example themes are for **demonstration only**. Copy them into your own application and customize the colors to match your brand. See [THEMING.md - Example App Themes](./THEMING.md#example-app-themes) for detailed adoption instructions.
+
+Quick example of import order:
+
+```tsx
+// Import UIForge core styles FIRST, then your custom theme
+import '@appforgeapps/uiforge/styles.css'
+import './my-custom-theme.css'  // Your customized copy of an example theme
+```
+
+Quick component theming example:
 
 ```tsx
 import { useState } from 'react'
@@ -1817,6 +1834,8 @@ Simply open this repository in GitHub Codespaces to get started immediately with
 
 Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed guidelines.
 
+**Important for Component Contributors:** UIForge is a library-first project. Before contributing a component, review the [Component Design Guidelines](./COMPONENT_GUIDELINES.md) to ensure your component remains generic, reusable, and composable.
+
 Quick start:
 
 1. Fork the repository

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { default as default_2 } from 'react';
 import { FC } from 'react';
+import { ImgHTMLAttributes } from 'react';
 import { JSX } from 'react/jsx-runtime';
 import { RefObject } from 'react';
 
@@ -571,6 +572,263 @@ export declare function isAdultContent(url: string): boolean;
 
 export declare const IssueIcon: default_2.FC<IconProps>;
 
+/**
+ * A generic, reusable MediaCard component for displaying media-driven content items.
+ *
+ * Features:
+ * - Responsive layout: media left + body right (desktop), stacked (mobile)
+ * - Theme token integration for consistent spacing, typography, and elevation
+ * - Full accessibility support (alt text, focus states, ARIA labels, keyboard navigation)
+ * - Flexible customization via render props and slots
+ * - Multiple variants for different use cases
+ *
+ * @example
+ * ```tsx
+ * <MediaCard
+ *   title="Song Title"
+ *   subtitle="Artist Name"
+ *   mediaUrl="/album-art.jpg"
+ *   mediaAlt="Album artwork"
+ *   meta={{ duration: "3:45", year: "2024" }}
+ *   actions={<button>Play</button>}
+ * />
+ * ```
+ */
+export declare const MediaCard: default_2.FC<MediaCardProps>;
+
+/**
+ * Props for the MediaCard component
+ */
+export declare interface MediaCardProps {
+    /**
+     * Main title text displayed prominently
+     */
+    title: string;
+    /**
+     * Secondary subtitle text
+     */
+    subtitle?: string;
+    /**
+     * URL or path to the media (image/video)
+     */
+    mediaUrl: string;
+    /**
+     * Alt text for the media (required for accessibility)
+     */
+    mediaAlt: string;
+    /**
+     * Optional metadata as key-value pairs
+     */
+    meta?: Record<string, string>;
+    /**
+     * Optional action buttons or elements to display
+     */
+    actions?: default_2.ReactNode;
+    /**
+     * Visual variant of the card
+     */
+    variant?: 'default' | 'compact' | 'featured';
+    /**
+     * Custom className for additional styling
+     */
+    className?: string;
+    /**
+     * Theme variant ('light' or 'dark')
+     */
+    theme?: 'light' | 'dark';
+    /**
+     * Optional custom body content (render prop)
+     */
+    renderBody?: () => default_2.ReactNode;
+    /**
+     * Optional custom footer content (render prop)
+     */
+    renderFooter?: () => default_2.ReactNode;
+    /**
+     * Click handler for the entire card
+     */
+    onClick?: () => void;
+    /**
+     * Makes the card focusable and keyboard-navigable
+     */
+    tabIndex?: number;
+    /**
+     * ARIA label for the card
+     */
+    ariaLabel?: string;
+}
+
+/**
+ * MediaListSkeleton - A loading skeleton component for lists of MediaCard components
+ *
+ * Features:
+ * - Configurable number of skeleton items
+ * - CSS shimmer animation for visual feedback
+ * - Respects `prefers-reduced-motion` for accessibility
+ * - Uses UIForge design tokens for consistent sizing
+ * - Theme support (light/dark)
+ * - SSR-friendly (no client-side JavaScript required)
+ *
+ * Perfect for:
+ * - Loading states while fetching media lists
+ * - Progressive loading experiences
+ * - Skeleton screens for any MediaCard-based lists
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <MediaListSkeleton count={5} />
+ *
+ * // Dark theme
+ * <MediaListSkeleton count={3} theme="dark" />
+ *
+ * // In a conditional render
+ * {isLoading ? (
+ *   <MediaListSkeleton count={6} />
+ * ) : (
+ *   songList.map(song => <SongCard key={song.id} {...song} />)
+ * )}
+ * ```
+ */
+export declare const MediaListSkeleton: default_2.FC<MediaListSkeletonProps>;
+
+/**
+ * Props for the MediaListSkeleton component
+ */
+export declare interface MediaListSkeletonProps {
+    /**
+     * Number of skeleton placeholders to render
+     * @default 3
+     */
+    count?: number;
+    /**
+     * Theme variant ('light' or 'dark')
+     * @default 'light'
+     */
+    theme?: 'light' | 'dark';
+    /**
+     * Custom className for additional styling
+     */
+    className?: string;
+    /**
+     * ARIA label for accessibility
+     * @default 'Loading media items'
+     */
+    ariaLabel?: string;
+}
+
+/**
+ * MediaPlaceholder - A placeholder component for missing or loading media
+ *
+ * Features:
+ * - Three display modes: icon, initials, gradient
+ * - Multiple size options
+ * - Customizable border radius
+ * - Theme support (light/dark)
+ * - Accessibility support with alt text
+ *
+ * Perfect for:
+ * - Missing profile pictures
+ * - Loading states for images
+ * - Default avatars
+ * - Fallback media for MediaCard
+ *
+ * @example
+ * ```tsx
+ * // Icon placeholder (default)
+ * <MediaPlaceholder alt="Profile picture" />
+ *
+ * // Initials placeholder
+ * <MediaPlaceholder
+ *   type="initials"
+ *   name="John Doe"
+ *   size="large"
+ *   borderRadius="full"
+ *   alt="John Doe's avatar"
+ * />
+ *
+ * // Gradient placeholder
+ * <MediaPlaceholder
+ *   type="gradient"
+ *   gradientColor="purple"
+ *   size="medium"
+ *   alt="Album artwork placeholder"
+ * />
+ *
+ * // Custom icon
+ * <MediaPlaceholder
+ *   type="icon"
+ *   icon={<MusicIcon />}
+ *   alt="Music placeholder"
+ * />
+ * ```
+ */
+export declare const MediaPlaceholder: default_2.FC<MediaPlaceholderProps>;
+
+/**
+ * Props for the MediaPlaceholder component
+ */
+export declare interface MediaPlaceholderProps {
+    /**
+     * Type of placeholder to display
+     * - 'icon': Shows an icon (default)
+     * - 'initials': Shows initials from a name
+     * - 'gradient': Shows a gradient background
+     */
+    type?: 'icon' | 'initials' | 'gradient';
+    /**
+     * Icon to display (only used when type='icon')
+     * Can be any React node (e.g., SVG, emoji, or icon component)
+     */
+    icon?: default_2.ReactNode;
+    /**
+     * Name to extract initials from (only used when type='initials')
+     * Examples: "John Doe" → "JD", "Taylor Swift" → "TS"
+     */
+    name?: string;
+    /**
+     * Custom initials text (overrides automatic extraction from name)
+     */
+    initials?: string;
+    /**
+     * Gradient color scheme (only used when type='gradient')
+     * - 'blue': Blue gradient
+     * - 'purple': Purple gradient
+     * - 'green': Green gradient
+     * - 'orange': Orange gradient
+     * - 'pink': Pink gradient
+     */
+    gradientColor?: 'blue' | 'purple' | 'green' | 'orange' | 'pink';
+    /**
+     * Size of the placeholder
+     * - 'small': 64px
+     * - 'medium': 84px (default)
+     * - 'large': 120px
+     * - 'xlarge': 160px
+     */
+    size?: 'small' | 'medium' | 'large' | 'xlarge';
+    /**
+     * Border radius style
+     * - 'small': 4px
+     * - 'medium': 8px (default)
+     * - 'large': 12px
+     * - 'full': 50% (circular)
+     */
+    borderRadius?: 'small' | 'medium' | 'large' | 'full';
+    /**
+     * Custom className for additional styling
+     */
+    className?: string;
+    /**
+     * Alt text for accessibility (required for screen readers)
+     */
+    alt?: string;
+    /**
+     * Theme variant ('light' or 'dark')
+     */
+    theme?: 'light' | 'dark';
+}
+
 export declare const MeditationIcon: default_2.FC<IconProps>;
 
 export declare const MeetingIcon: default_2.FC<IconProps>;
@@ -1714,6 +1972,180 @@ export declare interface UseDynamicPageCountOptions {
     approxItemHeight?: number;
 }
 
+/**
+ * useOptimizedImage - A hook that provides optimized image attributes
+ *
+ * This hook helps you implement best practices for image loading and performance:
+ *
+ * **Performance Best Practices:**
+ * 1. **Lazy Loading**: Use `loading="lazy"` for images below the fold
+ * 2. **Async Decoding**: Use `decoding="async"` to avoid blocking the main thread
+ * 3. **Responsive Images**: Use `srcSet` and `sizes` for different screen sizes
+ * 4. **Aspect Ratio**: Use `aspectRatio` to prevent layout shift (CLS)
+ * 5. **LQIP (Low Quality Image Placeholder)**: Consider using a blur-up technique
+ *
+ * **Recommended Image Sizes:**
+ * - Thumbnails: 64px, 84px, 120px
+ * - Cards: 320px, 480px, 640px
+ * - Hero images: 1024px, 1280px, 1920px
+ * - Always provide WebP/AVIF formats when possible
+ *
+ * **Accessibility:**
+ * - Always provide meaningful `alt` text
+ * - Use empty `alt=""` for decorative images
+ * - Consider adding `title` for additional context
+ *
+ * **LQIP Guidance:**
+ * For optimal user experience, consider implementing a Low Quality Image Placeholder (LQIP):
+ * 1. Generate a tiny version of the image (e.g., 20px wide, base64 encoded)
+ * 2. Display it as background while the full image loads
+ * 3. Blur it with CSS `filter: blur(10px)` for a smooth appearance
+ * 4. Fade in the full image when loaded
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * function BasicImage() {
+ *   const { imgProps } = useOptimizedImage({
+ *     src: '/image.jpg',
+ *     alt: 'Product photo',
+ *     loading: 'lazy',
+ *     decoding: 'async'
+ *   })
+ *   return <img {...imgProps} />
+ * }
+ *
+ * // Responsive images with srcSet
+ * function ResponsiveImage() {
+ *   const { imgProps } = useOptimizedImage({
+ *     src: '/image-800w.jpg',
+ *     alt: 'Responsive image',
+ *     srcSet: '/image-400w.jpg 400w, /image-800w.jpg 800w, /image-1200w.jpg 1200w',
+ *     sizes: '(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw',
+ *     loading: 'lazy',
+ *     decoding: 'async'
+ *   })
+ *   return <img {...imgProps} />
+ * }
+ *
+ * // With aspect ratio (prevents layout shift)
+ * function AspectRatioImage() {
+ *   const { imgProps, containerProps } = useOptimizedImage({
+ *     src: '/image.jpg',
+ *     alt: 'Fixed aspect ratio',
+ *     aspectRatio: '16/9',
+ *     loading: 'lazy'
+ *   })
+ *   return (
+ *     <div {...containerProps}>
+ *       <img {...imgProps} />
+ *     </div>
+ *   )
+ * }
+ *
+ * // Complete example with all options
+ * function CompleteExample() {
+ *   const { imgProps, containerProps } = useOptimizedImage({
+ *     src: '/hero-1200w.jpg',
+ *     alt: 'Hero image with mountains',
+ *     srcSet: '/hero-640w.jpg 640w, /hero-1200w.jpg 1200w, /hero-1920w.jpg 1920w',
+ *     sizes: '(max-width: 640px) 100vw, (max-width: 1200px) 80vw, 1200px',
+ *     aspectRatio: '16/9',
+ *     loading: 'lazy',
+ *     decoding: 'async',
+ *     width: 1200,
+ *     className: 'hero-image'
+ *   })
+ *
+ *   return (
+ *     <div {...containerProps}>
+ *       <img {...imgProps} />
+ *     </div>
+ *   )
+ * }
+ * ```
+ *
+ * @param options - Configuration options for the optimized image
+ * @returns Object containing imgProps (and optionally containerProps)
+ */
+export declare function useOptimizedImage(options: UseOptimizedImageOptions): UseOptimizedImageResult;
+
+/**
+ * Options for the useOptimizedImage hook
+ */
+export declare interface UseOptimizedImageOptions {
+    /**
+     * Source URL for the image
+     */
+    src: string;
+    /**
+     * Alt text for accessibility (required)
+     */
+    alt: string;
+    /**
+     * Source set for responsive images
+     * @example "image-320w.jpg 320w, image-640w.jpg 640w, image-1024w.jpg 1024w"
+     */
+    srcSet?: string;
+    /**
+     * Sizes attribute for responsive images
+     * @example "(max-width: 640px) 100vw, 50vw"
+     */
+    sizes?: string;
+    /**
+     * Loading strategy
+     * - 'lazy': Load when near viewport (default, recommended for most images)
+     * - 'eager': Load immediately
+     */
+    loading?: 'lazy' | 'eager';
+    /**
+     * Decoding strategy
+     * - 'async': Decode asynchronously (default, recommended for performance)
+     * - 'sync': Decode synchronously
+     * - 'auto': Browser decides
+     */
+    decoding?: 'async' | 'sync' | 'auto';
+    /**
+     * Aspect ratio for placeholder (prevents layout shift)
+     * @example "16/9" or "1/1" or "4/3"
+     */
+    aspectRatio?: string;
+    /**
+     * Width of the image (used with aspectRatio to calculate height)
+     */
+    width?: number;
+    /**
+     * Height of the image (used with aspectRatio or standalone)
+     */
+    height?: number;
+    /**
+     * Additional CSS class names
+     */
+    className?: string;
+    /**
+     * Inline styles
+     */
+    style?: React.CSSProperties;
+}
+
+/**
+ * Return type for useOptimizedImage hook
+ */
+export declare interface UseOptimizedImageResult {
+    /**
+     * Props to spread onto an <img> element
+     */
+    imgProps: ImgHTMLAttributes<HTMLImageElement>;
+    /**
+     * Container props (if aspectRatio is used)
+     * Apply these to a wrapper div for proper aspect ratio handling
+     */
+    containerProps?: {
+        style: React.CSSProperties;
+        className?: string;
+    };
+}
+
 /**
  * A hook that determines whether a container element is "compact" by measuring its width.
  * Uses ResizeObserver to respond to container size changes.