@applicaster/zapp-react-native-utils 16.0.0-alpha.1212303401 → 16.0.0-alpha.1218188693

package/entryActions/aliasPresentation.ts

@@ -0,0 +1,124 @@
+/**
+ * Presentation defaults 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.
+ *
+ * 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`.
+ */
+
+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",
+};
+
+/** 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,
+};
+
+/** Per-app overrides for the maps above. */
+export type AliasPresentation = {
+  labels?: Record<string, string>;
+  assets?: Record<string, string>;
+};
+
+function formatAliasLabel(
+  alias: string,
+  overrides?: AliasPresentation
+): string {
+  const label = overrides?.labels?.[alias] ?? ALIAS_LABELS[alias];
+
+  if (label) {
+    return label;
+  }
+
+  const formatted = alias.replace(/_/g, " ");
+
+  return formatted.charAt(0).toUpperCase() + formatted.slice(1);
+}
+
+const nonEmptyString = (value: unknown): value is string =>
+  typeof value === "string" && value.length > 0;
+
+/**
+ * Label the backend stated outright, if any. Distinct from
+ * {@link resolveButtonLabel} because an explicit label outranks the executor's
+ * action state, while the alias fallback does not.
+ */
+export function resolveExplicitLabel(
+  button: EntryAction["button"]
+): string | undefined {
+  if (nonEmptyString(button?.title)) {
+    return button.title;
+  }
+
+  if (nonEmptyString(button?.label)) {
+    return button.label;
+  }
+
+  return undefined;
+}
+
+/** Label to show for an entry action: explicit title/label, else the alias. */
+export function resolveButtonLabel(
+  button: EntryAction["button"],
+  overrides?: AliasPresentation
+): string {
+  const explicit = resolveExplicitLabel(button);
+
+  if (explicit) {
+    return explicit;
+  }
+
+  if (nonEmptyString(button?.alias)) {
+    return formatAliasLabel(button.alias, overrides);
+  }
+
+  return "";
+}
+
+/** Icon to show for an entry action: explicit iconURL, else the alias default. */
+export function resolveButtonAsset(
+  button: EntryAction["button"],
+  overrides?: AliasPresentation
+): string | undefined {
+  if (button?.iconURL) {
+    return button.iconURL;
+  }
+
+  if (!button?.alias) {
+    return undefined;
+  }
+
+  return overrides?.assets?.[button.alias] ?? ALIAS_ASSETS[button.alias];
+}

package/entryActions/buildEntryActions.ts

@@ -0,0 +1,167 @@
+/// <reference types="@applicaster/applicaster-types" />
+import { createLogger } from "../logger";
+import { ActionExecutionContext } from "../actionsExecutor/types";
+import { RegisteredAction } from "../uiActionsRegistrator";
+
+import {
+  resolveButtonAsset,
+  resolveButtonLabel,
+  resolveExplicitLabel,
+} from "./aliasPresentation";
+import { EntryAction, EntryActionDeps } from "./types";
+
+const { log_info, log_warning, log_error } = createLogger({
+  subsystem: "EntryActions",
+  category: "EntryAction",
+});
+
+const ENTRY_ACTION_IDENTIFIER_PREFIX = "entry_action";
+
+/** True for actions inflated from `entry.extensions.entry_action`. */
+export function isEntryAction(item: RegisteredAction): boolean {
+  return item?.source === "entry";
+}
+
+function isValidEntryAction(value: unknown): value is EntryAction {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const { button, actions } = value as EntryAction;
+
+  return (
+    (typeof button?.title === "string" ||
+      typeof button?.label === "string" ||
+      typeof button?.alias === "string") &&
+    Array.isArray(actions)
+  );
+}
+
+function createEntryAction(
+  entryAction: EntryAction,
+  index: number,
+  entry: ZappEntry | ZappFeed,
+  deps: EntryActionDeps
+): RegisteredAction {
+  const { button, actions, dismiss_on_action } = entryAction;
+
+  const identifier = `${ENTRY_ACTION_IDENTIFIER_PREFIX}_${index}`;
+  const primaryAction = actions.length > 0 ? actions[0] : null;
+
+  const actionState = primaryAction
+    ? deps.actionExecutor?.getActionState?.(primaryAction.type, entry)
+    : null;
+
+  // An explicit title/label outranks the executor's action state; the
+  // alias-derived defaults only fill in when neither produced anything.
+  const label: CellActionEntryState["label"] =
+    resolveExplicitLabel(button) ||
+    actionState?.label ||
+    resolveButtonLabel(button, deps.aliasPresentation);
+
+  const asset: CellActionEntryState["asset"] =
+    button?.iconURL ||
+    actionState?.asset ||
+    resolveButtonAsset(button, deps.aliasPresentation);
+
+  const initialState = { state: 0, label, asset };
+
+  return {
+    identifier,
+    source: "entry",
+    action: {
+      initialEntryState: () => initialState,
+      invokeAction: async (
+        invokedEntry: ZappEntry,
+        options: InvokeArgsOptions = {}
+      ) => {
+        if (dismiss_on_action === true) {
+          options.dismiss?.();
+        }
+
+        log_info(
+          `invokeAction: entry action "${identifier}" triggered for entry "${invokedEntry?.id}"`,
+          { identifier, entryId: invokedEntry?.id, actionCount: actions.length }
+        );
+
+        // Both of these leave the user with a button that does nothing when
+        // tapped, and neither throws, so they would otherwise be invisible.
+        if (actions.length === 0) {
+          log_warning(
+            `invokeAction: entry action "${identifier}" on entry "${invokedEntry?.id}" declares no actions - the tap does nothing`,
+            { identifier, entryId: invokedEntry?.id }
+          );
+        }
+
+        if (typeof deps.actionExecutor?.handleActions !== "function") {
+          log_warning(
+            `invokeAction: no action executor available for entry action "${identifier}" - the tap does nothing`,
+            { identifier, entryId: invokedEntry?.id }
+          );
+        }
+
+        try {
+          await deps.actionExecutor?.handleActions(actions, {
+            entry: invokedEntry,
+            entryContext: invokedEntry,
+            ...deps.actionContext,
+            ...(options.component ? { component: options.component } : {}),
+          } as ActionExecutionContext);
+        } catch (error) {
+          log_error(
+            `invokeAction: entry action "${identifier}" failed for entry "${invokedEntry?.id}"`,
+            {
+              identifier,
+              entryId: invokedEntry?.id,
+              // Types only - the action payloads are backend supplied and may
+              // carry user data.
+              actionTypes: actions.map((action) => action?.type),
+              error,
+            }
+          );
+        }
+      },
+    },
+  };
+}
+
+/**
+ * Builds the list of actions declared on an entry via
+ * `entry.extensions.entry_action`.
+ */
+export function buildEntryActions(
+  entry: ZappEntry | ZappFeed,
+  deps: EntryActionDeps
+): RegisteredAction[] {
+  const entryId = (entry as ZappEntry)?.id;
+  const raw = (entry as any)?.extensions?.entry_action;
+
+  // Most entries simply declare no actions. This provider is resolved for
+  // every entry on every render, so saying so would drown everything else.
+  if (raw === undefined || raw === null) {
+    return [];
+  }
+
+  if (!Array.isArray(raw)) {
+    log_warning(
+      `buildEntryActions: entry "${entryId}" has extensions.entry_action of type ${typeof raw} instead of an array - no entry actions will be shown`,
+      { entryId, receivedType: typeof raw }
+    );
+
+    return [];
+  }
+
+  const valid = raw.filter(isValidEntryAction);
+  const invalid = raw.length - valid.length;
+
+  if (invalid > 0) {
+    log_warning(
+      `buildEntryActions: ${invalid} invalid entry action(s) skipped for entry "${entryId}"`,
+      { entryId, total: raw.length, invalid }
+    );
+  }
+
+  return valid.map((entryAction, index) =>
+    createEntryAction(entryAction, index, entry, deps)
+  );
+}

package/entryActions/index.ts

@@ -0,0 +1,17 @@
+export { buildEntryActions, isEntryAction } from "./buildEntryActions";
+
+export {
+  ALIAS_ASSETS,
+  ALIAS_LABELS,
+  resolveButtonAsset,
+  resolveButtonLabel,
+  resolveExplicitLabel,
+} from "./aliasPresentation";
+
+export type {
+  EntryAction,
+  EntryActionDeps,
+  EntryActionExecutionContext,
+} from "./types";
+
+export type { AliasPresentation } from "./aliasPresentation";

package/entryActions/types.ts

@@ -0,0 +1,39 @@
+/// <reference types="@applicaster/applicaster-types" />
+import type { ActionExecutorContextType } from "../actionsExecutor/ActionExecutorContext";
+import type { AliasPresentation } from "./aliasPresentation";
+
+/**
+ * A single action declared by the backend on an entry, under
+ * `entry.extensions.entry_action`.
+ */
+export type EntryAction = {
+  button: {
+    title?: string;
+    label?: string;
+    alias?: string;
+    iconURL?: string;
+  };
+  actions: ZappActionType[];
+  dismiss_on_action?: boolean;
+};
+
+/**
+ * Everything `buildEntryActions` needs from the surrounding React tree in order
+ * to execute an entry action. Supplied lazily so the registered provider always
+ * reads the freshest screen context.
+ */
+export type EntryActionDeps = {
+  actionExecutor: ActionExecutorContextType;
+  actionContext: EntryActionExecutionContext;
+  /** App-supplied labels/icons for backend aliases; defaults are used without it. */
+  aliasPresentation?: AliasPresentation;
+};
+
+/** The screen the action is executed against, spread into the execution context. */
+export type EntryActionExecutionContext = {
+  screenData?: unknown;
+  screenState?: unknown;
+  screenRoute?: string;
+  screenStateStore?: unknown;
+  screenEntry?: unknown;
+};

package/manifestUtils/_internals/index.js

@@ -135,7 +135,8 @@ function generateFieldsFromDefaults(label, defaults, fields) {
 function generateFieldsFromDefaultsWithoutPrefixedLabel(
   label,
   defaults,
-  fields
+  fields,
+  { withStyle = false } = {}
 ) {
   const keyPrefix = toSnakeCase(label);
 
@@ -151,7 +152,9 @@ function generateFieldsFromDefaultsWithoutPrefixedLabel(
         const generatedField = {
           ...fieldProps,
           label: capitalizeFirstLetter(field.suffix),
-          key: `${keyPrefix}_${toSnakeCase(field.suffix)}`,
+          key: withStyle
+            ? `${keyPrefix}_style_${toSnakeCase(field.suffix)}`
+            : `${keyPrefix}_${toSnakeCase(field.suffix)}`,
           initial_value: R.when(R.is(Array), R.head)(initialValue),
         };
 
@@ -164,7 +167,9 @@ function generateFieldsFromDefaultsWithoutPrefixedLabel(
             const section = condition.section ? `${condition.section}/` : "";
 
             return {
-              key: `${section}${keyPrefix}_${toSnakeCase(condition.key)}`,
+              key: withStyle
+                ? `${section}${keyPrefix}_style_${toSnakeCase(condition.key)}`
+                : `${section}${keyPrefix}_${toSnakeCase(condition.key)}`,
               condition_value: condition.value,
             };
           });

package/manifestUtils/defaultManifestConfigurations/player.js

@@ -204,6 +204,20 @@ function getPlayerConfiguration({ platform, version }) {
         label_tooltip: "Label for close button accessibility",
         type: "text_input",
       },
+      {
+        key: "accessibility_overflow_label",
+        label: "Accessibility overflow label",
+        initial_value: "More actions",
+        label_tooltip: "Label for the overflow (…) button accessibility",
+        type: "text_input",
+      },
+      {
+        key: "accessibility_overflow_hint",
+        label: "Accessibility overflow hint",
+        initial_value: "Opens the remaining player actions",
+        label_tooltip: "Hint for the overflow (…) button accessibility",
+        type: "text_input",
+      },
       {
         key: "accessibility_close_hint",
         label: "Accessibility close hint",
@@ -791,7 +805,7 @@ function getPlayerConfiguration({ platform, version }) {
         label: "Player action buttons",
         initial_value: null,
         label_tooltip:
-          "type here the identifiers of the action buttons you want to show on the player, separated by commas. Only 2 action buttons may be added at the same time",
+          "Comma-separated action identifiers. The entry_actions token expands from the playing entry's extensions.entry_action. When more than 2 actions resolve, the video and fullscreen audio players show Overflow (…) plus one companion - the first action that did not come from the entry, otherwise the first one - and the Overflow sheet lists every resolved action. A repeated identifier is counted once. No extra plugin is required.",
         type: "text_input",
       },
       {
@@ -1091,6 +1105,13 @@ function getPlayerConfiguration({ platform, version }) {
             type: "uploader",
             label_tooltip: "Override default close badge / icon",
           },
+          {
+            key: "overflow",
+            label: "Overflow badge",
+            type: "uploader",
+            label_tooltip:
+              "Override default overflow (…) badge / icon, shown when more action buttons resolve than fit on the player overlay",
+          },
           {
             key: "lock",
             label: "Lock player badge",

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.
@@ -136,15 +142,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__/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/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";