@applicaster/zapp-react-native-utils 16.0.0-alpha.2434153375 → 16.0.0-alpha.2500443242

package/modalState/ModalOrchestrator.ts

@@ -1,10 +1,16 @@
 import { dismissModal, modalStore, openBottomSheetModal } from "./store";
-import { isPresentSubMenuAction, Menu, MenuItem } from "./types";
+import {
+  getMenuItemActions,
+  isPresentSubMenuAction,
+  Menu,
+  MenuItem,
+  PresentSubMenuAction,
+} from "./types";
 import { ContentViewModel } from "./ContentViewModel";
 
 export type { Menu, MenuItem };
 
-export { isPresentSubMenuAction };
+export { isPresentSubMenuAction, getMenuItemActions };
 
 /**
  * Converts a Menu model into the props expected by BottomSheetModalContent.
@@ -38,6 +44,7 @@ function menuToModalArgs(
       title: menu.header?.title ?? menu.content.title,
       summary: menu.header?.subtitle,
       styleOverrides: menu.content.styleOverrides,
+      emptyMessage: menu.content.emptyMessage,
       onPress: onItemPress,
       viewModel,
     },
@@ -136,15 +143,21 @@ class ModalOrchestrator {
   private _buildOnPress(
     onItemPress?: (item: MenuItem) => void | Promise<void>
   ): (item: MenuItem) => void | Promise<void> {
-    return (item: MenuItem) => {
-      if (isPresentSubMenuAction(item.action)) {
-        // Navigate deeper into the sub-menu
-        this.open(item.action.menu, onItemPress);
-
-        return;
+    return async (item: MenuItem) => {
+      if (onItemPress) {
+        await onItemPress(item);
       }
 
-      return onItemPress?.(item);
+      const actions = getMenuItemActions(item);
+
+      const subMenuAction = actions.find(isPresentSubMenuAction) as
+        | PresentSubMenuAction
+        | undefined;
+
+      if (subMenuAction) {
+        // Navigate deeper into the sub-menu
+        this.open(subMenuAction.menu, onItemPress);
+      }
     };
   }
 

package/modalState/RemoteEditableCollection.ts

@@ -123,7 +123,14 @@ export class RemoteEditableCollection implements EditableCollection {
 
     try {
       for (const action of addEvents) {
-        await actionExecutor.handleAction(action as any);
+        if (this.content.context) {
+          await actionExecutor.handleAction(
+            action as any,
+            this.content.context
+          );
+        } else {
+          await actionExecutor.handleAction(action as any);
+        }
       }
     } catch (e) {
       actionFailed = true;
@@ -219,6 +226,7 @@ export class RemoteEditableCollection implements EditableCollection {
       await actionExecutor.handleAction(
         actionToExecute as any,
         {
+          ...this.content.context,
           entry: item as any,
         } as any
       );

package/modalState/__tests__/ModalOrchestrator.phase3.test.ts

@@ -44,4 +44,20 @@ describe("ModalOrchestrator phase 3", () => {
     expect(props.title).toBe("Sleep Timer");
     expect(props.summary).toBe("remaining");
   });
+
+  it("forwards the queue empty message onto the sheet props", () => {
+    modalOrchestrator.open({
+      header: { title: "Queue" },
+      content: {
+        title: "Queue",
+        items: [],
+        emptyMessage: "Queued items will be added here",
+      },
+    });
+
+    const props = (modalStore.getState().modalState.screen as any)
+      ?.modalBottomSheetContentProps;
+
+    expect(props.emptyMessage).toBe("Queued items will be added here");
+  });
 });

package/modalState/__tests__/RemoteEditableCollection.test.ts

@@ -34,16 +34,26 @@ const itemPlain: MenuItem = { id: "2", title: "B" };
 function makeCollection(
   items: MenuItem[],
   refetch = jest.fn().mockResolvedValue(undefined),
-  operations = ["remove", "reorder"]
+  operations = ["remove", "reorder"],
+  context?: Record<string, unknown>
 ) {
   const content = {
     items,
+    context,
     dynamicCollection: { operations, postUrl: "https://x/cloud-events" },
   } as unknown as Content;
 
   return { col: new RemoteEditableCollection(content, refetch), refetch };
 }
 
+const openingContext = {
+  component: {
+    id: "list-1",
+    data: { source: "https://example.com/user/collections/abc" },
+  },
+  screenData: { id: "playlist-screen" },
+};
+
 describe("RemoteEditableCollection", () => {
   beforeEach(() => jest.clearAllMocks());
 
@@ -118,6 +128,24 @@ describe("RemoteEditableCollection", () => {
       expect(refetch).toHaveBeenCalledTimes(1);
       expect(currentItems(col)).toEqual([itemWithRemove]);
     });
+
+    it("forwards stored sheet context plus the removed item as entry", async () => {
+      handleAction.mockResolvedValue("success");
+
+      const { col } = makeCollection(
+        [itemWithRemove, itemPlain],
+        jest.fn().mockResolvedValue(undefined),
+        ["remove", "reorder"],
+        openingContext
+      );
+
+      await col.remove(0);
+
+      expect(handleAction).toHaveBeenCalledWith(removeAction, {
+        ...openingContext,
+        entry: itemWithRemove,
+      });
+    });
   });
 
   describe("move", () => {
@@ -164,6 +192,35 @@ describe("RemoteEditableCollection", () => {
       expect(refetch).toHaveBeenCalledTimes(1);
     });
 
+    it("forwards stored sheet context plus the moved item as entry", async () => {
+      handleAction.mockResolvedValue("success");
+
+      const itemA: MenuItem = {
+        id: "2",
+        title: "B",
+        entryActions: [
+          { button: { alias: "reorder_item" }, actions: [removeAction] },
+        ],
+      };
+
+      const { col } = makeCollection(
+        [itemA],
+        jest.fn().mockResolvedValue(undefined),
+        ["remove", "reorder"],
+        openingContext
+      );
+
+      await col.move(["2"]);
+
+      expect(handleAction).toHaveBeenCalledWith(
+        expect.objectContaining({ type: "sendCloudEvent" }),
+        {
+          ...openingContext,
+          entry: itemA,
+        }
+      );
+    });
+
     it("rolls back on failure", async () => {
       handleAction.mockRejectedValue(new Error("nope"));
 
@@ -322,5 +379,37 @@ describe("RemoteEditableCollection", () => {
       expect(handleAction).toHaveBeenCalledWith(addAction);
       expect(refetch).toHaveBeenCalledTimes(1);
     });
+
+    it("forwards stored sheet context into events.add actions", async () => {
+      handleAction.mockResolvedValue("success");
+
+      const addAction = {
+        type: "showTextInput",
+        options: {
+          headerTitle: "Create Playlist",
+          buttonLabel: "Create",
+          actions: [{ type: "sendCloudEvent" }],
+        },
+      };
+
+      const content = {
+        items: [],
+        context: openingContext,
+        dynamicCollection: {
+          operations: ["add"],
+          postUrl: "https://x/cloud-events",
+          events: {
+            add: [addAction],
+          },
+        },
+      } as any;
+
+      const refetch = jest.fn().mockResolvedValue(undefined);
+      const col = new RemoteEditableCollection(content, refetch);
+
+      await col.add();
+
+      expect(handleAction).toHaveBeenCalledWith(addAction, openingContext);
+    });
   });
 });

package/modalState/__tests__/index.test.ts

@@ -1,4 +1,4 @@
-import { modalStore } from "../";
+import { modalStore, getMenuItemActions } from "../";
 
 describe("Modal State", () => {
   it("should have initial state", () => {
@@ -48,4 +48,33 @@ describe("Modal State", () => {
       });
     });
   });
+
+  describe("getMenuItemActions", () => {
+    it("returns actions array when actions is provided", () => {
+      const actions = [{ type: "action1" }, { type: "action2" }];
+      const item = { id: "1", title: "Item", actions };
+
+      expect(getMenuItemActions(item)).toEqual(actions);
+    });
+
+    it("returns [action] when single action is provided", () => {
+      const action = { type: "action1" };
+      const item = { id: "1", title: "Item", action };
+
+      expect(getMenuItemActions(item)).toEqual([action]);
+    });
+
+    it("returns action when action is passed as an array", () => {
+      const actions = [{ type: "action1" }];
+      const item = { id: "1", title: "Item", action: actions as any };
+
+      expect(getMenuItemActions(item)).toEqual(actions);
+    });
+
+    it("returns empty array when no action or actions are provided", () => {
+      expect(getMenuItemActions({ id: "1", title: "Item" })).toEqual([]);
+      expect(getMenuItemActions(null)).toEqual([]);
+      expect(getMenuItemActions(undefined)).toEqual([]);
+    });
+  });
 });

package/modalState/__tests__/useModalStoreState.test.ts

@@ -0,0 +1,142 @@
+import { act, renderHook } from "@testing-library/react-native";
+
+import { modalStore, useModalStoreState } from "../";
+
+const item = { id: "river-general", name: "Test Modal" };
+const props = { entry: { id: "modal-entry-1" } };
+
+const openModal = () =>
+  act(() => {
+    modalStore.getState().openModal({ item, props } as any);
+  });
+
+// Counts every render of the hook so the tests can assert on subscription
+// behaviour, not just on the returned value.
+const renderModalStoreState = (skipSubscription?: boolean) => {
+  const renders = { count: 0 };
+
+  const view = renderHook(() => {
+    renders.count += 1;
+
+    return skipSubscription === undefined
+      ? useModalStoreState()
+      : useModalStoreState(skipSubscription);
+  });
+
+  return { ...view, renders };
+};
+
+describe("useModalStoreState", () => {
+  afterEach(() => {
+    act(() => {
+      modalStore.getState().dismissModal();
+    });
+  });
+
+  describe("when subscribed (default)", () => {
+    it("returns the live modal state when called without arguments", () => {
+      const { result } = renderModalStoreState();
+
+      expect(result.current.visible).toBe(false);
+
+      openModal();
+
+      expect(result.current.visible).toBe(true);
+      expect(result.current.screen).toBe(item);
+      expect(result.current.props).toBe(props);
+    });
+
+    it("re-renders the consumer when the modal state changes", () => {
+      const { renders } = renderModalStoreState(false);
+
+      const rendersBeforeOpen = renders.count;
+
+      openModal();
+
+      expect(renders.count).toBeGreaterThan(rendersBeforeOpen);
+    });
+
+    // Counterpart to "returns a stable reference across store updates": an open
+    // modal is the one point where a live subscription and a skipped one hold
+    // different references, which is what makes that assertion meaningful.
+    it("returns a new reference while the modal is open", () => {
+      const { result } = renderModalStoreState(false);
+
+      const firstValue = result.current;
+
+      openModal();
+
+      expect(result.current).not.toBe(firstValue);
+    });
+  });
+
+  describe("when subscription is skipped", () => {
+    it("reports an empty modal state even while a modal is open", () => {
+      openModal();
+
+      expect(modalStore.getState().modalState.visible).toBe(true);
+
+      const { result } = renderModalStoreState(true);
+
+      expect(result.current).toMatchObject({
+        visible: false,
+        screen: null,
+        options: {},
+        props: {},
+      });
+    });
+
+    it("does not re-render the consumer when the modal state changes", () => {
+      const { renders } = renderModalStoreState(true);
+
+      const rendersBeforeOpen = renders.count;
+
+      openModal();
+
+      expect(renders.count).toBe(rendersBeforeOpen);
+    });
+
+    // The skipped branch has to hand back a module-level constant. Returning a
+    // fresh object would fail zustand's Object.is check and re-render on every
+    // store notification - the opposite of what skipping is for.
+    it("returns a stable reference across store updates", () => {
+      const { result } = renderModalStoreState(true);
+
+      const firstValue = result.current;
+
+      openModal();
+
+      // Asserted while the modal is open: dismissing resets the store to the
+      // very same initialModalState object, so an end-to-end round trip would
+      // hold this identity even for a live subscription.
+      expect(result.current).toBe(firstValue);
+
+      act(() => {
+        modalStore.getState().dismissModal();
+      });
+
+      expect(result.current).toBe(firstValue);
+    });
+  });
+
+  it("picks up the current modal state when it starts subscribing", () => {
+    let skipSubscription = true;
+
+    const { result, rerender } = renderHook(() =>
+      useModalStoreState(skipSubscription)
+    );
+
+    openModal();
+
+    expect(result.current.visible).toBe(false);
+
+    skipSubscription = false;
+
+    act(() => {
+      rerender(undefined);
+    });
+
+    expect(result.current.visible).toBe(true);
+    expect(result.current.screen).toBe(item);
+  });
+});

package/modalState/index.ts

@@ -25,6 +25,11 @@ export type {
   SelectionBehavior,
 } from "./types";
 
-export { isPresentSubMenuAction, OPERATIONS, hasOperation } from "./types";
+export {
+  isPresentSubMenuAction,
+  getMenuItemActions,
+  OPERATIONS,
+  hasOperation,
+} from "./types";
 
 export { useBottomSheetContent } from "./useBottomSheetContent";

package/modalState/store.ts

@@ -98,5 +98,12 @@ export const openBottomSheetModal = ({
   });
 };
 
-export const useModalStoreState = (): ModalState =>
-  useModalStore<ModalState>((state) => state.modalState);
+/**
+ * Pass `skipSubscription` from callers that render outside of a modal: the
+ * selector then returns the stable `initialModalState` reference, so the
+ * component is never re-rendered by modal state it does not read.
+ */
+export const useModalStoreState = (skipSubscription = false): ModalState =>
+  useModalStore<ModalState>((state) =>
+    skipSubscription ? initialModalState : state.modalState
+  );

package/modalState/types.ts

@@ -37,8 +37,8 @@ export interface MenuItem {
   summary?: string;
   icon?: string;
   isSelected?: boolean;
-  // When item represents an audio item, clicking on it will start playback
-  // and secondary action will allow to add it to queue or playlist
+  actions?: (Action | PresentSubMenuAction)[];
+  /** @deprecated Use `actions` array instead. Maintained for backwards compatibility. */
   action?: Action | PresentSubMenuAction;
   secondaryAction?: SecondaryAction;
   trailingButton?: any;
@@ -118,6 +118,9 @@ export interface Content {
   dynamicCollection?: DynamicCollectionOptions;
   themePluginId?: string;
   styleOverrides?: Record<string, any>;
+  /** Shown under Next Up when the queue sheet has no upcoming items. */
+  emptyMessage?: string;
+  context?: Record<string, any>;
 }
 
 export interface Menu {
@@ -131,3 +134,29 @@ export function isPresentSubMenuAction(
 ): action is PresentSubMenuAction {
   return !!action && typeof action === "object" && "menu" in action;
 }
+
+/**
+ * Normalizes an item's action/actions into an array of Action items.
+ * Supports canonical `actions: Action[]` and backwards-compatible `action: Action | Action[]`.
+ */
+export function getMenuItemActions(
+  item?: Partial<MenuItem> | null
+): (Action | PresentSubMenuAction)[] {
+  if (!item) {
+    return [];
+  }
+
+  if (Array.isArray(item.actions) && item.actions.length > 0) {
+    return item.actions;
+  }
+
+  if (Array.isArray((item as any).action)) {
+    return (item as any).action;
+  }
+
+  if (item.action) {
+    return [item.action];
+  }
+
+  return [];
+}

package/modalState/useBottomSheetContent.ts

@@ -1,14 +1,15 @@
-import React, { useEffect, useState } from "react";
+import React, { useCallback, useEffect, useState } from "react";
 import { toBooleanWithDefaultFalse } from "@applicaster/zapp-react-native-utils/booleanUtils";
 
-import {
-  isPresentSubMenuAction,
-  MenuItem,
-  modalOrchestrator,
-} from "./ModalOrchestrator";
+import { MenuItem, modalOrchestrator } from "./ModalOrchestrator";
 
 import { ContentViewModel } from "./ContentViewModel";
-import type { DynamicCollectionOptions, SelectionBehavior } from "./types";
+import {
+  DynamicCollectionOptions,
+  getMenuItemActions,
+  isPresentSubMenuAction,
+  SelectionBehavior,
+} from "./types";
 import type { EditableCollection } from "./EditableCollection";
 
 type Props = {
@@ -44,7 +45,9 @@ export const useBottomSheetContent = (props: Props): Return => {
   // Subscribe to the viewModel state changes
   useEffect(() => {
     return viewModel?.subscribe((nextState) => {
-      setState(nextState);
+      setState((state) => {
+        return state === nextState ? state : nextState;
+      });
     });
   }, [viewModel]);
 
@@ -64,15 +67,19 @@ export const useBottomSheetContent = (props: Props): Return => {
    * - If the item was a leaf action (not a submenu), triggers viewModel.refetch()
    *   so that checkmarks (isSelected) reflect the updated server state.
    */
-  const handleItemPress = async (item: MenuItem) => {
-    const isSubMenu = item.action && isPresentSubMenuAction(item.action);
+  const handleItemPress = useCallback(
+    async (item: MenuItem) => {
+      const actions = getMenuItemActions(item);
+      const isSubMenu = actions.some(isPresentSubMenuAction);
 
-    await onPress(item);
+      await onPress(item);
 
-    if (!isSubMenu) {
-      await viewModel?.refetch();
-    }
-  };
+      if (!isSubMenu) {
+        await viewModel?.refetch();
+      }
+    },
+    [onPress, viewModel]
+  );
 
   const goBackOrClose = React.useCallback(() => {
     if (modalOrchestrator.canGoBack) {
@@ -80,7 +87,7 @@ export const useBottomSheetContent = (props: Props): Return => {
     } else {
       modalOrchestrator.close();
     }
-  }, [modalOrchestrator.canGoBack]);
+  }, []);
 
   return {
     items: viewModel?.editableCollection ? editableItems : state?.items,
@@ -92,7 +99,7 @@ export const useBottomSheetContent = (props: Props): Return => {
     canGoBack: modalOrchestrator.canGoBack,
     handleItemPress,
     goBackOrClose,
-    close: () => modalOrchestrator.close(),
+    close: useCallback(() => modalOrchestrator.close(), []),
     role: state?.role,
     behavior: state?.behavior,
     dynamicCollection: state?.dynamicCollection,

package/navigationUtils/xrayNavigator.ts

@@ -0,0 +1,12 @@
+/**
+ * The app navigator for the X-Ray toolboxes (nav, screen), which run outside React. The
+ * NavigationProvider sets it after each commit; it is a plain module variable, so updating it
+ * never renders anything.
+ */
+let navigator: QuickBrickAppNavigator | undefined;
+
+export const setXrayNavigator = (value: QuickBrickAppNavigator | undefined) => {
+  navigator = value;
+};
+
+export const getXrayNavigator = () => navigator;

package/package.json

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