@djangocfg/ui-tools 2.1.310 → 2.1.313

package/src/tools/AudioPlayer/lazy.tsx

@@ -1,105 +1,16 @@
 'use client';
 
-/**
- * Lazy-loaded AudioPlayer Components
- *
- * Heavy WaveSurfer.js (~200KB) is loaded only when component is rendered.
- * Use this for automatic code-splitting with Suspense fallback.
- *
- * For direct imports without lazy loading, use:
- * import { HybridAudioPlayer } from '@djangocfg/ui-tools/audio'
- */
+import { createLazyComponent } from '../../components';
+import type { PlayerProps } from './types';
 
-import { createLazyComponent, LoadingFallback } from '../../components';
-import type {
-  HybridAudioPlayerProps,
-  HybridSimplePlayerProps,
-  HybridCompactPlayerProps,
-} from './components';
-
-// ============================================================================
-// Re-export types
-// ============================================================================
-
-export type { HybridAudioPlayerProps, HybridSimplePlayerProps, HybridCompactPlayerProps };
-
-// ============================================================================
-// Audio Loading Fallback
-// ============================================================================
-
-function AudioLoadingFallback() {
-  return (
-    <div className="flex items-center justify-center p-6 bg-muted/30 rounded-lg">
-      <div className="flex flex-col items-center gap-2">
-        <div className="relative">
-          <div className="h-10 w-10 animate-spin rounded-full border-4 border-muted border-t-primary" />
-          <div className="absolute inset-0 flex items-center justify-center">
-            <svg
-              className="h-5 w-5 text-muted-foreground"
-              fill="none"
-              viewBox="0 0 24 24"
-              stroke="currentColor"
-            >
-              <path
-                strokeLinecap="round"
-                strokeLinejoin="round"
-                strokeWidth={2}
-                d="M9 19V6l12-3v13M9 19c0 1.105-1.343 2-3 2s-3-.895-3-2 1.343-2 3-2 3 .895 3 2zm12-3c0 1.105-1.343 2-3 2s-3-.895-3-2 1.343-2 3-2 3 .895 3 2zM9 10l12-3"
-              />
-            </svg>
-          </div>
-        </div>
-        <span className="text-sm text-muted-foreground">Loading audio player...</span>
-      </div>
-    </div>
-  );
-}
-
-// ============================================================================
-// Lazy Components
-// ============================================================================
-
-/**
- * LazyHybridAudioPlayer - Lazy-loaded full-featured audio player
- *
- * Automatically shows loading state while WaveSurfer loads (~200KB)
- */
-export const LazyHybridAudioPlayer = createLazyComponent<HybridAudioPlayerProps>(
-  () => import('./components').then((mod) => ({ default: mod.HybridAudioPlayer })),
-  {
-    displayName: 'LazyHybridAudioPlayer',
-    fallback: <AudioLoadingFallback />,
-  }
-);
-
-/**
- * LazyHybridSimplePlayer - Lazy-loaded simple audio player
- *
- * Automatically shows loading state while WaveSurfer loads (~200KB)
- */
-export const LazyHybridSimplePlayer = createLazyComponent<HybridSimplePlayerProps>(
-  () => import('./components').then((mod) => ({ default: mod.HybridSimplePlayer })),
-  {
-    displayName: 'LazyHybridSimplePlayer',
-    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 })),
+export const LazyPlayer = createLazyComponent<PlayerProps>(
+  () => import('./Player').then((mod) => ({ default: mod.Player })),
   {
-    displayName: 'LazyHybridCompactPlayer',
+    displayName: 'LazyAudioPlayer',
     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 className="rounded-lg border border-border/60 bg-card px-4 py-6 text-sm text-muted-foreground">
+        Loading audio player…
       </div>
     ),
-  }
+  },
 );

package/src/tools/AudioPlayer/parts/Controls/ControlsRow.tsx

@@ -0,0 +1,30 @@
+'use client';
+
+import { TimeDisplay } from '../Meta/TimeDisplay';
+import { LoopButton } from './LoopButton';
+import { PlayButton } from './PlayButton';
+import { SkipButton } from './SkipButton';
+import { VolumeControl } from './VolumeControl';
+
+type Props = {
+  onPrev?: () => void;
+  onNext?: () => void;
+  showTime?: boolean;
+};
+
+export function ControlsRow({ onPrev, onNext, showTime = false }: Props) {
+  return (
+    <div className="flex items-center justify-between gap-3">
+      <div className="flex items-center gap-1">
+        <SkipButton direction="prev" onClick={onPrev} />
+        <PlayButton />
+        <SkipButton direction="next" onClick={onNext} />
+      </div>
+      <div className="flex items-center gap-2">
+        {showTime && <TimeDisplay />}
+        <VolumeControl />
+        <LoopButton />
+      </div>
+    </div>
+  );
+}

package/src/tools/AudioPlayer/parts/Controls/IconButton.tsx

@@ -0,0 +1,62 @@
+'use client';
+
+import type { ButtonHTMLAttributes, ReactNode } from 'react';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@djangocfg/ui-core/components';
+
+type Props = {
+  label: string;
+  // Keyboard shortcut hint shown in the tooltip (e.g. "L" for loop). Optional.
+  shortcut?: string;
+  active?: boolean;
+  children: ReactNode;
+  // Render the button without the tooltip wrapper. Useful for inline contexts
+  // (e.g. inside another tooltip / popover) where nesting Radix portals is
+  // unnecessary.
+  noTooltip?: boolean;
+} & Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'aria-label'>;
+
+export function IconButton({
+  label,
+  shortcut,
+  active,
+  children,
+  noTooltip,
+  className = '',
+  ...rest
+}: Props) {
+  // Active state uses a tinted primary surface — readable, on-brand, not loud.
+  const stateClasses = active
+    ? 'bg-primary/10 text-primary hover:bg-primary/15'
+    : 'text-muted-foreground hover:bg-accent hover:text-foreground';
+  const button = (
+    <button
+      type="button"
+      aria-label={label}
+      aria-pressed={active}
+      className={`audioplayer-press grid h-8 w-8 place-items-center rounded-md transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/60 disabled:opacity-50 disabled:pointer-events-none ${stateClasses} ${className}`}
+      {...rest}
+    >
+      {children}
+    </button>
+  );
+  if (noTooltip) return button;
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>{button}</TooltipTrigger>
+      <TooltipContent side="top">
+        <span className="flex items-center gap-1.5">
+          {label}
+          {shortcut && (
+            <kbd className="rounded border border-border/40 bg-muted px-1 font-mono text-[10px] text-muted-foreground">
+              {shortcut}
+            </kbd>
+          )}
+        </span>
+      </TooltipContent>
+    </Tooltip>
+  );
+}

package/src/tools/AudioPlayer/parts/Controls/LoopButton.tsx

@@ -0,0 +1,33 @@
+'use client';
+
+import { Repeat } from 'lucide-react';
+import { useEffect, useState } from 'react';
+import { usePlayerAudio, usePlayerControls } from '../../context/selectors';
+import { IconButton } from './IconButton';
+
+export function LoopButton() {
+  const audio = usePlayerAudio();
+  const { toggleLoop } = usePlayerControls();
+  const [loop, setLoop] = useState(audio.loop);
+
+  useEffect(() => {
+    // <audio> doesn't fire an event for loop changes, but our toggleLoop sets
+    // the property directly — so we sync via a small mutation observer pattern:
+    // poll on click only by reading audio.loop after toggleLoop runs.
+    setLoop(audio.loop);
+  }, [audio]);
+
+  return (
+    <IconButton
+      label={loop ? 'Disable loop' : 'Enable loop'}
+      shortcut="L"
+      active={loop}
+      onClick={() => {
+        toggleLoop();
+        setLoop(audio.loop);
+      }}
+    >
+      <Repeat size={16} strokeWidth={1.75} />
+    </IconButton>
+  );
+}

package/src/tools/AudioPlayer/parts/Controls/PlayButton.tsx

@@ -0,0 +1,86 @@
+'use client';
+
+import { LoaderCircle, Pause, Play, RotateCcw } from 'lucide-react';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@djangocfg/ui-core/components';
+import { usePlayerControls, usePlayerState } from '../../context/selectors';
+
+type Props = { size?: 'default' | 'compact' };
+
+export function PlayButton({ size = 'default' }: Props) {
+  const state = usePlayerState();
+  const { toggle, play } = usePlayerControls();
+
+  const dim = size === 'compact' ? 28 : 36;
+  const icon = size === 'compact' ? 14 : 16;
+
+  let label = 'Play';
+  let Icon: React.ComponentType<{ size?: number; strokeWidth?: number; className?: string }> = Play;
+  let onClick: () => void = () => void toggle();
+  let disabled = false;
+
+  switch (state.kind) {
+    case 'idle':
+      Icon = Play;
+      disabled = true;
+      break;
+    case 'loading':
+    case 'decoding':
+      Icon = LoaderCircle;
+      label = 'Loading';
+      disabled = true;
+      break;
+    case 'playing':
+      Icon = Pause;
+      label = 'Pause';
+      break;
+    case 'paused':
+      Icon = Play;
+      label = 'Play';
+      break;
+    case 'ended':
+      Icon = RotateCcw;
+      label = 'Replay';
+      onClick = () => void play();
+      break;
+    case 'error':
+      Icon = Play;
+      label = 'Retry';
+      onClick = () => void play();
+      break;
+  }
+
+  const button = (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      aria-label={label}
+      className="audioplayer-press grid place-items-center rounded-full bg-foreground text-background transition-colors hover:bg-foreground/90 disabled:opacity-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/60"
+      style={{ width: dim, height: dim }}
+    >
+      <Icon
+        size={icon}
+        strokeWidth={2}
+        className={state.kind === 'loading' || state.kind === 'decoding' ? 'animate-spin' : ''}
+      />
+    </button>
+  );
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>{button}</TooltipTrigger>
+      <TooltipContent side="top">
+        <span className="flex items-center gap-1.5">
+          {label}
+          <kbd className="rounded border border-border/40 bg-muted px-1 font-mono text-[10px] text-muted-foreground">
+            Space
+          </kbd>
+        </span>
+      </TooltipContent>
+    </Tooltip>
+  );
+}

package/src/tools/AudioPlayer/parts/Controls/SkipButton.tsx

@@ -0,0 +1,17 @@
+'use client';
+
+import { SkipBack, SkipForward } from 'lucide-react';
+import { IconButton } from './IconButton';
+
+type Props = { direction: 'prev' | 'next'; onClick?: () => void };
+
+export function SkipButton({ direction, onClick }: Props) {
+  if (!onClick) return null;
+  const Icon = direction === 'prev' ? SkipBack : SkipForward;
+  const label = direction === 'prev' ? 'Previous track' : 'Next track';
+  return (
+    <IconButton label={label} shortcut={direction === 'prev' ? '←' : '→'} onClick={onClick}>
+      <Icon size={16} strokeWidth={1.75} />
+    </IconButton>
+  );
+}

package/src/tools/AudioPlayer/parts/Controls/VolumeControl.tsx

@@ -0,0 +1,171 @@
+'use client';
+
+import { Volume2, VolumeX } from 'lucide-react';
+import { useEffect, useRef, useState } from 'react';
+import { useMediaQuery } from '@djangocfg/ui-core/hooks';
+import { usePlayerAudio, usePlayerControls } from '../../context/selectors';
+import { IconButton } from './IconButton';
+
+const CLOSE_DELAY_MS = 120;
+
+// `audio.volume` is read-only on iOS Safari (controlled by hardware buttons),
+// so a JS slider does nothing useful there. Detect once at module load.
+function isIosSafari(): boolean {
+  if (typeof navigator === 'undefined') return false;
+  const ua = navigator.userAgent;
+  const iOS = /iPad|iPhone|iPod/.test(ua) ||
+    (navigator.platform === 'MacIntel' && (navigator as { maxTouchPoints?: number }).maxTouchPoints! > 1);
+  return iOS;
+}
+const HIDE_VOLUME = isIosSafari();
+
+export function VolumeControl() {
+  const audio = usePlayerAudio();
+  const { setVolume, toggleMute } = usePlayerControls();
+  const [volume, setVol] = useState(audio.volume);
+  const [muted, setMuted] = useState(audio.muted);
+  const [isOpen, setOpen] = useState(false);
+  const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Touch devices have no hover — open the popover on click instead.
+  const isTouch = useMediaQuery('(hover: none), (pointer: coarse)');
+
+  useEffect(() => {
+    const sync = () => {
+      setVol(audio.volume);
+      setMuted(audio.muted);
+    };
+    audio.addEventListener('volumechange', sync);
+    return () => audio.removeEventListener('volumechange', sync);
+  }, [audio]);
+
+  useEffect(() => {
+    return () => {
+      if (closeTimer.current) clearTimeout(closeTimer.current);
+    };
+  }, []);
+
+  // Close on outside-click in touch mode.
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  useEffect(() => {
+    if (!isOpen || !isTouch) return;
+    const onDown = (e: PointerEvent) => {
+      if (!containerRef.current) return;
+      if (!containerRef.current.contains(e.target as Node)) setOpen(false);
+    };
+    document.addEventListener('pointerdown', onDown);
+    return () => document.removeEventListener('pointerdown', onDown);
+  }, [isOpen, isTouch]);
+
+  if (HIDE_VOLUME) {
+    // iOS Safari can't change volume via JS — keep mute toggle only.
+    return (
+      <IconButton
+        label={muted ? 'Unmute' : 'Mute'}
+        shortcut="M"
+        active={muted}
+        onClick={() => {
+          toggleMute();
+          setMuted(audio.muted);
+        }}
+      >
+        {muted || volume === 0 ? <VolumeX size={16} strokeWidth={1.75} /> : <Volume2 size={16} strokeWidth={1.75} />}
+      </IconButton>
+    );
+  }
+
+  const cancelClose = () => {
+    if (closeTimer.current) {
+      clearTimeout(closeTimer.current);
+      closeTimer.current = null;
+    }
+  };
+  const scheduleClose = () => {
+    cancelClose();
+    closeTimer.current = setTimeout(() => setOpen(false), CLOSE_DELAY_MS);
+  };
+  const open = () => {
+    cancelClose();
+    setOpen(true);
+  };
+
+  const Icon = muted || volume === 0 ? VolumeX : Volume2;
+
+  // Hover bindings only apply on devices with real hover. On touch the popover
+  // is toggled by the icon click.
+  const hoverHandlers = isTouch
+    ? {}
+    : {
+        onPointerEnter: open,
+        onPointerLeave: scheduleClose,
+        onFocusCapture: open,
+        onBlurCapture: (e: React.FocusEvent) => {
+          if (!e.currentTarget.contains(e.relatedTarget as Node | null)) scheduleClose();
+        },
+      };
+
+  return (
+    <div ref={containerRef} className="relative" {...hoverHandlers}>
+      <IconButton
+        label={isOpen ? 'Close volume' : muted ? 'Unmute' : 'Volume'}
+        shortcut={isTouch ? undefined : 'M'}
+        active={muted}
+        // Inside the popover wrapper — disable IconButton's tooltip when the
+        // popover is open (the popover already shows controls; nesting Radix
+        // tooltip+popover content fights for focus/dismiss).
+        noTooltip={isOpen}
+        onClick={() => {
+          if (isTouch) {
+            setOpen((v) => !v);
+            return;
+          }
+          toggleMute();
+          setMuted(audio.muted);
+        }}
+      >
+        <Icon size={16} strokeWidth={1.75} />
+      </IconButton>
+      {isOpen && (
+        <div
+          className="absolute bottom-full left-1/2 z-20 -translate-x-1/2 pb-2"
+          onPointerEnter={isTouch ? undefined : open}
+          onPointerLeave={isTouch ? undefined : scheduleClose}
+        >
+          <div className="flex items-center gap-2 rounded-md border border-border/60 bg-card px-3 py-2 shadow-sm">
+            <input
+              type="range"
+              min={0}
+              max={1}
+              step={0.01}
+              value={muted ? 0 : volume}
+              onChange={(e) => {
+                const v = parseFloat(e.target.value);
+                setVolume(v);
+                setVol(v);
+                if (v > 0) setMuted(false);
+              }}
+              className="h-1 w-32 appearance-none rounded-full bg-muted accent-foreground"
+              aria-label="Volume"
+            />
+            <span className="w-8 tabular-nums text-right text-[10px] text-muted-foreground">
+              {Math.round((muted ? 0 : volume) * 100)}
+            </span>
+            {isTouch && (
+              <button
+                type="button"
+                aria-label={muted ? 'Unmute' : 'Mute'}
+                className="audioplayer-press grid h-7 w-7 place-items-center rounded text-muted-foreground hover:bg-accent"
+                onClick={() => {
+                  toggleMute();
+                  setMuted(audio.muted);
+                }}
+              >
+                {muted ? <VolumeX size={14} strokeWidth={1.75} /> : <Volume2 size={14} strokeWidth={1.75} />}
+              </button>
+            )}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,6 @@
+export { PlayButton } from './PlayButton';
+export { SkipButton } from './SkipButton';
+export { LoopButton } from './LoopButton';
+export { VolumeControl } from './VolumeControl';
+export { ControlsRow } from './ControlsRow';
+export { IconButton } from './IconButton';

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

@@ -0,0 +1,24 @@
+'use client';
+
+import { useState } from 'react';
+import { CoverPlaceholder } from './CoverPlaceholder';
+
+type Props = { src?: string; alt?: string; size: number };
+
+export function Cover({ src, alt, size }: Props) {
+  const [errored, setErrored] = useState(false);
+  if (!src || errored) return <CoverPlaceholder size={size} />;
+  return (
+    <img
+      src={src}
+      alt={alt ?? ''}
+      width={size}
+      height={size}
+      loading="lazy"
+      decoding="async"
+      onError={() => setErrored(true)}
+      className="block rounded-md object-cover"
+      style={{ width: size, height: size }}
+    />
+  );
+}

package/src/tools/AudioPlayer/parts/Cover/CoverPlaceholder.tsx

@@ -0,0 +1,27 @@
+'use client';
+
+import { Music } from 'lucide-react';
+
+type Props = { size: number };
+
+export function CoverPlaceholder({ size }: Props) {
+  const inset = Math.max(4, Math.round(size * 0.14));
+  const iconSize = Math.round(size * 0.4);
+  return (
+    <div
+      className="relative grid place-items-center rounded-md bg-muted"
+      style={{ width: size, height: size }}
+      aria-hidden="true"
+    >
+      <span
+        className="absolute rounded-sm bg-muted-foreground/10"
+        style={{ inset }}
+      />
+      <Music
+        className="relative text-muted-foreground"
+        style={{ width: iconSize, height: iconSize }}
+        strokeWidth={1.5}
+      />
+    </div>
+  );
+}

package/src/tools/AudioPlayer/parts/Cover/ReactivePulse.tsx

@@ -0,0 +1,66 @@
+'use client';
+
+// Optional `subtle` reactive cover. Reads levels from the imperative store,
+// down-mixes to a single envelope, writes a CSS variable that drives a
+// compositor-only scale. No box-shadow, no glow.
+
+import { useEffect, useRef } from 'react';
+import { usePlayerLevels } from '../../context/selectors';
+import type { ReactNode } from 'react';
+
+type Props = { enabled: boolean; children: ReactNode };
+
+const VAR = '--audioplayer-pulse';
+const MAX_SCALE = 0.03;
+const SMOOTH = 0.18;
+
+export function ReactivePulse({ enabled, children }: Props) {
+  const ref = useRef<HTMLDivElement | null>(null);
+  const store = usePlayerLevels();
+
+  useEffect(() => {
+    if (!enabled) {
+      ref.current?.style.setProperty(VAR, '1');
+      return;
+    }
+    const el = ref.current;
+    if (!el) return;
+
+    if (typeof window !== 'undefined' && window.matchMedia?.('(prefers-reduced-motion: reduce)').matches) {
+      el.style.setProperty(VAR, '1');
+      return;
+    }
+
+    let raf = 0;
+    let env = 0;
+    const tick = () => {
+      const buf = store.getCurrent();
+      let energy = 0;
+      const usable = Math.min(buf.length, 32);
+      if (usable > 0) {
+        for (let i = 0; i < usable; i++) energy += buf[i];
+        energy /= usable;
+      }
+      env = env + (energy - env) * SMOOTH;
+      const scale = 1 + Math.min(MAX_SCALE, env * MAX_SCALE * 1.5);
+      el.style.setProperty(VAR, scale.toFixed(4));
+      raf = requestAnimationFrame(tick);
+    };
+    raf = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(raf);
+  }, [enabled, store]);
+
+  return (
+    <div
+      ref={ref}
+      className="audioplayer-pulse"
+      style={{
+        transform: 'scale(var(--audioplayer-pulse, 1))',
+        transformOrigin: 'center',
+        willChange: enabled ? 'transform' : undefined,
+      }}
+    >
+      {children}
+    </div>
+  );
+}

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

@@ -0,0 +1,3 @@
+export { Cover } from './Cover';
+export { CoverPlaceholder } from './CoverPlaceholder';
+export { ReactivePulse } from './ReactivePulse';

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

@@ -0,0 +1,35 @@
+'use client';
+
+import { AlertTriangle, RotateCcw } from 'lucide-react';
+import { usePlayerControls, usePlayerState } from '../../context/selectors';
+
+const REASONS: Record<string, string> = {
+  network: 'Network error while loading audio.',
+  decode: "We can't decode this audio.",
+  unsupported: 'This audio format is not supported.',
+  unknown: 'Audio playback failed.',
+};
+
+export function ErrorState() {
+  const state = usePlayerState();
+  const { play } = usePlayerControls();
+  if (state.kind !== 'error') return null;
+  const message = REASONS[state.reason] ?? REASONS.unknown;
+  return (
+    <div
+      role="alert"
+      className="flex items-center gap-3 rounded-md bg-destructive/10 px-3 py-2 text-xs text-destructive"
+    >
+      <AlertTriangle size={14} strokeWidth={1.75} />
+      <span className="flex-1">{message}</span>
+      <button
+        type="button"
+        onClick={() => void play()}
+        className="audioplayer-press inline-flex items-center gap-1 rounded-md px-2 py-1 text-destructive hover:bg-destructive/15 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-destructive/40"
+      >
+        <RotateCcw size={12} strokeWidth={2} />
+        Retry
+      </button>
+    </div>
+  );
+}