@zomako/elearning-components 1.0.0

package/FlashcardDeck/FlashcardDeck.css

@@ -0,0 +1,134 @@
+.flashcard-deck-container {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 2rem;
+  padding: 2rem;
+  max-width: 600px;
+  margin: 0 auto;
+}
+
+.flashcard-deck-header {
+  width: 100%;
+  text-align: center;
+}
+
+.flashcard-counter {
+  font-size: 1rem;
+  color: #666;
+  font-weight: 500;
+}
+
+.flashcard-wrapper {
+  perspective: 1000px;
+  width: 100%;
+  min-height: 300px;
+}
+
+.flashcard {
+  position: relative;
+  width: 100%;
+  height: 300px;
+  cursor: pointer;
+  transform-style: preserve-3d;
+}
+
+.flashcard-face {
+  position: absolute;
+  width: 100%;
+  height: 100%;
+  backface-visibility: hidden;
+  border-radius: 12px;
+  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1), 0 2px 4px rgba(0, 0, 0, 0.06);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 2rem;
+  box-sizing: border-box;
+}
+
+.flashcard-front {
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  color: white;
+  transform: rotateY(0deg);
+}
+
+.flashcard-back {
+  background: linear-gradient(135deg, #f093fb 0%, #f5576c 100%);
+  color: white;
+  transform: rotateY(180deg);
+}
+
+.flashcard-content {
+  font-size: 1.25rem;
+  text-align: center;
+  word-wrap: break-word;
+  overflow-wrap: break-word;
+  line-height: 1.6;
+  font-weight: 500;
+}
+
+.flashcard-controls {
+  display: flex;
+  gap: 1rem;
+  width: 100%;
+  justify-content: center;
+}
+
+.flashcard-button {
+  padding: 0.75rem 2rem;
+  font-size: 1rem;
+  font-weight: 600;
+  border: none;
+  border-radius: 8px;
+  cursor: pointer;
+  transition: all 0.3s ease;
+  background-color: #667eea;
+  color: white;
+  min-width: 120px;
+}
+
+.flashcard-button:hover:not(:disabled) {
+  background-color: #5568d3;
+  transform: translateY(-2px);
+  box-shadow: 0 4px 8px rgba(102, 126, 234, 0.3);
+}
+
+.flashcard-button:active:not(:disabled) {
+  transform: translateY(0);
+}
+
+.flashcard-button:disabled {
+  background-color: #e0e0e0;
+  color: #9e9e9e;
+  cursor: not-allowed;
+  opacity: 0.6;
+}
+
+.flashcard-empty-message {
+  text-align: center;
+  color: #666;
+  font-size: 1.1rem;
+  padding: 2rem;
+}
+
+/* Responsive design */
+@media (max-width: 768px) {
+  .flashcard-deck-container {
+    padding: 1rem;
+  }
+
+  .flashcard {
+    height: 250px;
+  }
+
+  .flashcard-content {
+    font-size: 1.1rem;
+  }
+
+  .flashcard-button {
+    padding: 0.625rem 1.5rem;
+    font-size: 0.9rem;
+    min-width: 100px;
+  }
+}

package/FlashcardDeck/FlashcardDeck.jsx

@@ -0,0 +1,87 @@
+import React, { useState } from 'react';
+import { motion } from 'framer-motion';
+import './FlashcardDeck.css';
+
+const FlashcardDeck = ({ cards = [] }) => {
+  const [currentIndex, setCurrentIndex] = useState(0);
+  const [isFlipped, setIsFlipped] = useState(false);
+
+  if (!cards || cards.length === 0) {
+    return (
+      <div className="flashcard-deck-container">
+        <p className="flashcard-empty-message">No cards available</p>
+      </div>
+    );
+  }
+
+  const currentCard = cards[currentIndex];
+  const canGoPrevious = currentIndex > 0;
+  const canGoNext = currentIndex < cards.length - 1;
+
+  const handlePrevious = () => {
+    if (canGoPrevious) {
+      setCurrentIndex(currentIndex - 1);
+      setIsFlipped(false);
+    }
+  };
+
+  const handleNext = () => {
+    if (canGoNext) {
+      setCurrentIndex(currentIndex + 1);
+      setIsFlipped(false);
+    }
+  };
+
+  const handleCardClick = () => {
+    setIsFlipped(!isFlipped);
+  };
+
+  return (
+    <div className="flashcard-deck-container">
+      <div className="flashcard-deck-header">
+        <span className="flashcard-counter">
+          Card {currentIndex + 1} of {cards.length}
+        </span>
+      </div>
+
+      <div className="flashcard-wrapper">
+        <motion.div
+          key={currentIndex}
+          className="flashcard"
+          onClick={handleCardClick}
+          animate={{ rotateY: isFlipped ? 180 : 0 }}
+          transition={{ duration: 0.6, type: 'spring', stiffness: 100 }}
+          style={{ transformStyle: 'preserve-3d' }}
+        >
+          <div className="flashcard-face flashcard-front">
+            <div className="flashcard-content">{currentCard.front}</div>
+          </div>
+          <div className="flashcard-face flashcard-back">
+            <div className="flashcard-content">{currentCard.back}</div>
+          </div>
+        </motion.div>
+      </div>
+
+      <div className="flashcard-controls">
+        <button
+          className="flashcard-button flashcard-button-previous"
+          onClick={handlePrevious}
+          disabled={!canGoPrevious}
+          aria-label="Previous card"
+        >
+          Previous
+        </button>
+        <button
+          className="flashcard-button flashcard-button-next"
+          onClick={handleNext}
+          disabled={!canGoNext}
+          aria-label="Next card"
+        >
+          Next
+        </button>
+      </div>
+    </div>
+  );
+};
+
+export default FlashcardDeck;

package/FlashcardDeck/FlashcardDeck.tsx

@@ -0,0 +1,96 @@
+import React, { useState } from 'react';
+import { motion } from 'framer-motion';
+import './FlashcardDeck.css';
+
+export interface Flashcard {
+  front: string;
+  back: string;
+}
+
+interface FlashcardDeckProps {
+  cards?: Flashcard[];
+}
+
+const FlashcardDeck: React.FC<FlashcardDeckProps> = ({ cards = [] }) => {
+  const [currentIndex, setCurrentIndex] = useState<number>(0);
+  const [isFlipped, setIsFlipped] = useState<boolean>(false);
+
+  if (!cards || cards.length === 0) {
+    return (
+      <div className="flashcard-deck-container">
+        <p className="flashcard-empty-message">No cards available</p>
+      </div>
+    );
+  }
+
+  const currentCard = cards[currentIndex];
+  const canGoPrevious = currentIndex > 0;
+  const canGoNext = currentIndex < cards.length - 1;
+
+  const handlePrevious = (): void => {
+    if (canGoPrevious) {
+      setCurrentIndex(currentIndex - 1);
+      setIsFlipped(false);
+    }
+  };
+
+  const handleNext = (): void => {
+    if (canGoNext) {
+      setCurrentIndex(currentIndex + 1);
+      setIsFlipped(false);
+    }
+  };
+
+  const handleCardClick = (): void => {
+    setIsFlipped(!isFlipped);
+  };
+
+  return (
+    <div className="flashcard-deck-container">
+      <div className="flashcard-deck-header">
+        <span className="flashcard-counter">
+          Card {currentIndex + 1} of {cards.length}
+        </span>
+      </div>
+
+      <div className="flashcard-wrapper">
+        <motion.div
+          key={currentIndex}
+          className="flashcard"
+          onClick={handleCardClick}
+          animate={{ rotateY: isFlipped ? 180 : 0 }}
+          transition={{ duration: 0.6, type: 'spring', stiffness: 100 }}
+          style={{ transformStyle: 'preserve-3d' }}
+        >
+          <div className="flashcard-face flashcard-front">
+            <div className="flashcard-content">{currentCard.front}</div>
+          </div>
+          <div className="flashcard-face flashcard-back">
+            <div className="flashcard-content">{currentCard.back}</div>
+          </div>
+        </motion.div>
+      </div>
+
+      <div className="flashcard-controls">
+        <button
+          className="flashcard-button flashcard-button-previous"
+          onClick={handlePrevious}
+          disabled={!canGoPrevious}
+          aria-label="Previous card"
+        >
+          Previous
+        </button>
+        <button
+          className="flashcard-button flashcard-button-next"
+          onClick={handleNext}
+          disabled={!canGoNext}
+          aria-label="Next card"
+        >
+          Next
+        </button>
+      </div>
+    </div>
+  );
+};
+
+export default FlashcardDeck;

package/FlashcardDeck/README.md

@@ -0,0 +1,313 @@
+# FlashcardDeck Component
+
+A fully-featured, reusable React component for displaying interactive flashcards with smooth 3D flip animations. Perfect for e-learning applications, study tools, quiz systems, and any scenario where you need to present information in a card-based format with front and back sides.
+
+## Purpose
+
+The `FlashcardDeck` component provides an engaging way to display educational content, study materials, or any paired information. It allows users to:
+
+- View one card at a time from a deck of flashcards
+- Click on cards to flip them and reveal the back side with a smooth 3D animation
+- Navigate through the deck using Previous and Next buttons
+- Track their progress with a card counter
+
+The component is built with React and uses Framer Motion for smooth, performant animations. It's fully self-contained, responsive, and accessible.
+
+## Features
+
+- **3D Flip Animation**: Smooth, spring-based 3D rotation animation powered by Framer Motion
+- **Card Navigation**: Previous and Next buttons to move through the deck
+- **Progress Tracking**: Displays current card position (e.g., "Card 1 of 10")
+- **Responsive Design**: Optimized for both desktop and mobile devices
+- **Accessibility**: Includes ARIA labels for screen readers
+- **Empty State Handling**: Gracefully handles empty or missing card arrays
+- **Auto-reset**: Automatically resets flip state when navigating to a new card
+- **Disabled States**: Navigation buttons are properly disabled at deck boundaries
+
+## Installation
+
+### Prerequisites
+
+- React 16.8+ (hooks support required)
+- Node.js and npm (or yarn/pnpm)
+
+### Install Dependencies
+
+```bash
+npm install react react-dom framer-motion
+```
+
+Or with yarn:
+
+```bash
+yarn add react react-dom framer-motion
+```
+
+Or with pnpm:
+
+```bash
+pnpm add react react-dom framer-motion
+```
+
+## Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `cards` | `Array<{front: string, back: string}>` | No | `[]` | An array of flashcard objects. Each object must have a `front` property (string) representing the front side text and a `back` property (string) representing the back side text. If not provided or empty, the component displays an empty state message. |
+
+### TypeScript Interface
+
+If you're using TypeScript, you can import the type definitions:
+
+```typescript
+import FlashcardDeck, { Flashcard } from './FlashcardDeck/FlashcardDeck';
+
+// Flashcard interface
+interface Flashcard {
+  front: string;
+  back: string;
+}
+
+// Component props interface
+interface FlashcardDeckProps {
+  cards?: Flashcard[];
+}
+```
+
+## Usage
+
+### Basic Example
+
+```jsx
+import React from 'react';
+import FlashcardDeck from './FlashcardDeck/FlashcardDeck';
+
+const App = () => {
+  const cards = [
+    {
+      front: 'What is React?',
+      back: 'React is a JavaScript library for building user interfaces, particularly web applications. It allows developers to create reusable UI components.',
+    },
+    {
+      front: 'What is JSX?',
+      back: 'JSX is a syntax extension for JavaScript that looks similar to HTML. It allows you to write HTML-like code in your JavaScript files.',
+    },
+    {
+      front: 'What is a component?',
+      back: 'A component is a reusable piece of code that returns JSX. Components can be functional or class-based and help organize your UI into manageable pieces.',
+    },
+  ];
+
+  return <FlashcardDeck cards={cards} />;
+};
+
+export default App;
+```
+
+### TypeScript Example
+
+```tsx
+import React from 'react';
+import FlashcardDeck, { Flashcard } from './FlashcardDeck/FlashcardDeck';
+
+const App: React.FC = () => {
+  const cards: Flashcard[] = [
+    {
+      front: 'Capital of France?',
+      back: 'Paris',
+    },
+    {
+      front: 'Capital of Japan?',
+      back: 'Tokyo',
+    },
+    {
+      front: 'Capital of Australia?',
+      back: 'Canberra',
+    },
+  ];
+
+  return <FlashcardDeck cards={cards} />;
+};
+
+export default App;
+```
+
+### Dynamic Card Loading Example
+
+```jsx
+import React, { useState, useEffect } from 'react';
+import FlashcardDeck from './FlashcardDeck/FlashcardDeck';
+
+const App = () => {
+  const [cards, setCards] = useState([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    // Simulate API call
+    fetch('/api/flashcards')
+      .then((res) => res.json())
+      .then((data) => {
+        setCards(data);
+        setLoading(false);
+      })
+      .catch((error) => {
+        console.error('Error loading cards:', error);
+        setLoading(false);
+      });
+  }, []);
+
+  if (loading) {
+    return <div>Loading flashcards...</div>;
+  }
+
+  return <FlashcardDeck cards={cards} />;
+};
+
+export default App;
+```
+
+### Empty State Example
+
+```jsx
+import React from 'react';
+import FlashcardDeck from './FlashcardDeck/FlashcardDeck';
+
+const App = () => {
+  // Component will display "No cards available" message
+  return <FlashcardDeck cards={[]} />;
+};
+```
+
+## Component Structure
+
+```
+FlashcardDeck/
+├── FlashcardDeck.jsx    # Main component file (JavaScript)
+├── FlashcardDeck.tsx    # Main component file (TypeScript)
+├── FlashcardDeck.css    # Component styles
+├── index.js             # Export file
+└── README.md           # This documentation
+```
+
+## Styling
+
+The component includes its own CSS file with customizable styles. You can override the default styles by targeting the following CSS classes:
+
+### Available CSS Classes
+
+- `.flashcard-deck-container` - Main container wrapper
+- `.flashcard-deck-header` - Header section containing the card counter
+- `.flashcard-counter` - Card position counter text
+- `.flashcard-wrapper` - Wrapper with 3D perspective
+- `.flashcard` - Card container with 3D transform
+- `.flashcard-face` - Base class for both card faces
+- `.flashcard-front` - Front side of the card (purple gradient)
+- `.flashcard-back` - Back side of the card (pink gradient)
+- `.flashcard-content` - Content wrapper inside each card face
+- `.flashcard-controls` - Container for navigation buttons
+- `.flashcard-button` - Base button styles
+- `.flashcard-button-previous` - Previous button
+- `.flashcard-button-next` - Next button
+- `.flashcard-empty-message` - Empty state message
+
+### Custom Styling Example
+
+```css
+/* Override card colors */
+.flashcard-front {
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+}
+
+.flashcard-back {
+  background: linear-gradient(135deg, #f093fb 0%, #f5576c 100%);
+}
+
+/* Customize button styles */
+.flashcard-button {
+  background-color: #4CAF50;
+  border-radius: 20px;
+}
+
+.flashcard-button:hover:not(:disabled) {
+  background-color: #45a049;
+}
+```
+
+## Animation Details
+
+The component uses Framer Motion for animations:
+
+- **Flip Animation**: Spring-based rotation on the Y-axis (180 degrees)
+- **Duration**: 0.6 seconds
+- **Animation Type**: Spring with stiffness of 100
+- **3D Transform**: Uses CSS `transform-style: preserve-3d` for proper 3D rendering
+- **Backface Visibility**: Hidden to ensure only the visible side is shown during rotation
+
+## Browser Support
+
+Works in all modern browsers that support:
+- CSS 3D Transforms
+- ES6+ JavaScript
+- React 16.8+ (hooks)
+
+Tested and working in:
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- Mobile browsers (iOS Safari, Chrome Mobile)
+
+## Accessibility
+
+The component includes accessibility features:
+
+- ARIA labels on navigation buttons (`aria-label="Previous card"` and `aria-label="Next card"`)
+- Semantic HTML structure
+- Keyboard navigation support (buttons are focusable)
+- Disabled state indicators for navigation buttons
+
+## Performance Considerations
+
+- Uses React hooks for efficient state management
+- Framer Motion handles GPU-accelerated animations
+- Minimal re-renders (only updates when necessary)
+- CSS transforms for smooth animations without layout shifts
+
+## Common Use Cases
+
+1. **Language Learning**: Vocabulary flashcards with words and translations
+2. **Study Tools**: Question and answer flashcards for exam preparation
+3. **Training Materials**: Concept explanations with detailed descriptions
+4. **Quiz Systems**: Interactive quiz questions with answers
+5. **Memory Games**: Matching games with clues and solutions
+
+## Troubleshooting
+
+### Cards not flipping
+
+- Ensure Framer Motion is properly installed: `npm install framer-motion`
+- Check that the CSS file is imported correctly
+- Verify that both `front` and `back` properties exist on each card object
+
+### Navigation buttons not working
+
+- Ensure cards array is not empty
+- Check browser console for any JavaScript errors
+- Verify that cards prop is passed correctly
+
+### Styling issues
+
+- Make sure `FlashcardDeck.css` is imported in your component
+- Check for CSS conflicts with your global styles
+- Verify that CSS classes are not being overridden unintentionally
+
+## License
+
+This component is part of the e-learning-components project. Use it freely in your projects.
+
+## Contributing
+
+Contributions are welcome! Please ensure that:
+- Code follows React best practices
+- Animations remain smooth and performant
+- Accessibility features are maintained
+- Documentation is updated accordingly

package/FlashcardDeck/index.js

@@ -0,0 +1 @@
+export { default } from './FlashcardDeck';

package/README.md

@@ -0,0 +1,53 @@
+# E-learning Components
+
+A collection of reusable React components for e-learning applications.
+
+## Components
+
+### FlashcardDeck
+
+A fully-featured flashcard component with 3D flip animations. See `FlashcardDeck/README.md` for detailed documentation.
+
+## Getting Started
+
+### Installation
+
+```bash
+npm install
+```
+
+### Development
+
+```bash
+npm run dev
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+## Project Structure
+
+```
+elearning-components/
+├── FlashcardDeck/          # FlashcardDeck component
+│   ├── FlashcardDeck.jsx   # Component (JavaScript)
+│   ├── FlashcardDeck.tsx   # Component (TypeScript)
+│   ├── FlashcardDeck.css   # Styles
+│   ├── index.js            # Export
+│   └── README.md           # Documentation
+├── src/                    # Application source
+│   ├── App.jsx             # Demo app
+│   └── main.jsx            # Entry point
+├── package.json            # Dependencies
+├── vite.config.js          # Vite configuration
+└── README.md               # This file
+```
+
+## Technologies
+
+- React 18
+- Framer Motion
+- Vite