@djangocfg/ui-nextjs 2.1.66 → 2.1.68

package/src/tools/AudioPlayer/@refactoring/01-TYPES.md

@@ -0,0 +1,301 @@
+# Phase 2: Types Split
+
+## Source: `types.ts` (185 lines)
+
+Split into 3 files by domain.
+
+---
+
+## `types/audio.ts`
+
+Core audio-related types.
+
+```typescript
+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 {
+  audioContext: AudioContext | null;
+  sourceNode: MediaElementAudioSourceNode | null;
+  createAnalyser: (options?: { fftSize?: number; smoothing?: number }) => AnalyserNode | null;
+  disconnectAnalyser: (analyser: AnalyserNode) => void;
+}
+
+// =============================================================================
+// AUDIO CONTEXT STATE
+// =============================================================================
+
+export interface AudioContextState {
+  // Core instances
+  wavesurfer: WaveSurfer | null;
+  audioElement: HTMLMediaElement | null;
+  sharedAudio: SharedWebAudioContext;
+
+  // Playback state
+  isReady: boolean;
+  isPlaying: boolean;
+  currentTime: number;
+  duration: number;
+  volume: number;
+  isMuted: boolean;
+  isLooping: boolean;
+
+  // Audio analysis
+  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;
+}
+```
+
+---
+
+## `types/components.ts`
+
+Component props types.
+
+```typescript
+import type { CSSProperties } from 'react';
+import type { WaveformOptions, EqualizerOptions, AudioSource, PlaybackStatus } from './audio';
+
+// =============================================================================
+// AUDIO PLAYER PROPS
+// =============================================================================
+
+export interface AudioPlayerProps {
+  showControls?: boolean;
+  showWaveform?: boolean;
+  showEqualizer?: boolean;
+  showTimer?: boolean;
+  showVolume?: boolean;
+  showLoop?: boolean;
+  waveformOptions?: WaveformOptions;
+  equalizerOptions?: EqualizerOptions;
+  className?: string;
+  style?: CSSProperties;
+}
+
+// =============================================================================
+// AUDIO EQUALIZER PROPS
+// =============================================================================
+
+export interface AudioEqualizerProps {
+  barCount?: number;
+  height?: number;
+  gap?: number;
+  showPeaks?: boolean;
+  barColor?: string;
+  peakColor?: string;
+  className?: string;
+}
+
+// =============================================================================
+// AUDIO REACTIVE COVER PROPS
+// =============================================================================
+
+export interface AudioReactiveCoverProps {
+  variant?: 'glow' | 'orbs' | 'spotlight' | 'mesh';
+  intensity?: 'subtle' | 'medium' | 'strong';
+  colorScheme?: 'primary' | 'vibrant' | 'cool' | 'warm';
+}
+
+// =============================================================================
+// AUDIO VIEWER PROPS (legacy)
+// =============================================================================
+
+export interface AudioViewerProps {
+  source: AudioSource;
+  autoPlay?: boolean;
+  showControls?: boolean;
+  showWaveform?: boolean;
+  showEqualizer?: boolean;
+  showTimer?: boolean;
+  showVolume?: boolean;
+  waveformOptions?: WaveformOptions;
+  equalizerOptions?: EqualizerOptions;
+  onPlaybackStatusUpdate?: (status: PlaybackStatus) => void;
+  className?: string;
+  style?: CSSProperties;
+}
+```
+
+---
+
+## `types/effects.ts`
+
+Effect-related types (moved from effects/index.ts).
+
+```typescript
+// =============================================================================
+// EFFECT TYPES
+// =============================================================================
+
+export type EffectVariant = 'glow' | 'orbs' | 'spotlight' | 'mesh';
+export type EffectIntensity = 'subtle' | 'medium' | 'strong';
+export type EffectColorScheme = 'primary' | 'vibrant' | 'cool' | 'warm';
+
+export interface AudioLevels {
+  bass: number;
+  mid: number;
+  high: number;
+  overall: number;
+}
+
+export interface EffectConfig {
+  opacity: number;
+  scale: number;
+  blur: string;
+}
+
+export interface EffectColors {
+  colors: string[];
+  hueShift: number;
+}
+
+export interface EffectLayer {
+  inset: number;
+  opacity: number;
+  scale: number;
+  background: string;
+  blur: string;
+  animation?: string;
+}
+
+export interface Orb {
+  x: number;
+  y: number;
+  size: number;
+  color: string;
+  opacity: number;
+  scale: number;
+}
+
+export interface MeshGradient {
+  width: string;
+  height: string;
+  top?: string;
+  bottom?: string;
+  left?: string;
+  right?: string;
+  color: string;
+  opacity: number;
+  scale: number;
+  rotation: number;
+  blur: string;
+  isCenter?: boolean;
+}
+
+export interface SpotlightData {
+  rotation: number;
+  inset: number;
+  colors: Array<{ color: string; opacity: number }>;
+  pulseInset: number;
+  pulseOpacity: number;
+  pulseScale: number;
+  ringOpacity: number;
+  ringScale: number;
+}
+```
+
+---
+
+## `types/index.ts`
+
+Re-export all types.
+
+```typescript
+// Audio types
+export type {
+  AudioSource,
+  PlaybackStatus,
+  WaveformOptions,
+  EqualizerOptions,
+  SharedWebAudioContext,
+  AudioContextState,
+} from './audio';
+
+// Component props
+export type {
+  AudioPlayerProps,
+  AudioEqualizerProps,
+  AudioReactiveCoverProps,
+  AudioViewerProps,
+} from './components';
+
+// Effect types
+export type {
+  EffectVariant,
+  EffectIntensity,
+  EffectColorScheme,
+  AudioLevels,
+  EffectConfig,
+  EffectColors,
+  EffectLayer,
+  Orb,
+  MeshGradient,
+  SpotlightData,
+} from './effects';
+```

package/src/tools/AudioPlayer/@refactoring/02-HOOKS.md

@@ -0,0 +1,281 @@
+# Phase 3: Hooks Extraction
+
+## Source: `context.tsx` (lines 25-229)
+
+Extract two internal hooks from context.tsx.
+
+---
+
+## `hooks/useSharedWebAudio.ts`
+
+Web Audio API context management. Prevents "InvalidStateError" from multiple MediaElementSourceNodes.
+
+```typescript
+'use client';
+
+import { useRef, useEffect, useCallback } from 'react';
+import type { SharedWebAudioContext } from '../types';
+
+/**
+ * Manages a shared Web Audio context and source node.
+ * All analyzers share the same source to prevent InvalidStateError.
+ */
+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;
+
+    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;
+
+        if (connectedElementRef.current !== audioElement) {
+          if (sourceRef.current) {
+            try { sourceRef.current.disconnect(); } catch { /* ignore */ }
+          }
+
+          sourceRef.current = audioContext.createMediaElementSource(audioElement);
+          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]);
+
+  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;
+
+      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;
+    }
+  }, []);
+
+  const disconnectAnalyser = useCallback((analyser: AnalyserNode) => {
+    try {
+      analyser.disconnect();
+      analyserNodesRef.current.delete(analyser);
+    } catch { /* ignore */ }
+  }, []);
+
+  return {
+    audioContext: audioContextRef.current,
+    sourceNode: sourceRef.current,
+    createAnalyser,
+    disconnectAnalyser,
+  };
+}
+```
+
+---
+
+## `hooks/useAudioAnalysis.ts`
+
+Real-time audio frequency analysis for reactive effects.
+
+```typescript
+'use client';
+
+import { useState, useRef, useEffect, useCallback } from 'react';
+import type { SharedWebAudioContext, AudioLevels } from '../types';
+
+/**
+ * Analyzes audio frequencies for bass, mid, high, and overall levels.
+ * Uses shared Web Audio context to prevent duplicate source nodes.
+ */
+export function useAudioAnalysis(
+  sharedAudio: SharedWebAudioContext,
+  isPlaying: boolean
+): AudioLevels {
+  const [levels, setLevels] = useState<AudioLevels>({ bass: 0, mid: 0, high: 0, overall: 0 });
+  const analyserRef = useRef<AnalyserNode | null>(null);
+  const animationRef = useRef<number | null>(null);
+  const dataArrayRef = useRef<Uint8Array | null>(null);
+
+  const cleanup = useCallback(() => {
+    if (animationRef.current) {
+      cancelAnimationFrame(animationRef.current);
+      animationRef.current = null;
+    }
+  }, []);
+
+  // Create analyser when shared audio is ready
+  useEffect(() => {
+    if (!sharedAudio.sourceNode || analyserRef.current) return;
+
+    const analyser = sharedAudio.createAnalyser({ fftSize: 256, smoothing: 0.85 });
+    if (analyser) {
+      analyserRef.current = analyser;
+      dataArrayRef.current = new Uint8Array(analyser.frequencyBinCount);
+    }
+
+    return () => {
+      if (analyserRef.current) {
+        sharedAudio.disconnectAnalyser(analyserRef.current);
+        analyserRef.current = null;
+        dataArrayRef.current = null;
+      }
+    };
+  }, [sharedAudio.sourceNode, sharedAudio.createAnalyser, sharedAudio.disconnectAnalyser]);
+
+  // Animation loop
+  useEffect(() => {
+    if (!isPlaying || !analyserRef.current || !dataArrayRef.current) {
+      cleanup();
+      // Smooth fade out
+      setLevels(prev => ({
+        bass: prev.bass * 0.95 < 0.01 ? 0 : prev.bass * 0.95,
+        mid: prev.mid * 0.95,
+        high: prev.high * 0.95,
+        overall: prev.overall * 0.95,
+      }));
+      return;
+    }
+
+    const analyser = analyserRef.current;
+    const dataArray = dataArrayRef.current;
+
+    const animate = () => {
+      analyser.getByteFrequencyData(dataArray);
+      const binCount = dataArray.length;
+
+      // Bass (0-15%)
+      const bassEnd = Math.floor(binCount * 0.15);
+      let bassSum = 0;
+      for (let i = 0; i < bassEnd; i++) bassSum += dataArray[i];
+      const bass = bassSum / bassEnd / 255;
+
+      // Mids (15-50%)
+      const midStart = bassEnd;
+      const midEnd = Math.floor(binCount * 0.5);
+      let midSum = 0;
+      for (let i = midStart; i < midEnd; i++) midSum += dataArray[i];
+      const mid = midSum / (midEnd - midStart) / 255;
+
+      // Highs (50-100%)
+      const highStart = midEnd;
+      let highSum = 0;
+      for (let i = highStart; i < binCount; i++) highSum += dataArray[i];
+      const high = highSum / (binCount - highStart) / 255;
+
+      // Overall
+      let totalSum = 0;
+      for (let i = 0; i < binCount; i++) totalSum += dataArray[i];
+      const overall = totalSum / binCount / 255;
+
+      // Smooth with lerp
+      setLevels(prev => ({
+        bass: prev.bass * 0.7 + bass * 0.3,
+        mid: prev.mid * 0.7 + mid * 0.3,
+        high: prev.high * 0.7 + high * 0.3,
+        overall: prev.overall * 0.7 + overall * 0.3,
+      }));
+
+      animationRef.current = requestAnimationFrame(animate);
+    };
+
+    animationRef.current = requestAnimationFrame(animate);
+    return cleanup;
+  }, [isPlaying, cleanup]);
+
+  return levels;
+}
+```
+
+---
+
+## `hooks/useAudioHotkeys.ts`
+
+Move existing file, update imports.
+
+```typescript
+// Same content, just update imports:
+// - import type { ... } from '../types';
+// - import { useAudioControls, useAudioState } from '../context';
+```
+
+---
+
+## `hooks/useVisualization.tsx`
+
+Rename from `useAudioVisualization.tsx`, update imports.
+
+```typescript
+// Same content, just update imports
+// Export both old and new names for backward compatibility
+export { useVisualization as useAudioVisualization };
+```
+
+---
+
+## `hooks/index.ts`
+
+```typescript
+// Internal hooks (used by provider)
+export { useSharedWebAudio } from './useSharedWebAudio';
+export { useAudioAnalysis } from './useAudioAnalysis';
+
+// Public hooks
+export { useAudioHotkeys, AUDIO_SHORTCUTS } from './useAudioHotkeys';
+export type { AudioHotkeyOptions, ShortcutItem, ShortcutGroup } from './useAudioHotkeys';
+
+export {
+  useVisualization,
+  useAudioVisualization, // backward compat alias
+  VisualizationProvider,
+  VARIANT_INFO,
+  INTENSITY_INFO,
+  COLOR_SCHEME_INFO,
+} from './useVisualization';
+export type {
+  VisualizationSettings,
+  VisualizationVariant,
+  VisualizationIntensity,
+  VisualizationColorScheme,
+  UseAudioVisualizationReturn,
+  VisualizationProviderProps,
+} from './useVisualization';
+```