@djangocfg/ui-nextjs 2.1.89 → 2.1.91

package/src/tools/VideoPlayer/README.md

@@ -1,264 +0,0 @@
-# VideoPlayer
-
-Unified video player component supporting multiple modes and source types.
-
-## Modes
-
-| Mode | Source Types | Use Case |
-|------|-------------|----------|
-| `vidstack` | YouTube, Vimeo, HLS, DASH | Full-featured player with themes and controls |
-| `native` | URL, data-url | Lightweight HTML5 player |
-| `streaming` | stream, blob | HTTP Range streaming with auth, binary data |
-
-Mode is auto-detected from source type, or can be forced via `mode` prop.
-
-## Installation
-
-```tsx
-import {
-  VideoPlayer,
-  VideoPlayerProvider,
-  VideoErrorFallback,
-  resolveFileSource
-} from '@djangocfg/ui-nextjs';
-```
-
-## Basic Usage
-
-### YouTube / Vimeo
-
-```tsx
-<VideoPlayer source={{ type: 'youtube', id: 'dQw4w9WgXcQ' }} />
-<VideoPlayer source={{ type: 'vimeo', id: '123456789' }} />
-```
-
-### HLS / DASH Streaming
-
-```tsx
-<VideoPlayer source={{ type: 'hls', url: 'https://example.com/video.m3u8' }} />
-<VideoPlayer source={{ type: 'dash', url: 'https://example.com/video.mpd' }} />
-```
-
-### Direct URL
-
-```tsx
-<VideoPlayer source={{ type: 'url', url: 'https://example.com/video.mp4' }} />
-```
-
-### HTTP Range Streaming (with auth)
-
-```tsx
-// Full source (standalone)
-<VideoPlayer
-  source={{
-    type: 'stream',
-    sessionId: 'abc123',
-    path: '/videos/movie.mp4',
-    getStreamUrl: (id, path) => `/api/stream/${id}?path=${path}&token=${token}`
-  }}
-/>
-
-// Simplified source (with context)
-<VideoPlayerProvider sessionId={sessionId} getStreamUrl={getStreamUrl}>
-  <VideoPlayer source={{ type: 'stream', path: '/videos/movie.mp4' }} />
-</VideoPlayerProvider>
-```
-
-### Blob / ArrayBuffer
-
-```tsx
-<VideoPlayer
-  source={{
-    type: 'blob',
-    data: arrayBuffer,
-    mimeType: 'video/mp4'
-  }}
-/>
-```
-
-## Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `source` | `VideoSourceUnion` | required | Video source configuration |
-| `mode` | `'auto' \| 'vidstack' \| 'native' \| 'streaming'` | `'auto'` | Force specific player mode |
-| `aspectRatio` | `number \| 'auto' \| 'fill'` | `16/9` | Aspect ratio or fill parent |
-| `autoPlay` | `boolean` | `false` | Auto-play on load |
-| `muted` | `boolean` | `false` | Muted by default |
-| `loop` | `boolean` | `false` | Loop playback |
-| `controls` | `boolean` | `true` | Show player controls |
-| `playsInline` | `boolean` | `true` | Inline playback on mobile |
-| `preload` | `'none' \| 'metadata' \| 'auto'` | `'metadata'` | Preload strategy |
-| `theme` | `'default' \| 'minimal' \| 'modern'` | `'default'` | Vidstack theme |
-| `errorFallback` | `ReactNode \| (props) => ReactNode` | - | Custom error UI |
-| `className` | `string` | - | Container className |
-| `videoClassName` | `string` | - | Video element className |
-
-## Events
-
-| Event | Type | Description |
-|-------|------|-------------|
-| `onPlay` | `() => void` | Playback started |
-| `onPause` | `() => void` | Playback paused |
-| `onEnded` | `() => void` | Playback ended |
-| `onError` | `(error: string) => void` | Error occurred |
-| `onLoadStart` | `() => void` | Loading started |
-| `onCanPlay` | `() => void` | Ready to play |
-| `onTimeUpdate` | `(time: number, duration: number) => void` | Time updated |
-
-## Ref API
-
-```tsx
-const playerRef = useRef<VideoPlayerRef>(null);
-
-<VideoPlayer ref={playerRef} source={source} />
-
-// Control methods
-playerRef.current?.play();
-playerRef.current?.pause();
-playerRef.current?.seek(30);        // Seek to 30 seconds
-playerRef.current?.setVolume(0.5);  // 0-1
-playerRef.current?.setMuted(true);
-playerRef.current?.reload();
-```
-
-## Error Handling
-
-### Custom Error Fallback
-
-```tsx
-<VideoPlayer
-  source={source}
-  errorFallback={(props) => (
-    <div>
-      <p>Error: {props.error}</p>
-      <button onClick={props.retry}>Retry</button>
-    </div>
-  )}
-/>
-```
-
-### Pre-built Error Fallback with Download
-
-```tsx
-import { VideoErrorFallback } from '@djangocfg/ui-nextjs';
-
-<VideoPlayer
-  source={source}
-  errorFallback={(props) => (
-    <VideoErrorFallback
-      {...props}
-      downloadUrl={getDownloadUrl()}
-      downloadFilename="video.mp4"
-      fileSize="125 MB"
-    />
-  )}
-/>
-```
-
-## Fill Mode
-
-Use `aspectRatio="fill"` to fill the parent container:
-
-```tsx
-<div className="absolute inset-0">
-  <VideoPlayer source={source} aspectRatio="fill" />
-</div>
-```
-
-## Context Provider
-
-For apps with multiple streaming videos, use the context to avoid repetition:
-
-```tsx
-// In layout or parent component
-<VideoPlayerProvider
-  sessionId={sessionId}
-  getStreamUrl={(id, path) => `/api/stream/${id}?path=${path}`}
->
-  {/* All nested VideoPlayers use this config */}
-  <VideoPlayer source={{ type: 'stream', path: '/video1.mp4' }} />
-  <VideoPlayer source={{ type: 'stream', path: '/video2.mp4' }} />
-</VideoPlayerProvider>
-```
-
-## File Source Helper
-
-For file browser integration:
-
-```tsx
-import { resolveFileSource } from '@djangocfg/ui-nextjs';
-
-const source = resolveFileSource({
-  file: { name: 'movie.mp4', path: '/videos/movie.mp4' },
-  sessionId: 'abc123',
-  getStreamUrl: (id, path) => `/api/stream/${id}?path=${path}`,
-});
-
-if (source) {
-  return <VideoPlayer source={source} />;
-}
-```
-
-## Source Types Reference
-
-```typescript
-type VideoSourceUnion =
-  | { type: 'url'; url: string; title?: string; poster?: string }
-  | { type: 'youtube'; id: string; title?: string; poster?: string }
-  | { type: 'vimeo'; id: string; title?: string; poster?: string }
-  | { type: 'hls'; url: string; title?: string; poster?: string }
-  | { type: 'dash'; url: string; title?: string; poster?: string }
-  | { type: 'stream'; sessionId: string; path: string; getStreamUrl: fn; mimeType?: string }
-  | { type: 'blob'; data: ArrayBuffer | Blob; mimeType?: string }
-  | { type: 'data-url'; data: string; mimeType?: string }
-```
-
-## Architecture
-
-```
-VideoPlayer/
-├── 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
-
-Full accessibility support:
-- Keyboard navigation (Space, Arrow keys, F for fullscreen)
-- Screen reader announcements
-- Focus indicators
-- ARIA labels and roles
-
-## Browser Support
-
-- Chrome 63+
-- Firefox 67+
-- Safari 12+
-- Edge 79+
-- iOS Safari 12+
-- Chrome Android 63+

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

@@ -1,138 +0,0 @@
-/**
- * Custom Video Controls for Vidstack Player
- */
-
-'use client';
-
-import { Maximize, Minimize, Pause, Play, Volume2, VolumeX } from 'lucide-react';
-import React from 'react';
-
-import { cn } from '@djangocfg/ui-core/lib';
-import { useMediaRemote, useMediaStore } from '@vidstack/react';
-
-import type { MediaPlayerInstance } from '@vidstack/react';
-interface VideoControlsProps {
-  player: React.RefObject<MediaPlayerInstance | null>;
-  className?: string;
-}
-
-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;
-  const currentTime = store.currentTime;
-  const duration = store.duration;
-  const volume = store.volume;
-
-  const formatTime = (seconds: number): string => {
-    if (!seconds || seconds < 0) return '0:00';
-    const minutes = Math.floor(seconds / 60);
-    const secs = Math.floor(seconds % 60);
-    return `${minutes}:${secs.toString().padStart(2, '0')}`;
-  };
-
-  const handleProgressClick = (e: React.MouseEvent<HTMLDivElement>) => {
-    if (!duration) return;
-    const rect = e.currentTarget.getBoundingClientRect();
-    const clickX = e.clientX - rect.left;
-    const percentage = clickX / rect.width;
-    const newTime = percentage * duration;
-    remote.seek(newTime);
-  };
-
-  const handleVolumeChange = (e: React.MouseEvent<HTMLDivElement>) => {
-    const rect = e.currentTarget.getBoundingClientRect();
-    const clickX = e.clientX - rect.left;
-    const percentage = Math.max(0, Math.min(1, clickX / rect.width));
-    remote.changeVolume(percentage);
-    if (percentage > 0 && isMuted) {
-      remote.toggleMuted();
-    }
-  };
-
-  const progress = duration > 0 ? (currentTime / duration) * 100 : 0;
-
-  return (
-    <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",
-        "opacity-0 group-hover:opacity-100 focus-within:opacity-100",
-        "pointer-events-none group-hover:pointer-events-auto",
-        className
-      )}
-    >
-      {/* Progress Bar */}
-      <div className="px-4 pb-2 pointer-events-auto">
-        <div
-          className="h-1.5 bg-white/20 rounded-full cursor-pointer hover:h-2 transition-all group"
-          onClick={handleProgressClick}
-        >
-          <div
-            className="h-full bg-primary rounded-full transition-all relative group-hover:bg-primary/90"
-            style={{ width: `${progress}%` }}
-          >
-            <div className="absolute right-0 top-1/2 -translate-y-1/2 w-3 h-3 bg-white rounded-full opacity-0 group-hover:opacity-100 transition-opacity" />
-          </div>
-        </div>
-      </div>
-
-      {/* Control Bar */}
-      <div className="flex items-center gap-4 px-4 pb-4 pointer-events-auto">
-        {/* Play/Pause */}
-        <button
-          onClick={() => remote.togglePaused()}
-          className="text-white hover:text-primary transition-colors p-1.5 hover:bg-white/10 rounded-full"
-        >
-          {isPaused ? <Play className="h-6 w-6" /> : <Pause className="h-6 w-6" />}
-        </button>
-
-        {/* Time */}
-        <div className="text-white text-sm font-medium">
-          {formatTime(currentTime)} / {formatTime(duration)}
-        </div>
-
-        <div className="flex-1" />
-
-        {/* Volume Control */}
-        <div className="flex items-center gap-2 group/volume">
-          <button
-            onClick={() => remote.toggleMuted()}
-            className="text-white hover:text-primary transition-colors p-1.5 hover:bg-white/10 rounded-full"
-          >
-            {isMuted || volume === 0 ? (
-              <VolumeX className="h-5 w-5" />
-            ) : (
-              <Volume2 className="h-5 w-5" />
-            )}
-          </button>
-
-          <div
-            className="w-0 group-hover/volume:w-20 transition-all overflow-hidden"
-          >
-            <div
-              className="h-1.5 bg-white/20 rounded-full cursor-pointer hover:h-2 transition-all"
-              onClick={handleVolumeChange}
-            >
-              <div
-                className="h-full bg-white rounded-full transition-all"
-                style={{ width: `${volume * 100}%` }}
-              />
-            </div>
-          </div>
-        </div>
-
-        {/* Fullscreen */}
-        <button
-          onClick={() => isFullscreen ? remote.exitFullscreen() : remote.enterFullscreen()}
-          className="text-white hover:text-primary transition-colors p-1.5 hover:bg-white/10 rounded-full"
-        >
-          {isFullscreen ? <Minimize className="h-5 w-5" /> : <Maximize className="h-5 w-5" />}
-        </button>
-      </div>
-    </div>
-  );
-}

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

@@ -1,174 +0,0 @@
-/**
- * VideoErrorFallback - Pre-built error fallback with download button
- * For use with VideoPlayer errorFallback prop
- */
-
-'use client';
-
-import React from 'react';
-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 type { ErrorFallbackProps } from '../types';
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export interface VideoErrorFallbackProps extends ErrorFallbackProps {
-  /** URL for download button (if provided, shows download button) */
-  downloadUrl?: string;
-  /** Filename for download */
-  downloadFilename?: string;
-  /** File size to display */
-  fileSize?: string;
-  /** Show retry button */
-  showRetry?: boolean;
-  /** Custom className */
-  className?: string;
-  /** Custom icon */
-  icon?: React.ReactNode;
-  /** Custom title (defaults to error message) */
-  title?: string;
-  /** Custom description */
-  description?: string;
-}
-
-// ============================================================================
-// Component
-// ============================================================================
-
-/**
- * Pre-built error fallback component for VideoPlayer
- *
- * @example
- * // Basic usage
- * <VideoPlayer
- *   source={source}
- *   errorFallback={(props) => (
- *     <VideoErrorFallback
- *       {...props}
- *       downloadUrl={getDownloadUrl()}
- *       downloadFilename="video.mp4"
- *     />
- *   )}
- * />
- *
- * @example
- * // With file size
- * <VideoErrorFallback
- *   error="Failed to load video"
- *   downloadUrl="/api/download/video.mp4"
- *   fileSize="125 MB"
- *   showRetry
- *   retry={() => reloadVideo()}
- * />
- */
-export function VideoErrorFallback({
-  error,
-  retry,
-  downloadUrl,
-  downloadFilename,
-  fileSize,
-  showRetry = true,
-  className,
-  icon,
-  title,
-  description,
-}: VideoErrorFallbackProps) {
-  const displayTitle = title || error || 'Video cannot be previewed';
-
-  return (
-    <div
-      className={cn(
-        'absolute inset-0 flex flex-col items-center justify-center gap-4 bg-black/90 text-white p-6',
-        className
-      )}
-    >
-      {/* Icon */}
-      {icon || <FileVideo className="w-16 h-16 text-muted-foreground" />}
-
-      {/* Title */}
-      <p className="text-lg font-medium text-center">{displayTitle}</p>
-
-      {/* Description / File size */}
-      {(description || fileSize) && (
-        <p className="text-sm text-muted-foreground text-center">
-          {description || fileSize}
-        </p>
-      )}
-
-      {/* Actions */}
-      <div className="flex items-center gap-3 mt-2">
-        {/* Retry button */}
-        {showRetry && retry && (
-          <Button
-            variant="outline"
-            size="sm"
-            onClick={retry}
-            className="gap-2"
-          >
-            <RefreshCw className="w-4 h-4" />
-            Retry
-          </Button>
-        )}
-
-        {/* Download button */}
-        {downloadUrl && (
-          <DownloadButton
-            url={downloadUrl}
-            filename={downloadFilename}
-            variant="default"
-            size="sm"
-          >
-            Download to view
-          </DownloadButton>
-        )}
-      </div>
-    </div>
-  );
-}
-
-// ============================================================================
-// Factory for common use cases
-// ============================================================================
-
-export interface CreateVideoErrorFallbackOptions {
-  /** Function to get download URL from source */
-  getDownloadUrl?: (source: unknown) => string | undefined;
-  /** Function to get filename from source */
-  getFilename?: (source: unknown) => string | undefined;
-  /** Function to get file size from source */
-  getFileSize?: (source: unknown) => string | undefined;
-  /** Show retry button */
-  showRetry?: boolean;
-}
-
-/**
- * Factory to create error fallback function for VideoPlayer
- *
- * @example
- * const errorFallback = createVideoErrorFallback({
- *   getDownloadUrl: (source) => source.downloadUrl,
- *   getFilename: (source) => source.filename,
- *   showRetry: true,
- * });
- *
- * <VideoPlayer source={source} errorFallback={errorFallback} />
- */
-export function createVideoErrorFallback(
-  options: CreateVideoErrorFallbackOptions
-): (props: ErrorFallbackProps, source?: unknown) => React.ReactNode {
-  return (props: ErrorFallbackProps, source?: unknown) => (
-    <VideoErrorFallback
-      {...props}
-      downloadUrl={options.getDownloadUrl?.(source)}
-      downloadFilename={options.getFilename?.(source)}
-      fileSize={options.getFileSize?.(source)}
-      showRetry={options.showRetry}
-    />
-  );
-}