@djangocfg/ui-nextjs 2.1.82 → 2.1.83

package/src/tools/AudioPlayer/@refactoring/00-PLAN.md

@@ -1,148 +0,0 @@
-# AudioPlayer Refactoring Plan
-
-## Goal
-
-Decompose the AudioPlayer module into a clean, maintainable folder structure with proper separation of concerns.
-
-## Current Issues
-
-1. **`context.tsx` is too large (574 lines)** - contains 4 different hooks and provider
-2. **`types.ts` is monolithic (185 lines)** - mixes audio, component, and effect types
-3. **`effects/index.ts` is overloaded (413 lines)** - types, constants, and calculations together
-4. **`AudioReactiveCover.tsx` has inline effect components** - harder to maintain
-
-## Target Structure
-
-```
-AudioPlayer/
-├── index.ts                      # Public API (re-exports)
-│
-├── types/
-│   ├── index.ts                  # Re-exports all types
-│   ├── audio.ts                  # Core audio types
-│   ├── components.ts             # Component props
-│   └── effects.ts                # Effect-related types
-│
-├── hooks/
-│   ├── index.ts                  # Re-exports all hooks
-│   ├── useSharedWebAudio.ts      # Web Audio API management
-│   ├── useAudioAnalysis.ts       # Frequency analysis
-│   ├── useAudioHotkeys.ts        # Keyboard shortcuts (existing)
-│   └── useVisualization.tsx      # Settings + Provider (renamed)
-│
-├── context/
-│   ├── index.ts                  # Re-exports
-│   ├── AudioProvider.tsx         # Provider component only
-│   └── selectors.ts              # useAudio, useAudioControls, useAudioState, useAudioElement
-│
-├── components/
-│   ├── index.ts                  # Re-exports
-│   ├── AudioPlayer.tsx           # Main player UI
-│   ├── AudioEqualizer.tsx        # Equalizer visualization
-│   ├── SimpleAudioPlayer.tsx     # Easy-to-use wrapper
-│   ├── ShortcutsPopover.tsx      # Keyboard shortcuts popover
-│   ├── VisualizationToggle.tsx   # Effect toggle button
-│   └── ReactiveCover/            # Cover with effects
-│       ├── index.tsx             # Main component
-│       ├── GlowEffect.tsx        # Glow effect
-│       ├── OrbsEffect.tsx        # Orbs effect
-│       ├── SpotlightEffect.tsx   # Spotlight effect
-│       └── MeshEffect.tsx        # Mesh gradient effect
-│
-├── effects/
-│   ├── index.ts                  # Re-exports
-│   ├── constants.ts              # INTENSITY_CONFIG, COLOR_SCHEMES
-│   ├── calculations.ts           # calculateGlowLayers, calculateOrbs, etc.
-│   └── animations.ts             # EFFECT_ANIMATIONS CSS string
-│
-└── utils/
-    ├── index.ts                  # Re-exports
-    └── formatTime.ts             # Time formatting helper
-```
-
-## Migration Steps
-
-### Phase 1: Create folder structure
-- [ ] Create `types/`, `hooks/`, `context/`, `components/`, `effects/`, `utils/` folders
-
-### Phase 2: Split types
-- [ ] Create `types/audio.ts` - AudioSource, PlaybackStatus, SharedWebAudioContext, AudioContextState
-- [ ] Create `types/components.ts` - AudioPlayerProps, AudioEqualizerProps, etc.
-- [ ] Create `types/effects.ts` - EffectVariant, AudioLevels, EffectConfig, etc.
-- [ ] Create `types/index.ts` - re-export all
-
-### Phase 3: Extract hooks from context.tsx
-- [ ] Create `hooks/useSharedWebAudio.ts` - extract from context.tsx
-- [ ] Create `hooks/useAudioAnalysis.ts` - extract from context.tsx
-- [ ] Move `useAudioHotkeys.ts` to `hooks/`
-- [ ] Move `useAudioVisualization.tsx` to `hooks/useVisualization.tsx`
-- [ ] Create `hooks/index.ts`
-
-### Phase 4: Refactor context
-- [ ] Create `context/AudioProvider.tsx` - provider only
-- [ ] Create `context/selectors.ts` - useAudio, useAudioControls, useAudioState, useAudioElement
-- [ ] Create `context/index.ts`
-
-### Phase 5: Reorganize components
-- [ ] Move `AudioPlayer.tsx` to `components/`
-- [ ] Move `AudioEqualizer.tsx` to `components/`
-- [ ] Move `SimpleAudioPlayer.tsx` to `components/`
-- [ ] Rename and move `AudioShortcutsPopover.tsx` to `components/ShortcutsPopover.tsx`
-- [ ] Move `VisualizationToggle.tsx` to `components/`
-- [ ] Split `AudioReactiveCover.tsx` into `components/ReactiveCover/`
-
-### Phase 6: Refactor effects
-- [ ] Create `effects/constants.ts` - INTENSITY_CONFIG, COLOR_SCHEMES
-- [ ] Create `effects/calculations.ts` - all calculate* functions
-- [ ] Create `effects/animations.ts` - EFFECT_ANIMATIONS
-- [ ] Update `effects/index.ts`
-
-### Phase 7: Create utils
-- [ ] Create `utils/formatTime.ts` - extract from AudioPlayer.tsx
-- [ ] Create `utils/index.ts`
-
-### Phase 8: Update main index.ts
-- [ ] Update `index.ts` to re-export from new locations
-- [ ] Ensure backward compatibility of public API
-
-### Phase 9: Cleanup
-- [ ] Delete old files
-- [ ] Run type check
-- [ ] Test imports
-
-## File Size Targets
-
-| File | Current | Target |
-|------|---------|--------|
-| context.tsx | 574 lines | Split into 4 files (~100-150 each) |
-| types.ts | 185 lines | Split into 3 files (~60 each) |
-| effects/index.ts | 413 lines | Split into 3 files (~100-150 each) |
-| AudioReactiveCover.tsx | 390 lines | Split into 5 files (~80 each) |
-
-## Public API (must remain unchanged)
-
-```typescript
-// Components
-export { SimpleAudioPlayer } from './components';
-export { AudioPlayer } from './components';
-export { AudioEqualizer } from './components';
-export { AudioReactiveCover } from './components';
-export { AudioShortcutsPopover } from './components'; // alias for backward compat
-
-// Context & Hooks
-export { AudioProvider, useAudio, useAudioControls, useAudioState, useAudioElement } from './context';
-export { useAudioHotkeys, AUDIO_SHORTCUTS } from './hooks';
-export { useAudioVisualization, VisualizationProvider } from './hooks'; // alias
-
-// Effects utilities
-export { INTENSITY_CONFIG, COLOR_SCHEMES, ... } from './effects';
-
-// Types (all existing types)
-export type { AudioSource, PlaybackStatus, ... } from './types';
-```
-
-## Notes
-
-- Keep backward compatibility for all public exports
-- Internal imports will change but external API stays the same
-- Run `pnpm check` after each phase to catch issues early

package/src/tools/AudioPlayer/@refactoring/01-TYPES.md

@@ -1,301 +0,0 @@
-# Phase 2: Types Split
-
-## Source: `types.ts` (185 lines)
-
-Split into 3 files by domain.
-
----
-
-## `types/audio.ts`
-
-Core audio-related types.
-
-```typescript
-import type WaveSurfer from 'wavesurfer.js';
-import type { AudioLevels } from '../effects';
-
-// =============================================================================
-// AUDIO SOURCE
-// =============================================================================
-
-export interface AudioSource {
-  uri: string;
-}
-
-// =============================================================================
-// PLAYBACK STATE
-// =============================================================================
-
-export interface PlaybackStatus {
-  isLoaded: boolean;
-  isPlaying: boolean;
-  duration: number;
-  currentTime: number;
-  volume: number;
-  isMuted: boolean;
-}
-
-// =============================================================================
-// WAVEFORM OPTIONS
-// =============================================================================
-
-export interface WaveformOptions {
-  waveColor?: string;
-  progressColor?: string;
-  height?: number;
-  barWidth?: number;
-  barRadius?: number;
-  barGap?: number;
-  cursorWidth?: number;
-  cursorColor?: string;
-}
-
-// =============================================================================
-// EQUALIZER OPTIONS
-// =============================================================================
-
-export interface EqualizerOptions {
-  barCount?: number;
-  height?: number;
-  gap?: number;
-  showPeaks?: boolean;
-  barColor?: string;
-  peakColor?: string;
-}
-
-// =============================================================================
-// SHARED WEB AUDIO CONTEXT
-// =============================================================================
-
-export interface SharedWebAudioContext {
-  audioContext: AudioContext | null;
-  sourceNode: MediaElementAudioSourceNode | null;
-  createAnalyser: (options?: { fftSize?: number; smoothing?: number }) => AnalyserNode | null;
-  disconnectAnalyser: (analyser: AnalyserNode) => void;
-}
-
-// =============================================================================
-// AUDIO CONTEXT STATE
-// =============================================================================
-
-export interface AudioContextState {
-  // Core instances
-  wavesurfer: WaveSurfer | null;
-  audioElement: HTMLMediaElement | null;
-  sharedAudio: SharedWebAudioContext;
-
-  // Playback state
-  isReady: boolean;
-  isPlaying: boolean;
-  currentTime: number;
-  duration: number;
-  volume: number;
-  isMuted: boolean;
-  isLooping: boolean;
-
-  // Audio analysis
-  audioLevels: AudioLevels;
-
-  // Actions
-  play: () => Promise<void>;
-  pause: () => void;
-  togglePlay: () => void;
-  seek: (time: number) => void;
-  seekTo: (progress: number) => void;
-  skip: (seconds: number) => void;
-  setVolume: (volume: number) => void;
-  toggleMute: () => void;
-  toggleLoop: () => void;
-  setLoop: (enabled: boolean) => void;
-  restart: () => void;
-}
-```
-
----
-
-## `types/components.ts`
-
-Component props types.
-
-```typescript
-import type { CSSProperties } from 'react';
-import type { WaveformOptions, EqualizerOptions, AudioSource, PlaybackStatus } from './audio';
-
-// =============================================================================
-// AUDIO PLAYER PROPS
-// =============================================================================
-
-export interface AudioPlayerProps {
-  showControls?: boolean;
-  showWaveform?: boolean;
-  showEqualizer?: boolean;
-  showTimer?: boolean;
-  showVolume?: boolean;
-  showLoop?: boolean;
-  waveformOptions?: WaveformOptions;
-  equalizerOptions?: EqualizerOptions;
-  className?: string;
-  style?: CSSProperties;
-}
-
-// =============================================================================
-// AUDIO EQUALIZER PROPS
-// =============================================================================
-
-export interface AudioEqualizerProps {
-  barCount?: number;
-  height?: number;
-  gap?: number;
-  showPeaks?: boolean;
-  barColor?: string;
-  peakColor?: string;
-  className?: string;
-}
-
-// =============================================================================
-// AUDIO REACTIVE COVER PROPS
-// =============================================================================
-
-export interface AudioReactiveCoverProps {
-  variant?: 'glow' | 'orbs' | 'spotlight' | 'mesh';
-  intensity?: 'subtle' | 'medium' | 'strong';
-  colorScheme?: 'primary' | 'vibrant' | 'cool' | 'warm';
-}
-
-// =============================================================================
-// AUDIO VIEWER PROPS (legacy)
-// =============================================================================
-
-export interface AudioViewerProps {
-  source: AudioSource;
-  autoPlay?: boolean;
-  showControls?: boolean;
-  showWaveform?: boolean;
-  showEqualizer?: boolean;
-  showTimer?: boolean;
-  showVolume?: boolean;
-  waveformOptions?: WaveformOptions;
-  equalizerOptions?: EqualizerOptions;
-  onPlaybackStatusUpdate?: (status: PlaybackStatus) => void;
-  className?: string;
-  style?: CSSProperties;
-}
-```
-
----
-
-## `types/effects.ts`
-
-Effect-related types (moved from effects/index.ts).
-
-```typescript
-// =============================================================================
-// EFFECT TYPES
-// =============================================================================
-
-export type EffectVariant = 'glow' | 'orbs' | 'spotlight' | 'mesh';
-export type EffectIntensity = 'subtle' | 'medium' | 'strong';
-export type EffectColorScheme = 'primary' | 'vibrant' | 'cool' | 'warm';
-
-export interface AudioLevels {
-  bass: number;
-  mid: number;
-  high: number;
-  overall: number;
-}
-
-export interface EffectConfig {
-  opacity: number;
-  scale: number;
-  blur: string;
-}
-
-export interface EffectColors {
-  colors: string[];
-  hueShift: number;
-}
-
-export interface EffectLayer {
-  inset: number;
-  opacity: number;
-  scale: number;
-  background: string;
-  blur: string;
-  animation?: string;
-}
-
-export interface Orb {
-  x: number;
-  y: number;
-  size: number;
-  color: string;
-  opacity: number;
-  scale: number;
-}
-
-export interface MeshGradient {
-  width: string;
-  height: string;
-  top?: string;
-  bottom?: string;
-  left?: string;
-  right?: string;
-  color: string;
-  opacity: number;
-  scale: number;
-  rotation: number;
-  blur: string;
-  isCenter?: boolean;
-}
-
-export interface SpotlightData {
-  rotation: number;
-  inset: number;
-  colors: Array<{ color: string; opacity: number }>;
-  pulseInset: number;
-  pulseOpacity: number;
-  pulseScale: number;
-  ringOpacity: number;
-  ringScale: number;
-}
-```
-
----
-
-## `types/index.ts`
-
-Re-export all types.
-
-```typescript
-// Audio types
-export type {
-  AudioSource,
-  PlaybackStatus,
-  WaveformOptions,
-  EqualizerOptions,
-  SharedWebAudioContext,
-  AudioContextState,
-} from './audio';
-
-// Component props
-export type {
-  AudioPlayerProps,
-  AudioEqualizerProps,
-  AudioReactiveCoverProps,
-  AudioViewerProps,
-} from './components';
-
-// Effect types
-export type {
-  EffectVariant,
-  EffectIntensity,
-  EffectColorScheme,
-  AudioLevels,
-  EffectConfig,
-  EffectColors,
-  EffectLayer,
-  Orb,
-  MeshGradient,
-  SpotlightData,
-} from './effects';
-```