@applicaster/zapp-react-native-utils 16.0.0-alpha.3683430391 → 16.0.0-alpha.4004661200

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

@@ -0,0 +1,100 @@
+import { openBottomSheetAction } from "../openBottomSheet";
+import { 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();
+  });
+});

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: 1000,
+        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: 1000,
+        source: "confirmation",
+      },
+    ]);
+
+    expect(result).toBe(ActionResult.Success);
+  });
+});

package/actionsExecutor/actions/dismissBottomSheet.ts

@@ -0,0 +1,22 @@
+/// <reference types="@applicaster/applicaster-types" />
+import { dismissModal } 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");
+  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

@@ -27,4 +27,12 @@ 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/navigateToScreen.ts

@@ -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>;
 }
 
 /**
@@ -55,6 +68,7 @@ export function createNavigateToScreenAction(
 
     const navigationAction = action.options?.navigationAction;
     const entrySource = action.options?.entry;
+    const navigationOptions = action.options?.navigationOptions;
 
     const entry = entrySource
       ? entrySource === "@{entry/}"
@@ -83,10 +97,10 @@ export function createNavigateToScreenAction(
       };
 
       if (navigationAction === "push") {
-        navigator.push(overriddenEntry);
+        navigator.push(overriddenEntry, navigationOptions);
       } else {
         // Use replaceTop for entries since replace() only accepts ZappRiver
-        navigator.replaceTop(overriddenEntry);
+        navigator.replaceTop(overriddenEntry, navigationOptions);
       }
 
       return ActionResult.Success;
@@ -113,9 +127,9 @@ export function createNavigateToScreenAction(
     context?.callback?.({ success: false, error: null, abort: true });
 
     if (navigationAction === "push") {
-      navigator.push(river);
+      navigator.push(river, navigationOptions);
     } else {
-      navigator.replace(river);
+      navigator.replace(river, navigationOptions);
     }
 
     return ActionResult.Success;

package/actionsExecutor/actions/openBottomSheet.ts

@@ -0,0 +1,320 @@
+/// <reference types="@applicaster/applicaster-types" />
+import {
+  PipesClientResponseHelper,
+  RequestBuilder,
+} from "@applicaster/zapp-pipes-v2-client";
+import uuidv4 from "uuid/v4";
+import { modalOrchestrator } from "../../modalState/ModalOrchestrator";
+import { openBottomSheetModal } from "../../modalState/store";
+import {
+  DynamicCollectionOptions,
+  isPresentSubMenuAction,
+  Menu,
+  MenuItem,
+  Operation,
+  SelectionBehavior,
+} from "../../modalState/types";
+import { actionExecutor, ActionResult } from "../ActionExecutor";
+import { createLogger } from "../../logger";
+
+const { log_info, log_error } = createLogger({
+  subsystem: "ActionExecutorContext",
+  category: "General",
+});
+
+export type LoadedSheetContent = {
+  items: MenuItem[];
+  role?: string;
+  behavior?: SelectionBehavior;
+  dynamicCollection?: DynamicCollectionOptions;
+};
+
+/**
+ * Parse a raw `dynamic_collection_options` block (feed or inline content) into
+ * the typed `DynamicCollectionOptions`. `operations` accepts either a CSV
+ * string (feed) or an array (already parsed).
+ */
+export function parseDynamicCollectionOptions(
+  raw:
+    | {
+        operations?: string | string[];
+        postUrl?: string;
+        provider?: string;
+        events?: Record<string, any[]>;
+      }
+    | undefined
+): DynamicCollectionOptions | undefined {
+  if (!raw) {
+    return undefined;
+  }
+
+  const operations = Array.isArray(raw.operations)
+    ? (raw.operations as Operation[])
+    : ((raw.operations || "").split(",").filter(Boolean) as Operation[]);
+
+  return {
+    operations,
+    postUrl: raw.postUrl,
+    provider: raw.provider,
+    events: raw.events,
+  };
+}
+
+/**
+ * Converts a ZappEntry from a pipes feed into a MenuItem.
+ * - Icon: first src found in the image media_group.
+ * - Primary action: taken from tap_actions.actions[0].
+ * - isSelected: true when entry.id is in currentSelection.
+ */
+export function entryToMenuItem(
+  entry: ZappEntry,
+  currentSelection: string[] = []
+): MenuItem {
+  const imageGroup = entry.media_group?.find((g) => g.type === "image");
+
+  const firstImage = Array.isArray(imageGroup?.media_item)
+    ? imageGroup.media_item[0]
+    : imageGroup?.media_item;
+
+  // Primary action — first tap_action on the entry
+  const tapActions = entry.extensions?.tap_actions?.actions || [];
+  const primaryAction = tapActions.length > 0 ? tapActions[0] : undefined;
+
+  const summary = entry.summary as string;
+
+  const itemId = String(entry.id ?? entry.title ?? uuidv4());
+
+  return {
+    id: itemId,
+    title: entry.title as string,
+    summary,
+    icon: firstImage?.src,
+    isSelected: currentSelection.includes(itemId),
+    action: primaryAction,
+    entryActions: entry.extensions?.entry_action || [],
+  };
+}
+
+function parseCurrentSelection(rawSelection: unknown): string[] {
+  if (Array.isArray(rawSelection)) {
+    return (rawSelection as any[]).map(String);
+  }
+
+  if (rawSelection !== undefined && rawSelection !== null) {
+    return [String(rawSelection)];
+  }
+
+  return [];
+}
+
+function parseBehaviorFromFeed(
+  feed: ZappFeed | undefined,
+  currentSelection: string[]
+): SelectionBehavior | undefined {
+  const raw = feed?.extensions?.behavior;
+
+  if (!raw && currentSelection.length === 0) {
+    return undefined;
+  }
+
+  return {
+    selectMode: raw?.select_mode,
+    currentSelection,
+    selector: raw?.selector,
+  };
+}
+
+function parseBehaviorFromContentOptions(
+  content: Record<string, any> | undefined
+): SelectionBehavior | undefined {
+  const raw = content?.behavior ?? content?.extensions?.behavior;
+
+  if (!raw) {
+    return undefined;
+  }
+
+  return {
+    selectMode: raw.selectMode ?? raw.select_mode,
+    currentSelection: parseCurrentSelection(
+      raw.currentSelection ?? raw.current_selection
+    ),
+    selector: raw.selector,
+  };
+}
+
+// Exported so MultiLevelBottomSheetContent can lazy-load sub-levels
+export async function loadItemsFromSource(
+  source: string,
+  context?: Record<string, any>
+): Promise<LoadedSheetContent> {
+  const requestBuilder = new RequestBuilder()
+    .setEntryContext(context?.entry || {})
+    .setScreenContext(context?.screenData || {})
+    .setUrl(source);
+
+  await requestBuilder.buildAxiosRequest();
+
+  const responseData = await requestBuilder.call<ZappFeed>();
+
+  const responseHelper = new PipesClientResponseHelper(responseData);
+
+  if (responseHelper.error) {
+    throw responseHelper.error;
+  }
+
+  const feed = responseData?.response as ZappFeed;
+
+  const currentSelection = parseCurrentSelection(
+    feed?.extensions?.behavior?.current_selection
+  );
+
+  const items = (feed?.entry || []).map((entry) =>
+    entryToMenuItem(entry, currentSelection)
+  );
+
+  const dynamicCollectionOptions = feed?.extensions?.dynamic_collection_options;
+
+  const dynamicCollection = parseDynamicCollectionOptions(
+    dynamicCollectionOptions
+  );
+
+  return {
+    items,
+    role: feed?.extensions?.role,
+    behavior: parseBehaviorFromFeed(feed, currentSelection),
+    dynamicCollection,
+  };
+}
+
+export async function openBottomSheetAction(
+  action: ActionType,
+  context?: Record<string, any>
+): Promise<ActionResult> {
+  try {
+    const { content, header, themePluginId, styleOverrides } =
+      action.options || {};
+
+    // Custom body component — keep default ModalComponent so standard header
+    // (dismiss x) is used; content.component is body-only (e.g. TextInputContent).
+    if (content?.component) {
+      log_info("openBottomSheet: using custom content component");
+
+      openBottomSheetModal({
+        modalBottomSheetContentProps: {
+          title: header?.title,
+          summary: header?.subtitle,
+          items: [],
+          onPress: () => {},
+          contentComponent: content.component,
+          contentComponentProps: content.props || {},
+        },
+      });
+
+      return ActionResult.Success;
+    }
+
+    const inlineItems: ZappEntry[] = content?.items;
+    const itemsUrl: string = content?.itemsUrl;
+
+    let items: MenuItem[];
+    let role: string | undefined;
+    let behavior: SelectionBehavior | undefined;
+
+    let dynamicCollection: DynamicCollectionOptions | undefined;
+
+    if (Array.isArray(inlineItems) && inlineItems.length > 0) {
+      log_info("openBottomSheet: using inline items from action options", {
+        count: inlineItems.length,
+      });
+
+      role = content?.role ?? content?.extensions?.role;
+      behavior = parseBehaviorFromContentOptions(content);
+
+      items = inlineItems.map((entry) =>
+        entryToMenuItem(entry, behavior?.currentSelection ?? [])
+      );
+
+      dynamicCollection = parseDynamicCollectionOptions(
+        content?.dynamicCollection ??
+          content?.extensions?.dynamic_collection_options
+      );
+    } else if (itemsUrl) {
+      log_info(`openBottomSheet: loading items from source: ${itemsUrl}`);
+
+      const loaded = await loadItemsFromSource(itemsUrl, context);
+      items = loaded.items;
+      role = loaded.role ?? content?.role ?? content?.extensions?.role;
+      behavior = loaded.behavior ?? parseBehaviorFromContentOptions(content);
+      dynamicCollection = loaded.dynamicCollection;
+
+      log_info(
+        `openBottomSheet: loaded ${items.length} items from source: ${itemsUrl}`
+      );
+    } else {
+      log_error(
+        "openBottomSheet: no itemsUrl, items, or content.component provided in action options"
+      );
+
+      return ActionResult.Error;
+    }
+
+    const menu: Menu = {
+      header: header
+        ? {
+            title: header.title,
+            subtitle: header.subtitle,
+            icon: header.icon,
+          }
+        : undefined,
+      content: {
+        title: content?.title ?? "",
+        items,
+        itemsUrl, // stored so the component can reload after an action
+        role,
+        behavior,
+        dynamicCollection,
+        themePluginId,
+        styleOverrides: styleOverrides ?? content?.styleOverrides,
+      },
+    };
+
+    /**
+     * Called when the user taps a menu item.
+     *
+     * - PresentSubMenuAction  → handled by the orchestrator (pushes sub-menu)
+     * - Any other Action type → forwarded to the action executor, keeping the
+     *   original execution context so screen/entry data is available to handlers.
+     *   The pressed item is also added as `entry` so downstream actions can
+     *   reference it.
+     */
+    const onItemPress = async (item: MenuItem): Promise<void> => {
+      if (!item.action || isPresentSubMenuAction(item.action)) {
+        // Submenu navigation is handled internally by the orchestrator
+        return;
+      }
+
+      await actionExecutor.handleAction(
+        item.action as ActionType,
+        {
+          ...context,
+          entry: item as any,
+        } as any
+      );
+    };
+
+    if (action.options?.replace) {
+      modalOrchestrator.replace(menu, onItemPress);
+    } else {
+      modalOrchestrator.open(menu, onItemPress);
+    }
+
+    return ActionResult.Success;
+  } catch (error) {
+    log_error("openBottomSheet: failed to open bottom sheet", {
+      error,
+      action,
+    });
+
+    return ActionResult.Error;
+  }
+}

package/actionsExecutor/actions/refreshComponent.ts

@@ -57,6 +57,12 @@ export const refreshComponentAction: ActionHandler = async (
       }) || source;
   }
 
+  if (!dataSource) {
+    log_info("handleAction: refreshComponent skipped: no dataSource found");
+
+    return ActionResult.Success;
+  }
+
   log_info(`handleAction: refreshComponent for dataSource:${dataSource}`, {
     source,
     inflatedUrl: dataSource,