@applicaster/zapp-react-native-utils 16.0.0-alpha.1593888345 → 16.0.0-alpha.1701179921

package/entryActions/__tests__/buildEntryActions.test.ts

@@ -60,7 +60,7 @@ describe("buildEntryActions - alias & label resolution", () => {
     expect(state.label).toBe("Label Property Action");
   });
 
-  it("resolves entry action with known backend button alias (e.g. add_all_to_queue)", () => {
+  it("humanizes an un-overridden alias and falls back to the placeholder asset", () => {
     const entry = {
       id: "entry-3",
       extensions: {
@@ -71,11 +71,7 @@ describe("buildEntryActions - alias & label resolution", () => {
             dismiss_on_action: true,
           },
           {
-            button: { alias: "add_to_playlist" },
-            actions: [{ type: "test" }],
-          },
-          {
-            button: { alias: "delete_collection" },
+            button: { alias: "custom_unknown_action" },
             actions: [{ type: "test" }],
           },
         ],
@@ -84,42 +80,86 @@ describe("buildEntryActions - alias & label resolution", () => {
 
     const actions = resolveEntryActions(entry as any);
 
-    expect(actions).toHaveLength(3);
+    expect(actions).toHaveLength(2);
 
+    // No built-in alias vocabulary any more: underscores become spaces and
+    // only the first letter is capitalized, so "queue" stays lowercase.
     expect(actions[0].action.initialEntryState(entry as any)).toMatchObject({
       state: 0,
-      label: "Add all to Queue",
+      label: "Add all to queue",
     });
 
     expect(actions[1].action.initialEntryState(entry as any)).toMatchObject({
       state: 0,
-      label: "Add to Playlist",
+      label: "Custom unknown action",
     });
 
-    expect(actions[2].action.initialEntryState(entry as any)).toMatchObject({
-      state: 0,
-      label: "Delete collection",
-    });
+    // The asset has no such fallback: without an override it is the red-box
+    // placeholder, so a missing Studio icon is visible rather than absent.
+    for (const action of actions) {
+      expect(action.action.initialEntryState(entry as any)).toMatchObject({
+        asset: expect.stringMatching(/^data:image\/png;base64,/),
+      });
+    }
   });
 
-  it("formats unknown alias nicely as fallback", () => {
+  it("prefers aliasPresentation overrides over the humanized fallbacks", () => {
+    const deps = {
+      actionExecutor: { handleActions: jest.fn() } as any,
+      actionContext: {},
+      aliasPresentation: {
+        labels: { add_all_to_queue: "Add all to Queue" },
+        assets: { add_all_to_queue: "http://example.com/queue.png" },
+      },
+    };
+
     const entry = {
       id: "entry-4",
       extensions: {
         entry_action: [
           {
-            button: { alias: "custom_unknown_action" },
+            button: { alias: "add_all_to_queue" },
+            actions: [{ type: "test" }],
+          },
+          {
+            button: { alias: "not_overridden" },
             actions: [{ type: "test" }],
           },
         ],
       },
     };
 
-    const actions = resolveEntryActions(entry as any);
+    const actions = buildEntryActions(entry as any, deps);
 
-    expect(actions).toHaveLength(1);
+    expect(actions[0].action.initialEntryState(entry as any)).toMatchObject({
+      label: "Add all to Queue",
+      asset: "http://example.com/queue.png",
+    });
+
+    // Overrides are per-alias, so an alias absent from the map still humanizes.
+    expect(actions[1].action.initialEntryState(entry as any)).toMatchObject({
+      label: "Not overridden",
+    });
+  });
+
+  it("returns no asset when the button has neither iconURL nor alias", () => {
+    const entry = {
+      id: "entry-5",
+      extensions: {
+        entry_action: [
+          {
+            button: { label: "Plain Label" },
+            actions: [{ type: "test" }],
+          },
+        ],
+      },
+    };
+
+    const actions = resolveEntryActions(entry as any);
     const state = actions[0].action.initialEntryState(entry as any);
-    expect(state.label).toBe("Custom unknown action");
+
+    expect(state.label).toBe("Plain Label");
+    expect(state.asset).toBeUndefined();
   });
 
   it("uses actionExecutor.getActionState for plugin-provided label and asset", () => {
@@ -154,3 +194,42 @@ describe("buildEntryActions - alias & label resolution", () => {
     });
   });
 });
+
+describe("buildEntryActions - invokeAction execution context", () => {
+  it("forwards the List component from invoke options into handleActions", async () => {
+    const handleActions = jest.fn();
+
+    const component = {
+      id: "list-1",
+      data: { source: "https://example.com/user/collections/abc" },
+    };
+
+    const deps = {
+      actionExecutor: { handleActions } as any,
+      actionContext: { screenData: { id: "playlist-screen" } },
+    };
+
+    const entry = {
+      id: "entry-1",
+      extensions: {
+        entry_action: [
+          {
+            button: { title: "Edit Name" },
+            actions: [{ type: "refreshComponent" }],
+          },
+        ],
+      },
+    };
+
+    const [action] = buildEntryActions(entry as any, deps);
+
+    await action.action.invokeAction(entry as any, { component });
+
+    expect(handleActions).toHaveBeenCalledWith([{ type: "refreshComponent" }], {
+      entry,
+      entryContext: entry,
+      screenData: { id: "playlist-screen" },
+      component,
+    });
+  });
+});

package/entryActions/aliasPresentation.ts

@@ -1,52 +1,29 @@
 /**
- * Presentation defaults for backend action aliases.
+ * Presentation fallbacks for backend action aliases.
  *
  * Entries may declare an action by `alias` alone, without a label or an icon.
- * These maps are the last-resort labels/icons for the aliases we know about; an
- * unknown alias falls back to a humanized version of the alias itself.
+ * There is no built-in alias vocabulary: a label falls back to a humanized
+ * version of the alias itself, and an icon falls back to an inline placeholder
+ * that is deliberately conspicuous, so a missing asset reads as unconfigured
+ * rather than as a deliberate blank.
  *
- * They are defaults, not a framework guarantee: an app that speaks a different
- * alias vocabulary, needs other languages, or does not want to depend on these
- * icon hosts passes its own through `EntryActionDeps.aliasPresentation`.
+ * Both are last resorts, not a framework guarantee: an app that speaks its own
+ * alias vocabulary or needs other languages passes labels and assets through
+ * `EntryActionDeps.aliasPresentation`, which is consulted per alias.
  */
 
 import { EntryAction } from "./types";
 
-const ADD_TO_PLAYLIST_ICON =
-  "https://assets-secure.applicaster.com/zapp/assets/app_family/1710/906728572617/playlist_add_24dp_FFFFFF_FILL0_wght400_GRAD0_opsz24.png";
-
-const REMOVE_ICON =
-  "https://assets-secure.applicaster.com/zapp/assets/app_family/1710/372097240191/remove_24dp_EA3323_FILL0_wght400_GRAD0_opsz24.png";
-
-const EDIT_ICON =
-  "https://upload.wikimedia.org/wikipedia/commons/b/b6/Edit-icon.png";
-
-/** Known backend action alias labels. */
-export const ALIAS_LABELS: Record<string, string> = {
-  add_to_playlist: "Add to Playlist",
-  add_to_queue: "Add to Queue",
-  add_all_to_queue: "Add all to Queue",
-  play_all: "Play All",
-  remove_item: "Remove item",
-  delete_collection: "Delete collection",
-  create_collection: "Create collection",
-  edit: "Edit",
-  edit_name: "Edit Name & Details",
-};
+import { createLogger } from "@applicaster/zapp-react-native-utils/logger";
 
-/** Known backend action alias image assets. */
-export const ALIAS_ASSETS: Record<string, string> = {
-  add_to_playlist: ADD_TO_PLAYLIST_ICON,
-  add_to_queue: ADD_TO_PLAYLIST_ICON,
-  add_all_to_queue: ADD_TO_PLAYLIST_ICON,
-  play_all: ADD_TO_PLAYLIST_ICON,
-  remove_item: REMOVE_ICON,
-  delete_collection: REMOVE_ICON,
-  edit: EDIT_ICON,
-  edit_name: EDIT_ICON,
-};
+const logger = createLogger({
+  category: "zapp-react-native-utils:aliasPresentation",
+});
+
+const PLACEHOLDER_RED_BOX =
+  "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAJ0lEQVR4nO3NMQEAAAjDsIF/z2ACvlRAU5NMHuvPOQAAAAAAAMBdC/07Ai5sNw+CAAAAAElFTkSuQmCC";
 
-/** Per-app overrides for the maps above. */
+/** Per-app labels and icons, keyed by alias, that outrank the fallbacks. */
 export type AliasPresentation = {
   labels?: Record<string, string>;
   assets?: Record<string, string>;
@@ -56,7 +33,7 @@ function formatAliasLabel(
   alias: string,
   overrides?: AliasPresentation
 ): string {
-  const label = overrides?.labels?.[alias] ?? ALIAS_LABELS[alias];
+  const label = overrides?.labels?.[alias];
 
   if (label) {
     return label;
@@ -107,7 +84,7 @@ export function resolveButtonLabel(
   return "";
 }
 
-/** Icon to show for an entry action: explicit iconURL, else the alias default. */
+/** Icon to show for an entry action: explicit iconURL, matching alias asset or fallback to red box. */
 export function resolveButtonAsset(
   button: EntryAction["button"],
   overrides?: AliasPresentation
@@ -120,5 +97,12 @@ export function resolveButtonAsset(
     return undefined;
   }
 
-  return overrides?.assets?.[button.alias] ?? ALIAS_ASSETS[button.alias];
+  if (!overrides?.assets?.[button.alias]) {
+    logger.log_warning(
+      `Entry action alias '${button.alias}' was not resolved by any plugin feedDecorator or app override. Falling back to placeholder red box.`,
+      { data: { button } }
+    );
+  }
+
+  return overrides?.assets?.[button.alias] ?? PLACEHOLDER_RED_BOX;
 }

package/entryActions/buildEntryActions.ts

@@ -105,6 +105,7 @@ function createEntryAction(
             entry: invokedEntry,
             entryContext: invokedEntry,
             ...deps.actionContext,
+            ...(options.component ? { component: options.component } : {}),
           } as ActionExecutionContext);
         } catch (error) {
           log_error(

package/entryActions/index.ts

@@ -1,8 +1,6 @@
 export { buildEntryActions, isEntryAction } from "./buildEntryActions";
 
 export {
-  ALIAS_ASSETS,
-  ALIAS_LABELS,
   resolveButtonAsset,
   resolveButtonLabel,
   resolveExplicitLabel,

package/modalState/ModalOrchestrator.ts

@@ -44,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,
     },

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__/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/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

@@ -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 {