@applicaster/zapp-react-native-utils 15.0.0-alpha.1107527841 → 15.0.0-alpha.1123384087

package/manifestUtils/mobileAction/groups/index.js

@@ -0,0 +1,80 @@
+const { mobileActionButtonsContainer } = require("../container");
+const { mobileActionButton } = require("../button");
+
+const {
+  DEFAULT_MOBILE_ACTION_BUTTONS_CONTAINER_DEFAULTS,
+  DEFAULT_MOBILE_ACTION_BUTTON_SHARED_DEFAULTS,
+  DEFAULT_MOBILE_ACTION_BUTTON_PRESETS,
+} = require("./defaults");
+
+const CONTAINER_GROUP_LABEL = "Mobile Buttons Container"; // NOTE: used as key – "Mobile Buttons Container" -> "mobile_buttons_container"
+
+const CONTAINER_GROUP_DESCRIPTION =
+  "Configuration for mobile action buttons container";
+
+const BUTTON_GROUPS = [
+  {
+    index: 1,
+    label: "Mobile Button 1",
+    description: "Primary mobile action button",
+  },
+  {
+    index: 2,
+    label: "Mobile Button 2",
+    description: "Secondary mobile action button",
+  },
+  {
+    index: 3,
+    label: "Mobile Button 3",
+    description: "Tertiary mobile action button",
+  },
+];
+
+/**
+ * Builds the shared mobile action button manifest groups while letting each
+ * plugin supply only its supported insertion positions and explicit overrides.
+ *
+ * @param {object} options
+ * @param {object} [options.containerDefaults={}]
+ * @param {object} [options.sharedButtonDefaults={}]
+ * @param {Record<number, object>} [options.buttonOverrides={}]
+ * @returns {object[]}
+ */
+function buildMobileActionButtonGroups({
+  containerDefaults = {},
+  sharedButtonDefaults = {},
+  buttonOverrides = {},
+}) {
+  const groups = [
+    mobileActionButtonsContainer({
+      label: CONTAINER_GROUP_LABEL,
+      description: CONTAINER_GROUP_DESCRIPTION,
+      defaults: {
+        ...DEFAULT_MOBILE_ACTION_BUTTONS_CONTAINER_DEFAULTS,
+        ...containerDefaults,
+      },
+    }),
+  ];
+
+  BUTTON_GROUPS.forEach(({ index, label, description }) => {
+    groups.push(
+      mobileActionButton({
+        isFirstButton: index === 1,
+        label,
+        description,
+        defaults: {
+          ...DEFAULT_MOBILE_ACTION_BUTTON_SHARED_DEFAULTS,
+          ...sharedButtonDefaults,
+          ...DEFAULT_MOBILE_ACTION_BUTTON_PRESETS[index],
+          ...(buttonOverrides[index] || {}),
+        },
+      })
+    );
+  });
+
+  return groups;
+}
+
+module.exports = {
+  buildMobileActionButtonGroups,
+};

package/numberUtils/__tests__/toNumber.test.ts

@@ -11,16 +11,6 @@ describe("toNumber", () => {
     });
   });
 
-  it("return number if input is BigInt", () => {
-    const inputs = [5n, -5n];
-    expect.assertions(inputs.length);
-
-    inputs.forEach((input) => {
-      const output = toNumber(input);
-      expect(output).toBe(Number(input));
-    });
-  });
-
   it("return number if input is string as number", () => {
     const inputs = ["-1", "0", "1", "100", "0.2"];
     expect.assertions(inputs.length);
@@ -34,6 +24,8 @@ describe("toNumber", () => {
   it("return undefined if input is not a number", () => {
     const inputs = [
       "vfdvf",
+      "5n",
+      "-5n",
       null,
       undefined,
       NaN,
@@ -42,8 +34,6 @@ describe("toNumber", () => {
       { test: 1 },
       [],
       [1],
-      "5n",
-      "-5n",
     ];
 
     expect.assertions(inputs.length);
@@ -53,4 +43,29 @@ describe("toNumber", () => {
       expect(output).toBeUndefined();
     });
   });
+
+  describe("BigInt support", () => {
+    // Conditional test based on BigInt availability
+    const isBigIntSupported = typeof BigInt !== "undefined";
+
+    if (isBigIntSupported) {
+      it("converts BigInt to number when BigInt is supported", () => {
+        expect(toNumber(BigInt(5))).toBe(5);
+        expect(toNumber(BigInt(0))).toBe(0);
+        expect(toNumber(BigInt(-10))).toBe(-10);
+        expect(toNumber(BigInt(1000))).toBe(1000);
+      });
+
+      it("handles large BigInt values that may lose precision", () => {
+        const largeBigInt = BigInt(Number.MAX_SAFE_INTEGER) + BigInt(1);
+        const result = toNumber(largeBigInt);
+        expect(result).toBe(Number(largeBigInt));
+      });
+    } else {
+      it("skips BigInt tests when BigInt is not supported", () => {
+        // Placeholder test to indicate BigInt is not available
+        expect(typeof BigInt).toBe("undefined");
+      });
+    }
+  });
 });

package/numberUtils/__tests__/toPositiveNumber.test.ts

@@ -156,10 +156,38 @@ describe("toPositiveNumber", () => {
     it("handles Symbol values", () => {
       expect(toPositiveNumber(Symbol("test"))).toBeUndefined();
     });
+  });
 
-    it("converts BigInt values", () => {
-      expect(toPositiveNumber(5n)).toBe(5);
-      expect(toPositiveNumber(-5n)).toBeUndefined();
-    });
+  describe("BigInt support", () => {
+    // Conditional test based on BigInt availability
+    const isBigIntSupported = typeof BigInt !== "undefined";
+
+    if (isBigIntSupported) {
+      it("converts positive BigInt values to numbers when BigInt is supported", () => {
+        expect(toPositiveNumber(BigInt(5))).toBe(5);
+        expect(toPositiveNumber(BigInt(100))).toBe(100);
+        expect(toPositiveNumber(BigInt(1000))).toBe(1000);
+      });
+
+      it("returns undefined for zero BigInt", () => {
+        expect(toPositiveNumber(BigInt(0))).toBeUndefined();
+      });
+
+      it("returns undefined for negative BigInt values", () => {
+        expect(toPositiveNumber(BigInt(-5))).toBeUndefined();
+        expect(toPositiveNumber(BigInt(-100))).toBeUndefined();
+      });
+
+      it("handles large positive BigInt values", () => {
+        const largeBigInt = BigInt(Number.MAX_SAFE_INTEGER);
+        const result = toPositiveNumber(largeBigInt);
+        expect(result).toBe(Number(largeBigInt));
+      });
+    } else {
+      it("skips BigInt tests when BigInt is not supported", () => {
+        // Placeholder test to indicate BigInt is not available
+        expect(typeof BigInt).toBe("undefined");
+      });
+    }
   });
 });

package/numberUtils/index.ts

@@ -8,7 +8,11 @@ export const toNumber = (value: unknown): number | undefined => {
     return undefined;
   }
 
-  if (R.is(Number, value) || R.is(BigInt, value) || R.is(String, value)) {
+  // Feature-detect BigInt support to avoid ReferenceError on older runtimes
+  const isBigIntSupported = typeof BigInt !== "undefined";
+  const isBigIntValue = isBigIntSupported && R.is(BigInt, value);
+
+  if (R.is(Number, value) || isBigIntValue || R.is(String, value)) {
     const numberOrNan = Number(value);
 
     return Number.isNaN(numberOrNan) ? undefined : numberOrNan;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applicaster/zapp-react-native-utils",
-  "version": "15.0.0-alpha.1107527841",
+  "version": "15.0.0-alpha.1123384087",
   "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": "15.0.0-alpha.1107527841",
+    "@applicaster/applicaster-types": "15.0.0-alpha.1123384087",
     "buffer": "^5.2.1",
     "camelize": "^1.0.0",
     "dayjs": "^1.11.10",

package/reactHooks/feed/index.ts

@@ -1,5 +1,3 @@
-export { useFeedRefresh, feedRefreshLogger } from "./useFeedRefresh";
-
 export { useFeedLoader } from "./useFeedLoader";
 
 export { getSearchContext, getInflatedDataSourceUrl } from "./useInflatedUrl";

package/reactHooks/feed/useInflatedUrl.ts

@@ -45,7 +45,7 @@ interface GetInflatedDataSourceUrl {
   (properties: {
     source?: string;
     contexts: {
-      entry?: ZappEntry;
+      entry?: ZappEntry & { parent?: ZappEntry };
       screen?: ZappRiver;
       search?: object | string;
     };

package/reactHooks/state/__tests__/useComponentScreenState.test.ts

@@ -0,0 +1,246 @@
+import { renderHook, act } from "@testing-library/react-native";
+import { useComponentScreenState } from "../useComponentScreenState";
+import { useScreenContextV2 } from "@applicaster/zapp-react-native-utils/reactHooks/screen/useScreenContext";
+
+import { create } from "zustand";
+
+const createMockStore = () => create(() => ({}));
+
+// Mock the external dependencies
+jest.mock(
+  "@applicaster/zapp-react-native-utils/reactHooks/screen/useScreenContext",
+  () => ({
+    useScreenContextV2: jest.fn(),
+  })
+);
+
+const mockUseScreenContextV2 = useScreenContextV2 as jest.MockedFunction<
+  typeof useScreenContextV2
+>;
+
+describe("useComponentScreenState", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("should return initial value when no state exists for componentId", () => {
+    const mockStore = createMockStore();
+
+    mockUseScreenContextV2.mockReturnValue({
+      _componentStateStore: mockStore,
+    } as any);
+
+    const initialValue = "default-value";
+    const componentId = "test-component";
+
+    const { result } = renderHook(() =>
+      useComponentScreenState(componentId, initialValue)
+    );
+
+    expect(result.current[0]).toBe(initialValue);
+  });
+
+  it("should return stored value when state exists for componentId", () => {
+    const mockStore = createMockStore();
+    mockStore.setState({ "existing-component": "stored-value" });
+
+    mockUseScreenContextV2.mockReturnValue({
+      _componentStateStore: mockStore,
+    } as any);
+
+    const { result } = renderHook(() =>
+      useComponentScreenState("existing-component", "default")
+    );
+
+    expect(result.current[0]).toBe("stored-value");
+  });
+
+  it("should update state when setter is called", () => {
+    const mockStore = createMockStore();
+
+    mockUseScreenContextV2.mockReturnValue({
+      _componentStateStore: mockStore,
+    } as any);
+
+    const { result } = renderHook(() =>
+      useComponentScreenState("update-test", "initial")
+    );
+
+    // Verify initial value
+    expect(result.current[0]).toBe("initial");
+
+    // Update the value
+    act(() => {
+      result.current[1]("updated-value");
+    });
+
+    // Verify updated value
+    expect(result.current[0]).toBe("updated-value");
+  });
+
+  it("should handle different data types correctly", () => {
+    const mockStore = createMockStore();
+
+    mockUseScreenContextV2.mockReturnValue({
+      _componentStateStore: mockStore,
+    } as any);
+
+    // Test with number
+    const { result: numberResult } = renderHook(() =>
+      useComponentScreenState<number>("number-test", 42)
+    );
+
+    expect(numberResult.current[0]).toBe(42);
+
+    // Test with boolean
+    const { result: boolResult } = renderHook(() =>
+      useComponentScreenState<boolean>("bool-test", true)
+    );
+
+    expect(boolResult.current[0]).toBe(true);
+
+    // Test with object
+    const testObj = { key: "value" };
+
+    const { result: objResult } = renderHook(() =>
+      useComponentScreenState<{ key: string }>("obj-test", testObj)
+    );
+
+    expect(objResult.current[0]).toEqual(testObj);
+  });
+
+  it("should maintain separate states for different componentIds", () => {
+    const mockStore = createMockStore();
+
+    mockUseScreenContextV2.mockReturnValue({
+      _componentStateStore: mockStore,
+    } as any);
+
+    const { result: firstResult } = renderHook(() =>
+      useComponentScreenState("first", "first-initial")
+    );
+
+    const { result: secondResult } = renderHook(() =>
+      useComponentScreenState("second", "second-initial")
+    );
+
+    // Verify initial values are separate
+    expect(firstResult.current[0]).toBe("first-initial");
+    expect(secondResult.current[0]).toBe("second-initial");
+
+    // Update first component's state
+    act(() => {
+      firstResult.current[1]("first-updated");
+    });
+
+    // Verify only first component's state changed
+    expect(firstResult.current[0]).toBe("first-updated");
+    expect(secondResult.current[0]).toBe("second-initial");
+  });
+
+  it("should return a memoized setter function", () => {
+    const mockStore = createMockStore();
+
+    mockUseScreenContextV2.mockReturnValue({
+      _componentStateStore: mockStore,
+    } as any);
+
+    const { result, rerender } = renderHook(
+      ({ id, initial }) => useComponentScreenState(id, initial),
+      {
+        initialProps: { id: "memo-test", initial: "initial" },
+      }
+    );
+
+    const firstSetter = result.current[1];
+
+    // Rerender with same props
+    rerender({ id: "memo-test", initial: "initial" });
+
+    const secondSetter = result.current[1];
+
+    // Setter should be the same instance due to useCallback
+    expect(firstSetter).toBe(secondSetter);
+  });
+
+  it("should update setter when componentId changes", () => {
+    const mockStore = createMockStore();
+
+    mockUseScreenContextV2.mockReturnValue({
+      _componentStateStore: mockStore,
+    } as any);
+
+    const { result, rerender } = renderHook(
+      ({ id, initial }) => useComponentScreenState(id, initial),
+      {
+        initialProps: { id: "old-id", initial: "initial" },
+      }
+    );
+
+    const firstSetter = result.current[1];
+
+    // Rerender with different componentId
+    rerender({ id: "new-id", initial: "initial" });
+
+    const secondSetter = result.current[1];
+
+    // Setter should be different because componentId changed
+    expect(firstSetter).not.toBe(secondSetter);
+  });
+
+  it("should call store.setState with correct parameters", () => {
+    const mockStore = createMockStore();
+    const setStateSpy = jest.spyOn(mockStore, "setState");
+
+    mockUseScreenContextV2.mockReturnValue({
+      _componentStateStore: mockStore,
+    } as any);
+
+    const { result } = renderHook(() =>
+      useComponentScreenState("state-test", "initial")
+    );
+
+    const newValue = "new-value";
+
+    act(() => {
+      result.current[1](newValue);
+    });
+
+    expect(setStateSpy).toHaveBeenCalledWith({
+      "state-test": newValue,
+    });
+  });
+
+  it("should handle falsy initial values correctly", () => {
+    const mockStore = createMockStore();
+
+    mockUseScreenContextV2.mockReturnValue({
+      _componentStateStore: mockStore,
+    } as any);
+
+    // Test with falsy values
+    const { result: nullResult } = renderHook(() =>
+      useComponentScreenState("null-test", null)
+    );
+
+    expect(nullResult.current[0]).toBeNull();
+
+    const { result: falseResult } = renderHook(() =>
+      useComponentScreenState("false-test", false)
+    );
+
+    expect(falseResult.current[0]).toBe(false);
+
+    const { result: zeroResult } = renderHook(() =>
+      useComponentScreenState("zero-test", 0)
+    );
+
+    expect(zeroResult.current[0]).toBe(0);
+
+    const { result: emptyStrResult } = renderHook(() =>
+      useComponentScreenState("empty-test", "")
+    );
+
+    expect(emptyStrResult.current[0]).toBe("");
+  });
+});

package/reactHooks/state/index.ts

@@ -3,3 +3,5 @@ export { useRivers } from "./useRivers";
 export { useHomeRiver, getHomeRiver } from "./useHomeRiver";
 
 export { ZStoreProvider, useZStore } from "./ZStoreProvider";
+
+export { useComponentScreenState } from "./useComponentScreenState";

package/reactHooks/state/useComponentScreenState.ts

@@ -0,0 +1,45 @@
+import * as React from "react";
+import { useScreenContextV2 } from "@applicaster/zapp-react-native-utils/reactHooks/screen/useScreenContext";
+import { useStore } from "zustand";
+
+/**
+ * A custom hook that provides persistent state storage across component re-mounts
+ * using the screen's component state store.
+ *
+ * @see {@link DOCS/adr/0010-useComponentScreenState.md} - ADR explaining why useComponentScreenState is used for List/Hero/Grid/Gallery components
+ *
+ * The state is shared across all components using the same componentId within the same screen context.
+ * If no value exists for the componentId, the initial value is returned as a fallback but is not persisted in the store.
+ * The initial value must be explicitly set using the returned setter function to persist it.
+ *
+ * @template T - The type of value being stored
+ * @param componentId - Unique identifier for this state in the component state store
+ * @param initialValue - The default value if no value exists for the componentId
+ * @returns A tuple containing the current value and a memoized setter function
+ *
+ * @example
+ * ```tsx
+ * const [count, setCount] = useComponentScreenState<number>('counter', 0);
+ * const [name, setName] = useComponentScreenState<string>('username', 'Anonymous');
+ * ```
+ */
+export const useComponentScreenState = <T = unknown>(
+  componentId: string,
+  initialValue: T
+): [T, (value: T) => void] => {
+  const store = useScreenContextV2()._componentStateStore;
+
+  const value = useStore(
+    store,
+    (state) => (state[componentId] as T | undefined) ?? initialValue
+  );
+
+  const setValue = React.useCallback(
+    (nextValue: T) => {
+      store.setState({ [componentId]: nextValue });
+    },
+    [componentId, store]
+  );
+
+  return [value, setValue] as const;
+};

package/refreshUtils/RefreshCoordinator/__tests__/refreshCoordinator.test.ts

@@ -0,0 +1,161 @@
+import { refreshCoordinator } from "..";
+import { getDataRefreshConfig } from "../utils";
+import { Subscription } from "rxjs";
+
+jest.mock("../utils", () => ({
+  getDataRefreshConfig: jest.fn(),
+}));
+
+describe("RefreshCoordinator", () => {
+  const component = { id: "c1" } as ZappUIComponent;
+  const screenId = "screen-1";
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    refreshCoordinator.clear();
+    jest.useFakeTimers();
+  });
+
+  afterEach(() => {
+    jest.runOnlyPendingTimers();
+    jest.useRealTimers();
+  });
+
+  // ----------------------------------------
+  // Singleton
+  // ----------------------------------------
+  it("returns the same instance via getInstance", () => {
+    const instance1 = refreshCoordinator;
+    const instance2 = (refreshCoordinator as any).constructor.getInstance();
+    expect(instance1).toBe(instance2);
+  });
+
+  // ----------------------------------------
+  // register & unregister
+  // ----------------------------------------
+  it("register starts a timer and returns an unregister function", () => {
+    (getDataRefreshConfig as jest.Mock).mockReturnValue({
+      refreshIntervalMs: 1000,
+      isRefreshingEnabled: true,
+    });
+
+    const unregister = refreshCoordinator.register(component, screenId);
+
+    expect(typeof unregister).toBe("function");
+    expect((refreshCoordinator as any).timers.size).toBe(1);
+
+    // Calling unregister should remove timer
+    unregister();
+    expect((refreshCoordinator as any).timers.size).toBe(0);
+  });
+
+  it("does not register if refreshing is disabled", () => {
+    (getDataRefreshConfig as jest.Mock).mockReturnValue({
+      refreshIntervalMs: 1000,
+      isRefreshingEnabled: false,
+    });
+
+    const unregister = refreshCoordinator.register(component, screenId);
+
+    expect(unregister).toBeInstanceOf(Function);
+    expect((refreshCoordinator as any).timers.size).toBe(0);
+  });
+
+  it("replaces existing timer if component is re-registered", () => {
+    (getDataRefreshConfig as jest.Mock).mockReturnValue({
+      refreshIntervalMs: 1000,
+      isRefreshingEnabled: true,
+    });
+
+    const unregister1 = refreshCoordinator.register(component, screenId);
+    const unregister2 = refreshCoordinator.register(component, screenId);
+
+    expect((refreshCoordinator as any).timers.size).toBe(1);
+    expect(unregister1).toBeInstanceOf(Function);
+    expect(unregister2).toBeInstanceOf(Function);
+  });
+
+  // ----------------------------------------
+  // subscribeTo
+  // ----------------------------------------
+  it("subscribeTo only triggers listener for matching component & screen", () => {
+    (getDataRefreshConfig as jest.Mock).mockReturnValue({
+      refreshIntervalMs: 1000,
+      isRefreshingEnabled: true,
+    });
+
+    const listener = jest.fn();
+    refreshCoordinator.register(component, screenId);
+    const sub = refreshCoordinator.subscribeTo(component, screenId, listener);
+
+    // Emit a refresh manually via private Subject
+    (refreshCoordinator as any).refresh$.next({ component, screenId });
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    // Non-matching component should not call listener
+    (refreshCoordinator as any).refresh$.next({
+      component: { id: "other" } as ZappUIComponent,
+      screenId,
+    });
+
+    expect(listener).toHaveBeenCalledTimes(1);
+
+    sub.unsubscribe();
+  });
+
+  // ----------------------------------------
+  // subscribeToAny
+  // ----------------------------------------
+  it("subscribeToAny triggers listener with throttling and replaces previous listener", () => {
+    const listener1 = jest.fn();
+    const listener2 = jest.fn();
+
+    // First subscription
+    const sub1: Subscription = refreshCoordinator.subscribeToAny(listener1);
+    expect(sub1).toBeInstanceOf(Subscription);
+
+    // Second subscription replaces first
+    const sub2: Subscription = refreshCoordinator.subscribeToAny(listener2);
+    expect(sub2).toBeInstanceOf(Subscription);
+
+    // Emit multiple events quickly
+    (refreshCoordinator as any).refresh$.next({ component, screenId });
+    (refreshCoordinator as any).refresh$.next({ component, screenId });
+
+    // Because of throttleTime(500ms), fast events are ignored
+    jest.advanceTimersByTime(500);
+    expect(listener1).not.toHaveBeenCalled();
+    expect(listener2).toHaveBeenCalledTimes(1);
+
+    sub2.unsubscribe();
+  });
+
+  // ----------------------------------------
+  // clear
+  // ----------------------------------------
+  it("clear stops all timers, anyListener, and recreates subject", () => {
+    (getDataRefreshConfig as jest.Mock).mockReturnValue({
+      refreshIntervalMs: 1000,
+      isRefreshingEnabled: true,
+    });
+
+    const listener = jest.fn();
+    refreshCoordinator.register(component, screenId);
+    refreshCoordinator.subscribeToAny(listener);
+
+    expect((refreshCoordinator as any).timers.size).toBe(1);
+    expect((refreshCoordinator as any).anyListenerSubscription).toBeDefined();
+
+    refreshCoordinator.clear();
+
+    expect((refreshCoordinator as any).timers.size).toBe(0);
+    expect((refreshCoordinator as any).anyListenerSubscription).toBeUndefined();
+
+    // New events on new Subject still work
+    const newListener = jest.fn();
+    refreshCoordinator.subscribeToAny(newListener);
+    (refreshCoordinator as any).refresh$.next({ component, screenId });
+    jest.advanceTimersByTime(500);
+    expect(newListener).toHaveBeenCalled();
+  });
+});