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

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/_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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applicaster/zapp-react-native-utils",
-  "version": "16.0.0-alpha.1212303401",
+  "version": "16.0.0-alpha.1263110541",
   "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.1212303401",
+    "@applicaster/applicaster-types": "16.0.0-alpha.1263110541",
     "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"]);
+  });
+});

package/playerUtils/index.ts

@@ -7,7 +7,23 @@ import { isTV } from "@applicaster/zapp-react-native-utils/reactUtils";
 import { getBoolFromConfigValue } from "../configurationUtils";
 import { Dimensions } from "react-native";
 
-export { getPlayerActionButtons } from "./getPlayerActionButtons";
+export { resolvePlayerActions } from "./resolvePlayerActions";
+
+export { isEntryAction } from "../entryActions";
+
+export {
+  parseActionIdentifiers,
+  resolveActionIdentifiers,
+} from "../uiActionsRegistrator";
+
+export type { ResolveActionIdentifiersParams } from "../uiActionsRegistrator";
+
+export type {
+  ActionButtonDescriptor,
+  OverflowDescriptor,
+  PlayerControlDescriptor,
+  ResolvePlayerActionsParams,
+} from "./resolvePlayerActions";
 
 export {
   resolvePlayerContentText,

package/playerUtils/resolvePlayerActions.ts

@@ -0,0 +1,71 @@
+import { selectActionButtons } from "../conf/player/selectors";
+import {
+  usableActionItems,
+  RegisteredAction,
+  resolveActionIdentifiers,
+} from "../uiActionsRegistrator";
+
+export type ResolvePlayerActionsParams = {
+  configuration: any;
+  entry: ZappEntry | ZappFeed;
+  /** Expands the `entry_actions` token; see `resolveActionIdentifiers`. */
+  expandEntryActions?: (entry: ZappEntry | ZappFeed) => RegisteredAction[];
+};
+
+/**
+ * The player's action buttons, resolved against the entry.
+ *
+ * Every `player_action_buttons` token goes through `uiActionsRegistry`, except
+ * `entry_actions`, which the caller expands from the entry itself. The list is
+ * not capped; the overlay decides how many fit and sends the rest to the sheet.
+ */
+export function resolvePlayerActions({
+  configuration,
+  entry,
+  expandEntryActions,
+}: ResolvePlayerActionsParams): RegisteredAction[] {
+  const buttonsString = selectActionButtons(configuration);
+
+  if (!buttonsString) {
+    return [];
+  }
+
+  // Deduped at the source: `player_action_buttons` is a hand-typed string, so
+  // the same identifier can legitimately appear twice. Left alone, a repeat
+  // would be counted twice against the inline limit, rendered twice on the
+  // overlay, and collide as a React key. Items with no `invokeAction` are
+  // dropped here too - they can never do anything.
+  return usableActionItems(
+    resolveActionIdentifiers({
+      identifiers: buttonsString,
+      entry,
+      expandEntryActions,
+    })
+  );
+}
+
+/** One control on the player overlay, before overflow is applied. */
+export type ActionButtonDescriptor =
+  | { kind: "subtitle" }
+  | { kind: "close" }
+  | { kind: "airplay" }
+  | { kind: "action"; action: RegisteredAction };
+
+/**
+ * The Overflow control, produced by `splitOverflow` when more content actions
+ * resolve than fit on the overlay.
+ */
+export type OverflowDescriptor = {
+  kind: "overflow";
+  /**
+   * Every content action, the overlay companion included. An overlay button
+   * renders nothing when its action has no icon, so the companion needs the
+   * sheet as a second home or it could be reachable from nowhere.
+   */
+  additionalActions: RegisteredAction[];
+};
+
+/** What the overlay actually renders, once overflow has been applied. */
+export type PlayerControlDescriptor =
+  | ActionButtonDescriptor
+  | OverflowDescriptor;

package/reactHooks/actions/index.ts

@@ -6,6 +6,7 @@ import { ActionsContext } from "@applicaster/zapp-react-native-ui-components/Con
 import {
   observeEntryState,
   RegisteredActionValue,
+  uiActionsRegistry,
 } from "../../uiActionsRegistrator";
 import { reactHooksLogger } from "../logger";
 
@@ -34,7 +35,13 @@ export function useActions<T = unknown>(plugId: string): any {
       if (!logged) {
         logger.warning({
           message: `useActions: Couldn't find an action for ${plugId} plugin`,
-          data: { actions: context?.actions },
+          // Identifiers only. The action map holds every plugin's module and
+          // live React context, which is far too large for a log line and can
+          // carry whatever state those plugins hold.
+          data: {
+            plugId,
+            availableActions: Object.keys(context?.actions ?? {}),
+          },
         });
 
         setLogged(true);
@@ -80,7 +87,31 @@ export function useEntryActionState(
   useEffect(() => {
     if (!action) return undefined;
 
-    const subscription = observeEntryState(action, entry).subscribe(setState);
+    // An action's stream is third-party code. Subscribing with only a `next`
+    // handler lets RxJS rethrow an error notification asynchronously, where no
+    // error boundary catches it - one plugin faulting would take the app down
+    // rather than this one button. The button keeps its last known state.
+    let subscription;
+
+    try {
+      subscription = observeEntryState(action, entry).subscribe({
+        next: setState,
+        error: (error) =>
+          logger.warning({
+            message:
+              "useEntryActionState: the action's state stream failed - the button keeps its last state",
+            data: { entryId, error },
+          }),
+      });
+    } catch (error) {
+      logger.warning({
+        message:
+          "useEntryActionState: could not observe the action - the button keeps its initial state",
+        data: { entryId, error },
+      });
+
+      return undefined;
+    }
 
     return () => subscription.unsubscribe();
     // eslint-disable-next-line @wogns3623/better-exhaustive-deps/exhaustive-deps
@@ -88,6 +119,18 @@ export function useEntryActionState(
 
   const invokeAction = useCallback(
     (options: InvokeArgsOptions = {}) => {
+      if (typeof action?.invokeAction !== "function") {
+        // A button was rendered and pressed, and the press goes nowhere. Only
+        // reachable on a user interaction, so it costs nothing on render. The
+        // action value carries no identifier, so the label is what locates the
+        // button that misbehaved.
+        logger.warning({
+          message:
+            "useEntryActionState: the pressed action has no invokeAction - the press did nothing",
+          data: { entryId, label: state?.label },
+        });
+      }
+
       action?.invokeAction?.(entry, { updateState: setState, ...options });
     },
     // eslint-disable-next-line @wogns3623/better-exhaustive-deps/exhaustive-deps
@@ -96,3 +139,25 @@ export function useEntryActionState(
 
   return { state, invokeAction };
 }
+
+/**
+ * A value that changes whenever a provider is added to or removed from
+ * `uiActionsRegistry`.
+ *
+ * Providers can register after the UI that wants them has rendered - the audio
+ * player registers playback speed only once its controller has state, and
+ * plugin-backed actions are bridged in from an effect. Put this in the
+ * dependency list of anything that resolves actions, so the list is re-read
+ * instead of being frozen at first paint.
+ */
+export function useRegistryRevision(): number {
+  const [revision, setRevision] = useState(0);
+
+  useEffect(
+    () =>
+      uiActionsRegistry.subscribe(() => setRevision((current) => current + 1)),
+    []
+  );
+
+  return revision;
+}