@djangocfg/ui-nextjs 2.1.83 → 2.1.85

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-nextjs",
-  "version": "2.1.83",
+  "version": "2.1.85",
   "description": "Next.js UI component library with Radix UI primitives, Tailwind CSS styling, charts, and form components",
   "keywords": [
     "ui-components",
@@ -58,8 +58,8 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.83",
-    "@djangocfg/ui-core": "^2.1.83",
+    "@djangocfg/api": "^2.1.85",
+    "@djangocfg/ui-core": "^2.1.85",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "consola": "^3.4.2",
@@ -110,7 +110,7 @@
     "wavesurfer.js": "^7.12.1"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.83",
+    "@djangocfg/typescript-config": "^2.1.85",
     "@types/node": "^24.7.2",
     "eslint": "^9.37.0",
     "tailwindcss-animate": "1.0.7",

package/src/tools/AudioPlayer/README.md

@@ -1,30 +1,21 @@
 # AudioPlayer
 
-Audio player library with multiple player implementations for different use cases.
+Audio player with native HTML5 streaming and audio-reactive visualizations.
 
-## Player Comparison
+## Features
 
-| Feature | HybridSimplePlayer | SimpleAudioPlayer | ProgressiveAudioPlayer |
-|---------|-------------------|-------------------|------------------------|
-| **Recommended for** | Streaming, general use | Local files, full waveform | Large streaming files |
-| **Audio Engine** | HTML5 `<audio>` | WaveSurfer.js | HTML5 `<audio>` |
-| **Visualization** | Real-time frequency bars | Static waveform | Progressive waveform |
-| **Reactive Effects** | ✅ Full support | ✅ Full support | ❌ No |
-| **Streaming Support** | ✅ Native | ⚠️ Requires prefetch | ✅ Native |
-| **Seek Any Position** | ✅ Yes | ⚠️ Limited by buffer | ✅ Yes |
-| **No Crackling** | ✅ Guaranteed | ⚠️ Fixed in v2.1.82 | ✅ Yes |
-| **Memory Usage** | Low | High (full file) | Low |
+- Native HTML5 audio playback (no crackling, native streaming support)
+- Web Audio API for real-time frequency analysis
+- Audio-reactive cover effects (glow, orbs, spotlight, mesh)
+- Frequency visualization waveform
+- Full playback controls
 
----
-
-## Quick Start (Recommended)
-
-### HybridSimplePlayer — Best for Most Cases
+## Quick Start
 
 ```tsx
 import { HybridSimplePlayer } from '@djangocfg/ui-nextjs';
 
-// Minimal
+// Simple usage
 <HybridSimplePlayer src="https://example.com/audio.mp3" />
 
 // With metadata and reactive cover
@@ -43,15 +34,17 @@ import { HybridSimplePlayer } from '@djangocfg/ui-nextjs';
   title="Track Title"
   coverArt={coverUrl}
   showWaveform
+  waveformMode="frequency"  // 'frequency' | 'static'
+  showLoop
   reactiveCover
-  variant="spotlight"
-  intensity="medium"
-  colorScheme="vibrant"
-  layout="horizontal"
+  variant="spotlight"       // 'glow' | 'orbs' | 'spotlight' | 'mesh' | 'none'
+  intensity="medium"        // 'subtle' | 'medium' | 'strong'
+  colorScheme="primary"     // 'primary' | 'vibrant' | 'cool' | 'warm'
+  layout="horizontal"       // 'vertical' | 'horizontal'
 />
 ```
 
-### HybridSimplePlayer Props
+## Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -65,7 +58,7 @@ import { HybridSimplePlayer } from '@djangocfg/ui-nextjs';
 | `waveformHeight` | `number` | `64` | Waveform height in pixels |
 | `showTimer` | `boolean` | `true` | Show time display |
 | `showVolume` | `boolean` | `true` | Show volume control |
-| `showLoop` | `boolean` | `true` | Show loop/repeat button |
+| `showLoop` | `boolean` | `true` | Show loop button |
 | `reactiveCover` | `boolean` | `true` | Enable reactive effects |
 | `variant` | `VisualizationVariant` | `'spotlight'` | Effect variant |
 | `intensity` | `EffectIntensity` | `'medium'` | Effect intensity |
@@ -74,26 +67,27 @@ import { HybridSimplePlayer } from '@djangocfg/ui-nextjs';
 | `loop` | `boolean` | `false` | Loop playback |
 | `layout` | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction |
 
----
-
 ## Advanced Usage
 
-### Using HybridAudioProvider + HybridAudioPlayer
+### HybridAudioProvider + HybridAudioPlayer
 
-For full control over the hybrid player:
+For custom layouts:
 
 ```tsx
-import { HybridAudioProvider, HybridAudioPlayer, useHybridAudioContext } from '@djangocfg/ui-nextjs';
+import {
+  HybridAudioProvider,
+  HybridAudioPlayer,
+  AudioReactiveCover,
+  useHybridAudioContext
+} from '@djangocfg/ui-nextjs';
 
 function MyPlayer({ audioUrl }: { audioUrl: string }) {
   return (
     <HybridAudioProvider src={audioUrl}>
-      <HybridAudioPlayer
-        showControls
-        showWaveform
-        showTimer
-        showVolume
-      />
+      <AudioReactiveCover variant="spotlight" onClick={handleClick}>
+        <img src={coverUrl} alt="Cover" />
+      </AudioReactiveCover>
+      <HybridAudioPlayer showWaveform showControls />
       <CustomControls />
     </HybridAudioProvider>
   );
@@ -104,7 +98,6 @@ function CustomControls() {
 
   return (
     <div>
-      <p>Playing: {state.isPlaying ? 'Yes' : 'No'}</p>
       <p>Bass level: {(audioLevels.bass * 100).toFixed(0)}%</p>
       <button onClick={controls.togglePlay}>
         {state.isPlaying ? 'Pause' : 'Play'}
@@ -114,26 +107,26 @@ function CustomControls() {
 }
 ```
 
-### Hybrid Hooks
+## Hooks
 
-#### useHybridAudioContext
+### useHybridAudioContext
 
-Full access to audio state, controls, and Web Audio API:
+Full context access:
 
 ```tsx
 const {
-  state,       // { isReady, isPlaying, currentTime, duration, volume, isMuted, isLooping, buffered }
-  controls,    // { play, pause, togglePlay, seek, seekTo, skip, setVolume, toggleMute, toggleLoop, restart }
-  audioLevels, // { bass, mid, high, overall } - for reactive effects
-  webAudio,    // { context, analyser, sourceNode } - for custom visualizations
+  state,       // { isReady, isPlaying, currentTime, duration, volume, isMuted, isLooping }
+  controls,    // { play, pause, togglePlay, seek, skip, setVolume, toggleMute, toggleLoop }
+  audioLevels, // { bass, mid, high, overall }
+  webAudio,    // { context, analyser, sourceNode }
   audioRef,    // React ref to HTMLAudioElement
 } = useHybridAudioContext();
 ```
 
-#### Specialized Hooks
+### Specialized Hooks
 
 ```tsx
-// State only (read-only)
+// State only
 const { isPlaying, currentTime, duration } = useHybridAudioState();
 
 // Controls only (no re-render on time updates)
@@ -146,100 +139,36 @@ const { bass, mid, high, overall } = useHybridAudioLevels();
 const { context, analyser, sourceNode } = useHybridWebAudio();
 ```
 
----
-
-## WaveSurfer-based Player (Legacy)
-
-For cases where you need the static waveform visualization:
-
-```tsx
-import { SimpleAudioPlayer } from '@djangocfg/ui-nextjs';
-
-<SimpleAudioPlayer
-  src={audioUrl}
-  prefetch={true}  // Required for streaming URLs
-  title="Track Title"
-  showWaveform
-  reactiveCover
-/>
-```
-
-> **Note:** `prefetch={true}` downloads the entire file before playing. For large files or streaming, use `HybridSimplePlayer` instead.
-
----
-
 ## Components
 
-### HybridWaveform
-
-Real-time frequency visualization canvas:
-
-```tsx
-<HybridWaveform
-  mode="frequency"           // 'frequency' | 'static'
-  height={64}
-  barWidth={3}
-  barGap={2}
-  barRadius={2}
-  progressColor="hsl(217 91% 60%)"
-  waveColor="hsl(217 91% 60% / 0.3)"
-  bufferedColor="hsl(217 91% 60% / 0.15)"
-  onSeek={(time) => console.log('Seeked to', time)}
-/>
-```
-
 ### 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'
+  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>
 ```
 
-### AudioEqualizer
+### HybridWaveform
 
-Real-time frequency visualizer with animated bars:
+Real-time frequency visualization:
 
 ```tsx
-<AudioEqualizer
-  barCount={24}
-  height={48}
-  gap={2}
-  showPeaks
-  barColor="hsl(217 91% 60%)"
-  peakColor="hsl(217 91% 70%)"
+<HybridWaveform
+  mode="frequency"  // 'frequency' | 'static'
+  height={64}
+  barWidth={3}
+  barGap={2}
 />
 ```
 
----
-
-## 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% |
-
-Enable with:
-
-```tsx
-useAudioHotkeys({ enabled: true, skipDuration: 10, volumeStep: 0.1 });
-```
-
----
-
 ## Effect Variants
 
 | Variant | Description |
@@ -250,8 +179,6 @@ useAudioHotkeys({ enabled: true, skipDuration: 10, volumeStep: 0.1 });
 | `mesh` | Large gradient blobs with movement |
 | `none` | Effects disabled |
 
----
-
 ## Architecture
 
 ```
@@ -259,54 +186,21 @@ AudioPlayer/
 ├── index.ts                       # Public API exports
 ├── types/                         # TypeScript types
 ├── hooks/
-│   ├── useHybridAudio.ts          # 🆕 HTML5 audio + Web Audio hook
-│   ├── useHybridAudioAnalysis.ts  # 🆕 Frequency analysis for hybrid
-│   ├── useSharedWebAudio.ts       # Shared AudioContext (WaveSurfer)
-│   ├── useAudioAnalysis.ts        # Web Audio frequency analysis
-│   ├── useAudioHotkeys.ts         # Keyboard shortcuts
+│   ├── useHybridAudio.ts          # HTML5 audio + Web Audio hook
+│   ├── useHybridAudioAnalysis.ts  # Frequency analysis
 │   └── useVisualization.tsx       # Visualization settings
 ├── context/
-│   ├── HybridAudioProvider.tsx    # 🆕 Hybrid audio context
-│   ├── AudioProvider.tsx          # WaveSurfer context
-│   └── selectors.ts               # Hook selectors
+│   └── HybridAudioProvider.tsx    # Audio context provider
 ├── components/
-│   ├── HybridAudioPlayer.tsx      # 🆕 Main hybrid player
-│   ├── HybridSimplePlayer.tsx     # 🆕 All-in-one hybrid wrapper
-│   ├── HybridWaveform.tsx         # 🆕 Frequency visualization
-│   ├── AudioPlayer.tsx            # WaveSurfer player
-│   ├── SimpleAudioPlayer.tsx      # WaveSurfer wrapper
-│   ├── AudioEqualizer.tsx         # Frequency bars
+│   ├── HybridAudioPlayer.tsx      # Main player component
+│   ├── HybridSimplePlayer.tsx     # All-in-one wrapper
+│   ├── HybridWaveform.tsx         # Frequency visualization
 │   └── ReactiveCover/             # Reactive effects
-├── progressive/                   # Progressive/streaming player
-└── effects/                       # Effect calculations
-```
-
----
-
-## Migration Guide
-
-### From SimpleAudioPlayer to HybridSimplePlayer
-
-```tsx
-// Before
-<SimpleAudioPlayer
-  src={url}
-  prefetch={true}
-  showWaveform
-  reactiveCover
-  variant="spotlight"
-/>
-
-// After
-<HybridSimplePlayer
-  src={url}
-  showWaveform
-  reactiveCover
-  variant="spotlight"
-/>
+├── effects/                       # Effect calculations
+└── utils/                         # Utilities
 ```
 
-Key differences:
-- No `prefetch` prop needed — streaming works natively
-- `waveformMode="frequency"` shows real-time bars instead of static waveform
-- Same reactive effects support
+Key design:
+- HTML5 `<audio>` for playback (native streaming, no crackling)
+- Web Audio API AnalyserNode for visualization only (not connected to output)
+- Audio graph: `source → destination` + `source → analyser` (passive)

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

@@ -30,9 +30,6 @@ import {
 import { Button, Slider, cn } from '@djangocfg/ui-nextjs';
 import { useHybridAudioContext } from '../context/HybridAudioProvider';
 import { HybridWaveform } from './HybridWaveform';
-import { AudioEqualizer } from './AudioEqualizer';
-import { AudioShortcutsPopover } from './AudioShortcutsPopover';
-import { useAudioHotkeys } from '../hooks';
 import { formatTime } from '../utils';
 
 // =============================================================================
@@ -48,23 +45,12 @@ export interface HybridAudioPlayerProps {
   waveformMode?: 'frequency' | 'static';
   /** Waveform height in pixels */
   waveformHeight?: number;
-  /** Show equalizer bars */
-  showEqualizer?: boolean;
   /** Show time display */
   showTimer?: boolean;
   /** Show volume control */
   showVolume?: boolean;
   /** Show loop button */
   showLoop?: boolean;
-  /** Equalizer options */
-  equalizerOptions?: {
-    barCount?: number;
-    height?: number;
-    gap?: number;
-    showPeaks?: boolean;
-    barColor?: string;
-    peakColor?: string;
-  };
   /** Additional CSS class */
   className?: string;
   /** Inline styles */
@@ -80,19 +66,14 @@ export const HybridAudioPlayer = memo(function HybridAudioPlayer({
   showWaveform = true,
   waveformMode = 'frequency',
   waveformHeight = 64,
-  showEqualizer = false,
   showTimer = true,
   showVolume = true,
   showLoop = true,
-  equalizerOptions = {},
   className,
   style,
 }: HybridAudioPlayerProps) {
   const { state, controls } = useHybridAudioContext();
 
-  // Enable keyboard shortcuts
-  useAudioHotkeys({ enabled: state.isReady });
-
   const isLoading = !state.isReady;
 
   const handleVolumeChange = (value: number[]) => {
@@ -120,19 +101,6 @@ export const HybridAudioPlayer = memo(function HybridAudioPlayer({
         </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">
@@ -239,9 +207,6 @@ export const HybridAudioPlayer = memo(function HybridAudioPlayer({
               <Repeat className="h-4 w-4" />
             </Button>
           )}
-
-          {/* Shortcuts help */}
-          <AudioShortcutsPopover compact />
         </div>
       )}
     </div>

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

@@ -33,7 +33,6 @@ import { HybridAudioProvider } from '../context/HybridAudioProvider';
 import { HybridAudioPlayer } from './HybridAudioPlayer';
 import { AudioReactiveCover } from './ReactiveCover';
 import { VisualizationProvider, useVisualization } from '../hooks';
-import type { EqualizerOptions } from '../types';
 import type { EffectIntensity, EffectColorScheme } from '../effects';
 import type { VisualizationVariant } from '../hooks';
 
@@ -66,9 +65,6 @@ export interface HybridSimplePlayerProps {
   /** Waveform height in pixels */
   waveformHeight?: number;
 
-  /** Show equalizer bars */
-  showEqualizer?: boolean;
-
   /** Show timer */
   showTimer?: boolean;
 
@@ -99,9 +95,6 @@ export interface HybridSimplePlayerProps {
   /** Initial volume (0-1) */
   initialVolume?: number;
 
-  /** Equalizer customization */
-  equalizerOptions?: EqualizerOptions;
-
   /** Layout direction */
   layout?: 'vertical' | 'horizontal';
 
@@ -146,7 +139,6 @@ function HybridSimplePlayerContent({
   showWaveform = true,
   waveformMode = 'frequency',
   waveformHeight = 64,
-  showEqualizer = false,
   showTimer = true,
   showVolume = true,
   showLoop = true,
@@ -157,7 +149,6 @@ function HybridSimplePlayerContent({
   autoPlay = false,
   loop = false,
   initialVolume = 1,
-  equalizerOptions,
   layout = 'vertical',
   className,
   onPlay,
@@ -275,11 +266,9 @@ function HybridSimplePlayerContent({
             showWaveform={showWaveform}
             waveformMode={waveformMode}
             waveformHeight={waveformHeight}
-            showEqualizer={showEqualizer}
             showTimer={showTimer}
             showVolume={showVolume}
             showLoop={showLoop}
-            equalizerOptions={equalizerOptions}
             className="border-0 bg-transparent"
           />
         </div>

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

@@ -6,13 +6,12 @@
  * 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).
+ * Must be used within HybridAudioProvider context.
  */
 
 import { type ReactNode } from 'react';
 import { cn } from '@djangocfg/ui-nextjs';
-import { useAudioElement } from '../../context';
+import { useHybridAudioLevels, useHybridAudioState } from '../../context/HybridAudioProvider';
 import {
   type EffectVariant,
   type EffectIntensity,
@@ -64,8 +63,9 @@ export function AudioReactiveCover({
   onClick,
   className,
 }: AudioReactiveCoverProps) {
-  // Get audio levels from context (persists across variant changes)
-  const { isPlaying, audioLevels: levels } = useAudioElement();
+  // Get audio state from HybridAudioProvider context
+  const { isPlaying } = useHybridAudioState();
+  const levels = useHybridAudioLevels();
 
   // =========================================================================
   // PREPARE DATA BEFORE RENDER
@@ -110,22 +110,24 @@ export function AudioReactiveCover({
         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} />
-      )}
+      {/* Effect layers container - under cover, non-interactive */}
+      <div className="absolute inset-0 z-0 pointer-events-none overflow-visible">
+        {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} />
+        )}
+      </div>
 
       {/* Content (cover art) */}
       <div

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

@@ -1,15 +1,11 @@
 /**
  * AudioPlayer components - Public API
+ *
+ * Uses HTML5 audio for playback + Web Audio API for visualization.
+ * No crackling, native streaming support.
  */
 
-// WaveSurfer-based components (original)
-export { AudioPlayer } from './AudioPlayer';
-export { SimpleAudioPlayer, type SimpleAudioPlayerProps } from './SimpleAudioPlayer';
-export { AudioEqualizer } from './AudioEqualizer';
-export { AudioShortcutsPopover } from './AudioShortcutsPopover';
-export { VisualizationToggle, type VisualizationToggleProps } from './VisualizationToggle';
-
-// Hybrid player components (HTML5 audio + Web Audio for visualization)
+// Player components
 export { HybridAudioPlayer, type HybridAudioPlayerProps } from './HybridAudioPlayer';
 export { HybridSimplePlayer, type HybridSimplePlayerProps } from './HybridSimplePlayer';
 export { HybridWaveform, type HybridWaveformProps } from './HybridWaveform';

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

@@ -1,16 +1,9 @@
 /**
  * AudioPlayer context - Public API
  *
- * Re-exports provider and selector hooks
+ * HybridAudioProvider: HTML5 audio + Web Audio API for visualization
  */
 
-// WaveSurfer-based provider (original)
-export { AudioProvider, AudioPlayerContext } from './AudioProvider';
-
-// Selector hooks for WaveSurfer provider
-export { useAudio, useAudioControls, useAudioState, useAudioElement } from './selectors';
-
-// Hybrid provider (HTML5 audio + Web Audio for visualization)
 export {
   HybridAudioProvider,
   useHybridAudioContext,

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

@@ -1,14 +1,8 @@
 /**
- * AudioPlayer hooks - re-exports all hooks
+ * AudioPlayer hooks - Public API
  */
 
-// Internal hooks (used by provider)
-export { useSharedWebAudio } from './useSharedWebAudio';
-export { useAudioAnalysis } from './useAudioAnalysis';
-export { useAudioSource } from './useAudioSource';
-export type { UseAudioSourceResult } from './useAudioSource';
-
-// Hybrid player hooks
+// Core hybrid audio hook
 export { useHybridAudio } from './useHybridAudio';
 export type {
   UseHybridAudioOptions,
@@ -17,15 +11,14 @@ export type {
   HybridWebAudioAPI,
   UseHybridAudioReturn,
 } from './useHybridAudio';
-export { useHybridAudioAnalysis } from './useHybridAudioAnalysis';
 
-// Public hooks
-export { useAudioHotkeys, AUDIO_SHORTCUTS } from './useAudioHotkeys';
-export type { AudioHotkeyOptions, ShortcutItem, ShortcutGroup } from './useAudioHotkeys';
+// Frequency analysis hook
+export { useHybridAudioAnalysis } from './useHybridAudioAnalysis';
 
+// Visualization settings (localStorage persistence)
 export {
   useVisualization,
-  useAudioVisualization, // backward compat alias
+  useAudioVisualization,
   VisualizationProvider,
   VARIANT_INFO,
   INTENSITY_INFO,