@applicaster/zapp-react-native-utils 16.0.0-rc.70 → 16.0.0-rc.72

package/entryActions/__tests__/buildEntryActions.test.ts

@@ -0,0 +1,156 @@
+import { buildEntryActions } from "../buildEntryActions";
+
+describe("buildEntryActions - alias & label resolution", () => {
+  const mockDeps = {
+    actionExecutor: { handleActions: jest.fn() } as any,
+    actionContext: {},
+  };
+
+  const resolveEntryActions = (entry: ZappEntry) =>
+    buildEntryActions(entry, mockDeps);
+
+  it("resolves entry action with explicit button title", () => {
+    const entry = {
+      id: "entry-1",
+      extensions: {
+        entry_action: [
+          {
+            button: {
+              title: "Custom Action Title",
+              iconURL: "http://example.com/icon.png",
+            },
+            actions: [{ type: "test" }],
+            dismiss_on_action: true,
+          },
+        ],
+      },
+    };
+
+    const actions = resolveEntryActions(entry as any);
+
+    expect(actions).toHaveLength(1);
+    expect(actions[0].identifier).toBe("entry_action_0");
+
+    const state = actions[0].action.initialEntryState(entry as any);
+
+    expect(state).toEqual({
+      state: 0,
+      label: "Custom Action Title",
+      asset: "http://example.com/icon.png",
+    });
+  });
+
+  it("resolves entry action with button label property", () => {
+    const entry = {
+      id: "entry-2",
+      extensions: {
+        entry_action: [
+          {
+            button: { label: "Label Property Action" },
+            actions: [{ type: "test" }],
+          },
+        ],
+      },
+    };
+
+    const actions = resolveEntryActions(entry as any);
+
+    expect(actions).toHaveLength(1);
+    const state = actions[0].action.initialEntryState(entry as any);
+    expect(state.label).toBe("Label Property Action");
+  });
+
+  it("resolves entry action with known backend button alias (e.g. add_all_to_queue)", () => {
+    const entry = {
+      id: "entry-3",
+      extensions: {
+        entry_action: [
+          {
+            button: { alias: "add_all_to_queue" },
+            actions: [{ type: "test" }],
+            dismiss_on_action: true,
+          },
+          {
+            button: { alias: "add_to_playlist" },
+            actions: [{ type: "test" }],
+          },
+          {
+            button: { alias: "delete_collection" },
+            actions: [{ type: "test" }],
+          },
+        ],
+      },
+    };
+
+    const actions = resolveEntryActions(entry as any);
+
+    expect(actions).toHaveLength(3);
+
+    expect(actions[0].action.initialEntryState(entry as any)).toMatchObject({
+      state: 0,
+      label: "Add all to Queue",
+    });
+
+    expect(actions[1].action.initialEntryState(entry as any)).toMatchObject({
+      state: 0,
+      label: "Add to Playlist",
+    });
+
+    expect(actions[2].action.initialEntryState(entry as any)).toMatchObject({
+      state: 0,
+      label: "Delete collection",
+    });
+  });
+
+  it("formats unknown alias nicely as fallback", () => {
+    const entry = {
+      id: "entry-4",
+      extensions: {
+        entry_action: [
+          {
+            button: { alias: "custom_unknown_action" },
+            actions: [{ type: "test" }],
+          },
+        ],
+      },
+    };
+
+    const actions = resolveEntryActions(entry as any);
+
+    expect(actions).toHaveLength(1);
+    const state = actions[0].action.initialEntryState(entry as any);
+    expect(state.label).toBe("Custom unknown action");
+  });
+
+  it("uses actionExecutor.getActionState for plugin-provided label and asset", () => {
+    mockDeps.actionExecutor.getActionState = jest.fn(() => ({
+      label: "From Plugin",
+      asset: "plugin_asset",
+    }));
+
+    const entry = {
+      id: "entry-plugin-state",
+      extensions: {
+        entry_action: [
+          {
+            button: { alias: "custom_plugin_action" },
+            actions: [{ type: "plugin-action" }],
+          },
+        ],
+      },
+    };
+
+    const actions = resolveEntryActions(entry as any);
+    const state = actions[0].action.initialEntryState(entry as any);
+
+    expect(mockDeps.actionExecutor.getActionState).toHaveBeenCalledWith(
+      "plugin-action",
+      entry
+    );
+
+    expect(state).toMatchObject({
+      label: "From Plugin",
+      asset: "plugin_asset",
+    });
+  });
+});

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,166 @@
+/// <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,
+          } 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/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/package.json

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

package/playerUtils/__tests__/resolvePlayerActions.test.ts

@@ -0,0 +1,138 @@
+import { resolvePlayerActions } from "../resolvePlayerActions";
+import { selectActionButtons } from "../../conf/player/selectors";
+import { uiActionsRegistry } from "../../uiActionsRegistrator";
+
+jest.mock("../../conf/player/selectors", () => ({
+  selectActionButtons: jest.fn(),
+}));
+
+const action = (identifier: string) =>
+  ({ identifier, action: { invokeAction: jest.fn() } }) as any;
+
+describe("resolvePlayerActions", () => {
+  const entry = {
+    id: "e1",
+    extensions: {
+      entry_action: [
+        { button: { alias: "add_to_playlist" }, actions: [{ type: "test" }] },
+        { button: { alias: "add_to_queue" }, actions: [{ type: "test" }] },
+      ],
+    },
+  };
+
+  // The entry's own actions never reach the registry; the caller expands them.
+  const expandEntryActions = jest.fn(() => [
+    action("entry_action_0"),
+    action("entry_action_1"),
+  ]);
+
+  beforeEach(() => {
+    expandEntryActions.mockClear();
+
+    jest
+      .spyOn(uiActionsRegistry, "getActions")
+      .mockImplementation((name) => [action(name)]);
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it("expands entry_actions through the caller and keeps config order", () => {
+    (selectActionButtons as jest.Mock).mockReturnValue(
+      "entry_actions,local_storage_favourites_action,offline-content-button"
+    );
+
+    const result = resolvePlayerActions({
+      configuration: {},
+      entry,
+      expandEntryActions,
+    });
+
+    expect(expandEntryActions).toHaveBeenCalledWith(entry);
+
+    expect(uiActionsRegistry.getActions).not.toHaveBeenCalledWith(
+      "entry_actions",
+      entry
+    );
+
+    expect(result.map((item) => item.identifier)).toEqual([
+      "entry_action_0",
+      "entry_action_1",
+      "local_storage_favourites_action",
+      "offline-content-button",
+    ]);
+  });
+
+  it.each([undefined, null, ""])(
+    "resolves nothing when the config is %p",
+    (configured) => {
+      (selectActionButtons as jest.Mock).mockReturnValue(configured);
+
+      expect(
+        resolvePlayerActions({ configuration: {}, entry, expandEntryActions })
+      ).toEqual([]);
+    }
+  );
+
+  it("does not cap the resolved list at two items", () => {
+    (selectActionButtons as jest.Mock).mockReturnValue("a,b,c");
+
+    expect(
+      resolvePlayerActions({
+        configuration: {},
+        entry,
+        expandEntryActions,
+      }).map((item) => item.identifier)
+    ).toEqual(["a", "b", "c"]);
+  });
+
+  it("has no special case for any plugin identifier", () => {
+    (selectActionButtons as jest.Mock).mockReturnValue(
+      "open-modal-bottom-sheet-cell-action,local_storage_favourites_action"
+    );
+
+    expect(
+      resolvePlayerActions({
+        configuration: {},
+        entry,
+        expandEntryActions,
+      }).map((item) => item.identifier)
+    ).toEqual([
+      "open-modal-bottom-sheet-cell-action",
+      "local_storage_favourites_action",
+    ]);
+  });
+
+  it("collapses a repeated identifier in the config string", () => {
+    (selectActionButtons as jest.Mock).mockReturnValue(
+      "favorites,favorites,share"
+    );
+
+    expect(
+      resolvePlayerActions({
+        configuration: {},
+        entry,
+        expandEntryActions,
+      }).map((item) => item.identifier)
+    ).toEqual(["favorites", "share"]);
+  });
+
+  it("drops resolved items that cannot be invoked", () => {
+    (selectActionButtons as jest.Mock).mockReturnValue("broken,share");
+
+    (uiActionsRegistry.getActions as jest.Mock).mockImplementation((name) =>
+      name === "broken"
+        ? [{ identifier: "broken" } as any]
+        : [action(name as string)]
+    );
+
+    expect(
+      resolvePlayerActions({
+        configuration: {},
+        entry,
+        expandEntryActions,
+      }).map((item) => item.identifier)
+    ).toEqual(["share"]);
+  });
+});