@djangocfg/layouts 1.4.27 → 1.4.29

package/src/snippets/VideoPlayer/README.md

@@ -79,6 +79,41 @@ function AdvancedPlayer() {
 
 ## Supported Video Sources
 
+### YouTube
+- **URL Format**: `https://www.youtube.com/watch?v=VIDEO_ID` or `youtube/VIDEO_ID`
+- **Auto-conversion**: Full YouTube URLs are automatically converted to `youtube/ID` format
+- **Poster**: ⚠️ YouTube iframe ignores custom poster images and always shows YouTube's thumbnail
+- **Examples**:
+  ```tsx
+  url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
+  url: 'https://youtu.be/dQw4w9WgXcQ'
+  url: 'youtube/dQw4w9WgXcQ'
+  ```
+
+### Vimeo
+- **URL Format**: `https://vimeo.com/VIDEO_ID` or `vimeo/VIDEO_ID`
+- **Auto-conversion**: Full Vimeo URLs are automatically converted to `vimeo/ID` format
+- **Poster**: ⚠️ Vimeo may ignore custom poster and use their own thumbnail
+- **Example**: `url: 'vimeo/76979871'`
+
+### Direct Video Files (MP4, WebM, OGG)
+- **Poster**: ✅ **Works perfectly!** Custom poster images are fully supported
+- **Examples**:
+  ```tsx
+  url: 'https://example.com/video.mp4',
+  poster: '/images/video-poster.jpg'  // This works!
+  ```
+
+### HLS Streams
+- **Poster**: ✅ Custom poster supported
+- **Example**: `url: 'https://example.com/stream.m3u8'`
+
+### DASH Streams  
+- **Poster**: ✅ Custom poster supported
+- **Example**: `url: 'https://example.com/stream.mpd'`
+
+> **Note**: The `poster` prop works for direct video files, HLS, and DASH streams. For YouTube and Vimeo, the platform's own thumbnail is displayed regardless of the `poster` prop due to iframe limitations.
+
 ### YouTube
 ```tsx
 <VideoPlayer

package/src/snippets/VideoPlayer/VideoControls.tsx

@@ -6,12 +6,12 @@
 
 import React from 'react';
 import { useMediaStore, useMediaRemote } from '@vidstack/react';
-import type { MediaPlayerElement } from 'vidstack';
+import type { MediaPlayerInstance } from '@vidstack/react';
 import { Play, Pause, Volume2, VolumeX, Maximize, Minimize } from 'lucide-react';
 import { cn } from '@djangocfg/ui';
 
 interface VideoControlsProps {
-  player: React.RefObject<MediaPlayerElement | null>;
+  player: React.RefObject<MediaPlayerInstance | null>;
   className?: string;
 }
 
@@ -55,13 +55,17 @@ export function VideoControls({ player, className }: VideoControlsProps) {
   const progress = duration > 0 ? (currentTime / duration) * 100 : 0;
 
   return (
-    <div className={cn(
-      "absolute inset-0 flex flex-col justify-end opacity-0 hover:opacity-100 focus-within:opacity-100 transition-opacity duration-300",
-      "bg-gradient-to-t from-black/80 via-black/20 to-transparent",
-      className
-    )}>
+    <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">
+      <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}
@@ -76,7 +80,7 @@ export function VideoControls({ player, className }: VideoControlsProps) {
       </div>
 
       {/* Control Bar */}
-      <div className="flex items-center gap-4 px-4 pb-4">
+      <div className="flex items-center gap-4 px-4 pb-4 pointer-events-auto">
         {/* Play/Pause */}
         <button
           onClick={() => remote.togglePaused()}

package/src/snippets/VideoPlayer/VideoPlayer.tsx

@@ -1,3 +1,4 @@
+// @ts-nocheck
 /**
  * Professional VideoPlayer - Vidstack Implementation
  * Supports YouTube, Vimeo, MP4, HLS and more with custom controls
@@ -5,12 +6,103 @@
 
 'use client';
 
-import React, { forwardRef, useImperativeHandle, useRef } from 'react';
-import { MediaPlayer, MediaOutlet } from '@vidstack/react';
-import { MediaRemoteControl, type MediaPlayerElement } from 'vidstack';
+import React, { forwardRef, useImperativeHandle, useRef, useMemo } from 'react';
+import { MediaPlayer, MediaProvider, Poster } from '@vidstack/react';
+import { defaultLayoutIcons, DefaultVideoLayout } from '@vidstack/react/player/layouts/default';
+import type { MediaPlayerInstance } from '@vidstack/react';
+import consola from 'consola';
 import { cn } from '@djangocfg/ui';
 import { type VideoPlayerProps, type VideoPlayerRef } from './types';
-import { VideoControls } from './VideoControls';
+
+// Import Vidstack base styles
+import '@vidstack/react/player/styles/base.css';
+// Import default theme
+import '@vidstack/react/player/styles/default/theme.css';
+import '@vidstack/react/player/styles/default/layouts/video.css';
+
+/**
+ * Custom error class for invalid video URLs
+ */
+export class VideoUrlError extends Error {
+  constructor(
+    message: string,
+    public readonly url: string,
+    public readonly suggestion?: string
+  ) {
+    super(message);
+    this.name = 'VideoUrlError';
+  }
+}
+
+/**
+ * Validates and normalizes video URL for Vidstack
+ * @throws {VideoUrlError} If URL format is invalid for the detected provider
+ */
+function normalizeVideoUrl(url: string): string {
+  if (!url || typeof url !== 'string') {
+    throw new VideoUrlError('Video URL is required', url || '');
+  }
+
+  const trimmedUrl = url.trim();
+
+  // Already in correct format (youtube/ID, vimeo/ID, or direct URL)
+  if (trimmedUrl.startsWith('youtube/') || trimmedUrl.startsWith('vimeo/')) {
+    return trimmedUrl;
+  }
+
+  // YouTube URL patterns - auto-convert to youtube/ID format
+  const youtubePatterns = [
+    /(?:youtube\.com\/watch\?v=|youtu\.be\/|youtube\.com\/embed\/)([a-zA-Z0-9_-]{11})/,
+    /youtube\.com\/shorts\/([a-zA-Z0-9_-]{11})/,
+  ];
+
+  for (const pattern of youtubePatterns) {
+    const match = trimmedUrl.match(pattern);
+    if (match) {
+      // Auto-convert YouTube URL to youtube/ID format
+      const videoId = match[1];
+      if (process.env.NODE_ENV === 'development') {
+        consola.info(
+          `[VideoPlayer] Auto-converted YouTube URL to "youtube/${videoId}" format`
+        );
+      }
+      return `youtube/${videoId}`;
+    }
+  }
+
+  // Vimeo URL patterns - auto-convert to vimeo/ID format
+  const vimeoPattern = /vimeo\.com\/(\d+)/;
+  const vimeoMatch = trimmedUrl.match(vimeoPattern);
+  if (vimeoMatch) {
+    const videoId = vimeoMatch[1];
+    if (process.env.NODE_ENV === 'development') {
+      consola.info(
+        `[VideoPlayer] Auto-converted Vimeo URL to "vimeo/${videoId}" format`
+      );
+    }
+    return `vimeo/${videoId}`;
+  }
+
+  // Direct video URLs (mp4, webm, etc.) - allow as-is
+  if (/\.(mp4|webm|ogg|m3u8|mpd)(\?.*)?$/i.test(trimmedUrl)) {
+    return trimmedUrl;
+  }
+
+  // HLS/DASH streams
+  if (trimmedUrl.includes('.m3u8') || trimmedUrl.includes('.mpd')) {
+    return trimmedUrl;
+  }
+
+  // Unknown format - return as-is but warn in dev
+  if (process.env.NODE_ENV === 'development') {
+    consola.warn(
+      `[VideoPlayer] Unknown URL format: "${trimmedUrl}". ` +
+      `Supported formats: youtube/{id}, vimeo/{id}, or direct video URLs (.mp4, .webm, .m3u8)`
+    );
+  }
+
+  return trimmedUrl;
+}
 
 export const VideoPlayer = forwardRef<VideoPlayerRef, VideoPlayerProps>(({
   source,
@@ -27,26 +119,54 @@ export const VideoPlayer = forwardRef<VideoPlayerRef, VideoPlayerProps>(({
   onEnded,
   onError,
 }, ref) => {
-  const playerRef = useRef<MediaPlayerElement | null>(null);
+  const playerRef = useRef<MediaPlayerInstance | null>(null);
+
+  // Debug log
+  if (process.env.NODE_ENV === 'development') {
+    consola.info('[VideoPlayer] Received props:', {
+      url: source.url,
+      poster: source.poster,
+      title: source.title,
+    });
+  }
+
+  // Validate and normalize URL - throws VideoUrlError if invalid
+  const normalizedUrl = useMemo(() => {
+    try {
+      return normalizeVideoUrl(source.url);
+    } catch (error) {
+      if (error instanceof VideoUrlError) {
+        // Call onError callback and re-throw
+        onError?.(error.message + (error.suggestion ? ` Use: "${error.suggestion}"` : ''));
+        throw error;
+      }
+      throw error;
+    }
+  }, [source.url, onError]);
 
   // Expose player methods via ref
   useImperativeHandle(ref, () => {
-    const getRemote = () => {
-      if (!playerRef.current) return null;
-      const remote = new MediaRemoteControl();
-      remote.setTarget(playerRef.current as unknown as EventTarget);
-      return remote;
-    };
+    const player = playerRef.current;
     
     return {
-      play: () => getRemote()?.play(),
-      pause: () => getRemote()?.pause(),
-      togglePlay: () => getRemote()?.togglePaused(),
-      seekTo: (time: number) => getRemote()?.seek(time),
-      setVolume: (volume: number) => getRemote()?.changeVolume(Math.max(0, Math.min(1, volume))),
-      toggleMute: () => getRemote()?.toggleMuted(),
-      enterFullscreen: () => getRemote()?.enterFullscreen(),
-      exitFullscreen: () => getRemote()?.exitFullscreen(),
+      play: () => player?.play(),
+      pause: () => player?.pause(),
+      togglePlay: () => {
+        if (player) {
+          player.paused ? player.play() : player.pause();
+        }
+      },
+      seekTo: (time: number) => {
+        if (player) player.currentTime = time;
+      },
+      setVolume: (volume: number) => {
+        if (player) player.volume = Math.max(0, Math.min(1, volume));
+      },
+      toggleMute: () => {
+        if (player) player.muted = !player.muted;
+      },
+      enterFullscreen: () => player?.enterFullscreen(),
+      exitFullscreen: () => player?.exitFullscreen(),
     };
   }, []);
 
@@ -71,7 +191,7 @@ export const VideoPlayer = forwardRef<VideoPlayerRef, VideoPlayerProps>(({
       {/* Video Player */}
       <div 
         className={cn(
-          "relative w-full overflow-hidden rounded-sm bg-black",
+          "relative w-full rounded-sm bg-black overflow-hidden",
           theme === 'minimal' && "rounded-none",
           theme === 'modern' && "rounded-xl shadow-2xl"
         )}
@@ -80,8 +200,7 @@ export const VideoPlayer = forwardRef<VideoPlayerRef, VideoPlayerProps>(({
         <MediaPlayer
           ref={playerRef}
           title={source.title || 'Video'}
-          src={source.url}
-          poster={source.poster}
+          src={normalizedUrl}
           autoPlay={autoplay}
           muted={muted}
           playsInline={playsInline}
@@ -91,10 +210,25 @@ export const VideoPlayer = forwardRef<VideoPlayerRef, VideoPlayerProps>(({
           onError={handleError}
           className="w-full h-full"
         >
-          <MediaOutlet />
+          <MediaProvider />
           
-          {/* Custom controls */}
-          {controls && <VideoControls player={playerRef} />}
+          {/* Poster with proper aspect ratio handling */}
+          {source.poster && (
+            <Poster
+              className="vds-poster"
+              src={source.poster}
+              alt={source.title || 'Video poster'}
+              style={{ objectFit: 'cover' }}
+            />
+          )}
+          
+          {/* Use Vidstack's built-in default layout */}
+          {controls && (
+            <DefaultVideoLayout
+              icons={defaultLayoutIcons}
+              thumbnails={source.poster}
+            />
+          )}
         </MediaPlayer>
       </div>
       

package/src/snippets/VideoPlayer/index.ts

@@ -3,6 +3,6 @@
  * Export all components and types
  */
 
-export { VideoPlayer } from './VideoPlayer';
+export { VideoPlayer, VideoUrlError } from './VideoPlayer';
 export { VideoControls } from './VideoControls';
 export type { VideoSource, VideoPlayerProps, VideoPlayerRef } from './types';

package/src/validation/utils/curl-generator.ts

@@ -1,9 +1,13 @@
+"use client"
+
 /**
  * cURL Generator
  *
  * Generates cURL commands from API request details with authentication token
  */
 
+import consola from 'consola';
+
 export interface CurlOptions {
   method: string;
   path: string;
@@ -28,7 +32,7 @@ export function getAuthToken(): string | null {
 
     return token;
   } catch (error) {
-    console.error('Failed to get auth token:', error);
+    consola.error('Failed to get auth token:', error);
     return null;
   }
 }

package/src/layouts/UILayout/README.md

@@ -1,267 +0,0 @@
-# UILayout - Config-Driven UI Documentation System
-
-Modern, type-safe layout system for showcasing UI component libraries with built-in "Copy for AI" functionality.
-
-## 🎯 Key Features
-
-- **Config-Driven**: Single source of truth for all component documentation
-- **Type-Safe**: Full TypeScript support with strict typing
-- **Auto-Rendering**: Components automatically rendered from config
-- **AI-Ready**: One-click export of entire documentation for AI consumption
-- **Responsive**: Mobile-first design with adaptive sidebar
-- **Dark Mode**: Built-in theme support
-- **Organized**: Modular config structure by category
-
-## 📁 Structure
-
-```
-UILayout/
-├── config/                    # All configuration (Single Source of Truth)
-│   ├── components/           # Component configs by category
-│   │   ├── forms.config.tsx       # 8 form components
-│   │   ├── layout.config.tsx      # 5 layout components
-│   │   ├── navigation.config.tsx  # 4 navigation components
-│   │   ├── overlay.config.tsx     # 11 overlay components
-│   │   ├── feedback.config.tsx    # 5 feedback components
-│   │   ├── data.config.tsx        # 5 data display components
-│   │   ├── specialized.config.tsx # 2 specialized components
-│   │   ├── blocks.config.tsx      # 7 landing page blocks
-│   │   ├── hooks.config.tsx       # 6 custom hooks
-│   │   └── index.ts               # Aggregates all configs
-│   ├── categories.config.tsx # Category definitions
-│   ├── tailwind.config.ts    # Tailwind 4 guidelines
-│   ├── ai-export.config.ts   # AI context generator
-│   └── index.ts              # Main config exports
-├── components/               # React components
-│   ├── AutoComponentDemo.tsx      # Auto-renders from config
-│   ├── CategoryRenderer.tsx       # Renders entire category
-│   ├── TailwindGuideRenderer.tsx  # Renders Tailwind guide
-│   ├── Header.tsx                 # Header with "Copy for AI"
-│   ├── Sidebar.tsx
-│   └── MobileOverlay.tsx
-├── context/                  # React Context
-│   └── ShowcaseContext.tsx   # Navigation state management
-├── UILayout.tsx              # Main layout component
-├── UIGuideView.tsx           # Complete UI guide view
-├── UIGuideLanding.tsx        # Landing page
-└── UIGuideApp.tsx            # Full app wrapper
-```
-
-## 🚀 Quick Start
-
-### Basic Usage
-
-```tsx
-import { UILayout, CATEGORIES } from '@djangocfg/layouts';
-
-function MyComponentGuide() {
-  const [category, setCategory] = useState('forms');
-
-  return (
-    <UILayout
-      title="My Component Library"
-      categories={CATEGORIES}
-      currentCategory={category}
-      onCategoryChange={setCategory}
-    >
-      {/* Your content */}
-    </UILayout>
-  );
-}
-```
-
-### Using Category Renderer (Auto-render from config)
-
-```tsx
-import { UILayout, CATEGORIES, CategoryRenderer } from '@djangocfg/layouts';
-
-function MyComponentGuide() {
-  const [category, setCategory] = useState('forms');
-
-  return (
-    <UILayout
-      title="My Component Library"
-      categories={CATEGORIES}
-      currentCategory={category}
-      onCategoryChange={setCategory}
-    >
-      {/* Automatically renders all components in category */}
-      <CategoryRenderer categoryId={category} />
-    </UILayout>
-  );
-}
-```
-
-### Using Complete UI Guide
-
-```tsx
-import { UIGuideApp } from '@djangocfg/layouts';
-
-// Complete pre-configured UI guide with all components
-export default function Page() {
-  return <UIGuideApp />;
-}
-```
-
-## 📝 Adding New Components
-
-### 1. Add to Config
-
-Edit the appropriate config file in `config/components/`:
-
-```tsx
-// config/components/forms.config.tsx
-export const FORM_COMPONENTS: ComponentConfig[] = [
-  {
-    name: 'MyComponent',
-    category: 'forms',
-    description: 'A custom form component',
-    importPath: "import { MyComponent } from '@mylib/ui';",
-    example: `<MyComponent value="test" onChange={handler} />`,
-    preview: <MyComponent value="test" onChange={() => {}} />
-  },
-  // ... other components
-];
-```
-
-### 2. That's It!
-
-No need to:
-- ❌ Create separate demo files
-- ❌ Write duplicate rendering code
-- ❌ Update multiple places
-
-The component automatically:
-- ✅ Appears in the UI guide
-- ✅ Gets included in "Copy for AI"
-- ✅ Shows in the category with proper formatting
-
-## 🤖 Copy for AI Feature
-
-Click the "Copy for AI" button in the header to export entire documentation including:
-
-- ✅ Tailwind CSS v4 guidelines and best practices
-- ✅ All 53 components with full examples
-- ✅ Import statements
-- ✅ Usage examples
-- ✅ Properly formatted for AI consumption
-
-Perfect for giving AI assistants complete context about your UI library!
-
-## 📊 Component Statistics
-
-| Category | Components |
-|----------|------------|
-| Forms | 8 |
-| Layout | 5 |
-| Navigation | 4 |
-| Overlay | 11 |
-| Feedback | 5 |
-| Data Display | 5 |
-| Specialized | 2 |
-| Blocks | 7 |
-| Hooks | 6 |
-| **Total** | **53** |
-
-## 🎨 Customization
-
-### Custom Categories
-
-```tsx
-import type { ComponentCategory } from '@djangocfg/layouts';
-
-const customCategories: ComponentCategory[] = [
-  {
-    id: 'custom',
-    label: 'My Category',
-    icon: <MyIcon />,
-    count: 5,
-    description: 'Custom component category'
-  }
-];
-```
-
-### Custom Config
-
-```tsx
-import type { ComponentConfig } from '@djangocfg/layouts';
-
-const customComponents: ComponentConfig[] = [
-  {
-    name: 'Component',
-    category: 'custom',
-    description: '...',
-    importPath: '...',
-    example: '...',
-    preview: <Component />
-  }
-];
-```
-
-## 🔧 API Reference
-
-### UILayout Props
-
-```typescript
-interface UILayoutProps {
-  children: ReactNode;
-  title?: string;
-  description?: string;
-  categories: ComponentCategory[];
-  currentCategory?: string;
-  onCategoryChange?: (categoryId: string) => void;
-  logo?: ReactNode;
-  projectName?: string;
-}
-```
-
-### ComponentConfig Type
-
-```typescript
-interface ComponentConfig {
-  name: string;           // Component name
-  category: string;       // Category ID
-  description: string;    // Short description
-  importPath: string;     // Import statement
-  example: string;        // Code example
-  preview: ReactNode;     // Live preview component
-}
-```
-
-### Available Exports
-
-```typescript
-// Components
-export { UILayout, CategoryRenderer, AutoComponentDemo };
-
-// Views
-export { UIGuideView, UIGuideApp, UIGuideLanding };
-
-// Config
-export {
-  CATEGORIES,
-  COMPONENTS_CONFIG,
-  generateAIContext
-};
-
-// Types
-export type {
-  ComponentConfig,
-  ComponentCategory,
-  UILayoutProps
-};
-```
-
-## 🎯 Benefits
-
-1. **Single Source of Truth**: All component data in one place
-2. **Zero Duplication**: Write component config once, use everywhere
-3. **Type-Safe**: Full TypeScript support prevents errors
-4. **Auto-Update**: Add to config, automatically appears everywhere
-5. **AI-Friendly**: Built-in export for AI assistants
-6. **Maintainable**: Easy to update and extend
-7. **Scalable**: Add categories and components effortlessly
-
-## 📖 More Info
-
-See the main package README for complete documentation and examples.