@applicaster/zapp-react-native-utils 16.0.0-alpha.8901714553 → 16.0.0-alpha.9530606740

package/actionsExecutor/types.ts

@@ -0,0 +1,59 @@
+/// <reference types="@applicaster/applicaster-types" />
+import { ActionResult } from "./ActionExecutor";
+import { useScreenStateStore } from "../reactHooks/navigation/useScreenStateStore";
+
+/**
+ * Base context object passed to action handlers during execution.
+ * Contains references to the current entry, screen, and other execution state.
+ */
+export interface ActionExecutionContext {
+  /** The entry associated with this action (e.g., the item that was tapped) */
+  entry?: ZappEntry;
+
+  /** The current screen/river data */
+  screenData?: ZappRiver;
+
+  /** The entry that defines the screen (if screen was opened from an entry) */
+  screenEntry?: ZappEntry;
+
+  /** The UI component that triggered the action.
+   * From UIComponentContext as `{ ...component, parent }`.
+   */
+  component?: ZappUIComponent & { parent?: ZappUIComponent };
+
+  /** The route identifier for the current screen */
+  screenRoute?: string;
+
+  /** The screen state store for managing screen-level state (Zustand store) */
+  screenStateStore?: ReturnType<typeof useScreenStateStore>;
+
+  /** Context entry for additional data */
+  entryContext?: ZappEntry;
+
+  /** Callback function for action completion */
+  callback?: (result: { success: boolean; error: any; abort: boolean }) => void;
+
+  screenState: Record<any, any>;
+}
+
+/**
+ * Type for action handler functions.
+ * Handlers receive the action (which may have typed options) and execution context.
+ *
+ * @template _TOptions - Optional type hint for the action's options object (for documentation/intellisense)
+ * @param action - The action to execute
+ * @param context - The execution context
+ * @returns A promise that resolves to the action result
+ */
+export type ActionHandler<_TOptions = any> = (
+  action: ActionType,
+  context?: ActionExecutionContext
+) => Promise<ActionResult>;
+
+/**
+ * Factory function that creates an action handler.
+ * Used for actions that need to capture dependencies at registration time.
+ */
+export type ActionHandlerFactory<_TOptions = any> = (
+  ...dependencies: any[]
+) => ActionHandler<_TOptions>;

package/appUtils/contextKeysManager/__tests__/getKey/failure.test.ts

@@ -46,7 +46,7 @@ describe("Context Keys Manager - getKey", () => {
 
     expect(mockedLogger.warn).toHaveBeenCalledWith({
       message:
-        "Provided key is not valid - expecing an object with namespace and key properties",
+        "Provided key is not valid - expecting an object with namespace and key properties",
       data: { key: invalidKey },
     });
 

package/appUtils/contextKeysManager/__tests__/removeKey/failure.test.ts

@@ -47,7 +47,7 @@ describe("Context Keys Manager - removeKey", () => {
 
     expect(mockedLogger.warn).toHaveBeenCalledWith({
       message:
-        "Provided key is not valid - expecing an object with namespace and key properties",
+        "Provided key is not valid - expecting an object with namespace and key properties",
       data: { key },
     });
 

package/appUtils/contextKeysManager/__tests__/setKey/failure/invalidKey.test.ts

@@ -48,7 +48,7 @@ describe("Context Keys Manager - setKey", () => {
 
     expect(mockedLogger.warn).toHaveBeenCalledWith({
       message:
-        "Provided key is not valid - expecing an object with namespace and key properties",
+        "Provided key is not valid - expecting an object with namespace and key properties",
       data: { key },
     });
 
@@ -105,7 +105,7 @@ describe("Context Keys Manager - setKey", () => {
 
     expect(mockedLogger.warn).toHaveBeenCalledWith({
       message:
-        "Provided key is not valid - expecing an object with namespace and key properties",
+        "Provided key is not valid - expecting an object with namespace and key properties",
       data: { key },
     });
 
@@ -162,7 +162,7 @@ describe("Context Keys Manager - setKey", () => {
 
     expect(mockedLogger.warn).toHaveBeenCalledWith({
       message:
-        "Provided key is not valid - expecing an object with namespace and key properties",
+        "Provided key is not valid - expecting an object with namespace and key properties",
       data: { key },
     });
 
@@ -217,7 +217,7 @@ describe("Context Keys Manager - setKey", () => {
 
     expect(mockedLogger.warn).toHaveBeenCalledWith({
       message:
-        "Provided key is not valid - expecing an object with namespace and key properties",
+        "Provided key is not valid - expecting an object with namespace and key properties",
       data: { key },
     });
 

package/appUtils/contextKeysManager/index.ts

@@ -109,7 +109,7 @@ export class ContextKeysManager {
     if (!keyIsValid(parsedKey)) {
       this._logger.warn({
         message:
-          "Provided key is not valid - expecing an object with namespace and key properties",
+          "Provided key is not valid - expecting an object with namespace and key properties",
         data: { key },
       });
 

package/cellUtils/index.ts

@@ -1,7 +1,7 @@
 import * as R from "ramda";
 import { dayjs } from "../dateUtils";
-import validateColor from "validate-color";
 
+import { isValidColor } from "@applicaster/zapp-react-native-utils/colorUtils";
 import { transformColorCode as fixColorHexCode } from "@applicaster/zapp-react-native-utils/transform";
 import {
   capitalize,
@@ -468,15 +468,13 @@ export const getColorFromData = ({
   data,
   valueFromLayout,
 }: GetColorFromData): string => {
-  // Temporary hack to fix color validation when alpha is floating point number
-  // https://github.com/dreamyguy/validate-color/issues/44
-  if (validateColor(valueFromLayout.replace(".00", ""))) {
+  if (isValidColor(valueFromLayout)) {
     return valueFromLayout;
   }
 
   const pathValue = R.path(valueFromLayout.split("."), data);
 
-  if (pathValue && validateColor(pathValue)) {
+  if (pathValue && isValidColor(pathValue)) {
     return pathValue;
   }
 

package/colorUtils/__tests__/isTransparentColor.test.ts

@@ -0,0 +1,76 @@
+import { isTransparentColor } from "..";
+
+describe("isTransparentColor", () => {
+  it("returns true for transparent keyword and rgba colors with zero alpha", () => {
+    const transparentColors = [
+      "transparent",
+      "rgba(0,0,0,0)",
+      "rgba(255, 255, 255, 0)",
+      "rgba(0,0,0,0.0)",
+      "rgba(0,0,0,0.00)",
+      "rgba(0,0,0, 0)",
+      "hsla(0,0%,0%,0)",
+    ];
+
+    expect.assertions(transparentColors.length);
+
+    transparentColors.forEach((color) => {
+      expect(isTransparentColor(color)).toBe(true);
+    });
+  });
+
+  it("returns false for valid colors that are not fully transparent", () => {
+    const nonTransparentColors = [
+      "red",
+      "#fff",
+      "#ffffff",
+      "rgb(0,0,0)",
+      "rgba(0,0,0)",
+      "rgba(0,0,0,0.5)",
+      "rgba(255, 255, 255, 0.3)",
+      "rgba(255, 255, 255, 1.0)",
+      "rgba(239,239,239,1.0)",
+      "currentColor",
+      "inherit",
+      "#00000000",
+      "#fff0",
+    ];
+
+    expect.assertions(nonTransparentColors.length);
+
+    nonTransparentColors.forEach((color) => {
+      expect(isTransparentColor(color)).toBe(false);
+    });
+  });
+
+  it("returns false for case variants of the transparent keyword", () => {
+    expect(isTransparentColor("Transparent")).toBe(false);
+    expect(isTransparentColor("TRANSPARENT")).toBe(false);
+  });
+
+  it("returns false for invalid color strings", () => {
+    const invalidColors = [
+      "invalid",
+      "",
+      "#gggggg",
+      "#fff.00",
+      "unset",
+      " rgba(0,0,0,0) ",
+      "transparent ",
+    ];
+
+    expect.assertions(invalidColors.length);
+
+    invalidColors.forEach((color) => {
+      expect(isTransparentColor(color)).toBe(false);
+    });
+  });
+
+  it("returns false for nullish and non-string values", () => {
+    expect(isTransparentColor(undefined)).toBe(false);
+    expect(isTransparentColor(null)).toBe(false);
+    expect(isTransparentColor(123)).toBe(false);
+    expect(isTransparentColor({})).toBe(false);
+    expect(isTransparentColor([])).toBe(false);
+  });
+});

package/colorUtils/__tests__/isValidColor.test.ts

@@ -0,0 +1,70 @@
+import { isValidColor } from "..";
+
+describe("isValidColor", () => {
+  it("returns true for valid hex colors", () => {
+    const validHexColors = ["#fff", "#ffffff", "#FF0000", "#000", "#abc123"];
+
+    expect.assertions(validHexColors.length);
+
+    validHexColors.forEach((color) => {
+      expect(isValidColor(color)).toBe(true);
+    });
+  });
+
+  it("returns true for valid rgb and rgba colors", () => {
+    const validRgbColors = [
+      "rgb(255,0,0)",
+      "rgb(255, 0, 0)",
+      "rgba(255,0,0,0.5)",
+      "rgba(255, 0, 0, 0.5)",
+    ];
+
+    expect.assertions(validRgbColors.length);
+
+    validRgbColors.forEach((color) => {
+      expect(isValidColor(color)).toBe(true);
+    });
+  });
+
+  it("returns true for valid named and special CSS colors", () => {
+    const validNamedColors = ["red", "transparent", "currentColor", "inherit"];
+
+    expect.assertions(validNamedColors.length);
+
+    validNamedColors.forEach((color) => {
+      expect(isValidColor(color)).toBe(true);
+    });
+  });
+
+  it("returns true for valid hsl colors", () => {
+    expect(isValidColor("hsl(0, 100%, 50%)")).toBe(true);
+  });
+
+  it("returns false for invalid color strings", () => {
+    const invalidColors = [
+      "invalid",
+      "",
+      "#gggggg",
+      "#fff.00",
+      "unset",
+      undefined,
+      null,
+    ];
+
+    expect.assertions(invalidColors.length);
+
+    invalidColors.forEach((color) => {
+      expect(isValidColor(color)).toBe(false);
+    });
+  });
+
+  it("returns true for valid rgb and rgba colors", () => {
+    const validRgbColors = ["rgba(239,239,239,1.0)"];
+
+    expect.assertions(validRgbColors.length);
+
+    validRgbColors.forEach((color) => {
+      expect(isValidColor(color)).toBe(true);
+    });
+  });
+});

package/colorUtils/index.ts

@@ -0,0 +1,50 @@
+import validateColor from "validate-color";
+import { isNil } from "@applicaster/zapp-react-native-utils/utils";
+import { isString } from "@applicaster/zapp-react-native-utils/stringUtils";
+
+const normalizeRgbaAlpha = (color: string): string => {
+  return color.replace(
+    /^rgba\(([^)]+),\s*(\d+(?:\.\d+)?)\s*\)$/i,
+    (_, rgb, alpha) => {
+      const alphaValue = parseFloat(alpha);
+
+      if (!Number.isFinite(alphaValue) || !Number.isInteger(alphaValue)) {
+        return color;
+      }
+
+      return `rgba(${rgb},${alphaValue})`;
+    }
+  );
+};
+
+export const isValidColor = (color: string): boolean => {
+  if (isNil(color) || !isString(color)) {
+    return false;
+  }
+
+  if (validateColor(color)) {
+    return true;
+  }
+
+  // validate-color rejects integer alpha values written as floats (e.g. 1.0)
+  // https://github.com/dreamyguy/validate-color/issues/44
+  const normalizedColor = normalizeRgbaAlpha(color);
+
+  return normalizedColor !== color && validateColor(normalizedColor);
+};
+
+function isRgbaAlphaZero(color: string): boolean {
+  const layers = color
+    .replace("rgba(", "")
+    .replace(")", "")
+    .split(",")
+    .map((layer) => layer.trim());
+
+  return Number(layers[3]) === 0;
+}
+
+export const isTransparentColor = (color: string): boolean => {
+  return (
+    isValidColor(color) && (color === "transparent" || isRgbaAlphaZero(color))
+  );
+};

package/manifestUtils/_internals/index.js

@@ -157,6 +157,10 @@ function generateFieldsFromDefaultsWithoutPrefixedLabel(
 
         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 {
@@ -164,6 +168,8 @@ function generateFieldsFromDefaultsWithoutPrefixedLabel(
               condition_value: condition.value,
             };
           });
+
+          generatedField.rules = "all_conditions";
         }
 
         return generatedField;

package/manifestUtils/fieldUtils/__tests__/fieldUtils.test.js

@@ -1,9 +1,93 @@
 const {
+  parseShorthand,
+  margin,
+  padding,
   withConditional,
   getConditionalKey,
   createConditionalField,
 } = require("..");
 
+describe("parseShorthand", () => {
+  it("1 value → all four sides equal", () => {
+    expect(parseShorthand("8")).toEqual([8, 8, 8, 8]);
+  });
+
+  it("2 values → top/bottom, right/left", () => {
+    expect(parseShorthand("0 20")).toEqual([0, 20, 0, 20]);
+  });
+
+  it("3 values → top, right/left, bottom", () => {
+    expect(parseShorthand("0 0 20")).toEqual([0, 0, 20, 0]);
+  });
+
+  it("4 values → top right bottom left", () => {
+    expect(parseShorthand("1 2 3 4")).toEqual([1, 2, 3, 4]);
+  });
+
+  it("throws on invalid count", () => {
+    expect(() => parseShorthand("1 2 3 4 5")).toThrow();
+  });
+});
+
+describe("margin", () => {
+  it("returns 4 field descriptors with correct suffixes", () => {
+    const fields = margin("margin", { mobile: "0" });
+
+    expect(fields.map((f) => f.suffix)).toEqual([
+      "margin top",
+      "margin right",
+      "margin bottom",
+      "margin left",
+    ]);
+  });
+
+  it("sets type to number_input", () => {
+    margin("margin", { mobile: "0" }).forEach((f) => {
+      expect(f.type).toBe("number_input");
+    });
+  });
+
+  it("expands shorthand per platform", () => {
+    const fields = margin("margin", { mobile: "0 0 20", tv: "0 0 90" });
+    const byKey = Object.fromEntries(fields.map((f) => [f.suffix, f]));
+    expect(byKey["margin top"].initialValue).toEqual({ mobile: 0, tv: 0 });
+    expect(byKey["margin bottom"].initialValue).toEqual({ mobile: 20, tv: 90 });
+    expect(byKey["margin left"].initialValue).toEqual({ mobile: 0, tv: 0 });
+  });
+
+  it("supports a custom suffix prefix", () => {
+    const fields = margin("input margin", { mobile: "4" });
+    expect(fields[0].suffix).toBe("input margin top");
+  });
+});
+
+describe("padding", () => {
+  it("returns 4 field descriptors with correct suffixes", () => {
+    const fields = padding("padding", { mobile: "0" });
+
+    expect(fields.map((f) => f.suffix)).toEqual([
+      "padding top",
+      "padding right",
+      "padding bottom",
+      "padding left",
+    ]);
+  });
+
+  it("expands 2-value shorthand symmetrically", () => {
+    const fields = padding("padding", { mobile: "0 20", tv: "0 124" });
+    const byKey = Object.fromEntries(fields.map((f) => [f.suffix, f]));
+
+    expect(byKey["padding right"].initialValue).toEqual({
+      mobile: 20,
+      tv: 124,
+    });
+
+    expect(byKey["padding left"].initialValue).toEqual({ mobile: 20, tv: 124 });
+    expect(byKey["padding top"].initialValue).toEqual({ mobile: 0, tv: 0 });
+    expect(byKey["padding bottom"].initialValue).toEqual({ mobile: 0, tv: 0 });
+  });
+});
+
 describe("manifestUtils/fieldUtils", () => {
   it("appends conditions and adds all_conditions when there is more than one condition", () => {
     const config = {

package/manifestUtils/fieldUtils/index.js

@@ -1,3 +1,121 @@
+const { ZAPPIFEST_FIELDS } = require("../keys");
+const { toCamelCase } = require("../_internals");
+
+const SIDES = ["top", "right", "bottom", "left"];
+
+/**
+ * Parses a CSS margin/padding shorthand string into [top, right, bottom, left].
+ *
+ * 1 value  → all four sides
+ * 2 values → top/bottom, right/left
+ * 3 values → top, right/left, bottom
+ * 4 values → top, right, bottom, left
+ *
+ * @param {string} str
+ * @returns {[number, number, number, number]}
+ */
+function parseShorthand(str) {
+  const parts = String(str).trim().split(/\s+/).map(Number);
+
+  switch (parts.length) {
+    case 1:
+      return [parts[0], parts[0], parts[0], parts[0]];
+    case 2:
+      return [parts[0], parts[1], parts[0], parts[1]];
+    case 3:
+      return [parts[0], parts[1], parts[2], parts[1]];
+    case 4:
+      return parts;
+    default:
+      throw new Error(
+        `Shorthand expects 1–4 space-separated values, got ${parts.length}: "${str}"`
+      );
+  }
+}
+
+function spacingFields(prefix, initialValues) {
+  const platforms = Object.keys(initialValues);
+
+  const parsed = Object.fromEntries(
+    platforms.map((p) => [p, parseShorthand(initialValues[p])])
+  );
+
+  return SIDES.map((side, i) => ({
+    suffix: `${prefix} ${side}`,
+    type: ZAPPIFEST_FIELDS.number_input,
+    initialValue: Object.fromEntries(platforms.map((p) => [p, parsed[p][i]])),
+  }));
+}
+
+/**
+ * Generates four margin field descriptors (top/right/bottom/left) from a
+ * per-platform CSS shorthand string.
+ *
+ * @param {string} suffix - prefix word for generated field names, e.g. "margin"
+ * @param {Record<string, string>} initialValues - e.g. { mobile: "0 0 20", tv: "0 0 90" }
+ * @returns {object[]}
+ */
+function margin(suffix, initialValues) {
+  return spacingFields(suffix, initialValues);
+}
+
+/**
+ * Generates four padding field descriptors (top/right/bottom/left) from a
+ * per-platform CSS shorthand string.
+ *
+ * @param {string} suffix - prefix word for generated field names, e.g. "padding"
+ * @param {Record<string, string>} initialValues - e.g. { mobile: "0 20", tv: "0 124" }
+ * @returns {object[]}
+ */
+function padding(suffix, initialValues) {
+  return spacingFields(suffix, initialValues);
+}
+
+/**
+ * Returns a flat camelCase defaults object for a spacing shorthand.
+ * e.g. marginDefaults("margin", "0 0 20") → { marginTop: 0, marginRight: 0, marginBottom: 20, marginLeft: 0 }
+ *
+ * @param {string} suffix - e.g. "margin" or "padding"
+ * @param {string} shorthand - CSS-like shorthand string
+ * @returns {Record<string, number>}
+ */
+function spacingDefaults(suffix, shorthand) {
+  const values = parseShorthand(shorthand);
+
+  return Object.fromEntries(
+    SIDES.map((side, i) => [toCamelCase(`${suffix} ${side}`), values[i]])
+  );
+}
+
+function marginDefaults(suffix, shorthand) {
+  return spacingDefaults(suffix, shorthand);
+}
+
+function paddingDefaults(suffix, shorthand) {
+  return spacingDefaults(suffix, shorthand);
+}
+
+/**
+ * Returns four field descriptors (top/right/bottom/left) with only suffix and type — no initialValue.
+ * Used when defaults are stored separately in the subgroup spec.
+ *
+ * @param {string} prefix - e.g. "margin" or "padding"
+ * @returns {object[]}
+ */
+function marginFields(prefix) {
+  return SIDES.map((side) => ({
+    suffix: `${prefix} ${side}`,
+    type: ZAPPIFEST_FIELDS.number_input,
+  }));
+}
+
+function paddingFields(prefix) {
+  return SIDES.map((side) => ({
+    suffix: `${prefix} ${side}`,
+    type: ZAPPIFEST_FIELDS.number_input,
+  }));
+}
+
 /**
  * Appends new conditional_fields from conditions array
  * to config.conditional_fields
@@ -48,6 +166,13 @@ function createConditionalField(key, condition_value, category = "styles") {
 }
 
 module.exports = {
+  parseShorthand,
+  margin,
+  padding,
+  marginDefaults,
+  paddingDefaults,
+  marginFields,
+  paddingFields,
   withConditional,
   getConditionalKey,
   createConditionalField,

package/manifestUtils/keys.js

@@ -43,6 +43,7 @@ const TV_PLATFORMS = [
   "tvos_for_quickbrick",
   "samsung_tv",
   "lg_tv",
+  "vidaa",
   "vizio",
 ];
 
@@ -630,6 +631,14 @@ const MOBILE_ACTION_BUTTON_FIELDS = [
     type: ZAPPIFEST_FIELDS.number_input,
     suffix: "margin left",
   },
+  {
+    type: ZAPPIFEST_FIELDS.number_input,
+    suffix: "horizontal gutter",
+  },
+  {
+    type: ZAPPIFEST_FIELDS.number_input,
+    suffix: "vertical gutter",
+  },
 ];
 
 const TV_MENU_LABEL_FIELDS = [

package/manifestUtils/mobileAction/button/index.js

@@ -129,6 +129,22 @@ function mobileActionButton({ label, description, defaults, isFirstButton }) {
       conditions.push(createConditionalField(labelEnabledKey, true));
     }
 
+    const assetAlignmentKey = keyPrefixGenerator("asset_alignment");
+
+    // horizontal_gutter fields depends on [asset_alignment: left or asset_alignment: right]
+    if (isKeyHasSuffix("horizontal_gutter", key)) {
+      conditions.push(
+        createConditionalField(assetAlignmentKey, ["left", "right"])
+      );
+    }
+
+    // vertical_gutter fields depends on [asset_alignment: above or asset_alignment: below]
+    if (isKeyHasSuffix("vertical_gutter", key)) {
+      conditions.push(
+        createConditionalField(assetAlignmentKey, ["above", "below"])
+      );
+    }
+
     return withConditional(conditions)(field);
   });
 

package/manifestUtils/mobileAction/container/index.js

@@ -49,7 +49,9 @@ function mobileActionButtonsContainer({ label, description, defaults }) {
 
     // over_image_position depends on [positionKey: over_image]
     if (isKeyHasSuffix("over_image_position", key)) {
-      conditions.push(createConditionalField(positionKey, "over_image"));
+      conditions.push(
+        createConditionalField(positionKey, defaults.position[0])
+      );
     }
 
     // horizontal_gutter depends on [stackingKey: horizontal]

package/manifestUtils/mobileAction/groups/defaults.js

@@ -33,7 +33,7 @@ const DEFAULT_MOBILE_ACTION_BUTTON_SHARED_DEFAULTS = {
   assetHeight: 24,
   assetWidth: 24,
   assetMarginTop: 0,
-  assetMarginRight: 6,
+  assetMarginRight: 0,
   assetMarginBottom: 0,
   assetMarginLeft: 0,
   labelEnabled: true,
@@ -50,6 +50,8 @@ const DEFAULT_MOBILE_ACTION_BUTTON_SHARED_DEFAULTS = {
   marginRight: 0,
   marginBottom: 0,
   marginLeft: 0,
+  horizontalGutter: 8,
+  verticalGutter: 8,
 };
 
 const DEFAULT_MOBILE_ACTION_BUTTON_PRESETS = {

package/manifestUtils/platformIsTV.js

@@ -4,6 +4,7 @@ function platformIsTV(platform) {
     "android_tv_for_quickbrick",
     "amazon_fire_tv_for_quickbrick",
     "lg_tv",
+    "vidaa",
     "samsung_tv",
     "web",
     "vizio",