@djangocfg/ui-nextjs 2.1.65 → 2.1.67

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

@@ -0,0 +1,106 @@
+'use client';
+
+/**
+ * useSharedWebAudio - Manages a shared Web Audio context and source node.
+ *
+ * This prevents the "InvalidStateError" from creating multiple MediaElementSourceNodes
+ * for the same audio element. All analyzers share the same source.
+ */
+
+import { useRef, useEffect, useCallback } from 'react';
+import type { SharedWebAudioContext } from '../types';
+
+export function useSharedWebAudio(audioElement: HTMLMediaElement | null): SharedWebAudioContext {
+  const audioContextRef = useRef<AudioContext | null>(null);
+  const sourceRef = useRef<MediaElementAudioSourceNode | null>(null);
+  const connectedElementRef = useRef<HTMLMediaElement | null>(null);
+  const analyserNodesRef = useRef<Set<AnalyserNode>>(new Set());
+
+  // Initialize Web Audio on first play
+  useEffect(() => {
+    if (!audioElement) return;
+
+    // Already connected to this element
+    if (connectedElementRef.current === audioElement && audioContextRef.current) {
+      return;
+    }
+
+    const initAudio = () => {
+      try {
+        if (!audioContextRef.current) {
+          const AudioContextClass = window.AudioContext ||
+            (window as unknown as { webkitAudioContext: typeof AudioContext }).webkitAudioContext;
+          audioContextRef.current = new AudioContextClass();
+        }
+
+        const audioContext = audioContextRef.current;
+
+        // Only create source node once per audio element
+        if (connectedElementRef.current !== audioElement) {
+          if (sourceRef.current) {
+            try { sourceRef.current.disconnect(); } catch { /* ignore */ }
+          }
+
+          sourceRef.current = audioContext.createMediaElementSource(audioElement);
+          // Connect directly to destination (analysers will be inserted in between)
+          sourceRef.current.connect(audioContext.destination);
+          connectedElementRef.current = audioElement;
+        }
+      } catch (error) {
+        console.warn('[SharedWebAudio] Could not initialize:', error);
+      }
+    };
+
+    const handlePlay = () => {
+      initAudio();
+      if (audioContextRef.current?.state === 'suspended') {
+        audioContextRef.current.resume();
+      }
+    };
+
+    audioElement.addEventListener('play', handlePlay);
+    if (!audioElement.paused) {
+      handlePlay();
+    }
+
+    return () => {
+      audioElement.removeEventListener('play', handlePlay);
+    };
+  }, [audioElement]);
+
+  // Create an analyser connected to the shared source
+  const createAnalyser = useCallback((options?: { fftSize?: number; smoothing?: number }): AnalyserNode | null => {
+    if (!audioContextRef.current || !sourceRef.current) return null;
+
+    try {
+      const analyser = audioContextRef.current.createAnalyser();
+      analyser.fftSize = options?.fftSize ?? 256;
+      analyser.smoothingTimeConstant = options?.smoothing ?? 0.85;
+
+      // Connect: source -> analyser -> destination
+      sourceRef.current.connect(analyser);
+      analyser.connect(audioContextRef.current.destination);
+
+      analyserNodesRef.current.add(analyser);
+      return analyser;
+    } catch (error) {
+      console.warn('[SharedWebAudio] Could not create analyser:', error);
+      return null;
+    }
+  }, []);
+
+  // Disconnect an analyser
+  const disconnectAnalyser = useCallback((analyser: AnalyserNode) => {
+    try {
+      analyser.disconnect();
+      analyserNodesRef.current.delete(analyser);
+    } catch { /* ignore */ }
+  }, []);
+
+  return {
+    audioContext: audioContextRef.current,
+    sourceNode: sourceRef.current,
+    createAnalyser,
+    disconnectAnalyser,
+  };
+}

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

@@ -0,0 +1,201 @@
+'use client';
+
+/**
+ * useVisualization - Hook for managing audio visualization settings
+ *
+ * Persists settings in localStorage for user preferences
+ * Uses React Context for shared state between components
+ */
+
+import { createContext, useContext, useCallback, useMemo, type ReactNode } from 'react';
+import { useLocalStorage } from '@djangocfg/ui-nextjs';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type VisualizationVariant = 'glow' | 'orbs' | 'spotlight' | 'mesh' | 'none';
+export type VisualizationIntensity = 'subtle' | 'medium' | 'strong';
+export type VisualizationColorScheme = 'primary' | 'vibrant' | 'cool' | 'warm';
+
+export interface VisualizationSettings {
+  /** Enable reactive cover animation */
+  enabled: boolean;
+  /** Visual effect variant */
+  variant: VisualizationVariant;
+  /** Effect intensity */
+  intensity: VisualizationIntensity;
+  /** Color scheme */
+  colorScheme: VisualizationColorScheme;
+}
+
+export interface UseVisualizationReturn {
+  /** Current settings */
+  settings: VisualizationSettings;
+  /** Toggle visualization on/off */
+  toggle: () => void;
+  /** Set specific setting */
+  setSetting: <K extends keyof VisualizationSettings>(
+    key: K,
+    value: VisualizationSettings[K]
+  ) => void;
+  /** Cycle to next variant */
+  nextVariant: () => void;
+  /** Cycle to next intensity */
+  nextIntensity: () => void;
+  /** Cycle to next color scheme */
+  nextColorScheme: () => void;
+  /** Reset to defaults */
+  reset: () => void;
+}
+
+// Backward compatibility alias
+export type UseAudioVisualizationReturn = UseVisualizationReturn;
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const STORAGE_KEY = 'audio-visualization-settings';
+
+const DEFAULT_SETTINGS: VisualizationSettings = {
+  enabled: true,
+  variant: 'spotlight',
+  intensity: 'medium',
+  colorScheme: 'primary',
+};
+
+const VARIANTS: VisualizationVariant[] = ['spotlight', 'glow', 'orbs', 'mesh', 'none'];
+const INTENSITIES: VisualizationIntensity[] = ['subtle', 'medium', 'strong'];
+const COLOR_SCHEMES: VisualizationColorScheme[] = ['primary', 'vibrant', 'cool', 'warm'];
+
+// =============================================================================
+// CONTEXT
+// =============================================================================
+
+const VisualizationContext = createContext<UseVisualizationReturn | null>(null);
+
+// =============================================================================
+// PROVIDER
+// =============================================================================
+
+export interface VisualizationProviderProps {
+  children: ReactNode;
+}
+
+export function VisualizationProvider({ children }: VisualizationProviderProps) {
+  const value = useVisualizationState();
+  return (
+    <VisualizationContext.Provider value={value}>
+      {children}
+    </VisualizationContext.Provider>
+  );
+}
+
+// =============================================================================
+// INTERNAL HOOK (creates the actual state)
+// =============================================================================
+
+function useVisualizationState(): UseVisualizationReturn {
+  const [settings, setSettings] = useLocalStorage<VisualizationSettings>(
+    STORAGE_KEY,
+    DEFAULT_SETTINGS
+  );
+
+  const toggle = useCallback(() => {
+    setSettings((prev) => ({ ...prev, enabled: !prev.enabled }));
+  }, [setSettings]);
+
+  const setSetting = useCallback(
+    <K extends keyof VisualizationSettings>(
+      key: K,
+      value: VisualizationSettings[K]
+    ) => {
+      setSettings((prev) => ({ ...prev, [key]: value }));
+    },
+    [setSettings]
+  );
+
+  const nextVariant = useCallback(() => {
+    setSettings((prev) => {
+      const currentIndex = VARIANTS.indexOf(prev.variant);
+      const nextIndex = (currentIndex + 1) % VARIANTS.length;
+      return { ...prev, variant: VARIANTS[nextIndex] };
+    });
+  }, [setSettings]);
+
+  const nextIntensity = useCallback(() => {
+    setSettings((prev) => {
+      const currentIndex = INTENSITIES.indexOf(prev.intensity);
+      const nextIndex = (currentIndex + 1) % INTENSITIES.length;
+      return { ...prev, intensity: INTENSITIES[nextIndex] };
+    });
+  }, [setSettings]);
+
+  const nextColorScheme = useCallback(() => {
+    setSettings((prev) => {
+      const currentIndex = COLOR_SCHEMES.indexOf(prev.colorScheme);
+      const nextIndex = (currentIndex + 1) % COLOR_SCHEMES.length;
+      return { ...prev, colorScheme: COLOR_SCHEMES[nextIndex] };
+    });
+  }, [setSettings]);
+
+  const reset = useCallback(() => {
+    setSettings(DEFAULT_SETTINGS);
+  }, [setSettings]);
+
+  return useMemo(
+    () => ({
+      settings,
+      toggle,
+      setSetting,
+      nextVariant,
+      nextIntensity,
+      nextColorScheme,
+      reset,
+    }),
+    [settings, toggle, setSetting, nextVariant, nextIntensity, nextColorScheme, reset]
+  );
+}
+
+// =============================================================================
+// HOOK (uses context when available)
+// =============================================================================
+
+export function useVisualization(): UseVisualizationReturn {
+  const context = useContext(VisualizationContext);
+
+  // Always call the fallback hooks (React hooks rules require consistent calls)
+  const fallbackState = useVisualizationState();
+
+  // If inside a provider, use shared context; otherwise use fallback
+  return context ?? fallbackState;
+}
+
+// Backward compatibility alias
+export const useAudioVisualization = useVisualization;
+
+// =============================================================================
+// VARIANT INFO
+// =============================================================================
+
+export const VARIANT_INFO: Record<VisualizationVariant, { label: string; icon: string }> = {
+  spotlight: { label: 'Spotlight', icon: '💫' },
+  glow: { label: 'Glow', icon: '✨' },
+  orbs: { label: 'Orbs', icon: '🔮' },
+  mesh: { label: 'Mesh', icon: '🌈' },
+  none: { label: 'Off', icon: '⭕' },
+};
+
+export const INTENSITY_INFO: Record<VisualizationIntensity, { label: string }> = {
+  subtle: { label: 'Subtle' },
+  medium: { label: 'Medium' },
+  strong: { label: 'Strong' },
+};
+
+export const COLOR_SCHEME_INFO: Record<VisualizationColorScheme, { label: string; preview: string }> = {
+  primary: { label: 'Primary', preview: '🔵' },
+  vibrant: { label: 'Vibrant', preview: '🌈' },
+  cool: { label: 'Cool', preview: '💙' },
+  warm: { label: 'Warm', preview: '🔥' },
+};

package/src/tools/AudioPlayer/index.ts

@@ -0,0 +1,139 @@
+/**
+ * AudioPlayer - Complete audio playback solution with reactive visualizations
+ *
+ * @example
+ * // Simple usage
+ * import { SimpleAudioPlayer } from '@djangocfg/ui-nextjs';
+ * <SimpleAudioPlayer src="/audio.mp3" title="Track Title" />
+ *
+ * @example
+ * // Custom setup with context
+ * import { AudioProvider, AudioPlayer, useAudio } from '@djangocfg/ui-nextjs';
+ * <AudioProvider source={{ uri: audioUrl }} containerRef={ref}>
+ *   <AudioPlayer ref={ref} />
+ * </AudioProvider>
+ */
+
+// =============================================================================
+// COMPONENTS
+// =============================================================================
+
+export {
+  AudioPlayer,
+  SimpleAudioPlayer,
+  AudioEqualizer,
+  AudioShortcutsPopover,
+  VisualizationToggle,
+  AudioReactiveCover,
+  // Effect components (for custom implementations)
+  GlowEffect,
+  OrbsEffect,
+  SpotlightEffect,
+  MeshEffect,
+} from './components';
+
+export type {
+  SimpleAudioPlayerProps,
+  VisualizationToggleProps,
+  AudioReactiveCoverProps,
+  GlowEffectData,
+} from './components';
+
+// =============================================================================
+// CONTEXT
+// =============================================================================
+
+export {
+  AudioProvider,
+  AudioPlayerContext,
+  useAudio,
+  useAudioControls,
+  useAudioState,
+  useAudioElement,
+} from './context';
+
+// =============================================================================
+// HOOKS
+// =============================================================================
+
+export {
+  // Internal hooks (for custom implementations)
+  useSharedWebAudio,
+  useAudioAnalysis,
+  // Public hooks
+  useAudioHotkeys,
+  AUDIO_SHORTCUTS,
+  // Visualization
+  useVisualization,
+  useAudioVisualization, // backward compat alias
+  VisualizationProvider,
+  VARIANT_INFO,
+  INTENSITY_INFO,
+  COLOR_SCHEME_INFO,
+} from './hooks';
+
+export type {
+  AudioHotkeyOptions,
+  ShortcutItem,
+  ShortcutGroup,
+  VisualizationSettings,
+  VisualizationVariant,
+  VisualizationIntensity,
+  VisualizationColorScheme,
+  UseVisualizationReturn,
+  UseAudioVisualizationReturn,
+  VisualizationProviderProps,
+} from './hooks';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type {
+  // Audio types
+  AudioSource,
+  AudioContextState,
+  SharedWebAudioContext,
+  WaveformOptions,
+  PlaybackStatus,
+  // Component types
+  AudioPlayerProps,
+  AudioEqualizerProps,
+  AudioViewerProps,
+  EqualizerOptions,
+} from './types';
+
+// =============================================================================
+// EFFECTS
+// =============================================================================
+
+export {
+  // Utilities
+  getEffectConfig,
+  getColors,
+  prepareEffectColors,
+  calculateGlowLayers,
+  calculateOrbs,
+  calculateMeshGradients,
+  calculateSpotlight,
+  // Constants
+  INTENSITY_CONFIG,
+  COLOR_SCHEMES,
+  EFFECT_ANIMATIONS,
+} from './effects';
+
+export type {
+  EffectVariant,
+  EffectIntensity,
+  EffectColorScheme,
+  AudioLevels,
+  EffectConfig,
+  EffectColors,
+  EffectLayer,
+} from './effects';
+
+// =============================================================================
+// UTILITIES
+// =============================================================================
+
+export { formatTime } from './utils';

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

@@ -0,0 +1,107 @@
+/**
+ * Core audio-related types
+ */
+
+import type WaveSurfer from 'wavesurfer.js';
+import type { AudioLevels } from './effects';
+
+// =============================================================================
+// AUDIO SOURCE
+// =============================================================================
+
+export interface AudioSource {
+  uri: string;
+}
+
+// =============================================================================
+// PLAYBACK STATE
+// =============================================================================
+
+export interface PlaybackStatus {
+  isLoaded: boolean;
+  isPlaying: boolean;
+  duration: number;
+  currentTime: number;
+  volume: number;
+  isMuted: boolean;
+}
+
+// =============================================================================
+// WAVEFORM OPTIONS
+// =============================================================================
+
+export interface WaveformOptions {
+  waveColor?: string;
+  progressColor?: string;
+  height?: number;
+  barWidth?: number;
+  barRadius?: number;
+  barGap?: number;
+  cursorWidth?: number;
+  cursorColor?: string;
+}
+
+// =============================================================================
+// EQUALIZER OPTIONS
+// =============================================================================
+
+export interface EqualizerOptions {
+  barCount?: number;
+  height?: number;
+  gap?: number;
+  showPeaks?: boolean;
+  barColor?: string;
+  peakColor?: string;
+}
+
+// =============================================================================
+// SHARED WEB AUDIO CONTEXT
+// =============================================================================
+
+export interface SharedWebAudioContext {
+  /** The Web Audio AudioContext instance */
+  audioContext: AudioContext | null;
+  /** The MediaElementSourceNode connected to the audio element */
+  sourceNode: MediaElementAudioSourceNode | null;
+  /** Create an AnalyserNode connected to the shared source */
+  createAnalyser: (options?: { fftSize?: number; smoothing?: number }) => AnalyserNode | null;
+  /** Disconnect and cleanup an AnalyserNode */
+  disconnectAnalyser: (analyser: AnalyserNode) => void;
+}
+
+// =============================================================================
+// AUDIO CONTEXT STATE
+// =============================================================================
+
+export interface AudioContextState {
+  // Core instances
+  wavesurfer: WaveSurfer | null;
+  audioElement: HTMLMediaElement | null;
+  /** Shared Web Audio context for analyzers */
+  sharedAudio: SharedWebAudioContext;
+
+  // Playback state
+  isReady: boolean;
+  isPlaying: boolean;
+  currentTime: number;
+  duration: number;
+  volume: number;
+  isMuted: boolean;
+  isLooping: boolean;
+
+  // Audio analysis (for reactive effects)
+  audioLevels: AudioLevels;
+
+  // Actions
+  play: () => Promise<void>;
+  pause: () => void;
+  togglePlay: () => void;
+  seek: (time: number) => void;
+  seekTo: (progress: number) => void;
+  skip: (seconds: number) => void;
+  setVolume: (volume: number) => void;
+  toggleMute: () => void;
+  toggleLoop: () => void;
+  setLoop: (enabled: boolean) => void;
+  restart: () => void;
+}

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

@@ -0,0 +1,98 @@
+/**
+ * Component props types
+ */
+
+import type { CSSProperties } from 'react';
+import type { WaveformOptions, EqualizerOptions, AudioSource, PlaybackStatus } from './audio';
+
+// =============================================================================
+// AUDIO PLAYER PROPS
+// =============================================================================
+
+export interface AudioPlayerProps {
+  /** Show playback controls */
+  showControls?: boolean;
+  /** Show waveform visualization */
+  showWaveform?: boolean;
+  /** Show equalizer animation */
+  showEqualizer?: boolean;
+  /** Show timer (position/duration) */
+  showTimer?: boolean;
+  /** Show volume control */
+  showVolume?: boolean;
+  /** Show loop/repeat button */
+  showLoop?: boolean;
+  /** WaveSurfer options override */
+  waveformOptions?: WaveformOptions;
+  /** Equalizer options */
+  equalizerOptions?: EqualizerOptions;
+  /** Additional class name */
+  className?: string;
+  /** Additional styles */
+  style?: CSSProperties;
+}
+
+// =============================================================================
+// AUDIO EQUALIZER PROPS
+// =============================================================================
+
+export interface AudioEqualizerProps {
+  /** Number of frequency bars */
+  barCount?: number;
+  /** Height of the equalizer in pixels */
+  height?: number;
+  /** Gap between bars in pixels */
+  gap?: number;
+  /** Show peak indicators */
+  showPeaks?: boolean;
+  /** Bar color (CSS color) */
+  barColor?: string;
+  /** Peak indicator color */
+  peakColor?: string;
+  /** Additional class name */
+  className?: string;
+}
+
+// =============================================================================
+// AUDIO REACTIVE COVER PROPS
+// =============================================================================
+
+export interface AudioReactiveCoverProps {
+  /** Visual variant */
+  variant?: 'glow' | 'orbs' | 'spotlight' | 'mesh';
+  /** Intensity of effects */
+  intensity?: 'subtle' | 'medium' | 'strong';
+  /** Color scheme */
+  colorScheme?: 'primary' | 'vibrant' | 'cool' | 'warm';
+}
+
+// =============================================================================
+// AUDIO VIEWER PROPS (legacy)
+// =============================================================================
+
+export interface AudioViewerProps {
+  /** Audio source URL */
+  source: AudioSource;
+  /** Auto-play when loaded */
+  autoPlay?: boolean;
+  /** Show playback controls */
+  showControls?: boolean;
+  /** Show waveform visualization */
+  showWaveform?: boolean;
+  /** Show equalizer animation */
+  showEqualizer?: boolean;
+  /** Show timer */
+  showTimer?: boolean;
+  /** Show volume control */
+  showVolume?: boolean;
+  /** Waveform options */
+  waveformOptions?: WaveformOptions;
+  /** Equalizer options */
+  equalizerOptions?: EqualizerOptions;
+  /** Callback on playback status change */
+  onPlaybackStatusUpdate?: (status: PlaybackStatus) => void;
+  /** Additional class name */
+  className?: string;
+  /** Additional styles */
+  style?: CSSProperties;
+}