@applicaster/zapp-react-native-utils 16.0.0-rc.70 → 16.0.0-rc.72

package/uiActionsRegistrator/registry.ts

@@ -0,0 +1,245 @@
+/* eslint-disable no-dupe-class-members */
+import { Observable } from "rxjs";
+import { createLogger } from "../logger";
+
+const { log_debug, log_warning } = 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;
+};
+
+/**
+ * Where an action came from.
+ *
+ * `"entry"` marks actions inflated from `entry.extensions.entry_action`, which
+ * exist only for the entry being shown. Consumers that rank actions - the
+ * player picks a non-entry action as the overflow companion when it can - read
+ * this instead of pattern-matching the identifier.
+ */
+export type RegisteredActionSource = "entry";
+
+export type RegisteredAction = {
+  identifier: string; // Plugin identifier or synthetic name
+  action: RegisteredActionValue;
+  source?: RegisteredActionSource;
+};
+
+/**
+ * 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?.();
+  });
+}
+
+/** Called whenever a provider is added to or removed from the registry. */
+export type RegistryChangeListener = () => void;
+
+/**
+ * Whether an action wants to be shown for this entry.
+ *
+ * Plugins express this through one of three historical names; the first one
+ * they define answers, and an action that defines none is always shown. It
+ * lives here so that every surface - the player overlay, the bottom sheet, a
+ * cell - gives the same answer for the same action. Two surfaces disagreeing
+ * means an action the user can reach from one place and not another.
+ */
+export function isActionAvailableFor(
+  action: RegisteredActionValue | undefined,
+  entry: ZappEntry | ZappFeed
+): boolean {
+  const predicate =
+    action?.isSupportDownloads ??
+    action?.isActionSupported ??
+    action?.isActionAvailable;
+
+  return typeof predicate === "function" ? Boolean(predicate(entry)) : true;
+}
+
+class UIActionsRegistry {
+  private registeredActions: Record<string, UIActionProvider> = {};
+
+  private changeListeners: RegistryChangeListener[] = [];
+
+  /**
+   * Subscribes to provider registrations and unregistrations.
+   *
+   * Providers can appear after the UI that wants them has already rendered -
+   * the audio player registers playback speed only once its controller has
+   * state - so consumers need to be told rather than poll for it.
+   *
+   * Returns an unsubscribe function.
+   */
+  subscribe(listener: RegistryChangeListener): () => void {
+    this.changeListeners.push(listener);
+
+    return () => {
+      this.changeListeners = this.changeListeners.filter(
+        (registered) => registered !== listener
+      );
+    };
+  }
+
+  private notifyChanged(): void {
+    // Copied so a listener that unsubscribes itself does not disturb this pass.
+    this.changeListeners.slice().forEach((listener) => listener());
+  }
+
+  /**
+   * 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;
+    this.notifyChanged();
+
+    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 });
+        this.notifyChanged();
+      } 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 {
+    return this.registerActionProvider(identifier, () => [
+      { identifier, action },
+    ]);
+  }
+
+  getActions(name: string, entry?: ZappEntry | ZappFeed): RegisteredAction[] {
+    if (!this.registeredActions[name]) {
+      // Not necessarily a misconfiguration: consumers legitimately probe for
+      // providers that register late - the audio player asks for its own
+      // playback-speed action before the controller has state. Only the layer
+      // that knows the identifier was *configured* can call this a fault, so
+      // `resolveActionIdentifiers` is where that warning lives.
+      log_debug(`getActions: no provider registered for "${name}"`, { name });
+
+      return [];
+    }
+
+    // Resolution runs on every render of every surface that shows actions, so
+    // there is deliberately no log of the resolved list here.
+    return this.registeredActions[name]({ entry }) ?? [];
+  }
+
+  /**
+   * 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();

package/uiActionsRegistrator/resolveActionIdentifiers.ts

@@ -0,0 +1,100 @@
+import { createLogger } from "../logger";
+
+import { RegisteredAction, uiActionsRegistry } from "./registry";
+
+const { log_warning } = createLogger({
+  subsystem: "UIActionsRegistry",
+  category: "ActionRegistration",
+});
+
+/** Identifier that stands for "whatever this entry declares", not a provider. */
+export const ENTRY_ACTIONS_IDENTIFIER = "entry_actions";
+
+export type ResolveActionIdentifiersParams = {
+  identifiers: string | string[];
+  entry: ZappEntry | ZappFeed;
+  /**
+   * Expands the `entry_actions` token.
+   *
+   * The registry maps an identifier to a provider, which is the right shape for
+   * a plugin: one installation, one implementation, looked up by id. Entry
+   * actions are not that - they are data on the entry being shown, and their
+   * execution context belongs to whoever is showing it. So the caller expands
+   * them, rather than the registry holding one global provider whose context
+   * was captured wherever it happened to be registered.
+   */
+  expandEntryActions?: (entry: ZappEntry | ZappFeed) => RegisteredAction[];
+};
+
+/**
+ * Identifiers already reported as having no provider.
+ *
+ * Resolution runs on every render of every surface that shows actions, so one
+ * uninstalled plugin would otherwise repeat its warning forever. An identifier
+ * is forgotten again as soon as it does resolve, so a provider that appears
+ * late and later disappears is still reported.
+ */
+const reportedMissingProviders = new Set<string>();
+
+export function parseActionIdentifiers(
+  config?: string | string[] | null
+): string[] {
+  // Deliberately not using the `utils` barrel: this module sits underneath the
+  // registry, and pulling that barrel in creates an import cycle.
+  if (config === null || config === undefined) {
+    return [];
+  }
+
+  return (Array.isArray(config) ? config : config.split(","))
+    .map((identifier) => identifier.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Resolves a *configured* list of action identifiers against the registry.
+ *
+ * Everything reaching this function was typed into an app configuration
+ * (`player_action_buttons`, `modal_bottom_sheet_actions`), so an identifier
+ * with no provider at all means a button the app was configured to show will
+ * not appear - a typo, or a plugin that is not installed. A provider that runs
+ * and returns nothing is a different matter: that is the action opting out for
+ * this entry, which is expected and stays silent.
+ */
+export function resolveActionIdentifiers({
+  identifiers,
+  entry,
+  expandEntryActions,
+}: ResolveActionIdentifiersParams): RegisteredAction[] {
+  return parseActionIdentifiers(identifiers).flatMap((identifier) => {
+    if (identifier === ENTRY_ACTIONS_IDENTIFIER) {
+      if (expandEntryActions) {
+        return expandEntryActions(entry);
+      }
+
+      log_warning(
+        `resolveActionIdentifiers: "${ENTRY_ACTIONS_IDENTIFIER}" is configured but this caller cannot expand it - the entry's own actions will not be shown`,
+        { entryId: (entry as ZappEntry)?.id }
+      );
+
+      return [];
+    }
+
+    const actions = uiActionsRegistry.getActions(identifier, entry);
+
+    // `hasAction` is only read to decide what to say; resolution itself is
+    // unchanged, so an identifier with no provider still resolves to nothing
+    // exactly as before.
+    if (uiActionsRegistry.hasAction(identifier)) {
+      reportedMissingProviders.delete(identifier);
+    } else if (!reportedMissingProviders.has(identifier)) {
+      reportedMissingProviders.add(identifier);
+
+      log_warning(
+        `resolveActionIdentifiers: configured action "${identifier}" has no registered provider - its button will not be shown`,
+        { identifier, entryId: (entry as ZappEntry)?.id }
+      );
+    }
+
+    return actions;
+  });
+}

package/uiActionsRegistrator/usableActionItems.ts

@@ -0,0 +1,66 @@
+import { createLogger } from "../logger";
+
+import { RegisteredAction } from "./registry";
+
+const { log_warning } = createLogger({
+  subsystem: "UIActionsRegistry",
+  category: "ActionRegistration",
+});
+
+/**
+ * Identifiers already reported as unusable. This runs on every render of the
+ * player overlay, so the warning is emitted once per identifier and forgotten
+ * again as soon as that action becomes invokable.
+ */
+const reportedUnusable = new Set<string>();
+
+function isInvokableAction(
+  item: RegisteredAction | undefined
+): item is RegisteredAction {
+  return typeof item?.action?.invokeAction === "function";
+}
+
+/**
+ * Narrows a resolved action list to what can actually be shown and invoked:
+ * anything without a usable `invokeAction` is dropped, and a repeated
+ * identifier keeps only its first occurrence. Order is preserved.
+ *
+ * Both the player overflow and the bottom sheet plugin build their list this
+ * way, and the player resolver applies it to `player_action_buttons` too - a
+ * hand-typed config string can name the same action twice.
+ */
+export function usableActionItems(
+  items: RegisteredAction[]
+): RegisteredAction[] {
+  const seen = new Set<string>();
+  const result: RegisteredAction[] = [];
+
+  for (const item of items ?? []) {
+    const identifier = item?.identifier;
+
+    // A duplicate is expected - a config string may name the same action twice
+    // - and an action with no identifier cannot be named in a log anyway.
+    if (!identifier || seen.has(identifier)) {
+      continue;
+    }
+
+    if (!isInvokableAction(item)) {
+      if (!reportedUnusable.has(identifier)) {
+        reportedUnusable.add(identifier);
+
+        log_warning(
+          `usableActionItems: dropping action "${identifier}" - its provider returned no invokeAction, so it cannot be shown`,
+          { identifier }
+        );
+      }
+
+      continue;
+    }
+
+    reportedUnusable.delete(identifier);
+    seen.add(identifier);
+    result.push(item);
+  }
+
+  return result;
+}

package/playerUtils/__tests__/getPlayerActionButtons.test.ts

@@ -1,54 +0,0 @@
-import { getPlayerActionButtons } from "../getPlayerActionButtons";
-import { selectActionButtons } from "../../conf/player/selectors";
-
-jest.mock("../../conf/player/selectors", () => ({
-  selectActionButtons: jest.fn(),
-}));
-
-describe("getPlayerActionButtons", () => {
-  afterEach(() => {
-    jest.clearAllMocks();
-  });
-
-  it("returns an empty array if selectActionButtons returns undefined", () => {
-    (selectActionButtons as jest.Mock).mockReturnValue(undefined);
-    const result = getPlayerActionButtons({});
-    expect(result).toEqual([]);
-  });
-
-  it("returns an empty array if selectActionButtons returns null", () => {
-    (selectActionButtons as jest.Mock).mockReturnValue(null);
-    const result = getPlayerActionButtons({});
-    expect(result).toEqual([]);
-  });
-
-  it("returns an empty array if selectActionButtons returns empty string", () => {
-    (selectActionButtons as jest.Mock).mockReturnValue("");
-    const result = getPlayerActionButtons({});
-    expect(result).toEqual([]);
-  });
-
-  it("returns the first two trimmed action buttons", () => {
-    (selectActionButtons as jest.Mock).mockReturnValue(" play , pause , stop ");
-    const result = getPlayerActionButtons({});
-    expect(result).toEqual(["play", "pause"]);
-  });
-
-  it("returns only one button if only one is present", () => {
-    (selectActionButtons as jest.Mock).mockReturnValue(" play ");
-    const result = getPlayerActionButtons({});
-    expect(result).toEqual(["play"]);
-  });
-
-  it("trims whitespace from button names", () => {
-    (selectActionButtons as jest.Mock).mockReturnValue("  play  ,   pause  ");
-    const result = getPlayerActionButtons({});
-    expect(result).toEqual(["play", "pause"]);
-  });
-
-  it("returns an empty array if selectActionButtons returns only commas", () => {
-    (selectActionButtons as jest.Mock).mockReturnValue(" , , ");
-    const result = getPlayerActionButtons({});
-    expect(result).toEqual(["", ""]);
-  });
-});

package/playerUtils/getPlayerActionButtons.ts

@@ -1,17 +0,0 @@
-import { map, take, trim } from "../utils";
-import { selectActionButtons } from "../conf/player/selectors";
-
-/**
- * Returns the first two action buttons from the configuration.
- * @param {Object} configuration - The player configuration object.
- * @returns {Array} An array containing the first two action buttons.
- */
-export const getPlayerActionButtons = (configuration: any) => {
-  const buttonsString = selectActionButtons(configuration);
-
-  if (!buttonsString) {
-    return [];
-  }
-
-  return take(2, map(buttonsString.split(","), trim));
-};