@reelkit/stories-core

@reelkit/stories-core

Framework-agnostic stories state machine for ReelKit. Story and group navigation (tap to advance within a group, swipe to switch between users), auto-advance timer with pause/resume, tap zone detection, and segmented progress bar with sliding window for 50+ stories. ~1.7 kB gzip.

Installation

npm install @reelkit/stories-core @reelkit/core

Quick Start

import {
  createStoriesController,
  getTapAction,
  getSegments,
} from '@reelkit/stories-core';

const controller = createStoriesController({
  groupCount: 5,
  storyCounts: [3, 4, 2, 5, 3],
});

// Navigate stories
controller.nextStory();
controller.prevStory();

// Switch between users
controller.nextGroup();
controller.prevGroup();

// Read state via signals
console.log(controller.state.activeGroupIndex.value); // 0
console.log(controller.state.activeStoryIndex.value); // 1

// Tap zone detection
getTapAction(50, 400); // 'prev' (left 30%)
getTapAction(300, 400); // 'next' (right 70%)

// Progress bar segments
const segments = getSegments(5, 2, 0.6);
// [completed, completed, active(60%), upcoming, upcoming]

Features

• Stories controller with story and group navigation and boundary detection
• Timer controller with requestAnimationFrame progress and pause/resume
• Tap zone calculator (configurable left/right split ratio)
• Segmented progress bar with sliding window overflow
• Zero dependencies beyond @reelkit/core
• Pure functions, fully tree-shakeable

API Reference

createStoriesController

Config	Type	Default	Description
groupCount	number	required	Number of story groups
storyCounts	number[]	required	Stories per group
initialGroupIndex	number	0	Starting group index
initialStoryIndex	number	0	Starting story index
defaultImageDuration	number	5000	Default auto-advance (ms)
tapZoneSplit	number	0.3	Left zone ratio (0-1)

StoriesController

Method / Property	Type	Description
state.activeGroupIndex	Signal<number>	Current group index
state.activeStoryIndex	Signal<number>	Current story index
state.isPaused	Signal<boolean>	Paused state
nextStory()	void	Advance to next story
prevStory()	void	Go to previous story
nextGroup()	void	Switch to next user group
prevGroup()	void	Switch to previous user group
goToGroup(index)	void	Jump to specific group
pause()	void	Pause timer and auto-advance
resume()	void	Resume timer
dispose()	void	Clean up subscriptions

Events

Event	Type	Description
onStoryChange	(groupIndex, storyIndex) => void	Fired after story navigation
onGroupChange	(groupIndex) => void	Fired after group switch
onStoryViewed	(groupIndex, storyIndex) => void	Fired when a story is viewed
onComplete	() => void	Last story of last group finished
onClose	() => void	Close requested (boundary navigation)

getTapAction

function getTapAction(
  tapX: number,
  containerWidth: number,
  splitRatio?: number, // default: 0.3
): 'prev' | 'next';

getSegments

function getSegments(
  totalStories: number,
  activeIndex: number,
  timerProgress: number, // 0-1
): SegmentState[];

getVisibleWindow

function getVisibleWindow(
  totalStories: number,
  activeIndex: number,
  timerProgress: number,
  containerWidth: number,
  minSegmentWidth?: number, // default: 4
  gap?: number,
): VisibleWindow;

Types

type TapAction = 'prev' | 'next';

type SegmentStatus = 'completed' | 'active' | 'upcoming';

interface SegmentState {
  status: SegmentStatus;
  fillPercentage: number; // 0-100
}

interface VisibleWindow {
  startIndex: number;
  endIndex: number;
  segments: SegmentState[];
}

Documentation

API reference and guides at reelkit.dev.

Support

If ReelKit saved you some time, a star on GitHub would mean a lot.

License

MIT