@djangocfg/ui-tools 2.1.402 → 2.1.407

package/src/tools/VideoPlayer/README.md

@@ -1,264 +1,121 @@
 # 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
+Composable video player built on [media-chrome](https://media-chrome.org)
+(Mux, MIT, ~12 KB). One `<MediaController>` shell drives **YouTube**,
+**Vimeo**, **HLS**, native **MP4/WebM**, and arbitrary **iframe**
+embeds — the source element swaps, the UI stays the same.
 
 ```tsx
-import {
-  VideoPlayer,
-  VideoPlayerProvider,
-  VideoErrorFallback,
-  resolveFileSource
-} from '@djangocfg/ui-nextjs';
-```
+import { VideoPlayer } from '@djangocfg/ui-tools/video-player';
 
-## Basic Usage
+// Structured source
+<VideoPlayer source={{ type: 'youtube', videoId: 'sGbxmsDFVnE' }} />
 
-### YouTube / Vimeo
-
-```tsx
-<VideoPlayer source={{ type: 'youtube', id: 'dQw4w9WgXcQ' }} />
-<VideoPlayer source={{ type: 'vimeo', id: '123456789' }} />
+// Raw URL — auto-classified (YouTube / Vimeo / HLS / MP4 / iframe)
+<VideoPlayer source="https://youtu.be/sGbxmsDFVnE?t=90" />
 ```
 
-### HLS / DASH Streaming
+## Why media-chrome
 
-```tsx
-<VideoPlayer source={{ type: 'hls', url: 'https://example.com/video.m3u8' }} />
-<VideoPlayer source={{ type: 'dash', url: 'https://example.com/video.mpd' }} />
-```
+Native HTML5 `<video>` can't play YouTube. Hand-rolling the YouTube
+IFrame API and keeping it in sync with a custom control bar is fragile.
+media-chrome solves both: its `<media-controller>` speaks one protocol,
+and provider elements (`<youtube-video>`, `<vimeo-video>`,
+`<hls-video>`) plug into the same slot. Our control parts are thin
+React wrappers themed through CSS custom properties.
 
-### Direct URL
+## Sources
 
-```tsx
-<VideoPlayer source={{ type: 'url', url: 'https://example.com/video.mp4' }} />
-```
+`VideoSource` is a discriminated union — pass an object, or a raw URL
+string that `parseEmbedUrl` classifies for you.
 
-### HTTP Range Streaming (with auth)
+| `type` | Shape | Engine |
+|---|---|---|
+| `url` | `{ type:'url', url, mimeType?, poster?, title? }` | native `<video>` |
+| `youtube` | `{ type:'youtube', videoId, startTime?, playlistId?, poster?, title? }` | `youtube-video-element` |
+| `vimeo` | `{ type:'vimeo', videoId, startTime?, poster?, title? }` | `vimeo-video-element` |
+| `hls` | `{ type:'hls', url, poster?, title? }` | `hls-video-element` (native in Safari, `hls.js` elsewhere) |
+| `iframe` | `{ type:'iframe', url, allow?, poster?, title? }` | plain `<iframe>` — control bar auto-hidden |
 
 ```tsx
-// Full source (standalone)
-<VideoPlayer
-  source={{
-    type: 'stream',
-    sessionId: 'abc123',
-    path: '/videos/movie.mp4',
-    getStreamUrl: (id, path) => `/api/stream/${id}?path=${path}&token=${token}`
-  }}
-/>
+import { parseEmbedUrl } from '@djangocfg/ui-tools/video-player';
 
-// Simplified source (with context)
-<VideoPlayerProvider sessionId={sessionId} getStreamUrl={getStreamUrl}>
-  <VideoPlayer source={{ type: 'stream', path: '/videos/movie.mp4' }} />
-</VideoPlayerProvider>
-```
+parseEmbedUrl('https://www.youtube.com/watch?v=ID&t=42s');
+// → { type: 'youtube', videoId: 'ID', startTime: 42 }
 
-### Blob / ArrayBuffer
+parseEmbedUrl('https://vimeo.com/76979871');
+// → { type: 'vimeo', videoId: '76979871' }
 
-```tsx
-<VideoPlayer
-  source={{
-    type: 'blob',
-    data: arrayBuffer,
-    mimeType: 'video/mp4'
-  }}
-/>
+parseEmbedUrl('https://stream.mux.com/abc.m3u8');
+// → { type: 'hls', url: '…' }
 ```
 
 ## 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
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `source` | `VideoSource \| string` | — | Object or raw URL (auto-parsed). |
+| `controls` | `boolean` | `true` | `false` → no built-in control bar. |
+| `aspectRatio` | `number \| 'auto' \| 'fill'` | `16/9` | `'fill'` stretches to parent height; `'auto'` keeps intrinsic. |
+| `autoPlay` | `boolean` | `false` | Browsers require `muted` for autoplay to start. |
+| `muted` / `loop` / `playsInline` | `boolean` | — | Forwarded to the engine. |
+| `preload` | `'none' \| 'metadata' \| 'auto'` | — | Native sources only. |
+| `crossOrigin` | `'' \| 'anonymous' \| 'use-credentials'` | `'anonymous'` | Native sources only. |
+| `className` | `string` | — | On the `<MediaController>` wrapper. |
+| `children` | `ReactNode` | — | Replaces the default control bar entirely. |
 
-```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>
-```
+## Composable layout
 
-## 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:
+Bring your own control bar by passing `children`. Compose any
+media-chrome element or our restyled parts:
 
 ```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} />;
-}
+import {
+  VideoPlayer, ControlsBar, PlayButton, SeekBar,
+  Volume, PlaybackRate, Pip, Fullscreen,
+} from '@djangocfg/ui-tools/video-player';
+
+<VideoPlayer source={{ type: 'url', url: '/clip.mp4' }}>
+  <ControlsBar>
+    <PlayButton />
+    <SeekBar />
+    <Volume />
+    <PlaybackRate />
+    <Pip />
+    <Fullscreen />
+  </ControlsBar>
+</VideoPlayer>
 ```
 
-## Source Types Reference
+## Parts
 
-```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 }
-```
+`PlayButton` · `SeekBar` · `Volume` · `PlaybackRate` · `Pip` ·
+`Fullscreen` · `ControlsBar` · `Poster` — thin wrappers over
+media-chrome components, restyled through semantic tokens. Each accepts
+the props of the media-chrome element it wraps.
 
-## Architecture
+## Theming
 
-```
-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
-```
+media-chrome reads CSS custom properties; `styles/video-player.css`
+binds them to ui-core semantic tokens (`--primary`, `--popover`, …) via
+`color-mix`, so the player follows light/dark and any active preset.
+The video surface itself stays dark (`bg-black`) by convention.
 
-## Accessibility
+## Notes
 
-Full accessibility support:
-- Keyboard navigation (Space, Arrow keys, F for fullscreen)
-- Screen reader announcements
-- Focus indicators
-- ARIA labels and roles
+- **YouTube/Vimeo branding** — embed providers enforce a minimal logo;
+  `modestbranding` / `rel=0` reduce it but it cannot be fully removed.
+- **PiP over YouTube** — depends on the embed; the button hides itself
+  when the engine reports no support.
+- **HLS** — native in Safari; elsewhere `hls-video-element` lazy-loads
+  `hls.js` (~110 KB) on first HLS mount only.
+- **`LazyVideoPlayer`** — kept as a synchronous alias of `VideoPlayer`
+  for back-compat. No lazy boundary is needed; engines tree-shake per
+  source type.
 
-## Browser Support
+## Storybook
 
-- Chrome 63+
-- Firefox 67+
-- Safari 12+
-- Edge 79+
-- iOS Safari 12+
-- Chrome Android 63+
+`UI Tools / Video Player / Player` — `NativeMp4`, `YouTubeStarWars`,
+`YouTubeStarTrek`, `YouTubeAutoParseUrl`, `YouTubeWithTimestamp`,
+`Vimeo`, `Sintel`, `HlsStream`, `ComposableLayout`, `Fill`,
+`NoControls`, `LazyAlias`.

package/src/tools/VideoPlayer/VideoPlayer.tsx

@@ -0,0 +1,82 @@
+'use client';
+
+/**
+ * VideoPlayer — composable shell over `media-chrome` web components.
+ *
+ * The shell is just a `<MediaController>` wrapper + a `<CanvasDispatcher>`
+ * that mounts the right media element (`<video>`, `<youtube-video>`,
+ * `<vimeo-video>`, `<hls-video>`, `<iframe>`) into the `media` slot.
+ *
+ * Custom layouts: pass `children` to replace the default control bar.
+ * `controls={false}` opts out of any control surface (useful for
+ * iframe sources where the embed renders its own UI).
+ */
+
+import { useMemo, type CSSProperties } from 'react';
+import { MediaController } from 'media-chrome/react';
+import { cn } from '@djangocfg/ui-core/lib';
+import './styles/video-player.css';
+
+import type { VideoPlayerProps, AspectRatioValue } from './types';
+import { parseEmbedUrl } from './utils/parse-embed-url';
+import { CanvasDispatcher } from './canvas/canvas-dispatcher';
+import {
+  ControlsBar,
+  PlayButton,
+  SeekBar,
+  Volume,
+  PlaybackRate,
+  Pip,
+  Fullscreen,
+} from './parts';
+
+function aspectRatioStyle(ar: AspectRatioValue): CSSProperties | undefined {
+  if (ar === 'fill') return { height: '100%' };
+  if (ar === 'auto') return undefined;
+  return { aspectRatio: String(ar) };
+}
+
+export function VideoPlayer({
+  source,
+  controls = true,
+  aspectRatio = 16 / 9,
+  className,
+  children,
+  ...settings
+}: VideoPlayerProps) {
+  const normalized = useMemo(
+    () => (typeof source === 'string' ? parseEmbedUrl(source) : source),
+    [source],
+  );
+
+  const isIframe = normalized.type === 'iframe';
+  // For iframe embeds media-chrome cannot drive the inner player — hide the
+  // control bar to avoid a non-functional UI.
+  const showControls = controls && !isIframe;
+
+  return (
+    <MediaController
+      // Fade controls + scrim after 2.5s of inactivity while playing;
+      // they reappear on mousemove / pause / focus (media-chrome built-in).
+      autohide="2.5"
+      className={cn(
+        'video-player relative block w-full overflow-hidden rounded-lg bg-black',
+        className,
+      )}
+      style={aspectRatioStyle(aspectRatio)}
+    >
+      <CanvasDispatcher source={normalized} {...settings} />
+      {children ??
+        (showControls && (
+          <ControlsBar>
+            <PlayButton />
+            <SeekBar />
+            <Volume iconOnly />
+            <PlaybackRate />
+            <Pip />
+            <Fullscreen />
+          </ControlsBar>
+        ))}
+    </MediaController>
+  );
+}

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

@@ -0,0 +1,34 @@
+'use client';
+
+/**
+ * Dispatches `source.type` to the right canvas. Single-switch indirection
+ * keeps `<VideoPlayer>` simple and isolates engine-specific imports inside
+ * the canvas files so tree-shakers can drop unused providers.
+ */
+
+import type { VideoSource, VideoPlayerSettings } from '../types';
+import { NativeCanvas } from './native-canvas';
+import { YouTubeCanvas } from './youtube-canvas';
+import { VimeoCanvas } from './vimeo-canvas';
+import { HlsCanvas } from './hls-canvas';
+import { IframeCanvas } from './iframe-canvas';
+
+export interface CanvasDispatcherProps extends VideoPlayerSettings {
+  readonly source: VideoSource;
+}
+
+export function CanvasDispatcher({ source, ...settings }: CanvasDispatcherProps) {
+  switch (source.type) {
+    case 'youtube':
+      return <YouTubeCanvas source={source} {...settings} />;
+    case 'vimeo':
+      return <VimeoCanvas source={source} {...settings} />;
+    case 'hls':
+      return <HlsCanvas source={source} {...settings} />;
+    case 'iframe':
+      return <IframeCanvas source={source} />;
+    case 'url':
+    default:
+      return <NativeCanvas source={source} {...settings} />;
+  }
+}

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

@@ -0,0 +1,38 @@
+'use client';
+
+/**
+ * `<hls-video slot="media">` — HLS (`.m3u8`) playback via
+ * `hls-video-element`, which lazy-loads `hls.js` only on browsers that
+ * don't ship native HLS (everything except Safari).
+ */
+
+import 'hls-video-element';
+import { MediaPosterImage } from 'media-chrome/react';
+import type { HlsSource, VideoPlayerSettings } from '../types';
+
+export interface HlsCanvasProps extends VideoPlayerSettings {
+  readonly source: HlsSource;
+}
+
+export function HlsCanvas({
+  source,
+  autoPlay,
+  muted,
+  loop,
+  crossOrigin = 'anonymous',
+}: HlsCanvasProps) {
+  return (
+    <>
+      <hls-video
+        slot="media"
+        src={source.url}
+        crossOrigin={crossOrigin}
+        {...(muted && { muted: true })}
+        {...(autoPlay && { autoplay: true })}
+        {...(loop && { loop: true })}
+        playsInline
+      />
+      {source.poster && <MediaPosterImage slot="poster" src={source.poster} />}
+    </>
+  );
+}

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

@@ -0,0 +1,33 @@
+'use client';
+
+/**
+ * Fallback `<iframe>` for arbitrary embed URLs that don't fit a known
+ * provider. Rendered *outside* the media-chrome controls (no
+ * `slot="media"`) because there is no JS bridge between the iframe
+ * contents and `<MediaController>`. Consumers should pass
+ * `controls={false}` for iframe sources, or live with a non-functional
+ * control bar — we hide it via CSS in `VideoPlayer.tsx`.
+ */
+
+import type { IframeSource } from '../types';
+
+export interface IframeCanvasProps {
+  readonly source: IframeSource;
+}
+
+const DEFAULT_ALLOW =
+  'accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share';
+
+export function IframeCanvas({ source }: IframeCanvasProps) {
+  return (
+    <iframe
+      slot="media"
+      src={source.url}
+      title={source.title ?? 'Embedded video'}
+      allow={source.allow ?? DEFAULT_ALLOW}
+      allowFullScreen
+      referrerPolicy="strict-origin-when-cross-origin"
+      className="absolute inset-0 h-full w-full border-0"
+    />
+  );
+}

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

@@ -0,0 +1,12 @@
+export { CanvasDispatcher } from './canvas-dispatcher';
+export type { CanvasDispatcherProps } from './canvas-dispatcher';
+export { NativeCanvas } from './native-canvas';
+export type { NativeCanvasProps } from './native-canvas';
+export { YouTubeCanvas } from './youtube-canvas';
+export type { YouTubeCanvasProps } from './youtube-canvas';
+export { VimeoCanvas } from './vimeo-canvas';
+export type { VimeoCanvasProps } from './vimeo-canvas';
+export { HlsCanvas } from './hls-canvas';
+export type { HlsCanvasProps } from './hls-canvas';
+export { IframeCanvas } from './iframe-canvas';
+export type { IframeCanvasProps } from './iframe-canvas';

package/src/tools/VideoPlayer/canvas/jsx.d.ts

@@ -0,0 +1,54 @@
+/**
+ * JSX intrinsic-element declarations for the custom-element wrappers
+ * shipped by `youtube-video-element`, `vimeo-video-element`,
+ * `hls-video-element`.
+ *
+ * media-chrome relies on `slot="media"` to attach a media element to
+ * its `<MediaController>`. We declare the bare minimum prop surface
+ * we use — `src`, `slot`, `autoplay`, `muted`, `loop`, `playsinline`,
+ * `crossorigin`, `preload`, `poster`.
+ *
+ * All custom elements are HTMLElement subclasses with `HTMLVideoElement`
+ * -shaped APIs, so we type their JSX props as a partial of
+ * `HTMLVideoElementAttributes` + `slot`.
+ */
+
+import type { DetailedHTMLProps, HTMLAttributes, VideoHTMLAttributes } from 'react';
+
+type VideoLikeElement = DetailedHTMLProps<
+  VideoHTMLAttributes<HTMLElement> & HTMLAttributes<HTMLElement>,
+  HTMLElement
+>;
+
+/**
+ * `youtube-video-element` accepts a `config` property — an object merged
+ * into the YouTube IFrame `playerVars` (it is JSON-serialized into a
+ * `data-config` attribute internally). Used to suppress native chrome.
+ */
+type YouTubeVideoElement = VideoLikeElement & {
+  config?: Record<string, string | number | boolean>;
+};
+
+declare module 'react' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'youtube-video': YouTubeVideoElement;
+      'vimeo-video': VideoLikeElement;
+      'hls-video': VideoLikeElement;
+    }
+  }
+}
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'youtube-video': YouTubeVideoElement;
+      'vimeo-video': VideoLikeElement;
+      'hls-video': VideoLikeElement;
+    }
+  }
+}
+
+export {};

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

@@ -0,0 +1,38 @@
+'use client';
+
+/**
+ * Native `<video slot="media">` for direct MP4 / WebM / blob / data URLs.
+ */
+
+import { MediaPosterImage } from 'media-chrome/react';
+import type { UrlSource, VideoPlayerSettings } from '../types';
+
+export interface NativeCanvasProps extends VideoPlayerSettings {
+  readonly source: UrlSource;
+}
+
+export function NativeCanvas({
+  source,
+  autoPlay,
+  muted,
+  loop,
+  playsInline = true,
+  crossOrigin = 'anonymous',
+  preload = 'metadata',
+}: NativeCanvasProps) {
+  return (
+    <>
+      <video
+        slot="media"
+        src={source.url}
+        muted={muted}
+        loop={loop}
+        autoPlay={autoPlay}
+        playsInline={playsInline}
+        crossOrigin={crossOrigin}
+        preload={preload}
+      />
+      {source.poster && <MediaPosterImage slot="poster" src={source.poster} />}
+    </>
+  );
+}