@djangocfg/ui-nextjs 2.1.65 → 2.1.66

package/src/tools/VideoPlayer/providers/VidstackProvider.tsx

@@ -0,0 +1,254 @@
+/**
+ * VidstackProvider - Full-featured video player using Vidstack
+ * Supports YouTube, Vimeo, HLS, DASH, and direct URLs
+ */
+
+'use client';
+
+// Import Vidstack base styles
+import '@vidstack/react/player/styles/base.css';
+import '@vidstack/react/player/styles/default/theme.css';
+import '@vidstack/react/player/styles/default/layouts/video.css';
+
+import React, { forwardRef, useCallback, useImperativeHandle, useMemo, useRef, useState } from 'react';
+
+import { cn, generateOgImageUrl } from '@djangocfg/ui-core/lib';
+import { MediaPlayer, MediaProvider, Poster } from '@vidstack/react';
+import { defaultLayoutIcons, DefaultVideoLayout } from '@vidstack/react/player/layouts/default';
+
+import type { MediaPlayerInstance } from '@vidstack/react';
+import type { VidstackProviderProps, VideoPlayerRef, ErrorFallbackProps } from '../types';
+
+/**
+ * Convert source to Vidstack-compatible format
+ */
+function getVidstackSrc(source: VidstackProviderProps['source']): string {
+  switch (source.type) {
+    case 'youtube':
+      return `youtube/${source.id}`;
+    case 'vimeo':
+      return `vimeo/${source.id}`;
+    case 'hls':
+    case 'dash':
+    case 'url':
+      return source.url;
+    default:
+      return '';
+  }
+}
+
+/** Default error fallback UI */
+function DefaultErrorFallback({ error }: ErrorFallbackProps) {
+  return (
+    <div className="absolute inset-0 flex flex-col items-center justify-center gap-4 text-white bg-black">
+      <svg
+        className="w-16 h-16 text-muted-foreground"
+        fill="none"
+        stroke="currentColor"
+        viewBox="0 0 24 24"
+      >
+        <path
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          strokeWidth={2}
+          d="M15 10l4.553-2.276A1 1 0 0121 8.618v6.764a1 1 0 01-1.447.894L15 14M5 18h8a2 2 0 002-2V8a2 2 0 00-2-2H5a2 2 0 00-2 2v8a2 2 0 002 2z"
+        />
+      </svg>
+      <p className="text-lg">{error || 'Video cannot be played'}</p>
+    </div>
+  );
+}
+
+export const VidstackProvider = forwardRef<VideoPlayerRef, VidstackProviderProps>(
+  (
+    {
+      source,
+      aspectRatio = 16 / 9,
+      autoPlay = false,
+      muted = false,
+      loop = false,
+      playsInline = true,
+      controls = true,
+      className,
+      showInfo = false,
+      theme = 'default',
+      errorFallback,
+      onPlay,
+      onPause,
+      onEnded,
+      onError,
+      onLoadStart,
+      onCanPlay,
+      onTimeUpdate,
+    },
+    ref
+  ) => {
+    const playerRef = useRef<MediaPlayerInstance | null>(null);
+    const [hasError, setHasError] = useState(false);
+    const [errorMessage, setErrorMessage] = useState<string>('Video cannot be played');
+
+    // Generate poster if not provided
+    const posterUrl = useMemo(() => {
+      if (source.poster) return source.poster;
+      if (!source.title) return undefined;
+      return generateOgImageUrl({ title: source.title });
+    }, [source.poster, source.title]);
+
+    // Get Vidstack-compatible source URL
+    const vidstackSrc = useMemo(() => getVidstackSrc(source), [source]);
+
+    // Retry function
+    const retry = useCallback(() => {
+      setHasError(false);
+      setErrorMessage('Video cannot be played');
+      // Force reload by updating key would be needed, but for now just reset state
+      const player = playerRef.current;
+      if (player) {
+        player.currentTime = 0;
+        player.play();
+      }
+    }, []);
+
+    // Expose player methods via ref
+    useImperativeHandle(
+      ref,
+      () => {
+        const player = playerRef.current;
+
+        return {
+          play: () => player?.play(),
+          pause: () => player?.pause(),
+          togglePlay: () => {
+            if (player) {
+              player.paused ? player.play() : player.pause();
+            }
+          },
+          seekTo: (time: number) => {
+            if (player) player.currentTime = time;
+          },
+          setVolume: (volume: number) => {
+            if (player) player.volume = Math.max(0, Math.min(1, volume));
+          },
+          toggleMute: () => {
+            if (player) player.muted = !player.muted;
+          },
+          enterFullscreen: () => player?.enterFullscreen(),
+          exitFullscreen: () => player?.exitFullscreen(),
+          get currentTime() {
+            return player?.currentTime ?? 0;
+          },
+          get duration() {
+            return player?.duration ?? 0;
+          },
+          get paused() {
+            return player?.paused ?? true;
+          },
+        };
+      },
+      []
+    );
+
+    const handlePlay = () => onPlay?.();
+    const handlePause = () => onPause?.();
+    const handleEnded = () => onEnded?.();
+    const handleError = (detail: unknown) => {
+      const error = detail as { message?: string };
+      const msg = error?.message || 'Video playback error';
+      setHasError(true);
+      setErrorMessage(msg);
+      onError?.(msg);
+    };
+    const handleLoadStart = () => onLoadStart?.();
+    const handleCanPlay = () => {
+      setHasError(false);
+      onCanPlay?.();
+    };
+    const handleTimeUpdate = () => {
+      const player = playerRef.current;
+      if (player && onTimeUpdate) {
+        onTimeUpdate(player.currentTime, player.duration);
+      }
+    };
+
+    // Determine layout mode
+    const isFillMode = aspectRatio === 'fill';
+    const computedAspectRatio = aspectRatio === 'auto' || aspectRatio === 'fill' ? undefined : aspectRatio;
+
+    // Render error fallback
+    const renderErrorFallback = () => {
+      const fallbackProps: ErrorFallbackProps = { error: errorMessage, retry };
+
+      if (typeof errorFallback === 'function') {
+        return errorFallback(fallbackProps);
+      }
+
+      if (errorFallback) {
+        return errorFallback;
+      }
+
+      return <DefaultErrorFallback {...fallbackProps} />;
+    };
+
+    // Container styles based on mode
+    const containerStyles = isFillMode
+      ? { width: '100%', height: '100%' }
+      : { aspectRatio: computedAspectRatio };
+
+    return (
+      <div className={cn(isFillMode ? 'w-full h-full' : 'w-full', className)}>
+        <div
+          className={cn(
+            'relative w-full rounded-sm bg-black overflow-hidden',
+            isFillMode && 'h-full',
+            theme === 'minimal' && 'rounded-none',
+            theme === 'modern' && 'rounded-xl shadow-2xl'
+          )}
+          style={containerStyles}
+        >
+          {hasError ? (
+            renderErrorFallback()
+          ) : (
+            <MediaPlayer
+              ref={playerRef}
+              title={source.title || 'Video'}
+              src={vidstackSrc}
+              autoPlay={autoPlay}
+              muted={muted}
+              loop={loop}
+              playsInline={playsInline}
+              onPlay={handlePlay}
+              onPause={handlePause}
+              onEnded={handleEnded}
+              onError={handleError}
+              onLoadStart={handleLoadStart}
+              onCanPlay={handleCanPlay}
+              onTimeUpdate={handleTimeUpdate}
+              className="w-full h-full"
+            >
+              <MediaProvider />
+
+              {posterUrl && (
+                <Poster
+                  className="vds-poster"
+                  src={posterUrl}
+                  alt={source.title || 'Video poster'}
+                  style={{ objectFit: 'cover' }}
+                />
+              )}
+
+              {controls && <DefaultVideoLayout icons={defaultLayoutIcons} thumbnails={posterUrl} />}
+            </MediaPlayer>
+          )}
+        </div>
+
+        {showInfo && source.title && (
+          <div className="mt-4 space-y-2">
+            <h3 className="text-xl font-semibold text-foreground">{source.title}</h3>
+          </div>
+        )}
+      </div>
+    );
+  }
+);
+
+VidstackProvider.displayName = 'VidstackProvider';

package/src/tools/VideoPlayer/providers/index.ts

@@ -0,0 +1,8 @@
+/**
+ * VideoPlayer Providers
+ * Each provider handles a specific type of video playback
+ */
+
+export { VidstackProvider } from './VidstackProvider';
+export { NativeProvider } from './NativeProvider';
+export { StreamProvider } from './StreamProvider';

package/src/tools/VideoPlayer/types.ts

@@ -1,54 +1,195 @@
 /**
- * VideoPlayer Types - Professional Vidstack Implementation
+ * VideoPlayer Types - Unified Video Player
+ * Supports Vidstack, Native HTML5, and HTTP Streaming
  */
 
-export interface VideoSource {
-  /** Video URL - supports YouTube, Vimeo, MP4, HLS, etc. */
+import type React from 'react';
+
+// ============================================================================
+// Source Types - Different ways to provide video content
+// ============================================================================
+
+/** Simple URL source (mp4, webm, etc.) */
+export interface UrlSource {
+  type: 'url';
   url: string;
-  /** Video title */
   title?: string;
-  /** Video description */
-  description?: string;
-  /** Custom poster/thumbnail URL */
   poster?: string;
-  /** Video duration in seconds */
-  duration?: number;
 }
 
-export interface VideoPlayerProps {
-  /** Video source configuration */
-  source: VideoSource;
-  /** Aspect ratio (default: 16/9) */
-  aspectRatio?: number;
+/** YouTube embed source */
+export interface YouTubeSource {
+  type: 'youtube';
+  /** YouTube video ID (11 characters) */
+  id: string;
+  title?: string;
+  poster?: string;
+}
+
+/** Vimeo embed source */
+export interface VimeoSource {
+  type: 'vimeo';
+  /** Vimeo video ID */
+  id: string;
+  title?: string;
+  poster?: string;
+}
+
+/** HLS streaming source */
+export interface HLSSource {
+  type: 'hls';
+  /** URL to .m3u8 manifest */
+  url: string;
+  title?: string;
+  poster?: string;
+}
+
+/** DASH streaming source */
+export interface DASHSource {
+  type: 'dash';
+  /** URL to .mpd manifest */
+  url: string;
+  title?: string;
+  poster?: string;
+}
+
+/** HTTP Range streaming source (for large files with auth) */
+export interface StreamSource {
+  type: 'stream';
+  /** Session ID for authorization */
+  sessionId: string;
+  /** File path on server */
+  path: string;
+  /** Function to generate stream URL */
+  getStreamUrl: (sessionId: string, path: string) => string;
+  /** MIME type for the video */
+  mimeType?: string;
+  title?: string;
+  poster?: string;
+}
+
+/** Binary data source (ArrayBuffer) */
+export interface BlobSource {
+  type: 'blob';
+  /** Video data as ArrayBuffer */
+  data: ArrayBuffer;
+  /** MIME type (default: video/mp4) */
+  mimeType?: string;
+  title?: string;
+  poster?: string;
+}
+
+/** Base64 data URL source */
+export interface DataUrlSource {
+  type: 'data-url';
+  /** Base64 encoded data URL */
+  data: string;
+  title?: string;
+  poster?: string;
+}
+
+/** Union of all source types */
+export type VideoSourceUnion =
+  | UrlSource
+  | YouTubeSource
+  | VimeoSource
+  | HLSSource
+  | DASHSource
+  | StreamSource
+  | BlobSource
+  | DataUrlSource;
+
+// ============================================================================
+// Player Mode
+// ============================================================================
+
+/** Player mode - determines which provider to use */
+export type PlayerMode =
+  | 'auto'      // Auto-select based on source type
+  | 'vidstack'  // Force Vidstack (full-featured)
+  | 'native'    // Force native HTML5 <video>
+  | 'streaming'; // Force streaming provider
+
+// ============================================================================
+// Player Props
+// ============================================================================
+
+/** Aspect ratio options */
+export type AspectRatioValue = number | 'auto' | 'fill';
+
+/** Common player settings */
+export interface CommonPlayerSettings {
   /** Auto-play video */
-  autoplay?: boolean;
+  autoPlay?: boolean;
   /** Mute video by default */
   muted?: boolean;
+  /** Loop video */
+  loop?: boolean;
   /** Play video inline on mobile */
   playsInline?: boolean;
-  /** Show custom controls */
+  /** Show player controls */
   controls?: boolean;
-  /** Custom CSS class */
-  className?: string;
-  /** Show video info */
-  showInfo?: boolean;
-  /** Player theme */
-  theme?: 'default' | 'minimal' | 'modern';
-  /** Event callbacks */
+  /**
+   * Aspect ratio:
+   * - number (e.g. 16/9): Fixed aspect ratio
+   * - 'auto': Natural video aspect ratio
+   * - 'fill': Fill parent container (100% width & height)
+   */
+  aspectRatio?: AspectRatioValue;
+  /** Preload strategy */
+  preload?: 'auto' | 'metadata' | 'none';
+}
+
+/** Common player events */
+export interface CommonPlayerEvents {
   onPlay?: () => void;
   onPause?: () => void;
   onEnded?: () => void;
   onError?: (error: string) => void;
+  onLoadStart?: () => void;
+  onCanPlay?: () => void;
+  onTimeUpdate?: (currentTime: number, duration: number) => void;
+}
+
+/** Error fallback render props */
+export interface ErrorFallbackProps {
+  error: string;
+  retry?: () => void;
+}
+
+/** Main VideoPlayer props */
+export interface VideoPlayerProps extends CommonPlayerSettings, CommonPlayerEvents {
+  /** Video source configuration */
+  source: VideoSourceUnion;
+  /** Player mode (default: 'auto') */
+  mode?: PlayerMode;
+  /** Player theme (Vidstack only) */
+  theme?: 'default' | 'minimal' | 'modern';
+  /** Show video info below player */
+  showInfo?: boolean;
+  /** Container className */
+  className?: string;
+  /** Video element className (native/streaming only) */
+  videoClassName?: string;
+  /** Disable right-click context menu */
+  disableContextMenu?: boolean;
+  /** Show loading spinner */
+  showPreloader?: boolean;
+  /** Preloader timeout in ms */
+  preloaderTimeout?: number;
+  /** Custom error fallback UI */
+  errorFallback?: React.ReactNode | ((props: ErrorFallbackProps) => React.ReactNode);
 }
 
+/** VideoPlayer ref methods */
 export interface VideoPlayerRef {
   /** Play video */
-  play: () => void;
+  play: () => Promise<void> | void;
   /** Pause video */
   pause: () => void;
   /** Toggle play/pause */
   togglePlay: () => void;
-  /** Seek to time */
+  /** Seek to time in seconds */
   seekTo: (time: number) => void;
   /** Set volume (0-1) */
   setVolume: (volume: number) => void;
@@ -58,61 +199,169 @@ export interface VideoPlayerRef {
   enterFullscreen: () => void;
   /** Exit fullscreen */
   exitFullscreen: () => void;
+  /** Current playback time in seconds */
+  readonly currentTime: number;
+  /** Video duration in seconds */
+  readonly duration: number;
+  /** Whether video is paused */
+  readonly paused: boolean;
 }
 
-/**
- * NativePlayer Types - Lightweight HTML5 video player
- */
+// ============================================================================
+// Provider-specific Props (internal use)
+// ============================================================================
 
-export interface NativePlayerProps {
-  /** Video source URL (MP4, WebM) */
-  src: string;
-  /** Poster/thumbnail image URL */
-  poster?: string;
-  /** Aspect ratio (default: 16/9) */
-  aspectRatio?: number;
-  /** Auto-play video (default: true) */
-  autoPlay?: boolean;
-  /** Mute video (default: true) */
-  muted?: boolean;
-  /** Loop video (default: true) */
-  loop?: boolean;
-  /** Play video inline on mobile (default: true) */
-  playsInline?: boolean;
-  /** Preload strategy (default: 'auto') */
-  preload?: 'auto' | 'metadata' | 'none';
-  /** Show native browser controls (default: false) */
-  controls?: boolean;
-  /** Disable right-click context menu (default: true) */
+/** Props passed to Vidstack provider */
+export interface VidstackProviderProps extends CommonPlayerSettings, CommonPlayerEvents {
+  source: UrlSource | YouTubeSource | VimeoSource | HLSSource | DASHSource;
+  theme?: 'default' | 'minimal' | 'modern';
+  showInfo?: boolean;
+  className?: string;
+  errorFallback?: React.ReactNode | ((props: ErrorFallbackProps) => React.ReactNode);
+}
+
+/** Props passed to Native provider */
+export interface NativeProviderProps extends CommonPlayerSettings, CommonPlayerEvents {
+  source: UrlSource | DataUrlSource;
+  className?: string;
+  videoClassName?: string;
   disableContextMenu?: boolean;
-  /** Show preloader while video loads (default: true) */
   showPreloader?: boolean;
-  /** Preloader timeout in ms - hide even if not loaded (default: 5000) */
   preloaderTimeout?: number;
-  /** Container className */
+}
+
+/** Props passed to Stream provider */
+export interface StreamProviderProps extends CommonPlayerSettings, CommonPlayerEvents {
+  source: StreamSource | BlobSource | DataUrlSource;
   className?: string;
-  /** Video element className */
   videoClassName?: string;
-  /** Preloader overlay className */
-  preloaderClassName?: string;
-  /** Event callbacks */
-  onLoadStart?: () => void;
-  onCanPlay?: () => void;
-  onPlaying?: () => void;
-  onEnded?: () => void;
-  onError?: (e: React.SyntheticEvent<HTMLVideoElement, Event>) => void;
+  disableContextMenu?: boolean;
+  showPreloader?: boolean;
+  preloaderTimeout?: number;
+  errorFallback?: React.ReactNode | ((props: ErrorFallbackProps) => React.ReactNode);
 }
 
-export interface NativePlayerRef {
-  /** Play video */
-  play: () => Promise<void> | undefined;
-  /** Pause video */
-  pause: () => void;
-  /** Current playback time in seconds */
-  currentTime: number;
-  /** Whether video is paused */
-  paused: boolean;
-  /** Direct access to video element */
-  element: HTMLVideoElement | null;
+// ============================================================================
+// Helper function to resolve mode
+// ============================================================================
+
+/** Determine which provider to use based on source type */
+export function resolvePlayerMode(source: VideoSourceUnion, mode: PlayerMode = 'auto'): 'vidstack' | 'native' | 'streaming' {
+  if (mode !== 'auto') {
+    return mode;
+  }
+
+  switch (source.type) {
+    case 'youtube':
+    case 'vimeo':
+    case 'hls':
+    case 'dash':
+      return 'vidstack';
+
+    case 'stream':
+    case 'blob':
+      return 'streaming';
+
+    case 'data-url':
+    case 'url':
+    default:
+      return 'native';
+  }
 }
 
+// ============================================================================
+// File Source Helper (for FileWorkspace integration)
+// ============================================================================
+
+/** Options for resolving file source */
+export interface ResolveFileSourceOptions {
+  /** File content - can be data URL string or binary ArrayBuffer */
+  content: string | ArrayBuffer | null | undefined;
+  /** File path for streaming */
+  path: string;
+  /** MIME type of the file */
+  mimeType?: string;
+  /** Session ID for authenticated streaming */
+  sessionId?: string | null;
+  /** Load method hint - 'http_stream' enables streaming mode */
+  loadMethod?: 'http_stream' | 'rpc' | 'unspecified' | 'skip' | string;
+  /** Function to generate stream URL (required for streaming) */
+  getStreamUrl?: (sessionId: string, path: string) => string;
+  /** Optional title */
+  title?: string;
+  /** Optional poster */
+  poster?: string;
+}
+
+/**
+ * Resolve file content to VideoSourceUnion
+ * Useful for FileWorkspace/file manager integrations
+ *
+ * @example
+ * const source = resolveFileSource({
+ *   content: file.content,
+ *   path: file.path,
+ *   mimeType: file.mimeType,
+ *   sessionId: sessionId,
+ *   loadMethod: file.loadMethod,
+ *   getStreamUrl: terminalClient.terminal_media.streamStreamRetrieveUrl
+ * });
+ *
+ * <VideoPlayer source={source} />
+ */
+export function resolveFileSource(options: ResolveFileSourceOptions): VideoSourceUnion | null {
+  const {
+    content,
+    path,
+    mimeType,
+    sessionId,
+    loadMethod,
+    getStreamUrl,
+    title,
+    poster,
+  } = options;
+
+  const contentSize = content
+    ? typeof content === 'string'
+      ? content.length
+      : content.byteLength
+    : 0;
+  const hasContent = contentSize > 0;
+
+  // Priority 1: HTTP Range streaming for large files
+  if (loadMethod === 'http_stream' && !hasContent && sessionId && getStreamUrl) {
+    return {
+      type: 'stream',
+      sessionId,
+      path,
+      getStreamUrl,
+      mimeType,
+      title,
+      poster,
+    };
+  }
+
+  // Priority 2: Data URL (base64 string)
+  if (typeof content === 'string' && hasContent) {
+    return {
+      type: 'data-url',
+      data: content,
+      title,
+      poster,
+    };
+  }
+
+  // Priority 3: ArrayBuffer → Blob
+  if (content instanceof ArrayBuffer && hasContent) {
+    return {
+      type: 'blob',
+      data: content,
+      mimeType: mimeType || 'video/mp4',
+      title,
+      poster,
+    };
+  }
+
+  // No valid content
+  return null;
+}