npm package: @jojomohojo/image-carousel
Description: Simple carousel module with navigation and autoplay
Author: Joe Pattenden
Latest version: 1.0.0

# simple-carousel

A lightweight, dependency-free JavaScript carousel module with autoplay, navigation arrows, and dot indicators.

Ideal for projects needing a plug-and-play carousel component with no framework or build tools required.

## Installation

Install from npm:

```
npm install simple-carousel
```

## Usage

### HTML Structure (required)

```html
<div class="carousel">
  <div class="carousel-frame">
    <div class="carousel-track">
      <img src="1.jpg" class="carousel-image" />
      <img src="2.jpg" class="carousel-image" />
      <img src="3.jpg" class="carousel-image" />
    </div>
  </div>
  <button class="back-arrow">←</button>
  <button class="forward-arrow">→</button>
  <div class="navigation"></div>
</div>
```

### JavaScript

```js
import { initCarousel } from 'simple-carousel';

const container = document.querySelector('.carousel');
const { cleanup } = initCarousel(container);

// Optional: call cleanup() if the carousel is removed from the DOM
// cleanup();
```

## Expected HTML Classes

Your markup should include the following class names for proper behavior:

| Class Name         | Description                                      |
|--------------------|--------------------------------------------------|
| .carousel          | Main carousel container (pass this to the module)|
| .carousel-frame    | The visible window for images                    |
| .carousel-track    | The inner track that slides left/right           |
| .carousel-image    | Each image in the carousel                       |
| .back-arrow        | Button to navigate to the previous image         |
| .forward-arrow     | Button to navigate to the next image             |
| .navigation        | Container for the auto-generated dots            |

## Features

- Auto-play with pause on hover
- Navigation arrows
- Dot indicators
- Resizes dynamically
- Keyboard-friendly dot navigation
- No dependencies
- cleanup() support for single-page apps

## API

### initCarousel(container: HTMLElement): { cleanup: () => void }

- container: The root DOM element containing the carousel
- Returns: An object with a cleanup() function that removes all event listeners and intervals created by the module

## Customization

You can style the carousel freely using CSS. Here’s an example to get started:

```css
.carousel {
  position: relative;
  overflow: hidden;
}

.carousel-frame {
  width: 100%;
}

.carousel-track {
  display: flex;
  transition: transform 0.4s ease;
}

.carousel-image {
  min-width: 100%;
  object-fit: cover;
}

.navigation {
  display: flex;
  justify-content: center;
  margin-top: 10px;
}

.dot {
  width: 10px;
  height: 10px;
  margin: 0 5px;
  border-radius: 50%;
  background: #ccc;
  cursor: pointer;
}

.active-dot {
  background: #333;
}
```

## Example

```js
const carousel = document.querySelector('.carousel');
const { cleanup } = initCarousel(carousel);

// Later if needed
// cleanup();
```

## License

MIT

## Contributions

Contributions and issues are welcome! Open a pull request or submit an issue if you find a bug or want to suggest an improvement.