@djangocfg/ui-nextjs 2.1.78 → 2.1.79

package/README.md

@@ -57,11 +57,11 @@ All components from `@djangocfg/ui-core` are re-exported.
 import { Hero } from '@djangocfg/ui-nextjs/blocks';
 ```
 
-### Tools (4)
-`JsonTree` `PrettyCode` `Mermaid` `LottiePlayer`
+### Tools (7)
+`JsonTree` `PrettyCode` `Mermaid` `LottiePlayer` `AudioPlayer` `VideoPlayer` `ImageViewer`
 
 ```tsx
-import { PrettyCode } from '@djangocfg/ui-nextjs/tools';
+import { PrettyCode, AudioPlayer, VideoPlayer } from '@djangocfg/ui-nextjs/tools';
 ```
 
 ## Hooks
@@ -108,6 +108,25 @@ function Example() {
 import '@djangocfg/ui-nextjs/styles/globals';
 ```
 
+## Logger
+
+Universal logger with consola + zustand for Console panel integration.
+
+```tsx
+import { createLogger, createMediaLogger } from '@djangocfg/ui-nextjs/lib';
+
+// Basic logger
+const log = createLogger('MyComponent');
+log.info('User logged in', { userId: 123 });
+log.error('Failed to load', { error });
+
+// Media logger (with seek/buffer helpers)
+const mediaLog = createMediaLogger('AudioPlayer');
+mediaLog.load(src, 'stream');
+mediaLog.seek(from, to, duration);
+mediaLog.buffer(buffered, duration);
+```
+
 ## Exports
 
 | Path | Content |
@@ -116,7 +135,8 @@ import '@djangocfg/ui-nextjs/styles/globals';
 | `@djangocfg/ui-nextjs/components` | Components only |
 | `@djangocfg/ui-nextjs/hooks` | Hooks only |
 | `@djangocfg/ui-nextjs/blocks` | Landing page blocks |
-| `@djangocfg/ui-nextjs/tools` | JsonTree, Mermaid, etc. |
+| `@djangocfg/ui-nextjs/tools` | JsonTree, Mermaid, Media players |
+| `@djangocfg/ui-nextjs/lib` | Logger, utilities |
 | `@djangocfg/ui-nextjs/theme` | ThemeProvider, ThemeToggle |
 | `@djangocfg/ui-nextjs/styles` | CSS |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-nextjs",
-  "version": "2.1.78",
+  "version": "2.1.79",
   "description": "Next.js UI component library with Radix UI primitives, Tailwind CSS styling, charts, and form components",
   "keywords": [
     "ui-components",
@@ -58,8 +58,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.78",
-    "@djangocfg/ui-core": "^2.1.78",
+    "@djangocfg/api": "^2.1.79",
+    "@djangocfg/ui-core": "^2.1.79",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "consola": "^3.4.2",
@@ -110,7 +110,7 @@
     "wavesurfer.js": "^7.12.1"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.78",
+    "@djangocfg/typescript-config": "^2.1.79",
     "@types/node": "^24.7.2",
     "eslint": "^9.37.0",
     "tailwindcss-animate": "1.0.7",

package/src/tools/AudioPlayer/README.md

@@ -46,6 +46,7 @@ import { SimpleAudioPlayer } from '@djangocfg/ui-nextjs';
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `src` | `string` | required | Audio URL |
+| `prefetch` | `boolean` | `true` | Pre-fetch audio as blob (required for streaming URLs to enable seek) |
 | `title` | `string` | - | Track title |
 | `artist` | `string` | - | Artist name |
 | `coverArt` | `string \| ReactNode` | - | Cover image URL or custom element |
@@ -54,6 +55,7 @@ import { SimpleAudioPlayer } from '@djangocfg/ui-nextjs';
 | `showEqualizer` | `boolean` | `false` | Show equalizer bars |
 | `showTimer` | `boolean` | `true` | Show time display |
 | `showVolume` | `boolean` | `true` | Show volume control |
+| `showLoop` | `boolean` | `true` | Show loop/repeat button |
 | `reactiveCover` | `boolean` | `true` | Enable reactive effects |
 | `variant` | `VisualizationVariant` | - | Effect variant |
 | `intensity` | `EffectIntensity` | - | Effect intensity |
@@ -61,6 +63,8 @@ import { SimpleAudioPlayer } from '@djangocfg/ui-nextjs';
 | `autoPlay` | `boolean` | `false` | Auto-play on load |
 | `layout` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction |
 
+> **Note:** The `prefetch` option is enabled by default. This fetches the entire audio file as a blob before loading into WaveSurfer, which is required for seeking to work correctly with streaming URLs. For very large files (> 50MB), consider using `prefetch={false}` and the Progressive player mode instead.
+
 ---
 
 ## Advanced Usage
@@ -99,7 +103,10 @@ Context provider for audio state. Wraps all audio components.
 
 ```tsx
 <AudioProvider
-  source={{ uri: 'https://example.com/audio.mp3' }}
+  source={{
+    uri: 'https://example.com/audio.mp3',
+    prefetch: true  // Fetch as blob for seek support (default: false)
+  }}
   containerRef={containerRef}
   autoPlay={false}
   waveformOptions={{
@@ -115,6 +122,13 @@ Context provider for audio state. Wraps all audio components.
 </AudioProvider>
 ```
 
+#### AudioSource Options
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `uri` | `string` | required | Audio URL |
+| `prefetch` | `boolean` | `false` | Pre-fetch as blob (enables seek for streaming URLs) |
+
 ### AudioPlayer
 
 Main player component with waveform and controls.
@@ -294,6 +308,7 @@ AudioPlayer/
 │   └── effects.ts                 # Visualization effect types
 ├── hooks/
 │   ├── index.ts
+│   ├── useAudioSource.ts          # Audio source loading with prefetch
 │   ├── useAudioHotkeys.ts         # Keyboard shortcuts
 │   ├── useVisualization.tsx       # Visualization settings
 │   ├── useAudioAnalysis.ts        # Web Audio frequency analysis

package/src/tools/AudioPlayer/components/SimpleAudioPlayer.tsx

@@ -53,6 +53,13 @@ export interface SimpleAudioPlayerProps {
   /** Audio source URL */
   src: string;
 
+  /**
+   * Pre-fetch audio as blob before loading into WaveSurfer.
+   * Required for streaming URLs because WaveSurfer needs complete file for seek to work.
+   * @default true
+   */
+  prefetch?: boolean;
+
   /** Track title */
   title?: string;
 
@@ -132,6 +139,7 @@ export function SimpleAudioPlayer(props: SimpleAudioPlayerProps) {
 
 function SimpleAudioPlayerContent({
   src,
+  prefetch = true,
   title,
   artist,
   coverArt,
@@ -190,7 +198,7 @@ function SimpleAudioPlayerContent({
 
   return (
     <AudioProvider
-      source={{ uri: src }}
+      source={{ uri: src, prefetch }}
       containerRef={containerRef}
       autoPlay={autoPlay}
       waveformOptions={waveformOptions}

package/src/tools/AudioPlayer/context/AudioProvider.tsx

@@ -18,7 +18,7 @@ import {
 } from 'react';
 import { useWavesurfer } from '@wavesurfer/react';
 import type { AudioContextState, AudioSource, WaveformOptions } from '../types';
-import { useSharedWebAudio, useAudioAnalysis } from '../hooks';
+import { useSharedWebAudio, useAudioAnalysis, useAudioSource } from '../hooks';
 import { useAudioCache } from '../../../stores/mediaCache';
 import { audioDebug } from '../utils/debug';
 
@@ -61,11 +61,14 @@ export function AudioProvider({
   const { saveAudioPosition, getAudioPosition } = useAudioCache();
   const lastSavedTimeRef = useRef<number>(0);
 
+  // Handle prefetch if enabled (for streaming URLs)
+  const { url: resolvedUrl, isLoading: isPrefetching, progress: prefetchProgress } = useAudioSource(source);
+
   // Memoize WaveSurfer options with theme-aware colors
   const options = useMemo(
     () => ({
       container: containerRef,
-      url: source.uri,
+      url: resolvedUrl || undefined,  // Use prefetched blob URL or original
       // Theme-aware colors using HSL
       waveColor: waveformOptions.waveColor || 'hsl(217 91% 60% / 0.3)',
       progressColor: waveformOptions.progressColor || 'hsl(217 91% 60%)',
@@ -80,7 +83,7 @@ export function AudioProvider({
       hideScrollbar: true,
       autoplay: autoPlay,
     }),
-    [source.uri, autoPlay, waveformOptions, containerRef]
+    [resolvedUrl, autoPlay, waveformOptions, containerRef]
   );
 
   // Use official wavesurfer-react hook
@@ -309,6 +312,10 @@ export function AudioProvider({
       isMuted,
       isLooping,
 
+      // Prefetch state
+      isPrefetching,
+      prefetchProgress,
+
       // Audio analysis
       audioLevels,
 
@@ -336,6 +343,8 @@ export function AudioProvider({
       volume,
       isMuted,
       isLooping,
+      isPrefetching,
+      prefetchProgress,
       audioLevels,
       play,
       pause,

package/src/tools/AudioPlayer/hooks/index.ts

@@ -5,6 +5,8 @@
 // Internal hooks (used by provider)
 export { useSharedWebAudio } from './useSharedWebAudio';
 export { useAudioAnalysis } from './useAudioAnalysis';
+export { useAudioSource } from './useAudioSource';
+export type { UseAudioSourceResult } from './useAudioSource';
 
 // Public hooks
 export { useAudioHotkeys, AUDIO_SHORTCUTS } from './useAudioHotkeys';

package/src/tools/AudioPlayer/hooks/useAudioSource.ts

@@ -0,0 +1,139 @@
+'use client';
+
+/**
+ * useAudioSource - Handles audio source loading with optional prefetch
+ *
+ * For streaming URLs, WaveSurfer needs the complete file to enable seeking.
+ * This hook fetches the URL as blob when prefetch is enabled.
+ */
+
+import { useState, useEffect, useRef } from 'react';
+import type { AudioSource } from '../types';
+import { audioDebug } from '../utils/debug';
+
+export interface UseAudioSourceResult {
+  /** The resolved URL (blob URL if prefetched, original URL otherwise) */
+  url: string | null;
+  /** Whether the source is currently being fetched */
+  isLoading: boolean;
+  /** Error message if fetch failed */
+  error: string | null;
+  /** Progress percentage (0-100) during fetch */
+  progress: number;
+}
+
+export function useAudioSource(source: AudioSource): UseAudioSourceResult {
+  const [url, setUrl] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [progress, setProgress] = useState(0);
+  const blobUrlRef = useRef<string | null>(null);
+
+  useEffect(() => {
+    // Cleanup previous blob URL
+    if (blobUrlRef.current) {
+      URL.revokeObjectURL(blobUrlRef.current);
+      blobUrlRef.current = null;
+    }
+
+    // Reset state
+    setError(null);
+    setProgress(0);
+
+    // No prefetch - use URL directly
+    if (!source.prefetch) {
+      setUrl(source.uri);
+      setIsLoading(false);
+      return;
+    }
+
+    // Prefetch enabled - fetch as blob
+    const abortController = new AbortController();
+    setIsLoading(true);
+
+    const fetchAsBlob = async () => {
+      try {
+        audioDebug.info('Prefetching audio as blob', { uri: source.uri });
+
+        const response = await fetch(source.uri, {
+          signal: abortController.signal,
+        });
+
+        if (!response.ok) {
+          throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+
+        // Get content length for progress tracking
+        const contentLength = response.headers.get('Content-Length');
+        const totalBytes = contentLength ? parseInt(contentLength, 10) : 0;
+
+        if (!response.body) {
+          // Fallback for browsers without ReadableStream
+          const blob = await response.blob();
+          const blobUrl = URL.createObjectURL(blob);
+          blobUrlRef.current = blobUrl;
+          setUrl(blobUrl);
+          setProgress(100);
+          audioDebug.success('Audio prefetched (no stream)', { size: blob.size });
+          return;
+        }
+
+        // Stream the response for progress tracking
+        const reader = response.body.getReader();
+        const chunks: ArrayBuffer[] = [];
+        let receivedBytes = 0;
+
+        while (true) {
+          const { done, value } = await reader.read();
+
+          if (done) break;
+
+          // Convert Uint8Array to ArrayBuffer for Blob compatibility
+          chunks.push(value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength));
+          receivedBytes += value.length;
+
+          if (totalBytes > 0) {
+            setProgress(Math.round((receivedBytes / totalBytes) * 100));
+          }
+        }
+
+        // Combine chunks into blob
+        const blob = new Blob(chunks, { type: 'audio/mpeg' });
+        const blobUrl = URL.createObjectURL(blob);
+        blobUrlRef.current = blobUrl;
+        setUrl(blobUrl);
+        setProgress(100);
+
+        audioDebug.success('Audio prefetched', {
+          size: blob.size,
+          sizeFormatted: `${(blob.size / 1024 / 1024).toFixed(2)} MB`,
+        });
+      } catch (err) {
+        if (err instanceof Error && err.name === 'AbortError') {
+          return; // Ignore abort errors
+        }
+
+        const errorMessage = err instanceof Error ? err.message : 'Failed to prefetch audio';
+        audioDebug.error('Failed to prefetch audio', { error: errorMessage, uri: source.uri });
+        setError(errorMessage);
+
+        // Fallback to direct URL (may have seek issues)
+        setUrl(source.uri);
+      } finally {
+        setIsLoading(false);
+      }
+    };
+
+    fetchAsBlob();
+
+    return () => {
+      abortController.abort();
+      if (blobUrlRef.current) {
+        URL.revokeObjectURL(blobUrlRef.current);
+        blobUrlRef.current = null;
+      }
+    };
+  }, [source.uri, source.prefetch]);
+
+  return { url, isLoading, error, progress };
+}

package/src/tools/AudioPlayer/types/audio.ts

@@ -10,7 +10,15 @@ import type { AudioLevels } from './effects';
 // =============================================================================
 
 export interface AudioSource {
+  /** Audio URL (streaming or direct) */
   uri: string;
+  /**
+   * Pre-fetch the URL as blob before passing to WaveSurfer.
+   * Required for streaming URLs because WaveSurfer needs complete file for seek to work.
+   * When true, the URL will be fetched and converted to blob URL.
+   * @default false
+   */
+  prefetch?: boolean;
 }
 
 // =============================================================================
@@ -89,6 +97,12 @@ export interface AudioContextState {
   isMuted: boolean;
   isLooping: boolean;
 
+  // Prefetch state (for streaming URLs)
+  /** Whether audio is being prefetched as blob */
+  isPrefetching: boolean;
+  /** Prefetch progress (0-100) */
+  prefetchProgress: number;
+
   // Audio analysis (for reactive effects)
   audioLevels: AudioLevels;