klz-cables.com/components/cards/README.md

# Card Components

A comprehensive collection of specialized card components for displaying different content types from WordPress. These components provide consistent layouts across the site and replace the previous ProductList component.

## Overview

The card components are designed to work seamlessly with WordPress data structures from `lib/data.ts` and provide:

- **Consistent Design**: Unified styling and layout patterns
- **Responsive Design**: Works across all screen sizes
- **Internationalization**: Built-in support for multiple locales
- **Type Safety**: Full TypeScript support
- **Flexibility**: Multiple sizes and layouts
- **Performance**: Optimized with Next.js Image component

## Component Structure

```
components/cards/
├── BaseCard.tsx          # Foundation component
├── BlogCard.tsx          # Blog post cards
├── ProductCard.tsx       # Product cards
├── CategoryCard.tsx      # Category cards
├── CardGrid.tsx          # Grid wrapper
├── CardsExample.tsx      # Usage examples
├── index.ts              # Exports
└── README.md             # This file
```

## Components

### BaseCard

The foundation component that all other cards extend.

**Props:**
- `title`: Card title (ReactNode)
- `description`: Card description (ReactNode)
- `image`: Image URL (string)
- `imageAlt`: Image alt text (string)
- `size`: 'sm' | 'md' | 'lg'
- `layout`: 'vertical' | 'horizontal'
- `href`: Link URL (string)
- `badge`: Badge component (ReactNode)
- `footer`: Footer content (ReactNode)
- `header`: Header content (ReactNode)
- `loading`: Loading state (boolean)
- `hoverable`: Enable hover effects (boolean)
- `variant`: 'elevated' | 'flat' | 'bordered'
- `imageHeight`: 'sm' | 'md' | 'lg' | 'xl'

### BlogCard

Displays blog post information with featured image, title, excerpt, date, and categories.

**Props:**
- `post`: Post data from WordPress
- `showDate`: Display date (boolean)
- `showCategories`: Display categories (boolean)
- `readMoreText`: Read more link text (string)
- `excerptLength`: Excerpt character limit (number)
- `locale`: Formatting locale (string)

**Variations:**
- `BlogCardVertical` - Vertical layout
- `BlogCardHorizontal` - Horizontal layout
- `BlogCardSmall` - Small size
- `BlogCardLarge` - Large size

### ProductCard

Displays product information with image gallery, price, stock status, and actions.

**Props:**
- `product`: Product data from WordPress
- `showPrice`: Display price (boolean)
- `showStock`: Display stock status (boolean)
- `showSku`: Display SKU (boolean)
- `showCategories`: Display categories (boolean)
- `showAddToCart`: Show add to cart button (boolean)
- `showViewDetails`: Show view details button (boolean)
- `enableImageSwap`: Enable image hover swap (boolean)
- `locale`: Formatting locale (string)
- `onAddToCart`: Add to cart handler function

**Variations:**
- `ProductCardVertical` - Vertical layout
- `ProductCardHorizontal` - Horizontal layout
- `ProductCardSmall` - Small size
- `ProductCardLarge` - Large size

### CategoryCard

Displays category information with image/icon, name, description, and product count.

**Props:**
- `category`: Category data from WordPress
- `showCount`: Display product count (boolean)
- `showDescription`: Display description (boolean)
- `useIcon`: Use icon instead of image (boolean)
- `icon`: Custom icon component (ReactNode)
- `categoryType`: 'product' | 'blog'
- `locale`: Formatting locale (string)

**Variations:**
- `CategoryCardVertical` - Vertical layout
- `CategoryCardHorizontal` - Horizontal layout
- `CategoryCardSmall` - Small size
- `CategoryCardLarge` - Large size
- `CategoryCardIcon` - Icon-only variant

### CardGrid

Responsive grid wrapper for cards with loading and empty states.

**Props:**
- `items`: Array of card components (ReactNode[])
- `columns`: 1 | 2 | 3 | 4
- `gap`: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
- `loading`: Loading state (boolean)
- `emptyMessage`: Empty state message (string)
- `emptyComponent`: Custom empty component (ReactNode)
- `skeletonCount`: Loading skeleton count (number)
- `className`: Additional classes (string)
- `children`: Alternative to items (ReactNode)

**Variations:**
- `CardGrid2` - 2 columns
- `CardGrid3` - 3 columns
- `CardGrid4` - 4 columns
- `CardGridAuto` - Responsive auto columns

## Usage Examples

### Basic Blog Card

```tsx
import { BlogCard } from '@/components/cards';

<BlogCard 
  post={post}
  size="md"
  layout="vertical"
  showDate={true}
  showCategories={true}
  readMoreText="Weiterlesen"
/>
```

### Product Card with Cart

```tsx
import { ProductCard } from '@/components/cards';

<ProductCard 
  product={product}
  size="md"
  showPrice={true}
  showStock={true}
  showAddToCart={true}
  onAddToCart={(p) => console.log('Added:', p.name)}
/>
```

### Category Grid

```tsx
import { CategoryCard, CardGrid4 } from '@/components/cards';

<CardGrid4>
  {categories.map(category => (
    <CategoryCard 
      key={category.id}
      category={category}
      size="md"
      showCount={true}
    />
  ))}
</CardGrid4>
```

### Mixed Content Grid

```tsx
import { BlogCard, ProductCard, CategoryCard, CardGridAuto } from '@/components/cards';

<CardGridAuto>
  <BlogCard post={posts[0]} size="sm" />
  <ProductCard product={products[0]} size="sm" showPrice={true} />
  <CategoryCard category={categories[0]} size="sm" useIcon={true} />
</CardGridAuto>
```

## Integration with WordPress Data

All cards are designed to work with the WordPress data structures from `lib/data.ts`:

```tsx
import { getPostsForLocale, getProductsForLocale, getCategoriesForLocale } from '@/lib/data';

// Get data
const posts = getPostsForLocale('de');
const products = getProductsForLocale('de');
const categories = getCategoriesForLocale('de');

// Use in components
<CardGrid3>
  {products.map(product => (
    <ProductCard key={product.id} product={product} />
  ))}
</CardGrid3>
```

## Best Practices

1. **Always provide alt text** for images
2. **Use appropriate sizes**: sm for lists, md for grids, lg for featured
3. **Enable hover effects** for better UX
4. **Show loading states** when fetching data
5. **Handle empty states** gracefully
6. **Use locale prop** for internationalization
7. **Integrate with data layer** using types from `lib/data.ts`
8. **Use CardGrid** for consistent spacing and responsive layouts

## Responsive Design

All components are fully responsive:

- **Mobile**: Single column, stacked layout
- **Tablet**: 2 columns, optimized spacing
- **Desktop**: 3-4 columns, full features

## Accessibility

- Semantic HTML structure
- Proper ARIA labels
- Keyboard navigation support
- Screen reader friendly
- Focus indicators

## Performance

- Optimized with Next.js Image component
- Lazy loading for images
- Skeleton loading states
- Efficient rendering with proper keys
- Minimal bundle size

## Migration from ProductList

Replace the old ProductList with the new card components:

**Before:**
```tsx
import { ProductList } from '@/components/ProductList';

<ProductList products={products} locale="de" />
```

**After:**
```tsx
import { ProductCard, CardGrid3 } from '@/components/cards';

<CardGrid3>
  {products.map(product => (
    <ProductCard 
      key={product.id} 
      product={product}
      showPrice={true}
      showStock={true}
      onAddToCart={handleAddToCart}
    />
  ))}
</CardGrid3>
```

## TypeScript Support

All components include full TypeScript definitions:

```tsx
import { BlogCard, BlogCardProps } from '@/components/cards';
import { Post } from '@/lib/data';

const MyComponent: React.FC = () => {
  const post: Post = { /* ... */ };
  
  return <BlogCard post={post} />;
};
```

## Customization

All components support custom className props for additional styling:

```tsx
<BlogCard 
  post={post}
  className="custom-card"
  // ... other props
/>
```

## Future Enhancements

- [ ] Add animation variants
- [ ] Support for video backgrounds
- [ ] Lazy loading with Intersection Observer
- [ ] Progressive image loading
- [ ] Custom color schemes
- [ ] Drag and drop support
- [ ] Touch gestures for mobile

## Support

For questions or issues, refer to:
- `lib/data.ts` - Data structures
- `components/ui/` - UI components
- `components/cards/CardsExample.tsx` - Usage examples