@djangocfg/ui-nextjs 2.1.64 → 2.1.66

package/src/tools/AudioPlayer/README.md

@@ -0,0 +1,301 @@
+# AudioPlayer
+
+Audio player with waveform visualization, built on WaveSurfer.js.
+
+## Features
+
+- Waveform visualization with interactive seeking
+- Audio-reactive cover effects (glow, orbs, spotlight, mesh)
+- Real-time frequency equalizer
+- Keyboard shortcuts
+- Volume control with mute
+- Skip forward/backward
+- Playback speed control
+
+## Quick Start (Recommended)
+
+```tsx
+import { SimpleAudioPlayer } from '@djangocfg/ui-nextjs';
+
+// Minimal
+<SimpleAudioPlayer src="https://example.com/audio.mp3" />
+
+// With metadata
+<SimpleAudioPlayer
+  src={audioUrl}
+  title="Track Title"
+  artist="Artist Name"
+  coverArt="/path/to/cover.jpg"
+/>
+
+// Full customization
+<SimpleAudioPlayer
+  src={audioUrl}
+  title="Track Title"
+  coverArt={coverUrl}
+  showWaveform
+  showEqualizer={false}
+  reactiveCover
+  variant="spotlight"
+  layout="horizontal"
+/>
+```
+
+### SimpleAudioPlayer Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | required | Audio URL |
+| `title` | `string` | - | Track title |
+| `artist` | `string` | - | Artist name |
+| `coverArt` | `string \| ReactNode` | - | Cover image URL or custom element |
+| `coverSize` | `'sm' \| 'md' \| 'lg'` | `'md'` | Cover art size |
+| `showWaveform` | `boolean` | `true` | Show waveform |
+| `showEqualizer` | `boolean` | `false` | Show equalizer bars |
+| `showTimer` | `boolean` | `true` | Show time display |
+| `showVolume` | `boolean` | `true` | Show volume control |
+| `reactiveCover` | `boolean` | `true` | Enable reactive effects |
+| `variant` | `VisualizationVariant` | - | Effect variant |
+| `intensity` | `EffectIntensity` | - | Effect intensity |
+| `colorScheme` | `EffectColorScheme` | - | Effect colors |
+| `autoPlay` | `boolean` | `false` | Auto-play on load |
+| `layout` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction |
+
+---
+
+## Advanced Usage
+
+For full control, use `AudioProvider` + `AudioPlayer` directly:
+
+```tsx
+import { useRef } from 'react';
+import { AudioProvider, AudioPlayer } from '@djangocfg/ui-nextjs';
+
+function MyAudioPlayer({ audioUrl }: { audioUrl: string }) {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  return (
+    <AudioProvider
+      source={{ uri: audioUrl }}
+      containerRef={containerRef}
+    >
+      <AudioPlayer
+        ref={containerRef}
+        showControls
+        showWaveform
+        showTimer
+        showVolume
+      />
+    </AudioProvider>
+  );
+}
+```
+
+## Components
+
+### AudioProvider
+
+Context provider for audio state. Wraps all audio components.
+
+```tsx
+<AudioProvider
+  source={{ uri: 'https://example.com/audio.mp3' }}
+  containerRef={containerRef}
+  autoPlay={false}
+  waveformOptions={{
+    waveColor: 'hsl(217 91% 60% / 0.3)',
+    progressColor: 'hsl(217 91% 60%)',
+    height: 64,
+    barWidth: 3,
+    barRadius: 3,
+    barGap: 2,
+  }}
+>
+  {children}
+</AudioProvider>
+```
+
+### AudioPlayer
+
+Main player component with waveform and controls.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `showControls` | `boolean` | `true` | Show playback controls |
+| `showWaveform` | `boolean` | `true` | Show waveform visualization |
+| `showEqualizer` | `boolean` | `false` | Show equalizer animation |
+| `showTimer` | `boolean` | `true` | Show time display |
+| `showVolume` | `boolean` | `true` | Show volume slider |
+| `className` | `string` | - | Additional CSS class |
+
+### AudioEqualizer
+
+Real-time frequency visualizer with animated bars.
+
+```tsx
+<AudioEqualizer
+  barCount={24}
+  height={48}
+  gap={2}
+  showPeaks
+  barColor="hsl(217 91% 60%)"
+  peakColor="hsl(217 91% 70%)"
+/>
+```
+
+### AudioReactiveCover
+
+Album art wrapper with audio-reactive effects.
+
+```tsx
+<AudioReactiveCover
+  variant="spotlight"  // 'glow' | 'orbs' | 'spotlight' | 'mesh'
+  intensity="medium"   // 'subtle' | 'medium' | 'strong'
+  colorScheme="primary" // 'primary' | 'vibrant' | 'cool' | 'warm'
+  onClick={() => nextVariant()}
+>
+  <img src={coverArt} alt="Album cover" />
+</AudioReactiveCover>
+```
+
+### VisualizationToggle
+
+Button to cycle through visualization variants.
+
+```tsx
+<VisualizationToggle compact />
+```
+
+## Hooks
+
+### useAudio
+
+Access full audio state and controls.
+
+```tsx
+const {
+  isReady,
+  isPlaying,
+  currentTime,
+  duration,
+  volume,
+  isMuted,
+  audioLevels,  // { bass, mid, high, overall }
+  play,
+  pause,
+  togglePlay,
+  seek,
+  seekTo,
+  skip,
+  setVolume,
+  toggleMute,
+  restart,
+} = useAudio();
+```
+
+### useAudioControls
+
+Controls only (no re-render on time updates).
+
+```tsx
+const { play, pause, togglePlay, skip, restart } = useAudioControls();
+```
+
+### useAudioState
+
+Read-only playback state.
+
+```tsx
+const { isPlaying, currentTime, duration, volume } = useAudioState();
+```
+
+### useAudioElement
+
+Access audio element for custom visualizations.
+
+```tsx
+const { audioElement, isPlaying, audioLevels } = useAudioElement();
+```
+
+### useAudioVisualization
+
+Manage visualization settings (persisted in localStorage).
+
+```tsx
+const {
+  settings,      // { enabled, variant, intensity, colorScheme }
+  toggle,
+  setSetting,
+  nextVariant,
+  nextIntensity,
+  nextColorScheme,
+  reset,
+} = useAudioVisualization();
+```
+
+### useAudioHotkeys
+
+Enable keyboard shortcuts.
+
+```tsx
+useAudioHotkeys({
+  enabled: true,
+  skipDuration: 10,
+  volumeStep: 0.1,
+});
+```
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `Space` | Play/Pause |
+| `←` / `J` | Skip 10s backward |
+| `→` / `L` | Skip 10s forward |
+| `↑` | Volume up |
+| `↓` | Volume down |
+| `M` | Mute/Unmute |
+| `0-9` | Jump to 0-90% |
+
+## Waveform Options
+
+```typescript
+interface WaveformOptions {
+  waveColor?: string;      // Unplayed wave color
+  progressColor?: string;  // Played wave color
+  cursorColor?: string;    // Playhead cursor color
+  cursorWidth?: number;    // Cursor width in px
+  height?: number;         // Waveform height in px
+  barWidth?: number;       // Bar width in px
+  barRadius?: number;      // Bar corner radius
+  barGap?: number;         // Gap between bars
+}
+```
+
+## Effect Variants
+
+| Variant | Description |
+|---------|-------------|
+| `spotlight` | Rotating conic gradient with bass pulse |
+| `glow` | Multi-layered radial glows from edges |
+| `orbs` | Floating orbs that react to frequencies |
+| `mesh` | Large gradient blobs with movement |
+| `none` | Effects disabled |
+
+## Architecture
+
+```
+AudioPlayer/
+├── index.ts                  # Exports
+├── types.ts                  # Type definitions
+├── context.tsx               # AudioProvider, useAudio hooks
+├── AudioPlayer.tsx           # Main player component
+├── AudioEqualizer.tsx        # Frequency bars
+├── AudioReactiveCover.tsx    # Reactive album art
+├── AudioShortcutsPopover.tsx # Shortcuts help
+├── VisualizationToggle.tsx   # Effect toggle button
+├── useAudioHotkeys.ts        # Keyboard shortcuts
+├── useAudioVisualization.tsx # Visualization settings
+└── effects/
+    └── index.ts              # Effect calculations
+```

package/src/tools/AudioPlayer/SimpleAudioPlayer.tsx

@@ -0,0 +1,275 @@
+'use client';
+
+/**
+ * SimpleAudioPlayer - Easy-to-use audio player wrapper
+ *
+ * Combines AudioProvider + AudioPlayer + optional reactive cover
+ * in a single component with sensible defaults.
+ *
+ * @example
+ * // Minimal usage
+ * <SimpleAudioPlayer src="https://example.com/audio.mp3" />
+ *
+ * @example
+ * // With cover art
+ * <SimpleAudioPlayer
+ *   src={audioUrl}
+ *   title="Track Title"
+ *   artist="Artist Name"
+ *   coverArt="/path/to/cover.jpg"
+ * />
+ *
+ * @example
+ * // Full customization
+ * <SimpleAudioPlayer
+ *   src={audioUrl}
+ *   title="Track Title"
+ *   coverArt={coverUrl}
+ *   showWaveform
+ *   showEqualizer={false}
+ *   reactiveCover
+ *   variant="spotlight"
+ *   autoPlay={false}
+ * />
+ */
+
+import { useRef, type ReactNode } from 'react';
+import { Music } from 'lucide-react';
+import { cn } from '@djangocfg/ui-core';
+
+import { AudioProvider } from './context';
+import { AudioPlayer } from './AudioPlayer';
+import { AudioReactiveCover } from './AudioReactiveCover';
+import { VisualizationProvider, useAudioVisualization } from './useAudioVisualization';
+import type { WaveformOptions, EqualizerOptions } from './types';
+import type { EffectIntensity, EffectColorScheme } from './effects';
+import type { VisualizationVariant } from './useAudioVisualization';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface SimpleAudioPlayerProps {
+  /** Audio source URL */
+  src: string;
+
+  /** Track title */
+  title?: string;
+
+  /** Artist name */
+  artist?: string;
+
+  /** Cover art URL or ReactNode */
+  coverArt?: string | ReactNode;
+
+  /** Cover art size */
+  coverSize?: 'sm' | 'md' | 'lg';
+
+  /** Show waveform visualization */
+  showWaveform?: boolean;
+
+  /** Show equalizer bars */
+  showEqualizer?: boolean;
+
+  /** Show timer */
+  showTimer?: boolean;
+
+  /** Show volume control */
+  showVolume?: boolean;
+
+  /** Enable audio-reactive cover effects */
+  reactiveCover?: boolean;
+
+  /** Reactive effect variant */
+  variant?: VisualizationVariant;
+
+  /** Reactive effect intensity */
+  intensity?: EffectIntensity;
+
+  /** Reactive effect color scheme */
+  colorScheme?: EffectColorScheme;
+
+  /** Auto-play on load */
+  autoPlay?: boolean;
+
+  /** Waveform customization */
+  waveformOptions?: WaveformOptions;
+
+  /** Equalizer customization */
+  equalizerOptions?: EqualizerOptions;
+
+  /** Layout direction */
+  layout?: 'vertical' | 'horizontal';
+
+  /** Additional class name */
+  className?: string;
+}
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const COVER_SIZES = {
+  sm: 'w-24 h-24',
+  md: 'w-32 h-32',
+  lg: 'w-48 h-48',
+};
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export function SimpleAudioPlayer(props: SimpleAudioPlayerProps) {
+  return (
+    <VisualizationProvider>
+      <SimpleAudioPlayerContent {...props} />
+    </VisualizationProvider>
+  );
+}
+
+function SimpleAudioPlayerContent({
+  src,
+  title,
+  artist,
+  coverArt,
+  coverSize = 'md',
+  showWaveform = true,
+  showEqualizer = false,
+  showTimer = true,
+  showVolume = true,
+  reactiveCover = true,
+  variant,
+  intensity,
+  colorScheme,
+  autoPlay = false,
+  waveformOptions,
+  equalizerOptions,
+  layout = 'vertical',
+  className,
+}: SimpleAudioPlayerProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const { settings: vizSettings, nextVariant } = useAudioVisualization();
+
+  // Determine effective variant (from props or localStorage settings)
+  const effectiveVariant = variant ?? (vizSettings.variant !== 'none' ? vizSettings.variant : 'spotlight');
+  const effectiveIntensity = intensity ?? vizSettings.intensity;
+  const effectiveColorScheme = colorScheme ?? vizSettings.colorScheme;
+
+  // Show reactive cover if enabled and variant is not 'none'
+  const showReactiveCover = reactiveCover && effectiveVariant !== 'none';
+
+  // Render cover art content
+  const renderCoverContent = () => {
+    if (typeof coverArt === 'string') {
+      return (
+        <img
+          src={coverArt}
+          alt={title || 'Album cover'}
+          className="w-full h-full object-cover"
+        />
+      );
+    }
+
+    if (coverArt) {
+      return coverArt;
+    }
+
+    // Default placeholder
+    return (
+      <div className="w-full h-full bg-muted/30 flex items-center justify-center">
+        <Music className="w-1/3 h-1/3 text-muted-foreground/50" />
+      </div>
+    );
+  };
+
+  const isHorizontal = layout === 'horizontal';
+
+  return (
+    <AudioProvider
+      source={{ uri: src }}
+      containerRef={containerRef}
+      autoPlay={autoPlay}
+      waveformOptions={waveformOptions}
+    >
+      <div
+        className={cn(
+          'flex gap-4',
+          isHorizontal ? 'flex-row items-center' : 'flex-col items-center',
+          className
+        )}
+      >
+        {/* Cover Art */}
+        {(coverArt || reactiveCover) && (
+          <div className="flex flex-col items-center gap-2 shrink-0">
+            {showReactiveCover ? (
+              <AudioReactiveCover
+                size={coverSize}
+                variant={effectiveVariant as 'glow' | 'orbs' | 'spotlight' | 'mesh'}
+                intensity={effectiveIntensity}
+                colorScheme={effectiveColorScheme}
+                onClick={nextVariant}
+              >
+                <div className={cn('rounded-lg overflow-hidden', COVER_SIZES[coverSize])}>
+                  {renderCoverContent()}
+                </div>
+              </AudioReactiveCover>
+            ) : (
+              <div
+                className={cn(
+                  'rounded-lg overflow-hidden shadow-lg cursor-pointer',
+                  COVER_SIZES[coverSize]
+                )}
+                onClick={nextVariant}
+                role="button"
+                tabIndex={0}
+                onKeyDown={(e) => e.key === 'Enter' && nextVariant()}
+              >
+                {renderCoverContent()}
+              </div>
+            )}
+
+            {/* Effect indicator */}
+            {reactiveCover && (
+              <span className="text-[10px] uppercase tracking-wider text-muted-foreground/50 select-none">
+                {vizSettings.variant === 'none' ? 'off' : vizSettings.variant}
+              </span>
+            )}
+          </div>
+        )}
+
+        {/* Track Info + Player */}
+        <div className={cn('flex flex-col gap-3', isHorizontal ? 'flex-1 min-w-0' : 'w-full max-w-md')}>
+          {/* Track Info */}
+          {(title || artist) && (
+            <div className={cn('text-center', isHorizontal && 'text-left')}>
+              {title && (
+                <h3 className="text-base font-medium text-foreground truncate">
+                  {title}
+                </h3>
+              )}
+              {artist && (
+                <p className="text-sm text-muted-foreground truncate">
+                  {artist}
+                </p>
+              )}
+            </div>
+          )}
+
+          {/* Audio Player */}
+          <AudioPlayer
+            ref={containerRef}
+            showControls
+            showWaveform={showWaveform}
+            showEqualizer={showEqualizer}
+            showTimer={showTimer}
+            showVolume={showVolume}
+            equalizerOptions={equalizerOptions}
+            className="border-0 bg-transparent"
+          />
+        </div>
+      </div>
+    </AudioProvider>
+  );
+}
+
+export default SimpleAudioPlayer;

package/src/tools/AudioPlayer/VisualizationToggle.tsx

@@ -0,0 +1,68 @@
+'use client';
+
+/**
+ * VisualizationToggle - Simple toggle for audio visualization settings
+ *
+ * Click: cycle through variants
+ * Long press / right click: opens menu (future)
+ */
+
+import { Sparkles } from 'lucide-react';
+import { Button, cn } from '@djangocfg/ui-nextjs';
+import {
+  useAudioVisualization,
+  VARIANT_INFO,
+  type VisualizationVariant,
+} from './useAudioVisualization';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface VisualizationToggleProps {
+  /** Compact mode (icon only) */
+  compact?: boolean;
+  /** Additional class name */
+  className?: string;
+}
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export function VisualizationToggle({
+  compact = false,
+  className,
+}: VisualizationToggleProps) {
+  const { settings, nextVariant } = useAudioVisualization();
+
+  const currentInfo = VARIANT_INFO[settings.variant];
+  const isEnabled = settings.variant !== 'none';
+
+  return (
+    <Button
+      variant={isEnabled ? 'secondary' : 'ghost'}
+      size={compact ? 'icon' : 'sm'}
+      className={cn(
+        'transition-all',
+        isEnabled && 'bg-primary/10 text-primary hover:bg-primary/20',
+        className
+      )}
+      onClick={nextVariant}
+      title={`Visualization: ${currentInfo.label} (click to change)`}
+    >
+      <Sparkles
+        className={cn(
+          'h-4 w-4',
+          isEnabled && 'text-primary',
+          !compact && 'mr-1.5'
+        )}
+      />
+      {!compact && (
+        <span className="text-xs">{currentInfo.label}</span>
+      )}
+    </Button>
+  );
+}
+
+export default VisualizationToggle;