@applicaster/zapp-react-native-utils 16.0.0-alpha.2663208063 → 16.0.0-alpha.2710214351

package/modalState/__tests__/useModalStoreState.test.ts

@@ -0,0 +1,142 @@
+import { act, renderHook } from "@testing-library/react-native";
+
+import { modalStore, useModalStoreState } from "../";
+
+const item = { id: "river-general", name: "Test Modal" };
+const props = { entry: { id: "modal-entry-1" } };
+
+const openModal = () =>
+  act(() => {
+    modalStore.getState().openModal({ item, props } as any);
+  });
+
+// Counts every render of the hook so the tests can assert on subscription
+// behaviour, not just on the returned value.
+const renderModalStoreState = (skipSubscription?: boolean) => {
+  const renders = { count: 0 };
+
+  const view = renderHook(() => {
+    renders.count += 1;
+
+    return skipSubscription === undefined
+      ? useModalStoreState()
+      : useModalStoreState(skipSubscription);
+  });
+
+  return { ...view, renders };
+};
+
+describe("useModalStoreState", () => {
+  afterEach(() => {
+    act(() => {
+      modalStore.getState().dismissModal();
+    });
+  });
+
+  describe("when subscribed (default)", () => {
+    it("returns the live modal state when called without arguments", () => {
+      const { result } = renderModalStoreState();
+
+      expect(result.current.visible).toBe(false);
+
+      openModal();
+
+      expect(result.current.visible).toBe(true);
+      expect(result.current.screen).toBe(item);
+      expect(result.current.props).toBe(props);
+    });
+
+    it("re-renders the consumer when the modal state changes", () => {
+      const { renders } = renderModalStoreState(false);
+
+      const rendersBeforeOpen = renders.count;
+
+      openModal();
+
+      expect(renders.count).toBeGreaterThan(rendersBeforeOpen);
+    });
+
+    // Counterpart to "returns a stable reference across store updates": an open
+    // modal is the one point where a live subscription and a skipped one hold
+    // different references, which is what makes that assertion meaningful.
+    it("returns a new reference while the modal is open", () => {
+      const { result } = renderModalStoreState(false);
+
+      const firstValue = result.current;
+
+      openModal();
+
+      expect(result.current).not.toBe(firstValue);
+    });
+  });
+
+  describe("when subscription is skipped", () => {
+    it("reports an empty modal state even while a modal is open", () => {
+      openModal();
+
+      expect(modalStore.getState().modalState.visible).toBe(true);
+
+      const { result } = renderModalStoreState(true);
+
+      expect(result.current).toMatchObject({
+        visible: false,
+        screen: null,
+        options: {},
+        props: {},
+      });
+    });
+
+    it("does not re-render the consumer when the modal state changes", () => {
+      const { renders } = renderModalStoreState(true);
+
+      const rendersBeforeOpen = renders.count;
+
+      openModal();
+
+      expect(renders.count).toBe(rendersBeforeOpen);
+    });
+
+    // The skipped branch has to hand back a module-level constant. Returning a
+    // fresh object would fail zustand's Object.is check and re-render on every
+    // store notification - the opposite of what skipping is for.
+    it("returns a stable reference across store updates", () => {
+      const { result } = renderModalStoreState(true);
+
+      const firstValue = result.current;
+
+      openModal();
+
+      // Asserted while the modal is open: dismissing resets the store to the
+      // very same initialModalState object, so an end-to-end round trip would
+      // hold this identity even for a live subscription.
+      expect(result.current).toBe(firstValue);
+
+      act(() => {
+        modalStore.getState().dismissModal();
+      });
+
+      expect(result.current).toBe(firstValue);
+    });
+  });
+
+  it("picks up the current modal state when it starts subscribing", () => {
+    let skipSubscription = true;
+
+    const { result, rerender } = renderHook(() =>
+      useModalStoreState(skipSubscription)
+    );
+
+    openModal();
+
+    expect(result.current.visible).toBe(false);
+
+    skipSubscription = false;
+
+    act(() => {
+      rerender(undefined);
+    });
+
+    expect(result.current.visible).toBe(true);
+    expect(result.current.screen).toBe(item);
+  });
+});

package/modalState/index.ts

@@ -23,8 +23,15 @@ export type {
   SecondaryAction,
   SelectMode,
   SelectionBehavior,
+  OperationButton,
+  OperationButtons,
 } from "./types";
 
-export { isPresentSubMenuAction, OPERATIONS, hasOperation } from "./types";
+export {
+  isPresentSubMenuAction,
+  getMenuItemActions,
+  OPERATIONS,
+  hasOperation,
+} from "./types";
 
 export { useBottomSheetContent } from "./useBottomSheetContent";

package/modalState/store.ts

@@ -98,5 +98,12 @@ export const openBottomSheetModal = ({
   });
 };
 
-export const useModalStoreState = (): ModalState =>
-  useModalStore<ModalState>((state) => state.modalState);
+/**
+ * Pass `skipSubscription` from callers that render outside of a modal: the
+ * selector then returns the stable `initialModalState` reference, so the
+ * component is never re-rendered by modal state it does not read.
+ */
+export const useModalStoreState = (skipSubscription = false): ModalState =>
+  useModalStore<ModalState>((state) =>
+    skipSubscription ? initialModalState : state.modalState
+  );

package/modalState/types.ts

@@ -1,3 +1,5 @@
+import type { EntryAction } from "../entryActions/types";
+
 export interface Header {
   title: string;
   subtitle?: string;
@@ -37,8 +39,8 @@ export interface MenuItem {
   summary?: string;
   icon?: string;
   isSelected?: boolean;
-  // When item represents an audio item, clicking on it will start playback
-  // and secondary action will allow to add it to queue or playlist
+  actions?: (Action | PresentSubMenuAction)[];
+  /** @deprecated Use `actions` array instead. Maintained for backwards compatibility. */
   action?: Action | PresentSubMenuAction;
   secondaryAction?: SecondaryAction;
   trailingButton?: any;
@@ -107,6 +109,13 @@ export interface DynamicCollectionOptions {
   events?: Record<CollectionScopedOperation | string, Action[]>;
 }
 
+/** Presentation of a sheet-synthesized operation control; same fields as an entry action button. */
+export type OperationButton = Pick<EntryAction["button"], "title" | "iconURL">;
+
+export type OperationButtons = Partial<
+  Record<CollectionScopedOperation | string, OperationButton>
+>;
+
 export interface Content {
   title: string;
   stickyTitle?: boolean;
@@ -118,6 +127,11 @@ export interface Content {
   dynamicCollection?: DynamicCollectionOptions;
   themePluginId?: string;
   styleOverrides?: Record<string, any>;
+  /** Shown under Next Up when the queue sheet has no upcoming items. */
+  emptyMessage?: string;
+  /** Producer-owned presentation for sheet-synthesized operation controls (e.g. `add`). */
+  operationButtons?: OperationButtons;
+  context?: Record<string, any>;
 }
 
 export interface Menu {
@@ -131,3 +145,29 @@ export function isPresentSubMenuAction(
 ): 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

@@ -1,14 +1,15 @@
-import React, { useEffect, useState } from "react";
+import React, { useCallback, useEffect, useState } from "react";
 import { toBooleanWithDefaultFalse } from "@applicaster/zapp-react-native-utils/booleanUtils";
 
-import {
-  isPresentSubMenuAction,
-  MenuItem,
-  modalOrchestrator,
-} from "./ModalOrchestrator";
+import { MenuItem, modalOrchestrator } from "./ModalOrchestrator";
 
 import { ContentViewModel } from "./ContentViewModel";
-import type { DynamicCollectionOptions, SelectionBehavior } from "./types";
+import {
+  DynamicCollectionOptions,
+  getMenuItemActions,
+  isPresentSubMenuAction,
+  SelectionBehavior,
+} from "./types";
 import type { EditableCollection } from "./EditableCollection";
 
 type Props = {
@@ -44,7 +45,9 @@ export const useBottomSheetContent = (props: Props): Return => {
   // Subscribe to the viewModel state changes
   useEffect(() => {
     return viewModel?.subscribe((nextState) => {
-      setState(nextState);
+      setState((state) => {
+        return state === nextState ? state : nextState;
+      });
     });
   }, [viewModel]);
 
@@ -64,15 +67,19 @@ export const useBottomSheetContent = (props: Props): Return => {
    * - 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 isSubMenu = item.action && isPresentSubMenuAction(item.action);
+  const handleItemPress = useCallback(
+    async (item: MenuItem) => {
+      const actions = getMenuItemActions(item);
+      const isSubMenu = actions.some(isPresentSubMenuAction);
 
-    await onPress(item);
+      await onPress(item);
 
-    if (!isSubMenu) {
-      await viewModel?.refetch();
-    }
-  };
+      if (!isSubMenu) {
+        await viewModel?.refetch();
+      }
+    },
+    [onPress, viewModel]
+  );
 
   const goBackOrClose = React.useCallback(() => {
     if (modalOrchestrator.canGoBack) {
@@ -80,7 +87,7 @@ export const useBottomSheetContent = (props: Props): Return => {
     } else {
       modalOrchestrator.close();
     }
-  }, [modalOrchestrator.canGoBack]);
+  }, []);
 
   return {
     items: viewModel?.editableCollection ? editableItems : state?.items,
@@ -92,7 +99,7 @@ export const useBottomSheetContent = (props: Props): Return => {
     canGoBack: modalOrchestrator.canGoBack,
     handleItemPress,
     goBackOrClose,
-    close: () => modalOrchestrator.close(),
+    close: useCallback(() => modalOrchestrator.close(), []),
     role: state?.role,
     behavior: state?.behavior,
     dynamicCollection: state?.dynamicCollection,

package/navigationUtils/xrayNavigator.ts

@@ -0,0 +1,12 @@
+/**
+ * The app navigator for the X-Ray toolboxes (nav, screen), which run outside React. The
+ * NavigationProvider sets it after each commit; it is a plain module variable, so updating it
+ * never renders anything.
+ */
+let navigator: QuickBrickAppNavigator | undefined;
+
+export const setXrayNavigator = (value: QuickBrickAppNavigator | undefined) => {
+  navigator = value;
+};
+
+export const getXrayNavigator = () => navigator;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applicaster/zapp-react-native-utils",
-  "version": "16.0.0-alpha.2663208063",
+  "version": "16.0.0-alpha.2710214351",
   "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.2663208063",
+    "@applicaster/applicaster-types": "16.0.0-alpha.2710214351",
     "buffer": "^5.2.1",
     "camelize": "^1.0.0",
     "dayjs": "^1.11.10",
@@ -36,6 +36,7 @@
     "prop-types": "^15.0.0"
   },
   "peerDependencies": {
+    "@applicaster/quick-brick-assets": "*",
     "@applicaster/zapp-pipes-v2-client": "*",
     "@react-native-community/netinfo": "*",
     "react": "*",

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/pluginUtils/__tests__/pluginUtils.test.js

@@ -1,3 +1,9 @@
+const mockAppStoreGet = jest.fn();
+
+jest.mock("@applicaster/zapp-react-native-redux/AppStore", () => ({
+  appStore: { get: (key) => mockAppStoreGet(key) },
+}));
+
 import * as R from "ramda";
 import * as pluginUtils from "../index";
 
@@ -148,6 +154,32 @@ describe("findPluginByIdentifier", () => {
   });
 });
 
+describe("getPluginByIdentifier", () => {
+  const { getPluginByIdentifier } = pluginUtils;
+
+  const plugins = {
+    foo: pluginMock("foo", "foo", "some_plugin_type"),
+    bar: pluginMock("foo", "bar", "some_plugin_type"),
+  };
+
+  beforeEach(() => {
+    mockAppStoreGet.mockReset();
+  });
+
+  it("reads plugins from appStore and returns the matching plugin", () => {
+    mockAppStoreGet.mockReturnValue(plugins);
+
+    expect(getPluginByIdentifier("foo")).toEqual(plugins.foo);
+    expect(mockAppStoreGet).toHaveBeenCalledWith("plugins");
+  });
+
+  it("returns undefined when the plugin is not found", () => {
+    mockAppStoreGet.mockReturnValue(plugins);
+
+    expect(getPluginByIdentifier("do_not_exist")).toBeUndefined();
+  });
+});
+
 describe("findPluginByType", () => {
   const { findPluginByType } = pluginUtils;
 

package/pluginUtils/index.ts

@@ -1,4 +1,5 @@
 import * as R from "ramda";
+import { appStore } from "@applicaster/zapp-react-native-redux/AppStore";
 import { toCamelCase, toPascalCase } from "../stringUtils";
 
 import { getNavigationType } from "../navigationUtils";
@@ -97,6 +98,34 @@ export function findPluginByIdentifier(
   return plugin;
 }
 
+/**
+ * Like findPluginByIdentifier, but reads the current plugins list from appStore.
+ * Convenience for non-render / hook code that doesn't already have `plugins` in hand.
+ * @param identifier of the plugin to look for
+ * @param doNotWarn if set to true, will not log a warning if plugin is not found
+ * @return whole plugin if found, undefined otherwise
+ */
+export function getPluginByIdentifier(
+  identifier: string,
+  doNotWarn: boolean = false
+): (QuickBrickPlugin | ZappPlugin | Plugin) | undefined {
+  try {
+    const plugins = appStore.get("plugins") ?? {};
+
+    return findPluginByIdentifier(identifier, plugins, doNotWarn);
+  } catch (error) {
+    if (!doNotWarn) {
+      pluginUtilsLogger.warning({
+        message:
+          "Could not read plugins from appStore while resolving plugin by identifier",
+        data: { identifier, error },
+      });
+    }
+
+    return undefined;
+  }
+}
+
 const pluginTypeForItemTypeMap = {
   playable: "player",
 };