@djangocfg/ui-nextjs 2.1.65 → 2.1.67

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