@applicaster/zapp-react-native-utils 16.0.0-alpha.2851031376 → 16.0.0-alpha.2963644197

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

@@ -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();