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

package/actionsExecutor/ActionExecutorContext.tsx

@@ -9,7 +9,7 @@ import { ActionExecutionContext, ActionHandler } from "./types";
 import { batchRemoveAllFromNamespaceForStorage } from "../zappFrameworkUtils/localStorageHelper";
 import { sessionStorage } from "@applicaster/zapp-react-native-bridge/ZappStorage/SessionStorage";
 
-import { useNavigation, useRivers } from "../reactHooks";
+import { useNavigation, usePresentScreen, useRivers } from "../reactHooks";
 import { useContentTypes } from "@applicaster/zapp-react-native-redux/hooks";
 import { useSubscriberFor } from "../reactHooks/useSubscriberFor";
 import { APP_EVENTS } from "../appUtils/events";
@@ -25,6 +25,7 @@ import {
   localStorageRemoveAction,
   localStorageSetAction,
   localStorageToggleFlagAction,
+  createPresentScreenAction,
   openBottomSheetAction,
   refreshComponentAction,
   screenSetVariableAction,
@@ -157,6 +158,7 @@ export function withActionExecutor(Component) {
     const navigator = useNavigation();
     const rivers = useRivers();
     const contentTypes = useContentTypes();
+    const presentScreen = usePresentScreen();
 
     const handlers = useMemo(() => {
       return {
@@ -191,6 +193,13 @@ export function withActionExecutor(Component) {
       );
     }, [navigator, rivers, contentTypes]);
 
+    useEffect(() => {
+      return _actionExecutor.registerAction(
+        ACTION_TYPES.PRESENT_SCREEN,
+        createPresentScreenAction(presentScreen)
+      );
+    }, [presentScreen]);
+
     useEffect(() => {
       return _actionExecutor.registerAction(
         ACTION_TYPES.GO_BACK,

package/actionsExecutor/actions/__tests__/presentScreen.test.ts

@@ -0,0 +1,127 @@
+import { createPresentScreenAction } from "../presentScreen";
+import { ActionResult } from "../../ActionExecutor";
+
+const contextEntry = { id: "context-entry" } as any;
+
+const succeeded = { success: true, cancelled: false };
+
+const cancelled = { success: false, cancelled: true };
+
+describe("presentScreenAction", () => {
+  let presentScreen: jest.Mock;
+  let presentScreenAction: ReturnType<typeof createPresentScreenAction>;
+
+  beforeEach(() => {
+    presentScreen = jest.fn().mockResolvedValue(succeeded);
+    presentScreenAction = createPresentScreenAction(presentScreen);
+  });
+
+  it("presents the screen named by typeMapping", async () => {
+    await presentScreenAction({
+      type: "presentScreen",
+      options: { typeMapping: "parent_lock" },
+    });
+
+    expect(presentScreen).toHaveBeenCalledWith({
+      typeMapping: "parent_lock",
+      entry: undefined,
+    });
+  });
+
+  it("fails without presenting anything when typeMapping is missing", async () => {
+    const result = await presentScreenAction({
+      type: "presentScreen",
+      options: {},
+    });
+
+    expect(result).toBe(ActionResult.Error);
+    expect(presentScreen).not.toHaveBeenCalled();
+  });
+
+  it("resolves the '@{entry/}' token to the entry from the execution context", async () => {
+    await presentScreenAction(
+      {
+        type: "presentScreen",
+        options: { typeMapping: "parent_lock", entry: "@{entry/}" },
+      },
+      { entry: contextEntry }
+    );
+
+    expect(presentScreen).toHaveBeenCalledWith({
+      typeMapping: "parent_lock",
+      entry: contextEntry,
+    });
+  });
+
+  it("presents an entry supplied inline in the options", async () => {
+    const inlineEntry = { id: "inline-entry" } as any;
+
+    await presentScreenAction({
+      type: "presentScreen",
+      options: { typeMapping: "parent_lock", entry: inlineEntry },
+    });
+
+    expect(presentScreen).toHaveBeenCalledWith({
+      typeMapping: "parent_lock",
+      entry: inlineEntry,
+    });
+  });
+
+  it("fails without presenting anything when the entry option is not an object", async () => {
+    const result = await presentScreenAction({
+      type: "presentScreen",
+      options: { typeMapping: "parent_lock", entry: "not-an-entry" as any },
+    });
+
+    expect(result).toBe(ActionResult.Error);
+    expect(presentScreen).not.toHaveBeenCalled();
+  });
+
+  it("succeeds when the presented screen reports success", async () => {
+    presentScreen.mockResolvedValue(succeeded);
+
+    const result = await presentScreenAction({
+      type: "presentScreen",
+      options: { typeMapping: "parent_lock" },
+    });
+
+    expect(result).toBe(ActionResult.Success);
+  });
+
+  it("cancels the action chain when the presented screen is cancelled", async () => {
+    presentScreen.mockResolvedValue(cancelled);
+
+    const result = await presentScreenAction({
+      type: "presentScreen",
+      options: { typeMapping: "parent_lock" },
+    });
+
+    expect(result).toBe(ActionResult.Cancel);
+  });
+
+  it("cancels the action chain when the presented screen reports failure", async () => {
+    presentScreen.mockResolvedValue({ success: false, cancelled: false });
+
+    const result = await presentScreenAction({
+      type: "presentScreen",
+      options: { typeMapping: "parent_lock" },
+    });
+
+    expect(result).toBe(ActionResult.Cancel);
+  });
+
+  it("errors when the screen could not be presented at all", async () => {
+    presentScreen.mockResolvedValue({
+      success: false,
+      cancelled: false,
+      error: "can not resolve screen type mapping: parent_lock",
+    });
+
+    const result = await presentScreenAction({
+      type: "presentScreen",
+      options: { typeMapping: "parent_lock" },
+    });
+
+    expect(result).toBe(ActionResult.Error);
+  });
+});

package/actionsExecutor/actions/index.ts

@@ -27,6 +27,8 @@ export { screenToggleFlagAction } from "./screenToggleFlag";
 
 export { createNavigateToScreenAction } from "./navigateToScreen";
 
+export { createPresentScreenAction } from "./presentScreen";
+
 export { createGoBackAction } from "./goBack";
 
 export { createGoHomeAction } from "./goHome";

package/actionsExecutor/actions/presentScreen.ts

@@ -0,0 +1,78 @@
+/// <reference types="@applicaster/applicaster-types" />
+import { ActionResult } from "../ActionExecutor";
+import { ActionHandler, ActionExecutionContext } from "../types";
+import type { PresentScreenFn } from "../../reactHooks/navigation/usePresentScreen";
+import { createLogger } from "../../logger";
+
+const { log_error } = createLogger({
+  subsystem: "ActionExecutorContext",
+  category: "General",
+});
+
+/**
+ * Options for the presentScreen action.
+ */
+export interface PresentScreenOptions {
+  /** The screen type to present (from content types mapping) */
+  typeMapping: string;
+
+  /**
+   * Entry to present the screen with. Can be:
+   * - "@{entry/}" to use the context entry
+   * - A ZappEntry object
+   * - undefined to present the screen without an entry
+   */
+  entry?: "@{entry/}" | ZappEntry;
+}
+
+/**
+ * Creates a present-screen action handler with the provided dependencies.
+ *
+ * Unlike navigateToScreen, this action does not return until the presented
+ * screen reports a result, so a screen that gates the flow (a parental lock,
+ * for example) can stop the remaining actions by being cancelled.
+ *
+ * @param presentScreen - Presents a screen as a modal and resolves with its result
+ * @returns An action handler that presents a screen and awaits its outcome
+ */
+export function createPresentScreenAction(
+  presentScreen: PresentScreenFn
+): ActionHandler<PresentScreenOptions> {
+  return async function presentScreenAction(
+    action,
+    context?: ActionExecutionContext
+  ): Promise<ActionResult> {
+    const typeMapping = action.options?.typeMapping;
+
+    if (!typeMapping) {
+      log_error("presentScreen: typeMapping option is missing");
+
+      return ActionResult.Error;
+    }
+
+    const entrySource = action.options?.entry;
+
+    const entry = entrySource
+      ? entrySource === "@{entry/}"
+        ? context?.entry
+        : entrySource
+      : undefined;
+
+    if (entry && typeof entry !== "object") {
+      log_error(
+        `presentScreen: entry option is not an object, entry: ${entry}`
+      );
+
+      return ActionResult.Error;
+    }
+
+    const result = await presentScreen({ typeMapping, entry });
+
+    if (result.error) {
+      return ActionResult.Error;
+    }
+
+    // Anything short of success stops the remaining actions in the chain.
+    return result.success ? ActionResult.Success : ActionResult.Cancel;
+  };
+}

package/actionsExecutor/consts.ts

@@ -9,6 +9,7 @@ export const ACTION_TYPES = {
   PRESENT_SUB_MENU: "presentSubMenu",
   SEND_CLOUD_EVENT: "sendCloudEvent",
   NAVIGATE_TO_SCREEN: "navigateToScreen",
+  PRESENT_SCREEN: "presentScreen",
   GO_BACK: "goBack",
   GO_HOME: "goHome",
   SHOW_TOAST: "showToast",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applicaster/zapp-react-native-utils",
-  "version": "16.0.0-rc.81",
+  "version": "16.0.0-rc.83",
   "description": "Applicaster Zapp React Native utilities package",
   "main": "index.js",
   "types": "index.d.ts",
@@ -27,7 +27,7 @@
   },
   "homepage": "https://github.com/applicaster/quickbrick#readme",
   "dependencies": {
-    "@applicaster/applicaster-types": "16.0.0-rc.81",
+    "@applicaster/applicaster-types": "16.0.0-rc.83",
     "buffer": "^5.2.1",
     "camelize": "^1.0.0",
     "dayjs": "^1.11.10",

package/reactHooks/navigation/__tests__/index.test.tsx

@@ -7,6 +7,7 @@ import configureMockStore from "redux-mock-store";
 import { NavigationContext } from "@applicaster/zapp-react-native-ui-components/Contexts/NavigationContext";
 import { ROUTE_TYPES } from "@applicaster/zapp-react-native-utils/navigationUtils/routeTypes";
 import { ScreenDataContext } from "@applicaster/zapp-react-native-ui-components/Contexts/ScreenDataContext";
+import { modalStore } from "@applicaster/zapp-react-native-utils/modalState";
 
 const plugins = [];
 
@@ -156,6 +157,20 @@ const videoModalWrapper = ({ children }) => (
   </Provider>
 );
 
+const modalEntry = { id: "modal-entry-1", type: { value: "video" } };
+
+const modalPathname = `${ROUTE_TYPES.MODAL}/${rivers["river-general"].id}`;
+
+const modalWrapper = ({ children }) => (
+  <Provider store={store}>
+    <NavigationContext.Provider value={mainStackNavigator}>
+      <PathnameContext.Provider value={modalPathname}>
+        {children}
+      </PathnameContext.Provider>
+    </NavigationContext.Provider>
+  </Provider>
+);
+
 const hookModalWrapper = ({ children }) => (
   <Provider store={store}>
     <NavigationContext.Provider value={hookModalNavigator}>
@@ -188,6 +203,39 @@ describe("navigation", () => {
       });
     });
 
+    describe("Modal components", () => {
+      beforeEach(() => {
+        modalStore.getState().openModal({
+          item: rivers["river-general"] as any,
+          props: { entry: modalEntry },
+        });
+      });
+
+      afterEach(() => {
+        modalStore.getState().dismissModal();
+      });
+
+      it("should return a correct pathname", () => {
+        const { result } = renderHook(() => useRoute(), {
+          wrapper: modalWrapper,
+        });
+
+        expect(result.current.pathname).toEqual(modalPathname);
+      });
+
+      it("should return correct screenData information", () => {
+        const { result } = renderHook(() => useRoute(), {
+          wrapper: modalWrapper,
+        });
+
+        expect(result.current.screenData.id).toEqual(modalEntry.id);
+
+        expect(result.current.screenData.targetScreen.id).toEqual(
+          rivers["river-general"].id
+        );
+      });
+    });
+
     describe("Hook modal components", () => {
       it("should return a correct pathname", () => {
         const { result } = renderHook(() => useRoute(), {

package/reactHooks/navigation/__tests__/usePresentScreen.test.ts

@@ -0,0 +1,154 @@
+import { modalStore } from "../../../modalState";
+import { isWeb } from "../../../reactUtils";
+import { presentScreen } from "../usePresentScreen";
+
+jest.mock("../../../reactUtils", () => ({
+  ...jest.requireActual("../../../reactUtils"),
+  isWeb: jest.fn(() => false),
+}));
+
+const river = { id: "river-parent-lock", type: "parent_lock" } as any;
+
+const rivers = { "river-parent-lock": river };
+
+const contentTypes = { parent_lock: { screen_id: "river-parent-lock" } };
+
+const present = (args = {}) =>
+  presentScreen({ typeMapping: "parent_lock", rivers, contentTypes, ...args });
+
+const modalState = () => modalStore.getState().modalState;
+
+const screenCallback = () => modalState().props?.resultCallback as hookCallback;
+
+describe("presentScreen", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    (isWeb as jest.Mock).mockReturnValue(false);
+    modalStore.getState().dismissModal();
+  });
+
+  it("opens a modal with the river resolved from typeMapping", () => {
+    void present();
+
+    expect(modalState().visible).toBe(true);
+    expect(modalState().screen).toBe(river);
+  });
+
+  it("resolves with success when the presented screen reports success", async () => {
+    const result = present();
+
+    screenCallback()({ success: true, payload: { verified: true } });
+
+    await expect(result).resolves.toMatchObject({
+      success: true,
+      cancelled: false,
+      payload: { verified: true },
+    });
+  });
+
+  it("dismisses the modal once the presented screen reports a result", async () => {
+    const result = present();
+
+    screenCallback()({ success: true, payload: {} });
+    await result;
+
+    expect(modalState().visible).toBe(false);
+  });
+
+  it("resolves as cancelled when the modal is dismissed without a result", async () => {
+    const result = present();
+
+    // What the hardware back button does: RN Modal's onRequestClose resets modal state.
+    modalStore.getState().dismissModal();
+
+    await expect(result).resolves.toMatchObject({
+      success: false,
+      cancelled: true,
+    });
+  });
+
+  it("resolves as cancelled when the presented screen reports cancellation", async () => {
+    const result = present();
+
+    screenCallback()({ success: false, payload: {}, cancelled: true });
+
+    await expect(result).resolves.toMatchObject({
+      success: false,
+      cancelled: true,
+    });
+  });
+
+  it("resolves as cancelled when another modal replaces the presented screen", async () => {
+    const result = present();
+
+    modalStore.getState().openModal({ item: { id: "other-modal" } as any });
+
+    await expect(result).resolves.toMatchObject({ cancelled: true });
+  });
+
+  it("leaves the modal that replaced the presented screen open", async () => {
+    const result = present();
+    const other = { id: "other-modal" } as any;
+
+    modalStore.getState().openModal({ item: other });
+    await result;
+
+    expect(modalState().screen).toBe(other);
+    expect(modalState().visible).toBe(true);
+  });
+
+  it("ignores a result reported after the modal was already cancelled", async () => {
+    const result = present();
+    const callback = screenCallback();
+
+    modalStore.getState().dismissModal();
+    callback({ success: true, payload: {} });
+
+    await expect(result).resolves.toMatchObject({
+      success: false,
+      cancelled: true,
+    });
+  });
+
+  it("hands the entry to the ModalProvider so it reaches ScreenDataContext", () => {
+    const entry = { id: "entry-1", type: { value: "video" } } as any;
+
+    void present({ entry });
+
+    expect(modalState().props?.entry).toBe(entry);
+  });
+
+  it("omits the entry when the screen is presented without one", () => {
+    void present();
+
+    expect(modalState().props).not.toHaveProperty("entry");
+  });
+
+  it("fails without opening a modal when typeMapping has no content type", async () => {
+    const result = await present({ typeMapping: "unmapped" });
+
+    expect(result).toMatchObject({ success: false, cancelled: false });
+    expect(result.error).toEqual(expect.any(String));
+    expect(modalState().visible).toBe(false);
+  });
+
+  it("fails without opening a modal when the content type resolves to a missing river", async () => {
+    const result = await present({
+      contentTypes: { parent_lock: { screen_id: "gone" } },
+    });
+
+    expect(result).toMatchObject({ success: false, cancelled: false });
+    expect(result.error).toEqual(expect.any(String));
+    expect(modalState().visible).toBe(false);
+  });
+
+  it("fails without opening a modal on web, where no modal host exists", async () => {
+    (isWeb as jest.Mock).mockReturnValue(true);
+
+    const result = await present();
+
+    expect(result).toMatchObject({ success: false, cancelled: false });
+    expect(result.error).toEqual(expect.any(String));
+    expect(modalState().visible).toBe(false);
+  });
+});

package/reactHooks/navigation/index.ts

@@ -22,6 +22,8 @@ import { useLayoutVersion } from "../layout";
 
 export { useNavigation } from "./useNavigation";
 
+export { usePresentScreen, presentScreen } from "./usePresentScreen";
+
 export { useRoute } from "./useRoute";
 
 export { usePathname } from "./usePathname";

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