@applicaster/zapp-react-native-utils 16.0.0-alpha.1151561937 → 16.0.0-alpha.1180700101

package/reactHooks/navigation/usePresentScreen.ts

@@ -0,0 +1,157 @@
+/// <reference types="@applicaster/applicaster-types" />
+import { useCallback } from "react";
+
+import { useContentTypes } from "@applicaster/zapp-react-native-redux/hooks";
+
+import { modalStore } from "../../modalState";
+import { isWeb } from "../../reactUtils";
+import { createLogger } from "../../logger";
+import { useRivers } from "../state";
+
+const { log_error, log_info } = createLogger({
+  subsystem: "usePresentScreen",
+  category: "General",
+});
+
+export interface PresentScreenArgs {
+  /** The screen type to present (from content types mapping) */
+  typeMapping: string;
+
+  /** Entry to present the screen with. Omit to present the screen on its own. */
+  entry?: ZappEntry;
+}
+
+export interface PresentScreenResult {
+  /** The presented screen completed successfully */
+  success: boolean;
+
+  /** The presented screen was dismissed without completing (e.g. the back button) */
+  cancelled: boolean;
+
+  /** Set when the screen could not be presented at all */
+  error?: string;
+
+  /** Whatever the presented screen reported back */
+  payload?: unknown;
+}
+
+export type PresentScreenFn = (
+  args: PresentScreenArgs
+) => Promise<PresentScreenResult>;
+
+interface Dependencies {
+  rivers: Record<string, ZappRiver>;
+  contentTypes: ZappContentTypes;
+}
+
+const failure = (error: string): Promise<PresentScreenResult> => {
+  log_error(`presentScreen: ${error}`);
+
+  return Promise.resolve({ success: false, cancelled: false, error });
+};
+
+/**
+ * Presents a screen as a modal and resolves once that screen reports a result
+ * or is dismissed.
+ *
+ * The screen is rendered by the ModalProvider through the regular ScreenResolver,
+ * so it receives the `resultCallback` we pass here as its `callback` prop — the
+ * same channel hook screens already use to report success and cancellation.
+ */
+export const presentScreen = ({
+  typeMapping,
+  entry,
+  rivers,
+  contentTypes,
+}: PresentScreenArgs & Dependencies): Promise<PresentScreenResult> => {
+  if (!typeMapping) {
+    return failure("typeMapping option is missing");
+  }
+
+  // The web ModalProvider renders nothing, so no result could ever arrive and
+  // awaiting one would stall the caller indefinitely.
+  if (isWeb()) {
+    return failure("screens can not be presented as modals on web");
+  }
+
+  const screenId = contentTypes?.[typeMapping]?.screen_id;
+
+  if (!screenId) {
+    return failure(`can not resolve screen type mapping: ${typeMapping}`);
+  }
+
+  const river = rivers?.[screenId];
+
+  if (!river) {
+    return failure(`can not resolve river for screen id: ${screenId}`);
+  }
+
+  return new Promise<PresentScreenResult>((resolve) => {
+    let settled = false;
+    let unsubscribe: () => void = () => {};
+
+    const settle = (result: PresentScreenResult) => {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      unsubscribe();
+      resolve(result);
+    };
+
+    const resultCallback = ({
+      success,
+      cancelled,
+      payload,
+    }: hookCallbackArgs) =>
+      settle({ success: !!success, cancelled: !!cancelled, payload });
+
+    const props: Record<string, unknown> = { resultCallback };
+
+    if (entry) {
+      // The ModalProvider turns this into the screen's ScreenDataContext and
+      // screenData, so the presented screen reads the entry exactly as it
+      // would when navigated to.
+      props.entry = entry;
+    }
+
+    log_info(
+      `presentScreen: presenting screen type: ${typeMapping}${
+        entry ? ` with entry id: ${entry.id}` : ""
+      }`
+    );
+
+    modalStore.getState().openModal({ item: river, props });
+
+    // Covers every dismissal we do not initiate ourselves: the hardware back
+    // button (via the Modal's onRequestClose), a swipe dismiss, another modal
+    // taking our slot, or dismissModal() called from anywhere else.
+    unsubscribe = modalStore.subscribe(({ modalState }) => {
+      if (!modalState.visible || modalState.screen !== river) {
+        settle({ success: false, cancelled: true });
+      }
+    });
+  }).then((result) => {
+    // Only take down our own modal — by now something else may already own the slot.
+    if (modalStore.getState().modalState.screen === river) {
+      modalStore.getState().dismissModal();
+    }
+
+    return result;
+  });
+};
+
+/**
+ * @returns a function presenting a screen as a modal, resolving with its result.
+ */
+export const usePresentScreen = (): PresentScreenFn => {
+  const rivers = useRivers();
+  const contentTypes = useContentTypes();
+
+  return useCallback(
+    (args: PresentScreenArgs) =>
+      presentScreen({ ...args, rivers, contentTypes }),
+    [rivers, contentTypes]
+  );
+};

package/reactHooks/navigation/useRoute.ts

@@ -80,7 +80,20 @@ export const useRoute = (
   // if path is hook grab screenData from screenData
 
   if (isModalPathname(pathname)) {
-    const screenData = modalScreenData ?? ({} as ZappEntry);
+    if (!modalScreenData) {
+      return { screenData: {} as ZappEntry, pathname };
+    }
+
+    // Mirror the pushed-screen shape ({ ...entry, targetScreen }) so a screen
+    // presented as a modal reads its entry the same way it would when
+    // navigated to, instead of only seeing the bare river.
+    const screenData = legacyScreenData(
+      {
+        screen: modalScreenData,
+        entry: modalState.props?.entry as NavigatorEntry,
+      },
+      plugins
+    );
 
     return { screenData, pathname };
   }

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";