@applicaster/zapp-react-native-utils 16.0.0-alpha.2024822855 → 16.0.0-alpha.2105365027

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

@@ -25,6 +25,11 @@ export type {
   SelectionBehavior,
 } 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

@@ -37,8 +37,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;
@@ -118,6 +118,9 @@ 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;
+  context?: Record<string, any>;
 }
 
 export interface Menu {
@@ -131,3 +134,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.2024822855",
+  "version": "16.0.0-alpha.2105365027",
   "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.2024822855",
+    "@applicaster/applicaster-types": "16.0.0-alpha.2105365027",
     "buffer": "^5.2.1",
     "camelize": "^1.0.0",
     "dayjs": "^1.11.10",

package/perfTracker.ts

@@ -0,0 +1,203 @@
+import { createLogger } from "./logger";
+import { NativeModules } from "react-native";
+
+const { ProfilerBridge } = NativeModules;
+
+const loggerObj = createLogger({
+  category: "PerfTracker",
+  subsystem: "PerfTelemetry",
+});
+
+const renderCounts: Record<string, number> = {};
+const cellRenderCounts: Record<string, number> = {};
+
+const timingStats: Record<
+  string,
+  { totalMs: number; count: number; maxMs: number; minMs: number }
+> = {};
+
+const t0 = Date.now();
+
+export function getDelta(): number {
+  return Date.now() - t0;
+}
+
+export function recordTiming(
+  name: string,
+  durationMs: number,
+  details?: Record<string, any>
+): void {
+  const rounded = Math.round(durationMs * 100) / 100;
+
+  if (!timingStats[name]) {
+    timingStats[name] = {
+      totalMs: rounded,
+      count: 1,
+      maxMs: rounded,
+      minMs: rounded,
+    };
+  } else {
+    const s = timingStats[name];
+    s.totalMs = Math.round((s.totalMs + rounded) * 100) / 100;
+    s.count += 1;
+    if (rounded > s.maxMs) s.maxMs = rounded;
+    if (rounded < s.minMs) s.minMs = rounded;
+  }
+
+  const stat = timingStats[name];
+  const avg = Math.round((stat.totalMs / stat.count) * 100) / 100;
+  const delta = getDelta();
+
+  if (ProfilerBridge?.updateTimer) {
+    try {
+      ProfilerBridge.updateTimer("timings", name, rounded);
+    } catch (e) {}
+  }
+
+  if (stat.count <= 3 || rounded >= 3 || stat.count % 10 === 0) {
+    const msg = `[PERF TIMING #${stat.count}] ${name}: ${rounded}ms (avg: ${avg}ms, max: ${stat.maxMs}ms, total: ${stat.totalMs}ms) (+${delta}ms)`;
+
+    loggerObj.log_info(msg, {
+      timingName: name,
+      durationMs: rounded,
+      avgMs: avg,
+      maxMs: stat.maxMs,
+      minMs: stat.minMs,
+      totalMs: stat.totalMs,
+      count: stat.count,
+      deltaMs: delta,
+      ...(details || {}),
+    });
+  }
+}
+
+export function measureSync<T>(
+  name: string,
+  fn: () => T,
+  details?: Record<string, any>
+): T {
+  const start =
+    typeof performance !== "undefined" && performance.now
+      ? performance.now()
+      : Date.now();
+
+  try {
+    return fn();
+  } finally {
+    const end =
+      typeof performance !== "undefined" && performance.now
+        ? performance.now()
+        : Date.now();
+
+    recordTiming(name, end - start, details);
+  }
+}
+
+export function startTimer(
+  name: string,
+  details?: Record<string, any>
+): (additionalDetails?: Record<string, any>) => number {
+  const start =
+    typeof performance !== "undefined" && performance.now
+      ? performance.now()
+      : Date.now();
+
+  return (additionalDetails?: Record<string, any>) => {
+    const end =
+      typeof performance !== "undefined" && performance.now
+        ? performance.now()
+        : Date.now();
+
+    const duration = end - start;
+
+    recordTiming(name, duration, {
+      ...(details || {}),
+      ...(additionalDetails || {}),
+    });
+
+    return duration;
+  };
+}
+
+export function countRender(
+  componentName: string,
+  details?: Record<string, any>
+): number {
+  renderCounts[componentName] = (renderCounts[componentName] || 0) + 1;
+  const count = renderCounts[componentName];
+  const delta = getDelta();
+
+  if (ProfilerBridge?.updateCounter) {
+    try {
+      ProfilerBridge.updateCounter("render_count", componentName, count);
+    } catch (e) {}
+  }
+
+  const msg = `[PERF RENDER #${count}] ${componentName} (+${delta}ms)`;
+
+  loggerObj.log_info(msg, {
+    component: componentName,
+    count,
+    deltaMs: delta,
+    ...(details || {}),
+  });
+
+  return count;
+}
+
+export function countCellRender(
+  cellType: string,
+  itemId: string | number,
+  details?: Record<string, any>
+): number {
+  const key = `${cellType}:${itemId || "unknown"}`;
+  cellRenderCounts[key] = (cellRenderCounts[key] || 0) + 1;
+  const count = cellRenderCounts[key];
+
+  renderCounts[cellType] = (renderCounts[cellType] || 0) + 1;
+  const totalForType = renderCounts[cellType];
+  const delta = getDelta();
+
+  if (ProfilerBridge?.updateCounter) {
+    try {
+      ProfilerBridge.updateCounter("cell_render_count", cellType, totalForType);
+    } catch (e) {}
+  }
+
+  if (count > 1 || totalForType <= 12 || totalForType % 10 === 0) {
+    const msg = `[PERF CELL ${
+      count > 1 ? "RE-RENDER" : "RENDER"
+    } #${count}] ${cellType} item:${itemId} (total ${cellType}: #${totalForType}) (+${delta}ms)`;
+
+    loggerObj.log_info(msg, {
+      cellType,
+      itemId,
+      itemRenderCount: count,
+      totalForCellType: totalForType,
+      deltaMs: delta,
+      ...(details || {}),
+    });
+  }
+
+  return count;
+}
+
+export function dumpSummary(checkpoint: string): void {
+  const delta = getDelta();
+  let totalRenders = 0;
+
+  for (const k in renderCounts) {
+    totalRenders += renderCounts[k];
+  }
+
+  const summaryMsg = `=== [PERF SUMMARY at ${checkpoint}] total renders: ${totalRenders} (+${delta}ms) ===`;
+
+  loggerObj.log_info(summaryMsg, {
+    checkpoint,
+    elapsedMs: delta,
+    totalRenders,
+    renderCounts,
+    cellRenderCounts,
+    timingStats,
+  });
+}

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,