@djangocfg/ui-nextjs 2.1.65 → 2.1.67

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

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

package/src/tools/AudioPlayer/@refactoring/04-COMPONENTS.md

@@ -0,0 +1,251 @@
+# Phase 5: Components Reorganization
+
+## Overview
+
+Move all components to `components/` folder and split `AudioReactiveCover` into subcomponents.
+
+---
+
+## Files to Move (with import updates)
+
+| Current | New Location | Changes |
+|---------|--------------|---------|
+| `AudioPlayer.tsx` | `components/AudioPlayer.tsx` | Update imports |
+| `AudioEqualizer.tsx` | `components/AudioEqualizer.tsx` | Update imports |
+| `SimpleAudioPlayer.tsx` | `components/SimpleAudioPlayer.tsx` | Update imports |
+| `AudioShortcutsPopover.tsx` | `components/ShortcutsPopover.tsx` | Rename + update imports |
+| `VisualizationToggle.tsx` | `components/VisualizationToggle.tsx` | Update imports |
+
+---
+
+## `AudioReactiveCover` Split
+
+Current: 390 lines with 4 inline effect components.
+
+### `components/ReactiveCover/index.tsx`
+
+Main component (~100 lines).
+
+```typescript
+'use client';
+
+import { type ReactNode } from 'react';
+import { cn } from '@djangocfg/ui-nextjs';
+import { useAudioElement } from '../../context';
+import {
+  getEffectConfig,
+  prepareEffectColors,
+  EFFECT_ANIMATIONS,
+} from '../../effects';
+import type { EffectVariant, EffectIntensity, EffectColorScheme } from '../../types';
+
+import { GlowEffect } from './GlowEffect';
+import { OrbsEffect } from './OrbsEffect';
+import { SpotlightEffect } from './SpotlightEffect';
+import { MeshEffect } from './MeshEffect';
+
+// ... Props and constants ...
+
+export function AudioReactiveCover({
+  children,
+  size = 'lg',
+  variant = 'spotlight',
+  intensity = 'medium',
+  colorScheme = 'primary',
+  onClick,
+  className,
+}: AudioReactiveCoverProps) {
+  const { isPlaying, audioLevels: levels } = useAudioElement();
+
+  const sizeConfig = SIZES[size];
+  const effectConfig = getEffectConfig(intensity);
+  const { colors, hueShift } = prepareEffectColors(colorScheme, levels);
+  const containerScale = 1 + levels.overall * effectConfig.scale;
+
+  return (
+    <div
+      className={cn('relative', sizeConfig.container, className)}
+      style={{
+        transform: `scale(${containerScale})`,
+        transition: 'transform 0.1s ease-out',
+      }}
+    >
+      {variant === 'glow' && (
+        <GlowEffect
+          levels={levels}
+          config={effectConfig}
+          colors={colors}
+          hueShift={hueShift}
+          isPlaying={isPlaying}
+        />
+      )}
+
+      {variant === 'orbs' && (
+        <OrbsEffect
+          levels={levels}
+          config={effectConfig}
+          colors={colors}
+          baseSize={sizeConfig.orbBase}
+          isPlaying={isPlaying}
+        />
+      )}
+
+      {variant === 'spotlight' && (
+        <SpotlightEffect
+          levels={levels}
+          config={effectConfig}
+          colors={colors}
+          isPlaying={isPlaying}
+        />
+      )}
+
+      {variant === 'mesh' && (
+        <MeshEffect
+          levels={levels}
+          config={effectConfig}
+          colors={colors}
+          isPlaying={isPlaying}
+        />
+      )}
+
+      {/* Content */}
+      <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>
+
+      <style dangerouslySetInnerHTML={{ __html: EFFECT_ANIMATIONS }} />
+    </div>
+  );
+}
+```
+
+### `components/ReactiveCover/GlowEffect.tsx`
+
+```typescript
+'use client';
+
+import { cn } from '@djangocfg/ui-nextjs';
+import { calculateGlowLayers } from '../../effects';
+import type { AudioLevels, EffectConfig } from '../../types';
+
+interface GlowEffectProps {
+  levels: AudioLevels;
+  config: EffectConfig;
+  colors: string[];
+  hueShift: number;
+  isPlaying: boolean;
+}
+
+export function GlowEffect({ levels, config, colors, hueShift, isPlaying }: GlowEffectProps) {
+  const layers = calculateGlowLayers(levels, config, colors);
+  const showPulseRings = levels.bass > 0.5;
+  const showSparkle = levels.high > 0.4;
+
+  return (
+    <>
+      {/* Main glow layers */}
+      {layers.map((layer, i) => (
+        <div
+          key={i}
+          className={cn('absolute rounded-2xl -z-10', layer.blur)}
+          style={{
+            inset: `-${layer.inset}px`,
+            background: layer.background,
+            opacity: isPlaying ? layer.opacity : 0,
+            transform: i < 2 ? `scaleY(${layer.scale})` : `scale(${layer.scale})`,
+            animation: isPlaying && layer.animation ? layer.animation : 'none',
+            transition: 'opacity 0.3s',
+          }}
+        />
+      ))}
+
+      {/* Rotating color sweep */}
+      <div
+        className="absolute rounded-2xl blur-xl overflow-hidden -z-10"
+        style={{
+          inset: '-75px',
+          opacity: isPlaying ? 0.6 : 0,
+          transition: 'opacity 0.5s',
+        }}
+      >
+        <div
+          className="absolute inset-0"
+          style={{
+            background: `conic-gradient(
+              from ${hueShift}deg at 50% 50%,
+              hsl(${colors[0]} / 0.4) 0deg,
+              hsl(${colors[1] || colors[0]} / 0.3) 90deg,
+              hsl(${colors[2] || colors[0]} / 0.3) 180deg,
+              hsl(${colors[3] || colors[0]} / 0.3) 270deg,
+              hsl(${colors[0]} / 0.4) 360deg
+            )`,
+            animation: isPlaying ? 'glow-rotate 6s linear infinite' : 'none',
+          }}
+        />
+      </div>
+
+      {/* Pulse rings on bass hits */}
+      {showPulseRings && (
+        <>
+          <div
+            className="absolute -inset-6 rounded-xl border-2 animate-ping -z-10"
+            style={{
+              borderColor: `hsl(${colors[0]} / 0.4)`,
+              animationDuration: '1s',
+            }}
+          />
+          <div
+            className="absolute -inset-12 rounded-2xl border animate-ping -z-10"
+            style={{
+              borderColor: `hsl(${colors[1] || colors[0]} / 0.3)`,
+              animationDuration: '1.5s',
+              animationDelay: '0.2s',
+            }}
+          />
+        </>
+      )}
+
+      {/* Sparkle on high frequencies */}
+      {showSparkle && (
+        <div
+          className="absolute -inset-18 rounded-3xl -z-10"
+          style={{
+            background: `radial-gradient(circle at 50% 30%, hsl(${colors[2] || colors[0]} / 0.5) 0%, transparent 30%)`,
+            animation: 'sparkle-move 0.5s ease-out',
+          }}
+        />
+      )}
+    </>
+  );
+}
+```
+
+### Similar split for:
+- `components/ReactiveCover/OrbsEffect.tsx`
+- `components/ReactiveCover/SpotlightEffect.tsx`
+- `components/ReactiveCover/MeshEffect.tsx`
+
+---
+
+## `components/index.ts`
+
+```typescript
+// Main components
+export { AudioPlayer } from './AudioPlayer';
+export { AudioEqualizer } from './AudioEqualizer';
+export { SimpleAudioPlayer } from './SimpleAudioPlayer';
+export type { SimpleAudioPlayerProps } from './SimpleAudioPlayer';
+
+// ReactiveCover
+export { AudioReactiveCover } from './ReactiveCover';
+
+// UI components
+export { ShortcutsPopover as AudioShortcutsPopover } from './ShortcutsPopover';
+export { VisualizationToggle } from './VisualizationToggle';
+```