@djangocfg/ui-tools 2.1.91

package/src/tools/AudioPlayer/hooks/useVisualization.tsx

@@ -0,0 +1,207 @@
+'use client';
+
+/**
+ * useVisualization - Hook for managing audio visualization settings
+ *
+ * Persists settings in localStorage for user preferences
+ * Uses React Context for shared state between components
+ */
+
+import { createContext, useContext, useCallback, useMemo, type ReactNode } from 'react';
+import { useLocalStorage } from '../../_shared';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type VisualizationVariant = 'glow' | 'orbs' | 'spotlight' | 'mesh' | 'none';
+export type VisualizationIntensity = 'subtle' | 'medium' | 'strong';
+export type VisualizationColorScheme = 'primary' | 'vibrant' | 'cool' | 'warm';
+
+export interface VisualizationSettings {
+  /** Enable reactive cover animation */
+  enabled: boolean;
+  /** Visual effect variant */
+  variant: VisualizationVariant;
+  /** Effect intensity */
+  intensity: VisualizationIntensity;
+  /** Color scheme */
+  colorScheme: VisualizationColorScheme;
+  /** Playback volume (0-1) */
+  volume: number;
+  /** Loop playback */
+  isLooping: boolean;
+}
+
+export interface UseVisualizationReturn {
+  /** Current settings */
+  settings: VisualizationSettings;
+  /** Toggle visualization on/off */
+  toggle: () => void;
+  /** Set specific setting */
+  setSetting: <K extends keyof VisualizationSettings>(
+    key: K,
+    value: VisualizationSettings[K]
+  ) => void;
+  /** Cycle to next variant */
+  nextVariant: () => void;
+  /** Cycle to next intensity */
+  nextIntensity: () => void;
+  /** Cycle to next color scheme */
+  nextColorScheme: () => void;
+  /** Reset to defaults */
+  reset: () => void;
+}
+
+// Backward compatibility alias
+export type UseAudioVisualizationReturn = UseVisualizationReturn;
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const STORAGE_KEY = 'audio-player-settings';
+
+const DEFAULT_SETTINGS: VisualizationSettings = {
+  enabled: true,
+  variant: 'spotlight',
+  intensity: 'medium',
+  colorScheme: 'primary',
+  volume: 1,
+  isLooping: false,
+};
+
+const VARIANTS: VisualizationVariant[] = ['spotlight', 'glow', 'orbs', 'mesh', 'none'];
+const INTENSITIES: VisualizationIntensity[] = ['subtle', 'medium', 'strong'];
+const COLOR_SCHEMES: VisualizationColorScheme[] = ['primary', 'vibrant', 'cool', 'warm'];
+
+// =============================================================================
+// CONTEXT
+// =============================================================================
+
+const VisualizationContext = createContext<UseVisualizationReturn | null>(null);
+
+// =============================================================================
+// PROVIDER
+// =============================================================================
+
+export interface VisualizationProviderProps {
+  children: ReactNode;
+}
+
+export function VisualizationProvider({ children }: VisualizationProviderProps) {
+  const value = useVisualizationState();
+  return (
+    <VisualizationContext.Provider value={value}>
+      {children}
+    </VisualizationContext.Provider>
+  );
+}
+
+// =============================================================================
+// INTERNAL HOOK (creates the actual state)
+// =============================================================================
+
+function useVisualizationState(): UseVisualizationReturn {
+  const [settings, setSettings] = useLocalStorage<VisualizationSettings>(
+    STORAGE_KEY,
+    DEFAULT_SETTINGS
+  );
+
+  const toggle = useCallback(() => {
+    setSettings((prev) => ({ ...prev, enabled: !prev.enabled }));
+  }, [setSettings]);
+
+  const setSetting = useCallback(
+    <K extends keyof VisualizationSettings>(
+      key: K,
+      value: VisualizationSettings[K]
+    ) => {
+      setSettings((prev) => ({ ...prev, [key]: value }));
+    },
+    [setSettings]
+  );
+
+  const nextVariant = useCallback(() => {
+    setSettings((prev) => {
+      const currentIndex = VARIANTS.indexOf(prev.variant);
+      const nextIndex = (currentIndex + 1) % VARIANTS.length;
+      return { ...prev, variant: VARIANTS[nextIndex] };
+    });
+  }, [setSettings]);
+
+  const nextIntensity = useCallback(() => {
+    setSettings((prev) => {
+      const currentIndex = INTENSITIES.indexOf(prev.intensity);
+      const nextIndex = (currentIndex + 1) % INTENSITIES.length;
+      return { ...prev, intensity: INTENSITIES[nextIndex] };
+    });
+  }, [setSettings]);
+
+  const nextColorScheme = useCallback(() => {
+    setSettings((prev) => {
+      const currentIndex = COLOR_SCHEMES.indexOf(prev.colorScheme);
+      const nextIndex = (currentIndex + 1) % COLOR_SCHEMES.length;
+      return { ...prev, colorScheme: COLOR_SCHEMES[nextIndex] };
+    });
+  }, [setSettings]);
+
+  const reset = useCallback(() => {
+    setSettings(DEFAULT_SETTINGS);
+  }, [setSettings]);
+
+  return useMemo(
+    () => ({
+      settings,
+      toggle,
+      setSetting,
+      nextVariant,
+      nextIntensity,
+      nextColorScheme,
+      reset,
+    }),
+    [settings, toggle, setSetting, nextVariant, nextIntensity, nextColorScheme, reset]
+  );
+}
+
+// =============================================================================
+// HOOK (uses context when available)
+// =============================================================================
+
+export function useVisualization(): UseVisualizationReturn {
+  const context = useContext(VisualizationContext);
+
+  // Always call the fallback hooks (React hooks rules require consistent calls)
+  const fallbackState = useVisualizationState();
+
+  // If inside a provider, use shared context; otherwise use fallback
+  return context ?? fallbackState;
+}
+
+// Backward compatibility alias
+export const useAudioVisualization = useVisualization;
+
+// =============================================================================
+// VARIANT INFO
+// =============================================================================
+
+export const VARIANT_INFO: Record<VisualizationVariant, { label: string; icon: string }> = {
+  spotlight: { label: 'Spotlight', icon: '💫' },
+  glow: { label: 'Glow', icon: '✨' },
+  orbs: { label: 'Orbs', icon: '🔮' },
+  mesh: { label: 'Mesh', icon: '🌈' },
+  none: { label: 'Off', icon: '⭕' },
+};
+
+export const INTENSITY_INFO: Record<VisualizationIntensity, { label: string }> = {
+  subtle: { label: 'Subtle' },
+  medium: { label: 'Medium' },
+  strong: { label: 'Strong' },
+};
+
+export const COLOR_SCHEME_INFO: Record<VisualizationColorScheme, { label: string; preview: string }> = {
+  primary: { label: 'Primary', preview: '🔵' },
+  vibrant: { label: 'Vibrant', preview: '🌈' },
+  cool: { label: 'Cool', preview: '💙' },
+  warm: { label: 'Warm', preview: '🔥' },
+};

package/src/tools/AudioPlayer/index.ts

@@ -0,0 +1,133 @@
+/**
+ * AudioPlayer - Complete audio playback solution with reactive visualizations
+ *
+ * Uses HTML5 audio for playback + Web Audio API for visualization.
+ * No crackling, native streaming support.
+ *
+ * @example
+ * // Simple usage
+ * import { HybridSimplePlayer } from '../../_shared';
+ * <HybridSimplePlayer src="/audio.mp3" title="Track Title" />
+ *
+ * @example
+ * // Custom setup with context
+ * import { HybridAudioProvider, HybridAudioPlayer } from '../../_shared';
+ * <HybridAudioProvider src={audioUrl}>
+ *   <HybridAudioPlayer showWaveform showControls />
+ * </HybridAudioProvider>
+ */
+
+// =============================================================================
+// COMPONENTS
+// =============================================================================
+
+export {
+  HybridAudioPlayer,
+  HybridSimplePlayer,
+  HybridWaveform,
+  AudioReactiveCover,
+  // Effect components (for custom implementations)
+  GlowEffect,
+  OrbsEffect,
+  SpotlightEffect,
+  MeshEffect,
+} from './components';
+
+export type {
+  HybridAudioPlayerProps,
+  HybridSimplePlayerProps,
+  HybridWaveformProps,
+  AudioReactiveCoverProps,
+  GlowEffectData,
+} from './components';
+
+// =============================================================================
+// CONTEXT
+// =============================================================================
+
+export {
+  HybridAudioProvider,
+  useHybridAudioContext,
+  useHybridAudioState,
+  useHybridAudioControls,
+  useHybridAudioLevels,
+  useHybridWebAudio,
+} from './context';
+
+export type {
+  HybridAudioContextValue,
+  HybridAudioProviderProps,
+} from './context';
+
+// =============================================================================
+// HOOKS
+// =============================================================================
+
+export {
+  // Core hooks
+  useHybridAudio,
+  useHybridAudioAnalysis,
+  // Visualization settings
+  useVisualization,
+  useAudioVisualization,
+  VisualizationProvider,
+  VARIANT_INFO,
+  INTENSITY_INFO,
+  COLOR_SCHEME_INFO,
+} from './hooks';
+
+export type {
+  UseHybridAudioOptions,
+  HybridAudioState,
+  HybridAudioControls,
+  HybridWebAudioAPI,
+  UseHybridAudioReturn,
+  VisualizationSettings,
+  VisualizationVariant,
+  VisualizationIntensity,
+  VisualizationColorScheme,
+  UseVisualizationReturn,
+  UseAudioVisualizationReturn,
+  VisualizationProviderProps,
+} from './hooks';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type { EqualizerOptions } from './types';
+
+// =============================================================================
+// EFFECTS
+// =============================================================================
+
+export {
+  // Utilities
+  getEffectConfig,
+  getColors,
+  prepareEffectColors,
+  calculateGlowLayers,
+  calculateOrbs,
+  calculateMeshGradients,
+  calculateSpotlight,
+  // Constants
+  INTENSITY_CONFIG,
+  COLOR_SCHEMES,
+  EFFECT_ANIMATIONS,
+} from './effects';
+
+export type {
+  EffectVariant,
+  EffectIntensity,
+  EffectColorScheme,
+  AudioLevels,
+  EffectConfig,
+  EffectColors,
+  EffectLayer,
+} from './effects';
+
+// =============================================================================
+// UTILITIES
+// =============================================================================
+
+export { formatTime } from './utils';

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,27 @@
+/**
+ * AudioPlayer types
+ */
+
+// Equalizer options
+export interface EqualizerOptions {
+  barCount?: number;
+  height?: number;
+  gap?: number;
+  showPeaks?: boolean;
+  barColor?: string;
+  peakColor?: string;
+}
+
+// Effect types
+export type {
+  EffectVariant,
+  EffectIntensity,
+  EffectColorScheme,
+  AudioLevels,
+  EffectConfig,
+  EffectColors,
+  EffectLayer,
+  Orb,
+  MeshGradient,
+  SpotlightData,
+} from './effects';

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

@@ -0,0 +1,14 @@
+'use client';
+
+/**
+ * AudioPlayer Debug Logger
+ *
+ * Uses universal logger with media-specific helpers.
+ * Logs go to both console (dev) and zustand store (for Console panel).
+ */
+
+import { createMediaLogger } from '@djangocfg/ui-core/lib';
+
+export const audioDebug = createMediaLogger('AudioPlayer');
+
+export default audioDebug;

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,6 @@
+/**
+ * AudioPlayer utilities - Public API
+ */
+
+export { formatTime } from './formatTime';
+export { audioDebug } from './debug';

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

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

@@ -0,0 +1,121 @@
+# Phase 1: Types Extraction
+
+## Goal
+
+Extract all type definitions from ImageViewer.tsx into a dedicated types.ts file.
+
+## Types to Extract
+
+### ImageFile (Props)
+```typescript
+export interface ImageFile {
+  /** Display name for the image */
+  name: string;
+  /** File path used for change detection and caching */
+  path: string;
+  /** Optional MIME type */
+  mimeType?: string;
+}
+```
+
+### ImageViewerProps (Props)
+```typescript
+export interface ImageViewerProps {
+  /** Image file metadata */
+  file: ImageFile;
+  /** Image content as string or ArrayBuffer */
+  content: string | ArrayBuffer;
+  /** Whether viewer is inside a dialog (hides expand button) */
+  inDialog?: boolean;
+}
+```
+
+### ImageTransform (State)
+```typescript
+export interface ImageTransform {
+  /** Rotation angle: 0, 90, 180, or 270 degrees */
+  rotation: number;
+  /** Horizontal flip state */
+  flipH: boolean;
+  /** Vertical flip state */
+  flipV: boolean;
+}
+```
+
+### ZoomPreset (UI)
+```typescript
+export interface ZoomPreset {
+  /** Zoom level (1 = 100%) */
+  value: number;
+  /** Display label (e.g., "100%") */
+  label: string;
+}
+```
+
+### ImageToolbarProps (Internal)
+```typescript
+export interface ImageToolbarProps {
+  /** Current zoom scale */
+  scale: number;
+  /** Expand to fullscreen callback */
+  onExpand: () => void;
+  /** Rotate image callback */
+  onRotate: () => void;
+  /** Flip horizontal callback */
+  onFlipH: () => void;
+  /** Flip vertical callback */
+  onFlipV: () => void;
+  /** Whether horizontal flip is active */
+  flipH: boolean;
+  /** Whether vertical flip is active */
+  flipV: boolean;
+  /** Whether inside dialog (hides expand) */
+  inDialog?: boolean;
+}
+```
+
+### ImageInfoProps (Internal)
+```typescript
+export interface ImageInfoProps {
+  /** Blob URL source of the image */
+  src: string;
+  /** Content key for cache lookup */
+  contentKey: string;
+}
+```
+
+## File Structure
+
+```typescript
+// types.ts
+
+/**
+ * ImageViewer type definitions
+ */
+
+// =============================================================================
+// FILE TYPES
+// =============================================================================
+
+export interface ImageFile { ... }
+
+// =============================================================================
+// COMPONENT PROPS
+// =============================================================================
+
+export interface ImageViewerProps { ... }
+export interface ImageToolbarProps { ... }
+export interface ImageInfoProps { ... }
+
+// =============================================================================
+// STATE TYPES
+// =============================================================================
+
+export interface ImageTransform { ... }
+
+// =============================================================================
+// UI TYPES
+// =============================================================================
+
+export interface ZoomPreset { ... }
+```