@applicaster/zapp-react-native-utils 16.0.0-rc.12 → 16.0.0-rc.121

package/entryActions/buildEntryActions.ts

@@ -0,0 +1,167 @@
+/// <reference types="@applicaster/applicaster-types" />
+import { createLogger } from "../logger";
+import { ActionExecutionContext } from "../actionsExecutor/types";
+import { RegisteredAction } from "../uiActionsRegistrator";
+
+import {
+  resolveButtonAsset,
+  resolveButtonLabel,
+  resolveExplicitLabel,
+} from "./aliasPresentation";
+import { EntryAction, EntryActionDeps } from "./types";
+
+const { log_info, log_warning, log_error } = createLogger({
+  subsystem: "EntryActions",
+  category: "EntryAction",
+});
+
+const ENTRY_ACTION_IDENTIFIER_PREFIX = "entry_action";
+
+/** True for actions inflated from `entry.extensions.entry_action`. */
+export function isEntryAction(item: RegisteredAction): boolean {
+  return item?.source === "entry";
+}
+
+function isValidEntryAction(value: unknown): value is EntryAction {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+
+  const { button, actions } = value as EntryAction;
+
+  return (
+    (typeof button?.title === "string" ||
+      typeof button?.label === "string" ||
+      typeof button?.alias === "string") &&
+    Array.isArray(actions)
+  );
+}
+
+function createEntryAction(
+  entryAction: EntryAction,
+  index: number,
+  entry: ZappEntry | ZappFeed,
+  deps: EntryActionDeps
+): RegisteredAction {
+  const { button, actions, dismiss_on_action } = entryAction;
+
+  const identifier = `${ENTRY_ACTION_IDENTIFIER_PREFIX}_${index}`;
+  const primaryAction = actions.length > 0 ? actions[0] : null;
+
+  const actionState = primaryAction
+    ? deps.actionExecutor?.getActionState?.(primaryAction.type, entry)
+    : null;
+
+  // An explicit title/label outranks the executor's action state; the
+  // alias-derived defaults only fill in when neither produced anything.
+  const label: CellActionEntryState["label"] =
+    resolveExplicitLabel(button) ||
+    actionState?.label ||
+    resolveButtonLabel(button, deps.aliasPresentation);
+
+  const asset: CellActionEntryState["asset"] =
+    button?.iconURL ||
+    actionState?.asset ||
+    resolveButtonAsset(button, deps.aliasPresentation);
+
+  const initialState = { state: 0, label, asset };
+
+  return {
+    identifier,
+    source: "entry",
+    action: {
+      initialEntryState: () => initialState,
+      invokeAction: async (
+        invokedEntry: ZappEntry,
+        options: InvokeArgsOptions = {}
+      ) => {
+        if (dismiss_on_action === true) {
+          options.dismiss?.();
+        }
+
+        log_info(
+          `invokeAction: entry action "${identifier}" triggered for entry "${invokedEntry?.id}"`,
+          { identifier, entryId: invokedEntry?.id, actionCount: actions.length }
+        );
+
+        // Both of these leave the user with a button that does nothing when
+        // tapped, and neither throws, so they would otherwise be invisible.
+        if (actions.length === 0) {
+          log_warning(
+            `invokeAction: entry action "${identifier}" on entry "${invokedEntry?.id}" declares no actions - the tap does nothing`,
+            { identifier, entryId: invokedEntry?.id }
+          );
+        }
+
+        if (typeof deps.actionExecutor?.handleActions !== "function") {
+          log_warning(
+            `invokeAction: no action executor available for entry action "${identifier}" - the tap does nothing`,
+            { identifier, entryId: invokedEntry?.id }
+          );
+        }
+
+        try {
+          await deps.actionExecutor?.handleActions(actions, {
+            entry: invokedEntry,
+            entryContext: invokedEntry,
+            ...deps.actionContext,
+            ...(options.component ? { component: options.component } : {}),
+          } as ActionExecutionContext);
+        } catch (error) {
+          log_error(
+            `invokeAction: entry action "${identifier}" failed for entry "${invokedEntry?.id}"`,
+            {
+              identifier,
+              entryId: invokedEntry?.id,
+              // Types only - the action payloads are backend supplied and may
+              // carry user data.
+              actionTypes: actions.map((action) => action?.type),
+              error,
+            }
+          );
+        }
+      },
+    },
+  };
+}
+
+/**
+ * Builds the list of actions declared on an entry via
+ * `entry.extensions.entry_action`.
+ */
+export function buildEntryActions(
+  entry: ZappEntry | ZappFeed,
+  deps: EntryActionDeps
+): RegisteredAction[] {
+  const entryId = (entry as ZappEntry)?.id;
+  const raw = (entry as any)?.extensions?.entry_action;
+
+  // Most entries simply declare no actions. This provider is resolved for
+  // every entry on every render, so saying so would drown everything else.
+  if (raw === undefined || raw === null) {
+    return [];
+  }
+
+  if (!Array.isArray(raw)) {
+    log_warning(
+      `buildEntryActions: entry "${entryId}" has extensions.entry_action of type ${typeof raw} instead of an array - no entry actions will be shown`,
+      { entryId, receivedType: typeof raw }
+    );
+
+    return [];
+  }
+
+  const valid = raw.filter(isValidEntryAction);
+  const invalid = raw.length - valid.length;
+
+  if (invalid > 0) {
+    log_warning(
+      `buildEntryActions: ${invalid} invalid entry action(s) skipped for entry "${entryId}"`,
+      { entryId, total: raw.length, invalid }
+    );
+  }
+
+  return valid.map((entryAction, index) =>
+    createEntryAction(entryAction, index, entry, deps)
+  );
+}

package/entryActions/index.ts

@@ -0,0 +1,15 @@
+export { buildEntryActions, isEntryAction } from "./buildEntryActions";
+
+export {
+  resolveButtonAsset,
+  resolveButtonLabel,
+  resolveExplicitLabel,
+} from "./aliasPresentation";
+
+export type {
+  EntryAction,
+  EntryActionDeps,
+  EntryActionExecutionContext,
+} from "./types";
+
+export type { AliasPresentation } from "./aliasPresentation";

package/entryActions/types.ts

@@ -0,0 +1,39 @@
+/// <reference types="@applicaster/applicaster-types" />
+import type { ActionExecutorContextType } from "../actionsExecutor/ActionExecutorContext";
+import type { AliasPresentation } from "./aliasPresentation";
+
+/**
+ * A single action declared by the backend on an entry, under
+ * `entry.extensions.entry_action`.
+ */
+export type EntryAction = {
+  button: {
+    title?: string;
+    label?: string;
+    alias?: string;
+    iconURL?: string;
+  };
+  actions: ZappActionType[];
+  dismiss_on_action?: boolean;
+};
+
+/**
+ * Everything `buildEntryActions` needs from the surrounding React tree in order
+ * to execute an entry action. Supplied lazily so the registered provider always
+ * reads the freshest screen context.
+ */
+export type EntryActionDeps = {
+  actionExecutor: ActionExecutorContextType;
+  actionContext: EntryActionExecutionContext;
+  /** App-supplied labels/icons for backend aliases; defaults are used without it. */
+  aliasPresentation?: AliasPresentation;
+};
+
+/** The screen the action is executed against, spread into the execution context. */
+export type EntryActionExecutionContext = {
+  screenData?: unknown;
+  screenState?: unknown;
+  screenRoute?: string;
+  screenStateStore?: unknown;
+  screenEntry?: unknown;
+};

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

@@ -0,0 +1,158 @@
+const { player } = require("../defaultManifestConfigurations/player");
+
+const manifestFor = (platform) => player({ platform, version: "0.0.0" });
+
+const findGroup = (manifest, label) =>
+  manifest.styles.fields.find((group) => group.group && group.label === label);
+
+const findFieldInGroup = (manifest, label, key) =>
+  findGroup(manifest, label)?.fields?.find((field) => field.key === key);
+
+const findLocalization = (manifest, key) =>
+  manifest.localizations.fields.find((field) => field.key === key);
+
+describe("player manifest — audio playlist controls", () => {
+  const manifest = manifestFor("ios_for_quickbrick");
+
+  describe("Player Controls Layout", () => {
+    const field = () =>
+      findFieldInGroup(manifest, "Audio Player", "player_controls_layout");
+
+    it("is declared in the Audio Player group", () => {
+      expect(field()).toBeDefined();
+    });
+
+    it("is a select defaulting to the existing controls", () => {
+      expect(field().type).toBe("select");
+      expect(field().initial_value).toBe("playback_speed_and_sleep_timer");
+    });
+
+    it("only shows when the audio player layout is in use", () => {
+      expect(field()).toMatchObject({
+        rules: "conditional",
+        conditional_fields: [
+          { key: "styles/full_screen_audio_player", condition_value: true },
+        ],
+      });
+    });
+
+    it("offers exactly the two documented options", () => {
+      expect(field().options).toEqual([
+        {
+          text: "Playback Speed & Sleep Timer (Default)",
+          value: "playback_speed_and_sleep_timer",
+        },
+        {
+          text: "Playlist Controls (Previous & Next)",
+          value: "playlist_controls",
+        },
+      ]);
+    });
+  });
+
+  describe("control icons", () => {
+    it.each(["previous_track", "next_track"])(
+      "declares %s as an uploader",
+      (key) => {
+        expect(findFieldInGroup(manifest, "Assets", key)).toMatchObject({
+          key,
+          type: "uploader",
+        });
+      }
+    );
+
+    it.each(["previous_track", "next_track"])(
+      "only shows %s when the playlist controls layout is selected",
+      (key) => {
+        expect(findFieldInGroup(manifest, "Assets", key)).toMatchObject({
+          rules: "conditional",
+          conditional_fields: [
+            {
+              key: "styles/player_controls_layout",
+              condition_value: "playlist_controls",
+            },
+          ],
+        });
+      }
+    );
+
+    it.each([
+      "speed_0_8",
+      "speed_1",
+      "speed_1_2",
+      "speed_1_5",
+      "speed_2",
+      "sleep_timer",
+      "sleep_timer_active",
+    ])(
+      "only shows %s when the playback speed and sleep timer layout is selected",
+      (key) => {
+        expect(findFieldInGroup(manifest, "Assets", key)).toMatchObject({
+          rules: "conditional",
+          conditional_fields: [
+            {
+              key: "styles/player_controls_layout",
+              condition_value: "playback_speed_and_sleep_timer",
+            },
+          ],
+        });
+      }
+    );
+  });
+
+  describe("accessibility strings", () => {
+    it.each([
+      "accessibility_previous_track_label",
+      "accessibility_previous_track_hint",
+      "accessibility_next_track_label",
+      "accessibility_next_track_hint",
+    ])("declares %s with a default", (key) => {
+      expect(findLocalization(manifest, key)).toMatchObject({
+        type: "text_input",
+      });
+
+      expect(findLocalization(manifest, key).initial_value).toBeTruthy();
+    });
+  });
+
+  describe("tv platforms", () => {
+    // The audio player layout is mobile only, so nothing this feature adds —
+    // including its screen reader strings — belongs in a tv manifest.
+    it.each(["tvos_for_quickbrick", "android_tv_for_quickbrick", "lg_tv"])(
+      "adds no audio controls layout field on %s",
+      (platform) => {
+        expect(
+          findFieldInGroup(
+            manifestFor(platform),
+            "Audio Player",
+            "player_controls_layout"
+          )
+        ).toBeUndefined();
+      }
+    );
+
+    it.each([
+      "accessibility_previous_track_label",
+      "accessibility_previous_track_hint",
+      "accessibility_next_track_label",
+      "accessibility_next_track_hint",
+    ])("does not declare %s on tv", (key) => {
+      expect(
+        findLocalization(manifestFor("tvos_for_quickbrick"), key)
+      ).toBeUndefined();
+    });
+
+    it("still declares the tv-only localizations", () => {
+      expect(
+        findLocalization(
+          manifestFor("tvos_for_quickbrick"),
+          "back_to_live_label"
+        )
+      ).toBeDefined();
+
+      expect(
+        findLocalization(manifestFor("tvos_for_quickbrick"), "start_over_label")
+      ).toBeDefined();
+    });
+  });
+});

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,19 +152,29 @@ 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),
         };
 
         if (conditions) {
           generatedField.conditional_fields = conditions.map((condition) => {
+            if (condition.section === null) {
+              return { key: condition.key, condition_value: condition.value };
+            }
+
             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,
             };
           });
+
+          generatedField.rules = "all_conditions";
         }
 
         return generatedField;