@djangocfg/ui-nextjs 2.1.70 → 2.1.71

package/src/tools/AudioPlayer/progressive/ProgressiveAudioPlayer.tsx

@@ -0,0 +1,295 @@
+'use client';
+
+/**
+ * ProgressiveAudioPlayer - Audio player with progressive waveform loading
+ *
+ * Uses native HTML5 audio for playback (supports Range requests)
+ * and custom canvas for waveform visualization.
+ *
+ * Features:
+ * - Progressive waveform loading (no need to load entire file)
+ * - Smooth seek on any position
+ * - Buffered ranges visualization
+ * - Keyboard shortcuts
+ * - Volume control
+ * - Loop mode
+ */
+
+import { useRef, useCallback } from 'react';
+import {
+  Play,
+  Pause,
+  RotateCcw,
+  SkipBack,
+  SkipForward,
+  Volume2,
+  VolumeX,
+  Loader2,
+  Repeat,
+  AlertCircle,
+} from 'lucide-react';
+import { cn, Button, Slider } from '@djangocfg/ui-core';
+
+import { useAudioElement } from './useAudioElement';
+import { useProgressiveWaveform } from './useProgressiveWaveform';
+import { WaveformCanvas } from './WaveformCanvas';
+import { formatTime } from '../utils';
+import type { ProgressiveAudioPlayerProps, WaveformStyle } from './types';
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export function ProgressiveAudioPlayer({
+  src,
+  title,
+  artist,
+  coverArt,
+  showWaveform = true,
+  showControls = true,
+  showTimer = true,
+  showVolume = true,
+  showLoop = true,
+  autoPlay = false,
+  waveformStyle,
+  className,
+  onPlay,
+  onPause,
+  onEnded,
+  onTimeUpdate,
+  onError,
+}: ProgressiveAudioPlayerProps) {
+  const audioRef = useRef<HTMLAudioElement>(null);
+
+  // Audio element hook
+  const audio = useAudioElement({
+    src,
+    autoPlay,
+    onPlay,
+    onPause,
+    onEnded,
+    onTimeUpdate,
+    onError,
+  });
+
+  // Progressive waveform loading
+  const waveform = useProgressiveWaveform({
+    url: src,
+    duration: audio.duration,
+    enabled: showWaveform,
+  });
+
+  // Handlers
+  const handleSeek = useCallback((time: number) => {
+    audio.seek(time);
+  }, [audio]);
+
+  const handleVolumeChange = useCallback((value: number[]) => {
+    audio.setVolume(value[0] / 100);
+  }, [audio]);
+
+  // Loading state
+  const isLoading = !audio.isReady;
+  const hasError = audio.error || waveform.error;
+
+  // Default waveform style
+  const defaultStyle: WaveformStyle = {
+    waveColor: 'hsl(217 91% 60% / 0.3)',
+    progressColor: 'hsl(217 91% 60%)',
+    loadingColor: 'hsl(217 91% 60% / 0.1)',
+    cursorColor: 'hsl(217 91% 60%)',
+    barWidth: 3,
+    barGap: 2,
+    barRadius: 2,
+    height: 64,
+    ...waveformStyle,
+  };
+
+  return (
+    <div className={cn('flex flex-col gap-3 p-4 rounded-lg bg-card border', className)}>
+      {/* Hidden audio element */}
+      <audio
+        ref={(el) => {
+          (audioRef as any).current = el;
+          (audio.audioRef as any).current = el;
+        }}
+        preload="metadata"
+        crossOrigin="anonymous"
+      />
+
+      {/* Header with title/artist */}
+      {(title || artist) && (
+        <div className="text-center">
+          {title && <h3 className="text-sm font-medium truncate">{title}</h3>}
+          {artist && <p className="text-xs text-muted-foreground truncate">{artist}</p>}
+        </div>
+      )}
+
+      {/* Waveform */}
+      {showWaveform && (
+        <div className="relative">
+          <WaveformCanvas
+            peaks={waveform.peaks}
+            currentTime={audio.currentTime}
+            duration={audio.duration}
+            buffered={audio.buffered}
+            loadingPercent={waveform.loadedPercent}
+            onSeek={handleSeek}
+            interactive={audio.isReady}
+            style={defaultStyle}
+            className={cn(
+              'rounded transition-opacity',
+              isLoading && 'opacity-50'
+            )}
+          />
+
+          {/* Loading overlay */}
+          {isLoading && (
+            <div className="absolute inset-0 flex items-center justify-center">
+              <Loader2 className="h-6 w-6 animate-spin text-primary" />
+            </div>
+          )}
+
+          {/* Error overlay */}
+          {hasError && (
+            <div className="absolute inset-0 flex items-center justify-center bg-destructive/10 rounded">
+              <div className="flex items-center gap-2 text-destructive text-sm">
+                <AlertCircle className="h-4 w-4" />
+                <span>Failed to load</span>
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  onClick={waveform.retry}
+                  className="h-6 px-2"
+                >
+                  Retry
+                </Button>
+              </div>
+            </div>
+          )}
+
+          {/* Loading progress indicator */}
+          {waveform.isLoading && !isLoading && (
+            <div className="absolute bottom-0 left-0 right-0 h-0.5 bg-muted overflow-hidden rounded-full">
+              <div
+                className="h-full bg-primary transition-all duration-300"
+                style={{ width: `${waveform.loadedPercent}%` }}
+              />
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Timer */}
+      {showTimer && (
+        <div className="flex justify-between text-xs text-muted-foreground tabular-nums px-1">
+          <span>{formatTime(audio.currentTime)}</span>
+          <span>{formatTime(audio.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={() => audio.seek(0)}
+            disabled={!audio.isReady}
+            title="Restart"
+          >
+            <RotateCcw className="h-4 w-4" />
+          </Button>
+
+          {/* Skip back 5s */}
+          <Button
+            variant="ghost"
+            size="icon"
+            className="h-9 w-9"
+            onClick={() => audio.skip(-5)}
+            disabled={!audio.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={audio.togglePlay}
+            disabled={!audio.isReady && !isLoading}
+            title={audio.isPlaying ? 'Pause' : 'Play'}
+          >
+            {isLoading ? (
+              <Loader2 className="h-5 w-5 animate-spin" />
+            ) : audio.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={() => audio.skip(5)}
+            disabled={!audio.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={audio.toggleMute}
+                title={audio.isMuted ? 'Unmute' : 'Mute'}
+              >
+                {audio.isMuted || audio.volume === 0 ? (
+                  <VolumeX className="h-4 w-4" />
+                ) : (
+                  <Volume2 className="h-4 w-4" />
+                )}
+              </Button>
+
+              <Slider
+                value={[audio.isMuted ? 0 : audio.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', audio.isLooping && 'text-primary')}
+              onClick={audio.toggleLoop}
+              disabled={!audio.isReady}
+              title={audio.isLooping ? 'Disable loop' : 'Enable loop'}
+            >
+              <Repeat className="h-4 w-4" />
+            </Button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default ProgressiveAudioPlayer;

package/src/tools/AudioPlayer/progressive/WaveformCanvas.tsx

@@ -0,0 +1,381 @@
+'use client';
+
+/**
+ * WaveformCanvas - Canvas-based waveform visualization
+ *
+ * Features:
+ * - Progressive rendering as peaks load
+ * - Playback progress overlay
+ * - Buffered ranges indicator
+ * - Interactive seek (click/drag)
+ * - Hover preview
+ * - High DPI support
+ */
+
+import {
+  useRef,
+  useEffect,
+  useCallback,
+  useState,
+  forwardRef,
+  useImperativeHandle,
+} from 'react';
+import { cn } from '@djangocfg/ui-core';
+import type { WaveformStyle, LoadedRange } from './types';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+interface WaveformCanvasProps {
+  /** Peaks data (0-1 normalized) */
+  peaks: number[];
+  /** Current playback time (seconds) */
+  currentTime: number;
+  /** Total duration (seconds) */
+  duration: number;
+  /** Buffered ranges from audio element */
+  buffered?: TimeRanges | null;
+  /** Loaded ranges (for progressive loading indicator) */
+  loadedRanges?: LoadedRange[];
+  /** Loading progress (0-100) */
+  loadingPercent?: number;
+  /** Seek callback */
+  onSeek?: (time: number) => void;
+  /** Hover callback */
+  onHover?: (time: number | null) => void;
+  /** Is interactive */
+  interactive?: boolean;
+  /** Style options */
+  style?: WaveformStyle;
+  /** Additional class */
+  className?: string;
+}
+
+export interface WaveformCanvasRef {
+  redraw: () => void;
+}
+
+// =============================================================================
+// DEFAULT STYLES
+// =============================================================================
+
+const DEFAULT_STYLE: Required<WaveformStyle> = {
+  waveColor: 'hsl(217 91% 60% / 0.3)',
+  progressColor: 'hsl(217 91% 60%)',
+  loadingColor: 'hsl(217 91% 60% / 0.1)',
+  cursorColor: 'hsl(217 91% 60%)',
+  barWidth: 3,
+  barGap: 2,
+  barRadius: 2,
+  height: 64,
+};
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export const WaveformCanvas = forwardRef<WaveformCanvasRef, WaveformCanvasProps>(
+  function WaveformCanvas(props, ref) {
+    const {
+      peaks,
+      currentTime,
+      duration,
+      buffered,
+      loadedRanges = [],
+      loadingPercent = 100,
+      onSeek,
+      onHover,
+      interactive = true,
+      style = {},
+      className,
+    } = props;
+
+    const canvasRef = useRef<HTMLCanvasElement>(null);
+    const containerRef = useRef<HTMLDivElement>(null);
+    const [hoverX, setHoverX] = useState<number | null>(null);
+    const [isDragging, setIsDragging] = useState(false);
+
+    // Merge styles
+    const {
+      waveColor,
+      progressColor,
+      loadingColor,
+      cursorColor,
+      barWidth,
+      barGap,
+      barRadius,
+      height,
+    } = { ...DEFAULT_STYLE, ...style };
+
+    // ==========================================================================
+    // DRAWING
+    // ==========================================================================
+
+    const draw = useCallback(() => {
+      const canvas = canvasRef.current;
+      const container = containerRef.current;
+      if (!canvas || !container) return;
+
+      const ctx = canvas.getContext('2d');
+      if (!ctx) return;
+
+      // Get dimensions
+      const rect = container.getBoundingClientRect();
+      const width = rect.width;
+      const dpr = window.devicePixelRatio || 1;
+
+      // Set canvas size with DPI scaling
+      canvas.width = width * dpr;
+      canvas.height = height * dpr;
+      canvas.style.width = `${width}px`;
+      canvas.style.height = `${height}px`;
+      ctx.scale(dpr, dpr);
+
+      // Clear
+      ctx.clearRect(0, 0, width, height);
+
+      // Calculate bar positions
+      const totalBarSpace = barWidth + barGap;
+      const barCount = Math.floor(width / totalBarSpace);
+
+      if (barCount === 0) return;
+
+      // Progress position
+      const progress = duration > 0 ? currentTime / duration : 0;
+      const progressX = progress * width;
+
+      // Hover position
+      const hoverProgress = hoverX !== null ? hoverX / width : null;
+
+      // Draw loading placeholder for unloaded area
+      if (loadingPercent < 100) {
+        const loadedX = (loadingPercent / 100) * width;
+        ctx.fillStyle = loadingColor;
+        ctx.fillRect(loadedX, 0, width - loadedX, height);
+      }
+
+      // Resample peaks to match bar count
+      const resampledPeaks = resamplePeaks(peaks, barCount);
+
+      // Draw bars
+      for (let i = 0; i < barCount; i++) {
+        const x = i * totalBarSpace;
+        const peakValue = resampledPeaks[i] || 0;
+
+        // Bar height (minimum 2px for visibility)
+        const barHeight = Math.max(2, peakValue * (height - 4));
+        const y = (height - barHeight) / 2;
+
+        // Determine color based on position
+        const barProgress = (x + barWidth / 2) / width;
+        let color = waveColor;
+
+        if (barProgress <= progress) {
+          color = progressColor;
+        }
+
+        // Draw bar
+        ctx.fillStyle = color;
+        if (barRadius > 0) {
+          roundRect(ctx, x, y, barWidth, barHeight, barRadius);
+        } else {
+          ctx.fillRect(x, y, barWidth, barHeight);
+        }
+      }
+
+      // Draw cursor
+      if (duration > 0) {
+        ctx.fillStyle = cursorColor;
+        ctx.fillRect(progressX - 1, 0, 2, height);
+      }
+
+      // Draw hover indicator
+      if (hoverProgress !== null && interactive) {
+        ctx.fillStyle = `${cursorColor}80`; // 50% opacity
+        const hoverPx = hoverProgress * width;
+        ctx.fillRect(hoverPx - 1, 0, 2, height);
+      }
+
+      // Draw buffered indicator (thin line at bottom)
+      if (buffered && buffered.length > 0 && duration > 0) {
+        ctx.fillStyle = `${progressColor}40`;
+        for (let i = 0; i < buffered.length; i++) {
+          const start = (buffered.start(i) / duration) * width;
+          const end = (buffered.end(i) / duration) * width;
+          ctx.fillRect(start, height - 2, end - start, 2);
+        }
+      }
+    }, [
+      peaks,
+      currentTime,
+      duration,
+      buffered,
+      loadingPercent,
+      hoverX,
+      waveColor,
+      progressColor,
+      loadingColor,
+      cursorColor,
+      barWidth,
+      barGap,
+      barRadius,
+      height,
+      interactive,
+    ]);
+
+    // ==========================================================================
+    // INTERACTION HANDLERS
+    // ==========================================================================
+
+    const getTimeFromX = useCallback((clientX: number): number => {
+      const container = containerRef.current;
+      if (!container || duration <= 0) return 0;
+
+      const rect = container.getBoundingClientRect();
+      const x = clientX - rect.left;
+      const progress = Math.max(0, Math.min(1, x / rect.width));
+      return progress * duration;
+    }, [duration]);
+
+    const handleMouseMove = useCallback((e: React.MouseEvent) => {
+      if (!interactive) return;
+
+      const container = containerRef.current;
+      if (!container) return;
+
+      const rect = container.getBoundingClientRect();
+      const x = e.clientX - rect.left;
+      setHoverX(x);
+
+      const time = getTimeFromX(e.clientX);
+      onHover?.(time);
+
+      if (isDragging) {
+        onSeek?.(time);
+      }
+    }, [interactive, isDragging, getTimeFromX, onHover, onSeek]);
+
+    const handleMouseLeave = useCallback(() => {
+      setHoverX(null);
+      onHover?.(null);
+      setIsDragging(false);
+    }, [onHover]);
+
+    const handleMouseDown = useCallback((e: React.MouseEvent) => {
+      if (!interactive) return;
+      e.preventDefault();
+      setIsDragging(true);
+      const time = getTimeFromX(e.clientX);
+      onSeek?.(time);
+    }, [interactive, getTimeFromX, onSeek]);
+
+    const handleMouseUp = useCallback(() => {
+      setIsDragging(false);
+    }, []);
+
+    // Global mouseup for drag release
+    useEffect(() => {
+      if (!isDragging) return;
+
+      const handleGlobalMouseUp = () => setIsDragging(false);
+      window.addEventListener('mouseup', handleGlobalMouseUp);
+      return () => window.removeEventListener('mouseup', handleGlobalMouseUp);
+    }, [isDragging]);
+
+    // ==========================================================================
+    // EFFECTS
+    // ==========================================================================
+
+    // Redraw on any change
+    useEffect(() => {
+      draw();
+    }, [draw]);
+
+    // Redraw on resize
+    useEffect(() => {
+      const handleResize = () => draw();
+      window.addEventListener('resize', handleResize);
+      return () => window.removeEventListener('resize', handleResize);
+    }, [draw]);
+
+    // Expose redraw method
+    useImperativeHandle(ref, () => ({
+      redraw: draw,
+    }), [draw]);
+
+    return (
+      <div
+        ref={containerRef}
+        className={cn(
+          'relative w-full cursor-pointer select-none',
+          !interactive && 'cursor-default',
+          className
+        )}
+        style={{ height }}
+        onMouseMove={handleMouseMove}
+        onMouseLeave={handleMouseLeave}
+        onMouseDown={handleMouseDown}
+        onMouseUp={handleMouseUp}
+      >
+        <canvas
+          ref={canvasRef}
+          className="absolute inset-0"
+        />
+      </div>
+    );
+  }
+);
+
+// =============================================================================
+// HELPERS
+// =============================================================================
+
+/**
+ * Draw rounded rectangle
+ */
+function roundRect(
+  ctx: CanvasRenderingContext2D,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  radius: number
+) {
+  ctx.beginPath();
+  ctx.moveTo(x + radius, y);
+  ctx.lineTo(x + width - radius, y);
+  ctx.quadraticCurveTo(x + width, y, x + width, y + radius);
+  ctx.lineTo(x + width, y + height - radius);
+  ctx.quadraticCurveTo(x + width, y + height, x + width - radius, y + height);
+  ctx.lineTo(x + radius, y + height);
+  ctx.quadraticCurveTo(x, y + height, x, y + height - radius);
+  ctx.lineTo(x, y + radius);
+  ctx.quadraticCurveTo(x, y, x + radius, y);
+  ctx.closePath();
+  ctx.fill();
+}
+
+/**
+ * Resample peaks to target length
+ */
+function resamplePeaks(peaks: number[], targetLength: number): number[] {
+  if (peaks.length === 0) return new Array(targetLength).fill(0);
+  if (peaks.length === targetLength) return peaks;
+
+  const result = new Array<number>(targetLength);
+  const ratio = peaks.length / targetLength;
+
+  for (let i = 0; i < targetLength; i++) {
+    const start = Math.floor(i * ratio);
+    const end = Math.min(Math.ceil((i + 1) * ratio), peaks.length);
+
+    let max = 0;
+    for (let j = start; j < end; j++) {
+      if (peaks[j] > max) max = peaks[j];
+    }
+    result[i] = max;
+  }
+
+  return result;
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Progressive Audio Player
+ *
+ * Audio player with progressive waveform loading.
+ * Uses native HTML5 audio (supports Range requests) and custom canvas visualization.
+ */
+
+// Components
+export { ProgressiveAudioPlayer } from './ProgressiveAudioPlayer';
+export { WaveformCanvas } from './WaveformCanvas';
+
+// Hooks
+export { useAudioElement } from './useAudioElement';
+export { useProgressiveWaveform } from './useProgressiveWaveform';
+
+// Utilities
+export {
+  extractPeaks,
+  mergePeaks,
+  resamplePeaks,
+  smoothPeaks,
+  calculatePeaksCount,
+  timeToIndex,
+  indexToTime,
+} from './peaks';
+
+// Types
+export type {
+  WaveformData,
+  LoadedRange,
+  WaveformLoadingState,
+  AudioState,
+  AudioControls,
+  WaveformStyle,
+  WaveformInteraction,
+  ProgressiveAudioPlayerProps,
+  ChunkInfo,
+  DecodeResult,
+  DecoderOptions,
+} from './types';