@djangocfg/ui-tools 2.1.91

package/src/tools/VideoPlayer/README.md

@@ -0,0 +1,264 @@
+# VideoPlayer
+
+Unified video player component supporting multiple modes and source types.
+
+## Modes
+
+| 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 |
+
+Mode is auto-detected from source type, or can be forced via `mode` prop.
+
+## Installation
+
+```tsx
+import {
+  VideoPlayer,
+  VideoPlayerProvider,
+  VideoErrorFallback,
+  resolveFileSource
+} from '@djangocfg/ui-nextjs';
+```
+
+## Basic Usage
+
+### YouTube / Vimeo
+
+```tsx
+<VideoPlayer source={{ type: 'youtube', id: 'dQw4w9WgXcQ' }} />
+<VideoPlayer source={{ type: 'vimeo', id: '123456789' }} />
+```
+
+### HLS / DASH Streaming
+
+```tsx
+<VideoPlayer source={{ type: 'hls', url: 'https://example.com/video.m3u8' }} />
+<VideoPlayer source={{ type: 'dash', url: 'https://example.com/video.mpd' }} />
+```
+
+### Direct URL
+
+```tsx
+<VideoPlayer source={{ type: 'url', url: 'https://example.com/video.mp4' }} />
+```
+
+### HTTP Range Streaming (with auth)
+
+```tsx
+// Full source (standalone)
+<VideoPlayer
+  source={{
+    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>
+```
+
+### Blob / ArrayBuffer
+
+```tsx
+<VideoPlayer
+  source={{
+    type: 'blob',
+    data: arrayBuffer,
+    mimeType: 'video/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={source}
+  errorFallback={(props) => (
+    <div>
+      <p>Error: {props.error}</p>
+      <button onClick={props.retry}>Retry</button>
+    </div>
+  )}
+/>
+```
+
+### Pre-built Error Fallback with Download
+
+```tsx
+import { VideoErrorFallback } from '@djangocfg/ui-nextjs';
+
+<VideoPlayer
+  source={source}
+  errorFallback={(props) => (
+    <VideoErrorFallback
+      {...props}
+      downloadUrl={getDownloadUrl()}
+      downloadFilename="video.mp4"
+      fileSize="125 MB"
+    />
+  )}
+/>
+```
+
+## Fill Mode
+
+Use `aspectRatio="fill"` to fill the parent container:
+
+```tsx
+<div className="absolute inset-0">
+  <VideoPlayer source={source} aspectRatio="fill" />
+</div>
+```
+
+## Context Provider
+
+For apps with multiple streaming videos, use the context to avoid repetition:
+
+```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>
+```
+
+## File Source Helper
+
+For file browser integration:
+
+```tsx
+import { resolveFileSource } from '@djangocfg/ui-nextjs';
+
+const source = resolveFileSource({
+  file: { name: 'movie.mp4', path: '/videos/movie.mp4' },
+  sessionId: 'abc123',
+  getStreamUrl: (id, path) => `/api/stream/${id}?path=${path}`,
+});
+
+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/
+├── index.ts                    # Public API exports
+├── types/
+│   ├── index.ts                # Type re-exports
+│   ├── sources.ts              # Source types (Url, YouTube, HLS, etc.)
+│   ├── player.ts               # Player props, ref, events
+│   └── provider.ts             # Provider & context types
+├── hooks/
+│   ├── index.ts
+│   └── useVideoPositionCache.ts  # Playback position caching
+├── utils/
+│   ├── index.ts
+│   ├── resolvers.ts            # resolvePlayerMode, isSimpleStreamSource
+│   └── fileSource.ts           # resolveFileSource helper
+├── components/
+│   ├── index.ts
+│   ├── VideoPlayer.tsx         # Main orchestrator
+│   ├── VideoControls.tsx       # Standalone Vidstack controls
+│   └── VideoErrorFallback.tsx  # Pre-built error UI
+├── context/
+│   ├── index.ts
+│   └── VideoPlayerContext.tsx  # Streaming config provider
+└── providers/
+    ├── index.ts
+    ├── VidstackProvider.tsx    # YouTube, Vimeo, HLS, DASH
+    ├── NativeProvider.tsx      # HTML5 <video>
+    └── StreamProvider.tsx      # HTTP Range, Blob
+```
+
+## 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/components/VideoControls.tsx

@@ -0,0 +1,138 @@
+/**
+ * Custom Video Controls for Vidstack Player
+ */
+
+'use client';
+
+import { Maximize, Minimize, Pause, Play, Volume2, VolumeX } from 'lucide-react';
+import React from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+import { useMediaRemote, useMediaStore } from '@vidstack/react';
+
+import type { MediaPlayerInstance } from '@vidstack/react';
+interface VideoControlsProps {
+  player: React.RefObject<MediaPlayerInstance | null>;
+  className?: string;
+}
+
+export function VideoControls({ player, className }: VideoControlsProps) {
+  const store = useMediaStore(player);
+  const remote = useMediaRemote();
+
+  const isPaused = store.paused;
+  const isMuted = store.muted;
+  const isFullscreen = store.fullscreen;
+  const currentTime = store.currentTime;
+  const duration = store.duration;
+  const volume = store.volume;
+
+  const formatTime = (seconds: number): string => {
+    if (!seconds || seconds < 0) return '0:00';
+    const minutes = Math.floor(seconds / 60);
+    const secs = Math.floor(seconds % 60);
+    return `${minutes}:${secs.toString().padStart(2, '0')}`;
+  };
+
+  const handleProgressClick = (e: React.MouseEvent<HTMLDivElement>) => {
+    if (!duration) return;
+    const rect = e.currentTarget.getBoundingClientRect();
+    const clickX = e.clientX - rect.left;
+    const percentage = clickX / rect.width;
+    const newTime = percentage * duration;
+    remote.seek(newTime);
+  };
+
+  const handleVolumeChange = (e: React.MouseEvent<HTMLDivElement>) => {
+    const rect = e.currentTarget.getBoundingClientRect();
+    const clickX = e.clientX - rect.left;
+    const percentage = Math.max(0, Math.min(1, clickX / rect.width));
+    remote.changeVolume(percentage);
+    if (percentage > 0 && isMuted) {
+      remote.toggleMuted();
+    }
+  };
+
+  const progress = duration > 0 ? (currentTime / duration) * 100 : 0;
+
+  return (
+    <div
+      className={cn(
+        "absolute inset-0 flex flex-col justify-end transition-opacity duration-300",
+        "bg-gradient-to-t from-black/80 via-black/20 to-transparent",
+        "opacity-0 group-hover:opacity-100 focus-within:opacity-100",
+        "pointer-events-none group-hover:pointer-events-auto",
+        className
+      )}
+    >
+      {/* Progress Bar */}
+      <div className="px-4 pb-2 pointer-events-auto">
+        <div
+          className="h-1.5 bg-white/20 rounded-full cursor-pointer hover:h-2 transition-all group"
+          onClick={handleProgressClick}
+        >
+          <div
+            className="h-full bg-primary rounded-full transition-all relative group-hover:bg-primary/90"
+            style={{ width: `${progress}%` }}
+          >
+            <div className="absolute right-0 top-1/2 -translate-y-1/2 w-3 h-3 bg-white rounded-full opacity-0 group-hover:opacity-100 transition-opacity" />
+          </div>
+        </div>
+      </div>
+
+      {/* Control Bar */}
+      <div className="flex items-center gap-4 px-4 pb-4 pointer-events-auto">
+        {/* Play/Pause */}
+        <button
+          onClick={() => remote.togglePaused()}
+          className="text-white hover:text-primary transition-colors p-1.5 hover:bg-white/10 rounded-full"
+        >
+          {isPaused ? <Play className="h-6 w-6" /> : <Pause className="h-6 w-6" />}
+        </button>
+
+        {/* Time */}
+        <div className="text-white text-sm font-medium">
+          {formatTime(currentTime)} / {formatTime(duration)}
+        </div>
+
+        <div className="flex-1" />
+
+        {/* Volume Control */}
+        <div className="flex items-center gap-2 group/volume">
+          <button
+            onClick={() => remote.toggleMuted()}
+            className="text-white hover:text-primary transition-colors p-1.5 hover:bg-white/10 rounded-full"
+          >
+            {isMuted || volume === 0 ? (
+              <VolumeX className="h-5 w-5" />
+            ) : (
+              <Volume2 className="h-5 w-5" />
+            )}
+          </button>
+
+          <div
+            className="w-0 group-hover/volume:w-20 transition-all overflow-hidden"
+          >
+            <div
+              className="h-1.5 bg-white/20 rounded-full cursor-pointer hover:h-2 transition-all"
+              onClick={handleVolumeChange}
+            >
+              <div
+                className="h-full bg-white rounded-full transition-all"
+                style={{ width: `${volume * 100}%` }}
+              />
+            </div>
+          </div>
+        </div>
+
+        {/* Fullscreen */}
+        <button
+          onClick={() => isFullscreen ? remote.exitFullscreen() : remote.enterFullscreen()}
+          className="text-white hover:text-primary transition-colors p-1.5 hover:bg-white/10 rounded-full"
+        >
+          {isFullscreen ? <Minimize className="h-5 w-5" /> : <Maximize className="h-5 w-5" />}
+        </button>
+      </div>
+    </div>
+  );
+}

package/src/tools/VideoPlayer/components/VideoErrorFallback.tsx

@@ -0,0 +1,172 @@
+/**
+ * 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, Button, DownloadButton } from '../../_shared';
+
+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}
+    />
+  );
+}