@applicaster/zapp-react-native-utils 16.0.0-alpha.2663208063 → 16.0.0-alpha.2710214351

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

@@ -31,7 +31,7 @@ describe("showToastAction", () => {
         message: "Added to queue",
         extraMessage: "Extra info",
         style: undefined,
-        timeout: 1000,
+        timeout: 5000,
         source: "confirmation",
       },
     ]);
@@ -78,7 +78,7 @@ describe("showToastAction", () => {
         message: undefined,
         extraMessage: undefined,
         style: undefined,
-        timeout: 1000,
+        timeout: 5000,
         source: "confirmation",
       },
     ]);

package/actionsExecutor/actions/dismissBottomSheet.ts

@@ -1,5 +1,5 @@
 /// <reference types="@applicaster/applicaster-types" />
-import { dismissModal } from "../../modalState";
+import { dismissModal, modalOrchestrator } from "../../modalState";
 import { ActionResult } from "../ActionExecutor";
 import { ActionHandler } from "../types";
 import { createLogger } from "../../logger";
@@ -16,6 +16,7 @@ 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;
+  };
+}

package/actionsExecutor/actions/index.ts

@@ -15,6 +15,8 @@ export { appRestartAction } from "./appRestart";
 
 export { confirmDialogAction } from "./confirmDialog";
 
+export { showAlertAction } from "./showAlert";
+
 export { sendCloudEventAction } from "./sendCloudEvent";
 
 export { sessionStorageToggleFlagAction } from "./sessionStorageToggleFlag";
@@ -27,6 +29,12 @@ export { screenToggleFlagAction } from "./screenToggleFlag";
 
 export { createNavigateToScreenAction } from "./navigateToScreen";
 
+export { createPresentScreenAction } from "./presentScreen";
+
+export { createGoBackAction } from "./goBack";
+
+export { createGoHomeAction } from "./goHome";
+
 export { showToastAction } from "./showToast";
 
 export { openBottomSheetAction } from "./openBottomSheet";

package/actionsExecutor/actions/navigateToScreen.ts

@@ -13,7 +13,7 @@ const { log_info, log_error } = createLogger({
  */
 export interface NavigateToScreenOptions {
   /** The screen type to navigate to (from content types mapping) */
-  typeMapping: string;
+  typeMapping?: string;
 
   /** Navigation action: push adds to history, replace replaces current screen */
   navigationAction?: "push" | "replace";
@@ -25,6 +25,19 @@ export interface NavigateToScreenOptions {
    * - undefined to navigate to screen without entry
    */
   entry?: "@{entry/}" | ZappEntry;
+
+  /**
+   * Arbitrary values passed through to the destination screen.
+   *
+   * They are stored on the navigation route as `NavigationScreenData.options`
+   * and read on the target screen via `useNavigation().data?.options`. Use this
+   * to hand per-navigation parameters to a screen instead of routing them
+   * through module-level state.
+   *
+   * Note: `legacyScreenData()` does not carry these values, so they are not
+   * visible through `useCurrentScreenData()` / `useRoute()`.
+   */
+  navigationOptions?: Record<string, unknown>;
 }
 
 /**
@@ -45,16 +58,9 @@ export function createNavigateToScreenAction(
     action,
     context?: ActionExecutionContext
   ): Promise<ActionResult> {
-    const screenType = action.options?.typeMapping;
-
-    if (!screenType) {
-      log_error("navigateToScreen: typeMapping option is missing");
-
-      return ActionResult.Error;
-    }
-
     const navigationAction = action.options?.navigationAction;
     const entrySource = action.options?.entry;
+    const navigationOptions = action.options?.navigationOptions;
 
     const entry = entrySource
       ? entrySource === "@{entry/}"
@@ -62,61 +68,53 @@ export function createNavigateToScreenAction(
         : entrySource
       : null;
 
-    if (entry) {
-      if (typeof entry !== "object") {
-        log_error(
-          `navigateToScreen: entry option is not an object, entry: ${entry}`
-        );
+    const screenType = action.options?.typeMapping || entry?.type?.value;
 
-        return ActionResult.Error;
-      }
+    const navigate =
+      navigationAction === "push" ? navigator.push : navigator.replace;
+
+    let navigatingEntry: ZappEntry | ZappRiver = entry;
 
+    if (entry && screenType) {
       log_info(
         `navigateToScreen: navigating to screen type: ${screenType} with entry id: ${entry.id}`
       );
 
-      const overriddenEntry: ZappEntry = {
+      navigatingEntry = {
         ...entry,
-        type: {
-          value: screenType,
-        },
+        type: { value: screenType },
       };
+    } else {
+      if (!screenType) {
+        log_error(
+          "navigateToScreen: options.typeMapping or entry?.type?.value is not provided"
+        );
 
-      if (navigationAction === "push") {
-        navigator.push(overriddenEntry);
-      } else {
-        // Use replaceTop for entries since replace() only accepts ZappRiver
-        navigator.replaceTop(overriddenEntry);
+        return ActionResult.Error;
       }
 
-      return ActionResult.Success;
-    }
-
-    const screenId = contentTypes?.[screenType]?.screen_id || null;
+      const screenId = contentTypes?.[screenType]?.screen_id || null;
+      const river = rivers?.[screenId];
 
-    if (!screenId) {
-      log_error(
-        `navigateToScreen: can not resolve screen type mapping: ${screenType}`
-      );
+      if (!screenId) {
+        log_error(
+          `navigateToScreen: can not resolve screen type mapping: ${screenType}`
+        );
 
-      return ActionResult.Error;
-    }
+        return ActionResult.Error;
+      }
 
-    const river = rivers[screenId];
+      if (!river) {
+        log_error("navigateToScreen: can not resolve river");
 
-    if (!river) {
-      log_error("navigateToScreen: can not resolve river");
+        return ActionResult.Error;
+      }
 
-      return ActionResult.Error;
+      navigatingEntry = river;
     }
 
     context?.callback?.({ success: false, error: null, abort: true });
-
-    if (navigationAction === "push") {
-      navigator.push(river);
-    } else {
-      navigator.replace(river);
-    }
+    navigate(navigatingEntry, navigationOptions);
 
     return ActionResult.Success;
   };

package/actionsExecutor/actions/openBottomSheet.ts

@@ -8,6 +8,7 @@ import { modalOrchestrator } from "../../modalState/ModalOrchestrator";
 import { openBottomSheetModal } from "../../modalState/store";
 import {
   DynamicCollectionOptions,
+  getMenuItemActions,
   isPresentSubMenuAction,
   Menu,
   MenuItem,
@@ -91,6 +92,7 @@ export function entryToMenuItem(
     icon: firstImage?.src,
     isSelected: currentSelection.includes(itemId),
     action: primaryAction,
+    actions: tapActions,
     entryActions: entry.extensions?.entry_action || [],
   };
 }
@@ -206,7 +208,11 @@ export async function openBottomSheetAction(
           items: [],
           onPress: () => {},
           contentComponent: content.component,
-          contentComponentProps: content.props || {},
+          contentComponentProps: {
+            ...(content.props || {}),
+            actionContext: context,
+          },
+          themePluginId,
         },
       });
 
@@ -222,7 +228,18 @@ export async function openBottomSheetAction(
 
     let dynamicCollection: DynamicCollectionOptions | undefined;
 
-    if (Array.isArray(inlineItems) && inlineItems.length > 0) {
+    const rawDynamicCollection =
+      content?.dynamicCollection ??
+      content?.extensions?.dynamic_collection_options;
+
+    // An empty items array is a valid starting state for a provider-backed or
+    // offline collection. A sheet with neither items nor a source still errors.
+    const hasDynamicCollection = Boolean(rawDynamicCollection);
+
+    if (
+      Array.isArray(inlineItems) &&
+      (inlineItems.length > 0 || hasDynamicCollection)
+    ) {
       log_info("openBottomSheet: using inline items from action options", {
         count: inlineItems.length,
       });
@@ -234,10 +251,7 @@ export async function openBottomSheetAction(
         entryToMenuItem(entry, behavior?.currentSelection ?? [])
       );
 
-      dynamicCollection = parseDynamicCollectionOptions(
-        content?.dynamicCollection ??
-          content?.extensions?.dynamic_collection_options
-      );
+      dynamicCollection = parseDynamicCollectionOptions(rawDynamicCollection);
     } else if (itemsUrl) {
       log_info(`openBottomSheet: loading items from source: ${itemsUrl}`);
 
@@ -275,6 +289,9 @@ export async function openBottomSheetAction(
         dynamicCollection,
         themePluginId,
         styleOverrides: styleOverrides ?? content?.styleOverrides,
+        emptyMessage: content?.emptyMessage,
+        operationButtons: content?.operationButtons,
+        context,
       },
     };
 
@@ -288,18 +305,21 @@ export async function openBottomSheetAction(
      *   reference it.
      */
     const onItemPress = async (item: MenuItem): Promise<void> => {
-      if (!item.action || isPresentSubMenuAction(item.action)) {
-        // Submenu navigation is handled internally by the orchestrator
-        return;
-      }
+      const actions = getMenuItemActions(item);
 
-      await actionExecutor.handleAction(
-        item.action as ActionType,
-        {
-          ...context,
-          entry: item as any,
-        } as any
+      const executableActions = actions.filter(
+        (action) => !isPresentSubMenuAction(action)
       );
+
+      if (executableActions.length > 0) {
+        await actionExecutor.handleActions(
+          executableActions as ActionType[],
+          {
+            ...context,
+            entry: item as any,
+          } as any
+        );
+      }
     };
 
     if (action.options?.replace) {

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/actions/screenToggleFlag.ts

@@ -27,12 +27,10 @@ export const screenToggleFlagAction: ActionHandler<
   const screenRoute = context?.screenRoute;
   const screenStateStore = context?.screenStateStore;
 
-  await screenToggleFlag(
+  return await screenToggleFlag(
     screenRoute,
     screenStateStore,
     { entry: context?.entry, options: action.options },
     action
   );
-
-  return ActionResult.Success;
 };