@djangocfg/ui-nextjs 2.1.65 → 2.1.67

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

@@ -0,0 +1,201 @@
+/**
+ * VideoPlayer - Unified Video Player Component
+ *
+ * Supports multiple modes:
+ * - vidstack: Full-featured player (YouTube, Vimeo, HLS, DASH)
+ * - native: Lightweight HTML5 player
+ * - streaming: HTTP Range streaming with auth / Blob sources
+ *
+ * @example
+ * // YouTube video
+ * <VideoPlayer source={{ type: 'youtube', id: 'dQw4w9WgXcQ' }} />
+ *
+ * @example
+ * // HLS stream
+ * <VideoPlayer source={{ type: 'hls', url: 'https://example.com/video.m3u8' }} />
+ *
+ * @example
+ * // HTTP Range streaming with auth (full source)
+ * <VideoPlayer
+ *   source={{
+ *     type: 'stream',
+ *     sessionId: 'abc123',
+ *     path: '/videos/movie.mp4',
+ *     getStreamUrl: (id, path) => `/api/stream/${id}?path=${path}&token=${token}`
+ *   }}
+ * />
+ *
+ * @example
+ * // HTTP Range streaming (simplified, using VideoPlayerProvider context)
+ * <VideoPlayerProvider sessionId={sessionId} getStreamUrl={getStreamUrl}>
+ *   <VideoPlayer source={{ type: 'stream', path: '/videos/movie.mp4' }} />
+ * </VideoPlayerProvider>
+ *
+ * @example
+ * // Blob/ArrayBuffer
+ * <VideoPlayer source={{ type: 'blob', data: arrayBuffer, mimeType: 'video/mp4' }} />
+ */
+
+'use client';
+
+import React, { forwardRef, useMemo } from 'react';
+
+import { VidstackProvider, NativeProvider, StreamProvider } from '../providers';
+import { useVideoPlayerContext } from '../context';
+import { resolvePlayerMode, isSimpleStreamSource, resolveStreamSource } from '../utils';
+
+import type { VideoPlayerProps, VideoPlayerRef, VideoSourceUnion, VidstackProviderProps, NativeProviderProps, StreamProviderProps, SimpleStreamSource } from '../types';
+
+export const VideoPlayer = forwardRef<VideoPlayerRef, VideoPlayerProps & { source: VideoSourceUnion | SimpleStreamSource }>(
+  (
+    {
+      source: rawSource,
+      mode = 'auto',
+      aspectRatio = 16 / 9,
+      autoPlay = false,
+      muted = false,
+      loop = false,
+      playsInline = true,
+      controls = true,
+      preload = 'metadata',
+      theme = 'default',
+      showInfo = false,
+      className,
+      videoClassName,
+      disableContextMenu = false,
+      showPreloader = true,
+      preloaderTimeout = 5000,
+      errorFallback,
+      onPlay,
+      onPause,
+      onEnded,
+      onError,
+      onLoadStart,
+      onCanPlay,
+      onTimeUpdate,
+    },
+    ref
+  ) => {
+    // Get context for simplified stream sources
+    const context = useVideoPlayerContext();
+
+    // Resolve simplified stream source to full source using context
+    const source = useMemo(() => {
+      if (isSimpleStreamSource(rawSource)) {
+        const resolved = resolveStreamSource(rawSource, context);
+        if (!resolved) {
+          // Return a special error source that will trigger error fallback
+          return null;
+        }
+        return resolved;
+      }
+      return rawSource;
+    }, [rawSource, context]);
+
+    // Handle unresolved source
+    if (!source) {
+      // Render error state
+      const errorMessage = 'Stream source requires VideoPlayerProvider with getStreamUrl and sessionId';
+
+      if (typeof errorFallback === 'function') {
+        return (
+          <div className={className} style={{ aspectRatio: aspectRatio === 'fill' ? undefined : aspectRatio }}>
+            {errorFallback({ error: errorMessage })}
+          </div>
+        );
+      }
+
+      if (errorFallback) {
+        return (
+          <div className={className} style={{ aspectRatio: aspectRatio === 'fill' ? undefined : aspectRatio }}>
+            {errorFallback}
+          </div>
+        );
+      }
+
+      // Default error UI
+      return (
+        <div
+          className={className}
+          style={{
+            aspectRatio: aspectRatio === 'fill' ? undefined : aspectRatio,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            backgroundColor: 'black',
+            color: 'white',
+          }}
+        >
+          <p>{errorMessage}</p>
+        </div>
+      );
+    }
+
+    // Determine which provider to use
+    const resolvedMode = resolvePlayerMode(source, mode);
+
+    // Common props for all providers
+    const commonProps = {
+      aspectRatio,
+      autoPlay,
+      muted,
+      loop,
+      playsInline,
+      controls,
+      preload,
+      className,
+      onPlay,
+      onPause,
+      onEnded,
+      onError,
+      onLoadStart,
+      onCanPlay,
+      onTimeUpdate,
+    };
+
+    // Render appropriate provider
+    switch (resolvedMode) {
+      case 'vidstack':
+        return (
+          <VidstackProvider
+            ref={ref}
+            source={source as VidstackProviderProps['source']}
+            theme={theme}
+            showInfo={showInfo}
+            errorFallback={errorFallback}
+            {...commonProps}
+          />
+        );
+
+      case 'streaming':
+        return (
+          <StreamProvider
+            ref={ref}
+            source={source as StreamProviderProps['source']}
+            videoClassName={videoClassName}
+            disableContextMenu={disableContextMenu}
+            showPreloader={showPreloader}
+            preloaderTimeout={preloaderTimeout}
+            errorFallback={errorFallback}
+            {...commonProps}
+          />
+        );
+
+      case 'native':
+      default:
+        return (
+          <NativeProvider
+            ref={ref}
+            source={source as NativeProviderProps['source']}
+            videoClassName={videoClassName}
+            disableContextMenu={disableContextMenu}
+            showPreloader={showPreloader}
+            preloaderTimeout={preloaderTimeout}
+            {...commonProps}
+          />
+        );
+    }
+  }
+);
+
+VideoPlayer.displayName = 'VideoPlayer';

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

@@ -0,0 +1,14 @@
+/**
+ * VideoPlayer components - Public API
+ */
+
+export { VideoPlayer } from './VideoPlayer';
+export { VideoControls } from './VideoControls';
+export {
+  VideoErrorFallback,
+  createVideoErrorFallback,
+} from './VideoErrorFallback';
+export type {
+  VideoErrorFallbackProps,
+  CreateVideoErrorFallbackOptions,
+} from './VideoErrorFallback';

package/src/tools/VideoPlayer/context/VideoPlayerContext.tsx

@@ -0,0 +1,52 @@
+/**
+ * VideoPlayerContext - Context for streaming configuration
+ * Simplifies streaming API by providing getStreamUrl globally
+ */
+
+'use client';
+
+import React, { createContext, useContext, useMemo } from 'react';
+
+import type { VideoPlayerContextValue, VideoPlayerProviderProps } from '../types';
+
+// =============================================================================
+// Context
+// =============================================================================
+
+const VideoPlayerContext = createContext<VideoPlayerContextValue | null>(null);
+
+/**
+ * Provider for VideoPlayer streaming configuration
+ *
+ * @example
+ * // In your app layout or FileWorkspace
+ * <VideoPlayerProvider
+ *   sessionId={sessionId}
+ *   getStreamUrl={terminalClient.terminal_media.streamStreamRetrieveUrl}
+ * >
+ *   <VideoPlayer source={{ type: 'stream', path: '/video.mp4' }} />
+ * </VideoPlayerProvider>
+ */
+export function VideoPlayerProvider({
+  children,
+  getStreamUrl,
+  sessionId,
+}: VideoPlayerProviderProps) {
+  const value = useMemo(
+    () => ({ getStreamUrl, sessionId }),
+    [getStreamUrl, sessionId]
+  );
+
+  return (
+    <VideoPlayerContext.Provider value={value}>
+      {children}
+    </VideoPlayerContext.Provider>
+  );
+}
+
+/**
+ * Hook to access VideoPlayer context
+ */
+export function useVideoPlayerContext(): VideoPlayerContextValue | null {
+  return useContext(VideoPlayerContext);
+}

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

@@ -0,0 +1,8 @@
+/**
+ * VideoPlayer context - Public API
+ */
+
+export {
+  VideoPlayerProvider,
+  useVideoPlayerContext,
+} from './VideoPlayerContext';

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

@@ -0,0 +1,9 @@
+/**
+ * VideoPlayer hooks - Public API
+ */
+
+export { useVideoPositionCache } from './useVideoPositionCache';
+export type {
+  UseVideoPositionCacheOptions,
+  UseVideoPositionCacheReturn,
+} from './useVideoPositionCache';

package/src/tools/VideoPlayer/hooks/useVideoPositionCache.ts

@@ -0,0 +1,109 @@
+'use client';
+
+/**
+ * useVideoPositionCache - Manages video playback position caching
+ *
+ * Saves position periodically during playback and restores on load.
+ */
+
+import { useRef, useEffect, useCallback } from 'react';
+import { useVideoCache } from '../../../stores/mediaCache';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface UseVideoPositionCacheOptions {
+  /** Unique key for caching (e.g., video URL or stream key) */
+  cacheKey: string | null;
+  /** Current playback time in seconds */
+  currentTime: number;
+  /** Video duration in seconds */
+  duration: number;
+  /** Whether video is currently playing */
+  isPlaying: boolean;
+  /** Whether video is ready to play */
+  isReady: boolean;
+  /** Callback to seek to a specific time */
+  onSeek: (time: number) => void;
+}
+
+export interface UseVideoPositionCacheReturn {
+  /** Manually save current position */
+  savePosition: () => void;
+  /** Clear saved position */
+  clearPosition: () => void;
+}
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+/** Save interval in seconds */
+const SAVE_INTERVAL = 5;
+
+/** Minimum offset from end to restore (avoid restoring at the very end) */
+const END_BUFFER = 1;
+
+// =============================================================================
+// HOOK
+// =============================================================================
+
+export function useVideoPositionCache(
+  options: UseVideoPositionCacheOptions
+): UseVideoPositionCacheReturn {
+  const { cacheKey, currentTime, duration, isPlaying, isReady, onSeek } = options;
+
+  const { saveVideoPosition, getVideoPosition } = useVideoCache();
+  const lastSavedTimeRef = useRef<number>(0);
+  const hasRestoredRef = useRef<boolean>(false);
+
+  // Restore position when ready
+  useEffect(() => {
+    if (!isReady || !cacheKey || hasRestoredRef.current) return;
+
+    const savedPosition = getVideoPosition(cacheKey);
+    if (savedPosition && savedPosition > 0 && duration > 0) {
+      // Only restore if position is valid (not at the end)
+      if (savedPosition < duration - END_BUFFER) {
+        onSeek(savedPosition);
+      }
+    }
+    hasRestoredRef.current = true;
+  }, [isReady, cacheKey, duration, getVideoPosition, onSeek]);
+
+  // Reset restored flag when cache key changes
+  useEffect(() => {
+    hasRestoredRef.current = false;
+    lastSavedTimeRef.current = 0;
+  }, [cacheKey]);
+
+  // Save position periodically during playback
+  useEffect(() => {
+    if (!cacheKey || !isPlaying || currentTime <= 0) return;
+
+    const timeSinceLastSave = currentTime - lastSavedTimeRef.current;
+    if (timeSinceLastSave >= SAVE_INTERVAL || timeSinceLastSave < 0) {
+      saveVideoPosition(cacheKey, currentTime);
+      lastSavedTimeRef.current = currentTime;
+    }
+  }, [cacheKey, isPlaying, currentTime, saveVideoPosition]);
+
+  const savePosition = useCallback(() => {
+    if (cacheKey && currentTime > 0) {
+      saveVideoPosition(cacheKey, currentTime);
+      lastSavedTimeRef.current = currentTime;
+    }
+  }, [cacheKey, currentTime, saveVideoPosition]);
+
+  const clearPosition = useCallback(() => {
+    if (cacheKey) {
+      saveVideoPosition(cacheKey, 0);
+    }
+  }, [cacheKey, saveVideoPosition]);
+
+  return {
+    savePosition,
+    clearPosition,
+  };
+}

package/src/tools/VideoPlayer/index.ts

@@ -1,16 +1,77 @@
 /**
- * Professional VideoPlayer - Vidstack Implementation
- * Export all components and types
+ * VideoPlayer - Unified Video Player
+ * Supports Vidstack (YouTube, Vimeo, HLS, DASH), Native HTML5, and HTTP Streaming
  */
 
-export { VideoPlayer, VideoUrlError } from './VideoPlayer';
-export { NativePlayer } from './NativePlayer';
-export { VideoControls } from './VideoControls';
+// Main component
+export { VideoPlayer } from './components';
+
+// Controls (can be used standalone with Vidstack)
+export { VideoControls } from './components';
+
+// Error Fallback
+export {
+  VideoErrorFallback,
+  createVideoErrorFallback,
+} from './components';
+export type {
+  VideoErrorFallbackProps,
+  CreateVideoErrorFallbackOptions,
+} from './components';
+
+// Providers (for advanced usage)
+export { VidstackProvider, NativeProvider, StreamProvider } from './providers';
+
+// Context (for streaming configuration)
+export {
+  VideoPlayerProvider,
+  useVideoPlayerContext,
+} from './context';
+
+// Hooks
+export { useVideoPositionCache } from './hooks';
 export type {
-  VideoSource,
+  UseVideoPositionCacheOptions,
+  UseVideoPositionCacheReturn,
+} from './hooks';
+
+// Utils
+export {
+  resolvePlayerMode,
+  resolveFileSource,
+  isSimpleStreamSource,
+  resolveStreamSource,
+} from './utils';
+
+// Types
+export type {
+  // Source types
+  VideoSourceUnion,
+  UrlSource,
+  YouTubeSource,
+  VimeoSource,
+  HLSSource,
+  DASHSource,
+  StreamSource,
+  BlobSource,
+  DataUrlSource,
+  // Player types
+  PlayerMode,
+  AspectRatioValue,
   VideoPlayerProps,
   VideoPlayerRef,
-  NativePlayerProps,
-  NativePlayerRef,
+  ErrorFallbackProps,
+  // Provider props (internal)
+  VidstackProviderProps,
+  NativeProviderProps,
+  StreamProviderProps,
+  // Common types
+  CommonPlayerSettings,
+  CommonPlayerEvents,
+  // File source helper types
+  ResolveFileSourceOptions,
+  // Context types
+  VideoPlayerContextValue,
+  VideoPlayerProviderProps,
+  SimpleStreamSource,
 } from './types';
-

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

@@ -0,0 +1,206 @@
+/**
+ * NativeProvider - Lightweight native HTML5 video player
+ * For demo videos, background videos, autoplay loop muted scenarios
+ */
+
+'use client';
+
+import React, { forwardRef, useEffect, useImperativeHandle, useRef, useState } from 'react';
+
+import { cn } from '@djangocfg/ui-core/lib';
+import { Preloader, AspectRatio } from '@djangocfg/ui-core';
+
+import type { NativeProviderProps, VideoPlayerRef } from '../types';
+
+/**
+ * Get video URL from source
+ */
+function getVideoUrl(source: NativeProviderProps['source']): string {
+  switch (source.type) {
+    case 'url':
+      return source.url;
+    case 'data-url':
+      return source.data;
+    default:
+      return '';
+  }
+}
+
+export const NativeProvider = forwardRef<VideoPlayerRef, NativeProviderProps>(
+  (
+    {
+      source,
+      aspectRatio = 16 / 9,
+      autoPlay = true,
+      muted = true,
+      loop = true,
+      playsInline = true,
+      preload = 'auto',
+      controls = false,
+      disableContextMenu = true,
+      showPreloader = true,
+      preloaderTimeout = 5000,
+      className,
+      videoClassName,
+      onPlay,
+      onPause,
+      onEnded,
+      onError,
+      onLoadStart,
+      onCanPlay,
+      onTimeUpdate,
+    },
+    ref
+  ) => {
+    const [isLoading, setIsLoading] = useState(showPreloader);
+    const videoRef = useRef<HTMLVideoElement>(null);
+
+    const videoUrl = getVideoUrl(source);
+
+    // Expose video element methods via ref
+    useImperativeHandle(
+      ref,
+      () => ({
+        play: () => videoRef.current?.play(),
+        pause: () => videoRef.current?.pause(),
+        togglePlay: () => {
+          const video = videoRef.current;
+          if (video) {
+            video.paused ? video.play() : video.pause();
+          }
+        },
+        seekTo: (time: number) => {
+          if (videoRef.current) videoRef.current.currentTime = time;
+        },
+        setVolume: (volume: number) => {
+          if (videoRef.current) videoRef.current.volume = Math.max(0, Math.min(1, volume));
+        },
+        toggleMute: () => {
+          if (videoRef.current) videoRef.current.muted = !videoRef.current.muted;
+        },
+        enterFullscreen: () => videoRef.current?.requestFullscreen(),
+        exitFullscreen: () => document.exitFullscreen(),
+        get currentTime() {
+          return videoRef.current?.currentTime ?? 0;
+        },
+        get duration() {
+          return videoRef.current?.duration ?? 0;
+        },
+        get paused() {
+          return videoRef.current?.paused ?? true;
+        },
+      }),
+      []
+    );
+
+    useEffect(() => {
+      if (!showPreloader) return;
+
+      const video = videoRef.current;
+      if (!video) return;
+
+      // Check if video is already loaded
+      if (video.readyState >= 3) {
+        setIsLoading(false);
+        return;
+      }
+
+      const hideLoader = () => setIsLoading(false);
+
+      video.addEventListener('canplay', hideLoader);
+      video.addEventListener('loadeddata', hideLoader);
+      video.addEventListener('playing', hideLoader);
+
+      // Fallback: hide loader after timeout
+      const timeout = setTimeout(hideLoader, preloaderTimeout);
+
+      return () => {
+        video.removeEventListener('canplay', hideLoader);
+        video.removeEventListener('loadeddata', hideLoader);
+        video.removeEventListener('playing', hideLoader);
+        clearTimeout(timeout);
+      };
+    }, [showPreloader, preloaderTimeout]);
+
+    const handleContextMenu = (e: React.MouseEvent) => {
+      if (disableContextMenu) {
+        e.preventDefault();
+      }
+    };
+
+    const handleError = (e: React.SyntheticEvent<HTMLVideoElement>) => {
+      setIsLoading(false);
+      onError?.(e.currentTarget.error?.message || 'Video playback error');
+    };
+
+    const handleTimeUpdate = () => {
+      const video = videoRef.current;
+      if (video && onTimeUpdate) {
+        onTimeUpdate(video.currentTime, video.duration);
+      }
+    };
+
+    // Determine if we should use AspectRatio wrapper or fill mode
+    const isFillMode = aspectRatio === 'fill';
+    const computedAspectRatio = aspectRatio === 'auto' || aspectRatio === 'fill' ? undefined : aspectRatio;
+
+    // Video content
+    const videoContent = (
+      <>
+        {/* Preloader */}
+        {showPreloader && isLoading && (
+          <div
+            className={cn(
+              'absolute inset-0 flex items-center justify-center bg-muted/30 backdrop-blur-sm z-10'
+            )}
+          >
+            <Preloader size="lg" spinnerClassName="text-white" />
+          </div>
+        )}
+
+        {/* Video */}
+        <video
+          ref={videoRef}
+          className={cn('w-full h-full object-cover', videoClassName)}
+          src={videoUrl}
+          autoPlay={autoPlay}
+          muted={muted}
+          loop={loop}
+          playsInline={playsInline}
+          preload={preload}
+          controls={controls}
+          poster={source.poster}
+          onContextMenu={handleContextMenu}
+          onLoadStart={onLoadStart}
+          onCanPlay={onCanPlay}
+          onPlay={onPlay}
+          onPause={onPause}
+          onPlaying={() => setIsLoading(false)}
+          onEnded={onEnded}
+          onError={handleError}
+          onTimeUpdate={handleTimeUpdate}
+        />
+      </>
+    );
+
+    // Fill mode - no AspectRatio wrapper
+    if (isFillMode) {
+      return (
+        <div className={cn('relative w-full h-full overflow-hidden', className)}>
+          {videoContent}
+        </div>
+      );
+    }
+
+    // Normal mode with AspectRatio
+    return (
+      <div className={cn('relative overflow-hidden', className)}>
+        <AspectRatio ratio={computedAspectRatio}>
+          {videoContent}
+        </AspectRatio>
+      </div>
+    );
+  }
+);
+
+NativeProvider.displayName = 'NativeProvider';