@applicaster/zapp-react-native-utils 16.0.0-rc.9 → 16.0.0-rc.90

package/actionsExecutor/actions/__tests__/openBottomSheet.inlineItems.test.ts

@@ -0,0 +1,212 @@
+import { openBottomSheetAction } from "../openBottomSheet";
+import { actionExecutor, ActionResult } from "../../ActionExecutor";
+import { modalOrchestrator } from "../../../modalState/ModalOrchestrator";
+
+jest.mock("../../../modalState/store", () => ({
+  openBottomSheetModal: jest.fn(),
+}));
+
+jest.mock("../../../modalState/ModalOrchestrator", () => ({
+  modalOrchestrator: {
+    open: jest.fn(),
+    replace: jest.fn(),
+    stackSize: 0,
+  },
+  isPresentSubMenuAction: jest.requireActual("../../../modalState/types")
+    .isPresentSubMenuAction,
+}));
+
+describe("openBottomSheetAction inline items", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    (modalOrchestrator as any).stackSize = 0;
+  });
+
+  const speedSheetAction = {
+    type: "openBottomSheet",
+    options: {
+      header: { title: "Playback Speed" },
+      content: {
+        role: "collection_selector",
+        behavior: {
+          selectMode: "single",
+          currentSelection: ["1"],
+        },
+        items: [
+          {
+            id: "0.8",
+            title: "0.8x",
+            extensions: {
+              tap_actions: {
+                actions: [
+                  { type: "setPlaybackSpeed", options: { value: 0.8 } },
+                ],
+              },
+            },
+          },
+          {
+            id: "1",
+            title: "1x",
+            extensions: {
+              tap_actions: {
+                actions: [{ type: "setPlaybackSpeed", options: { value: 1 } }],
+              },
+            },
+          },
+        ],
+      },
+    },
+  } as any;
+
+  it("opens orchestrator with inline items and marks current selection", async () => {
+    const result = await openBottomSheetAction(speedSheetAction);
+
+    expect(result).toBe(ActionResult.Success);
+    expect(modalOrchestrator.open).toHaveBeenCalledTimes(1);
+    expect(modalOrchestrator.replace).not.toHaveBeenCalled();
+
+    const [menu] = (modalOrchestrator.open as jest.Mock).mock.calls[0];
+
+    expect(menu.content.items[0].isSelected).toBe(false);
+
+    expect(menu.content.items[1]).toMatchObject({
+      id: "1",
+      title: "1x",
+      isSelected: true,
+      action: { type: "setPlaybackSpeed", options: { value: 1 } },
+    });
+  });
+
+  it("pushes a new sheet by default even when another sheet is already open", async () => {
+    (modalOrchestrator as any).stackSize = 1;
+
+    await openBottomSheetAction(speedSheetAction);
+
+    expect(modalOrchestrator.open).toHaveBeenCalledTimes(1);
+    expect(modalOrchestrator.replace).not.toHaveBeenCalled();
+  });
+
+  it("replaces the current sheet when options.replace is true", async () => {
+    (modalOrchestrator as any).stackSize = 1;
+
+    await openBottomSheetAction({
+      ...speedSheetAction,
+      options: { ...speedSheetAction.options, replace: true },
+    });
+
+    expect(modalOrchestrator.replace).toHaveBeenCalledTimes(1);
+    expect(modalOrchestrator.open).not.toHaveBeenCalled();
+  });
+
+  it("executes all actions in tap_actions when onItemPress is called", async () => {
+    const multiActionSheet = {
+      type: "openBottomSheet",
+      options: {
+        header: { title: "Target Playlists" },
+        content: {
+          role: "collection_selector",
+          behavior: { selectMode: "none", currentSelection: [] },
+          items: [
+            {
+              id: "playlist-1",
+              title: "My Playlist",
+              extensions: {
+                tap_actions: {
+                  actions: [
+                    {
+                      type: "sendCloudEvent",
+                      options: { subject: "add_collection_to_collection" },
+                    },
+                    {
+                      type: "showToast",
+                      options: { message: "Added to playlist" },
+                    },
+                    { type: "dismissBottomSheet", options: {} },
+                  ],
+                },
+              },
+            },
+          ],
+        },
+      },
+    } as any;
+
+    await openBottomSheetAction(multiActionSheet);
+
+    const [menu, onItemPress] = (modalOrchestrator.open as jest.Mock).mock
+      .calls[0];
+
+    expect(menu.content.items[0].actions).toHaveLength(3);
+
+    const handleActionsSpy = jest
+      .spyOn(actionExecutor, "handleActions")
+      .mockResolvedValue(ActionResult.Success);
+
+    await onItemPress(menu.content.items[0]);
+
+    expect(handleActionsSpy).toHaveBeenCalledWith(
+      [
+        {
+          type: "sendCloudEvent",
+          options: { subject: "add_collection_to_collection" },
+        },
+        {
+          type: "showToast",
+          options: { message: "Added to playlist" },
+        },
+        { type: "dismissBottomSheet", options: {} },
+      ],
+      expect.objectContaining({
+        entry: menu.content.items[0],
+      })
+    );
+
+    handleActionsSpy.mockRestore();
+  });
+
+  it("executes preceding actions and excludes presentSubMenu from actionExecutor", async () => {
+    const subMenuSheet = {
+      type: "openBottomSheet",
+      options: {
+        header: { title: "Menu" },
+        content: {
+          items: [
+            {
+              id: "item-with-submenu",
+              title: "More Options",
+              extensions: {
+                tap_actions: {
+                  actions: [
+                    { type: "sendAnalytics", options: { event: "click_more" } },
+                    {
+                      type: "presentSubMenu",
+                      menu: { content: { title: "Sub Options", items: [] } },
+                    },
+                  ],
+                },
+              },
+            },
+          ],
+        },
+      },
+    } as any;
+
+    await openBottomSheetAction(subMenuSheet);
+
+    const [menu, onItemPress] = (modalOrchestrator.open as jest.Mock).mock
+      .calls[0];
+
+    const handleActionsSpy = jest
+      .spyOn(actionExecutor, "handleActions")
+      .mockResolvedValue(ActionResult.Success);
+
+    await onItemPress(menu.content.items[0]);
+
+    expect(handleActionsSpy).toHaveBeenCalledWith(
+      [{ type: "sendAnalytics", options: { event: "click_more" } }],
+      expect.objectContaining({ entry: menu.content.items[0] })
+    );
+
+    handleActionsSpy.mockRestore();
+  });
+});

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/__tests__/showAlert.test.ts

@@ -0,0 +1,49 @@
+import { showAlertAction } from "../showAlert";
+import { ActionResult } from "../../ActionExecutor";
+import { showAlertDialog } from "../../../alertUtils";
+
+jest.mock("../../../alertUtils", () => ({
+  showAlertDialog: jest.fn(),
+}));
+
+const dialog = showAlertDialog as jest.Mock;
+
+const dismiss = () => dialog.mock.calls[0][0].completion();
+
+describe("showAlert", () => {
+  beforeEach(() => dialog.mockReset());
+
+  it("shows the notice and resolves once it is dismissed", async () => {
+    const result = showAlertAction({
+      type: "showAlert",
+      options: { title: "Locked", message: "Ask the account owner." },
+    });
+
+    expect(dialog).toHaveBeenCalledWith(
+      expect.objectContaining({
+        title: "Locked",
+        message: "Ask the account owner.",
+        okButtonText: "OK",
+      })
+    );
+
+    dismiss();
+
+    // Dismissing a notice is not a cancellation: the chain carries on.
+    await expect(result).resolves.toBe(ActionResult.Success);
+  });
+
+  it("takes the dismiss label from the action", async () => {
+    const result = showAlertAction({
+      type: "showAlert",
+      options: { title: "Locked", okButtonText: "Got it" },
+    });
+
+    expect(dialog).toHaveBeenCalledWith(
+      expect.objectContaining({ okButtonText: "Got it" })
+    );
+
+    dismiss();
+    await result;
+  });
+});

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

@@ -0,0 +1,88 @@
+import { showToastAction } from "../showToast";
+import { postEvent } from "../../../reactHooks/useSubscriberFor";
+import { ActionResult } from "../../ActionExecutor";
+
+jest.mock("../../../reactHooks/useSubscriberFor", () => ({
+  postEvent: jest.fn(),
+}));
+
+describe("showToastAction", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("calls postEvent with confirmation source, default timeout, and returns Success", async () => {
+    const action = {
+      type: "showToast",
+      options: {
+        id: "toast-1",
+        message: "Added to queue",
+        extraMessage: "Extra info",
+      },
+    };
+
+    const result = await showToastAction(action);
+
+    expect(postEvent).toHaveBeenCalledTimes(1);
+
+    expect(postEvent).toHaveBeenCalledWith("showToast", [
+      {
+        id: "toast-1",
+        message: "Added to queue",
+        extraMessage: "Extra info",
+        style: undefined,
+        timeout: 5000,
+        source: "confirmation",
+      },
+    ]);
+
+    expect(result).toBe(ActionResult.Success);
+  });
+
+  it("preserves an explicit timeout and style override", async () => {
+    const action = {
+      type: "showToast",
+      options: {
+        message: "Playlist created",
+        timeout: 3000,
+        style: { backgroundColor: "#00FF00" },
+      },
+    };
+
+    await showToastAction(action);
+
+    expect(postEvent).toHaveBeenCalledWith("showToast", [
+      {
+        id: undefined,
+        message: "Playlist created",
+        extraMessage: undefined,
+        style: { backgroundColor: "#00FF00" },
+        timeout: 3000,
+        source: "confirmation",
+      },
+    ]);
+  });
+
+  it("handles missing or empty options without throwing", async () => {
+    const action = {
+      type: "showToast",
+    };
+
+    const result = await showToastAction(action);
+
+    expect(postEvent).toHaveBeenCalledTimes(1);
+
+    expect(postEvent).toHaveBeenCalledWith("showToast", [
+      {
+        id: undefined,
+        message: undefined,
+        extraMessage: undefined,
+        style: undefined,
+        timeout: 5000,
+        source: "confirmation",
+      },
+    ]);
+
+    expect(result).toBe(ActionResult.Success);
+  });
+});

package/actionsExecutor/actions/appRestart.ts

@@ -0,0 +1,24 @@
+/// <reference types="@applicaster/applicaster-types" />
+import * as QuickBrickManager from "@applicaster/zapp-react-native-bridge/QuickBrick";
+import { QUICK_BRICK_EVENTS } from "@applicaster/zapp-react-native-bridge/QuickBrick";
+import { ActionResult } from "../ActionExecutor";
+import { ActionHandler } from "../types";
+import { createLogger } from "../../logger";
+
+const { log_info } = createLogger({
+  subsystem: "ActionExecutorContext",
+  category: "General",
+});
+
+/**
+ * Restarts the application by triggering a force reload event.
+ * This action does not require any options or context.
+ */
+export const appRestartAction: ActionHandler =
+  async (): Promise<ActionResult> => {
+    log_info(`handleAction: ${QUICK_BRICK_EVENTS.FORCE_APP_RELOAD} event`);
+
+    QuickBrickManager.sendQuickBrickEvent(QUICK_BRICK_EVENTS.FORCE_APP_RELOAD);
+
+    return ActionResult.Success;
+  };

package/actionsExecutor/actions/confirmDialog.ts

@@ -0,0 +1,53 @@
+/// <reference types="@applicaster/applicaster-types" />
+import { showConfirmationDialog } from "../../alertUtils";
+import { ActionResult } from "../ActionExecutor";
+import { ActionHandler } from "../types";
+import { createLogger } from "../../logger";
+
+const { log_info } = createLogger({
+  subsystem: "ActionExecutorContext",
+  category: "General",
+});
+
+/**
+ * Options for the confirmDialog action.
+ */
+export interface ConfirmDialogOptions {
+  /** Dialog title (required) */
+  title: string;
+
+  /** Dialog message */
+  message?: string;
+
+  /** Confirm button text */
+  okButtonText?: string;
+
+  /** Cancel button text */
+  cancelButtonText?: string;
+
+  /** Callback when confirmed (deprecated - use action result) */
+  confirmCompletion?: () => void;
+
+  /** Callback when cancelled (deprecated - use action result) */
+  cancelCompletion?: () => void;
+}
+
+/**
+ * Shows a confirmation dialog to the user.
+ * Resolves to Success if user confirms, Cancel if user dismisses.
+ */
+export const confirmDialogAction: ActionHandler<ConfirmDialogOptions> = async (
+  action
+): Promise<ActionResult> => {
+  log_info("handleAction: confirmDialog event");
+
+  const options = action.options as ConfirmDialogOptions;
+
+  return new Promise<ActionResult>((resolve) => {
+    showConfirmationDialog({
+      ...options,
+      confirmCompletion: () => resolve(ActionResult.Success),
+      cancelCompletion: () => resolve(ActionResult.Cancel),
+    });
+  });
+};

package/actionsExecutor/actions/dismissBottomSheet.ts

@@ -0,0 +1,23 @@
+/// <reference types="@applicaster/applicaster-types" />
+import { dismissModal, modalOrchestrator } from "../../modalState";
+import { ActionResult } from "../ActionExecutor";
+import { ActionHandler } from "../types";
+import { createLogger } from "../../logger";
+
+const { log_info } = createLogger({
+  subsystem: "ActionExecutorContext",
+  category: "General",
+});
+
+/**
+ * Dismisses the active bottom sheet / modal.
+ */
+export const dismissBottomSheetAction: ActionHandler<
+  any
+> = async (): Promise<ActionResult> => {
+  log_info("handleAction: dismissBottomSheet");
+  modalOrchestrator.close();
+  dismissModal();
+
+  return ActionResult.Success;
+};

package/actionsExecutor/actions/goBack.ts

@@ -0,0 +1,60 @@
+/// <reference types="@applicaster/applicaster-types" />
+import { ActionResult } from "../ActionExecutor";
+import { ActionHandler } from "../types";
+import { createLogger } from "../../logger";
+
+const { log_info } = createLogger({
+  subsystem: "ActionExecutorContext",
+  category: "General",
+});
+
+/**
+ * Options for the goBack action.
+ */
+export interface GoBackOptions {
+  /**
+   * Navigate to the home screen when there is no screen to go back to.
+   * Defaults to true.
+   */
+  fallbackToHome?: boolean;
+
+  /**
+   * Go back to the first screen of the stack instead of the previous one.
+   * Defaults to false.
+   */
+  backToTop?: boolean;
+}
+
+/**
+ * Creates a go back action handler with the provided dependencies.
+ * This factory pattern allows the action to access navigation state at runtime.
+ *
+ * @param navigator - The app navigator performing the back navigation
+ * @returns An action handler that navigates back
+ */
+export function createGoBackAction(
+  navigator: QuickBrickAppNavigator
+): ActionHandler<GoBackOptions> {
+  return async function goBackAction(action): Promise<ActionResult> {
+    const fallbackToHome = action.options?.fallbackToHome ?? true;
+    const backToTop = action.options?.backToTop ?? false;
+
+    // With fallbackToHome on, the navigator goes home on an empty stack by
+    // itself. The guard only matters when the caller opted out of that.
+    if (!fallbackToHome && !navigator.canGoBack()) {
+      log_info(
+        "goBack: no screen to go back to and fallbackToHome is disabled, ignoring"
+      );
+
+      return ActionResult.Error;
+    }
+
+    log_info(
+      `goBack: navigating back, fallbackToHome: ${fallbackToHome}, backToTop: ${backToTop}`
+    );
+
+    navigator.goBack(fallbackToHome, false, backToTop);
+
+    return ActionResult.Success;
+  };
+}

package/actionsExecutor/actions/goHome.ts

@@ -0,0 +1,31 @@
+/// <reference types="@applicaster/applicaster-types" />
+import { ActionResult } from "../ActionExecutor";
+import { ActionHandler } from "../types";
+import { createLogger } from "../../logger";
+
+const { log_info } = createLogger({
+  subsystem: "ActionExecutorContext",
+  category: "General",
+});
+
+/**
+ * Creates a go home action handler with the provided dependencies.
+ * This factory pattern allows the action to access navigation state at runtime.
+ *
+ * The navigator's `initialLaunch` flag is intentionally not exposed: it selects
+ * the offline home river during app bootstrap and is not a per-action choice.
+ *
+ * @param navigator - The app navigator performing the navigation
+ * @returns An action handler that navigates to the home screen
+ */
+export function createGoHomeAction(
+  navigator: QuickBrickAppNavigator
+): ActionHandler {
+  return async function goHomeAction(): Promise<ActionResult> {
+    log_info("goHome: navigating to the home screen");
+
+    navigator.goHome();
+
+    return ActionResult.Success;
+  };
+}