@applicaster/zapp-react-native-utils 16.0.0-rc.71 → 16.0.0-rc.73

package/playerUtils/index.ts

@@ -7,7 +7,23 @@ import { isTV } from "@applicaster/zapp-react-native-utils/reactUtils";
 import { getBoolFromConfigValue } from "../configurationUtils";
 import { Dimensions } from "react-native";
 
-export { getPlayerActionButtons } from "./getPlayerActionButtons";
+export { resolvePlayerActions } from "./resolvePlayerActions";
+
+export { isEntryAction } from "../entryActions";
+
+export {
+  parseActionIdentifiers,
+  resolveActionIdentifiers,
+} from "../uiActionsRegistrator";
+
+export type { ResolveActionIdentifiersParams } from "../uiActionsRegistrator";
+
+export type {
+  ActionButtonDescriptor,
+  OverflowDescriptor,
+  PlayerControlDescriptor,
+  ResolvePlayerActionsParams,
+} from "./resolvePlayerActions";
 
 export {
   resolvePlayerContentText,

package/playerUtils/resolvePlayerActions.ts

@@ -0,0 +1,71 @@
+import { selectActionButtons } from "../conf/player/selectors";
+import {
+  usableActionItems,
+  RegisteredAction,
+  resolveActionIdentifiers,
+} from "../uiActionsRegistrator";
+
+export type ResolvePlayerActionsParams = {
+  configuration: any;
+  entry: ZappEntry | ZappFeed;
+  /** Expands the `entry_actions` token; see `resolveActionIdentifiers`. */
+  expandEntryActions?: (entry: ZappEntry | ZappFeed) => RegisteredAction[];
+};
+
+/**
+ * The player's action buttons, resolved against the entry.
+ *
+ * Every `player_action_buttons` token goes through `uiActionsRegistry`, except
+ * `entry_actions`, which the caller expands from the entry itself. The list is
+ * not capped; the overlay decides how many fit and sends the rest to the sheet.
+ */
+export function resolvePlayerActions({
+  configuration,
+  entry,
+  expandEntryActions,
+}: ResolvePlayerActionsParams): RegisteredAction[] {
+  const buttonsString = selectActionButtons(configuration);
+
+  if (!buttonsString) {
+    return [];
+  }
+
+  // Deduped at the source: `player_action_buttons` is a hand-typed string, so
+  // the same identifier can legitimately appear twice. Left alone, a repeat
+  // would be counted twice against the inline limit, rendered twice on the
+  // overlay, and collide as a React key. Items with no `invokeAction` are
+  // dropped here too - they can never do anything.
+  return usableActionItems(
+    resolveActionIdentifiers({
+      identifiers: buttonsString,
+      entry,
+      expandEntryActions,
+    })
+  );
+}
+
+/** One control on the player overlay, before overflow is applied. */
+export type ActionButtonDescriptor =
+  | { kind: "subtitle" }
+  | { kind: "close" }
+  | { kind: "airplay" }
+  | { kind: "action"; action: RegisteredAction };
+
+/**
+ * The Overflow control, produced by `splitOverflow` when more content actions
+ * resolve than fit on the overlay.
+ */
+export type OverflowDescriptor = {
+  kind: "overflow";
+  /**
+   * Every content action, the overlay companion included. An overlay button
+   * renders nothing when its action has no icon, so the companion needs the
+   * sheet as a second home or it could be reachable from nowhere.
+   */
+  additionalActions: RegisteredAction[];
+};
+
+/** What the overlay actually renders, once overflow has been applied. */
+export type PlayerControlDescriptor =
+  | ActionButtonDescriptor
+  | OverflowDescriptor;

package/reactHooks/actions/index.ts

@@ -6,6 +6,7 @@ import { ActionsContext } from "@applicaster/zapp-react-native-ui-components/Con
 import {
   observeEntryState,
   RegisteredActionValue,
+  uiActionsRegistry,
 } from "../../uiActionsRegistrator";
 import { reactHooksLogger } from "../logger";
 
@@ -34,7 +35,13 @@ export function useActions<T = unknown>(plugId: string): any {
       if (!logged) {
         logger.warning({
           message: `useActions: Couldn't find an action for ${plugId} plugin`,
-          data: { actions: context?.actions },
+          // Identifiers only. The action map holds every plugin's module and
+          // live React context, which is far too large for a log line and can
+          // carry whatever state those plugins hold.
+          data: {
+            plugId,
+            availableActions: Object.keys(context?.actions ?? {}),
+          },
         });
 
         setLogged(true);
@@ -80,7 +87,31 @@ export function useEntryActionState(
   useEffect(() => {
     if (!action) return undefined;
 
-    const subscription = observeEntryState(action, entry).subscribe(setState);
+    // An action's stream is third-party code. Subscribing with only a `next`
+    // handler lets RxJS rethrow an error notification asynchronously, where no
+    // error boundary catches it - one plugin faulting would take the app down
+    // rather than this one button. The button keeps its last known state.
+    let subscription;
+
+    try {
+      subscription = observeEntryState(action, entry).subscribe({
+        next: setState,
+        error: (error) =>
+          logger.warning({
+            message:
+              "useEntryActionState: the action's state stream failed - the button keeps its last state",
+            data: { entryId, error },
+          }),
+      });
+    } catch (error) {
+      logger.warning({
+        message:
+          "useEntryActionState: could not observe the action - the button keeps its initial state",
+        data: { entryId, error },
+      });
+
+      return undefined;
+    }
 
     return () => subscription.unsubscribe();
     // eslint-disable-next-line @wogns3623/better-exhaustive-deps/exhaustive-deps
@@ -88,6 +119,18 @@ export function useEntryActionState(
 
   const invokeAction = useCallback(
     (options: InvokeArgsOptions = {}) => {
+      if (typeof action?.invokeAction !== "function") {
+        // A button was rendered and pressed, and the press goes nowhere. Only
+        // reachable on a user interaction, so it costs nothing on render. The
+        // action value carries no identifier, so the label is what locates the
+        // button that misbehaved.
+        logger.warning({
+          message:
+            "useEntryActionState: the pressed action has no invokeAction - the press did nothing",
+          data: { entryId, label: state?.label },
+        });
+      }
+
       action?.invokeAction?.(entry, { updateState: setState, ...options });
     },
     // eslint-disable-next-line @wogns3623/better-exhaustive-deps/exhaustive-deps
@@ -96,3 +139,25 @@ export function useEntryActionState(
 
   return { state, invokeAction };
 }
+
+/**
+ * A value that changes whenever a provider is added to or removed from
+ * `uiActionsRegistry`.
+ *
+ * Providers can register after the UI that wants them has rendered - the audio
+ * player registers playback speed only once its controller has state, and
+ * plugin-backed actions are bridged in from an effect. Put this in the
+ * dependency list of anything that resolves actions, so the list is re-read
+ * instead of being frozen at first paint.
+ */
+export function useRegistryRevision(): number {
+  const [revision, setRevision] = useState(0);
+
+  useEffect(
+    () =>
+      uiActionsRegistry.subscribe(() => setRevision((current) => current + 1)),
+    []
+  );
+
+  return revision;
+}

package/uiActionsRegistrator/__tests__/resolveActionIdentifiers.test.ts

@@ -0,0 +1,93 @@
+import {
+  parseActionIdentifiers,
+  resolveActionIdentifiers,
+} from "../resolveActionIdentifiers";
+import { uiActionsRegistry } from "../registry";
+
+const action = (identifier: string) =>
+  ({ identifier, action: { invokeAction: jest.fn() } }) as any;
+
+describe("parseActionIdentifiers", () => {
+  it("parses comma-separated identifiers", () => {
+    expect(parseActionIdentifiers(" a, b , ,c ")).toEqual(["a", "b", "c"]);
+  });
+
+  it("parses identifier arrays", () => {
+    expect(parseActionIdentifiers([" a ", "", "b", "  ", "c"])).toEqual([
+      "a",
+      "b",
+      "c",
+    ]);
+  });
+
+  it("returns empty array for nil config", () => {
+    expect(parseActionIdentifiers(null)).toEqual([]);
+    expect(parseActionIdentifiers(undefined)).toEqual([]);
+  });
+});
+
+describe("resolveActionIdentifiers", () => {
+  const entry = { id: "entry-1" } as any;
+
+  beforeEach(() => {
+    jest
+      .spyOn(uiActionsRegistry, "getActions")
+      .mockImplementation((identifier) => [action(identifier)] as any);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it("resolves through registry by default", () => {
+    const result = resolveActionIdentifiers({
+      identifiers: "favorites,share",
+      entry,
+    });
+
+    expect(result.map((item) => item.identifier)).toEqual([
+      "favorites",
+      "share",
+    ]);
+
+    expect(uiActionsRegistry.getActions).toHaveBeenCalledWith(
+      "favorites",
+      entry
+    );
+
+    expect(uiActionsRegistry.getActions).toHaveBeenCalledWith("share", entry);
+  });
+
+  it("expands entry_actions through the caller, not the registry", () => {
+    const expanded = [action("entry_action_0"), action("entry_action_1")];
+    const expandEntryActions = jest.fn(() => expanded);
+
+    const unregister = uiActionsRegistry.registerAction("share", {
+      invokeAction: jest.fn(),
+    });
+
+    try {
+      const result = resolveActionIdentifiers({
+        identifiers: "entry_actions,share",
+        entry,
+        expandEntryActions,
+      });
+
+      expect(expandEntryActions).toHaveBeenCalledWith(entry);
+
+      expect(result.map((item) => item.identifier)).toEqual([
+        "entry_action_0",
+        "entry_action_1",
+        "share",
+      ]);
+    } finally {
+      unregister();
+    }
+  });
+
+  it("resolves nothing for entry_actions when the caller cannot expand it", () => {
+    expect(
+      resolveActionIdentifiers({ identifiers: "entry_actions", entry })
+    ).toEqual([]);
+  });
+});

package/uiActionsRegistrator/__tests__/subscribe.test.ts

@@ -0,0 +1,107 @@
+import { isActionAvailableFor, uiActionsRegistry } from "../registry";
+
+const value = { invokeAction: jest.fn() };
+
+describe("uiActionsRegistry.subscribe", () => {
+  it("fires on registration and on unregistration", () => {
+    const listener = jest.fn();
+    const unsubscribe = uiActionsRegistry.subscribe(listener);
+
+    const unregister = uiActionsRegistry.registerAction("late-action", value);
+
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    unregister();
+
+    expect(listener).toHaveBeenCalledTimes(2);
+
+    unsubscribe();
+  });
+
+  it("lets a listener see the action it was told about", () => {
+    let seen: string[] = [];
+
+    const unsubscribe = uiActionsRegistry.subscribe(() => {
+      seen = uiActionsRegistry
+        .getActions("late-action", { id: "e1" } as any)
+        .map((item) => item.identifier);
+    });
+
+    const unregister = uiActionsRegistry.registerAction("late-action", value);
+
+    expect(seen).toEqual(["late-action"]);
+
+    unregister();
+    unsubscribe();
+  });
+
+  it("stops calling a listener once unsubscribed", () => {
+    const listener = jest.fn();
+
+    uiActionsRegistry.subscribe(listener)();
+
+    uiActionsRegistry.registerAction("another-action", value)();
+
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it("survives a listener that unsubscribes itself while being notified", () => {
+    const other = jest.fn();
+
+    const unsubscribeOther = uiActionsRegistry.subscribe(other);
+
+    const unsubscribeSelf = uiActionsRegistry.subscribe(() => {
+      unsubscribeSelf();
+    });
+
+    expect(() =>
+      uiActionsRegistry.registerAction("self-removing", value)()
+    ).not.toThrow();
+
+    expect(other).toHaveBeenCalled();
+
+    unsubscribeOther();
+  });
+});
+
+describe("isActionAvailableFor", () => {
+  const entry = { id: "e1" } as any;
+
+  it("shows an action that states no opinion", () => {
+    expect(isActionAvailableFor({ invokeAction: jest.fn() }, entry)).toBe(true);
+  });
+
+  it.each([
+    ["isSupportDownloads"],
+    ["isActionSupported"],
+    ["isActionAvailable"],
+  ])("honours %s", (predicate) => {
+    expect(
+      isActionAvailableFor(
+        { invokeAction: jest.fn(), [predicate]: () => false } as any,
+        entry
+      )
+    ).toBe(false);
+  });
+
+  it("asks only the first predicate the action defines", () => {
+    const isActionAvailable = jest.fn(() => true);
+
+    expect(
+      isActionAvailableFor(
+        {
+          invokeAction: jest.fn(),
+          isSupportDownloads: () => false,
+          isActionAvailable,
+        } as any,
+        entry
+      )
+    ).toBe(false);
+
+    expect(isActionAvailable).not.toHaveBeenCalled();
+  });
+
+  it("treats a missing action as unavailable-free", () => {
+    expect(isActionAvailableFor(undefined, entry)).toBe(true);
+  });
+});

package/uiActionsRegistrator/__tests__/usableActionItems.test.ts

@@ -0,0 +1,52 @@
+import { usableActionItems } from "../usableActionItems";
+
+const action = (identifier: string) =>
+  ({ identifier, action: { invokeAction: jest.fn() } }) as any;
+
+describe("usableActionItems", () => {
+  it("keeps a usable list untouched, in order", () => {
+    const base = [action("share"), action("favorites")];
+
+    expect(usableActionItems(base).map((item) => item.identifier)).toEqual([
+      "share",
+      "favorites",
+    ]);
+  });
+
+  it("keeps the first of a repeated identifier", () => {
+    const firstShare = action("share");
+    const secondShare = action("share");
+
+    const result = usableActionItems([
+      firstShare,
+      action("favorites"),
+      secondShare,
+    ]);
+
+    expect(result.map((item) => item.identifier)).toEqual([
+      "share",
+      "favorites",
+    ]);
+
+    expect(result[0]).toBe(firstShare);
+  });
+
+  it("drops items that cannot be invoked or have no identifier", () => {
+    const result = usableActionItems([
+      action("share"),
+      { identifier: "blank" } as any,
+      { identifier: "no-invoke", action: {} } as any,
+      { action: { invokeAction: jest.fn() } } as any,
+      action("entry_action_0"),
+    ]);
+
+    expect(result.map((item) => item.identifier)).toEqual([
+      "share",
+      "entry_action_0",
+    ]);
+  });
+
+  it("tolerates a missing list", () => {
+    expect(usableActionItems(undefined as any)).toEqual([]);
+  });
+});

package/uiActionsRegistrator/index.ts

@@ -1,203 +1,25 @@
-/* eslint-disable no-dupe-class-members */
-import { Observable } from "rxjs";
-import { createLogger } from "../logger";
-
-const { log_debug, log_warning, log_verbose } = createLogger({
-  subsystem: "UIActionsRegistry",
-  category: "ActionRegistration",
-});
-
-/**
- * The runtime value of a UI action.
- *
- * This is the object that consumers interact with (render buttons for,
- * invoke on press, read initial state from, etc.). It intentionally keeps an
- * open shape (`[K: string]: any`) so that both the modern registry-based
- * actions and the legacy context-provider based actions can be represented by
- * the same structure.
- */
-export type RegisteredActionValue = {
-  state?: any;
-  getInitialState?: () => Promise<void>;
-  initialEntryState?: (item: ZappEntry | ZappFeed) => CellActionEntryState;
-  invokeAction: (
-    item: ZappEntry | ZappFeed,
-    options?: InvokeArgsOptions
-  ) => void;
-  isActionAvailable?: (item: ZappEntry | ZappFeed) => boolean;
-  addListener?: (
-    entryId: string,
-    listener: CellActionStateListenerFunction
-  ) => CellActionStateRemoveListenerFunction;
-  /**
-   * Optional RX stream of the action state for a given entry. When not
-   * provided, `observeEntryState` derives one from `initialEntryState` +
-   * `addListener` (see below).
-   */
-  observeEntryState?: (
-    entry: ZappEntry | ZappFeed
-  ) => Observable<CellActionEntryState>;
-  [K: string]: any;
-};
-
-export type RegisteredAction = {
-  identifier: string; // Plugin identifier or synthetic name
-  action: RegisteredActionValue;
-};
-
-/**
- * A function that, given an optional context (currently just the `entry`),
- * returns the list of actions it wants to contribute.
- *
- * Returning an array is what allows a single provider (plugin or otherwise) to
- * expose more than one action, and to compute those actions based on the entry.
- */
-export type UIActionProvider = (params: {
-  entry?: ZappEntry | ZappFeed;
-}) => RegisteredAction[];
-
-/**
- * Returns an RX `Observable` that emits the action state for `entry`.
- *
- * If the action already exposes its own `observeEntryState`, it is used as-is.
- * Otherwise we build the stream from the legacy imperative API:
- *  - it immediately emits `initialEntryState(entry)` (if available), and
- *  - it subscribes to further changes via `addListener(entryId, listener)`,
- *    unsubscribing automatically when the observable is torn down.
- *
- * This lets every action - old or new - be consumed reactively through a single
- * mechanism, without each consumer having to wire up `addListener` manually.
- */
-export function observeEntryState(
-  action: RegisteredActionValue | undefined,
-  entry: ZappEntry | ZappFeed
-): Observable<CellActionEntryState> {
-  if (typeof action?.observeEntryState === "function") {
-    return action.observeEntryState(entry);
-  }
-
-  return new Observable<CellActionEntryState>((subscriber) => {
-    const initialState = action?.initialEntryState?.(entry);
-
-    if (initialState !== undefined) {
-      subscriber.next(initialState);
-    }
-
-    const removeListener = action?.addListener?.(
-      String((entry as ZappEntry)?.id),
-      (state: CellActionEntryState) => subscriber.next(state)
-    );
-
-    return () => removeListener?.();
-  });
-}
-
-class UIActionsRegistry {
-  private registeredActions: Record<string, UIActionProvider> = {};
-
-  /**
-   * Register a dynamic action provider under a unique `name`.
-   * The provider can return one or more actions and may use the passed `entry`.
-   * Returns an unregister function.
-   */
-  registerActionProvider(
-    name: string,
-    actionProvider: UIActionProvider
-  ): () => void {
-    const isOverride = Boolean(this.registeredActions[name]);
-
-    if (isOverride) {
-      log_warning(
-        `registerActionProvider: overriding existing provider for "${name}"`,
-        { name }
-      );
-    } else {
-      log_debug(`registerActionProvider: registered "${name}"`, { name });
-    }
-
-    this.registeredActions[name] = actionProvider;
-
-    return () => {
-      // Only remove if it's still the same provider to avoid races where a
-      // newer registration replaced this one.
-      if (this.registeredActions[name] === actionProvider) {
-        delete this.registeredActions[name];
-        log_debug(`registerActionProvider: unregistered "${name}"`, { name });
-      } else {
-        log_debug(
-          `registerActionProvider: skipped unregister for "${name}" – newer provider is active`,
-          { name }
-        );
-      }
-    };
-  }
-
-  /**
-   * Convenience helper to register a single, static action from anywhere in the
-   * app (it does not need to be a plugin). Returns an unregister function.
-   */
-  registerAction(
-    identifier: string,
-    action: RegisteredActionValue
-  ): () => void {
-    log_debug(`registerAction: registering single action "${identifier}"`, {
-      identifier,
-    });
-
-    return this.registerActionProvider(identifier, () => [
-      { identifier, action },
-    ]);
-  }
-
-  getEntryActions(entry: ZappEntry): RegisteredAction[] {
-    const results = Object.keys(this.registeredActions)
-      .map((key) => this.registeredActions[key]({ entry }))
-      .flatMap((a) => a);
-
-    log_verbose(
-      `getEntryActions: resolved ${results.length} action(s) for entry "${entry?.id}"`,
-      { entryId: entry?.id, identifiers: results.map((r) => r.identifier) }
-    );
-
-    return results;
-  }
-
-  getActions(name: string, entry?: ZappEntry | ZappFeed): RegisteredAction[] {
-    if (!this.registeredActions[name]) {
-      log_warning(`getActions: no provider found for "${name}"`, { name });
-
-      return [];
-    }
-
-    const results = this.registeredActions[name]({ entry }) ?? [];
-
-    log_verbose(
-      `getActions: resolved ${results.length} action(s) for "${name}"`,
-      {
-        name,
-        entryId: (entry as ZappEntry)?.id,
-        identifiers: results.map((r) => r.identifier),
-      }
-    );
-
-    return results;
-  }
-
-  /**
-   * Returns the runtime value of the first action registered under `name`, or
-   * `undefined`. This mirrors the shape returned by the legacy `useActions`
-   * hook, easing migration of single-action consumers.
-   */
-  getAction(
-    name: string,
-    entry?: ZappEntry | ZappFeed
-  ): RegisteredActionValue | undefined {
-    return this.getActions(name, entry)[0]?.action;
-  }
-
-  hasAction(name: string): boolean {
-    return Boolean(this.registeredActions[name]);
-  }
-}
-
-export const uiActionsRegistry = new UIActionsRegistry();
+export {
+  canRenderActionIcon,
+  resolveActionAsset,
+  isActionAvailableFor,
+  observeEntryState,
+  uiActionsRegistry,
+} from "./registry";
+
+export type {
+  RegisteredAction,
+  RegisteredActionSource,
+  RegisteredActionValue,
+  RegistryChangeListener,
+  UIActionProvider,
+} from "./registry";
+
+export { usableActionItems } from "./usableActionItems";
+
+export {
+  ENTRY_ACTIONS_IDENTIFIER,
+  parseActionIdentifiers,
+  resolveActionIdentifiers,
+} from "./resolveActionIdentifiers";
+
+export type { ResolveActionIdentifiersParams } from "./resolveActionIdentifiers";