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

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

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

Product Card with Cart

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

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

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

Mixed Content Grid

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:

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:

import { ProductList } from '@/components/ProductList';

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

After:

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:

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:

<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