story-az-card-kit/README.md

A flexible and customizable story card component with multiple layouts

# Story Card Component

A flexible and customizable story card component library with multiple layouts, themes, and interactive features. Built with React and vanilla JavaScript support.

## Features

- 🎨 **Multiple Layouts**: Vertical, Horizontal, Grid, Masonry, Carousel, and Flip cards
- 🌈 **5 Beautiful Themes**: Default, Dark, Minimal, Elegant, and Modern
- 📱 **Fully Responsive**: Works perfectly on all device sizes
- ⚡ **Performance Optimized**: Lazy loading, smooth animations, and efficient rendering
- 🎯 **Accessible**: ARIA labels, keyboard navigation, and screen reader support
- 🔧 **Highly Customizable**: Extensive props and CSS custom properties
- 🚀 **Vanilla JS Support**: Can be used without React
- 📦 **Zero Dependencies**: Lightweight and fast

## Installation

```bash
npm install story-card-component
```

## Quick Start

### React Usage

```jsx
import React from 'react';
import { StoryCard, GridCard, CarouselCard } from 'story-card-component';

function App() {
  const story = {
    title: "Amazing Adventure",
    description: "An incredible journey through unknown lands...",
    image: "https://example.com/image.jpg",
    author: "John Doe",
    date: "2024-01-15",
    tags: ["Adventure", "Travel"]
  };

  return (
    <div>
      {/* Single Story Card */}
      <StoryCard {...story} />
      
      {/* Grid Layout */}
      <GridCard 
        stories={[story, story, story]} 
        columns={3} 
        theme="modern" 
      />
      
      {/* Carousel Layout */}
      <CarouselCard 
        stories={[story, story, story]} 
        autoPlay={true} 
        theme="elegant" 
      />
    </div>
  );
}
```

### Vanilla JavaScript Usage

```javascript
import { createStoryCard, StoryCardManager } from 'story-card-component';

// Create a single card
const card = createStoryCard({
  title: "Amazing Adventure",
  description: "An incredible journey through unknown lands...",
  image: "https://example.com/image.jpg",
  author: "John Doe",
  date: "2024-01-15",
  tags: ["Adventure", "Travel"],
  theme: "modern",
  onClick: (e, data) => console.log('Card clicked:', data)
});

document.body.appendChild(card);

// Create a managed grid
const manager = new StoryCardManager('#container', {
  stories: [story1, story2, story3],
  columns: 3,
  theme: 'modern',
  onCardClick: (story) => console.log('Story clicked:', story)
});
```

## Layouts

### 1. Vertical Card (Default)
```jsx
<StoryCard 
  title="Story Title"
  description="Story description..."
  image="image-url.jpg"
  layout="vertical"
  theme="default"
/>
```

### 2. Horizontal Card
```jsx
<HorizontalCard 
  title="Story Title"
  description="Story description..."
  image="image-url.jpg"
  imagePosition="left" // or "right"
  theme="elegant"
/>
```

### 3. Grid Layout
```jsx
<GridCard 
  stories={storiesArray}
  columns={3} // 1-6 columns
  gap="medium" // "small", "medium", "large"
  theme="modern"
  responsive={true}
  onCardClick={(e, data, index) => console.log('Card clicked:', index)}
/>
```

### 4. Masonry Layout
```jsx
<MasonryCard 
  stories={storiesArray}
  columns={3} // 2-5 columns
  gap="medium"
  theme="minimal"
  onCardClick={(e, data, index) => console.log('Card clicked:', index)}
/>
```

### 5. Carousel Layout
```jsx
<CarouselCard 
  stories={storiesArray}
  autoPlay={true}
  autoPlayInterval={3000}
  showArrows={true}
  showDots={true}
  theme="dark"
  onCardClick={(e, data, index) => console.log('Card clicked:', index)}
/>
```

### 6. Flip Card
```jsx
<FlipCard 
  frontContent={<StoryCard {...frontStory} />}
  backContent={<StoryCard {...backStory} />}
  flipDirection="horizontal" // or "vertical"
  autoFlip={false}
  autoFlipInterval={5000}
  theme="elegant"
/>
```

## Themes

### Available Themes:
- **default**: Clean and modern design
- **dark**: Dark mode with light text
- **minimal**: Simple border design
- **elegant**: Gradient background with serif fonts
- **modern**: Bold typography with larger spacing

```jsx
<StoryCard 
  title="Story Title"
  description="Story description..."
  theme="dark" // Choose your theme
/>
```

## Props Reference

### StoryCard Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | string | - | Card title |
| `description` | string | - | Card description |
| `image` | string | - | Image URL |
| `author` | string | - | Author name |
| `date` | string | - | Publication date |
| `tags` | string[] | [] | Array of tags |
| `layout` | string | 'vertical' | Layout type |
| `theme` | string | 'default' | Theme type |
| `onClick` | function | - | Click handler |
| `className` | string | - | Additional CSS classes |

### GridCard Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `stories` | array | [] | Array of story objects |
| `columns` | number | 3 | Number of columns (1-6) |
| `gap` | string | 'medium' | Gap size between cards |
| `theme` | string | 'default' | Theme for all cards |
| `responsive` | boolean | true | Enable responsive behavior |
| `onCardClick` | function | - | Click handler for cards |

### CarouselCard Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `stories` | array | [] | Array of story objects |
| `autoPlay` | boolean | false | Enable auto-play |
| `autoPlayInterval` | number | 3000 | Auto-play interval in ms |
| `showArrows` | boolean | true | Show navigation arrows |
| `showDots` | boolean | true | Show pagination dots |
| `theme` | string | 'default' | Theme for all cards |

## CSS Custom Properties

You can customize the appearance using CSS custom properties:

```css
:root {
  /* Colors */
  --story-card-primary: #3b82f6;
  --story-card-secondary: #64748b;
  
  /* Typography */
  --story-card-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
  --story-card-font-size-base: 1rem;
  
  /* Spacing */
  --story-card-spacing-md: 1rem;
  --story-card-spacing-lg: 1.5rem;
  
  /* Border radius */
  --story-card-radius-lg: 0.75rem;
  
  /* Shadows */
  --story-card-shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
  
  /* Transitions */
  --story-card-transition-normal: 250ms ease-in-out;
}
```

## Advanced Usage

### StoryCardManager (Vanilla JS)

```javascript
import { StoryCardManager } from 'story-card-component';

const manager = new StoryCardManager('#container', {
  stories: storiesArray,
  layout: 'grid',
  theme: 'modern',
  columns: 3,
  itemsPerPage: 12,
  sortBy: 'date',
  sortOrder: 'desc',
  onCardClick: (story) => console.log('Story clicked:', story)
});

// Filter by tags
manager.filterByTags(['Adventure', 'Travel']);

// Search stories
manager.search('amazing');

// Sort stories
manager.sortBy('title', 'asc');

// Navigate pages
manager.nextPage();
manager.previousPage();
manager.goToPage(3);

// Add new story
manager.addStory(newStory);

// Update story
manager.updateStory(0, updatedStory);

// Remove story
manager.removeStory(0);

// Get current state
const state = manager.getState();
```

### Custom Styling

```css
/* Custom card styles */
.story-card {
  border: 2px solid #e2e8f0;
  transition: all 0.3s ease;
}

.story-card:hover {
  border-color: #3b82f6;
  transform: translateY(-8px);
}

/* Custom theme */
.story-card--custom {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
}

.story-card--custom .story-card__title {
  color: white;
  text-shadow: 0 2px 4px rgba(0,0,0,0.3);
}
```

## Browser Support

- Chrome 60+
- Firefox 55+
- Safari 12+
- Edge 79+

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Changelog

### v1.0.0
- Initial release
- 6 different layouts
- 5 beautiful themes
- React and vanilla JS support
- Full responsive design
- Accessibility features
- Performance optimizations

## Support

If you have any questions or need help, please open an issue on GitHub or contact us at support@example.com.