migration wip
This commit is contained in:
319
components/cards/README.md
Normal file
319
components/cards/README.md
Normal file
@@ -0,0 +1,319 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user