@djangocfg/ui-nextjs 2.1.85 → 2.1.87

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-nextjs",
-  "version": "2.1.85",
+  "version": "2.1.87",
   "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.85",
-    "@djangocfg/ui-core": "^2.1.85",
+    "@djangocfg/api": "^2.1.87",
+    "@djangocfg/ui-core": "^2.1.87",
     "@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.85",
+    "@djangocfg/typescript-config": "^2.1.87",
     "@types/node": "^24.7.2",
     "eslint": "^9.37.0",
     "tailwindcss-animate": "1.0.7",

package/src/stores/mediaCache.ts

@@ -32,6 +32,12 @@ interface EffectConfig {
   blur: string;
 }
 
+/** Video player settings (persisted) */
+interface VideoPlayerSettings {
+  volume: number;
+  isLooping: boolean;
+}
+
 // Stream URL TTL (30 seconds - shorter to avoid stale session/token issues)
 const STREAM_URL_TTL = 30 * 1000;
 
@@ -51,6 +57,7 @@ interface MediaCacheState {
   videoPosterUrls: Map<string, string>;
   videoPlaybackPositions: Map<string, number>;
   videoMetadata: Map<string, VideoMetadata>;
+  videoPlayerSettings: VideoPlayerSettings;
 }
 
 interface MediaCacheActions {
@@ -86,6 +93,8 @@ interface MediaCacheActions {
   cacheVideoMetadata: (url: string, meta: VideoMetadata) => void;
   getVideoMetadata: (url: string) => VideoMetadata | null;
   invalidateSession: (sessionId: string) => void;
+  getVideoPlayerSettings: () => VideoPlayerSettings;
+  saveVideoPlayerSettings: (settings: Partial<VideoPlayerSettings>) => void;
 
   // Global
   clearCache: () => void;
@@ -100,6 +109,11 @@ interface MediaCacheActions {
 type MediaCacheStore = MediaCacheState & MediaCacheActions;
 
 // Initial state
+const DEFAULT_VIDEO_SETTINGS: VideoPlayerSettings = {
+  volume: 1,
+  isLooping: false,
+};
+
 const initialState: MediaCacheState = {
   blobUrls: new Map(),
   imageDimensions: new Map(),
@@ -109,6 +123,7 @@ const initialState: MediaCacheState = {
   videoPosterUrls: new Map(),
   videoPlaybackPositions: new Map(),
   videoMetadata: new Map(),
+  videoPlayerSettings: DEFAULT_VIDEO_SETTINGS,
 };
 
 export const useMediaCacheStore = create<MediaCacheStore>()(
@@ -320,6 +335,18 @@ export const useMediaCacheStore = create<MediaCacheStore>()(
           );
         },
 
+        getVideoPlayerSettings: () => get().videoPlayerSettings,
+
+        saveVideoPlayerSettings: (settings) => {
+          set(
+            (state) => ({
+              videoPlayerSettings: { ...state.videoPlayerSettings, ...settings },
+            }),
+            false,
+            'video/savePlayerSettings'
+          );
+        },
+
         // ========== Global ==========
 
         clearCache: () => {
@@ -339,7 +366,7 @@ export const useMediaCacheStore = create<MediaCacheStore>()(
       }),
       {
         name: 'media-cache-storage',
-        // Only persist playback positions and poster URLs
+        // Only persist playback positions, poster URLs, and player settings
         partialize: (state) => ({
           audioPlaybackPositions: Array.from(
             state.audioPlaybackPositions.entries()
@@ -348,6 +375,7 @@ export const useMediaCacheStore = create<MediaCacheStore>()(
             state.videoPlaybackPositions.entries()
           ),
           videoPosterUrls: Array.from(state.videoPosterUrls.entries()),
+          videoPlayerSettings: state.videoPlayerSettings,
         }),
         // Rehydrate Maps from arrays
         onRehydrateStorage: () => (state) => {
@@ -356,6 +384,7 @@ export const useMediaCacheStore = create<MediaCacheStore>()(
             const persistedAudio = state.audioPlaybackPositions as unknown;
             const persistedVideo = state.videoPlaybackPositions as unknown;
             const persistedPosters = state.videoPosterUrls as unknown;
+            const persistedSettings = state.videoPlayerSettings as unknown;
 
             state.audioPlaybackPositions = new Map(
               Array.isArray(persistedAudio)
@@ -372,6 +401,13 @@ export const useMediaCacheStore = create<MediaCacheStore>()(
                 ? (persistedPosters as [string, string][])
                 : []
             );
+            // Merge persisted settings with defaults (handles missing fields)
+            state.videoPlayerSettings = {
+              ...DEFAULT_VIDEO_SETTINGS,
+              ...(persistedSettings && typeof persistedSettings === 'object'
+                ? (persistedSettings as Partial<VideoPlayerSettings>)
+                : {}),
+            };
           }
         },
       }
@@ -432,6 +468,20 @@ export const useVideoCache = () =>
       cacheVideoMetadata: state.cacheVideoMetadata,
       getVideoMetadata: state.getVideoMetadata,
       invalidateSession: state.invalidateSession,
+      getVideoPlayerSettings: state.getVideoPlayerSettings,
+      saveVideoPlayerSettings: state.saveVideoPlayerSettings,
+    }))
+  );
+
+/**
+ * Hook for video player settings only
+ * Returns current settings and save function
+ */
+export const useVideoPlayerSettings = () =>
+  useMediaCacheStore(
+    useShallow((state) => ({
+      settings: state.videoPlayerSettings,
+      saveSettings: state.saveVideoPlayerSettings,
     }))
   );
 

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

@@ -7,7 +7,7 @@
  * Uses native HTML5 audio for playback with Web Audio API for visualization only.
  */
 
-import { createContext, useContext, useMemo, type ReactNode } from 'react';
+import { createContext, useContext, useMemo, useEffect, useRef, type ReactNode } from 'react';
 import {
   useHybridAudio,
   type UseHybridAudioOptions,
@@ -16,6 +16,7 @@ import {
   type HybridWebAudioAPI,
 } from '../hooks/useHybridAudio';
 import { useHybridAudioAnalysis } from '../hooks/useHybridAudioAnalysis';
+import { useVisualization } from '../hooks/useVisualization';
 import type { AudioLevels } from '../effects';
 
 // =============================================================================
@@ -54,7 +55,43 @@ export interface HybridAudioProviderProps extends UseHybridAudioOptions {
 }
 
 export function HybridAudioProvider({ children, ...options }: HybridAudioProviderProps) {
-  const { audioRef, state, controls, webAudio } = useHybridAudio(options);
+  // Load persisted settings (shared with visualization)
+  const { settings: savedSettings, setSetting } = useVisualization();
+
+  // Use saved settings as initial values
+  const effectiveOptions = {
+    ...options,
+    initialVolume: savedSettings.volume,
+    loop: savedSettings.isLooping,
+  };
+
+  const { audioRef, state, controls, webAudio } = useHybridAudio(effectiveOptions);
+
+  // Track if we've applied initial settings
+  const hasAppliedInitialSettings = useRef(false);
+
+  // Apply saved settings after audio is ready (for hydration timing)
+  useEffect(() => {
+    if (!state.isReady || hasAppliedInitialSettings.current) return;
+    hasAppliedInitialSettings.current = true;
+
+    // Apply saved volume and loop settings
+    controls.setVolume(savedSettings.volume);
+    controls.setLoop(savedSettings.isLooping);
+  }, [state.isReady, savedSettings, controls]);
+
+  // Persist settings when they change
+  useEffect(() => {
+    if (!state.isReady) return;
+
+    // Only save if values actually changed
+    if (state.volume !== savedSettings.volume) {
+      setSetting('volume', state.volume);
+    }
+    if (state.isLooping !== savedSettings.isLooping) {
+      setSetting('isLooping', state.isLooping);
+    }
+  }, [state.isReady, state.volume, state.isLooping, savedSettings, setSetting]);
 
   // Audio analysis for reactive effects
   const audioLevels = useHybridAudioAnalysis(webAudio.analyser, state.isPlaying);

package/src/tools/AudioPlayer/hooks/useVisualization.tsx

@@ -27,6 +27,10 @@ export interface VisualizationSettings {
   intensity: VisualizationIntensity;
   /** Color scheme */
   colorScheme: VisualizationColorScheme;
+  /** Playback volume (0-1) */
+  volume: number;
+  /** Loop playback */
+  isLooping: boolean;
 }
 
 export interface UseVisualizationReturn {
@@ -56,13 +60,15 @@ export type UseAudioVisualizationReturn = UseVisualizationReturn;
 // CONSTANTS
 // =============================================================================
 
-const STORAGE_KEY = 'audio-visualization-settings';
+const STORAGE_KEY = 'audio-player-settings';
 
 const DEFAULT_SETTINGS: VisualizationSettings = {
   enabled: true,
   variant: 'spotlight',
   intensity: 'medium',
   colorScheme: 'primary',
+  volume: 1,
+  isLooping: false,
 };
 
 const VARIANTS: VisualizationVariant[] = ['spotlight', 'glow', 'orbs', 'mesh', 'none'];

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

@@ -7,3 +7,6 @@ export type {
   UseVideoPositionCacheOptions,
   UseVideoPositionCacheReturn,
 } from './useVideoPositionCache';
+
+export { useVideoPlayerSettings } from './useVideoPlayerSettings';
+export type { VideoPlayerSettingsReturn } from './useVideoPlayerSettings';

package/src/tools/VideoPlayer/hooks/useVideoPlayerSettings.ts

@@ -0,0 +1,70 @@
+'use client';
+
+/**
+ * useVideoPlayerSettings - Hook for persisted video player settings
+ *
+ * Provides volume and loop settings that persist in localStorage.
+ * Use this hook in video player providers to apply saved settings.
+ *
+ * @example
+ * const { settings, updateVolume, updateLoop } = useVideoPlayerSettings();
+ *
+ * // Apply to video element
+ * videoRef.current.volume = settings.volume;
+ * videoRef.current.loop = settings.isLooping;
+ *
+ * // Save when user changes
+ * const handleVolumeChange = (vol: number) => {
+ *   videoRef.current.volume = vol;
+ *   updateVolume(vol);
+ * };
+ */
+
+import { useCallback } from 'react';
+import { useVideoPlayerSettings as useSettings } from '../../../stores/mediaCache';
+
+export interface VideoPlayerSettingsReturn {
+  /** Current settings */
+  settings: {
+    volume: number;
+    isLooping: boolean;
+  };
+  /** Update volume (0-1) */
+  updateVolume: (volume: number) => void;
+  /** Update loop setting */
+  updateLoop: (isLooping: boolean) => void;
+  /** Update multiple settings at once */
+  updateSettings: (settings: { volume?: number; isLooping?: boolean }) => void;
+}
+
+export function useVideoPlayerSettings(): VideoPlayerSettingsReturn {
+  const { settings, saveSettings } = useSettings();
+
+  const updateVolume = useCallback(
+    (volume: number) => {
+      saveSettings({ volume: Math.max(0, Math.min(1, volume)) });
+    },
+    [saveSettings]
+  );
+
+  const updateLoop = useCallback(
+    (isLooping: boolean) => {
+      saveSettings({ isLooping });
+    },
+    [saveSettings]
+  );
+
+  const updateSettings = useCallback(
+    (newSettings: { volume?: number; isLooping?: boolean }) => {
+      saveSettings(newSettings);
+    },
+    [saveSettings]
+  );
+
+  return {
+    settings,
+    updateVolume,
+    updateLoop,
+    updateSettings,
+  };
+}

package/src/tools/VideoPlayer/providers/NativeProvider.tsx

@@ -9,6 +9,7 @@ import React, { forwardRef, useEffect, useImperativeHandle, useRef, useState } f
 
 import { cn } from '@djangocfg/ui-core/lib';
 import { Preloader, AspectRatio } from '@djangocfg/ui-core';
+import { useVideoPlayerSettings } from '../hooks/useVideoPlayerSettings';
 
 import type { NativeProviderProps, VideoPlayerRef } from '../types';
 import { videoDebug } from '../utils/debug';
@@ -56,6 +57,9 @@ export const NativeProvider = forwardRef<VideoPlayerRef, NativeProviderProps>(
     const [isLoading, setIsLoading] = useState(showPreloader);
     const videoRef = useRef<HTMLVideoElement>(null);
 
+    // Persisted player settings
+    const { settings: savedSettings, updateVolume } = useVideoPlayerSettings();
+
     const videoUrl = getVideoUrl(source);
 
     // Debug: Log video source
@@ -140,6 +144,8 @@ export const NativeProvider = forwardRef<VideoPlayerRef, NativeProviderProps>(
       const handleCanPlayDebug = () => {
         videoDebug.state('canplay', { duration: video.duration, buffered: video.buffered.length });
         videoDebug.buffer(video.buffered, video.duration);
+        // Apply saved volume
+        video.volume = savedSettings.volume;
       };
 
       const handleSeeking = () => {
@@ -176,7 +182,20 @@ export const NativeProvider = forwardRef<VideoPlayerRef, NativeProviderProps>(
         video.removeEventListener('waiting', handleWaiting);
         video.removeEventListener('stalled', handleStalled);
       };
-    }, []);
+    }, [savedSettings.volume]);
+
+    // Persist volume when user changes it via native controls
+    useEffect(() => {
+      const video = videoRef.current;
+      if (!video) return;
+
+      const handleVolumeChange = () => {
+        updateVolume(video.volume);
+      };
+
+      video.addEventListener('volumechange', handleVolumeChange);
+      return () => video.removeEventListener('volumechange', handleVolumeChange);
+    }, [updateVolume]);
 
     const handleContextMenu = (e: React.MouseEvent) => {
       if (disableContextMenu) {

package/src/tools/VideoPlayer/providers/StreamProvider.tsx

@@ -15,6 +15,7 @@ import React, { forwardRef, useCallback, useEffect, useImperativeHandle, useRef,
 import { cn } from '@djangocfg/ui-core/lib';
 import { Preloader, AspectRatio } from '@djangocfg/ui-core';
 import { useMediaCacheStore, generateContentKey } from '../../../stores/mediaCache';
+import { useVideoPlayerSettings } from '../hooks/useVideoPlayerSettings';
 
 import type { StreamProviderProps, VideoPlayerRef, StreamSource, BlobSource, DataUrlSource, ErrorFallbackProps } from '../types';
 import { videoDebug } from '../utils/debug';
@@ -84,6 +85,9 @@ export const StreamProvider = forwardRef<VideoPlayerRef, StreamProviderProps>(
     const saveVideoPosition = useMediaCacheStore.getState().saveVideoPosition;
     const getVideoPosition = useMediaCacheStore.getState().getVideoPosition;
 
+    // Persisted player settings
+    const { settings: savedSettings, updateVolume } = useVideoPlayerSettings();
+
     // Retry function for error fallback
     // Regenerates URL for stream sources to get fresh token/session
     const retry = useCallback(() => {
@@ -233,12 +237,15 @@ export const StreamProvider = forwardRef<VideoPlayerRef, StreamProviderProps>(
       }
     }, [source]);
 
-    // Restore cached playback position when video is ready
+    // Restore cached playback position and settings when video is ready
     const handleCanPlay = useCallback(() => {
       const video = videoRef.current;
       if (video) {
         videoDebug.state('canplay', { duration: video.duration, buffered: video.buffered.length });
         videoDebug.buffer(video.buffered, video.duration);
+
+        // Apply saved volume (user preference)
+        video.volume = savedSettings.volume;
       }
       setIsLoading(false);
 
@@ -258,7 +265,7 @@ export const StreamProvider = forwardRef<VideoPlayerRef, StreamProviderProps>(
 
       onCanPlay?.();
       // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [getSourceKey, onCanPlay]);
+    }, [getSourceKey, onCanPlay, savedSettings.volume]);
 
     // Save playback position periodically
     const handleTimeUpdate = useCallback(() => {
@@ -383,6 +390,19 @@ export const StreamProvider = forwardRef<VideoPlayerRef, StreamProviderProps>(
       };
     }, [videoUrl]);
 
+    // Persist volume when user changes it via native controls
+    useEffect(() => {
+      const video = videoRef.current;
+      if (!video) return;
+
+      const handleVolumeChange = () => {
+        updateVolume(video.volume);
+      };
+
+      video.addEventListener('volumechange', handleVolumeChange);
+      return () => video.removeEventListener('volumechange', handleVolumeChange);
+    }, [videoUrl, updateVolume]);
+
     // Determine if we should use AspectRatio wrapper or fill mode
     const isFillMode = aspectRatio === 'fill';
     const computedAspectRatio = aspectRatio === 'auto' || aspectRatio === 'fill' ? undefined : aspectRatio;