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

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

package/actionsExecutor/actions/index.ts

@@ -0,0 +1,38 @@
+// Export action handlers
+export { localStorageSetAction } from "./localStorageSet";
+
+export { sessionStorageSetAction } from "./sessionStorageSet";
+
+export { localStorageRemoveAction } from "./localStorageRemove";
+
+export { sessionStorageRemoveAction } from "./sessionStorageRemove";
+
+export { refreshComponentAction } from "./refreshComponent";
+
+export { switchLayoutAction } from "./switchLayout";
+
+export { appRestartAction } from "./appRestart";
+
+export { confirmDialogAction } from "./confirmDialog";
+
+export { sendCloudEventAction } from "./sendCloudEvent";
+
+export { sessionStorageToggleFlagAction } from "./sessionStorageToggleFlag";
+
+export { localStorageToggleFlagAction } from "./localStorageToggleFlag";
+
+export { screenSetVariableAction } from "./screenSetVariable";
+
+export { screenToggleFlagAction } from "./screenToggleFlag";
+
+export { createNavigateToScreenAction } from "./navigateToScreen";
+
+export { createGoBackAction } from "./goBack";
+
+export { createGoHomeAction } from "./goHome";
+
+export { showToastAction } from "./showToast";
+
+export { openBottomSheetAction } from "./openBottomSheet";
+
+export { dismissBottomSheetAction } from "./dismissBottomSheet";

package/actionsExecutor/actions/localStorageRemove.ts

@@ -0,0 +1,27 @@
+/// <reference types="@applicaster/applicaster-types" />
+import { localStorage } from "@applicaster/zapp-react-native-bridge/ZappStorage/LocalStorage";
+import { batchRemoveFromStorage } from "../../zappFrameworkUtils/localStorageHelper";
+import { ActionResult } from "../ActionExecutor";
+import { ActionHandler } from "../types";
+import { StorageValuesToRemove } from "../../zappFrameworkUtils/types";
+
+/**
+ * Options for localStorage/sessionStorage remove actions.
+ */
+export interface StorageRemoveOptions {
+  /** The keys to remove, organized by namespace */
+  content: StorageValuesToRemove;
+}
+
+/**
+ * Removes values from local storage organized by namespaces.
+ */
+export const localStorageRemoveAction: ActionHandler<
+  StorageRemoveOptions
+> = async (action): Promise<ActionResult> => {
+  const namespaces = action.options.content;
+  await batchRemoveFromStorage(namespaces, localStorage);
+  // TODO: Add support for ownershipKey and ownershipNamespace
+
+  return ActionResult.Success;
+};

package/actionsExecutor/actions/localStorageSet.ts

@@ -0,0 +1,28 @@
+/// <reference types="@applicaster/applicaster-types" />
+import { localStorage } from "@applicaster/zapp-react-native-bridge/ZappStorage/LocalStorage";
+import { batchSave } from "../../zappFrameworkUtils/localStorageHelper";
+import { ActionResult } from "../ActionExecutor";
+import { ActionHandler } from "../types";
+import { StorageValuesToAdd } from "../../zappFrameworkUtils/types";
+
+/**
+ * Options for localStorage/sessionStorage set actions.
+ */
+export interface StorageSetOptions {
+  /** The values to save, organized by namespace */
+  content: StorageValuesToAdd;
+}
+
+/**
+ * Saves values to local storage organized by namespaces.
+ * The values persist across app sessions.
+ */
+export const localStorageSetAction: ActionHandler<StorageSetOptions> = async (
+  action
+): Promise<ActionResult> => {
+  const namespaces = action.options.content;
+  await batchSave(namespaces, localStorage);
+  // TODO: Add support for ownershipKey and ownershipNamespace
+
+  return ActionResult.Success;
+};

package/actionsExecutor/actions/localStorageToggleFlag.ts

@@ -0,0 +1,28 @@
+/// <reference types="@applicaster/applicaster-types" />
+import { localStorageToggleFlag } from "../StorageActions";
+import { ActionResult } from "../ActionExecutor";
+import { ActionHandler, ActionExecutionContext } from "../types";
+
+/**
+ * Options for storage toggle flag actions (localStorage/sessionStorage).
+ */
+export interface StorageToggleFlagOptions {
+  /** The key/namespace for storing the flag */
+  key: string;
+
+  /** Path to extract the tag from entry */
+  selector?: string;
+
+  /** Maximum number of items that can be selected */
+  max_items?: number;
+}
+
+/**
+ * Toggles a flag in local storage (adds or removes an item from a collection).
+ * Used for features like favorites, watchlists, etc.
+ */
+export const localStorageToggleFlagAction: ActionHandler<
+  StorageToggleFlagOptions
+> = async (action, context?: ActionExecutionContext): Promise<ActionResult> => {
+  return await localStorageToggleFlag(context, action);
+};

package/actionsExecutor/actions/navigateToScreen.ts

@@ -0,0 +1,137 @@
+/// <reference types="@applicaster/applicaster-types" />
+import { ActionResult } from "../ActionExecutor";
+import { ActionHandler, ActionExecutionContext } from "../types";
+import { createLogger } from "../../logger";
+
+const { log_info, log_error } = createLogger({
+  subsystem: "ActionExecutorContext",
+  category: "General",
+});
+
+/**
+ * Options for the navigateToScreen action.
+ */
+export interface NavigateToScreenOptions {
+  /** The screen type to navigate to (from content types mapping) */
+  typeMapping: string;
+
+  /** Navigation action: push adds to history, replace replaces current screen */
+  navigationAction?: "push" | "replace";
+
+  /**
+   * Entry to navigate with. Can be:
+   * - "@{entry/}" to use the context entry
+   * - A ZappEntry object
+   * - 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>;
+}
+
+/**
+ * Creates a navigation action handler with the provided dependencies.
+ * This factory pattern allows the action to access navigation state at runtime.
+ *
+ * @param navigator - The app navigator for push/replace operations
+ * @param rivers - Map of screen IDs to river definitions
+ * @param contentTypes - Map of content type names to screen configurations
+ * @returns An action handler that performs screen navigation
+ */
+export function createNavigateToScreenAction(
+  navigator: QuickBrickAppNavigator,
+  rivers: Record<string, ZappRiver>,
+  contentTypes: ZappContentTypes
+): ActionHandler<NavigateToScreenOptions> {
+  return async function navigateToScreenAction(
+    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/}"
+        ? context?.entry
+        : entrySource
+      : null;
+
+    if (entry) {
+      if (typeof entry !== "object") {
+        log_error(
+          `navigateToScreen: entry option is not an object, entry: ${entry}`
+        );
+
+        return ActionResult.Error;
+      }
+
+      log_info(
+        `navigateToScreen: navigating to screen type: ${screenType} with entry id: ${entry.id}`
+      );
+
+      const overriddenEntry: ZappEntry = {
+        ...entry,
+        type: {
+          value: screenType,
+        },
+      };
+
+      if (navigationAction === "push") {
+        navigator.push(overriddenEntry, navigationOptions);
+      } else {
+        // Use replaceTop for entries since replace() only accepts ZappRiver
+        navigator.replaceTop(overriddenEntry, navigationOptions);
+      }
+
+      return ActionResult.Success;
+    }
+
+    const screenId = contentTypes?.[screenType]?.screen_id || null;
+
+    if (!screenId) {
+      log_error(
+        `navigateToScreen: can not resolve screen type mapping: ${screenType}`
+      );
+
+      return ActionResult.Error;
+    }
+
+    const river = rivers[screenId];
+
+    if (!river) {
+      log_error("navigateToScreen: can not resolve river");
+
+      return ActionResult.Error;
+    }
+
+    context?.callback?.({ success: false, error: null, abort: true });
+
+    if (navigationAction === "push") {
+      navigator.push(river, navigationOptions);
+    } else {
+      navigator.replace(river, navigationOptions);
+    }
+
+    return ActionResult.Success;
+  };
+}