@djangocfg/ui-nextjs 2.1.66 → 2.1.68

package/src/tools/AudioPlayer/@refactoring/05-EFFECTS.md

@@ -0,0 +1,427 @@
+# Phase 6: Effects Refactoring
+
+## Source: `effects/index.ts` (413 lines)
+
+Split into 3 files by concern.
+
+---
+
+## `effects/constants.ts`
+
+Configuration constants (~60 lines).
+
+```typescript
+import type { EffectIntensity, EffectColorScheme, EffectConfig } from '../types';
+
+// =============================================================================
+// INTENSITY CONFIGURATION
+// =============================================================================
+
+export const INTENSITY_CONFIG: Record<EffectIntensity, EffectConfig> = {
+  subtle: { opacity: 0.3, scale: 0.02, blur: 'blur-2xl' },
+  medium: { opacity: 0.5, scale: 0.04, blur: 'blur-xl' },
+  strong: { opacity: 0.7, scale: 0.06, blur: 'blur-lg' },
+};
+
+// =============================================================================
+// COLOR SCHEMES
+// =============================================================================
+
+export const COLOR_SCHEMES: Record<EffectColorScheme, string[]> = {
+  primary: ['217 91% 60%'],
+  vibrant: ['217 91% 60%', '142 76% 36%', '262 83% 58%', '25 95% 53%'],
+  cool: ['217 91% 60%', '262 83% 58%', '199 89% 48%'],
+  warm: ['25 95% 53%', '0 84% 60%', '38 92% 50%'],
+};
+
+// Default multi-color palette
+export const DEFAULT_GLOW_COLORS = [
+  '217 91% 60%',  // Blue
+  '262 83% 58%',  // Purple
+  '330 81% 60%',  // Pink
+  '25 95% 53%',   // Orange
+];
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+export function getEffectConfig(intensity: EffectIntensity): EffectConfig {
+  return INTENSITY_CONFIG[intensity];
+}
+
+export function getColors(colorScheme: EffectColorScheme): string[] {
+  return COLOR_SCHEMES[colorScheme];
+}
+```
+
+---
+
+## `effects/calculations.ts`
+
+Effect calculation functions (~250 lines).
+
+```typescript
+import type {
+  AudioLevels,
+  EffectConfig,
+  EffectColors,
+  EffectLayer,
+  Orb,
+  MeshGradient,
+  SpotlightData,
+  EffectColorScheme,
+} from '../types';
+import { COLOR_SCHEMES, DEFAULT_GLOW_COLORS } from './constants';
+
+// =============================================================================
+// PREPARE EFFECT COLORS
+// =============================================================================
+
+export function prepareEffectColors(
+  colorScheme: EffectColorScheme,
+  levels: AudioLevels
+): EffectColors {
+  const baseColors = COLOR_SCHEMES[colorScheme];
+  const colors = baseColors.length > 1 ? baseColors : DEFAULT_GLOW_COLORS;
+  const hueShift = Math.floor(
+    (levels.bass * 30) + (levels.mid * 20) + (levels.high * 10)
+  );
+
+  return { colors, hueShift };
+}
+
+// =============================================================================
+// GLOW LAYERS
+// =============================================================================
+
+export function calculateGlowLayers(
+  levels: AudioLevels,
+  config: EffectConfig,
+  colors: string[]
+): EffectLayer[] {
+  const { bass, mid, high } = levels;
+
+  return [
+    // Layer 1: Bass glow - bottom
+    {
+      inset: 60 + bass * 90,
+      opacity: 1,
+      scale: 1 + bass * 0.5,
+      background: `radial-gradient(ellipse 80% 60% at 50% 100%, hsl(${colors[0]} / ${0.4 + bass * 0.4}) 0%, transparent 70%)`,
+      blur: 'blur-3xl',
+    },
+    // Layer 2: Mid glow - top
+    {
+      inset: 45 + mid * 75,
+      opacity: 1,
+      scale: 1 + mid * 0.4,
+      background: `radial-gradient(ellipse 70% 50% at 50% 0%, hsl(${colors[1] || colors[0]} / ${0.3 + mid * 0.5}) 0%, transparent 70%)`,
+      blur: 'blur-2xl',
+    },
+    // Layer 3: High glow - left
+    {
+      inset: 30 + high * 60,
+      opacity: 1,
+      scale: 1 + high * 0.3,
+      background: `radial-gradient(ellipse 50% 80% at 0% 50%, hsl(${colors[2] || colors[0]} / ${0.3 + high * 0.4}) 0%, transparent 60%)`,
+      blur: 'blur-2xl',
+    },
+    // Layer 4: High glow - right
+    {
+      inset: 30 + high * 60,
+      opacity: 1,
+      scale: 1 + high * 0.3,
+      background: `radial-gradient(ellipse 50% 80% at 100% 50%, hsl(${colors[3] || colors[0]} / ${0.3 + high * 0.4}) 0%, transparent 60%)`,
+      blur: 'blur-2xl',
+    },
+    // Layer 5: Center pulsing glow
+    {
+      inset: 24 + bass * 45,
+      opacity: 1,
+      scale: 1 + bass * 0.2,
+      background: `radial-gradient(circle at 50% 50%, hsl(${colors[0]} / ${0.2 + bass * 0.3}) 0%, hsl(${colors[1] || colors[0]} / ${0.1 + mid * 0.2}) 40%, transparent 70%)`,
+      blur: 'blur-xl',
+      animation: 'glow-breathe 2s ease-in-out infinite',
+    },
+  ];
+}
+
+// =============================================================================
+// ORBS
+// =============================================================================
+
+export function calculateOrbs(
+  levels: AudioLevels,
+  config: EffectConfig,
+  colors: string[],
+  baseSize: number = 50
+): Orb[] {
+  const { bass, mid, high, overall } = levels;
+  const size = baseSize * 3;
+
+  const bassMove = bass * 30;
+  const midMove = mid * 25;
+  const highMove = high * 20;
+
+  return [
+    {
+      x: -40 + bassMove,
+      y: -40 - bassMove * 0.5,
+      size: size * (1 + bass * 1.2),
+      color: colors[0],
+      opacity: 0.5 + bass * 0.5,
+      scale: 1 + bass * 0.6,
+    },
+    {
+      x: 130 - midMove * 0.5,
+      y: -30 + midMove,
+      size: size * (0.9 + mid * 1.0),
+      color: colors[1] || colors[0],
+      opacity: 0.5 + mid * 0.5,
+      scale: 1 + mid * 0.5,
+    },
+    {
+      x: 140 + highMove * 0.3,
+      y: 120 - highMove,
+      size: size * (0.8 + high * 0.8),
+      color: colors[2] || colors[0],
+      opacity: 0.4 + high * 0.6,
+      scale: 1 + high * 0.45,
+    },
+    {
+      x: -30 - midMove * 0.4,
+      y: 130 + midMove * 0.3,
+      size: size * (0.9 + mid * 0.9),
+      color: colors[3] || colors[0],
+      opacity: 0.45 + mid * 0.55,
+      scale: 1 + mid * 0.5,
+    },
+    {
+      x: 50,
+      y: 50,
+      size: size * (0.6 + overall * 1.5),
+      color: colors[0],
+      opacity: 0.3 + overall * 0.5,
+      scale: 1 + overall * 0.7,
+    },
+  ];
+}
+
+// =============================================================================
+// MESH GRADIENTS
+// =============================================================================
+
+export function calculateMeshGradients(
+  levels: AudioLevels,
+  config: EffectConfig,
+  colors: string[]
+): MeshGradient[] {
+  const { bass, mid, high, overall } = levels;
+
+  const bassOffset = bass * 40;
+  const midOffset = mid * 30;
+  const highOffset = high * 25;
+
+  return [
+    {
+      width: `${200 + bass * 150}%`,
+      height: `${200 + bass * 150}%`,
+      top: `${-80 + bassOffset}%`,
+      right: `${-80 - bassOffset}%`,
+      color: colors[0],
+      opacity: 0.4 + bass * 0.6,
+      scale: 1 + bass * 0.5,
+      rotation: bass * 45,
+      blur: 'blur-2xl',
+    },
+    {
+      width: `${180 + mid * 120}%`,
+      height: `${180 + mid * 120}%`,
+      bottom: `${-60 + midOffset}%`,
+      left: `${-60 - midOffset}%`,
+      color: colors[1] || colors[0],
+      opacity: 0.4 + mid * 0.6,
+      scale: 1 + mid * 0.4,
+      rotation: -mid * 40,
+      blur: 'blur-2xl',
+    },
+    {
+      width: `${140 + high * 100}%`,
+      height: `${140 + high * 100}%`,
+      top: `${70 - highOffset}%`,
+      right: `${-50 + highOffset}%`,
+      color: colors[2] || colors[0],
+      opacity: 0.35 + high * 0.65,
+      scale: 1 + high * 0.35,
+      rotation: high * 35,
+      blur: 'blur-xl',
+    },
+    {
+      width: `${160 + bass * 140}%`,
+      height: `${160 + bass * 140}%`,
+      top: `${-60 - bassOffset * 0.8}%`,
+      left: `${-60 + bassOffset * 0.8}%`,
+      color: colors[3] || colors[1] || colors[0],
+      opacity: 0.35 + bass * 0.65,
+      scale: 1 + bass * 0.55,
+      rotation: -bass * 50,
+      blur: 'blur-2xl',
+    },
+    {
+      width: `${80 + overall * 150}%`,
+      height: `${80 + overall * 150}%`,
+      top: '50%',
+      left: '50%',
+      color: colors[0],
+      opacity: 0.3 + overall * 0.5,
+      scale: 1 + overall * 0.4,
+      rotation: 0,
+      isCenter: true,
+      blur: 'blur-3xl',
+    },
+  ];
+}
+
+// =============================================================================
+// SPOTLIGHT
+// =============================================================================
+
+export function calculateSpotlight(
+  levels: AudioLevels,
+  config: EffectConfig,
+  colors: string[],
+  rotation: number
+): SpotlightData {
+  const { bass, mid, high, overall } = levels;
+
+  return {
+    rotation: rotation + mid * 180,
+    inset: 12 + bass * 30,
+    colors: colors.map((c, i) => ({
+      color: c,
+      opacity: i === 0 ? 0.3 + bass * 0.7 : i === 1 ? 0.3 + mid * 0.7 : 0.3 + high * 0.7,
+    })),
+    pulseInset: 24 + bass * 50,
+    pulseOpacity: 0.3 + bass * 0.7,
+    pulseScale: 1 + bass * 0.4,
+    ringOpacity: 0.2 + overall * 0.6,
+    ringScale: 1 + overall * 0.3,
+  };
+}
+```
+
+---
+
+## `effects/animations.ts`
+
+CSS keyframes (~80 lines).
+
+```typescript
+/**
+ * CSS keyframes for audio-reactive effects.
+ * Injected once via <style> tag.
+ */
+export const EFFECT_ANIMATIONS = `
+  @keyframes spotlight-spin {
+    0% { transform: rotate(0deg); }
+    100% { transform: rotate(360deg); }
+  }
+
+  @keyframes orb-float-1 {
+    0%, 100% { transform: translate(-50%, -50%) translateY(0); }
+    50% { transform: translate(-50%, -50%) translateY(-15px); }
+  }
+
+  @keyframes orb-float-2 {
+    0%, 100% { transform: translate(-50%, -50%) translateX(0); }
+    50% { transform: translate(-50%, -50%) translateX(15px); }
+  }
+
+  @keyframes orb-float-3 {
+    0%, 100% { transform: translate(-50%, -50%) translate(0, 0); }
+    33% { transform: translate(-50%, -50%) translate(10px, -10px); }
+    66% { transform: translate(-50%, -50%) translate(-10px, 10px); }
+  }
+
+  @keyframes orb-float-4 {
+    0%, 100% { transform: translate(-50%, -50%) translate(0, 0); }
+    50% { transform: translate(-50%, -50%) translate(-15px, -10px); }
+  }
+
+  @keyframes mesh-float-1 {
+    0%, 100% { transform: translate(0, 0) scale(1); }
+    25% { transform: translate(-5%, 10%) scale(1.05); }
+    50% { transform: translate(5%, 5%) scale(0.95); }
+    75% { transform: translate(-3%, -5%) scale(1.02); }
+  }
+
+  @keyframes mesh-float-2 {
+    0%, 100% { transform: translate(0, 0) scale(1); }
+    33% { transform: translate(8%, -8%) scale(1.08); }
+    66% { transform: translate(-6%, 6%) scale(0.92); }
+  }
+
+  @keyframes mesh-float-3 {
+    0%, 100% { transform: translate(0, 0) scale(1); }
+    50% { transform: translate(10%, 10%) scale(1.1); }
+  }
+
+  @keyframes mesh-float-4 {
+    0%, 100% { transform: translate(0, 0) scale(1) rotate(0deg); }
+    25% { transform: translate(10%, -5%) scale(1.1) rotate(5deg); }
+    50% { transform: translate(-5%, 10%) scale(0.95) rotate(-5deg); }
+    75% { transform: translate(-10%, -10%) scale(1.05) rotate(3deg); }
+  }
+
+  @keyframes mesh-pulse {
+    0%, 100% { transform: translate(-50%, -50%) scale(1); opacity: 0.3; }
+    50% { transform: translate(-50%, -50%) scale(1.2); opacity: 0.5; }
+  }
+
+  @keyframes glow-breathe {
+    0%, 100% { opacity: 0.6; transform: scale(1); }
+    50% { opacity: 1; transform: scale(1.05); }
+  }
+
+  @keyframes glow-rotate {
+    0% { transform: rotate(0deg); }
+    100% { transform: rotate(360deg); }
+  }
+
+  @keyframes sparkle-move {
+    0% { opacity: 0; transform: scale(0.8); }
+    50% { opacity: 1; }
+    100% { opacity: 0; transform: scale(1.2); }
+  }
+`;
+```
+
+---
+
+## `effects/index.ts`
+
+Re-export all.
+
+```typescript
+// Constants
+export {
+  INTENSITY_CONFIG,
+  COLOR_SCHEMES,
+  DEFAULT_GLOW_COLORS,
+  getEffectConfig,
+  getColors,
+} from './constants';
+
+// Calculations
+export {
+  prepareEffectColors,
+  calculateGlowLayers,
+  calculateOrbs,
+  calculateMeshGradients,
+  calculateSpotlight,
+} from './calculations';
+
+// Animations
+export { EFFECT_ANIMATIONS } from './animations';
+```

package/src/tools/AudioPlayer/@refactoring/06-UTILS-AND-INDEX.md

@@ -0,0 +1,193 @@
+# Phase 7-8: Utils and Main Index
+
+## `utils/formatTime.ts`
+
+Extract from `AudioPlayer.tsx`.
+
+```typescript
+/**
+ * Format seconds to mm:ss display format.
+ */
+export 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')}`;
+}
+```
+
+---
+
+## `utils/index.ts`
+
+```typescript
+export { formatTime } from './formatTime';
+```
+
+---
+
+## Main `index.ts` (Final Public API)
+
+```typescript
+/**
+ * AudioPlayer - Audio playback with waveform visualization
+ *
+ * Built on WaveSurfer.js with audio-reactive effects
+ */
+
+// =============================================================================
+// COMPONENTS
+// =============================================================================
+
+// Simple wrapper (recommended)
+export { SimpleAudioPlayer } from './components';
+export type { SimpleAudioPlayerProps } from './components';
+
+// Core components
+export { AudioPlayer } from './components';
+export { AudioEqualizer } from './components';
+export { AudioReactiveCover } from './components';
+export { AudioShortcutsPopover } from './components';
+export { VisualizationToggle } from './components';
+
+// =============================================================================
+// CONTEXT & HOOKS
+// =============================================================================
+
+// Provider and hooks
+export {
+  AudioProvider,
+  useAudio,
+  useAudioControls,
+  useAudioState,
+  useAudioElement,
+} from './context';
+
+// Hotkeys
+export { useAudioHotkeys, AUDIO_SHORTCUTS } from './hooks';
+
+// Visualization settings
+export {
+  useAudioVisualization,
+  VisualizationProvider,
+  VARIANT_INFO,
+  INTENSITY_INFO,
+  COLOR_SCHEME_INFO,
+} from './hooks';
+
+// =============================================================================
+// EFFECTS
+// =============================================================================
+
+export {
+  INTENSITY_CONFIG,
+  COLOR_SCHEMES,
+  getEffectConfig,
+  getColors,
+  prepareEffectColors,
+  calculateGlowLayers,
+  calculateOrbs,
+  calculateMeshGradients,
+  calculateSpotlight,
+  EFFECT_ANIMATIONS,
+} from './effects';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type {
+  // Audio types
+  AudioSource,
+  PlaybackStatus,
+  WaveformOptions,
+  EqualizerOptions,
+  SharedWebAudioContext,
+  AudioContextState,
+  // Component props
+  AudioPlayerProps,
+  AudioEqualizerProps,
+  AudioReactiveCoverProps,
+  AudioViewerProps,
+  // Effect types
+  EffectVariant,
+  EffectIntensity,
+  EffectColorScheme,
+  AudioLevels,
+  EffectConfig,
+  EffectColors,
+  EffectLayer,
+} from './types';
+
+// Visualization types
+export type {
+  VisualizationSettings,
+  VisualizationVariant,
+  VisualizationIntensity,
+  VisualizationColorScheme,
+  UseAudioVisualizationReturn,
+  VisualizationProviderProps,
+} from './hooks';
+
+// Hotkey types
+export type {
+  AudioHotkeyOptions,
+  ShortcutItem,
+  ShortcutGroup,
+} from './hooks';
+```
+
+---
+
+## Folder Structure Summary
+
+After refactoring:
+
+```
+AudioPlayer/
+├── index.ts                          # ~80 lines (exports only)
+│
+├── types/
+│   ├── index.ts                      # ~30 lines
+│   ├── audio.ts                      # ~80 lines
+│   ├── components.ts                 # ~50 lines
+│   └── effects.ts                    # ~60 lines
+│
+├── hooks/
+│   ├── index.ts                      # ~30 lines
+│   ├── useSharedWebAudio.ts          # ~90 lines
+│   ├── useAudioAnalysis.ts           # ~100 lines
+│   ├── useAudioHotkeys.ts            # ~150 lines
+│   └── useVisualization.tsx          # ~200 lines
+│
+├── context/
+│   ├── index.ts                      # ~5 lines
+│   ├── AudioProvider.tsx             # ~180 lines
+│   └── selectors.ts                  # ~60 lines
+│
+├── components/
+│   ├── index.ts                      # ~15 lines
+│   ├── AudioPlayer.tsx               # ~200 lines
+│   ├── AudioEqualizer.tsx            # ~200 lines
+│   ├── SimpleAudioPlayer.tsx         # ~280 lines
+│   ├── ShortcutsPopover.tsx          # ~95 lines
+│   ├── VisualizationToggle.tsx       # ~70 lines
+│   └── ReactiveCover/
+│       ├── index.tsx                 # ~100 lines
+│       ├── GlowEffect.tsx            # ~80 lines
+│       ├── OrbsEffect.tsx            # ~40 lines
+│       ├── SpotlightEffect.tsx       # ~60 lines
+│       └── MeshEffect.tsx            # ~50 lines
+│
+├── effects/
+│   ├── index.ts                      # ~20 lines
+│   ├── constants.ts                  # ~50 lines
+│   ├── calculations.ts               # ~250 lines
+│   └── animations.ts                 # ~80 lines
+│
+└── utils/
+    ├── index.ts                      # ~3 lines
+    └── formatTime.ts                 # ~10 lines
+
+Total: ~23 files, avg ~85 lines per file (vs current 12 files, avg ~240 lines)
+```