@djangocfg/ui-tools 2.1.416 → 2.1.417

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

@@ -1,6 +1,6 @@
 'use client';
 
-import type { ButtonHTMLAttributes, ReactNode } from 'react';
+import { forwardRef, type ButtonHTMLAttributes, type ReactNode } from 'react';
 import {
   Tooltip,
   TooltipContent,
@@ -19,21 +19,20 @@ type Props = {
   noTooltip?: boolean;
 } & Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'aria-label'>;
 
-export function IconButton({
-  label,
-  shortcut,
-  active,
-  children,
-  noTooltip,
-  className = '',
-  ...rest
-}: Props) {
+// `forwardRef` is mandatory: this button is used as `<PopoverTrigger asChild>`
+// in VolumeControl. Without ref forwarding, Radix can't anchor the popper to
+// the trigger, and `<PopoverContent>` renders with zero rect (invisible).
+export const IconButton = forwardRef<HTMLButtonElement, Props>(function IconButton(
+  { label, shortcut, active, children, noTooltip, className = '', ...rest },
+  ref,
+) {
   // 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
+      ref={ref}
       type="button"
       aria-label={label}
       aria-pressed={active}
@@ -59,4 +58,4 @@ export function IconButton({
       </TooltipContent>
     </Tooltip>
   );
-}
+});

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

@@ -1,13 +1,11 @@
 'use client';
 
 import { Volume2, VolumeX } from 'lucide-react';
-import { useEffect, useRef, useState } from 'react';
-import { useMediaQuery } from '@djangocfg/ui-core/hooks';
+import { useEffect, useState } from 'react';
+import { Popover, PopoverContent, PopoverTrigger, Slider } from '@djangocfg/ui-core/components';
 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 {
@@ -19,16 +17,22 @@ function isIosSafari(): boolean {
 }
 const HIDE_VOLUME = isIosSafari();
 
+/**
+ * Volume control — click-to-open Popover with a vertical `<Slider>`.
+ *
+ * Click on the trigger toggles the popover (not mute). Mute lives as a
+ * dedicated icon button inside the popover. This avoids the classic
+ * Radix `<Tooltip>` + `<Popover>` collision on the same trigger:
+ * hovering opened the tooltip, click toggled the popover — but the
+ * tooltip's pointer-events fought the popover's outside-click logic.
+ * One trigger, one job: open the popover; volume + mute live inside.
+ */
 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 = () => {
@@ -39,26 +43,7 @@ export function VolumeControl() {
     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'}
@@ -74,98 +59,50 @@ export function VolumeControl() {
     );
   }
 
-  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();
-        },
-      };
+  const handleChange = (v: number) => {
+    setVolume(v);
+    setVol(v);
+    if (v > 0) setMuted(false);
+  };
 
   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}
+    <Popover open={isOpen} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <IconButton
+          label={isOpen ? 'Close volume' : 'Volume'}
+          // Tooltip while open would race the popover for pointer/focus
+          // — suppress it as soon as the popover opens.
+          noTooltip={isOpen}
+          active={muted}
         >
-          <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>
+          <Icon size={16} strokeWidth={1.75} />
+        </IconButton>
+      </PopoverTrigger>
+      <PopoverContent
+        side="top"
+        align="center"
+        sideOffset={6}
+        className="flex w-14! flex-col items-center gap-2 p-3!"
+        // Keep the focus ring on the trigger; the slider still accepts
+        // keyboard once tabbed into.
+        onOpenAutoFocus={(e) => e.preventDefault()}
+      >
+        <span className="w-full text-center tabular-nums text-[10px] text-muted-foreground">
+          {Math.round((muted ? 0 : volume) * 100)}
+        </span>
+        <Slider
+          orientation="vertical"
+          min={0}
+          max={1}
+          step={0.01}
+          value={[muted ? 0 : volume]}
+          onValueChange={([v]) => handleChange(v)}
+          aria-label="Volume"
+          className="h-32"
+        />
+      </PopoverContent>
+    </Popover>
   );
 }

package/src/tools/media/AudioPlayer/types.ts

@@ -51,6 +51,18 @@ export type PlayerProps = {
 
   ariaLabel?: string;
   enableKeyboardShortcuts?: boolean;
+  /**
+   * Move keyboard focus into the player container on mount. Activates
+   * the hotkey scope (Space=play/pause, ←→=seek, ↑↓=volume, M=mute)
+   * without the user having to click the player first.
+   *
+   * Useful when the player mounts as the result of an explicit user
+   * action — e.g. a file picker selecting an audio file — so keyboard
+   * control is immediately live.
+   *
+   * @default false
+   */
+  autoFocus?: boolean;
 
   // When the user clicks on the waveform while paused, also start playback.
   // Default true — clicking on a time mark almost always means "play here".
@@ -92,4 +104,7 @@ export type PlayerHandle = {
   seek: (seconds: number) => void;
   getCurrentTime: () => number;
   getDuration: () => number;
+  /** Move keyboard focus to the player container so its hotkey scope
+   *  (Space=play/pause, ←→=seek, ↑↓=volume, M=mute) becomes active. */
+  focus: () => void;
 };