@djangocfg/ui-tools 2.1.310 → 2.1.313

package/src/tools/AudioPlayer/context/MetaContext.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import { createContext } from 'react';
+
+export type PlayerMeta = {
+  src: string;
+  title?: string;
+  artist?: string;
+  album?: string;
+  cover?: string;
+  hasPrev: boolean;
+  hasNext: boolean;
+};
+
+export const MetaCtx = createContext<PlayerMeta | null>(null);
+MetaCtx.displayName = 'AudioPlayerMetaCtx';

package/src/tools/AudioPlayer/context/PlayerProvider.tsx

@@ -0,0 +1,314 @@
+'use client';
+
+import { useEffect, useId, useMemo, useRef, useState } from 'react';
+import type { ReactNode } from 'react';
+import { unlockAudioContext } from '../audio/audioContext';
+import { getPeaksFromCache, setPeaks } from '../audio/peaksCache';
+import { registerPlayer, setActivePlayer } from '../store/activePlayerBus';
+import { createLevelsStore } from '../store/createLevelsStore';
+import type { LevelsStore } from '../store/createLevelsStore';
+import {
+  getPreferences,
+  setStoredMuted,
+  setStoredVolume,
+  subscribePreferences,
+} from '../store/preferencesStore';
+import { clamp } from '../utils/clamp';
+import type { PlayerControls, PlayerErrorReason } from '../types';
+import { AudioRefCtx } from './AudioRefContext';
+import { ControlsCtx } from './ControlsContext';
+import { LevelsCtx } from './LevelsContext';
+import { MetaCtx, type PlayerMeta } from './MetaContext';
+import { StateCtx } from './StateContext';
+import { createAudioSnapshotSource, useAudioElementState } from '../hooks/useAudioElementEvents';
+
+export type PlayerProviderProps = {
+  src: string;
+  peaks?: Float32Array;
+  title?: string;
+  artist?: string;
+  album?: string;
+  cover?: string;
+  autoplay?: boolean;
+  loop?: boolean;
+  initialVolume?: number;
+  muted?: boolean;
+  preload?: 'none' | 'metadata' | 'auto';
+  exclusive?: boolean;
+  onPrev?: () => void;
+  onNext?: () => void;
+  onPlay?: () => void;
+  onPause?: () => void;
+  onEnded?: () => void;
+  onError?: (reason: PlayerErrorReason, e: unknown) => void;
+  children: ReactNode;
+};
+
+function createAudioElement(): HTMLAudioElement {
+  const a = new Audio();
+  a.crossOrigin = 'anonymous';
+  a.preload = 'metadata';
+  return a;
+}
+
+export function PlayerProvider(props: PlayerProviderProps) {
+  const {
+    src,
+    peaks: peaksProp,
+    title,
+    artist,
+    album,
+    cover,
+    autoplay = false,
+    loop = false,
+    initialVolume,
+    muted: mutedProp,
+    preload = 'metadata',
+    exclusive = true,
+    onPrev,
+    onNext,
+    onPlay,
+    onPause,
+    onEnded,
+    onError,
+    children,
+  } = props;
+
+  // Explicit props win and opt the player out of the persisted preference sync.
+  // Otherwise we read defaults from the shared store and stay subscribed so a
+  // change in one player is reflected in every other player on the page.
+  const volumeIsControlled = initialVolume !== undefined;
+  const mutedIsControlled = mutedProp !== undefined;
+
+  const playerId = useId();
+
+  // <audio>, snapshot source, levels store — created exactly once per
+  // component instance via useState lazy initializer (StrictMode-safe: the
+  // initializer runs once even though render runs twice).
+  const [audio] = useState<HTMLAudioElement>(createAudioElement);
+  const [source] = useState(() => createAudioSnapshotSource(audio));
+  const [levelsStore] = useState<LevelsStore>(() => createLevelsStore());
+
+  // Seed peaks-from-prop into the module cache so other consumers benefit too.
+  if (peaksProp && getPeaksFromCache(src) === undefined) {
+    setPeaks(src, peaksProp);
+  }
+  const initialPeaks = peaksProp ?? getPeaksFromCache(src);
+  const [activePeaks, setActivePeaks] = useState<Float32Array | undefined>(initialPeaks);
+
+  // Apply src / preload / loop / volume / muted imperatively.
+  useEffect(() => {
+    if (audio.src !== src) {
+      audio.src = src;
+      audio.load();
+    }
+  }, [audio, src]);
+
+  useEffect(() => {
+    audio.preload = preload;
+  }, [audio, preload]);
+
+  useEffect(() => {
+    audio.loop = loop;
+  }, [audio, loop]);
+
+  // Initial volume / muted: prop > stored > defaults.
+  useEffect(() => {
+    const stored = getPreferences();
+    audio.volume = clamp(volumeIsControlled ? (initialVolume as number) : stored.volume, 0, 1);
+    audio.muted = mutedIsControlled ? Boolean(mutedProp) : stored.muted;
+    // Run once at mount; later updates flow through the subscription below
+    // (or, for controlled players, through the prop effects).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [audio]);
+
+  // Re-apply when controlled props change explicitly.
+  useEffect(() => {
+    if (!volumeIsControlled || initialVolume === undefined) return;
+    audio.volume = clamp(initialVolume, 0, 1);
+  }, [audio, volumeIsControlled, initialVolume]);
+
+  useEffect(() => {
+    if (!mutedIsControlled || mutedProp === undefined) return;
+    audio.muted = mutedProp;
+  }, [audio, mutedIsControlled, mutedProp]);
+
+  // Subscribe uncontrolled players to the shared preferences store so they
+  // stay in sync with each other and across tabs.
+  useEffect(() => {
+    if (volumeIsControlled && mutedIsControlled) return;
+    return subscribePreferences((prefs) => {
+      if (!volumeIsControlled && audio.volume !== prefs.volume) {
+        audio.volume = prefs.volume;
+      }
+      if (!mutedIsControlled && audio.muted !== prefs.muted) {
+        audio.muted = prefs.muted;
+      }
+    });
+  }, [audio, volumeIsControlled, mutedIsControlled]);
+
+  // When src changes, swap in cached peaks if available; clear otherwise.
+  useEffect(() => {
+    setActivePeaks(getPeaksFromCache(src));
+  }, [src]);
+
+  // Lifecycle event hooks.
+  useEffect(() => {
+    const handlePlay = () => onPlay?.();
+    const handlePause = () => onPause?.();
+    const handleEnded = () => onEnded?.();
+    const handleError = (e: Event) => {
+      const code = audio.error?.code ?? null;
+      const reason: PlayerErrorReason =
+        code === 2 ? 'network' : code === 3 ? 'decode' : code === 4 ? 'unsupported' : 'unknown';
+      onError?.(reason, e);
+    };
+    audio.addEventListener('play', handlePlay);
+    audio.addEventListener('pause', handlePause);
+    audio.addEventListener('ended', handleEnded);
+    audio.addEventListener('error', handleError);
+    return () => {
+      audio.removeEventListener('play', handlePlay);
+      audio.removeEventListener('pause', handlePause);
+      audio.removeEventListener('ended', handleEnded);
+      audio.removeEventListener('error', handleError);
+    };
+  }, [audio, onEnded, onError, onPause, onPlay]);
+
+  // Refs let controls.play() claim the active slot immediately, without
+  // re-memoizing on every prop change.
+  const exclusiveRef = useRef(exclusive);
+  exclusiveRef.current = exclusive;
+  const playerIdRef = useRef(playerId);
+  playerIdRef.current = playerId;
+
+  // Single-active-player coordination.
+  useEffect(() => {
+    if (!exclusive) return;
+    const unregister = registerPlayer(playerId, () => {
+      audio.pause();
+    });
+    // Backstop: claim the slot whenever the element starts playing, even if
+    // playback was triggered outside our controls (MediaSession, native UI).
+    const onPlayHandler = () => setActivePlayer(playerId);
+    audio.addEventListener('play', onPlayHandler);
+    return () => {
+      audio.removeEventListener('play', onPlayHandler);
+      unregister();
+    };
+  }, [audio, exclusive, playerId]);
+
+  // Hard cleanup on unmount: stop playback, release the network buffer.
+  // The element + cached MediaElementSourceNode are GC'd together via the
+  // WeakMap. In StrictMode (dev) the first mount-then-unmount pair fires this
+  // immediately, so the discarded audio never keeps playing in the background.
+  useEffect(() => {
+    return () => {
+      try {
+        audio.pause();
+        audio.removeAttribute('src');
+        audio.load();
+      } catch {
+        // ignore
+      }
+    };
+  }, [audio]);
+
+  // Controls — memoized once. Functions close over `audio` (stable ref).
+  const controls = useMemo<PlayerControls>(() => {
+    const playFn = async () => {
+      // Claim the active slot synchronously so siblings get paused before our
+      // audio.play() resolves. Backstop listener on `play` event covers
+      // playback started outside this function.
+      if (exclusiveRef.current) setActivePlayer(playerIdRef.current);
+      try {
+        await unlockAudioContext();
+      } catch {
+        // ignored — playback may still work without AudioContext.
+      }
+      try {
+        await audio.play();
+      } catch (e) {
+        // Caller decides; surface via onError when it's a real failure.
+        const isAbort = e instanceof DOMException && e.name === 'AbortError';
+        if (!isAbort) onError?.('unknown', e);
+      }
+    };
+    const pauseFn = () => {
+      audio.pause();
+    };
+    return {
+      play: playFn,
+      pause: pauseFn,
+      toggle: async () => {
+        if (audio.paused || audio.ended) await playFn();
+        else pauseFn();
+      },
+      seek: (seconds: number) => {
+        if (!Number.isFinite(seconds)) return;
+        const dur = Number.isFinite(audio.duration) ? audio.duration : 0;
+        audio.currentTime = clamp(seconds, 0, dur || seconds);
+      },
+      seekTo: (ratio: number) => {
+        const r = clamp(ratio, 0, 1);
+        const dur = Number.isFinite(audio.duration) ? audio.duration : 0;
+        if (dur > 0) audio.currentTime = r * dur;
+      },
+      setVolume: (v: number) => {
+        const next = clamp(v, 0, 1);
+        audio.volume = next;
+        if (next > 0 && audio.muted) audio.muted = false;
+        if (!volumeIsControlled) setStoredVolume(next);
+        if (!mutedIsControlled && next > 0) setStoredMuted(false);
+      },
+      toggleMute: () => {
+        const next = !audio.muted;
+        audio.muted = next;
+        if (!mutedIsControlled) setStoredMuted(next);
+      },
+      toggleLoop: () => {
+        audio.loop = !audio.loop;
+      },
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [audio, volumeIsControlled, mutedIsControlled]);
+
+  // Autoplay attempt (best-effort; suspended context will reject silently).
+  useEffect(() => {
+    if (!autoplay) return;
+    void controls.play();
+  }, [autoplay, controls]);
+
+  const state = useAudioElementState(source, Boolean(audio.src), activePeaks);
+
+  const meta = useMemo<PlayerMeta>(
+    () => ({
+      src,
+      title,
+      artist,
+      album,
+      cover,
+      hasPrev: Boolean(onPrev),
+      hasNext: Boolean(onNext),
+    }),
+    [src, title, artist, album, cover, onPrev, onNext],
+  );
+
+  return (
+    <AudioRefCtx.Provider value={audio}>
+      <MetaCtx.Provider value={meta}>
+        <StateCtx.Provider value={state}>
+          <ControlsCtx.Provider value={controls}>
+            <LevelsCtx.Provider value={levelsStore}>{children}</LevelsCtx.Provider>
+          </ControlsCtx.Provider>
+        </StateCtx.Provider>
+      </MetaCtx.Provider>
+    </AudioRefCtx.Provider>
+  );
+}
+
+// Internal helper for parts that want to expose peaks-update from the lazy hook.
+export function usePeaksSetter() {
+  // The provider seeds peaks via setPeaks() in the module cache; consumers
+  // re-read on src change. usePeaks hook re-uses the cache directly.
+}

package/src/tools/AudioPlayer/context/StateContext.tsx

@@ -0,0 +1,7 @@
+'use client';
+
+import { createContext } from 'react';
+import type { PlayerState } from '../types';
+
+export const StateCtx = createContext<PlayerState | null>(null);
+StateCtx.displayName = 'AudioPlayerStateCtx';

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

@@ -1,16 +1,17 @@
-/**
- * AudioPlayer context - Public API
- *
- * HybridAudioProvider: HTML5 audio + Web Audio API for visualization
- */
-
+export { AudioRefCtx } from './AudioRefContext';
+export { ControlsCtx } from './ControlsContext';
+export { LevelsCtx } from './LevelsContext';
+export { MetaCtx } from './MetaContext';
+export type { PlayerMeta } from './MetaContext';
+export { StateCtx } from './StateContext';
+export { PlayerProvider } from './PlayerProvider';
+export type { PlayerProviderProps } from './PlayerProvider';
 export {
-  HybridAudioProvider,
-  useHybridAudioContext,
-  useHybridAudioState,
-  useHybridAudioControls,
-  useHybridAudioLevels,
-  useHybridWebAudio,
-  type HybridAudioContextValue,
-  type HybridAudioProviderProps,
-} from './HybridAudioProvider';
+  usePlayerAudio,
+  usePlayerControls,
+  usePlayerDuration,
+  usePlayerLevels,
+  usePlayerMeta,
+  usePlayerPaused,
+  usePlayerState,
+} from './selectors';

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

@@ -0,0 +1,36 @@
+'use client';
+
+import { useContext } from 'react';
+import type { Context } from 'react';
+import type { LevelsStore } from '../store';
+import type { PlayerControls, PlayerState } from '../types';
+import { AudioRefCtx } from './AudioRefContext';
+import { ControlsCtx } from './ControlsContext';
+import { LevelsCtx } from './LevelsContext';
+import { MetaCtx, type PlayerMeta } from './MetaContext';
+import { StateCtx } from './StateContext';
+
+function useCtxOrThrow<T>(ctx: Context<T | null>, name: string): T {
+  const value = useContext(ctx);
+  if (value === null) {
+    throw new Error(`${name} must be used inside <PlayerProvider>`);
+  }
+  return value;
+}
+
+export const usePlayerState = (): PlayerState => useCtxOrThrow(StateCtx, 'usePlayerState');
+export const usePlayerControls = (): PlayerControls => useCtxOrThrow(ControlsCtx, 'usePlayerControls');
+export const usePlayerLevels = (): LevelsStore => useCtxOrThrow(LevelsCtx, 'usePlayerLevels');
+export const usePlayerMeta = (): PlayerMeta => useCtxOrThrow(MetaCtx, 'usePlayerMeta');
+export const usePlayerAudio = (): HTMLAudioElement => useCtxOrThrow(AudioRefCtx, 'usePlayerAudio');
+
+// Narrow slices.
+export const usePlayerPaused = (): boolean => {
+  const s = usePlayerState();
+  return s.kind !== 'playing';
+};
+
+export const usePlayerDuration = (): number => {
+  const s = usePlayerState();
+  return 'duration' in s ? s.duration : 0;
+};

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

@@ -1,39 +1,12 @@
-/**
- * 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 {
-  UseHybridAudioOptions,
-  HybridAudioState,
-  HybridAudioControls,
-  HybridWebAudioAPI,
-  UseHybridAudioReturn,
-} from './useHybridAudio';
-
-// Frequency analysis hook
-export { useHybridAudioAnalysis } from './useHybridAudioAnalysis';
-
-// Visualization settings (localStorage persistence)
-export {
-  useVisualization,
-  useAudioVisualization,
-  VisualizationProvider,
-  VARIANT_INFO,
-  INTENSITY_INFO,
-  COLOR_SCHEME_INFO,
-} from './useVisualization';
-export type {
-  VisualizationSettings,
-  VisualizationVariant,
-  VisualizationIntensity,
-  VisualizationColorScheme,
-  UseVisualizationReturn,
-  UseAudioVisualizationReturn,
-  VisualizationProviderProps,
-} from './useVisualization';
+export { createAudioSnapshotSource, useAudioElementState } from './useAudioElementEvents';
+export { usePeaks } from './usePeaks';
+export type { UsePeaksOptions } from './usePeaks';
+export { useAnalyser } from './useAnalyser';
+export { usePlayheadLoop } from './usePlayheadLoop';
+export { useMediaSession } from './useMediaSession';
+export { useKeyboardShortcuts } from './useKeyboardShortcuts';
+export type { UseKeyboardShortcutsOptions } from './useKeyboardShortcuts';
+export { useElementWidth } from './useResizeObserver';
+export { useThemeWatcher } from './useThemeWatcher';
+export { useActivePlayer, useLastActivePlayer, useIsActivePlayer } from './useActivePlayer';
+export { usePlayerPreferences } from './usePlayerPreferences';

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

@@ -0,0 +1,31 @@
+'use client';
+
+// Subscribe to the global active-player id. Reads from activePlayerBus, which
+// already coordinates same-tab + cross-tab via BroadcastChannel.
+
+import { useSyncExternalStore } from 'react';
+import {
+  getActivePlayer,
+  getLastActivePlayer,
+  subscribeActivePlayer,
+} from '../store/activePlayerBus';
+
+const getServerSnapshot = (): string | null => null;
+
+/** Currently active player id. `null` when nothing plays. */
+export function useActivePlayer(): string | null {
+  return useSyncExternalStore(subscribeActivePlayer, getActivePlayer, getServerSnapshot);
+}
+
+/** Most recently active player id. Stays set after pause; useful for "last
+ * played" UIs where you want to keep showing a track even when paused. */
+export function useLastActivePlayer(): string | null {
+  return useSyncExternalStore(subscribeActivePlayer, getLastActivePlayer, getServerSnapshot);
+}
+
+/** True when the given id is currently active. Convenience for conditional
+ * styling without comparing strings inline. */
+export function useIsActivePlayer(id: string | null | undefined): boolean {
+  const active = useActivePlayer();
+  return Boolean(id) && active === id;
+}

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

@@ -0,0 +1,62 @@
+'use client';
+
+// Lazily creates an AnalyserNode bound to the player's <audio> via the cached
+// MediaElementSourceNode, samples it at ~30 Hz into a Float32Array, and pushes
+// frames into the LevelsStore. Only mounted by LiveWaveform / reactive cover.
+
+import { useEffect } from 'react';
+import { getAudioContext } from '../audio/audioContext';
+import { getMediaElementSource } from '../audio/mediaElementSourceCache';
+import type { LevelsStore } from '../store/createLevelsStore';
+
+const FFT_SIZE = 1024;
+const READ_INTERVAL_MS = 33;
+const SMOOTHING = 0.8;
+
+export function useAnalyser(audio: HTMLAudioElement, store: LevelsStore, enabled: boolean) {
+  useEffect(() => {
+    if (!enabled) return;
+    let analyser: AnalyserNode | null = null;
+    let interval: ReturnType<typeof setInterval> | null = null;
+    let buffer = new Uint8Array(0);
+    let normalized = new Float32Array(0);
+    let cancelled = false;
+
+    try {
+      const ctx = getAudioContext();
+      const source = getMediaElementSource(audio);
+      analyser = ctx.createAnalyser();
+      analyser.fftSize = FFT_SIZE;
+      analyser.smoothingTimeConstant = SMOOTHING;
+      source.connect(analyser);
+      buffer = new Uint8Array(analyser.frequencyBinCount);
+      normalized = new Float32Array(analyser.frequencyBinCount);
+      store.setActive(true);
+
+      const tick = () => {
+        if (cancelled || !analyser) return;
+        if (typeof document !== 'undefined' && document.hidden) return;
+        analyser.getByteFrequencyData(buffer);
+        for (let i = 0; i < buffer.length; i++) normalized[i] = buffer[i] / 255;
+        store.set(normalized);
+      };
+      interval = setInterval(tick, READ_INTERVAL_MS);
+    } catch {
+      // Not supported in this environment; leave levels empty.
+      store.setActive(false);
+    }
+
+    return () => {
+      cancelled = true;
+      if (interval) clearInterval(interval);
+      if (analyser) {
+        try {
+          analyser.disconnect();
+        } catch {
+          // ignore
+        }
+      }
+      store.setActive(false);
+    };
+  }, [audio, store, enabled]);
+}

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

@@ -0,0 +1,102 @@
+// useSyncExternalStore over a low-frequency set of HTMLAudioElement events.
+// Snapshot is cached; consumers only re-render when one of the tracked fields
+// actually changes (Object.is on the snapshot). See ADR-001 / research 03 §2.
+
+import { useSyncExternalStore } from 'react';
+import type { PlayerErrorReason, PlayerState, PlayerStateKind } from '../types';
+
+const TRACKED = [
+  'play',
+  'pause',
+  'ended',
+  'loadedmetadata',
+  'durationchange',
+  'emptied',
+  'waiting',
+  'canplay',
+  'error',
+] as const;
+
+type Snapshot = {
+  paused: boolean;
+  ended: boolean;
+  duration: number;
+  ready: boolean;
+  errorCode: number | null;
+};
+
+function readSnapshot(audio: HTMLAudioElement): Snapshot {
+  return {
+    paused: audio.paused,
+    ended: audio.ended,
+    duration: Number.isFinite(audio.duration) ? audio.duration : 0,
+    ready: audio.readyState >= 2,
+    errorCode: audio.error?.code ?? null,
+  };
+}
+
+function snapshotsEqual(a: Snapshot, b: Snapshot): boolean {
+  return (
+    a.paused === b.paused &&
+    a.ended === b.ended &&
+    a.duration === b.duration &&
+    a.ready === b.ready &&
+    a.errorCode === b.errorCode
+  );
+}
+
+export function createAudioSnapshotSource(audio: HTMLAudioElement) {
+  let cached: Snapshot = readSnapshot(audio);
+  return {
+    subscribe(cb: () => void): () => void {
+      const refresh = () => {
+        const next = readSnapshot(audio);
+        if (!snapshotsEqual(cached, next)) {
+          cached = next;
+          cb();
+        }
+      };
+      for (const e of TRACKED) audio.addEventListener(e, refresh);
+      return () => {
+        for (const e of TRACKED) audio.removeEventListener(e, refresh);
+      };
+    },
+    getSnapshot(): Snapshot {
+      return cached;
+    },
+    getServerSnapshot(): Snapshot {
+      return cached;
+    },
+  };
+}
+
+function errorCodeToReason(code: number | null): PlayerErrorReason {
+  // MediaError codes: 1 ABORT, 2 NETWORK, 3 DECODE, 4 SRC_NOT_SUPPORTED.
+  if (code === 2) return 'network';
+  if (code === 3) return 'decode';
+  if (code === 4) return 'unsupported';
+  return 'unknown';
+}
+
+function snapshotToState(snap: Snapshot, hasSrc: boolean, peaks?: Float32Array): PlayerState {
+  if (snap.errorCode !== null) {
+    return { kind: 'error', reason: errorCodeToReason(snap.errorCode), duration: snap.duration };
+  }
+  if (!hasSrc) return { kind: 'idle' };
+  if (!snap.ready) return { kind: 'loading' };
+  const kind: PlayerStateKind = snap.ended
+    ? 'ended'
+    : snap.paused
+      ? 'paused'
+      : 'playing';
+  return { kind, duration: snap.duration, peaks };
+}
+
+export function useAudioElementState(
+  source: ReturnType<typeof createAudioSnapshotSource>,
+  hasSrc: boolean,
+  peaks?: Float32Array,
+): PlayerState {
+  const snap = useSyncExternalStore(source.subscribe, source.getSnapshot, source.getServerSnapshot);
+  return snapshotToState(snap, hasSrc, peaks);
+}