feat: add playback rate menu

Author: sampotts

internal/design/ui/menus.md

@@ -244,6 +244,7 @@ Button that navigates back to the parent view. Placed at the top of a submenu `C
 **ARIA (automatic):** `aria-label` from `label` prop.
 
 **Behavior:**
+
 - Click pops the navigation stack.
 - `ArrowLeft` anywhere in the submenu also pops (handled by Content).
 - After pop, focus returns to the `Trigger` that navigated forward.
@@ -503,12 +504,7 @@ media-menu {
 }
 
 /* Menu open/close — fade + slight scale */
-@starting-style {
-  media-menu[data-open] {
-    opacity: 0;
-    transform: scale(0.97);
-  }
-}
+media-menu[data-starting-style],
 media-menu[data-ending-style] {
   opacity: 0;
   transform: scale(0.97);

packages/core/src/core/index.ts

@@ -38,6 +38,8 @@ export * from './ui/play-button/play-button-core';
 export * from './ui/play-button/play-button-data-attrs';
 export * from './ui/playback-rate-button/playback-rate-button-core';
 export * from './ui/playback-rate-button/playback-rate-button-data-attrs';
+export * from './ui/playback-rate-menu/playback-rate-menu-core';
+export * from './ui/playback-rate-menu/playback-rate-menu-data-attrs';
 export * from './ui/popover/popover-core';
 export * from './ui/popover/popover-css-vars';
 export * from './ui/popover/popover-data-attrs';

packages/core/src/core/ui/playback-rate-menu/playback-rate-menu-core.ts

@@ -0,0 +1,116 @@
+import { createState } from '@videojs/store';
+import { defaults } from '@videojs/utils/object';
+import { isFunction, isUndefined } from '@videojs/utils/predicate';
+import type { NonNullableObject } from '@videojs/utils/types';
+
+import type { MediaPlaybackRateState } from '../../media/state';
+import type { ButtonState } from '../types';
+
+export interface PlaybackRateMenuProps {
+  /** Custom label for the menu trigger. */
+  label?: string | ((state: PlaybackRateMenuState) => string) | undefined;
+  /** Custom formatter for visible playback rate labels. */
+  formatRate?: ((rate: number) => string) | undefined;
+  /** Whether playback rate selection is disabled. */
+  disabled?: boolean | undefined;
+}
+
+export interface PlaybackRateMenuState extends ButtonState {
+  rate: number;
+  rates: readonly number[];
+  disabled: boolean;
+}
+
+function formatPlaybackRate(rate: number): string {
+  return `${rate}×`;
+}
+
+export class PlaybackRateMenuCore {
+  static readonly defaultProps: NonNullableObject<PlaybackRateMenuProps> = {
+    label: '',
+    formatRate: formatPlaybackRate,
+    disabled: false,
+  };
+
+  readonly state = createState<PlaybackRateMenuState>({
+    rate: 1,
+    rates: [],
+    disabled: false,
+    label: '',
+  });
+
+  #props = { ...PlaybackRateMenuCore.defaultProps };
+  #media: MediaPlaybackRateState | null = null;
+
+  constructor(props?: PlaybackRateMenuProps) {
+    if (props) this.setProps(props);
+  }
+
+  setProps(props: PlaybackRateMenuProps): void {
+    this.#props = defaults(props, PlaybackRateMenuCore.defaultProps);
+  }
+
+  getLabel(state: PlaybackRateMenuState): string {
+    const { label } = this.#props;
+
+    if (isFunction(label)) {
+      const customLabel = label(state);
+      if (customLabel) return customLabel;
+    } else if (label) {
+      return label;
+    }
+
+    return `Playback rate ${state.rate}`;
+  }
+
+  getRateLabel(rate: number): string {
+    return this.#props.formatRate(rate);
+  }
+
+  getRateValue(rate: number): string {
+    return String(rate);
+  }
+
+  getAttrs(state: PlaybackRateMenuState) {
+    return {
+      'aria-label': this.getLabel(state),
+      'aria-disabled': state.disabled ? 'true' : undefined,
+    };
+  }
+
+  setMedia(media: MediaPlaybackRateState): void {
+    this.#media = media;
+  }
+
+  getState(): PlaybackRateMenuState {
+    const media = this.#media!;
+
+    this.state.patch({
+      rate: media.playbackRate,
+      rates: media.playbackRates,
+      disabled: this.#props.disabled || media.playbackRates.length === 0,
+    });
+    this.state.patch({ label: this.getLabel(this.state.current) });
+
+    return this.state.current;
+  }
+
+  select(media: MediaPlaybackRateState, rate: number): void {
+    if (this.#props.disabled) return;
+    if (!media.playbackRates.includes(rate)) return;
+
+    media.setPlaybackRate(rate);
+  }
+
+  selectValue(media: MediaPlaybackRateState, value: string): void {
+    const rate = media.playbackRates.find((candidate) => this.getRateValue(candidate) === value);
+    if (isUndefined(rate)) return;
+
+    this.select(media, rate);
+  }
+}
+
+export namespace PlaybackRateMenuCore {
+  export type Props = PlaybackRateMenuProps;
+  export type State = PlaybackRateMenuState;
+}

packages/core/src/core/ui/playback-rate-menu/playback-rate-menu-data-attrs.ts

@@ -0,0 +1,9 @@
+import type { StateAttrMap } from '../types';
+import type { PlaybackRateMenuState } from './playback-rate-menu-core';
+
+export const PlaybackRateMenuDataAttrs = {
+  /** Current playback rate. */
+  rate: 'data-rate',
+  /** Present when playback rate selection is disabled. */
+  disabled: 'data-disabled',
+} as const satisfies StateAttrMap<PlaybackRateMenuState>;

packages/core/src/core/ui/playback-rate-menu/tests/playback-rate-menu-core.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import type { MediaPlaybackRateState } from '../../../media/state';
+import type { PlaybackRateMenuState } from '../playback-rate-menu-core';
+import { PlaybackRateMenuCore } from '../playback-rate-menu-core';
+
+function createMediaState(overrides: Partial<MediaPlaybackRateState> = {}): MediaPlaybackRateState {
+  return {
+    playbackRates: [0.5, 1, 1.5, 2],
+    playbackRate: 1,
+    setPlaybackRate: vi.fn(),
+    ...overrides,
+  };
+}
+
+function createState(overrides: Partial<PlaybackRateMenuState> = {}): PlaybackRateMenuState {
+  return {
+    rate: 1,
+    rates: [0.5, 1, 1.5, 2],
+    disabled: false,
+    label: '',
+    ...overrides,
+  };
+}
+
+describe('PlaybackRateMenuCore', () => {
+  describe('getState', () => {
+    it('projects playbackRate and playbackRates', () => {
+      const core = new PlaybackRateMenuCore();
+      const media = createMediaState({ playbackRate: 1.5, playbackRates: [1, 1.5] });
+      core.setMedia(media);
+      const state = core.getState();
+
+      expect(state.rate).toBe(1.5);
+      expect(state.rates).toEqual([1, 1.5]);
+    });
+
+    it('marks state disabled when no rates are available', () => {
+      const core = new PlaybackRateMenuCore();
+      const media = createMediaState({ playbackRates: [] });
+      core.setMedia(media);
+
+      expect(core.getState().disabled).toBe(true);
+    });
+  });
+
+  describe('getLabel', () => {
+    it('returns default label with rate', () => {
+      const core = new PlaybackRateMenuCore();
+      expect(core.getLabel(createState({ rate: 1.5 }))).toBe('Playback rate 1.5');
+    });
+
+    it('returns custom string label', () => {
+      const core = new PlaybackRateMenuCore({ label: 'Speed' });
+      expect(core.getLabel(createState())).toBe('Speed');
+    });
+
+    it('returns custom function label', () => {
+      const core = new PlaybackRateMenuCore({
+        label: (state) => `${state.rate}× speed`,
+      });
+      expect(core.getLabel(createState({ rate: 2 }))).toBe('2× speed');
+    });
+  });
+
+  describe('getRateLabel', () => {
+    it('formats rate labels by default', () => {
+      const core = new PlaybackRateMenuCore();
+      expect(core.getRateLabel(1.5)).toBe('1.5×');
+    });
+
+    it('uses a custom formatter', () => {
+      const core = new PlaybackRateMenuCore({
+        formatRate: (rate) => (rate === 1 ? 'Normal' : `${rate}×`),
+      });
+
+      expect(core.getRateLabel(1)).toBe('Normal');
+    });
+  });
+
+  describe('getAttrs', () => {
+    it('returns aria-label', () => {
+      const core = new PlaybackRateMenuCore();
+      const attrs = core.getAttrs(createState({ rate: 1.5 }));
+      expect(attrs['aria-label']).toBe('Playback rate 1.5');
+    });
+
+    it('sets aria-disabled when disabled', () => {
+      const core = new PlaybackRateMenuCore();
+      const attrs = core.getAttrs(createState({ disabled: true }));
+      expect(attrs['aria-disabled']).toBe('true');
+    });
+  });
+
+  describe('select', () => {
+    it('sets a rate from the available list', () => {
+      const core = new PlaybackRateMenuCore();
+      const media = createMediaState();
+      core.select(media, 1.5);
+      expect(media.setPlaybackRate).toHaveBeenCalledWith(1.5);
+    });
+
+    it('does nothing when disabled', () => {
+      const core = new PlaybackRateMenuCore({ disabled: true });
+      const media = createMediaState();
+      core.select(media, 1.5);
+      expect(media.setPlaybackRate).not.toHaveBeenCalled();
+    });
+
+    it('does nothing for unavailable rates', () => {
+      const core = new PlaybackRateMenuCore();
+      const media = createMediaState();
+      core.select(media, 3);
+      expect(media.setPlaybackRate).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('selectValue', () => {
+    it('sets the rate matching a menu value', () => {
+      const core = new PlaybackRateMenuCore();
+      const media = createMediaState();
+      core.selectValue(media, '2');
+      expect(media.setPlaybackRate).toHaveBeenCalledWith(2);
+    });
+
+    it('does nothing for an unknown menu value', () => {
+      const core = new PlaybackRateMenuCore();
+      const media = createMediaState();
+      core.selectValue(media, '3');
+      expect(media.setPlaybackRate).not.toHaveBeenCalled();
+    });
+  });
+});

packages/core/src/core/ui/popover/popover-css-vars.ts

@@ -3,6 +3,8 @@ export const PopoverCSSVars = {
   sideOffset: '--media-popover-side-offset',
   /** Distance between the popup and the trigger along the alignment axis. */
   alignOffset: '--media-popover-align-offset',
+  /** Minimum distance between the popup and the positioning boundary. */
+  boundaryOffset: '--media-popover-boundary-offset',
   /** The anchor element's width. */
   anchorWidth: '--media-popover-anchor-width',
   /** The anchor element's height. */

packages/core/src/core/ui/tooltip/tooltip-css-vars.ts

@@ -3,6 +3,8 @@ export const TooltipCSSVars = {
   sideOffset: '--media-tooltip-side-offset',
   /** Distance between the popup and the trigger along the alignment axis. */
   alignOffset: '--media-tooltip-align-offset',
+  /** Minimum distance between the popup and the positioning boundary. */
+  boundaryOffset: '--media-tooltip-boundary-offset',
   /** The anchor element's width. */
   anchorWidth: '--media-tooltip-anchor-width',
   /** The anchor element's height. */

packages/core/src/dom/gesture/tests/gesture.test.ts

@@ -431,6 +431,22 @@ describe('interactive child filtering', () => {
     expect(handler).not.toHaveBeenCalled();
   });
 
+  it('does not fire when event originates from a child with role="menuitemradio"', () => {
+    const container = setup();
+    const item = document.createElement('div');
+    item.setAttribute('role', 'menuitemradio');
+    container.appendChild(item);
+
+    const handler = vi.fn();
+    createTapGesture(container, handler);
+
+    pointerDown(item);
+    vi.advanceTimersByTime(50);
+    pointerUp(item, { pointerType: 'mouse', clientX: 150 });
+
+    expect(handler).not.toHaveBeenCalled();
+  });
+
   it('does not fire when event originates from a nested child inside an interactive element', () => {
     const container = setup();
     const button = document.createElement('button');

packages/core/src/dom/hotkey/coordinator.ts

@@ -135,6 +135,8 @@ export class HotkeyCoordinator {
     // Let interactive elements handle their own activation keys.
     if (isInteractiveActivation(event)) return;
 
+    if (event.defaultPrevented) return;
+
     const editable = isEditableTarget(event);
 
     for (const binding of this.#bindings) {

packages/core/src/dom/hotkey/tests/hotkey.test.ts

@@ -286,4 +286,18 @@ describe('createHotkey', () => {
 
     cleanup();
   });
+
+  it('does not fire when the event has already been handled', () => {
+    const el = setup();
+    const onActivate = vi.fn();
+
+    el.addEventListener('keydown', (event) => event.preventDefault(), { capture: true });
+    const cleanup = createHotkey(el, { keys: 'ArrowRight', onActivate });
+
+    el.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight', bubbles: true, cancelable: true }));
+
+    expect(onActivate).not.toHaveBeenCalled();
+
+    cleanup();
+  });
 });