@applicaster/zapp-react-native-utils 16.0.0-rc.11 → 16.0.0-rc.111

package/appUtils/playerManager/__tests__/playerToolbox.test.ts

@@ -0,0 +1,97 @@
+const mockRegister = jest.fn();
+let mockXray: Record<string, unknown> | null = {};
+
+jest.mock("../../../logger", () => ({
+  getXray: () => mockXray,
+}));
+
+const loadToolbox = () => {
+  let module;
+
+  jest.isolateModules(() => {
+    module = require("../playerToolbox");
+  });
+
+  return module as typeof import("../playerToolbox");
+};
+
+const player = (overrides = {}) => ({
+  getSeekableDuration: () => 100,
+  getContentPosition: () => 40,
+  seekTo: jest.fn(),
+  ...overrides,
+});
+
+const manager = (active) =>
+  ({ getActivePlayer: () => active, isCasting: () => false }) as any;
+
+const registeredTools = async (active) => {
+  mockRegister.mockResolvedValue(undefined);
+  mockXray = { registerReactToolbox: mockRegister };
+  await loadToolbox().registerPlayerToolbox(manager(active));
+
+  const { tools } = mockRegister.mock.calls[0][0];
+
+  return Object.fromEntries(tools.map((tool) => [tool.name, tool.handler]));
+};
+
+describe("playerToolbox", () => {
+  beforeEach(() => {
+    mockRegister.mockReset();
+  });
+
+  it("does nothing when X-Ray has no React toolbox API", async () => {
+    mockXray = {};
+
+    await expect(
+      loadToolbox().registerPlayerToolbox(manager(null))
+    ).resolves.toBeUndefined();
+  });
+
+  it("does nothing when getXray returns null", async () => {
+    mockXray = null;
+
+    await expect(
+      loadToolbox().registerPlayerToolbox(manager(null))
+    ).resolves.toBeUndefined();
+  });
+
+  it("swallows a failed registration", async () => {
+    mockRegister.mockRejectedValue(new Error("no native bridge"));
+    mockXray = { registerReactToolbox: mockRegister };
+
+    await expect(
+      loadToolbox().registerPlayerToolbox(manager(null))
+    ).resolves.toBeUndefined();
+  });
+
+  it("seeks to an absolute position, from the end when negative, clamped", async () => {
+    const active = player();
+    const tools = await registeredTools(active);
+
+    expect(tools.seek({ position: 30 })).toEqual({ position: 30 });
+    expect(tools.seek({ position: -10 })).toEqual({ position: 90 });
+    expect(tools.seek({ position: 500 })).toEqual({ position: 100 });
+    expect(tools.seek({ position: -500 })).toEqual({ position: 0 });
+    expect(active.seekTo.mock.calls).toEqual([[30], [90], [100], [0]]);
+  });
+
+  it("offsets from the current position and refuses zero", async () => {
+    const tools = await registeredTools(player());
+
+    expect(tools.offset({ seconds: 15 })).toEqual({ from: 40, position: 55 });
+    expect(tools.offset({ seconds: -60 })).toEqual({ from: 40, position: 0 });
+
+    expect(() => tools.offset({ seconds: 0 })).toThrow(
+      "Ignored zero relative seek"
+    );
+  });
+
+  it("refuses to seek a stream that is not seekable", async () => {
+    const tools = await registeredTools(
+      player({ getSeekableDuration: () => 0 })
+    );
+
+    expect(() => tools.seek({ position: 10 })).toThrow("Seek is not supported");
+  });
+});

package/appUtils/playerManager/__tests__/usePlayerContent.test.tsx

@@ -0,0 +1,64 @@
+import { renderHook, act } from "@testing-library/react-native";
+import { BehaviorSubject } from "rxjs";
+
+import { usePlayerContent } from "../usePlayerContent";
+
+const mockPlayer: any = {
+  subject: null as BehaviorSubject<any> | null,
+  getContent: jest.fn(),
+  getContentObservable: jest.fn(),
+};
+
+jest.mock("../usePlayer", () => ({
+  usePlayer: () => mockPlayer,
+}));
+
+describe("usePlayerContent", () => {
+  beforeEach(() => {
+    mockPlayer.subject = new BehaviorSubject({
+      title: "First Title",
+      summary: "First Summary",
+    });
+
+    mockPlayer.getContent = jest.fn(() => mockPlayer.subject.getValue());
+
+    mockPlayer.getContentObservable = jest.fn(() =>
+      mockPlayer.subject.asObservable()
+    );
+  });
+
+  it("returns the player's current content", () => {
+    const { result } = renderHook(() => usePlayerContent());
+
+    expect(result.current).toEqual({
+      title: "First Title",
+      summary: "First Summary",
+    });
+  });
+
+  it("re-renders when the player publishes new content", () => {
+    const { result } = renderHook(() => usePlayerContent());
+
+    act(() => {
+      mockPlayer.subject.next({
+        title: "Second Title",
+        summary: "Second Summary",
+      });
+    });
+
+    expect(result.current).toEqual({
+      title: "Second Title",
+      summary: "Second Summary",
+    });
+  });
+
+  it("unsubscribes on unmount", () => {
+    const { unmount } = renderHook(() => usePlayerContent());
+
+    expect(mockPlayer.subject.observed).toBe(true);
+
+    unmount();
+
+    expect(mockPlayer.subject.observed).toBe(false);
+  });
+});

package/appUtils/playerManager/__tests__/usePlayerControllerSetup.test.tsx

@@ -0,0 +1,62 @@
+import { renderHook } from "@testing-library/react-native";
+
+import { usePlayerControllerSetup } from "../usePlayerControllerSetup";
+import { PlayerAnalyticsManager } from "../../../analyticsUtils/PlayerAnalyticsManager";
+
+const calls: string[] = [];
+
+jest.mock("../index", () => ({
+  playerManager: {
+    isPlayerRegistered: jest.fn(() => false),
+    registerPlayer: jest.fn(() => calls.push("registerPlayer")),
+    unregisterPlayer: jest.fn(),
+  },
+}));
+
+jest.mock("../../../analyticsUtils/PlayerAnalyticsManager", () => ({
+  PlayerAnalyticsManager: {
+    getInstance: jest.fn(() => calls.push("analyticsManager")),
+  },
+}));
+
+jest.mock("../../../reactHooks/useConfiguration", () => ({
+  useConfiguration: () => ({}),
+}));
+
+jest.mock("../../../playerUtils/useValidatePlayerConfig", () => ({
+  useValidatePlayerConfig: jest.fn(),
+}));
+
+jest.mock("../../../reactUtils", () => ({
+  isTV: () => false,
+}));
+
+jest.mock(
+  "@applicaster/zapp-react-native-ui-components/Helpers/Platform",
+  () => ({
+    isAppleTV: () => false,
+  })
+);
+
+class Controller {
+  destroy = jest.fn();
+}
+
+describe("usePlayerControllerSetup", () => {
+  it("creates the analytics manager before the player registers", () => {
+    renderHook(() =>
+      usePlayerControllerSetup({
+        props: { playerId: "player-1", entry: { id: "entry-1" } },
+        ControllerType: Controller,
+        ref: null,
+        manifest: {},
+        pluginId: "plugin",
+      })
+    );
+
+    // The manager attaches analytics to players as they register, so a player
+    // registered before it exists would send no player analytics events
+    expect(PlayerAnalyticsManager.getInstance).toHaveBeenCalled();
+    expect(calls).toEqual(["analyticsManager", "registerPlayer"]);
+  });
+});

package/appUtils/playerManager/{conts.ts → const.ts}

@@ -59,6 +59,19 @@ export enum SharedPlayerCallBacksKeys {
   // PIP
   OnPlayerDetached = "onPlayerDetached",
   OnPlayerAttached = "onPlayerAttached",
+
+  OnRemoteCommand = "onRemoteCommand",
+}
+
+// Ids native sends in onRemoteCommand (lock screen / Control Center / CarPlay buttons)
+export enum RemoteCommand {
+  Play = "play",
+  Pause = "pause",
+  Stop = "stop",
+  NextTrack = "nextTrack",
+  PreviousTrack = "previousTrack",
+  SkipForward = "skipForward",
+  SkipBackward = "skipBackward",
 }
 
 export enum PlayerRole {
@@ -67,3 +80,23 @@ export enum PlayerRole {
   Chromecast = "Chromecast",
   Unspecified = "Unspecified",
 }
+
+/**
+ * The playback engine backing a web player. Published on
+ * `window.applicaster.playerType` when a player is created, so that plugins
+ * observing the player can tell which engine they are looking at instead of
+ * inferring it from the API the instance happens to expose.
+ *
+ * Keep in sync with `ApplicasterGlobals["playerType"]` in applicaster-types.
+ */
+export enum WebPlayerEngine {
+  Videojs = "videojs",
+  Hlsjs = "hlsjs",
+  Dashjs = "dashjs",
+}
+
+export enum PLAYER_EVENTS {
+  PlayNextTriggered = "play_next_triggered",
+}
+
+export type PlayNextTriggeredEvent = { id: string };

package/appUtils/playerManager/index.ts

@@ -9,8 +9,9 @@ import {
   unsubscribeToDeviceNetworkChanges,
 } from "@applicaster/quick-brick-core/App/NetworkStatusProvider/utils";
 import { setUserLanguagePreference } from "./userLanguagePreference";
-import { PlayerRole } from "./conts";
+import { PlayerRole } from "./const";
 import { RNPlayerManager } from "./nativePlayerManager";
+import { registerPlayerToolbox } from "./playerToolbox";
 
 const { log_error, log_debug, log_warning } = createLogger({
   category: "General",
@@ -54,6 +55,7 @@ export class PlayerManager {
   public static getInstance() {
     if (!PlayerManager.instance) {
       PlayerManager.instance = new PlayerManager();
+      registerPlayerToolbox(PlayerManager.instance);
     }
 
     return PlayerManager.instance;

package/appUtils/playerManager/player.ts

@@ -1,9 +1,22 @@
 import * as R from "ramda";
-import { BehaviorSubject } from "rxjs";
+import { BehaviorSubject, Observable } from "rxjs";
+import { distinctUntilChanged } from "rxjs/operators";
 import { isEmptyOrNil } from "@applicaster/zapp-react-native-utils/cellUtils";
 import { createLogger, utilsLogger } from "../../logger";
-import { getBoolFromConfigValue } from "../../configurationUtils";
-import { PlayerRole, SharedPlayerCallBacksKeys } from "./conts";
+import {
+  getBoolFromConfigValue,
+  imageSrcFromMediaItem,
+} from "../../configurationUtils";
+// Imported from the leaf modules rather than the `playerUtils` barrel: that
+// barrel imports `playerManager`, so going through it would create a require
+// cycle (playerManager/index -> player -> playerUtils/index -> playerManager).
+import {
+  resolvePlayerTitleSubtitle,
+  getPlayerContentDataKeys,
+} from "../../playerUtils/resolvePlayerTitleSubtitle";
+import { isAudioItem } from "../../playerUtils/isAudioItem";
+import { isTV } from "../../reactUtils";
+import { PlayerRole, SharedPlayerCallBacksKeys } from "./const";
 import { OverlaysObserver } from "./OverlayObserver/OverlaysObserver";
 import { TVSeekController } from "../../reactHooks/player/TVSeekControlller/TVSeekController";
 
@@ -19,6 +32,23 @@ export declare type PlayerControllerListenerData = {
   id: string;
   listener: QuickBrickPlayer.SharedPlayerCallBacks;
 };
+
+/**
+ * The player's resolved Title/Subtitle text, published by the player the same
+ * way duration and progress are. Consumers render these values as-is rather
+ * than reading `entry` or the plugin configuration themselves.
+ */
+export type PlayerContent = {
+  title: Option<string | number>;
+  summary: Option<string | number>;
+  /**
+   * Cover art for the content currently playing. Published alongside the text
+   * (rather than read from `entry` by whoever needs it) so it follows the same
+   * entry: on live audio that means the programme's own artwork, refreshed
+   * with every feed poll, instead of the channel's.
+   */
+  imageUrl: Option<string>;
+};
 /**
  * Player Instance Controller
  * Instance exposes utility methods that will help set or get state
@@ -45,6 +75,7 @@ export class Player {
   readonly playerRole: PlayerRole = PlayerRole.Unspecified;
   private overlaysObserver?: OverlaysObserver | null;
   private entryObservable?: BehaviorSubject<ZappEntry> | null;
+  private contentSubject?: BehaviorSubject<PlayerContent> | null;
 
   protected listeners: {
     [key: string]: QuickBrickPlayer.SharedPlayerCallBacks;
@@ -58,7 +89,17 @@ export class Player {
 
   set entry(newEntry: ZappEntry | null) {
     this._entry = newEntry;
+    // The live entry is scoped to the entry it overlays - see
+    // `OverlaysObserver.clearLiveEntry`. No-op when there is no observer,
+    // which is every non-live player.
+    this.overlaysObserver?.clearLiveEntry();
     this.entryObservable?.next(newEntry);
+    // Optional chaining short-circuits the whole call expression, so
+    // `getContent()` is NOT evaluated while no subscriber exists. That
+    // matters: `PlayerNative` assigns `this.entry` in its constructor, before
+    // subclass arrow-function properties such as `getPluginConfiguration`
+    // have been assigned.
+    this.contentSubject?.next(this.getContent());
   }
 
   constructor(props) {
@@ -117,6 +158,77 @@ export class Player {
     return this.entryObservable;
   };
 
+  /**
+   * The player's resolved Title/Subtitle.
+   *
+   * Resolved on demand rather than cached: the plugin configuration arrives
+   * asynchronously on both the native and cast paths, so a value computed once
+   * at entry-set time would be stale for whichever arrives first.
+   *
+   * Every fallback (no config, empty/whitespace key, unresolvable key, key
+   * resolving to an empty string or to a non-string/non-number) lives in
+   * `resolvePlayerContentText` and is never reimplemented here.
+   */
+  getContent = (): PlayerContent => {
+    // Live audio keeps playing one channel while the programme on air
+    // changes, so the observer's freshly-loaded programme entry wins when
+    // there is one. Read through `?.` so this never constructs an observer:
+    // a VOD or cast player has none and falls straight through to its entry.
+    const entry = this.overlaysObserver?.liveEntry ?? this.entry;
+
+    return {
+      ...resolvePlayerTitleSubtitle({
+        entry,
+        pluginConfiguration: this.getPluginConfiguration(),
+        dataKeys: getPlayerContentDataKeys({
+          isTV: isTV(),
+          isAudioContent: isAudioItem(entry),
+        }),
+      }),
+      // Same selection Android's `EntryHelpers.extractCoverImage` makes:
+      // prefer the `image_base` media item, otherwise the first one available.
+      // Reused rather than reimplemented so the two platforms cannot drift.
+      imageUrl: entry ? imageSrcFromMediaItem(entry, []) : undefined,
+    };
+  };
+
+  /**
+   * Created lazily, like `entryObservable`. An eagerly created subject would
+   * resolve during `PlayerNative`'s constructor and call a not-yet-assigned
+   * `getPluginConfiguration`.
+   *
+   * The seed is produced by calling the resolver, never from raw entry fields:
+   * a `BehaviorSubject` replays its seed synchronously on subscribe, so a raw
+   * seed would overwrite correctly-resolved text at mount.
+   */
+  getContentObservable = (): Observable<PlayerContent> => {
+    if (!this.contentSubject) {
+      this.contentSubject = new BehaviorSubject<PlayerContent>(
+        this.getContent()
+      );
+    }
+
+    return this.contentSubject.asObservable().pipe(
+      // `resolvePlayerTitleSubtitle` returns a fresh object every call, so
+      // reference equality would never dedupe. Compare by value.
+      distinctUntilChanged(
+        (previous, next) =>
+          previous.title === next.title &&
+          previous.summary === next.summary &&
+          previous.imageUrl === next.imageUrl
+      )
+    );
+  };
+
+  /**
+   * Re-resolves and publishes the current content. Called when something the
+   * resolution depends on changed without `entry` itself being reassigned -
+   * today that is the observer swapping in a newly-loaded live programme.
+   */
+  publishContent = () => {
+    this.contentSubject?.next(this.getContent());
+  };
+
   /**
    * ---------------------------------------- PLAYER SETTERS GETTERS ----------------------------------------
    * These methods let you get information about the content / ad playing
@@ -634,6 +746,13 @@ export class Player {
     });
   };
 
+  onRemoteCommand = (event: QuickBrickPlayer.RemoteCommandEvent) => {
+    this.invokeListenersUpdate({
+      callbackName: SharedPlayerCallBacksKeys.OnRemoteCommand,
+      event,
+    });
+  };
+
   getTracksState = (): QuickBrickPlayer.TracksState =>
     this.playerState.trackState;
 
@@ -711,6 +830,8 @@ export class Player {
     // PIP
     onPlayerDetached: this.onPlayerDetached,
     onPlayerAttached: this.onPlayerAttached,
+
+    onRemoteCommand: this.onRemoteCommand,
   });
 
   play = () => {};
@@ -720,6 +841,7 @@ export class Player {
   setPlaybackRate = (_rate) => {};
   startSleepTimer = (_timestamp) => {};
   cancelSleepTimer = () => {};
+  command = (_command: string, _userInfo?: Record<string, any>) => {};
 
   getPluginConfiguration = () => null;
   appStateChange = (_appState, _previousAppState) => {};

package/appUtils/playerManager/playerFactory.ts

@@ -1,7 +1,7 @@
 import { appStore } from "@applicaster/zapp-react-native-redux/AppStore";
 import { findPluginByIdentifier } from "@applicaster/zapp-react-native-utils/pluginUtils";
 import { Player } from "./player";
-import { PlayerRole } from "./conts";
+import { PlayerRole } from "./const";
 
 type PlayerFactoryItem = {
   Component: any;

package/appUtils/playerManager/playerNative.ts

@@ -3,9 +3,10 @@ import { isEmptyOrNil } from "@applicaster/zapp-react-native-utils/cellUtils";
 import { createLogger, utilsLogger } from "../../logger";
 import { Player } from "./player";
 import { findNodeHandle } from "react-native";
-import { PlayerRole } from "./conts";
+import { PlayerRole } from "./const";
 import { toBooleanWithDefaultFalse } from "../../booleanUtils";
 import { RNPlayerManager } from "./nativePlayerManager";
+import { isApplePlatform } from "../../reactUtils";
 
 const logger = createLogger({
   category: "PlayerNativeController",
@@ -27,6 +28,7 @@ interface PlayerMethods {
   appStateChange?: (appState: string, previousAppState: string) => void;
   closeNativePlayer?: () => void;
   togglePlayPause?: () => void;
+  command?: (command: string, userInfo?: Record<string, any>) => void;
 }
 
 type PlayerComponent = ReactComponent<PlayerRefProps> & PlayerMethods;
@@ -52,6 +54,7 @@ const PlayerModuleFuncNames = {
   startSleepTimer: "startSleepTimer",
   cancelSleepTimer: "cancelSleepTimer",
   getSleepTimerEnd: "getSleepTimerEnd",
+  command: "command",
 };
 
 export class PlayerNative extends Player {
@@ -206,6 +209,25 @@ export class PlayerNative extends Player {
     }
   };
 
+  command = (command: string, userInfo?: Record<string, any>) => {
+    if (isApplePlatform()) {
+      const module = this.getPlayerModule();
+      module?.command?.(command, this.playerId, userInfo);
+
+      return true;
+    }
+
+    if (
+      !this.invokeNativeFunction(
+        PlayerModuleFuncNames.command,
+        command,
+        userInfo
+      )
+    ) {
+      this.currentPlayerComponent()?.command?.(command, userInfo);
+    }
+  };
+
   disableBufferAnimation = (): boolean => false;
 
   selectTrack = (
@@ -296,9 +318,11 @@ export class PlayerNative extends Player {
     }, listeners);
   };
 
-  isAudioItem = () =>
-    this.getEntry()?.content?.type?.includes?.("audio") ||
-    this.getEntry()?.type?.value === "audio";
+  isAudioItem = (): boolean =>
+    Boolean(
+      this.getEntry()?.content?.type?.includes?.("audio") ||
+        this.getEntry()?.type?.value?.includes?.("audio")
+    );
 
   isFullScreenSupported = (): boolean => {
     const config = this.getConfig();

package/appUtils/playerManager/playerNativeCommand.ts

@@ -1,14 +1,11 @@
 import { isApplePlatform } from "../../reactUtils";
 import { NativeModules } from "react-native";
 
-const NativePlayerModule = isApplePlatform()
-  ? NativeModules.PlayerModule
-  : NativeModules.QuickBrickDefaultPlayerModule;
-
 const PlayerNativeCommandTypes = {
   pause: "pause",
   clearPlayerData: "clearPlayerData",
   removeViewByNativeId: "removeViewByNativeId",
+  setPlayerControls: "setPlayerControls",
 };
 
 const PlayerNativeSendCommand = (
@@ -16,8 +13,8 @@ const PlayerNativeSendCommand = (
   playerId: string,
   userInfo?: Record<string, any>
 ) => {
-  if (playerId && command) {
-    NativePlayerModule?.command?.(command, playerId, userInfo);
+  if (isApplePlatform() && playerId && command) {
+    NativeModules.PlayerModule?.command?.(command, playerId, userInfo);
   }
 };