@applicaster/zapp-react-native-utils 15.1.13 → 15.1.15-alpha.4236143002

package/modalState/types.ts

@@ -0,0 +1,160 @@
+export interface Header {
+  title: string;
+  subtitle?: string;
+  icon?: string;
+}
+
+export interface Action {
+  type: string;
+  payload?: any;
+  options?: any;
+}
+
+// Represented as 3 dots icon on top menu (opens new second level menu on desktop
+// or a new bottom sheet on mobile)
+export interface PresentSubMenuAction extends Action {
+  menu: Menu;
+}
+
+export interface SecondaryAction {
+  action: Action | PresentSubMenuAction;
+  icon?: string;
+}
+
+/**
+ * A group of actions attached to an entry, keyed by a button alias
+ * (e.g. "remove_item", "reorder_item"). Injected by the feed decorator and
+ * dispatched by the remote EditableCollection when an operation runs.
+ */
+export interface EntryActionGroup {
+  button?: { alias?: string };
+  actions?: Action[];
+}
+
+export interface MenuItem {
+  id: string;
+  title: string;
+  summary?: string;
+  icon?: string;
+  isSelected?: boolean;
+  actions?: (Action | PresentSubMenuAction)[];
+  /** @deprecated Use `actions` array instead. Maintained for backwards compatibility. */
+  action?: Action | PresentSubMenuAction;
+  secondaryAction?: SecondaryAction;
+  trailingButton?: any;
+  entryActions?: EntryActionGroup[];
+}
+
+export type SelectMode = "single" | "multi" | "none";
+
+export interface SelectionBehavior {
+  selectMode?: SelectMode;
+  currentSelection?: string[];
+  selector?: string;
+}
+
+/**
+ * Operations that act on a specific item in the collection.
+ * Their action payloads are looked up on the item's entryActions (e.g. "remove_item", "reorder_item").
+ */
+export type ItemScopedOperation = "remove" | "reorder";
+
+/**
+ * Operations that act on the collection as a whole.
+ * Their action payloads are looked up on dynamicCollection.events (e.g. events.add, events.clearAll, events.delete).
+ */
+export type CollectionScopedOperation = "add" | "clearAll" | "delete";
+
+/**
+ * UI display or behavior flags that do not require action payloads.
+ */
+export type UIOperation = "nowPlaying";
+
+export const OPERATIONS = {
+  REMOVE: "remove",
+  REORDER: "reorder",
+  ADD: "add",
+  CLEAR_ALL: "clearAll",
+  DELETE: "delete",
+  NOW_PLAYING: "nowPlaying",
+} as const;
+
+export function hasOperation(
+  operations: string[] | undefined,
+  target: string
+): boolean {
+  if (!Array.isArray(operations)) return false;
+
+  const targetLower = target.toLowerCase();
+
+  return operations.some(
+    (op) => typeof op === "string" && op.toLowerCase() === targetLower
+  );
+}
+
+export type Operation =
+  | ItemScopedOperation
+  | CollectionScopedOperation
+  | UIOperation;
+
+export interface DynamicCollectionOptions {
+  operations: Operation[];
+  postUrl?: string;
+  provider?: string;
+  /**
+   * Action handlers for CollectionScopedOperations (e.g. "add", "clearAll", "delete").
+   */
+  events?: Record<CollectionScopedOperation | string, Action[]>;
+}
+
+export interface Content {
+  title: string;
+  stickyTitle?: boolean;
+  items: MenuItem[];
+  itemsUrl?: string;
+  action?: Action;
+  role?: string;
+  behavior?: SelectionBehavior;
+  dynamicCollection?: DynamicCollectionOptions;
+  themePluginId?: string;
+  styleOverrides?: Record<string, any>;
+  context?: Record<string, any>;
+}
+
+export interface Menu {
+  header?: Header;
+  content: Content;
+  closeButton?: boolean;
+}
+
+export function isPresentSubMenuAction(
+  action: any
+): action is PresentSubMenuAction {
+  return !!action && typeof action === "object" && "menu" in action;
+}
+
+/**
+ * Normalizes an item's action/actions into an array of Action items.
+ * Supports canonical `actions: Action[]` and backwards-compatible `action: Action | Action[]`.
+ */
+export function getMenuItemActions(
+  item?: Partial<MenuItem> | null
+): (Action | PresentSubMenuAction)[] {
+  if (!item) {
+    return [];
+  }
+
+  if (Array.isArray(item.actions) && item.actions.length > 0) {
+    return item.actions;
+  }
+
+  if (Array.isArray((item as any).action)) {
+    return (item as any).action;
+  }
+
+  if (item.action) {
+    return [item.action];
+  }
+
+  return [];
+}

package/modalState/useBottomSheetContent.ts

@@ -0,0 +1,104 @@
+import React, { useEffect, useState } from "react";
+import { toBooleanWithDefaultFalse } from "@applicaster/zapp-react-native-utils/booleanUtils";
+
+import { MenuItem, modalOrchestrator } from "./ModalOrchestrator";
+
+import { ContentViewModel } from "./ContentViewModel";
+import {
+  DynamicCollectionOptions,
+  getMenuItemActions,
+  isPresentSubMenuAction,
+  SelectionBehavior,
+} from "./types";
+import type { EditableCollection } from "./EditableCollection";
+
+type Props = {
+  viewModel?: ContentViewModel | null;
+  onPress: (item: MenuItem) => void | Promise<void>;
+};
+
+type Return = {
+  items: MenuItem[];
+  isLoading: boolean;
+  error?: Error | string;
+  showCentralLoading: boolean;
+  canGoBack: boolean;
+  handleItemPress: (item: MenuItem) => Promise<void>;
+  goBackOrClose: () => void;
+  close: () => void;
+  role?: string;
+  behavior?: SelectionBehavior;
+  dynamicCollection?: DynamicCollectionOptions;
+  editableCollection: EditableCollection | null;
+  themePluginId?: string;
+};
+
+export const useBottomSheetContent = (props: Props): Return => {
+  const { onPress, viewModel } = props;
+
+  const [state, setState] = useState(viewModel?.getState());
+
+  const [editableItems, setEditableItems] = useState<MenuItem[]>(
+    () => viewModel?.getState().items || []
+  );
+
+  // Subscribe to the viewModel state changes
+  useEffect(() => {
+    return viewModel?.subscribe((nextState) => {
+      setState(nextState);
+    });
+  }, [viewModel]);
+
+  // Subscribe to editable collection items
+  useEffect(() => {
+    if (viewModel?.editableCollection) {
+      const subscription =
+        viewModel.editableCollection.items$.subscribe(setEditableItems);
+
+      return () => subscription.unsubscribe();
+    }
+  }, [viewModel?.editableCollection]);
+
+  /**
+   * Handles an item press:
+   * - Delegates to the parent onPress (which runs the action and awaits it).
+   * - If the item was a leaf action (not a submenu), triggers viewModel.refetch()
+   *   so that checkmarks (isSelected) reflect the updated server state.
+   */
+  const handleItemPress = async (item: MenuItem) => {
+    const actions = getMenuItemActions(item);
+    const isSubMenu = actions.some(isPresentSubMenuAction);
+
+    await onPress(item);
+
+    if (!isSubMenu) {
+      await viewModel?.refetch();
+    }
+  };
+
+  const goBackOrClose = React.useCallback(() => {
+    if (modalOrchestrator.canGoBack) {
+      modalOrchestrator.back();
+    } else {
+      modalOrchestrator.close();
+    }
+  }, [modalOrchestrator.canGoBack]);
+
+  return {
+    items: viewModel?.editableCollection ? editableItems : state?.items,
+    isLoading: toBooleanWithDefaultFalse(state?.isLoading),
+    error: state?.error,
+    showCentralLoading: toBooleanWithDefaultFalse(
+      state?.isLoading && state?.items.length === 0
+    ),
+    canGoBack: modalOrchestrator.canGoBack,
+    handleItemPress,
+    goBackOrClose,
+    close: () => modalOrchestrator.close(),
+    role: state?.role,
+    behavior: state?.behavior,
+    dynamicCollection: state?.dynamicCollection,
+    editableCollection: viewModel?.editableCollection || null,
+    themePluginId: state?.themePluginId,
+  };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applicaster/zapp-react-native-utils",
-  "version": "15.1.13",
+  "version": "15.1.15-alpha.4236143002",
   "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": "15.1.13",
+    "@applicaster/applicaster-types": "15.1.15-alpha.4236143002",
     "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;
+}

package/reactHooks/usePluginConfiguration.ts

@@ -1,7 +1,7 @@
 import * as R from "ramda";
 import { useMemo } from "react";
 
-import { usePickFromState } from "@applicaster/zapp-react-native-redux/hooks";
+import { usePlugins } from "@applicaster/zapp-react-native-redux/hooks";
 
 // importing this way prevents typescript packages importing from this
 // file to go crazy reporting errors on JS
@@ -24,8 +24,11 @@ export function parsePluginConfiguration(plugin, manifest) {
   return populateFields(plugin, manifest.custom_configuration_fields);
 }
 
-export function usePluginConfiguration<T, S>(identifier, manifest) {
-  const { plugins } = usePickFromState(["plugins"]);
+export function usePluginConfiguration<T = any, S = Record<string, any>>(
+  identifier: string,
+  manifest?: any
+) {
+  const plugins = usePlugins();
 
   const plugin = useMemo(
     () => R.find(R.propEq("identifier", identifier), plugins),