@djangocfg/ui-tools 2.1.312 → 2.1.313

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

@@ -0,0 +1,91 @@
+'use client';
+
+// Player keyboard shortcuts via ui-core's useHotkey (react-hotkeys-hook).
+//
+// Idiomatic pattern: each useHotkey call returns a callback ref that scopes
+// the binding to the element it's attached to. We compose all of them into
+// one ref and hand it to the player container. Library handles focus gating;
+// no manual `document.activeElement` polling, no `data-scope` juggling.
+
+import { useCallback } from 'react';
+import { useHotkey } from '@djangocfg/ui-core/hooks';
+import { clamp } from '../utils/clamp';
+import type { PlayerControls } from '../types';
+
+export type HotkeyBinding = {
+  /** Human label for help dialogs and tooltips. */
+  label: string;
+  /** Pretty hint shown to users (e.g. "Space", "←", "M"). */
+  hint: string;
+};
+
+export type UseKeyboardShortcutsOptions = {
+  audio: HTMLAudioElement;
+  controls: PlayerControls;
+  enabled?: boolean;
+};
+
+export type UseKeyboardShortcutsReturn = {
+  /** Attach to the player container — react-hotkeys-hook only fires when
+   * focus is within this element. Composes with other refs via callback. */
+  ref: (instance: HTMLElement | null) => void;
+  /** All registered bindings — useful for rendering a help dialog. */
+  bindings: ReadonlyArray<HotkeyBinding>;
+};
+
+const OPTS = { preventDefault: true } as const;
+
+const BINDINGS: ReadonlyArray<HotkeyBinding> = [
+  { label: 'Play / pause', hint: 'Space' },
+  { label: 'Seek +5s', hint: '→' },
+  { label: 'Seek −5s', hint: '←' },
+  { label: 'Volume up', hint: '↑' },
+  { label: 'Volume down', hint: '↓' },
+  { label: 'Toggle mute', hint: 'M' },
+  { label: 'Toggle loop', hint: 'L' },
+];
+
+export function useKeyboardShortcuts({
+  audio,
+  controls,
+  enabled = true,
+}: UseKeyboardShortcutsOptions): UseKeyboardShortcutsReturn {
+  // Each useHotkey returns a callback ref that scopes the binding to its
+  // element. We must call them at the top level (rules of hooks).
+  const refToggle = useHotkey(['space', 'k'], () => void controls.toggle(), {
+    ...OPTS, enabled, description: 'Play / pause',
+  });
+  const refForward = useHotkey('right', () => controls.seek(audio.currentTime + 5), {
+    ...OPTS, enabled, description: 'Seek +5s',
+  });
+  const refBackward = useHotkey('left', () => controls.seek(audio.currentTime - 5), {
+    ...OPTS, enabled, description: 'Seek −5s',
+  });
+  const refVolUp = useHotkey('up', () => controls.setVolume(clamp(audio.volume + 0.05, 0, 1)), {
+    ...OPTS, enabled, description: 'Volume up',
+  });
+  const refVolDown = useHotkey('down', () => controls.setVolume(clamp(audio.volume - 0.05, 0, 1)), {
+    ...OPTS, enabled, description: 'Volume down',
+  });
+  const refMute = useHotkey('m', () => controls.toggleMute(), {
+    ...OPTS, enabled, description: 'Toggle mute',
+  });
+  const refLoop = useHotkey('l', () => controls.toggleLoop(), {
+    ...OPTS, enabled, description: 'Toggle loop',
+  });
+
+  const ref = useCallback(
+    (instance: HTMLElement | null) => {
+      refToggle(instance);
+      refForward(instance);
+      refBackward(instance);
+      refVolUp(instance);
+      refVolDown(instance);
+      refMute(instance);
+      refLoop(instance);
+    },
+    [refToggle, refForward, refBackward, refVolUp, refVolDown, refMute, refLoop],
+  );
+
+  return { ref, bindings: BINDINGS };
+}

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

@@ -0,0 +1,74 @@
+'use client';
+
+import { useEffect } from 'react';
+import type { PlayerControls } from '../types';
+import type { PlayerMeta } from '../context/MetaContext';
+
+const ACTIONS: MediaSessionAction[] = [
+  'play',
+  'pause',
+  'previoustrack',
+  'nexttrack',
+  'seekbackward',
+  'seekforward',
+];
+
+export function useMediaSession(
+  audio: HTMLAudioElement,
+  meta: PlayerMeta,
+  controls: PlayerControls,
+  onPrev?: () => void,
+  onNext?: () => void,
+): void {
+  useEffect(() => {
+    if (typeof navigator === 'undefined' || !('mediaSession' in navigator)) return;
+    const ms = navigator.mediaSession;
+    try {
+      ms.metadata = new MediaMetadata({
+        title: meta.title ?? '',
+        artist: meta.artist ?? '',
+        album: meta.album ?? '',
+        artwork: meta.cover
+          ? [{ src: meta.cover, sizes: '512x512', type: 'image/jpeg' }]
+          : [],
+      });
+    } catch {
+      // ignore
+    }
+
+    const handlers: Partial<Record<MediaSessionAction, MediaSessionActionHandler | null>> = {
+      play: () => {
+        void controls.play();
+      },
+      pause: () => controls.pause(),
+      previoustrack: onPrev ?? null,
+      nexttrack: onNext ?? null,
+      seekbackward: (details) => {
+        const offset = details.seekOffset ?? 10;
+        controls.seek(audio.currentTime - offset);
+      },
+      seekforward: (details) => {
+        const offset = details.seekOffset ?? 10;
+        controls.seek(audio.currentTime + offset);
+      },
+    };
+
+    for (const a of ACTIONS) {
+      try {
+        ms.setActionHandler(a, handlers[a] ?? null);
+      } catch {
+        // ignore unsupported actions
+      }
+    }
+
+    return () => {
+      for (const a of ACTIONS) {
+        try {
+          ms.setActionHandler(a, null);
+        } catch {
+          // ignore
+        }
+      }
+    };
+  }, [audio, controls, meta.title, meta.artist, meta.album, meta.cover, onPrev, onNext]);
+}

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

@@ -0,0 +1,83 @@
+'use client';
+
+// Lazy peaks fetch with module-cache + in-flight dedupe. Triggers on first
+// `play()`, IntersectionObserver visibility, or explicit `decodeOnMount` flag.
+
+import { useEffect, useState } from 'react';
+import { getPeaks, getPeaksFromCache } from '../audio/peaksCache';
+
+export type UsePeaksOptions = {
+  src: string;
+  enabled?: boolean;
+  triggerRef?: React.RefObject<Element | null>;
+  decodeOnMount?: boolean;
+};
+
+export function usePeaks(opts: UsePeaksOptions): {
+  peaks: Float32Array | null;
+  loading: boolean;
+  error: unknown;
+} {
+  const { src, enabled = true, triggerRef, decodeOnMount = false } = opts;
+  const cached = getPeaksFromCache(src) ?? null;
+  const [peaks, setLocal] = useState<Float32Array | null>(cached);
+  const [loading, setLoading] = useState<boolean>(!cached && enabled);
+  const [error, setError] = useState<unknown>(null);
+
+  useEffect(() => {
+    if (!enabled) return;
+    const hit = getPeaksFromCache(src);
+    if (hit) {
+      setLocal(hit);
+      setLoading(false);
+      return;
+    }
+    setLocal(null);
+    setLoading(true);
+    let cancelled = false;
+    let started = false;
+
+    const startDecode = () => {
+      if (started) return;
+      started = true;
+      getPeaks(src)
+        .then((p) => {
+          if (cancelled) return;
+          setLocal(p);
+          setLoading(false);
+        })
+        .catch((e) => {
+          if (cancelled) return;
+          setError(e);
+          setLoading(false);
+        });
+    };
+
+    if (decodeOnMount || !triggerRef?.current || typeof IntersectionObserver === 'undefined') {
+      startDecode();
+      return () => {
+        cancelled = true;
+      };
+    }
+
+    const obs = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            startDecode();
+            obs.disconnect();
+            break;
+          }
+        }
+      },
+      { rootMargin: '200px' },
+    );
+    obs.observe(triggerRef.current);
+    return () => {
+      cancelled = true;
+      obs.disconnect();
+    };
+  }, [src, enabled, decodeOnMount, triggerRef]);
+
+  return { peaks, loading, error };
+}

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

@@ -0,0 +1,21 @@
+'use client';
+
+// Read the persistent player preferences (volume, muted). useSyncExternalStore
+// over preferencesStore — re-renders when localStorage changes (same tab or
+// other tab via the native `storage` event).
+
+import { useSyncExternalStore } from 'react';
+import {
+  getPreferences,
+  subscribePreferences,
+  type PlayerPreferences,
+} from '../store/preferencesStore';
+
+const SSR: PlayerPreferences = { volume: 1, muted: false };
+function getServerSnapshot(): PlayerPreferences {
+  return SSR;
+}
+
+export function usePlayerPreferences(): PlayerPreferences {
+  return useSyncExternalStore(subscribePreferences, getPreferences, getServerSnapshot);
+}

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

@@ -0,0 +1,77 @@
+'use client';
+
+// One rAF loop reads audio.currentTime and writes a single CSS variable.
+// Pauses on document.hidden and when the audio is paused (with a final
+// flush to keep the bar in sync after the seek that triggered the pause).
+
+import { useEffect } from 'react';
+
+const VAR = '--p';
+
+export function usePlayheadLoop(
+  audio: HTMLAudioElement,
+  el: HTMLElement | null,
+  enabled = true,
+): void {
+  useEffect(() => {
+    if (!enabled || !el) return;
+    let raf = 0;
+    let lastPct = -1;
+
+    const writePct = () => {
+      const dur = audio.duration;
+      if (!Number.isFinite(dur) || dur <= 0) return;
+      const pct = Math.max(0, Math.min(100, (audio.currentTime / dur) * 100));
+      if (Math.abs(pct - lastPct) < 0.01) return;
+      lastPct = pct;
+      el.style.setProperty(VAR, `${pct.toFixed(2)}%`);
+    };
+
+    const tick = () => {
+      if (typeof document !== 'undefined' && document.hidden) {
+        raf = 0;
+        return;
+      }
+      writePct();
+      raf = requestAnimationFrame(tick);
+    };
+
+    const start = () => {
+      if (raf) return;
+      raf = requestAnimationFrame(tick);
+    };
+    const stop = () => {
+      if (!raf) return;
+      cancelAnimationFrame(raf);
+      raf = 0;
+      writePct();
+    };
+
+    if (!audio.paused) start();
+
+    const onPlay = () => start();
+    const onPauseOrEnd = () => stop();
+    const onSeek = () => writePct();
+    const onVisibility = () => {
+      if (document.hidden) stop();
+      else if (!audio.paused) start();
+    };
+
+    audio.addEventListener('play', onPlay);
+    audio.addEventListener('pause', onPauseOrEnd);
+    audio.addEventListener('ended', onPauseOrEnd);
+    audio.addEventListener('seeked', onSeek);
+    audio.addEventListener('timeupdate', writePct);
+    document.addEventListener('visibilitychange', onVisibility);
+
+    return () => {
+      stop();
+      audio.removeEventListener('play', onPlay);
+      audio.removeEventListener('pause', onPauseOrEnd);
+      audio.removeEventListener('ended', onPauseOrEnd);
+      audio.removeEventListener('seeked', onSeek);
+      audio.removeEventListener('timeupdate', writePct);
+      document.removeEventListener('visibilitychange', onVisibility);
+    };
+  }, [audio, el, enabled]);
+}

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

@@ -0,0 +1,20 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+export function useElementWidth(el: HTMLElement | null): number {
+  const [w, setW] = useState(0);
+  useEffect(() => {
+    if (!el || typeof ResizeObserver === 'undefined') return;
+    setW(el.clientWidth);
+    const obs = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        const next = entry.contentRect.width;
+        setW((prev) => (Math.abs(prev - next) < 0.5 ? prev : next));
+      }
+    });
+    obs.observe(el);
+    return () => obs.disconnect();
+  }, [el]);
+  return w;
+}

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

@@ -0,0 +1,22 @@
+'use client';
+
+// Fires `cb` whenever <html> class changes (typical light/dark toggle convention)
+// or the user's color-scheme media preference flips. Used to repaint canvases
+// after a theme switch — see ADR-003.
+
+import { useEffect } from 'react';
+
+export function useThemeWatcher(cb: () => void): void {
+  useEffect(() => {
+    const root = document.documentElement;
+    const obs = new MutationObserver(cb);
+    obs.observe(root, { attributes: true, attributeFilter: ['class', 'data-theme'] });
+    const mq = window.matchMedia?.('(prefers-color-scheme: dark)');
+    const onMq = () => cb();
+    mq?.addEventListener?.('change', onMq);
+    return () => {
+      obs.disconnect();
+      mq?.removeEventListener?.('change', onMq);
+    };
+  }, [cb]);
+}

package/src/tools/AudioPlayer/index.ts

@@ -1,139 +1,68 @@
-/**
- * AudioPlayer - Complete audio playback solution with reactive visualizations
- *
- * Uses HTML5 audio for playback + Web Audio API for visualization.
- * No crackling, native streaming support.
- *
- * @example
- * // Simple usage
- * import { HybridSimplePlayer } from '../../_shared';
- * <HybridSimplePlayer src="/audio.mp3" title="Track Title" />
- *
- * @example
- * // Custom setup with context
- * import { HybridAudioProvider, HybridAudioPlayer } from '../../_shared';
- * <HybridAudioProvider src={audioUrl}>
- *   <HybridAudioPlayer showWaveform showControls />
- * </HybridAudioProvider>
- */
-
-// =============================================================================
-// COMPONENTS
-// =============================================================================
-
-export {
-  HybridAudioPlayer,
-  HybridSimplePlayer,
-  HybridCompactPlayer,
-  HybridWaveform,
-  AudioReactiveCover,
-  // Effect components (for custom implementations)
-  GlowEffect,
-  OrbsEffect,
-  SpotlightEffect,
-  MeshEffect,
-} from './components';
-
+export { Player } from './Player';
+export { LazyPlayer } from './lazy';
 export type {
-  HybridAudioPlayerProps,
-  HybridSimplePlayerProps,
-  HybridCompactPlayerProps,
-  HybridWaveformProps,
-  AudioReactiveCoverProps,
-  GlowEffectData,
-} from './components';
-
-// =============================================================================
-// CONTEXT
-// =============================================================================
-
+  PlayerProps,
+  PlayerState,
+  PlayerStateKind,
+  PlayerControls,
+  PlayerHandle,
+  WaveformConfig,
+  WaveformMode,
+  ReactiveCoverMode,
+  PlayerVariant,
+  PlayerErrorReason,
+} from './types';
+
+// Selector hooks for advanced consumers (rare).
 export {
-  HybridAudioProvider,
-  useHybridAudioContext,
-  useHybridAudioState,
-  useHybridAudioControls,
-  useHybridAudioLevels,
-  useHybridWebAudio,
+  PlayerProvider,
+  usePlayerAudio,
+  usePlayerControls,
+  usePlayerDuration,
+  usePlayerLevels,
+  usePlayerMeta,
+  usePlayerPaused,
+  usePlayerState,
 } from './context';
-
-export type {
-  HybridAudioContextValue,
-  HybridAudioProviderProps,
-} from './context';
-
-// =============================================================================
-// HOOKS
-// =============================================================================
-
 export {
-  // Audio bus
-  useAudioBus,
-  useAudioBusStore,
-  // Core hooks
-  useHybridAudio,
-  useHybridAudioAnalysis,
-  // Visualization settings
-  useVisualization,
-  useAudioVisualization,
-  VisualizationProvider,
-  VARIANT_INFO,
-  INTENSITY_INFO,
-  COLOR_SCHEME_INFO,
-} from './hooks';
-
-export type {
-  UseAudioBusReturn,
-  UseHybridAudioOptions,
-  HybridAudioState,
-  HybridAudioControls,
-  HybridWebAudioAPI,
-  UseHybridAudioReturn,
-  VisualizationSettings,
-  VisualizationVariant,
-  VisualizationIntensity,
-  VisualizationColorScheme,
-  UseVisualizationReturn,
-  UseAudioVisualizationReturn,
-  VisualizationProviderProps,
-} from './hooks';
-
-// =============================================================================
-// TYPES
-// =============================================================================
-
-export type { EqualizerOptions } from './types';
-
-// =============================================================================
-// EFFECTS
-// =============================================================================
-
+  setActivePlayer,
+  getActivePlayer,
+  getLastActivePlayer,
+  subscribeActivePlayer,
+  getPreferences,
+  setStoredVolume,
+  setStoredMuted,
+  subscribePreferences,
+} from './store';
+export type { PlayerPreferences } from './store';
 export {
-  // Utilities
-  getEffectConfig,
-  getColors,
-  prepareEffectColors,
-  calculateGlowLayers,
-  calculateOrbs,
-  calculateMeshGradients,
-  calculateSpotlight,
-  // Constants
-  INTENSITY_CONFIG,
-  COLOR_SCHEMES,
-  EFFECT_ANIMATIONS,
-} from './effects';
-
-export type {
-  EffectVariant,
-  EffectIntensity,
-  EffectColorScheme,
-  AudioLevels,
-  EffectConfig,
-  EffectColors,
-  EffectLayer,
-} from './effects';
-
-// =============================================================================
-// UTILITIES
-// =============================================================================
-
-export { formatTime } from './utils';
+  useActivePlayer,
+  useLastActivePlayer,
+  useIsActivePlayer,
+} from './hooks/useActivePlayer';
+export { usePlayerPreferences } from './hooks/usePlayerPreferences';
+export { clearPeaksCache, setPeaks } from './audio';
+
+// Slot components — for custom layouts inside <PlayerProvider>.
+// Each one is presentational: reads from the player context, renders one
+// piece of UI. Compose them in any grid you want.
+export { Cover, CoverPlaceholder, ReactivePulse } from './parts/Cover';
+export { Title, Artist, TimeDisplay } from './parts/Meta';
+export {
+  PlayButton,
+  SkipButton,
+  VolumeControl,
+  LoopButton,
+  ControlsRow,
+  IconButton,
+} from './parts/Controls';
+export {
+  Waveform,
+  PeaksWaveform,
+  LiveWaveform,
+  BarsWaveform,
+  ProgressBar,
+  WaveformSkeleton,
+} from './parts/Waveform';
+export { ErrorState } from './parts/ErrorState';
+export { DefaultLayout, CompactLayout } from './parts/Layout';