@applicaster/zapp-react-native-utils 16.0.0-alpha.1593888345 → 16.0.0-alpha.1733304298

package/modalState/__tests__/ModalOrchestrator.phase3.test.ts

@@ -44,4 +44,43 @@ describe("ModalOrchestrator phase 3", () => {
     expect(props.title).toBe("Sleep Timer");
     expect(props.summary).toBe("remaining");
   });
+
+  it("forwards the queue empty message onto the sheet props", () => {
+    modalOrchestrator.open({
+      header: { title: "Queue" },
+      content: {
+        title: "Queue",
+        items: [],
+        emptyMessage: "Queued items will be added here",
+      },
+    });
+
+    const props = (modalStore.getState().modalState.screen as any)
+      ?.modalBottomSheetContentProps;
+
+    expect(props.emptyMessage).toBe("Queued items will be added here");
+  });
+
+  it("forwards operationButtons onto the sheet props unchanged", () => {
+    const operationButtons = {
+      add: {
+        title: "Create New Playlist",
+        iconURL: "https://example.com/add.png",
+      },
+    };
+
+    modalOrchestrator.open({
+      header: { title: "Playlists" },
+      content: {
+        title: "Playlists",
+        items: [],
+        operationButtons,
+      },
+    });
+
+    const props = (modalStore.getState().modalState.screen as any)
+      ?.modalBottomSheetContentProps;
+
+    expect(props.operationButtons).toEqual(operationButtons);
+  });
 });

package/modalState/__tests__/RemoteEditableCollection.test.ts

@@ -34,16 +34,26 @@ const itemPlain: MenuItem = { id: "2", title: "B" };
 function makeCollection(
   items: MenuItem[],
   refetch = jest.fn().mockResolvedValue(undefined),
-  operations = ["remove", "reorder"]
+  operations = ["remove", "reorder"],
+  context?: Record<string, unknown>
 ) {
   const content = {
     items,
+    context,
     dynamicCollection: { operations, postUrl: "https://x/cloud-events" },
   } as unknown as Content;
 
   return { col: new RemoteEditableCollection(content, refetch), refetch };
 }
 
+const openingContext = {
+  component: {
+    id: "list-1",
+    data: { source: "https://example.com/user/collections/abc" },
+  },
+  screenData: { id: "playlist-screen" },
+};
+
 describe("RemoteEditableCollection", () => {
   beforeEach(() => jest.clearAllMocks());
 
@@ -118,6 +128,24 @@ describe("RemoteEditableCollection", () => {
       expect(refetch).toHaveBeenCalledTimes(1);
       expect(currentItems(col)).toEqual([itemWithRemove]);
     });
+
+    it("forwards stored sheet context plus the removed item as entry", async () => {
+      handleAction.mockResolvedValue("success");
+
+      const { col } = makeCollection(
+        [itemWithRemove, itemPlain],
+        jest.fn().mockResolvedValue(undefined),
+        ["remove", "reorder"],
+        openingContext
+      );
+
+      await col.remove(0);
+
+      expect(handleAction).toHaveBeenCalledWith(removeAction, {
+        ...openingContext,
+        entry: itemWithRemove,
+      });
+    });
   });
 
   describe("move", () => {
@@ -164,6 +192,35 @@ describe("RemoteEditableCollection", () => {
       expect(refetch).toHaveBeenCalledTimes(1);
     });
 
+    it("forwards stored sheet context plus the moved item as entry", async () => {
+      handleAction.mockResolvedValue("success");
+
+      const itemA: MenuItem = {
+        id: "2",
+        title: "B",
+        entryActions: [
+          { button: { alias: "reorder_item" }, actions: [removeAction] },
+        ],
+      };
+
+      const { col } = makeCollection(
+        [itemA],
+        jest.fn().mockResolvedValue(undefined),
+        ["remove", "reorder"],
+        openingContext
+      );
+
+      await col.move(["2"]);
+
+      expect(handleAction).toHaveBeenCalledWith(
+        expect.objectContaining({ type: "sendCloudEvent" }),
+        {
+          ...openingContext,
+          entry: itemA,
+        }
+      );
+    });
+
     it("rolls back on failure", async () => {
       handleAction.mockRejectedValue(new Error("nope"));
 
@@ -322,5 +379,37 @@ describe("RemoteEditableCollection", () => {
       expect(handleAction).toHaveBeenCalledWith(addAction);
       expect(refetch).toHaveBeenCalledTimes(1);
     });
+
+    it("forwards stored sheet context into events.add actions", async () => {
+      handleAction.mockResolvedValue("success");
+
+      const addAction = {
+        type: "showTextInput",
+        options: {
+          headerTitle: "Create Playlist",
+          buttonLabel: "Create",
+          actions: [{ type: "sendCloudEvent" }],
+        },
+      };
+
+      const content = {
+        items: [],
+        context: openingContext,
+        dynamicCollection: {
+          operations: ["add"],
+          postUrl: "https://x/cloud-events",
+          events: {
+            add: [addAction],
+          },
+        },
+      } as any;
+
+      const refetch = jest.fn().mockResolvedValue(undefined);
+      const col = new RemoteEditableCollection(content, refetch);
+
+      await col.add();
+
+      expect(handleAction).toHaveBeenCalledWith(addAction, openingContext);
+    });
   });
 });

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,6 +23,8 @@ export type {
   SecondaryAction,
   SelectMode,
   SelectionBehavior,
+  OperationButton,
+  OperationButtons,
 } from "./types";
 
 export {

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;
@@ -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 {

package/modalState/useBottomSheetContent.ts

@@ -1,4 +1,4 @@
-import React, { useEffect, useState } from "react";
+import React, { useCallback, useEffect, useState } from "react";
 import { toBooleanWithDefaultFalse } from "@applicaster/zapp-react-native-utils/booleanUtils";
 
 import { MenuItem, modalOrchestrator } from "./ModalOrchestrator";
@@ -45,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]);
 
@@ -65,16 +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 actions = getMenuItemActions(item);
-    const isSubMenu = actions.some(isPresentSubMenuAction);
+  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) {
@@ -82,7 +87,7 @@ export const useBottomSheetContent = (props: Props): Return => {
     } else {
       modalOrchestrator.close();
     }
-  }, [modalOrchestrator.canGoBack]);
+  }, []);
 
   return {
     items: viewModel?.editableCollection ? editableItems : state?.items,
@@ -94,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.1593888345",
+  "version": "16.0.0-alpha.1733304298",
   "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.1593888345",
+    "@applicaster/applicaster-types": "16.0.0-alpha.1733304298",
     "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/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",
 };

package/quickBrickAssets/__tests__/index.test.ts

@@ -0,0 +1,18 @@
+// The Jest stand-in for @applicaster/quick-brick-assets maps each existing key to itself
+import { getQuickBrickAsset } from "..";
+
+describe("getQuickBrickAsset", () => {
+  it("returns the asset for a plugin identifier and path", () => {
+    expect(
+      getQuickBrickAsset("mute_unmute_action", "action/flavour_1/mute.png")
+    ).toBe("mute_unmute_action/action/flavour_1/mute.png");
+  });
+
+  it("rejects unknown paths and plugin identifiers at compile time", () => {
+    // @ts-expect-error - no such file in mute_unmute_action
+    getQuickBrickAsset("mute_unmute_action", "action/flavour_9/mute.png");
+
+    // @ts-expect-error - no assets folder for this plugin
+    getQuickBrickAsset("unknown_plugin", "action/flavour_1/mute.png");
+  });
+});

package/quickBrickAssets/index.ts

@@ -0,0 +1,35 @@
+import assets from "@applicaster/quick-brick-assets";
+import type {
+  QuickBrickAssetKey,
+  QuickBrickAssetSource,
+} from "@applicaster/quick-brick-assets";
+
+export type { QuickBrickAssetKey, QuickBrickAssetSource };
+
+type PluginOf<K> = K extends `${infer Plugin}/${string}` ? Plugin : never;
+
+type PathOf<K, Plugin extends string> = K extends `${Plugin}/${infer Path}`
+  ? Path
+  : never;
+
+/** Plugin identifiers that have a folder in `@applicaster/quick-brick-assets`. */
+export type QuickBrickAssetPlugin = PluginOf<QuickBrickAssetKey>;
+
+/** Asset paths inside the given plugin's folder. */
+export type QuickBrickAssetPath<Plugin extends QuickBrickAssetPlugin> = PathOf<
+  QuickBrickAssetKey,
+  Plugin
+>;
+
+/**
+ * Looks up an asset of `@applicaster/quick-brick-assets` by plugin identifier
+ * and path relative to the plugin folder, e.g.
+ * `getQuickBrickAsset("mute_unmute_action", "action/flavour_1/mute.png")`.
+ * Both arguments are checked against the package's files at compile time.
+ * Density variants (`@2x` / `@3x`) are not supported.
+ */
+export const getQuickBrickAsset = <Plugin extends QuickBrickAssetPlugin>(
+  pluginIdentifier: Plugin,
+  assetPath: QuickBrickAssetPath<Plugin>
+): QuickBrickAssetSource =>
+  assets[`${pluginIdentifier}/${assetPath}` as QuickBrickAssetKey];

package/reactHooks/__tests__/getPluginConfiguration.test.ts

@@ -0,0 +1,82 @@
+import { renderHook } from "@testing-library/react-native";
+
+const plugin = {
+  identifier: "cast",
+  configuration: {
+    title: "Configured",
+    localizations: { fr: { close: "Fermer" } },
+  },
+};
+
+jest.mock("@applicaster/zapp-react-native-redux/hooks", () => ({
+  usePlugins: () => [plugin],
+}));
+
+jest.mock(
+  "@applicaster/zapp-react-native-utils/appUtils/localizationsHelper",
+  () => ({ getUILanguage: () => "fr" })
+);
+
+import {
+  getPluginConfiguration,
+  mergeLocalizations,
+  usePluginConfiguration,
+} from "../usePluginConfiguration";
+
+const manifest = {
+  custom_configuration_fields: [
+    { key: "title", initial_value: "Default" },
+    { key: "color", initial_value: "red" },
+  ],
+  localizations: {
+    fields: [
+      { key: "close", initial_value: "Close" },
+      { key: "cancel", initial_value: "Cancel" },
+    ],
+  },
+};
+
+it("matches usePluginConfiguration outside React", () => {
+  const { result } = renderHook(() => usePluginConfiguration("cast", manifest));
+
+  expect(getPluginConfiguration(plugin, manifest)).toEqual(result.current);
+});
+
+// Expected values are what R.mergeDeepWith((l, r) => (isNil(l) ? r : l)) returned before ramda was removed
+describe("mergeLocalizations", () => {
+  const defaults = { en: { close: "Close", cancel: "Cancel" } };
+
+  it("returns the defaults when nothing is configured", () => {
+    expect(mergeLocalizations(undefined, defaults)).toEqual(defaults);
+  });
+
+  it("keeps configured values, fills nil ones and missing keys from defaults", () => {
+    expect(
+      mergeLocalizations(
+        { en: { close: null, extra: "X" }, fr: { close: "Fermer" } },
+        defaults
+      )
+    ).toEqual({
+      en: { close: "Close", extra: "X", cancel: "Cancel" },
+      fr: { close: "Fermer" },
+    });
+  });
+
+  it("does not merge arrays", () => {
+    expect(
+      mergeLocalizations(
+        { en: { close: ["a"] } },
+        { en: { close: ["b"], cancel: "C" } }
+      )
+    ).toEqual({ en: { close: ["a"], cancel: "C" } });
+  });
+});
+
+it("keeps configured languages first, so the fallback language stays the configured one", () => {
+  const merged = mergeLocalizations(
+    { he: { close: "סגור" }, en: { close: "Close it" } },
+    { en: { close: "Close" } }
+  );
+
+  expect(Object.keys(merged)).toEqual(["he", "en"]);
+});