@djangocfg/ui-nextjs 2.1.66 → 2.1.68

package/src/tools/VideoPlayer/@refactoring/02-UTILS.md

@@ -0,0 +1,141 @@
+# Phase 2: Utils Extraction
+
+## Goal
+
+Extract helper functions from types.ts into dedicated utils files.
+
+## Files to Create
+
+### utils/resolvers.ts
+
+Player mode and source resolution:
+
+```typescript
+/**
+ * Video source and player mode resolvers
+ */
+
+import type { VideoSourceUnion, PlayerMode, SimpleStreamSource, StreamSource } from '../types';
+
+/**
+ * Determine the appropriate player mode for a given source
+ */
+export function resolvePlayerMode(source: VideoSourceUnion): PlayerMode {
+  switch (source.type) {
+    case 'youtube':
+    case 'vimeo':
+    case 'hls':
+    case 'dash':
+      return 'vidstack';
+    case 'stream':
+    case 'blob':
+    case 'data-url':
+      return 'streaming';
+    case 'url':
+    default:
+      return 'native';
+  }
+}
+
+/**
+ * Check if source is a simple stream (needs context resolution)
+ */
+export function isSimpleStreamSource(
+  source: VideoSourceUnion
+): source is SimpleStreamSource {
+  return (
+    source.type === 'stream' &&
+    !('getStreamUrl' in source)
+  );
+}
+
+/**
+ * Resolve simple stream source with context getStreamUrl
+ */
+export function resolveStreamSource(
+  source: SimpleStreamSource,
+  getStreamUrl: (streamKey: string) => Promise<string>
+): StreamSource {
+  return {
+    ...source,
+    getStreamUrl,
+  };
+}
+```
+
+### utils/fileSource.ts
+
+File content to source conversion:
+
+```typescript
+/**
+ * File source resolution utilities
+ */
+
+import type { VideoSourceUnion, ResolveFileSourceOptions } from '../types';
+
+/**
+ * Convert file content to appropriate VideoSource
+ */
+export function resolveFileSource(options: ResolveFileSourceOptions): VideoSourceUnion {
+  const { fileName, content, mimeType } = options;
+
+  // Data URL string
+  if (typeof content === 'string' && content.startsWith('data:')) {
+    return {
+      type: 'data-url',
+      dataUrl: content,
+      mimeType,
+    };
+  }
+
+  // Regular URL string
+  if (typeof content === 'string') {
+    return {
+      type: 'url',
+      url: content,
+      mimeType,
+    };
+  }
+
+  // ArrayBuffer -> Blob source
+  return {
+    type: 'blob',
+    data: content,
+    mimeType: mimeType || guessMimeType(fileName),
+    fileName,
+  };
+}
+
+/**
+ * Guess MIME type from file extension
+ */
+function guessMimeType(fileName: string): string {
+  const ext = fileName.split('.').pop()?.toLowerCase();
+  const mimeTypes: Record<string, string> = {
+    mp4: 'video/mp4',
+    webm: 'video/webm',
+    ogg: 'video/ogg',
+    mov: 'video/quicktime',
+    avi: 'video/x-msvideo',
+    mkv: 'video/x-matroska',
+  };
+  return mimeTypes[ext || ''] || 'video/mp4';
+}
+```
+
+### utils/index.ts
+
+```typescript
+/**
+ * VideoPlayer utilities - Public API
+ */
+
+export {
+  resolvePlayerMode,
+  isSimpleStreamSource,
+  resolveStreamSource,
+} from './resolvers';
+
+export { resolveFileSource } from './fileSource';
+```

package/src/tools/VideoPlayer/@refactoring/03-HOOKS.md

@@ -0,0 +1,178 @@
+# Phase 3: Hooks Extraction
+
+## Goal
+
+Extract duplicated video position caching logic into a reusable hook.
+
+## Current Duplication
+
+The position caching pattern is duplicated in:
+1. `VidstackProvider.tsx` (lines ~180-220)
+2. `StreamProvider.tsx` (lines ~200-240)
+
+Both implement:
+- Save position every 5 seconds during playback
+- Restore position when video loads (canPlay)
+- Clear position when video ends
+
+## File to Create
+
+### hooks/useVideoPositionCache.ts
+
+```typescript
+'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;
+  /** 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 position to restore (avoid 0 or near-end) */
+const MIN_RESTORE_POSITION = 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 > MIN_RESTORE_POSITION && savedPosition < duration - 1) {
+      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]);
+
+  // Save position on pause
+  useEffect(() => {
+    if (!cacheKey || isPlaying || currentTime <= 0) return;
+
+    saveVideoPosition(cacheKey, currentTime);
+    lastSavedTimeRef.current = currentTime;
+  }, [cacheKey, isPlaying, currentTime, saveVideoPosition]);
+
+  const savePosition = useCallback(() => {
+    if (cacheKey && currentTime > 0) {
+      saveVideoPosition(cacheKey, currentTime);
+    }
+  }, [cacheKey, currentTime, saveVideoPosition]);
+
+  const clearPosition = useCallback(() => {
+    if (cacheKey) {
+      saveVideoPosition(cacheKey, 0);
+    }
+  }, [cacheKey, saveVideoPosition]);
+
+  return {
+    savePosition,
+    clearPosition,
+  };
+}
+```
+
+### hooks/index.ts
+
+```typescript
+/**
+ * VideoPlayer hooks - Public API
+ */
+
+export { useVideoPositionCache } from './useVideoPositionCache';
+export type {
+  UseVideoPositionCacheOptions,
+  UseVideoPositionCacheReturn,
+} from './useVideoPositionCache';
+```
+
+## Usage in Providers
+
+After extraction, providers can use:
+
+```typescript
+// In VidstackProvider.tsx
+const { clearPosition } = useVideoPositionCache({
+  cacheKey: sourceKey,
+  currentTime: player?.currentTime ?? 0,
+  duration: player?.duration ?? 0,
+  isPlaying: !paused,
+  isReady: canPlay,
+  onSeek: (time) => player?.currentTime = time,
+});
+
+// Clear on video end
+useEffect(() => {
+  if (ended) clearPosition();
+}, [ended, clearPosition]);
+```
+
+## Benefits
+
+1. **DRY** - Single source of truth for position caching logic
+2. **Testable** - Hook can be unit tested independently
+3. **Reusable** - Can be used in future video components
+4. **Maintainable** - Changes only need to be made in one place

package/src/tools/VideoPlayer/@refactoring/04-COMPONENTS.md

@@ -0,0 +1,95 @@
+# Phase 4: Components Organization
+
+## Goal
+
+Move standalone components to a dedicated `components/` folder for consistency.
+
+## Current Location
+
+```
+VideoPlayer/
+├── VideoPlayer.tsx          # Main orchestrator
+├── VideoControls.tsx        # Vidstack controls
+├── VideoErrorFallback.tsx   # Error UI
+└── providers/               # Provider implementations
+```
+
+## Target Location
+
+```
+VideoPlayer/
+├── components/
+│   ├── index.ts
+│   ├── VideoPlayer.tsx
+│   ├── VideoControls.tsx
+│   └── VideoErrorFallback.tsx
+└── providers/               # Unchanged
+```
+
+## Files to Create
+
+### components/index.ts
+
+```typescript
+/**
+ * VideoPlayer components - Public API
+ */
+
+export { VideoPlayer } from './VideoPlayer';
+export { VideoControls } from './VideoControls';
+export {
+  VideoErrorFallback,
+  createVideoErrorFallback,
+} from './VideoErrorFallback';
+```
+
+## Component Updates
+
+### VideoPlayer.tsx
+
+Update imports to use new paths:
+
+```typescript
+// Before
+import { VidstackProvider } from './providers';
+import { NativeProvider } from './providers';
+import { StreamProvider } from './providers';
+import { resolvePlayerMode, isSimpleStreamSource, resolveStreamSource } from './types';
+import { useVideoPlayerContext } from './VideoPlayerContext';
+
+// After
+import { VidstackProvider, NativeProvider, StreamProvider } from '../providers';
+import { resolvePlayerMode, isSimpleStreamSource, resolveStreamSource } from '../utils';
+import { useVideoPlayerContext } from '../context';
+```
+
+### VideoControls.tsx
+
+Update imports:
+
+```typescript
+// Before
+import type { ... } from './types';
+
+// After
+import type { ... } from '../types';
+```
+
+### VideoErrorFallback.tsx
+
+Update imports:
+
+```typescript
+// Before
+import type { ErrorFallbackProps } from './types';
+
+// After
+import type { ErrorFallbackProps } from '../types';
+```
+
+## Notes
+
+- VideoPlayer.tsx is the main entry point, moved to components/
+- Providers stay in their own folder (already well-organized)
+- Context moves to context/ folder
+- All imports updated to reflect new structure

package/src/tools/VideoPlayer/@refactoring/05-EXECUTION-CHECKLIST.md

@@ -0,0 +1,139 @@
+# Execution Checklist
+
+## Pre-flight
+
+- [ ] Read all current files
+- [ ] Backup or rename original files
+- [ ] Create folder structure
+
+## Phase 1: Folder Structure
+
+```bash
+cd src/tools/VideoPlayer
+mkdir -p types hooks utils components context
+```
+
+- [ ] Create `types/` directory
+- [ ] Create `hooks/` directory
+- [ ] Create `utils/` directory
+- [ ] Create `components/` directory
+- [ ] Create `context/` directory
+
+## Phase 2: Types
+
+- [ ] Create `types/sources.ts` - Source type definitions
+- [ ] Create `types/player.ts` - Player config and main types
+- [ ] Create `types/provider.ts` - Provider-specific types
+- [ ] Create `types/index.ts` - Re-exports
+- [ ] Run `pnpm check`
+
+## Phase 3: Utils
+
+- [ ] Create `utils/resolvers.ts` - resolvePlayerMode, isSimpleStreamSource
+- [ ] Create `utils/fileSource.ts` - resolveFileSource
+- [ ] Create `utils/index.ts` - Re-exports
+- [ ] Run `pnpm check`
+
+## Phase 4: Hooks
+
+- [ ] Create `hooks/useVideoPositionCache.ts` - Position caching logic
+- [ ] Create `hooks/index.ts` - Re-exports
+- [ ] Run `pnpm check`
+
+## Phase 5: Components
+
+- [ ] Move `VideoPlayer.tsx` to `components/`
+- [ ] Move `VideoControls.tsx` to `components/`
+- [ ] Move `VideoErrorFallback.tsx` to `components/`
+- [ ] Create `components/index.ts`
+- [ ] Update imports in all moved files
+- [ ] Run `pnpm check`
+
+## Phase 6: Context
+
+- [ ] Move `VideoPlayerContext.tsx` to `context/`
+- [ ] Create `context/index.ts`
+- [ ] Update imports
+- [ ] Run `pnpm check`
+
+## Phase 7: Update Providers
+
+- [ ] Update imports in `VidstackProvider.tsx`
+- [ ] Update imports in `NativeProvider.tsx`
+- [ ] Update imports in `StreamProvider.tsx`
+- [ ] Optionally integrate `useVideoPositionCache` hook
+- [ ] Run `pnpm check`
+
+## Phase 8: Main Index
+
+- [ ] Update `index.ts` with new imports
+- [ ] Verify all exports work
+- [ ] Run `pnpm check`
+
+## Phase 9: Cleanup
+
+- [ ] Delete old `types.ts`
+- [ ] Delete old `VideoPlayer.tsx`
+- [ ] Delete old `VideoControls.tsx`
+- [ ] Delete old `VideoErrorFallback.tsx`
+- [ ] Delete old `VideoPlayerContext.tsx`
+- [ ] Run `pnpm check`
+- [ ] Run `pnpm build` (optional)
+
+## Post-flight
+
+- [ ] Test video playback (URL source)
+- [ ] Test YouTube embed
+- [ ] Test stream playback
+- [ ] Test error fallback
+- [ ] Verify position caching works
+
+## Final Structure
+
+```
+VideoPlayer/
+├── index.ts
+├── README.md
+├── types/
+│   ├── index.ts
+│   ├── sources.ts
+│   ├── player.ts
+│   └── provider.ts
+├── hooks/
+│   ├── index.ts
+│   └── useVideoPositionCache.ts
+├── utils/
+│   ├── index.ts
+│   ├── resolvers.ts
+│   └── fileSource.ts
+├── components/
+│   ├── index.ts
+│   ├── VideoPlayer.tsx
+│   ├── VideoControls.tsx
+│   └── VideoErrorFallback.tsx
+├── context/
+│   ├── index.ts
+│   └── VideoPlayerContext.tsx
+└── providers/
+    ├── index.ts
+    ├── VidstackProvider.tsx
+    ├── NativeProvider.tsx
+    └── StreamProvider.tsx
+```
+
+## Metrics
+
+| Metric | Before | After |
+|--------|--------|-------|
+| types.ts | 369 lines | Split into 3 files (~100 each) |
+| Total files | 10 | 18 |
+| Hooks | 0 | 1 (useVideoPositionCache) |
+| Utils | 0 (in types.ts) | 2 |
+| Duplicated code | Position caching x2 | Extracted to hook |
+
+## Optional Improvements
+
+After main refactoring, consider:
+1. Integrate `useVideoPositionCache` into providers
+2. Extract more shared logic from StreamProvider
+3. Add unit tests for utils and hooks

package/src/tools/VideoPlayer/README.md

@@ -218,16 +218,32 @@ type VideoSourceUnion =
 
 ```
 VideoPlayer/
-├── VideoPlayer.tsx         # Main orchestrator
-├── VideoPlayerContext.tsx  # Context for streaming config
-├── VideoErrorFallback.tsx  # Pre-built error UI
-├── VideoControls.tsx       # Standalone controls (Vidstack)
-├── types.ts                # Type definitions
-├── providers/
-│   ├── VidstackProvider.tsx   # YouTube, Vimeo, HLS, DASH
-│   ├── NativeProvider.tsx     # HTML5 <video>
-│   └── StreamProvider.tsx     # HTTP Range, Blob
-└── index.ts                # Exports
+├── 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

package/src/tools/VideoPlayer/{VideoControls.tsx → components/VideoControls.tsx}

@@ -19,7 +19,7 @@ interface VideoControlsProps {
 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;
@@ -56,7 +56,7 @@ export function VideoControls({ player, className }: VideoControlsProps) {
   const progress = duration > 0 ? (currentTime / duration) * 100 : 0;
 
   return (
-    <div 
+    <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",
@@ -67,11 +67,11 @@ export function VideoControls({ player, className }: VideoControlsProps) {
     >
       {/* Progress Bar */}
       <div className="px-4 pb-2 pointer-events-auto">
-        <div 
+        <div
           className="h-1.5 bg-white/20 rounded-full cursor-pointer hover:h-2 transition-all group"
           onClick={handleProgressClick}
         >
-          <div 
+          <div
             className="h-full bg-primary rounded-full transition-all relative group-hover:bg-primary/90"
             style={{ width: `${progress}%` }}
           >
@@ -109,15 +109,15 @@ export function VideoControls({ player, className }: VideoControlsProps) {
               <Volume2 className="h-5 w-5" />
             )}
           </button>
-          
-          <div 
+
+          <div
             className="w-0 group-hover/volume:w-20 transition-all overflow-hidden"
           >
-            <div 
+            <div
               className="h-1.5 bg-white/20 rounded-full cursor-pointer hover:h-2 transition-all"
               onClick={handleVolumeChange}
             >
-              <div 
+              <div
                 className="h-full bg-white rounded-full transition-all"
                 style={{ width: `${volume * 100}%` }}
               />
@@ -136,4 +136,3 @@ export function VideoControls({ player, className }: VideoControlsProps) {
     </div>
   );
 }
-

package/src/tools/VideoPlayer/{VideoErrorFallback.tsx → components/VideoErrorFallback.tsx}

@@ -10,9 +10,9 @@ import { FileVideo, RefreshCw } from 'lucide-react';
 
 import { cn } from '@djangocfg/ui-core/lib';
 import { Button } from '@djangocfg/ui-core/components';
-import { DownloadButton } from '../../components/button-download';
+import { DownloadButton } from '../../../components/button-download';
 
-import type { ErrorFallbackProps } from './types';
+import type { ErrorFallbackProps } from '../types';
 
 // ============================================================================
 // Types

package/src/tools/VideoPlayer/{VideoPlayer.tsx → components/VideoPlayer.tsx}

@@ -40,12 +40,11 @@
 
 import React, { forwardRef, useMemo } from 'react';
 
-import { VidstackProvider, NativeProvider, StreamProvider } from './providers';
-import { useVideoPlayerContext, isSimpleStreamSource, resolveStreamSource } from './VideoPlayerContext';
-import { resolvePlayerMode } from './types';
+import { VidstackProvider, NativeProvider, StreamProvider } from '../providers';
+import { useVideoPlayerContext } from '../context';
+import { resolvePlayerMode, isSimpleStreamSource, resolveStreamSource } from '../utils';
 
-import type { VideoPlayerProps, VideoPlayerRef, VideoSourceUnion, VidstackProviderProps, NativeProviderProps, StreamProviderProps } from './types';
-import type { SimpleStreamSource } from './VideoPlayerContext';
+import type { VideoPlayerProps, VideoPlayerRef, VideoSourceUnion, VidstackProviderProps, NativeProviderProps, StreamProviderProps, SimpleStreamSource } from '../types';
 
 export const VideoPlayer = forwardRef<VideoPlayerRef, VideoPlayerProps & { source: VideoSourceUnion | SimpleStreamSource }>(
   (

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';