@djangocfg/ui-tools 2.1.402 → 2.1.407

package/src/tools/VideoPlayer/canvas/vimeo-canvas.tsx

@@ -0,0 +1,39 @@
+'use client';
+
+/**
+ * `<vimeo-video slot="media">` — Vimeo Player API wrapper as a custom
+ * element via `vimeo-video-element`. Same media-chrome integration story
+ * as the YouTube canvas.
+ */
+
+import 'vimeo-video-element';
+import { MediaPosterImage } from 'media-chrome/react';
+import type { VimeoSource, VideoPlayerSettings } from '../types';
+
+export interface VimeoCanvasProps extends VideoPlayerSettings {
+  readonly source: VimeoSource;
+}
+
+export function VimeoCanvas({
+  source,
+  autoPlay,
+  muted,
+  loop,
+}: VimeoCanvasProps) {
+  const base = `https://vimeo.com/${source.videoId}`;
+  const src = source.startTime ? `${base}#t=${source.startTime}s` : base;
+
+  return (
+    <>
+      <vimeo-video
+        slot="media"
+        src={src}
+        {...(muted && { muted: true })}
+        {...(autoPlay && { autoplay: true })}
+        {...(loop && { loop: true })}
+        playsInline
+      />
+      {source.poster && <MediaPosterImage slot="poster" src={source.poster} />}
+    </>
+  );
+}

package/src/tools/VideoPlayer/canvas/youtube-canvas.tsx

@@ -0,0 +1,77 @@
+'use client';
+
+/**
+ * `<youtube-video slot="media">` — registers the custom element via
+ * `youtube-video-element` side-effect import. The element wraps the
+ * YouTube IFrame API and exposes an `HTMLVideoElement`-shaped surface
+ * that media-chrome's `<MediaController>` drives.
+ *
+ * `youtube-video-element` already defaults the embed to `controls=0`,
+ * `rel=0`, `iv_load_policy=3`, `modestbranding=1`. We extend that via
+ * the `config` prop (serialized into `data-config`, merged into the
+ * IFrame `playerVars`) to also suppress YouTube's keyboard handling
+ * (`disablekb=1` — our controls own keyboard) and the in-player
+ * close-captions toggle the element turns on by default.
+ *
+ * NOTE: YouTube's ToS forbids fully hiding its branding — a small logo
+ * and the pause-screen overlay remain by design. `modestbranding=1` is
+ * the maximum allowed suppression.
+ */
+
+import 'youtube-video-element';
+import { MediaPosterImage } from 'media-chrome/react';
+import type { YouTubeSource, VideoPlayerSettings } from '../types';
+
+export interface YouTubeCanvasProps extends VideoPlayerSettings {
+  readonly source: YouTubeSource;
+}
+
+/**
+ * Extra YouTube IFrame `playerVars` merged on top of the element
+ * defaults. Keep keys YouTube-documented:
+ * https://developers.google.com/youtube/player_parameters
+ */
+const YT_PLAYER_VARS = {
+  // We render our own media-chrome control bar — hide YouTube's.
+  controls: 0,
+  // Our keyboard shortcuts own the player; disable YouTube's.
+  disablekb: 1,
+  // Minimise the YouTube logo chrome (max suppression allowed by ToS).
+  modestbranding: 1,
+  // Do not surface "More videos" / related-channel end-screen suggestions.
+  rel: 0,
+  // Hide video annotations.
+  iv_load_policy: 3,
+  // Keep playback inline on iOS instead of forcing native fullscreen.
+  playsinline: 1,
+  // Don't auto-load closed captions.
+  cc_load_policy: 0,
+} as const;
+
+export function YouTubeCanvas({
+  source,
+  autoPlay,
+  muted,
+  loop,
+}: YouTubeCanvasProps) {
+  const params = new URLSearchParams();
+  params.set('v', source.videoId);
+  if (source.startTime) params.set('t', `${source.startTime}s`);
+  if (source.playlistId) params.set('list', source.playlistId);
+  const src = `https://www.youtube.com/watch?${params.toString()}`;
+
+  return (
+    <>
+      <youtube-video
+        slot="media"
+        src={src}
+        config={YT_PLAYER_VARS}
+        {...(muted && { muted: true })}
+        {...(autoPlay && { autoplay: true })}
+        {...(loop && { loop: true })}
+        playsInline
+      />
+      {source.poster && <MediaPosterImage slot="poster" src={source.poster} />}
+    </>
+  );
+}

package/src/tools/VideoPlayer/index.ts

@@ -1,77 +1,63 @@
 /**
- * VideoPlayer - Unified Video Player
- * Supports Vidstack (YouTube, Vimeo, HLS, DASH), Native HTML5, and HTTP Streaming
+ * VideoPlayer — full public surface.
+ *
+ * Prefer importing through the subpath entry:
+ *   `import { VideoPlayer } from '@djangocfg/ui-tools/video-player'`
+ *
+ * which routes through `lazy.tsx`. This `index.ts` is the underlying barrel.
  */
 
-// Main component
-export { VideoPlayer } from './components';
+export { VideoPlayer } from './VideoPlayer';
 
-// Controls (can be used standalone with Vidstack)
-export { VideoControls } from './components';
-
-// Error Fallback
-export {
-  VideoErrorFallback,
-  createVideoErrorFallback,
-} from './components';
 export type {
-  VideoErrorFallbackProps,
-  CreateVideoErrorFallbackOptions,
-} from './components';
+  VideoPlayerProps,
+  VideoPlayerSettings,
+  VideoSource,
+  UrlSource,
+  YouTubeSource,
+  VimeoSource,
+  HlsSource,
+  IframeSource,
+  AspectRatioValue,
+} from './types';
 
-// Providers (for advanced usage)
-export { VidstackProvider, NativeProvider, StreamProvider } from './providers';
+export { parseEmbedUrl } from './utils/parse-embed-url';
+export { extractYouTubeId, parseYouTubeStartTime } from './utils/youtube-id';
+export { extractVimeoId } from './utils/vimeo-id';
 
-// Context (for streaming configuration)
 export {
-  VideoPlayerProvider,
-  useVideoPlayerContext,
-} from './context';
-
-// Hooks
-export { useVideoPositionCache } from './hooks';
+  CanvasDispatcher,
+  NativeCanvas,
+  YouTubeCanvas,
+  VimeoCanvas,
+  HlsCanvas,
+  IframeCanvas,
+} from './canvas';
 export type {
-  UseVideoPositionCacheOptions,
-  UseVideoPositionCacheReturn,
-} from './hooks';
+  CanvasDispatcherProps,
+  NativeCanvasProps,
+  YouTubeCanvasProps,
+  VimeoCanvasProps,
+  HlsCanvasProps,
+  IframeCanvasProps,
+} from './canvas';
 
-// Utils
 export {
-  resolvePlayerMode,
-  resolveFileSource,
-  isSimpleStreamSource,
-  resolveStreamSource,
-} from './utils';
-
-// Types
+  PlayButton,
+  SeekBar,
+  Volume,
+  Fullscreen,
+  Pip,
+  PlaybackRate,
+  ControlsBar,
+  Poster,
+} from './parts';
 export type {
-  // Source types
-  VideoSourceUnion,
-  UrlSource,
-  YouTubeSource,
-  VimeoSource,
-  HLSSource,
-  DASHSource,
-  StreamSource,
-  BlobSource,
-  DataUrlSource,
-  // Player types
-  PlayerMode,
-  AspectRatioValue,
-  VideoPlayerProps,
-  VideoPlayerRef,
-  ErrorFallbackProps,
-  // Provider props (internal)
-  VidstackProviderProps,
-  NativeProviderProps,
-  StreamProviderProps,
-  // Common types
-  CommonPlayerSettings,
-  CommonPlayerEvents,
-  // File source helper types
-  ResolveFileSourceOptions,
-  // Context types
-  VideoPlayerContextValue,
-  VideoPlayerProviderProps,
-  SimpleStreamSource,
-} from './types';
+  PlayButtonProps,
+  SeekBarProps,
+  VolumeProps,
+  FullscreenProps,
+  PipProps,
+  PlaybackRateProps,
+  ControlsBarProps,
+} from './parts';

package/src/tools/VideoPlayer/lazy.tsx

@@ -1,63 +1,20 @@
 'use client';
 
 /**
- * Lazy-loaded VideoPlayer Component
+ * Subpath entry: `@djangocfg/ui-tools/video-player`.
  *
- * Heavy Vidstack (~150KB) is loaded only when component is rendered.
- * Use this for automatic code-splitting with Suspense fallback.
+ * Built on `media-chrome` web components — the React layer is ~3 KB of
+ * thin wrappers, and provider engines (`youtube-video-element`,
+ * `vimeo-video-element`, `hls-video-element`) are imported only by the
+ * matching canvas file, so unused engines are tree-shaken.
  *
- * For direct imports without lazy loading, use:
- * import { VideoPlayer } from '@djangocfg/ui-tools/video'
+ * `LazyVideoPlayer` is preserved as a synchronous alias for back-compat
+ * with existing consumers (e.g. cmdop desktop's document-preview).
  */
 
-import { createLazyComponent, LoadingFallback } from '../../components';
-import type { VideoPlayerProps } from './types';
+export * from './index';
 
-// ============================================================================
-// Re-export types
-// ============================================================================
+import { VideoPlayer } from './VideoPlayer';
 
-export type { VideoPlayerProps };
-
-// ============================================================================
-// Video Loading Fallback
-// ============================================================================
-
-function VideoLoadingFallback() {
-  return (
-    <div className="flex items-center justify-center bg-black/90 rounded-lg aspect-video">
-      <div className="flex flex-col items-center gap-2">
-        <div className="relative">
-          <div className="h-10 w-10 animate-spin rounded-full border-4 border-white/20 border-t-white" />
-          <div className="absolute inset-0 flex items-center justify-center">
-            <svg
-              className="h-5 w-5 text-white/60"
-              fill="currentColor"
-              viewBox="0 0 24 24"
-            >
-              <path d="M8 5v14l11-7z" />
-            </svg>
-          </div>
-        </div>
-        <span className="text-sm text-white/60">Loading video player...</span>
-      </div>
-    </div>
-  );
-}
-
-// ============================================================================
-// Lazy Component
-// ============================================================================
-
-/**
- * LazyVideoPlayer - Lazy-loaded professional video player
- *
- * Automatically shows loading state while Vidstack loads (~150KB)
- */
-export const LazyVideoPlayer = createLazyComponent<VideoPlayerProps>(
-  () => import('./components').then((mod) => ({ default: mod.VideoPlayer })),
-  {
-    displayName: 'LazyVideoPlayer',
-    fallback: <VideoLoadingFallback />,
-  }
-);
+/** @deprecated Use `VideoPlayer` directly — no lazy boundary is needed. */
+export const LazyVideoPlayer = VideoPlayer;

package/src/tools/VideoPlayer/parts/controls-bar.tsx

@@ -0,0 +1,35 @@
+'use client';
+
+import { MediaControlBar } from 'media-chrome/react';
+import { cn } from '@djangocfg/ui-core/lib';
+import type { ComponentProps } from 'react';
+
+export type ControlsBarProps = ComponentProps<typeof MediaControlBar>;
+
+/**
+ * Control bar pinned to the bottom over a bottom-up black scrim so the
+ * controls stay legible on any video frame. Colours read on-black
+ * regardless of theme — the video canvas is always a black surface.
+ *
+ * The bar participates in media-chrome's `autohide`: when the
+ * `<MediaController>` adds the `mediacontrolshidden` user-inactive
+ * state, we fade the whole bar (controls + scrim) out together.
+ */
+export function ControlsBar({ className, children, ...props }: ControlsBarProps) {
+  return (
+    <MediaControlBar
+      {...props}
+      className={cn(
+        // Layout — extra top padding gives the scrim room to fade in.
+        'video-player__control-bar',
+        'absolute inset-x-0 bottom-0 flex items-center gap-1 px-2 pb-1.5 pt-8',
+        // Bottom-up scrim so controls read over any frame.
+        'bg-gradient-to-t from-black/75 via-black/40 to-transparent',
+        'text-foreground',
+        className,
+      )}
+    >
+      {children}
+    </MediaControlBar>
+  );
+}

package/src/tools/VideoPlayer/parts/fullscreen.tsx

@@ -0,0 +1,19 @@
+'use client';
+
+import { MediaFullscreenButton } from 'media-chrome/react';
+import { cn } from '@djangocfg/ui-core/lib';
+import type { ComponentProps } from 'react';
+
+export type FullscreenProps = ComponentProps<typeof MediaFullscreenButton>;
+
+export function Fullscreen({ className, ...props }: FullscreenProps) {
+  return (
+    <MediaFullscreenButton
+      {...props}
+      className={cn(
+        'media-control-square h-8 w-8 rounded-md text-foreground hover:bg-foreground/10',
+        className,
+      )}
+    />
+  );
+}

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

@@ -0,0 +1,15 @@
+export { PlayButton } from './play-button';
+export type { PlayButtonProps } from './play-button';
+export { SeekBar } from './seek-bar';
+export type { SeekBarProps } from './seek-bar';
+export { Volume } from './volume';
+export type { VolumeProps } from './volume';
+export { Fullscreen } from './fullscreen';
+export type { FullscreenProps } from './fullscreen';
+export { Pip } from './pip';
+export type { PipProps } from './pip';
+export { PlaybackRate } from './playback-rate';
+export type { PlaybackRateProps } from './playback-rate';
+export { ControlsBar } from './controls-bar';
+export type { ControlsBarProps } from './controls-bar';
+export { Poster } from './poster';

package/src/tools/VideoPlayer/parts/pip.tsx

@@ -0,0 +1,19 @@
+'use client';
+
+import { MediaPipButton } from 'media-chrome/react';
+import { cn } from '@djangocfg/ui-core/lib';
+import type { ComponentProps } from 'react';
+
+export type PipProps = ComponentProps<typeof MediaPipButton>;
+
+export function Pip({ className, ...props }: PipProps) {
+  return (
+    <MediaPipButton
+      {...props}
+      className={cn(
+        'media-control-square h-8 w-8 rounded-md text-foreground hover:bg-foreground/10',
+        className,
+      )}
+    />
+  );
+}

package/src/tools/VideoPlayer/parts/play-button.tsx

@@ -0,0 +1,19 @@
+'use client';
+
+import { MediaPlayButton } from 'media-chrome/react';
+import { cn } from '@djangocfg/ui-core/lib';
+import type { ComponentProps } from 'react';
+
+export type PlayButtonProps = ComponentProps<typeof MediaPlayButton>;
+
+export function PlayButton({ className, ...props }: PlayButtonProps) {
+  return (
+    <MediaPlayButton
+      {...props}
+      className={cn(
+        'media-control-square video-player__control h-8 w-8',
+        className,
+      )}
+    />
+  );
+}

package/src/tools/VideoPlayer/parts/playback-rate.tsx

@@ -0,0 +1,31 @@
+'use client';
+
+import { MediaPlaybackRateButton } from 'media-chrome/react';
+import { cn } from '@djangocfg/ui-core/lib';
+import type { ComponentProps } from 'react';
+
+export type PlaybackRateProps = Omit<
+  ComponentProps<typeof MediaPlaybackRateButton>,
+  'rates'
+> & {
+  /** Space-separated list, e.g. `'0.5 1 1.5 2'`, or an array of numbers. */
+  readonly rates?: string | readonly number[];
+};
+
+const DEFAULT_RATES: readonly number[] = [0.5, 0.75, 1, 1.25, 1.5, 1.75, 2];
+
+export function PlaybackRate({ className, rates, ...props }: PlaybackRateProps) {
+  const value = rates ?? DEFAULT_RATES;
+  return (
+    <MediaPlaybackRateButton
+      {...props}
+      // media-chrome's setter accepts `string | ArrayLike<number>` — the
+      // React typing pulls from the getter only, which is narrower.
+      rates={value as unknown as ArrayLike<number>}
+      className={cn(
+        'h-8 rounded-md px-2 text-xs tabular-nums text-foreground hover:bg-foreground/10',
+        className,
+      )}
+    />
+  );
+}

package/src/tools/VideoPlayer/parts/poster.tsx

@@ -0,0 +1,3 @@
+'use client';
+
+export { MediaPosterImage as Poster } from 'media-chrome/react';

package/src/tools/VideoPlayer/parts/seek-bar.tsx

@@ -0,0 +1,26 @@
+'use client';
+
+import { MediaTimeRange, MediaTimeDisplay } from 'media-chrome/react';
+import { cn } from '@djangocfg/ui-core/lib';
+import type { ComponentProps } from 'react';
+
+export type SeekBarProps = ComponentProps<typeof MediaTimeRange> & {
+  readonly showTime?: boolean;
+};
+
+export function SeekBar({ className, showTime = true, ...props }: SeekBarProps) {
+  return (
+    <>
+      <MediaTimeRange
+        {...props}
+        className={cn('h-8 flex-1 text-foreground', className)}
+      />
+      {showTime && (
+        <MediaTimeDisplay
+          showDuration
+          className="px-2 text-xs tabular-nums text-muted-foreground"
+        />
+      )}
+    </>
+  );
+}

package/src/tools/VideoPlayer/parts/volume.tsx

@@ -0,0 +1,32 @@
+'use client';
+
+import { MediaMuteButton, MediaVolumeRange } from 'media-chrome/react';
+import { cn } from '@djangocfg/ui-core/lib';
+import type { ComponentProps } from 'react';
+
+export interface VolumeProps {
+  readonly className?: string;
+  readonly iconOnly?: boolean;
+  readonly muteProps?: ComponentProps<typeof MediaMuteButton>;
+  readonly rangeProps?: ComponentProps<typeof MediaVolumeRange>;
+}
+
+export function Volume({ className, iconOnly, muteProps, rangeProps }: VolumeProps) {
+  return (
+    <div className={cn('flex items-center', className)}>
+      <MediaMuteButton
+        {...muteProps}
+        className={cn(
+          'media-control-square h-8 w-8 rounded-md text-foreground hover:bg-foreground/10',
+          muteProps?.className,
+        )}
+      />
+      {!iconOnly && (
+        <MediaVolumeRange
+          {...rangeProps}
+          className={cn('h-8 w-20 text-foreground', rangeProps?.className)}
+        />
+      )}
+    </div>
+  );
+}

package/src/tools/VideoPlayer/styles/video-player.css

@@ -0,0 +1,141 @@
+/*
+ * media-chrome theme.
+ *
+ * The video canvas is ALWAYS a black surface, so the control chrome is
+ * themed against on-black contrast — icons/text stay light in both the
+ * light and dark app themes. Only the accent (progress bar / thumb) and
+ * the scrub-time popover follow semantic tokens, since the popover is a
+ * detached surface that should match the rest of the platform.
+ *
+ * media-chrome ships its own focus-ring + tooltip styles; we only override
+ * what's needed to match the rest of the platform.
+ */
+
+media-controller {
+  /* On-black control chrome — fixed regardless of app theme. */
+  --video-on-canvas: rgb(245 245 245);
+
+  /* Surfaces */
+  --media-control-background: transparent;
+  --media-control-hover-background: rgb(255 255 255 / 0.14);
+  --media-control-padding: 0;
+
+  /* Foreground / accent */
+  --media-primary-color: var(--primary);
+  --media-secondary-color: rgb(255 255 255 / 0.6);
+  --media-text-color: var(--video-on-canvas);
+  --media-icon-color: var(--video-on-canvas);
+  --media-loading-icon-color: var(--video-on-canvas);
+
+  /* Range / progress bar — thin translucent rail, small accent thumb.
+     The range element keeps a tall hit-area; only the painted track is
+     4px so it reads as a slim progress line over the video. */
+  --media-range-track-background: color-mix(in oklab, white 28%, transparent);
+  --media-range-track-border-radius: 9999px;
+  --media-range-track-height: 4px;
+  --media-range-track-pointer-background: color-mix(in oklab, white 40%, transparent);
+  --media-range-bar-color: var(--primary);
+  --media-range-thumb-background: var(--primary);
+  --media-range-thumb-border-radius: 9999px;
+  --media-range-thumb-width: 12px;
+  --media-range-thumb-height: 12px;
+  --media-range-thumb-opacity: 0;
+  --media-range-thumb-transition: opacity 0.15s ease;
+
+  /* Tooltip */
+  --media-tooltip-background: var(--popover);
+  --media-tooltip-color: var(--popover-foreground);
+  --media-tooltip-border-radius: 6px;
+
+  /* Font */
+  --media-font-family: inherit;
+  --media-font-size: 12px;
+
+  /* Layout */
+  display: block;
+  position: relative;
+  width: 100%;
+}
+
+/* Square icon buttons should size to the wrapper. */
+media-controller .media-control-square::part(button) {
+  width: 100%;
+  height: 100%;
+}
+
+/*
+ * Control buttons / text — fixed on-black colours. The video canvas is
+ * always dark, so these never follow the app's light/dark theme.
+ */
+.video-player__control {
+  color: var(--video-on-canvas, rgb(245 245 245));
+  border-radius: 0.375rem;
+  transition: background-color 0.15s ease;
+}
+
+.video-player__control:hover {
+  background-color: rgb(255 255 255 / 0.14);
+}
+
+.video-player__time {
+  color: rgb(255 255 255 / 0.72);
+}
+
+/* Hide the default control bar background — we paint our own gradient
+   scrim via the <ControlsBar> wrapper. */
+media-control-bar {
+  background: transparent;
+}
+
+/*
+ * Auto-hide. media-chrome flags inactivity by setting `userinactive` on
+ * the <media-controller>; it only does so while playback is running, and
+ * removes it on mousemove / pause / focus. We fade the whole control bar
+ * (controls + gradient scrim) together with a smooth opacity transition.
+ */
+.video-player__control-bar {
+  opacity: 1;
+  transition: opacity 0.3s ease-out;
+}
+
+media-controller[userinactive]:not([mediapaused]) .video-player__control-bar {
+  opacity: 0;
+  pointer-events: none;
+}
+
+/*
+ * Seek-bar hover preview. `<media-time-range>` exposes two slotted
+ * boxes: `preview-box` (a 120×109 thumbnail panel) and `current-box`
+ * (the scrub time label). With no `thumbnails` track wired up the
+ * preview-box has zero slotted content but still paints its default
+ * dark `rgb(31,31,31)` background — it shows as a stray empty
+ * rectangle floating over the video.
+ *
+ * Hide the empty preview-box entirely; keep `current-box` and style
+ * its time label as a compact popover chip.
+ */
+media-time-range {
+  /* media-chrome's own preview/box vars — point them at our popover
+     surface so the scrub time chip matches the rest of the controls. */
+  --media-preview-background: var(--popover);
+  --media-preview-border-radius: 6px;
+  --media-text-color: var(--popover-foreground);
+}
+
+/* Reveal the accent thumb only while hovering / scrubbing the rail. */
+media-time-range:hover {
+  --media-range-thumb-opacity: 1;
+}
+
+media-time-range::part(preview-box) {
+  display: none;
+}
+
+media-time-range::part(current-box) {
+  padding: 2px 6px;
+  border-radius: 6px;
+  background: var(--popover) !important;
+  color: var(--popover-foreground);
+  font-size: 11px;
+  box-shadow: 0 4px 12px color-mix(in oklab, var(--foreground) 18%, transparent);
+}