@djangocfg/ui-nextjs 2.1.66 → 2.1.68

package/src/tools/AudioPlayer/{useAudioVisualization.tsx → hooks/useVisualization.tsx}

@@ -1,7 +1,7 @@
 'use client';
 
 /**
- * useAudioVisualization - Hook for managing audio visualization settings
+ * useVisualization - Hook for managing audio visualization settings
  *
  * Persists settings in localStorage for user preferences
  * Uses React Context for shared state between components
@@ -29,7 +29,7 @@ export interface VisualizationSettings {
   colorScheme: VisualizationColorScheme;
 }
 
-export interface UseAudioVisualizationReturn {
+export interface UseVisualizationReturn {
   /** Current settings */
   settings: VisualizationSettings;
   /** Toggle visualization on/off */
@@ -49,6 +49,9 @@ export interface UseAudioVisualizationReturn {
   reset: () => void;
 }
 
+// Backward compatibility alias
+export type UseAudioVisualizationReturn = UseVisualizationReturn;
+
 // =============================================================================
 // CONSTANTS
 // =============================================================================
@@ -70,7 +73,7 @@ const COLOR_SCHEMES: VisualizationColorScheme[] = ['primary', 'vibrant', 'cool',
 // CONTEXT
 // =============================================================================
 
-const VisualizationContext = createContext<UseAudioVisualizationReturn | null>(null);
+const VisualizationContext = createContext<UseVisualizationReturn | null>(null);
 
 // =============================================================================
 // PROVIDER
@@ -93,7 +96,7 @@ export function VisualizationProvider({ children }: VisualizationProviderProps)
 // INTERNAL HOOK (creates the actual state)
 // =============================================================================
 
-function useVisualizationState(): UseAudioVisualizationReturn {
+function useVisualizationState(): UseVisualizationReturn {
   const [settings, setSettings] = useLocalStorage<VisualizationSettings>(
     STORAGE_KEY,
     DEFAULT_SETTINGS
@@ -159,7 +162,7 @@ function useVisualizationState(): UseAudioVisualizationReturn {
 // HOOK (uses context when available)
 // =============================================================================
 
-export function useAudioVisualization(): UseAudioVisualizationReturn {
+export function useVisualization(): UseVisualizationReturn {
   const context = useContext(VisualizationContext);
 
   // Always call the fallback hooks (React hooks rules require consistent calls)
@@ -169,6 +172,9 @@ export function useAudioVisualization(): UseAudioVisualizationReturn {
   return context ?? fallbackState;
 }
 
+// Backward compatibility alias
+export const useAudioVisualization = useVisualization;
+
 // =============================================================================
 // VARIANT INFO
 // =============================================================================

package/src/tools/AudioPlayer/index.ts

@@ -1,50 +1,114 @@
 /**
- * AudioPlayer - Audio playback with waveform visualization
+ * AudioPlayer - Complete audio playback solution with reactive visualizations
  *
- * Built on WaveSurfer.js with audio-reactive effects
+ * @example
+ * // Simple usage
+ * import { SimpleAudioPlayer } from '@djangocfg/ui-nextjs';
+ * <SimpleAudioPlayer src="/audio.mp3" title="Track Title" />
+ *
+ * @example
+ * // Custom setup with context
+ * import { AudioProvider, AudioPlayer, useAudio } from '@djangocfg/ui-nextjs';
+ * <AudioProvider source={{ uri: audioUrl }} containerRef={ref}>
+ *   <AudioPlayer ref={ref} />
+ * </AudioProvider>
  */
 
-// Simple wrapper (recommended for most use cases)
-export { SimpleAudioPlayer } from './SimpleAudioPlayer';
-export type { SimpleAudioPlayerProps } from './SimpleAudioPlayer';
+// =============================================================================
+// COMPONENTS
+// =============================================================================
 
-// Core components (for advanced usage)
-export { AudioPlayer } from './AudioPlayer';
-export { AudioEqualizer } from './AudioEqualizer';
-export { AudioReactiveCover } from './AudioReactiveCover';
-export { AudioShortcutsPopover } from './AudioShortcutsPopover';
-export { VisualizationToggle } from './VisualizationToggle';
+export {
+  AudioPlayer,
+  SimpleAudioPlayer,
+  AudioEqualizer,
+  AudioShortcutsPopover,
+  VisualizationToggle,
+  AudioReactiveCover,
+  // Effect components (for custom implementations)
+  GlowEffect,
+  OrbsEffect,
+  SpotlightEffect,
+  MeshEffect,
+} from './components';
+
+export type {
+  SimpleAudioPlayerProps,
+  VisualizationToggleProps,
+  AudioReactiveCoverProps,
+  GlowEffectData,
+} from './components';
+
+// =============================================================================
+// CONTEXT
+// =============================================================================
 
-// Context and hooks
 export {
   AudioProvider,
+  AudioPlayerContext,
   useAudio,
   useAudioControls,
   useAudioState,
   useAudioElement,
 } from './context';
 
-export { useAudioHotkeys, AUDIO_SHORTCUTS } from './useAudioHotkeys';
+// =============================================================================
+// HOOKS
+// =============================================================================
 
 export {
-  useAudioVisualization,
+  // Internal hooks (for custom implementations)
+  useSharedWebAudio,
+  useAudioAnalysis,
+  // Public hooks
+  useAudioHotkeys,
+  AUDIO_SHORTCUTS,
+  // Visualization
+  useVisualization,
+  useAudioVisualization, // backward compat alias
   VisualizationProvider,
   VARIANT_INFO,
   INTENSITY_INFO,
   COLOR_SCHEME_INFO,
-} from './useAudioVisualization';
+} from './hooks';
+
+export type {
+  AudioHotkeyOptions,
+  ShortcutItem,
+  ShortcutGroup,
+  VisualizationSettings,
+  VisualizationVariant,
+  VisualizationIntensity,
+  VisualizationColorScheme,
+  UseVisualizationReturn,
+  UseAudioVisualizationReturn,
+  VisualizationProviderProps,
+} from './hooks';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type {
+  // Audio types
+  AudioSource,
+  AudioContextState,
+  SharedWebAudioContext,
+  WaveformOptions,
+  PlaybackStatus,
+  // Component types
+  AudioPlayerProps,
+  AudioEqualizerProps,
+  AudioViewerProps,
+  EqualizerOptions,
+} from './types';
+
+// =============================================================================
+// EFFECTS
+// =============================================================================
 
-// Effects utilities
 export {
-  type EffectVariant,
-  type EffectIntensity,
-  type EffectColorScheme,
-  type AudioLevels,
-  type EffectConfig,
-  type EffectColors,
-  type EffectLayer,
-  INTENSITY_CONFIG,
-  COLOR_SCHEMES,
+  // Utilities
   getEffectConfig,
   getColors,
   prepareEffectColors,
@@ -52,33 +116,24 @@ export {
   calculateOrbs,
   calculateMeshGradients,
   calculateSpotlight,
+  // Constants
+  INTENSITY_CONFIG,
+  COLOR_SCHEMES,
   EFFECT_ANIMATIONS,
 } from './effects';
 
-// Types
 export type {
-  AudioSource,
-  PlaybackStatus,
-  WaveformOptions,
-  EqualizerOptions,
-  AudioContextState,
-  AudioPlayerProps,
-  AudioEqualizerProps,
-  AudioReactiveCoverProps,
-  AudioViewerProps,
-} from './types';
+  EffectVariant,
+  EffectIntensity,
+  EffectColorScheme,
+  AudioLevels,
+  EffectConfig,
+  EffectColors,
+  EffectLayer,
+} from './effects';
 
-export type {
-  VisualizationSettings,
-  VisualizationVariant,
-  VisualizationIntensity,
-  VisualizationColorScheme,
-  UseAudioVisualizationReturn,
-  VisualizationProviderProps,
-} from './useAudioVisualization';
+// =============================================================================
+// UTILITIES
+// =============================================================================
 
-export type {
-  AudioHotkeyOptions,
-  ShortcutItem,
-  ShortcutGroup,
-} from './useAudioHotkeys';
+export { formatTime } from './utils';

package/src/tools/AudioPlayer/types/audio.ts

@@ -0,0 +1,107 @@
+/**
+ * Core audio-related types
+ */
+
+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 {
+  /** The Web Audio AudioContext instance */
+  audioContext: AudioContext | null;
+  /** The MediaElementSourceNode connected to the audio element */
+  sourceNode: MediaElementAudioSourceNode | null;
+  /** Create an AnalyserNode connected to the shared source */
+  createAnalyser: (options?: { fftSize?: number; smoothing?: number }) => AnalyserNode | null;
+  /** Disconnect and cleanup an AnalyserNode */
+  disconnectAnalyser: (analyser: AnalyserNode) => void;
+}
+
+// =============================================================================
+// AUDIO CONTEXT STATE
+// =============================================================================
+
+export interface AudioContextState {
+  // Core instances
+  wavesurfer: WaveSurfer | null;
+  audioElement: HTMLMediaElement | null;
+  /** Shared Web Audio context for analyzers */
+  sharedAudio: SharedWebAudioContext;
+
+  // Playback state
+  isReady: boolean;
+  isPlaying: boolean;
+  currentTime: number;
+  duration: number;
+  volume: number;
+  isMuted: boolean;
+  isLooping: boolean;
+
+  // Audio analysis (for reactive effects)
+  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;
+}

package/src/tools/AudioPlayer/{types.ts → types/components.ts}

@@ -1,90 +1,12 @@
-import type { CSSProperties } from 'react';
-import type WaveSurfer from 'wavesurfer.js';
-import type { AudioLevels } from './effects';
-
-// =============================================================================
-// AUDIO SOURCE
-// =============================================================================
-
-export interface AudioSource {
-  uri: string;
-}
+/**
+ * Component props types
+ */
 
-// =============================================================================
-// 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;
-}
-
-// =============================================================================
-// AUDIO CONTEXT STATE
-// =============================================================================
-
-export interface AudioContextState {
-  // Core instances
-  wavesurfer: WaveSurfer | null;
-  audioElement: HTMLMediaElement | null;
-
-  // Playback state
-  isReady: boolean;
-  isPlaying: boolean;
-  currentTime: number;
-  duration: number;
-  volume: number;
-  isMuted: boolean;
-
-  // Audio analysis (for reactive effects)
-  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;
-  restart: () => void;
-}
+import type { CSSProperties } from 'react';
+import type { WaveformOptions, EqualizerOptions, AudioSource, PlaybackStatus } from './audio';
 
 // =============================================================================
-// COMPONENT PROPS
+// AUDIO PLAYER PROPS
 // =============================================================================
 
 export interface AudioPlayerProps {
@@ -98,6 +20,8 @@ export interface AudioPlayerProps {
   showTimer?: boolean;
   /** Show volume control */
   showVolume?: boolean;
+  /** Show loop/repeat button */
+  showLoop?: boolean;
   /** WaveSurfer options override */
   waveformOptions?: WaveformOptions;
   /** Equalizer options */
@@ -108,6 +32,10 @@ export interface AudioPlayerProps {
   style?: CSSProperties;
 }
 
+// =============================================================================
+// AUDIO EQUALIZER PROPS
+// =============================================================================
+
 export interface AudioEqualizerProps {
   /** Number of frequency bars */
   barCount?: number;
@@ -125,6 +53,10 @@ export interface AudioEqualizerProps {
   className?: string;
 }
 
+// =============================================================================
+// AUDIO REACTIVE COVER PROPS
+// =============================================================================
+
 export interface AudioReactiveCoverProps {
   /** Visual variant */
   variant?: 'glow' | 'orbs' | 'spotlight' | 'mesh';
@@ -134,6 +66,10 @@ export interface AudioReactiveCoverProps {
   colorScheme?: 'primary' | 'vibrant' | 'cool' | 'warm';
 }
 
+// =============================================================================
+// AUDIO VIEWER PROPS (legacy)
+// =============================================================================
+
 export interface AudioViewerProps {
   /** Audio source URL */
   source: AudioSource;

package/src/tools/AudioPlayer/types/effects.ts

@@ -0,0 +1,73 @@
+/**
+ * Effect-related types for audio-reactive visualizations
+ */
+
+// =============================================================================
+// 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;
+}

package/src/tools/AudioPlayer/types/index.ts

@@ -0,0 +1,35 @@
+/**
+ * AudioPlayer types - re-exports all types
+ */
+
+// 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';

package/src/tools/AudioPlayer/utils/formatTime.ts

@@ -0,0 +1,10 @@
+/**
+ * formatTime - Format seconds to mm:ss string
+ */
+
+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')}`;
+}

package/src/tools/AudioPlayer/utils/index.ts

@@ -0,0 +1,5 @@
+/**
+ * AudioPlayer utilities - Public API
+ */
+
+export { formatTime } from './formatTime';

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

@@ -0,0 +1,71 @@
+# ImageViewer Refactoring Plan
+
+## Overview
+
+Decompose the monolithic 589-line `ImageViewer.tsx` into a well-organized module structure similar to AudioPlayer.
+
+## Current Structure (Before)
+
+```
+ImageViewer/
+├── ImageViewer.tsx (589 lines) - Everything in one file
+├── index.ts (16 lines)
+└── README.md
+```
+
+**Issues:**
+- Single 589-line file with mixed concerns
+- 2 sub-components inline (ImageToolbar, ImageInfo)
+- 1 utility function inline (createLQIP)
+- 8 separate useState calls
+- Types defined inline
+- Constants hardcoded
+
+## Target Structure (After)
+
+```
+ImageViewer/
+├── index.ts                    # Public API
+├── README.md                   # Documentation
+├── components/
+│   ├── index.ts
+│   ├── ImageViewer.tsx         # Main component (~150 lines)
+│   ├── ImageToolbar.tsx        # Toolbar with zoom/rotate/flip (~130 lines)
+│   └── ImageInfo.tsx           # Dimensions display (~35 lines)
+├── hooks/
+│   ├── index.ts
+│   ├── useImageTransform.ts    # Rotation/flip state management
+│   └── useImageLoading.ts      # LQIP and loading state
+├── utils/
+│   ├── index.ts
+│   ├── lqip.ts                 # LQIP generator utility
+│   └── constants.ts            # Zoom presets, size limits
+└── types.ts                    # All type definitions
+```
+
+## Benefits
+
+1. **Separation of Concerns** - Each file has single responsibility
+2. **Testability** - Hooks and utils can be unit tested independently
+3. **Reusability** - Components can be used standalone
+4. **Maintainability** - Easier to find and modify specific functionality
+5. **Code Organization** - Consistent with AudioPlayer structure
+
+## Execution Phases
+
+| Phase | Description | Files |
+|-------|-------------|-------|
+| 1 | Create folder structure | components/, hooks/, utils/ |
+| 2 | Extract types | types.ts |
+| 3 | Extract constants and utilities | utils/constants.ts, utils/lqip.ts |
+| 4 | Extract hooks | hooks/useImageTransform.ts, hooks/useImageLoading.ts |
+| 5 | Split components | ImageToolbar.tsx, ImageInfo.tsx |
+| 6 | Refactor main component | ImageViewer.tsx (simplified) |
+| 7 | Update exports | index.ts, components/index.ts, hooks/index.ts |
+| 8 | Cleanup and verify | Delete old file, run pnpm check |
+
+## Risk Assessment
+
+- **Low Risk**: Pure extraction with no logic changes
+- **Testing**: Run `pnpm check` after each phase
+- **Rollback**: Keep old file until verification complete