Stories Core

Die Engine hinter @reelkit/react-stories-player. Reines TypeScript ohne Abhängigkeiten von einem Framework. Nutze sie, um Stories Player für Angular, Vue oder Vanilla JS zu bauen.

Installation

npm i @reelkit/stories-core

Stories-Controller

createStoriesController(config, events?) gibt einen StoriesController zurück, der die Navigation über Gruppen und Stories verwaltet. Er verfolgt den Zustand von Pause und Fortsetzen, merkt sich pro Gruppe die zuletzt angesehene Story und löst bei jedem Übergang Callbacks aus.

Konfiguration (StoriesControllerConfig)

Events (StoriesControllerEvents)

Zustand (reaktive Signals)

Methoden

Beispiel

import { createStoriesController } from '@reelkit/stories-core';
import { createTimerController, 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();

Timer-Controller

Der Timer, der den Fortschritt jeder Story antreibt, liegt in @reelkit/core als createTimerController und wird mit der Diashow der Lightbox geteilt. Importiere ihn aus @reelkit/core oder aus deinem Binding (@reelkit/react, @reelkit/vue, @reelkit/angular); dieses Paket exportiert ihn nicht mehr. Konfiguration, Zustand und Methoden findest du unter Autoplay in der Core-API, und das Beispiel des Stories-Controllers oben zeigt, wie er mit onStoryTimerComplete verbunden wird.

Canvas-Renderer für den Fortschritt

createCanvasProgressRenderer(config?) zeichnet segmentierte Fortschrittsleisten auf ein Canvas. Er skaliert für Retina-Displays, folgt der Breite seines Containers über observeElementSize aus @reelkit/core und nutzt ein gleitendes Fenster, wenn die Segmente nicht hineinpassen.

Konfiguration (CanvasProgressRendererConfig)

Methoden

createCanvasProgressRenderer gibt einen CanvasProgressRenderer zurück, das Objekt, das du behältst, wenn du ein Feld einer Komponente oder eine Ref für den Renderer typisierst:

Beispiel

import { createCanvasProgressRenderer } from '@reelkit/stories-core';

const renderer = createCanvasProgressRenderer({
  gap: 2,
  barHeight: 2,
  fillColor: '#ffffff',
  bgColor: 'rgba(255, 255, 255, 0.3)',
});

// Attach to a canvas element
const canvas = document.querySelector('canvas')!;
renderer.attach(canvas);

// Draw on each animation frame
let frameId: number;

function loop() {
  const totalStories = 5;
  const activeIndex = 2;
  const progress = timer.progress.value; // 0-1

  renderer.draw(totalStories, activeIndex, progress);
  frameId = requestAnimationFrame(loop);
}

frameId = requestAnimationFrame(loop);

// Cleanup
cancelAnimationFrame(frameId);
renderer.dispose();

Controller für den Gesehen-Status

createStoriesViewedStateController(config) ist alles, was ein Feed braucht, um sich das Gesehene zu merken, mit einem einzigen Aufruf: die Zählungen für die Ringe, wo jede Gruppe weitermacht, und das Erfassen, über einen Speicher, der ein Neuladen übersteht. Er importiert kein Framework, also nutzen React, Vue und Angular ihn gleich: Erstelle ihn einmal dort, wo der Feed lebt, und gib ihn an die Ringliste und den Player, die ihn selbst anhängen und ihm folgen. Er baut auf createViewedStateController aus dem Core mit dem Key für stabile IDs auf zwei Achsen auf; greif direkt darauf zurück, wenn das hier nicht passt. Ein Eintrag benennt die weiteste erreichte Story und keine Zahl von Aufrufen, sodass die Stelle einer Gruppe eine Neusortierung des Feeds übersteht, während eine aus der Mitte einer Gruppe entfernte Story deren Zählung verkürzt und ihren Ring wieder leuchten lässt.

Konfiguration (StoriesViewedStateControllerConfig)

storageKey, key und storage werden einmal gelesen, wenn der Controller erstellt wird. Um den Speicher zu wechseln, erstelle einen neuen Controller.

StoriesViewedStateController

Beispiel

import { createStoriesViewedStateController } from '@reelkit/stories-core';

// Once, where the feed lives. The getter is read every time, so it has to
// return the groups as they are now.
const viewed = createStoriesViewedStateController({
  storageKey: 'stories-seen',
  groups: () => groups,
});

// The player components do this themselves when given `viewed`.
const detach = viewed.attach();

viewed.viewedState.value; // Map { 'user_42' => 2 }, and a signal to follow
viewed.resumeStoryIndex(0); // 2 — the first story not yet seen
viewed.markViewed(0, 2); // furthest point wins; a rewatch never rewinds
viewed.forget(); // clears it all

detach();

Hilfsfunktionen

Reine Funktionen für die Erkennung von Tippzonen und die Rechnung der Fortschrittsleiste.

Layout-Helfer

Reine Funktionen, die der Player jedes Bindings teilt, damit die Player für React, Vue und Angular gleich groß sind und gleich aufgebaut werden. Ein Binding ruft sie auf; eine App braucht sie nur, wenn sie einen eigenen Player baut.

Größe

Die Grenze für Smartphones, die getStoriesSize nutzt, ist isMobileWidth, exportiert aus @reelkit/core und jedem Binding: 768px und schmaler ist ein Smartphone. Siehe Größenerkennung.

Geometrie des Desktop-Karussells

Die Versätze sind relativ zur aktiven Gruppe: negativ nach links, positiv nach rechts, 0 für die aktive Story selbst.

Darstellung

Die Typen CarouselSlot, RingPresentation und RingPresentationOptions werden mit ihnen exportiert.

Typen

Alle Typdefinitionen, die @reelkit/stories-core exportiert.

type MediaType = 'image' | 'video';

interface StoryItem {
  id: string;
  mediaType: MediaType;
  src: string;
  poster?: string;
  duration?: number;
  createdAt?: string | Date;
  aspectRatio?: number;
}

interface AuthorInfo {
  id: string;
  name: string;
  avatar: string;
  verified?: boolean;
}

interface StoriesGroup<T extends StoryItem = StoryItem> {
  author: AuthorInfo;
  stories: T[];
}

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

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

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

type TapAction = 'prev' | 'next';

interface CarouselSlot {
  x: number;
  width: number;
  height: number;
}

interface RingPresentationOptions {
  totalStories: number;
  viewedCount: number;
  size: number; // px
  gradientColors?: string[];
  viewedColor?: string;
}

interface RingPresentation {
  avatarSize: number;
  className: string;
  style: Record<string, string>;
}

Dieses Paket ist die Engine, kein Player: Es hält die Zustandsmaschine und die Geometrie und überlässt das Rendern einem Binding. Greif zuerst zu einem fertigen Player und zum Binding deines Frameworks — dem virtualisierten Reel, der Brücke für Signals, den Overlay-Helfern —, wenn du einen eigenen baust.