@djangocfg/ui-nextjs 2.1.81 → 2.1.83

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

@@ -1,281 +0,0 @@
-# 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';
-```

package/src/tools/AudioPlayer/@refactoring/03-CONTEXT.md

@@ -1,328 +0,0 @@
-# Phase 4: Context Refactoring
-
-## Source: `context.tsx` (lines 231-574)
-
-Split provider from selector hooks.
-
----
-
-## `context/AudioProvider.tsx`
-
-Provider component only (~150 lines).
-
-```typescript
-'use client';
-
-import {
-  createContext,
-  useRef,
-  useMemo,
-  useCallback,
-  useState,
-  useEffect,
-  type ReactNode,
-} from 'react';
-import { useWavesurfer } from '@wavesurfer/react';
-import type { AudioContextState, AudioSource, WaveformOptions } from '../types';
-import { useSharedWebAudio, useAudioAnalysis } from '../hooks';
-import { useAudioCache } from '../../../stores/mediaCache';
-
-// =============================================================================
-// CONTEXT
-// =============================================================================
-
-export const AudioPlayerContext = createContext<AudioContextState | null>(null);
-
-// =============================================================================
-// PROVIDER PROPS
-// =============================================================================
-
-interface AudioProviderProps {
-  source: AudioSource;
-  autoPlay?: boolean;
-  waveformOptions?: WaveformOptions;
-  containerRef: React.RefObject<HTMLDivElement | null>;
-  children: ReactNode;
-}
-
-// =============================================================================
-// PROVIDER
-// =============================================================================
-
-export function AudioProvider({
-  source,
-  autoPlay = false,
-  waveformOptions = {},
-  containerRef,
-  children,
-}: AudioProviderProps) {
-  // Cache for playback position persistence
-  const { saveAudioPosition, getAudioPosition } = useAudioCache();
-  const lastSavedTimeRef = useRef<number>(0);
-
-  // Memoize WaveSurfer options
-  const options = useMemo(
-    () => ({
-      container: containerRef,
-      url: source.uri,
-      waveColor: waveformOptions.waveColor || 'hsl(217 91% 60% / 0.3)',
-      progressColor: waveformOptions.progressColor || 'hsl(217 91% 60%)',
-      cursorColor: waveformOptions.cursorColor || 'hsl(217 91% 60%)',
-      cursorWidth: waveformOptions.cursorWidth ?? 2,
-      height: waveformOptions.height ?? 64,
-      barWidth: waveformOptions.barWidth ?? 3,
-      barRadius: waveformOptions.barRadius ?? 3,
-      barGap: waveformOptions.barGap ?? 2,
-      normalize: true,
-      interact: true,
-      hideScrollbar: true,
-      autoplay: autoPlay,
-    }),
-    [source.uri, autoPlay, waveformOptions, containerRef]
-  );
-
-  const { wavesurfer, isReady, isPlaying, currentTime } = useWavesurfer(options);
-
-  // Restore cached position
-  useEffect(() => {
-    if (isReady && wavesurfer && source.uri) {
-      const cachedPosition = getAudioPosition(source.uri);
-      if (cachedPosition && cachedPosition > 0) {
-        const duration = wavesurfer.getDuration();
-        if (cachedPosition < duration - 1) {
-          wavesurfer.setTime(cachedPosition);
-        }
-      }
-    }
-  }, [isReady, wavesurfer, source.uri, getAudioPosition]);
-
-  // Save position periodically
-  useEffect(() => {
-    if (!source.uri) return;
-
-    if (isPlaying && currentTime > 0) {
-      const timeSinceLastSave = currentTime - lastSavedTimeRef.current;
-      if (timeSinceLastSave >= 5 || timeSinceLastSave < 0) {
-        saveAudioPosition(source.uri, currentTime);
-        lastSavedTimeRef.current = currentTime;
-      }
-    }
-
-    if (!isPlaying && currentTime > 0) {
-      saveAudioPosition(source.uri, currentTime);
-      lastSavedTimeRef.current = currentTime;
-    }
-  }, [isPlaying, currentTime, source.uri, saveAudioPosition]);
-
-  // Derived state
-  const duration = wavesurfer?.getDuration() ?? 0;
-  const volume = wavesurfer?.getVolume() ?? 1;
-  const isMuted = wavesurfer?.getMuted() ?? false;
-
-  // Loop state
-  const [isLooping, setIsLooping] = useState(false);
-
-  useEffect(() => {
-    if (!wavesurfer) return;
-
-    const handleFinish = () => {
-      if (isLooping) {
-        wavesurfer.seekTo(0);
-        wavesurfer.play();
-      }
-    };
-
-    wavesurfer.on('finish', handleFinish);
-    return () => {
-      wavesurfer.un('finish', handleFinish);
-    };
-  }, [wavesurfer, isLooping]);
-
-  // Audio element
-  const audioElement = useMemo(() => wavesurfer?.getMediaElement() ?? null, [wavesurfer]);
-
-  // Shared Web Audio context
-  const sharedAudio = useSharedWebAudio(audioElement);
-
-  // Audio analysis
-  const audioLevels = useAudioAnalysis(sharedAudio, isPlaying);
-
-  // Actions
-  const play = useCallback(async () => { await wavesurfer?.play(); }, [wavesurfer]);
-  const pause = useCallback(() => { wavesurfer?.pause(); }, [wavesurfer]);
-  const togglePlay = useCallback(() => { wavesurfer?.playPause(); }, [wavesurfer]);
-
-  const seek = useCallback((time: number) => {
-    if (wavesurfer) {
-      wavesurfer.setTime(Math.max(0, Math.min(time, duration)));
-    }
-  }, [wavesurfer, duration]);
-
-  const seekTo = useCallback((progress: number) => {
-    if (wavesurfer) {
-      wavesurfer.seekTo(Math.max(0, Math.min(progress, 1)));
-    }
-  }, [wavesurfer]);
-
-  const skip = useCallback((seconds: number) => { wavesurfer?.skip(seconds); }, [wavesurfer]);
-
-  const setVolume = useCallback((vol: number) => {
-    if (wavesurfer) {
-      wavesurfer.setVolume(Math.max(0, Math.min(vol, 1)));
-    }
-  }, [wavesurfer]);
-
-  const toggleMute = useCallback(() => {
-    if (wavesurfer) {
-      wavesurfer.setMuted(!wavesurfer.getMuted());
-    }
-  }, [wavesurfer]);
-
-  const restart = useCallback(() => {
-    if (wavesurfer) {
-      wavesurfer.seekTo(0);
-      wavesurfer.play();
-    }
-  }, [wavesurfer]);
-
-  const toggleLoop = useCallback(() => { setIsLooping(prev => !prev); }, []);
-  const setLoop = useCallback((enabled: boolean) => { setIsLooping(enabled); }, []);
-
-  // Context value
-  const contextValue = useMemo<AudioContextState>(
-    () => ({
-      wavesurfer,
-      audioElement,
-      sharedAudio,
-      isReady,
-      isPlaying,
-      currentTime,
-      duration,
-      volume,
-      isMuted,
-      isLooping,
-      audioLevels,
-      play,
-      pause,
-      togglePlay,
-      seek,
-      seekTo,
-      skip,
-      setVolume,
-      toggleMute,
-      toggleLoop,
-      setLoop,
-      restart,
-    }),
-    [
-      wavesurfer, audioElement, sharedAudio,
-      isReady, isPlaying, currentTime, duration, volume, isMuted, isLooping,
-      audioLevels,
-      play, pause, togglePlay, seek, seekTo, skip, setVolume, toggleMute, toggleLoop, setLoop, restart,
-    ]
-  );
-
-  return (
-    <AudioPlayerContext.Provider value={contextValue}>
-      {children}
-    </AudioPlayerContext.Provider>
-  );
-}
-```
-
----
-
-## `context/selectors.ts`
-
-Selector hooks for performance optimization.
-
-```typescript
-'use client';
-
-import { useContext } from 'react';
-import { AudioPlayerContext } from './AudioProvider';
-import type { AudioContextState } from '../types';
-
-// =============================================================================
-// MAIN HOOK
-// =============================================================================
-
-export function useAudio(): AudioContextState {
-  const context = useContext(AudioPlayerContext);
-  if (!context) {
-    throw new Error('useAudio must be used within an AudioProvider');
-  }
-  return context;
-}
-
-// =============================================================================
-// SELECTIVE HOOKS - for performance optimization
-// =============================================================================
-
-/** Hook for playback controls only (no re-render on time updates) */
-export function useAudioControls() {
-  const {
-    isReady,
-    play,
-    pause,
-    togglePlay,
-    skip,
-    restart,
-    setVolume,
-    toggleMute,
-    toggleLoop,
-    setLoop,
-  } = useAudio();
-
-  return {
-    isReady,
-    play,
-    pause,
-    togglePlay,
-    skip,
-    restart,
-    setVolume,
-    toggleMute,
-    toggleLoop,
-    setLoop,
-  };
-}
-
-/** Hook for playback state (read-only) */
-export function useAudioState() {
-  const {
-    isReady,
-    isPlaying,
-    currentTime,
-    duration,
-    volume,
-    isMuted,
-    isLooping,
-  } = useAudio();
-
-  return {
-    isReady,
-    isPlaying,
-    currentTime,
-    duration,
-    volume,
-    isMuted,
-    isLooping,
-  };
-}
-
-/** Hook for audio element access (for equalizer and reactive effects) */
-export function useAudioElement() {
-  const { audioElement, sharedAudio, isPlaying, audioLevels } = useAudio();
-  return { audioElement, sharedAudio, isPlaying, audioLevels };
-}
-```
-
----
-
-## `context/index.ts`
-
-```typescript
-export { AudioPlayerContext, AudioProvider } from './AudioProvider';
-export { useAudio, useAudioControls, useAudioState, useAudioElement } from './selectors';
-```