fix(core): time slider valuetext at zero duration and CI docs

Use Number.isFinite for duration in time slider aria-valuetext so
duration 0 still formats. Fix formatOptions JSDoc for api-docs schema.

Cache optional control labels so impure label callbacks run once per
state. Inline duration decomposition in formatDuration (remove redundant
toDurationRecord filtering).

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: sampotts

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

@@ -3,7 +3,7 @@ import { defaults } from '@videojs/utils/object';
 import type { NonNullableObject } from '@videojs/utils/types';
 
 import type { MediaPlaybackRateState } from '../../media/state';
-import { resolveOptionalControlLabel } from '../resolve-optional-control-label';
+import { createOptionalControlLabelCache } from '../resolve-optional-control-label';
 import type { ButtonState, TranslationKeyOrString } from '../types';
 
 export interface PlaybackRateButtonProps {
@@ -30,24 +30,26 @@ export class PlaybackRateButtonCore {
 
   #props = { ...PlaybackRateButtonCore.defaultProps };
   #media: MediaPlaybackRateState | null = null;
+  readonly #customLabel = createOptionalControlLabelCache<PlaybackRateButtonState>();
 
   constructor(props?: PlaybackRateButtonProps) {
     if (props) this.setProps(props);
   }
 
   setProps(props: PlaybackRateButtonProps): void {
     this.#props = defaults(props, PlaybackRateButtonCore.defaultProps);
+    this.#customLabel.invalidate();
   }
 
   getLabel(state: PlaybackRateButtonState): TranslationKeyOrString {
-    const custom = resolveOptionalControlLabel(this.#props.label, state);
+    const custom = this.#customLabel.resolve(this.#props.label, state);
     if (custom !== undefined) return custom;
 
     return 'playbackRateAria';
   }
 
   getLabelParams(state: PlaybackRateButtonState): { rate: number } | undefined {
-    if (resolveOptionalControlLabel(this.#props.label, state) !== undefined) return undefined;
+    if (this.#customLabel.resolve(this.#props.label, state) !== undefined) return undefined;
     return { rate: state.rate };
   }
 

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

@@ -4,7 +4,7 @@ import { isUndefined } from '@videojs/utils/predicate';
 import type { NonNullableObject } from '@videojs/utils/types';
 
 import type { MediaPlaybackRateState } from '../../media/state';
-import { resolveOptionalControlLabel } from '../resolve-optional-control-label';
+import { createOptionalControlLabelCache } from '../resolve-optional-control-label';
 import type { ButtonState, TranslationKeyOrString } from '../types';
 
 export interface PlaybackRateMenuProps {
@@ -42,23 +42,25 @@ export class PlaybackRateMenuCore {
 
   #props = { ...PlaybackRateMenuCore.defaultProps };
   #media: MediaPlaybackRateState | null = null;
+  readonly #customLabel = createOptionalControlLabelCache<PlaybackRateMenuState>();
 
   constructor(props?: PlaybackRateMenuProps) {
     if (props) this.setProps(props);
   }
 
   setProps(props: PlaybackRateMenuProps): void {
     this.#props = defaults(props, PlaybackRateMenuCore.defaultProps);
+    this.#customLabel.invalidate();
   }
 
   getLabel(state: PlaybackRateMenuState): TranslationKeyOrString {
-    const custom = resolveOptionalControlLabel(this.#props.label, state);
+    const custom = this.#customLabel.resolve(this.#props.label, state);
     if (custom !== undefined) return custom;
     return 'playbackRateAria';
   }
 
   getLabelParams(state: PlaybackRateMenuState): { rate: number } | undefined {
-    if (resolveOptionalControlLabel(this.#props.label, state) !== undefined) return undefined;
+    if (this.#customLabel.resolve(this.#props.label, state) !== undefined) return undefined;
     return { rate: state.rate };
   }
 

packages/core/src/core/ui/resolve-optional-control-label.ts

@@ -17,3 +17,26 @@ export function resolveOptionalControlLabel<State>(
   if (label) return label;
   return undefined;
 }
+
+/** Per-instance cache so `getLabel` / `getLabelParams` share one resolution per state snapshot. */
+export function createOptionalControlLabelCache<State>(): {
+  resolve(
+    label: TranslationKeyOrString | ((state: State) => TranslationKeyOrString) | undefined,
+    state: State
+  ): TranslationKeyOrString | undefined;
+  invalidate(): void;
+} {
+  let cache: { state: State; custom: TranslationKeyOrString | undefined } | null = null;
+
+  return {
+    resolve(label, state) {
+      if (cache?.state !== state) {
+        cache = { state, custom: resolveOptionalControlLabel(label, state) };
+      }
+      return cache.custom;
+    },
+    invalidate() {
+      cache = null;
+    },
+  };
+}

packages/core/src/core/ui/seek-button/seek-button-core.ts

@@ -3,7 +3,7 @@ import { defaults } from '@videojs/utils/object';
 import type { NonNullableObject } from '@videojs/utils/types';
 
 import type { MediaTimeState } from '../../media/state';
-import { resolveOptionalControlLabel } from '../resolve-optional-control-label';
+import { createOptionalControlLabelCache } from '../resolve-optional-control-label';
 import type { ButtonState, TranslationKeyOrString } from '../types';
 
 export interface SeekButtonProps {
@@ -39,24 +39,26 @@ export class SeekButtonCore {
 
   #props = { ...SeekButtonCore.defaultProps };
   #media: MediaTimeState | null = null;
+  readonly #customLabel = createOptionalControlLabelCache<SeekButtonState>();
 
   constructor(props?: SeekButtonProps) {
     if (props) this.setProps(props);
   }
 
   setProps(props: SeekButtonProps): void {
     this.#props = defaults(props, SeekButtonCore.defaultProps);
+    this.#customLabel.invalidate();
   }
 
   getLabel(state: SeekButtonState): TranslationKeyOrString {
-    const custom = resolveOptionalControlLabel(this.#props.label, state);
+    const custom = this.#customLabel.resolve(this.#props.label, state);
     if (custom !== undefined) return custom;
 
     return state.direction === 'backward' ? 'seekBackwardSeconds' : 'seekForwardSeconds';
   }
 
   getLabelParams(state: SeekButtonState): { seconds: number } | undefined {
-    if (resolveOptionalControlLabel(this.#props.label, state) !== undefined) return undefined;
+    if (this.#customLabel.resolve(this.#props.label, state) !== undefined) return undefined;
     return { seconds: Math.abs(this.#props.seconds) };
   }
 

packages/core/src/core/ui/seek-button/tests/seek-button-core.test.ts

@@ -124,6 +124,22 @@ describe('SeekButtonCore', () => {
       const core = new SeekButtonCore({ label: 'Skip' });
       expect(core.getLabelParams(createState())).toBeUndefined();
     });
+
+    it('shares one label callback invocation with getLabel for the same state', () => {
+      let calls = 0;
+      const core = new SeekButtonCore({
+        seconds: 30,
+        label: () => {
+          calls += 1;
+          return calls === 1 ? 'custom' : '';
+        },
+      });
+      const state = createState({ direction: 'forward' });
+
+      expect(core.getLabel(state)).toBe('custom');
+      expect(core.getLabelParams(state)).toBeUndefined();
+      expect(calls).toBe(1);
+    });
   });
 
   describe('getAttrs', () => {

packages/core/src/core/ui/tests/resolve-optional-control-label.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
-import { resolveOptionalControlLabel } from '../resolve-optional-control-label';
+import { createOptionalControlLabelCache, resolveOptionalControlLabel } from '../resolve-optional-control-label';
 
 describe('resolveOptionalControlLabel', () => {
   const state = { x: 1 as const };
@@ -26,3 +26,28 @@ describe('resolveOptionalControlLabel', () => {
     expect(resolveOptionalControlLabel(() => '', state)).toBeUndefined();
   });
 });
+
+describe('createOptionalControlLabelCache', () => {
+  const state = { x: 1 as const };
+
+  it('reuses resolution for the same state snapshot', () => {
+    let calls = 0;
+    const cache = createOptionalControlLabelCache<typeof state>();
+    const label = () => {
+      calls += 1;
+      return calls === 1 ? 'first' : '';
+    };
+
+    expect(cache.resolve(label, state)).toBe('first');
+    expect(cache.resolve(label, state)).toBe('first');
+    expect(calls).toBe(1);
+  });
+
+  it('invalidates cached resolution', () => {
+    const cache = createOptionalControlLabelCache<typeof state>();
+
+    expect(cache.resolve('A', state)).toBe('A');
+    cache.invalidate();
+    expect(cache.resolve('B', state)).toBe('B');
+  });
+});

packages/core/src/core/ui/time-slider/time-slider-core.ts

@@ -15,7 +15,7 @@ export interface TimeSliderProps extends SliderProps {
   max?: number | undefined;
   /** Leading+trailing throttle (ms) for `onValueChange` during drag. */
   changeThrottle?: number | undefined;
-  /** Options for {@link formatDuration} when building the slider thumb's `aria-valuetext`. */
+  /** Options for `formatDuration` when building the slider thumb `aria-valuetext`. */
   formatOptions?: TimeFormatOptions | undefined;
 }
 
@@ -83,7 +83,7 @@ export class TimeSliderCore extends SliderCore {
     const formatOptions = this.#props.formatOptions;
     const currentPhrase = formatDuration(announceValue, formatOptions);
     const durationPhrase = formatDuration(state.duration, formatOptions);
-    const valuetext = durationPhrase ? `${currentPhrase} of ${durationPhrase}` : currentPhrase;
+    const valuetext = Number.isFinite(state.duration) ? `${currentPhrase} of ${durationPhrase}` : currentPhrase;
 
     return {
       ...base,

packages/core/src/core/ui/time/time-core.ts

@@ -16,7 +16,7 @@ export interface TimeProps {
   negativeSign?: string | undefined;
   /** Custom label for accessibility. */
   label?: TranslationKeyOrString | ((state: TimeState) => TranslationKeyOrString) | undefined;
-  /** Options for {@link formatDuration} when building {@link TimeState#phrase} and screen reader text (not clock digits). */
+  /** Options for `formatDuration` when building spoken-duration copy (`phrase` state and screen readers), not digital clock text. */
   formatOptions?: TimeFormatOptions | undefined;
 }
 

packages/utils/src/time/format.ts

@@ -131,21 +131,6 @@ export function secondsToIsoDuration(seconds: number): string {
   return duration;
 }
 
-function toDurationRecord(totalSeconds: number): Record<'hours' | 'minutes' | 'seconds', number> {
-  const sec = Math.floor(Math.abs(totalSeconds));
-  const hours = Math.floor(sec / 3600);
-  const minutes = Math.floor((sec % 3600) / 60);
-  const seconds = sec % 60;
-
-  const record = { hours: 0, minutes: 0, seconds: 0 };
-  if (hours > 0) record.hours = hours;
-  if (minutes > 0) record.minutes = minutes;
-  if (seconds > 0 || (hours === 0 && minutes === 0)) {
-    record.seconds = seconds;
-  }
-  return record;
-}
-
 /**
  * Human-readable duration using {@link Intl.DurationFormat} when available.
  *
@@ -159,11 +144,15 @@ export function formatDuration(seconds: number, options?: TimeFormatOptions): st
 
   const negative = seconds < 0;
   const positiveSeconds = Math.abs(seconds);
-  const { hours, minutes, seconds: sec } = toDurationRecord(positiveSeconds);
+  const totalSeconds = Math.floor(positiveSeconds);
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const secondsPart = totalSeconds % 60;
+
   const record: Partial<{ hours: number; minutes: number; seconds: number }> = {};
   if (hours > 0) record.hours = hours;
   if (minutes > 0) record.minutes = minutes;
-  if (sec > 0 || (hours === 0 && minutes === 0)) record.seconds = sec;
+  if (secondsPart > 0 || (hours === 0 && minutes === 0)) record.seconds = secondsPart;
 
   let body: string;
   type DurationFormatConstructor = new (
@@ -185,6 +174,11 @@ export function formatDuration(seconds: number, options?: TimeFormatOptions): st
     body = formatTimeAsPhrase(positiveSeconds);
   }
 
+  // Some ICU builds return an empty string for a zero-length duration; fall back to the phrase formatter.
+  if (!body.trim()) {
+    body = formatTimeAsPhrase(positiveSeconds);
+  }
+
   if (negative) {
     const suffix = options?.translate?.('remaining') ?? 'remaining';
     return `${body} ${suffix}`;