@djangocfg/ui-tools 2.1.418 → 2.1.419

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

@@ -2,12 +2,20 @@
 
 import { MediaPipButton } from 'media-chrome/react';
 import { cn } from '@djangocfg/ui-core/lib';
-import type { ComponentProps } from 'react';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@djangocfg/ui-core/components';
+import type { ComponentProps, ReactNode } from 'react';
 
-export type PipProps = ComponentProps<typeof MediaPipButton>;
+export type PipProps = ComponentProps<typeof MediaPipButton> & {
+  /** Tooltip copy. Defaults to `"Picture in picture"`. Pass `false` to opt out. */
+  readonly label?: ReactNode | false;
+};
 
-export function Pip({ className, ...props }: PipProps) {
-  return (
+export function Pip({ className, label, ...props }: PipProps) {
+  const button = (
     <MediaPipButton
       {...props}
       className={cn(
@@ -16,4 +24,13 @@ export function Pip({ className, ...props }: PipProps) {
       )}
     />
   );
+
+  if (label === false) return button;
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>{button}</TooltipTrigger>
+      <TooltipContent side="top">{label ?? 'Picture in picture'}</TooltipContent>
+    </Tooltip>
+  );
 }

package/src/tools/media/VideoPlayer/parts/play-button.tsx

@@ -2,12 +2,20 @@
 
 import { MediaPlayButton } from 'media-chrome/react';
 import { cn } from '@djangocfg/ui-core/lib';
-import type { ComponentProps } from 'react';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@djangocfg/ui-core/components';
+import type { ComponentProps, ReactNode } from 'react';
 
-export type PlayButtonProps = ComponentProps<typeof MediaPlayButton>;
+export type PlayButtonProps = ComponentProps<typeof MediaPlayButton> & {
+  /** Tooltip copy. Defaults to `"Play / Pause"`. Pass `false` to opt out. */
+  readonly label?: ReactNode | false;
+};
 
-export function PlayButton({ className, ...props }: PlayButtonProps) {
-  return (
+export function PlayButton({ className, label, ...props }: PlayButtonProps) {
+  const button = (
     <MediaPlayButton
       {...props}
       className={cn(
@@ -16,4 +24,13 @@ export function PlayButton({ className, ...props }: PlayButtonProps) {
       )}
     />
   );
+
+  if (label === false) return button;
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>{button}</TooltipTrigger>
+      <TooltipContent side="top">{label ?? 'Play / Pause'}</TooltipContent>
+    </Tooltip>
+  );
 }

package/src/tools/media/VideoPlayer/parts/playback-rate.tsx

@@ -2,7 +2,12 @@
 
 import { MediaPlaybackRateButton } from 'media-chrome/react';
 import { cn } from '@djangocfg/ui-core/lib';
-import type { ComponentProps } from 'react';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@djangocfg/ui-core/components';
+import type { ComponentProps, ReactNode } from 'react';
 
 export type PlaybackRateProps = Omit<
   ComponentProps<typeof MediaPlaybackRateButton>,
@@ -10,13 +15,15 @@ export type PlaybackRateProps = Omit<
 > & {
   /** Space-separated list, e.g. `'0.5 1 1.5 2'`, or an array of numbers. */
   readonly rates?: string | readonly number[];
+  /** Tooltip copy. Defaults to `"Playback speed"`. Pass `false` to opt out. */
+  readonly label?: ReactNode | false;
 };
 
 const DEFAULT_RATES: readonly number[] = [0.5, 0.75, 1, 1.25, 1.5, 1.75, 2];
 
-export function PlaybackRate({ className, rates, ...props }: PlaybackRateProps) {
+export function PlaybackRate({ className, rates, label, ...props }: PlaybackRateProps) {
   const value = rates ?? DEFAULT_RATES;
-  return (
+  const button = (
     <MediaPlaybackRateButton
       {...props}
       // media-chrome's setter accepts `string | ArrayLike<number>` — the
@@ -28,4 +35,13 @@ export function PlaybackRate({ className, rates, ...props }: PlaybackRateProps)
       )}
     />
   );
+
+  if (label === false) return button;
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>{button}</TooltipTrigger>
+      <TooltipContent side="top">{label ?? 'Playback speed'}</TooltipContent>
+    </Tooltip>
+  );
 }

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

@@ -1,32 +1,251 @@
 'use client';
 
-import { MediaMuteButton, MediaVolumeRange } from 'media-chrome/react';
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type ButtonHTMLAttributes,
+  type ReactNode,
+} from 'react';
+import { Volume2, VolumeX, Volume1 } from 'lucide-react';
 import { cn } from '@djangocfg/ui-core/lib';
-import type { ComponentProps } from 'react';
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+  Slider,
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@djangocfg/ui-core/components';
 
 export interface VolumeProps {
   readonly className?: string;
+  /**
+   * Reserved for backwards compatibility. The control is always a single
+   * icon button that opens a popover with a vertical slider on hover/focus,
+   * so this flag is now a no-op. Kept so existing consumers
+   * (`<Volume iconOnly />`) don't break.
+   */
   readonly iconOnly?: boolean;
-  readonly muteProps?: ComponentProps<typeof MediaMuteButton>;
-  readonly rangeProps?: ComponentProps<typeof MediaVolumeRange>;
+  /** Mute-button tooltip copy. Defaults to `"Volume"`. Pass `false` to opt out. */
+  readonly muteLabel?: ReactNode | false;
 }
 
-export function Volume({ className, iconOnly, muteProps, rangeProps }: VolumeProps) {
+// Hide the popover slider on iOS Safari — `video.volume` is read-only
+// there (controlled by hardware buttons), so a JS slider does nothing.
+// The trigger still toggles mute, which iOS *does* honour.
+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;
+}
+
+// media-chrome request event names. Dispatched on any descendant of
+// `<media-controller>`; the controller catches them and updates its
+// internal store, which then propagates state back via attributes.
+const MEDIA_VOLUME_REQUEST = 'mediavolumerequest';
+const MEDIA_MUTE_REQUEST = 'mediamuterequest';
+const MEDIA_UNMUTE_REQUEST = 'mediaunmuterequest';
+
+/**
+ * Click-style trigger that visually matches the rest of the VideoPlayer
+ * control bar. Mirrors `.video-player__control` styling from
+ * `styles/video-player.css` so it slots in next to `<MediaPlayButton>` &
+ * friends without standing out.
+ */
+const TriggerButton = forwardRef<
+  HTMLButtonElement,
+  ButtonHTMLAttributes<HTMLButtonElement>
+>(function TriggerButton({ className, children, ...rest }, ref) {
   return (
-    <div className={cn('flex items-center', className)}>
-      <MediaMuteButton
-        {...muteProps}
-        className={cn(
-          'media-control-square video-player__control h-8 w-8',
-          muteProps?.className,
-        )}
-      />
-      {!iconOnly && (
-        <MediaVolumeRange
-          {...rangeProps}
-          className={cn('h-8 w-20', rangeProps?.className)}
-        />
+    <button
+      ref={ref}
+      type="button"
+      className={cn(
+        'video-player__control',
+        'grid h-8 w-8 place-items-center rounded-md',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/60',
+        className,
       )}
+      {...rest}
+    >
+      {children}
+    </button>
+  );
+});
+
+/**
+ * VideoPlayer volume control.
+ *
+ * - **Click** the trigger → mute / unmute toggle (dispatches a
+ *   `mediamuterequest` / `mediaunmuterequest` so media-chrome's store
+ *   stays the single source of truth — no parallel state machine).
+ * - **Hover / keyboard focus** → opens a popover containing a vertical
+ *   `<Slider>` (0..100). Drag = volume change via `mediavolumerequest`.
+ * - Icon reflects level (mute / low / high) and mirrors `media.muted`.
+ *
+ * State is read directly off the underlying `HTMLMediaElement` (located
+ * via the closest `<media-controller>`'s `.media` accessor); we never
+ * shadow media-chrome's store.
+ */
+export function Volume({ className, muteLabel }: VolumeProps) {
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
+  const [volume, setVolume] = useState(1);
+  const [muted, setMuted] = useState(false);
+  const [open, setOpen] = useState(false);
+  const [iosSafari] = useState(isIosSafari);
+
+  // Resolve & track the underlying HTMLMediaElement so we can read live
+  // volume / muted. media-chrome fires `mediaelementchange` on the
+  // controller whenever the slotted media element swaps (e.g. source
+  // change), so we re-bind listeners on each swap.
+  useEffect(() => {
+    const trigger = triggerRef.current;
+    if (!trigger) return;
+    const controller = trigger.closest('media-controller') as
+      | (HTMLElement & { media?: HTMLMediaElement | null })
+      | null;
+    if (!controller) return;
+
+    let media: HTMLMediaElement | null = controller.media ?? null;
+    const sync = () => {
+      if (!media) return;
+      setVolume(media.volume);
+      setMuted(media.muted);
+    };
+    const bind = (el: HTMLMediaElement | null) => {
+      if (!el) return;
+      el.addEventListener('volumechange', sync);
+      sync();
+    };
+    const unbind = (el: HTMLMediaElement | null) => {
+      if (!el) return;
+      el.removeEventListener('volumechange', sync);
+    };
+
+    bind(media);
+
+    const onMediaChange = (e: Event) => {
+      unbind(media);
+      const detail = (e as CustomEvent).detail as HTMLMediaElement | null;
+      media = detail ?? controller.media ?? null;
+      bind(media);
+    };
+    controller.addEventListener('mediaelementchange', onMediaChange);
+
+    return () => {
+      unbind(media);
+      controller.removeEventListener('mediaelementchange', onMediaChange);
+    };
+  }, []);
+
+  const dispatch = useCallback((name: string, detail?: number) => {
+    const trigger = triggerRef.current;
+    if (!trigger) return;
+    trigger.dispatchEvent(
+      new CustomEvent(name, { detail, bubbles: true, composed: true }),
+    );
+  }, []);
+
+  const toggleMute = useCallback(() => {
+    dispatch(muted ? MEDIA_UNMUTE_REQUEST : MEDIA_MUTE_REQUEST);
+  }, [dispatch, muted]);
+
+  const onSlider = useCallback(
+    (value: number) => {
+      dispatch(MEDIA_VOLUME_REQUEST, value);
+      // If the user nudges the slider above zero, treat that as an
+      // implicit unmute — matches what the native HTML5 volume slider does.
+      if (value > 0 && muted) dispatch(MEDIA_UNMUTE_REQUEST);
+    },
+    [dispatch, muted],
+  );
+
+  const effectiveVolume = muted ? 0 : volume;
+  const Icon =
+    muted || volume === 0 ? VolumeX : volume < 0.5 ? Volume1 : Volume2;
+
+  const trigger = (
+    <TriggerButton
+      ref={triggerRef}
+      aria-label={muted ? 'Unmute' : 'Mute'}
+      aria-pressed={muted}
+      onClick={toggleMute}
+    >
+      <Icon className="h-4 w-4" strokeWidth={1.75} />
+    </TriggerButton>
+  );
+
+  // On iOS Safari volume is hardware-only — skip the popover entirely
+  // and let the trigger work as a plain mute/unmute button.
+  if (iosSafari) {
+    if (muteLabel === false) return <div className={cn('flex', className)}>{trigger}</div>;
+    return (
+      <div className={cn('flex items-center', className)}>
+        <Tooltip>
+          <TooltipTrigger asChild>{trigger}</TooltipTrigger>
+          <TooltipContent side="top">{muteLabel ?? 'Mute / unmute'}</TooltipContent>
+        </Tooltip>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className={cn('flex items-center', className)}
+      // Hover-driven open: opening on pointerenter of the wrapper (not
+      // just the button) gives the user a forgiving hit-area when their
+      // cursor drifts between trigger and popover. The popover itself
+      // also catches pointerenter via Radix portal — so once it's open,
+      // moving into it keeps it open.
+      onPointerEnter={() => setOpen(true)}
+      onPointerLeave={() => setOpen(false)}
+      onFocus={() => setOpen(true)}
+      onBlur={(e) => {
+        // Don't close when focus moves between the trigger and the
+        // popover content (both live in this wrapper / its portal).
+        if (!e.currentTarget.contains(e.relatedTarget as Node | null)) {
+          setOpen(false);
+        }
+      }}
+    >
+      <Popover open={open} onOpenChange={setOpen}>
+        <PopoverTrigger asChild>{trigger}</PopoverTrigger>
+        <PopoverContent
+          side="top"
+          align="center"
+          sideOffset={8}
+          // Keep focus on the trigger so click-to-mute still works while
+          // the popover is visible; the slider remains keyboard-reachable
+          // via Tab once a user explicitly tabs into it.
+          onOpenAutoFocus={(e) => e.preventDefault()}
+          onCloseAutoFocus={(e) => e.preventDefault()}
+          onPointerEnter={() => setOpen(true)}
+          onPointerLeave={() => setOpen(false)}
+          className="flex w-12 flex-col items-center gap-2 p-3"
+        >
+          <span className="w-full text-center text-[10px] tabular-nums text-muted-foreground">
+            {Math.round(effectiveVolume * 100)}
+          </span>
+          <Slider
+            orientation="vertical"
+            min={0}
+            max={1}
+            step={0.01}
+            value={[effectiveVolume]}
+            onValueChange={([v]) => onSlider(v)}
+            aria-label="Volume"
+            className="h-24"
+          />
+        </PopoverContent>
+      </Popover>
     </div>
   );
 }

package/src/tools/media/VideoPlayer/styles/video-player.css

@@ -42,11 +42,6 @@ media-controller {
   --media-range-thumb-opacity: 0;
   --media-range-thumb-transition: opacity 0.15s ease;
 
-  /* Tooltip */
-  --media-tooltip-background: var(--popover);
-  --media-tooltip-color: var(--popover-foreground);
-  --media-tooltip-border-radius: 6px;
-
   /* Font */
   --media-font-family: inherit;
   --media-font-size: 12px;
@@ -87,6 +82,29 @@ media-control-bar {
   background: transparent;
 }
 
+/*
+ * Suppress media-chrome's built-in tooltips. They are sticky elements
+ * slotted under each control button's shadow root (exposed via
+ * `part="tooltip"`) and paint a permanent "Play" / "Mute" / "Enter
+ * fullscreen" label below the bar. We wrap each control with our own
+ * Radix-backed <Tooltip> from @djangocfg/ui-core, which fires only on
+ * hover/focus and matches the rest of the platform. Reach into the
+ * shadow DOM via ::part(tooltip) — a global `media-tooltip` selector
+ * cannot pierce the boundary.
+ */
+media-play-button::part(tooltip),
+media-mute-button::part(tooltip),
+media-fullscreen-button::part(tooltip),
+media-pip-button::part(tooltip),
+media-playback-rate-button::part(tooltip),
+media-captions-button::part(tooltip),
+media-airplay-button::part(tooltip),
+media-cast-button::part(tooltip),
+media-seek-forward-button::part(tooltip),
+media-seek-backward-button::part(tooltip) {
+  display: none !important;
+}
+
 /*
  * Auto-hide. media-chrome flags inactivity by setting `userinactive` on
  * the <media-controller>; it only does so while playback is running, and
@@ -120,17 +138,79 @@ media-time-range {
   --media-preview-background: var(--popover);
   --media-preview-border-radius: 6px;
   --media-text-color: var(--popover-foreground);
+
+  /* Kill media-chrome's default blue focus rectangle on the range track.
+     media-chrome paints a `box-shadow: inset 0 0 0 2px rgb(27 127 204 / .9)`
+     via `--media-focus-box-shadow` whenever the inner `<input type=range>`
+     matches `:focus-visible`, which wraps the entire seek-bar in a big
+     blue rectangle on click/Tab. We opt out of the track-wide ring and
+     surface focus on the thumb instead (see :focus-visible below). */
+  --media-focus-box-shadow: none;
 }
 
-/* Reveal the accent thumb only while hovering / scrubbing the rail. */
-media-time-range:hover {
+/* Reveal the accent thumb only while hovering / scrubbing the rail, OR
+   when the rail is keyboard-focused so a11y keyboard users still see
+   where focus lives. */
+media-time-range:hover,
+media-time-range:focus-within {
   --media-range-thumb-opacity: 1;
 }
 
+/* Keyboard focus indicator: a ring around the thumb (not the track).
+   Uses the platform `--ring` semantic token so it matches every other
+   focusable surface. */
+media-time-range:focus-within {
+  --media-range-thumb-box-shadow: 0 0 0 2px var(--ring);
+}
+
 media-time-range::part(preview-box) {
   display: none;
 }
 
+/*
+ * YouTube iframe bleed-through suppression.
+ *
+ * YouTube's IFrame embed ToS requires showing some chrome that cannot be
+ * hidden via player params: the title bar at the top, the large pause
+ * button on the pause screen, and the bottom branding/share tray on
+ * hover/pause. We can't remove them, but we CAN make them non-interactive
+ * — so the user never triggers YouTube's hover-state, never gets a
+ * "More videos" overlay, and clicks never reach the YT iframe.
+ *
+ * The <youtube-video> custom element renders an inner <iframe>; disable
+ * pointer events on it (and on the wrapper itself, just in case the
+ * element later swaps layout). The companion `.vp-yt-click-shield` div
+ * inside <media-controller> absorbs clicks and converts them into
+ * media-chrome play/pause requests — so click-to-toggle still works.
+ *
+ * Our control bar lives above the shield and re-enables pointer events
+ * for the slot, so the controls stay clickable.
+ */
+youtube-video,
+youtube-video iframe {
+  pointer-events: none;
+}
+
+.vp-yt-click-shield {
+  position: absolute;
+  inset: 0;
+  cursor: pointer;
+  background: transparent;
+  pointer-events: auto;
+  /* Sit above the iframe but below the slotted control bar. */
+  z-index: 1;
+}
+
+/* media-chrome slots its control surfaces directly under
+   <media-controller>; raise them above the click-shield and restore
+   pointer events so buttons remain interactive. */
+media-controller > media-control-bar,
+media-controller > [slot='centered-chrome'],
+media-controller > [slot='top-chrome'] {
+  z-index: 2;
+  pointer-events: auto;
+}
+
 media-time-range::part(current-box) {
   padding: 2px 6px;
   border-radius: 6px;

package/src/tools/overlay/ResponsiveDialog/lazy.tsx

@@ -10,7 +10,7 @@
  * import { LazyResponsiveDialog, LazyResponsiveDialogContent } from '@djangocfg/ui-tools/responsive-dialog';
  */
 
-import { createLazyComponent, LoadingFallback } from '../../../components/lazy-wrapper';
+import { createLazyComponent, LoadingFallback } from '../../../common/lazy-wrapper';
 import type {
   ResponsiveDialogProps,
   ResponsiveDialogContentProps,

package/src/tools/overlay/ScrollSpy/lazy.tsx

@@ -4,7 +4,7 @@
  * Lazy-loaded ScrollSpy Component
  */
 
-import { createLazyComponent, LoadingFallback } from '../../../components/lazy-wrapper';
+import { createLazyComponent, LoadingFallback } from '../../../common/lazy-wrapper';
 import type {
   ScrollSpyProps,
   ScrollSpyNavProps,

package/src/tools/overlay/SelectionToolbar/lazy.tsx

@@ -4,7 +4,7 @@
  * Lazy-loaded SelectionToolbar Component
  */
 
-import { createLazyComponent, LoadingFallback } from '../../../components/lazy-wrapper';
+import { createLazyComponent, LoadingFallback } from '../../../common/lazy-wrapper';
 import type {
   SelectionToolbarProps,
   SelectionToolbarContentProps,

package/src/tools/overlay/Tour/lazy.tsx

@@ -4,7 +4,7 @@
  * Lazy-loaded Tour Component
  */
 
-import { createLazyComponent, LoadingFallback } from '../../../components/lazy-wrapper';
+import { createLazyComponent, LoadingFallback } from '../../../common/lazy-wrapper';
 import type {
   TourProps,
   TourPopoverProps,

package/src/tools/visual/Marquee/lazy.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { createLazyComponent } from '../../../components/lazy-wrapper';
+import { createLazyComponent } from '../../../common/lazy-wrapper';
 import type { MarqueeProps } from './types';
 
 export const LazyMarquee = createLazyComponent<MarqueeProps>(

package/src/tools/visual/QRCode/lazy.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { createLazyComponent } from '../../../components/lazy-wrapper';
+import { createLazyComponent } from '../../../common/lazy-wrapper';
 import type { QRCodeProps } from './types';
 
 export const LazyQRCode = createLazyComponent<QRCodeProps>(