🎠 Kedo React Carousel

A responsive, touch-enabled carousel component for React with Next.js support and comprehensive test coverage.

✨ Features

• 📱 Responsive Design - Adapts to different screen sizes
• 👆 Touch/Swipe Support - Mobile-friendly touch gestures
• ⚡ Next.js Compatible - SSR support out of the box
• 🎯 Auto Play - Optional automatic slide progression
• 🎨 Customizable - Custom navigation buttons and dots
• 🧪 Well Tested - 80%+ test coverage
• 📦 Lightweight - Minimal dependencies
• ♿ Accessible - ARIA compliant

📊 Test Coverage

Our carousel component is thoroughly tested with comprehensive unit tests:

| Metric | Coverage | |--------|----------| | Statements | 85%+ | | Branches | 80%+ | | Functions | 90%+ | | Lines | 85%+ |

🚀 Installation

npm install kedo-react-carousel

📖 Usage

Basic Usage

import React from 'react';
import Carousel from 'kedo-react-carousel';

function App() {
  return (
    <Carousel>
      <div>Slide 1</div>
      <div>Slide 2</div>
      <div>Slide 3</div>
    </Carousel>
  );
}

Advanced Usage

import React from 'react';
import Carousel from 'kedo-react-carousel';

function App() {
  const handleSlideChange = (slideIndex, direction) => {
    console.log(`Moved to slide ${slideIndex} via ${direction}`);
  };

  return (
    <Carousel
      slidesToShow={3}
      slidesToScroll={1}
      autoPlay={true}
      autoPlayTimer={3000}
      pauseOnHover={true}
      showDots={true}
      responsive={[
        {
          breakpoint: 768,
          settings: {
            slidesToShow: 2,
            slidesToScroll: 1
          }
        },
        {
          breakpoint: 480,
          settings: {
            slidesToShow: 1,
            slidesToScroll: 1
          }
        }
      ]}
      onSlideChange={handleSlideChange}
    >
      <div>Slide 1</div>
      <div>Slide 2</div>
      <div>Slide 3</div>
      <div>Slide 4</div>
      <div>Slide 5</div>
    </Carousel>
  );
}

🔧 Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | children | ReactNode | - | Slides content | | slidesToShow | number | 1 | Number of slides to show | | slidesToScroll | number | 1 | Number of slides to scroll | | autoPlay | boolean | false | Enable auto play | | autoPlayTimer | number | 1000 | Auto play interval (ms) | | pauseOnHover | boolean | false | Pause auto play on hover | | showDots | boolean | false | Show navigation dots | | responsive | ResponsiveSettings[] | [] | Responsive breakpoints | | nextButton | ReactElement | - | Custom next button | | prevButton | ReactElement | - | Custom prev button | | dotComponent | ComponentType<DotProps> | - | Custom dot component | | onSlideChange | function | - | Slide change callback |

🧪 Testing

Run the test suite:

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in CI mode
npm run test:ci

# Generate test report
npm run test:report

Test Structure

Our test suite covers:

• ✅ Component Rendering - Ensures all components render correctly
• ✅ Navigation Logic - Tests next/prev button functionality
• ✅ Auto Play - Validates automatic slide progression
• ✅ Touch/Swipe - Tests mobile touch interactions
• ✅ Responsive Behavior - Validates breakpoint handling
• ✅ Custom Components - Tests custom button and dot components
• ✅ Edge Cases - Handles empty slides, single slides, etc.
• ✅ Cleanup - Ensures proper cleanup of timers and listeners

📈 Quality Metrics

• Test Coverage: 85%+ overall coverage
• Code Quality: ESLint compliant
• Performance: Optimized for minimal re-renders
• Accessibility: ARIA compliant navigation
• Browser Support: Modern browsers + IE11

🔄 CI/CD Pipeline

Our package includes automated testing and publishing:

GitHub Actions Workflows

1. Test Workflow (.github/workflows/test.yml)

   • Runs on Node.js 16.x, 18.x, 20.x
   • Executes full test suite
   • Generates coverage reports
   • Uploads to Codecov
   • Comments coverage on PRs

2. Publish Workflow (.github/workflows/publish.yml)

   • Triggers on GitHub releases
   • Runs tests before publishing
   • Publishes to NPM automatically
   • Updates release with publish status

Setting Up CI/CD

1. Add NPM Token: Add NPM_TOKEN to GitHub repository secrets
2. Enable Codecov: Connect your repository to Codecov
3. Configure Badges: Update badge URLs in README

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Ensure tests pass (npm test)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/ppuneet64/kedo-react-carousel.git

# Install dependencies
npm install

# Run tests
npm test

# Build the package
npm run build

# Run example
npm run dev

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• React team for the amazing framework
• Testing Library for excellent testing utilities
• All contributors who help improve this package

Made with ❤️ by Puneet Pandey