@djangocfg/ui-tools 2.1.417 → 2.1.419

package/src/tools/input/SpeechRecognition/widgets/VoiceComposerSlot.tsx

@@ -6,6 +6,7 @@ import { AlertCircle, Loader2, Mic } from 'lucide-react';
 
 import { useCountdownFromSeconds, useNotificationSounds } from '@djangocfg/ui-core/hooks';
 import { cn } from '@djangocfg/ui-core/lib';
+import { Tooltip, TooltipContent, TooltipTrigger } from '@djangocfg/ui-core/components';
 import { useActiveComposer } from '@djangocfg/ui-tools/composer-registry';
 import { useSpeechRecognition } from '../hooks/useSpeechRecognition';
 import { useVoiceSupport } from '../hooks/useVoiceSupport';
@@ -364,44 +365,48 @@ export function VoiceComposerSlot({
           Failed
         </span>
       ) : null}
-      <button
-        type="button"
-        onClick={toggle}
-        aria-pressed={slotState === 'listening'}
-        aria-label={ariaLabel}
-        title={tooltip}
-        data-state={slotState}
-        className={cn(
-          'relative inline-flex items-center justify-center rounded-full transition-all duration-200',
-          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
-          SIZE_CLS[size],
-          slotState === 'listening' &&
-            'bg-destructive text-destructive-foreground hover:bg-destructive/90',
-          slotState === 'processing' &&
-            'bg-primary/10 text-primary hover:bg-primary/15',
-          slotState === 'error' &&
-            'bg-destructive/10 text-destructive hover:bg-destructive/15',
-          slotState === 'idle' &&
-            'text-muted-foreground hover:bg-muted hover:text-foreground',
-          className,
-        )}
-      >
-        {/* Recording feedback — pulsing circle overlay driven by the
-            live mic level. Hidden in every non-listening state. */}
-        <RecordingPulse active={slotState === 'listening'} level={rec.level} />
-        {slotState === 'processing' ? (
-          <Loader2 className="animate-spin" />
-        ) : slotState === 'error' ? (
-          <AlertCircle />
-        ) : (
-          <Mic
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <button
+            type="button"
+            onClick={toggle}
+            aria-pressed={slotState === 'listening'}
+            aria-label={ariaLabel}
+            data-state={slotState}
             className={cn(
-              'transition-transform duration-200',
-              slotState === 'listening' && 'scale-110',
+              'relative inline-flex items-center justify-center rounded-full transition-all duration-200',
+              'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+              SIZE_CLS[size],
+              slotState === 'listening' &&
+                'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+              slotState === 'processing' &&
+                'bg-primary/10 text-primary hover:bg-primary/15',
+              slotState === 'error' &&
+                'bg-destructive/10 text-destructive hover:bg-destructive/15',
+              slotState === 'idle' &&
+                'text-muted-foreground hover:bg-muted hover:text-foreground',
+              className,
             )}
-          />
-        )}
-      </button>
+          >
+            {/* Recording feedback — pulsing circle overlay driven by the
+                live mic level. Hidden in every non-listening state. */}
+            <RecordingPulse active={slotState === 'listening'} level={rec.level} />
+            {slotState === 'processing' ? (
+              <Loader2 className="animate-spin" />
+            ) : slotState === 'error' ? (
+              <AlertCircle />
+            ) : (
+              <Mic
+                className={cn(
+                  'transition-transform duration-200',
+                  slotState === 'listening' && 'scale-110',
+                )}
+              />
+            )}
+          </button>
+        </TooltipTrigger>
+        <TooltipContent side="top">{tooltip}</TooltipContent>
+      </Tooltip>
     </span>
   );
 }

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

@@ -99,19 +99,11 @@ export function PlayerShell({
     container.setAttribute('tabindex', '0');
   }, [container]);
 
-  // `autoFocus` opts the player into pulling keyboard focus on mount
-  // (and whenever the container ref is established). Once focused,
-  // the hotkey scope (Space=play/pause, ←→=seek, ↑↓=volume, M=mute)
-  // is immediately live.
-  //
-  // Deferred via a 0-timeout so the tree row's native focus event
-  // (fired by the click that triggered the mount) lands first; we
-  // then steal focus here. rAF was racy — the row's focus event can
-  // fire AFTER the next animation frame.
+  // 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;
-    const id = setTimeout(() => container.focus(), 0);
-    return () => clearTimeout(id);
+    container.focus({ preventScroll: true });
   }, [autoFocus, container]);
 
   return (

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

@@ -51,17 +51,10 @@ 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
-   */
+
+  /** 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.

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

@@ -4,10 +4,18 @@
  * ImageToolbar - Floating toolbar for image controls
  */
 
-import { useMemo } from 'react';
+import { useMemo, type ReactNode } from 'react';
 import { ZoomIn, ZoomOut, RotateCw, FlipHorizontal, FlipVertical, Maximize2, Expand } from 'lucide-react';
 import { useControls } from 'react-zoom-pan-pinch';
-import { DropdownMenu, DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from '@djangocfg/ui-core/components';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@djangocfg/ui-core/components';
 import { useAppT } from '@djangocfg/i18n';
 import { cn } from '@djangocfg/ui-core/lib';
 import { ZOOM_PRESETS } from '../utils';
@@ -29,6 +37,36 @@ const TB_BUTTON =
   'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-white/70 ' +
   'disabled:opacity-40 disabled:pointer-events-none';
 
+// Small helper so each icon button shares the same Tooltip wrapper +
+// accessibility shape (visible tooltip on hover/focus, aria-label for AT).
+function TbIconButton({
+  label,
+  onClick,
+  className,
+  children,
+}: {
+  label: string;
+  onClick: () => void;
+  className?: string;
+  children: ReactNode;
+}) {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <button
+          type="button"
+          aria-label={label}
+          onClick={onClick}
+          className={cn(TB_BUTTON, 'h-7 w-7', className)}
+        >
+          {children}
+        </button>
+      </TooltipTrigger>
+      <TooltipContent side="top">{label}</TooltipContent>
+    </Tooltip>
+  );
+}
+
 export function ImageToolbar({
   scale,
   transform,
@@ -59,14 +97,9 @@ export function ImageToolbar({
   return (
     <div className="absolute bottom-4 left-1/2 -translate-x-1/2 z-10 flex items-center gap-0.5 bg-black/60 backdrop-blur-sm border border-white/10 rounded-lg p-1 shadow-lg">
       {/* Zoom controls */}
-      <button
-        type="button"
-        className={cn(TB_BUTTON, 'h-7 w-7')}
-        onClick={() => zoomOut()}
-        title={labels.zoomOut}
-      >
+      <TbIconButton label={labels.zoomOut} onClick={() => zoomOut()}>
         <ZoomOut className="h-3.5 w-3.5" />
-      </button>
+      </TbIconButton>
 
       <DropdownMenu>
         <DropdownMenuTrigger asChild>
@@ -90,56 +123,39 @@ export function ImageToolbar({
         </DropdownMenuContent>
       </DropdownMenu>
 
-      <button
-        type="button"
-        className={cn(TB_BUTTON, 'h-7 w-7')}
-        onClick={() => zoomIn()}
-        title={labels.zoomIn}
-      >
+      <TbIconButton label={labels.zoomIn} onClick={() => zoomIn()}>
         <ZoomIn className="h-3.5 w-3.5" />
-      </button>
+      </TbIconButton>
 
       <div className="w-px h-4 bg-white/20 mx-1" />
 
       {/* Fit to view */}
-      <button
-        type="button"
-        className={cn(TB_BUTTON, 'h-7 w-7')}
-        onClick={() => resetTransform()}
-        title={labels.fitToView}
-      >
+      <TbIconButton label={labels.fitToView} onClick={() => resetTransform()}>
         <Maximize2 className="h-3.5 w-3.5" />
-      </button>
+      </TbIconButton>
 
       <div className="w-px h-4 bg-white/20 mx-1" />
 
       {/* Transform controls */}
-      <button
-        type="button"
-        className={cn(TB_BUTTON, 'h-7 w-7', transform.flipH && 'bg-white/20 text-white')}
+      <TbIconButton
+        label={labels.flipHorizontal}
         onClick={onFlipH}
-        title={labels.flipHorizontal}
+        className={transform.flipH ? 'bg-white/20 text-white' : undefined}
       >
         <FlipHorizontal className="h-3.5 w-3.5" />
-      </button>
+      </TbIconButton>
 
-      <button
-        type="button"
-        className={cn(TB_BUTTON, 'h-7 w-7', transform.flipV && 'bg-white/20 text-white')}
+      <TbIconButton
+        label={labels.flipVertical}
         onClick={onFlipV}
-        title={labels.flipVertical}
+        className={transform.flipV ? 'bg-white/20 text-white' : undefined}
       >
         <FlipVertical className="h-3.5 w-3.5" />
-      </button>
+      </TbIconButton>
 
-      <button
-        type="button"
-        className={cn(TB_BUTTON, 'h-7 w-7')}
-        onClick={onRotate}
-        title={labels.rotate}
-      >
+      <TbIconButton label={labels.rotate} onClick={onRotate}>
         <RotateCw className="h-3.5 w-3.5" />
-      </button>
+      </TbIconButton>
 
       {transform.rotation !== 0 && (
         <span className="text-[10px] text-white/60 font-mono pl-1">
@@ -150,14 +166,9 @@ export function ImageToolbar({
       {onExpand && (
         <>
           <div className="w-px h-4 bg-white/20 mx-1" />
-          <button
-            type="button"
-            className={cn(TB_BUTTON, 'h-7 w-7')}
-            onClick={onExpand}
-            title={labels.fullscreen}
-          >
+          <TbIconButton label={labels.fullscreen} onClick={onExpand}>
             <Expand className="h-3.5 w-3.5" />
-          </button>
+          </TbIconButton>
         </>
       )}
     </div>

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

@@ -20,7 +20,7 @@ import {
   TransformComponent,
   type ReactZoomPanPinchRef,
 } from 'react-zoom-pan-pinch';
-import { cn, Dialog, DialogContent, DialogTitle, Alert, AlertDescription } from '@djangocfg/ui-core';
+import { cn, Dialog, DialogContent, DialogTitle, Alert, AlertDescription, Tooltip, TooltipContent, TooltipTrigger } from '@djangocfg/ui-core';
 import { useAppT } from '@djangocfg/i18n';
 import { useHotkey } from '@djangocfg/ui-core/hooks';
 
@@ -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) => {
@@ -305,24 +313,32 @@ export function ImageViewer({
       {/* Gallery navigation */}
       {hasMultiple && (
         <>
-          <button
-            type="button"
-            onClick={prev}
-            aria-label={labels.prev}
-            title={labels.prev}
-            className="absolute left-2 top-1/2 -translate-y-1/2 z-10 bg-black/50 hover:bg-black/70 text-white rounded-full p-1.5 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-white"
-          >
-            <ChevronLeft className="h-5 w-5" />
-          </button>
-          <button
-            type="button"
-            onClick={next}
-            aria-label={labels.next}
-            title={labels.next}
-            className="absolute right-2 top-1/2 -translate-y-1/2 z-10 bg-black/50 hover:bg-black/70 text-white rounded-full p-1.5 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-white"
-          >
-            <ChevronRight className="h-5 w-5" />
-          </button>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <button
+                type="button"
+                onClick={prev}
+                aria-label={labels.prev}
+                className="absolute left-2 top-1/2 -translate-y-1/2 z-10 bg-black/50 hover:bg-black/70 text-white rounded-full p-1.5 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-white"
+              >
+                <ChevronLeft className="h-5 w-5" />
+              </button>
+            </TooltipTrigger>
+            <TooltipContent side="right">{labels.prev}</TooltipContent>
+          </Tooltip>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <button
+                type="button"
+                onClick={next}
+                aria-label={labels.next}
+                className="absolute right-2 top-1/2 -translate-y-1/2 z-10 bg-black/50 hover:bg-black/70 text-white rounded-full p-1.5 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-white"
+              >
+                <ChevronRight className="h-5 w-5" />
+              </button>
+            </TooltipTrigger>
+            <TooltipContent side="left">{labels.next}</TooltipContent>
+          </Tooltip>
           <div className="absolute top-3 left-1/2 -translate-x-1/2 z-10 bg-black/60 backdrop-blur-sm border border-white/10 text-white/80 text-xs font-mono px-2 py-0.5 rounded-full pointer-events-none">
             {currentIndex + 1} / {images.length}
           </div>

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

@@ -10,7 +10,7 @@
  * import { ImageViewer } from '@djangocfg/ui-tools/image-viewer'
  */
 
-import { createLazyComponent, LoadingFallback } from '../../../components';
+import { createLazyComponent, LoadingFallback } from '../../../common';
 import type { ImageViewerProps } from './types';
 
 // ============================================================================

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/LottiePlayer/lazy.tsx

@@ -10,7 +10,7 @@
  * import { LottiePlayer } from '@djangocfg/ui-tools/lottie'
  */
 
-import { createLazyComponent } from '../../../components';
+import { createLazyComponent } from '../../../common';
 import type { LottiePlayerProps } from './types';
 
 // ============================================================================

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 { useCallback, 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(
@@ -50,22 +51,67 @@ export function VideoPlayer({
   );
 
   const isIframe = normalized.type === 'iframe';
+  const isYouTube = normalized.type === 'youtube';
   // For iframe embeds media-chrome cannot drive the inner player — hide the
   // 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);
+
+  // Click-to-play overlay for YouTube — the underlying YT iframe is made
+  // `pointer-events: none` via CSS to suppress YouTube's own hover-state /
+  // UI (title bar, pause-screen, branding tray; ToS forbids hiding them,
+  // but we can make them inert). This overlay restores click-to-toggle
+  // by dispatching media-chrome request events the controller listens for.
+  const onYouTubeShieldClick = useCallback(() => {
+    const el = controllerRef.current;
+    if (!el) return;
+    const paused = el.hasAttribute('mediapaused');
+    const eventName = paused ? 'mediaplayrequest' : 'mediapauserequest';
+    el.dispatchEvent(new CustomEvent(eventName, { bubbles: true, composed: true }));
+  }, []);
+
+  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)}
     >
       <CanvasDispatcher source={normalized} {...settings} />
+      {isYouTube && (
+        // Transparent click-shield over the YT iframe. The iframe itself
+        // is pointer-events:none (see video-player.css); this div absorbs
+        // pointer events and forwards a play/pause request to media-chrome,
+        // so users still get click-to-toggle without ever interacting with
+        // YouTube's own UI.
+        <div
+          className="vp-yt-click-shield"
+          onClick={onYouTubeShieldClick}
+          aria-hidden="true"
+        />
+      )}
       {children ??
         (showControls && (
           <ControlsBar>

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

@@ -2,12 +2,20 @@
 
 import { MediaFullscreenButton } 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 FullscreenProps = ComponentProps<typeof MediaFullscreenButton>;
+export type FullscreenProps = ComponentProps<typeof MediaFullscreenButton> & {
+  /** Tooltip copy. Defaults to `"Fullscreen"`. Pass `false` to opt out. */
+  readonly label?: ReactNode | false;
+};
 
-export function Fullscreen({ className, ...props }: FullscreenProps) {
-  return (
+export function Fullscreen({ className, label, ...props }: FullscreenProps) {
+  const button = (
     <MediaFullscreenButton
       {...props}
       className={cn(
@@ -16,4 +24,13 @@ export function Fullscreen({ className, ...props }: FullscreenProps) {
       )}
     />
   );
+
+  if (label === false) return button;
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>{button}</TooltipTrigger>
+      <TooltipContent side="top">{label ?? 'Fullscreen'}</TooltipContent>
+    </Tooltip>
+  );
 }

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>
+  );
 }