@djangocfg/ui-nextjs 2.1.77 → 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.77",
+  "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.77",
-    "@djangocfg/ui-core": "^2.1.77",
+    "@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.77",
+    "@djangocfg/typescript-config": "^2.1.79",
     "@types/node": "^24.7.2",
     "eslint": "^9.37.0",
     "tailwindcss-animate": "1.0.7",

package/src/lib/index.ts

@@ -1,2 +1,5 @@
 // Re-export from ui-core
-export * from '@djangocfg/ui-core/lib';
+export * from '@djangocfg/ui-core/lib';
+
+// Logger (consola + zustand for Console panel)
+export * from './logger';

package/src/lib/logger/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Universal Logger
+ *
+ * Combines console logging with zustand store for Console panel.
+ * Use createMediaLogger for media tools (AudioPlayer, VideoPlayer, ImageViewer).
+ */
+
+export { createLogger, createMediaLogger, logger, log } from './logger';
+export { useLogStore, useFilteredLogs, useLogCount, useErrorCount } from './logStore';
+export type { LogEntry, LogLevel, LogFilter, LogStore, Logger, MediaLogger } from './types';

package/src/lib/logger/logStore.ts

@@ -0,0 +1,122 @@
+/**
+ * Log Store
+ *
+ * Zustand store for log accumulation and filtering.
+ * Keeps logs in memory for Console panel display.
+ */
+
+'use client';
+
+import { create } from 'zustand';
+import type { LogStore, LogEntry, LogFilter } from './types';
+
+const DEFAULT_FILTER: LogFilter = {
+  levels: ['debug', 'info', 'warn', 'error', 'success'],
+  component: undefined,
+  search: undefined,
+  since: undefined,
+};
+
+const MAX_LOGS = 1000;
+
+function generateId(): string {
+  return `log-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+
+function matchesFilter(entry: LogEntry, filter: LogFilter): boolean {
+  // Level filter
+  if (!filter.levels.includes(entry.level)) {
+    return false;
+  }
+
+  // Component filter (case-insensitive partial match)
+  if (filter.component) {
+    const comp = filter.component.toLowerCase();
+    if (!entry.component.toLowerCase().includes(comp)) {
+      return false;
+    }
+  }
+
+  // Search filter (case-insensitive, searches message and data)
+  if (filter.search) {
+    const search = filter.search.toLowerCase();
+    const inMessage = entry.message.toLowerCase().includes(search);
+    const inData = entry.data
+      ? JSON.stringify(entry.data).toLowerCase().includes(search)
+      : false;
+    if (!inMessage && !inData) {
+      return false;
+    }
+  }
+
+  // Time filter
+  if (filter.since && entry.timestamp < filter.since) {
+    return false;
+  }
+
+  return true;
+}
+
+export const useLogStore = create<LogStore>((set, get) => ({
+  logs: [],
+  filter: DEFAULT_FILTER,
+  maxLogs: MAX_LOGS,
+
+  addLog: (entry) => {
+    const newEntry: LogEntry = {
+      ...entry,
+      id: generateId(),
+      timestamp: new Date(),
+    };
+
+    set((state) => {
+      const newLogs = [...state.logs, newEntry];
+      // Trim to max size
+      if (newLogs.length > state.maxLogs) {
+        return { logs: newLogs.slice(-state.maxLogs) };
+      }
+      return { logs: newLogs };
+    });
+  },
+
+  clearLogs: () => {
+    set({ logs: [] });
+  },
+
+  setFilter: (filter) => {
+    set((state) => ({
+      filter: { ...state.filter, ...filter },
+    }));
+  },
+
+  resetFilter: () => {
+    set({ filter: DEFAULT_FILTER });
+  },
+
+  getFilteredLogs: () => {
+    const { logs, filter } = get();
+    return logs.filter((entry) => matchesFilter(entry, filter));
+  },
+
+  exportLogs: () => {
+    const { logs } = get();
+    return JSON.stringify(logs, null, 2);
+  },
+}));
+
+// Selector hooks for performance
+export const useFilteredLogs = () => {
+  const logs = useLogStore((state) => state.logs);
+  const filter = useLogStore((state) => state.filter);
+  return logs.filter((entry) => matchesFilter(entry, filter));
+};
+
+export const useLogCount = () => {
+  return useLogStore((state) => state.logs.length);
+};
+
+export const useErrorCount = () => {
+  return useLogStore((state) =>
+    state.logs.filter((log) => log.level === 'error').length
+  );
+};

package/src/lib/logger/logger.ts

@@ -0,0 +1,175 @@
+/**
+ * Logger
+ *
+ * Universal logger with consola + zustand store integration.
+ * Logs are accumulated for Console panel display.
+ * In production, only logs to store (no console output).
+ */
+
+'use client';
+
+import { consola, type ConsolaInstance } from 'consola';
+import { useLogStore } from './logStore';
+import type { Logger, LogLevel, MediaLogger } from './types';
+
+// Check environment
+const isDev = process.env.NODE_ENV !== 'production';
+const isBrowser = typeof window !== 'undefined';
+
+// Create base consola instance
+const baseConsola = consola.create({
+  level: isDev ? 4 : 2, // 4 = debug, 2 = warn
+});
+
+/**
+ * Extract error details from unknown error type
+ */
+function extractErrorData(data?: Record<string, unknown>): {
+  cleanData: Record<string, unknown> | undefined;
+  stack: string | undefined;
+} {
+  if (!data) return { cleanData: undefined, stack: undefined };
+
+  const cleanData = { ...data };
+  let stack: string | undefined;
+
+  // Extract stack from error object
+  if (data.error instanceof Error) {
+    stack = data.error.stack;
+    cleanData.error = {
+      name: data.error.name,
+      message: data.error.message,
+    };
+  } else if (typeof data.error === 'object' && data.error !== null) {
+    const errObj = data.error as Record<string, unknown>;
+    if (typeof errObj.stack === 'string') {
+      stack = errObj.stack;
+    }
+    if (typeof errObj.message === 'string') {
+      cleanData.error = errObj.message;
+    }
+  }
+
+  return { cleanData, stack };
+}
+
+/**
+ * Format buffer ranges for logging
+ */
+function formatBufferRanges(buffered: TimeRanges, duration: number): string {
+  if (buffered.length === 0) return 'empty';
+
+  const ranges: string[] = [];
+  for (let i = 0; i < buffered.length; i++) {
+    const start = buffered.start(i);
+    const end = buffered.end(i);
+    const percent = ((end - start) / duration * 100).toFixed(1);
+    ranges.push(`${start.toFixed(1)}-${end.toFixed(1)}s (${percent}%)`);
+  }
+  return ranges.join(', ');
+}
+
+/**
+ * Create a logger for a specific component/module
+ */
+export function createLogger(component: string): Logger {
+  const consolaTagged = baseConsola.withTag(component);
+
+  const log = (level: LogLevel, message: string, data?: Record<string, unknown>) => {
+    const { cleanData, stack } = extractErrorData(data);
+
+    // Add to store (for Console panel)
+    if (isBrowser) {
+      useLogStore.getState().addLog({
+        level,
+        component,
+        message,
+        data: cleanData,
+        stack,
+      });
+    }
+
+    // Log to console via consola (in dev mode)
+    if (isDev) {
+      const consolaMethod = level === 'success' ? 'success' : level;
+      if (cleanData) {
+        consolaTagged[consolaMethod](message, cleanData);
+      } else {
+        consolaTagged[consolaMethod](message);
+      }
+    }
+  };
+
+  return {
+    debug: (message, data) => log('debug', message, data),
+    info: (message, data) => log('info', message, data),
+    warn: (message, data) => log('warn', message, data),
+    error: (message, data) => log('error', message, data),
+    success: (message, data) => log('success', message, data),
+  };
+}
+
+/**
+ * Create a media-specific logger with helper methods
+ * for AudioPlayer, VideoPlayer, ImageViewer
+ */
+export function createMediaLogger(component: string): MediaLogger {
+  const baseLogger = createLogger(component);
+
+  return {
+    ...baseLogger,
+
+    load: (src: string, type?: string) => {
+      const typeStr = type ? ` (${type})` : '';
+      baseLogger.info(`LOAD: ${src}${typeStr}`);
+    },
+
+    state: (state: string, details?: Record<string, unknown>) => {
+      baseLogger.debug(`STATE: ${state}`, details);
+    },
+
+    seek: (from: number, to: number, duration: number) => {
+      baseLogger.debug(`SEEK: ${from.toFixed(2)}s -> ${to.toFixed(2)}s`, {
+        from,
+        to,
+        duration,
+        progress: `${((to / duration) * 100).toFixed(1)}%`,
+      });
+    },
+
+    buffer: (buffered: TimeRanges, duration: number) => {
+      if (buffered.length > 0) {
+        baseLogger.debug(`BUFFER: ${formatBufferRanges(buffered, duration)}`);
+      }
+    },
+
+    event: (name: string, data?: unknown) => {
+      if (data !== undefined) {
+        baseLogger.debug(`EVENT: ${name}`, { data });
+      } else {
+        baseLogger.debug(`EVENT: ${name}`);
+      }
+    },
+  };
+}
+
+/**
+ * Global logger for non-component code
+ */
+export const logger = createLogger('App');
+
+/**
+ * Quick access for one-off logs
+ */
+export const log = {
+  debug: (component: string, message: string, data?: Record<string, unknown>) =>
+    createLogger(component).debug(message, data),
+  info: (component: string, message: string, data?: Record<string, unknown>) =>
+    createLogger(component).info(message, data),
+  warn: (component: string, message: string, data?: Record<string, unknown>) =>
+    createLogger(component).warn(message, data),
+  error: (component: string, message: string, data?: Record<string, unknown>) =>
+    createLogger(component).error(message, data),
+  success: (component: string, message: string, data?: Record<string, unknown>) =>
+    createLogger(component).success(message, data),
+};

package/src/lib/logger/types.ts

@@ -0,0 +1,82 @@
+/**
+ * Logger Types
+ *
+ * Type definitions for the universal logging system.
+ * Compatible with Console panel in FileWorkspace IDE layout.
+ */
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'success';
+
+export interface LogEntry {
+  /** Unique log ID */
+  id: string;
+  /** Timestamp when log was created */
+  timestamp: Date;
+  /** Log level */
+  level: LogLevel;
+  /** Component/module name that created the log */
+  component: string;
+  /** Log message */
+  message: string;
+  /** Additional data (objects, errors, etc.) */
+  data?: Record<string, unknown>;
+  /** Error stack trace (for error level) */
+  stack?: string;
+}
+
+export interface LogFilter {
+  /** Filter by log levels */
+  levels: LogLevel[];
+  /** Filter by component name (partial match) */
+  component?: string;
+  /** Filter by message text (partial match) */
+  search?: string;
+  /** Filter by time range */
+  since?: Date;
+}
+
+export interface LogStore {
+  /** All accumulated logs */
+  logs: LogEntry[];
+  /** Current filter settings */
+  filter: LogFilter;
+  /** Maximum logs to keep */
+  maxLogs: number;
+
+  /** Add new log entry */
+  addLog: (entry: Omit<LogEntry, 'id' | 'timestamp'>) => void;
+  /** Clear all logs */
+  clearLogs: () => void;
+  /** Update filter settings */
+  setFilter: (filter: Partial<LogFilter>) => void;
+  /** Reset filter to defaults */
+  resetFilter: () => void;
+  /** Get filtered logs */
+  getFilteredLogs: () => LogEntry[];
+  /** Export logs as JSON string */
+  exportLogs: () => string;
+}
+
+export interface Logger {
+  debug: (message: string, data?: Record<string, unknown>) => void;
+  info: (message: string, data?: Record<string, unknown>) => void;
+  warn: (message: string, data?: Record<string, unknown>) => void;
+  error: (message: string, data?: Record<string, unknown>) => void;
+  success: (message: string, data?: Record<string, unknown>) => void;
+}
+
+/**
+ * Media-specific log helper methods
+ */
+export interface MediaLogger extends Logger {
+  /** Log source load event */
+  load: (src: string, type?: string) => void;
+  /** Log state change */
+  state: (state: string, details?: Record<string, unknown>) => void;
+  /** Log seek event */
+  seek: (from: number, to: number, duration: number) => void;
+  /** Log buffer ranges */
+  buffer: (buffered: TimeRanges, duration: number) => void;
+  /** Log generic event */
+  event: (name: string, data?: unknown) => void;
+}

package/src/stores/mediaCache.ts

@@ -3,6 +3,9 @@
 import { create } from 'zustand';
 import { persist, devtools } from 'zustand/middleware';
 import { useShallow } from 'zustand/react/shallow';
+import { createLogger } from '../lib/logger';
+
+const cacheDebug = createLogger('MediaCache');
 
 // Types
 interface BlobUrlEntry {
@@ -120,6 +123,7 @@ export const useMediaCacheStore = create<MediaCacheStore>()(
           const existing = get().blobUrls.get(key);
           if (existing) {
             // Increment ref count
+            cacheDebug.debug(`Blob URL reused: ${key}`, { refCount: existing.refCount + 1 });
             set(
               (state) => ({
                 blobUrls: new Map(state.blobUrls).set(key, {
@@ -136,6 +140,8 @@ export const useMediaCacheStore = create<MediaCacheStore>()(
           // Create new blob URL
           const blob = new Blob([content], { type: mimeType });
           const url = URL.createObjectURL(blob);
+          const sizeMB = (content.byteLength / 1024 / 1024).toFixed(2);
+          cacheDebug.debug(`Blob URL created: ${key}`, { mimeType, size: `${sizeMB}MB` });
           set(
             (state) => ({
               blobUrls: new Map(state.blobUrls).set(key, {
@@ -156,6 +162,7 @@ export const useMediaCacheStore = create<MediaCacheStore>()(
 
           if (entry.refCount <= 1) {
             // Last reference - revoke and remove
+            cacheDebug.debug(`Blob URL revoked: ${key}`);
             URL.revokeObjectURL(entry.url);
             set(
               (state) => {
@@ -168,6 +175,7 @@ export const useMediaCacheStore = create<MediaCacheStore>()(
             );
           } else {
             // Decrement ref count
+            cacheDebug.debug(`Blob URL released: ${key}`, { refCount: entry.refCount - 1 });
             set(
               (state) => ({
                 blobUrls: new Map(state.blobUrls).set(key, {
@@ -315,6 +323,8 @@ export const useMediaCacheStore = create<MediaCacheStore>()(
         // ========== Global ==========
 
         clearCache: () => {
+          const stats = get().getCacheStats();
+          cacheDebug.info('Clearing cache', stats);
           // Revoke all blob URLs before clearing
           get().blobUrls.forEach(({ url }) => URL.revokeObjectURL(url));
           set(initialState, false, 'clearCache');

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}