@flowplayer/spins 0.1.0-rc.10

package/README.md

@@ -0,0 +1,220 @@
+# @flowplayer/spins
+
+A TypeScript library for creating Flowplayer playlist components optimized for short-form video content like Reels and Shorts.
+
+```typescript
+import { spins } from "@flowplayer/spins";
+
+const spinsContainer = spins({ 
+  playlist: "your-playlist-id",
+  token: "your-token",
+  lang: "en",
+  ui: { theme: "minimal" }
+});
+document.body.appendChild(spinsContainer);
+```
+
+### React Usage
+
+```tsx
+import { spins, type SpinsConfig } from "@flowplayer/spins";
+import { useEffect, useRef } from "react";
+
+function SpinsPlayer({ playlistId }: { playlistId: string }) {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (containerRef.current) {
+      const spinsContainer = spins({ 
+        playlist: playlistId,
+        token: "your-token",
+        lang: "en",
+        ui: { theme: "minimal" }
+      });
+      containerRef.current.appendChild(spinsContainer);
+    }
+  }, [playlistId]);
+
+  return <div ref={containerRef} className="spins-container" />;
+}
+```
+
+## Features
+
+- 🎯 **Type-safe** - Built with TypeScript and Zod schema validation
+- 🛡️ **Runtime validation** - Safely deserializes API responses
+- 🎨 **Styled components** - Includes CSS for playlist styling
+- 🔧 **Error handling** - Graceful fallbacks for network and validation errors
+- 📦 **ESM ready** - Modern ES modules with tree-shaking support
+- 📱 **Short-form optimized** - Designed for vertical video content like TikTok, Instagram Reels, and YouTube Shorts
+
+## Installation
+
+```bash
+npm install @flowplayer/spins
+# or
+bun add @flowplayer/spins
+```
+
+## Usage
+
+```typescript
+import { spins, type SpinsConfig } from "@flowplayer/spins";
+
+// Create a playlist component for short-form content
+const config: SpinsConfig = {
+  playlist: "your-playlist-id", // or array of SpinConfig objects
+  token: "your-flowplayer-token",
+  lang: "en",
+  ui: { theme: "minimal" },
+  autoplay: 1
+};
+
+const spinsContainer = spins(config);
+document.body.appendChild(spinsContainer);
+```
+
+## Short-Form Video Content
+
+This library is specifically designed to handle short-form video playlists, making it easy to create engaging vertical video experiences similar to:
+
+- **TikTok-style feeds** - Vertical scrolling through short videos
+- **Instagram Reels** - Quick, engaging video content
+- **YouTube Shorts** - Bite-sized video experiences
+
+The component automatically handles playlist loading and provides the structure needed for smooth, mobile-optimized video playback.
+
+## API Reference
+
+### `spins(config: SpinsConfig): SpinsContainer`
+
+Creates a Flowplayer playlist component container optimized for short-form video content.
+
+#### Parameters
+
+- `config.playlist: string | Array<SpinConfig>` - The playlist ID or array of spin configurations
+- `config.token: string` - Your Flowplayer token
+- `config.lang: string` - Language code (e.g., "en", "es")
+- `config.ui: object` - UI configuration options
+- `config.autoplay?: 0 | 1` - Enable/disable autoplay (optional)
+- `config.hls?: HLSConfig` - HLS-specific configuration (optional)
+- `config.ima?: PlayerIMAConfig` - IMA ads configuration (optional)
+
+#### Returns
+
+Returns a `SpinsContainer` (extends `HTMLDivElement`) with event handling capabilities:
+- `on(event, handler)` - Subscribe to events
+- `off(event, handler)` - Unsubscribe from events
+- `emit(event, data)` - Emit custom events (internal use)
+
+#### Events
+
+- `SPIN_CREATED` - Fired when a new spin is created
+- `SPIN_IN_VIEWPORT` - Fired when a spin enters the viewport
+
+#### Error Handling
+
+The function gracefully handles:
+- Network errors (API unavailable, timeout, etc.)
+- Invalid playlist configurations
+- HTTP errors (404, 500, etc.)
+
+## TypeScript Support
+
+The library exports TypeScript types for full type safety:
+
+```typescript
+import { type SpinsConfig, type SpinConfig, type SpinsContainer } from "@flowplayer/spins";
+```
+
+### `SpinsConfig`
+
+The main configuration interface:
+
+```typescript
+interface SpinsConfig {
+  playlist: string | Array<SpinConfig>;
+  token: string;
+  lang: string;
+  ui: Config["ui"];
+  autoplay?: 0 | 1;
+  hls?: HLSConfig["hls"];
+  ima?: PlayerIMAConfig;
+}
+```
+
+### `SpinConfig`
+
+Individual spin configuration:
+
+```typescript
+interface SpinConfig {
+  src: Config["src"];
+  title?: string;
+  poster?: string;
+  description?: string;
+  subtitles?: SubtitlesConfig["subtitles"];
+  thumbnails: ThumbnailsConfig["thumbnails"];
+  ima?: PlayerIMAConfig;
+}
+```
+
+## CSS Styling
+
+The component includes default CSS styling optimized for short-form video content. Styles are imported from:
+- `@flowplayer/spins/dist/spins.css` - Component-specific styles
+- Flowplayer CDN - Base player styles loaded automatically
+
+You can override styles by targeting the spins container and its children:
+
+```css
+.spins-container {
+  /* Base spins container styles */
+}
+
+flowplayer-spin {
+  /* Individual spin container styles */
+}
+```
+
+## Development
+
+### Prerequisites
+
+- [Bun](https://bun.sh/) runtime
+- TypeScript 5+
+
+### Scripts
+
+```bash
+# Development with Storybook
+bun run dev
+
+# Build the library
+bun run build
+
+# Build TypeScript declarations
+bun run build:dts
+
+# Run tests
+bun run test
+
+# Lint and format code
+bun run lint
+
+# Build Storybook for production
+bun run build-storybook
+```
+
+## Contributing
+
+This project uses:
+- **Biome** for linting and formatting
+- **Husky** for pre-commit hooks
+- **Vitest** with **Playwright** for browser testing
+- **Storybook** for component development and documentation
+- **Lit** for custom web components
+
+## License
+
+This is a paid feature of the Wowza Flowplayer platform. Usage requires a valid Flowplayer license.