@djangocfg/ui-tools 2.1.416 → 2.1.418

package/src/tools/media/AudioPlayer/PlayerShell.tsx

@@ -4,7 +4,6 @@
 // keyboard shortcuts and MediaSession wiring; renders the picked layout.
 
 import { useCallback, useEffect, useImperativeHandle, useState } from 'react';
-import { TooltipProvider } from '@djangocfg/ui-core/components';
 import { useIsPhone } from '@djangocfg/ui-core/hooks';
 import { usePlayerAudio, usePlayerControls, usePlayerMeta } from './context/selectors';
 import { useElementWidth } from './hooks/useResizeObserver';
@@ -26,6 +25,7 @@ type Props = Pick<
   | 'enableKeyboardShortcuts'
   | 'ariaLabel'
   | 'seekStartsPlayback'
+  | 'autoFocus'
 > & {
   handleRef?: React.Ref<PlayerHandle>;
 };
@@ -40,6 +40,7 @@ export function PlayerShell({
   enableKeyboardShortcuts = true,
   ariaLabel,
   seekStartsPlayback = true,
+  autoFocus = false,
   handleRef,
 }: Props) {
   const [container, setContainer] = useState<HTMLDivElement | null>(null);
@@ -87,8 +88,9 @@ export function PlayerShell({
       seek: (s: number) => controls.seek(s),
       getCurrentTime: () => audio.currentTime,
       getDuration: () => (Number.isFinite(audio.duration) ? audio.duration : 0),
+      focus: () => container?.focus(),
     }),
-    [audio, controls],
+    [audio, controls, container],
   );
 
   // Keyboard shortcuts work only when the container can take focus.
@@ -97,26 +99,31 @@ export function PlayerShell({
     container.setAttribute('tabindex', '0');
   }, [container]);
 
+  // Declarative autoFocus: focus the container once the DOM node is ready.
+  // Parents that want a *fresh* focus per source remount us via `key={src}`.
+  useEffect(() => {
+    if (!autoFocus || !container) return;
+    container.focus({ preventScroll: true });
+  }, [autoFocus, container]);
+
   return (
-    <TooltipProvider delayDuration={400}>
-      <div
-        ref={setRootRef}
-        role="group"
-        aria-label={ariaLabel ?? 'Audio player'}
-        className={`audioplayer @container/player rounded-lg border border-border/60 bg-card text-foreground shadow-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50 ${className}`}
-      >
-        {resolvedVariant === 'compact' ? (
-          <CompactLayout waveform={waveform} seekStartsPlayback={seekStartsPlayback} />
-        ) : (
-          <DefaultLayout
-            waveform={waveform}
-            reactiveCover={reactiveCover}
-            onPrev={onPrev}
-            onNext={onNext}
-            seekStartsPlayback={seekStartsPlayback}
-          />
-        )}
-      </div>
-    </TooltipProvider>
+    <div
+      ref={setRootRef}
+      role="group"
+      aria-label={ariaLabel ?? 'Audio player'}
+      className={`audioplayer @container/player rounded-lg border border-border/60 bg-card text-foreground shadow-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50 ${className}`}
+    >
+      {resolvedVariant === 'compact' ? (
+        <CompactLayout waveform={waveform} seekStartsPlayback={seekStartsPlayback} />
+      ) : (
+        <DefaultLayout
+          waveform={waveform}
+          reactiveCover={reactiveCover}
+          onPrev={onPrev}
+          onNext={onNext}
+          seekStartsPlayback={seekStartsPlayback}
+        />
+      )}
+    </div>
   );
 }

package/src/tools/media/AudioPlayer/lazy.tsx

@@ -3,31 +3,41 @@
 /**
  * `@djangocfg/ui-tools/audio-player` subpath entrypoint.
  *
- * `LazyPlayer` is exported as a direct (synchronous) alias of `Player`. We
- * intentionally avoid `React.lazy` + `import('./Player')` here: under bundlers
- * that pre-bundle subpath entries (Vite optimizeDeps in Next.js/Vite/SB), the
- * dynamic import creates a second chunk that re-instantiates the React
- * Contexts (AudioRefCtx/ControlsCtx/MetaCtx/StateCtx/LevelsCtx). The slot
- * components and selector hooks re-exported below would then read from a
- * different context instance than `<PlayerProvider>` writes to, which made
- * `usePlayerAudio` throw "must be used inside <PlayerProvider>".
+ * We deliberately keep this surface narrow:
  *
- * Heavy audio-decoding work (peaks, AudioContext) already happens lazily at
- * runtime via effects inside `PlayerProvider`/`PlayerShell` — there is no
- * benefit to splitting the React shell behind a second chunk.
+ *   - `Player` / `LazyPlayer` — the only React component you should
+ *     import. Already wraps `<PlayerProvider>` + `<PlayerShell>`.
+ *   - types
+ *   - `PlayerProvider` + selector hooks — for the rare consumer that
+ *     wants to render a fully custom layout. They must own the
+ *     provider themselves.
+ *   - cross-instance store helpers (active player, preferences).
+ *
+ * Slot components (Cover/Title/Waveform/Controls/Layout) and internal
+ * peak-cache helpers are NOT re-exported from this entrypoint. Earlier
+ * versions did re-export them, which produced a second module-graph
+ * entry into the `context/*` files under Vite's `optimizeDeps`
+ * pre-bundling — the slot files import the same selectors as
+ * `PlayerShell`, but via a different URL key, so `<PlayerProvider>`
+ * (one context instance) and `usePlayerAudio` inside a slot read
+ * (another context instance) ended up on different `createContext()`
+ * objects → "usePlayerAudio must be used inside <PlayerProvider>".
+ *
+ * If you need raw slots, import from a deeper path (e.g.
+ * `@djangocfg/ui-tools/src/tools/media/AudioPlayer/parts/Cover`) and
+ * accept that you must own a single `<PlayerProvider>` boundary.
  */
 
 // ============================================================================
-// Player component (synchronous; previously lazy — see note above)
+// Player component (synchronous; previously lazy)
 // ============================================================================
 
 export { Player, Player as LazyPlayer } from './Player';
 
 // ============================================================================
-// Light surface — types, store, context, slot components, hooks
+// Types
 // ============================================================================
 
-// Types
 export type {
   PlayerProps,
   PlayerState,
@@ -41,7 +51,10 @@ export type {
   PlayerErrorReason,
 } from './types';
 
+// ============================================================================
 // Context provider + selector hooks (no UI)
+// ============================================================================
+
 export {
   PlayerProvider,
   usePlayerAudio,
@@ -53,7 +66,10 @@ export {
   usePlayerState,
 } from './context';
 
+// ============================================================================
 // Cross-instance store (active player, preferences)
+// ============================================================================
+
 export {
   setActivePlayer,
   getActivePlayer,
@@ -66,37 +82,9 @@ export {
   type PlayerPreferences,
 } from './store';
 
-// Store-backed hooks
 export {
   useActivePlayer,
   useLastActivePlayer,
   useIsActivePlayer,
 } from './hooks/useActivePlayer';
 export { usePlayerPreferences } from './hooks/usePlayerPreferences';
-
-// Peak cache helpers
-export { clearPeaksCache, setPeaks } from './audio';
-
-// Slot components — presentational, read from PlayerContext. Safe to
-// re-export synchronously: they don't import the heavy Player tree
-// (audio decoding, layouts, shell) — only context selectors and types.
-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';

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

@@ -52,6 +52,11 @@ export type PlayerProps = {
   ariaLabel?: string;
   enableKeyboardShortcuts?: boolean;
 
+  /** Focus the player container on mount so its keyboard scope is active
+   *  immediately. Pair with `key={src}` upstream when the parent wants a
+   *  fresh focus on every source change (file-browser inspector pattern). */
+  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".
   // Set false for embeds where stray clicks shouldn't trigger sound.
@@ -92,4 +97,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;
 };

package/src/tools/media/ImageViewer/components/ImageViewer.tsx

@@ -38,6 +38,7 @@ export function ImageViewer({
   images,
   initialIndex = 0,
   inDialog = false,
+  autoFocus = false,
 }: ImageViewerProps) {
   const t = useAppT();
 
@@ -134,6 +135,13 @@ export function ImageViewer({
     return true;
   }, []);
 
+  // Declarative autoFocus: focus the container once on mount. Pair with
+  // `key={src}` upstream for per-source focus reset.
+  useEffect(() => {
+    if (!autoFocus) return;
+    containerRef.current?.focus({ preventScroll: true });
+  }, [autoFocus]);
+
   // Keyboard: zoom / rotate / pan (only when container focused)
   useEffect(() => {
     const handleKeyDown = (e: KeyboardEvent) => {

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

@@ -43,6 +43,10 @@ export interface ImageViewerProps {
   initialIndex?: number;
   /** Hide expand button when already in dialog */
   inDialog?: boolean;
+  /** Focus the viewer container on mount so its keyboard scope is active
+   *  immediately (zoom/rotate/gallery hotkeys). Pair with `key={src}`
+   *  upstream when the parent wants a fresh focus per source change. */
+  autoFocus?: boolean;
 }
 
 export interface ImageToolbarProps {

package/src/tools/media/VideoPlayer/VideoPlayer.tsx

@@ -12,7 +12,7 @@
  * iframe sources where the embed renders its own UI).
  */
 
-import { useMemo, type CSSProperties } from 'react';
+import { useEffect, useMemo, useRef, type CSSProperties } from 'react';
 import { MediaController } from 'media-chrome/react';
 import { cn } from '@djangocfg/ui-core/lib';
 import './styles/video-player.css';
@@ -42,6 +42,7 @@ export function VideoPlayer({
   aspectRatio = 16 / 9,
   className,
   children,
+  autoFocus = false,
   ...settings
 }: VideoPlayerProps) {
   const normalized = useMemo(
@@ -54,13 +55,31 @@ export function VideoPlayer({
   // control bar to avoid a non-functional UI.
   const showControls = controls && !isIframe;
 
+  // MediaController is a custom element; without `tabindex` it cannot take
+  // focus, so its built-in keyboard shortcuts (space/arrows/f) never fire.
+  // We type the ref through the element interface (HTMLElement methods are
+  // all we use) — media-chrome's full MediaController type pulls private
+  // fields we don't need to see.
+  const controllerRef = useRef<HTMLElement | null>(null);
+  useEffect(() => {
+    if (!autoFocus) return;
+    const el = controllerRef.current;
+    if (!el) return;
+    if (!el.hasAttribute('tabindex')) el.setAttribute('tabindex', '0');
+    el.focus({ preventScroll: true });
+  }, [autoFocus]);
+
   return (
     <MediaController
+      ref={(el) => {
+        controllerRef.current = el as unknown as HTMLElement | null;
+      }}
       // Fade controls + scrim after 2.5s of inactivity while playing;
       // they reappear on mousemove / pause / focus (media-chrome built-in).
       autohide="2.5"
       className={cn(
         'video-player relative block w-full overflow-hidden rounded-lg bg-black',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/50',
         className,
       )}
       style={aspectRatioStyle(aspectRatio)}

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

@@ -79,4 +79,8 @@ export interface VideoPlayerProps extends VideoPlayerSettings {
   readonly className?: string;
   /** Custom children replace the default control bar entirely. */
   readonly children?: ReactNode;
+  /** Focus the player container on mount so media-chrome keyboard shortcuts
+   *  (space=play/pause, f=fullscreen, arrows=seek/volume) are active
+   *  immediately. Pair with `key={src}` upstream for per-source focus reset. */
+  readonly autoFocus?: boolean;
 }