@djangocfg/ui-tools 2.1.201 → 2.1.203

package/src/tools/AudioPlayer/README.md

@@ -13,11 +13,14 @@ Audio player with native HTML5 streaming and audio-reactive visualizations.
 ## Quick Start
 
 ```tsx
-import { HybridSimplePlayer } from '@djangocfg/ui-nextjs';
+import { HybridSimplePlayer, HybridCompactPlayer } from '@djangocfg/ui-nextjs';
 
 // Simple usage
 <HybridSimplePlayer src="https://example.com/audio.mp3" />
 
+// Compact single-row player (for lists, sidebars)
+<HybridCompactPlayer src="https://example.com/audio.mp3" title="Rain & Thunder" />
+
 // With metadata and reactive cover
 <HybridSimplePlayer
   src={audioUrl}
@@ -156,6 +159,38 @@ Album art wrapper with audio-reactive effects:
 </AudioReactiveCover>
 ```
 
+### HybridCompactPlayer
+
+Single-row player — play/pause + waveform + timer. No cover art, no volume slider.
+
+```tsx
+<HybridCompactPlayer
+  src={audioUrl}
+  title="Track name"     // used as tooltip
+  waveformMode="frequency"  // 'frequency' | 'static'
+  showTimer={true}
+  autoPlay={false}
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `src` | `string` | required | Audio URL |
+| `title` | `string` | - | Tooltip / aria-label |
+| `waveformMode` | `'frequency' \| 'static'` | `'frequency'` | Visualization mode |
+| `showTimer` | `boolean` | `true` | Show current/total time |
+| `autoPlay` | `boolean` | `false` | Auto-play on load |
+| `loop` | `boolean` | `false` | Loop playback |
+| `initialVolume` | `number` | `1` | Initial volume 0-1 |
+
+For lazy-loading (preferred in Next.js apps):
+
+```tsx
+import { LazyHybridCompactPlayer } from '@djangocfg/ui-tools';
+
+<LazyHybridCompactPlayer src={url} title="Track" autoPlay />
+```
+
 ### HybridWaveform
 
 Real-time frequency visualization:
@@ -193,7 +228,8 @@ AudioPlayer/
 │   └── HybridAudioProvider.tsx    # Audio context provider
 ├── components/
 │   ├── HybridAudioPlayer.tsx      # Main player component
-│   ├── HybridSimplePlayer.tsx     # All-in-one wrapper
+│   ├── HybridSimplePlayer.tsx     # All-in-one wrapper (with cover, volume, effects)
+│   ├── HybridCompactPlayer.tsx    # Compact single-row player
 │   ├── HybridWaveform.tsx         # Frequency visualization
 │   └── ReactiveCover/             # Reactive effects
 ├── effects/                       # Effect calculations

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

@@ -0,0 +1,153 @@
+'use client';
+
+/**
+ * HybridCompactPlayer - Single-row audio player
+ *
+ * Designed for tight spaces: play/pause + waveform + timer.
+ * No cover art, no volume slider, no skip buttons.
+ *
+ * @example
+ * <HybridCompactPlayer src="https://example.com/audio.mp3" title="Rain & Thunder" />
+ *
+ * @example
+ * // Lazy-loaded (preferred in app)
+ * <LazyHybridCompactPlayer src={url} autoPlay />
+ */
+
+import { type ReactNode } from 'react';
+import { Play, Pause, Loader2 } from 'lucide-react';
+import { cn } from '@djangocfg/ui-core';
+import { Button } from '../../_shared';
+
+import { HybridAudioProvider } from '../context/HybridAudioProvider';
+import { HybridWaveform } from './HybridWaveform';
+import { useHybridAudioContext } from '../context/HybridAudioProvider';
+import { formatTime } from '../utils';
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export interface HybridCompactPlayerProps {
+  /** Audio source URL */
+  src: string;
+  /** Track title (shown as tooltip / aria-label) */
+  title?: string;
+  /** Auto-play on load */
+  autoPlay?: boolean;
+  /** Loop playback */
+  loop?: boolean;
+  /** Initial volume (0-1) */
+  initialVolume?: number;
+  /** Waveform visualization mode */
+  waveformMode?: 'frequency' | 'static';
+  /** Show timer */
+  showTimer?: boolean;
+  /** Additional class name */
+  className?: string;
+  /** Callbacks */
+  onPlay?: () => void;
+  onPause?: () => void;
+  onEnded?: () => void;
+  onError?: (error: Error) => void;
+}
+
+// =============================================================================
+// COMPONENT
+// =============================================================================
+
+export function HybridCompactPlayer({
+  src,
+  title,
+  autoPlay = false,
+  loop = false,
+  initialVolume = 1,
+  waveformMode = 'frequency',
+  showTimer = true,
+  className,
+  onPlay,
+  onPause,
+  onEnded,
+  onError,
+}: HybridCompactPlayerProps): ReactNode {
+  return (
+    <HybridAudioProvider
+      src={src}
+      autoPlay={autoPlay}
+      loop={loop}
+      initialVolume={initialVolume}
+      onPlay={onPlay}
+      onPause={onPause}
+      onEnded={onEnded}
+      onError={onError}
+    >
+      <HybridCompactPlayerInner
+        title={title}
+        waveformMode={waveformMode}
+        showTimer={showTimer}
+        className={className}
+      />
+    </HybridAudioProvider>
+  );
+}
+
+// =============================================================================
+// INNER (needs context)
+// =============================================================================
+
+interface InnerProps {
+  title?: string;
+  waveformMode: 'frequency' | 'static';
+  showTimer: boolean;
+  className?: string;
+}
+
+function HybridCompactPlayerInner({ title, waveformMode, showTimer, className }: InnerProps) {
+  const { state, controls } = useHybridAudioContext();
+  const isLoading = !state.isReady;
+
+  return (
+    <div className={cn('flex items-center gap-2 w-full', className)}>
+      {/* Play / Pause */}
+      <Button
+        variant="outline"
+        size="icon"
+        className="h-8 w-8 flex-shrink-0"
+        onClick={controls.togglePlay}
+        disabled={!state.isReady && !isLoading}
+        title={title ?? (state.isPlaying ? 'Pause' : 'Play')}
+        aria-label={state.isPlaying ? 'Pause' : 'Play'}
+      >
+        {isLoading ? (
+          <Loader2 className="h-3.5 w-3.5 animate-spin" />
+        ) : state.isPlaying ? (
+          <Pause className="h-3.5 w-3.5" />
+        ) : (
+          <Play className="h-3.5 w-3.5 ml-0.5" />
+        )}
+      </Button>
+
+      {/* Waveform */}
+      <div className="flex-1 min-w-0">
+        <HybridWaveform
+          mode={waveformMode}
+          height={32}
+          barWidth={2}
+          barGap={1}
+          className={cn(isLoading && 'opacity-40')}
+        />
+      </div>
+
+      {/* Timer */}
+      {showTimer && (
+        <span className="text-[11px] text-muted-foreground tabular-nums flex-shrink-0">
+          {formatTime(state.currentTime)}
+          <span className="text-muted-foreground/50"> / </span>
+          {formatTime(state.duration)}
+        </span>
+      )}
+    </div>
+  );
+}
+
+export default HybridCompactPlayer;

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

@@ -118,6 +118,10 @@ const COVER_SIZES = {
   lg: 'w-48 h-48',
 };
 
+// In horizontal layout cover stays fixed-size; in vertical it fills the full width
+const COVER_SIZE_FOR_LAYOUT = (coverSize: 'sm' | 'md' | 'lg', isHorizontal: boolean) =>
+  isHorizontal ? coverSize : 'full';
+
 // =============================================================================
 // COMPONENT
 // =============================================================================
@@ -209,16 +213,16 @@ function HybridSimplePlayerContent({
       >
         {/* Cover Art */}
         {(coverArt || reactiveCover) && (
-          <div className="flex flex-col items-center gap-2 shrink-0">
+          <div className={cn('flex flex-col items-center gap-2', isHorizontal ? 'shrink-0' : 'w-full')}>
             {showReactiveCover ? (
               <AudioReactiveCover
-                size={coverSize}
+                size={COVER_SIZE_FOR_LAYOUT(coverSize, isHorizontal)}
                 variant={effectiveVariant as 'glow' | 'orbs' | 'spotlight' | 'mesh'}
                 intensity={effectiveIntensity}
                 colorScheme={effectiveColorScheme}
                 onClick={nextVariant}
               >
-                <div className={cn('rounded-lg overflow-hidden', COVER_SIZES[coverSize])}>
+                <div className={cn('rounded-lg overflow-hidden', isHorizontal ? COVER_SIZES[coverSize] : 'w-full h-full')}>
                   {renderCoverContent()}
                 </div>
               </AudioReactiveCover>
@@ -226,7 +230,7 @@ function HybridSimplePlayerContent({
               <div
                 className={cn(
                   'rounded-lg overflow-hidden shadow-lg cursor-pointer',
-                  COVER_SIZES[coverSize]
+                  isHorizontal ? COVER_SIZES[coverSize] : 'w-full sm:max-w-xs aspect-square mx-auto'
                 )}
                 onClick={nextVariant}
                 role="button"
@@ -248,7 +252,7 @@ function HybridSimplePlayerContent({
 
         {/* Track Info + Player */}
         <div
-          className={cn('flex flex-col gap-3', isHorizontal ? 'flex-1 min-w-0' : 'w-full max-w-md')}
+          className={cn('flex flex-col gap-3', isHorizontal ? 'flex-1 min-w-0' : 'w-full')}
         >
           {/* Track Info */}
           {(title || artist) && (

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

@@ -32,7 +32,8 @@ import { GlowEffect, OrbsEffect, SpotlightEffect, MeshEffect, type GlowEffectDat
 
 export interface AudioReactiveCoverProps {
   children: ReactNode;
-  size?: 'sm' | 'md' | 'lg';
+  /** 'sm' | 'md' | 'lg' = fixed sizes; 'full' = stretch to container width (aspect-square) */
+  size?: 'sm' | 'md' | 'lg' | 'full';
   variant?: EffectVariant;
   intensity?: EffectIntensity;
   colorScheme?: EffectColorScheme;
@@ -48,6 +49,7 @@ 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 },
+  full: { container: 'w-full sm:max-w-xs aspect-square mx-auto', orbBase: 60 },
 };
 
 // =============================================================================

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

@@ -8,6 +8,7 @@
 // Player components
 export { HybridAudioPlayer, type HybridAudioPlayerProps } from './HybridAudioPlayer';
 export { HybridSimplePlayer, type HybridSimplePlayerProps } from './HybridSimplePlayer';
+export { HybridCompactPlayer, type HybridCompactPlayerProps } from './HybridCompactPlayer';
 export { HybridWaveform, type HybridWaveformProps } from './HybridWaveform';
 
 // ReactiveCover

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

@@ -2,6 +2,10 @@
  * AudioPlayer hooks - Public API
  */
 
+// Audio bus — global exclusivity (one player at a time)
+export { useAudioBus, useAudioBusStore } from './useAudioBus';
+export type { UseAudioBusReturn } from './useAudioBus';
+
 // Core hybrid audio hook
 export { useHybridAudio } from './useHybridAudio';
 export type {

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

@@ -0,0 +1,76 @@
+'use client';
+
+/**
+ * useAudioBus — Global audio exclusivity via Zustand store.
+ *
+ * Ensures only one audio player plays at a time across the entire page.
+ * No provider needed — singleton store, works anywhere in the tree.
+ *
+ * Also integrates with @djangocfg/ui-tools AudioPlayer automatically
+ * (wired into useHybridAudio).
+ *
+ * @example
+ * const { announce } = useAudioBus('my-player-id', () => pause());
+ *
+ * // When playback starts:
+ * announce(); // all other players will pause
+ */
+
+import { useEffect, useRef, useCallback } from 'react';
+import { create } from 'zustand';
+
+// =============================================================================
+// Store
+// =============================================================================
+
+interface AudioBusStore {
+  /** ID of the currently active (playing) player, null if none */
+  activeId: string | null;
+  setActiveId: (id: string | null) => void;
+}
+
+export const useAudioBusStore = create<AudioBusStore>((set) => ({
+  activeId: null,
+  setActiveId: (id) => set({ activeId: id }),
+}));
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+export interface UseAudioBusReturn {
+  /** Broadcast: this player is now playing — all others should stop */
+  announce: () => void;
+  /** Release: this player stopped (clears activeId if it was ours) */
+  release: () => void;
+}
+
+/**
+ * @param playerId  Stable unique ID for this player instance
+ * @param onStop    Called when another player announces — should pause this player
+ */
+export function useAudioBus(playerId: string, onStop: () => void): UseAudioBusReturn {
+  const onStopRef = useRef(onStop);
+  onStopRef.current = onStop;
+
+  const setActiveId = useAudioBusStore((s) => s.setActiveId);
+
+  // Subscribe to store changes — if another player becomes active, stop this one
+  useEffect(() => {
+    return useAudioBusStore.subscribe((state) => {
+      if (state.activeId !== null && state.activeId !== playerId) {
+        onStopRef.current();
+      }
+    });
+  }, [playerId]);
+
+  const announce = useCallback(() => {
+    setActiveId(playerId);
+  }, [playerId, setActiveId]);
+
+  const release = useCallback(() => {
+    useAudioBusStore.setState((s) => s.activeId === playerId ? { activeId: null } : s);
+  }, [playerId]);
+
+  return { announce, release };
+}

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

@@ -11,7 +11,8 @@
  *   source -> analyser (parallel path for visualization only, no output)
  */
 
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useId, useRef, useState } from 'react';
+import { useAudioBus } from './useAudioBus';
 
 // =============================================================================
 // TYPES
@@ -23,6 +24,8 @@ export interface UseHybridAudioOptions {
   initialVolume?: number;
   loop?: boolean;
   crossOrigin?: 'anonymous' | 'use-credentials';
+  /** Set to true to opt out of global audio bus (player won't stop others and won't be stopped) */
+  excludeFromBus?: boolean;
   onPlay?: () => void;
   onPause?: () => void;
   onEnded?: () => void;
@@ -81,6 +84,7 @@ export function useHybridAudio(options: UseHybridAudioOptions): UseHybridAudioRe
     initialVolume = 1,
     loop = false,
     crossOrigin = 'anonymous',
+    excludeFromBus = false,
     onPlay,
     onPause,
     onEnded,
@@ -89,6 +93,8 @@ export function useHybridAudio(options: UseHybridAudioOptions): UseHybridAudioRe
     onReady,
   } = options;
 
+  const playerId = useId();
+
   // Refs
   const audioRef = useRef<HTMLAudioElement | null>(null);
   const audioContextRef = useRef<AudioContext | null>(null);
@@ -162,6 +168,14 @@ export function useHybridAudio(options: UseHybridAudioOptions): UseHybridAudioRe
     }
   }, []);
 
+  // Audio bus — stop other players when this one plays
+  const { announce: busAnnounce, release: busRelease } = useAudioBus(
+    playerId,
+    useCallback(() => {
+      if (!excludeFromBus) audioRef.current?.pause();
+    }, [excludeFromBus])
+  );
+
   // Resume AudioContext on user interaction
   const resumeAudioContext = useCallback(async () => {
     const ctx = audioContextRef.current;
@@ -176,6 +190,7 @@ export function useHybridAudio(options: UseHybridAudioOptions): UseHybridAudioRe
     if (!audio) return;
 
     try {
+      if (!excludeFromBus) busAnnounce();
       initWebAudio();
       await resumeAudioContext();
       await audio.play();
@@ -183,7 +198,7 @@ export function useHybridAudio(options: UseHybridAudioOptions): UseHybridAudioRe
       console.error('[useHybridAudio] Play failed:', error);
       onError?.(error as Error);
     }
-  }, [initWebAudio, resumeAudioContext, onError]);
+  }, [excludeFromBus, busAnnounce, initWebAudio, resumeAudioContext, onError]);
 
   const pause = useCallback(() => {
     audioRef.current?.pause();
@@ -286,6 +301,7 @@ export function useHybridAudio(options: UseHybridAudioOptions): UseHybridAudioRe
     return () => {
       audio.pause();
       audio.src = '';
+      busRelease();
       if (audioContextRef.current) {
         audioContextRef.current.close().catch(() => {});
       }

package/src/tools/AudioPlayer/index.ts

@@ -24,6 +24,7 @@
 export {
   HybridAudioPlayer,
   HybridSimplePlayer,
+  HybridCompactPlayer,
   HybridWaveform,
   AudioReactiveCover,
   // Effect components (for custom implementations)
@@ -36,6 +37,7 @@ export {
 export type {
   HybridAudioPlayerProps,
   HybridSimplePlayerProps,
+  HybridCompactPlayerProps,
   HybridWaveformProps,
   AudioReactiveCoverProps,
   GlowEffectData,
@@ -64,6 +66,9 @@ export type {
 // =============================================================================
 
 export {
+  // Audio bus
+  useAudioBus,
+  useAudioBusStore,
   // Core hooks
   useHybridAudio,
   useHybridAudioAnalysis,
@@ -77,6 +82,7 @@ export {
 } from './hooks';
 
 export type {
+  UseAudioBusReturn,
   UseHybridAudioOptions,
   HybridAudioState,
   HybridAudioControls,

package/src/tools/AudioPlayer/lazy.tsx

@@ -14,13 +14,14 @@ import { createLazyComponent, LoadingFallback } from '../../components';
 import type {
   HybridAudioPlayerProps,
   HybridSimplePlayerProps,
+  HybridCompactPlayerProps,
 } from './components';
 
 // ============================================================================
 // Re-export types
 // ============================================================================
 
-export type { HybridAudioPlayerProps, HybridSimplePlayerProps };
+export type { HybridAudioPlayerProps, HybridSimplePlayerProps, HybridCompactPlayerProps };
 
 // ============================================================================
 // Audio Loading Fallback
@@ -83,3 +84,22 @@ export const LazyHybridSimplePlayer = createLazyComponent<HybridSimplePlayerProp
     fallback: <AudioLoadingFallback />,
   }
 );
+
+/**
+ * LazyHybridCompactPlayer - Lazy-loaded compact single-row audio player
+ *
+ * Use in tight spaces: play/pause + waveform + timer in one line.
+ */
+export const LazyHybridCompactPlayer = createLazyComponent<HybridCompactPlayerProps>(
+  () => import('./components').then((mod) => ({ default: mod.HybridCompactPlayer })),
+  {
+    displayName: 'LazyHybridCompactPlayer',
+    fallback: (
+      <div className="flex items-center gap-2 h-8 px-1 animate-pulse">
+        <div className="h-8 w-8 rounded-md bg-muted flex-shrink-0" />
+        <div className="flex-1 h-4 rounded bg-muted" />
+        <div className="h-3 w-12 rounded bg-muted flex-shrink-0" />
+      </div>
+    ),
+  }
+);

package/src/tools/Uploader/README.md

@@ -49,7 +49,32 @@ All-in-one component with dropzone and preview list.
 />
 ```
 
-### Custom Composition
+### Standalone — custom upload handler (no UploadProvider)
+
+If you handle uploads yourself (custom API hooks, multipart POST, etc.), pass `uploadFn` instead of wrapping with `UploadProvider`. Supports drag/drop, click, and Ctrl+V paste.
+
+```tsx
+import { UploadDropzone } from '@djangocfg/ui-tools/upload';
+
+function MyUploader() {
+  const { uploadAsset } = useAssets(); // your own API hook
+
+  return (
+    <UploadDropzone
+      accept={['image', 'video']}
+      maxSizeMB={50}
+      pasteEnabled
+      uploadFn={async (files) => {
+        for (const file of files) {
+          await uploadAsset({ file, name: file.name });
+        }
+      }}
+    />
+  );
+}
+```
+
+### Custom Composition (with rpldy)
 
 ```tsx
 import {
@@ -116,11 +141,11 @@ Custom overlay:
 
 ### Components
 
-| Component | Description |
-|-----------|-------------|
-| `Uploader` | All-in-one (Provider + Dropzone + Preview) |
-| `UploadProvider` | Context provider wrapping @rpldy/uploady |
-| `UploadDropzone` | Drag-drop zone with file input |
+| Component | Needs UploadProvider | Description |
+|-----------|---------------------|-------------|
+| `Uploader` | Yes | All-in-one (Provider + Dropzone + Preview) |
+| `UploadDropzone` | **Optional** | Drag-drop zone — use `uploadFn` for standalone mode |
+| `UploadProvider` | — | Context provider wrapping @rpldy/uploady |
 | `UploadPreviewList` | List of upload items with progress |
 | `UploadPreviewItem` | Single item (thumbnail, status, actions) |
 | `UploadAddButton` | Button to add files |

package/src/tools/Uploader/Uploader.story.tsx

@@ -369,3 +369,47 @@ export const PageDropCustomOverlay = () => (
     </UploadProvider>
   </div>
 );
+
+// Standalone — uploadFn instead of UploadProvider (custom API hooks, no rpldy)
+export const StandaloneWithUploadFn = () => {
+  const [files, setFiles] = useState<string[]>([]);
+
+  return (
+    <div className="max-w-2xl space-y-4">
+      <Card>
+        <CardContent className="pt-4">
+          <p className="text-sm text-muted-foreground flex items-center gap-2">
+            <ClipboardPaste className="h-4 w-4" />
+            No <code className="text-xs bg-muted px-1 rounded">UploadProvider</code> needed.
+            Pass <code className="text-xs bg-muted px-1 rounded">uploadFn</code> to handle files yourself.
+            Drag, click, or paste (Ctrl+V).
+          </p>
+        </CardContent>
+      </Card>
+      <UploadDropzone
+        accept={['image', 'document']}
+        maxSizeMB={10}
+        pasteEnabled
+        uploadFn={(selected) => {
+          setFiles((prev) => [...prev, ...selected.map((f) => f.name)]);
+          logger.info('Custom uploadFn received: ' + selected.map((f) => f.name).join(', '));
+        }}
+        onPasteNoMatch={() => logger.info('Paste: no uploadable content found')}
+      />
+      {files.length > 0 && (
+        <Card>
+          <CardHeader>
+            <CardTitle className="text-sm">Received by uploadFn</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <ul className="text-sm space-y-1">
+              {files.map((name, i) => (
+                <li key={i} className="text-muted-foreground">{name}</li>
+              ))}
+            </ul>
+          </CardContent>
+        </Card>
+      )}
+    </div>
+  );
+};

package/src/tools/Uploader/components/UploadDropzone.tsx

@@ -9,6 +9,17 @@ import { buildAcceptString, logger } from '../utils';
 import { useClipboardPaste } from '../hooks/useClipboardPaste';
 import type { UploadDropzoneProps } from '../types';
 
+function useOptionalUploady(uploadFn?: (files: File[]) => void) {
+  try {
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    const { upload } = useUploady();
+    return uploadFn ?? upload;
+  } catch {
+    // Not inside UploadProvider — use uploadFn if provided, otherwise noop
+    return uploadFn ?? (() => {});
+  }
+}
+
 export function UploadDropzone({
   accept = ['image', 'audio', 'video', 'document'],
   multiple = true,
@@ -18,11 +29,12 @@ export function UploadDropzone({
   className,
   children,
   onFilesSelected,
+  uploadFn,
   pasteEnabled = true,
   onPasteNoMatch,
 }: UploadDropzoneProps) {
   const t = useT();
-  const { upload } = useUploady();
+  const upload = useOptionalUploady(uploadFn);
   const inputRef = useRef<HTMLInputElement>(null);
   const [isDragging, setIsDragging] = useState(false);
   const dragCounter = useRef(0);