@djangocfg/ui-nextjs 2.1.64 → 2.1.66

package/src/tools/VideoPlayer/README.md

@@ -1,239 +1,248 @@
-# VideoPlayer - Professional Vidstack Implementation
+# VideoPlayer
 
-A professional, accessible video player built with Vidstack React that supports YouTube, Vimeo, MP4, HLS, and more.
+Unified video player component supporting multiple modes and source types.
 
-## Features
+## Modes
 
-- ✅ **Multi-platform support**: YouTube, Vimeo, MP4, HLS, DASH
-- ✅ **Custom controls**: Professional UI with hover effects
-- ✅ **Accessibility**: Full keyboard navigation and screen reader support
-- ✅ **Responsive**: Works on all screen sizes
-- ✅ **TypeScript**: Full type safety
-- ✅ **Themes**: Default, minimal, and modern themes
-- ✅ **No recommendations**: Clean playback without YouTube distractions
+| Mode | Source Types | Use Case |
+|------|-------------|----------|
+| `vidstack` | YouTube, Vimeo, HLS, DASH | Full-featured player with themes and controls |
+| `native` | URL, data-url | Lightweight HTML5 player |
+| `streaming` | stream, blob | HTTP Range streaming with auth, binary data |
 
-## Installation
+Mode is auto-detected from source type, or can be forced via `mode` prop.
 
-The VideoPlayer is already included in the UI package with all dependencies:
+## Installation
 
-```bash
-pnpm add @vidstack/react@next media-icons@next
+```tsx
+import {
+  VideoPlayer,
+  VideoPlayerProvider,
+  VideoErrorFallback,
+  resolveFileSource
+} from '@djangocfg/ui-nextjs';
 ```
 
 ## Basic Usage
 
+### YouTube / Vimeo
+
 ```tsx
-import { VideoPlayer } from '@djangocfg/ui-nextjs/tools';
-
-function MyComponent() {
-  return (
-    <VideoPlayer
-      source={{
-        url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
-        title: 'Never Gonna Give You Up',
-        description: 'Rick Astley - Never Gonna Give You Up (Official Video)'
-      }}
-      autoplay={false}
-      controls={true}
-      className="max-w-4xl mx-auto"
-    />
-  );
-}
+<VideoPlayer source={{ type: 'youtube', id: 'dQw4w9WgXcQ' }} />
+<VideoPlayer source={{ type: 'vimeo', id: '123456789' }} />
 ```
 
-## Advanced Usage
+### HLS / DASH Streaming
 
 ```tsx
-import { VideoPlayer, VideoPlayerRef } from '@djangocfg/ui-nextjs/tools';
-import { useRef } from 'react';
-
-function AdvancedPlayer() {
-  const playerRef = useRef<VideoPlayerRef>(null);
-
-  const handleCustomPlay = () => {
-    playerRef.current?.play();
-  };
-
-  return (
-    <VideoPlayer
-      ref={playerRef}
-      source={{
-        url: 'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4',
-        title: 'Big Buck Bunny',
-        poster: 'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/images/BigBuckBunny.jpg',
-        duration: 596
-      }}
-      theme="modern"
-      autoplay={false}
-      muted={false}
-      playsInline={true}
-      showInfo={true}
-      onPlay={() => console.log('Video started')}
-      onPause={() => console.log('Video paused')}
-      onEnded={() => console.log('Video ended')}
-      onError={(error) => console.error('Video error:', error)}
-    />
-  );
-}
+<VideoPlayer source={{ type: 'hls', url: 'https://example.com/video.m3u8' }} />
+<VideoPlayer source={{ type: 'dash', url: 'https://example.com/video.mpd' }} />
 ```
 
-## Supported Video Sources
-
-### YouTube
-- **URL Format**: `https://www.youtube.com/watch?v=VIDEO_ID` or `youtube/VIDEO_ID`
-- **Auto-conversion**: Full YouTube URLs are automatically converted to `youtube/ID` format
-- **Poster**: ⚠️ YouTube iframe ignores custom poster images and always shows YouTube's thumbnail
-- **Examples**:
-  ```tsx
-  url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
-  url: 'https://youtu.be/dQw4w9WgXcQ'
-  url: 'youtube/dQw4w9WgXcQ'
-  ```
-
-### Vimeo
-- **URL Format**: `https://vimeo.com/VIDEO_ID` or `vimeo/VIDEO_ID`
-- **Auto-conversion**: Full Vimeo URLs are automatically converted to `vimeo/ID` format
-- **Poster**: ⚠️ Vimeo may ignore custom poster and use their own thumbnail
-- **Example**: `url: 'vimeo/76979871'`
-
-### Direct Video Files (MP4, WebM, OGG)
-- **Poster**: ✅ **Works perfectly!** Custom poster images are fully supported
-- **Examples**:
-  ```tsx
-  url: 'https://example.com/video.mp4',
-  poster: '/images/video-poster.jpg'  // This works!
-  ```
-
-### HLS Streams
-- **Poster**: ✅ Custom poster supported
-- **Example**: `url: 'https://example.com/stream.m3u8'`
-
-### DASH Streams  
-- **Poster**: ✅ Custom poster supported
-- **Example**: `url: 'https://example.com/stream.mpd'`
-
-> **Note**: The `poster` prop works for direct video files, HLS, and DASH streams. For YouTube and Vimeo, the platform's own thumbnail is displayed regardless of the `poster` prop due to iframe limitations.
-
-### YouTube
+### Direct URL
+
 ```tsx
+<VideoPlayer source={{ type: 'url', url: 'https://example.com/video.mp4' }} />
+```
+
+### HTTP Range Streaming (with auth)
+
+```tsx
+// Full source (standalone)
 <VideoPlayer
   source={{
-    url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
-    title: 'YouTube Video'
+    type: 'stream',
+    sessionId: 'abc123',
+    path: '/videos/movie.mp4',
+    getStreamUrl: (id, path) => `/api/stream/${id}?path=${path}&token=${token}`
   }}
 />
+
+// Simplified source (with context)
+<VideoPlayerProvider sessionId={sessionId} getStreamUrl={getStreamUrl}>
+  <VideoPlayer source={{ type: 'stream', path: '/videos/movie.mp4' }} />
+</VideoPlayerProvider>
 ```
 
-### Vimeo
+### Blob / ArrayBuffer
+
 ```tsx
 <VideoPlayer
   source={{
-    url: 'https://vimeo.com/76979871',
-    title: 'Vimeo Video'
+    type: 'blob',
+    data: arrayBuffer,
+    mimeType: 'video/mp4'
   }}
 />
 ```
 
-### Direct MP4
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `source` | `VideoSourceUnion` | required | Video source configuration |
+| `mode` | `'auto' \| 'vidstack' \| 'native' \| 'streaming'` | `'auto'` | Force specific player mode |
+| `aspectRatio` | `number \| 'auto' \| 'fill'` | `16/9` | Aspect ratio or fill parent |
+| `autoPlay` | `boolean` | `false` | Auto-play on load |
+| `muted` | `boolean` | `false` | Muted by default |
+| `loop` | `boolean` | `false` | Loop playback |
+| `controls` | `boolean` | `true` | Show player controls |
+| `playsInline` | `boolean` | `true` | Inline playback on mobile |
+| `preload` | `'none' \| 'metadata' \| 'auto'` | `'metadata'` | Preload strategy |
+| `theme` | `'default' \| 'minimal' \| 'modern'` | `'default'` | Vidstack theme |
+| `errorFallback` | `ReactNode \| (props) => ReactNode` | - | Custom error UI |
+| `className` | `string` | - | Container className |
+| `videoClassName` | `string` | - | Video element className |
+
+## Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `onPlay` | `() => void` | Playback started |
+| `onPause` | `() => void` | Playback paused |
+| `onEnded` | `() => void` | Playback ended |
+| `onError` | `(error: string) => void` | Error occurred |
+| `onLoadStart` | `() => void` | Loading started |
+| `onCanPlay` | `() => void` | Ready to play |
+| `onTimeUpdate` | `(time: number, duration: number) => void` | Time updated |
+
+## Ref API
+
+```tsx
+const playerRef = useRef<VideoPlayerRef>(null);
+
+<VideoPlayer ref={playerRef} source={source} />
+
+// Control methods
+playerRef.current?.play();
+playerRef.current?.pause();
+playerRef.current?.seek(30);        // Seek to 30 seconds
+playerRef.current?.setVolume(0.5);  // 0-1
+playerRef.current?.setMuted(true);
+playerRef.current?.reload();
+```
+
+## Error Handling
+
+### Custom Error Fallback
+
 ```tsx
 <VideoPlayer
-  source={{
-    url: 'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4',
-    title: 'Direct MP4',
-    poster: 'https://example.com/poster.jpg'
-  }}
+  source={source}
+  errorFallback={(props) => (
+    <div>
+      <p>Error: {props.error}</p>
+      <button onClick={props.retry}>Retry</button>
+    </div>
+  )}
 />
 ```
 
-### HLS Stream
+### Pre-built Error Fallback with Download
+
 ```tsx
+import { VideoErrorFallback } from '@djangocfg/ui-nextjs';
+
 <VideoPlayer
-  source={{
-    url: 'https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8',
-    title: 'HLS Stream'
-  }}
+  source={source}
+  errorFallback={(props) => (
+    <VideoErrorFallback
+      {...props}
+      downloadUrl={getDownloadUrl()}
+      downloadFilename="video.mp4"
+      fileSize="125 MB"
+    />
+  )}
 />
 ```
 
-## API Reference
+## Fill Mode
 
-### VideoPlayerProps
+Use `aspectRatio="fill"` to fill the parent container:
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `source` | `VideoSource` | - | Video source configuration |
-| `aspectRatio` | `number` | `16/9` | Video aspect ratio |
-| `autoplay` | `boolean` | `false` | Auto-play video |
-| `muted` | `boolean` | `false` | Mute video by default |
-| `playsInline` | `boolean` | `true` | Play inline on mobile |
-| `controls` | `boolean` | `true` | Show custom controls |
-| `showInfo` | `boolean` | `false` | Show video info below player |
-| `theme` | `'default' \| 'minimal' \| 'modern'` | `'default'` | Player theme |
-| `className` | `string` | - | Custom CSS class |
-| `onPlay` | `() => void` | - | Play event callback |
-| `onPause` | `() => void` | - | Pause event callback |
-| `onEnded` | `() => void` | - | End event callback |
-| `onError` | `(error: string) => void` | - | Error event callback |
-
-### VideoSource
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `url` | `string` | Video URL (YouTube, Vimeo, MP4, HLS, etc.) |
-| `title` | `string?` | Video title |
-| `description` | `string?` | Video description |
-| `poster` | `string?` | Custom poster/thumbnail URL |
-| `duration` | `number?` | Video duration in seconds |
-
-### VideoPlayerRef Methods
-
-| Method | Description |
-|--------|-------------|
-| `play()` | Play the video |
-| `pause()` | Pause the video |
-| `togglePlay()` | Toggle play/pause |
-| `seekTo(time: number)` | Seek to specific time |
-| `setVolume(volume: number)` | Set volume (0-1) |
-| `toggleMute()` | Toggle mute |
-| `enterFullscreen()` | Enter fullscreen |
-| `exitFullscreen()` | Exit fullscreen |
-
-## Themes
-
-### Default Theme
-Clean, professional look with rounded corners and subtle shadows.
-
-### Minimal Theme
-No rounded corners, minimal styling for embedding in tight spaces.
-
-### Modern Theme
-Enhanced shadows and larger border radius for a contemporary look.
+```tsx
+<div className="absolute inset-0">
+  <VideoPlayer source={source} aspectRatio="fill" />
+</div>
+```
 
-## Accessibility
+## Context Provider
 
-The VideoPlayer includes full accessibility support:
+For apps with multiple streaming videos, use the context to avoid repetition:
 
-- ✅ Keyboard navigation (Space, Arrow keys, F for fullscreen)
-- ✅ Screen reader announcements
-- ✅ Focus indicators
-- ✅ ARIA labels and roles
-- ✅ High contrast support
+```tsx
+// In layout or parent component
+<VideoPlayerProvider
+  sessionId={sessionId}
+  getStreamUrl={(id, path) => `/api/stream/${id}?path=${path}`}
+>
+  {/* All nested VideoPlayers use this config */}
+  <VideoPlayer source={{ type: 'stream', path: '/video1.mp4' }} />
+  <VideoPlayer source={{ type: 'stream', path: '/video2.mp4' }} />
+</VideoPlayerProvider>
+```
 
-## Performance
+## File Source Helper
 
-- ✅ Lazy loading of video content
-- ✅ Efficient re-renders with Vidstack's optimized state management
-- ✅ Minimal bundle size impact
-- ✅ Hardware-accelerated playback when available
+For file browser integration:
 
-## Browser Support
+```tsx
+import { resolveFileSource } from '@djangocfg/ui-nextjs';
 
-Supports all modern browsers through Vidstack's comprehensive compatibility layer:
+const source = resolveFileSource({
+  file: { name: 'movie.mp4', path: '/videos/movie.mp4' },
+  sessionId: 'abc123',
+  getStreamUrl: (id, path) => `/api/stream/${id}?path=${path}`,
+});
 
-- ✅ Chrome 63+
-- ✅ Firefox 67+
-- ✅ Safari 12+
-- ✅ Edge 79+
-- ✅ iOS Safari 12+
-- ✅ Chrome Android 63+
+if (source) {
+  return <VideoPlayer source={source} />;
+}
+```
+
+## Source Types Reference
+
+```typescript
+type VideoSourceUnion =
+  | { type: 'url'; url: string; title?: string; poster?: string }
+  | { type: 'youtube'; id: string; title?: string; poster?: string }
+  | { type: 'vimeo'; id: string; title?: string; poster?: string }
+  | { type: 'hls'; url: string; title?: string; poster?: string }
+  | { type: 'dash'; url: string; title?: string; poster?: string }
+  | { type: 'stream'; sessionId: string; path: string; getStreamUrl: fn; mimeType?: string }
+  | { type: 'blob'; data: ArrayBuffer | Blob; mimeType?: string }
+  | { type: 'data-url'; data: string; mimeType?: string }
+```
+
+## Architecture
+
+```
+VideoPlayer/
+├── VideoPlayer.tsx         # Main orchestrator
+├── VideoPlayerContext.tsx  # Context for streaming config
+├── VideoErrorFallback.tsx  # Pre-built error UI
+├── VideoControls.tsx       # Standalone controls (Vidstack)
+├── types.ts                # Type definitions
+├── providers/
+│   ├── VidstackProvider.tsx   # YouTube, Vimeo, HLS, DASH
+│   ├── NativeProvider.tsx     # HTML5 <video>
+│   └── StreamProvider.tsx     # HTTP Range, Blob
+└── index.ts                # Exports
+```
+
+## Accessibility
+
+Full accessibility support:
+- Keyboard navigation (Space, Arrow keys, F for fullscreen)
+- Screen reader announcements
+- Focus indicators
+- ARIA labels and roles
+
+## Browser Support
 
+- Chrome 63+
+- Firefox 67+
+- Safari 12+
+- Edge 79+
+- iOS Safari 12+
+- Chrome Android 63+

package/src/tools/VideoPlayer/VideoErrorFallback.tsx

@@ -0,0 +1,174 @@
+/**
+ * VideoErrorFallback - Pre-built error fallback with download button
+ * For use with VideoPlayer errorFallback prop
+ */
+
+'use client';
+
+import React from 'react';
+import { FileVideo, RefreshCw } from 'lucide-react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+import { Button } from '@djangocfg/ui-core/components';
+import { DownloadButton } from '../../components/button-download';
+
+import type { ErrorFallbackProps } from './types';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface VideoErrorFallbackProps extends ErrorFallbackProps {
+  /** URL for download button (if provided, shows download button) */
+  downloadUrl?: string;
+  /** Filename for download */
+  downloadFilename?: string;
+  /** File size to display */
+  fileSize?: string;
+  /** Show retry button */
+  showRetry?: boolean;
+  /** Custom className */
+  className?: string;
+  /** Custom icon */
+  icon?: React.ReactNode;
+  /** Custom title (defaults to error message) */
+  title?: string;
+  /** Custom description */
+  description?: string;
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+/**
+ * Pre-built error fallback component for VideoPlayer
+ *
+ * @example
+ * // Basic usage
+ * <VideoPlayer
+ *   source={source}
+ *   errorFallback={(props) => (
+ *     <VideoErrorFallback
+ *       {...props}
+ *       downloadUrl={getDownloadUrl()}
+ *       downloadFilename="video.mp4"
+ *     />
+ *   )}
+ * />
+ *
+ * @example
+ * // With file size
+ * <VideoErrorFallback
+ *   error="Failed to load video"
+ *   downloadUrl="/api/download/video.mp4"
+ *   fileSize="125 MB"
+ *   showRetry
+ *   retry={() => reloadVideo()}
+ * />
+ */
+export function VideoErrorFallback({
+  error,
+  retry,
+  downloadUrl,
+  downloadFilename,
+  fileSize,
+  showRetry = true,
+  className,
+  icon,
+  title,
+  description,
+}: VideoErrorFallbackProps) {
+  const displayTitle = title || error || 'Video cannot be previewed';
+
+  return (
+    <div
+      className={cn(
+        'absolute inset-0 flex flex-col items-center justify-center gap-4 bg-black/90 text-white p-6',
+        className
+      )}
+    >
+      {/* Icon */}
+      {icon || <FileVideo className="w-16 h-16 text-muted-foreground" />}
+
+      {/* Title */}
+      <p className="text-lg font-medium text-center">{displayTitle}</p>
+
+      {/* Description / File size */}
+      {(description || fileSize) && (
+        <p className="text-sm text-muted-foreground text-center">
+          {description || fileSize}
+        </p>
+      )}
+
+      {/* Actions */}
+      <div className="flex items-center gap-3 mt-2">
+        {/* Retry button */}
+        {showRetry && retry && (
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={retry}
+            className="gap-2"
+          >
+            <RefreshCw className="w-4 h-4" />
+            Retry
+          </Button>
+        )}
+
+        {/* Download button */}
+        {downloadUrl && (
+          <DownloadButton
+            url={downloadUrl}
+            filename={downloadFilename}
+            variant="default"
+            size="sm"
+          >
+            Download to view
+          </DownloadButton>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// ============================================================================
+// Factory for common use cases
+// ============================================================================
+
+export interface CreateVideoErrorFallbackOptions {
+  /** Function to get download URL from source */
+  getDownloadUrl?: (source: unknown) => string | undefined;
+  /** Function to get filename from source */
+  getFilename?: (source: unknown) => string | undefined;
+  /** Function to get file size from source */
+  getFileSize?: (source: unknown) => string | undefined;
+  /** Show retry button */
+  showRetry?: boolean;
+}
+
+/**
+ * Factory to create error fallback function for VideoPlayer
+ *
+ * @example
+ * const errorFallback = createVideoErrorFallback({
+ *   getDownloadUrl: (source) => source.downloadUrl,
+ *   getFilename: (source) => source.filename,
+ *   showRetry: true,
+ * });
+ *
+ * <VideoPlayer source={source} errorFallback={errorFallback} />
+ */
+export function createVideoErrorFallback(
+  options: CreateVideoErrorFallbackOptions
+): (props: ErrorFallbackProps, source?: unknown) => React.ReactNode {
+  return (props: ErrorFallbackProps, source?: unknown) => (
+    <VideoErrorFallback
+      {...props}
+      downloadUrl={options.getDownloadUrl?.(source)}
+      downloadFilename={options.getFilename?.(source)}
+      fileSize={options.getFileSize?.(source)}
+      showRetry={options.showRetry}
+    />
+  );
+}