### Install Vue Lightbox and Dependencies

Source: https://reelkit.dev/docs/vue-lightbox

Install the necessary packages for Vue Lightbox, including the core library, Vue utilities, and Lucide Vue Next for icons.

```bash
npm install @reelkit/vue-lightbox @reelkit/vue lucide-vue-next
```

--------------------------------

### Basic rk-reel Component Setup

Source: https://reelkit.dev/docs/angular/guide

Demonstrates the basic setup of the rk-reel component with vertical direction, wheel scroll enabled, and a custom item template. It also shows how to handle the afterChange event.

```typescript
import { Component } from '@angular/core';
import { ReelComponent, ReelIndicatorComponent, RkReelItemDirective } from '@reelkit/angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [ReelComponent, ReelIndicatorComponent, RkReelItemDirective],
  template: `
    <rk-reel
      [count]="items.length"
      style="width: 100%; height: 100dvh"
      direction="vertical"
      [enableWheel]="true"
      (afterChange)="onAfterChange($event)"
    >
      <ng-template rkReelItem let-i let-size="size">
        <div [style.width.px]="size[0]" [style.height.px]="size[1]"
             [style.background]="items[i].color"
             style="display:flex;flex-direction:column;align-items:center;justify-content:center;color:#fff">
          <div style="font-size:1.5rem;font-weight:bold">{{ items[i].title }}</div>
          <div style="font-size:0.875rem;opacity:0.8">{{ items[i].subtitle }}</div>
        </div>
      </ng-template>

      <div style="position:absolute;right:12px;top:50%;transform:translateY(-50%);z-index:10">
        <rk-reel-indicator direction="vertical" />
      </div>
    </rk-reel>
  `,
})
export class AppComponent {
  items = [
    { title: 'Virtualized', subtitle: 'Only 3 slides in DOM', color: '#6366f1' },
    { title: 'Touch First', subtitle: 'Native swipe gestures', color: '#8b5cf6' },
    { title: 'Zero Deps', subtitle: 'Tiny bundle size', color: '#7c3aed' },
    { title: 'Keyboard Nav', subtitle: 'Full a11y support', color: '#ec4899' },
    { title: 'SSR Ready', subtitle: 'Works everywhere', color: '#14b8a6' },
    { title: '60fps', subtitle: 'Smooth animations', color: '#f59e0b' },
  ];

  onAfterChange(event: { index: number; indexInRange: number }) {
    console.log('Current index:', event.index);
  }
}

```

--------------------------------

### Install ReelKit Lightbox

Source: https://reelkit.dev/docs/lightbox

Install the necessary ReelKit packages using npm. Ensure lucide-react is also installed if you plan to use default icons.

```bash
npm install @reelkit/react-lightbox @reelkit/react lucide-react
```

--------------------------------

### Install Reel Player and Dependencies

Source: https://reelkit.dev/docs/reel-player

Install the necessary packages for the Reel Player component. Ensure lucide-react is included if you plan to use default icons.

```bash
npm install @reelkit/react-reel-player @reelkit/react lucide-react
```

--------------------------------

### Install Stories Core

Source: https://reelkit.dev/docs/stories-core

Install the Stories Core package using npm.

```bash
npm i @reelkit/stories-core
```

--------------------------------

### Install Vue Reel Player

Source: https://reelkit.dev/docs/vue-reel-player

Install the necessary packages for the Vue Reel Player. This includes the core player, the Vue utilities, and Lucide Vue Next for icons.

```bash
npm install @reelkit/vue-reel-player @reelkit/vue lucide-vue-next
```

--------------------------------

### Install @reelkit/react with pnpm

Source: https://reelkit.dev/docs/installation

Use this command to add the React package to your project.

```bash
pnpm add @reelkit/react
```

--------------------------------

### Install @reelkit/vue with npm

Source: https://reelkit.dev/docs/installation

Use this command to add the Vue package to your project.

```bash
npm install @reelkit/vue
```

--------------------------------

### Install ReelKit Stories Player

Source: https://reelkit.dev/docs/stories-player

Install the necessary packages for the stories player. Ensure you also import the component's styles.

```bash
npm i @reelkit/react-stories-player @reelkit/react lucide-react
```

--------------------------------

### Install Angular Reel Player

Source: https://reelkit.dev/docs/angular-reel-player

Install the necessary packages for the Angular Reel Player, including core components and icon library.

```bash
npm install @reelkit/angular-reel-player @reelkit/angular lucide-angular
```

--------------------------------

### Basic Reel Component Setup in React

Source: https://reelkit.dev

Demonstrates how to set up a basic Reel component using the @reelkit/react package. Ensure you have the necessary items and define the size and item builder.

```tsx
import { Reel, ReelIndicator } from '@reelkit/react';

const items = ['Slide 1', 'Slide 2', 'Slide 3'];

function App() {
  return (
    <Reel
      count={items.length}
      size={[400, 600]}
      itemBuilder={(index) => (
        <div className="slide">{items[index]}</div>
      )} 
    >
      <ReelIndicator />
    </Reel>
  );
}
```

--------------------------------

### Quick Start: Stories Overlay and Ring List

Source: https://reelkit.dev/docs/stories-player

A complete example demonstrating how to use StoriesOverlay and StoriesRingList components to create an Instagram-style stories experience. It includes state management for visibility and selection, and handles story viewing progress.

```tsx
import { useState, useMemo } from 'react';
import {
  StoriesOverlay,
  StoriesRingList,
  type StoriesGroup,
} from '@reelkit/react-stories-player';
import '@reelkit/react-stories-player/styles.css';

const groups: StoriesGroup[] = [
  {
    author: {
      id: 'user-1',
      name: 'Alice',
      avatar: '/cdn/samples/avatars/avatar-06.jpg',
      verified: true,
    },
    stories: [
      {
        id: 's1-1',
        mediaType: 'image',
        src: '/cdn/samples/images/stories/story-001.jpg',
      },
      {
        id: 's1-2',
        mediaType: 'image',
        src: '/cdn/samples/images/stories/story-002.jpg',
      },
      {
        id: 's1-3',
        mediaType: 'image',
        src: '/cdn/samples/images/stories/story-003.jpg',
      },
    ],
  },
  {
    author: {
      id: 'user-2',
      name: 'Bob',
      avatar: '/cdn/samples/avatars/avatar-07.jpg',
    },
    stories: [
      {
        id: 's2-1',
        mediaType: 'image',
        src: '/cdn/samples/images/stories/story-004.jpg',
      },
      {
        id: 's2-2',
        mediaType: 'image',
        src: '/cdn/samples/images/stories/story-005.jpg',
      },
    ],
  },
  {
    author: {
      id: 'user-3',
      name: 'Charlie',
      avatar: '/cdn/samples/avatars/avatar-08.jpg',
      verified: true,
    },
    stories: [
      {
        id: 's3-1',
        mediaType: 'image',
        src: '/cdn/samples/images/stories/story-006.jpg',
      },
    ],
  },
];

export default function App() {
  const [isOpen, setIsOpen] = useState(false);
  const [selectedGroup, setSelectedGroup] = useState(0);
  const viewedState = useMemo(() => new Map<string, number>(), []);

  const openStories = (groupIndex: number) => {
    setSelectedGroup(groupIndex);
    setIsOpen(true);
  };

  return (
    <div style={{ padding: 16, background: '#0f172a', minHeight: '100vh' }}>
      <StoriesRingList
        groups={groups}
        viewedState={viewedState}
        onSelect={openStories}
      />

      <StoriesOverlay
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        groups={groups}
        initialGroupIndex={selectedGroup}
        onStoryViewed={(gi, si) => {
          const author = groups[gi].author;
          const current = viewedState.get(author.id) ?? 0;
          viewedState.set(author.id, Math.max(current, si + 1));
        }}
      />
    </div>
  );
}
```

--------------------------------

### Install @reelkit/vue with pnpm

Source: https://reelkit.dev/docs/installation

Use this command to add the Vue package to your project.

```bash
pnpm add @reelkit/vue
```

--------------------------------

### Install Angular Lightbox

Source: https://reelkit.dev/docs/angular-lightbox

Install the necessary packages for Angular Lightbox and Lucide Angular icons using npm.

```bash
npm install @reelkit/angular-lightbox @reelkit/angular lucide-angular
```

--------------------------------

### Install @reelkit/react with npm

Source: https://reelkit.dev/docs/installation

Use this command to add the React package to your project.

```bash
npm install @reelkit/react
```

--------------------------------

### Install @reelkit/vue with yarn

Source: https://reelkit.dev/docs/installation

Use this command to add the Vue package to your project.

```bash
yarn add @reelkit/vue
```

--------------------------------

### Install @reelkit/react with yarn

Source: https://reelkit.dev/docs/installation

Use this command to add the React package to your project.

```bash
yarn add @reelkit/react
```

--------------------------------

### Install @reelkit/angular with npm

Source: https://reelkit.dev/docs/installation

Use this command to add the Angular package to your project.

```bash
npm install @reelkit/angular
```

--------------------------------

### Install @reelkit/angular with pnpm

Source: https://reelkit.dev/docs/installation

Use this command to add the Angular package to your project.

```bash
pnpm add @reelkit/angular
```

--------------------------------

### Angular Quick Start: Minimal Vertical Slider

Source: https://reelkit.dev/docs/getting-started

Set up a minimal vertical slider in Angular using ReelKit's Angular components. This example requires importing ReelComponent, ReelIndicatorComponent, and RkReelItemDirective.

```typescript
import { Component } from '@angular/core';
import {
  ReelComponent,
  ReelIndicatorComponent,
  RkReelItemDirective,
} from '@reelkit/angular';

const items = [
  { id: 1, title: 'Slide 1', color: '#6366f1' },
  { id: 2, title: 'Slide 2', color: '#8b5cf6' },
  { id: 3, title: 'Slide 3', color: '#ec4899' },
];

@Component({
  standalone: true,
  imports: [ReelComponent, ReelIndicatorComponent, RkReelItemDirective],
  template: `
    <rk-reel [count]="items.length" [size]="[400, 600]"
             direction="vertical" [enableWheel]="true">
      <ng-template rkReelItem let-i let-size="size">
        <div [style.width.px]="size[0]" [style.height.px]="size[1]"
             [style.background]="items[i].color"
             style="display:flex;align-items:center;justify-content:center;
                    font-size:2rem;color:#fff">
          {{ items[i].title }}
        </div>
      </ng-template>
      <rk-reel-indicator />
    </rk-reel>
  `,
})
export class AppComponent {
  readonly items = items;
}
```

--------------------------------

### Next.js App Router Client Component Setup

Source: https://reelkit.dev/docs/ssr

Use the 'use client' directive for Reel components in Next.js App Router. This example shows how to import and render Reel and ReelIndicator with dynamic item data.

```tsx
'use client';

import { Reel, ReelIndicator } from '@reelkit/react';

export function Feed({ items }: { items: FeedItem[] }) {
  return (
    <Reel
      count={items.length}
      size={[400, 700]}
      direction="vertical"
      enableWheel
      itemBuilder={(index) => (
        <div className="w-full h-full flex items-center justify-center">
          {items[index].title}
        </div>
      )}>
      <ReelIndicator />
    </Reel>
  );
}

```

--------------------------------

### Install @reelkit/angular with yarn

Source: https://reelkit.dev/docs/installation

Use this command to add the Angular package to your project.

```bash
yarn add @reelkit/angular
```

--------------------------------

### Quick Start: Basic Reel Player Implementation

Source: https://reelkit.dev/docs/vue-reel-player

Render a grid of thumbnails that open the Reel Player overlay when clicked. The `v-model:is-open` binding ensures the parent `ref` stays synchronized with the player's visibility.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { ReelPlayerOverlay, type ContentItem } from '@reelkit/vue-reel-player';
import '@reelkit/vue-reel-player/styles.css';

const content: ContentItem[] = [
  {
    id: '1',
    media: [{
      id: 'v1',
      type: 'video',
      src: '/cdn/samples/videos/video-01.mp4',
      poster: '/cdn/samples/videos/video-poster-01.jpg',
      aspectRatio: 16 / 9,
    }],
    author: { name: 'Alex Johnson', avatar: '/cdn/samples/avatars/avatar-01.jpg' },
    likes: 1234,
    description: 'Amazing sunset vibes',
  },
  {
    id: '2',
    media: [{
      id: 'img1',
      type: 'image',
      src: '/cdn/samples/images/image-01.jpg',
      aspectRatio: 2 / 3,
    }],
    author: { name: 'Sarah Miller', avatar: '/cdn/samples/avatars/avatar-02.jpg' },
    likes: 5678,
    description: 'Nature at its finest',
  },
  {
    id: '3',
    media: [{
      id: 'v2',
      type: 'video',
      src: '/cdn/samples/videos/video-02.mp4',
      poster: '/cdn/samples/videos/video-poster-02.jpg',
      aspectRatio: 16 / 9,
    }],
    author: { name: 'Mike Chen', avatar: '/cdn/samples/avatars/avatar-03.jpg' },
    likes: 3456,
    description: 'Adventure awaits',
  },
];

const isOpen = ref(false);
const startIndex = ref(0);

function openAt(i: number) {
  startIndex.value = i;
  isOpen.value = true;
}
</script>

<template>
  <div style="display:grid;grid-template-columns:repeat(3,1fr);gap:6px">
    <button
      v-for="(item, i) in content"
      :key="item.id"
      @click="openAt(i)"
      style="aspect-ratio:9/16;cursor:pointer;overflow:hidden;padding:0;border:0"
    >
      <img
        :src="item.media[0].poster || item.media[0].src"
        style="width:100%;height:100%;object-fit:cover"
      />
    </button>
  </div>

  <ReelPlayerOverlay
    v-model:is-open="isOpen"
    :content="content"
    :initial-index="startIndex"
  />
</template>

```

--------------------------------

### Basic Vue Lightbox Usage

Source: https://reelkit.dev/docs/vue-lightbox

Demonstrates how to set up and use the LightboxOverlay component in a Vue 3 application. It includes defining image items, managing the open state with v-model, and initializing the lightbox with a starting index.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import { LightboxOverlay, type LightboxItem } from '@reelkit/vue-lightbox';
import '@reelkit/vue-lightbox/styles.css';

const images: LightboxItem[] = [
  {
    src: '/cdn/samples/images/image-01.jpg',
    title: 'Mountain River',
    description: 'A beautiful mountain river',
  },
  {
    src: '/cdn/samples/images/image-02.jpg',
    title: 'Snowy Peaks',
  },
  {
    src: '/cdn/samples/images/image-03.jpg',
    title: 'Misty Forest',
    description: 'Morning fog over the forest canopy',
  },
  {
    src: '/cdn/samples/images/image-04.jpg',
    title: 'Autumn Trail',
  },
  {
    src: '/cdn/samples/images/image-05.jpg',
    title: 'Ocean Cliff',
    description: 'Dramatic cliffs above the Pacific',
  },
  {
    src: '/cdn/samples/images/image-06.jpg',
    title: 'Desert Dunes',
  },
];

const open = ref(false);
const startIndex = ref(0);

function openAt(i: number) {
  startIndex.value = i;
  open.value = true;
}
</script>

<template>
  <div style="display:grid;grid-template-columns:repeat(3,1fr);gap:8px">
    <button
      v-for="(img, i) in images"
      :key="img.src"
      style="aspect-ratio:4/3;cursor:pointer"
      @click="openAt(i)"
    >
      <img :src="img.src" style="width:100%;height:100%;object-fit:cover" />
    </button>
  </div>

  <LightboxOverlay
    v-model:is-open="open"
    :items="images"
    :initial-index="startIndex"
  />
</template>

```

--------------------------------

### ReelIndicator Usage Examples

Source: https://reelkit.dev/docs/vue/guide

Shows how to use ReelIndicator, both auto-connected within a Reel and manually with explicit count and active props.

```html
<!-- Auto-connect: count and active are inherited from parent Reel -->
<Reel :count="10" :size="[400, 600]">
  <template #item="{ index, size }"> ... </template>
  <ReelIndicator direction="vertical" />
</Reel>

<!-- Manual usage: pass count and active explicitly (e.g. outside a Reel) -->
<ReelIndicator :count="10" :active="currentIndex" />

```

--------------------------------

### Setup Video Slide Renderer in Vue

Source: https://reelkit.dev/docs/vue-lightbox

Integrate video slides by calling `useVideoSlideRenderer` and forwarding the returned renderers into the overlay's slots. Wrap the overlay in `SoundProvider` for built-in sound toggle functionality.

```vue
<script setup lang="ts">
import { ref } from 'vue';
import {
  LightboxOverlay,
  useVideoSlideRenderer,
  type LightboxItem,
} from '@reelkit/vue-lightbox';
import '@reelkit/vue-lightbox/styles.css';

const open = ref(false);
const items: LightboxItem[] = [
  { src: '/image-01.jpg', title: 'Image' },
  {
    type: 'video',
    src: '/clip.mp4',
    poster: '/clip.jpg',
    title: 'Clip',
  },
];

const { VideoSlideRenderer, VideoControlsRenderer, SoundProvider } =
  useVideoSlideRenderer(items);
</script>

<template>
  <SoundProvider>
    <LightboxOverlay v-model:is-open="open" :items="items">
      <template #slide="scope">
        <VideoSlideRenderer v-bind="scope" />
      </template>
      <template #controls="scope">
        <VideoControlsRenderer v-bind="scope" />
      </template>
    </LightboxOverlay>
  </SoundProvider>
</template>
```

--------------------------------

### Basic Angular Lightbox Usage

Source: https://reelkit.dev/docs/angular-lightbox

Demonstrates how to import and use the RkLightboxOverlayComponent in an Angular application. Ensure styles are imported and the component is added to the imports array. The example shows how to bind an array of items and control the lightbox's visibility.

```typescript
import { Component } from '@angular/core';
import {
  RkLightboxOverlayComponent,
  type LightboxItem,
} from '@reelkit/angular-lightbox';
import '@reelkit/angular-lightbox/styles.css';

const images: LightboxItem[] = [
  {
    src: '/cdn/samples/images/image-01.jpg',
    title: 'Mountain River',
    description: 'A beautiful mountain river',
  },
  {
    src: '/cdn/samples/images/image-02.jpg',
    title: 'Snowy Peaks',
  },
  {
    src: '/cdn/samples/images/image-03.jpg',
    title: 'Misty Forest',
    description: 'Morning fog over the forest canopy',
  },
  {
    src: '/cdn/samples/images/image-04.jpg',
    title: 'Autumn Trail',
  },
  {
    src: '/cdn/samples/images/image-05.jpg',
    title: 'Ocean Cliff',
    description: 'Dramatic cliffs above the Pacific',
  },
  {
    src: '/cdn/samples/images/image-06.jpg',
    title: 'Desert Dunes',
  },
];

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [RkLightboxOverlayComponent],
  template:воды
    <div style="display:grid;grid-template-columns:repeat(3,1fr);gap:8px">
      @for (img of images; track img.src; let i = $index) {
        <button (click)="openIndex = i" style="aspect-ratio:4/3;cursor:pointer">
          <img [src]="img.src" style="width:100%;height:100%;object-fit:cover" />
        </button>
      }
    </div>

    <rk-lightbox-overlay
      [isOpen]="openIndex !== null"
      [items]="images"
      [initialIndex]="openIndex ?? 0"
      (closed)="openIndex = null"
    />
  `,
})
export class AppComponent {
  images = images;
  openIndex: number | null = null;
}

```

--------------------------------

### Create and Bind Timeline Controller

Source: https://reelkit.dev/docs/core/guide

Initialize a `TimelineController` for video scrub bars, optionally providing callbacks for scrub start and end events. Attach it to a video element and bind interactions to a track element.

```typescript
import { createTimelineController } from '@reelkit/core';

const timeline = createTimelineController({
  onScrubStart: () => video.pause(),
  onScrubEnd: () => video.play(),
});

timeline.attach(video);
const dispose = timeline.bindInteractions(trackEl);

// Render: read signals and update DOM
timeline.progress.observe(() => {
  fillEl.style.width = `${timeline.progress.value * 100}%`;
});

// Cleanup
dispose();
timeline.detach();
```

--------------------------------

### Implement Custom Lightbox Transition Function

Source: https://reelkit.dev/docs/lightbox

Create your own `TransitionTransformFn` for custom animations and pass it via the `transitionFn` prop. The signature should mirror the core slider transitions. This example demonstrates a custom fade effect.

```tsx
import {
  LightboxOverlay,
  type TransitionTransformFn,
} from '@reelkit/react-lightbox';

const customFade: TransitionTransformFn = (offset, size) => ({
  transform: `translate3d(${offset * size[0]}px, 0, 0)`,
  opacity: 1 - Math.min(Math.abs(offset), 1),
});

<LightboxOverlay
  isOpen={isOpen}
  images={images}
  transitionFn={customFade}
  onClose={() => setIsOpen(false)}
/>
```

--------------------------------

### React Quick Start: Minimal Vertical Slider

Source: https://reelkit.dev/docs/getting-started

Implement a basic vertical slider in React using the Reel and ReelIndicator components. Ensure you have the '@reelkit/react' package installed.

```tsx
import { Reel, ReelIndicator } from '@reelkit/react';

const items = [
  { id: 1, title: 'Slide 1', color: '#6366f1' },
  { id: 2, title: 'Slide 2', color: '#8b5cf6' },
  { id: 3, title: 'Slide 3', color: '#ec4899' },
];

function App() {
  return (
    <Reel
      count={items.length}
      size={[400, 600]}
      direction="vertical"
      enableWheel
      itemBuilder={(index) => (
        <div
          style={{
            width: '100%',
            height: '100%',
            background: items[index].color,
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center',
            fontSize: '2rem',
            color: 'white',
          }}
        >
          {items[index].title}
        </div>
      )} 
    >
      <ReelIndicator />
    </Reel>
  );
}
```

--------------------------------

### Vue Quick Start: Minimal Vertical Slider

Source: https://reelkit.dev/docs/getting-started

Integrate a minimal vertical slider in Vue.js using the '@reelkit/vue' package. This example demonstrates the use of the Reel and ReelIndicator components with Vue's template syntax.

```vue
<script setup lang="ts">
import { Reel, ReelIndicator } from '@reelkit/vue';

const items = [
  { id: 1, title: 'Slide 1', color: '#6366f1' },
  { id: 2, title: 'Slide 2', color: '#8b5cf6' },
  { id: 3, title: 'Slide 3', color: '#ec4899' },
];
</script>

<template>
  <Reel
    :count="items.length"
    :size="[400, 600]"
    direction="vertical"
    enable-wheel
  >
    <template #item="{ index, size }">
      <div
        :style="{
          width: size[0] + 'px',
          height: size[1] + 'px',
          background: items[index].color,
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          fontSize: '2rem',
          color: '#fff',
        }" 
      >
        {{ items[index].title }}
      </div>
    </template>

    <ReelIndicator />
  </Reel>
</template>
```

--------------------------------

### Virtualization

Source: https://reelkit.dev/docs/core/guide

Explains how the core renders a limited number of slides to the DOM for performance and how to customize the range extractor.

```APIDOC
## Virtualization

### Description
The core renders only 3 slides to the DOM at any time (current, previous, next). The range extractor determines which indices are included in the rendered window.

### `defaultRangeExtractor`
- **Usage**: `defaultRangeExtractor(currentIndex: number, count: number): number[]`
- **Description**: Extracts the default range of indices to render, typically the current slide and its immediate neighbors.

### Custom Range Extractor
- **Description**: Allows for custom logic to determine which slide indices to render, for example, to skip hidden slides.
- **Example**: 
```typescript
const hiddenSlides = new Set([2, 5]);

const skipHiddenExtractor = (current: number, count: number): number[] => {
  const result: number[] = [];
  // Collect prev, current, next — skip hidden, shift forward
  for (let i = current - 1, added = 0; added < 3 && i < count; i++) {
    if (i >= 0 && !hiddenSlides.has(i)) {
      result.push(i);
      added++;
    }
  }
  return result;
};
```

**Note**: The result is always clamped to a maximum of 3 indices. If your extractor returns more, the core keeps 3 centered around the current slide.
```

--------------------------------

### Initialize and Use Stories Controller

Source: https://reelkit.dev/docs/stories-core

Create and manage a stories controller for navigation and playback. Wire up a timer for auto-advance and react to story changes. Ensure to dispose of resources when done.

```typescript
import {
  createStoriesController,
  createTimerController,
} from '@reelkit/stories-core';
import { reaction } from '@reelkit/core';

const groups = [
  { stories: ['s1', 's2', 's3'] },
  { stories: ['s4', 's5'] },
];

const controller = createStoriesController(
  {
    groupCount: groups.length,
    storyCounts: groups.map((g) => g.stories.length),
    defaultImageDuration: 5000,
  },
  {
    onStoryChange(groupIndex, storyIndex) {
      console.log('Story changed:', groupIndex, storyIndex);
    },
    onComplete() {
      console.log('All stories viewed');
    },
    onClose() {
      console.log('Overlay closed');
    },
  },
);

// Wire up a timer for auto-advance
const timer = createTimerController({
  duration: 5000,
  onComplete: () => controller.onStoryTimerComplete(),
});

// React to story changes and restart the timer
const dispose = reaction(
  () => [
    controller.state.activeGroupIndex,
    controller.state.activeStoryIndex,
  ],
  () => timer.start(),
);

// Start playback
timer.start();

// Navigation
controller.nextStory();
controller.pause();
controller.resume();

// Cleanup
dispose();
timer.dispose();
controller.dispose();

```

--------------------------------

### Basic Angular Reel Player Usage

Source: https://reelkit.dev/docs/angular-reel-player

Demonstrates how to import the Reel Player stylesheet and component, and set up a basic content feed with a thumbnail grid.

```typescript
import { Component, signal } from '@angular/core';
import {
  RkReelPlayerOverlayComponent,
  type ContentItem,
} from '@reelkit/angular-reel-player';
import '@reelkit/angular-reel-player/styles.css';

const content: ContentItem[] = [
  {
    id: '1',
    media: [{
      id: 'v1',
      type: 'video',
      src: '/cdn/samples/videos/video-01.mp4',
      poster: '/cdn/samples/videos/video-poster-01.jpg',
      aspectRatio: 16 / 9,
    }],
    author: { name: 'Alex Johnson', avatar: '/cdn/samples/avatars/avatar-01.jpg' },
    likes: 1234,
    description: 'Amazing content',
  },
  {
    id: '2',
    media: [{
      id: 'img1',
      type: 'image',
      src: '/cdn/samples/images/image-01.jpg',
      aspectRatio: 2 / 3,
    }],
    author: { name: 'Sarah Miller', avatar: '/cdn/samples/avatars/avatar-02.jpg' },
    likes: 5678,
    description: 'Nature at its finest',
  },
  {
    id: '3',
    media: [{
      id: 'v2',
      type: 'video',
      src: '/cdn/samples/videos/video-02.mp4',
      poster: '/cdn/samples/videos/video-poster-02.jpg',
      aspectRatio: 16 / 9,
    }],
    author: { name: 'Mike Chen', avatar: '/cdn/samples/avatars/avatar-03.jpg' },
    likes: 3456,
    description: 'Adventure awaits',
  },
];

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [RkReelPlayerOverlayComponent],
  template: `
    <!-- Grid thumbnail view -->
    <div style="display:grid;grid-template-columns:repeat(3,1fr);gap:6px">
      @for (item of content; track item.id; let i = $index) {
        <button
          (click)="openAt(i)"
          style="aspect-ratio:9/16;cursor:pointer;overflow:hidden"
        >
          <img
            [src]="item.media[0].poster || item.media[0].src"
            style="width:100%;height:100%;object-fit:cover"
          />
        </button>
      }
    </div>

    <rk-reel-player-overlay
      [isOpen]="isOpen()"
      [content]="content"
      [initialIndex]="startIndex()"
      (closed)="isOpen.set(false)"
    />
  `,
})
export class AppComponent {
  readonly content = content;
  readonly isOpen = signal(false);
  readonly startIndex = signal(0);

  openAt(index: number): void {
    this.startIndex.set(index);
    this.isOpen.set(true);
  }
}

```

--------------------------------

### ReelIndicator Usage Examples

Source: https://reelkit.dev/docs/angular/guide

Demonstrates auto-connecting ReelIndicator within an rk-reel and manual usage outside of it.

```html
<!-- Auto-connect: count and active are inherited from parent rk-reel -->
<rk-reel [count]="10" [size]="[400, 600]">
  <ng-template rkReelItem let-i let-size="size"> ... </ng-template>
  <rk-reel-indicator direction="vertical" />
</rk-reel>

<!-- Manual usage: pass count and active explicitly (e.g. outside a rk-reel) -->
<rk-reel-indicator [count]="10" [active]="currentIndex" />
```

--------------------------------

### Signals

Source: https://reelkit.dev/docs/core/guide

Demonstrates how to use the lightweight signal system for reactive state management.

```APIDOC
## Signals

### Description
The core uses a lightweight signal system for reactivity.

### `createSignal`
- **Usage**: `createSignal(initialValue: T): Signal<T>`
- **Description**: Creates a reactive signal with an initial value.
- **Methods**: 
  - `observe(callback: () => void): () => void` - Observes changes to the signal's value and returns a disposer function.
  - `value` (getter/setter) - Gets or sets the signal's value.

### `createComputed`
- **Usage**: `createComputed(factory: () => T, dependencies: () => any[]): Signal<T>`
- **Description**: Creates a computed signal whose value is derived from other signals.

### `reaction`
- **Usage**: `reaction(dependencies: () => any[], effect: () => void): () => void`
- **Description**: Runs a side effect in response to changes in specified dependency signals. Returns a disposer function.

### Example
```typescript
import { createSignal, createComputed, reaction } from '@reelkit/core';

// Create a signal
const count = createSignal(0);

// Observe changes (returns a disposer function)
const dispose = count.observe(() => console.log(count.value));

// Update value
count.value = 5;

// Create computed signal (requires a deps factory)
const doubled = createComputed(() => count.value * 2, () => [count]);

// Run side effects on signal changes
const disposeReaction = reaction(
  () => [count],
  () => console.log('Count changed:', count.value)
);

// Cleanup
dispose();
disposeReaction();
```
```

--------------------------------

### Timer Controller

Source: https://reelkit.dev/docs/stories-core

Provides methods to control a timer for stories, including starting, pausing, resuming, resetting, and disposing of the timer.

```APIDOC
## Timer Controller Methods

### `start(duration?: number) => void`

Starts or restarts the timer. An optional `duration` can be provided to override the default duration.

### `pause() => void`

Pauses the timer at its current position.

### `resume() => void`

Resumes the timer from its paused position.

### `reset() => void`

Resets the timer's progress to 0 and stops it.

### `dispose() => void`

Cleans up any resources used by the timer controller.
```

--------------------------------

### Basic Image Lightbox Implementation

Source: https://reelkit.dev/docs/lightbox

Implement a basic image gallery using LightboxOverlay. Pass an array of LightboxItem objects and manage the overlay's visibility with a state variable.

```tsx
import { useState } from 'react';
import { LightboxOverlay, type LightboxItem } from '@reelkit/react-lightbox';
import '@reelkit/react-lightbox/styles.css';

const images: LightboxItem[] = [
  {
    src: 'https://example.com/image1.jpg',
    title: 'Sunset',
    description: 'Beautiful sunset over the ocean',
  },
  {
    src: 'https://example.com/image2.jpg',
    title: 'Mountains',
  },
];

function App() {
  const [index, setIndex] = useState<number | null>(null);

  return (
    <>
      {images.map((img, i) => (
        <img
          key={i}
          src={img.src}
          onClick={() => setIndex(i)}
        />
      ))}
      <LightboxOverlay
        isOpen={index !== null}
        images={images}
        initialIndex={index ?? 0}
        onClose={() => setIndex(null)}
      />
    </>
  );
}

```

--------------------------------

### Get Focusable Elements

Source: https://reelkit.dev/docs/core/api

Returns an array of all keyboard-focusable descendant elements within a container, in DOM order. It skips disabled, hidden, and `tabindex='-1'` elements.

```typescript
getFocusableElements(container: HTMLElement) => HTMLElement[]
```

--------------------------------

### Basic Reel Slider with Vertical Direction

Source: https://reelkit.dev/docs/vue/guide

Demonstrates the basic setup of the Reel component for vertical sliding. It includes item rendering, enabling wheel scroll, and integrating ReelIndicator.

```vue
<script setup lang="ts">
import { Reel, ReelIndicator } from '@reelkit/vue';

const items = [
  { title: 'Virtualized', subtitle: 'Only 3 slides in DOM', color: '#6366f1' },
  { title: 'Touch First', subtitle: 'Native swipe gestures', color: '#8b5cf6' },
  { title: 'Zero Deps', subtitle: 'Tiny bundle size', color: '#7c3aed' },
  { title: 'Keyboard Nav', subtitle: 'Full a11y support', color: '#ec4899' },
  { title: 'SSR Ready', subtitle: 'Works everywhere', color: '#14b8a6' },
  { title: '60fps', subtitle: 'Smooth animations', color: '#f59e0b' },
];

const onAfterChange = (index: number) => {
  console.log('Current index:', index);
};
</script>

<template>
  <Reel
    :count="items.length"
    style="width: 100%; height: 100dvh"
    direction="vertical"
    :enable-wheel="true"
    @after-change="onAfterChange"
  >
    <template #item="{ index, size }">
      <div
        :style="{
          width: size[0] + 'px',
          height: size[1] + 'px',
          background: items[index].color,
          display: 'flex',
          flexDirection: 'column',
          alignItems: 'center',
          justifyContent: 'center',
          color: '#fff',
        }"
      >
        <div style="font-size: 1.5rem; font-weight: bold">
          {{ items[index].title }}
        </div>
        <div style="font-size: 0.875rem; opacity: 0.8">
          {{ items[index].subtitle }}
        </div>
      </div>
    </template>

    <div style="position: absolute; right: 12px; top: 50%; transform: translateY(-50%); z-index: 10">
      <ReelIndicator direction="vertical" />
    </div>
  </Reel>
</template>

```

--------------------------------

### useSoundState

Source: https://reelkit.dev/docs/vue/api

Composable to access the current SoundController from context.

```APIDOC
## useSoundState

Access the current `SoundController` from context. Must be called inside a `<SoundProvider>`. Throws if called outside.

```typescript
import { useSoundState } from '@reelkit/vue';

// Inside a SoundProvider descendant
const sound = useSoundState();

sound.muted;    // Signal<boolean>
sound.toggle(); // Toggle muted state
```
```

--------------------------------

### Programmatic API Usage

Source: https://reelkit.dev/docs/angular/guide

Demonstrates how to obtain the Reel API instance using the (apiReady) event and control the slider programmatically with methods like prev(), next(), and goTo().

```typescript
import { Component } from '@angular/core';
import { ReelComponent, RkReelItemDirective, type ReelApi } from '@reelkit/angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [ReelComponent, RkReelItemDirective],
  template: `
    <rk-reel
      [count]="10"
      [size]="[400, 600]"
      (apiReady)="api = $event"
    >
      <ng-template rkReelItem let-i let-size="size">
        <app-slide [index]="i" [size]="size" />
      </ng-template>
    </rk-reel>

    <button (click)="api?.prev()">Prev</button>
    <button (click)="api?.next()">Next</button>
    <button (click)="api?.goTo(5)">Go to 5</button>
  `,
})
export class AppComponent {
  api: ReelApi | undefined;
}

```

--------------------------------

### Inject and Use SoundStateService in Angular

Source: https://reelkit.dev/docs/angular-reel-player

Shows how to inject and utilize the SoundStateService within an Angular component for controlling player mute and disabled states. Examples for template usage are provided.

```typescript
import { inject } from '@angular/core';
import { SoundStateService } from '@reelkit/angular-reel-player';

@Component({ ... })
export class AppComponent {
  readonly soundState = inject(SoundStateService);

  // Use in template:
  // [class.muted]="soundState.muted()"
  // [disabled]="soundState.disabled()"
  // (click)="soundState.toggle()"
}
```

--------------------------------

### Custom Slide Rendering with StoriesOverlay

Source: https://reelkit.dev/docs/stories-player

Completely replace the default image and video slides using the `renderSlide` prop. This example demonstrates conditional rendering of `VideoStorySlide` and `ImageStorySlide` based on `story.mediaType`.

```tsx
import {
  StoriesOverlay,
  ImageStorySlide,
  VideoStorySlide,
} from '@reelkit/react-stories-player';

<StoriesOverlay
  isOpen={isOpen}
  onClose={handleClose}
  groups={groups}
  renderSlide={({ story, index, groupIndex, size, activeGroupIndex, activeStoryIndex, onDurationReady, onReady, onWaiting, onError, onEnded }) => {
    const [w, h] = size;

    if (story.mediaType === 'video') {
      return (
        <div style={{ width: w, height: h, background: '#000' }}>
          <VideoStorySlide
            src={story.src}
            poster={story.poster}
            groupIndex={groupIndex}
            storyIndex={index}
            activeGroupIndex={activeGroupIndex}
            activeStoryIndex={activeStoryIndex}
            onDurationReady={onDurationReady}
            onPlaying={onReady}
            onWaiting={onWaiting}
            onEnded={onEnded}
            onError={onError}
          />
        </div>
      );
    }

    return (
      <div style={{ width: w, height: h, background: '#000' }}>
        <ImageStorySlide src={story.src} onLoad={onReady} onError={onError} />
      </div>
    );
  }}
/>
```

--------------------------------

### useFullscreen

Source: https://reelkit.dev/docs/vue/api

Composable for managing the Fullscreen API with cross-browser support.

```APIDOC
## useFullscreen

Composable for managing the Fullscreen API with cross-browser support. Exits fullscreen automatically on unmount.

```typescript
import { ref } from 'vue';
import { useFullscreen } from '@reelkit/vue';

const containerRef = ref<HTMLElement | null>(null);
const { isFullscreen, request, exit, toggle } = useFullscreen({
  elementRef: containerRef,
});
```

Return| Type| Description
---|---|---
isFullscreen| Signal<boolean>| Core signal reflecting current fullscreen state (read `.value`)
request| () => Promise<void>| Request fullscreen on the referenced element. If another element is already fullscreen, it is exited first (awaited).
exit| () => Promise<void>| Exit fullscreen
toggle| () => Promise<void>| Toggle fullscreen state
```

--------------------------------

### Bridge Core Signal to Vue Ref

Source: https://reelkit.dev/docs/vue/api

Use toVueRef to bridge a core Signal into a read-only Vue Ref for reactivity in templates. Must be called within a Vue setup or effect-scope-aware context.

```typescript
import { defineComponent, h } from 'vue';
import { toVueRef, useSoundState } from '@reelkit/vue';

export const MuteIcon = defineComponent({
  setup() {
    const sound = useSoundState();
    const muted = toVueRef(sound.muted); // Readonly<Ref<boolean>>

    return () => h('span', muted.value ? '🔇' : '🔊');
  },
});
```

--------------------------------

### Basic Reel Player Usage

Source: https://reelkit.dev/docs/reel-player

Implement a basic Reel Player overlay. Pass an array of content items and manage the player's visibility using the isOpen state.

```tsx
import { useState } from 'react';
import { ReelPlayerOverlay, type ContentItem } from '@reelkit/react-reel-player';
import '@reelkit/react-reel-player/styles.css';

const content: ContentItem[] = [
  {
    id: '1',
    media: [{
      id: 'v1',
      type: 'video',
      src: 'https://example.com/video.mp4',
      poster: 'https://example.com/poster.jpg',
      aspectRatio: 9 / 16,
    }],
    author: { name: 'John Doe', avatar: 'https://example.com/avatar.jpg' },
    likes: 1234,
    description: 'Amazing video!',
  },
];

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Open Player</button>
      <ReelPlayerOverlay
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        content={content}
      />
    </>
  );
}
```

--------------------------------

### Next.js Pages Router SSR Integration

Source: https://reelkit.dev/docs/ssr

Integrate Reel components with Next.js Pages Router using getServerSideProps. This example demonstrates fetching data on the server and passing it as props to the page component.

```tsx
// pages/feed.tsx
import { Reel } from '@reelkit/react';
import type { GetServerSideProps } from 'next';

interface Props {
  items: FeedItem[];
}

export const getServerSideProps: GetServerSideProps<Props> = async () => {
  const items = await fetchFeedItems();
  return { props: { items } };
};

export default function FeedPage({ items }: Props) {
  return (
    <Reel
      count={items.length}
      size={[400, 700]}
      itemBuilder={(index) => <Slide data={items[index]} />}
    />
  );
}

```

--------------------------------

### Use Video Slide Renderer Hook

Source: https://reelkit.dev/docs/lightbox

Use this hook for opt-in video support in the lightbox. It returns functions to render slides, controls, and a sound provider. Wrap your overlay in SoundProvider and pass the render functions. The `isOpen` parameter resets mute on close, enabling autoplay on reopen.

```typescript
import { useVideoSlideRenderer } from '@reelkit/react-lightbox';

const { renderSlide, renderControls, SoundProvider, hasVideo } =
  useVideoSlideRenderer(items, isOpen);

// SoundProvider  — wrap LightboxOverlay in this for mute/unmute support
// renderSlide    — pass to LightboxOverlay's renderSlide prop
// renderControls — pass to LightboxOverlay's renderControls prop
//                  (includes Counter, FullscreenButton, SoundButton, CloseButton)
// hasVideo       — true if items contain at least one video
// isOpen param   — resets mute to true on close (enables autoplay on reopen)
```