@applicaster/zapp-react-native-utils 16.0.0-rc.75 → 16.0.0-rc.77

package/actionsExecutor/ActionExecutorContext.tsx

@@ -18,6 +18,8 @@ import { createLogger } from "../logger";
 import {
   appRestartAction,
   confirmDialogAction,
+  createGoBackAction,
+  createGoHomeAction,
   createNavigateToScreenAction,
   dismissBottomSheetAction,
   localStorageRemoveAction,
@@ -189,6 +191,20 @@ export function withActionExecutor(Component) {
       );
     }, [navigator, rivers, contentTypes]);
 
+    useEffect(() => {
+      return _actionExecutor.registerAction(
+        ACTION_TYPES.GO_BACK,
+        createGoBackAction(navigator)
+      );
+    }, [navigator]);
+
+    useEffect(() => {
+      return _actionExecutor.registerAction(
+        ACTION_TYPES.GO_HOME,
+        createGoHomeAction(navigator)
+      );
+    }, [navigator]);
+
     return (
       <ActionExecutorContext.Provider value={handlers}>
         <Component {...props} />

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

@@ -0,0 +1,62 @@
+import { createGoBackAction } from "../goBack";
+import { ActionResult } from "../../ActionExecutor";
+
+function createNavigator(canGoBack = true) {
+  return {
+    goBack: jest.fn(),
+    canGoBack: jest.fn().mockReturnValue(canGoBack),
+  } as unknown as QuickBrickAppNavigator;
+}
+
+describe("goBack", () => {
+  it("goes back with fallbackToHome enabled when no options are provided", async () => {
+    const navigator = createNavigator();
+
+    const result = await createGoBackAction(navigator)({ type: "goBack" });
+
+    expect(navigator.goBack).toHaveBeenCalledWith(true, false, false);
+    expect(result).toBe(ActionResult.Success);
+  });
+
+  it("forwards backToTop", async () => {
+    const navigator = createNavigator();
+
+    const action = {
+      type: "goBack",
+      options: { backToTop: true },
+    };
+
+    const result = await createGoBackAction(navigator)(action);
+
+    expect(navigator.goBack).toHaveBeenCalledWith(true, false, true);
+    expect(result).toBe(ActionResult.Success);
+  });
+
+  it("goes back without falling back to home when the stack allows it", async () => {
+    const navigator = createNavigator(true);
+
+    const action = {
+      type: "goBack",
+      options: { fallbackToHome: false },
+    };
+
+    const result = await createGoBackAction(navigator)(action);
+
+    expect(navigator.goBack).toHaveBeenCalledWith(false, false, false);
+    expect(result).toBe(ActionResult.Success);
+  });
+
+  it("does nothing when there is nothing to go back to and fallbackToHome is off", async () => {
+    const navigator = createNavigator(false);
+
+    const action = {
+      type: "goBack",
+      options: { fallbackToHome: false },
+    };
+
+    const result = await createGoBackAction(navigator)(action);
+
+    expect(navigator.goBack).not.toHaveBeenCalled();
+    expect(result).toBe(ActionResult.Error);
+  });
+});

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

@@ -0,0 +1,19 @@
+import { createGoHomeAction } from "../goHome";
+import { ActionResult } from "../../ActionExecutor";
+
+function createNavigator() {
+  return {
+    goHome: jest.fn(),
+  } as unknown as QuickBrickAppNavigator;
+}
+
+describe("goHome", () => {
+  it("navigates to the home screen", async () => {
+    const navigator = createNavigator();
+
+    const result = await createGoHomeAction(navigator)({ type: "goHome" });
+
+    expect(navigator.goHome).toHaveBeenCalledWith();
+    expect(result).toBe(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

@@ -27,6 +27,10 @@ export { screenToggleFlagAction } from "./screenToggleFlag";
 
 export { createNavigateToScreenAction } from "./navigateToScreen";
 
+export { createGoBackAction } from "./goBack";
+
+export { createGoHomeAction } from "./goHome";
+
 export { showToastAction } from "./showToast";
 
 export { openBottomSheetAction } from "./openBottomSheet";

package/actionsExecutor/consts.ts

@@ -9,6 +9,8 @@ export const ACTION_TYPES = {
   PRESENT_SUB_MENU: "presentSubMenu",
   SEND_CLOUD_EVENT: "sendCloudEvent",
   NAVIGATE_TO_SCREEN: "navigateToScreen",
+  GO_BACK: "goBack",
+  GO_HOME: "goHome",
   SHOW_TOAST: "showToast",
   LOCAL_STORAGE_SET: "localStorageSet",
   LOCAL_STORAGE_REMOVE: "localStorageRemove",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applicaster/zapp-react-native-utils",
-  "version": "16.0.0-rc.75",
+  "version": "16.0.0-rc.77",
   "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.75",
+    "@applicaster/applicaster-types": "16.0.0-rc.77",
     "buffer": "^5.2.1",
     "camelize": "^1.0.0",
     "dayjs": "^1.11.10",