feat(packages): opaque translation keys in core ui with duration formatting

Use TranslationKeyOrString for control labels, centralize optional label
resolution, and expose formatOptions for formatDuration-based copy across
time controls and sliders; extend utils time helpers used by core and tests.

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

Author: sampotts

packages/core/src/core/i18n/types.ts

@@ -57,6 +57,12 @@ export type TranslationParams = {
   mediaErrorCustom: never;
 };
 
+/**
+ * Either a known translation id from {@link TranslationParams}, or any other string the platform may
+ * use as copy (custom overlay key, literal text, etc.).
+ */
+export type TranslationKeyOrString = keyof TranslationParams | (string & {});
+
 /** Placeholder shape for each key that accepts `t(key, params)`. Omitting a key here is a type error when defining strings. */
 type ParametricTranslations = {
   seekForwardSeconds: Contains<'{seconds}'>;

packages/core/src/core/index.ts

@@ -46,6 +46,7 @@ export * from './ui/popover/popover-data-attrs';
 export * from './ui/popover/popup-host-attr';
 export * from './ui/poster/poster-core';
 export * from './ui/poster/poster-data-attrs';
+export * from './ui/resolve-optional-control-label';
 export * from './ui/seek-button/seek-button-core';
 export * from './ui/seek-button/seek-button-data-attrs';
 export * from './ui/slider/slider-core';

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

@@ -1,14 +1,14 @@
 import { createState } from '@videojs/store';
 import { defaults } from '@videojs/utils/object';
-import { isFunction } from '@videojs/utils/predicate';
 import type { NonNullableObject } from '@videojs/utils/types';
 
 import type { MediaTextTrackState } from '../../media/state';
-import type { ButtonState } from '../types';
+import { resolveOptionalControlLabel } from '../resolve-optional-control-label';
+import type { ButtonState, TranslationKeyOrString } from '../types';
 
 export interface CaptionsButtonProps {
   /** Custom label for the button. */
-  label?: string | ((state: CaptionsButtonState) => string) | undefined;
+  label?: TranslationKeyOrString | ((state: CaptionsButtonState) => TranslationKeyOrString) | undefined;
   /** Whether the button is disabled. */
   disabled?: boolean | undefined;
 }
@@ -40,17 +40,11 @@ export class CaptionsButtonCore {
     this.#props = defaults(props, CaptionsButtonCore.defaultProps);
   }
 
-  getLabel(state: CaptionsButtonState): string {
-    const { label } = this.#props;
+  getLabel(state: CaptionsButtonState): TranslationKeyOrString {
+    const custom = resolveOptionalControlLabel(this.#props.label, state);
+    if (custom !== undefined) return custom;
 
-    if (isFunction(label)) {
-      const customLabel = label(state);
-      if (customLabel) return customLabel;
-    } else if (label) {
-      return label;
-    }
-
-    return state.subtitlesShowing ? 'Disable captions' : 'Enable captions';
+    return state.subtitlesShowing ? 'disableCaptions' : 'enableCaptions';
   }
 
   getAttrs(state: CaptionsButtonState) {

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

@@ -66,12 +66,12 @@ describe('CaptionsButtonCore', () => {
   describe('getLabel', () => {
     it('returns Enable captions when captions are disabled', () => {
       const core = new CaptionsButtonCore();
-      expect(core.getLabel(createState({ subtitlesShowing: false }))).toBe('Enable captions');
+      expect(core.getLabel(createState({ subtitlesShowing: false }))).toBe('enableCaptions');
     });
 
     it('returns Disable captions when captions are enabled', () => {
       const core = new CaptionsButtonCore();
-      expect(core.getLabel(createState({ subtitlesShowing: true }))).toBe('Disable captions');
+      expect(core.getLabel(createState({ subtitlesShowing: true }))).toBe('disableCaptions');
     });
 
     it('returns custom string label', () => {
@@ -91,7 +91,7 @@ describe('CaptionsButtonCore', () => {
     it('returns aria-label', () => {
       const core = new CaptionsButtonCore();
       const attrs = core.getAttrs(createState({ subtitlesShowing: false }));
-      expect(attrs['aria-label']).toBe('Enable captions');
+      expect(attrs['aria-label']).toBe('enableCaptions');
     });
 
     it('sets aria-disabled when disabled', () => {

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

@@ -1,15 +1,15 @@
 import { createState } from '@videojs/store';
 import { defaults } from '@videojs/utils/object';
-import { isFunction } from '@videojs/utils/predicate';
 import type { NonNullableObject } from '@videojs/utils/types';
 
 import type { MediaRemotePlaybackState, RemotePlaybackConnectionState } from '../../media/state';
 import type { MediaFeatureAvailability } from '../../media/types';
-import type { ButtonState } from '../types';
+import { resolveOptionalControlLabel } from '../resolve-optional-control-label';
+import type { ButtonState, TranslationKeyOrString } from '../types';
 
 export interface CastButtonProps {
   /** Custom label for the button. */
-  label?: string | ((state: CastButtonState) => string) | undefined;
+  label?: TranslationKeyOrString | ((state: CastButtonState) => TranslationKeyOrString) | undefined;
   /** Whether the button is disabled. */
   disabled?: boolean | undefined;
 }
@@ -42,19 +42,13 @@ export class CastButtonCore {
     this.#props = defaults(props, CastButtonCore.defaultProps);
   }
 
-  getLabel(state: CastButtonState): string {
-    const { label } = this.#props;
+  getLabel(state: CastButtonState): TranslationKeyOrString {
+    const custom = resolveOptionalControlLabel(this.#props.label, state);
+    if (custom !== undefined) return custom;
 
-    if (isFunction(label)) {
-      const customLabel = label(state);
-      if (customLabel) return customLabel;
-    } else if (label) {
-      return label;
-    }
-
-    if (state.castState === 'connected') return 'Stop casting';
-    if (state.castState === 'connecting') return 'Connecting';
-    return 'Start casting';
+    if (state.castState === 'connected') return 'stopCasting';
+    if (state.castState === 'connecting') return 'connectingCast';
+    return 'startCasting';
   }
 
   getAttrs(state: CastButtonState) {

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

@@ -78,17 +78,17 @@ describe('CastButtonCore', () => {
   describe('getLabel', () => {
     it('returns Start casting when disconnected', () => {
       const core = new CastButtonCore();
-      expect(core.getLabel(createState({ castState: 'disconnected' }))).toBe('Start casting');
+      expect(core.getLabel(createState({ castState: 'disconnected' }))).toBe('startCasting');
     });
 
     it('returns Stop casting when connected', () => {
       const core = new CastButtonCore();
-      expect(core.getLabel(createState({ castState: 'connected' }))).toBe('Stop casting');
+      expect(core.getLabel(createState({ castState: 'connected' }))).toBe('stopCasting');
     });
 
     it('returns Connecting when connecting', () => {
       const core = new CastButtonCore();
-      expect(core.getLabel(createState({ castState: 'connecting' }))).toBe('Connecting');
+      expect(core.getLabel(createState({ castState: 'connecting' }))).toBe('connectingCast');
     });
 
     it('returns custom string label', () => {
@@ -108,7 +108,7 @@ describe('CastButtonCore', () => {
     it('returns aria-label', () => {
       const core = new CastButtonCore();
       const attrs = core.getAttrs(createState());
-      expect(attrs['aria-label']).toBe('Start casting');
+      expect(attrs['aria-label']).toBe('startCasting');
     });
 
     it('sets aria-disabled when disabled', () => {

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

@@ -1,14 +1,14 @@
 import { createState } from '@videojs/store';
 import { defaults } from '@videojs/utils/object';
-import { isFunction } from '@videojs/utils/predicate';
 import type { NonNullableObject } from '@videojs/utils/types';
 
 import type { MediaFullscreenState } from '../../media/state';
-import type { ButtonState } from '../types';
+import { resolveOptionalControlLabel } from '../resolve-optional-control-label';
+import type { ButtonState, TranslationKeyOrString } from '../types';
 
 export interface FullscreenButtonProps {
   /** Custom label for the button. */
-  label?: string | ((state: FullscreenButtonState) => string) | undefined;
+  label?: TranslationKeyOrString | ((state: FullscreenButtonState) => TranslationKeyOrString) | undefined;
   /** Whether the button is disabled. */
   disabled?: boolean | undefined;
 }
@@ -41,17 +41,11 @@ export class FullscreenButtonCore {
     this.#props = defaults(props, FullscreenButtonCore.defaultProps);
   }
 
-  getLabel(state: FullscreenButtonState): string {
-    const { label } = this.#props;
+  getLabel(state: FullscreenButtonState): TranslationKeyOrString {
+    const custom = resolveOptionalControlLabel(this.#props.label, state);
+    if (custom !== undefined) return custom;
 
-    if (isFunction(label)) {
-      const customLabel = label(state);
-      if (customLabel) return customLabel;
-    } else if (label) {
-      return label;
-    }
-
-    return state.fullscreen ? 'Exit fullscreen' : 'Enter fullscreen';
+    return state.fullscreen ? 'exitFullscreen' : 'enterFullscreen';
   }
 
   getAttrs(state: FullscreenButtonState) {

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

@@ -48,12 +48,12 @@ describe('FullscreenButtonCore', () => {
   describe('getLabel', () => {
     it('returns Enter fullscreen when not fullscreen', () => {
       const core = new FullscreenButtonCore();
-      expect(core.getLabel(createState({ fullscreen: false }))).toBe('Enter fullscreen');
+      expect(core.getLabel(createState({ fullscreen: false }))).toBe('enterFullscreen');
     });
 
     it('returns Exit fullscreen when fullscreen', () => {
       const core = new FullscreenButtonCore();
-      expect(core.getLabel(createState({ fullscreen: true }))).toBe('Exit fullscreen');
+      expect(core.getLabel(createState({ fullscreen: true }))).toBe('exitFullscreen');
     });
 
     it('returns custom string label', () => {
@@ -73,7 +73,7 @@ describe('FullscreenButtonCore', () => {
     it('returns aria-label', () => {
       const core = new FullscreenButtonCore();
       const attrs = core.getAttrs(createState());
-      expect(attrs['aria-label']).toBe('Enter fullscreen');
+      expect(attrs['aria-label']).toBe('enterFullscreen');
     });
 
     it('sets aria-disabled when disabled', () => {

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

@@ -1,14 +1,14 @@
 import { createState } from '@videojs/store';
 import { defaults } from '@videojs/utils/object';
-import { isFunction } from '@videojs/utils/predicate';
 import type { NonNullableObject } from '@videojs/utils/types';
 
 import type { MediaBufferState, MediaLiveState, MediaTimeState } from '../../media/state';
-import type { ButtonState } from '../types';
+import { resolveOptionalControlLabel } from '../resolve-optional-control-label';
+import type { ButtonState, TranslationKeyOrString } from '../types';
 
 export interface LiveButtonProps {
   /** Custom label for the button. */
-  label?: string | ((state: LiveButtonState) => string) | undefined;
+  label?: TranslationKeyOrString | ((state: LiveButtonState) => TranslationKeyOrString) | undefined;
   /** Whether the button is disabled. */
   disabled?: boolean | undefined;
 }
@@ -82,18 +82,12 @@ export class LiveButtonCore {
     this.#props = defaults(props, LiveButtonCore.defaultProps);
   }
 
-  getLabel(state: LiveButtonState): string {
-    const { label } = this.#props;
+  getLabel(state: LiveButtonState): TranslationKeyOrString {
+    const custom = resolveOptionalControlLabel(this.#props.label, state);
+    if (custom !== undefined) return custom;
 
-    if (isFunction(label)) {
-      const customLabel = label(state);
-      if (customLabel) return customLabel;
-    } else if (label) {
-      return label;
-    }
-
-    if (state.liveEdge) return 'Playing live';
-    return 'Seek to live edge';
+    if (state.liveEdge) return 'playingLive';
+    return 'seekToLiveEdge';
   }
 
   getAttrs(state: LiveButtonState) {

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

@@ -148,12 +148,12 @@ describe('LiveButtonCore', () => {
   describe('getLabel', () => {
     it('returns "Seek to live edge" when behind live', () => {
       const core = new LiveButtonCore();
-      expect(core.getLabel(createState({ live: true, liveEdge: false }))).toBe('Seek to live edge');
+      expect(core.getLabel(createState({ live: true, liveEdge: false }))).toBe('seekToLiveEdge');
     });
 
     it('returns "Playing live" when at live edge', () => {
       const core = new LiveButtonCore();
-      expect(core.getLabel(createState({ live: true, liveEdge: true }))).toBe('Playing live');
+      expect(core.getLabel(createState({ live: true, liveEdge: true }))).toBe('playingLive');
     });
 
     it('returns custom string label', () => {