@applicaster/zapp-react-native-utils 16.0.0-alpha.2434153375 → 16.0.0-alpha.2500443242

package/entryActions/__tests__/buildEntryActions.test.ts

@@ -60,7 +60,7 @@ describe("buildEntryActions - alias & label resolution", () => {
     expect(state.label).toBe("Label Property Action");
   });
 
-  it("resolves entry action with known backend button alias (e.g. add_all_to_queue)", () => {
+  it("humanizes an un-overridden alias and falls back to the placeholder asset", () => {
     const entry = {
       id: "entry-3",
       extensions: {
@@ -71,11 +71,7 @@ describe("buildEntryActions - alias & label resolution", () => {
             dismiss_on_action: true,
           },
           {
-            button: { alias: "add_to_playlist" },
-            actions: [{ type: "test" }],
-          },
-          {
-            button: { alias: "delete_collection" },
+            button: { alias: "custom_unknown_action" },
             actions: [{ type: "test" }],
           },
         ],
@@ -84,42 +80,86 @@ describe("buildEntryActions - alias & label resolution", () => {
 
     const actions = resolveEntryActions(entry as any);
 
-    expect(actions).toHaveLength(3);
+    expect(actions).toHaveLength(2);
 
+    // No built-in alias vocabulary any more: underscores become spaces and
+    // only the first letter is capitalized, so "queue" stays lowercase.
     expect(actions[0].action.initialEntryState(entry as any)).toMatchObject({
       state: 0,
-      label: "Add all to Queue",
+      label: "Add all to queue",
     });
 
     expect(actions[1].action.initialEntryState(entry as any)).toMatchObject({
       state: 0,
-      label: "Add to Playlist",
+      label: "Custom unknown action",
     });
 
-    expect(actions[2].action.initialEntryState(entry as any)).toMatchObject({
-      state: 0,
-      label: "Delete collection",
-    });
+    // The asset has no such fallback: without an override it is the red-box
+    // placeholder, so a missing Studio icon is visible rather than absent.
+    for (const action of actions) {
+      expect(action.action.initialEntryState(entry as any)).toMatchObject({
+        asset: expect.stringMatching(/^data:image\/png;base64,/),
+      });
+    }
   });
 
-  it("formats unknown alias nicely as fallback", () => {
+  it("prefers aliasPresentation overrides over the humanized fallbacks", () => {
+    const deps = {
+      actionExecutor: { handleActions: jest.fn() } as any,
+      actionContext: {},
+      aliasPresentation: {
+        labels: { add_all_to_queue: "Add all to Queue" },
+        assets: { add_all_to_queue: "http://example.com/queue.png" },
+      },
+    };
+
     const entry = {
       id: "entry-4",
       extensions: {
         entry_action: [
           {
-            button: { alias: "custom_unknown_action" },
+            button: { alias: "add_all_to_queue" },
+            actions: [{ type: "test" }],
+          },
+          {
+            button: { alias: "not_overridden" },
             actions: [{ type: "test" }],
           },
         ],
       },
     };
 
-    const actions = resolveEntryActions(entry as any);
+    const actions = buildEntryActions(entry as any, deps);
 
-    expect(actions).toHaveLength(1);
+    expect(actions[0].action.initialEntryState(entry as any)).toMatchObject({
+      label: "Add all to Queue",
+      asset: "http://example.com/queue.png",
+    });
+
+    // Overrides are per-alias, so an alias absent from the map still humanizes.
+    expect(actions[1].action.initialEntryState(entry as any)).toMatchObject({
+      label: "Not overridden",
+    });
+  });
+
+  it("returns no asset when the button has neither iconURL nor alias", () => {
+    const entry = {
+      id: "entry-5",
+      extensions: {
+        entry_action: [
+          {
+            button: { label: "Plain Label" },
+            actions: [{ type: "test" }],
+          },
+        ],
+      },
+    };
+
+    const actions = resolveEntryActions(entry as any);
     const state = actions[0].action.initialEntryState(entry as any);
-    expect(state.label).toBe("Custom unknown action");
+
+    expect(state.label).toBe("Plain Label");
+    expect(state.asset).toBeUndefined();
   });
 
   it("uses actionExecutor.getActionState for plugin-provided label and asset", () => {
@@ -154,3 +194,42 @@ describe("buildEntryActions - alias & label resolution", () => {
     });
   });
 });
+
+describe("buildEntryActions - invokeAction execution context", () => {
+  it("forwards the List component from invoke options into handleActions", async () => {
+    const handleActions = jest.fn();
+
+    const component = {
+      id: "list-1",
+      data: { source: "https://example.com/user/collections/abc" },
+    };
+
+    const deps = {
+      actionExecutor: { handleActions } as any,
+      actionContext: { screenData: { id: "playlist-screen" } },
+    };
+
+    const entry = {
+      id: "entry-1",
+      extensions: {
+        entry_action: [
+          {
+            button: { title: "Edit Name" },
+            actions: [{ type: "refreshComponent" }],
+          },
+        ],
+      },
+    };
+
+    const [action] = buildEntryActions(entry as any, deps);
+
+    await action.action.invokeAction(entry as any, { component });
+
+    expect(handleActions).toHaveBeenCalledWith([{ type: "refreshComponent" }], {
+      entry,
+      entryContext: entry,
+      screenData: { id: "playlist-screen" },
+      component,
+    });
+  });
+});

package/entryActions/aliasPresentation.ts

@@ -1,52 +1,29 @@
 /**
- * Presentation defaults for backend action aliases.
+ * Presentation fallbacks for backend action aliases.
  *
  * Entries may declare an action by `alias` alone, without a label or an icon.
- * These maps are the last-resort labels/icons for the aliases we know about; an
- * unknown alias falls back to a humanized version of the alias itself.
+ * There is no built-in alias vocabulary: a label falls back to a humanized
+ * version of the alias itself, and an icon falls back to an inline placeholder
+ * that is deliberately conspicuous, so a missing asset reads as unconfigured
+ * rather than as a deliberate blank.
  *
- * They are defaults, not a framework guarantee: an app that speaks a different
- * alias vocabulary, needs other languages, or does not want to depend on these
- * icon hosts passes its own through `EntryActionDeps.aliasPresentation`.
+ * Both are last resorts, not a framework guarantee: an app that speaks its own
+ * alias vocabulary or needs other languages passes labels and assets through
+ * `EntryActionDeps.aliasPresentation`, which is consulted per alias.
  */
 
 import { EntryAction } from "./types";
 
-const ADD_TO_PLAYLIST_ICON =
-  "https://assets-secure.applicaster.com/zapp/assets/app_family/1710/906728572617/playlist_add_24dp_FFFFFF_FILL0_wght400_GRAD0_opsz24.png";
-
-const REMOVE_ICON =
-  "https://assets-secure.applicaster.com/zapp/assets/app_family/1710/372097240191/remove_24dp_EA3323_FILL0_wght400_GRAD0_opsz24.png";
-
-const EDIT_ICON =
-  "https://upload.wikimedia.org/wikipedia/commons/b/b6/Edit-icon.png";
-
-/** Known backend action alias labels. */
-export const ALIAS_LABELS: Record<string, string> = {
-  add_to_playlist: "Add to Playlist",
-  add_to_queue: "Add to Queue",
-  add_all_to_queue: "Add all to Queue",
-  play_all: "Play All",
-  remove_item: "Remove item",
-  delete_collection: "Delete collection",
-  create_collection: "Create collection",
-  edit: "Edit",
-  edit_name: "Edit Name & Details",
-};
+import { createLogger } from "@applicaster/zapp-react-native-utils/logger";
 
-/** Known backend action alias image assets. */
-export const ALIAS_ASSETS: Record<string, string> = {
-  add_to_playlist: ADD_TO_PLAYLIST_ICON,
-  add_to_queue: ADD_TO_PLAYLIST_ICON,
-  add_all_to_queue: ADD_TO_PLAYLIST_ICON,
-  play_all: ADD_TO_PLAYLIST_ICON,
-  remove_item: REMOVE_ICON,
-  delete_collection: REMOVE_ICON,
-  edit: EDIT_ICON,
-  edit_name: EDIT_ICON,
-};
+const logger = createLogger({
+  category: "zapp-react-native-utils:aliasPresentation",
+});
+
+const PLACEHOLDER_RED_BOX =
+  "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAJ0lEQVR4nO3NMQEAAAjDsIF/z2ACvlRAU5NMHuvPOQAAAAAAAMBdC/07Ai5sNw+CAAAAAElFTkSuQmCC";
 
-/** Per-app overrides for the maps above. */
+/** Per-app labels and icons, keyed by alias, that outrank the fallbacks. */
 export type AliasPresentation = {
   labels?: Record<string, string>;
   assets?: Record<string, string>;
@@ -56,7 +33,7 @@ function formatAliasLabel(
   alias: string,
   overrides?: AliasPresentation
 ): string {
-  const label = overrides?.labels?.[alias] ?? ALIAS_LABELS[alias];
+  const label = overrides?.labels?.[alias];
 
   if (label) {
     return label;
@@ -107,7 +84,7 @@ export function resolveButtonLabel(
   return "";
 }
 
-/** Icon to show for an entry action: explicit iconURL, else the alias default. */
+/** Icon to show for an entry action: explicit iconURL, matching alias asset or fallback to red box. */
 export function resolveButtonAsset(
   button: EntryAction["button"],
   overrides?: AliasPresentation
@@ -120,5 +97,12 @@ export function resolveButtonAsset(
     return undefined;
   }
 
-  return overrides?.assets?.[button.alias] ?? ALIAS_ASSETS[button.alias];
+  if (!overrides?.assets?.[button.alias]) {
+    logger.log_warning(
+      `Entry action alias '${button.alias}' was not resolved by any plugin feedDecorator or app override. Falling back to placeholder red box.`,
+      { data: { button } }
+    );
+  }
+
+  return overrides?.assets?.[button.alias] ?? PLACEHOLDER_RED_BOX;
 }

package/entryActions/buildEntryActions.ts

@@ -105,6 +105,7 @@ function createEntryAction(
             entry: invokedEntry,
             entryContext: invokedEntry,
             ...deps.actionContext,
+            ...(options.component ? { component: options.component } : {}),
           } as ActionExecutionContext);
         } catch (error) {
           log_error(

package/entryActions/index.ts

@@ -1,8 +1,6 @@
 export { buildEntryActions, isEntryAction } from "./buildEntryActions";
 
 export {
-  ALIAS_ASSETS,
-  ALIAS_LABELS,
   resolveButtonAsset,
   resolveButtonLabel,
   resolveExplicitLabel,

package/focusManager/FocusManager.ts

@@ -224,12 +224,38 @@ class FocusManager {
 
   unregisterFocusable(focusableId: string) {
     const node = this.tree.find(focusableId);
+    const parentNode = this.tree.findParent(focusableId);
 
     this.focusableComponents = this.focusableComponents.filter(
       (c) => c !== node?.component
     );
 
     this.tree.remove(focusableId);
+
+    if (this._focusedId === focusableId) {
+      this._focusedId = null;
+      this.retainFocus(parentNode);
+    }
+  }
+
+  // Empty groups drop their focusable list after the feed fails, which is
+  // after Layout's one-shot focus pass. Land on the nearest ancestor that is
+  // still mounted so key handlers keep a target.
+  private retainFocus(node: TreeNode | null) {
+    let current = node;
+
+    while (current) {
+      const ref = current.component;
+
+      if (ref?.current?.props?.id) {
+        this.setFocusLocal(ref);
+        ref.current.onFocus?.(ref.current, {}, undefined);
+
+        return;
+      }
+
+      current = current.parentId ? this.tree.find(current.parentId) : null;
+    }
   }
 
   private setNextFocus(

package/focusManager/__tests__/FocusManager.test.ts

@@ -231,6 +231,15 @@ describe("FocusManager", () => {
     ).toBeFalsy();
   });
 
+  it("moves focus to the mounted parent when the focused element unregisters", () => {
+    focusManager.setFocus("child1");
+
+    focusManager.unregisterFocusable("child1");
+
+    expect(focusManager.focusedId).toBe("group");
+    expect(focusManager.focused).toBe(group.current);
+  });
+
   it("focusManager registerFocusable should be defined", () => {
     expect(focusManager.registerFocusable).toBeDefined();
   });

package/localizationUtils/index.ts

@@ -28,17 +28,23 @@ const RTL_LOCALES = [
   "yi", // Yiddish
 ];
 
+// The strings for the UI language, else the first language present
+export const getLocalizedStrings = (
+  localizations = {},
+  languageCode = getUILanguage()
+) =>
+  localizations?.[languageCode] ||
+  Object.values(localizations).find(
+    (value) => typeof value === "object" && value !== null
+  ) ||
+  {};
+
 export function useLocalizedStrings({ localizations = {} }) {
   const languageCode = getUILanguage();
 
   // TODO: probably we can call getLocalizations here from localizationsHelper.js
   const result = useMemo(
-    () =>
-      localizations?.[languageCode] ||
-      Object.values(localizations).find(
-        (value) => typeof value === "object" && value !== null
-      ) ||
-      {},
+    () => getLocalizedStrings(localizations, languageCode),
     [languageCode, localizations]
   );
 

package/logger/__tests__/xrayToolbox.test.ts

@@ -0,0 +1,69 @@
+const xray = require("@applicaster/quick-brick-xray");
+
+const toolbox = { name: "test", description: "", tools: [] };
+
+const load = (): typeof import("../xrayToolbox") => {
+  let module;
+
+  jest.isolateModules(() => {
+    module = require("../xrayToolbox");
+  });
+
+  return module;
+};
+
+describe("registerXrayToolbox", () => {
+  afterEach(() => {
+    delete xray.registerReactToolbox;
+  });
+
+  it("registers once per name", async () => {
+    xray.registerReactToolbox = jest.fn().mockResolvedValue(undefined);
+    const { registerXrayToolbox } = load();
+
+    await expect(registerXrayToolbox(toolbox)).resolves.toBe(true);
+    await expect(registerXrayToolbox(toolbox)).resolves.toBe(true);
+
+    expect(xray.registerReactToolbox).toHaveBeenCalledTimes(1);
+  });
+
+  it("resolves false without a toolbox API", async () => {
+    await expect(load().registerXrayToolbox(toolbox)).resolves.toBe(false);
+  });
+
+  it("keeps a failed registration instead of retrying it", async () => {
+    xray.registerReactToolbox = jest
+      .fn()
+      .mockRejectedValue(new Error("XRayToolboxBridge is not available"));
+
+    const { registerXrayToolbox } = load();
+
+    await expect(registerXrayToolbox(toolbox)).resolves.toBe(false);
+    await expect(registerXrayToolbox(toolbox)).resolves.toBe(false);
+
+    expect(xray.registerReactToolbox).toHaveBeenCalledTimes(1);
+  });
+
+  it("registers new tools under the same name again (Fast Refresh)", async () => {
+    xray.registerReactToolbox = jest.fn().mockResolvedValue(undefined);
+    const { registerXrayToolbox } = load();
+
+    await registerXrayToolbox(toolbox);
+    await registerXrayToolbox({ ...toolbox, tools: [] });
+
+    expect(xray.registerReactToolbox).toHaveBeenCalledTimes(2);
+  });
+
+  it("stops trying every toolbox once the bridge is missing", async () => {
+    xray.registerReactToolbox = jest.fn().mockRejectedValue(new Error("no"));
+    const { registerXrayToolbox } = load();
+
+    await registerXrayToolbox(toolbox);
+
+    await expect(
+      registerXrayToolbox({ ...toolbox, name: "other" })
+    ).resolves.toBe(false);
+
+    expect(xray.registerReactToolbox).toHaveBeenCalledTimes(1);
+  });
+});

package/logger/xrayToolbox.ts

@@ -0,0 +1,67 @@
+import { getXray } from ".";
+
+/** One tool of an X-Ray React toolbox: an agent calls it by name with JSON arguments. */
+export type XrayToolSpec = {
+  name: string;
+  description: string;
+  parameters?: Array<{
+    name: string;
+    type: "number" | "string";
+    description: string;
+  }>;
+  handler: (args: Record<string, unknown>) => unknown;
+};
+
+export type XrayToolbox = {
+  name: string;
+  description: string;
+  tools: XrayToolSpec[];
+};
+
+type RegisterReactToolbox = (toolbox: XrayToolbox) => Promise<void>;
+
+const registered = new Map<
+  string,
+  { tools: XrayToolSpec[]; registration: Promise<boolean> }
+>();
+
+/** Set once a registration fails: the build has no X-Ray bridge, which cannot appear later. */
+let bridgeMissing = false;
+
+/**
+ * Registers an X-Ray React toolbox and resolves whether it is registered. The same tools are
+ * registered once; new tools under the same name (Fast Refresh re-ran the module) replace them.
+ * A build without the X-Ray native bridge (release builds) rejects the first attempt and every
+ * later call resolves false at once, so callers on hot paths pay for one attempt only.
+ */
+export const registerXrayToolbox = (toolbox: XrayToolbox): Promise<boolean> => {
+  const cached = registered.get(toolbox.name);
+
+  if (cached?.tools === toolbox.tools) return cached.registration;
+
+  if (bridgeMissing) return Promise.resolve(false);
+
+  const register = (
+    getXray() as
+      | { registerReactToolbox?: RegisterReactToolbox }
+      | null
+      | undefined
+  )?.registerReactToolbox;
+
+  const registration = register
+    ? register(toolbox).then(
+        () => true,
+        () => {
+          bridgeMissing = true;
+
+          return false;
+        }
+      )
+    : Promise.resolve(false);
+
+  if (!register) bridgeMissing = true;
+
+  registered.set(toolbox.name, { tools: toolbox.tools, registration });
+
+  return registration;
+};

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/generalContent.js

@@ -12,6 +12,12 @@ const generalContent = () => ({
         label: "Navigation Bar",
         placeholder: "Choose Nav Bar",
       },
+      {
+        key: "hide_menu",
+        type: "switch",
+        label: "Hide Menu",
+        initial_value: false,
+      },
     ],
   },
   styles: {

package/manifestUtils/defaultManifestConfigurations/player.js

@@ -830,6 +830,14 @@ function getPlayerConfiguration({ platform, version }) {
         type: "switch",
         label_tooltip:
           "Enable this option to have a floating video player when the app is in the background.",
+      },
+      {
+        key: "vertical_video_player",
+        label: "Vertical video mode",
+        initial_value: false,
+        type: "switch",
+        label_tooltip:
+          "Enable this option to use the vertical video player layout.",
       }
     );
 

package/manifestUtils/keys.js

@@ -412,6 +412,12 @@ const mobileActionButtonContainerFields = (positionOptions) => [
     type: ZAPPIFEST_FIELDS.switch,
     suffix: "buttons enabled",
   },
+  {
+    type: ZAPPIFEST_FIELDS.switch,
+    suffix: "cell navigation enabled",
+    label_tooltip:
+      "Controls whether tapping on the cell (outside the buttons) triggers its navigation behavior. When disabled, only the configured buttons are interactive. Useful for Home screens (tap anywhere to open) vs. Details screens (only buttons should work).",
+  },
   {
     type: ZAPPIFEST_FIELDS.select,
     suffix: "position",
@@ -472,7 +478,6 @@ const MOBILE_ACTION_BUTTON_FIELDS = [
     suffix: "assign action",
     options: [
       { text: "primary navigation", value: "navigation_action" },
-      { text: "secondary navigation", value: "secondary_navigation" },
       { text: "favorite", value: "local_storage_favourites_action" },
       { text: "more", value: "open-modal-bottom-sheet-cell-action" },
       { text: "add to calendar", value: "add_to_calendar_action" },

package/manifestUtils/mobileAction/container/__tests__/mobileActionButtonsContainer.test.js

@@ -7,6 +7,7 @@ describe("mobileActionButtonsContainer", () => {
       description: "container",
       defaults: {
         buttonsEnabled: false,
+        cellNavigationEnabled: false,
         position: ["over_image", "text_label_1", "text_label_2"],
         align: "left",
         overImagePosition: "bottom_left",
@@ -31,6 +32,26 @@ describe("mobileActionButtonsContainer", () => {
     expect(enabledField).toBeTruthy();
     expect(enabledField.type).toBe("switch");
 
+    const cellNavigationField = result.fields.find(
+      (field) =>
+        field.key === "mobile_buttons_container_cell_navigation_enabled"
+    );
+
+    expect(cellNavigationField).toMatchObject({
+      type: "switch",
+      label: "Cell navigation enabled",
+      initial_value: false,
+      label_tooltip: expect.stringContaining(
+        "Controls whether tapping on the cell"
+      ),
+      conditional_fields: [
+        {
+          key: "styles/mobile_buttons_container_buttons_enabled",
+          condition_value: true,
+        },
+      ],
+    });
+
     const positionField = result.fields.find(
       (field) => field.key === "mobile_buttons_container_position"
     );

package/manifestUtils/mobileAction/groups/__tests__/buildMobileActionButtonGroups.test.js

@@ -67,7 +67,7 @@ describe("buildMobileActionButtonGroups", () => {
     );
 
     expect(button2EnabledField.initial_value).toBe(false);
-    expect(button2AssignActionField.initial_value).toBe("secondary_navigation");
+    expect(button2AssignActionField.initial_value).toBe("trailer_action");
 
     const button3Fields = groups[3].fields;
 

package/manifestUtils/mobileAction/groups/defaults.js

@@ -1,5 +1,6 @@
 const DEFAULT_MOBILE_ACTION_BUTTONS_CONTAINER_DEFAULTS = {
   buttonsEnabled: false,
+  cellNavigationEnabled: false,
 
   align: "left",
   overImagePosition: "bottom_left",
@@ -63,7 +64,7 @@ const DEFAULT_MOBILE_ACTION_BUTTON_PRESETS = {
   },
   2: {
     buttonEnabled: false,
-    assignAction: "secondary_navigation",
+    assignAction: "trailer_action",
   },
   3: {
     buttonEnabled: false,