@djangocfg/ui-tools 2.1.312 → 2.1.314

package/src/tools/AudioPlayer/parts/ErrorState/index.ts

@@ -0,0 +1 @@
+export { ErrorState } from './ErrorState';

package/src/tools/AudioPlayer/parts/Layout/CompactLayout.tsx

@@ -0,0 +1,25 @@
+'use client';
+
+import { PlayButton, VolumeControl } from '../Controls';
+import { TimeDisplay } from '../Meta';
+import { Waveform } from '../Waveform';
+import type { WaveformConfig } from '../../types';
+
+type Props = { waveform?: WaveformConfig; seekStartsPlayback?: boolean };
+
+export function CompactLayout({ waveform, seekStartsPlayback }: Props) {
+  return (
+    <div className="flex items-center gap-3 p-2">
+      <PlayButton size="compact" />
+      <div className="min-w-0 flex-1">
+        <Waveform
+          config={waveform}
+          height={waveform?.height ?? 24}
+          seekStartsPlayback={seekStartsPlayback}
+        />
+      </div>
+      <TimeDisplay />
+      <VolumeControl />
+    </div>
+  );
+}

package/src/tools/AudioPlayer/parts/Layout/DefaultLayout.tsx

@@ -0,0 +1,48 @@
+'use client';
+
+import { ControlsRow } from '../Controls';
+import { Cover, ReactivePulse } from '../Cover';
+import { ErrorState } from '../ErrorState';
+import { Artist, Title } from '../Meta';
+import { Waveform } from '../Waveform';
+import type { ReactiveCoverMode, WaveformConfig } from '../../types';
+import { usePlayerMeta } from '../../context/selectors';
+
+type Props = {
+  waveform?: WaveformConfig;
+  reactiveCover?: ReactiveCoverMode;
+  onPrev?: () => void;
+  onNext?: () => void;
+  seekStartsPlayback?: boolean;
+};
+
+export function DefaultLayout({ waveform, reactiveCover, onPrev, onNext, seekStartsPlayback }: Props) {
+  const meta = usePlayerMeta();
+  const cover = (
+    <Cover src={meta.cover} alt={meta.title ? `${meta.title} cover` : ''} size={56} />
+  );
+  return (
+    <div className="flex flex-col gap-3.5 p-4">
+      {/* Header: cover ↔ meta, vertically centered. No timer here — timer
+          lives in ControlsRow next to playback. */}
+      <div className="flex items-center gap-3">
+        {reactiveCover === 'subtle' ? (
+          <ReactivePulse enabled>{cover}</ReactivePulse>
+        ) : (
+          cover
+        )}
+        <div className="min-w-0 flex-1">
+          <Title />
+          <Artist />
+        </div>
+      </div>
+      <Waveform
+        config={waveform}
+        height={waveform?.height ?? 40}
+        seekStartsPlayback={seekStartsPlayback}
+      />
+      <ErrorState />
+      <ControlsRow onPrev={onPrev} onNext={onNext} showTime />
+    </div>
+  );
+}

package/src/tools/AudioPlayer/parts/Layout/index.ts

@@ -0,0 +1,2 @@
+export { DefaultLayout } from './DefaultLayout';
+export { CompactLayout } from './CompactLayout';

package/src/tools/AudioPlayer/parts/Meta/Artist.tsx

@@ -0,0 +1,14 @@
+'use client';
+
+import { usePlayerMeta } from '../../context/selectors';
+
+export function Artist() {
+  const { artist, album } = usePlayerMeta();
+  if (!artist && !album) return null;
+  const text = [artist, album].filter(Boolean).join(' · ');
+  return (
+    <p className="truncate text-xs text-muted-foreground" title={text}>
+      {text}
+    </p>
+  );
+}

package/src/tools/AudioPlayer/parts/Meta/TimeDisplay.tsx

@@ -0,0 +1,49 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+import { usePlayerAudio, usePlayerDuration } from '../../context/selectors';
+import { formatTime } from '../../utils/formatTime';
+
+const READ_INTERVAL_MS = 200;
+
+export function TimeDisplay() {
+  const audio = usePlayerAudio();
+  const duration = usePlayerDuration();
+  const currentRef = useRef<HTMLSpanElement | null>(null);
+
+  useEffect(() => {
+    const el = currentRef.current;
+    if (!el) return;
+    let raf = 0;
+    let last = -1;
+    let timer: ReturnType<typeof setInterval> | null = null;
+    const write = () => {
+      const t = audio.currentTime;
+      if (Math.abs(t - last) < 0.5) return;
+      last = t;
+      el.textContent = formatTime(t);
+    };
+    write();
+    const onSeek = () => write();
+    audio.addEventListener('seeked', onSeek);
+    audio.addEventListener('timeupdate', onSeek);
+    // Backup poll when timeupdate is throttled (e.g. background tab → visible).
+    timer = setInterval(() => {
+      if (!audio.paused) write();
+    }, READ_INTERVAL_MS);
+    return () => {
+      cancelAnimationFrame(raf);
+      audio.removeEventListener('seeked', onSeek);
+      audio.removeEventListener('timeupdate', onSeek);
+      if (timer) clearInterval(timer);
+    };
+  }, [audio]);
+
+  return (
+    <span className="tabular-nums text-xs text-muted-foreground">
+      <span ref={currentRef}>{formatTime(audio.currentTime)}</span>
+      {' / '}
+      {formatTime(duration)}
+    </span>
+  );
+}

package/src/tools/AudioPlayer/parts/Meta/Title.tsx

@@ -0,0 +1,13 @@
+'use client';
+
+import { usePlayerMeta } from '../../context/selectors';
+
+export function Title() {
+  const { title } = usePlayerMeta();
+  if (!title) return null;
+  return (
+    <p className="truncate text-sm font-medium text-foreground" title={title}>
+      {title}
+    </p>
+  );
+}

package/src/tools/AudioPlayer/parts/Meta/index.ts

@@ -0,0 +1,3 @@
+export { Title } from './Title';
+export { Artist } from './Artist';
+export { TimeDisplay } from './TimeDisplay';

package/src/tools/AudioPlayer/parts/Skeleton/CoverSkeleton.tsx

@@ -0,0 +1,13 @@
+'use client';
+
+type Props = { size: number };
+
+export function CoverSkeleton({ size }: Props) {
+  return (
+    <div
+      className="audioplayer-shimmer rounded-md bg-muted"
+      style={{ width: size, height: size }}
+      aria-hidden="true"
+    />
+  );
+}

package/src/tools/AudioPlayer/parts/Skeleton/MetaSkeleton.tsx

@@ -0,0 +1,10 @@
+'use client';
+
+export function MetaSkeleton() {
+  return (
+    <div className="flex flex-col gap-1.5" aria-hidden="true">
+      <div className="audioplayer-shimmer h-3.5 w-2/3 rounded bg-muted" />
+      <div className="audioplayer-shimmer h-3 w-1/3 rounded bg-muted/70" />
+    </div>
+  );
+}

package/src/tools/AudioPlayer/parts/Skeleton/index.ts

@@ -0,0 +1,2 @@
+export { MetaSkeleton } from './MetaSkeleton';
+export { CoverSkeleton } from './CoverSkeleton';

package/src/tools/AudioPlayer/parts/Waveform/BarsWaveform.tsx

@@ -0,0 +1,48 @@
+'use client';
+
+// Decorative CSS-only equalizer. No audio coupling. Use when waveform shape
+// doesn't matter (notification bells, generic "audio playing" affordance).
+
+import { useMemo } from 'react';
+import { usePlayerPaused } from '../../context/selectors';
+
+type Props = {
+  height: number;
+  barWidth: number;
+  barGap: number;
+  bars?: number;
+};
+
+const BAR_COUNT = 28;
+
+export function BarsWaveform({ height, barWidth, barGap, bars = BAR_COUNT }: Props) {
+  const paused = usePlayerPaused();
+  const items = useMemo(() => {
+    return Array.from({ length: bars }, (_, i) => ({
+      delay: `${(i % 7) * 90}ms`,
+      duration: `${800 + (i % 5) * 120}ms`,
+    }));
+  }, [bars]);
+
+  return (
+    <div
+      className="audioplayer-bars flex w-full items-center justify-between"
+      style={{ height, gap: barGap }}
+      data-mode="bars"
+      aria-hidden="true"
+    >
+      {items.map((it, i) => (
+        <span
+          key={i}
+          className="rounded-sm bg-primary"
+          style={{
+            width: barWidth,
+            height: '40%',
+            animation: paused ? undefined : `audioplayer-bar ${it.duration} ${it.delay} ease-in-out infinite`,
+            transformOrigin: 'center',
+          }}
+        />
+      ))}
+    </div>
+  );
+}

package/src/tools/AudioPlayer/parts/Waveform/LiveWaveform.tsx

@@ -0,0 +1,95 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+import { alpha, useThemeColor } from '@djangocfg/ui-core/styles/palette';
+import { useAnalyser } from '../../hooks/useAnalyser';
+import { useElementWidth } from '../../hooks/useResizeObserver';
+import { usePlayerAudio, usePlayerControls, usePlayerLevels } from '../../context/selectors';
+import { attachHover, attachSeek } from './waveformInteraction';
+import { paintLive } from './waveformRenderer';
+
+type Props = {
+  height: number;
+  barWidth: number;
+  barGap: number;
+  seekStartsPlayback?: boolean;
+};
+
+export function LiveWaveform({ height, barWidth, barGap, seekStartsPlayback }: Props) {
+  const audio = usePlayerAudio();
+  const controls = usePlayerControls();
+  const store = usePlayerLevels();
+  const [container, setContainer] = useState<HTMLDivElement | null>(null);
+  const canvasRef = useRef<HTMLCanvasElement | null>(null);
+  const fgHex = useThemeColor('primary');
+  const mutedHex = useThemeColor('muted-foreground');
+  const colorRef = useRef(fgHex);
+  colorRef.current = fgHex;
+  useElementWidth(container);
+
+  useAnalyser(audio, store, true);
+
+  // rAF paint loop reads from the imperative store. Zero React renders.
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return;
+    let raf = 0;
+    const tick = () => {
+      if (typeof document !== 'undefined' && document.hidden) {
+        raf = requestAnimationFrame(tick);
+        return;
+      }
+      paintLive(canvas, store.getCurrent(), {
+        color: colorRef.current,
+        barWidth,
+        barGap,
+        minBarHeight: 1,
+      });
+      raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+  }, [store, barWidth, barGap]);
+
+  useEffect(() => {
+    if (!container) return;
+    const detachSeek = attachSeek(container, audio, {
+      startsPlayback: seekStartsPlayback,
+      onPlayRequest: () => void controls.play(),
+    });
+    const detachHover = attachHover(container, audio);
+    return () => {
+      detachSeek();
+      detachHover();
+    };
+  }, [audio, container, controls, seekStartsPlayback]);
+
+  return (
+    <div
+      ref={setContainer}
+      className="audioplayer-waveform relative w-full select-none cursor-pointer"
+      style={{ height }}
+      data-mode="live"
+    >
+      <canvas ref={canvasRef} className="absolute inset-0 h-full w-full" aria-hidden="true" />
+      <div
+        className="audioplayer-hover pointer-events-none absolute top-0 bottom-0 w-px transition-opacity"
+        style={{
+          left: 'var(--hp, -10px)',
+          opacity: 'var(--ho, 0)',
+          backgroundColor: alpha(mutedHex, 0.5),
+        }}
+        aria-hidden="true"
+      />
+      <div
+        data-audioplayer-time-tip
+        className="audioplayer-tip pointer-events-none absolute -top-7 -translate-x-1/2 rounded bg-foreground px-1.5 py-0.5 text-[10px] tabular-nums text-background transition-opacity"
+        style={{
+          left: 'var(--hp, -100px)',
+          opacity: 'var(--ht, 0)',
+        }}
+        aria-hidden="true"
+      />
+    </div>
+  );
+}

package/src/tools/AudioPlayer/parts/Waveform/PeaksWaveform.tsx

@@ -0,0 +1,100 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { alpha, useThemeColor } from '@djangocfg/ui-core/styles/palette';
+import { usePlayerAudio, usePlayerControls } from '../../context/selectors';
+import { useElementWidth } from '../../hooks/useResizeObserver';
+import { usePlayheadLoop } from '../../hooks/usePlayheadLoop';
+import { useThemeWatcher } from '../../hooks/useThemeWatcher';
+import { attachHover, attachSeek } from './waveformInteraction';
+import { paintPeaks } from './waveformRenderer';
+
+type Props = {
+  peaks: Float32Array;
+  height: number;
+  barWidth: number;
+  barGap: number;
+  seekStartsPlayback?: boolean;
+};
+
+export function PeaksWaveform({ peaks, height, barWidth, barGap, seekStartsPlayback }: Props) {
+  const audio = usePlayerAudio();
+  const controls = usePlayerControls();
+  // State-backed ref so child hooks re-run once the DOM node attaches.
+  const [container, setContainer] = useState<HTMLDivElement | null>(null);
+  const bgCanvasRef = useRef<HTMLCanvasElement | null>(null);
+  const fgCanvasRef = useRef<HTMLCanvasElement | null>(null);
+  const width = useElementWidth(container);
+
+  const fgHex = useThemeColor('primary');
+  const mutedHex = useThemeColor('muted-foreground');
+
+  const repaint = useCallback(() => {
+    const bg = bgCanvasRef.current;
+    const fg = fgCanvasRef.current;
+    if (!bg || !fg) return;
+    paintPeaks(bg, peaks, { color: alpha(mutedHex, 0.4), barWidth, barGap, minBarHeight: 1 });
+    paintPeaks(fg, peaks, { color: fgHex, barWidth, barGap, minBarHeight: 1 });
+  }, [peaks, barWidth, barGap, fgHex, mutedHex]);
+
+  useEffect(repaint, [repaint, width]);
+  useThemeWatcher(repaint);
+
+  usePlayheadLoop(audio, container, true);
+
+  useEffect(() => {
+    if (!container) return;
+    const detachSeek = attachSeek(container, audio, {
+      startsPlayback: seekStartsPlayback,
+      onPlayRequest: () => void controls.play(),
+    });
+    const detachHover = attachHover(container, audio);
+    return () => {
+      detachSeek();
+      detachHover();
+    };
+  }, [audio, container, controls, seekStartsPlayback]);
+
+  return (
+    <div
+      ref={setContainer}
+      className="audioplayer-waveform relative w-full select-none cursor-pointer"
+      style={{ height, ['--p' as string]: '0%' }}
+      data-mode="peaks"
+    >
+      <canvas ref={bgCanvasRef} className="absolute inset-0 h-full w-full" aria-hidden="true" />
+      <div
+        className="audioplayer-fg-clip absolute inset-0"
+        style={{
+          clipPath: 'polygon(0 0, var(--p) 0, var(--p) 100%, 0 100%)',
+          willChange: 'clip-path',
+        }}
+      >
+        <canvas ref={fgCanvasRef} className="absolute inset-0 h-full w-full" aria-hidden="true" />
+      </div>
+      <div
+        className="audioplayer-cursor pointer-events-none absolute top-0 bottom-0 w-px"
+        style={{ left: 'var(--p)', backgroundColor: alpha(fgHex, 0.7) }}
+        aria-hidden="true"
+      />
+      <div
+        className="audioplayer-hover pointer-events-none absolute top-0 bottom-0 w-px transition-opacity"
+        style={{
+          left: 'var(--hp, -10px)',
+          opacity: 'var(--ho, 0)',
+          backgroundColor: alpha(mutedHex, 0.5),
+        }}
+        aria-hidden="true"
+      />
+      <div
+        data-audioplayer-time-tip
+        className="audioplayer-tip pointer-events-none absolute -top-7 -translate-x-1/2 rounded bg-foreground px-1.5 py-0.5 text-[10px] tabular-nums text-background transition-opacity"
+        style={{
+          left: 'var(--hp, -100px)',
+          opacity: 'var(--ht, 0)',
+        }}
+        aria-hidden="true"
+      />
+    </div>
+  );
+}

package/src/tools/AudioPlayer/parts/Waveform/ProgressBar.tsx

@@ -0,0 +1,76 @@
+'use client';
+
+// Plain progress bar — no waveform, no animation. Same playhead mechanics as
+// the canvas modes (clip-path via --p, click/drag to seek). Use when you want
+// a track scrubber without amplitude visualisation.
+
+import { useEffect, useState } from 'react';
+import { alpha, useThemeColor } from '@djangocfg/ui-core/styles/palette';
+import { usePlayerAudio, usePlayerControls } from '../../context/selectors';
+import { usePlayheadLoop } from '../../hooks/usePlayheadLoop';
+import { attachHover, attachSeek } from './waveformInteraction';
+
+type Props = { height?: number; seekStartsPlayback?: boolean };
+
+export function ProgressBar({ height = 4, seekStartsPlayback }: Props) {
+  const audio = usePlayerAudio();
+  const controls = usePlayerControls();
+  const [container, setContainer] = useState<HTMLDivElement | null>(null);
+  const fgHex = useThemeColor('primary');
+  const mutedHex = useThemeColor('muted-foreground');
+
+  usePlayheadLoop(audio, container, true);
+
+  useEffect(() => {
+    if (!container) return;
+    const detachSeek = attachSeek(container, audio, {
+      startsPlayback: seekStartsPlayback,
+      onPlayRequest: () => void controls.play(),
+    });
+    const detachHover = attachHover(container, audio);
+    return () => {
+      detachSeek();
+      detachHover();
+    };
+  }, [audio, container, controls, seekStartsPlayback]);
+
+  return (
+    <div
+      ref={setContainer}
+      className="audioplayer-waveform relative w-full select-none cursor-pointer"
+      style={{ ['--p' as string]: '0%' }}
+      data-mode="progress"
+    >
+      <div
+        className="rounded-full"
+        style={{ height, backgroundColor: alpha(mutedHex, 0.25) }}
+      />
+      <div
+        className="absolute inset-y-0 left-0 rounded-full"
+        style={{
+          width: 'var(--p)',
+          backgroundColor: fgHex,
+        }}
+        aria-hidden="true"
+      />
+      <div
+        className="audioplayer-hover pointer-events-none absolute -top-1 -bottom-1 w-px transition-opacity"
+        style={{
+          left: 'var(--hp, -10px)',
+          opacity: 'var(--ho, 0)',
+          backgroundColor: alpha(mutedHex, 0.5),
+        }}
+        aria-hidden="true"
+      />
+      <div
+        data-audioplayer-time-tip
+        className="audioplayer-tip pointer-events-none absolute -top-7 -translate-x-1/2 rounded bg-foreground px-1.5 py-0.5 text-[10px] tabular-nums text-background transition-opacity"
+        style={{
+          left: 'var(--hp, -100px)',
+          opacity: 'var(--ht, 0)',
+        }}
+        aria-hidden="true"
+      />
+    </div>
+  );
+}

package/src/tools/AudioPlayer/parts/Waveform/Waveform.tsx

@@ -0,0 +1,74 @@
+'use client';
+
+import { useRef } from 'react';
+import { usePlayerMeta } from '../../context/selectors';
+import { usePeaks } from '../../hooks/usePeaks';
+import type { WaveformConfig } from '../../types';
+import { BarsWaveform } from './BarsWaveform';
+import { LiveWaveform } from './LiveWaveform';
+import { PeaksWaveform } from './PeaksWaveform';
+import { ProgressBar } from './ProgressBar';
+import { WaveformSkeleton } from './WaveformSkeleton';
+
+type Props = {
+  config?: WaveformConfig;
+  height: number;
+  seekStartsPlayback?: boolean;
+};
+
+export function Waveform({ config, height, seekStartsPlayback }: Props) {
+  const meta = usePlayerMeta();
+  const triggerRef = useRef<HTMLDivElement | null>(null);
+
+  const mode = config?.mode ?? 'peaks';
+  const barWidth = config?.barWidth ?? 2;
+  const barGap = config?.barGap ?? 1;
+
+  const peaksEnabled = mode === 'peaks';
+  const { peaks, loading, error } = usePeaks({
+    src: meta.src,
+    enabled: peaksEnabled,
+    triggerRef,
+    decodeOnMount: config?.decodeOnMount,
+  });
+
+  if (mode === 'none') return null;
+  if (mode === 'progress')
+    return <ProgressBar height={Math.min(height, 6)} seekStartsPlayback={seekStartsPlayback} />;
+  if (mode === 'bars') return <BarsWaveform height={height} barWidth={barWidth} barGap={barGap} />;
+  if (mode === 'live')
+    return (
+      <LiveWaveform
+        height={height}
+        barWidth={barWidth}
+        barGap={barGap}
+        seekStartsPlayback={seekStartsPlayback}
+      />
+    );
+
+  // peaks mode
+  if (loading || (!peaks && !error)) {
+    return (
+      <div ref={triggerRef}>
+        <WaveformSkeleton height={height} />
+      </div>
+    );
+  }
+  if (!peaks) {
+    // Decode failed — degrade to a plain scrubber. Playback works; user can
+    // still seek; we just can't show amplitude. Per ADR-002 we never surface
+    // decode failure as a hard error.
+    return <ProgressBar height={Math.min(height, 6)} seekStartsPlayback={seekStartsPlayback} />;
+  }
+  return (
+    <div ref={triggerRef}>
+      <PeaksWaveform
+        peaks={peaks}
+        height={height}
+        barWidth={barWidth}
+        barGap={barGap}
+        seekStartsPlayback={seekStartsPlayback}
+      />
+    </div>
+  );
+}

package/src/tools/AudioPlayer/parts/Waveform/WaveformSkeleton.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+type Props = { height: number };
+
+export function WaveformSkeleton({ height }: Props) {
+  return (
+    <div
+      className="audioplayer-skeleton relative w-full overflow-hidden"
+      style={{ height }}
+      aria-hidden="true"
+    >
+      <div className="absolute inset-x-0 top-1/2 h-px -translate-y-1/2 bg-muted-foreground/30" />
+      <div className="absolute inset-0 audioplayer-shimmer" />
+    </div>
+  );
+}

package/src/tools/AudioPlayer/parts/Waveform/index.ts

@@ -0,0 +1,8 @@
+export { Waveform } from './Waveform';
+export { PeaksWaveform } from './PeaksWaveform';
+export { LiveWaveform } from './LiveWaveform';
+export { BarsWaveform } from './BarsWaveform';
+export { ProgressBar } from './ProgressBar';
+export { WaveformSkeleton } from './WaveformSkeleton';
+export { paintPeaks, paintLive } from './waveformRenderer';
+export { attachSeek, attachHover } from './waveformInteraction';