@djangocfg/ui-nextjs 2.1.65 → 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

@@ -0,0 +1,325 @@
+# AudioPlayer
+
+Audio player with waveform visualization, built on WaveSurfer.js.
+
+## Features
+
+- Waveform visualization with interactive seeking
+- Audio-reactive cover effects (glow, orbs, spotlight, mesh)
+- Real-time frequency equalizer
+- Keyboard shortcuts
+- Volume control with mute
+- Skip forward/backward
+- Playback speed control
+
+## Quick Start (Recommended)
+
+```tsx
+import { SimpleAudioPlayer } from '@djangocfg/ui-nextjs';
+
+// Minimal
+<SimpleAudioPlayer src="https://example.com/audio.mp3" />
+
+// With metadata
+<SimpleAudioPlayer
+  src={audioUrl}
+  title="Track Title"
+  artist="Artist Name"
+  coverArt="/path/to/cover.jpg"
+/>
+
+// Full customization
+<SimpleAudioPlayer
+  src={audioUrl}
+  title="Track Title"
+  coverArt={coverUrl}
+  showWaveform
+  showEqualizer={false}
+  reactiveCover
+  variant="spotlight"
+  layout="horizontal"
+/>
+```
+
+### SimpleAudioPlayer Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | required | Audio URL |
+| `title` | `string` | - | Track title |
+| `artist` | `string` | - | Artist name |
+| `coverArt` | `string \| ReactNode` | - | Cover image URL or custom element |
+| `coverSize` | `'sm' \| 'md' \| 'lg'` | `'md'` | Cover art size |
+| `showWaveform` | `boolean` | `true` | Show waveform |
+| `showEqualizer` | `boolean` | `false` | Show equalizer bars |
+| `showTimer` | `boolean` | `true` | Show time display |
+| `showVolume` | `boolean` | `true` | Show volume control |
+| `reactiveCover` | `boolean` | `true` | Enable reactive effects |
+| `variant` | `VisualizationVariant` | - | Effect variant |
+| `intensity` | `EffectIntensity` | - | Effect intensity |
+| `colorScheme` | `EffectColorScheme` | - | Effect colors |
+| `autoPlay` | `boolean` | `false` | Auto-play on load |
+| `layout` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction |
+
+---
+
+## Advanced Usage
+
+For full control, use `AudioProvider` + `AudioPlayer` directly:
+
+```tsx
+import { useRef } from 'react';
+import { AudioProvider, AudioPlayer } from '@djangocfg/ui-nextjs';
+
+function MyAudioPlayer({ audioUrl }: { audioUrl: string }) {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  return (
+    <AudioProvider
+      source={{ uri: audioUrl }}
+      containerRef={containerRef}
+    >
+      <AudioPlayer
+        ref={containerRef}
+        showControls
+        showWaveform
+        showTimer
+        showVolume
+      />
+    </AudioProvider>
+  );
+}
+```
+
+## Components
+
+### AudioProvider
+
+Context provider for audio state. Wraps all audio components.
+
+```tsx
+<AudioProvider
+  source={{ uri: 'https://example.com/audio.mp3' }}
+  containerRef={containerRef}
+  autoPlay={false}
+  waveformOptions={{
+    waveColor: 'hsl(217 91% 60% / 0.3)',
+    progressColor: 'hsl(217 91% 60%)',
+    height: 64,
+    barWidth: 3,
+    barRadius: 3,
+    barGap: 2,
+  }}
+>
+  {children}
+</AudioProvider>
+```
+
+### AudioPlayer
+
+Main player component with waveform and controls.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `showControls` | `boolean` | `true` | Show playback controls |
+| `showWaveform` | `boolean` | `true` | Show waveform visualization |
+| `showEqualizer` | `boolean` | `false` | Show equalizer animation |
+| `showTimer` | `boolean` | `true` | Show time display |
+| `showVolume` | `boolean` | `true` | Show volume slider |
+| `className` | `string` | - | Additional CSS class |
+
+### AudioEqualizer
+
+Real-time frequency visualizer with animated bars.
+
+```tsx
+<AudioEqualizer
+  barCount={24}
+  height={48}
+  gap={2}
+  showPeaks
+  barColor="hsl(217 91% 60%)"
+  peakColor="hsl(217 91% 70%)"
+/>
+```
+
+### AudioReactiveCover
+
+Album art wrapper with audio-reactive effects.
+
+```tsx
+<AudioReactiveCover
+  variant="spotlight"  // 'glow' | 'orbs' | 'spotlight' | 'mesh'
+  intensity="medium"   // 'subtle' | 'medium' | 'strong'
+  colorScheme="primary" // 'primary' | 'vibrant' | 'cool' | 'warm'
+  onClick={() => nextVariant()}
+>
+  <img src={coverArt} alt="Album cover" />
+</AudioReactiveCover>
+```
+
+### VisualizationToggle
+
+Button to cycle through visualization variants.
+
+```tsx
+<VisualizationToggle compact />
+```
+
+## Hooks
+
+### useAudio
+
+Access full audio state and controls.
+
+```tsx
+const {
+  isReady,
+  isPlaying,
+  currentTime,
+  duration,
+  volume,
+  isMuted,
+  audioLevels,  // { bass, mid, high, overall }
+  play,
+  pause,
+  togglePlay,
+  seek,
+  seekTo,
+  skip,
+  setVolume,
+  toggleMute,
+  restart,
+} = useAudio();
+```
+
+### useAudioControls
+
+Controls only (no re-render on time updates).
+
+```tsx
+const { play, pause, togglePlay, skip, restart } = useAudioControls();
+```
+
+### useAudioState
+
+Read-only playback state.
+
+```tsx
+const { isPlaying, currentTime, duration, volume } = useAudioState();
+```
+
+### useAudioElement
+
+Access audio element for custom visualizations.
+
+```tsx
+const { audioElement, isPlaying, audioLevels } = useAudioElement();
+```
+
+### useAudioVisualization
+
+Manage visualization settings (persisted in localStorage).
+
+```tsx
+const {
+  settings,      // { enabled, variant, intensity, colorScheme }
+  toggle,
+  setSetting,
+  nextVariant,
+  nextIntensity,
+  nextColorScheme,
+  reset,
+} = useAudioVisualization();
+```
+
+### useAudioHotkeys
+
+Enable keyboard shortcuts.
+
+```tsx
+useAudioHotkeys({
+  enabled: true,
+  skipDuration: 10,
+  volumeStep: 0.1,
+});
+```
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `Space` | Play/Pause |
+| `←` / `J` | Skip 10s backward |
+| `→` / `L` | Skip 10s forward |
+| `↑` | Volume up |
+| `↓` | Volume down |
+| `M` | Mute/Unmute |
+| `0-9` | Jump to 0-90% |
+
+## Waveform Options
+
+```typescript
+interface WaveformOptions {
+  waveColor?: string;      // Unplayed wave color
+  progressColor?: string;  // Played wave color
+  cursorColor?: string;    // Playhead cursor color
+  cursorWidth?: number;    // Cursor width in px
+  height?: number;         // Waveform height in px
+  barWidth?: number;       // Bar width in px
+  barRadius?: number;      // Bar corner radius
+  barGap?: number;         // Gap between bars
+}
+```
+
+## Effect Variants
+
+| Variant | Description |
+|---------|-------------|
+| `spotlight` | Rotating conic gradient with bass pulse |
+| `glow` | Multi-layered radial glows from edges |
+| `orbs` | Floating orbs that react to frequencies |
+| `mesh` | Large gradient blobs with movement |
+| `none` | Effects disabled |
+
+## Architecture
+
+```
+AudioPlayer/
+├── 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
+```

package/src/tools/AudioPlayer/components/AudioEqualizer.tsx

@@ -0,0 +1,200 @@
+'use client';
+
+/**
+ * AudioEqualizer - Real-time frequency visualizer with animated bars
+ *
+ * Uses shared Web Audio context from AudioProvider for real-time frequency analysis.
+ * This prevents "InvalidStateError" from creating multiple MediaElementSourceNodes.
+ *
+ * Features:
+ * - Real-time frequency visualization
+ * - Configurable number of bars
+ * - 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';
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const DEFAULT_BAR_COUNT = 24;
+const DEFAULT_HEIGHT = 48;
+const DEFAULT_GAP = 2;
+const PEAK_DECAY_RATE = 0.02;
+const PEAK_HOLD_TIME = 500;
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export function AudioEqualizer({
+  barCount = DEFAULT_BAR_COUNT,
+  height = DEFAULT_HEIGHT,
+  gap = DEFAULT_GAP,
+  showPeaks = true,
+  barColor,
+  peakColor,
+  className,
+}: AudioEqualizerProps) {
+  // Get shared audio context from AudioProvider
+  const { sharedAudio, isPlaying } = useAudioElement();
+
+  const [frequencies, setFrequencies] = useState<number[]>(() =>
+    new Array(barCount).fill(0)
+  );
+  const [peaks, setPeaks] = useState<number[]>(() =>
+    new Array(barCount).fill(0)
+  );
+
+  // Refs for analyzer and animation
+  const analyserRef = useRef<AnalyserNode | null>(null);
+  const animationRef = useRef<number | null>(null);
+  const peakTimersRef = useRef<number[]>(new Array(barCount).fill(0));
+  // Pre-allocated buffer for frequency data (prevents allocation per frame)
+  const dataArrayRef = useRef<Uint8Array | null>(null);
+
+  // Cleanup function
+  const cleanup = useCallback(() => {
+    if (animationRef.current) {
+      cancelAnimationFrame(animationRef.current);
+      animationRef.current = null;
+    }
+  }, []);
+
+  // Create analyzer using shared context
+  useEffect(() => {
+    // Wait for shared audio to be ready
+    if (!sharedAudio.sourceNode) {
+      return;
+    }
+
+    // Only create analyzer once
+    if (analyserRef.current) {
+      return;
+    }
+
+    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 () => {
+      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();
+      setFrequencies(new Array(barCount).fill(0));
+      return;
+    }
+
+    const analyser = analyserRef.current;
+    const dataArray = dataArrayRef.current;
+
+    const animate = () => {
+      analyser.getByteFrequencyData(dataArray as Uint8Array<ArrayBuffer>);
+
+      const step = Math.floor(dataArray.length / barCount);
+      const newFrequencies: number[] = [];
+      const newPeaks: number[] = [...peaks];
+      const now = Date.now();
+
+      for (let i = 0; i < barCount; i++) {
+        let sum = 0;
+        for (let j = 0; j < step; j++) {
+          sum += dataArray[i * step + j] || 0;
+        }
+        const value = sum / step / 255;
+        newFrequencies.push(value);
+
+        if (showPeaks) {
+          if (value > newPeaks[i]) {
+            newPeaks[i] = value;
+            peakTimersRef.current[i] = now;
+          } else if (now - peakTimersRef.current[i] > PEAK_HOLD_TIME) {
+            newPeaks[i] = Math.max(0, newPeaks[i] - PEAK_DECAY_RATE);
+          }
+        }
+      }
+
+      setFrequencies(newFrequencies);
+      if (showPeaks) {
+        setPeaks(newPeaks);
+      }
+
+      animationRef.current = requestAnimationFrame(animate);
+    };
+
+    animationRef.current = requestAnimationFrame(animate);
+
+    return cleanup;
+  }, [isPlaying, barCount, showPeaks, cleanup, peaks]);
+
+  // Reset peaks array when barCount changes
+  useEffect(() => {
+    setPeaks(new Array(barCount).fill(0));
+    peakTimersRef.current = new Array(barCount).fill(0);
+  }, [barCount]);
+
+  // Calculate bar width
+  const totalGaps = (barCount - 1) * gap;
+  const barWidth = `calc((100% - ${totalGaps}px) / ${barCount})`;
+
+  return (
+    <div
+      className={cn('relative flex items-end justify-between', className)}
+      style={{ height }}
+    >
+      {frequencies.map((freq, index) => (
+        <div
+          key={index}
+          className="relative flex flex-col justify-end"
+          style={{
+            width: barWidth,
+            height: '100%',
+          }}
+        >
+          {/* Peak indicator */}
+          {showPeaks && peaks[index] > 0.01 && (
+            <div
+              className="absolute w-full transition-all duration-75"
+              style={{
+                height: 2,
+                bottom: `${peaks[index] * 100}%`,
+                backgroundColor: peakColor || 'hsl(217 91% 70%)',
+              }}
+            />
+          )}
+
+          {/* Frequency bar */}
+          <div
+            className="w-full rounded-t-sm transition-all duration-75"
+            style={{
+              height: `${Math.max(freq * 100, 2)}%`,
+              backgroundColor: barColor || 'hsl(217 91% 60%)',
+              opacity: 0.3 + freq * 0.7,
+            }}
+          />
+        </div>
+      ))}
+    </div>
+  );
+}
+
+export default AudioEqualizer;