@djangocfg/ui-tools 2.1.402 → 2.1.407

package/src/tools/VideoPlayer/types.ts

@@ -0,0 +1,82 @@
+/**
+ * VideoPlayer types — discriminated `VideoSource` union + props.
+ *
+ * The component is engine-agnostic at the API surface: callers either
+ * pass a structured `VideoSource` or a raw URL string (auto-parsed via
+ * `parseEmbedUrl`).
+ */
+
+import type { ReactNode } from 'react';
+
+export interface UrlSource {
+  readonly type: 'url';
+  readonly url: string;
+  readonly mimeType?: string;
+  readonly title?: string;
+  readonly poster?: string;
+}
+
+export interface YouTubeSource {
+  readonly type: 'youtube';
+  readonly videoId: string;
+  readonly startTime?: number;
+  readonly playlistId?: string;
+  readonly title?: string;
+  readonly poster?: string;
+}
+
+export interface VimeoSource {
+  readonly type: 'vimeo';
+  readonly videoId: string;
+  readonly startTime?: number;
+  readonly title?: string;
+  readonly poster?: string;
+}
+
+export interface HlsSource {
+  readonly type: 'hls';
+  readonly url: string;
+  readonly title?: string;
+  readonly poster?: string;
+}
+
+export interface IframeSource {
+  readonly type: 'iframe';
+  readonly url: string;
+  readonly title?: string;
+  readonly poster?: string;
+  readonly allow?: string;
+}
+
+export type VideoSource =
+  | UrlSource
+  | YouTubeSource
+  | VimeoSource
+  | HlsSource
+  | IframeSource;
+
+export type AspectRatioValue = number | 'auto' | 'fill';
+
+export interface VideoPlayerSettings {
+  readonly autoPlay?: boolean;
+  readonly muted?: boolean;
+  readonly loop?: boolean;
+  readonly playsInline?: boolean;
+  readonly crossOrigin?: '' | 'anonymous' | 'use-credentials';
+  readonly preload?: 'none' | 'metadata' | 'auto';
+}
+
+export interface VideoPlayerProps extends VideoPlayerSettings {
+  /**
+   * Structured source object — or a raw URL string that will be
+   * auto-classified via `parseEmbedUrl` (YouTube / Vimeo / HLS / MP4 / iframe).
+   */
+  readonly source: VideoSource | string;
+  /** Default `true`. When `false`, no built-in `<MediaControlBar>` is rendered. */
+  readonly controls?: boolean;
+  /** Default `16/9`. `'fill'` stretches to parent height; `'auto'` keeps intrinsic. */
+  readonly aspectRatio?: AspectRatioValue;
+  readonly className?: string;
+  /** Custom children replace the default control bar entirely. */
+  readonly children?: ReactNode;
+}

package/src/tools/VideoPlayer/utils/parse-embed-url.ts

@@ -0,0 +1,70 @@
+/**
+ * Smart URL classifier — maps an arbitrary string into a structured
+ * `VideoSource`.
+ *
+ * Order:
+ *   1. YouTube  (youtube.com, youtu.be, shorts, embed)
+ *   2. Vimeo    (vimeo.com, player.vimeo.com)
+ *   3. HLS      (`.m3u8`)
+ *   4. Native   (`.mp4`, `.webm`, `.mov`, `.mkv`, `.ogv`, `.m4v`)
+ *   5. Fallback — treat as iframe embed.
+ *
+ * Pure; no React, no DOM.
+ */
+
+import type { VideoSource } from '../types';
+import { extractYouTubeId, parseYouTubeStartTime } from './youtube-id';
+import { extractVimeoId } from './vimeo-id';
+
+const NATIVE_VIDEO_EXT = /\.(mp4|webm|mov|mkv|ogv|m4v)(\?.*)?$/i;
+const HLS_EXT = /\.m3u8(\?.*)?$/i;
+
+export function parseEmbedUrl(input: string): VideoSource {
+  const trimmed = input.trim();
+
+  // 1. YouTube.
+  const ytId = extractYouTubeId(trimmed);
+  if (ytId) {
+    let startTime: number | undefined;
+    let playlistId: string | undefined;
+    try {
+      const url = new URL(trimmed);
+      startTime = parseYouTubeStartTime(url.searchParams.get('t'));
+      const list = url.searchParams.get('list');
+      if (list && /^[\w-]+$/.test(list)) playlistId = list;
+    } catch {
+      /* ignore */
+    }
+    return {
+      type: 'youtube',
+      videoId: ytId,
+      ...(startTime !== undefined && { startTime }),
+      ...(playlistId && { playlistId }),
+    };
+  }
+
+  // 2. Vimeo.
+  const vimeoId = extractVimeoId(trimmed);
+  if (vimeoId) {
+    return { type: 'vimeo', videoId: vimeoId };
+  }
+
+  // 3. HLS.
+  if (HLS_EXT.test(trimmed)) {
+    return { type: 'hls', url: trimmed };
+  }
+
+  // 4. Native video file.
+  if (NATIVE_VIDEO_EXT.test(trimmed)) {
+    return { type: 'url', url: trimmed };
+  }
+
+  // 5. Fallback: blob: / data: / unknown http(s) URL — assume native <video>
+  //    can handle blob/data, iframe for everything else.
+  if (/^(blob:|data:)/i.test(trimmed)) {
+    return { type: 'url', url: trimmed };
+  }
+
+  // Unknown URL — fall back to iframe so embeds still surface.
+  return { type: 'iframe', url: trimmed };
+}

package/src/tools/VideoPlayer/utils/vimeo-id.ts

@@ -0,0 +1,24 @@
+/**
+ * Extract a Vimeo numeric `videoId` from a URL.
+ *
+ * Supports:
+ *   - vimeo.com/123456789
+ *   - vimeo.com/123456789/HASH
+ *   - player.vimeo.com/video/123456789
+ *
+ * Returns `null` if the URL does not match.
+ */
+export function extractVimeoId(input: string): string | null {
+  let url: URL;
+  try {
+    url = new URL(input);
+  } catch {
+    return null;
+  }
+  const host = url.hostname.replace(/^www\./, '');
+  if (host !== 'vimeo.com' && host !== 'player.vimeo.com') return null;
+
+  // /video/<id> on player.vimeo.com, /<id> on vimeo.com.
+  const match = url.pathname.match(/(?:^\/video\/|^\/)(\d+)/);
+  return match ? match[1] : null;
+}

package/src/tools/VideoPlayer/utils/youtube-id.ts

@@ -0,0 +1,64 @@
+/**
+ * Extract a YouTube `videoId` from a URL.
+ *
+ * Supports:
+ *   - youtube.com/watch?v=ID
+ *   - youtu.be/ID
+ *   - youtube.com/shorts/ID
+ *   - youtube.com/embed/ID
+ *   - youtube.com/v/ID
+ *   - m.youtube.com/* mirrors
+ *
+ * Returns `null` if the URL does not match.
+ */
+export function extractYouTubeId(input: string): string | null {
+  let url: URL;
+  try {
+    url = new URL(input);
+  } catch {
+    return null;
+  }
+
+  const host = url.hostname.replace(/^www\.|^m\./, '');
+
+  if (host === 'youtu.be') {
+    const id = url.pathname.replace(/^\//, '').split('/')[0];
+    return isValidId(id) ? id : null;
+  }
+
+  if (host === 'youtube.com' || host === 'youtube-nocookie.com') {
+    if (url.pathname === '/watch') {
+      const v = url.searchParams.get('v');
+      return v && isValidId(v) ? v : null;
+    }
+    const m = url.pathname.match(/^\/(?:shorts|embed|v|live)\/([^/?#]+)/);
+    if (m) {
+      return isValidId(m[1]) ? m[1] : null;
+    }
+  }
+
+  return null;
+}
+
+/** Parse the YouTube `?t=` / `&t=` start-time param (`90`, `90s`, `1m30s`). */
+export function parseYouTubeStartTime(input: string | null): number | undefined {
+  if (!input) return undefined;
+  // Pure seconds.
+  if (/^\d+s?$/.test(input)) {
+    const n = parseInt(input, 10);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+  }
+  // `1h2m3s` / `2m30s` / `45s`.
+  const match = input.match(/^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s?)?$/);
+  if (!match) return undefined;
+  const [, h, m, s] = match;
+  const total =
+    (h ? parseInt(h, 10) * 3600 : 0) +
+    (m ? parseInt(m, 10) * 60 : 0) +
+    (s ? parseInt(s, 10) : 0);
+  return total > 0 ? total : undefined;
+}
+
+function isValidId(id: string | undefined): id is string {
+  return !!id && /^[\w-]{6,}$/.test(id);
+}

package/src/tools/index.ts

@@ -43,43 +43,50 @@ export * from './JsonForm/utils';
 export { default as OpenapiViewer } from './OpenapiViewer';
 export type { PlaygroundConfig, SchemaSource, PlaygroundProps } from './OpenapiViewer';
 
-// Export VideoPlayer
+// Export VideoPlayer (media-chrome shell with provider-aware canvases)
 export {
   VideoPlayer,
-  VideoControls,
-  VidstackProvider,
-  NativeProvider,
-  StreamProvider,
-  VideoPlayerProvider,
-  useVideoPlayerContext,
-  VideoErrorFallback,
-  createVideoErrorFallback,
-  resolvePlayerMode,
-  resolveFileSource,
-  isSimpleStreamSource,
-  resolveStreamSource,
+  CanvasDispatcher,
+  NativeCanvas,
+  YouTubeCanvas,
+  VimeoCanvas,
+  HlsCanvas,
+  IframeCanvas,
+  PlayButton,
+  SeekBar,
+  Volume,
+  Fullscreen,
+  Pip,
+  PlaybackRate,
+  ControlsBar,
+  Poster,
+  parseEmbedUrl,
+  extractYouTubeId,
+  extractVimeoId,
 } from './VideoPlayer';
 export type {
-  VideoSourceUnion,
+  VideoSource,
   UrlSource,
   YouTubeSource,
   VimeoSource,
-  HLSSource,
-  DASHSource,
-  StreamSource,
-  BlobSource,
-  DataUrlSource,
-  PlayerMode,
+  HlsSource,
+  IframeSource,
   AspectRatioValue,
   VideoPlayerProps,
-  VideoPlayerRef,
-  ErrorFallbackProps,
-  ResolveFileSourceOptions,
-  VideoPlayerContextValue,
-  VideoPlayerProviderProps,
-  SimpleStreamSource,
-  VideoErrorFallbackProps,
-  CreateVideoErrorFallbackOptions,
+  VideoPlayerSettings,
+  PlayButtonProps,
+  SeekBarProps,
+  VolumeProps,
+  FullscreenProps,
+  PipProps,
+  PlaybackRateProps,
+  ControlsBarProps,
+  CanvasDispatcherProps,
+  NativeCanvasProps,
+  YouTubeCanvasProps,
+  VimeoCanvasProps,
+  HlsCanvasProps,
+  IframeCanvasProps,
 } from './VideoPlayer';
 
 // AudioPlayer v6 — under construction (see @dev/@refactoring6-audioplayer/).

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,172 +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, Button, DownloadButton } from '../../_shared';
-
-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}
-    />
-  );
-}