@applicaster/zapp-react-native-ui-components 16.0.0-rc.8 → 16.0.0-rc.81

package/Components/GeneralContentScreen/hookAdapter/runInBackground.ts

@@ -0,0 +1,48 @@
+import { shouldSkipHook } from "./validationHelper";
+import { requestToSkipHook } from "./networkService";
+import { log_debug, log_error } from "./logger";
+
+/**
+ * Headless pre-hook for the General Content Screen. `configuration` is the
+ * Hook object with the screen merged in; skip-hook fields live under `rules`.
+ */
+export const runInBackground = async (
+  item,
+  callback,
+  configuration,
+  presentUI
+) => {
+  try {
+    const skipHookIfKeysExist = configuration?.rules?.skip_hook_storage_key;
+
+    if (skipHookIfKeysExist) {
+      const shouldSkip = await shouldSkipHook(skipHookIfKeysExist);
+
+      if (shouldSkip) {
+        log_debug(
+          `runInBackground: Storage key found: ${skipHookIfKeysExist}. Skipping hook.`
+        );
+
+        return callback({ success: true, error: null, payload: item });
+      }
+    }
+
+    const skipHookEndpoint = configuration?.rules?.skip_hook_endpoint;
+
+    if (skipHookEndpoint?.source) {
+      const success = await requestToSkipHook(skipHookEndpoint, item);
+
+      if (success) {
+        log_debug(
+          "runInBackground: Network call forced to finish hook. Skipping hook."
+        );
+
+        return callback({ success: true, error: null, payload: item });
+      }
+    }
+  } catch (error) {
+    log_error(`runInBackground: Error: ${error.message}`);
+  }
+
+  return presentUI();
+};

package/Components/GeneralContentScreen/hookAdapter/skipExpression.ts

@@ -0,0 +1,252 @@
+import { getNamespaceAndKey } from "@applicaster/zapp-react-native-utils/appUtils/contextKeysManager/utils";
+import { log_error, log_info } from "./logger";
+
+/**
+ * Boolean expressions over storage keys, used by the General Content Screen
+ * hook adapter to decide whether a hook should be skipped.
+ *
+ * The `skip_hook_storage_key` rule normally holds a comma-separated list of
+ * keys, meaning "skip when any of these exists". That covers presence only, so
+ * a condition such as "the user is logged in but has not picked a profile yet"
+ * cannot be expressed. To keep the manifest field untouched, an expression may
+ * be packed into the very same string as JSON: anything starting with `{` is
+ * parsed as an expression, anything else keeps the legacy behaviour.
+ *
+ * The expression evaluates to the SKIP condition — true means "do not present
+ * the hook" — matching the name of the rule it is configured in.
+ *
+ * Keys are written as `namespace.key` and resolved exactly like the legacy
+ * format: everything before the LAST dot is the namespace, so
+ * `com.applicaster.feature.someKey` reads `someKey` from `com.applicaster.feature`.
+ * A key with no dot falls back to the default namespace.
+ *
+ * Operators:
+ *
+ *   "ns.key"                              shorthand for { "exists": "ns.key" }
+ *   { "exists":  "ns.key" }               the key holds a truthy value
+ *   { "missing": "ns.key" }               the key holds no value
+ *   { "equals": { "key": "ns.key", "value": "kids" } }
+ *   { "all": [ …operands ] }              AND, short-circuits on the first false
+ *   { "any": [ …operands ] }              OR, short-circuits on the first true
+ *   { "not": operand }                    negation
+ *
+ * @example Show the profile selector to a logged-in user who has no profile yet
+ * ```json
+ * {
+ *   "any": [
+ *     { "missing": "quick-brick-login-flow.access_token" },
+ *     { "exists": "user_account.profile" }
+ *   ]
+ * }
+ * ```
+ * As it is stored in the `skip_hook_storage_key` string field:
+ * ```json
+ * "skip_hook_storage_key": "{\"any\":[{\"missing\":\"quick-brick-login-flow.access_token\"},{\"exists\":\"user_account.profile\"}]}"
+ * ```
+ *
+ * @example Skip an onboarding hook once it has been seen on a subscribed device
+ * ```json
+ * {
+ *   "all": [
+ *     "onboarding.completed",
+ *     { "equals": { "key": "user_account.plan", "value": "premium" } }
+ *   ]
+ * }
+ * ```
+ *
+ * Every failure mode — malformed JSON, an unknown operator, an operand of the
+ * wrong type, a storage read that throws — evaluates to false, so a broken
+ * configuration presents the hook rather than silently hiding a screen.
+ */
+export type SkipExpression =
+  | string
+  | { exists: string }
+  | { missing: string }
+  | { equals: { key: string; value: string } }
+  | { all: SkipExpression[] }
+  | { any: SkipExpression[] }
+  | { not: SkipExpression };
+
+/** Reads a single storage key. Injected so evaluation stays storage-agnostic. */
+export type ReadKey = (key: string, namespace?: string) => Promise<unknown>;
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const hasOperator = (node: Record<string, unknown>, operator: string) =>
+  Object.prototype.hasOwnProperty.call(node, operator);
+
+/**
+ * Whether a `skip_hook_storage_key` value is meant as an expression at all.
+ *
+ * Deliberately a shape check rather than a successful parse: a value that opens
+ * with `{` was written as an expression even when its JSON is broken, and must
+ * never fall back to being read as a list of storage keys.
+ */
+export const looksLikeSkipExpression = (input: unknown): boolean =>
+  isPlainObject(input) ||
+  (typeof input === "string" && input.trim().startsWith("{"));
+
+/**
+ * Reads a `skip_hook_storage_key` value as an expression, or returns null when
+ * it is not one — an empty value, a legacy comma-separated key list, or an
+ * expression whose JSON is malformed.
+ */
+export const parseSkipExpression = (input: unknown): SkipExpression | null => {
+  if (isPlainObject(input)) {
+    return input as SkipExpression;
+  }
+
+  if (!looksLikeSkipExpression(input)) {
+    return null;
+  }
+
+  const trimmed = (input as string).trim();
+
+  try {
+    const parsed = JSON.parse(trimmed);
+
+    if (!isPlainObject(parsed)) {
+      log_error(
+        `parseSkipExpression: Expression must be an object, got: ${trimmed}`
+      );
+
+      return null;
+    }
+
+    return parsed as SkipExpression;
+  } catch (error) {
+    log_error(
+      `parseSkipExpression: Malformed expression: ${trimmed}. Error: ${error.message}`,
+      { error }
+    );
+
+    return null;
+  }
+};
+
+const keyIsTruthy = async (key: string, readKey: ReadKey): Promise<boolean> => {
+  const { namespace, key: name } = getNamespaceAndKey(key);
+
+  return Boolean(await readKey(name, namespace));
+};
+
+const evaluateEquals = async (
+  operand: { key: string; value: string },
+  readKey: ReadKey
+): Promise<boolean> => {
+  const { namespace, key: name } = getNamespaceAndKey(operand.key);
+  const value = await readKey(name, namespace);
+
+  return value == null ? false : String(value) === String(operand.value);
+};
+
+const evaluateNode = async (
+  node: SkipExpression,
+  readKey: ReadKey
+): Promise<boolean> => {
+  try {
+    if (typeof node === "string") {
+      return await keyIsTruthy(node, readKey);
+    }
+
+    if (!isPlainObject(node)) {
+      log_error(
+        `evaluateSkipExpression: Not an operator: ${JSON.stringify(node)}`
+      );
+
+      return false;
+    }
+
+    // The node came from configuration JSON, so every operand is read back as
+    // unknown and type-checked here rather than trusted from the union.
+    const operator = node as Record<string, unknown>;
+
+    if (
+      hasOperator(operator, "exists") &&
+      typeof operator.exists === "string"
+    ) {
+      return await keyIsTruthy(operator.exists, readKey);
+    }
+
+    if (
+      hasOperator(operator, "missing") &&
+      typeof operator.missing === "string"
+    ) {
+      return !(await keyIsTruthy(operator.missing, readKey));
+    }
+
+    if (hasOperator(operator, "equals") && isPlainObject(operator.equals)) {
+      return await evaluateEquals(
+        operator.equals as { key: string; value: string },
+        readKey
+      );
+    }
+
+    if (hasOperator(operator, "all") && Array.isArray(operator.all)) {
+      for (const operand of operator.all) {
+        if (!(await evaluateNode(operand, readKey))) {
+          return false;
+        }
+      }
+
+      // An empty operand list carries no condition, so it stays false rather
+      // than skipping the hook on the vacuous truth of an empty AND.
+      return operator.all.length > 0;
+    }
+
+    if (hasOperator(operator, "any") && Array.isArray(operator.any)) {
+      for (const operand of operator.any) {
+        if (await evaluateNode(operand, readKey)) {
+          return true;
+        }
+      }
+
+      return false;
+    }
+
+    if (hasOperator(operator, "not")) {
+      return !(await evaluateNode(operator.not as SkipExpression, readKey));
+    }
+
+    log_error(
+      `evaluateSkipExpression: Unknown or malformed operator: ${JSON.stringify(
+        node
+      )}`
+    );
+
+    return false;
+  } catch (error) {
+    log_error(
+      `evaluateSkipExpression: Error: ${error.message} evaluating: ${JSON.stringify(
+        node
+      )}`,
+      { error }
+    );
+
+    return false;
+  }
+};
+
+/**
+ * Evaluates a parsed expression to the skip decision. A null expression — the
+ * field held no expression — is not a condition, so nothing is skipped.
+ */
+export const evaluateSkipExpression = async (
+  expression: SkipExpression | null,
+  readKey: ReadKey
+): Promise<boolean> => {
+  if (!expression) {
+    return false;
+  }
+
+  const shouldSkip = await evaluateNode(expression, readKey);
+
+  log_info(
+    `evaluateSkipExpression: Expression evaluated to ${shouldSkip}, ${
+      shouldSkip ? "skipping hook" : "proceeding with hook"
+    }`
+  );
+
+  return shouldSkip;
+};

package/Components/GeneralContentScreen/hookAdapter/validationHelper.ts

@@ -0,0 +1,90 @@
+import { getNamespaceAndKey } from "@applicaster/zapp-react-native-utils/appUtils/contextKeysManager/utils";
+import { localStorage } from "@applicaster/zapp-react-native-bridge/ZappStorage/LocalStorage";
+import { sessionStorage } from "@applicaster/zapp-react-native-bridge/ZappStorage/SessionStorage";
+import {
+  looksLikeSkipExpression,
+  parseSkipExpression,
+  evaluateSkipExpression,
+} from "./skipExpression";
+import { log_error, log_info } from "./logger";
+
+type ParseKey = { key: string; namespace?: string };
+
+export function parseKeyEntries(input: string): ParseKey[] {
+  return input.split(",").flatMap((item) => {
+    const trimmed = item.trim();
+
+    return trimmed ? getNamespaceAndKey(trimmed) : [];
+  });
+}
+
+export const getKeyToSkipHook = async (key: string, namespace?: string) => {
+  const value = await sessionStorage.getItem(key, namespace);
+
+  if (value) {
+    return value;
+  }
+
+  return await localStorage.getItem(key, namespace);
+};
+
+/**
+ * Decides whether the hook should be skipped, from the `skip_hook_storage_key`
+ * rule. The value is either a comma-separated key list — skip when ANY of them
+ * exists — or, packed into the same string, a JSON boolean expression over
+ * storage keys. See `skipExpression.ts` for the expression format.
+ */
+export const shouldSkipHook = async (
+  skipHookIfKeysExist?: string
+): Promise<boolean> => {
+  if (!skipHookIfKeysExist?.trim()) {
+    log_info("shouldSkipHook: No skipping condition provided");
+
+    return false;
+  }
+
+  if (looksLikeSkipExpression(skipHookIfKeysExist)) {
+    return await evaluateSkipExpression(
+      parseSkipExpression(skipHookIfKeysExist),
+      getKeyToSkipHook
+    );
+  }
+
+  const keyEntries = parseKeyEntries(skipHookIfKeysExist);
+
+  if (keyEntries.length === 0) {
+    log_info("shouldSkipHook: No valid keys provided");
+
+    return false;
+  }
+
+  for (const entry of keyEntries) {
+    try {
+      const value = await getKeyToSkipHook(entry.key, entry.namespace);
+
+      if (value) {
+        log_info(
+          `shouldSkipHook: Hook will be skipped due to: ${
+            entry.namespace ?? ""
+          } ${entry.key}. Finishing hook flow`
+        );
+
+        return true;
+      }
+    } catch (error) {
+      log_error(
+        `shouldSkipHook: Error: ${error.message} checking key: ${
+          entry.namespace ?? ""
+        } ${entry.key}`,
+        { error }
+      );
+    }
+  }
+
+  log_info(
+    // eslint-disable-next-line max-len
+    "shouldSkipHook: No skipping condition met, none of the provided keys found in storage, proceeding with hook"
+  );
+
+  return false;
+};

package/Components/GeneralContentScreen/hookFocus/index.tsx

@@ -0,0 +1,13 @@
+import * as React from "react";
+
+type Props = {
+  children: React.ReactElement;
+};
+
+/**
+ * On native platforms the river `ComponentsMap` registers its own initial focus,
+ * so a hook-presented general content screen needs no extra focus wrapper here.
+ * The web counterpart (`index.web.tsx`) recreates the content focus group that
+ * the `River` wrapper would normally provide.
+ */
+export const HookContentFocusGroup = ({ children }: Props) => <>{children}</>;

package/Components/GeneralContentScreen/hookFocus/index.web.tsx

@@ -0,0 +1,69 @@
+import * as React from "react";
+import { StyleSheet } from "react-native";
+import { shallow } from "zustand/shallow";
+
+import { FocusableGroup } from "../../FocusableGroup";
+import {
+  useContentId,
+  useNavbarId,
+  usePathname,
+} from "@applicaster/zapp-react-native-utils/reactHooks/navigation";
+import { useZappHookModalStore } from "../../../Contexts/ZappHookModalContext";
+
+import { useInitialFocus } from "../../Screen/TV/hooks";
+
+const styles = StyleSheet.create({
+  container: { flex: 1 },
+});
+
+type Props = {
+  children: React.ReactElement;
+};
+
+/**
+ * A general content screen presented as a full-screen hook is rendered straight
+ * through `ComponentsMap`, bypassing the web `River` wrapper. That wrapper is what
+ * normally creates the `quick-brick-content` FocusableGroup (with `preferredFocus`)
+ * the focus manager relies on and what lets initial focus land on the content.
+ *
+ * Without it the hook screen renders but nothing is focusable on web TV. This
+ * recreates that content group and triggers initial focus, mirroring `River`.
+ */
+const FocusedHookContent = ({ children }: Props) => {
+  const contentId = useContentId();
+  const navbarId = useNavbarId();
+  const pathname = usePathname();
+
+  useInitialFocus();
+
+  return (
+    <FocusableGroup
+      id={contentId}
+      // Nest under the hook-modal route so the focus manager treats this as the
+      // active screen's content node; `useInitialFocus` targets the same route.
+      groupId={pathname}
+      nextFocusUp={navbarId}
+      preferredFocus
+      shouldUsePreferredFocus
+      style={styles.container}
+    >
+      {React.cloneElement(children, { groupId: contentId })}
+    </FocusableGroup>
+  );
+};
+
+export const HookContentFocusGroup = ({ children }: Props) => {
+  const isRunningInBackground = useZappHookModalStore(
+    (state) => state.isRunningInBackground,
+    shallow
+  );
+
+  // A hook presented full screen (either as a `/hooks/<id>` screen or a
+  // full-screen modal) needs the content focus group. Only background runs,
+  // which render invisibly, must be left alone so they don't steal focus.
+  if (isRunningInBackground) {
+    return <>{children}</>;
+  }
+
+  return <FocusedHookContent>{children}</FocusedHookContent>;
+};

package/Components/GeneralContentScreen/index.ts

@@ -1 +1,3 @@
 export { GeneralContentScreen } from "./GeneralContentScreen";
+
+export { GeneralContentScreenHookAdapter } from "./GeneralContentScreenHookAdapter";

package/Components/Layout/FullWidthRow.tsx

@@ -0,0 +1,38 @@
+import * as React from "react";
+import { StyleSheet, View } from "react-native";
+
+const styles = StyleSheet.create({
+  row: { flexDirection: "row" },
+  basis: {
+    maxWidth: "100%",
+    flexBasis: "100%",
+  },
+});
+
+type Props = {
+  children: React.ReactNode;
+};
+
+/**
+ * Constrains its child to exactly the available parent width.
+ *
+ * UI components such as Hero and List render their items inside a parent
+ * `ScrollView` (e.g. when wrapped by tabs). A child placed directly in a
+ * scroll container can size itself to its own content rather than to the
+ * viewport, which causes items to be measured at a stale width and resize
+ * unexpectedly after layout changes such as device rotation.
+ *
+ * Wrapping the content in a `flexDirection: "row"` parent with a
+ * `flexBasis: "100%"` / `maxWidth: "100%"` child forces the child to
+ * re-derive its width from the parent on every layout pass instead of
+ * caching a measured pixel width, keeping it full-width and stable.
+ *
+ * @param children - The content to render at full parent width.
+ */
+export function FullWidthRow({ children }: Props) {
+  return (
+    <View style={styles.row}>
+      <View style={styles.basis}>{children}</View>
+    </View>
+  );
+}

package/Components/MasterCell/DefaultComponents/ActionButton.tsx

@@ -37,13 +37,16 @@ function getAssetValue(asset, flavour, fallbackAsset = null) {
     return null;
   }
 
-  if (typeof asset === "string") return asset;
+  if (typeof asset === "string") return fallbackAsset || asset;
 
   if (Array.isArray(asset)) {
     const flavourIndex = Number(flavour.replace("flavour_", ""));
-    if (flavour && flavourIndex > -1) return asset[flavourIndex - 1];
 
-    return asset[0];
+    if (flavour && flavourIndex > -1) {
+      return fallbackAsset || asset[flavourIndex - 1];
+    }
+
+    return fallbackAsset || asset[0];
   }
 
   return asset.src || fallbackAsset;
@@ -109,13 +112,21 @@ export const ActionButton = React.memo(function ActionButtonComponent(
         <Image
           fadeDuration={0}
           style={asset?.style || props?.style}
-          uri={getAssetValue(actionState.asset, flavour, asset?.src)}
+          uri={getAssetValue(
+            actionState.asset,
+            flavour,
+            actionState.state === 1 ? asset?.src.active : asset?.src.inactive
+          )}
           {...asset?.props}
         />
       ) : (
         <AssetComponent
           flavour={flavour}
-          asset={getAssetValue(asset, flavour)}
+          asset={getAssetValue(
+            asset,
+            flavour,
+            actionState.state === 1 ? asset?.src.active : asset?.src.inactive
+          )}
           cellUUID={cellUUID}
           {...(props?.extraProps ?? {})}
         />

package/Components/MasterCell/DefaultComponents/ActionButtonsCore/__tests__/placement.test.ts

@@ -6,28 +6,54 @@ import {
 describe("ActionButtonsCore placement", () => {
   const buttons = { type: "View", name: "buttons" };
 
-  const above_labels = [
-    { name: "above_label_1" },
-    { name: "above_label_2" },
-    { name: "above_label_3" },
+  const slots = [
+    { name: "text_label_1", element: { type: "View", id: "label_1" } },
+    { name: "text_label_2", element: { type: "View", id: "label_2" } },
+    { name: "text_label_3", element: { type: "View", id: "label_3" } },
   ];
 
-  const below_labels = [
-    { name: "below_label_1" },
-    { name: "below_label_2" },
-    { name: "below_label_3" },
-  ];
+  const labels = slots.map((slot) => slot.element);
 
   it("inserts buttons after the matching label", () => {
     expect(
-      insertBetweenLabels({ position: "below_label_2" }, buttons, below_labels)
-    ).toEqual([below_labels[0], below_labels[1], buttons, below_labels[2]]);
+      insertBetweenLabels({ position: "below_text_label_2" }, buttons, slots)
+    ).toEqual([labels[0], labels[1], buttons, labels[2]]);
   });
 
   it("inserts buttons before the matching label", () => {
     expect(
-      insertBetweenLabels({ position: "above_label_2" }, buttons, above_labels)
-    ).toEqual([above_labels[0], buttons, above_labels[1], above_labels[2]]);
+      insertBetweenLabels({ position: "above_text_label_2" }, buttons, slots)
+    ).toEqual([labels[0], buttons, labels[1], labels[2]]);
+  });
+
+  it("inserts buttons after the matching label on a plain name match", () => {
+    expect(
+      insertBetweenLabels({ position: "text_label_2" }, buttons, slots)
+    ).toEqual([labels[0], labels[1], buttons, labels[2]]);
+  });
+
+  it("keeps the slot when its label is empty (null element)", () => {
+    const slotsWithEmpty = [
+      { name: "text_label_1", element: { id: "label_1" } },
+      { name: "text_label_2", element: null },
+      { name: "text_label_3", element: { id: "label_3" } },
+    ];
+
+    expect(
+      insertBetweenLabels(
+        { position: "above_text_label_2" },
+        buttons,
+        slotsWithEmpty
+      )
+    ).toEqual([{ id: "label_1" }, buttons, { id: "label_3" }]);
+
+    expect(
+      insertBetweenLabels(
+        { position: "below_text_label_2" },
+        buttons,
+        slotsWithEmpty
+      )
+    ).toEqual([{ id: "label_1" }, buttons, { id: "label_3" }]);
   });
 
   it("prepends buttons only when on_top is allowed", () => {
@@ -35,17 +61,17 @@ describe("ActionButtonsCore placement", () => {
       insertBetweenLabels(
         { position: "on_top", allowOnTop: true },
         buttons,
-        below_labels
+        slots
       )
-    ).toEqual([buttons, ...below_labels]);
+    ).toEqual([buttons, ...labels]);
 
     expect(
       insertBetweenLabels(
         { position: "on_top", allowOnTop: false },
         buttons,
-        below_labels
+        slots
       )
-    ).toEqual(below_labels);
+    ).toEqual(labels);
   });
 
   it("appends buttons when appendWhenMissing is enabled", () => {
@@ -53,9 +79,9 @@ describe("ActionButtonsCore placement", () => {
       insertBetweenLabels(
         { position: "unknown", appendWhenMissing: true },
         buttons,
-        below_labels
+        slots
       )
-    ).toEqual([...below_labels, buttons]);
+    ).toEqual([...labels, buttons]);
   });
 
   it("returns labels unchanged when appendWhenMissing is disabled", () => {
@@ -63,9 +89,9 @@ describe("ActionButtonsCore placement", () => {
       insertBetweenLabels(
         { position: "unknown", appendWhenMissing: false },
         buttons,
-        below_labels
+        slots
       )
-    ).toEqual(below_labels);
+    ).toEqual(labels);
   });
 
   const labelContainers = [