@djangocfg/ui-tools 2.1.91

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,12 @@
+/**
+ * VideoPlayer hooks - Public API
+ */
+
+export { useVideoPositionCache } from './useVideoPositionCache';
+export type {
+  UseVideoPositionCacheOptions,
+  UseVideoPositionCacheReturn,
+} from './useVideoPositionCache';
+
+export { useVideoPlayerSettings } from './useVideoPlayerSettings';
+export type { VideoPlayerSettingsReturn } from './useVideoPlayerSettings';

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

@@ -0,0 +1,70 @@
+'use client';
+
+/**
+ * useVideoPlayerSettings - Hook for persisted video player settings
+ *
+ * Provides volume and loop settings that persist in localStorage.
+ * Use this hook in video player providers to apply saved settings.
+ *
+ * @example
+ * const { settings, updateVolume, updateLoop } = useVideoPlayerSettings();
+ *
+ * // Apply to video element
+ * videoRef.current.volume = settings.volume;
+ * videoRef.current.loop = settings.isLooping;
+ *
+ * // Save when user changes
+ * const handleVolumeChange = (vol: number) => {
+ *   videoRef.current.volume = vol;
+ *   updateVolume(vol);
+ * };
+ */
+
+import { useCallback } from 'react';
+import { useVideoPlayerSettings as useSettings } from '../../../stores/mediaCache';
+
+export interface VideoPlayerSettingsReturn {
+  /** Current settings */
+  settings: {
+    volume: number;
+    isLooping: boolean;
+  };
+  /** Update volume (0-1) */
+  updateVolume: (volume: number) => void;
+  /** Update loop setting */
+  updateLoop: (isLooping: boolean) => void;
+  /** Update multiple settings at once */
+  updateSettings: (settings: { volume?: number; isLooping?: boolean }) => void;
+}
+
+export function useVideoPlayerSettings(): VideoPlayerSettingsReturn {
+  const { settings, saveSettings } = useSettings();
+
+  const updateVolume = useCallback(
+    (volume: number) => {
+      saveSettings({ volume: Math.max(0, Math.min(1, volume)) });
+    },
+    [saveSettings]
+  );
+
+  const updateLoop = useCallback(
+    (isLooping: boolean) => {
+      saveSettings({ isLooping });
+    },
+    [saveSettings]
+  );
+
+  const updateSettings = useCallback(
+    (newSettings: { volume?: number; isLooping?: boolean }) => {
+      saveSettings(newSettings);
+    },
+    [saveSettings]
+  );
+
+  return {
+    settings,
+    updateVolume,
+    updateLoop,
+    updateSettings,
+  };
+}

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

@@ -0,0 +1,116 @@
+'use client';
+
+/**
+ * useVideoPositionCache - Manages video playback position caching
+ *
+ * Saves position periodically during playback and restores on load.
+ */
+
+import { useRef, useEffect, useCallback } from 'react';
+import { useMediaCacheStore } 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;
+
+  // Get stable function references from store
+  const saveVideoPosition = useMediaCacheStore.getState().saveVideoPosition;
+  const getVideoPosition = useMediaCacheStore.getState().getVideoPosition;
+
+  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;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isReady, cacheKey, duration, 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;
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [cacheKey, isPlaying, currentTime]);
+
+  const savePosition = useCallback(() => {
+    if (cacheKey && currentTime > 0) {
+      saveVideoPosition(cacheKey, currentTime);
+      lastSavedTimeRef.current = currentTime;
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [cacheKey, currentTime]);
+
+  const clearPosition = useCallback(() => {
+    if (cacheKey) {
+      saveVideoPosition(cacheKey, 0);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [cacheKey]);
+
+  return {
+    savePosition,
+    clearPosition,
+  };
+}

package/src/tools/VideoPlayer/index.ts

@@ -0,0 +1,77 @@
+/**
+ * VideoPlayer - Unified Video Player
+ * Supports Vidstack (YouTube, Vimeo, HLS, DASH), Native HTML5, and HTTP Streaming
+ */
+
+// 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 {
+  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,
+  ErrorFallbackProps,
+  // Provider props (internal)
+  VidstackProviderProps,
+  NativeProviderProps,
+  StreamProviderProps,
+  // Common types
+  CommonPlayerSettings,
+  CommonPlayerEvents,
+  // File source helper types
+  ResolveFileSourceOptions,
+  // Context types
+  VideoPlayerContextValue,
+  VideoPlayerProviderProps,
+  SimpleStreamSource,
+} from './types';