@djangocfg/ui-nextjs 2.1.65 → 2.1.67

package/src/tools/AudioPlayer/components/AudioPlayer.tsx

@@ -0,0 +1,231 @@
+'use client';
+
+/**
+ * AudioPlayer - Audio playback controls and waveform display
+ *
+ * Uses AudioContext for state management
+ * Renders waveform (via container ref), controls, timer, and equalizer
+ * Supports keyboard shortcuts for playback control
+ */
+
+import { forwardRef } from 'react';
+import {
+  Play,
+  Pause,
+  RotateCcw,
+  SkipBack,
+  SkipForward,
+  Volume2,
+  VolumeX,
+  Loader2,
+  Repeat,
+} from 'lucide-react';
+import { Button, Slider, cn } from '@djangocfg/ui-nextjs';
+import { useAudio } from '../context';
+import { AudioEqualizer } from './AudioEqualizer';
+import { useAudioHotkeys } from '../hooks';
+import { AudioShortcutsPopover } from './AudioShortcutsPopover';
+import { formatTime } from '../utils';
+import type { AudioPlayerProps } from '../types';
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export const AudioPlayer = forwardRef<HTMLDivElement, AudioPlayerProps>(
+  function AudioPlayer(
+    {
+      showControls = true,
+      showWaveform = true,
+      showEqualizer = false,
+      showTimer = true,
+      showVolume = true,
+      showLoop = true,
+      equalizerOptions = {},
+      className,
+      style,
+    },
+    ref
+  ) {
+    // Get all state and controls from context
+    const {
+      isReady,
+      isPlaying,
+      currentTime,
+      duration,
+      volume,
+      isMuted,
+      isLooping,
+      togglePlay,
+      restart,
+      skip,
+      setVolume,
+      toggleMute,
+      toggleLoop,
+    } = useAudio();
+
+    // Enable keyboard shortcuts
+    useAudioHotkeys({ enabled: isReady });
+
+    const isLoading = !isReady;
+
+    const handleVolumeChange = (value: number[]) => {
+      setVolume(value[0] / 100);
+    };
+
+    return (
+      <div
+        className={cn(
+          'flex flex-col gap-3 p-4 rounded-lg bg-card border',
+          className
+        )}
+        style={style}
+      >
+        {/* Waveform container - rendered by WaveSurfer via context */}
+        {showWaveform && (
+          <div className="relative">
+            <div
+              ref={ref}
+              className={cn(
+                'w-full rounded transition-opacity',
+                isLoading && 'opacity-50'
+              )}
+            />
+            {isLoading && (
+              <div className="absolute inset-0 flex items-center justify-center">
+                <Loader2 className="h-6 w-6 animate-spin text-primary" />
+              </div>
+            )}
+          </div>
+        )}
+
+        {/* Equalizer animation */}
+        {showEqualizer && (
+          <AudioEqualizer
+            barCount={equalizerOptions.barCount}
+            height={equalizerOptions.height}
+            gap={equalizerOptions.gap}
+            showPeaks={equalizerOptions.showPeaks}
+            barColor={equalizerOptions.barColor}
+            peakColor={equalizerOptions.peakColor}
+            className="px-1"
+          />
+        )}
+
+        {/* Timer */}
+        {showTimer && (
+          <div className="flex justify-between text-xs text-muted-foreground tabular-nums px-1">
+            <span>{formatTime(currentTime)}</span>
+            <span>{formatTime(duration)}</span>
+          </div>
+        )}
+
+        {/* Controls */}
+        {showControls && (
+          <div className="flex items-center justify-center gap-1">
+            {/* Restart */}
+            <Button
+              variant="ghost"
+              size="icon"
+              className="h-9 w-9"
+              onClick={restart}
+              disabled={!isReady}
+              title="Restart"
+            >
+              <RotateCcw className="h-4 w-4" />
+            </Button>
+
+            {/* Skip back 5s */}
+            <Button
+              variant="ghost"
+              size="icon"
+              className="h-9 w-9"
+              onClick={() => skip(-5)}
+              disabled={!isReady}
+              title="Back 5 seconds"
+            >
+              <SkipBack className="h-4 w-4" />
+            </Button>
+
+            {/* Play/Pause */}
+            <Button
+              variant="default"
+              size="icon"
+              className="h-12 w-12 rounded-full"
+              onClick={togglePlay}
+              disabled={!isReady && !isLoading}
+              title={isPlaying ? 'Pause' : 'Play'}
+            >
+              {isLoading ? (
+                <Loader2 className="h-5 w-5 animate-spin" />
+              ) : isPlaying ? (
+                <Pause className="h-5 w-5" />
+              ) : (
+                <Play className="h-5 w-5 ml-0.5" />
+              )}
+            </Button>
+
+            {/* Skip forward 5s */}
+            <Button
+              variant="ghost"
+              size="icon"
+              className="h-9 w-9"
+              onClick={() => skip(5)}
+              disabled={!isReady}
+              title="Forward 5 seconds"
+            >
+              <SkipForward className="h-4 w-4" />
+            </Button>
+
+            {/* Volume */}
+            {showVolume && (
+              <>
+                <Button
+                  variant="ghost"
+                  size="icon"
+                  className="h-9 w-9"
+                  onClick={toggleMute}
+                  title={isMuted ? 'Unmute' : 'Mute'}
+                >
+                  {isMuted || volume === 0 ? (
+                    <VolumeX className="h-4 w-4" />
+                  ) : (
+                    <Volume2 className="h-4 w-4" />
+                  )}
+                </Button>
+
+                <Slider
+                  value={[isMuted ? 0 : volume * 100]}
+                  max={100}
+                  step={1}
+                  onValueChange={handleVolumeChange}
+                  className="w-20"
+                  aria-label="Volume"
+                />
+              </>
+            )}
+
+            {/* Loop/Repeat */}
+            {showLoop && (
+              <Button
+                variant="ghost"
+                size="icon"
+                className={cn('h-9 w-9', isLooping && 'text-primary')}
+                onClick={toggleLoop}
+                disabled={!isReady}
+                title={isLooping ? 'Disable loop' : 'Enable loop'}
+              >
+                <Repeat className="h-4 w-4" />
+              </Button>
+            )}
+
+            {/* Shortcuts help */}
+            <AudioShortcutsPopover compact />
+          </div>
+        )}
+      </div>
+    );
+  }
+);
+
+export default AudioPlayer;

package/src/tools/AudioPlayer/components/AudioShortcutsPopover.tsx

@@ -0,0 +1,99 @@
+'use client';
+
+/**
+ * AudioShortcutsPopover
+ *
+ * Displays keyboard shortcuts for audio player controls.
+ */
+
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+  Button,
+  Kbd,
+  KbdGroup,
+  Separator,
+  Tooltip,
+  TooltipTrigger,
+  TooltipContent,
+} from '@djangocfg/ui-nextjs';
+import { Keyboard } from 'lucide-react';
+import { AUDIO_SHORTCUTS } from '../hooks';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+interface AudioShortcutsPopoverProps {
+  /** Compact mode for smaller displays */
+  compact?: boolean;
+}
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export function AudioShortcutsPopover({ compact = false }: AudioShortcutsPopoverProps) {
+  const trigger = (
+    <PopoverTrigger asChild>
+      <Button
+        variant="ghost"
+        size="icon"
+        className={compact ? 'h-6 w-6' : 'size-7 text-muted-foreground hover:text-foreground'}
+        title={compact ? undefined : 'Keyboard shortcuts'}
+      >
+        <Keyboard className={compact ? 'h-3.5 w-3.5' : 'size-4'} />
+      </Button>
+    </PopoverTrigger>
+  );
+
+  return (
+    <Popover>
+      {compact ? (
+        <Tooltip>
+          <TooltipTrigger asChild>{trigger}</TooltipTrigger>
+          <TooltipContent side="bottom">Shortcuts</TooltipContent>
+        </Tooltip>
+      ) : (
+        trigger
+      )}
+      <PopoverContent className="w-56 p-0" align="end">
+        <div className="px-3 py-2 border-b">
+          <h4 className="font-medium text-sm">Player Shortcuts</h4>
+        </div>
+        <div className="p-2 space-y-3 max-h-72 overflow-y-auto">
+          {AUDIO_SHORTCUTS.map((group, groupIndex) => (
+            <div key={group.title}>
+              {groupIndex > 0 && <Separator className="my-2" />}
+              <div className="text-xs font-medium text-muted-foreground mb-1.5 px-1">
+                {group.title}
+              </div>
+              <div className="space-y-1">
+                {group.shortcuts.map((shortcut) => (
+                  <div
+                    key={shortcut.label}
+                    className="flex items-center justify-between px-1 py-0.5"
+                  >
+                    <span className="text-sm text-foreground">
+                      {shortcut.label}
+                    </span>
+                    <KbdGroup>
+                      {shortcut.keys.map((key, i) => (
+                        <Kbd key={i} size="sm">
+                          {key}
+                        </Kbd>
+                      ))}
+                    </KbdGroup>
+                  </div>
+                ))}
+              </div>
+            </div>
+          ))}
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+export default AudioShortcutsPopover;

package/src/tools/AudioPlayer/components/ReactiveCover/AudioReactiveCover.tsx

@@ -0,0 +1,147 @@
+'use client';
+
+/**
+ * AudioReactiveCover - Album art with audio-reactive animations
+ *
+ * Uses effects utilities for clean data preparation before render.
+ * Click on cover to switch between effect variants.
+ *
+ * Audio analysis is performed in the AudioProvider context to persist
+ * across variant changes (including switching to 'none' and back).
+ */
+
+import { type ReactNode } from 'react';
+import { cn } from '@djangocfg/ui-nextjs';
+import { useAudioElement } from '../../context';
+import {
+  type EffectVariant,
+  type EffectIntensity,
+  type EffectColorScheme,
+  getEffectConfig,
+  prepareEffectColors,
+  calculateGlowLayers,
+  calculateOrbs,
+  calculateMeshGradients,
+  calculateSpotlight,
+  EFFECT_ANIMATIONS,
+} from '../../effects';
+import { GlowEffect, OrbsEffect, SpotlightEffect, MeshEffect, type GlowEffectData } from './effects';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface AudioReactiveCoverProps {
+  children: ReactNode;
+  size?: 'sm' | 'md' | 'lg';
+  variant?: EffectVariant;
+  intensity?: EffectIntensity;
+  colorScheme?: EffectColorScheme;
+  onClick?: () => void;
+  className?: string;
+}
+
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+
+const SIZES = {
+  sm: { container: 'w-32 h-32', orbBase: 40 },
+  md: { container: 'w-40 h-40', orbBase: 50 },
+  lg: { container: 'w-48 h-48', orbBase: 60 },
+};
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export function AudioReactiveCover({
+  children,
+  size = 'lg',
+  variant = 'spotlight',
+  intensity = 'medium',
+  colorScheme = 'primary',
+  onClick,
+  className,
+}: AudioReactiveCoverProps) {
+  // Get audio levels from context (persists across variant changes)
+  const { isPlaying, audioLevels: levels } = useAudioElement();
+
+  // =========================================================================
+  // PREPARE DATA BEFORE RENDER
+  // =========================================================================
+
+  const sizeConfig = SIZES[size];
+  const effectConfig = getEffectConfig(intensity);
+  const { colors, hueShift } = prepareEffectColors(colorScheme, levels);
+
+  // Calculate scale based on overall level
+  const containerScale = 1 + levels.overall * effectConfig.scale;
+
+  // Prepare effect-specific data - NO memoization for real-time reactivity
+  const glowData: GlowEffectData | null = variant === 'glow' ? {
+    layers: calculateGlowLayers(levels, effectConfig, colors),
+    hueShift,
+    showPulseRings: levels.bass > 0.5,
+    showSparkle: levels.high > 0.4,
+  } : null;
+
+  const orbsData = variant === 'orbs'
+    ? calculateOrbs(levels, effectConfig, colors, sizeConfig.orbBase)
+    : null;
+
+  const meshData = variant === 'mesh'
+    ? calculateMeshGradients(levels, effectConfig, colors)
+    : null;
+
+  const spotlightData = variant === 'spotlight'
+    ? calculateSpotlight(levels, effectConfig, colors, levels.mid * 360)
+    : null;
+
+  // =========================================================================
+  // RENDER
+  // =========================================================================
+
+  return (
+    <div
+      className={cn('relative', sizeConfig.container, className)}
+      style={{
+        transform: `scale(${containerScale})`,
+        transition: 'transform 0.1s ease-out',
+      }}
+    >
+      {/* Effect layers */}
+      {glowData && (
+        <GlowEffect data={glowData} colors={colors} isPlaying={isPlaying} />
+      )}
+
+      {orbsData && (
+        <OrbsEffect orbs={orbsData} blur={effectConfig.blur} isPlaying={isPlaying} />
+      )}
+
+      {spotlightData && (
+        <SpotlightEffect data={spotlightData} colors={colors} blur={effectConfig.blur} isPlaying={isPlaying} />
+      )}
+
+      {meshData && (
+        <MeshEffect gradients={meshData} blur={effectConfig.blur} isPlaying={isPlaying} />
+      )}
+
+      {/* Content (cover art) */}
+      <div
+        className="relative w-full h-full rounded-lg overflow-hidden shadow-2xl z-10 bg-background cursor-pointer"
+        onClick={onClick}
+        role={onClick ? 'button' : undefined}
+        tabIndex={onClick ? 0 : undefined}
+        onKeyDown={onClick ? (e) => e.key === 'Enter' && onClick() : undefined}
+      >
+        {children}
+      </div>
+
+      {/* Inject animations once */}
+      <style dangerouslySetInnerHTML={{ __html: EFFECT_ANIMATIONS }} />
+    </div>
+  );
+}
+
+export default AudioReactiveCover;

package/src/tools/AudioPlayer/components/ReactiveCover/effects/GlowEffect.tsx

@@ -0,0 +1,110 @@
+'use client';
+
+/**
+ * GlowEffect - Multi-layer glow effect with pulse rings
+ */
+
+import { cn } from '@djangocfg/ui-nextjs';
+import type { calculateGlowLayers } from '../../../effects';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface GlowEffectData {
+  layers: ReturnType<typeof calculateGlowLayers>;
+  hueShift: number;
+  showPulseRings: boolean;
+  showSparkle: boolean;
+}
+
+interface GlowEffectProps {
+  data: GlowEffectData;
+  colors: string[];
+  isPlaying: boolean;
+}
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export function GlowEffect({ data, colors, isPlaying }: GlowEffectProps) {
+  const { layers, hueShift, showPulseRings, showSparkle } = data;
+
+  return (
+    <>
+      {/* Main glow layers */}
+      {layers.map((layer, i) => (
+        <div
+          key={i}
+          className={cn('absolute rounded-2xl -z-10', layer.blur)}
+          style={{
+            inset: `-${layer.inset}px`,
+            background: layer.background,
+            opacity: isPlaying ? layer.opacity : 0,
+            transform: i < 2 ? `scaleY(${layer.scale})` : `scale(${layer.scale})`,
+            animation: isPlaying && layer.animation ? layer.animation : 'none',
+            transition: 'opacity 0.3s',
+          }}
+        />
+      ))}
+
+      {/* Rotating color sweep */}
+      <div
+        className="absolute rounded-2xl blur-xl overflow-hidden -z-10"
+        style={{
+          inset: '-75px',
+          opacity: isPlaying ? 0.6 : 0,
+          transition: 'opacity 0.5s',
+        }}
+      >
+        <div
+          className="absolute inset-0"
+          style={{
+            background: `conic-gradient(
+              from ${hueShift}deg at 50% 50%,
+              hsl(${colors[0]} / 0.4) 0deg,
+              hsl(${colors[1] || colors[0]} / 0.3) 90deg,
+              hsl(${colors[2] || colors[0]} / 0.3) 180deg,
+              hsl(${colors[3] || colors[0]} / 0.3) 270deg,
+              hsl(${colors[0]} / 0.4) 360deg
+            )`,
+            animation: isPlaying ? 'glow-rotate 6s linear infinite' : 'none',
+          }}
+        />
+      </div>
+
+      {/* Pulse rings on bass hits */}
+      {showPulseRings && (
+        <>
+          <div
+            className="absolute -inset-6 rounded-xl border-2 animate-ping -z-10"
+            style={{
+              borderColor: `hsl(${colors[0]} / 0.4)`,
+              animationDuration: '1s',
+            }}
+          />
+          <div
+            className="absolute -inset-12 rounded-2xl border animate-ping -z-10"
+            style={{
+              borderColor: `hsl(${colors[1] || colors[0]} / 0.3)`,
+              animationDuration: '1.5s',
+              animationDelay: '0.2s',
+            }}
+          />
+        </>
+      )}
+
+      {/* Sparkle on high frequencies */}
+      {showSparkle && (
+        <div
+          className="absolute -inset-18 rounded-3xl -z-10"
+          style={{
+            background: `radial-gradient(circle at 50% 30%, hsl(${colors[2] || colors[0]} / 0.5) 0%, transparent 30%)`,
+            animation: 'sparkle-move 0.5s ease-out',
+          }}
+        />
+      )}
+    </>
+  );
+}

package/src/tools/AudioPlayer/components/ReactiveCover/effects/MeshEffect.tsx

@@ -0,0 +1,58 @@
+'use client';
+
+/**
+ * MeshEffect - Mesh gradient blobs that react to audio
+ */
+
+import { cn } from '@djangocfg/ui-nextjs';
+import type { calculateMeshGradients } from '../../../effects';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+interface MeshEffectProps {
+  gradients: ReturnType<typeof calculateMeshGradients>;
+  blur: string;
+  isPlaying: boolean;
+}
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export function MeshEffect({ gradients, isPlaying }: MeshEffectProps) {
+  return (
+    <>
+      {gradients.map((g, i) => {
+        const isCenter = 'isCenter' in g && g.isCenter;
+        const scale = 'scale' in g ? g.scale : 1;
+        const rotation = 'rotation' in g ? g.rotation : 0;
+        const itemBlur = 'blur' in g ? g.blur : 'blur-2xl';
+
+        return (
+          <div
+            key={i}
+            className={cn('absolute rounded-full -z-10', itemBlur)}
+            style={{
+              width: g.width,
+              height: g.height,
+              top: 'top' in g ? g.top : undefined,
+              bottom: 'bottom' in g ? g.bottom : undefined,
+              left: 'left' in g ? g.left : undefined,
+              right: 'right' in g ? g.right : undefined,
+              background: isCenter
+                ? `radial-gradient(circle, hsl(${g.color} / 0.6) 0%, hsl(${g.color} / 0.3) 30%, transparent 60%)`
+                : `radial-gradient(circle, hsl(${g.color}) 0%, hsl(${g.color} / 0.5) 30%, transparent 65%)`,
+              opacity: isPlaying ? g.opacity : 0,
+              transform: isCenter
+                ? `translate(-50%, -50%) scale(${scale})`
+                : `scale(${scale}) rotate(${rotation}deg)`,
+              transition: 'all 0.08s ease-out',
+            }}
+          />
+        );
+      })}
+    </>
+  );
+}

package/src/tools/AudioPlayer/components/ReactiveCover/effects/OrbsEffect.tsx

@@ -0,0 +1,45 @@
+'use client';
+
+/**
+ * OrbsEffect - Floating orb particles that react to audio
+ */
+
+import { cn } from '@djangocfg/ui-nextjs';
+import type { calculateOrbs } from '../../../effects';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+interface OrbsEffectProps {
+  orbs: ReturnType<typeof calculateOrbs>;
+  blur: string;
+  isPlaying: boolean;
+}
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export function OrbsEffect({ orbs, blur, isPlaying }: OrbsEffectProps) {
+  return (
+    <>
+      {orbs.map((orb, i) => (
+        <div
+          key={i}
+          className={cn('absolute rounded-full -z-10', blur)}
+          style={{
+            width: orb.size,
+            height: orb.size,
+            left: `${orb.x}%`,
+            top: `${orb.y}%`,
+            background: `radial-gradient(circle at 30% 30%, hsl(${orb.color}) 0%, hsl(${orb.color} / 0.5) 40%, transparent 70%)`,
+            opacity: isPlaying ? orb.opacity : 0,
+            transform: `translate(-50%, -50%) scale(${orb.scale})`,
+            transition: 'all 0.08s ease-out',
+          }}
+        />
+      ))}
+    </>
+  );
+}