@djangocfg/ui-nextjs 2.1.66 → 2.1.67

package/src/tools/VideoPlayer/types/player.ts

@@ -0,0 +1,116 @@
+/**
+ * Player configuration types
+ */
+
+import type React from 'react';
+import type { VideoSourceUnion } from './sources';
+
+// =============================================================================
+// 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;
+  /** Mute video by default */
+  muted?: boolean;
+  /** Loop video */
+  loop?: boolean;
+  /** Play video inline on mobile */
+  playsInline?: boolean;
+  /** Show player controls */
+  controls?: boolean;
+  /**
+   * 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;
+  /** Called when buffering progress changes (buffered seconds, total duration) */
+  onBufferProgress?: (buffered: 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: () => Promise<void> | void;
+  /** Pause video */
+  pause: () => void;
+  /** Toggle play/pause */
+  togglePlay: () => void;
+  /** Seek to time in seconds */
+  seekTo: (time: number) => void;
+  /** Set volume (0-1) */
+  setVolume: (volume: number) => void;
+  /** Toggle mute */
+  toggleMute: () => void;
+  /** Enter fullscreen */
+  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;
+}

package/src/tools/VideoPlayer/types/provider.ts

@@ -0,0 +1,93 @@
+/**
+ * Provider-specific types
+ */
+
+import type React from 'react';
+import type { VideoSourceUnion, UrlSource, YouTubeSource, VimeoSource, HLSSource, DASHSource, StreamSource, BlobSource, DataUrlSource } from './sources';
+import type { CommonPlayerSettings, CommonPlayerEvents, ErrorFallbackProps } from './player';
+
+// =============================================================================
+// Provider Props
+// =============================================================================
+
+/** 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;
+  showPreloader?: boolean;
+  preloaderTimeout?: number;
+}
+
+/** Props passed to Stream provider */
+export interface StreamProviderProps extends CommonPlayerSettings, CommonPlayerEvents {
+  source: StreamSource | BlobSource | DataUrlSource;
+  className?: string;
+  videoClassName?: string;
+  disableContextMenu?: boolean;
+  showPreloader?: boolean;
+  preloaderTimeout?: number;
+  errorFallback?: React.ReactNode | ((props: ErrorFallbackProps) => React.ReactNode);
+}
+
+// =============================================================================
+// File Source Helper Types
+// =============================================================================
+
+/** 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;
+}
+
+// =============================================================================
+// Context Types
+// =============================================================================
+
+export interface VideoPlayerContextValue {
+  /** Function to generate stream URL (for HTTP Range streaming) */
+  getStreamUrl?: (sessionId: string, path: string) => string;
+  /** Current session ID */
+  sessionId?: string | null;
+}
+
+export interface VideoPlayerProviderProps extends VideoPlayerContextValue {
+  children: React.ReactNode;
+}
+
+/** Simplified stream source (uses context for getStreamUrl) */
+export interface SimpleStreamSource {
+  type: 'stream';
+  /** File path on server */
+  path: string;
+  /** Session ID (optional, uses context if not provided) */
+  sessionId?: string;
+  /** MIME type for the video */
+  mimeType?: string;
+  title?: string;
+  poster?: string;
+}

package/src/tools/VideoPlayer/types/sources.ts

@@ -0,0 +1,97 @@
+/**
+ * Video source type definitions
+ */
+
+// =============================================================================
+// Source Types - Different ways to provide video content
+// =============================================================================
+
+/** Simple URL source (mp4, webm, etc.) */
+export interface UrlSource {
+  type: 'url';
+  url: string;
+  title?: string;
+  poster?: string;
+}
+
+/** 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;

package/src/tools/VideoPlayer/utils/fileSource.ts

@@ -0,0 +1,78 @@
+/**
+ * File source resolution utilities
+ */
+
+import type { VideoSourceUnion, ResolveFileSourceOptions } from '../types';
+
+/**
+ * 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;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * VideoPlayer utilities - Public API
+ */
+
+export {
+  resolvePlayerMode,
+  isSimpleStreamSource,
+  resolveStreamSource,
+} from './resolvers';
+
+export { resolveFileSource } from './fileSource';

package/src/tools/VideoPlayer/utils/resolvers.ts

@@ -0,0 +1,75 @@
+/**
+ * Video source and player mode resolvers
+ */
+
+import type { VideoSourceUnion, PlayerMode, SimpleStreamSource, StreamSource, VideoPlayerContextValue } from '../types';
+
+/**
+ * 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';
+  }
+}
+
+/**
+ * Check if source is a simplified stream source (without getStreamUrl)
+ */
+export function isSimpleStreamSource(
+  source: VideoSourceUnion | SimpleStreamSource
+): source is SimpleStreamSource {
+  return source.type === 'stream' && !('getStreamUrl' in source);
+}
+
+/**
+ * Resolve simplified stream source to full stream source using context
+ */
+export function resolveStreamSource(
+  source: SimpleStreamSource,
+  context: VideoPlayerContextValue | null
+): StreamSource | null {
+  if (!context?.getStreamUrl) {
+    console.warn(
+      'VideoPlayer: Stream source requires getStreamUrl. ' +
+      'Either provide it in source or wrap with VideoPlayerProvider.'
+    );
+    return null;
+  }
+
+  const sessionId = source.sessionId || context.sessionId;
+  if (!sessionId) {
+    console.warn('VideoPlayer: Stream source requires sessionId.');
+    return null;
+  }
+
+  return {
+    type: 'stream',
+    sessionId,
+    path: source.path,
+    getStreamUrl: context.getStreamUrl,
+    mimeType: source.mimeType,
+    title: source.title,
+    poster: source.poster,
+  };
+}

package/src/tools/index.ts

@@ -125,3 +125,13 @@ export type {
 // Export ImageViewer
 export { ImageViewer } from './ImageViewer';
 export type { ImageViewerProps, ImageFile } from './ImageViewer';
+
+// Export Media Cache Store
+export {
+  useMediaCacheStore,
+  useImageCache,
+  useAudioCache,
+  useVideoCache,
+  useBlobUrlCleanup,
+  generateContentKey,
+} from '../stores/mediaCache';