@qwanyx/carousel 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# @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

package/dist/index.d.mts

@@ -0,0 +1,372 @@
+import React, { CSSProperties, ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Position in the slide (percentage-based for responsiveness)
+ */
+interface Position {
+    x: number;
+    y: number;
+}
+/**
+ * Size of an object
+ */
+interface Size {
+    width: number;
+    height: number;
+    unit?: 'percent' | 'px';
+}
+/**
+ * Transform properties
+ */
+interface Transform {
+    rotation?: number;
+    scaleX?: number;
+    scaleY?: number;
+    skewX?: number;
+    skewY?: number;
+    originX?: number;
+    originY?: number;
+}
+/**
+ * Animation keyframe
+ */
+interface AnimationKeyframe {
+    offset: number;
+    properties: Partial<{
+        opacity: number;
+        x: number;
+        y: number;
+        scale: number;
+        rotation: number;
+    }>;
+}
+/**
+ * Animation definition
+ */
+interface Animation {
+    name?: string;
+    duration: number;
+    delay?: number;
+    easing?: string;
+    iterations?: number;
+    direction?: 'normal' | 'reverse' | 'alternate';
+    fillMode?: 'none' | 'forwards' | 'backwards' | 'both';
+    keyframes?: AnimationKeyframe[];
+    preset?: 'fadeIn' | 'fadeOut' | 'slideInLeft' | 'slideInRight' | 'slideInUp' | 'slideInDown' | 'zoomIn' | 'zoomOut' | 'bounce' | 'pulse';
+}
+/**
+ * Object types that can be placed on a slide
+ */
+type ObjectType = 'text' | 'image' | 'video' | 'audio' | 'shape' | 'component' | 'group';
+/**
+ * Base properties for all objects
+ */
+interface BaseObject {
+    id: string;
+    type: ObjectType;
+    name?: string;
+    position: Position;
+    size?: Size;
+    transform?: Transform;
+    opacity?: number;
+    visible?: boolean;
+    locked?: boolean;
+    animation?: Animation;
+    style?: CSSProperties;
+    className?: string;
+}
+/**
+ * Text object
+ */
+interface TextObject extends BaseObject {
+    type: 'text';
+    content: string;
+    fontSize?: number;
+    fontFamily?: string;
+    fontWeight?: string | number;
+    fontStyle?: 'normal' | 'italic';
+    textAlign?: 'left' | 'center' | 'right' | 'justify';
+    verticalAlign?: 'top' | 'middle' | 'bottom';
+    color?: string;
+    backgroundColor?: string;
+    lineHeight?: number;
+    letterSpacing?: number;
+    textShadow?: string;
+    padding?: number | string;
+}
+/**
+ * Image object
+ */
+interface ImageObject extends BaseObject {
+    type: 'image';
+    src: string;
+    alt?: string;
+    objectFit?: 'contain' | 'cover' | 'fill' | 'none';
+    objectPosition?: string;
+    borderRadius?: number | string;
+    border?: string;
+    shadow?: string;
+    filter?: string;
+}
+/**
+ * Video object
+ */
+interface VideoObject extends BaseObject {
+    type: 'video';
+    src: string;
+    poster?: string;
+    autoplay?: boolean;
+    muted?: boolean;
+    loop?: boolean;
+    controls?: boolean;
+    objectFit?: 'contain' | 'cover' | 'fill';
+}
+/**
+ * Audio object (invisible, but plays sound)
+ */
+interface AudioObject extends BaseObject {
+    type: 'audio';
+    src: string;
+    autoplay?: boolean;
+    loop?: boolean;
+    volume?: number;
+    showWaveform?: boolean;
+    showControls?: boolean;
+}
+/**
+ * Shape object (rectangle, circle, etc.)
+ */
+interface ShapeObject extends BaseObject {
+    type: 'shape';
+    shape: 'rectangle' | 'circle' | 'ellipse' | 'triangle' | 'polygon' | 'line' | 'arrow';
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    borderRadius?: number | string;
+    points?: number;
+    startPoint?: Position;
+    endPoint?: Position;
+}
+/**
+ * Custom React component object
+ */
+interface ComponentObject extends BaseObject {
+    type: 'component';
+    render: (props: {
+        isActive: boolean;
+        slideIndex: number;
+    }) => ReactNode;
+    props?: Record<string, unknown>;
+}
+/**
+ * Group of objects (can be transformed together)
+ */
+interface GroupObject extends BaseObject {
+    type: 'group';
+    children: SlideObject[];
+}
+/**
+ * Union of all object types
+ */
+type SlideObject = TextObject | ImageObject | VideoObject | AudioObject | ShapeObject | ComponentObject | GroupObject;
+/**
+ * Layer containing objects
+ */
+interface Layer {
+    id: string;
+    name: string;
+    visible: boolean;
+    locked: boolean;
+    opacity: number;
+    blendMode?: 'normal' | 'multiply' | 'screen' | 'overlay' | 'darken' | 'lighten';
+    objects: SlideObject[];
+}
+/**
+ * Background configuration
+ */
+interface SlideBackground {
+    type: 'color' | 'gradient' | 'image' | 'video';
+    value: string;
+    opacity?: number;
+    blur?: number;
+    overlay?: string;
+}
+/**
+ * Slide transition
+ */
+type TransitionType = 'none' | 'fade' | 'slide' | 'slideLeft' | 'slideRight' | 'slideUp' | 'slideDown' | 'zoom' | 'zoomIn' | 'zoomOut' | 'flip' | 'cube' | 'rotate';
+interface SlideTransition {
+    type: TransitionType;
+    duration?: number;
+    easing?: string;
+}
+/**
+ * Complete slide definition
+ */
+interface Slide {
+    id: string;
+    name?: string;
+    layers: Layer[];
+    background?: SlideBackground;
+    duration?: number;
+    enterTransition?: SlideTransition;
+    exitTransition?: SlideTransition;
+    notes?: string;
+    thumbnail?: string;
+    tags?: string[];
+}
+/**
+ * Navigation options
+ */
+interface NavigationOptions {
+    arrows?: boolean;
+    dots?: boolean;
+    thumbnails?: boolean;
+    keyboard?: boolean;
+    touch?: boolean;
+    mouseWheel?: boolean;
+    progress?: boolean;
+}
+/**
+ * Autoplay options
+ */
+interface AutoplayOptions {
+    enabled: boolean;
+    interval?: number;
+    pauseOnHover?: boolean;
+    pauseOnInteraction?: boolean;
+}
+/**
+ * Main carousel/presentation props
+ */
+interface CarouselProps {
+    slides: Slide[];
+    initialIndex?: number;
+    transition?: TransitionType;
+    transitionDuration?: number;
+    navigation?: NavigationOptions | boolean;
+    autoplay?: AutoplayOptions | boolean;
+    loop?: boolean;
+    aspectRatio?: string;
+    allowFullscreen?: boolean;
+    theme?: 'light' | 'dark' | 'auto';
+    className?: string;
+    style?: CSSProperties;
+    onSlideChange?: (index: number, slide: Slide) => void;
+    onFullscreenChange?: (isFullscreen: boolean) => void;
+    onObjectClick?: (object: SlideObject, slide: Slide) => void;
+}
+/**
+ * Carousel ref methods
+ */
+interface CarouselRef {
+    next: () => void;
+    prev: () => void;
+    goTo: (index: number) => void;
+    getCurrentIndex: () => number;
+    getCurrentSlide: () => Slide;
+    enterFullscreen: () => void;
+    exitFullscreen: () => void;
+    toggleFullscreen: () => void;
+    play: () => void;
+    pause: () => void;
+    isPlaying: () => boolean;
+}
+/**
+ * Create a simple slide with just objects (default layer)
+ */
+declare function createSimpleSlide(id: string, objects: SlideObject[], options?: Partial<Omit<Slide, 'id' | 'layers'>>): Slide;
+/**
+ * Create a single-image slide (convenience method)
+ */
+declare function createImageSlide(id: string, src: string, options?: {
+    title?: string;
+    objectFit?: ImageObject['objectFit'];
+    background?: SlideBackground;
+}): Slide;
+
+/**
+ * Qwanyx Carousel - Universal slide/presentation engine
+ */
+declare const Carousel: React.ForwardRefExoticComponent<CarouselProps & React.RefAttributes<CarouselRef>>;
+
+interface SlideRendererProps {
+    slide: Slide;
+    isActive: boolean;
+    slideIndex: number;
+}
+/**
+ * Main slide renderer - renders background, layers, and all objects
+ */
+declare function SlideRenderer({ slide, isActive, slideIndex }: SlideRendererProps): react_jsx_runtime.JSX.Element;
+
+interface ThumbnailsProps {
+    slides: Slide[];
+    currentIndex: number;
+    onSelect: (index: number) => void;
+    position?: 'bottom' | 'left' | 'right';
+    size?: 'small' | 'medium' | 'large';
+    theme?: 'light' | 'dark';
+}
+/**
+ * Thumbnails navigation component
+ */
+declare function Thumbnails({ slides, currentIndex, onSelect, position, size, theme, }: ThumbnailsProps): react_jsx_runtime.JSX.Element;
+
+interface UseCarouselOptions {
+    slides: Slide[];
+    initialIndex?: number;
+    loop?: boolean;
+    autoplay?: AutoplayOptions | boolean;
+    onSlideChange?: (index: number, slide: Slide) => void;
+}
+declare function useCarousel({ slides, initialIndex, loop, autoplay, onSlideChange, }: UseCarouselOptions): {
+    currentIndex: number;
+    currentSlide: Slide;
+    totalSlides: number;
+    direction: "next" | "prev";
+    isPlaying: boolean;
+    canGoNext: boolean;
+    canGoPrev: boolean;
+    next: () => void;
+    prev: () => void;
+    goTo: (index: number) => void;
+    play: () => void;
+    pause: () => void;
+    handleInteraction: () => void;
+};
+
+declare const createSlide: {
+    /**
+     * Create a simple image slide (single image, full slide)
+     */
+    image: (id: string, src: string, options?: {
+        title?: string;
+        objectFit?: "contain" | "cover" | "fill" | "none";
+        background?: SlideBackground;
+    }) => Slide;
+    /**
+     * Create a video slide
+     */
+    video: (id: string, src: string, options?: {
+        poster?: string;
+        autoplay?: boolean;
+        muted?: boolean;
+        loop?: boolean;
+        controls?: boolean;
+    }) => Slide;
+    /**
+     * Create a slide with custom objects
+     */
+    custom: (id: string, objects: SlideObject[], options?: Partial<Omit<Slide, "id" | "layers">>) => Slide;
+    /**
+     * Create a slide with a React component
+     */
+    component: (id: string, render: (props: {
+        isActive: boolean;
+        slideIndex: number;
+    }) => React.ReactNode, options?: Partial<Omit<Slide, "id" | "layers">>) => Slide;
+};
+
+export { type Animation, type AnimationKeyframe, type AudioObject, type AutoplayOptions, type BaseObject, Carousel, type CarouselProps, type CarouselRef, type ComponentObject, type GroupObject, type ImageObject, type Layer, type NavigationOptions, type ObjectType, type Position, type ShapeObject, type Size, type Slide, type SlideBackground, type SlideObject, SlideRenderer, type SlideTransition, type TextObject, Thumbnails, type Transform, type TransitionType, type VideoObject, createImageSlide, createSimpleSlide, createSlide, useCarousel };