feat(core): add buffering indicator component (#527)

packages/core/src/core/index.ts

@@ -1,4 +1,6 @@
 export * from './media/state';
+export * from './ui/buffering-indicator/buffering-indicator-core';
+export * from './ui/buffering-indicator/buffering-indicator-data-attrs';
 export * from './ui/controls/controls-core';
 export * from './ui/controls/controls-data-attrs';
 export * from './ui/fullscreen-button/fullscreen-button-core';

packages/core/src/core/ui/buffering-indicator/buffering-indicator-core.ts

@@ -0,0 +1,53 @@
+import { createState } from '@videojs/store';
+import { defaults } from '@videojs/utils/object';
+import type { NonNullableObject } from '@videojs/utils/types';
+
+import type { MediaPlaybackState } from '../../media/state';
+
+export interface BufferingIndicatorProps {
+  /** Delay in milliseconds before the indicator becomes visible. */
+  delay?: number | undefined;
+}
+
+export interface BufferingIndicatorState {
+  /** Whether the indicator should be visible. True after the delay elapses while media is waiting and not paused. */
+  visible: boolean;
+}
+
+export class BufferingIndicatorCore {
+  static readonly defaultProps: NonNullableObject<BufferingIndicatorProps> = {
+    delay: 500,
+  };
+
+  readonly state = createState<BufferingIndicatorState>({ visible: false });
+
+  #props = { ...BufferingIndicatorCore.defaultProps };
+  #timer: ReturnType<typeof setTimeout> | null = null;
+
+  setProps(props: BufferingIndicatorProps): void {
+    this.#props = defaults(props, BufferingIndicatorCore.defaultProps);
+  }
+
+  update(media: MediaPlaybackState): void {
+    const buffering = media.waiting && !media.paused;
+
+    if (buffering && !this.state.current.visible && !this.#timer) {
+      this.#timer = setTimeout(() => {
+        this.#timer = null;
+        this.state.patch({ visible: true });
+      }, this.#props.delay);
+    } else if (!buffering) {
+      if (this.#timer !== null) {
+        clearTimeout(this.#timer);
+        this.#timer = null;
+      }
+
+      this.state.patch({ visible: false });
+    }
+  }
+}
+
+export namespace BufferingIndicatorCore {
+  export type Props = BufferingIndicatorProps;
+  export type State = BufferingIndicatorState;
+}

packages/core/src/core/ui/buffering-indicator/buffering-indicator-data-attrs.ts

@@ -0,0 +1,7 @@
+import type { StateAttrMap } from '../types';
+import type { BufferingIndicatorState } from './buffering-indicator-core';
+
+export const BufferingIndicatorDataAttrs = {
+  /** Present when the buffering indicator is visible (after delay). */
+  visible: 'data-visible',
+} as const satisfies StateAttrMap<BufferingIndicatorState>;

packages/core/src/core/ui/buffering-indicator/tests/buffering-indicator-core.test.ts

@@ -0,0 +1,237 @@
+import { flush } from '@videojs/store';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { MediaPlaybackState } from '../../../media/state';
+import { BufferingIndicatorCore } from '../buffering-indicator-core';
+
+function createMediaState(overrides: Partial<MediaPlaybackState> = {}): MediaPlaybackState {
+  return {
+    paused: true,
+    ended: false,
+    started: false,
+    waiting: false,
+    play: vi.fn(async () => {}),
+    pause: vi.fn(),
+    ...overrides,
+  };
+}
+
+describe('BufferingIndicatorCore', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('update', () => {
+    it('visible is false when not waiting', () => {
+      const core = new BufferingIndicatorCore();
+
+      core.update(createMediaState({ waiting: false, paused: false }));
+
+      expect(core.state.current.visible).toBe(false);
+    });
+
+    it('visible is false when waiting but paused', () => {
+      const core = new BufferingIndicatorCore();
+
+      core.update(createMediaState({ waiting: true, paused: true }));
+
+      expect(core.state.current.visible).toBe(false);
+    });
+
+    it('visible is false immediately when waiting and not paused (before delay)', () => {
+      const core = new BufferingIndicatorCore();
+
+      core.update(createMediaState({ waiting: true, paused: false }));
+
+      expect(core.state.current.visible).toBe(false);
+    });
+
+    it('visible becomes true after default delay elapses', () => {
+      const core = new BufferingIndicatorCore();
+
+      core.update(createMediaState({ waiting: true, paused: false }));
+      vi.advanceTimersByTime(500);
+
+      expect(core.state.current.visible).toBe(true);
+    });
+
+    it('visible stays false if waiting ends before delay', () => {
+      const core = new BufferingIndicatorCore();
+
+      core.update(createMediaState({ waiting: true, paused: false }));
+      vi.advanceTimersByTime(300);
+
+      core.update(createMediaState({ waiting: false, paused: false }));
+
+      expect(core.state.current.visible).toBe(false);
+
+      // Even after more time, still not visible
+      vi.advanceTimersByTime(500);
+      expect(core.state.current.visible).toBe(false);
+    });
+
+    it('resets timer when waiting toggles off and on within delay', () => {
+      const core = new BufferingIndicatorCore();
+      const waiting = createMediaState({ waiting: true, paused: false });
+      const notWaiting = createMediaState({ waiting: false, paused: false });
+
+      core.update(waiting);
+      vi.advanceTimersByTime(300);
+
+      // Stop waiting (cancels timer)
+      core.update(notWaiting);
+
+      // Start waiting again (new timer)
+      core.update(waiting);
+      vi.advanceTimersByTime(300);
+
+      // Only 300ms into the new timer, not yet visible
+      expect(core.state.current.visible).toBe(false);
+
+      // Full 500ms from second start
+      vi.advanceTimersByTime(200);
+      expect(core.state.current.visible).toBe(true);
+    });
+
+    it('immediately hides when waiting ends while visible', () => {
+      const core = new BufferingIndicatorCore();
+
+      core.update(createMediaState({ waiting: true, paused: false }));
+      vi.advanceTimersByTime(500);
+      expect(core.state.current.visible).toBe(true);
+
+      core.update(createMediaState({ waiting: false, paused: false }));
+      expect(core.state.current.visible).toBe(false);
+    });
+
+    it('immediately hides when paused while visible', () => {
+      const core = new BufferingIndicatorCore();
+
+      core.update(createMediaState({ waiting: true, paused: false }));
+      vi.advanceTimersByTime(500);
+      expect(core.state.current.visible).toBe(true);
+
+      core.update(createMediaState({ waiting: true, paused: true }));
+      expect(core.state.current.visible).toBe(false);
+    });
+
+    it('is idempotent — repeated calls with same state do not restart timer', () => {
+      const core = new BufferingIndicatorCore();
+      const media = createMediaState({ waiting: true, paused: false });
+
+      core.update(media);
+      vi.advanceTimersByTime(300);
+
+      // Same state again — should NOT restart timer
+      core.update(media);
+      vi.advanceTimersByTime(200);
+
+      // 500ms total from first call — timer should fire
+      expect(core.state.current.visible).toBe(true);
+    });
+  });
+
+  describe('custom delay', () => {
+    it('respects a custom delay value', () => {
+      const core = new BufferingIndicatorCore();
+      core.setProps({ delay: 1000 });
+
+      core.update(createMediaState({ waiting: true, paused: false }));
+      vi.advanceTimersByTime(500);
+      expect(core.state.current.visible).toBe(false);
+
+      vi.advanceTimersByTime(500);
+      expect(core.state.current.visible).toBe(true);
+    });
+
+    it('respects delay: 0 for immediate visibility', () => {
+      const core = new BufferingIndicatorCore();
+      core.setProps({ delay: 0 });
+
+      core.update(createMediaState({ waiting: true, paused: false }));
+      vi.advanceTimersByTime(0);
+
+      expect(core.state.current.visible).toBe(true);
+    });
+
+    it('does not apply new delay to an already running timer', () => {
+      const core = new BufferingIndicatorCore();
+
+      core.update(createMediaState({ waiting: true, paused: false }));
+      vi.advanceTimersByTime(300);
+
+      core.setProps({ delay: 1000 });
+      vi.advanceTimersByTime(200);
+
+      // Original 500ms timer fires
+      expect(core.state.current.visible).toBe(true);
+    });
+  });
+
+  describe('state.subscribe', () => {
+    it('notifies subscribers when visible becomes true', () => {
+      const core = new BufferingIndicatorCore();
+      const callback = vi.fn();
+
+      core.state.subscribe(callback);
+
+      core.update(createMediaState({ waiting: true, paused: false }));
+      expect(callback).not.toHaveBeenCalled();
+
+      vi.advanceTimersByTime(500);
+      flush();
+
+      expect(callback).toHaveBeenCalledOnce();
+    });
+
+    it('notifies subscribers when visible becomes false', () => {
+      const core = new BufferingIndicatorCore();
+      const callback = vi.fn();
+
+      core.update(createMediaState({ waiting: true, paused: false }));
+      vi.advanceTimersByTime(500);
+      flush();
+
+      core.state.subscribe(callback);
+
+      core.update(createMediaState({ waiting: false, paused: false }));
+      flush();
+
+      expect(callback).toHaveBeenCalledOnce();
+    });
+
+    it('does not notify if waiting ends before delay', () => {
+      const core = new BufferingIndicatorCore();
+      const callback = vi.fn();
+
+      core.state.subscribe(callback);
+
+      core.update(createMediaState({ waiting: true, paused: false }));
+      vi.advanceTimersByTime(300);
+      core.update(createMediaState({ waiting: false, paused: false }));
+
+      vi.advanceTimersByTime(500);
+      flush();
+
+      expect(callback).not.toHaveBeenCalled();
+    });
+
+    it('supports unsubscribe', () => {
+      const core = new BufferingIndicatorCore();
+      const callback = vi.fn();
+
+      const unsubscribe = core.state.subscribe(callback);
+      unsubscribe();
+
+      core.update(createMediaState({ waiting: true, paused: false }));
+      vi.advanceTimersByTime(500);
+      flush();
+
+      expect(callback).not.toHaveBeenCalled();
+    });
+  });
+});