@applicaster/zapp-react-native-utils 16.0.0-rc.8 → 16.0.0-rc.81

package/uiActionsRegistrator/index.ts

@@ -0,0 +1,25 @@
+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";

package/uiActionsRegistrator/registry.ts

@@ -0,0 +1,335 @@
+/* eslint-disable no-dupe-class-members */
+import type { ComponentType } from "react";
+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 {
+  // The first name the action defines *as a function* answers. Nullish
+  // coalescing would let a plugin shipping one of these as a plain flag
+  // short-circuit the chain and mask a real predicate behind it.
+  const predicate = [
+    action?.isSupportDownloads,
+    action?.isActionSupported,
+    action?.isActionAvailable,
+  ].find((candidate) => typeof candidate === "function");
+
+  if (!predicate) {
+    return true;
+  }
+
+  try {
+    return Boolean(predicate(entry));
+  } catch (error) {
+    // Third-party code, called during render. Showing the action is the
+    // recoverable answer: a button that does nothing beats a screen that does
+    // not render.
+    log_warning(
+      "isActionAvailableFor: availability check threw - the action is shown",
+      { entryId: (entry as ZappEntry)?.id, error }
+    );
+
+    return true;
+  }
+}
+
+/** How an action's asset should be drawn, or `null` if it cannot be. */
+export type ResolvedActionAsset =
+  | { uri: string }
+  | { Component: ComponentType<any> }
+  | null;
+
+/**
+ * Interprets `CellActionEntryState["asset"]`.
+ *
+ * It is either something an image can take - a URI, or a per-flavour array -
+ * or a component that draws itself. A plain object is neither: a locale or
+ * state map arrives that way, and handing one to JSX throws "Element type is
+ * invalid".
+ *
+ * A React *element* carries the same `$$typeof` marker as a `memo`,
+ * `forwardRef` or `lazy` result, so `asset: <Icon/>` where `asset: Icon` was
+ * meant would pass a naive check and throw exactly that. Elements are told
+ * apart by carrying `props`.
+ *
+ * One function so that "can this draw?" and "draw it" cannot disagree.
+ */
+export function resolveActionAsset(asset: unknown): ResolvedActionAsset {
+  if (typeof asset === "string") {
+    return asset.length > 0 ? { uri: asset } : null;
+  }
+
+  if (Array.isArray(asset)) {
+    const first = asset.find(
+      (candidate) => typeof candidate === "string" && candidate.length > 0
+    );
+
+    return first ? { uri: first as string } : null;
+  }
+
+  if (typeof asset === "function") {
+    return { Component: asset as ComponentType<any> };
+  }
+
+  if (
+    typeof asset === "object" &&
+    asset !== null &&
+    "$$typeof" in asset &&
+    !("props" in asset)
+  ) {
+    return { Component: asset as ComponentType<any> };
+  }
+
+  return null;
+}
+
+/**
+ * Whether the action has something an icon-only button can actually draw.
+ *
+ * An overlay button is an icon and nothing else, so an action whose state
+ * carries no usable asset renders as nothing at all - legal for an entry action
+ * declared with a title and no `iconURL`. Surfaces that must keep an action
+ * reachable ask this before putting it somewhere it can only appear as an icon.
+ */
+export function canRenderActionIcon(
+  action: RegisteredActionValue | undefined,
+  entry: ZappEntry | ZappFeed
+): boolean {
+  try {
+    return resolveActionAsset(action?.initialEntryState?.(entry)?.asset) !== null; // prettier-ignore
+  } catch {
+    return false;
+  }
+}
+
+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/zappFrameworkUtils/__tests__/localStorageHelper.test.ts

@@ -0,0 +1,146 @@
+import {
+  batchSaveOwnedValues,
+  batchRemoveOwnedValues,
+} from "../localStorageHelper";
+import { localStorage } from "@applicaster/zapp-react-native-bridge/ZappStorage/LocalStorage";
+
+// Mock localStorage
+jest.mock(
+  "@applicaster/zapp-react-native-bridge/ZappStorage/LocalStorage",
+  () => ({
+    localStorage: {
+      getItem: jest.fn(),
+      setItem: jest.fn(),
+      removeItem: jest.fn(),
+    },
+  })
+);
+
+describe("localStorageHelper", () => {
+  const ownershipKey = "test_ownership_key";
+  const ownershipNamespace = "test_namespace";
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe("addOwnedKeys via batchSaveOwnedValues", () => {
+    it("should add new keys to existing owned keys", async () => {
+      // Setup existing keys in storage
+      const existingKeys = {
+        namespace1: ["key1"],
+      };
+
+      (localStorage.getItem as jest.Mock).mockResolvedValue(
+        JSON.stringify(existingKeys)
+      );
+
+      const newValues = {
+        namespace1: { key2: "value2" },
+        namespace2: { key3: "value3" },
+      };
+
+      await batchSaveOwnedValues({
+        storageValues: newValues,
+        ownershipKey,
+        ownershipNamespace,
+      });
+
+      // Verify localStorage.setItem was called with correct updated keys
+      // Note: order of keys in array might vary depending on Set implementation, but usually insertion order
+      // However, to be safe, we can parse the argument and check contents
+
+      const lastCall = (localStorage.setItem as jest.Mock).mock.calls.find(
+        (call) => call[0] === ownershipKey
+      );
+
+      expect(lastCall).toBeDefined();
+      const savedData = JSON.parse(lastCall[1]);
+
+      expect(savedData.namespace1).toContain("key1");
+      expect(savedData.namespace1).toContain("key2");
+      expect(savedData.namespace2).toContain("key3");
+    });
+
+    it("should handle empty existing keys", async () => {
+      (localStorage.getItem as jest.Mock).mockResolvedValue(null);
+
+      const newValues = {
+        namespace1: { key1: "value1" },
+      };
+
+      await batchSaveOwnedValues({
+        storageValues: newValues,
+        ownershipKey,
+        ownershipNamespace,
+      });
+
+      const lastCall = (localStorage.setItem as jest.Mock).mock.calls.find(
+        (call) => call[0] === ownershipKey
+      );
+
+      expect(lastCall).toBeDefined();
+      const savedData = JSON.parse(lastCall[1]);
+
+      expect(savedData.namespace1).toEqual(["key1"]);
+    });
+  });
+
+  describe("removeOwnedKeys via batchRemoveOwnedValues", () => {
+    it("should remove keys from owned keys", async () => {
+      const existingKeys = {
+        namespace1: ["key1", "key2"],
+        namespace2: ["key3"],
+      };
+
+      (localStorage.getItem as jest.Mock).mockResolvedValue(
+        JSON.stringify(existingKeys)
+      );
+
+      const keysToRemove = {
+        namespace1: ["key1"],
+      };
+
+      await batchRemoveOwnedValues({
+        storageValues: keysToRemove,
+        ownershipKey,
+        ownershipNamespace,
+      });
+
+      const lastCall = (localStorage.setItem as jest.Mock).mock.calls.find(
+        (call) => call[0] === ownershipKey
+      );
+
+      expect(lastCall).toBeDefined();
+      const savedData = JSON.parse(lastCall[1]);
+
+      expect(savedData.namespace1).toEqual(["key2"]);
+      expect(savedData.namespace2).toEqual(["key3"]);
+    });
+
+    it("should remove namespace if all keys removed", async () => {
+      const existingKeys = {
+        namespace1: ["key1"],
+      };
+
+      (localStorage.getItem as jest.Mock).mockResolvedValue(
+        JSON.stringify(existingKeys)
+      );
+
+      const keysToRemove = {
+        namespace1: ["key1"],
+      };
+
+      await batchRemoveOwnedValues({
+        storageValues: keysToRemove,
+        ownershipKey,
+        ownershipNamespace,
+      });
+
+      expect(localStorage.removeItem).toHaveBeenCalledWith(
+        ownershipKey,
+        ownershipNamespace
+      );
+    });
+  });
+});