@applicaster/zapp-react-native-utils 16.0.0-rc.9 → 16.0.0-rc.91

package/entryActions/__tests__/buildEntryActions.test.ts

@@ -0,0 +1,235 @@
+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("humanizes an un-overridden alias and falls back to the placeholder asset", () => {
+    const entry = {
+      id: "entry-3",
+      extensions: {
+        entry_action: [
+          {
+            button: { alias: "add_all_to_queue" },
+            actions: [{ type: "test" }],
+            dismiss_on_action: true,
+          },
+          {
+            button: { alias: "custom_unknown_action" },
+            actions: [{ type: "test" }],
+          },
+        ],
+      },
+    };
+
+    const actions = resolveEntryActions(entry as any);
+
+    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",
+    });
+
+    expect(actions[1].action.initialEntryState(entry as any)).toMatchObject({
+      state: 0,
+      label: "Custom unknown action",
+    });
+
+    // 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("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: "add_all_to_queue" },
+            actions: [{ type: "test" }],
+          },
+          {
+            button: { alias: "not_overridden" },
+            actions: [{ type: "test" }],
+          },
+        ],
+      },
+    };
+
+    const actions = buildEntryActions(entry as any, deps);
+
+    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("Plain Label");
+    expect(state.asset).toBeUndefined();
+  });
+
+  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",
+    });
+  });
+});
+
+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

@@ -0,0 +1,108 @@
+/**
+ * Presentation fallbacks for backend action aliases.
+ *
+ * Entries may declare an action by `alias` alone, without a label or an icon.
+ * 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.
+ *
+ * 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";
+
+import { createLogger } from "@applicaster/zapp-react-native-utils/logger";
+
+const logger = createLogger({
+  category: "zapp-react-native-utils:aliasPresentation",
+});
+
+const PLACEHOLDER_RED_BOX =
+  "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAJ0lEQVR4nO3NMQEAAAjDsIF/z2ACvlRAU5NMHuvPOQAAAAAAAMBdC/07Ai5sNw+CAAAAAElFTkSuQmCC";
+
+/** Per-app labels and icons, keyed by alias, that outrank the fallbacks. */
+export type AliasPresentation = {
+  labels?: Record<string, string>;
+  assets?: Record<string, string>;
+};
+
+function formatAliasLabel(
+  alias: string,
+  overrides?: AliasPresentation
+): string {
+  const label = overrides?.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, matching alias asset or fallback to red box. */
+export function resolveButtonAsset(
+  button: EntryAction["button"],
+  overrides?: AliasPresentation
+): string | undefined {
+  if (button?.iconURL) {
+    return button.iconURL;
+  }
+
+  if (!button?.alias) {
+    return undefined;
+  }
+
+  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

@@ -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,15 @@
+export { buildEntryActions, isEntryAction } from "./buildEntryActions";
+
+export {
+  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;
+};