@djangocfg/ui-nextjs 2.1.66 → 2.1.67

package/src/tools/AudioPlayer/@refactoring/07-EXECUTION-CHECKLIST.md

@@ -0,0 +1,146 @@
+# Execution Checklist
+
+## Pre-flight
+
+- [ ] Run `pnpm check` - ensure current code compiles
+- [ ] Commit current state as backup
+
+---
+
+## Phase 1: Create Folder Structure
+
+```bash
+cd src/tools/AudioPlayer
+mkdir -p types hooks context components/ReactiveCover effects utils
+```
+
+- [ ] Create `types/` folder
+- [ ] Create `hooks/` folder
+- [ ] Create `context/` folder
+- [ ] Create `components/` folder
+- [ ] Create `components/ReactiveCover/` folder
+- [ ] Create `effects/` subfolder (already exists, will add files)
+- [ ] Create `utils/` folder
+
+---
+
+## Phase 2: Types Split
+
+- [ ] Create `types/audio.ts`
+- [ ] Create `types/components.ts`
+- [ ] Create `types/effects.ts`
+- [ ] Create `types/index.ts`
+- [ ] Run `pnpm check`
+
+---
+
+## Phase 3: Hooks Extraction
+
+- [ ] Create `hooks/useSharedWebAudio.ts` (extract from context.tsx)
+- [ ] Create `hooks/useAudioAnalysis.ts` (extract from context.tsx)
+- [ ] Move `useAudioHotkeys.ts` → `hooks/useAudioHotkeys.ts`
+- [ ] Move `useAudioVisualization.tsx` → `hooks/useVisualization.tsx`
+- [ ] Create `hooks/index.ts`
+- [ ] Run `pnpm check`
+
+---
+
+## Phase 4: Context Refactoring
+
+- [ ] Create `context/AudioProvider.tsx`
+- [ ] Create `context/selectors.ts`
+- [ ] Create `context/index.ts`
+- [ ] Delete old `context.tsx`
+- [ ] Run `pnpm check`
+
+---
+
+## Phase 5: Components Reorganization
+
+- [ ] Move `AudioPlayer.tsx` → `components/AudioPlayer.tsx`
+- [ ] Move `AudioEqualizer.tsx` → `components/AudioEqualizer.tsx`
+- [ ] Move `SimpleAudioPlayer.tsx` → `components/SimpleAudioPlayer.tsx`
+- [ ] Move `AudioShortcutsPopover.tsx` → `components/ShortcutsPopover.tsx`
+- [ ] Move `VisualizationToggle.tsx` → `components/VisualizationToggle.tsx`
+- [ ] Split `AudioReactiveCover.tsx` into `components/ReactiveCover/`
+  - [ ] Create `components/ReactiveCover/index.tsx`
+  - [ ] Create `components/ReactiveCover/GlowEffect.tsx`
+  - [ ] Create `components/ReactiveCover/OrbsEffect.tsx`
+  - [ ] Create `components/ReactiveCover/SpotlightEffect.tsx`
+  - [ ] Create `components/ReactiveCover/MeshEffect.tsx`
+- [ ] Create `components/index.ts`
+- [ ] Delete old component files from root
+- [ ] Run `pnpm check`
+
+---
+
+## Phase 6: Effects Refactoring
+
+- [ ] Create `effects/constants.ts`
+- [ ] Create `effects/calculations.ts`
+- [ ] Create `effects/animations.ts`
+- [ ] Update `effects/index.ts`
+- [ ] Run `pnpm check`
+
+---
+
+## Phase 7: Utils
+
+- [ ] Create `utils/formatTime.ts`
+- [ ] Create `utils/index.ts`
+- [ ] Run `pnpm check`
+
+---
+
+## Phase 8: Update Main Index
+
+- [ ] Rewrite `index.ts` with new import paths
+- [ ] Run `pnpm check`
+
+---
+
+## Phase 9: Cleanup & Verification
+
+- [ ] Delete old files:
+  - [ ] `context.tsx`
+  - [ ] `types.ts`
+  - [ ] `useAudioHotkeys.ts` (moved)
+  - [ ] `useAudioVisualization.tsx` (moved)
+  - [ ] `AudioPlayer.tsx` (moved)
+  - [ ] `AudioEqualizer.tsx` (moved)
+  - [ ] `SimpleAudioPlayer.tsx` (moved)
+  - [ ] `AudioShortcutsPopover.tsx` (moved)
+  - [ ] `VisualizationToggle.tsx` (moved)
+  - [ ] `AudioReactiveCover.tsx` (split)
+
+- [ ] Run `pnpm check` - final verification
+- [ ] Test in playground
+- [ ] Commit refactoring
+
+---
+
+## Rollback Plan
+
+If something goes wrong:
+
+```bash
+git checkout HEAD -- src/tools/AudioPlayer/
+```
+
+---
+
+## Files to Delete (after successful migration)
+
+```
+src/tools/AudioPlayer/
+├── context.tsx           # → context/AudioProvider.tsx + context/selectors.ts
+├── types.ts              # → types/*.ts
+├── useAudioHotkeys.ts    # → hooks/useAudioHotkeys.ts
+├── useAudioVisualization.tsx  # → hooks/useVisualization.tsx
+├── AudioPlayer.tsx       # → components/AudioPlayer.tsx
+├── AudioEqualizer.tsx    # → components/AudioEqualizer.tsx
+├── SimpleAudioPlayer.tsx # → components/SimpleAudioPlayer.tsx
+├── AudioShortcutsPopover.tsx  # → components/ShortcutsPopover.tsx
+├── VisualizationToggle.tsx    # → components/VisualizationToggle.tsx
+└── AudioReactiveCover.tsx     # → components/ReactiveCover/*.tsx
+```

package/src/tools/AudioPlayer/README.md

@@ -286,16 +286,40 @@ interface WaveformOptions {
 
 ```
 AudioPlayer/
-├── index.ts                  # Exports
-├── types.ts                  # Type definitions
-├── context.tsx               # AudioProvider, useAudio hooks
-├── AudioPlayer.tsx           # Main player component
-├── AudioEqualizer.tsx        # Frequency bars
-├── AudioReactiveCover.tsx    # Reactive album art
-├── AudioShortcutsPopover.tsx # Shortcuts help
-├── VisualizationToggle.tsx   # Effect toggle button
-├── useAudioHotkeys.ts        # Keyboard shortcuts
-├── useAudioVisualization.tsx # Visualization settings
+├── index.ts                       # Public API exports
+├── types/
+│   ├── index.ts                   # Type re-exports
+│   ├── audio.ts                   # Audio state & source types
+│   ├── components.ts              # Component prop types
+│   └── effects.ts                 # Visualization effect types
+├── hooks/
+│   ├── index.ts
+│   ├── useAudioHotkeys.ts         # Keyboard shortcuts
+│   ├── useVisualization.tsx       # Visualization settings
+│   ├── useAudioAnalysis.ts        # Web Audio frequency analysis
+│   └── useSharedWebAudio.ts       # Shared AudioContext
+├── utils/
+│   ├── index.ts
+│   └── formatTime.ts              # Time formatting
+├── context/
+│   ├── index.ts
+│   ├── AudioProvider.tsx          # Audio state provider
+│   └── selectors.ts               # useAudio, useAudioControls hooks
+├── components/
+│   ├── index.ts
+│   ├── AudioPlayer.tsx            # Main player component
+│   ├── SimpleAudioPlayer.tsx      # All-in-one wrapper
+│   ├── AudioEqualizer.tsx         # Frequency bars
+│   ├── AudioShortcutsPopover.tsx  # Shortcuts help
+│   ├── VisualizationToggle.tsx    # Effect toggle button
+│   └── ReactiveCover/
+│       ├── index.ts
+│       ├── AudioReactiveCover.tsx # Reactive album art
+│       └── effects/               # Effect components
+│           ├── GlowEffect.tsx
+│           ├── OrbsEffect.tsx
+│           ├── SpotlightEffect.tsx
+│           └── MeshEffect.tsx
 └── effects/
-    └── index.ts              # Effect calculations
+    └── index.ts                   # Effect calculations
 ```

package/src/tools/AudioPlayer/{AudioEqualizer.tsx → components/AudioEqualizer.tsx}

@@ -3,8 +3,8 @@
 /**
  * AudioEqualizer - Real-time frequency visualizer with animated bars
  *
- * Uses Web Audio API AnalyserNode for real-time frequency analysis
- * Renders animated vertical bars that respond to audio playback
+ * Uses shared Web Audio context from AudioProvider for real-time frequency analysis.
+ * This prevents "InvalidStateError" from creating multiple MediaElementSourceNodes.
  *
  * Features:
  * - Real-time frequency visualization
@@ -12,12 +12,13 @@
  * - Theme-aware colors (dark/light support)
  * - Smooth animations with CSS transitions
  * - Peak hold indicators
+ * - Pre-allocated buffers for performance
  */
 
 import { useEffect, useRef, useState, useCallback } from 'react';
 import { cn } from '@djangocfg/ui-nextjs';
-import { useAudioElement } from './context';
-import type { AudioEqualizerProps } from './types';
+import { useAudioElement } from '../context';
+import type { AudioEqualizerProps } from '../types';
 
 // =============================================================================
 // CONSTANTS
@@ -42,8 +43,8 @@ export function AudioEqualizer({
   peakColor,
   className,
 }: AudioEqualizerProps) {
-  // Get audio element and playing state from context
-  const { audioElement, isPlaying } = useAudioElement();
+  // Get shared audio context from AudioProvider
+  const { sharedAudio, isPlaying } = useAudioElement();
 
   const [frequencies, setFrequencies] = useState<number[]>(() =>
     new Array(barCount).fill(0)
@@ -52,13 +53,12 @@ export function AudioEqualizer({
     new Array(barCount).fill(0)
   );
 
-  // Refs for Web Audio API
-  const audioContextRef = useRef<AudioContext | null>(null);
+  // Refs for analyzer and animation
   const analyserRef = useRef<AnalyserNode | null>(null);
-  const sourceRef = useRef<MediaElementAudioSourceNode | null>(null);
   const animationRef = useRef<number | null>(null);
   const peakTimersRef = useRef<number[]>(new Array(barCount).fill(0));
-  const connectedElementRef = useRef<HTMLMediaElement | null>(null);
+  // Pre-allocated buffer for frequency data (prevents allocation per frame)
+  const dataArrayRef = useRef<Uint8Array | null>(null);
 
   // Cleanup function
   const cleanup = useCallback(() => {
@@ -68,82 +68,47 @@ export function AudioEqualizer({
     }
   }, []);
 
-  // Initialize Web Audio API
+  // Create analyzer using shared context
   useEffect(() => {
-    if (!audioElement) {
-      cleanup();
+    // Wait for shared audio to be ready
+    if (!sharedAudio.sourceNode) {
       return;
     }
 
-    // Avoid reconnecting same element
-    if (connectedElementRef.current === audioElement && audioContextRef.current) {
+    // Only create analyzer once
+    if (analyserRef.current) {
       return;
     }
 
-    const initAudio = () => {
-      try {
-        if (!audioContextRef.current) {
-          audioContextRef.current = new AudioContext();
-        }
-
-        const audioContext = audioContextRef.current;
-
-        if (!analyserRef.current) {
-          analyserRef.current = audioContext.createAnalyser();
-          analyserRef.current.fftSize = 64;
-          analyserRef.current.smoothingTimeConstant = 0.8;
-        }
-
-        if (connectedElementRef.current !== audioElement) {
-          if (sourceRef.current) {
-            try {
-              sourceRef.current.disconnect();
-            } catch {
-              // Ignore disconnect errors
-            }
-          }
-
-          sourceRef.current = audioContext.createMediaElementSource(audioElement);
-          sourceRef.current.connect(analyserRef.current);
-          analyserRef.current.connect(audioContext.destination);
-          connectedElementRef.current = audioElement;
-        }
-      } catch (error) {
-        console.warn('AudioEqualizer: Could not connect to audio element', error);
-      }
-    };
-
-    const handlePlay = () => {
-      initAudio();
-      if (audioContextRef.current?.state === 'suspended') {
-        audioContextRef.current.resume();
-      }
-    };
-
-    audioElement.addEventListener('play', handlePlay);
-
-    if (!audioElement.paused) {
-      handlePlay();
+    const analyser = sharedAudio.createAnalyser({ fftSize: 64, smoothing: 0.8 });
+    if (analyser) {
+      analyserRef.current = analyser;
+      // Pre-allocate data array
+      dataArrayRef.current = new Uint8Array(analyser.frequencyBinCount);
     }
 
     return () => {
-      audioElement.removeEventListener('play', handlePlay);
+      if (analyserRef.current) {
+        sharedAudio.disconnectAnalyser(analyserRef.current);
+        analyserRef.current = null;
+        dataArrayRef.current = null;
+      }
     };
-  }, [audioElement, cleanup]);
+  }, [sharedAudio.sourceNode, sharedAudio.createAnalyser, sharedAudio.disconnectAnalyser]);
 
   // Animation loop
   useEffect(() => {
-    if (!isPlaying || !analyserRef.current) {
+    if (!isPlaying || !analyserRef.current || !dataArrayRef.current) {
       cleanup();
       setFrequencies(new Array(barCount).fill(0));
       return;
     }
 
     const analyser = analyserRef.current;
-    const dataArray = new Uint8Array(analyser.frequencyBinCount);
+    const dataArray = dataArrayRef.current;
 
     const animate = () => {
-      analyser.getByteFrequencyData(dataArray);
+      analyser.getByteFrequencyData(dataArray as Uint8Array<ArrayBuffer>);
 
       const step = Math.floor(dataArray.length / barCount);
       const newFrequencies: number[] = [];

package/src/tools/AudioPlayer/{AudioPlayer.tsx → components/AudioPlayer.tsx}

@@ -18,24 +18,15 @@ import {
   Volume2,
   VolumeX,
   Loader2,
+  Repeat,
 } from 'lucide-react';
 import { Button, Slider, cn } from '@djangocfg/ui-nextjs';
-import { useAudio } from './context';
+import { useAudio } from '../context';
 import { AudioEqualizer } from './AudioEqualizer';
-import { useAudioHotkeys } from './useAudioHotkeys';
+import { useAudioHotkeys } from '../hooks';
 import { AudioShortcutsPopover } from './AudioShortcutsPopover';
-import type { AudioPlayerProps } from './types';
-
-// =============================================================================
-// HELPERS
-// =============================================================================
-
-function formatTime(seconds: number): string {
-  if (!seconds || !isFinite(seconds) || seconds < 0) return '0:00';
-  const mins = Math.floor(seconds / 60);
-  const secs = Math.floor(seconds % 60);
-  return `${mins}:${secs.toString().padStart(2, '0')}`;
-}
+import { formatTime } from '../utils';
+import type { AudioPlayerProps } from '../types';
 
 // =============================================================================
 // COMPONENT
@@ -49,6 +40,7 @@ export const AudioPlayer = forwardRef<HTMLDivElement, AudioPlayerProps>(
       showEqualizer = false,
       showTimer = true,
       showVolume = true,
+      showLoop = true,
       equalizerOptions = {},
       className,
       style,
@@ -63,11 +55,13 @@ export const AudioPlayer = forwardRef<HTMLDivElement, AudioPlayerProps>(
       duration,
       volume,
       isMuted,
+      isLooping,
       togglePlay,
       restart,
       skip,
       setVolume,
       toggleMute,
+      toggleLoop,
     } = useAudio();
 
     // Enable keyboard shortcuts
@@ -211,6 +205,20 @@ export const AudioPlayer = forwardRef<HTMLDivElement, AudioPlayerProps>(
               </>
             )}
 
+            {/* Loop/Repeat */}
+            {showLoop && (
+              <Button
+                variant="ghost"
+                size="icon"
+                className={cn('h-9 w-9', isLooping && 'text-primary')}
+                onClick={toggleLoop}
+                disabled={!isReady}
+                title={isLooping ? 'Disable loop' : 'Enable loop'}
+              >
+                <Repeat className="h-4 w-4" />
+              </Button>
+            )}
+
             {/* Shortcuts help */}
             <AudioShortcutsPopover compact />
           </div>

package/src/tools/AudioPlayer/{AudioShortcutsPopover.tsx → components/AudioShortcutsPopover.tsx}

@@ -19,10 +19,10 @@ import {
   TooltipContent,
 } from '@djangocfg/ui-nextjs';
 import { Keyboard } from 'lucide-react';
-import { AUDIO_SHORTCUTS } from './useAudioHotkeys';
+import { AUDIO_SHORTCUTS } from '../hooks';
 
 // =============================================================================
-// COMPONENT
+// TYPES
 // =============================================================================
 
 interface AudioShortcutsPopoverProps {
@@ -30,6 +30,10 @@ interface AudioShortcutsPopoverProps {
   compact?: boolean;
 }
 
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
 export function AudioShortcutsPopover({ compact = false }: AudioShortcutsPopoverProps) {
   const trigger = (
     <PopoverTrigger asChild>

package/src/tools/AudioPlayer/components/ReactiveCover/AudioReactiveCover.tsx

@@ -0,0 +1,147 @@
+'use client';
+
+/**
+ * AudioReactiveCover - Album art with audio-reactive animations
+ *
+ * Uses effects utilities for clean data preparation before render.
+ * Click on cover to switch between effect variants.
+ *
+ * Audio analysis is performed in the AudioProvider context to persist
+ * across variant changes (including switching to 'none' and back).
+ */
+
+import { type ReactNode } from 'react';
+import { cn } from '@djangocfg/ui-nextjs';
+import { useAudioElement } from '../../context';
+import {
+  type EffectVariant,
+  type EffectIntensity,
+  type EffectColorScheme,
+  getEffectConfig,
+  prepareEffectColors,
+  calculateGlowLayers,
+  calculateOrbs,
+  calculateMeshGradients,
+  calculateSpotlight,
+  EFFECT_ANIMATIONS,
+} from '../../effects';
+import { GlowEffect, OrbsEffect, SpotlightEffect, MeshEffect, type GlowEffectData } from './effects';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface AudioReactiveCoverProps {
+  children: ReactNode;
+  size?: 'sm' | 'md' | 'lg';
+  variant?: EffectVariant;
+  intensity?: EffectIntensity;
+  colorScheme?: EffectColorScheme;
+  onClick?: () => void;
+  className?: string;
+}
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const SIZES = {
+  sm: { container: 'w-32 h-32', orbBase: 40 },
+  md: { container: 'w-40 h-40', orbBase: 50 },
+  lg: { container: 'w-48 h-48', orbBase: 60 },
+};
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export function AudioReactiveCover({
+  children,
+  size = 'lg',
+  variant = 'spotlight',
+  intensity = 'medium',
+  colorScheme = 'primary',
+  onClick,
+  className,
+}: AudioReactiveCoverProps) {
+  // Get audio levels from context (persists across variant changes)
+  const { isPlaying, audioLevels: levels } = useAudioElement();
+
+  // =========================================================================
+  // PREPARE DATA BEFORE RENDER
+  // =========================================================================
+
+  const sizeConfig = SIZES[size];
+  const effectConfig = getEffectConfig(intensity);
+  const { colors, hueShift } = prepareEffectColors(colorScheme, levels);
+
+  // Calculate scale based on overall level
+  const containerScale = 1 + levels.overall * effectConfig.scale;
+
+  // Prepare effect-specific data - NO memoization for real-time reactivity
+  const glowData: GlowEffectData | null = variant === 'glow' ? {
+    layers: calculateGlowLayers(levels, effectConfig, colors),
+    hueShift,
+    showPulseRings: levels.bass > 0.5,
+    showSparkle: levels.high > 0.4,
+  } : null;
+
+  const orbsData = variant === 'orbs'
+    ? calculateOrbs(levels, effectConfig, colors, sizeConfig.orbBase)
+    : null;
+
+  const meshData = variant === 'mesh'
+    ? calculateMeshGradients(levels, effectConfig, colors)
+    : null;
+
+  const spotlightData = variant === 'spotlight'
+    ? calculateSpotlight(levels, effectConfig, colors, levels.mid * 360)
+    : null;
+
+  // =========================================================================
+  // RENDER
+  // =========================================================================
+
+  return (
+    <div
+      className={cn('relative', sizeConfig.container, className)}
+      style={{
+        transform: `scale(${containerScale})`,
+        transition: 'transform 0.1s ease-out',
+      }}
+    >
+      {/* Effect layers */}
+      {glowData && (
+        <GlowEffect data={glowData} colors={colors} isPlaying={isPlaying} />
+      )}
+
+      {orbsData && (
+        <OrbsEffect orbs={orbsData} blur={effectConfig.blur} isPlaying={isPlaying} />
+      )}
+
+      {spotlightData && (
+        <SpotlightEffect data={spotlightData} colors={colors} blur={effectConfig.blur} isPlaying={isPlaying} />
+      )}
+
+      {meshData && (
+        <MeshEffect gradients={meshData} blur={effectConfig.blur} isPlaying={isPlaying} />
+      )}
+
+      {/* Content (cover art) */}
+      <div
+        className="relative w-full h-full rounded-lg overflow-hidden shadow-2xl z-10 bg-background cursor-pointer"
+        onClick={onClick}
+        role={onClick ? 'button' : undefined}
+        tabIndex={onClick ? 0 : undefined}
+        onKeyDown={onClick ? (e) => e.key === 'Enter' && onClick() : undefined}
+      >
+        {children}
+      </div>
+
+      {/* Inject animations once */}
+      <style dangerouslySetInnerHTML={{ __html: EFFECT_ANIMATIONS }} />
+    </div>
+  );
+}
+
+export default AudioReactiveCover;