@mottosports/motto-video-player 1.0.0

package/README.md

@@ -0,0 +1,233 @@
+# Motto Video Player
+
+React video player component for the Motto platform, powered by Shaka Player with TanStack Query integration.
+
+## Features
+
+- 🎬 **Dual Components**: Bare `VideoPlayer` for direct URL playback and `Video` wrapper for data fetching
+- 🔄 **TanStack Query Integration**: Advanced caching, background refetching, and error handling
+- 📱 **Responsive Design**: Automatic aspect ratio handling and mobile-friendly controls
+- 🎮 **Skip Controls**: Built-in skip back/forward buttons with customizable durations
+- 🎯 **Quality Control**: Automatic quality selection and manual quality switching
+- 📊 **Analytics**: Built-in Mux analytics support
+- 🖥️ **Chromecast Support**: Cast videos to compatible devices
+- 🔒 **DRM Support**: Content protection with various DRM systems
+- 📦 **TypeScript**: Full TypeScript support with comprehensive type definitions
+
+## Installation
+
+```bash
+npm install @motto-ui-components/motto-video-player @tanstack/react-query
+```
+
+## Quick Start
+
+### Setup QueryClient (Required for Video wrapper)
+
+```jsx
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+
+const queryClient = new QueryClient();
+
+function App() {
+  return (
+    <QueryClientProvider client={queryClient}>
+      <YourComponents />
+    </QueryClientProvider>
+  );
+}
+```
+
+### Basic Usage
+
+#### VideoPlayer (Bare Component)
+For direct stream URL playback:
+
+```jsx
+import { VideoPlayer } from '@motto-ui-components/motto-video-player';
+
+function MyPlayer() {
+  return (
+    <VideoPlayer
+      src="https://example.com/video.m3u8"
+      controls
+      aspectRatio={16/9}
+      onPlay={() => console.log('Playing')}
+      onError={(error) => console.error(error)}
+    />
+  );
+}
+```
+
+#### Video (Wrapper Component)
+For data fetching with TanStack Query:
+
+```jsx
+import { Video } from '@motto-ui-components/motto-video-player';
+
+function MyPlayer() {
+  return (
+    <Video
+      videoId="your-video-id"
+      publicKey="your-public-key"
+      controls
+      refetchInterval={30000}
+      events={{
+        onVideoData: (video) => console.log('Video loaded:', video),
+        onError: (error) => console.error('Error:', error),
+        onPlay: () => console.log('Playing')
+      }}
+    />
+  );
+}
+```
+
+## Component Comparison
+
+| Feature | VideoPlayer | Video |
+|---------|-------------|-------|
+| **Use Case** | Direct stream URL | Data fetching with videoId |
+| **Data Fetching** | ❌ Manual | ✅ Automatic with TanStack Query |
+| **Caching** | ❌ None | ✅ Smart caching & background updates |
+| **Loading States** | ❌ Manual | ✅ Built-in loading indicators |
+| **Error Handling** | ❌ Manual | ✅ Automatic retry with exponential backoff |
+| **Performance** | ✅ Minimal overhead | ✅ Optimized with query deduplication |
+
+## Advanced Configuration
+
+### TanStack Query Options
+
+```jsx
+<Video
+  videoId="123"
+  publicKey="key"
+  refetchInterval={30000}
+  queryOptions={{
+    staleTime: 5 * 60 * 1000, // 5 minutes
+    retry: 3,
+    retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000)
+  }}
+/>
+```
+
+### Skip Controls
+
+```jsx
+<VideoPlayer
+  src="..."
+  skipConfig={{
+    showSkipBack: true,
+    showSkipForward: true,
+    skipDuration: 15,
+    position: 'controls' // or 'overlay'
+  }}
+  onSkipBack={(newTime) => console.log('Skipped to:', newTime)}
+  onSkipForward={(newTime) => console.log('Skipped to:', newTime)}
+/>
+```
+
+### Responsive Sizing
+
+```jsx
+// Default responsive 16:9
+<VideoPlayer src="..." />
+
+// Custom aspect ratio
+<VideoPlayer src="..." aspectRatio={4/3} />
+
+// Fixed dimensions
+<VideoPlayer src="..." width={800} height={450} />
+```
+
+### Analytics Integration
+
+```jsx
+<VideoPlayer
+  src="..."
+  muxConfig={{
+    debug: false,
+    data: {
+      env_key: 'your-mux-env-key',
+      video_title: 'Video Title',
+      video_id: 'video-123',
+      player_name: 'Web Player',
+      viewer_user_id: 'user-456'
+    }
+  }}
+  onMuxReady={(monitor) => console.log('Mux ready')}
+/>
+```
+
+## API Reference
+
+### VideoPlayer Props
+
+```typescript
+interface VideoPlayerProps {
+  src: string;                    // Video source URL
+  autoPlay?: boolean;            // Auto-play video
+  controls?: boolean;            // Show player controls
+  aspectRatio?: number;          // Video aspect ratio (default: 16/9)
+  width?: number;               // Fixed width
+  height?: number;              // Fixed height
+  skipConfig?: SkipConfig;      // Skip controls configuration
+  muxConfig?: MuxConfig;        // Mux analytics configuration
+  onPlay?: () => void;          // Play event callback
+  onPause?: () => void;         // Pause event callback
+  onError?: (error: any) => void; // Error event callback
+  // ... more props
+}
+```
+
+### Video Props
+
+```typescript
+interface VideoProps extends Omit<VideoPlayerProps, 'src'> {
+  videoId?: string;             // Video ID for data fetching
+  publicKey?: string;           // Public key for API authentication
+  videoData?: VideoData;        // Pre-loaded video data
+  refetchInterval?: number;     // Background refetch interval (ms)
+  queryOptions?: QueryOptions;  // TanStack Query configuration
+  events?: {
+    onVideoData?: (video: VideoData) => void;
+    onEmptyPlaylists?: () => void;
+    onError?: (error: Error) => void;
+    // ... player events
+  };
+}
+```
+
+## TanStack Query Benefits
+
+### Caching & Performance
+- **Automatic Caching**: Videos are cached with configurable stale time
+- **Background Refetching**: Data stays fresh with background updates
+- **Request Deduplication**: Identical requests are automatically deduplicated
+- **Garbage Collection**: Memory-efficient cleanup of unused cache entries
+
+### Resilience & UX
+- **Smart Retries**: Exponential backoff retry logic for failed requests
+- **Loading States**: Built-in loading indicators for better UX
+- **Error Recovery**: Automatic error handling and recovery mechanisms
+- **Optimistic Updates**: Support for optimistic UI updates
+
+## Examples
+
+Check out the [example app](../../apps/example) for comprehensive usage examples including:
+
+- Basic VideoPlayer usage
+- Video wrapper with TanStack Query
+- Pre-loaded data scenarios
+- Skip controls integration
+- Responsive design patterns
+
+## Contributing
+
+1. Clone the repository
+2. Install dependencies: `pnpm install`
+3. Start development: `pnpm dev`
+4. Build: `pnpm build`
+
+## License
+
+ISC