npm package: @qwanyx/carousel
Description: Universal slide/presentation engine for Qwanyx ecosystem
Author: Qwanyx
Latest version: 0.1.23

# @qwanyx/carousel

Universal slide/presentation engine for the Qwanyx ecosystem.

## Features

- **Polymorphic slides**: Images, videos, documents, HTML, or custom React components
- **Multiple transitions**: Fade, slide, zoom, flip, cube
- **Rich navigation**: Arrows, dots, thumbnails, keyboard, touch/swipe
- **Presentation mode**: Fullscreen support with keyboard shortcuts
- **Autoplay**: With configurable intervals and pause-on-interaction
- **Responsive**: Adapts to any container size
- **TypeScript**: Full type safety

## Installation

```bash
npm install @qwanyx/carousel
```

## Quick Start

```tsx
import { Carousel, createSlide } from '@qwanyx/carousel';

const slides = [
  createSlide.image('1', '/photo1.jpg', { title: 'Beautiful sunset' }),
  createSlide.image('2', '/photo2.jpg', { title: 'Mountain view' }),
  createSlide.video('3', '/video.mp4', { poster: '/poster.jpg' }),
];

function MyGallery() {
  return (
    <Carousel
      slides={slides}
      transition="fade"
      navigation={{ arrows: true, dots: true }}
      allowFullscreen
    />
  );
}
```

## Slide Types

### Image Slide

```tsx
createSlide.image('id', '/image.jpg', {
  title: 'Image title',
  description: 'Description',
  alt: 'Alt text',
  objectFit: 'cover', // 'contain' | 'cover' | 'fill' | 'none'
});
```

### Video Slide

```tsx
createSlide.video('id', '/video.mp4', {
  poster: '/poster.jpg',
  autoplay: true,
  muted: true,
  loop: true,
  controls: true,
});
```

### Document Slide (PDF)

```tsx
createSlide.document('id', '/document.pdf', {
  title: 'My Document',
});
```

### HTML Slide

```tsx
createSlide.html('id', '<div>Custom HTML content</div>', {
  title: 'HTML Slide',
});
```

### Component Slide

```tsx
createSlide.component('id', () => <MyCustomComponent />, {
  title: 'Custom Component',
});
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `slides` | `Slide[]` | required | Array of slides |
| `initialIndex` | `number` | `0` | Starting slide index |
| `transition` | `TransitionType` | `'fade'` | Transition animation |
| `transitionDuration` | `number` | `300` | Duration in ms |
| `navigation` | `NavigationOptions \| boolean` | `true` | Navigation controls |
| `autoplay` | `AutoplayOptions \| boolean` | `false` | Autoplay settings |
| `loop` | `boolean` | `false` | Enable infinite loop |
| `aspectRatio` | `string` | `'16/9'` | Container aspect ratio |
| `allowFullscreen` | `boolean` | `true` | Enable fullscreen mode |
| `theme` | `'light' \| 'dark'` | `'dark'` | Color theme |
| `onSlideChange` | `function` | - | Callback on slide change |

## Keyboard Shortcuts

| Key | Action |
|-----|--------|
| `←` `↑` | Previous slide |
| `→` `↓` | Next slide |
| `Space` | Play/pause autoplay |
| `F` | Toggle fullscreen |
| `Esc` | Exit fullscreen |

## Ref Methods

```tsx
const carouselRef = useRef<CarouselRef>(null);

// Available methods:
carouselRef.current?.next();
carouselRef.current?.prev();
carouselRef.current?.goTo(2);
carouselRef.current?.getCurrentIndex();
carouselRef.current?.enterFullscreen();
carouselRef.current?.exitFullscreen();
carouselRef.current?.toggleFullscreen();
carouselRef.current?.play();
carouselRef.current?.pause();
```

## License

MIT